@contentful/experience-design-system-cli 2.14.2 → 2.15.0

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

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
+import { PALETTE } from '../../analyze/select/tui/theme.js';
 import { Box, Text, useStdout } from 'ink';
 import { join, resolve } from 'node:path';
 import { appendFileSync, writeFileSync } from 'node:fs';
@@ -33,6 +34,10 @@ import { nextStateAfterPrint } from './run-print-files-helpers.js';
 import { PushDecisionGateStep } from './steps/PushDecisionGateStep.js';
 import { chooseGateAction } from './push-decision-gate-helpers.js';
 import { ImportApiClient, ApiError } from '../../apply/api-client.js';
+import { detectSlotCycles, extractComponentsFromManifest, formatSlotCycleReport } from '../../apply/command.js';
+import { findSlotCycles } from '../../analyze/cycle-detection.js';
+import { buildComponentGraph } from '../../analyze/slot-graph.js';
+import { parseEdsiError, formatParsedEdsiError } from '../../apply/error-parser.js';
 import { handlePreview422, applySkipValidationErrors, clearedValidationErrorState } from './wizard-422-helpers.js';
 import { parseGenerateStderrChunk } from './wizard-generate-progress.js';
 import { spawnGenerateChild } from './spawn-generate.js';
@@ -49,14 +54,12 @@ import { checkAgentAuth } from '../../generate/agent-runner.js';
 import { normalizePath } from '../path-utils.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../../host-utils.js';
 import { writeExperiencesCredentials } from '../../credentials-store.js';
-import { nextStepAfterScopeGate, nextStepAfterCredentialsValidated, shouldBypassPreview, buildSkippedPreviewTransition, shouldRefusePush, buildSkippedPushTransition, shouldSkipFinalReviewAfterCredentials, resolveNoCacheForGenerate, } from './wizard-state-transitions.js';
+import { nextStepAfterScopeGate, nextStepAfterCredentialsValidated, shouldBypassPreview, buildSkippedPreviewTransition, shouldRefusePush, buildSkippedPushTransition, shouldSkipFinalReviewAfterCredentials, resolveNoCacheForGenerate, resolveCycleGateAction, } from './wizard-state-transitions.js';
+import { computeCycleAutoRejectTargets } from '../cycle-auto-reject.js';
 function findCliPath() {
     return join(fileURLToPath(import.meta.url), '..', '..', '..', '..', '..', 'bin', 'cli.js');
 }
 export function buildSelectAgentArgs(opts) {
-    // Feature 3: the wizard auto-filter run should never fail-loud on validation
-    // errors — those components surface in the AI-excluded section with a
-    // synthesized reason, not an exit-1 abort. So we always pass --exclude-invalid.
     const args = ['analyze', 'select-agent', '--agent', opts.agent, '--session', opts.sessionId, '--exclude-invalid'];
     if (opts.model)
         args.push('--model', opts.model);
@@ -67,11 +70,6 @@ export function buildSelectAgentArgs(opts) {
     return args;
 }
 export function parseAutoFilterProgressLine(line) {
-    // Format: progress=select-agent:N/M:<decision>:<name>:<url-encoded-reason>
-    // Name and reason CANNOT contain `:` raw (name comes from component identifier
-    // which forbids colons; reason is URL-encoded). We split with a limit so any
-    // stray colon inside the URL-encoded reason wouldn't matter — but the encoder
-    // also handles `:` as `%3A` so this is defensive.
     const prefix = 'progress=select-agent:';
     if (!line.startsWith(prefix))
         return null;
@@ -106,10 +104,6 @@ export function parseAutoFilterProgressLine(line) {
     };
 }
 export function buildGenerateComponentsArgs(opts) {
-    // Default behavior preserves the SHA cache (re-runs only re-classify
-    // changed components). The operator opts into a full re-classify pass via
-    // `experiences import --no-cache`, which forwards through to the spawned
-    // `generate components` subprocess. See wizard-cache.test.ts.
     const args = ['generate', 'components', '--agent', opts.agent, '--session', opts.sessionId];
     if (opts.tokensPath)
         args.push('--tokens', opts.tokensPath);
@@ -134,12 +128,6 @@ function runCli(args) {
         });
     });
 }
-/**
- * Parse the `wrote tokens.json (N tokens)` confirmation line emitted by
- * `experiences print tokens`. Returns 0 when the line cannot be parsed —
- * the wizard still records the run; downstream consumers should treat 0 as
- * "unknown" rather than "no tokens".
- */
 export function parsePrintTokensCount(stdout) {
     const m = /\((\d+)\s+token/.exec(stdout);
     return m ? Number(m[1]) : 0;
@@ -148,10 +136,9 @@ 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, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, } = {}) {
+export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope = false, autoRejectCycles = false, compositionMode = 'atomic', compositionMap, compositionAgent = false, compositionAgentMode, compositionRefresh = false, generateMap, promptOverrides, 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();
@@ -166,39 +153,19 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         extractSessionId: null,
         tokensPath: '',
     });
-    // Feature 3: holds the spawned `analyze select-agent` subprocess so the
-    // scope-gate's `q` (during running) can SIGTERM it for cancellation.
+    // Set at finalize when zero components are accepted (confirmed via the
+    // FinalizeDialog warning). Read by preview/push so buildManifest emits an
+    // empty-but-present components manifest → server deletes all. A ref (not
+    // state) so the async preview/push closures see the confirmed value.
+    const allowEmptyDeleteAllRef = useRef(false);
     const autoFilterChildRef = useRef(null);
-    // Promise that resolves when the auto-filter subprocess fully exits. Used
-    // by `cancelAutoFilterAndWait` so scope-gate confirm can guarantee its
-    // snapshot write goes AFTER the subprocess's last write.
     const autoFilterDonePromiseRef = useRef(null);
-    // Background `generate components` subprocess spawned from scope-gate
-    // confirm so its LLM call overlaps with the operator's credential entry.
-    // Held in refs so we can SIGTERM on credential failure / quit, and await
-    // the promise from inside `validateCredentials` once creds come back OK.
     const generateChildRef = useRef(null);
     const generatePromiseRef = useRef(null);
-    // Modify-entry short-circuit: when the launcher passes seed session IDs
-    // and `initialStep: 'final-review'`, skip the welcome/token-input bootstrap
-    // and land directly on the post-generate review screen. The DB-backed
-    // 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 && !pushFromPickerReady && !!initialRawTokensPath;
-    const isFreshSession = !seedExtractSessionId;
-    const effectiveNoCache = resolveNoCacheForGenerate({ isFreshSession, cliNoCache: noCache });
+    const effectiveNoCache = resolveNoCacheForGenerate({ cliNoCache: noCache });
     const initialStepResolved = modifyEntryReady
         ? 'final-review'
         : pushFromPickerReady
@@ -209,7 +176,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     ? 'token-input'
                     : 'welcome';
     const initialOutDir = initialProjectPath ? join(resolve(initialProjectPath), '.contentful') : '';
-    const initialTokensPath = (modifyEntryReady || pushFromPickerReady) && initialOutDir ? join(initialOutDir, 'tokens.json') : '';
+    // Only point at tokens.json when the run actually had a tokens session. A run
+    // saved without tokens has no tokens.json on disk, so assuming one exists made
+    // modify/push-from-picker fail with "file not found: .../tokens.json".
+    const initialTokensPath = (modifyEntryReady || pushFromPickerReady) && initialOutDir && seedTokenSessionId
+        ? join(initialOutDir, 'tokens.json')
+        : '';
     const [state, setState] = useState({
         step: modifyEntryReady || rawTokensEntryReady || pushFromPickerReady
             ? initialStepResolved
@@ -236,6 +208,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         renamedSlotsCount: 0,
         generateProgress: null,
         extractProgress: null,
+        compositionPhase: null,
         componentsPath: '',
         spaceId: initialSpaceId,
         environmentId: initialEnvironmentId,
@@ -266,6 +239,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         lastRunId: null,
         finalizeErrorBanner: null,
         finalReviewPassed: modifyEntryReady || pushFromPickerReady,
+        allowEmptyDeleteAll: false,
     });
     useEffect(() => {
         sessionRef.current = {
@@ -320,7 +294,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         logStep({ update: sanitized });
         setState((prev) => ({ ...prev, ...partial }));
     };
-    // ── Agent auth pre-flight ───────────────────────────────────────────────────────
     const runAgentAuthCheck = async (nextStep) => {
         const authCheckStepNumber = nextStep === 'generating-tokens' ? 1 : state.tokensPath ? 4 : 3;
         update({ step: 'checking-claude-auth', authCheckStepNumber });
@@ -347,7 +320,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: nextStep });
         return true;
     };
-    // ── Step runners ────────────────────────────────────────────────────────
     const runGenerateTokens = async (rawTokensPath, outDir) => {
         const result = await new Promise((res) => {
             const tokenArgs = [findCliPath(), 'generate', 'tokens', '--agent', state.agent, '--raw-tokens', rawTokensPath];
@@ -392,9 +364,28 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     };
     const runExtract = async (projectPath) => {
         const outDir = join(resolve(projectPath), '.contentful');
-        update({ step: 'extracting', outDir, extractProgress: null });
+        update({ step: 'extracting', outDir, extractProgress: null, compositionPhase: null });
         const r = await new Promise((res) => {
-            const child = spawn('node', [findCliPath(), 'analyze', 'extract', '--project', projectPath]);
+            const extractArgs = [findCliPath(), 'analyze', 'extract', '--project', projectPath];
+            if (compositionMode === 'composite') {
+                extractArgs.push('--composite');
+                if (compositionMap)
+                    extractArgs.push('--composition-map', compositionMap);
+                if (compositionAgent)
+                    extractArgs.push('--composition-agent');
+                if (compositionAgentMode)
+                    extractArgs.push('--composition-agent-mode', compositionAgentMode);
+                if (compositionRefresh)
+                    extractArgs.push('--composition-refresh');
+                if (generateMap)
+                    extractArgs.push('--generate-map', generateMap);
+                for (const p of promptOverrides ?? [])
+                    extractArgs.push('--prompt', p);
+                // Composition resolution uses the same agent the user picked for the run.
+                if (state.agent)
+                    extractArgs.push('--agent', state.agent);
+            }
+            const child = spawn('node', extractArgs);
             let stdout = '';
             let stderr = '';
             child.stdout.on('data', (d) => {
@@ -432,6 +423,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                                 componentsFound,
                             },
                         }));
+                        continue;
+                    }
+                    const compositionMatch = /^progress=composition:(.+)$/.exec(line.trim());
+                    if (compositionMatch) {
+                        const phase = compositionMatch[1];
+                        setState((prev) => ({ ...prev, compositionPhase: phase }));
                     }
                 }
             });
@@ -470,11 +467,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             autoFilterDonePromiseRef.current = runAutoFilter(extractSessionId);
         }
     };
-    // Feature 3: spawn `analyze select-agent` after extract and stream decisions
-    // into wizard state via stderr progress lines. The subprocess writes
-    // `raw_components.status` + `reject_reason` itself (see Task 2), so the
-    // scope-gate UI re-loads via `loadScopeComponents` to get fresh data on every
-    // render — but we also keep a memory-side `aiDecisions` map for streaming UX.
     const runAutoFilter = (sessionId) => {
         return new Promise((res) => {
             const args = buildSelectAgentArgs({
@@ -507,12 +499,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     }));
                 }
             });
-            // Use 'close' (not 'exit') so the status flip happens after the child's
-            // stdio AND its inherited SQLite WAL/SHM file handles have been fully
-            // released by the OS. 'exit' fires the instant the process terminates;
-            // setting state then triggers a wizard re-render that re-opens
-            // pipeline.db from the scope-gate step, and the lock from the dead
-            // child's still-mapped WAL handle surfaces as "database is locked".
             child.on('close', (code, signal) => {
                 autoFilterChildRef.current = null;
                 if (signal === 'SIGTERM') {
@@ -553,16 +539,10 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             }
         }
     };
-    // Variant that returns a Promise resolving when the subprocess has fully
-    // exited. Used by scope-gate confirm to guarantee operator-write-last
-    // ordering on the review-state snapshot (PR #43 race fix).
     const cancelAutoFilterAndWait = async () => {
         const child = autoFilterChildRef.current;
         const donePromise = autoFilterDonePromiseRef.current;
         if (!child || child.killed) {
-            // Subprocess already gone (or never started). If the Promise is still
-            // pending — e.g. exit handler hasn't fired yet — await it; otherwise
-            // resolve immediately.
             if (donePromise)
                 await donePromise;
             return;
@@ -576,9 +556,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         if (donePromise)
             await donePromise;
     };
-    // Cancel a running generation prefetch (SIGTERM the child + clear refs +
-    // reset state). Best-effort — if the child has already exited, this is a
-    // no-op aside from clearing the prefetch status.
     const cancelGeneratePrefetch = () => {
         const child = generateChildRef.current;
         if (child && !child.killed) {
@@ -598,9 +575,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             generateProgress: null,
         }));
     };
-    // Spawn `generate components` in the background. Wires up the same
-    // stderr-progress streaming as `runGenerate` but stores the in-flight
-    // promise in a ref so the post-credentials path can await it.
     const startGeneratePrefetch = (extractSessionId, tokensPath) => {
         const args = [
             findCliPath(),
@@ -633,10 +607,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }));
         donePromise
             .then((result) => {
-            // Clear the child ref regardless of how it ended.
             generateChildRef.current = null;
             if (result.signal === 'SIGTERM') {
-                // Caller already reset state via cancelGeneratePrefetch.
                 return;
             }
             if (result.exitCode !== 0) {
@@ -655,8 +627,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             const generatedCount = countMatch ? Number(countMatch[1]) : 0;
             const renamedMatch = /^renamed-slots:\s*(\d+)$/m.exec(result.stdout);
             const renamedSlotsCount = renamedMatch ? Number(renamedMatch[1]) : 0;
-            // Persist generated state but DO NOT auto-advance — the credentials
-            // path will pick this up via `advanceAfterCredentialsValidated`.
             setState((prev) => ({
                 ...prev,
                 generateSessionId,
@@ -727,7 +697,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ generatedAcceptedCount, step: 'credentials' });
     };
     const runEditFromPreview = async () => {
-        // Post-preview edits land in the unified final-review screen.
         update({ step: 'final-review' });
     };
     const runSkipValidationErrorsAndRetry = async (errors) => {
@@ -738,11 +707,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const advanceWithCredentials = (spaceId, environmentId, cmaToken, host) => {
         const resolvedHost = resolveWizardHost(host);
         credentialsRef.current = { spaceId, environmentId, cmaToken };
-        // The dedicated `credential-test-gate` screen was dropped — credentials are
-        // now always validated immediately after they're persisted. The inline
-        // `credentialsValidating` status (PR #54) handles the visual feedback while
-        // the API ping is in flight. The literal `'credential-test-gate'` is kept
-        // in the WizardStep union for back-compat, but is never set as a step.
         void validateCredentials(spaceId, environmentId, cmaToken, resolvedHost);
     };
     const confirmCredentials = async (spaceId, environmentId, cmaToken, host) => {
@@ -769,8 +733,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
     };
     const validateCredentials = async (spaceId, environmentId, cmaToken, host) => {
-        // Inline validation: stay on the credentials step, flip the validating
-        // boolean so CredentialsStep locks input + renders an inline status.
         update({ step: 'credentials', credentialsValidating: true, credentialsError: '' });
         try {
             const resolvedHost = resolveWizardHost(host);
@@ -786,9 +748,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
         catch (e) {
             if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
-                // Validation failure: cancel any in-flight generate prefetch so we
-                // don't leave an orphaned subprocess running after the operator backs
-                // out (Risk #1 in the spec).
                 cancelGeneratePrefetch();
                 update({ step: 'credentials', credentialsValidating: false, credentialsError: e.message });
                 return;
@@ -804,10 +763,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
         }
     };
-    // Branch after credentials are known good (validated, or skipped via the
-    // credential-test-gate skip path). Either runs the generator (if there are
-    // accepted components) or jumps straight to push-decision-gate (if scope
-    // rejected everything but tokens/removals still need to be pushed).
     const advanceAfterCredentialsValidated = async () => {
         if (shouldSkipFinalReviewAfterCredentials(state)) {
             update({ step: 'push-decision-gate' });
@@ -824,25 +779,15 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 });
                 return;
             }
-            // Prefetch path: if a background generate is already running or has
-            // already completed, await it (or use its result) instead of spawning
-            // a second LLM call. Transition to 'generating' first so the operator
-            // sees the familiar RunningStep progress screen while we wait —
-            // matching the no-prefetch flow's visual.
             const inflight = generatePromiseRef.current;
             if (inflight) {
                 update({ step: 'generating' });
                 const result = await inflight;
                 generatePromiseRef.current = null;
                 if (result.exitCode === 0 && result.signal !== 'SIGTERM') {
-                    // The donePromise.then() handler already populated
-                    // generateSessionId / generatedCount in state. Advance to
-                    // final-review using the latest values via functional setState so
-                    // we read whichever update landed last.
                     setState((prev) => ({ ...prev, step: 'final-review' }));
                     return;
                 }
-                // Prefetch failed — fall through to retry via a fresh runGenerate.
             }
             if (await runAgentAuthCheck('generating')) {
                 void runGenerate(sid, state.tokensPath, state.acceptedCount);
@@ -852,11 +797,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         update({ step: 'push-decision-gate' });
     };
     const runPreview = async (extractSessionId, tokensPath, spaceId, environmentId, cmaToken, host) => {
-        // Skip-credentials short-circuit. When the operator pressed `s` on the
-        // credentials screen, we never got a working token — calling
-        // previewImport would 401/403 (or worse, send a half-formed manifest
-        // somewhere). Jump straight to the push-decision-gate; Task 3 disables
-        // the push options downstream.
         if (shouldBypassPreview(state)) {
             update(buildSkippedPreviewTransition());
             return;
@@ -885,14 +825,12 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             if (tokensPath) {
                 tokens = await readTokensFromPath('tokens', tokensPath);
             }
-            let manifest = buildManifest(components, tokens);
+            let manifest = buildManifest(components, tokens, { deleteAllComponents: allowEmptyDeleteAllRef.current });
             let preview = await client.previewImport(manifest);
-            // Second pass: seed CDF from false removals + preserve defaults from changed items
             if (extractSessionId) {
                 let needsRepreview = false;
                 const db = openPipelineDb();
                 try {
-                    // Seed CDF for components server thinks are removed but exist locally
                     if (preview.components.removed.length > 0) {
                         const localNames = new Set(db.prepare(`SELECT name FROM raw_components WHERE session_id = ?`).all(extractSessionId).map((r) => r.name));
                         const falseRemovals = preview.components.removed.filter((r) => localNames.has(r.name));
@@ -902,7 +840,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                                 needsRepreview = true;
                         }
                     }
-                    // Preserve server-side defaults so we don't accidentally propose removing them
                     if (preview.components.changed.length > 0) {
                         const seededDefaults = seedDefaultsFromChangedItems(db, extractSessionId, preview.components.changed);
                         if (seededDefaults > 0)
@@ -910,7 +847,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     }
                     if (needsRepreview) {
                         components = loadCDFComponents(db, extractSessionId);
-                        manifest = buildManifest(components, tokens);
+                        manifest = buildManifest(components, tokens, { deleteAllComponents: allowEmptyDeleteAllRef.current });
                         preview = await client.previewImport(manifest);
                     }
                 }
@@ -918,16 +855,19 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     db.close();
                 }
             }
-            // 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)) {
+                // No-op push: the accepted set already matches the target space, so
+                // there is nothing to create/update/remove. Route to a terminal "done"
+                // state rather than bouncing back to final-review — the review screen
+                // resets every component to needs-review on remount, which otherwise
+                // traps the operator in an accept → empty-preview → reset loop.
                 update({
-                    step: 'final-review',
-                    finalizeErrorBanner: 'Nothing to push — accept a component, reject a component that exists in Contentful, or quit.',
+                    step: 'done',
                     serverPreview: preview,
+                    pushResult: {
+                        componentTypes: { created: 0, updated: 0, removed: 0, failed: 0 },
+                        designTokens: { created: 0, updated: 0, removed: 0, failed: 0 },
+                    },
                     ...clearedValidationErrorState(),
                 });
                 return;
@@ -950,8 +890,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     catch {
                         /* non-JSON */
                     }
-                    // Space-level config errors (e.g. "Design system public CMA is disabled") cannot be
-                    // fixed by re-entering credentials — send to error screen.
                     if (bodyMsg && /disabled/i.test(bodyMsg)) {
                         update({
                             step: 'error',
@@ -965,9 +903,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     return;
                 }
                 if (e.status === 404) {
-                    // 404 from previewImport means the design systems endpoint doesn't exist for this
-                    // space/environment (typically wrong --host or wrong space/env). Not a credentials
-                    // problem — show a clear error instead of looping.
                     update({
                         step: 'error',
                         errorStep: 'apply preview',
@@ -989,7 +924,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     });
                     return;
                 }
-                // 'unparseable' and 'not-422' both fall through to the generic error branch below.
                 update({
                     step: 'error',
                     errorStep: 'apply preview',
@@ -1008,12 +942,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         }
     };
     const runPush = async (manifest, spaceId, environmentId, cmaToken, host, acknowledgeBreakingChanges, preview) => {
-        // Skip-credentials defensive guard. The push-decision-gate disables
-        // push-emitting choices when `credentialsSkipped` is true, so we
-        // should never get here in practice. But if a state-machine bug or
-        // future regression ever did, refuse to issue the API call — there
-        // is no validated token and the operator explicitly opted out of
-        // push. Route back to the local-save (print-gate) path instead.
         if (shouldRefusePush(state)) {
             update(buildSkippedPushTransition());
             return;
@@ -1034,6 +962,16 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 return;
             }
         }
+        const cycles = detectSlotCycles(extractComponentsFromManifest(manifest));
+        if (cycles.length > 0) {
+            update({
+                step: 'error',
+                errorStep: 'apply push',
+                errorMessage: formatSlotCycleReport(cycles).join('\n'),
+                errorAllowCredentialRetry: false,
+            });
+            return;
+        }
         update({ step: 'pushing', pushProgress: null });
         try {
             const resolvedHost = resolveWizardHost(host);
@@ -1067,9 +1005,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     if (s) {
                         const done = s.total - s.pending;
                         const items = op.items ?? [];
-                        // Best-effort fresh signal: pick the most recently succeeded item
-                        // (the API does not surface an in-progress status today). Falls
-                        // back to null and the PushingStep hides the line.
                         const lastDone = items.length > 0 ? items[items.length - 1] : null;
                         const current = lastDone && lastDone.status === 'succeeded' ? lastDone.id : null;
                         update({
@@ -1124,27 +1059,43 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 };
             }
             else {
-                // API didn't return items — fall back to summary + preview counts
+                const summary = operation.summary ?? { total: 0, pending: 0, succeeded: 0, failed: 0 };
+                const anyFailure = summary.failed > 0 || operation.sys.status === 'failed' || operation.sys.status === 'partial';
                 pushResult = {
                     componentTypes: {
-                        created: preview?.components.new.length ?? 0,
-                        updated: preview?.components.changed.length ?? 0,
-                        removed: preview?.components.removed.length ?? 0,
-                        failed: 0,
+                        created: anyFailure ? 0 : (preview?.components.new.length ?? 0),
+                        updated: anyFailure ? 0 : (preview?.components.changed.length ?? 0),
+                        removed: anyFailure ? 0 : (preview?.components.removed.length ?? 0),
+                        failed: summary.failed,
                     },
                     designTokens: {
-                        created: preview?.tokens.new.length ?? 0,
-                        updated: preview?.tokens.changed.length ?? 0,
-                        removed: preview?.tokens.removed.length ?? 0,
+                        created: anyFailure ? 0 : (preview?.tokens.new.length ?? 0),
+                        updated: anyFailure ? 0 : (preview?.tokens.changed.length ?? 0),
+                        removed: anyFailure ? 0 : (preview?.tokens.removed.length ?? 0),
                         failed: 0,
                     },
-                    summary: operation.summary,
+                    summary,
                 };
             }
             update({ step: 'done', pushResult });
         }
         catch (e) {
-            const msg = e instanceof ApiError ? e.message : e instanceof Error ? e.message : 'Push failed';
+            let msg;
+            if (e instanceof ApiError) {
+                const parsed = parseEdsiError(e.body || e.message);
+                msg = formatParsedEdsiError(parsed, {
+                    verbose: process.env['EDSI_VERBOSE_ERRORS'] === '1',
+                    raw: e.body,
+                });
+                if (!msg)
+                    msg = e.message;
+            }
+            else if (e instanceof Error) {
+                msg = e.message;
+            }
+            else {
+                msg = 'Push failed';
+            }
             update({
                 step: 'error',
                 errorStep: 'apply push',
@@ -1159,6 +1110,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         const printArgs = ['print', 'components', '--out', componentsPath];
         if (extractSessionId)
             printArgs.push('--session', extractSessionId);
+        if (opts.allowEmpty)
+            printArgs.push('--allow-empty');
         const r = await runCli(printArgs);
         if (r.exitCode !== 0) {
             update({
@@ -1168,9 +1121,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
             return { ok: false };
         }
-        // Co-locate tokens.json with components.json. Without this, `--out-dir`
-        // would move components.json to the operator's chosen path while leaving
-        // tokens.json behind at <projectPath>/.contentful/tokens.json.
         let emittedTokensPath;
         let emittedTokenCount;
         if (opts.tokenSessionId) {
@@ -1198,11 +1148,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
     const runSaveAndPush = async () => {
         await startSaveFlow({ skipGate: true, andPush: true });
     };
-    // ── Task 4: save-path orchestration ────────────────────────────────────────
-    // Wraps every `runPrintFiles` site. When `--out-dir` is set we skip the
-    // inline prompt and conflict gate entirely. Otherwise the wizard transitions
-    // to the path-prompt step; the operator's submit handler calls back into
-    // `proceedToWrite` (which may surface the conflict gate).
     const pendingSaveOptionsRef = useRef({});
     const startSaveFlow = async (opts = {}) => {
         pendingSaveOptionsRef.current = opts;
@@ -1234,20 +1179,14 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         const result = await runPrintFiles(extractSessionId, path, {
             ...(skipGate ? { skipGate: true } : {}),
             ...(state.tokenSessionId ? { tokenSessionId: state.tokenSessionId } : {}),
+            ...(allowEmptyDeleteAllRef.current ? { allowEmpty: true } : {}),
         });
         if (!result.ok)
             return;
-        // Prefer the freshly emitted path/count (covers --out-dir); fall back to
-        // the values captured during the original generate-tokens step.
         const recordedTokensPath = result.tokensPath ?? (state.tokenSessionId ? tokensPath || null : null);
         const recordedTokenCount = result.tokenCount ?? state.tokenCount;
         if (result.ok) {
-            // Append a run record on every successful write. Best-effort: append
-            // failures must not break the wizard flow (they surface on stderr).
             try {
-                // Build the v3 fingerprints. Both are best-effort: if any step
-                // throws (missing source file, hash failure, db lookup error) we
-                // fall back to null fingerprints rather than aborting the save.
                 let sourceFingerprint = null;
                 let savedFingerprint = null;
                 try {
@@ -1292,6 +1231,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     generateSessionId: state.generateSessionId,
                     sourceFingerprint,
                     savedFingerprint,
+                    compositionMode,
                 });
                 setState((prev) => ({ ...prev, lastRunId: record.id }));
             }
@@ -1303,7 +1243,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
         }
     };
-    // ── Effect: kick off automatic steps ───────────────────────────────────────────────
     const tokenReuseChecked = useRef(false);
     useEffect(() => {
         if (state.step === 'generating-tokens') {
@@ -1326,21 +1265,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     });
                 }
                 catch {
-                    // No existing tokens — need LLM to generate
                     if (await runAgentAuthCheck('generating-tokens')) {
                         void runGenerateTokens(state.rawTokensPath, state.outDir);
                     }
                 }
             })();
         }
-    }, [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).
+    }, [state.step]);
     const pushFromPickerDispatched = useRef(false);
     useEffect(() => {
         if (state.step !== 'push-from-picker')
@@ -1350,7 +1281,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         pushFromPickerDispatched.current = true;
         void runPreview(state.extractSessionId, state.tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
     }, [state.step]);
-    // ── Render ────────────────────────────────────────────────────────────────────────────
     const noQuitSteps = [
         'run-picker',
         'checking-claude-auth',
@@ -1364,7 +1294,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
         'pushing',
     ];
     const hints = noQuitSteps.includes(state.step) ? [] : [{ key: 'q', label: 'quit' }];
-    // step count: tokens step adds 1, components steps add 2 (extract + generate)
     const hasTokens = !!state.tokensPath;
     const hasComponents = !state.skipComponents;
     const totalSteps = 3 + (hasTokens ? 1 : 0) + (hasComponents ? 2 : 0);
@@ -1376,10 +1305,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                             update({ step: 'welcome' });
                             return;
                         }
-                        // Push / modify routing exits the wizard back into the CLI
-                        // surface so `replayRun` / `modifyRun` (which spin their own
-                        // UI / spawn their own Ink trees) can take over. The CLI
-                        // entry point in `command.ts` provides `onRunPicked`.
                         onRunPicked?.(selection);
                     }, onCancel: () => process.exit(0) }));
             case 'welcome':
@@ -1411,9 +1336,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 return (_jsx(PathValidationStep, { projectPath: state.projectPath, onConfirm: (path) => {
                         void runExtract(path);
                     }, onSkipComponents: () => {
-                        // No components — only design tokens to push. Still gather creds
-                        // first (unless --no-push, in which case there is nothing to do
-                        // and we save files instead).
                         if (noPush) {
                             update({ skipComponents: true, acceptedCount: 0 });
                             void startSaveFlow();
@@ -1433,11 +1355,29 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 else {
                     extractDetail = 'Scanning...';
                 }
-                return (_jsx(RunningStep, { stepNumber: hasTokens ? 2 : 1, totalSteps: totalSteps, title: "Extracting components", description: "I'm scanning your files and figuring out what components exist, what props they have, and how they're structured. This is fully automatic \u2014 sit tight.", detail: extractDetail }));
+                const compositionDetail = (() => {
+                    const phase = state.compositionPhase;
+                    if (!phase)
+                        return undefined;
+                    if (phase === 'resolving')
+                        return 'Resolving composition mapping...';
+                    if (phase === 'cache-hit')
+                        return 'Composition mapping (cached)...';
+                    if (phase === 'authoring')
+                        return 'Writing a composition parser...';
+                    if (phase === 'parsing')
+                        return 'Running the composition parser...';
+                    if (phase.startsWith('agent:'))
+                        return `Resolving composition via ${phase.slice('agent:'.length)} agent...`;
+                    if (phase === 'done')
+                        return 'Composition mapping resolved ✓';
+                    return `Composition: ${phase}`;
+                })();
+                return (_jsx(RunningStep, { stepNumber: hasTokens ? 2 : 1, totalSteps: totalSteps, title: "Extracting components", description: "I'm scanning your files and figuring out what components exist, what props they have, and how they're structured. This is fully automatic \u2014 sit tight.", detail: extractDetail, secondaryDetail: compositionDetail }));
             }
             case 'scope-gate': {
                 if (!state.extractSessionId) {
-                    return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: "red", children: "Error: extract session ID missing \u2014 please re-run." }) }));
+                    return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: PALETTE.error, children: "Error: extract session ID missing \u2014 please re-run." }) }));
                 }
                 const sessionId = state.extractSessionId;
                 const db = openPipelineDb();
@@ -1448,12 +1388,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 finally {
                     db.close();
                 }
-                // INTEG-4318: overlay the streamed auto-filter decisions (from
-                // stderr progress lines) onto DB-loaded rows so 'failed' components
-                // (LLM omitted a tool call in a batch) surface in the scope-gate
-                // instead of silently defaulting to included.
                 components = mergeAiDecisions(components, state.aiDecisions);
-                return (_jsx(ScopeGateHost, { components: components, autoAccept: autoAcceptScope, aiFilterStatus: state.aiFilterStatus, aiFilterProgress: state.aiFilterProgress, aiFilterError: state.aiFilterError, onCancelAutoFilter: cancelAutoFilter, onConfirm: (decisions) => {
+                return (_jsx(ScopeGateHost, { components: components, autoAccept: autoAcceptScope, compositionMode: compositionMode, aiFilterStatus: state.aiFilterStatus, aiFilterProgress: state.aiFilterProgress, aiFilterError: state.aiFilterError, onCancelAutoFilter: cancelAutoFilter, onConfirm: (decisions) => {
                         void runScopeGate({
                             sessionId,
                             decisions,
@@ -1467,12 +1403,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                                     }
                                     return;
                                 }
-                                // next === 'credentials' (push enabled). Kick off the
-                                // generate child in the background so the LLM call overlaps
-                                // with the operator's credential entry. We only prefetch
-                                // when we have accepted components to classify AND push is
-                                // enabled (noPush path is already excluded — the scope-gate
-                                // helper would have returned 'generating' there).
                                 if (acceptedCount > 0 && !noPush) {
                                     if (await runAgentAuthCheck('credentials')) {
                                         startGeneratePrefetch(sid, state.tokensPath);
@@ -1487,7 +1417,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                                     void startSaveFlow();
                                     return;
                                 }
-                                // 'credentials' — still need creds for tokens/removals push.
                                 advanceToPushFlow(count);
                             },
                         });
@@ -1502,38 +1431,122 @@ 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, initialFinalizeError: state.finalizeErrorBanner, onFinalize: (accepted, rejected, unresolved) => {
+                return (_jsx(FinalReviewHost, { extractSessionId: state.extractSessionId, generatedCount: state.generatedCount, autoAccept: autoAcceptScope, compositionMode: compositionMode, 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`);
-                        update({ finalReviewPassed: true });
-                        // 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.
+                        let acceptedCount = accepted;
+                        const detectAcceptedCycles = () => {
+                            if (!state.extractSessionId)
+                                return [];
+                            try {
+                                const db = openPipelineDb();
+                                try {
+                                    const acceptedComponents = loadCDFComponents(db, state.extractSessionId);
+                                    return findSlotCycles(buildComponentGraph(acceptedComponents));
+                                }
+                                finally {
+                                    db.close();
+                                }
+                            }
+                            catch {
+                                return [];
+                            }
+                        };
+                        let acceptedCycles = detectAcceptedCycles();
+                        const gateAction = resolveCycleGateAction({
+                            hasCycles: acceptedCycles.length > 0,
+                            autoRejectCycles,
+                        });
+                        const routeToCycleError = () => {
+                            update({
+                                step: 'error',
+                                errorStep: 'final review',
+                                errorMessage: formatSlotCycleReport(acceptedCycles).join('\n'),
+                                errorAllowCredentialRetry: false,
+                            });
+                        };
+                        if (gateAction === 'block') {
+                            routeToCycleError();
+                            return;
+                        }
+                        if (gateAction === 'auto-reject' && state.extractSessionId) {
+                            const sessionId = state.extractSessionId;
+                            let excluded = [];
+                            try {
+                                const db = openPipelineDb();
+                                try {
+                                    const acceptedComponents = loadCDFComponents(db, sessionId);
+                                    const targets = computeCycleAutoRejectTargets(acceptedCycles, buildComponentGraph(acceptedComponents));
+                                    excluded = [...targets];
+                                    if (excluded.length > 0) {
+                                        const stmt = db.prepare(`UPDATE raw_components SET status = 'generate-rejected' WHERE session_id = ? AND name = ?`);
+                                        db.exec('BEGIN');
+                                        try {
+                                            for (const name of excluded) {
+                                                stmt.run(sessionId, name);
+                                            }
+                                            db.exec('COMMIT');
+                                        }
+                                        catch (e) {
+                                            db.exec('ROLLBACK');
+                                            throw e;
+                                        }
+                                    }
+                                }
+                                finally {
+                                    db.close();
+                                }
+                            }
+                            catch {
+                                routeToCycleError();
+                                return;
+                            }
+                            if (excluded.length > 0) {
+                                process.stderr.write(`Auto-rejected cycle participants: ${excluded.join(', ')}\n`);
+                                logStep({ event: 'cycle-auto-reject', excluded });
+                            }
+                            acceptedCycles = detectAcceptedCycles();
+                            if (acceptedCycles.length > 0) {
+                                routeToCycleError();
+                                return;
+                            }
+                            const remaining = (() => {
+                                if (!state.extractSessionId)
+                                    return acceptedCount;
+                                try {
+                                    const db = openPipelineDb();
+                                    try {
+                                        return loadCDFComponents(db, sessionId).length;
+                                    }
+                                    finally {
+                                        db.close();
+                                    }
+                                }
+                                catch {
+                                    return acceptedCount;
+                                }
+                            })();
+                            acceptedCount = remaining;
+                        }
+                        const allowEmptyDeleteAll = acceptedCount === 0;
+                        allowEmptyDeleteAllRef.current = allowEmptyDeleteAll;
+                        update({ finalReviewPassed: true, allowEmptyDeleteAll });
                         if (noPush) {
-                            update({ generatedAcceptedCount: accepted });
+                            update({ generatedAcceptedCount: acceptedCount });
                             void startSaveFlow();
                             return;
                         }
                         if (noSave) {
-                            update({ generatedAcceptedCount: accepted });
+                            update({ generatedAcceptedCount: acceptedCount });
                             const { extractSessionId, tokensPath } = sessionRef.current;
                             void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
                             return;
                         }
                         if (autoAcceptScope) {
-                            // Headless run with neither --no-save nor --no-push: pick the
-                            // default "both" path automatically to preserve scripted
-                            // (auto-accept-scope) UX from before the gate gained a third
-                            // option. Operators who want push-only must pass --no-save.
-                            update({ generatedAcceptedCount: accepted });
+                            update({ generatedAcceptedCount: acceptedCount });
                             void runSaveAndPush();
                             return;
                         }
-                        update({ generatedAcceptedCount: accepted, step: 'push-decision-gate' });
+                        update({ generatedAcceptedCount: acceptedCount, step: 'push-decision-gate' });
                     }, onQuit: () => process.exit(0) }));
             }
             case 'push-decision-gate': {
@@ -1557,22 +1570,13 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                             void runPreview(extractSessionId, tokensPath, state.spaceId, state.environmentId, state.cmaToken, state.host);
                             return;
                         }
-                        // save-only
                         void startSaveFlow();
                     }, onQuit: () => process.exit(0) }));
             }
             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);
-                    }, 
-                    // 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) => {
+                    }, onContinue: (spaceId, environmentId, cmaToken, host) => {
                         void confirmCredentials(spaceId, environmentId, cmaToken, host);
                     }, onRetryPrefetch: state.generatePrefetchStatus === 'failed' && sessionRef.current.extractSessionId
                         ? () => {
@@ -1580,39 +1584,27 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                             void startGeneratePrefetch(sid, state.tokensPath);
                         }
                         : undefined, onSkip: () => {
-                        // Skip-credentials: mark the wizard as skipped, clear any
-                        // stale credentialsError banner, and advance through the
-                        // normal post-credentials branch. The in-flight generate
-                        // prefetch (PR #54) is intentionally NOT cancelled here —
-                        // the operator still wants to see classifications.
                         update({ credentialsSkipped: true, credentialsError: '' });
                         void advanceAfterCredentialsValidated();
                     }, onQuit: () => {
                         cancelGeneratePrefetch();
                         process.exit(0);
                     } }));
-            // 'credential-test-gate' is intentionally NOT rendered as a dedicated
-            // screen any more (the post-#54 inline credentials-validating status made
-            // the gate redundant). The step value is kept in the union for back-compat
-            // with existing imports/tests but is never actually set as a step —
-            // `advanceWithCredentials` calls `validateCredentials` directly.
-            //
-            // 'validating-credentials' is intentionally NOT rendered as a dedicated
-            // screen any more (see CredentialsStep `validating` prop). The step
-            // 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':
+            case 'preview-gate': {
+                // Only offer "[e] Edit definitions" when the manifest actually has
+                // components to edit. In the delete-all / empty case the manifest is
+                // present-but-empty (only $schema), so editing would dead-end on the
+                // "No generated definitions found" screen.
+                const editableComponentCount = Object.keys(state.manifest?.componentsManifest ?? {}).filter((k) => k !== '$schema').length;
                 return (_jsx(WizardPreviewStep, { preview: state.serverPreview, spaceId: state.spaceId, environmentId: state.environmentId, stepNumber: totalSteps, totalSteps: totalSteps, onConfirm: (acknowledge) => {
                         void runPush(state.manifest, state.spaceId, state.environmentId, state.cmaToken, state.host, acknowledge, state.serverPreview);
-                    }, onEdit: () => {
-                        void runEditFromPreview();
-                    }, onSaveFiles: () => {
+                    }, ...(editableComponentCount > 0 ? { onEdit: () => void runEditFromPreview() } : {}), onSaveFiles: () => {
                         void startSaveFlow();
                     }, onQuit: () => process.exit(0) }));
+            }
             case 'pushing':
                 return _jsx(PushingStep, { stepNumber: totalSteps, totalSteps: totalSteps, progress: state.pushProgress });
             case 'path-prompt':
@@ -1664,10 +1656,6 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             }
             case 'error':
                 return (_jsx(ErrorStep, { stepName: state.errorStep, message: state.errorMessage, onExit: () => process.exit(1), onRetryCredentials: state.errorAllowCredentialRetry ? () => update({ step: 'credentials', credentialsError: '' }) : undefined }));
-            // 'validating-credentials' kept in the WizardStep union for back-compat
-            // but is no longer reachable as a step (validateCredentials toggles the
-            // `credentialsValidating` boolean while leaving step on 'credentials').
-            // Default-return null so the switch is exhaustive.
             default:
                 return null;
         }