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

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.12.1-dev-build-bae15c7.0",
+  "version": "2.12.1-dev-build-c47114b.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/apply/api-client.js

@@ -1,4 +1,5 @@
 import { DEFAULT_API_HOST, toApiHost } from '../host-utils.js';
+import { getDebugLogger } from '../lib/debug-logger.js';
 export const DEFAULT_HOST = DEFAULT_API_HOST;
 // Phase-prefix constants used at the two ApiError throw sites below and
 // imported by orchestrator.ts to identify preview-phase 422s for retry.
@@ -128,27 +129,57 @@ export class ImportApiClient {
     }
     async previewImport(manifest) {
         const url = `${this.base()}/design_systems/imports/preview`;
+        const debug = getDebugLogger();
+        const startedAt = Date.now();
+        debug.event('apply', 'preview.request', {
+            url,
+            componentCount: manifest.components?.length ?? 0,
+            tokenCount: manifest.designTokens?.length ?? 0,
+        });
         const res = await fetch(url, {
             method: 'POST',
             headers: this.headers(),
             body: JSON.stringify(manifest),
         });
         if (!res.ok) {
-            throw new ApiError(`${PREVIEW_ERROR_PREFIX} ${res.status}`, res.status, await res.text());
+            const body = await res.text();
+            debug.event('apply', 'preview.error', {
+                status: res.status,
+                durationMs: Date.now() - startedAt,
+                bodyHead: body.slice(0, 2000),
+            });
+            throw new ApiError(`${PREVIEW_ERROR_PREFIX} ${res.status}`, res.status, body);
         }
-        return (await res.json());
+        const parsed = (await res.json());
+        debug.event('apply', 'preview.ok', { status: res.status, durationMs: Date.now() - startedAt });
+        return parsed;
     }
     async applyImport(manifest, acknowledgeBreakingChanges) {
         const url = `${this.base()}/design_systems/imports/apply`;
+        const debug = getDebugLogger();
+        const startedAt = Date.now();
+        debug.event('apply', 'apply.request', { url, acknowledgeBreakingChanges });
         const res = await fetch(url, {
             method: 'POST',
             headers: this.headers(),
             body: JSON.stringify({ ...manifest, acknowledgeBreakingChanges }),
         });
         if (!res.ok) {
-            throw new ApiError(`${APPLY_ERROR_PREFIX} ${res.status}`, res.status, await res.text());
+            const body = await res.text();
+            debug.event('apply', 'apply.error', {
+                status: res.status,
+                durationMs: Date.now() - startedAt,
+                bodyHead: body.slice(0, 2000),
+            });
+            throw new ApiError(`${APPLY_ERROR_PREFIX} ${res.status}`, res.status, body);
         }
-        return (await res.json());
+        const parsed = (await res.json());
+        debug.event('apply', 'apply.accepted', {
+            status: res.status,
+            operationId: parsed.sys?.id,
+            durationMs: Date.now() - startedAt,
+        });
+        return parsed;
     }
     async pollOperation(operationId, opts = {}) {
         const intervalMs = opts.intervalMs ?? 2000;
@@ -166,7 +197,17 @@ export class ImportApiClient {
             }
             const op = (await res.json());
             opts.onProgress?.(op);
+            getDebugLogger().event('apply', 'poll.tick', {
+                operationId,
+                attempt,
+                status: op.sys.status,
+            });
             if (terminalStatuses.has(op.sys.status)) {
+                getDebugLogger().event('apply', 'poll.terminal', {
+                    operationId,
+                    attempt,
+                    status: op.sys.status,
+                });
                 return op;
             }
             if (attempt < maxAttempts - 1) {

package/dist/src/apply/command.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { validateCDF, flattenDTCG, validateDTCG, buildManifest, buildFilteredManifest, } from '@contentful/experience-design-system-types';
 import { ApiError, ImportApiClient } from './api-client.js';
 import { openPipelineDb, loadCDFComponents } from '../session/db.js';
+import { isEmptyPreview } from './preview-utils.js';
 import { ServerPreviewApp, ServerPreviewConfirm, ServerApplyProgress, ServerApplyDone } from './tui/ServerApplyView.js';
 import { SelectView, makeSelectKey } from './tui/SelectView.js';
 import { buildPostPushUrl } from '../lib/contentful-urls.js';
@@ -170,18 +171,6 @@ async function resolveSharedInputs(opts) {
     return { components, tokens, client };
 }
 // --- Output helpers ---
-function isEmptyPreview(preview) {
-    const { components, tokens, taxonomies } = preview;
-    return (components.new.length === 0 &&
-        components.changed.length === 0 &&
-        components.removed.length === 0 &&
-        tokens.new.length === 0 &&
-        tokens.changed.length === 0 &&
-        tokens.removed.length === 0 &&
-        taxonomies.new.length === 0 &&
-        taxonomies.changed.length === 0 &&
-        taxonomies.removed.length === 0);
-}
 export function hasBreakingChangesWithImpact(preview) {
     const allChanged = [...preview.components.changed, ...preview.tokens.changed];
     return allChanged.some((c) => c.changeClassification?.classification === 'breaking' &&

package/dist/src/apply/preview-utils.d.ts

@@ -0,0 +1,12 @@
+import type { ServerPreviewResponse } from '@contentful/experience-design-system-types';
+/**
+ * True when a preview response describes zero server-side changes across
+ * every diff bucket (components, tokens, taxonomies). Used by:
+ *   - `experiences apply` (CLI): short-circuit the confirm-and-push step.
+ *   - `experiences import` wizard: block finalize when the resulting push
+ *     would be a pure no-op (INTEG-4411 refined guard).
+ *
+ * A push that produces ANY entry in ANY bucket — including a rejection that
+ * removes a server-side component — is NOT empty.
+ */
+export declare function isEmptyPreview(preview: ServerPreviewResponse): boolean;

package/dist/src/apply/preview-utils.js

@@ -0,0 +1,22 @@
+/**
+ * True when a preview response describes zero server-side changes across
+ * every diff bucket (components, tokens, taxonomies). Used by:
+ *   - `experiences apply` (CLI): short-circuit the confirm-and-push step.
+ *   - `experiences import` wizard: block finalize when the resulting push
+ *     would be a pure no-op (INTEG-4411 refined guard).
+ *
+ * A push that produces ANY entry in ANY bucket — including a rejection that
+ * removes a server-side component — is NOT empty.
+ */
+export function isEmptyPreview(preview) {
+    const { components, tokens, taxonomies } = preview;
+    return (components.new.length === 0 &&
+        components.changed.length === 0 &&
+        components.removed.length === 0 &&
+        tokens.new.length === 0 &&
+        tokens.changed.length === 0 &&
+        tokens.removed.length === 0 &&
+        taxonomies.new.length === 0 &&
+        taxonomies.changed.length === 0 &&
+        taxonomies.removed.length === 0);
+}

package/dist/src/credentials-store.d.ts

@@ -10,7 +10,23 @@ export type ExperiencesCredentials = {
     /** Feature 8: persisted custom prompt path for `generate components`. */
     generatePromptPath?: string;
     autoFilter?: boolean;
+    /** Feature: default debug-mode (writes JSONL trace of every decision) for all commands. */
+    debug?: boolean;
 };
+/**
+ * Read persisted Contentful credentials.
+ *
+ * Precedence (INTEG-4410): what the operator saved on disk via
+ * `experiences setup` or the wizard's credentials step wins over ambient
+ * `CONTENTFUL_*` / `EDS_HOST` env vars. Env vars are still consulted as a
+ * fallback when the field on disk is missing or empty — this preserves
+ * back-compat for CI / scripts that only export env and never call setup.
+ *
+ * The pre-INTEG-4410 order (env-first) silently shadowed saved values, so
+ * operators who saved a different space via setup kept seeing the env one
+ * pre-filled in the wizard. The saved value now wins; the env fallback only
+ * fires when the on-disk field is empty.
+ */
 export declare function readExperiencesCredentials(): Promise<ExperiencesCredentials>;
 export declare function writeExperiencesCredentials(creds: ExperiencesCredentials): Promise<void>;
 export declare function experiencesCredentialsPath(): string;

package/dist/src/credentials-store.js

@@ -4,21 +4,37 @@ import { homedir } from 'node:os';
 import { toConfiguredHost } from './host-utils.js';
 const CREDENTIALS_DIR = join(homedir(), '.config', 'experiences');
 const CREDENTIALS_PATH = join(CREDENTIALS_DIR, 'credentials.json');
+/**
+ * Read persisted Contentful credentials.
+ *
+ * Precedence (INTEG-4410): what the operator saved on disk via
+ * `experiences setup` or the wizard's credentials step wins over ambient
+ * `CONTENTFUL_*` / `EDS_HOST` env vars. Env vars are still consulted as a
+ * fallback when the field on disk is missing or empty — this preserves
+ * back-compat for CI / scripts that only export env and never call setup.
+ *
+ * The pre-INTEG-4410 order (env-first) silently shadowed saved values, so
+ * operators who saved a different space via setup kept seeing the env one
+ * pre-filled in the wizard. The saved value now wins; the env fallback only
+ * fires when the on-disk field is empty.
+ */
 export async function readExperiencesCredentials() {
     try {
         const raw = await readFile(CREDENTIALS_PATH, 'utf8');
         const parsed = JSON.parse(raw);
-        const host = toConfiguredHost(process.env['EDS_HOST'] ?? parsed.host);
+        // Disk value wins when non-empty; env is the fallback.
+        const host = toConfiguredHost(parsed.host || process.env['EDS_HOST']);
         return {
-            spaceId: process.env['CONTENTFUL_SPACE_ID'] ?? parsed.spaceId ?? '',
-            environmentId: process.env['CONTENTFUL_ENVIRONMENT_ID'] ?? parsed.environmentId ?? '',
-            cmaToken: process.env['CONTENTFUL_MANAGEMENT_TOKEN'] ?? parsed.cmaToken ?? '',
+            spaceId: parsed.spaceId || process.env['CONTENTFUL_SPACE_ID'] || '',
+            environmentId: parsed.environmentId || process.env['CONTENTFUL_ENVIRONMENT_ID'] || '',
+            cmaToken: parsed.cmaToken || process.env['CONTENTFUL_MANAGEMENT_TOKEN'] || '',
             ...(host ? { host } : {}),
             ...(parsed.agent ? { agent: parsed.agent } : {}),
             ...(parsed.agentModel ? { agentModel: parsed.agentModel } : {}),
             ...(parsed.selectPromptPath ? { selectPromptPath: parsed.selectPromptPath } : {}),
             ...(parsed.generatePromptPath ? { generatePromptPath: parsed.generatePromptPath } : {}),
             ...(typeof parsed.autoFilter === 'boolean' ? { autoFilter: parsed.autoFilter } : {}),
+            ...(typeof parsed.debug === 'boolean' ? { debug: parsed.debug } : {}),
         };
     }
     catch {
@@ -32,7 +48,7 @@ export async function readExperiencesCredentials() {
     }
 }
 export async function writeExperiencesCredentials(creds) {
-    const { host: _host, agent, agentModel, selectPromptPath, generatePromptPath, autoFilter, ...rest } = creds;
+    const { host: _host, agent, agentModel, selectPromptPath, generatePromptPath, autoFilter, debug, ...rest } = creds;
     const host = toConfiguredHost(creds.host);
     await mkdir(CREDENTIALS_DIR, { recursive: true });
     await writeFile(CREDENTIALS_PATH, JSON.stringify({
@@ -43,6 +59,7 @@ export async function writeExperiencesCredentials(creds) {
         ...(selectPromptPath ? { selectPromptPath } : {}),
         ...(generatePromptPath ? { generatePromptPath } : {}),
         ...(typeof autoFilter === 'boolean' ? { autoFilter } : {}),
+        ...(typeof debug === 'boolean' ? { debug } : {}),
     }, null, 2) + '\n', { mode: 0o600 });
 }
 export function experiencesCredentialsPath() {

package/dist/src/generate/agent-runner.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { getDebugLogger } from '../lib/debug-logger.js';
 const VALID_SELECT_TOOL_NAMES = new Set(['select_component', 'reject_component']);
 export function parseSelectToolCallLines(stdout) {
     const calls = [];
@@ -218,6 +219,10 @@ const DEFAULT_MODELS = {
     cursor: 'claude-3-5-haiku-20241022',
 };
 export function resolveBinary(agent) {
+    const envKey = `EDS_AGENT_BINARY_${agent.toUpperCase()}`;
+    const override = process.env[envKey];
+    if (override && override.trim())
+        return override.trim();
     return AGENT_BINARIES[agent];
 }
 function buildArgs(agent, prompt, model) {
@@ -239,6 +244,17 @@ export async function runAgent(options) {
     const { agent, prompt, interactive, timeoutMs, model, onOutput } = options;
     const binary = resolveBinary(agent);
     const args = buildArgs(agent, prompt, model);
+    const debug = getDebugLogger();
+    const startedAt = Date.now();
+    debug.event('agent', 'run.start', {
+        agent,
+        binary,
+        model,
+        interactive,
+        timeoutMs,
+        promptLen: prompt.length,
+        promptHead: prompt.slice(0, 500),
+    });
     return new Promise((resolve) => {
         const child = spawn(binary, args, {
             stdio: interactive ? 'inherit' : ['pipe', 'pipe', 'pipe'],
@@ -265,12 +281,24 @@ export async function runAgent(options) {
         }
         child.on('close', (code, signal) => {
             clearTimeout(timer);
-            resolve({
+            const result = {
                 exitCode: signal ? 1 : (code ?? 1),
                 stdout,
                 stderr,
                 timedOut,
+            };
+            debug.event('agent', 'run.end', {
+                agent,
+                model,
+                durationMs: Date.now() - startedAt,
+                exitCode: result.exitCode,
+                signal,
+                timedOut,
+                stdoutLen: stdout.length,
+                stderrLen: stderr.length,
+                stderrTail: stderr.slice(-1000),
             });
+            resolve(result);
         });
     });
 }
@@ -278,12 +306,19 @@ export async function checkAgentAuth(agent) {
     if (agent !== 'claude')
         return 'ok';
     const binary = resolveBinary(agent);
-    // Verify the binary exists first
-    const whichResult = await new Promise((resolve) => {
+    // Verify the binary exists first. When `binary` is an absolute path (e.g.
+    // set via EDS_AGENT_BINARY_CLAUDE=/opt/custom/claude), `which` on some
+    // shells doesn't resolve it — check the filesystem directly for absolute
+    // paths, and fall back to `which` for bare names on $PATH.
+    const binaryExists = await new Promise((resolve) => {
+        if (binary.startsWith('/')) {
+            import('node:fs/promises').then((fs) => fs.access(binary).then(() => resolve(true), () => resolve(false)));
+            return;
+        }
         const child = spawn('which', [binary], { stdio: 'ignore' });
-        child.on('close', (code) => resolve(code ?? 1));
+        child.on('close', (code) => resolve(code === 0));
     });
-    if (whichResult !== 0)
+    if (!binaryExists)
         return 'not-found';
     // Use `claude auth status` — fast, no API call, works regardless of which
     // auth provider (direct, Bedrock, Vertex) or whether AWS_PROFILE is set.

package/dist/src/generate/command.js

@@ -496,7 +496,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
                         await waitUntilExit();
                     }
                     else {
-                        process.stdout.write(`generate complete\nskill: ${skill}\nagent: ${agent}\nsession: ${sessionId ?? ''}\n`);
+                        process.stdout.write(`generate complete\nskill: ${skill}\nagent: ${agent}\nsession=${sessionId ?? ''}\n`);
                         process.exit(0);
                     }
                     return;
@@ -563,7 +563,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
         await waitUntilExit();
     }
     else {
-        process.stdout.write(`generate complete\nskill: ${skill}\nagent: ${agent}\nsession: ${sessionId ?? ''}\n`);
+        process.stdout.write(`generate complete\nskill: ${skill}\nagent: ${agent}\nsession=${sessionId ?? ''}\n`);
         process.exit(0);
     }
 }

package/dist/src/import/auto-filter-resolve.d.ts

@@ -1,12 +1,3 @@
-/**
- * Resolve the effective auto-filter setting from a CLI flag plus the persisted
- * config preference.
- *
- * Precedence (highest first):
- *   1. CLI flag (`--auto-filter` or `--no-auto-filter`) — wins when set
- *   2. Config (`credentials.json` `autoFilter` field) — used when flag absent
- *   3. Default ON — when neither is set
- */
 export declare function resolveAutoFilter(opts: {
     autoFilter?: boolean;
 }, configAutoFilter?: boolean): boolean;

package/dist/src/import/auto-filter-resolve.js

@@ -7,10 +7,10 @@
  *   2. Config (`credentials.json` `autoFilter` field) — used when flag absent
  *   3. Default ON — when neither is set
  */
+import { getDebugLogger } from '../lib/debug-logger.js';
 export function resolveAutoFilter(opts, configAutoFilter) {
-    if (opts.autoFilter !== undefined)
-        return opts.autoFilter;
-    if (configAutoFilter !== undefined)
-        return configAutoFilter;
-    return true;
+    const source = opts.autoFilter !== undefined ? 'flag' : configAutoFilter !== undefined ? 'config' : 'default';
+    const value = opts.autoFilter ?? configAutoFilter ?? true;
+    getDebugLogger().event('filter', 'auto-filter.resolve', { source, value });
+    return value;
 }

package/dist/src/import/command.js

@@ -5,8 +5,10 @@ import { resolveAgent, resolveModel } from './agent-model-resolve.js';
 import { readExperiencesCredentials } from '../credentials-store.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../host-utils.js';
 import { replayRun, modifyRun } from '../runs/replay-helpers.js';
+import { pickerPushRun } from '../runs/push-launcher.js';
 import { resolvePromptFlags } from './print-prompt.js';
 import { shouldShowRunPicker } from '../runs/run-picker-mount.js';
+import { dispatchPickerSelection } from './picker-dispatch.js';
 export function registerImportCommand(program) {
     program
         .command('import')
@@ -220,15 +222,20 @@ export function registerImportCommand(program) {
                 isTTY: !!process.stdin.isTTY,
             });
             let pickerSelection = null;
+            // Ink `unmount` handle captured after `render(...)` below so the
+            // picker callback can tear down the wizard cleanly. Prior to this
+            // fix the callback did `setImmediate(() => process.exit(0))`, which
+            // killed the process before `dispatchPickerSelection` could run.
+            let unmountInk = null;
             const pickerProps = {};
             if (pickerDecision.shouldShow) {
                 pickerProps.initialRuns = pickerDecision.runs;
                 pickerProps.onRunPicked = (selection) => {
                     pickerSelection = selection;
-                    setImmediate(() => process.exit(0));
+                    unmountInk?.();
                 };
             }
-            const { waitUntilExit } = render(createElement(WizardApp, {
+            const { waitUntilExit, unmount } = render(createElement(WizardApp, {
                 initialSpaceId: creds.spaceId,
                 initialEnvironmentId: creds.environmentId || 'master',
                 initialCmaToken: creds.cmaToken,
@@ -250,43 +257,24 @@ export function registerImportCommand(program) {
                 ...(opts.rawTokens ? { initialRawTokensPath: resolve(opts.rawTokens) } : {}),
                 ...pickerProps,
             }));
-            try {
-                await waitUntilExit();
-            }
-            catch {
-                /* Ink throws on process.exit; swallow so picker dispatch can run. */
-            }
+            unmountInk = unmount;
+            await waitUntilExit();
             // ── Picker dispatch ─────────────────────────────────────────────
-            // If the operator picked a run, route into the existing entry
-            // points so credential resolution and mutex checks stay in one
-            // place. The --modify path resolves the run record via
-            // resolveRunTarget and threads its session IDs through
-            // launchModifyWizard (see runs/replay-helpers.ts).
+            // If the operator picked a run, route into replayRun / modifyRun.
+            // dispatchPickerSelection lives in ./picker-dispatch.ts so this
+            // decision is testable without an Ink runtime.
             if (pickerSelection) {
-                const sel = pickerSelection;
-                if (sel.action === 'push' && sel.runId) {
-                    await replayRun({
-                        runIdOrPath: sel.runId,
-                        ...(opts.spaceId ? { spaceId: opts.spaceId } : {}),
-                        ...(opts.environmentId ? { environmentId: opts.environmentId } : {}),
-                        ...(opts.cmaToken ? { cmaToken: opts.cmaToken } : {}),
-                        ...(opts.host ? { host: opts.host } : {}),
-                        interactive: !!process.stdout.isTTY,
-                        ...(opts.force ? { force: true } : {}),
-                    });
-                    return;
-                }
-                if (sel.action === 'modify' && sel.runId) {
-                    await modifyRun({
-                        runIdOrPath: sel.runId,
-                        ...(opts.outDir ? { outDir: opts.outDir } : {}),
-                        ...(opts.overwrite ? { overwrite: true } : {}),
-                        ...(opts.saveAsNew ? { saveAsNew: true } : {}),
-                        ...(opts.force ? { force: true } : {}),
-                    });
-                    return;
-                }
-                // action === 'new' falls through — the wizard already advanced.
+                await dispatchPickerSelection(pickerSelection, {
+                    ...(opts.spaceId ? { spaceId: opts.spaceId } : {}),
+                    ...(opts.environmentId ? { environmentId: opts.environmentId } : {}),
+                    ...(opts.cmaToken ? { cmaToken: opts.cmaToken } : {}),
+                    ...(opts.host ? { host: opts.host } : {}),
+                    interactive: !!process.stdout.isTTY,
+                    ...(opts.outDir ? { outDir: opts.outDir } : {}),
+                    ...(opts.overwrite ? { overwrite: true } : {}),
+                    ...(opts.saveAsNew ? { saveAsNew: true } : {}),
+                    ...(opts.force ? { force: true } : {}),
+                }, { replayRun, modifyRun, pickerPushRun });
             }
             return;
         }

package/dist/src/import/orchestrator.js

@@ -5,13 +5,17 @@ import { execFile } from 'node:child_process';
 import { openPipelineDb, getOrCreateSession, createStep, updateStep, findLatestSessionForCommand, } from '../session/db.js';
 import { PREVIEW_ERROR_PREFIX, VALIDATION_FAILED_CODE, parsePreviewValidationErrors } from '../apply/api-client.js';
 import { buildPostPushUrl } from '../lib/contentful-urls.js';
+import { getDebugLogger, debugEnvForSubprocess } from '../lib/debug-logger.js';
 function findCliPath() {
     return join(fileURLToPath(import.meta.url), '..', '..', '..', '..', 'bin', 'cli.js');
 }
 async function runStep(args, cliPath, env = {}, streamStderr = false) {
+    const debug = getDebugLogger();
+    const startedAt = Date.now();
+    debug.event('import', 'subprocess.spawn', { cliPath, args });
     return new Promise((res) => {
         const child = execFile('node', [cliPath, ...args], {
-            env: { ...process.env, ...env },
+            env: debugEnvForSubprocess({ ...process.env, ...env }),
         });
         let stdout = '';
         let stderr = '';
@@ -25,7 +29,16 @@ async function runStep(args, cliPath, env = {}, streamStderr = false) {
                 process.stderr.write(text);
         });
         child.on('close', (code) => {
-            res({ exitCode: code ?? 0, stdout, stderr });
+            const exitCode = code ?? 0;
+            debug.event('import', 'subprocess.exit', {
+                args,
+                exitCode,
+                durationMs: Date.now() - startedAt,
+                stdoutLen: stdout.length,
+                stderrLen: stderr.length,
+                stderrTail: stderr.slice(-1000),
+            });
+            res({ exitCode, stdout, stderr });
         });
     });
 }

package/dist/src/import/picker-dispatch.d.ts

@@ -0,0 +1,26 @@
+import type { RunPickerSelection } from '../runs/run-picker.js';
+import type { replayRun as replayRunFn, modifyRun as modifyRunFn } from '../runs/replay-helpers.js';
+import type { pickerPushRun as pickerPushRunFn } from '../runs/push-launcher.js';
+export type PickerDispatchOptions = {
+    spaceId?: string;
+    environmentId?: string;
+    cmaToken?: string;
+    host?: string;
+    interactive?: boolean;
+    outDir?: string;
+    overwrite?: boolean;
+    saveAsNew?: boolean;
+    force?: boolean;
+};
+export type PickerDispatchDeps = {
+    replayRun: typeof replayRunFn;
+    modifyRun: typeof modifyRunFn;
+    /**
+     * Interactive picker-Push launcher — mounts the wizard so the operator sees
+     * preview + push progress + view URL rather than a single-line summary.
+     * Optional so existing test fixtures that only stub {replayRun, modifyRun}
+     * still type-check; when omitted, picker-Push falls back to replayRun.
+     */
+    pickerPushRun?: typeof pickerPushRunFn;
+};
+export declare function dispatchPickerSelection(selection: RunPickerSelection, opts: PickerDispatchOptions, deps: PickerDispatchDeps): Promise<void>;

package/dist/src/import/picker-dispatch.js

@@ -0,0 +1,44 @@
+// Route a resolved RunPickerSelection into replayRun / modifyRun / picker-push.
+// Extracted from command.ts so the dispatch decision is testable without an
+// Ink runtime and so the picker callback in command.ts is a simple
+// state-capture (no process.exit shenanigans that would kill the process
+// before dispatch runs).
+export async function dispatchPickerSelection(selection, opts, deps) {
+    if (selection.action === 'push' && selection.runId) {
+        // Interactive TTY → mount the wizard's preview + push UX. Non-interactive
+        // (CI / scripted / non-TTY) → keep the headless shell-out via replayRun
+        // that `experiences import --push-from-run <id>` relies on.
+        if (opts.interactive !== false && deps.pickerPushRun) {
+            await deps.pickerPushRun({
+                runIdOrPath: selection.runId,
+                ...(opts.spaceId ? { spaceId: opts.spaceId } : {}),
+                ...(opts.environmentId ? { environmentId: opts.environmentId } : {}),
+                ...(opts.cmaToken ? { cmaToken: opts.cmaToken } : {}),
+                ...(opts.host ? { host: opts.host } : {}),
+                ...(opts.force ? { force: true } : {}),
+            });
+            return;
+        }
+        await deps.replayRun({
+            runIdOrPath: selection.runId,
+            ...(opts.spaceId ? { spaceId: opts.spaceId } : {}),
+            ...(opts.environmentId ? { environmentId: opts.environmentId } : {}),
+            ...(opts.cmaToken ? { cmaToken: opts.cmaToken } : {}),
+            ...(opts.host ? { host: opts.host } : {}),
+            ...(opts.interactive !== undefined ? { interactive: opts.interactive } : {}),
+            ...(opts.force ? { force: true } : {}),
+        });
+        return;
+    }
+    if (selection.action === 'modify' && selection.runId) {
+        await deps.modifyRun({
+            runIdOrPath: selection.runId,
+            ...(opts.outDir ? { outDir: opts.outDir } : {}),
+            ...(opts.overwrite ? { overwrite: true } : {}),
+            ...(opts.saveAsNew ? { saveAsNew: true } : {}),
+            ...(opts.force ? { force: true } : {}),
+        });
+        return;
+    }
+    // action === 'new' → no-op; the wizard already advanced past the picker.
+}

package/dist/src/import/tui/WizardApp.d.ts

@@ -99,13 +99,19 @@ export type WizardAppProps = {
      * would never re-emit `tokens.json` for the modified save path.
      */
     seedTokenSessionId?: string;
+    /**
+     * Push-from-picker entry: overrides `state.tokensPath` so runPreview can
+     * read the run record's saved tokens.json without waiting for the wizard
+     * to re-emit it (push-from-picker skips the save flow entirely).
+     */
+    seedTokensPath?: string;
     /**
      * Modify-entry: overrides the wizard's initial step. When set, the wizard
      * bypasses its normal welcome/token-input bootstrap. Currently only
      * `'final-review'` is plumbed end-to-end; `'scope-gate'` is accepted for
      * future use but falls through to standard behavior.
      */
-    initialStep?: 'scope-gate' | 'final-review';
+    initialStep?: 'scope-gate' | 'final-review' | 'push-from-picker';
     /**
      * Headless raw-token source path. When set (and the modify-entry props
      * are not), the wizard seeds `state.rawTokensPath` and lands directly on
@@ -125,4 +131,4 @@ export type WizardAppProps = {
     initialRuns?: RunRecord[];
     onRunPicked?: (selection: RunPickerSelection) => void;
 };
-export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope, noCache, autoFilter, livePreview, noPush, noSave, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, initialStep, initialRawTokensPath, initialRuns, onRunPicked, }?: WizardAppProps): React.ReactElement;
+export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope, noCache, autoFilter, livePreview, noPush, noSave, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, }?: WizardAppProps): React.ReactElement;