plan serve and plan build Commands

Summary

Dev server with hot reload (serve) and static site generation (build). Renders plan files as themed HTML pages with navigation, cross-reference links, status badges, and aggregate dashboard views using backlog and decision-log runes.

These commands share 90% of their pipeline — serve wraps it in a dev server with file watching, build writes the output as static HTML.

Acceptance Criteria

• plan serve starts a dev server rendering plan files as themed HTML pages
• Hot reload on file changes — re-scan and browser refresh
• Auto-generated dashboard if no index.md exists (uses backlog and decision-log runes)
• Sidebar navigation derived from file system and entity types
• Entity pages show full rendered content with status badges, xref links, checklist progress
• plan build generates a self-contained static HTML site to --out directory
• --theme option selects default, minimal, or path to custom CSS
• --base-url for GitHub Pages deployment (prefix all URLs)
• Dashboard uses backlog and decision-log runes for aggregate views
• Tests for HTML generation, navigation structure, and theme application

Approach

Build a lightweight rendering pipeline: scanner → entity registry → Markdoc parse → transform → identity transform → HTML template. Wrap entity pages in a shell template with navigation sidebar and theme CSS. For serve, use a simple HTTP server (Node http module) with fs.watch for hot reload. For build, write all pages to the output directory.

Dependencies

• CLI Plugin Discovery Architecture (plugin architecture)
• Plan File Scanner Library (plan file scanner)
• Add Entity Registration to @refrakt-md/plan (entity registration — for xref resolution)
• Build backlog Rune (backlog rune — for dashboard views)
• Build decision-log Rune (decision-log rune — for dashboard views)
• Plan Dashboard Theme (dashboard theme CSS)

References

• Plan CLI (Plan CLI)