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                  # create public/site, templates, index.json, and a first card
microsite add /path/to/repo --title "Release" # add a new card + details markdown
microsite update /path/to/repo                # rescan HTML resources and refresh card paths
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 ui --host 127.0.0.1 --port 0        # 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 public/site exists, writes the bundled index.html/details.md templates, and seeds index.json.

• Creates a first card and details markdown by default; use --no-first-card to skip or --first-card to force when re-running.
• Flags: --slug, --repo-name, --title, --level, --purpose, --summary, --date, --source, --source-type, --source-label, --source-url, --source-ref.

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 public/site for .html files, sets micro_site_home to index.html, and refreshes paths.resources for every card.

• 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 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 tiny stdlib HTTP server; accepts an optional repo path, --host, --port (use 0 for a free port), and --no-browser.

• Inference (/infer) requires a repo path and Git URL; returns slug, repo name, branch (via git symbolic-ref fallback main), detected HTML resources, and site structure signals.
• Snapshot (/snapshot) lists cards, details markdown, and HTML resources, highlighting missing index.json, missing details, orphan details, non-HTML resources, and missing resource files.
• Generate (/generate) runs init + update with provided title/summary/purpose/level, uses Git metadata for source, creates placeholder HTML resources when requested, and surfaces update warnings.
• Auto-opens the browser unless --no-browser is set.

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
    core/
      add.py
      fix.py
      init.py
      sync.py
      update.py
      validate.py
      utils.py
      schema.py
    templates/
      index.html
      details.md
    ui_assets/
    ui_server.py
    VERSION
  tests/
  pyproject.toml
  requirements.txt