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

package/dist/src/runs/ls-command.js

@@ -0,0 +1,137 @@
+import { listRuns } from './store.js';
+import { resolveRunTarget } from './resolve-run-target.js';
+import { checkRunStaleness, shortStalenessSummary, formatStalenessDetail } from './staleness.js';
+function pad(value, width) {
+    if (value.length >= width)
+        return value;
+    return value + ' '.repeat(width - value.length);
+}
+function formatCreated(iso) {
+    // Drop ms + Z, render as `YYYY-MM-DD HH:MM`.
+    const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(iso);
+    return m ? `${m[1]} ${m[2]}` : iso;
+}
+function formatPushed(record) {
+    if (!record.pushedTo)
+        return '(not pushed)';
+    return `${record.pushedTo.spaceId}/${record.pushedTo.environmentId}`;
+}
+function makeColumns(staleness) {
+    return [
+        { header: 'ID', get: (r) => r.id },
+        { header: 'CREATED', get: (r) => formatCreated(r.createdAt) },
+        { header: 'PROJECT', get: (r) => r.projectPath },
+        { header: 'SAVED TO', get: (r) => r.savePath },
+        { header: 'COMPONENTS', get: (r) => String(r.componentCount) },
+        { header: 'PUSHED', get: formatPushed },
+        { header: 'STALE', get: (_r, i) => shortStalenessSummary(staleness[i]) },
+    ];
+}
+function renderFooter(runs, write) {
+    if (runs.length === 0)
+        return;
+    const id = runs[0].id;
+    write('\n');
+    write(`Push run ${id}:    experiences import --push-from-run ${id}\n`);
+    write(`Modify run ${id}:  experiences import --modify ${id}\n`);
+}
+async function renderDetail(run, write) {
+    const lines = [
+        `Run ${run.id}`,
+        `Created: ${formatCreated(run.createdAt)}`,
+        `Project: ${run.projectPath}`,
+        `Saved:   ${run.savePath}`,
+        `Components: ${run.componentCount}`,
+        `Tokens:     ${run.tokenCount}`,
+    ];
+    if (run.tokensPath) {
+        lines.push(`Tokens saved: ${run.tokensPath}`);
+    }
+    lines.push(`Agent:      ${run.agent}`, `Pushed:     ${formatPushed(run)}`, '');
+    // Staleness status block. v2/v1 records (no sourceFingerprint) render as
+    // UNKNOWN — the operator can re-extract for a fresh run.
+    if (!run.sourceFingerprint) {
+        lines.push('Status: UNKNOWN (run pre-dates the staleness fingerprint).');
+    }
+    else {
+        const staleness = await checkRunStaleness(run);
+        lines.push(...formatStalenessDetail(staleness));
+    }
+    lines.push('', `Push to Contentful:   experiences import --push-from-run ${run.id}`, `Modify in wizard:     experiences import --modify ${run.id}`, '');
+    write(lines.join('\n'));
+}
+export async function runLsCommand(opts = {}) {
+    const write = opts.write ?? ((s) => process.stdout.write(s));
+    if (opts.pushed && opts.notPushed) {
+        throw new Error('--pushed and --not-pushed are mutually exclusive');
+    }
+    if (opts.target) {
+        const run = await resolveRunTarget(opts.target);
+        if (opts.json) {
+            write(JSON.stringify(run, null, 2) + '\n');
+            return;
+        }
+        await renderDetail(run, write);
+        return;
+    }
+    let runs = await listRuns({
+        ...(opts.projectPath ? { projectPath: opts.projectPath } : {}),
+        ...(typeof opts.limit === 'number' ? { limit: opts.limit } : {}),
+    });
+    if (opts.pushed)
+        runs = runs.filter((r) => r.pushedTo !== null);
+    if (opts.notPushed)
+        runs = runs.filter((r) => r.pushedTo === null);
+    if (opts.json) {
+        write(JSON.stringify(runs, null, 2) + '\n');
+        return;
+    }
+    if (runs.length === 0) {
+        write('No runs recorded yet. Run `experiences import` to create one.\n');
+        return;
+    }
+    // Compute staleness once per row so the table is consistent across the
+    // STALE column and any future detail-equivalent surfaces.
+    const stalenessByIdx = await Promise.all(runs.map(async (r) => (r.sourceFingerprint ? checkRunStaleness(r) : null)));
+    const stalenessForCol = stalenessByIdx.map((s) => s ?? {
+        stale: false,
+        staleComponents: [],
+        staleTokens: false,
+        savedComponentsEdited: false,
+        savedTokensEdited: false,
+        missingSourceFiles: [],
+    });
+    const columns = makeColumns(stalenessForCol);
+    // Auto-expand each column to max(header, max(row value)) so long paths
+    // aren't silently truncated.
+    const widths = columns.map((c) => Math.max(c.header.length, ...runs.map((r, i) => c.get(r, i).length)));
+    const headerRow = columns.map((c, i) => pad(c.header, widths[i])).join('  ');
+    write(headerRow + '\n');
+    for (let i = 0; i < runs.length; i++) {
+        const r = runs[i];
+        const row = columns.map((c, ci) => pad(c.get(r, i), widths[ci])).join('  ');
+        write(row + '\n');
+    }
+    renderFooter(runs, write);
+}
+export function registerRunsCommand(program) {
+    program
+        .command('runs [target]')
+        .alias('ls')
+        .description('List recorded import runs from ~/.config/experiences/runs.json, or show one run when [target] (id or path) is given')
+        .option('--project <path>', 'Filter by source project path (absolute)')
+        .option('--limit <n>', 'Limit the number of rows', (v) => parseInt(v, 10))
+        .option('--json', 'Emit RunRecord JSON to stdout (array, or single object with [target])')
+        .option('--pushed', 'Only show runs that have been pushed to Contentful')
+        .option('--not-pushed', 'Only show runs that have not been pushed')
+        .action(async (target, options) => {
+        await runLsCommand({
+            ...(target ? { target } : {}),
+            ...(options.project ? { projectPath: options.project } : {}),
+            ...(typeof options.limit === 'number' && !Number.isNaN(options.limit) ? { limit: options.limit } : {}),
+            ...(options.json ? { json: true } : {}),
+            ...(options.pushed ? { pushed: true } : {}),
+            ...(options.notPushed ? { notPushed: true } : {}),
+        });
+    });
+}

package/dist/src/runs/modify-launcher.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thin indirection so `runModifyCommand` can be unit-tested without spinning
+ * up the real Ink wizard. The production implementation lives here.
+ */
+export type ModifyLauncherInput = {
+    extractSessionId: string;
+    generateSessionId: string | null;
+    /** Token session id from the run record; null when no tokens were
+     *  generated. Forwarded to the wizard so the modify entry pre-loads
+     *  tokens alongside the extract/generate sessions. */
+    tokenSessionId?: string | null;
+    projectPath: string;
+    savePath: string;
+    entryStep: 'scope-gate' | 'final-review';
+    saveMode: 'overwrite' | 'new' | 'prompt';
+    outDirOverride?: string;
+    /** Pre-fill space id (from the run record's pushedTo). */
+    initialSpaceId?: string;
+    /** Pre-fill environment id (from the run record's pushedTo). */
+    initialEnvironmentId?: string;
+    /** Pre-fill host (from the run record's pushedTo). */
+    initialHost?: string;
+};
+export declare function launchModifyWizard(input: ModifyLauncherInput): Promise<void>;

package/dist/src/runs/modify-launcher.js

@@ -0,0 +1,36 @@
+/**
+ * Thin indirection so `runModifyCommand` can be unit-tested without spinning
+ * up the real Ink wizard. The production implementation lives here.
+ */
+export async function launchModifyWizard(input) {
+    const { render } = await import('ink');
+    const { createElement } = await import('react');
+    const { WizardApp } = await import('../import/tui/WizardApp.js');
+    // Modify entry: re-open the wizard with the prior run's sessions seeded so
+    // extract + generate are skipped. The wizard short-circuits to `initialStep`
+    // (typically `final-review`) using state derived from the seed IDs. Saved
+    // credentials from the run record's `pushedTo` pre-fill the credentials
+    // step (CMA token is never persisted, so it still falls through to the
+    // env/credentials.json/prompt resolution path).
+    const props = {
+        initialProjectPath: input.projectPath,
+        seedExtractSessionId: input.extractSessionId,
+        initialStep: input.entryStep,
+    };
+    if (input.generateSessionId)
+        props.seedGenerateSessionId = input.generateSessionId;
+    if (input.tokenSessionId)
+        props.seedTokenSessionId = input.tokenSessionId;
+    if (input.saveMode === 'overwrite')
+        props.outDirOverride = input.savePath;
+    if (input.outDirOverride)
+        props.outDirOverride = input.outDirOverride;
+    if (input.initialSpaceId)
+        props.initialSpaceId = input.initialSpaceId;
+    if (input.initialEnvironmentId)
+        props.initialEnvironmentId = input.initialEnvironmentId;
+    if (input.initialHost)
+        props.initialHost = input.initialHost;
+    const { waitUntilExit } = render(createElement(WizardApp, props));
+    await waitUntilExit();
+}

package/dist/src/runs/path-prompt.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+export type PathPromptProps = {
+    defaultPath: string;
+    onSubmit: (path: string) => void;
+    onCancel: () => void;
+    label?: string;
+};
+export declare function PathPrompt({ defaultPath, onSubmit, onCancel, label, }: PathPromptProps): React.ReactElement;

package/dist/src/runs/path-prompt.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import { readdirSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { useImmediateInput } from '../analyze/select/tui/hooks/useImmediateInput.js';
+import { normalizePath } from '../import/path-utils.js';
+function autocomplete(partial) {
+    if (!partial)
+        return null;
+    const normalized = normalizePath(partial);
+    const dir = dirname(normalized);
+    const base = basename(normalized);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const matches = entries.filter((e) => e.startsWith(base));
+    if (matches.length === 0)
+        return null;
+    if (matches.length === 1)
+        return join(dir, matches[0]);
+    // Common prefix
+    let prefix = matches[0];
+    for (const m of matches) {
+        while (!m.startsWith(prefix))
+            prefix = prefix.slice(0, -1);
+        if (!prefix)
+            break;
+    }
+    return prefix.length > base.length ? join(dir, prefix) : null;
+}
+export function PathPrompt({ defaultPath, onSubmit, onCancel, label = 'Save to', }) {
+    const [input, setInput] = useState('');
+    const [cursorVisible, setCursorVisible] = useState(true);
+    useEffect(() => {
+        const interval = setInterval(() => setCursorVisible((v) => !v), 500);
+        return () => clearInterval(interval);
+    }, []);
+    useImmediateInput((rawInput, key) => {
+        if (key.return) {
+            const trimmed = input.trim();
+            onSubmit(trimmed === '' ? defaultPath : normalizePath(trimmed));
+            return;
+        }
+        if (key.escape) {
+            onCancel();
+            return;
+        }
+        if (key.tab) {
+            const target = input.trim() || defaultPath;
+            const completed = autocomplete(target);
+            if (completed)
+                setInput(completed);
+            return;
+        }
+        if (key.backspace || key.delete) {
+            setInput((v) => v.slice(0, -1));
+            return;
+        }
+        if (rawInput && !key.ctrl && !key.meta) {
+            setInput((v) => v + rawInput);
+        }
+    });
+    const shown = input || defaultPath;
+    const isPlaceholder = input === '';
+    const cursor = cursorVisible ? '█' : ' ';
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: "cyan", children: "?" }), _jsxs(Text, { bold: true, children: [label, ":"] }), _jsx(Text, { dimColor: isPlaceholder, children: shown }), _jsx(Text, { children: cursor })] }), _jsxs(Box, { gap: 3, children: [_jsx(Text, { dimColor: true, children: "[Enter] Confirm" }), _jsx(Text, { dimColor: true, children: "[Tab] Autocomplete" }), _jsx(Text, { dimColor: true, children: "[Esc] Cancel" })] })] }));
+}

package/dist/src/runs/push-creds-prompt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Interactive credentials fallback for `experiences import --push-from-run`.
+ *
+ * The wizard ships a full `CredentialsStep` Ink component already — rather
+ * than reimplementing the field-entry UI, we mount that step in a tiny Ink
+ * app that resolves a promise once the operator confirms.
+ *
+ * Returns the four credential values (host comes back as a configured host
+ * string, e.g. `api.contentful.com`).
+ */
+export type CollectedCredentials = {
+    spaceId: string;
+    environmentId: string;
+    cmaToken: string;
+    host: string;
+};
+export type PromptForCredentialsOptions = {
+    initialSpaceId?: string;
+    initialEnvironmentId?: string;
+    initialCmaToken?: string;
+    initialHost?: string;
+    /** Short summary line rendered above the form. */
+    summary?: string;
+};
+export declare function promptForPushCredentials(opts?: PromptForCredentialsOptions): Promise<CollectedCredentials>;

package/dist/src/runs/push-creds-prompt.js

@@ -0,0 +1,39 @@
+import React from 'react';
+export async function promptForPushCredentials(opts = {}) {
+    const { render, Box, Text } = await import('ink');
+    const { useState } = await import('react');
+    const { CredentialsStep } = await import('../import/tui/steps/CredentialsStep.js');
+    return new Promise((resolve, reject) => {
+        let app = null;
+        function App() {
+            const [done, setDone] = useState(false);
+            const handle = (spaceId, environmentId, cmaToken, host) => {
+                if (done)
+                    return;
+                setDone(true);
+                // Defer unmount so Ink flushes the final render.
+                queueMicrotask(() => {
+                    app?.unmount();
+                    resolve({ spaceId, environmentId, cmaToken, host });
+                });
+            };
+            if (done) {
+                return React.createElement(Box, null, React.createElement(Text, null, ''));
+            }
+            return React.createElement(CredentialsStep, {
+                summary: opts.summary ?? 'Enter Contentful credentials to push this run. Press Enter on each field to advance.',
+                ...(opts.initialSpaceId !== undefined ? { initialSpaceId: opts.initialSpaceId } : {}),
+                ...(opts.initialEnvironmentId !== undefined ? { initialEnvironmentId: opts.initialEnvironmentId } : {}),
+                ...(opts.initialCmaToken !== undefined ? { initialCmaToken: opts.initialCmaToken } : {}),
+                ...(opts.initialHost !== undefined ? { initialHost: opts.initialHost } : {}),
+                onConfirm: handle,
+                onContinue: handle,
+                onQuit: () => {
+                    app?.unmount();
+                    reject(new Error('Credentials entry cancelled.'));
+                },
+            });
+        }
+        app = render(React.createElement(App));
+    });
+}

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

@@ -0,0 +1,29 @@
+export type PushSessionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the package's CLI binary. Duplicates the walk from export-helpers
+ * so push-helpers can be imported independently.
+ */
+declare function findCliPath(): string;
+export type PushSessionOptions = {
+    sessionId: string;
+    spaceId: string;
+    environmentId: string;
+    cmaToken: string;
+    host?: string;
+};
+/**
+ * Push a recorded pipeline.db session's components + tokens to Contentful by
+ * shelling out to `experiences apply push --session <id>`. Does no local
+ * file I/O — that is the whole point of --push-from-run.
+ */
+export declare function pushRunSession(opts: PushSessionOptions): Promise<PushSessionResult>;
+/** Internal test surface. Not part of the public API. */
+export declare const __testing: {
+    findCliPath: typeof findCliPath;
+};
+export {};

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

@@ -0,0 +1,69 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the package's CLI binary. Duplicates the walk from export-helpers
+ * so push-helpers can be imported independently.
+ */
+function findCliPath() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    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;
+    }
+    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,
+            });
+        });
+    });
+}
+/**
+ * Push a recorded pipeline.db session's components + tokens to Contentful by
+ * shelling out to `experiences apply push --session <id>`. Does no local
+ * file I/O — that is the whole point of --push-from-run.
+ */
+export async function pushRunSession(opts) {
+    const args = [
+        'apply',
+        'push',
+        '--session',
+        opts.sessionId,
+        '--space-id',
+        opts.spaceId,
+        '--environment-id',
+        opts.environmentId,
+        '--cma-token',
+        opts.cmaToken,
+        '--yes',
+    ];
+    if (opts.host) {
+        args.push('--host', opts.host);
+    }
+    const r = await runCli(args);
+    if (r.exitCode === 0)
+        return { ok: true };
+    return { ok: false, error: r.stderr.trim() || r.stdout.trim() || `exit ${r.exitCode}` };
+}
+/** Internal test surface. Not part of the public API. */
+export const __testing = { findCliPath };

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

@@ -0,0 +1,67 @@
+export type ReplayRunOptions = {
+    runIdOrPath: string;
+    /** From `--space-id` flag. */
+    spaceId?: string;
+    /** From `--environment-id` flag. */
+    environmentId?: string;
+    /** From `--cma-token` flag (or CONTENTFUL_MANAGEMENT_TOKEN env). */
+    cmaToken?: string;
+    /** From `--host` flag. */
+    host?: string;
+    /**
+     * When true (interactive TTY), prompt for missing credentials via the
+     * wizard's CredentialsStep. When false (non-TTY / CI), throw with the
+     * pinned error string from the spec.
+     */
+    interactive?: boolean;
+    /** When true, bypass the source/saved-file staleness check. */
+    force?: boolean;
+    /**
+     * Test seam: replace the interactive prompt with a deterministic resolver.
+     * The CLI surface never sets this; only used by tests.
+     */
+    promptForCredentials?: (need: {
+        spaceId?: string;
+        environmentId?: string;
+        cmaToken?: string;
+        host?: string;
+    }) => Promise<{
+        spaceId: string;
+        environmentId: string;
+        cmaToken: string;
+        host: string;
+    }>;
+};
+/**
+ * Push a prior run's recorded pipeline.db session directly to Contentful
+ * without re-running extraction or generation, and without writing any
+ * components.json / tokens.json to disk.
+ *
+ * Exposed as `experiences import --push-from-run <id-or-path>`.
+ *
+ * Credentials resolution order:
+ *   1. Flags on the command (`--space-id`, `--environment-id`, `--cma-token`,
+ *      `--host`).
+ *   2. The run record's `pushedTo` field (space / env / host only — the
+ *      CMA token is never persisted).
+ *   3. `~/.config/experiences/credentials.json` (the `experiences setup`
+ *      store) and matching env vars.
+ *   4. If still incomplete and interactive: open the wizard's existing
+ *      credentials step. If non-TTY: error.
+ */
+export declare function replayRun(opts: ReplayRunOptions): Promise<void>;
+export type ModifyRunOptions = {
+    runIdOrPath: string;
+    saveAsNew?: boolean;
+    overwrite?: boolean;
+    outDir?: string;
+    /** When true, bypass the source/saved-file staleness check. */
+    force?: boolean;
+};
+/**
+ * Re-open the wizard with a prior run's extract/generate session pre-populated
+ * so the operator can tweak fields. Exposed as
+ * `experiences import --modify <id-or-path>`. Default entry step is
+ * `final-review`.
+ */
+export declare function modifyRun(opts: ModifyRunOptions): Promise<void>;

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

@@ -0,0 +1,148 @@
+import { resolve } from 'node:path';
+import { resolveRunTarget } from './resolve-run-target.js';
+import { updateRun } from './store.js';
+import { pushRunSession } from './push-helpers.js';
+import { readExperiencesCredentials } from '../credentials-store.js';
+import { launchModifyWizard } from './modify-launcher.js';
+import { checkRunStaleness, formatStalenessDetail } from './staleness.js';
+function formatStalenessRefusal(run, detail) {
+    return [
+        `Refusing to replay run ${run.id} — source or saved files have drifted since the run was recorded.`,
+        ...detail,
+        '',
+        'Re-extract with `experiences import --project <path>` for a fresh run, or pass --force to bypass.',
+    ].join('\n');
+}
+const MISSING_CREDS_ERROR = "--push-from-run requires credentials (space-id / environment-id / cma-token). Pass --cma-token or run 'experiences setup' first.";
+/**
+ * Push a prior run's recorded pipeline.db session directly to Contentful
+ * without re-running extraction or generation, and without writing any
+ * components.json / tokens.json to disk.
+ *
+ * Exposed as `experiences import --push-from-run <id-or-path>`.
+ *
+ * Credentials resolution order:
+ *   1. Flags on the command (`--space-id`, `--environment-id`, `--cma-token`,
+ *      `--host`).
+ *   2. The run record's `pushedTo` field (space / env / host only — the
+ *      CMA token is never persisted).
+ *   3. `~/.config/experiences/credentials.json` (the `experiences setup`
+ *      store) and matching env vars.
+ *   4. If still incomplete and interactive: open the wizard's existing
+ *      credentials step. If non-TTY: error.
+ */
+export async function replayRun(opts) {
+    const run = await resolveRunTarget(opts.runIdOrPath);
+    // Staleness gate: refuse before any push side effect when source files or
+    // saved artifacts have drifted. Bypassed by --force.
+    if (!opts.force) {
+        const staleness = await checkRunStaleness(run);
+        if (staleness.stale) {
+            throw new Error(formatStalenessRefusal(run, formatStalenessDetail(staleness)));
+        }
+    }
+    const sessionId = run.generateSessionId ?? run.extractSessionId;
+    // Layered credentials resolution.
+    const stored = await readExperiencesCredentials();
+    let spaceId = opts.spaceId || run.pushedTo?.spaceId || stored.spaceId || '';
+    let environmentId = opts.environmentId || run.pushedTo?.environmentId || stored.environmentId || '';
+    let cmaToken = opts.cmaToken || stored.cmaToken || '';
+    let host = opts.host || run.pushedTo?.host || stored.host || '';
+    if (!spaceId || !environmentId || !cmaToken) {
+        if (!opts.interactive) {
+            throw new Error(MISSING_CREDS_ERROR);
+        }
+        const prompt = opts.promptForCredentials ??
+            (async (need) => {
+                const { promptForPushCredentials } = await import('./push-creds-prompt.js');
+                return promptForPushCredentials({
+                    ...(need.spaceId ? { initialSpaceId: need.spaceId } : {}),
+                    ...(need.environmentId ? { initialEnvironmentId: need.environmentId } : {}),
+                    ...(need.cmaToken ? { initialCmaToken: need.cmaToken } : {}),
+                    ...(need.host ? { initialHost: need.host } : {}),
+                    summary: `Push run ${run.id} → enter credentials. Defaults reflect the run record and your saved setup.`,
+                });
+            });
+        const collected = await prompt({
+            spaceId,
+            environmentId,
+            cmaToken,
+            host,
+        });
+        spaceId = collected.spaceId;
+        environmentId = collected.environmentId;
+        cmaToken = collected.cmaToken;
+        host = collected.host;
+        if (!spaceId || !environmentId || !cmaToken) {
+            throw new Error(MISSING_CREDS_ERROR);
+        }
+    }
+    const result = await pushRunSession({
+        sessionId,
+        spaceId,
+        environmentId,
+        cmaToken,
+        ...(host ? { host } : {}),
+    });
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+    // Push the tokens session too when the run has one. Tokens live in their
+    // own pipeline.db session (separate from extract/generate), so a single
+    // `apply push --session <id>` only covers components. Without this second
+    // push, design tokens recorded by the run never reach Contentful on replay.
+    if (run.tokenSessionId) {
+        const tokenResult = await pushRunSession({
+            sessionId: run.tokenSessionId,
+            spaceId,
+            environmentId,
+            cmaToken,
+            ...(host ? { host } : {}),
+        });
+        if (!tokenResult.ok) {
+            throw new Error(tokenResult.error);
+        }
+    }
+    await updateRun(run.id, {
+        pushedTo: { spaceId, environmentId, host: host || '' },
+    });
+    const componentLine = `Pushed ${run.componentCount} component${run.componentCount === 1 ? '' : 's'} to ${spaceId}/${environmentId}`;
+    const tokensLine = run.tokenCount > 0 ? ` (also: ${run.tokenCount} token${run.tokenCount === 1 ? '' : 's'})` : '';
+    process.stdout.write(`${componentLine}${tokensLine}\n`);
+}
+/**
+ * Re-open the wizard with a prior run's extract/generate session pre-populated
+ * so the operator can tweak fields. Exposed as
+ * `experiences import --modify <id-or-path>`. Default entry step is
+ * `final-review`.
+ */
+export async function modifyRun(opts) {
+    if (opts.saveAsNew && opts.overwrite) {
+        throw new Error('--save-as-new and --overwrite are mutually exclusive.');
+    }
+    const run = await resolveRunTarget(opts.runIdOrPath);
+    if (!opts.force) {
+        const staleness = await checkRunStaleness(run);
+        if (staleness.stale) {
+            throw new Error(formatStalenessRefusal(run, formatStalenessDetail(staleness)));
+        }
+    }
+    const saveMode = opts.overwrite ? 'overwrite' : opts.saveAsNew ? 'new' : 'prompt';
+    await launchModifyWizard({
+        extractSessionId: run.extractSessionId,
+        generateSessionId: run.generateSessionId,
+        tokenSessionId: run.tokenSessionId,
+        projectPath: run.projectPath,
+        savePath: run.savePath,
+        entryStep: 'final-review',
+        saveMode,
+        ...(opts.outDir ? { outDirOverride: resolve(opts.outDir) } : {}),
+        // Pre-fill credentials from the run record's last push so the operator
+        // doesn't have to re-type space/environment/host on modify. The CMA
+        // token is never persisted, so it still resolves via env var /
+        // credentials.json / interactive prompt at the credentials step.
+        ...(run.pushedTo?.spaceId ? { initialSpaceId: run.pushedTo.spaceId } : {}),
+        ...(run.pushedTo?.environmentId ? { initialEnvironmentId: run.pushedTo.environmentId } : {}),
+        ...(run.pushedTo?.host ? { initialHost: run.pushedTo.host } : {}),
+    });
+}

package/dist/src/runs/resolve-run-target.d.ts

@@ -0,0 +1,12 @@
+import { type RunRecord } from './store.js';
+/**
+ * Decide whether a positional CLI arg refers to a run-id or a filesystem path,
+ * then look up the corresponding RunRecord.
+ *
+ * Mirrors `git checkout` accepting either a sha or a ref: anything that *looks
+ * like* a path is treated as one; otherwise we fall back to a run-id lookup.
+ *
+ * Path detection: arg starts with `/`, `./`, `../`, or `~/`, OR equals `.`,
+ * OR equals `~`.
+ */
+export declare function resolveRunTarget(arg: string): Promise<RunRecord>;