create-ailk 0.30.0 → 0.31.0

package/component-catalog.md

@@ -15,13 +15,13 @@ The component inventory of `@working-theory/ui` and the shells of `@working-theo
 3. Check the Primitives, Panels and Shells tables too — a low-level control, a collapsible layout container, or a route-level frame lives there, not under Sections or Blocks.
 4. Only then build. If you do build, you are declaring the capability is genuinely absent.
 
-Inventory: **321 component files** across 16 tiers — 57 sections, 107 blocks, 19 chrome, 79 primitives, 6 panels, 8 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 6 scheduling-blocks, 5 signal-collectors-sections, 9 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 318 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
+Inventory: **324 component files** across 16 tiers — 60 sections, 107 blocks, 19 chrome, 79 primitives, 6 panels, 8 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 6 scheduling-blocks, 5 signal-collectors-sections, 9 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 321 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
 
-Description coverage: **317/321** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 238 from the component's own doc-comment header, 35 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
+Description coverage: **320/324** components carry a capability description derived from source — 45 from the section registry's hand-authored when-to-use text, 240 from the component's own doc-comment header, 35 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
 
-Of those, **283** are *strong* — a capability sentence you could match a requirement against — and **34** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
+Of those, **286** are *strong* — a capability sentence you could match a requirement against — and **34** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
 
-Per tier, strong out of total: **Sections** 56/57 · **Blocks** 99/107 · **Chrome** 10/19 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 7/8 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 6/6 · **Signal-Collectors Sections** 5/5 · **Signal-Collectors Blocks** 8/9 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
+Per tier, strong out of total: **Sections** 59/60 · **Blocks** 99/107 · **Chrome** 10/19 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 7/8 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 6/6 · **Signal-Collectors Sections** 5/5 · **Signal-Collectors Blocks** 8/9 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
 
 That grade is **mechanical**. It counts what it can measure — how much a description adds beyond the component's own name, how much of it is spent on wiring, whether the extraction came out damaged — and it cannot tell a fluent paragraph about the wrong subject from a useful one. A person reading these tables will find more rows unusable than the weak count admits. Treat it as a floor on the problem, not a measurement of it, and read the source before concluding a capability is absent.
 
@@ -53,7 +53,7 @@ The left column is search vocabulary — how a person phrases the need. It is ha
 
 ---
 
-## Sections (57)
+## Sections (60)
 
 Page-level content bands. Most are MDX-driven (authored by `type` in page frontmatter and dispatched by `SectionRenderer`); a few are composed directly in a route.
 
@@ -61,6 +61,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 
 | Component | What it does | How to use it |
 | --- | --- | --- |
+| `AddToCalendar` | An Event page's "Add to calendar" control. A Server Component of three plain links built by `eventCalendarLinks` in `@working-theory/schema`: Google Calendar and Outlook open in a new tab; Apple Calendar downloads the `.ics`. Rendered directly by `renderPage` for every Event page with a start date (the `BlogPost` precedent of a section a caller renders with typed props), never authored in `sections[]`. | `import { AddToCalendar } from "@working-theory/ui/sections"` |
 | `AlertSection` | A compact, dismissible in-page alert strip — use for a confirmation or status notice (e.g. a delivery-page 'your download is on its way' message), typically the first section on the page. Bounded to success/info/warning tone; dismissal persists per-visitor. | MDX `type: alert` |
 | `AlertSectionDismissIsland` | Dismiss state + × button for AlertSection. Mirrors the chrome Banner's dismiss-persistence precedent (`packages/ui/src/chrome/BannerDismissIsland.tsx`): a localStorage-backed dismissed flag, read on mount and written on dismiss, with graceful degradation when localStorage is unavailable (SSR, iframe, quota, etc.). | internal — compose from `packages/ui/src/sections/AlertSectionDismissIsland.tsx` |
 | `AskAi` | Use above the footer — hands the visitor to a third-party AI seeded with the entity question. Bounded to five measured providers (ChatGPT/Claude/Google AI/Grok/Perplexity), each deep-linked with an authored prompt. The `ticker` variant renders a compact full-width band instead of the default headline/description/provider-row layout. | MDX `type: ask-ai` |
@@ -92,6 +93,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 | `HeroIntakeContext` | The bounded seam through which a consumer page mounts its own conversational intake as the FIRST surface INSIDE one of Hero's existing gate surfaces (the `lightboxCta` FormLightbox, or the panel variant's form-slot card), with the existing multi-step StepFlow as the in-gate fallback (correcting 's whole-page swap). | `import { HeroIntakeContext } from "@working-theory/ui/sections"` |
 | `HeroPromptCapture` | The Hero `promptCapture` opt-in's wiring. Composes the two new blocks — `PromptCaptureCard` (the chat-style card) and `SuggestionChipCarousel` (the one-expanded-slot chip row) — and owns the ONE piece of state they share: the typed text. A chip click writes into it; the card renders and edits it; submit carries it onward. | `import { HeroPromptCapture } from "@working-theory/ui/sections"` |
 | `HeroQuickSearch` | Surfaces the existing ⌘K quick-search as an inline trigger inside the hero CTA cluster (Chassis 2). It does NOT re-roll a search input: it composes the SearchInputTrigger primitive (an input-style control at CTA height) plus the Command palette primitive, so there is ONE search mechanism. The nav's compact 24px ⌘K pill stays as-is — the hero reads as a search INPUT, matching the 44px "Get Started" CTA. | internal — compose from `packages/ui/src/sections/HeroQuickSearch.tsx` |
+| `HeroTypedHeadline` | The centred Hero's `typing` opt-in. The headline, then each subheadline sentence, types on its own line with a caret: solid while letters appear, blinking at every pause and after the last line. THE FULL TEXT IS ALWAYS IN THE DOM: each row renders its typed part and its untyped rest, and only the split point moves. | internal — compose from `packages/ui/src/sections/HeroTypedHeadline.tsx` |
 | `Items` | A general-purpose card/items grid — use for services, use cases, or any homogeneous list of cards. | MDX `type: items` · `import { Items } from "@working-theory/ui/sections"` |
 | `ItemsFilterIsland` | A search box and facet selects over an items section's cards. Items (a Server Component) renders every card on the server and wraps each in an `ItemsFilterSlot`; the island only decides which slots show. So every card is in the server HTML, and before hydration (or with no JavaScript) every slot is visible. | internal — compose from `packages/ui/src/sections/ItemsFilterIsland.tsx` |
 | `ItemsTileLinkIsland` | Makes a whole linked tile card its link's click target. | internal — compose from `packages/ui/src/sections/ItemsTileLinkIsland.tsx` |
@@ -102,6 +104,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 | `Newsletter` | An email signup form — use for a low-commitment conversion ask. | MDX `type: newsletter` · `import { Newsletter } from "@working-theory/ui/sections"` |
 | `Objection` | Objection-and-response pairs — use for you-might-think rhetoric that isn't phrased as a question. | MDX `type: objection` |
 | `Pricing` | A plan comparison — the page's pricing decision surface; six variants cover tables, toggles, single-price offers, and add-on grids. | MDX `type: pricing` · `import { Pricing } from "@working-theory/ui/sections"` |
+| `ProjectListings` | The site's public project listings — each a name linking to /projects/<slug>, newest decided first, at most `limit` (default 6), no logos. Use it on the home to show what the site lists; the rows are filled at render from the site's public project listings, never authored, and with none (or the API unreachable) the section is removed from the page. Author only the eyebrow, headline, description and `limit`. | MDX `type: project-listings` |
 | `ReportHeader` | The tiny header the chrome-off report reader puts above the document — a back arrow and the report's title, nothing else. Use it ONLY with `document-viewer` on a /reports/<slug> page; it is not a hero and has no description, CTA or media slot. `backHref` is optional: a reader who arrived from an emailed link has nowhere to go back to, and the header renders the title alone rather than a dead control. | MDX `type: report-header` |
 | `ReportsList` | A listing of reports, each linking to /reports/<slug>. Two variants over one data shape: `cards` (default) is a titled grid with cover, date and a Read link — the home or resources listing; `list` is centered titles with dates and no covers, for a full-bleed slide (set `tone: "on-dark"` on a dark surface). Not for blog posts — that is `blog-list`. | MDX `type: reports-list` |
 | `SchedulerEmbed` | A declarative third-party booking iframe (e.g. Google Calendar Appointment Schedules) — use for a booking/scheduling moment; sets the provider's cookies on load, so a site classifying it as non-essential may wrap it in a consent gate. | MDX `type: scheduler-embed` · `import { SchedulerEmbed } from "@working-theory/ui/sections"` · `packages/ui/src/sections/SchedulerEmbed.tsx` |

package/dist/cli.js

@@ -23,6 +23,14 @@
  *      agent key from AILK_AGENT_KEY, print one line per page and the count
  *      line, exit 1 if any failed (2 on a refusal it names, nothing sent)
  *      (#10207)
+ *      on an `inventory` subcommand: freeze a site's URLs into
+ *      .ailk-cutover/inventory.json once and audit each page against its
+ *      workspace, exit 1 if any prose page fails (2 on a refusal) (#10648)
+ *      on an `export-content` subcommand: write every published page back to
+ *      its content file, sections recombined, exit 1 if any failed (#10648)
+ *      on a `cutover` subcommand: plan — or, with --apply, run — the eight
+ *      cutover steps, stopping at the first failure, exit 1 (2 on a refusal)
+ *      (#10648)
  *      on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
  *      print the report, exit (1 iff routes are missing in check mode)
  *      on a `license set` subcommand: write the key into the scaffold, push it
@@ -70,6 +78,9 @@ import { ADOPT_HELP, AdoptRefusedError, adoptSite, formatAdoptReport, parseAdopt
 import { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 import { CLAUDE_MD_CHECK_PATH } from "./claude-md.js";
 import { buildScaffoldMarkers } from "./copy.js";
+import { CUTOVER_HELP, CutoverRefusedError, cutover, parseCutoverArgs, } from "./cutover.js";
+import { EXPORT_CONTENT_HELP, ExportContentRefusedError, exportContent, parseExportContentArgs, } from "./export-content.js";
+import { INVENTORY_HELP, InventoryRefusedError, inventory, parseInventoryArgs, } from "./inventory.js";
 import { ImportMdxRefusedError } from "./lib/import-mdx.js";
 import { assertKeyedOrFreeReleased, assertReleased } from "./lib/module-license-gate.js";
 import { withNpmTokenUserConfig } from "./lib/npm-auth.js";
@@ -351,6 +362,94 @@ async function main() {
             process.exit(2);
         }
     }
+    // `inventory [dir]` (#10648): freeze a site's URL set and audit each page
+    // against its workspace.
+    if (argv[0] === "inventory") {
+        try {
+            const args = parseInventoryArgs(argv.slice(1));
+            if (args.help) {
+                process.stdout.write(INVENTORY_HELP);
+                process.exit(0);
+            }
+            const { exitCode } = await inventory({
+                targetDir: args.target ?? process.cwd(),
+                origin: args.origin,
+                refreeze: args.refreeze,
+                docsPath: args.docsPath,
+                apiUrl: args.apiUrl,
+                workspaceId: args.workspaceId,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof ParseError) && !(err instanceof InventoryRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(2);
+        }
+    }
+    // `export-content [dir]` (#10648): the cutover's rollback — every published
+    // page back to its content file.
+    if (argv[0] === "export-content") {
+        try {
+            const args = parseExportContentArgs(argv.slice(1));
+            if (args.help) {
+                process.stdout.write(EXPORT_CONTENT_HELP);
+                process.exit(0);
+            }
+            const { exitCode } = await exportContent({
+                targetDir: args.target ?? process.cwd(),
+                dryRun: args.dryRun,
+                apiUrl: args.apiUrl,
+                workspaceId: args.workspaceId,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof ParseError) && !(err instanceof ExportContentRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(2);
+        }
+    }
+    // `cutover [dir]` (#10648): the eight cutover steps, a dry run by default.
+    if (argv[0] === "cutover") {
+        try {
+            const args = parseCutoverArgs(argv.slice(1));
+            if (args.help) {
+                process.stdout.write(CUTOVER_HELP);
+                process.exit(0);
+            }
+            const { exitCode } = await cutover({
+                targetDir: args.target ?? process.cwd(),
+                before: args.before,
+                after: args.after,
+                apply: args.apply,
+                ...(args.envTarget !== undefined && { envTarget: args.envTarget }),
+                docsPath: args.docsPath,
+                ...(args.pixelTolerance !== undefined && { pixelTolerance: args.pixelTolerance }),
+                apiUrl: args.apiUrl,
+                workspaceId: args.workspaceId,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof ParseError) &&
+                !(err instanceof CutoverRefusedError) &&
+                !(err instanceof InventoryRefusedError) &&
+                !(err instanceof MigrateContentRefusedError) &&
+                !(err instanceof ImportMdxRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(2);
+        }
+    }
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
     // argv shape (#4986). Check mode exits 1 iff a template route is missing;
     // locally modified routes are reported but do not fail; --apply exits 0.

package/dist/cutover.d.ts

@@ -0,0 +1,109 @@
+import { type WordsCodec, type WorkspaceRow } from "./inventory.js";
+import { type LanguageImportResult } from "./language-import.js";
+import { type ImportMdxOutcome, type ImportMdxResult, type MdxAdapterModule } from "./lib/import-mdx.js";
+export declare const CUTOVER_STEPS: readonly ["import", "publish", "inventory", "comparison", "set-env", "deploy", "verify", "remove-files"];
+export type CutoverStep = (typeof CUTOVER_STEPS)[number];
+export declare const ENV_TARGETS: readonly ["preview", "production"];
+export type EnvTarget = (typeof ENV_TARGETS)[number];
+/** A refusal the CLI exits 2 on, raised before step 1. */
+export declare class CutoverRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+/** A spawned command, no shell: its status and captured stdout. */
+export type Runner = (command: string, args: string[], options: {
+    cwd: string;
+    input?: string;
+}) => {
+    status: number | null;
+    stdout: string;
+    error?: string;
+};
+/** The default runner: `spawnSync` with no shell, stdout piped, stderr shown. */
+export declare const spawnRunner: Runner;
+/** Every step's collaborator; a test injects fakes, the CLI takes the defaults. */
+export interface CutoverDeps {
+    migrate: (o: {
+        apply: boolean;
+    }) => Promise<{
+        result: ImportMdxResult;
+        exitCode: 0 | 1;
+        language?: LanguageImportResult;
+    }>;
+    list: () => Promise<WorkspaceRow[]>;
+    inventory: () => Promise<{
+        exitCode: 0 | 1;
+        summary: string;
+    }>;
+    /** The frozen page paths compared, and every frozen path swept. */
+    frozen: () => {
+        pages: string[];
+        sweep: string[];
+    } | undefined;
+    compare: (o: {
+        after: string;
+        pages: string[];
+        sweep: string[];
+        screenshots: boolean;
+        dir: string;
+    }) => Promise<{
+        pass: boolean;
+        summary: string;
+    }>;
+    run: Runner;
+    git: Runner;
+}
+export interface CutoverOptions {
+    targetDir: string;
+    /** The site served from files. */
+    before?: string | undefined;
+    /** A deployment reading the database. */
+    after?: string | undefined;
+    apply?: boolean;
+    envTarget?: EnvTarget;
+    docsPath?: string | undefined;
+    /** The share of pixels that may differ; default 0. */
+    pixelTolerance?: number;
+    apiUrl?: string | undefined;
+    workspaceId?: string | undefined;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof globalThis.fetch;
+    /** Injectable for tests; defaults to the site's installed adapter. */
+    adapters?: MdxAdapterModule;
+    /** Injectable for tests; defaults to the site's installed codec. */
+    codec?: WordsCodec;
+    /** Injectable for tests: names the run's directory. */
+    now?: () => Date;
+    deps?: Partial<CutoverDeps>;
+    onLine?: (line: string) => void;
+}
+export interface StepRecord {
+    n: number;
+    name: CutoverStep;
+    status: "passed" | "failed" | "not-run" | "planned";
+    command: string;
+    evidence: string[];
+}
+/**
+ * Step 8's paths: each imported file under the root it came from, repo-relative
+ * (D8). An outcome's path is relative to the content root the importer walked.
+ */
+export declare function removablePaths(pages: readonly ImportMdxOutcome[]): string[];
+export declare function cutover(opts: CutoverOptions): Promise<{
+    exitCode: 0 | 1;
+    steps: StepRecord[];
+}>;
+export interface CutoverArgs {
+    target: string | undefined;
+    before: string | undefined;
+    after: string | undefined;
+    apply: boolean;
+    envTarget: EnvTarget | undefined;
+    docsPath: string | undefined;
+    pixelTolerance: number | undefined;
+    apiUrl: string | undefined;
+    workspaceId: string | undefined;
+    help: boolean;
+}
+export declare const CUTOVER_HELP = "create-ailk cutover \u2014 move a site from its page files to its database, one checked step at a time.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk cutover [<dir>] --before <origin> --after <origin> [--apply] [--env-target preview|production] [--docs-path <path>] [--pixel-tolerance <ratio>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                      The site. Defaults to the current dir.\n\nOptions:\n  --before <origin>          The site served from its files.\n  --after <origin>           A deployment reading the database (a preview\n                             with CONTENT_ADAPTER=database).\n  --apply                    Run the steps. Without it the command plans\n                             them: it sends only reads, spawns nothing and\n                             writes nothing.\n  --env-target <target>      preview (the default) or production \u2014 where\n                             step 5 sets CONTENT_ADAPTER and step 6 deploys.\n  --docs-path <path>         Where the site serves its docs. Default /docs.\n  --pixel-tolerance <ratio>  The share of a screenshot's pixels that may\n                             differ. Default 0.\n  --api-url <origin>         The API origin that holds the workspace \u2014 on a\n                             spoke, its hub's. Else AILK_API_URL.\n  --workspace <wksp_id>      The workspace. Else AILK_WORKSPACE_ID.\n  -h, --help                 Show this help.\n\nSteps, in this order; the first that fails stops the run:\n  1 import        create-ailk migrate-content <dir> --apply; stops, before\n                  writing, when the import would change a page's render\n  2 publish       every imported page is published (publish in Admin)\n  3 inventory     create-ailk inventory <dir> --origin <before>; audit passes\n  4 comparison    text, JSON-LD and screenshots per frozen page, before and\n                  after, at 1440 and 390 wide; every frozen URL answers 200\n  5 set env       vercel env add CONTENT_ADAPTER <target> = database (apps/web)\n  6 deploy        vercel deploy [--prod] (apps/web)\n  7 verify        text and JSON-LD per frozen page on the deployment; 200s\n  8 remove files  git rm --quiet -- <the imported files> (staged, not committed)\n\nEach run writes .ailk-cutover/runs/<UTC time>/run.json and the comparison's\nevidence beside it (gitignored). The comparison needs Playwright's Chromium:\npnpm add -D @playwright/test && pnpm exec playwright install chromium. When VERCEL_AUTOMATION_BYPASS_SECRET is set,\nrequests to --after and the deployment carry it. The agent key needs the\ncontent-edit grant; on a spoke, AILK_SPOKE_KEY is needed too. The rollback\nis create-ailk export-content (docs/internal/runbooks/site-cutover.md).\nExit 0 when every step passed (a dry run: when the import plan has no\nfailed page), 1 when one failed, 2 on a refusal.\n";
+export declare function parseCutoverArgs(argv: string[]): CutoverArgs;