@contentful/experience-design-system-cli 2.7.5-dev-build-752dc9c.0 → 2.10.1-dev-build-90df010.0

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

@@ -18,7 +18,9 @@ import { DoneStep } from './steps/DoneStep.js';
 import { ErrorStep } from './steps/ErrorStep.js';
 import { TokenInputStep } from './steps/TokenInputStep.js';
 import { GenerateReviewStep } from './steps/GenerateReviewStep.js';
+import { PreviewValidationErrorStep } from './steps/PreviewValidationErrorStep.js';
 import { ImportApiClient, ApiError } from '../../apply/api-client.js';
+import { handlePreview422, applySkipValidationErrors, clearedValidationErrorState } from './wizard-422-helpers.js';
 import { readTokensFromPath, hasBreakingChangesWithImpact } from '../../apply/manifest.js';
 import { buildManifest } from '@contentful/experience-design-system-types';
 import { openPipelineDb, loadCDFComponents, seedCDFFromPreviewResponse, seedDefaultsFromChangedItems, backfillUnclassifiedProps, } from '../../session/db.js';
@@ -29,6 +31,34 @@ import { writeExperiencesCredentials } from '../../credentials-store.js';
 function findCliPath() {
     return join(fileURLToPath(import.meta.url), '..', '..', '..', '..', '..', 'bin', 'cli.js');
 }
+export function buildAnalyzeSelectArgs(opts) {
+    const args = ['analyze', 'select', '--session', opts.sessionId];
+    if (opts.acceptAll) {
+        // The wizard pre-shows validation errors in the analyze-extract TUI before
+        // reaching this gate, so the user has already seen what will be excluded.
+        // Pass --exclude-invalid to bypass the headless fail-loud gate (which is
+        // for CI / scripted callers that need to fail loud) — the wizard surfaces
+        // the auto-rejection via formatAcceptanceSummary on the next screen.
+        args.push('--select-all', '--exclude-invalid');
+    }
+    return args;
+}
+export function formatAcceptanceSummary(opts) {
+    const acceptedClause = `${opts.accepted} component${opts.accepted === 1 ? '' : 's'} accepted`;
+    if (opts.autoRejected === 0)
+        return `${acceptedClause}.`;
+    return `${acceptedClause}, ${opts.autoRejected} excluded due to validation errors.`;
+}
+export function formatGeneratedSummary(opts) {
+    const generatedClause = `Generated definitions for ${opts.generated} component${opts.generated === 1 ? '' : 's'}.`;
+    const renamedClause = opts.renamedSlots > 0
+        ? ` ${opts.renamedSlots} unnamed slot${opts.renamedSlots === 1 ? '' : 's'} renamed (children / slot_<n>) so the LLM could classify them.`
+        : '';
+    const exclusionClause = opts.autoRejected > 0
+        ? ` ${opts.autoRejected} component${opts.autoRejected === 1 ? '' : 's'} excluded earlier due to validation errors.`
+        : '';
+    return `${generatedClause}${renamedClause}${exclusionClause}`;
+}
 function runCli(args) {
     return new Promise((res) => {
         execFile('node', [findCliPath(), ...args], (error, stdout, stderr) => {
@@ -70,8 +100,10 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         generateSessionId: null,
         extractedCount: 0,
         acceptedCount: 0,
+        autoRejectedCount: 0,
         generatedCount: 0,
         generatedAcceptedCount: 0,
+        renamedSlotsCount: 0,
         generateProgress: null,
         extractProgress: null,
         componentsPath: '',
@@ -91,6 +123,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         errorMessage: '',
         errorAllowCredentialRetry: false,
         authCheckStepNumber: 1,
+        previewValidationErrors: [],
+        previewValidationMissingNames: [],
     });
     useEffect(() => {
         sessionRef.current = {
@@ -195,7 +229,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             child.on('exit', (code) => res({ exitCode: code ?? 0, stdout, stderr }));
         });
         if (result.exitCode !== 0) {
-            update({ step: 'error', errorStep: 'generate tokens', errorMessage: result.stderr.trim() || 'Unknown error' });
+            update({
+                step: 'error',
+                errorStep: 'generate tokens',
+                errorMessage: result.stderr.trim() || 'Unknown error',
+            });
             return;
         }
         const sessionMatch = /^session:\s*(.+)$/m.exec(result.stdout);
@@ -206,7 +244,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             printArgs.push('--session', tokenSessionId);
         const r = await runCli(printArgs);
         if (r.exitCode !== 0) {
-            update({ step: 'error', errorStep: 'print tokens', errorMessage: r.stderr.trim() || 'Unknown error' });
+            update({
+                step: 'error',
+                errorStep: 'print tokens',
+                errorMessage: r.stderr.trim() || 'Unknown error',
+            });
             return;
         }
         update({ step: 'path-validation', tokensPath, tokenSessionId });
@@ -259,7 +301,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             child.on('exit', (code) => res({ exitCode: code ?? 0, stdout, stderr }));
         });
         if (r.exitCode !== 0) {
-            update({ step: 'error', errorStep: 'analyze extract', errorMessage: r.stderr.trim() || 'Unknown error' });
+            update({
+                step: 'error',
+                errorStep: 'analyze extract',
+                errorMessage: r.stderr.trim() || 'Unknown error',
+            });
             return;
         }
         const sessionMatch = /^session=(.+)$/m.exec(r.stdout);
@@ -274,41 +320,57 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
             return;
         }
-        update({ step: 'review-extraction-gate', extractSessionId, extractedCount });
+        update({
+            step: 'review-extraction-gate',
+            extractSessionId,
+            extractedCount,
+        });
     };
     const runAnalyzeSelect = async (sessionId, extractedCount, tokensPath, acceptAll) => {
-        logStep({ fn: 'runAnalyzeSelect:enter', sessionId, extractedCount, acceptAll });
+        logStep({
+            fn: 'runAnalyzeSelect:enter',
+            sessionId,
+            extractedCount,
+            acceptAll,
+        });
         let acceptedCount;
-        if (acceptAll) {
-            logStep({ fn: 'runAnalyzeSelect:acceptAll-skip-spawn' });
-            acceptedCount = extractedCount;
+        if (!acceptAll && state.serverPreview && !process.env['EDS_PREVIEW_ANNOTATIONS']) {
+            process.env['EDS_PREVIEW_ANNOTATIONS'] = JSON.stringify(buildPreviewAnnotations(state.serverPreview));
         }
-        else {
-            if (state.serverPreview && !process.env['EDS_PREVIEW_ANNOTATIONS']) {
-                process.env['EDS_PREVIEW_ANNOTATIONS'] = JSON.stringify(buildPreviewAnnotations(state.serverPreview));
-            }
+        if (!acceptAll) {
             update({ step: 'analyze-select' });
-            const r = await runCliInteractive(['analyze', 'select', '--session', sessionId]);
-            logStep({ fn: 'runAnalyzeSelect:post-spawn', exitCode: r.exitCode });
+        }
+        const args = buildAnalyzeSelectArgs({ sessionId, acceptAll });
+        const r = acceptAll ? await runCli(args) : await runCliInteractive(args);
+        logStep({ fn: 'runAnalyzeSelect:post-spawn', exitCode: r.exitCode, args });
+        if (!acceptAll)
             clearPreviewEnvVars();
-            if (r.exitCode !== 0) {
-                update({ step: 'error', errorStep: 'analyze select', errorMessage: r.stderr.trim() || 'Unknown error' });
-                return;
-            }
-            // Read accepted count from the review state file (since TUI subprocess inherits stdio)
-            const artifactsRoot = process.env['EDS_REVIEW_ARTIFACTS_DIR']
-                ? resolve(process.env['EDS_REVIEW_ARTIFACTS_DIR'])
-                : resolve(homedir(), '.contentful', 'experience-design-system-cli', 'reviews');
-            const reviewStatePath = resolve(artifactsRoot, sessionId, 'current-review-state.json');
-            try {
-                const reviewState = JSON.parse(await readFile(reviewStatePath, 'utf8'));
-                acceptedCount = reviewState.components.filter((c) => c.status === 'accepted').length;
-            }
-            catch {
-                acceptedCount = extractedCount;
-            }
+        if (r.exitCode !== 0) {
+            update({
+                step: 'error',
+                errorStep: 'analyze select',
+                errorMessage: r.stderr.trim() || 'Unknown error',
+            });
+            return;
         }
-        update({ acceptedCount });
+        // Read accepted count from the review state file (since TUI subprocess inherits stdio
+        // in the manual review path; in the bulk path we also persist to the same file).
+        // Also extract auto-rejected count (components with error-severity validation issues
+        // dropped by the gate) so the user sees what was excluded on the next step.
+        const artifactsRoot = process.env['EDS_REVIEW_ARTIFACTS_DIR']
+            ? resolve(process.env['EDS_REVIEW_ARTIFACTS_DIR'])
+            : resolve(homedir(), '.contentful', 'experience-design-system-cli', 'reviews');
+        const reviewStatePath = resolve(artifactsRoot, sessionId, 'current-review-state.json');
+        let autoRejectedCount = 0;
+        try {
+            const reviewState = JSON.parse(await readFile(reviewStatePath, 'utf8'));
+            acceptedCount = reviewState.components.filter((c) => c.status === 'accepted').length;
+            autoRejectedCount = reviewState.components.filter((c) => c.status === 'rejected' && (c.originalProposal.validationIssues ?? []).some((i) => i.severity === 'error')).length;
+        }
+        catch {
+            acceptedCount = extractedCount;
+        }
+        update({ acceptedCount, autoRejectedCount });
         if (acceptedCount > 0) {
             if (await runAgentAuthCheck('generating')) {
                 void runGenerate(sessionId, tokensPath, acceptedCount);
@@ -335,7 +397,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 for (const line of chunk.split('\n')) {
                     const m = /\[(\d+)\/(\d+)\]\s+(.+)/.exec(line);
                     if (m)
-                        update({ generateProgress: { done: Number(m[1]), total: Number(m[2]), current: m[3].trim() } });
+                        update({
+                            generateProgress: {
+                                done: Number(m[1]),
+                                total: Number(m[2]),
+                                current: m[3].trim(),
+                            },
+                        });
                 }
             });
             child.on('exit', (code) => res({ exitCode: code ?? 0, stdout, stderr }));
@@ -352,7 +420,15 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         const generateSessionId = sessionMatch ? sessionMatch[1].trim() : null;
         const countMatch = /(\d+) components?/.exec(result.stderr);
         const generatedCount = countMatch ? Number(countMatch[1]) : acceptedCount;
-        update({ step: 'review-generated-gate', generateSessionId, generatedCount, generateProgress: null });
+        const renamedMatch = /^renamed-slots:\s*(\d+)$/m.exec(result.stdout);
+        const renamedSlotsCount = renamedMatch ? Number(renamedMatch[1]) : 0;
+        update({
+            step: 'review-generated-gate',
+            generateSessionId,
+            generatedCount,
+            renamedSlotsCount,
+            generateProgress: null,
+        });
     };
     const advanceToPushFlow = (generatedAcceptedCount) => {
         update({ generatedAcceptedCount, step: 'credentials' });
@@ -367,7 +443,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             if (sessionId) {
                 const r = await runCliInteractive(['generate', 'components', 'edit', '--session', sessionId]);
                 if (r.exitCode !== 0) {
-                    update({ step: 'error', errorStep: 'generate edit', errorMessage: r.stderr.trim() || 'Unknown error' });
+                    update({
+                        step: 'error',
+                        errorStep: 'generate edit',
+                        errorMessage: r.stderr.trim() || 'Unknown error',
+                    });
                     return;
                 }
                 const acceptedMatch = /Accepted: (\d+)/.exec(r.stderr);
@@ -409,7 +489,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const runEditFromPreview = async (preview) => {
         const sessionId = state.extractSessionId;
         if (!sessionId) {
-            update({ step: 'error', errorStep: 'edit definitions', errorMessage: 'No session available for editing' });
+            update({
+                step: 'error',
+                errorStep: 'edit definitions',
+                errorMessage: 'No session available for editing',
+            });
             return;
         }
         process.env['EDS_PREVIEW_ANNOTATIONS'] = JSON.stringify(buildPreviewAnnotations(preview));
@@ -430,13 +514,22 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         const r = await runCliInteractive(['analyze', 'select', '--session', sessionId]);
         clearPreviewEnvVars();
         if (r.exitCode !== 0) {
-            update({ step: 'error', errorStep: 'edit definitions', errorMessage: 'Editor exited with an error' });
+            update({
+                step: 'error',
+                errorStep: 'edit definitions',
+                errorMessage: 'Editor exited with an error',
+            });
             return;
         }
         // Re-preview with updated definitions
         const { extractSessionId: sid, tokensPath: tp } = sessionRef.current;
         void runPreview(sid, tp, state.spaceId, state.environmentId, state.cmaToken, state.host);
     };
+    const runSkipValidationErrorsAndRetry = async (errors) => {
+        await applySkipValidationErrors(state.extractSessionId, errors);
+        const { extractSessionId: sid, tokensPath: tp } = sessionRef.current;
+        void runPreview(sid, tp, state.spaceId, state.environmentId, state.cmaToken, state.host);
+    };
     const advanceWithCredentials = (spaceId, environmentId, cmaToken, host) => {
         const resolvedHost = resolveWizardHost(host);
         credentialsRef.current = { spaceId, environmentId, cmaToken };
@@ -452,7 +545,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const confirmCredentials = async (spaceId, environmentId, cmaToken, host) => {
         const resolvedHost = resolveWizardHost(host);
         try {
-            await writeExperiencesCredentials({ spaceId, environmentId, cmaToken, host: resolvedHost });
+            await writeExperiencesCredentials({
+                spaceId,
+                environmentId,
+                cmaToken,
+                host: resolvedHost,
+            });
             advanceWithCredentials(spaceId, environmentId, cmaToken, resolvedHost);
         }
         catch (e) {
@@ -471,7 +569,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: 'validating-credentials' });
         try {
             const resolvedHost = resolveWizardHost(host);
-            const client = new ImportApiClient({ cmaToken, spaceId, environmentId, host: resolvedHost });
+            const client = new ImportApiClient({
+                cmaToken,
+                spaceId,
+                environmentId,
+                host: resolvedHost,
+            });
             await client.validateToken();
             const { extractSessionId, tokensPath } = sessionRef.current;
             void runPreview(extractSessionId, tokensPath, spaceId, environmentId, cmaToken, resolvedHost);
@@ -494,7 +597,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: 'previewing' });
         const resolvedHost = resolveWizardHost(host);
         try {
-            const client = new ImportApiClient({ cmaToken, spaceId, environmentId, host: resolvedHost });
+            const client = new ImportApiClient({
+                cmaToken,
+                spaceId,
+                environmentId,
+                host: resolvedHost,
+            });
             let components = [];
             if (extractSessionId) {
                 const db = openPipelineDb();
@@ -543,7 +651,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     db.close();
                 }
             }
-            update({ step: 'preview-gate', serverPreview: preview, manifest });
+            update({ step: 'preview-gate', serverPreview: preview, manifest, ...clearedValidationErrorState() });
         }
         catch (e) {
             if (e instanceof ApiError) {
@@ -585,11 +693,31 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     });
                     return;
                 }
-                update({ step: 'error', errorStep: 'apply preview', errorMessage: e.message, errorAllowCredentialRetry: true });
+                const outcome = await handlePreview422(e, extractSessionId);
+                if (outcome.kind === 'validation-error') {
+                    update({
+                        step: 'preview-validation-error',
+                        previewValidationErrors: outcome.errors,
+                        previewValidationMissingNames: outcome.missingNames,
+                    });
+                    return;
+                }
+                // 'unparseable' and 'not-422' both fall through to the generic error branch below.
+                update({
+                    step: 'error',
+                    errorStep: 'apply preview',
+                    errorMessage: e.message,
+                    errorAllowCredentialRetry: true,
+                });
                 return;
             }
             const msg = e instanceof Error ? e.message : 'Preview failed';
-            update({ step: 'error', errorStep: 'apply preview', errorMessage: msg, errorAllowCredentialRetry: true });
+            update({
+                step: 'error',
+                errorStep: 'apply preview',
+                errorMessage: msg,
+                errorAllowCredentialRetry: true,
+            });
         }
     };
     const runPush = async (manifest, spaceId, environmentId, cmaToken, host, acknowledgeBreakingChanges, preview) => {
@@ -612,17 +740,28 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: 'pushing' });
         try {
             const resolvedHost = resolveWizardHost(host);
-            const client = new ImportApiClient({ cmaToken, spaceId, environmentId, host: resolvedHost });
+            const client = new ImportApiClient({
+                cmaToken,
+                spaceId,
+                environmentId,
+                host: resolvedHost,
+            });
             let operation = await client.applyImport(manifest, acknowledgeBreakingChanges);
             try {
                 logStep({
-                    applyResponse: { status: operation?.sys?.status, id: operation?.sys?.id, keys: Object.keys(operation ?? {}) },
+                    applyResponse: {
+                        status: operation?.sys?.status,
+                        id: operation?.sys?.id,
+                        keys: Object.keys(operation ?? {}),
+                    },
                 });
             }
             catch (err) {
                 process.stderr.write(`[eds] log write failed: ${err instanceof Error ? err.message : String(err)}\n`);
             }
-            update({ pushProgress: `Queued (operation ${operation.sys.id.slice(0, 8)}...)` });
+            update({
+                pushProgress: `Queued (operation ${operation.sys.id.slice(0, 8)}...)`,
+            });
             let pollCount = 0;
             operation = await client.pollOperation(operation.sys.id, {
                 onProgress: (op) => {
@@ -633,7 +772,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                         update({ pushProgress: `${done}/${s.total} entities processed` });
                     }
                     try {
-                        logStep({ pollTick: { attempt: pollCount, status: op.sys.status, summary: op.summary } });
+                        logStep({
+                            pollTick: {
+                                attempt: pollCount,
+                                status: op.sys.status,
+                                summary: op.summary,
+                            },
+                        });
                     }
                     catch (err) {
                         process.stderr.write(`[eds] log write failed: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -691,7 +836,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
         catch (e) {
             const msg = e instanceof ApiError ? e.message : e instanceof Error ? e.message : 'Push failed';
-            update({ step: 'error', errorStep: 'apply push', errorMessage: msg, errorAllowCredentialRetry: true });
+            update({
+                step: 'error',
+                errorStep: 'apply push',
+                errorMessage: msg,
+                errorAllowCredentialRetry: true,
+            });
         }
     };
     const runPrintFiles = async (extractSessionId, outDir) => {
@@ -702,7 +852,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             printArgs.push('--session', extractSessionId);
         const r = await runCli(printArgs);
         if (r.exitCode !== 0) {
-            update({ step: 'error', errorStep: 'print components', errorMessage: r.stderr.trim() || 'Unknown error' });
+            update({
+                step: 'error',
+                errorStep: 'print components',
+                errorMessage: r.stderr.trim() || 'Unknown error',
+            });
             return;
         }
         // tokensPath is already on disk from generate-tokens step; just record it
@@ -724,7 +878,11 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                         stat(state.rawTokensPath).catch(() => null),
                     ]);
                     const sourceChanged = sourceStat ? sourceStat.mtimeMs > tokensStat.mtimeMs : false;
-                    update({ step: 'token-reuse-gate', tokensPath: existingTokensPath, tokenSourceChanged: sourceChanged });
+                    update({
+                        step: 'token-reuse-gate',
+                        tokensPath: existingTokensPath,
+                        tokenSourceChanged: sourceChanged,
+                    });
                 }
                 catch {
                     // No existing tokens — need LLM to generate
@@ -828,11 +986,15 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 const progressDetail = p
                     ? `[${p.done}/${p.total}] ${p.current} — this can take 10–30 minutes for large libraries`
                     : `Starting up ${state.agent}... (this can take 10–30 minutes for large libraries — grab a coffee)`;
-                return (_jsx(RunningStep, { stepNumber: stepNum, totalSteps: totalSteps, title: "Generating definitions", description: `${state.acceptedCount} component${state.acceptedCount === 1 ? '' : 's'} accepted. ${state.agent} is mapping your TypeScript types to Contentful's CDF format.${hasTokens ? ' Using your design tokens for prop resolution.' : ''}`, detail: progressDetail }));
+                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 'review-generated-gate': {
                 const stepNum = hasTokens ? 4 : 3;
-                return (_jsx(GateStep, { successMessage: `Step ${stepNum} complete — definitions generated`, summary: `Generated definitions for ${state.generatedCount} component${state.generatedCount === 1 ? '' : 's'}.`, context: "Take a final look before pushing to Contentful. You can accept, reject, or inspect each component's generated definition.", continueLabel: "Review definitions", skipLabel: "Approve all and skip", onContinue: () => {
+                return (_jsx(GateStep, { successMessage: `Step ${stepNum} complete — definitions generated`, summary: formatGeneratedSummary({
+                        generated: state.generatedCount,
+                        renamedSlots: state.renamedSlotsCount,
+                        autoRejected: state.autoRejectedCount,
+                    }), context: "Take a final look before pushing to Contentful. You can accept, reject, or inspect each component's generated definition.", continueLabel: "Review definitions", skipLabel: "Approve all and skip", onContinue: () => {
                         update({ step: 'generate-review' });
                     }, onSkip: () => {
                         void runGenerateEdit(state.generateSessionId, state.generatedCount, true);
@@ -843,7 +1005,10 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: "red", children: "Error: no session ID \u2014 cannot load generated definitions." }) }));
                 }
                 return (_jsx(GenerateReviewStep, { extractSessionId: state.extractSessionId, onFinalize: (accepted, rejected) => {
-                        update({ generatedAcceptedCount: accepted, step: 'push-decision-gate' });
+                        update({
+                            generatedAcceptedCount: accepted,
+                            step: 'push-decision-gate',
+                        });
                         void Promise.resolve();
                         // log so orchestrator can read it
                         process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}\n`);
@@ -905,6 +1070,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 const totalFailed = state.pushResult.componentTypes.failed + state.pushResult.designTokens.failed;
                 return (_jsx(DoneStep, { componentTypes: state.pushResult.componentTypes, designTokens: state.pushResult.designTokens, summary: state.pushResult.summary, spaceId: state.spaceId, environmentId: state.environmentId, onExit: () => process.exit(totalFailed > 0 ? 1 : 0) }));
             }
+            case 'preview-validation-error': {
+                return (_jsx(PreviewValidationErrorStep, { errors: state.previewValidationErrors, missingNames: state.previewValidationMissingNames, onEdit: () => {
+                        void runEditFromPreview(null);
+                    }, onSkip: () => {
+                        void runSkipValidationErrorsAndRetry(state.previewValidationErrors);
+                    }, onQuit: () => process.exit(0) }));
+            }
             case 'error':
                 return (_jsx(ErrorStep, { stepName: state.errorStep, message: state.errorMessage, onExit: () => process.exit(1), onRetryCredentials: state.errorAllowCredentialRetry ? () => update({ step: 'credentials', credentialsError: '' }) : undefined }));
         }

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

@@ -9,6 +9,7 @@ type GateStepProps = {
     onSkip?: () => void;
     onQuit: () => void;
     showSkip?: boolean;
+    intent?: 'success' | 'error';
 };
-export declare function GateStep({ successMessage, summary, context, continueLabel, skipLabel, onContinue, onSkip, onQuit, showSkip, }: GateStepProps): React.ReactElement;
+export declare function GateStep({ successMessage, summary, context, continueLabel, skipLabel, onContinue, onSkip, onQuit, showSkip, intent, }: GateStepProps): React.ReactElement;
 export {};

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

@@ -1,7 +1,7 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { useImmediateInput } from '../../../analyze/select/tui/hooks/useImmediateInput.js';
-export function GateStep({ successMessage, summary, context, continueLabel = 'Continue', skipLabel = 'Approve all and skip', onContinue, onSkip, onQuit, showSkip = true, }) {
+export function GateStep({ successMessage, summary, context, continueLabel = 'Continue', skipLabel = 'Approve all and skip', onContinue, onSkip, onQuit, showSkip = true, intent = 'success', }) {
     useImmediateInput((input, key) => {
         if (key.return) {
             onContinue();
@@ -16,5 +16,7 @@ export function GateStep({ successMessage, summary, context, continueLabel = 'Co
             return;
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { color: "green", children: ["\u2713 ", successMessage] }), summary && _jsx(Text, { dimColor: true, children: summary }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: context }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: ["[Enter] ", continueLabel] }), showSkip && onSkip && _jsxs(Text, { dimColor: true, children: ["[a] ", skipLabel] }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
+    const headerColor = intent === 'error' ? 'red' : 'green';
+    const headerIcon = intent === 'error' ? '✗' : '✓';
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { color: headerColor, children: [headerIcon, " ", successMessage] }), summary && _jsx(Text, { dimColor: true, children: summary }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: context }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: ["[Enter] ", continueLabel] }), showSkip && onSkip && _jsxs(Text, { dimColor: true, children: ["[a] ", skipLabel] }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
 }

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { PreviewValidationError } from '../../../apply/api-client.js';
+type PreviewValidationErrorStepProps = {
+    errors: PreviewValidationError[];
+    missingNames: string[];
+    onEdit: () => void;
+    onSkip: () => void;
+    onQuit: () => void;
+};
+export declare function PreviewValidationErrorStep({ errors, missingNames, onEdit, onSkip, onQuit, }: PreviewValidationErrorStepProps): React.ReactElement;
+export {};

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

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { GateStep } from './GateStep.js';
+export function PreviewValidationErrorStep({ errors, missingNames, onEdit, onSkip, onQuit, }) {
+    const uniqueNames = [...new Set(errors.map((e) => e.componentName))];
+    const matchedNames = uniqueNames.filter((n) => !missingNames.includes(n));
+    const errorLines = errors.map((e) => `  ${e.componentName}: ${e.message}`).join('\n');
+    const missingNote = missingNames.length > 0
+        ? `\n\nNote: ${missingNames.length} component name${missingNames.length === 1 ? '' : 's'} from the server (${missingNames.join(', ')}) ${missingNames.length === 1 ? 'does' : 'do'} not match anything in this session — they cannot be edited or skipped from here.`
+        : '';
+    const skipLabel = matchedNames.length === 0
+        ? 'No matching components to skip'
+        : `Skip ${matchedNames.length === 1 ? matchedNames[0] : `${matchedNames.length} components`} and retry`;
+    return (_jsx(GateStep, { intent: "error", successMessage: "Preview validation failed", summary: errorLines, context: `${uniqueNames.length} component${uniqueNames.length === 1 ? '' : 's'} failed server validation. Edit their definitions in the review TUI, or skip them and retry preview without them.${missingNote}`, continueLabel: "Edit definitions", skipLabel: skipLabel, showSkip: matchedNames.length > 0, onContinue: onEdit, onSkip: onSkip, onQuit: onQuit }));
+}

package/dist/src/import/tui/wizard-422-helpers.d.ts

@@ -0,0 +1,48 @@
+import { ApiError, type PreviewValidationError } from '../../apply/api-client.js';
+import { patchReviewStateWithValidationErrors, rejectComponentsByName } from '../../analyze/select/command.js';
+export type Preview422Outcome = {
+    kind: 'validation-error';
+    errors: PreviewValidationError[];
+    missingNames: string[];
+} | {
+    kind: 'unparseable';
+    message: string;
+} | {
+    kind: 'not-422';
+};
+/**
+ * Decide what to do with an `ApiError` raised by `previewImport()`.
+ * Returns `not-422` if the caller should fall through to its other branches
+ * (404 / 401 / 403 / generic), `unparseable` if the body cannot be parsed
+ * into structured component-level errors (caller should route to the generic
+ * error step), or `validation-error` with the patched-state side effects
+ * already applied.
+ *
+ * Pure decision logic + a single delegated side effect to
+ * `patchReviewStateWithValidationErrors`. Extracted from `WizardApp.runPreview`
+ * so the routing is unit-testable without driving the full TUI.
+ */
+export declare function handlePreview422(err: ApiError, extractSessionId: string | null, patchFn?: typeof patchReviewStateWithValidationErrors): Promise<Preview422Outcome>;
+/**
+ * The WizardState patch the wizard should spread into any update that
+ * transitions OUT of the preview-validation-error step (e.g. into
+ * preview-gate after a successful retry). Without this, the validation-error
+ * arrays linger in state and any future code path that reads them sees stale
+ * data from a prior failed attempt.
+ */
+export declare function clearedValidationErrorState(): {
+    previewValidationErrors: PreviewValidationError[];
+    previewValidationMissingNames: string[];
+};
+/**
+ * Run the "skip and retry" side effect: dedup the offending component
+ * names from a list of errors and call `rejectComponentsByName`. Returns
+ * the deduped names so the caller can log them or include them in test
+ * assertions. No-op when sessionId is null or errors are empty.
+ *
+ * The DB update inside `rejectComponentsByName` is what makes the next
+ * preview see a manifest with the offenders excluded — see SP-3 retro
+ * Bug 1: writing to the JSON state file alone is not enough because
+ * `loadCDFComponents` reads from the pipeline DB.
+ */
+export declare function applySkipValidationErrors(sessionId: string | null, errors: PreviewValidationError[], rejectFn?: typeof rejectComponentsByName): Promise<string[]>;

package/dist/src/import/tui/wizard-422-helpers.js

@@ -0,0 +1,60 @@
+import { parsePreviewValidationErrors } from '../../apply/api-client.js';
+import { patchReviewStateWithValidationErrors, rejectComponentsByName } from '../../analyze/select/command.js';
+/**
+ * Decide what to do with an `ApiError` raised by `previewImport()`.
+ * Returns `not-422` if the caller should fall through to its other branches
+ * (404 / 401 / 403 / generic), `unparseable` if the body cannot be parsed
+ * into structured component-level errors (caller should route to the generic
+ * error step), or `validation-error` with the patched-state side effects
+ * already applied.
+ *
+ * Pure decision logic + a single delegated side effect to
+ * `patchReviewStateWithValidationErrors`. Extracted from `WizardApp.runPreview`
+ * so the routing is unit-testable without driving the full TUI.
+ */
+export async function handlePreview422(err, extractSessionId, patchFn = patchReviewStateWithValidationErrors) {
+    if (err.status !== 422)
+        return { kind: 'not-422' };
+    const errors = parsePreviewValidationErrors(err.body);
+    if (errors.length === 0)
+        return { kind: 'unparseable', message: err.message };
+    let missingNames = [];
+    if (extractSessionId) {
+        const result = await patchFn(extractSessionId, errors);
+        missingNames = result.missingNames;
+    }
+    return { kind: 'validation-error', errors, missingNames };
+}
+/**
+ * The WizardState patch the wizard should spread into any update that
+ * transitions OUT of the preview-validation-error step (e.g. into
+ * preview-gate after a successful retry). Without this, the validation-error
+ * arrays linger in state and any future code path that reads them sees stale
+ * data from a prior failed attempt.
+ */
+export function clearedValidationErrorState() {
+    return {
+        previewValidationErrors: [],
+        previewValidationMissingNames: [],
+    };
+}
+/**
+ * Run the "skip and retry" side effect: dedup the offending component
+ * names from a list of errors and call `rejectComponentsByName`. Returns
+ * the deduped names so the caller can log them or include them in test
+ * assertions. No-op when sessionId is null or errors are empty.
+ *
+ * The DB update inside `rejectComponentsByName` is what makes the next
+ * preview see a manifest with the offenders excluded — see SP-3 retro
+ * Bug 1: writing to the JSON state file alone is not enough because
+ * `loadCDFComponents` reads from the pipeline DB.
+ */
+export async function applySkipValidationErrors(sessionId, errors, rejectFn = rejectComponentsByName) {
+    if (!sessionId)
+        return [];
+    const names = [...new Set(errors.map((e) => e.componentName))];
+    if (names.length === 0)
+        return [];
+    await rejectFn(sessionId, names);
+    return names;
+}