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

package/dist/src/import/tui/WizardApp.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { execFile, spawn } from 'node:child_process';
 import { mkdir } from 'node:fs/promises';
 import { buildRunTeaserLine } from './run-teaser.js';
+import { getDebugLogger } from '../../lib/debug-logger.js';
 import { PathPrompt } from '../../runs/path-prompt.js';
 import { RunPicker } from '../../runs/run-picker.js';
 import { SaveConflictGate } from '../../runs/save-conflict.js';
@@ -28,7 +29,6 @@ import { ErrorStep } from './steps/ErrorStep.js';
 import { TokenInputStep } from './steps/TokenInputStep.js';
 import { PreviewValidationErrorStep } from './steps/PreviewValidationErrorStep.js';
 import { PushingStep } from './steps/PushingStep.js';
-import { computePushExpected } from './push-progress.js';
 import { nextStateAfterPrint } from './run-print-files-helpers.js';
 import { PushDecisionGateStep } from './steps/PushDecisionGateStep.js';
 import { chooseGateAction } from './push-decision-gate-helpers.js';
@@ -37,6 +37,7 @@ import { handlePreview422, applySkipValidationErrors, clearedValidationErrorStat
 import { parseGenerateStderrChunk } from './wizard-generate-progress.js';
 import { spawnGenerateChild } from './spawn-generate.js';
 import { readTokensFromPath, hasBreakingChangesWithImpact } from '../../apply/manifest.js';
+import { isEmptyPreview } from '../../apply/preview-utils.js';
 import { buildManifest } from '@contentful/experience-design-system-types';
 import { openPipelineDb, loadCDFComponents, loadScopeComponents, seedCDFFromPreviewResponse, seedDefaultsFromChangedItems, backfillUnclassifiedProps, } from '../../session/db.js';
 import { ScopeGateHost } from './scope-gate-host.js';
@@ -147,8 +148,10 @@ const WIZARD_LOG = join(tmpdir(), 'experiences-import-wizard.log');
 function logStep(entry) {
     const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n';
     appendFileSync(WIZARD_LOG, line);
+    // Tee into the unified debug log when enabled — cheap no-op otherwise.
+    getDebugLogger().event('wizard', 'step', entry);
 }
-export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope = false, noCache = false, autoFilter = true, livePreview = true, noPush = false, noSave = false, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, initialStep, initialRawTokensPath, initialRuns, onRunPicked, } = {}) {
+export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope = false, noCache = false, autoFilter = true, livePreview = true, noPush = false, noSave = false, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, } = {}) {
     const defaultConfiguredHost = toConfiguredHost(host || process.env['EDS_HOST']) ?? DEFAULT_CONFIGURED_HOST;
     const resolveWizardHost = (hostValue) => hostValue || defaultConfiguredHost;
     const { stdout } = useStdout();
@@ -182,22 +185,31 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     // GenerateReviewStep loads its data off `state.extractSessionId`, so all
     // we need to do here is seed the IDs and the step.
     const modifyEntryReady = !!seedExtractSessionId && initialStep === 'final-review';
+    // Push-from-picker entry: the run-picker's Push action mounts the wizard
+    // with seeded session IDs and `initialStep: 'push-from-picker'` so the
+    // operator sees the same preview + push UX as a fresh import. Skips
+    // welcome, token-input, scope-gate, final-review, and push-decision-gate;
+    // an effect below dispatches `runPreview` on mount which drives
+    // previewing → pushing → done.
+    const pushFromPickerReady = !!seedExtractSessionId && initialStep === 'push-from-picker';
     // Headless raw-tokens entry: when the operator passed `--raw-tokens <path>`
     // the CLI seeds this prop. Skip welcome + token-input and land on the
     // `generating-tokens` step which already drives the token-classification
     // subprocess off `state.rawTokensPath`. Modify-entry wins if both are set.
-    const rawTokensEntryReady = !modifyEntryReady && !!initialRawTokensPath;
+    const rawTokensEntryReady = !modifyEntryReady && !pushFromPickerReady && !!initialRawTokensPath;
     const initialStepResolved = modifyEntryReady
         ? 'final-review'
-        : rawTokensEntryReady
-            ? 'generating-tokens'
-            : initialProjectPath
-                ? 'token-input'
-                : 'welcome';
+        : pushFromPickerReady
+            ? 'push-from-picker'
+            : rawTokensEntryReady
+                ? 'generating-tokens'
+                : initialProjectPath
+                    ? 'token-input'
+                    : 'welcome';
     const initialOutDir = initialProjectPath ? join(resolve(initialProjectPath), '.contentful') : '';
-    const initialTokensPath = modifyEntryReady && initialOutDir ? join(initialOutDir, 'tokens.json') : '';
+    const initialTokensPath = (modifyEntryReady || pushFromPickerReady) && initialOutDir ? join(initialOutDir, 'tokens.json') : '';
     const [state, setState] = useState({
-        step: modifyEntryReady || rawTokensEntryReady
+        step: modifyEntryReady || rawTokensEntryReady || pushFromPickerReady
             ? initialStepResolved
             : initialRuns && initialRuns.length > 0
                 ? 'run-picker'
@@ -207,7 +219,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         projectPath: initialProjectPath ?? '',
         outDir: initialOutDir,
         rawTokensPath: rawTokensEntryReady ? initialRawTokensPath : '',
-        tokensPath: initialTokensPath,
+        tokensPath: seedTokensPath ?? initialTokensPath,
         tokenSourceChanged: null,
         skipComponents: false,
         tokenSessionId: seedTokenSessionId ?? null,
@@ -231,7 +243,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         serverPreview: null,
         manifest: null,
         pushProgress: null,
-        pushExpected: null,
         pushResult: {
             componentTypes: { created: 0, updated: 0, removed: 0, failed: 0 },
             designTokens: { created: 0, updated: 0, removed: 0, failed: 0 },
@@ -251,6 +262,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         generatePrefetchError: null,
         credentialsSkipped: false,
         lastRunId: null,
+        finalizeErrorBanner: null,
     });
     useEffect(() => {
         sessionRef.current = {
@@ -357,7 +369,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
             return;
         }
-        const sessionMatch = /^session:\s*(.+)$/m.exec(result.stdout);
+        const sessionMatch = /^session=(.+)$/m.exec(result.stdout);
         const tokenSessionId = sessionMatch ? sessionMatch[1].trim() : null;
         const tokensPath = join(outDir, 'tokens.json');
         const printArgs = ['print', 'tokens', '--out', tokensPath];
@@ -906,7 +918,27 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     db.close();
                 }
             }
-            update({ step: 'preview-gate', serverPreview: preview, manifest, ...clearedValidationErrorState() });
+            // INTEG-4411 refined: preview-aware finalize guard. If the resulting
+            // push would be a pure no-op across every diff bucket, don't send an
+            // empty manifest to EDSI — route back to `final-review` with an inline
+            // banner. Accepted components, rejections that remove server-side
+            // components, and token-only diffs all keep this branch from firing.
+            if (isEmptyPreview(preview)) {
+                update({
+                    step: 'final-review',
+                    finalizeErrorBanner: 'Nothing to push — accept a component, reject a component that exists in Contentful, or quit.',
+                    serverPreview: preview,
+                    ...clearedValidationErrorState(),
+                });
+                return;
+            }
+            update({
+                step: 'preview-gate',
+                serverPreview: preview,
+                manifest,
+                finalizeErrorBanner: null,
+                ...clearedValidationErrorState(),
+            });
         }
         catch (e) {
             if (e instanceof ApiError) {
@@ -1002,8 +1034,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 return;
             }
         }
-        const pushExpected = preview ? computePushExpected(preview) : null;
-        update({ step: 'pushing', pushExpected, pushProgress: null });
+        update({ step: 'pushing', pushProgress: null });
         try {
             const resolvedHost = resolveWizardHost(host);
             const client = new ImportApiClient({
@@ -1303,6 +1334,22 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             })();
         }
     }, [state.step]); // intentional: only re-run when step changes
+    // Push-from-picker entry: on mount, dispatch runPreview to jump through
+    // previewing → preview-gate → pushing → done. We DON'T wait for the
+    // operator to interact with any pre-preview screen; the run-picker Push
+    // action is a "click Push and watch it happen" flow. `preview-gate` still
+    // renders after runPreview resolves — that's the diff-review screen where
+    // the operator can confirm/quit/edit. We route straight past
+    // push-decision-gate (which is for save-vs-push decisions on a fresh run).
+    const pushFromPickerDispatched = useRef(false);
+    useEffect(() => {
+        if (state.step !== 'push-from-picker')
+            return;
+        if (pushFromPickerDispatched.current)
+            return;
+        pushFromPickerDispatched.current = true;
+        void runPreview(state.extractSessionId, state.tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
+    }, [state.step]);
     // ── Render ────────────────────────────────────────────────────────────────────────────
     const noQuitSteps = [
         'run-picker',
@@ -1313,6 +1360,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         'generating',
         'printing',
         'previewing',
+        'push-from-picker',
         'pushing',
     ];
     const hints = noQuitSteps.includes(state.step) ? [] : [{ key: 'q', label: 'quit' }];
@@ -1454,8 +1502,16 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 return (_jsx(RunningStep, { stepNumber: stepNum, totalSteps: totalSteps, title: "Generating definitions", description: `${formatAcceptanceSummary({ accepted: state.acceptedCount, autoRejected: state.autoRejectedCount })} ${state.agent} is mapping your TypeScript types to Contentful's CDF format.${hasTokens ? ' Using your design tokens for prop resolution.' : ''}`, detail: progressDetail }));
             }
             case 'final-review': {
-                return (_jsx(FinalReviewHost, { extractSessionId: state.extractSessionId, generatedCount: state.generatedCount, autoAccept: autoAcceptScope, livePreview: livePreview, spaceId: state.spaceId, environmentId: state.environmentId, cmaToken: state.cmaToken, host: state.host, tokensPath: state.tokensPath, onFinalize: (accepted, rejected, unresolved) => {
+                return (_jsx(FinalReviewHost, { extractSessionId: state.extractSessionId, generatedCount: state.generatedCount, autoAccept: autoAcceptScope, livePreview: livePreview, spaceId: state.spaceId, environmentId: state.environmentId, cmaToken: state.cmaToken, host: state.host, tokensPath: state.tokensPath, initialFinalizeError: state.finalizeErrorBanner, onFinalize: (accepted, rejected, unresolved) => {
                         process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}  Unresolved: ${unresolved}\n`);
+                        // INTEG-4411 refined: no `accepted === 0` up-front block here.
+                        // A zero-accepted finalize can still be a valid push when the
+                        // operator explicitly rejected component(s) that exist server-
+                        // side (→ REMOVALS) or when tokens carry a diff. The load-
+                        // bearing no-op check consults the preview response inside
+                        // `runPreview` below (see `isEmptyPreview` branch) and routes
+                        // back to `final-review` with `finalizeErrorBanner` set when
+                        // the diff is truly empty.
                         if (noPush) {
                             update({ generatedAcceptedCount: accepted });
                             void startSaveFlow();
@@ -1507,7 +1563,17 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             case 'credentials':
                 return (_jsx(CredentialsStep, { initialSpaceId: state.spaceId, initialEnvironmentId: state.environmentId, initialCmaToken: state.cmaToken, initialHost: state.host, error: state.credentialsError || undefined, validating: state.credentialsValidating, generatePrefetchStatus: state.generatePrefetchStatus, generatePrefetchError: state.generatePrefetchError, onConfirm: (spaceId, environmentId, cmaToken, host) => {
                         void confirmCredentials(spaceId, environmentId, cmaToken, host);
-                    }, onContinue: advanceWithCredentials, onRetryPrefetch: state.generatePrefetchStatus === 'failed' && sessionRef.current.extractSessionId
+                    }, 
+                    // INTEG-4410: unify the unchanged-form path with the changed-form
+                    // path so credentials are ALWAYS persisted to disk on submit.
+                    // The pre-fix wiring routed `onContinue` at
+                    // `advanceWithCredentials`, which only mutated state — so on
+                    // `--modify` (where the wizard seeds `run.pushedTo` into the
+                    // form, not disk) an operator pressing Enter never wrote to
+                    // ~/.config/experiences/credentials.json and disk stayed stale.
+                    onContinue: (spaceId, environmentId, cmaToken, host) => {
+                        void confirmCredentials(spaceId, environmentId, cmaToken, host);
+                    }, onRetryPrefetch: state.generatePrefetchStatus === 'failed' && sessionRef.current.extractSessionId
                         ? () => {
                             const sid = sessionRef.current.extractSessionId;
                             void startGeneratePrefetch(sid, state.tokensPath);
@@ -1535,6 +1601,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             // value is kept in the union for back-compat with existing imports/tests
             // but should never actually be set — `validateCredentials` keeps the
             // step on 'credentials' and toggles `credentialsValidating` instead.
+            case 'push-from-picker':
             case 'previewing':
                 return (_jsx(RunningStep, { stepNumber: totalSteps, totalSteps: totalSteps, title: "Computing diff", description: "Computing diff against your Contentful space..." }));
             case 'preview-gate':
@@ -1546,7 +1613,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                         void startSaveFlow();
                     }, onQuit: () => process.exit(0) }));
             case 'pushing':
-                return (_jsx(PushingStep, { stepNumber: totalSteps, totalSteps: totalSteps, expected: state.pushExpected, progress: state.pushProgress }));
+                return _jsx(PushingStep, { stepNumber: totalSteps, totalSteps: totalSteps, progress: state.pushProgress });
             case 'path-prompt':
                 return (_jsx(PathPrompt, { defaultPath: state.outDir, onSubmit: (submitted) => {
                         void (async () => {

package/dist/src/import/tui/final-review-host.d.ts

@@ -11,5 +11,12 @@ export type FinalReviewHostProps = {
     cmaToken?: string;
     host?: string;
     tokensPath?: string;
+    /**
+     * INTEG-4411 refined: message displayed as an inline banner when the wizard
+     * routes back here after the preview API returned an empty diff (pure
+     * no-op push). Cleared on the next `a` / `A` keystroke inside
+     * GenerateReviewStep.
+     */
+    initialFinalizeError?: string | null;
 };
-export declare function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, }: FinalReviewHostProps): React.ReactElement;
+export declare function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: FinalReviewHostProps): React.ReactElement;

package/dist/src/import/tui/final-review-host.js

@@ -2,14 +2,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import React from 'react';
 import { GenerateReviewStep } from './steps/GenerateReviewStep.js';
-export function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, }) {
+export function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }) {
     if (!extractSessionId) {
         return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: "red", children: "Error: no session ID \u2014 cannot load generated definitions." }) }));
     }
     if (autoAccept) {
         return _jsx(FinalReviewAutoAccept, { generatedCount: generatedCount, onFinalize: onFinalize });
     }
-    return (_jsx(GenerateReviewStep, { extractSessionId: extractSessionId, onFinalize: onFinalize, onQuit: onQuit, livePreview: livePreview, spaceId: spaceId, environmentId: environmentId, cmaToken: cmaToken, host: host, tokensPath: tokensPath }));
+    return (_jsx(GenerateReviewStep, { extractSessionId: extractSessionId, onFinalize: onFinalize, onQuit: onQuit, livePreview: livePreview, spaceId: spaceId, environmentId: environmentId, cmaToken: cmaToken, host: host, tokensPath: tokensPath, initialFinalizeError: initialFinalizeError }));
 }
 function FinalReviewAutoAccept({ generatedCount, onFinalize, }) {
     React.useEffect(() => {

package/dist/src/import/tui/push-progress.d.ts

@@ -1,16 +1,3 @@
-import type { ServerPreviewResponse } from '@contentful/experience-design-system-types';
-export type PushExpected = {
-    componentTypes: {
-        create: number;
-        update: number;
-        remove: number;
-    };
-    designTokens: {
-        create: number;
-        update: number;
-        remove: number;
-    };
-};
 export type PushProgress = {
     kind: 'queued';
     operationId: string;
@@ -20,4 +7,3 @@ export type PushProgress = {
     total: number;
     current: string | null;
 } | null;
-export declare function computePushExpected(preview: ServerPreviewResponse): PushExpected;

package/dist/src/import/tui/push-progress.js

@@ -1,14 +1 @@
-export function computePushExpected(preview) {
-    return {
-        componentTypes: {
-            create: preview.components?.new?.length ?? 0,
-            update: preview.components?.changed?.length ?? 0,
-            remove: preview.components?.removed?.length ?? 0,
-        },
-        designTokens: {
-            create: preview.tokens?.new?.length ?? 0,
-            update: preview.tokens?.changed?.length ?? 0,
-            remove: preview.tokens?.removed?.length ?? 0,
-        },
-    };
-}
+export {};

package/dist/src/import/tui/steps/GenerateReviewStep.d.ts

@@ -16,6 +16,13 @@ type GenerateReviewStepProps = {
     cmaToken?: string;
     host?: string;
     tokensPath?: string;
+    /**
+     * INTEG-4411 refined: initial value for the inline `finalizeError` banner.
+     * The wizard sets this when it routes back to `final-review` after the
+     * preview API returned an empty diff (pure no-op push). Cleared on the
+     * next `a` / `A` keystroke.
+     */
+    initialFinalizeError?: string | null;
 };
 /**
  * Sort components for the final-review sidebar so the underlying data array
@@ -31,5 +38,5 @@ export declare function sortComponentsForSidebar<T extends {
     key: string;
     entry: CDFComponentEntry;
 }>(components: T[]): T[];
-export declare function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, }: GenerateReviewStepProps): React.ReactElement;
+export declare function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: GenerateReviewStepProps): React.ReactElement;
 export {};

package/dist/src/import/tui/steps/GenerateReviewStep.js

@@ -35,7 +35,7 @@ export function sortComponentsForSidebar(components) {
 }
 const VISIBLE_COUNT = 20;
 const PANEL_HEIGHT = 22;
-export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview = true, spaceId = '', environmentId = '', cmaToken = '', host = '', tokensPath = '', }) {
+export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview = true, spaceId = '', environmentId = '', cmaToken = '', host = '', tokensPath = '', initialFinalizeError = null, }) {
     const { stdout } = useStdout();
     const terminalWidth = stdout?.columns ?? 80;
     const [components, setComponents] = useState([]);
@@ -51,6 +51,9 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
     const [showJson, setShowJson] = useState(false);
     const [draftValue, setDraftValue] = useState('');
     const [saveError, setSaveError] = useState(null);
+    // INTEG-4411: inline banner shown when the operator tries to finalize
+    // with zero accepted components. Cleared on the next 'a' or 'A' press.
+    const [finalizeError, setFinalizeError] = useState(initialFinalizeError);
     // Feature 1: per-component review metadata (rationale + source location)
     // for the currently-selected component. Reloaded when selection changes.
     const [reviewMetadata, setReviewMetadata] = useState(null);
@@ -192,6 +195,15 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
         // 'generate-rejected' so loadCDFComponents excludes it from the manifest.
         // The operator told us they want accept-to-ship semantics — leaving a
         // component unresolved should NOT silently push it (Pilot-2026-06-24 R2).
+        const acceptedCount = components.filter((c) => c.status === 'accepted').length;
+        // INTEG-4411 refined: DO NOT block on `acceptedCount === 0` up-front.
+        // A push with zero accepted but one or more rejections targeting a
+        // component that exists server-side still produces REMOVALS — a valid
+        // push, not a no-op. Same for token-only diffs. The load-bearing no-op
+        // check lives downstream in WizardApp.runPreview, which consults the
+        // preview response and only blocks when every diff bucket is empty.
+        // We keep the `finalizeError` state so the wizard can route back here
+        // with an inline banner when that downstream check fires.
         const explicitlyRejected = components.filter((c) => c.status === 'rejected').map((c) => c.key);
         const unresolved = components.filter((c) => c.status === 'needs-review').map((c) => c.key);
         const toReject = [...explicitlyRejected, ...unresolved];
@@ -215,7 +227,6 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
                 db.close();
             }
         }
-        const acceptedCount = components.filter((c) => c.status === 'accepted').length;
         onFinalize(acceptedCount, explicitlyRejected.length, unresolved.length);
     };
     const handleEditSave = () => {
@@ -405,6 +416,7 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
         }
         if (input === 'a') {
             updateStatus(selectedIdx, 'accepted');
+            setFinalizeError(null);
             return;
         }
         if (input === 'r') {
@@ -413,6 +425,7 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
         }
         if (input === 'A') {
             setComponents((prev) => prev.map((c) => (c.status === 'needs-review' ? { ...c, status: 'accepted' } : c)));
+            setFinalizeError(null);
             return;
         }
         if (input === 'J') {
@@ -513,7 +526,7 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
                     if (!hasCounts)
                         return null;
                     return (_jsxs(Box, { children: [_jsx(Text, { children: 'Preview: ' }), _jsx(Text, { color: "green", children: `${counts.new} new` }), _jsx(Text, { children: ' · ' }), _jsx(Text, { color: "yellow", children: `${counts.changed} changed` }), _jsx(Text, { children: ' · ' }), _jsx(Text, { dimColor: true, children: `${counts.removed} removed` }), removedComponents.length > 0 && _jsx(Text, { dimColor: true, children: ' ([d] removed list)' }), _jsx(Text, { children: ' · ' }), _jsx(Text, { color: "red", bold: true, children: `${counts.breaking} breaking` })] }));
-                })(), !dialogOpen && emptyCount > 0 && (_jsx(Text, { color: "yellow", children: `⚠ ${emptyCount} component${emptyCount === 1 ? '' : 's'} had no classifiable props — review with care` })), !dialogOpen && (_jsxs(Box, { children: [_jsx(Sidebar, { components: sidebarItems, selectedId: selected?.key ?? null, focused: sidebarFocused, scrollOffset: sidebarScrollOffset, visibleCount: VISIBLE_COUNT, onSelect: (id) => {
+                })(), !dialogOpen && emptyCount > 0 && (_jsx(Text, { color: "yellow", children: `⚠ ${emptyCount} component${emptyCount === 1 ? '' : 's'} had no classifiable props — review with care` })), !dialogOpen && finalizeError && _jsx(Text, { color: "red", children: `⚠ ${finalizeError}` }), !dialogOpen && (_jsxs(Box, { children: [_jsx(Sidebar, { components: sidebarItems, selectedId: selected?.key ?? null, focused: sidebarFocused, scrollOffset: sidebarScrollOffset, visibleCount: VISIBLE_COUNT, onSelect: (id) => {
                             const idx = components.findIndex((c) => c.key === id);
                             if (idx >= 0) {
                                 setSelectedIdx(idx);

package/dist/src/import/tui/steps/PushingStep.d.ts

@@ -1,10 +1,9 @@
 import React from 'react';
-import type { PushExpected, PushProgress } from '../push-progress.js';
+import type { PushProgress } from '../push-progress.js';
 type PushingStepProps = {
     stepNumber: number;
     totalSteps: number;
-    expected: PushExpected | null;
     progress: PushProgress;
 };
-export declare function PushingStep({ stepNumber, totalSteps, expected, progress }: PushingStepProps): React.ReactElement;
+export declare function PushingStep({ stepNumber, totalSteps, progress }: PushingStepProps): React.ReactElement;
 export {};

package/dist/src/import/tui/steps/PushingStep.js

@@ -1,25 +1,8 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { Box, Text } from 'ink';
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const ACTION_LABELS = {
-    create: 'Creating',
-    update: 'Updating',
-    remove: 'Deleting',
-};
-function ActionRow({ label, expectedCount, progress, }) {
-    // Per spec: do NOT fake proportional tallies. Left side stays "?/N" until
-    // terminal status surfaces real per-action counts.
-    const left = progress && progress.kind === 'progress' ? '?' : '?';
-    return (_jsxs(Box, { gap: 1, children: [_jsxs(Text, { children: [" ", label] }), _jsxs(Text, { dimColor: true, children: [left, "/", expectedCount] })] }));
-}
-function EntitySection({ title, counts, progress, }) {
-    const visibleActions = ['create', 'update', 'remove'].filter((k) => counts[k] > 0);
-    if (visibleActions.length === 0)
-        return null;
-    return (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { bold: true, children: title }), visibleActions.map((k) => (_jsx(ActionRow, { label: ACTION_LABELS[k], expectedCount: counts[k], progress: progress }, k)))] }));
-}
-export function PushingStep({ stepNumber, totalSteps, expected, progress }) {
+export function PushingStep({ stepNumber, totalSteps, progress }) {
     const [frame, setFrame] = useState(0);
     const [elapsed, setElapsed] = useState(0);
     useEffect(() => {
@@ -36,5 +19,5 @@ export function PushingStep({ stepNumber, totalSteps, expected, progress }) {
     const operationId = progress && progress.kind === 'queued' ? progress.operationId : null;
     const showGlobal = progress && progress.kind === 'progress';
     const showCurrent = progress && progress.kind === 'progress' && progress.current ? progress.current : null;
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { dimColor: true, children: '─'.repeat(40) }), _jsxs(Box, { gap: 1, children: [_jsxs(Text, { bold: true, children: ["Step ", stepNumber, " of ", totalSteps] }), _jsx(Text, { bold: true, children: "\u2014" }), _jsx(Text, { bold: true, children: "Push to Contentful" })] }), _jsx(Text, { dimColor: true, children: '─'.repeat(40) })] }), _jsx(Text, { children: "Writing component types and design tokens to your Contentful space..." }), operationId && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "Operation:" }), _jsx(Text, { children: operationId })] })), expected && (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(EntitySection, { title: "Component types", counts: expected.componentTypes, progress: progress }), _jsx(EntitySection, { title: "Design tokens", counts: expected.designTokens, progress: progress })] })), showGlobal && progress && progress.kind === 'progress' && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: "cyan", children: SPINNER_FRAMES[frame] }), _jsxs(Text, { dimColor: true, children: [progress.processed, "/", progress.total, " entities"] })] })), showCurrent && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "Now processing:" }), _jsx(Text, { children: showCurrent })] })), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ["Elapsed: ", elapsedStr] }) })] }));
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { dimColor: true, children: '─'.repeat(40) }), _jsxs(Box, { gap: 1, children: [_jsxs(Text, { bold: true, children: ["Step ", stepNumber, " of ", totalSteps] }), _jsx(Text, { bold: true, children: "\u2014" }), _jsx(Text, { bold: true, children: "Push to Contentful" })] }), _jsx(Text, { dimColor: true, children: '─'.repeat(40) })] }), _jsx(Text, { children: "Writing component types and design tokens to your Contentful space..." }), operationId && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "Operation:" }), _jsx(Text, { children: operationId })] })), showGlobal && progress && progress.kind === 'progress' && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: "cyan", children: SPINNER_FRAMES[frame] }), _jsxs(Text, { dimColor: true, children: [progress.processed, "/", progress.total, " entities"] })] })), showCurrent && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "Now processing:" }), _jsx(Text, { children: showCurrent })] })), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, children: ["Elapsed: ", elapsedStr] }) })] }));
 }

package/dist/src/lib/debug-logger.d.ts

@@ -0,0 +1,49 @@
+export type DebugCategory = 'config' | 'agent' | 'apply' | 'import' | 'analyze' | 'filter' | 'session' | 'runs' | 'tui' | 'wizard' | 'setup' | 'output' | 'other';
+export interface DebugLogger {
+    readonly enabled: boolean;
+    readonly path: string | null;
+    event(category: DebugCategory, name: string, payload?: Record<string, unknown>): void;
+}
+export declare function redactForDebug(payload: unknown): unknown;
+export interface InitDebugLoggerOptions {
+    /** Effective on/off decision (flag > env > config, resolved by caller). */
+    enabled: boolean;
+    /** Command name — recorded in the session-open event for filtering. */
+    command?: string;
+    /** Override log root (defaults to ~/.contentful/experience-design-system-cli/debug/). */
+    root?: string;
+}
+/**
+ * Initialize the process-wide debug logger. Safe to call multiple times —
+ * subsequent calls return the existing instance.
+ *
+ * If EDSI_DEBUG_LOG is already set in the environment, this process joins
+ * that log file (used by spawned subprocesses so a whole `experiences import`
+ * flow lands in a single file).
+ */
+export declare function initDebugLogger(opts: InitDebugLoggerOptions): DebugLogger;
+export declare function getDebugLogger(): DebugLogger;
+/** Test-only: reset the singleton. */
+export declare function __resetDebugLoggerForTest(): void;
+/**
+ * Resolve effective debug-mode setting from three sources.
+ *
+ * Precedence (highest first):
+ *   1. `--debug` / `--no-debug` CLI flag
+ *   2. `EDSI_DEBUG` env var (truthy: 1, true, yes, on)
+ *   3. Persisted `debug` field in credentials.json
+ *   4. Default: OFF
+ */
+export declare function resolveDebugMode(opts: {
+    debug?: boolean;
+}, configDebug?: boolean): boolean;
+/**
+ * Emit the bright-green "debug logs at <path>" banner to stderr.
+ * No-op when debug is disabled or stderr is not a TTY-friendly stream.
+ * Callers should invoke this once at start and once at end of the command.
+ */
+export declare function printDebugBanner(logger: DebugLogger, phase: 'start' | 'end'): void;
+/** Directory that contains the current process's debug log, if any. */
+export declare function debugLogPath(): string | null;
+/** Ensure spawned children join the same debug log by including EDSI_DEBUG_LOG in their env. */
+export declare function debugEnvForSubprocess(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;