@sitespec/cli

Project-local SiteSpec CLI.

The public binary is sitespec; normal websites invoke it through npm scripts such as npm run dev and npm run site -- spec --json.

The package exposes sitespec through bin/sitespec.js, a stable shim that is present before the TypeScript build output exists. The shim loads dist/index.js at runtime and prints a build instruction if the CLI has not been built yet. This keeps npm workspace binary linking deterministic during repository bootstrap.

Existing-site migration

sitespec migrate audit <url> captures generated migration evidence from a production page using an installed Chrome/Chromium browser. It records fixed-viewport screenshots, a DOM snapshot, computed design inventory, media inventory, conservative section candidates, and a compact DOM layout index without generating SiteSpec source.

sitespec migrate segment <audit> opens the audited production URL in a dedicated Chrome/Chromium session and injects a live DOM picker. A reviewer selects exact production region roots, can navigate parent/child/sibling DOM candidates, name blocks explicitly, mark Header/Footer/Ignore roles, drag or collapse the inspector, reload the production page without losing current selections, switch between Inspect and Interact modes, and save selector/fingerprint/evidence records to segments.json. Screenshot segmentation is not used.

sitespec migrate design <audit...> consumes two or more completed audits from the same host and writes generated cross-page analysis: exact observed foundations, normalized primitive/semantic/typography candidates, section-rhythm.json, a rationalized foundation-proposal.json with stable token-scale names and responsive layout relationships, section clusters, shared-shell candidates, and media-role hints. Section rhythm is inferred from balanced section-root vertical padding and cross-checked against clustering plus viewport/property evidence, so one-sided page offsets or spacing dominated by horizontal/gap usage are not promoted to space.section. Completed manual segments take precedence over automatic section candidates. Cross-page manual matches are conservatively gated by deterministic semantic intent inferred primarily from reviewer labels, so visually similar blocks with conflicting purposes are kept separate. The command is analysis-only and never mutates the installed Design System.

sitespec migrate foundation review <analysis> creates foundation-review.json, the explicit accept/reject/pending boundary between inference and canonical source. It preserves proposal provenance with a SHA-256, allows reviewer-owned token/role renames, and can preserve required-but-unresolved compatibility values as explicitly provisional rather than presenting them as inferred facts. sitespec migrate foundation materialize <review> writes a non-destructive foundation-tokens.json preview; only --apply --replace can replace the target design/tokens.json, and only after the review plus target layout/font/existing-semantic-contract preflight are ready.

sitespec migrate components review/contracts turns accepted reusable section families into reviewable component.yaml previews while keeping shell families separate. sitespec migrate shell contracts converts accepted header/footer families into a shell-pack file contract without fabricating Astro source. sitespec migrate ui review/contracts does the same for direct leaf UI evidence: conservative review can auto-accept repeated Button/Link families while heuristic Card/Badge boundaries remain pending. Every accepted UI primitive must expose canonical variant default; if observations only provide named variants, review maps the most-supported observed variant to default and preserves the source name in provenance.

sitespec migrate implementations infer <analysis> turns the current accepted foundation/UI/section/shell contracts plus saved audit DOM/computed-style evidence into migration-owned Astro implementation previews and additive semantic token extensions. Contracts remain the public API boundary: production HTML is not copied verbatim and unobserved interactive/runtime behavior is not fabricated. sitespec migrate design-system materialize <analysis> assembles the reviewed foundation tokens, accepted manifests, shell contract, and—when current—those implementation previews into design-system-staging/. Before inference the pack stays contract-only/partial; after inference expected Astro files are copied and Design System lint runs. Pending/rejected families remain excluded, while missing local font binaries are reported as visual-fidelity follow-up rather than being replaced with bundled starter assets.