@storystick/cli 0.0.0-stage → 0.2.0-rc.1

package/dist/cli.js

@@ -0,0 +1,1520 @@
+#!/usr/bin/env node
+/**
+ * Storystick CLI
+ *
+ * Phase 0: `storystick generate`
+ * Reads .story files, resolves composition, generates TypeScript types.
+ *
+ * Future: `storystick dev` will add file watching + incremental regeneration.
+ * The pipeline function below is designed to be callable from both.
+ */
+import { resolveReleaseContext } from './release-context.js';
+import { pushReleaseSchema } from './release-schema-client.js';
+import { syncRelease } from './release-sync.js';
+import { cac } from 'cac';
+import pc from 'picocolors';
+import { existsSync, statSync } from 'fs';
+import { resolve, relative, dirname } from 'path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { generateTypes, generateQueryTypes, generatePreviewProvenanceManifest, } from '@storystick/core';
+import { serializeSchema } from '@storystick/core/serializer';
+import { rewrapStorystickError } from './cli-error.js';
+import { assertSchemaPlanAllowed, fetchSchemaChangePlan, fetchSchemaPushToken, pushSchema, schemaPlanFence, schemaToPushBody, } from './push-client.js';
+import { printBackfillRecommendation } from './_backfill-recommendation.js';
+import { changeSpinner, configureOutput, diagnosticToJson, emitJsonResult, exitJsonFailure, exitWithError, formatDiagnostic, getOutputMode, isVerbose, logFinishedStep, logMessage, logOutput, logWarning, promptDeviceAuth, succeedSpinner, withInterrupt, withSlowSpinner, } from './output.js';
+import { commitPreparedGeneration, commitGeneratedFiles, prepareGeneratedFiles, } from './generated-transaction.js';
+import { clearSyncOperation, markSyncOperationPushed, readSyncOperation, writePreparedSyncOperation, } from './sync-transaction.js';
+import { resolveCliRuntimeConfig } from './runtime-config.js';
+import { buildExternalMigrationArtifact } from './migration-artifact.js';
+import { requireProjectConnection, validateProjectTokenReadback, } from './project-connection.js';
+import { runResolve } from './resolve.js';
+export { runResolve } from './resolve.js';
+// ─── Resolve pipeline (shared by generate, push, sync) ───
+/**
+ * Run the full pipeline: discover → parse → resolve → generate → write.
+ *
+ * ADR-072 §A1 (lock T3 / L7): writes are gated on `resolved.success`. A
+ * failed resolve no longer writes a partial / stale `dist/` to disk; init
+ * and link pick up the gap via `result.success === false` and surface
+ * "run manually" hints instead of silent half-bootstrapped projects.
+ */
+export async function runPipeline(options) {
+    const { rootDir, storyDirs, outputDir, corePath } = options;
+    const prepared = await preparePipeline({ rootDir, storyDirs, corePath });
+    if (!prepared.success) {
+        return {
+            storyCount: prepared.stories.size,
+            diagnostics: prepared.diagnostics,
+            success: false,
+            generatedFiles: [],
+            stories: prepared.stories,
+        };
+    }
+    const absOutputDir = resolve(rootDir, outputDir);
+    const committed = await commitGeneratedFiles(absOutputDir, prepared.generated, {
+        check: options.check,
+        faultAt: options.generationFaultAt,
+    });
+    return {
+        storyCount: prepared.stories.size,
+        diagnostics: prepared.diagnostics,
+        success: prepared.success,
+        generatedFiles: [...committed.files],
+        stories: prepared.stories,
+    };
+}
+/**
+ * Resolve and generate entirely in memory. `init` and `sync` use this seam to
+ * prove the local project is viable before either a remote effect or a local
+ * generation pointer is published.
+ */
+export async function preparePipeline(options) {
+    const resolved = await runResolve(options);
+    return {
+        ...resolved,
+        generated: resolved.success
+            ? [
+                ...generateTypes(resolved.stories),
+                generateQueryTypes(resolved.stories),
+                generatePreviewProvenanceManifest(resolved.stories),
+            ]
+            : [],
+    };
+}
+/**
+ * Spinner threshold for push / sync / generate (ADR-072 §D11). Shorter
+ * than `init`'s 2000ms — steady-state schema work is sub-second on a
+ * small project, so a 800ms gate keeps the UX silent for the common
+ * case while still surfacing liveness on the slow paths.
+ */
+const SPINNER_DELAY_MS = 800;
+function renderSchemaPlan(plan) {
+    const base = plan.baseVersion?.slice(0, 8) ?? 'none';
+    logMessage(`${pc.bold('Schema plan')}: ${plan.classification} (${base} → ${plan.nextVersion.slice(0, 8)})`);
+    for (const change of plan.changes) {
+        logMessage(pc.dim(`  ${change.path}: ${change.message}`));
+    }
+}
+function renderNewBindingNotes(notes) {
+    for (const note of notes)
+        logWarning(note.message);
+}
+// ─────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────
+export function findCorePath(rootDir) {
+    // `--root` selects the consumer project. Resolve its installed core stories
+    // before considering the CLI process CWD so monorepo and CI invocations are
+    // equivalent to running the command from inside that project.
+    const projectPath = resolve(rootDir, 'node_modules', '@storystick', 'core', 'stories', 'core');
+    if (existsSync(projectPath))
+        return projectPath;
+    // Resolve the CLI's declared ESM dependency, including strict pnpm installs.
+    // package.json is private to core and is not part of its exports contract.
+    try {
+        const coreEntry = fileURLToPath(import.meta.resolve('@storystick/core'));
+        const coreRoot = resolve(dirname(coreEntry), '..');
+        const corePath = resolve(coreRoot, 'stories', 'core');
+        if (existsSync(corePath))
+            return corePath;
+    }
+    catch {
+        // Fall through to the CWD-relative fallback.
+    }
+    // Fallback: cwd-relative node_modules lookup.
+    const nmPath = resolve('node_modules', '@storystick', 'core', 'stories', 'core');
+    if (existsSync(nmPath))
+        return nmPath;
+    // Warn but don't fail — core stories enhance but aren't required.
+    logWarning('Core stories not found. Built-in types may be unavailable.');
+    return nmPath;
+}
+/**
+ * Scan for directories containing .story files.
+ * If specific dirs are given, use those. Otherwise scan common locations.
+ */
+function findStoryDirs(rootDir, explicit) {
+    if (explicit && explicit.length > 0)
+        return explicit;
+    // Convention-based discovery (avoid scanning entire project with '.')
+    const candidates = [
+        'stories',
+        'src/stories',
+        'content/stories',
+        'src',
+        'components',
+    ];
+    const found = candidates.filter((dir) => {
+        const full = resolve(rootDir, dir);
+        return existsSync(full) && statSync(full).isDirectory();
+    });
+    // Default to 'stories' if nothing found (clearer error than scanning everything)
+    return found.length > 0 ? found : ['stories'];
+}
+function envSection(entries) {
+    // Two columns + purpose. Column widths sized once based on entries.
+    const nameW = Math.max(...entries.map(([n]) => n.length));
+    const kindW = Math.max(...entries.map(([, k]) => k.length));
+    const lines = entries.map(([n, k, p]) => `  ${n.padEnd(nameW)}  ${k.padEnd(kindW)}  ${p}`);
+    return { title: 'Environment', body: lines.join('\n') };
+}
+const ENV_SCHEMA_PUSH = [
+    ['STORYSTICK_PROJECT_ID', 'required', 'Project shortId'],
+    [
+        'NEXT_PUBLIC_STORYSTICK_PROJECT_ID',
+        'required',
+        'Matching public project shortId',
+    ],
+    [
+        'STORYSTICK_API_KEY',
+        'required',
+        'Pattern D auth — exchange for short-lived JWT',
+    ],
+    [
+        'NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY',
+        'required',
+        'Matching browser-safe project key',
+    ],
+    ['STORYSTICK_GATEWAY_URL', 'optional', 'Override Pattern D gateway URL'],
+];
+const ENV_INIT = [
+    [
+        'STORYSTICK_STARTER_CATALOG_URL',
+        'optional',
+        'Override the HTTPS starter catalog',
+    ],
+    ['STORYSTICK_HUB_URL', 'optional', 'Override the account and project Hub'],
+    ['STORYSTICK_GATEWAY_URL', 'optional', 'Override the project gateway'],
+];
+const ENV_BACKFILL = [
+    ['STORYSTICK_PROJECT_ID', 'required', 'Project shortId'],
+    [
+        'NEXT_PUBLIC_STORYSTICK_PROJECT_ID',
+        'required',
+        'Matching public project shortId',
+    ],
+    [
+        'STORYSTICK_API_KEY',
+        'required',
+        'Pattern D auth — exchange for short-lived JWT',
+    ],
+    [
+        'NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY',
+        'required',
+        'Matching browser-safe project key',
+    ],
+    ['STORYSTICK_GATEWAY_URL', 'optional', 'Override Pattern D gateway URL'],
+];
+const ENV_SLICE_PREVIEWS = [
+    ['STORYSTICK_PROJECT_ID', 'required', 'Project shortId (or pass --project)'],
+    ['STORYSTICK_HUB_URL', 'optional', 'Override the account and project Hub'],
+    ['STORYSTICK_GATEWAY_URL', 'optional', 'Override the project gateway'],
+];
+const cli = cac('storystick');
+cli.command('setup', 'Inspect local project setup without changing files or running scripts')
+    .option('--root <dir>', 'Application directory', { default: '.' })
+    .option('--remote', 'Also read source and delivery setup using your CLI login')
+    .option('--project <shortId>', 'Project to inspect remotely (defaults to local connection)')
+    .option('--json', 'Emit structured facts and next actions')
+    .action(async (options) => {
+    const { runSetup } = await import('./commands/setup.js');
+    await runSetup(options);
+});
+cli.command('schema', 'Validate and export the compiled schema locally; does not push or publish')
+    .option('--root <dir>', 'Application directory', { default: '.' })
+    .option('--stories <dirs>', 'Directories to scan (comma-separated)')
+    .option('--out <file>', 'Project-relative schema output', { default: 'generated/storystick-schema.json' })
+    .option('--json', 'Emit the output identity as JSON')
+    .action(async (options) => {
+    configureOutput({ json: options.json === true });
+    const { dispose } = withInterrupt();
+    try {
+        const { exportSchema } = await import('./schema-export.js');
+        const rootDir = resolve(options.root);
+        const result = await exportSchema({ rootDir, storyDirs: findStoryDirs(rootDir, options.stories?.split(',').map((s) => s.trim())), corePath: findCorePath(rootDir), out: options.out });
+        if (getOutputMode() === 'json')
+            emitJsonResult({ command: 'schema', ok: true, data: result });
+        else
+            logFinishedStep(`Exported ${result.storyCount} stories to ${result.path}`);
+    }
+    catch (err) {
+        if (getOutputMode() === 'json')
+            exitJsonFailure({ command: 'schema', err });
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+});
+cli
+    .command('generate', 'Generate TypeScript types from .story files')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--output <dir>', 'Output directory for generated types', {
+    default: 'generated/storystick',
+})
+    .option('--stories <dirs>', 'Directories to scan (comma-separated)')
+    .option('--verbose', 'Render info-level diagnostics and warning details')
+    .option('--quiet', 'Suppress success and warning output (failures still emit)')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .option('--check', 'Check generated artifacts without modifying files')
+    .example('  $ storystick generate')
+    .example('  $ storystick generate --root apps/web --output src/types/storystick')
+    .example('  $ storystick generate --stories stories,storybook-stories')
+    .action(async (options) => {
+    configureOutput({
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+    // Canonical command shell (ADR-072 §D2). Inline by design — `dispose()`
+    // is semantic-critical and stays visible at the call site. `signal`
+    // becomes load-bearing once Batch 7 wires exit 130 (D13) into the
+    // parse path; pre-D13 it's just a no-op handle that disposes cleanly.
+    const { signal, dispose } = withInterrupt();
+    void signal;
+    try {
+        const rootDir = resolve(options.root);
+        const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((s) => s.trim()));
+        const corePath = findCorePath(rootDir);
+        logMessage(`${pc.bold('Storystick')} — generating types...`);
+        logMessage(pc.dim(`Root: ${rootDir}`));
+        logMessage(pc.dim(`Stories: ${storyDirs.join(', ')}`));
+        logMessage(pc.dim(`Core: ${relative(rootDir, corePath) || corePath}`));
+        // ADR-072 §D11: spinner only when the work is actually slow
+        // (>800ms). Async I/O foundation (Batch 0) is what makes the
+        // setTimeout fire — pre-Batch-0 the parse path blocked the event
+        // loop and the spinner never rendered.
+        const result = await withSlowSpinner('Generating types…', SPINNER_DELAY_MS, () => runPipeline({
+            rootDir,
+            storyDirs,
+            outputDir: options.output,
+            corePath,
+            check: options.check === true,
+        }));
+        // Print diagnostics
+        const errors = result.diagnostics.filter((d) => d.severity === 'error');
+        const warnings = result.diagnostics.filter((d) => d.severity === 'warning');
+        const infos = result.diagnostics.filter((d) => d.severity === 'info');
+        // ADR-072 §D15: under --json, emit the structured envelope and skip
+        // the human-readable diagnostic / success block (those go to stderr
+        // under --json anyway via the muted log primitives).
+        if (getOutputMode() === 'json') {
+            if (result.success) {
+                emitJsonResult({
+                    command: 'generate',
+                    ok: true,
+                    data: {
+                        storyCount: result.storyCount,
+                        generatedFiles: result.generatedFiles,
+                    },
+                    diagnostics: result.diagnostics.map(diagnosticToJson),
+                });
+                return;
+            }
+            exitJsonFailure({
+                command: 'generate',
+                err: new Error(`Generation failed with ${errors.length} error(s)`),
+                diagnostics: result.diagnostics.map(diagnosticToJson),
+            });
+        }
+        // ADR-072 §D5 / D12: under --verbose, info-level diagnostics are
+        // rendered inline; default mode shows them as a "suppressed" count.
+        const renderable = isVerbose()
+            ? [...errors, ...warnings, ...infos]
+            : [...errors, ...warnings];
+        for (const d of renderable) {
+            logMessage(formatDiagnostic(d, rootDir));
+        }
+        if (!isVerbose() &&
+            infos.length > 0 &&
+            (errors.length > 0 || warnings.length > 0)) {
+            logMessage(pc.dim(`  + ${infos.length} info message(s) suppressed`));
+        }
+        if (result.success) {
+            logFinishedStep(`Generated types for ${pc.bold(String(result.storyCount))} stories`);
+            for (const f of result.generatedFiles) {
+                logMessage(pc.dim(`  ${relative(rootDir, f)}`));
+            }
+            // ADR-072 §D5 + F3: post-success warning count with discoverability
+            // hint pointing the user at --verbose for full details. Under
+            // --verbose, list the details inline instead of just counting.
+            if (warnings.length > 0) {
+                if (isVerbose()) {
+                    for (const w of warnings) {
+                        logWarning(formatDiagnostic(w, rootDir));
+                    }
+                }
+                else {
+                    logWarning(`${warnings.length} warning(s) (use --verbose to see)`);
+                }
+            }
+        }
+        else {
+            exitWithError(`Generation failed with ${pc.bold(String(errors.length))} error(s)`);
+        }
+    }
+    catch (err) {
+        if (getOutputMode() === 'json') {
+            exitJsonFailure({ command: 'generate', err });
+        }
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+});
+// ─────────────────────────────────────────────
+// Push command
+// ─────────────────────────────────────────────
+cli
+    .command('push', 'Push resolved schemas to Storystick')
+    .option('--release <id>', 'Target an unpublished release (or use the selected CLI release)')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--stories <dirs>', 'Directories to scan (comma-separated)')
+    .option('--verbose', 'Show endpoint URL, info-level diagnostics, warning details')
+    .option('--quiet', 'Suppress success and warning output (failures still emit)')
+    .option('--dry-run', 'Plan schema changes without publishing them')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .example('  $ storystick push')
+    .example('  $ storystick push --dry-run')
+    .example('  $ storystick push --verbose')
+    .example('  $ storystick push --root apps/blog')
+    .action(async (options) => {
+    configureOutput({
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+    // Canonical command shell (ADR-072 §D2).
+    const { signal, dispose } = withInterrupt();
+    void signal;
+    try {
+        const rootDir = resolve(options.root);
+        const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((s) => s.trim()));
+        const corePath = findCorePath(rootDir);
+        const runtime = resolveCliRuntimeConfig({ rootDir });
+        const release = resolveReleaseContext(rootDir, runtime.gatewayUrl, options.release);
+        if (release) {
+            const resolved = await runResolve({ rootDir, storyDirs, corePath });
+            if (!resolved.success)
+                throw Error(resolved.diagnostics.filter(d => d.severity === 'error').map(d => formatDiagnostic(d, rootDir)).join('\n'));
+            const result = await pushReleaseSchema({ context: release, schema: serializeSchema(resolved.stories, resolved.diagnostics), rootDir, dryRun: options.dryRun, signal });
+            if (getOutputMode() === 'json')
+                emitJsonResult({ command: 'push', ok: true, data: result });
+            else
+                logMessage(`Release ${release.releaseId}: ${result.status} (${result.version.slice(0, 8)}). Main unchanged.`);
+            return;
+        }
+        const connection = requireProjectConnection(rootDir);
+        logMessage(`${pc.bold('Storystick')} — pushing schemas...`);
+        logMessage(pc.dim(`Root: ${rootDir}`));
+        if (options.verbose) {
+            logMessage(pc.dim(`Gateway: ${runtime.gatewayUrl}`));
+        }
+        // ADR-072 §D11: single spinner that mutates across phases.
+        // "Resolving stories…" while the parse path runs, switching to
+        // "Pushing schemas…" once the network leg starts. The auto-✔ is
+        // suppressed (withSlowSpinner stops cleanly) — the structured
+        // success line below is the canonical UX.
+        //
+        // Diagnostics rendering happens AFTER the spinner stops. ora's
+        // concurrent-write handling is robust, but rendering inside the
+        // spinner closure interleaves with frame redraws and is harder
+        // to reason about. Render once the spinner is gone.
+        const phased = await withSlowSpinner('Resolving stories…', SPINNER_DELAY_MS, async () => {
+            const resolved = await runResolve({ rootDir, storyDirs, corePath });
+            if (!resolved.success) {
+                return { kind: 'resolve-failed', resolved };
+            }
+            changeSpinner('Planning schema changes…');
+            const schema = serializeSchema(resolved.stories, resolved.diagnostics);
+            const gatewayUrl = runtime.gatewayUrl;
+            const token = await fetchSchemaPushToken(gatewayUrl, connection.apiKey, {
+                signal,
+            });
+            validateProjectTokenReadback(token, connection);
+            const body = schemaToPushBody(schema);
+            const plan = await fetchSchemaChangePlan(gatewayUrl, token, body, {
+                signal,
+            });
+            if (options.dryRun === true) {
+                return { kind: 'planned', resolved, schema, plan };
+            }
+            assertSchemaPlanAllowed(plan);
+            changeSpinner('Pushing schemas…');
+            const pushResult = await pushSchema(gatewayUrl, token, body, schemaPlanFence(plan), { signal });
+            return { kind: 'ok', resolved, schema, plan, pushResult };
+        });
+        // Resolve outcomes — diagnostics first, then either error-exit or
+        // continue with the success path.
+        const errors = phased.resolved.diagnostics.filter((d) => d.severity === 'error');
+        const warnings = phased.resolved.diagnostics.filter((d) => d.severity === 'warning');
+        const infos = phased.resolved.diagnostics.filter((d) => d.severity === 'info');
+        const renderable = isVerbose()
+            ? [...errors, ...warnings, ...infos]
+            : [...errors, ...warnings];
+        for (const d of renderable) {
+            logMessage(formatDiagnostic(d, rootDir));
+        }
+        if (phased.kind === 'resolve-failed') {
+            if (getOutputMode() === 'json') {
+                exitJsonFailure({
+                    command: 'push',
+                    err: new Error(`Push failed: ${errors.length} error(s). Fix errors and try again.`),
+                    diagnostics: phased.resolved.diagnostics.map(diagnosticToJson),
+                });
+            }
+            exitWithError(`Push failed: ${pc.bold(String(errors.length))} error(s). Fix errors and try again.`);
+        }
+        // Type narrowing for the rest of the success path.
+        const { schema, plan } = phased;
+        if (phased.kind === 'planned') {
+            if (getOutputMode() === 'json') {
+                emitJsonResult({
+                    command: 'push',
+                    ok: true,
+                    data: {
+                        status: 'planned',
+                        version: schema.version,
+                        storyCount: schema.storyCount,
+                        plan,
+                    },
+                    diagnostics: phased.resolved.diagnostics.map(diagnosticToJson),
+                });
+                return;
+            }
+            renderSchemaPlan(plan);
+            logFinishedStep('Dry run complete; no schema was published.');
+            return;
+        }
+        const result = phased.pushResult;
+        if (getOutputMode() === 'json') {
+            emitJsonResult({
+                command: 'push',
+                ok: true,
+                data: {
+                    status: result.status,
+                    version: schema.version,
+                    storyCount: schema.storyCount,
+                    plan,
+                    newBindingNotes: result.newBindingNotes,
+                    recommendBackfill: result.recommendBackfill,
+                },
+                diagnostics: phased.resolved.diagnostics.map(diagnosticToJson),
+            });
+            return;
+        }
+        if (result.status === 'unchanged') {
+            logMessage(pc.dim(`Schemas unchanged (${schema.version.slice(0, 8)})`));
+        }
+        else {
+            logFinishedStep(`Pushed ${pc.bold(String(schema.storyCount))} stories (${schema.version.slice(0, 8)})`);
+        }
+        renderNewBindingNotes(result.newBindingNotes);
+        printBackfillRecommendation(result.recommendBackfill);
+        // ADR-072 §D5 + F3: post-success warning count + discoverability hint;
+        // under --verbose, list the warning details inline instead.
+        if (warnings.length > 0) {
+            if (isVerbose()) {
+                for (const w of warnings) {
+                    logWarning(formatDiagnostic(w, rootDir));
+                }
+            }
+            else {
+                logWarning(`${warnings.length} warning(s) (use --verbose to see)`);
+            }
+        }
+    }
+    catch (err) {
+        if (getOutputMode() === 'json') {
+            exitJsonFailure({ command: 'push', err });
+        }
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+});
+// ─────────────────────────────────────────────
+// Sync command (generate + push)
+// ─────────────────────────────────────────────
+cli
+    .command('sync', 'Generate types and push schemas (generate + push in one step)')
+    .option('--release <id>', 'Target an unpublished release (or use the selected CLI release)')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--output <dir>', 'Output directory for generated types', {
+    default: 'generated/storystick',
+})
+    .option('--stories <dirs>', 'Directories to scan (comma-separated)')
+    .option('--verbose', 'Show endpoint URL, info-level diagnostics, warning details')
+    .option('--quiet', 'Suppress success and warning output (failures still emit)')
+    .option('--dry-run', 'Plan without staging, publishing, or moving the pointer')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .example('  $ storystick sync')
+    .example('  $ storystick sync --dry-run')
+    .example('  $ storystick sync --verbose')
+    .action(async (options) => {
+    configureOutput({
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+    const { signal, dispose } = withInterrupt();
+    let failureStep = 'generate';
+    try {
+        const rootDir = resolve(options.root);
+        const outputDirectory = resolve(rootDir, options.output);
+        const release = resolveReleaseContext(rootDir, resolveCliRuntimeConfig({ rootDir }).gatewayUrl, options.release);
+        if (release) {
+            const result = await syncRelease({ context: release, rootDir, outputDirectory, dryRun: options.dryRun, signal, prepare: async () => {
+                    const prepared = await preparePipeline({ rootDir, storyDirs: findStoryDirs(rootDir, options.stories?.split(',').map((s) => s.trim())), corePath: findCorePath(rootDir) });
+                    if (!prepared.success)
+                        throw Error(prepared.diagnostics.filter(d => d.severity === 'error').map(d => formatDiagnostic(d, rootDir)).join('\n'));
+                    return { schema: serializeSchema(prepared.stories, prepared.diagnostics), generated: prepared.generated, storyCount: prepared.stories.size };
+                } });
+            if (getOutputMode() === 'json')
+                emitJsonResult({ command: 'sync', ok: true, data: result });
+            else
+                logMessage(`Synced release ${release.releaseId}. Main unchanged.`);
+            return;
+        }
+        // A confirmed remote push is the transaction's point of no return. If
+        // the previous process stopped after that point, finish the local
+        // pointer commit from the durable receipt without touching the network.
+        const pending = readSyncOperation(rootDir);
+        if (pending?.target)
+            throw Error('A release sync is pending. Select its release before resuming.');
+        if (pending?.state === 'prepared' &&
+            pending.outputDirectory !== outputDirectory) {
+            throw new Error(`A prepared sync exists for output ${pending.outputDirectory}. Resume with the same --output value.`);
+        }
+        if (pending?.state === 'pushed') {
+            if (options.dryRun === true) {
+                throw new Error('A pushed sync is waiting for its local commit. Run `storystick sync` without --dry-run to resume it.');
+            }
+            if (pending.outputDirectory !== outputDirectory) {
+                throw new Error(`A pushed sync is waiting for output ${pending.outputDirectory}. Resume with the same --output value.`);
+            }
+            failureStep = 'commit';
+            const committed = await commitPreparedGeneration(pending.outputDirectory, pending.generationId);
+            clearSyncOperation(rootDir);
+            const pushResult = pending.pushResult;
+            if (getOutputMode() === 'json') {
+                emitJsonResult({
+                    command: 'sync',
+                    ok: true,
+                    data: {
+                        resumed: true,
+                        generate: {
+                            storyCount: pending.storyCount,
+                            generatedFiles: committed.files,
+                        },
+                        push: {
+                            status: pushResult.status,
+                            version: pushResult.version,
+                            storyCount: pending.storyCount,
+                            newBindingNotes: pushResult.newBindingNotes,
+                            recommendBackfill: pushResult.recommendBackfill,
+                        },
+                    },
+                });
+                return;
+            }
+            logFinishedStep(`Resumed sync for ${pc.bold(String(pending.storyCount))} stories (${pending.schemaVersion.slice(0, 8)})`);
+            renderNewBindingNotes(pushResult.newBindingNotes);
+            printBackfillRecommendation(pushResult.recommendBackfill);
+            return;
+        }
+        const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((s) => s.trim()));
+        const corePath = findCorePath(rootDir);
+        const runtime = resolveCliRuntimeConfig({ rootDir });
+        const connection = requireProjectConnection(rootDir);
+        logMessage(`${pc.bold('Storystick')} — sync (generate + push)...`);
+        logMessage(pc.dim(`Root: ${rootDir}`));
+        if (options.verbose) {
+            logMessage(pc.dim(`Gateway: ${runtime.gatewayUrl}`));
+        }
+        const phased = await withSlowSpinner('Resolving stories…', SPINNER_DELAY_MS, async () => {
+            const prepared = await preparePipeline({
+                rootDir,
+                storyDirs,
+                corePath,
+            });
+            if (!prepared.success) {
+                return { kind: 'generate-failed', prepared };
+            }
+            const schema = serializeSchema(prepared.stories, prepared.diagnostics);
+            const gatewayUrl = runtime.gatewayUrl;
+            failureStep = 'plan';
+            changeSpinner('Planning schema changes…');
+            const token = await fetchSchemaPushToken(gatewayUrl, connection.apiKey, {
+                signal,
+            });
+            validateProjectTokenReadback(token, connection);
+            const body = schemaToPushBody(schema);
+            const plan = await fetchSchemaChangePlan(gatewayUrl, token, body, {
+                signal,
+            });
+            if (options.dryRun === true) {
+                return { kind: 'planned', prepared, schema, plan };
+            }
+            assertSchemaPlanAllowed(plan);
+            failureStep = 'generate';
+            changeSpinner('Staging generated types…');
+            const staged = await prepareGeneratedFiles(outputDirectory, prepared.generated);
+            const receipt = writePreparedSyncOperation({
+                rootDir,
+                outputDirectory,
+                schemaVersion: schema.version,
+                generationId: staged.generationId,
+                storyCount: prepared.stories.size,
+            });
+            failureStep = 'push';
+            changeSpinner('Pushing schemas…');
+            const pushResult = await pushSchema(gatewayUrl, token, body, schemaPlanFence(plan), { signal });
+            markSyncOperationPushed(receipt, pushResult);
+            failureStep = 'commit';
+            changeSpinner('Committing generated types…');
+            const committed = await commitPreparedGeneration(outputDirectory, staged.generationId);
+            clearSyncOperation(rootDir);
+            return {
+                kind: 'ok',
+                prepared,
+                schema,
+                plan,
+                committed,
+                pushResult,
+            };
+        });
+        const errors = phased.prepared.diagnostics.filter((d) => d.severity === 'error');
+        const warnings = phased.prepared.diagnostics.filter((d) => d.severity === 'warning');
+        const infos = phased.prepared.diagnostics.filter((d) => d.severity === 'info');
+        const renderable = isVerbose()
+            ? [...errors, ...warnings, ...infos]
+            : [...errors, ...warnings];
+        for (const d of renderable) {
+            logMessage(formatDiagnostic(d, rootDir));
+        }
+        if (phased.kind === 'generate-failed') {
+            // ADR-072 §D7: disambiguate which step in the sync pipeline failed.
+            if (getOutputMode() === 'json') {
+                exitJsonFailure({
+                    command: 'sync',
+                    err: new Error(`Sync failed at generate step: ${errors.length} error(s)`),
+                    diagnostics: phased.prepared.diagnostics.map(diagnosticToJson),
+                });
+            }
+            exitWithError(`Sync failed at generate step: ${pc.bold(String(errors.length))} error(s)`);
+        }
+        const { prepared, schema, plan } = phased;
+        if (phased.kind === 'planned') {
+            if (getOutputMode() === 'json') {
+                emitJsonResult({
+                    command: 'sync',
+                    ok: true,
+                    data: {
+                        status: 'planned',
+                        generate: { storyCount: prepared.stories.size },
+                        push: {
+                            version: schema.version,
+                            storyCount: schema.storyCount,
+                            plan,
+                        },
+                    },
+                    diagnostics: prepared.diagnostics.map(diagnosticToJson),
+                });
+                return;
+            }
+            renderSchemaPlan(plan);
+            logFinishedStep('Dry run complete; no generated artifacts or schema were published.');
+            return;
+        }
+        const { committed, pushResult } = phased;
+        if (getOutputMode() === 'json') {
+            emitJsonResult({
+                command: 'sync',
+                ok: true,
+                data: {
+                    generate: {
+                        storyCount: prepared.stories.size,
+                        generatedFiles: committed.files,
+                    },
+                    push: {
+                        status: pushResult.status,
+                        version: schema.version,
+                        storyCount: schema.storyCount,
+                        plan,
+                        newBindingNotes: pushResult.newBindingNotes,
+                        recommendBackfill: pushResult.recommendBackfill,
+                    },
+                },
+                diagnostics: prepared.diagnostics.map(diagnosticToJson),
+            });
+            return;
+        }
+        logFinishedStep(`Generated types for ${pc.bold(String(prepared.stories.size))} stories`);
+        for (const file of committed.files) {
+            logMessage(pc.dim(`  ${relative(rootDir, file)}`));
+        }
+        if (pushResult.status === 'unchanged') {
+            logMessage(pc.dim(`Schemas unchanged (${schema.version.slice(0, 8)})`));
+        }
+        else {
+            logFinishedStep(`Pushed ${pc.bold(String(schema.storyCount))} stories (${schema.version.slice(0, 8)})`);
+        }
+        renderNewBindingNotes(pushResult.newBindingNotes);
+        printBackfillRecommendation(pushResult.recommendBackfill);
+        if (warnings.length > 0) {
+            if (isVerbose()) {
+                for (const warning of warnings) {
+                    logWarning(formatDiagnostic(warning, rootDir));
+                }
+            }
+            else {
+                logWarning(`${warnings.length} warning(s) (use --verbose to see)`);
+            }
+        }
+    }
+    catch (err) {
+        const wrapped = err instanceof Error && !/^Sync failed at /.test(err.message)
+            ? rewrapStorystickError(`Sync failed at ${failureStep} step: ${err.message}`, err)
+            : err;
+        if (getOutputMode() === 'json') {
+            exitJsonFailure({ command: 'sync', err: wrapped });
+        }
+        exitWithError(wrapped);
+    }
+    finally {
+        dispose();
+    }
+});
+// ─────────────────────────────────────────────
+// Auth commands (device-auth — SPEC-1 Item #2)
+// ─────────────────────────────────────────────
+cli
+    .command('login', 'Log in to Storystick via your browser (device-auth flow)')
+    .option('--hub-url <url>', 'Hub base URL (defaults to https://storystick.app)')
+    .option('--gateway-url <url>', 'Credential issuer origin (HTTPS; HTTP loopback for local development)')
+    .example('  $ storystick login')
+    .action(async (options) => {
+    configureOutput({});
+    const { deviceAuthLogin, loadAuth } = await import('./auth-device.js');
+    // Default device name to the machine's hostname so the approval page
+    // reads "Authorize CLI on tanguy-mbp?" rather than an opaque id.
+    const { hostname } = await import('node:os');
+    const deviceName = hostname();
+    const abortController = new AbortController();
+    const onInt = () => abortController.abort();
+    process.on('SIGINT', onInt);
+    try {
+        await deviceAuthLogin({
+            hubUrl: options.hubUrl,
+            gatewayUrl: options.gatewayUrl,
+            deviceName,
+            signal: abortController.signal,
+            onPrompt: promptDeviceAuth,
+        });
+        const stored = loadAuth(resolveCliRuntimeConfig({ gatewayUrl: options.gatewayUrl }).gatewayUrl);
+        const who = stored?.email ?? 'your account';
+        // Lands ✔ in place of the "Waiting for authorization…" spinner
+        // frame — one active line per ADR-061 rule 1, no flicker.
+        succeedSpinner(`Logged in as ${pc.bold(who)}`);
+    }
+    catch (err) {
+        exitWithError(err, 'Login failed.');
+    }
+    finally {
+        process.off('SIGINT', onInt);
+    }
+});
+cli
+    .command('logout', 'Revoke the current Storystick CLI session and remove local auth')
+    .option('--local', 'Forget local auth without revoking the remote session')
+    .option('--gateway-url <url>', 'Issuer whose CLI session should be revoked')
+    .option('--root <dir>', 'Project directory for environment selection')
+    .example('  $ storystick logout')
+    .example('  $ storystick logout --local')
+    .action(async (options) => {
+    configureOutput({});
+    const { signal, dispose } = withInterrupt();
+    try {
+        const { logoutAuthSession } = await import('./auth-device.js');
+        const result = await logoutAuthSession({
+            signal,
+            localOnly: options.local === true,
+            gatewayUrl: options.gatewayUrl,
+            rootDir: options.root,
+        });
+        if (result === 'local-only') {
+            logFinishedStep('Local CLI session forgotten.');
+            logWarning('The remote session was not revoked.');
+            return;
+        }
+        if (result === 'revoked') {
+            logFinishedStep('Logged out and CLI session revoked.');
+        }
+        else {
+            logFinishedStep('No local CLI session found.');
+        }
+    }
+    catch (err) {
+        exitWithError(err, 'The local session was kept so revocation can be retried.');
+    }
+    finally {
+        dispose();
+    }
+});
+cli
+    .command('whoami', 'Show the currently logged-in user')
+    .option('--gateway-url <url>', 'Issuer whose CLI session should be inspected')
+    .option('--root <dir>', 'Project directory for environment selection')
+    .option('--json', 'Emit JSON to stdout')
+    .example('  $ storystick whoami')
+    .example('  $ storystick whoami --json')
+    .action(async (options) => {
+    configureOutput({
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+    const { whoami } = await import('./auth-device.js');
+    const info = await whoami({ gatewayUrl: options.gatewayUrl, rootDir: options.root });
+    if (getOutputMode() === 'json') {
+        // ADR-072 §D15: { userId, email } | null on success.
+        emitJsonResult({
+            command: 'whoami',
+            ok: true,
+            data: info ? { userId: info.userId, email: info.email } : null,
+        });
+        return;
+    }
+    if (info) {
+        const who = info.email ?? info.userId;
+        logMessage(`Logged in as ${pc.bold(who)}`);
+    }
+    else {
+        logMessage(`Not logged in. Run ${pc.bold('storystick login')} to authenticate.`);
+    }
+});
+// ─────────────────────────────────────────────
+// Init command (SPEC-1 Item #1 — create / --link <shortId> / interactive)
+// ─────────────────────────────────────────────
+cli
+    .command('init [project-name]', 'Create a new Storystick project or link an existing one')
+    .option('--link <shortId>', 'Link to an existing project instead of creating a new one')
+    .option('--team <teamShortId>', 'Create the project in this Team (required for multiple Teams outside a TTY)')
+    .option('--json', 'Emit a JSON envelope on stdout; never prompt')
+    .option('--starter <name>', 'Starter ID from the configured Storystick catalog')
+    .option('--into <dir>', 'Create or scaffold into this directory')
+    .option('--origin <origin>', 'Allowed HTTP(S) application origin')
+    .option('--locale <tag>', 'Primary BCP 47 site locale')
+    .option('--site-url <origin>', 'Production origin for canonical URLs')
+    .option('--force', 'Overwrite known Storystick files in an existing Next app')
+    .example('  $ storystick init my-blog              # create new project')
+    .option('--new-team <name>', 'Create a new team for this project')
+    .example('  $ storystick init my-blog --team a3k9m2x7')
+    .example('  $ storystick init my-blog --team a3k9m2x7 --locale en --json')
+    .example('  $ storystick init --link a3k9m2x7      # link existing project by shortId')
+    .example('  $ storystick init my-blog --into . --origin http://localhost:4000')
+    .example('  $ storystick init                      # interactive: new or link')
+    .example('  $ storystick init my-blog --starter minimal-next --locale en')
+    .action(async (projectName, options) => {
+    const { runInit } = await import('./init.js');
+    await runInit(projectName, {
+        link: options.link,
+        starter: options.starter,
+        into: options.into,
+        origin: options.origin,
+        locale: options.locale,
+        siteUrl: options.siteUrl,
+        force: options.force,
+        team: options.team,
+        newTeam: options.newTeam,
+        json: options.json,
+    });
+});
+// ─────────────────────────────────────────────
+// User-scoped parity commands (SPEC-1 Item #4)
+// ─────────────────────────────────────────────
+cli
+    .command('list', 'List all projects you belong to')
+    .alias('ls')
+    .option('--json', 'Emit JSON to stdout')
+    .option('--all', 'Include archived projects')
+    .example('  $ storystick list')
+    .example('  $ storystick ls --all')
+    .example('  $ storystick list --json')
+    .action(async (options) => {
+    const { runList } = await import('./commands/list.js');
+    await runList({ json: options.json === true, all: options.all === true });
+});
+cli
+    .command('info [shortId]', 'Show details for the active project, or for the given shortId')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--json', 'Emit JSON to stdout')
+    .example('  $ storystick info                     # active project (from .env.local)')
+    .example('  $ storystick info a3k9m2x7            # specific project by shortId')
+    .example('  $ storystick info --json')
+    .action(async (shortId, options) => {
+    const { runInfo } = await import('./commands/info.js');
+    await runInfo(shortId, {
+        root: options.root,
+        json: options.json === true,
+    });
+});
+cli
+    .command('connect <shortId>', 'Provision and atomically write a complete project connection')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--origin <url>', 'Explicit HTTP(S) origin to append')
+    .option('--dry-run', 'Show the redacted connection plan without mutating')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .example('  $ storystick connect a3k9m2x7')
+    .example('  $ storystick connect a3k9m2x7 --root apps/web')
+    .example('  $ storystick connect a3k9m2x7 --origin https://app.example.com')
+    .example('  $ storystick connect a3k9m2x7 --dry-run')
+    .action(async (shortId, options) => {
+    const { runConnect } = await import('./commands/connect.js');
+    await runConnect(shortId, {
+        root: options.root,
+        origin: options.origin,
+        dryRun: options.dryRun === true,
+        json: options.json === true,
+    });
+});
+cli
+    .command('archive <shortId>', 'Soft-delete a project (recoverable for 30 days)')
+    .option('--yes', 'Skip the confirmation prompt (required when non-interactive or --json)')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .example('  $ storystick archive a3k9m2x7')
+    .example('  $ storystick archive a3k9m2x7 --yes      # CI / non-TTY')
+    .action(async (shortId, options) => {
+    const { runArchive } = await import('./commands/archive.js');
+    await runArchive(shortId, {
+        json: options.json === true,
+        yes: options.yes === true,
+    });
+});
+// ─────────────────────────────────────────────
+// Content import and schema migrations
+// ─────────────────────────────────────────────
+cli
+    .command('content <action> [target]', 'Plan, apply, resume and verify a content import')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--project <shortId>', 'Target Storystick project')
+    .option('--dry-run', 'Prepare a server plan without creating or editing content')
+    .option('--apply', 'Apply the previously reviewed plan')
+    .option('--plan <digest>', 'Exact server plan digest')
+    .option('--resume <runId>', 'Resume an existing import run')
+    .option('--new-run', 'Prepare a fresh plan after cancellation or a conflict')
+    .option('--renew <uploadSessionId>', 'Explicitly renew an expired or failed asset upload')
+    .option('--json', 'Emit JSON to stdout')
+    .action(async (action, target, options) => {
+    const { runContent } = await import('./commands/content.js');
+    // cac/mri coerces numeric-looking options before its type transforms.
+    // Native string parsing preserves leading zeroes and long digest values.
+    const names = ['root', 'project', 'plan', 'resume', 'renew'];
+    const raw = parseArgs({ options: Object.fromEntries(names.map(name => [name, { type: 'string' }])), strict: false, allowPositionals: true }).values;
+    await runContent(action, target, { ...options, ...Object.fromEntries(names.filter(name => typeof raw[name] === 'string').map(name => [name, raw[name]])) });
+});
+cli
+    .command('migrate <action> [...identifiers]', 'Analyze, prepare, activate, and inspect a schema migration')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--stories <dirs>', 'Directories to scan (comma-separated)')
+    .option('--recipe <id>', 'Native recipe id', {
+    default: 'text-to-single-line-richtext',
+})
+    .option('--migration <file>', 'Client-owned migration module for controlled external execution')
+    .option('--bindings <paths>', 'Comma-separated schema field definition paths', {
+    default: 'stories.page.fields.title',
+})
+    .option('--cursor <cursor>', 'Read cursor returned by the server')
+    .option('--limit <count>', 'Issues per page', { default: 50 })
+    .option('--preparation <id>', 'Exact preparation id')
+    .option('--phase <phase>', 'prepared or serving')
+    .option('--level <level>', 'manual-attestation or adapter-readback', {
+    default: 'manual-attestation',
+})
+    .option('--artifact <id>', 'Artifact identity')
+    .option('--digest <digest>', 'Artifact digest')
+    .option('--schema-version <version>', 'Target schema version')
+    .option('--generation <id>', 'Target generation id')
+    .option('--surfaces <list>', 'Comma-separated controlled surfaces')
+    .option('--references <list>', 'Comma-separated proof references')
+    .option('--request-id <id>', 'Retry-safe idempotency key')
+    .option('--run <id>', 'Select an existing run when recent-run discovery is ambiguous')
+    .option('--app-url <url>', 'Candidate application origin for build identity readback')
+    .option('--serving-url <url>', 'Public application origin to prove after promotion')
+    .option('--preview-proof <reference>', 'Reference to a manually checked B Preview')
+    .option('--yes', 'Confirm authority transfer without an interactive prompt')
+    .option('--verbose', 'Show additional diagnostics')
+    .option('--quiet', 'Suppress success and warning output')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .example('  $ storystick migrate analyze --bindings stories.page.fields.title')
+    .example('  $ storystick migrate prepare <runId> <analysisId>')
+    .example('  $ storystick migrate status [runId]')
+    .example('  $ storystick migrate pair-build <runId> --phase prepared --app-url <url>')
+    .action(async (action, identifiers, options) => {
+    configureOutput({
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+    const args = Array.isArray(identifiers) ? identifiers : [];
+    const failUsage = (message) => {
+        const error = new Error(message);
+        if (getOutputMode() === 'json') {
+            exitJsonFailure({ command: `migrate ${action}`, err: error });
+        }
+        return exitWithError(error);
+    };
+    const expectArguments = (names, optional = false) => {
+        const minimum = optional ? 0 : names.length;
+        if (args.length < minimum || args.length > names.length) {
+            const rendered = names
+                .map((name) => (optional ? `[${name}]` : `<${name}>`))
+                .join(' ');
+            failUsage(`Usage: storystick migrate ${action}${rendered ? ` ${rendered}` : ''}`);
+        }
+        return args;
+    };
+    const common = {
+        root: options.root,
+        requestId: options.requestId,
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    };
+    const migrations = await import('./commands/migrate.js');
+    if (action === 'preview') {
+        const [modulePath] = expectArguments(['module'], true);
+        if (modulePath && options.migration)
+            failUsage('Use either a positional module or --migration, not both.');
+        const rootDir = resolve(options.root);
+        try {
+            const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((entry) => entry.trim()));
+            const resolved = await runResolve({ rootDir, storyDirs, corePath: findCorePath(rootDir) });
+            if (!resolved.success)
+                throw new Error('Target schema resolution failed; no migration run was created.');
+            const targetSchema = serializeSchema(resolved.stories, resolved.diagnostics);
+            const migration = modulePath ?? options.migration;
+            const artifact = migration ? await buildExternalMigrationArtifact(rootDir, migration) : undefined;
+            const recipe = artifact ? undefined : {
+                id: options.recipe,
+                version: 1,
+                bindings: String(options.bindings).split(',').map((schemaPath) => ({ schemaPath: schemaPath.trim() }))
+                    .filter((binding) => binding.schemaPath.length > 0),
+            };
+            await migrations.runMigratePreview(targetSchema, { artifact, recipe, runId: options.run }, { ...common, root: rootDir });
+        }
+        catch (error) {
+            if (getOutputMode() === 'json')
+                exitJsonFailure({ command: 'migrate preview', err: error });
+            exitWithError(error);
+        }
+        return;
+    }
+    if (action === 'build') {
+        expectArguments([]);
+        if (!options.migration) {
+            failUsage('Usage: storystick migrate build --migration <file>');
+        }
+        await migrations.runMigrateBuild(options.migration, {
+            ...common,
+            root: resolve(options.root),
+        });
+        return;
+    }
+    if (action === 'analyze') {
+        expectArguments([]);
+        const rootDir = resolve(options.root);
+        try {
+            const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((entry) => entry.trim()));
+            const resolved = await runResolve({
+                rootDir,
+                storyDirs,
+                corePath: findCorePath(rootDir),
+            });
+            if (!resolved.success) {
+                throw new Error('Target schema resolution failed; no migration run was created.');
+            }
+            const targetSchema = serializeSchema(resolved.stories, resolved.diagnostics);
+            if (options.migration) {
+                const artifact = await buildExternalMigrationArtifact(rootDir, options.migration);
+                await migrations.runMigrateAnalyzeExternal(targetSchema, artifact, {
+                    ...common,
+                    root: rootDir,
+                });
+            }
+            else {
+                const recipe = {
+                    id: options.recipe,
+                    version: 1,
+                    bindings: String(options.bindings)
+                        .split(',')
+                        .map((schemaPath) => ({ schemaPath: schemaPath.trim() }))
+                        .filter((binding) => binding.schemaPath.length > 0),
+                };
+                await migrations.runMigrateAnalyze(targetSchema, recipe, { ...common, root: rootDir });
+            }
+        }
+        catch (error) {
+            if (getOutputMode() === 'json') {
+                exitJsonFailure({ command: 'migrate analyze', err: error });
+            }
+            exitWithError(error);
+        }
+        return;
+    }
+    if (action === 'prepare') {
+        const [runId, analysisId] = expectArguments(['runId', 'analysisId']);
+        const artifact = options.migration
+            ? await buildExternalMigrationArtifact(resolve(options.root), options.migration)
+            : undefined;
+        await migrations.runMigratePrepare(runId, analysisId, {
+            ...common,
+            ...(artifact ? { artifact } : {}),
+        });
+        return;
+    }
+    if (action === 'status') {
+        const [runId] = expectArguments(['runId'], true);
+        await migrations.runMigrateStatus(runId, common);
+        return;
+    }
+    if (action === 'issues') {
+        const [runId, analysisId] = expectArguments(['runId', 'analysisId']);
+        await migrations.runMigrateIssues(runId, analysisId, {
+            ...common,
+            cursor: options.cursor,
+            limit: Number(options.limit),
+        });
+        return;
+    }
+    if (action === 'resume' || action === 'abort') {
+        const [runId] = expectArguments(['runId']);
+        await migrations.runMigrateRunCommand(action, runId, common);
+        return;
+    }
+    if (action === 'pair-build') {
+        const [runId] = expectArguments(['runId']);
+        if (options.phase !== 'prepared' && options.phase !== 'serving') {
+            failUsage('Pass --phase prepared or --phase serving.');
+        }
+        const appUrl = options.phase === 'serving'
+            ? options.servingUrl ?? options.appUrl : options.appUrl;
+        if (!appUrl)
+            failUsage('Pass --app-url <url> (or --serving-url for serving).');
+        const rootDir = resolve(options.root);
+        try {
+            const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((entry) => entry.trim()));
+            const resolved = await runResolve({ rootDir, storyDirs,
+                corePath: findCorePath(rootDir) });
+            if (!resolved.success)
+                throw new Error('Application schema resolution failed; no build was paired.');
+            await migrations.runMigratePairBuild(runId, serializeSchema(resolved.stories, resolved.diagnostics), { phase: options.phase, appUrl, previewProof: options.previewProof,
+                requestId: options.requestId }, { ...common, root: rootDir });
+        }
+        catch (error) {
+            if (getOutputMode() === 'json')
+                exitJsonFailure({ command: 'migrate pair-build', err: error });
+            exitWithError(error);
+        }
+        return;
+    }
+    if (action === 'attest') {
+        const [runId] = expectArguments(['runId']);
+        const required = [
+            'preparation',
+            'phase',
+            'artifact',
+            'digest',
+            'schemaVersion',
+            'generation',
+            'surfaces',
+            'references',
+        ];
+        const missing = required.filter((name) => !options[name]);
+        if (missing.length > 0) {
+            failUsage(`Missing required option(s): ${missing.join(', ')}`);
+        }
+        await migrations.runMigrateAttest({
+            runId,
+            preparationId: options.preparation,
+            phase: options.phase,
+            level: options.level,
+            artifactId: options.artifact,
+            artifactDigest: options.digest,
+            schemaVersion: options.schemaVersion,
+            generationId: options.generation,
+            surfaces: String(options.surfaces)
+                .split(',')
+                .map((value) => value.trim()),
+            references: String(options.references)
+                .split(',')
+                .map((value) => value.trim()),
+        }, common);
+        return;
+    }
+    if (action === 'activate') {
+        if (args.length <= 1 && (args[0] || options.migration || options.run)) {
+            const [modulePath] = expectArguments(['module'], true);
+            if (modulePath && options.migration)
+                failUsage('Use either a positional module or --migration, not both.');
+            const rootDir = resolve(options.root);
+            try {
+                const storyDirs = findStoryDirs(rootDir, options.stories?.split(',').map((entry) => entry.trim()));
+                const resolved = await runResolve({ rootDir, storyDirs, corePath: findCorePath(rootDir) });
+                if (!resolved.success)
+                    throw new Error('Target schema resolution failed; activation was not attempted.');
+                const targetSchema = serializeSchema(resolved.stories, resolved.diagnostics);
+                const migration = modulePath ?? options.migration;
+                const artifact = migration ? await buildExternalMigrationArtifact(rootDir, migration) : undefined;
+                const recipe = artifact ? undefined : {
+                    id: options.recipe,
+                    version: 1,
+                    bindings: String(options.bindings).split(',').map((schemaPath) => ({ schemaPath: schemaPath.trim() }))
+                        .filter((binding) => binding.schemaPath.length > 0),
+                };
+                await migrations.runMigrateGuidedActivate(targetSchema, {
+                    artifact, recipe, runId: options.run,
+                    appUrl: options.appUrl, servingUrl: options.servingUrl,
+                    previewProof: options.previewProof,
+                    yes: options.yes === true,
+                }, { ...common, root: rootDir });
+            }
+            catch (error) {
+                if (getOutputMode() === 'json')
+                    exitJsonFailure({ command: 'migrate activate', err: error });
+                exitWithError(error);
+            }
+            return;
+        }
+        const [runId, preparationId, evidenceId] = expectArguments([
+            'runId',
+            'preparationId',
+            'evidenceId',
+        ]);
+        await migrations.runMigrateActivate(runId, preparationId, evidenceId, common);
+        return;
+    }
+    if (action === 'receipt') {
+        const [runId] = expectArguments(['runId']);
+        await migrations.runMigrateReceipt(runId, common);
+        return;
+    }
+    failUsage(`Unknown migration action "${action}". Expected preview, analyze, prepare, status, issues, resume, abort, attest, activate, or receipt.`);
+});
+cli
+    .command('backfill-refs', 'Re-extract live references for the active project')
+    .option('--storyType <name>', 'Limit to one story type')
+    .option('--document <shortId>', 'Limit to one document')
+    .option('--dry-run', 'Count what would change without writing')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--verbose', 'Render info-level diagnostics')
+    .option('--quiet', 'Suppress success and warning output (failures still emit)')
+    .option('--json', 'Emit JSONL events on stdout (one per chunk + a final event)')
+    .example('  $ storystick backfill-refs                # whole project')
+    .example('  $ storystick backfill-refs --storyType blogPost')
+    .example('  $ storystick backfill-refs --document a3k9m2x7')
+    .example('  $ storystick backfill-refs --dry-run')
+    .action(async (options) => {
+    const { runBackfillRefs } = await import('./commands/backfill-refs.js');
+    await runBackfillRefs({
+        storyType: options.storyType,
+        documentId: options.document,
+        dryRun: options.dryRun === true,
+        root: options.root,
+        json: options.json === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+    });
+});
+cli
+    .command('source <operation> [workspaceId]', 'Source: configure, prepare, release, status, stop, recover, export, apply, import, github-status, github-inspect, github-prepare, github-import, propose')
+    .option('--root <dir>', 'Local repository or application directory', { default: '.' })
+    .option('--project <shortId>', 'Connected Storystick project')
+    .option('--config <file>', 'Preparation scope and recipe (default .storystick/source.json)')
+    .option('--schema <file>', 'Compiled schema for the single-app Next.js source preset')
+    .option('--ref <commit>', 'Committed local ref (default HEAD), or immutable GitHub commit for github-*')
+    .option('--app-root <path>', 'Repository-relative application folder for github-inspect')
+    .option('--connection-revision <revision>', 'GitHub connection revision returned by github-inspect')
+    .option('--repair-command <command>', 'For recover only: repair unsaved source in the retained sandbox before checkpointing (uses workspace budget)')
+    .option('--repair-cwd <path>', 'Repository-relative directory for the recovery command')
+    .option('--out <directory>', 'New export directory or independent integration checkout')
+    .option('--change <directory>', 'Verified source export to apply locally or propose on GitHub')
+    .option('--expected-revision <revision>', 'Workspace revision observed before export or import')
+    .option('--request-id <id>', 'Stable operation identity for retries')
+    .option('--dry-run', 'Validate and inspect a source preparation locally without uploading')
+    .option('--json', 'Emit a JSON envelope')
+    .action(async (operation, workspaceId, options) => {
+    const { runSource } = await import('./commands/source.js');
+    await runSource(operation, workspaceId, options);
+});
+cli
+    .command('slice-previews sync', 'Sync Slice Library captures declared in a repository manifest')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--manifest <file>', 'Manifest path relative to root', {
+    default: 'slice-previews.json',
+})
+    .option('--project <shortId>', 'Project shortId (defaults to ProjectConnection)')
+    .option('--dry-run', 'Validate and list captures without uploading')
+    .option('--verbose', 'Show manifest details')
+    .option('--quiet', 'Suppress success and warning output')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .example('  $ storystick slice-previews sync')
+    .example('  $ storystick slice-previews sync --dry-run --json')
+    .action(async (options) => {
+    const { runSlicePreviewsSync } = await import('./commands/slice-previews.js');
+    await runSlicePreviewsSync({
+        root: options.root,
+        manifest: options.manifest,
+        projectShortId: options.project,
+        dryRun: options.dryRun === true,
+        verbose: options.verbose === true,
+        quiet: options.quiet === true,
+        json: options.json === true,
+    });
+});
+cli
+    .command('mcp', 'Serve project capabilities over MCP stdio')
+    .option('--project <shortId>', 'Project this server may access (required)')
+    .option('--write', 'Enable verified draft writes and Undo with your editor role')
+    .option('--root <dir>', 'Directory for gateway configuration', { default: '.' })
+    .action(async (options) => {
+    configureOutput({ json: false });
+    const { signal, dispose } = withInterrupt();
+    try {
+        const { runProjectMcp } = await import('./mcp.js');
+        await runProjectMcp({ project: options.project, root: options.root, write: options.write === true, signal });
+    }
+    catch (err) {
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+});
+cli.help((sections) => {
+    // cac runs this single global callback for every `outputHelp` —
+    // top-level AND per-command. We detect which by examining the Usage
+    // section's body (set at runtime to `$ <cli> <usageText|rawName>`).
+    const commandsIdx = sections.findIndex((s) => s.title === 'Commands');
+    if (commandsIdx >= 0) {
+        // Top-level `--help`. After the Commands list, splice in a short
+        // categorization so first-time users see the shape of the CLI at a
+        // glance instead of a flat list.
+        sections.splice(commandsIdx + 1, 0, {
+            title: 'Command groups',
+            body: [
+                pc.bold('  Schema') + '       generate, push, sync',
+                pc.bold('  Migrations') +
+                    '   migrate analyze, prepare, status, issues, resume, abort, attest, pair-build, activate, receipt',
+                pc.bold('  Auth') + '         login, logout, whoami',
+                pc.bold('  Projects') + '     init, list, info, connect, archive',
+                pc.bold('  Refs') + '         backfill-refs',
+                pc.bold('  Slice library') + ' slice-previews sync',
+                pc.bold('  Assistants') + '   mcp',
+            ].join('\n'),
+        });
+        return;
+    }
+    // ADR-072 §F1: append an Environment: section for the schema/refs
+    // commands so AI agents and CI scripts see the env-var contract on
+    // `<cmd> --help` without having to read the source. cac doesn't
+    // surface the matched command to its global helpCallback, so we sniff
+    // it off the Usage line ("$ storystick <name> ...").
+    const usage = sections.find((s) => s.title === 'Usage');
+    if (!usage)
+        return;
+    const body = usage.body;
+    if (body.includes(' init')) {
+        sections.push(envSection(ENV_INIT));
+    }
+    else if (body.includes(' push') || body.includes(' sync')) {
+        sections.push(envSection(ENV_SCHEMA_PUSH));
+    }
+    else if (body.includes(' backfill-refs')) {
+        sections.push(envSection(ENV_BACKFILL));
+    }
+    else if (body.includes(' slice-previews sync')) {
+        sections.push(envSection(ENV_SLICE_PREVIEWS));
+    }
+    else if (body.includes(' mcp')) {
+        sections.push(envSection([
+            ['STORYSTICK_GATEWAY_URL', 'optional', 'Project gateway override; also read from --root/.env.local'],
+            ['XDG_CONFIG_HOME', 'optional', 'Operator session directory; sign in with storystick login first'],
+        ]));
+    }
+});
+const cliPackage = createRequire(import.meta.url)('../package.json');
+cli.version(cliPackage.version);
+cli.command('release <operation> [value]', 'Manage releases and prepare, review or publish a coordinated release')
+    .option('--approval <digest>', 'Confirm the exact reviewed publication')
+    .option('--request-id <id>', 'Stable request identity for publication preparation')
+    .option('--root <dir>', 'Project root directory', { default: '.' })
+    .option('--project <id>', 'Project short ID')
+    .option('--json', 'Emit a JSON envelope on stdout')
+    .action(async (operation, value, options) => {
+    const { runRelease } = await import('./commands/release.js');
+    await runRelease(operation, value, options);
+});
+cli.command('connection <operation>', 'Connect a project to GitHub or Vercel without deploying')
+    .option('--root <dir>', 'Website folder')
+    .option('--project <shortId>', 'Storystick project')
+    .option('--provider <provider>', 'github or vercel')
+    .option('--attempt <id>', 'Authorization attempt returned by begin or status')
+    .option('--cursor <cursor>', 'Next resource page')
+    .option('--installation <id>', 'GitHub installation')
+    .option('--repository <id>', 'GitHub repository numeric ID')
+    .option('--full-name <name>', 'GitHub owner/repository')
+    .option('--branch <branch>', 'GitHub source branch')
+    .option('--destination <id>', 'Vercel project ID')
+    .option('--json', 'Machine-readable output; never opens a browser')
+    .action(async (operation, options) => {
+    const { runConnection } = await import('./commands/connection.js');
+    await runConnection(operation, options);
+});
+cli.command('delivery <operation>', 'Configure or inspect release hosting; never deploys or publishes')
+    .option('--root <dir>', 'Local application directory', { default: '.' })
+    .option('--project <id>', 'Storystick project short ID')
+    .option('--from-vercel', 'Read team/project IDs from .vercel/project.json (not credentials)')
+    .option('--team <id>', 'Vercel team ID')
+    .option('--destination <id>', 'Vercel project ID')
+    .option('--site-url <origin>', 'Existing HTTPS production origin')
+    .option('--root-directory <path>', 'Deployment root within the source scope')
+    .option('--build-command <command>', 'Deployment build override')
+    .option('--dry-run', 'Inspect the configuration without saving it')
+    .option('--json', 'Emit structured results')
+    .action(async (operation, options) => {
+    const { runDelivery } = await import('./commands/delivery.js');
+    await runDelivery(operation, options);
+});
+cli.command('guide', 'Print the Storystick development skill')
+    .option('--reference <name>', 'Read a focused reference: setup or story-and-next')
+    .action(async (options) => {
+    // Readers such as head may close the pipe before the guide finishes.
+    process.stdout.on('error', (error) => {
+        if (error.code !== 'EPIPE')
+            throw error;
+    });
+    configureOutput({});
+    const { dispose } = withInterrupt();
+    try {
+        if (options.reference && !['setup', 'story-and-next'].includes(options.reference))
+            throw new Error('Unknown reference. Choose setup or story-and-next.');
+        const { readFile } = await import('node:fs/promises');
+        const { fileURLToPath } = await import('node:url');
+        const path = options.reference ? `references/${options.reference}.md` : 'SKILL.md';
+        const guide = new URL(`../assets/skills/storystick-development/${path}`, import.meta.url);
+        logOutput(`# Guide source: ${fileURLToPath(guide)}\n${await readFile(guide, 'utf8')}`);
+    }
+    catch (err) {
+        exitWithError(err);
+    }
+    finally {
+        dispose();
+    }
+});
+cli.parse();