microsite-cli

Overview

microsite-cli scaffolds and maintains microsites for the raycool.dev card-stream ecosystem, keeping the evergreen contract intact and enabling optional database syncs.

Installation

pip install -e .

Quickstart

microsite init /path/to/repo                  # scaffold dev/public, templates, index.json
microsite add /path/to/repo --title "Release" # add a new card + details markdown
microsite update /path/to/repo                # rescan public site HTML resources
microsite update /path/to/repo --dev          # rescan dev site HTML resources
microsite validate /path/to/repo              # validate the contract and filesystem
microsite fix /path/to/repo                   # auto-fix common validation issues
microsite sync-db /path/to/repo --db-url ...  # push cards to PostgreSQL
microsite maturity /path/to/repo +1           # upshift maturity tier
microsite ui --port 8000                      # launch the Setup Wizard UI (Ctrl+C to stop)
microsite version                             # print tool version

Command Reference

Details for every CLI entry point, in the same order as the README.

microsite init

Ensures dev/site and public/site (optional) exist, writes the bundled index.html/details.md templates, and seeds index.json.

• Registers the repository in the cards database using the slug or --repo-id.
• Flags: --slug, --name, --repo-id, --db-url, --no-public.

microsite add

Adds a new card to index.json and creates its details markdown using the bundled template.

• Infers slug/repo name from the folder; auto-increments the sequence for matching slug/level/date.
• Flags: --title (required), --level, --purpose, --summary, --date, --source-type, --source-label, --source-url, --source-ref, --dry-run.

microsite update

Rescans the site directory for .html files, sets micro_site_home to index.html, and refreshes paths.resources for every card.

• Use --dev to operate on the dev/site layer (defaults to public).
• Warns when index.html is missing, when card details files are absent, or when details_md does not match the expected filename.

microsite validate

Validates contract fields and filesystem state.

• Checks required fields/types, normalized slugs, allowed levels, ISO dates, and that index.json is a list.
• Enforces micro_site_home == index.html when present and requires either details_md or details_html.
• Verifies details files exist, match details/<id>.md, and have no YAML frontmatter or <iframe>/<script> tags.
• Ensures referenced local resources exist; exits non-zero when errors are found.

microsite fix

Auto-fixes common validation issues without creating new content.

• Ensures paths exists, sets micro_site_home to index.html, and removes references to missing details_md/details_html.
• Relinks standard detail paths if files already exist (e.g., details/<id>.md); respects --dry-run to preview.

microsite maturity

Manages the repository's maturity tier (0-5) and displays the derived Phase.

• Supports absolute tier settings (0-5) or relative shifts (+N, -N).
• Phases: Establish (0-1), Comprehend (2-3), Automate (4-5).
• Flags: --repo-id, --db-url.

microsite sync-db

Synchronizes index.json to PostgreSQL with psycopg2; uses --db-url or MICROSITE_DB_URL.

• Upserts a repo record (default base_url: https://raycool.dev/microsites/<slug>) and all cards, including paths, source, and type when set.
• Fails fast on missing/invalid index.json or connection info and reports the count of synced cards.

microsite ui

Launches the Setup Wizard UI via a threaded HTTP server; accepts an optional repo path and --port.

• Inference (/infer) requires a repo path and Git URL; returns slug, repo name, branch, detected HTML resources, and site structure signals.
• Snapshot (/snapshot) lists cards, details markdown, and HTML resources, highlighting missing index.json, missing details, orphan details, and missing resource files.
• Generate (/generate) runs init + update with provided metadata, uses Git metadata for source, and creates placeholder HTML resources when requested.
• Provides a Markdown editor for card details and a viewer for HTML resources.

microsite version

Prints the CLI version.

Evergreen Contract

• Required fields: id, slug, title, summary, date, repo, level, purpose, and paths.
• Card IDs follow <slug>-<level>-<yyyy-mm-dd>-<seq> (three-digit sequence); details markdown is expected at details/<id>.md.
• paths.micro_site_home must be index.html when it exists; other HTML under public/site belong in paths.resources.
• Details markdown must avoid duplicated metadata/frontmatter and unsafe HTML tags (iframe, script); referenced local resources must exist.

Project Layout

microsite-cli/
  microsite/
    cli.py
    ui_server.py
    VERSION
    db.py
    core/
      add.py
      fix.py
      init.py
      maturity.py
      schema.py
      sync.py
      update.py
      utils.py
      validate.py
    templates/
      index.html
      details.md
      AGENTS.md
      DEVELOPERS.md
      OPERATIONAL.md
      DEV_README.md
    ui_assets/
  tests/
  pyproject.toml
  requirements.txt