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

package/dist/src/import/command.js

@@ -2,6 +2,7 @@ import { resolve, join } from 'node:path';
 import { runPipeline } from './orchestrator.js';
 import { resolveAutoFilter } from './auto-filter-resolve.js';
 import { resolveAgent, resolveModel } from './agent-model-resolve.js';
+import { resolveCompositionMode } from '../lib/composition-mode.js';
 import { readExperiencesCredentials } from '../credentials-store.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../host-utils.js';
 import { replayRun, modifyRun } from '../runs/replay-helpers.js';
@@ -28,7 +29,7 @@ export function registerImportCommand(program) {
         .option('--skip-analyze', 'Skip the analyze step (uses most recent extract session)')
         .option('--skip-generate', 'Skip the generate step (uses most recent generate session)')
         .option('--print', 'Write components.json to --out after generation')
-        .option('--skip-apply', 'Skip pushing to Contentful (stops after generate)')
+        .option('--skip-apply', '(deprecated alias for --no-push) Skip pushing to Contentful')
         .option('--no-cache', 'Re-run all steps even if output already exists')
         .option('--yes', 'Skip interactive confirmation in apply push')
         .option('--verbose', 'Show full agent output and all entity progress')
@@ -38,10 +39,19 @@ export function registerImportCommand(program) {
         .option('--dry-run', "(deprecated, will change semantics in a future release) Print generate components prompt without invoking the agent. Use --print-prompt for the same behaviour explicitly, or '--dry-run --no-push' for the upcoming manifest-preview semantics.")
         .option('--print-prompt', 'Print the generate components prompt without invoking the agent. Replaces the legacy --dry-run prompt-print behaviour on this command.')
         .option('--auto-accept-scope', 'Accept all extracted components without prompting (for scripted/non-TTY callers)')
+        .option('--composite', 'Import embedded-component hierarchy (opt in; default is atomic)')
+        .option('--atomic', 'Import flat components with no embedded-component hierarchy (default)')
+        .option('--composition-map <path>', 'Consume a hand-authored parent→children interchange map (implies --composite)')
+        .option('--composition-agent', 'Opt into agentic mapping resolution when deterministic sources find no groups (implies --composite)')
+        .option('--composition-refresh', 'Bypass the composition cache and re-resolve from scratch, forcing the agent to run (implies --composite)')
+        .option('--composition-agent-mode <mode>', "Agent mode: 'parser' (agent writes a sandboxed parser, default) or 'edges' (agent lists edges)")
+        .option('--generate-map <path>', 'Also write a composition-map skeleton from resolved edges during extract (implies --composite)')
+        .option('--prompt <stage=value>', 'Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md', (v, acc) => [...acc, v], [])
+        .option('--auto-reject-cycles', 'Automatically reject components involved in slot cycles and retry')
         .option('--auto-filter', 'Force the AI auto-filter ON (overrides the credentials.json autoFilter preference)')
         .option('--no-auto-filter', 'Skip the automatic AI pre-filter; jump straight to manual scope-gate (overrides the credentials.json autoFilter preference; no-op when paired with --auto-accept-scope)')
         .option('--no-live-preview', 'Skip the automatic preview re-run after each FieldEditor save (no-op when paired with --auto-accept-scope)')
-        .option('--no-push', 'Run extract → scope-gate → generate → final-review and exit without pushing to Contentful (no credentials prompt; live preview disabled)')
+        .option('--no-push', 'Import without pushing to Contentful. Interactive: runs the full wizard (extract → scope-gate → generate → final-review) and stops before push. Non-interactive (piped/CI): runs headless through generate. No credentials needed either way.')
         .option('--no-save', 'Push without writing components.json / tokens.json to disk (default: save AND push)')
         .option('--out-dir <path>', 'Save components.json / tokens.json to this directory; bypasses the inline save-path prompt')
         .option('--on-conflict <mode>', "How to handle existing components.json / tokens.json at the save path: 'overwrite' replaces files, 'skip' writes to a timestamped subdirectory, 'fail' exits non-zero. Skips the wizard's interactive conflict gate when set.", (value) => {
@@ -59,9 +69,31 @@ export function registerImportCommand(program) {
         .option('--save-as-new', 'Only valid with --modify: always save to a new path (prompts for one)')
         .option('--force', 'Bypass staleness checks when paired with --push-from-run or --modify.')
         .action(async (opts) => {
-        // ── --push-from-run handling ───────────────────────────────────────
-        // Push-only replay of a prior run. Mutex checks happen *before* any
-        // side effects (no DB reads, no wizard render).
+        // --modify and --push-from-run resume a recorded session; the composition
+        // mode comes from that run's record, so composition flags on the command
+        // line don't apply. Warn and clear them rather than let them mislead.
+        if (opts.modify !== undefined || opts.pushFromRun !== undefined) {
+            const passedCompositionFlags = [
+                opts.composite ? '--composite' : null,
+                opts.atomic ? '--atomic' : null,
+                opts.compositionMap ? '--composition-map' : null,
+                opts.compositionAgent ? '--composition-agent' : null,
+                opts.compositionAgentMode ? '--composition-agent-mode' : null,
+                opts.compositionRefresh ? '--composition-refresh' : null,
+                opts.generateMap ? '--generate-map' : null,
+            ].filter((f) => f !== null);
+            if (passedCompositionFlags.length > 0) {
+                const entry = opts.modify !== undefined ? '--modify' : '--push-from-run';
+                process.stderr.write(`Note: ${passedCompositionFlags.join(', ')} ignored with ${entry} — composition mode comes from the recorded run.\n`);
+                opts.composite = undefined;
+                opts.atomic = undefined;
+                opts.compositionMap = undefined;
+                opts.compositionAgent = undefined;
+                opts.compositionAgentMode = undefined;
+                opts.compositionRefresh = undefined;
+                opts.generateMap = undefined;
+            }
+        }
         if (opts.pushFromRun !== undefined) {
             if (opts.modify !== undefined) {
                 process.stderr.write('Error: --push-from-run and --modify are mutually exclusive. --push-from-run pushes the recorded session; --modify re-opens the wizard for edits.\n');
@@ -106,7 +138,6 @@ export function registerImportCommand(program) {
                 return;
             }
         }
-        // ── --modify handling ──────────────────────────────────────────────
         if (opts.modify !== undefined) {
             if (opts.project !== '.') {
                 process.stderr.write('Error: --modify and --project are mutually exclusive. The project path is read from the recorded run.\n');
@@ -154,10 +185,6 @@ export function registerImportCommand(program) {
             process.exit(1);
             return;
         }
-        // ── --raw-tokens validation ─────────────────────────────────────────
-        // The raw-tokens path is a source file the wizard hands to
-        // `generate tokens --raw-tokens <path>`. Validate at parse time so
-        // operators get an immediate error before the wizard renders.
         if (opts.rawTokens !== undefined) {
             if (opts.tokens !== undefined) {
                 process.stderr.write('Error: --raw-tokens and --tokens are mutually exclusive: --raw-tokens is the source file to classify, --tokens is a pre-classified DTCG sidecar.\n');
@@ -182,9 +209,16 @@ export function registerImportCommand(program) {
             process.stderr.write(promptFlags.deprecationNotice);
         }
         const dryRunForward = promptFlags.forwardDryRun;
+        // "Don't push" is one user intent (--no-push); --skip-apply is a
+        // deprecated alias. Interactive runs (TTY) take the wizard and stop
+        // before push; non-interactive runs take the headless pipeline and stop
+        // after generate. Either way no credentials are required.
+        const noPushRequested = opts.push === false || opts.skipApply === true;
         const isHeadless = opts.skipAnalyze ||
             opts.skipGenerate ||
-            opts.skipApply ||
+            // A "don't push" request on a non-TTY is a headless intent (the wizard
+            // needs a TTY); in a TTY it stays interactive and is NOT headless.
+            (noPushRequested && !process.stdout.isTTY) ||
             !!opts.spaceId ||
             !!opts.environmentId ||
             !!opts.cmaToken ||
@@ -193,7 +227,7 @@ export function registerImportCommand(program) {
             false;
         const autoAcceptScope = opts.autoAcceptScope ?? false;
         if (!process.stdout.isTTY && !isHeadless && !autoAcceptScope) {
-            process.stderr.write('Error: experiences import is interactive. Pass --auto-accept-scope, or use a headless mode by providing credentials (--space-id, --environment-id, --cma-token) or one of --skip-analyze, --skip-generate, --skip-apply, --yes, --dry-run, --print-prompt.\n');
+            process.stderr.write('Error: experiences import is interactive. Pass --auto-accept-scope, or use a headless mode by providing credentials (--space-id, --environment-id, --cma-token) or one of --no-push, --skip-analyze, --skip-generate, --yes, --dry-run, --print-prompt.\n');
             process.exit(1);
             return;
         }
@@ -202,15 +236,9 @@ export function registerImportCommand(program) {
             const { createElement } = await import('react');
             const { WizardApp } = await import('./tui/WizardApp.js');
             const creds = await readExperiencesCredentials();
-            // Parity-audit Q4: resolve --agent / --model overrides against the
-            // stored credentials.json so both flags are functional for the
-            // wizard path. Flag wins, then stored value, then default.
             const resolvedAgent = resolveAgent(opts.agent, creds.agent);
             const resolvedModel = resolveModel(opts.model, creds.agentModel);
-            // ── Run picker decision ─────────────────────────────────────────
-            // When runs.json has prior entries and the operator didn't ask for
-            // a specific entry point, open the wizard with the run picker. The
-            // helper enforces every gate (TTY, conflicting flags, file state).
+            const resolvedCompositionMode = resolveCompositionMode(opts, creds.compositionMode);
             const pickerDecision = await shouldShowRunPicker({
                 flags: {
                     ...(opts.pushFromRun !== undefined ? { pushFromRun: opts.pushFromRun } : {}),
@@ -222,10 +250,6 @@ export function registerImportCommand(program) {
                 isTTY: !!process.stdin.isTTY,
             });
             let pickerSelection = null;
-            // Ink `unmount` handle captured after `render(...)` below so the
-            // picker callback can tear down the wizard cleanly. Prior to this
-            // fix the callback did `setImmediate(() => process.exit(0))`, which
-            // killed the process before `dispatchPickerSelection` could run.
             let unmountInk = null;
             const pickerProps = {};
             if (pickerDecision.shouldShow) {
@@ -245,10 +269,18 @@ export function registerImportCommand(program) {
                 initialProjectPath: opts.project !== '.' ? resolve(opts.project) : undefined,
                 host: opts.host,
                 autoAcceptScope,
+                autoRejectCycles: opts.autoRejectCycles ?? false,
+                compositionMode: resolvedCompositionMode,
+                ...(opts.compositionMap ? { compositionMap: opts.compositionMap } : {}),
+                ...(opts.compositionAgent ? { compositionAgent: true } : {}),
+                ...(opts.compositionAgentMode ? { compositionAgentMode: opts.compositionAgentMode } : {}),
+                ...(opts.compositionRefresh ? { compositionRefresh: true } : {}),
+                ...(opts.generateMap ? { generateMap: opts.generateMap } : {}),
+                ...(opts.prompt && opts.prompt.length > 0 ? { promptOverrides: opts.prompt } : {}),
                 noCache: opts.cache === false,
                 autoFilter: resolveAutoFilter({ autoFilter: opts.autoFilter }, creds.autoFilter),
                 livePreview: opts.livePreview !== false,
-                noPush: opts.push === false,
+                noPush: noPushRequested,
                 noSave: opts.save === false,
                 ...(opts.outDir ? { outDirOverride: resolve(opts.outDir) } : {}),
                 ...(opts.onConflict ? { onConflictMode: opts.onConflict } : {}),
@@ -259,10 +291,6 @@ export function registerImportCommand(program) {
             }));
             unmountInk = unmount;
             await waitUntilExit();
-            // ── Picker dispatch ─────────────────────────────────────────────
-            // If the operator picked a run, route into replayRun / modifyRun.
-            // dispatchPickerSelection lives in ./picker-dispatch.ts so this
-            // decision is testable without an Ink runtime.
             if (pickerSelection) {
                 await dispatchPickerSelection(pickerSelection, {
                     ...(opts.spaceId ? { spaceId: opts.spaceId } : {}),
@@ -278,21 +306,23 @@ export function registerImportCommand(program) {
             }
             return;
         }
-        const skipApply = opts.skipApply ?? false;
+        // --no-push (and its deprecated alias --skip-apply) both mean "stop
+        // before the push" on the headless path — so neither requires credentials.
+        const skipApply = noPushRequested;
         const spaceId = opts.spaceId ?? process.env['CONTENTFUL_SPACE_ID'];
         const environmentId = opts.environmentId ?? process.env['CONTENTFUL_ENVIRONMENT_ID'];
         const cmaToken = opts.cmaToken ?? process.env['CONTENTFUL_MANAGEMENT_TOKEN'];
         if (!skipApply && (!spaceId || !environmentId || !cmaToken)) {
-            process.stderr.write('Error: --space-id (or CONTENTFUL_SPACE_ID), --environment-id (or CONTENTFUL_ENVIRONMENT_ID), and --cma-token (or CONTENTFUL_MANAGEMENT_TOKEN) are required unless --skip-apply is set.\n');
+            process.stderr.write('Error: --space-id (or CONTENTFUL_SPACE_ID), --environment-id (or CONTENTFUL_ENVIRONMENT_ID), and --cma-token (or CONTENTFUL_MANAGEMENT_TOKEN) are required unless --no-push is set.\n');
             process.exit(1);
             return;
         }
         const projectRoot = resolve(opts.project);
         const outDir = opts.out ? resolve(opts.out) : join(projectRoot, '.contentful');
-        // Parity-audit Q4: also honor stored agent/model in headless mode.
         const headlessCreds = await readExperiencesCredentials();
         const headlessAgent = resolveAgent(opts.agent, headlessCreds.agent);
         const headlessModel = resolveModel(opts.model, headlessCreds.agentModel);
+        const headlessCompositionMode = resolveCompositionMode(opts, headlessCreds.compositionMode);
         const result = await runPipeline({
             project: projectRoot,
             out: outDir,
@@ -317,6 +347,14 @@ export function registerImportCommand(program) {
             host: opts.host,
             dryRun: dryRunForward,
             selectPromptPath: opts.selectPromptPath,
+            autoRejectCycles: opts.autoRejectCycles ?? false,
+            compositionMode: headlessCompositionMode,
+            ...(opts.compositionMap ? { compositionMap: opts.compositionMap } : {}),
+            ...(opts.compositionAgent ? { compositionAgent: true } : {}),
+            ...(opts.compositionAgentMode ? { compositionAgentMode: opts.compositionAgentMode } : {}),
+            ...(opts.compositionRefresh ? { compositionRefresh: true } : {}),
+            ...(opts.generateMap ? { generateMap: opts.generateMap } : {}),
+            ...(opts.prompt && opts.prompt.length > 0 ? { promptOverrides: opts.prompt } : {}),
         }, (line) => process.stderr.write(line + '\n'));
         const hasFailed = result.steps.some((s) => s.status === 'failed');
         if (!process.stdout.isTTY) {

package/dist/src/import/cycle-auto-reject.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentGraphNode } from '../analyze/composite-closure.js';
+export declare function computeCycleAutoRejectTargets(slotCycles: Array<{
+    path: string[];
+}>, graph: ComponentGraphNode[]): Set<string>;

package/dist/src/import/cycle-auto-reject.js

@@ -0,0 +1,14 @@
+import { findAllAncestors } from '../analyze/lineage.js';
+export function computeCycleAutoRejectTargets(slotCycles, graph) {
+    const targets = new Set();
+    const participants = new Set();
+    for (const cyc of slotCycles)
+        for (const p of cyc.path)
+            participants.add(p);
+    for (const p of participants) {
+        targets.add(p);
+        for (const anc of findAllAncestors(p, graph))
+            targets.add(anc);
+    }
+    return targets;
+}

package/dist/src/import/orchestrator.d.ts

@@ -1,3 +1,4 @@
+import type { CompositionMode } from '../lib/composition-mode.js';
 export interface PipelineOptions {
     project: string;
     out: string;
@@ -23,6 +24,15 @@ export interface PipelineOptions {
     deselect?: string[];
     /** Forwarded to the spawned `analyze select-agent` subprocess. */
     selectPromptPath?: string;
+    /** When true, auto-reject cycle participants and retry push instead of surfacing an error. */
+    autoRejectCycles?: boolean;
+    compositionMode?: CompositionMode;
+    compositionMap?: string;
+    compositionAgent?: boolean;
+    compositionAgentMode?: string;
+    compositionRefresh?: boolean;
+    generateMap?: string;
+    promptOverrides?: string[];
 }
 export interface StepResult {
     step: string;
@@ -36,19 +46,22 @@ export interface PipelineResult {
     session: string;
     project: string;
     steps: StepResult[];
+    cycleError?: {
+        report: string[];
+    };
 }
+export declare const SLOT_CYCLE_MARKER = "manifest:components/slot-cycles";
+export declare function isSlotCycleError(result: {
+    exitCode: number;
+    stderr: string;
+}): boolean;
+export declare function extractCycleReport(stderr: string): string[];
+export declare function parseCycleComponentNames(report: string[]): string[];
 export declare function isPreviewValidationError(result: {
     exitCode: number;
     stderr: string;
 }): boolean;
 export declare function parseOffendingComponentNames(output: string): string[];
-/**
- * Build the apply-push StepResult record. Centralizes the success/failure
- * shape so excludedByValidationRetry is recorded consistently in both
- * branches — previously the total-failure branch dropped it, leaving users
- * with a failed pipeline and no audit trail of what was auto-excluded
- * before the retry loop gave up.
- */
 export declare function buildPushStepResult(args: {
     created: number;
     updated: number;

package/dist/src/import/orchestrator.js

@@ -2,7 +2,8 @@ import { mkdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
-import { openPipelineDb, getOrCreateSession, createStep, updateStep, findLatestSessionForCommand, } from '../session/db.js';
+import { openPipelineDb, getOrCreateSession, createStep, updateStep, findLatestSessionForCommand, loadCDFComponents, } from '../session/db.js';
+import { detectSlotCycles, formatSlotCycleReport } from '../apply/command.js';
 import { PREVIEW_ERROR_PREFIX, VALIDATION_FAILED_CODE, parsePreviewValidationErrors } from '../apply/api-client.js';
 import { buildPostPushUrl } from '../lib/contentful-urls.js';
 import { getDebugLogger, debugEnvForSubprocess } from '../lib/debug-logger.js';
@@ -43,27 +44,34 @@ async function runStep(args, cliPath, env = {}, streamStderr = false) {
     });
 }
 const MAX_VALIDATION_RETRIES = Number(process.env['EDS_MAX_VALIDATION_RETRIES'] ?? 2);
+export const SLOT_CYCLE_MARKER = 'manifest:components/slot-cycles';
+export function isSlotCycleError(result) {
+    return result.exitCode !== 0 && result.stderr.includes(SLOT_CYCLE_MARKER);
+}
+export function extractCycleReport(stderr) {
+    return stderr.split('\n').filter((line) => line.trim());
+}
+export function parseCycleComponentNames(report) {
+    const names = [];
+    for (const line of report) {
+        const m = line.match(/Fix: remove '([^']+)' from /);
+        if (m)
+            names.push(m[1]);
+    }
+    return [...new Set(names)];
+}
 export function isPreviewValidationError(result) {
     return (result.exitCode !== 0 &&
         result.stderr.includes(`${PREVIEW_ERROR_PREFIX} 422`) &&
         result.stderr.includes(VALIDATION_FAILED_CODE));
 }
 export function parseOffendingComponentNames(output) {
-    // The 422 body is appended to the ApiError message by the constructor and
-    // written to stderr by die(). Extract the JSON portion by finding the first '{'.
     const jsonStart = output.indexOf('{');
     if (jsonStart === -1)
         return [];
     const errors = parsePreviewValidationErrors(output.slice(jsonStart));
     return [...new Set(errors.map((e) => e.componentName))];
 }
-/**
- * Build the apply-push StepResult record. Centralizes the success/failure
- * shape so excludedByValidationRetry is recorded consistently in both
- * branches — previously the total-failure branch dropped it, leaving users
- * with a failed pipeline and no audit trail of what was auto-excluded
- * before the retry loop gave up.
- */
 export function buildPushStepResult(args) {
     const { created, updated, failed, durationMs, stderr, excludedByRetry, totalFailure } = args;
     const excludedDetail = excludedByRetry.length > 0 ? { excludedByValidationRetry: excludedByRetry } : {};
@@ -106,13 +114,11 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
     await mkdir(outDir, { recursive: true });
     const steps = [];
     let stepNum = 0;
-    // print components is an optional step; adjust total accordingly
     const totalSteps = 4 + (opts.print ? 1 : 0);
     function stepLabel(name) {
         stepNum++;
         return `  Step ${stepNum}/${totalSteps}  ${name}  `;
     }
-    // ── Step 1: analyze extract ──────────────────────────────────────────────
     const analyzeLabel = stepLabel('Statically analyzing project');
     const analyzeSkipped = !opts.noCache && opts.skipAnalyze;
     let extractSessionId = null;
@@ -123,7 +129,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             status: 'skipped',
             reason: '--skip-analyze',
         });
-        // Try to find a prior extract session to hand to downstream steps
         const prior = findLatestSessionForCommand(db, 'analyze extract');
         extractSessionId = prior ?? null;
     }
@@ -133,6 +138,23 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
         });
         const t0 = Date.now();
         const analyzeArgs = ['analyze', 'extract', '--project', projectRoot];
+        if (opts.compositionMode === 'composite') {
+            analyzeArgs.push('--composite');
+            if (opts.compositionMap)
+                analyzeArgs.push('--composition-map', opts.compositionMap);
+            if (opts.compositionAgent)
+                analyzeArgs.push('--composition-agent');
+            if (opts.compositionAgentMode)
+                analyzeArgs.push('--composition-agent-mode', opts.compositionAgentMode);
+            if (opts.compositionRefresh)
+                analyzeArgs.push('--composition-refresh');
+            if (opts.generateMap)
+                analyzeArgs.push('--generate-map', opts.generateMap);
+            for (const p of opts.promptOverrides ?? [])
+                analyzeArgs.push('--prompt', p);
+            if (opts.agent)
+                analyzeArgs.push('--agent', opts.agent);
+        }
         const r = await runStep(analyzeArgs, cliPath);
         const durationMs = Date.now() - t0;
         if (r.exitCode !== 0) {
@@ -149,7 +171,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             db.close();
             return { session: sessionId, project: projectRoot, steps };
         }
-        // Read session ID from DB — avoids dependence on subprocess stdout format.
         extractSessionId = findLatestSessionForCommand(db, 'analyze extract') ?? null;
         const componentMatch = /Extracted (\d+) component/.exec(r.stderr);
         const componentCount = componentMatch ? Number(componentMatch[1]) : 0;
@@ -164,7 +185,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             detail: { components: componentCount },
         });
     }
-    // ── Step 2: analyze select ───────────────────────────────────────────────
     const editLabel = stepLabel('Filtering components');
     if (analyzeSkipped) {
         progressWriter(`${editLabel}–  skipped (--skip-analyze)`);
@@ -179,7 +199,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             extractSession: extractSessionId,
         });
         const t0Edit = Date.now();
-        // Use agentic select when an agent is available and no manual select/deselect patterns are given.
         const useAgentSelect = !opts.selectAll && (!opts.select || opts.select.length === 0) && (!opts.deselect || opts.deselect.length === 0);
         let editArgs;
         if (useAgentSelect) {
@@ -202,7 +221,7 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             else if (opts.deselect && opts.deselect.length > 0) {
                 for (const p of opts.deselect)
                     editArgs.push('--deselect', p);
-                editArgs.push('--select-all'); // select-all with deselect patterns = select all except matches
+                editArgs.push('--select-all');
             }
             else {
                 editArgs.push('--select-all');
@@ -245,7 +264,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             reason: 'no extract session',
         });
     }
-    // ── Step 3: generate components ──────────────────────────────────────────
     if (opts.skipGenerate) {
         const generateLabel = stepLabel('Categorizing component props');
         progressWriter(`${generateLabel}–  skipped (--skip-generate)`);
@@ -301,7 +319,29 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
         progressWriter(`${generateLabel}✓  components stored locally  (${(durationMs / 1000).toFixed(1)}s)`);
         steps.push({ step: 'generate components', status: 'complete', durationMs });
     }
-    // ── Step 4 (optional): print components ─────────────────────────────────
+    // Block save or push when the accepted set still contains a slot cycle.
+    // Skipped under --auto-reject-cycles, which delegates to the push-path
+    // retry loop below (reject cycle members, then retry) instead of blocking.
+    if (extractSessionId && !opts.autoRejectCycles) {
+        const acceptedCycles = (() => {
+            try {
+                return detectSlotCycles(loadCDFComponents(db, extractSessionId));
+            }
+            catch {
+                return [];
+            }
+        })();
+        if (acceptedCycles.length > 0) {
+            const report = formatSlotCycleReport(acceptedCycles);
+            process.stderr.write(report.join('\n') + '\n');
+            progressWriter('Slot cycle detected. The accepted components contain circular slot references — refusing to save or push.');
+            for (const line of report)
+                progressWriter(line);
+            steps.push({ step: 'cycle gate', status: 'failed', error: report.join('\n') });
+            db.close();
+            return { session: sessionId, project: projectRoot, steps, cycleError: { report } };
+        }
+    }
     if (opts.print) {
         const printLabel = stepLabel('Writing components.json');
         const printArgs = ['print', 'components', '--out', componentsPath];
@@ -331,7 +371,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
         progressWriter(`${printLabel}✓  components.json written  (${(durationMs / 1000).toFixed(1)}s)`);
         steps.push({ step: 'print components', status: 'complete', durationMs });
     }
-    // ── Step 4/5: apply push ─────────────────────────────────────────────────
     const applyLabelText = opts.spaceId && opts.environmentId
         ? `Applying changes to Space: ${opts.spaceId} Environment: ${opts.environmentId}`
         : 'Applying changes to Contentful';
@@ -361,10 +400,6 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             '--cma-token',
             opts.cmaToken,
         ];
-        // Components are stored under the extract session ID (generate command uses resolveSessionId
-        // which returns the passed --session value, i.e. the extract session). Pass that directly so
-        // apply push reads from the DB without needing a components.json file.
-        // Fall back to --components so the step fails with a clear error rather than a generic one.
         if (extractSessionId) {
             pushArgs.push('--session', extractSessionId);
         }
@@ -379,28 +414,20 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             pushArgs.push('--host', opts.host);
         if (opts.verbose)
             pushArgs.push('--verbose');
-        pushArgs.push('--yes'); // always non-interactive in subprocess context
+        pushArgs.push('--yes');
         const pushStepId = createStep(db, sessionId, 'apply push', {
             components: componentsPath,
         });
         const t0 = Date.now();
         let r = await runStep(pushArgs, cliPath, { FORCE_COLOR: '1' }, true);
-        // Bounded retry loop: on a preview-phase 422 with a parseable ValidationFailed
-        // body, exclude the offending components and re-run apply push.
         const excludedByRetry = [];
         let validationRetryCount = 0;
         while (validationRetryCount < MAX_VALIDATION_RETRIES && isPreviewValidationError(r) && extractSessionId) {
             const offenders = parseOffendingComponentNames(r.stderr + r.stdout);
             if (offenders.length === 0)
-                break; // unparseable body — give up and surface original error
+                break;
             process.stderr.write(`[retry ${validationRetryCount + 1}/${MAX_VALIDATION_RETRIES}] Preview validation failed — excluding ${offenders.join(', ')} and retrying\n`);
             excludedByRetry.push(...offenders);
-            // No --select-all here: that would route through runNonInteractive's
-            // rebuild path, which DELETEs all rows and re-inserts with default
-            // status='extracted' — wiping the post-`generate components` state
-            // (status='generated' + raw_props.cdf_type) the next apply push reads.
-            // The bare --exclude-components form takes the rejectComponentsByName
-            // early-return: pure UPDATE, no rebuild.
             const rejectArgs = [
                 'analyze',
                 'select',
@@ -411,7 +438,7 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             ];
             const rejectResult = await runStep(rejectArgs, cliPath);
             if (rejectResult.exitCode !== 0)
-                break; // selection step failed — give up
+                break;
             r = await runStep(pushArgs, cliPath, { FORCE_COLOR: '1' }, true);
             validationRetryCount++;
         }
@@ -433,6 +460,83 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             ? (pushResult.componentTypes?.failed ?? 0) + (pushResult.designTokens?.failed ?? 0)
             : Number(/(\d+) failed/.exec(r.stdout + r.stderr)?.[1] ?? 0);
         const totalPushed = created + updated + failed;
+        if (isSlotCycleError(r)) {
+            const report = extractCycleReport(r.stderr);
+            if (opts.autoRejectCycles && extractSessionId) {
+                const cycleNames = parseCycleComponentNames(report);
+                if (cycleNames.length > 0) {
+                    process.stderr.write(`[cycle-retry] Slot cycle detected — excluding ${cycleNames.join(', ')} and retrying\n`);
+                    const rejectArgs = [
+                        'analyze',
+                        'select',
+                        '--session',
+                        extractSessionId,
+                        '--exclude-components',
+                        cycleNames.join(','),
+                    ];
+                    const rejectResult = await runStep(rejectArgs, cliPath);
+                    if (rejectResult.exitCode === 0) {
+                        const retryT0 = Date.now();
+                        const retryR = await runStep(pushArgs, cliPath, { FORCE_COLOR: '1' }, true);
+                        const retryDurationMs = Date.now() - t0 + (Date.now() - retryT0);
+                        if (isSlotCycleError(retryR)) {
+                            const retryReport = extractCycleReport(retryR.stderr);
+                            updateStep(db, pushStepId, 'failed', {}, retryR.stderr);
+                            progressWriter(`${pushLabel}✗  failed (${(retryDurationMs / 1000).toFixed(1)}s)`);
+                            progressWriter('Slot cycle detected after auto-reject retry. The manifest still contains circular slot references.');
+                            for (const line of retryReport)
+                                progressWriter(line);
+                            steps.push(buildPushStepResult({
+                                created,
+                                updated,
+                                failed,
+                                durationMs: retryDurationMs,
+                                stderr: retryR.stderr,
+                                excludedByRetry: [...excludedByRetry, ...cycleNames],
+                                totalFailure: true,
+                            }));
+                            db.close();
+                            return { session: sessionId, project: projectRoot, steps, cycleError: { report: retryReport } };
+                        }
+                        if (retryR.exitCode !== 0) {
+                            updateStep(db, pushStepId, 'failed', {}, retryR.stderr);
+                            progressWriter(`${pushLabel}✗  failed (${(retryDurationMs / 1000).toFixed(1)}s)`);
+                            steps.push(buildPushStepResult({
+                                created,
+                                updated,
+                                failed,
+                                durationMs: retryDurationMs,
+                                stderr: retryR.stderr,
+                                excludedByRetry: [...excludedByRetry, ...cycleNames],
+                                totalFailure: true,
+                            }));
+                            db.close();
+                            return { session: sessionId, project: projectRoot, steps };
+                        }
+                        excludedByRetry.push(...cycleNames);
+                        r = retryR;
+                    }
+                }
+            }
+            if (isSlotCycleError(r)) {
+                updateStep(db, pushStepId, 'failed', {}, r.stderr);
+                progressWriter(`${pushLabel}✗  failed (${(durationMs / 1000).toFixed(1)}s)`);
+                progressWriter('Slot cycle detected. The manifest contains circular slot references that would block the push.');
+                for (const line of report)
+                    progressWriter(line);
+                steps.push(buildPushStepResult({
+                    created,
+                    updated,
+                    failed,
+                    durationMs,
+                    stderr: r.stderr,
+                    excludedByRetry,
+                    totalFailure: true,
+                }));
+                db.close();
+                return { session: sessionId, project: projectRoot, steps, cycleError: { report } };
+            }
+        }
         if (r.exitCode !== 0 && (totalPushed === 0 || failed === totalPushed)) {
             // Total failure — nothing was pushed
             updateStep(db, pushStepId, 'failed', {}, r.stderr);

package/dist/src/import/strip-allowed-components.d.ts

@@ -0,0 +1,18 @@
+import type { CDFComponentEntry } from '@contentful/experience-design-system-types';
+/**
+ * Atomic-mode normalization (spec T8, option a): keep every slot's structure
+ * but drop its `$allowedComponents` composition constraint. Applied over the
+ * loaded component array regardless of source (`--session` or `--components`),
+ * so the atomic bypass cannot leak a live composition link into the pushed
+ * manifest. Starving `$allowedComponents` at this single point also makes
+ * slot-cycle detection structurally return zero (see T12).
+ *
+ * Returns a new array with cloned entries; inputs are not mutated.
+ */
+export declare function stripAllowedComponents(components: Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>): Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>;

package/dist/src/import/strip-allowed-components.js

@@ -0,0 +1,22 @@
+/**
+ * Atomic-mode normalization (spec T8, option a): keep every slot's structure
+ * but drop its `$allowedComponents` composition constraint. Applied over the
+ * loaded component array regardless of source (`--session` or `--components`),
+ * so the atomic bypass cannot leak a live composition link into the pushed
+ * manifest. Starving `$allowedComponents` at this single point also makes
+ * slot-cycle detection structurally return zero (see T12).
+ *
+ * Returns a new array with cloned entries; inputs are not mutated.
+ */
+export function stripAllowedComponents(components) {
+    return components.map(({ key, entry }) => {
+        if (!entry.$slots)
+            return { key, entry };
+        const $slots = {};
+        for (const [slotName, slotDef] of Object.entries(entry.$slots)) {
+            const { $allowedComponents: _dropped, ...rest } = slotDef;
+            $slots[slotName] = rest;
+        }
+        return { key, entry: { ...entry, $slots } };
+    });
+}