# Constellation Portal
Constellation Portal is a Rust-based CLI that converts curated markdown collections (requirements, ADRs, audits, tasks) into a static, themeable knowledge portal. It follows the plan vision of shipping a single, extensible binary with configurable defaults and quick scaffolding for new documents.
## Features
- `constellate build` turns a workspace directory into a distributable static site (implementation placeholder for now).
- `constellate serve` watches the workspace, rebuilds on changes, and serves the Material-themed portal with live reload (port configurable via `--port` and `--no-watch` to disable).
- The generated home page includes a Material-styled task digest that surfaces in-progress, next-up, and recently finished tasks; tweak the number of entries via `.constellate.toml` (`cards.task_summary_limit`).
- Sidebar navigation supports configurable collections per document type (status buckets with per-bucket limits) plus an optional "View all" drawer that reuses the search index for scoped browsing.
- `constellate status` enforces per-type workflows (todo/ready/in-progress/done, etc.), updates front matter, and logs transitions under a `## Changes` section.
- `constellate new` scaffolds ADRs, tasks, or audits with sensible front matter, sequential IDs (based on configurable prefixes/widths), ID-prefixed slugified filenames (configurable globally or per document type), and a `created: YYYY-MM-DD HH:MM:SS` timestamp.
- `constellate validate` checks markdown syntax (frontmatter structure, YAML validity) and validates internal links, with options for syntax-only or links-only checks and path filtering for targeted validation.
- `[document_types.list]` can emit auto-generated list documents (an "all" view plus optional per-status partitions) and surface them as shortcuts at the top of the navigation sidebar.
- `constellate init` bootstraps a brand-new workspace by creating `workspace/pages` with a welcome doc, a minimal `.constellate.toml`, and a `.gitignore` that ignores `workspace/dist`.
- `constellate theme list` enumerates built-in layouts so teams can plan overrides, and `constellate theme export` copies the default templates into your workspace for customization.
- `constellate dump-config` writes the default `.constellate.toml` so teams can override folders, document types, and templates.
## Requirements
- Rust 1.76+ with `cargo`.
- Optional: Nix for reproducible shells (`nix-shell nix/shell.nix`).
## Docker Usage
Prefer containers? The published image bundles only the `constellate` binary and exposes `/workspace` as a volume so you can mount any portal sources:
```bash
# Preview your local workspace with live reload on port 8080
docker run --rm -p 8080:8080 \
-v "$PWD/workspace:/workspace" \
onjin/constellate:0.3.2
```
- Bind-mount a different path if your sources live elsewhere (`-v "$PWD/my-docs:/workspace"`).
- Override CLI flags as needed (for example `... constellate serve --input /workspace --output /workspace/dist --host 0.0.0.0 -p 8181 --no-watch`).
- When no volume is mounted the container starts with an empty `/workspace`; create or copy content into the mount before running the image.
### Static Hosting via Nginx
After running `constellate build`, you can serve the generated `workspace/dist` with any static web server. This Dockerfile example uses the Constellate image for the build step and Nginx for hosting:
```dockerfile
FROM onjin/constellate:0.3.2 AS builder
WORKDIR /workspace
COPY workspace/ /workspace/
RUN constellate build --input /workspace --output /workspace/dist
FROM nginx:1.25-alpine
COPY --from=builder /workspace/dist /usr/share/nginx/html
```
Build and run it:
```bash
docker build -t constellate-site .
docker run --rm -p 8080:80 constellate-site
```
Any time documents change, rerun `constellate build` (or rebuild the Docker image) so Nginx serves the updated static portal.
## Nix Integration
- `nix run github:onjin/constellate` executes the packaged CLI directly from the flake, while `nix shell github:onjin/constellate` drops the binary into a subshell.
- `nix develop github:onjin/constellate` reuses `nix/shell.nix` so you can enter the development environment without cloning.
- `flake.nix` exposes `packages.constellate`, an overlay, and dev shells so other flakes can `inputs.constellate` and reference `self.packages.${system}.constellate`.
- NixOS systems can enable the CLI via `imports = [ inputs.constellate.nixosModules.constellate ]; programs.constellate.enable = true;`.
- Home Manager users can import `inputs.constellate.homeManagerModules.constellate` and toggle `programs.constellate.enable = true` to add the binary to `home.packages`.
- `nix develop` or `nix flake check` rely on the same shell definition used by `nix-shell nix/shell.nix`.
## Shell Completions
- Run `constellate completion --shell bash > constellate.bash` to generate a Bash completion script (other shells supported via `--shell`).
- Source the generated script manually or drop it into your shell's completion directory.
- The NixOS/Home Manager modules set `enableBashIntegration = true` by default, which enables Bash completion when you toggle `programs.constellate.enable = true`.
## Contributing
Development workflow, template guard rails, and documentation expectations now live in [CONTRIBUTING.md](CONTRIBUTING.md). Refer to that guide for `cargo` commands, template export instructions, and the renderer migration plan before opening a PR.
## Project Layout
- `src/main.rs` – clap-powered CLI entry point.
- `Cargo.toml` – crate metadata and dependencies (`clap`, `color-eyre`).
- `nix/shell.nix` – development environment definition.
- `workspace/pages/` – default document tree (requirements, docs, support, tasks, ADRs, audits, initiatives) that tracks Constellate itself and serves as the sample input for `constellate build`.
- `workspace/.constellate.toml` – workspace-scoped configuration that maps document types to folders and points to the template overrides directory.
- `workspace/templates/` – optional override directory for Minijinja templates and partials referenced by the theme configuration.
## Next Steps
1. Extract the generator, status manager, and server utilities into dedicated modules with unit tests for markdown parsing, navigation rendering, and status transitions.
2. Expand configuration loading so teams can define additional document types, status workflows, and dashboard cards without touching the binary.
3. Implement theme discovery plus user asset overrides to complement the default Material skin.
`.constellate.toml` also governs per-type status workflows and ID generation. Each `[[document_types]]` entry can define `statuses = [...]` plus `id = { prefix = "REQ-", width = 3 }` so `constellate new` always issues the next sequential identifier with consistent padding. Use the `[portal]` block to customize the site title/subtitle that appear in the header and hero (defaults to “Constellate Portal” / “Markdown → Material UI”).