@contentful/experience-design-system-cli 2.12.0 → 2.12.1-dev-build-589b615.0

package/dist/src/import/tui/wizard-save-flow.d.ts

@@ -0,0 +1,37 @@
+import { type RunRecord } from '../../runs/store.js';
+import { type OnConflictMode } from '../../runs/save-path-resolver.js';
+/**
+ * Wizard save-flow orchestration helpers (Task 4 / spec part 1+2).
+ *
+ * Kept as a separate module so the logic is testable without rendering the
+ * full Ink WizardApp.
+ */
+export type PlanSaveFlowInput = {
+    /** Resolved default save path (e.g. `${project}/.contentful`). */
+    defaultPath: string;
+    /** When set, bypass the inline prompt entirely (`--out-dir` flag). */
+    outDirOverride?: string | undefined;
+    /**
+     * Headless conflict-resolution mode (`--on-conflict`). Only meaningful when
+     * `outDirOverride` is also set — otherwise we still need to prompt for the
+     * path interactively. When provided alongside an override, the conflict
+     * gate is bypassed and the mode is applied via `resolveSavePath`.
+     */
+    onConflict?: OnConflictMode | undefined;
+};
+export type PlanSaveFlowOutput = {
+    kind: 'write';
+    path: string;
+} | {
+    kind: 'prompt';
+    defaultPath: string;
+} | {
+    kind: 'fail';
+    conflict: {
+        path: string;
+        files: string[];
+    };
+};
+export declare function planSaveFlow(input: PlanSaveFlowInput): Promise<PlanSaveFlowOutput>;
+export type RecordRunAfterSaveInput = Omit<RunRecord, 'id' | 'createdAt'>;
+export declare function recordRunAfterSave(input: RecordRunAfterSaveInput): Promise<RunRecord>;

package/dist/src/import/tui/wizard-save-flow.js

@@ -0,0 +1,20 @@
+import { appendRun } from '../../runs/store.js';
+import { resolveSavePath } from '../../runs/save-path-resolver.js';
+export async function planSaveFlow(input) {
+    if (input.outDirOverride) {
+        if (input.onConflict) {
+            const resolved = await resolveSavePath(input.outDirOverride, { onConflict: input.onConflict });
+            if (resolved.kind === 'write')
+                return { kind: 'write', path: resolved.path };
+            if (resolved.kind === 'fail')
+                return { kind: 'fail', conflict: resolved.conflict };
+            // `no-conflict` / `conflict` never come back when onConflict is set.
+            return { kind: 'write', path: input.outDirOverride };
+        }
+        return { kind: 'write', path: input.outDirOverride };
+    }
+    return { kind: 'prompt', defaultPath: input.defaultPath };
+}
+export async function recordRunAfterSave(input) {
+    return appendRun(input);
+}

package/dist/src/import/tui/wizard-state-transitions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure state-machine helpers for the wizard. Extracted from WizardApp.tsx so the
+ * transitions can be unit-tested without rendering ink.
+ *
+ * Bug fix (2026-06): credentials moved BEFORE generate so:
+ *   1. Bad creds (401/403) are caught upfront — before the operator pays the cost
+ *      of extract + LLM classification (potentially many minutes).
+ *   2. Live preview in final-review actually fires, because the validated creds
+ *      are present in WizardApp state when GenerateReviewStep mounts.
+ *
+ * New order:
+ *   welcome → token-input → path-validation → extracting → scope-gate
+ *          → credentials (validates inline) → generating
+ *          → generating → final-review → push-decision-gate → previewing
+ *          → preview-gate → pushing → done
+ *
+ * `--no-push` short-circuits the credentials/preview/push branch — the operator
+ * just wants extract + classify + final-review without ever touching Contentful.
+ */
+export type WizardStepAfterScope = 'credentials' | 'generating' | 'push-decision-gate' | 'print-gate';
+export type WizardStepAfterCredentials = 'generating' | 'push-decision-gate';
+/**
+ * Transition target after the scope-gate confirms.
+ *
+ * - acceptedCount > 0:
+ *   - !noPush → `credentials` (gather + validate creds upfront, before LLM cost)
+ *   - noPush  → `generating` (skip creds entirely; live preview no-ops gracefully)
+ * - acceptedCount === 0 (everything rejected):
+ *   - !noPush → `credentials` (still need creds to push tokens / removals)
+ *   - noPush  → `print-gate` (nothing to do; let the operator save files and exit)
+ */
+export declare function nextStepAfterScopeGate(opts: {
+    acceptedCount: number;
+    noPush: boolean;
+}): WizardStepAfterScope;
+/**
+ * Transition target after credentials are validated (or skipped via the
+ * inline validation pings the API). Drives the post-credentials branch:
+ *   - acceptedCount > 0 → `generating` (run the generator now that creds are good)
+ *   - acceptedCount === 0 → `push-decision-gate` (no components to generate;
+ *     skip straight to push-decision and preview)
+ */
+export declare function nextStepAfterCredentialsValidated(opts: {
+    acceptedCount: number;
+}): WizardStepAfterCredentials;
+/**
+ * Skip-credentials spec — Task 2. When the operator pressed `s` on the
+ * credentials screen, the wizard advanced without validating creds. That
+ * makes `previewImport` impossible (no working token) and undesirable (the
+ * whole point is to inspect locally without touching the server). Callers
+ * check this before issuing the API call and route to
+ * `buildSkippedPreviewTransition()` instead.
+ */
+export declare function shouldBypassPreview(state: {
+    credentialsSkipped: boolean;
+}): boolean;
+/**
+ * State patch applied when `shouldBypassPreview` is true: skip the preview
+ * step entirely, surface no server preview to downstream consumers, and
+ * hand control to the push-decision-gate (which will render with push
+ * disabled — see Task 3).
+ */
+export declare function buildSkippedPreviewTransition(): {
+    step: 'push-decision-gate';
+    serverPreview: null;
+};
+/**
+ * Skip-credentials spec — Task 4 (defensive guard). The push-decision-gate
+ * disables "Save AND push" and "Push only" when credentialsSkipped is true,
+ * so `runPush` should never be reached. If a state-machine regression ever
+ * routed an operator past that guard, `runPush` checks this helper and
+ * refuses to issue the API call — instead it routes back to the print-files
+ * local-save path via `buildSkippedPushTransition`.
+ */
+export declare function shouldRefusePush(state: {
+    credentialsSkipped: boolean;
+}): boolean;
+export declare function buildSkippedPushTransition(): {
+    step: 'print-gate';
+};

package/dist/src/import/tui/wizard-state-transitions.js

@@ -0,0 +1,79 @@
+/**
+ * Pure state-machine helpers for the wizard. Extracted from WizardApp.tsx so the
+ * transitions can be unit-tested without rendering ink.
+ *
+ * Bug fix (2026-06): credentials moved BEFORE generate so:
+ *   1. Bad creds (401/403) are caught upfront — before the operator pays the cost
+ *      of extract + LLM classification (potentially many minutes).
+ *   2. Live preview in final-review actually fires, because the validated creds
+ *      are present in WizardApp state when GenerateReviewStep mounts.
+ *
+ * New order:
+ *   welcome → token-input → path-validation → extracting → scope-gate
+ *          → credentials (validates inline) → generating
+ *          → generating → final-review → push-decision-gate → previewing
+ *          → preview-gate → pushing → done
+ *
+ * `--no-push` short-circuits the credentials/preview/push branch — the operator
+ * just wants extract + classify + final-review without ever touching Contentful.
+ */
+/**
+ * Transition target after the scope-gate confirms.
+ *
+ * - acceptedCount > 0:
+ *   - !noPush → `credentials` (gather + validate creds upfront, before LLM cost)
+ *   - noPush  → `generating` (skip creds entirely; live preview no-ops gracefully)
+ * - acceptedCount === 0 (everything rejected):
+ *   - !noPush → `credentials` (still need creds to push tokens / removals)
+ *   - noPush  → `print-gate` (nothing to do; let the operator save files and exit)
+ */
+export function nextStepAfterScopeGate(opts) {
+    if (opts.acceptedCount > 0) {
+        return opts.noPush ? 'generating' : 'credentials';
+    }
+    return opts.noPush ? 'print-gate' : 'credentials';
+}
+/**
+ * Transition target after credentials are validated (or skipped via the
+ * inline validation pings the API). Drives the post-credentials branch:
+ *   - acceptedCount > 0 → `generating` (run the generator now that creds are good)
+ *   - acceptedCount === 0 → `push-decision-gate` (no components to generate;
+ *     skip straight to push-decision and preview)
+ */
+export function nextStepAfterCredentialsValidated(opts) {
+    return opts.acceptedCount > 0 ? 'generating' : 'push-decision-gate';
+}
+/**
+ * Skip-credentials spec — Task 2. When the operator pressed `s` on the
+ * credentials screen, the wizard advanced without validating creds. That
+ * makes `previewImport` impossible (no working token) and undesirable (the
+ * whole point is to inspect locally without touching the server). Callers
+ * check this before issuing the API call and route to
+ * `buildSkippedPreviewTransition()` instead.
+ */
+export function shouldBypassPreview(state) {
+    return state.credentialsSkipped === true;
+}
+/**
+ * State patch applied when `shouldBypassPreview` is true: skip the preview
+ * step entirely, surface no server preview to downstream consumers, and
+ * hand control to the push-decision-gate (which will render with push
+ * disabled — see Task 3).
+ */
+export function buildSkippedPreviewTransition() {
+    return { step: 'push-decision-gate', serverPreview: null };
+}
+/**
+ * Skip-credentials spec — Task 4 (defensive guard). The push-decision-gate
+ * disables "Save AND push" and "Push only" when credentialsSkipped is true,
+ * so `runPush` should never be reached. If a state-machine regression ever
+ * routed an operator past that guard, `runPush` checks this helper and
+ * refuses to issue the API call — instead it routes back to the print-files
+ * local-save path via `buildSkippedPushTransition`.
+ */
+export function shouldRefusePush(state) {
+    return state.credentialsSkipped === true;
+}
+export function buildSkippedPushTransition() {
+    return { step: 'print-gate' };
+}

package/dist/src/lib/contentful-urls.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared Contentful webapp URL builders.
+ *
+ * The wizard's `done` step and the `experiences import` orchestrator both used
+ * to inline the same post-push URL formatter. This module centralizes that
+ * formatter so the wizard, `apply push`, and `apply select` all emit the same
+ * URL shape.
+ *
+ * Path: `/views/components` (modern path; the legacy `/exo/components` was
+ * replaced in INTEG-4227).
+ *
+ * Host mapping: api.contentful.com → app.contentful.com,
+ *               api.flinkly.com    → app.flinkly.com,
+ *               api.quirely.com    → app.quirely.com.
+ * Unknown hosts fall through unchanged (no guessing — see the parity-gap-fills
+ * spec, "Gap 4 URL host mapping" risk note).
+ */
+export interface BuildPostPushUrlInput {
+    host: string;
+    spaceId: string;
+    environmentId: string;
+}
+/**
+ * Map a Contentful API host to the corresponding webapp host. For api.*.com
+ * inputs this swaps the `api.` prefix to `app.`; any other host is returned
+ * as-is (callers get the raw host, no guessing).
+ */
+export declare function apiHostToAppHost(host: string): string;
+/**
+ * Build the Contentful webapp URL operators see after a successful push.
+ * Matches the wizard `done` step's existing output byte-for-byte for
+ * `api.contentful.com`.
+ */
+export declare function buildPostPushUrl({ host, spaceId, environmentId }: BuildPostPushUrlInput): string;

package/dist/src/lib/contentful-urls.js

@@ -0,0 +1,41 @@
+/**
+ * Shared Contentful webapp URL builders.
+ *
+ * The wizard's `done` step and the `experiences import` orchestrator both used
+ * to inline the same post-push URL formatter. This module centralizes that
+ * formatter so the wizard, `apply push`, and `apply select` all emit the same
+ * URL shape.
+ *
+ * Path: `/views/components` (modern path; the legacy `/exo/components` was
+ * replaced in INTEG-4227).
+ *
+ * Host mapping: api.contentful.com → app.contentful.com,
+ *               api.flinkly.com    → app.flinkly.com,
+ *               api.quirely.com    → app.quirely.com.
+ * Unknown hosts fall through unchanged (no guessing — see the parity-gap-fills
+ * spec, "Gap 4 URL host mapping" risk note).
+ */
+function normalizeHost(host) {
+    return host
+        .trim()
+        .replace(/^https?:\/\//i, '')
+        .replace(/\/+$/, '');
+}
+/**
+ * Map a Contentful API host to the corresponding webapp host. For api.*.com
+ * inputs this swaps the `api.` prefix to `app.`; any other host is returned
+ * as-is (callers get the raw host, no guessing).
+ */
+export function apiHostToAppHost(host) {
+    const normalized = normalizeHost(host);
+    return normalized.replace(/^api\./, 'app.');
+}
+/**
+ * Build the Contentful webapp URL operators see after a successful push.
+ * Matches the wizard `done` step's existing output byte-for-byte for
+ * `api.contentful.com`.
+ */
+export function buildPostPushUrl({ host, spaceId, environmentId }) {
+    const appHost = apiHostToAppHost(host);
+    return `https://${appHost}/spaces/${spaceId}/environments/${environmentId}/views/components`;
+}

package/dist/src/program.js

@@ -10,6 +10,7 @@ import { registerSessionCommand } from './session/command.js';
 import { registerPrintCommand } from './print/command.js';
 import { registerImportCommand } from './import/command.js';
 import { registerSetupCommand } from './setup/command.js';
+import { registerRunsCommand } from './runs/ls-command.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 /**
@@ -62,6 +63,7 @@ export function createProgram() {
     registerSessionCommand(program);
     registerImportCommand(program);
     registerSetupCommand(program);
+    registerRunsCommand(program);
     registerBuildCommand(program);
     return program;
 }

package/dist/src/runs/export-helpers.d.ts

@@ -0,0 +1,30 @@
+export type PrintResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the path to the package's CLI binary (`<pkg>/bin/cli.js`).
+ *
+ * Walks up from this module's location until it finds a directory that
+ * contains `bin/cli.js`. This is robust to layout differences between source
+ * (`<pkg>/src/runs/export-helpers.ts`) and compiled output
+ * (`<pkg>/dist/src/runs/export-helpers.js`) — the previous string-counted
+ * `..` chain was off-by-one against the compiled layout, sending lookups to
+ * `<pkg>/dist/bin/cli.js` (which does not exist).
+ */
+declare function findCliPath(): string;
+export declare function printComponentsFromSession(opts: {
+    sessionId: string;
+    outPath: string;
+}): Promise<PrintResult>;
+export declare function printTokensFromSession(opts: {
+    sessionId: string;
+    outPath: string;
+}): Promise<PrintResult>;
+/** Internal test surface. Not part of the public API. */
+export declare const __testing: {
+    findCliPath: typeof findCliPath;
+};
+export {};

package/dist/src/runs/export-helpers.js

@@ -0,0 +1,59 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the path to the package's CLI binary (`<pkg>/bin/cli.js`).
+ *
+ * Walks up from this module's location until it finds a directory that
+ * contains `bin/cli.js`. This is robust to layout differences between source
+ * (`<pkg>/src/runs/export-helpers.ts`) and compiled output
+ * (`<pkg>/dist/src/runs/export-helpers.js`) — the previous string-counted
+ * `..` chain was off-by-one against the compiled layout, sending lookups to
+ * `<pkg>/dist/bin/cli.js` (which does not exist).
+ */
+function findCliPath() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    // Search up to 8 levels; the real distance is 3 (src) or 4 (dist/src).
+    for (let i = 0; i < 8; i++) {
+        const candidate = join(dir, 'bin', 'cli.js');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fall back to the compiled-layout path; the existsSync check in runCli
+    // will surface a clear error if it is missing.
+    return join(fileURLToPath(import.meta.url), '..', '..', '..', '..', 'bin', 'cli.js');
+}
+function runCli(args) {
+    const cliPath = findCliPath();
+    if (!existsSync(cliPath)) {
+        return Promise.resolve({
+            exitCode: 1,
+            stdout: '',
+            stderr: `Cannot find CLI binary at ${cliPath}`,
+        });
+    }
+    return new Promise((res) => {
+        execFile('node', [cliPath, ...args], (err, stdout, stderr) => {
+            res({ exitCode: err && 'code' in err && typeof err.code === 'number' ? err.code : err ? 1 : 0, stdout, stderr });
+        });
+    });
+}
+export async function printComponentsFromSession(opts) {
+    const r = await runCli(['print', 'components', '--session', opts.sessionId, '--out', opts.outPath]);
+    if (r.exitCode === 0)
+        return { ok: true };
+    return { ok: false, error: r.stderr.trim() || `exit ${r.exitCode}` };
+}
+export async function printTokensFromSession(opts) {
+    const r = await runCli(['print', 'tokens', '--session', opts.sessionId, '--out', opts.outPath]);
+    if (r.exitCode === 0)
+        return { ok: true };
+    return { ok: false, error: r.stderr.trim() || `exit ${r.exitCode}` };
+}
+/** Internal test surface. Not part of the public API. */
+export const __testing = { findCliPath };

package/dist/src/runs/fingerprint.d.ts

@@ -0,0 +1,47 @@
+export type SourceFileEntry = {
+    mtime: string;
+    componentName?: string;
+};
+export type SourceFingerprint = {
+    files: Record<string, SourceFileEntry>;
+    rawTokensPath: string | null;
+    rawTokensMtime: string | null;
+    rawTokensContentHash: string | null;
+};
+export type SavedFingerprint = {
+    componentsJsonHash: string | null;
+    tokensJsonHash: string | null;
+};
+/**
+ * Minimal duck-typed sqlite interface; we don't depend on better-sqlite3
+ * directly from this module (the wizard already opens the DB and passes it
+ * in). `name` may be null in the DB; we filter those rows out.
+ */
+export interface RawComponentsDb {
+    prepare(sql: string): {
+        all(sessionId: string): Array<Record<string, unknown>>;
+    };
+}
+export declare function sha256Hex(buf: Buffer | string): string;
+/**
+ * Build a per-file fingerprint of every source file that contributed to a
+ * run. Stats each unique source_path once (first-seen component name wins),
+ * and (optionally) hashes the raw tokens file too.
+ *
+ * Missing files do NOT throw — they're simply omitted. The read-side
+ * staleness check re-stats from disk and surfaces missing files there so we
+ * can report which one disappeared.
+ */
+export declare function buildSourceFingerprint(opts: {
+    db: RawComponentsDb;
+    extractSessionId: string;
+    rawTokensPath?: string | null;
+}): Promise<SourceFingerprint>;
+/**
+ * Hash the saved JSON contents the wizard just wrote. Caller passes the raw
+ * bytes (or strings) so we hash exactly what landed on disk.
+ */
+export declare function buildSavedFingerprint(input: {
+    componentsJson: string | Buffer | null;
+    tokensJson: string | Buffer | null;
+}): SavedFingerprint;

package/dist/src/runs/fingerprint.js

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+function rowField(row, key) {
+    const v = row[key];
+    return typeof v === 'string' ? v : null;
+}
+export function sha256Hex(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * Build a per-file fingerprint of every source file that contributed to a
+ * run. Stats each unique source_path once (first-seen component name wins),
+ * and (optionally) hashes the raw tokens file too.
+ *
+ * Missing files do NOT throw — they're simply omitted. The read-side
+ * staleness check re-stats from disk and surfaces missing files there so we
+ * can report which one disappeared.
+ */
+export async function buildSourceFingerprint(opts) {
+    const rows = opts.db
+        .prepare('SELECT name, source_path FROM raw_components WHERE session_id = ?')
+        .all(opts.extractSessionId);
+    const files = {};
+    const seen = new Set();
+    for (const row of rows) {
+        const sourcePath = rowField(row, 'source_path');
+        const name = rowField(row, 'name');
+        if (!sourcePath)
+            continue;
+        const abs = resolve(sourcePath);
+        if (seen.has(abs))
+            continue;
+        seen.add(abs);
+        try {
+            const st = await stat(abs);
+            const entry = { mtime: st.mtime.toISOString() };
+            if (name)
+                entry.componentName = name;
+            files[abs] = entry;
+        }
+        catch {
+            // Source file missing at fingerprint time — skip silently. Staleness
+            // can only fire on files we recorded; a file removed before save
+            // simply isn't tracked. Operators usually re-extract in that case.
+        }
+    }
+    let rawTokensPath = null;
+    let rawTokensMtime = null;
+    let rawTokensContentHash = null;
+    if (opts.rawTokensPath) {
+        const abs = resolve(opts.rawTokensPath);
+        rawTokensPath = abs;
+        try {
+            const [st, buf] = await Promise.all([stat(abs), readFile(abs)]);
+            rawTokensMtime = st.mtime.toISOString();
+            rawTokensContentHash = sha256Hex(buf);
+        }
+        catch {
+            // Missing raw tokens — record the path but leave mtime/hash null so
+            // the staleness check can detect it as missing on read.
+        }
+    }
+    return { files, rawTokensPath, rawTokensMtime, rawTokensContentHash };
+}
+/**
+ * Hash the saved JSON contents the wizard just wrote. Caller passes the raw
+ * bytes (or strings) so we hash exactly what landed on disk.
+ */
+export function buildSavedFingerprint(input) {
+    return {
+        componentsJsonHash: input.componentsJson != null ? sha256Hex(input.componentsJson) : null,
+        tokensJsonHash: input.tokensJson != null ? sha256Hex(input.tokensJson) : null,
+    };
+}

package/dist/src/runs/ls-command.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+export type RunLsOptions = {
+    write?: (chunk: string) => void;
+    projectPath?: string;
+    limit?: number;
+    target?: string;
+    json?: boolean;
+    pushed?: boolean;
+    notPushed?: boolean;
+};
+export declare function runLsCommand(opts?: RunLsOptions): Promise<void>;
+export declare function registerRunsCommand(program: Command): void;