cto-legends · module specification · foundation · v0.2.1
legends-astro: Astro v7 Migration Contracts, Content Layer & Build Parity CLI
Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.
GitHub Repository (https://github.com/avalonreset/legends-astro) · Handoff: cto-legends handoff legends-astro
legends-astro (succeeding the legacy alias legends-astro-kit) is a portable Python 3.11+ and Node.js 22.12+ CLI that gives coding agents deterministic pre-migration contract extraction, Astro v7 Content Layer scaffolding, offline official documentation search, and post-build dist/ parity verification. It is designed for WordPress to Astro, Next.js to Astro, and legacy static HTML to Astro v7 rebuilds where preserving SEO equity, URL route shapes, structured data, and interactive client DOM selectors is mandatory.
Architecturally, legends-astro separates static project readiness checks (legends_astro/cli.py and scripts/doctor.mjs), source-to-contract extraction and HTML-to-Markdown conversion (legends_astro/auditor.py), SHA-256-verified documentation indexing (legends_astro/docs_nav.py), and Empire knowledge pack attachment (knowledge/astro/pack.json). Every inspection of consumer astro.config.* files and project scripts runs as static text/regex analysis without importing or executing untrusted JavaScript code.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Prompting a raw frontier LLM to 'convert my WordPress or HTML site to Astro' routinely fails in six predictable ways: generating obsolete Astro v4/v5 Content Collections syntax (src/content/config.ts, type: 'content', and entry.slug) from stale pre-training data, dropping DOM id attributes required by client-side JavaScript, bundling inline first-paint CSS so the page flashes on load, silently altering URL route shapes (/page.html vs /page/index.html), leaking draft: true posts into production builds, and invoking the global Astronomer Airflow astro binary on Windows PATH.
- Pre-Migration Contract Extraction (migration-contract.json): source-audit parses legacy HTML directories, WordPress WXR .xml exports, WordPress REST .json dumps, or legends-firecrawl .json captures into a deterministic JSON contract recording every route, URL shape (file, directory, clean, root), <title>, meta description, canonical URL, OpenGraph/Twitter tags, JSON-LD @type blocks, and DOM IDs cross-referenced against getElementById and querySelector('#...') calls.
- Mechanical Post-Build dist/ Parity & Draft Leak Verification: verify-build inspects the compiled dist/ directory against migration-contract.json and src/content/ to verify 100% route presence, zero leaked draft: true routes or body text, intact SEO and JSON-LD blocks, preserved client-JS DOM IDs, inline <style data-first-paint> ordering before <script> tags in <head>, and unbroken internal links and local assets.
- Static Astro v7 Config Inspection & Pinned Docs Provenance: doctor validates Node runtime floors (>=22.12.0 for astro@7.3.1, >=22.23.4 for astro@7.4.2), detects global Astronomer CLI PATH collisions, and flags Astro v7 traps without executing consumer astro.config.* files. docs-lookup searches 24 vendored withastro/docs MDX guides verified by SHA-256 against vendor/astro-docs/manifest.json, avoiding broken upstream /llms.txt 404 endpoints.
CLI Subcommands & Capability Surface
legends-astro doctor [--project <dir>] [--strict-pin] [--live] [--json] — Runtime, PATH Collision & Astro v7 Readiness Doctor: Checks Node.js runtime versions (>=22.12.0 / >=22.23.4, tested LTS 24.15.0), detects global astro PATH collisions with the Astronomer Airflow CLI, verifies the 27-file vendor/astro-docs/manifest.json SHA-256 snapshot and knowledge/astro/pack.json, and inspects local node_modules/astro/bin/astro.mjs and lockfiles (npm, pnpm, yarn, bun). Flags legacy src/content/config.ts traps and unguarded prerender = false routes statically without executing consumer config code.legends-astro source-audit --source <html-or-wp-or-firecrawl> [--output migration-contract.json] [--base-url <url>] — Deterministic Source Contract Extraction: Audits static HTML trees, WordPress WXR .xml exports, WordPress REST .json dumps, or legends-firecrawl .json scrapes into a structured migration-contract.json. Extracts every route shape, recommended build.format and trailingSlash settings, SEO metadata, JSON-LD schemas, client-JS DOM id and data-* selectors, inline <head> styles, forms, asset references, and clean Markdown body text.legends-astro ingest --source <path> --output <astro-dir> [--apply] — Preview-First Astro v7 Content Layer Scaffolding: Previews the exact files required to stand up an Astro v7 Content Layer site from legacy sources without touching disk by default. When --apply is passed, generates src/content.config.ts using glob() from astro/loaders and z from astro/zod, src/lib/published.ts enforcing draft !== true filtering, converted Markdown entries under src/content/pages/*.md, public/_redirects for legacy URL aliases, and migration-contract.json.legends-astro verify-build --dist <dist-dir> [--project <astro-dir>] [--contract migration-contract.json] — Post-Build dist/ Parity, SEO, DOM ABI & Draft Safety Gate: Runs a deterministic post-build audit over compiled dist/ HTML files after node ./node_modules/astro/bin/astro.mjs build completes. Fails with structured diagnostics if any contracted route, <title>, meta description, JSON-LD block, or client-JS DOM ID is missing, if any draft: true entry from src/content/ leaked into dist/, if <style data-first-paint> is ordered after a <script>, or if internal links and assets fail to resolve.legends-astro docs-lookup ["<query>"] [--list] [--live-locations] [--check-live] — SHA-256 Pinned Astro v7 Docs & Runbook Lookup: Searches 24 vendored official withastro/docs MDX guides (pinned to commit 0844aab04ea2f3859132ab97b1e9daa01ade76a1) and 9 operational wiki/ runbooks completely offline. Provides verified upstream API endpoints (registry.npmjs.org/astro/latest and GitHub commits API) when --live-locations or --check-live is requested, bypassing upstream docs.astro.build/llms.txt HTTP 404s.legends-astro knowledge-pack --check / claude-empire.py knowledge attach knowledge/astro/pack.json — Attachable Empire Knowledge Pack & Migration Receipt Workflow: Validates the bundled legends.knowledge-pack/v1 manifest and SHA-256 file digests for attachment into an Empire vault under wiki/library/legends-astro/astro. Includes 9 source-cited Astro v7 engineering runbooks, a complete source ledger (references/sources.md), and a structured migration receipt template (templates/migration-receipt.md).
Raw Frontier LLM vs. legends-astro Execution Matrix
- Content Collections API & Schema Syntax: Raw LLM (Emits legacy Astro v4/v5 src/content/config.ts with type: 'content' and entry.slug from stale model training weights, failing Astro v7 builds.) vs. Module (Scaffolds and enforces Astro v7 Content Layer src/content.config.ts with glob() from astro/loaders, z from astro/zod, and entry.id routing.) — legends-astro doctor --project <dir> flags legacy config paths before build; canary astro@7.3.1 tests verify compilation.
- SEO Metadata, Route Shape & Redirect Parity: Raw LLM (Rewrites pages ad-hoc, silently dropping JSON-LD blocks, meta descriptions, or changing /slug.html routes to /slug/index.html without redirects.) vs. Module (Locks pre-migration route shapes, canonicals, meta tags, and JSON-LD in migration-contract.json and generates public/_redirects for legacy paths.) — legends-astro verify-build --dist <dist> --contract migration-contract.json asserts 1:1 route and metadata preservation.
- Client JavaScript DOM Selector Survival: Raw LLM (Refactors HTML markup into Astro components while renaming or stripping id and data-* attributes targeted by client scripts, breaking interactivity.) vs. Module (source-audit cross-references HTML id attributes against getElementById and querySelector calls in .js files and records required DOM IDs in the contract.) — verify-build parses compiled dist/ HTML and fails if any contracted client-JS DOM ID is absent.
- Draft Content Isolation & First-Paint CSS Ordering: Raw LLM (Forgets to filter draft: true entries in getStaticPaths() or bundles critical inline CSS after blocking scripts, leaking drafts and causing FOUC.) vs. Module (Generates src/lib/published.ts (draft !== true) and checks that <style data-first-paint> remains inline in <head> prior to any <script>.) — verify-build scans src/content/ for draft entries and asserts zero route or body-text leakage in dist/.
- Untrusted Repository Inspection & CLI Binary Safety: Raw LLM (Executes global astro commands (colliding with Astronomer Airflow CLI on Windows) or imports untrusted astro.config.mjs files during audits.) vs. Module (Inspects consumer configs statically as text without code execution and enforces project-local node ./node_modules/astro/bin/astro.mjs invocation.) — pathCollisionCheck in doctor output and 4 negative tamper/escape self-tests in scripts/verify-sources.mjs.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why does legends-astro enforce src/content.config.ts instead of src/content/config.ts?
- Astro v7 uses the Content Layer API, which defines collections at src/content.config.ts using loader functions such as glob() from astro/loaders, schemas from astro/zod, and entry.id for routing. Legacy Astro v4/v5 patterns (src/content/config.ts, type: 'content', and entry.slug) frequently hallucinated by frontier LLMs fail in Astro v7 builds.
- Why does legends-astro warn about a global astro binary on PATH and require node ./node_modules/astro/bin/astro.mjs?
- Official Astro does not support global CLI installations, and on Windows (especially with winget) a global astro executable on PATH is frequently the Astronomer Airflow CLI. Invoking project-local node ./node_modules/astro/bin/astro.mjs guarantees the exact project-locked Astro compiler runs.
- How does legends-astro provide up-to-date Astro v7 documentation when docs.astro.build/llms.txt returns HTTP 404?
- Upstream requests to https://docs.astro.build/llms.txt and /llms-full.txt return HTTP 404. legends-astro ships a 27-file vendored snapshot of official withastro/docs MDX guides verified by SHA-256 against vendor/astro-docs/manifest.json, searchable offline via legends-astro docs-lookup, plus optional live drift probes against registry.npmjs.org/astro/latest and the GitHub commits API.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.