@contentful/experience-design-system-cli 2.12.4-dev-build-a1a979f.0 → 2.12.4-dev-build-9c819d8.0

package/dist/package.json

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

package/dist/src/analyze/command.js

@@ -6,7 +6,8 @@ import { extractComponents } from './extract/pipeline.js';
 import { AnalyzeView } from './tui/AnalyzeView.js';
 import { registerAnalyzeEditCommand } from './select/command.js';
 import { registerAnalyzeSelectAgentCommand } from './select-agent/command.js';
-import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, } from '../session/db.js';
+import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, storeSlotCycles, } from '../session/db.js';
+import { findSlotCycles, suggestCycleBreakEdge } from './cycle-detection.js';
 import { preClassifyComponent } from './pre-classify.js';
 import { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
 import { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
@@ -191,6 +192,20 @@ export function registerAnalyzeCommand(program) {
         }
         const validatedComponents = validateExtractedComponents(filteredComponents);
         storeRawComponents(db, sessionId, validatedComponents);
+        // INTEG-4401: post-extract slot-dependency cycle detection. The apply
+        // worker rejects cyclic slot graphs at push time, so we surface the
+        // same violation locally as a soft warning here (TUI reads
+        // slot_cycles) and as a hard block at manifest finalization.
+        const cycleInput = validatedComponents.map((c) => ({
+            name: c.name,
+            slots: c.slots.map((s) => ({ name: s.name, allowedComponents: s.allowedComponents })),
+        }));
+        const cycles = findSlotCycles(cycleInput);
+        const withBreaks = cycles.map((cycle) => ({
+            ...cycle,
+            suggestedBreak: suggestCycleBreakEdge(cycle, cycles),
+        }));
+        storeSlotCycles(db, sessionId, withBreaks);
         storeScannedFiles(db, sessionId, sourceFiles.map((f) => relative(projectRoot, f)));
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();

package/dist/src/analyze/cycle-detection.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Slot-dependency cycle detection.
+ *
+ * The Contentful Experience Design System backend rejects component manifests
+ * that contain slot-dependency cycles at apply time — a topo-sort in the
+ * apply worker refuses to create component types whose slot's
+ * `$allowedComponents` transitively point back at themselves. Reference:
+ * `experience-design-system-integrations` / services/design-system-sources-apply-worker/src/topo-sort.ts.
+ *
+ * We surface the same check locally so the wizard can:
+ *   1. warn the operator at extract time (soft) with sidebar badges + banner,
+ *   2. hard-block the push at manifest-finalization time before any API call.
+ *
+ * The algorithm is Johnson's — an O((V + E)(C + 1)) enumeration of all
+ * elementary (simple) cycles in a directed graph. We need *elementary*
+ * cycles rather than just cycle-existence because an operator can have
+ * multiple independent cycles they need to address separately, and each
+ * gets its own suggested fix.
+ *
+ * Johnson's algorithm reference: Donald B. Johnson, "Finding all the
+ * elementary circuits of a directed graph." SIAM J. Comput., 4(1):77-84, 1975.
+ */
+/** A directed edge in the slot-dependency graph. */
+export interface SlotEdge {
+    fromComponent: string;
+    slotName: string;
+    toComponent: string;
+}
+/** A single elementary cycle, with `path[0] === path[path.length - 1]`. */
+export interface SlotCycle {
+    /** Component names visited, with the first repeated at the end. */
+    path: string[];
+    /** Ordered edges forming the cycle. `edges.length === path.length - 1`. */
+    edges: SlotEdge[];
+}
+/** Input shape mirroring the slot definition on CDFComponentEntry. */
+export interface ComponentSlotInfo {
+    name: string;
+    slots: Array<{
+        name: string;
+        allowedComponents?: string[];
+    }>;
+}
+/**
+ * Johnson's algorithm — enumerates all elementary (simple) cycles in the
+ * slot-dependency graph. Self-loops are handled as a degenerate first pass
+ * because Tarjan's SCC decomposition assigns a self-looping node to its own
+ * single-node SCC, which Johnson's inner loop otherwise skips.
+ */
+export declare function findSlotCycles(components: ComponentSlotInfo[]): SlotCycle[];
+/**
+ * Pick which edge is the best candidate to remove to break a cycle.
+ * Heuristic: prefer removing the edge whose `toComponent` appears most often
+ * as a destination across all cycles — that "hub" node is the biggest
+ * contributor and removing an inbound edge to it likely breaks multiple
+ * cycles at once. Falls back to the first edge in the cycle for
+ * deterministic output when all candidates are tied.
+ */
+export declare function suggestCycleBreakEdge(cycle: SlotCycle, allCycles: SlotCycle[]): SlotEdge;
+/**
+ * Format a cycle for the compact banner:
+ *   `CardA → header → CardB → footer → CardA`
+ *
+ * Truncates at `maxHops` edges (default 8), inserting `…` mid-path so the
+ * beginning and end remain visible. A hop is one edge; the returned string
+ * for an n-edge cycle contains n+1 component names.
+ */
+export declare function formatCyclePath(cycle: SlotCycle, maxHops?: number): string;

package/dist/src/analyze/cycle-detection.js

@@ -0,0 +1,285 @@
+/**
+ * Slot-dependency cycle detection.
+ *
+ * The Contentful Experience Design System backend rejects component manifests
+ * that contain slot-dependency cycles at apply time — a topo-sort in the
+ * apply worker refuses to create component types whose slot's
+ * `$allowedComponents` transitively point back at themselves. Reference:
+ * `experience-design-system-integrations` / services/design-system-sources-apply-worker/src/topo-sort.ts.
+ *
+ * We surface the same check locally so the wizard can:
+ *   1. warn the operator at extract time (soft) with sidebar badges + banner,
+ *   2. hard-block the push at manifest-finalization time before any API call.
+ *
+ * The algorithm is Johnson's — an O((V + E)(C + 1)) enumeration of all
+ * elementary (simple) cycles in a directed graph. We need *elementary*
+ * cycles rather than just cycle-existence because an operator can have
+ * multiple independent cycles they need to address separately, and each
+ * gets its own suggested fix.
+ *
+ * Johnson's algorithm reference: Donald B. Johnson, "Finding all the
+ * elementary circuits of a directed graph." SIAM J. Comput., 4(1):77-84, 1975.
+ */
+function buildGraph(components) {
+    const nodes = [];
+    const seen = new Set();
+    for (const c of components) {
+        if (seen.has(c.name))
+            continue;
+        seen.add(c.name);
+        nodes.push(c.name);
+    }
+    const adjacency = new Map();
+    for (const node of nodes)
+        adjacency.set(node, []);
+    for (const comp of components) {
+        const outgoing = adjacency.get(comp.name);
+        if (!outgoing)
+            continue;
+        for (const slot of comp.slots) {
+            const allowed = slot.allowedComponents ?? [];
+            for (const target of allowed) {
+                if (!seen.has(target))
+                    continue; // unknown / external — ignore
+                outgoing.push({ target, slotName: slot.name });
+            }
+        }
+    }
+    return { nodes, adjacency };
+}
+/**
+ * Tarjan's strongly-connected-components algorithm — used by Johnson's
+ * algorithm to constrain cycle search to one SCC at a time. Returns SCCs in
+ * reverse-topological order.
+ */
+function stronglyConnectedComponents(nodes, adjacency) {
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    const nodeSet = new Set(nodes);
+    function strongconnect(v) {
+        index.set(v, counter);
+        lowlink.set(v, counter);
+        counter += 1;
+        stack.push(v);
+        onStack.add(v);
+        const neighbours = adjacency.get(v) ?? [];
+        for (const { target } of neighbours) {
+            if (!nodeSet.has(target))
+                continue;
+            if (!index.has(target)) {
+                strongconnect(target);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(target)));
+            }
+            else if (onStack.has(target)) {
+                lowlink.set(v, Math.min(lowlink.get(v), index.get(target)));
+            }
+        }
+        if (lowlink.get(v) === index.get(v)) {
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+            } while (w !== v);
+            sccs.push(scc);
+        }
+    }
+    for (const node of nodes) {
+        if (!index.has(node))
+            strongconnect(node);
+    }
+    return sccs;
+}
+/**
+ * Given a specific traversal `path` (component names) and the edge multiset
+ * we walked to build it, materialize a `SlotCycle`. Because multiple parallel
+ * edges may exist between the same two components (different slot names), we
+ * carry the exact edges along the search rather than reconstructing them from
+ * the node path.
+ */
+function makeCycle(path, edges) {
+    return { path: [...path, path[0]], edges: [...edges] };
+}
+/**
+ * Johnson's algorithm — enumerates all elementary (simple) cycles in the
+ * slot-dependency graph. Self-loops are handled as a degenerate first pass
+ * because Tarjan's SCC decomposition assigns a self-looping node to its own
+ * single-node SCC, which Johnson's inner loop otherwise skips.
+ */
+export function findSlotCycles(components) {
+    if (components.length === 0)
+        return [];
+    const { nodes, adjacency } = buildGraph(components);
+    if (nodes.length === 0)
+        return [];
+    const cycles = [];
+    // Degenerate case: self-loops. For any component whose slot allows itself,
+    // emit a length-1 cycle before invoking Johnson's inner loop — Tarjan's
+    // trivial single-node SCC test in Johnson's original paper only counts as
+    // an SCC if the node participates in an edge, which we replicate here.
+    for (const node of nodes) {
+        const outgoing = adjacency.get(node) ?? [];
+        for (const edge of outgoing) {
+            if (edge.target === node) {
+                cycles.push({
+                    path: [node, node],
+                    edges: [{ fromComponent: node, slotName: edge.slotName, toComponent: node }],
+                });
+            }
+        }
+    }
+    // Johnson's main algorithm — iterate over remaining nodes in a fixed order,
+    // decomposing the subgraph induced by `{node, ...higherOrder}` into SCCs,
+    // and running the blocked-list circuit search rooted at the least node of
+    // each non-trivial SCC. This is the classic formulation from the paper.
+    const nodeOrder = [...nodes].sort();
+    let remaining = [...nodeOrder];
+    while (remaining.length > 0) {
+        const subgraphNodes = remaining;
+        const sccs = stronglyConnectedComponents(subgraphNodes, adjacency).filter((scc) => {
+            if (scc.length > 1)
+                return true;
+            // Non-trivial single-node SCC iff the node has a self-loop within the
+            // subgraph. We already emitted those above, so exclude here.
+            return false;
+        });
+        if (sccs.length === 0)
+            break;
+        // Pick the SCC containing the lexicographically-smallest node — mirrors
+        // the "least vertex" root selection in Johnson's paper.
+        let startNode = null;
+        let startScc = null;
+        for (const scc of sccs) {
+            const min = [...scc].sort()[0];
+            if (startNode === null || min < startNode) {
+                startNode = min;
+                startScc = scc;
+            }
+        }
+        if (startNode === null || startScc === null)
+            break;
+        const sccSet = new Set(startScc);
+        const blocked = new Set();
+        const blockedMap = new Map();
+        const pathStack = [];
+        const edgeStack = [];
+        function unblock(u) {
+            blocked.delete(u);
+            const dependents = blockedMap.get(u);
+            if (!dependents)
+                return;
+            for (const w of dependents) {
+                if (blocked.has(w))
+                    unblock(w);
+            }
+            dependents.clear();
+        }
+        function circuit(v, root) {
+            let foundCycle = false;
+            pathStack.push(v);
+            blocked.add(v);
+            const outgoing = adjacency.get(v) ?? [];
+            for (const { target: w, slotName } of outgoing) {
+                if (!sccSet.has(w))
+                    continue;
+                edgeStack.push({ fromComponent: v, slotName, toComponent: w });
+                if (w === root) {
+                    cycles.push(makeCycle(pathStack, edgeStack));
+                    foundCycle = true;
+                }
+                else if (!blocked.has(w)) {
+                    if (circuit(w, root))
+                        foundCycle = true;
+                }
+                edgeStack.pop();
+            }
+            if (foundCycle) {
+                unblock(v);
+            }
+            else {
+                for (const { target: w } of outgoing) {
+                    if (!sccSet.has(w))
+                        continue;
+                    let deps = blockedMap.get(w);
+                    if (!deps) {
+                        deps = new Set();
+                        blockedMap.set(w, deps);
+                    }
+                    deps.add(v);
+                }
+            }
+            pathStack.pop();
+            return foundCycle;
+        }
+        circuit(startNode, startNode);
+        // Remove `startNode` from consideration and repeat with the reduced
+        // subgraph. In classic Johnson's this is done by re-running SCC on the
+        // subgraph induced by the remaining nodes.
+        remaining = remaining.filter((n) => n !== startNode);
+    }
+    return cycles;
+}
+/**
+ * Pick which edge is the best candidate to remove to break a cycle.
+ * Heuristic: prefer removing the edge whose `toComponent` appears most often
+ * as a destination across all cycles — that "hub" node is the biggest
+ * contributor and removing an inbound edge to it likely breaks multiple
+ * cycles at once. Falls back to the first edge in the cycle for
+ * deterministic output when all candidates are tied.
+ */
+export function suggestCycleBreakEdge(cycle, allCycles) {
+    if (cycle.edges.length === 0) {
+        throw new Error('suggestCycleBreakEdge: cycle has no edges');
+    }
+    const indegree = new Map();
+    for (const c of allCycles) {
+        for (const edge of c.edges) {
+            indegree.set(edge.toComponent, (indegree.get(edge.toComponent) ?? 0) + 1);
+        }
+    }
+    let best = cycle.edges[0];
+    let bestScore = indegree.get(best.toComponent) ?? 0;
+    for (const edge of cycle.edges) {
+        const score = indegree.get(edge.toComponent) ?? 0;
+        if (score > bestScore) {
+            best = edge;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * Format a cycle for the compact banner:
+ *   `CardA → header → CardB → footer → CardA`
+ *
+ * Truncates at `maxHops` edges (default 8), inserting `…` mid-path so the
+ * beginning and end remain visible. A hop is one edge; the returned string
+ * for an n-edge cycle contains n+1 component names.
+ */
+export function formatCyclePath(cycle, maxHops = 8) {
+    const arrow = ' → ';
+    const parts = [];
+    // Interleave: component, slot, component, slot, ..., final component
+    // path.length === edges.length + 1.
+    for (let i = 0; i < cycle.edges.length; i += 1) {
+        parts.push(cycle.path[i]);
+        parts.push(cycle.edges[i].slotName);
+    }
+    parts.push(cycle.path[cycle.path.length - 1]);
+    if (cycle.edges.length <= maxHops) {
+        return parts.join(arrow);
+    }
+    // Truncated: keep the first `keep` edges' worth of tokens and the final
+    // component. Two "tokens per hop" (component + slot) plus the trailing
+    // component name.
+    const keepHops = Math.max(1, maxHops - 1);
+    const keepTokens = keepHops * 2;
+    const head = parts.slice(0, keepTokens).join(arrow);
+    const tail = parts[parts.length - 1];
+    return `${head}${arrow}…${arrow}${tail}`;
+}

package/dist/src/analyze/extract/slot-allowed-components.js

@@ -2,25 +2,26 @@
 // expands the second generic argument to string | JSXElementConstructor<any>).
 // Only the first generic argument (the props type name) is captured.
 const REACT_ELEMENT_GENERIC = /(?:React\.)?ReactElement\s*<\s*([A-Za-z_$][\w$.]*)(?![\w$.])/g;
-// Svelte 5 typed snippets: `Snippet<[XProps]>`. The type argument is a tuple
-// listing render args; when a snippet is authored to render a nested
-// ComponentType, the single tuple element is that component's Props type.
-// We only match the single-element tuple form — non-props render args
-// (e.g. `Snippet<[year: number]>`) don't reference a ComponentType and are
-// filtered out below via propsToComponent lookup.
-const SVELTE_SNIPPET_GENERIC = /Snippet\s*<\s*\[\s*([A-Za-z_$][\w$.]*)\s*\]\s*>/g;
+const SVELTE_SNIPPET_TUPLE = /Snippet\s*<\s*\[([^\]]*)\]\s*>/g;
+const IDENTIFIER = /[A-Za-z_$][\w$.]*/g;
 export function extractAllowedComponentsFromTypeText(typeText, ctx) {
     const found = new Set();
-    for (const re of [REACT_ELEMENT_GENERIC, SVELTE_SNIPPET_GENERIC]) {
-        re.lastIndex = 0;
-        let m;
-        while ((m = re.exec(typeText)) !== null) {
-            const propsTypeName = m[1];
-            const componentName = ctx.propsToComponent.get(propsTypeName);
-            if (componentName && ctx.componentNames.has(componentName)) {
-                found.add(componentName);
-            }
-        }
+    const record = (propsTypeName) => {
+        const componentName = ctx.propsToComponent.get(propsTypeName);
+        if (componentName && ctx.componentNames.has(componentName))
+            found.add(componentName);
+    };
+    REACT_ELEMENT_GENERIC.lastIndex = 0;
+    let m;
+    while ((m = REACT_ELEMENT_GENERIC.exec(typeText)) !== null)
+        record(m[1]);
+    SVELTE_SNIPPET_TUPLE.lastIndex = 0;
+    while ((m = SVELTE_SNIPPET_TUPLE.exec(typeText)) !== null) {
+        const tupleBody = m[1];
+        IDENTIFIER.lastIndex = 0;
+        let id;
+        while ((id = IDENTIFIER.exec(tupleBody)) !== null)
+            record(id[0]);
     }
     return [...found].sort();
 }

package/dist/src/apply/command.d.ts

@@ -1,6 +1,10 @@
 import type { Command } from 'commander';
-import type { DTCGTokenEntry } from '@contentful/experience-design-system-types';
+import type { CDFComponentEntry, DTCGTokenEntry } from '@contentful/experience-design-system-types';
 import type { ServerPreviewResponse } from '@contentful/experience-design-system-types';
 export declare function readTokensFromPath(flag: string, p: string): Promise<DTCGTokenEntry[]>;
+export declare function assertNoSlotCycles(components: Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>): void;
 export declare function hasBreakingChangesWithImpact(preview: ServerPreviewResponse): boolean;
 export declare function registerApplyCommand(program: Command): void;

package/dist/src/apply/command.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { validateCDF, flattenDTCG, validateDTCG, buildManifest, buildFilteredManifest, } from '@contentful/experience-design-system-types';
 import { ApiError, ImportApiClient } from './api-client.js';
 import { openPipelineDb, loadCDFComponents } from '../session/db.js';
+import { findSlotCycles, suggestCycleBreakEdge, formatCyclePath } from '../analyze/cycle-detection.js';
 import { isEmptyPreview } from './preview-utils.js';
 import { ServerPreviewApp, ServerPreviewConfirm, ServerApplyProgress, ServerApplyDone } from './tui/ServerApplyView.js';
 import { SelectView, makeSelectKey } from './tui/SelectView.js';
@@ -170,6 +171,37 @@ async function resolveSharedInputs(opts) {
     });
     return { components, tokens, client };
 }
+// --- INTEG-4401: pre-push slot-cycle hard block ---
+//
+// The backend apply worker rejects cyclic slot graphs at topo-sort time, but
+// by then the request has already been serialized, transported, and partially
+// applied — leading to confusing partial-failure states. Detecting the same
+// violation locally lets us fail fast with a clear message and zero
+// side-effects. Called from the `apply push` and `apply select` flows only;
+// `apply preview` is read-only and still runs (its diff is used to warn but
+// not to block).
+export function assertNoSlotCycles(components) {
+    const cycleInput = components.map(({ key, entry }) => ({
+        name: key,
+        slots: Object.entries(entry.$slots ?? {}).map(([slotName, slotDef]) => ({
+            name: slotName,
+            allowedComponents: slotDef.$allowedComponents ?? [],
+        })),
+    }));
+    const cycles = findSlotCycles(cycleInput);
+    if (cycles.length === 0)
+        return;
+    const lines = [];
+    lines.push(`Error: manifest:components/slot-cycles — ${cycles.length} slot dependency cycle(s) detected. Push refused.`);
+    for (let i = 0; i < cycles.length; i += 1) {
+        const cycle = cycles[i];
+        lines.push(`  Cycle ${i + 1}: ${formatCyclePath(cycle)}`);
+        const suggested = suggestCycleBreakEdge(cycle, cycles);
+        lines.push(`    Fix: remove '${suggested.toComponent}' from ${suggested.fromComponent}.$slots.${suggested.slotName}.$allowedComponents`);
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+    process.exit(1);
+}
 // --- Output helpers ---
 export function hasBreakingChangesWithImpact(preview) {
     const allChanged = [...preview.components.changed, ...preview.tokens.changed];
@@ -445,6 +477,12 @@ export function registerApplyCommand(program) {
             throw e;
         }
         const { components, tokens, client } = inputs;
+        // INTEG-4401: refuse before spending any credentials or bytes on a
+        // manifest the backend will reject. Cycle detection is deterministic
+        // and cheap so we run it here (not just at extract time) — this also
+        // guards `apply push --components` where extract-time cycles are not
+        // in the session DB.
+        assertNoSlotCycles(components);
         try {
             await client.validateToken();
         }
@@ -623,6 +661,11 @@ export function registerApplyCommand(program) {
             throw e;
         }
         const { components, tokens, client } = inputs;
+        // INTEG-4401: same pre-push cycle block as `apply push`. Running the
+        // check on the FULL component set (not the filtered selection) is
+        // deliberate: partial selection cannot resolve a cycle whose
+        // participants are all still present in the target space.
+        assertNoSlotCycles(components);
         try {
             await client.validateToken();
         }

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

@@ -37,6 +37,6 @@ type GenerateReviewStepProps = {
 export declare function sortComponentsForSidebar<T extends {
     key: string;
     entry: CDFComponentEntry;
-}>(components: T[]): T[];
+}>(components: T[], cycleParticipants?: Set<string>): T[];
 export declare function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: GenerateReviewStepProps): React.ReactElement;
 export {};

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

@@ -8,7 +8,8 @@ import { StatusBar } from '../../../analyze/select/tui/components/StatusBar.js';
 import { FinalizeDialog } from '../../../analyze/select/tui/components/FinalizeDialog.js';
 import { QuitDialog } from '../../../analyze/select/tui/components/QuitDialog.js';
 import { useImmediateInput } from '../../../analyze/select/tui/hooks/useImmediateInput.js';
-import { openPipelineDb, loadCDFComponents, storeCDFComponents, loadComponentReviewMetadata, loadComponentRationale, } from '../../../session/db.js';
+import { openPipelineDb, loadCDFComponents, storeCDFComponents, loadComponentReviewMetadata, loadComponentRationale, loadSlotCycles, } from '../../../session/db.js';
+import { formatCyclePath } from '../../../analyze/cycle-detection.js';
 import { RationalePanel } from '../../../analyze/select/tui/components/RationalePanel.js';
 import { ComponentRationalePanel } from '../../../analyze/select/tui/components/ComponentRationalePanel.js';
 import { applyPreviewAnnotations } from '../../../analyze/select/preview-annotations.js';
@@ -24,13 +25,22 @@ import { computeNextScrollOffset } from '../../../analyze/select/tui/hooks/scrol
  *
  * Within each tier (empty / non-empty) we tie-break alphabetically by `key`.
  */
-export function sortComponentsForSidebar(components) {
+export function sortComponentsForSidebar(components, cycleParticipants) {
     const isEmpty = (entry) => Object.keys(entry.$properties ?? {}).length === 0 && Object.keys(entry.$slots ?? {}).length === 0;
+    // Tier order: cycle members first (they block push — surface loudest),
+    // then empty (soft warning), then everything else. Ties broken alpha.
+    const tier = (c) => {
+        if (cycleParticipants?.has(c.key))
+            return 0;
+        if (isEmpty(c.entry))
+            return 1;
+        return 2;
+    };
     return [...components].sort((a, b) => {
-        const aEmpty = isEmpty(a.entry);
-        const bEmpty = isEmpty(b.entry);
-        if (aEmpty !== bEmpty)
-            return aEmpty ? -1 : 1;
+        const at = tier(a);
+        const bt = tier(b);
+        if (at !== bt)
+            return at - bt;
         return a.key.localeCompare(b.key);
     });
 }
@@ -76,6 +86,12 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
     // Tracks the first `g` of a potential `gg` double-tap (jumps to top in
     // JSON-view + panel-focused state). Reset on any non-`g` key.
     const pendingGRef = useRef(false);
+    // INTEG-4401: slot-dependency cycles loaded from the session DB. Non-empty
+    // triggers sidebar (cycle) badges, banner + [c] detail-panel affordance,
+    // and (at push time) a hard block.
+    const [slotCycles, setSlotCycles] = useState([]);
+    const [showCyclePanel, setShowCyclePanel] = useState(false);
+    const [cyclePanelScroll, setCyclePanelScroll] = useState(0);
     const handleLivePreviewResult = (response) => {
         if (!response)
             return;
@@ -107,8 +123,10 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
         async function load() {
             const db = openPipelineDb();
             let cdfComponents;
+            let cycles = [];
             try {
                 cdfComponents = loadCDFComponents(db, extractSessionId);
+                cycles = loadSlotCycles(db, extractSessionId);
             }
             finally {
                 db.close();
@@ -123,7 +141,12 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
                 entry,
                 status: 'needs-review',
             }));
-            setComponents(sortComponentsForSidebar(reviewEntries));
+            const cycleParticipants = new Set();
+            for (const c of cycles)
+                for (const p of c.path)
+                    cycleParticipants.add(p);
+            setSlotCycles(cycles);
+            setComponents(sortComponentsForSidebar(reviewEntries, cycleParticipants));
             setLoading(false);
         }
         load().catch((e) => {
@@ -283,6 +306,31 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
             }
             return;
         }
+        // INTEG-4401: slot-cycle detail panel. Same modal-swallow rules as
+        // showRemovedPanel; q/Esc close, ↑↓ scroll.
+        if (showCyclePanel) {
+            if (input === 'c' || input === 'q' || key.escape) {
+                setShowCyclePanel(false);
+                setCyclePanelScroll(0);
+                return;
+            }
+            if (key.upArrow || input === 'k') {
+                setCyclePanelScroll((v) => Math.max(0, v - 1));
+                return;
+            }
+            if (key.downArrow || input === 'j') {
+                setCyclePanelScroll((v) => v + 1);
+                return;
+            }
+            return;
+        }
+        // Open the cycle panel from sidebar-focused state when there is at
+        // least one cycle to display.
+        if (input === 'c' && sidebarFocused && slotCycles.length > 0) {
+            setShowCyclePanel(true);
+            setCyclePanelScroll(0);
+            return;
+        }
         // `d` opens the panel only when live-preview is enabled and there is at
         // least one removed component to display. Sidebar-focused only so it
         // doesn't collide with FieldEditor input.
@@ -476,19 +524,32 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
     const selectedJson = selected ? JSON.stringify({ [selected.key]: selected.entry }, null, 2) : '';
     const isEmpty = (c) => Object.keys(c.entry.$properties).length === 0 && Object.keys(c.entry.$slots ?? {}).length === 0;
     const emptyCount = components.filter(isEmpty).length;
+    // INTEG-4401: cycle-participant set drives sidebar `(cycle)` badges plus
+    // the banner counts. Recomputed on every render — cheap for typical N.
+    const cycleParticipantSet = new Set();
+    for (const cycle of slotCycles)
+        for (const p of cycle.path)
+            cycleParticipantSet.add(p);
+    const sidebarSuffix = (c) => {
+        if (cycleParticipantSet.has(c.key))
+            return ' (cycle)';
+        if (isEmpty(c))
+            return ' (empty)';
+        return '';
+    };
     const sidebarItems = components.map((c) => ({
         id: c.key,
-        name: isEmpty(c) ? `${c.key} (empty)` : c.key,
+        name: `${c.key}${sidebarSuffix(c)}`,
         status: c.status,
         previewAnnotation: previewAnnotations.get(c.key),
         extractionConfidence: null,
         needsReview: false,
         validationErrorCount: 0,
-        validationWarningCount: isEmpty(c) ? 1 : 0,
+        validationWarningCount: sidebarSuffix(c) !== '' ? 1 : 0,
     }));
-    // Account for the "(empty)" suffix added to zero-prop component names so the
-    // sidebar doesn't truncate it.
-    const longestName = components.reduce((m, c) => Math.max(m, c.key.length + (isEmpty(c) ? ' (empty)'.length : 0)), 0);
+    // Account for the "(cycle)" / "(empty)" suffix added to badged component
+    // names so the sidebar doesn't truncate them.
+    const longestName = components.reduce((m, c) => Math.max(m, c.key.length + sidebarSuffix(c).length), 0);
     // +5 = border (1) + status icon (1) + badge column (1) + space (1) + border (1).
     // The badge column is reserved even when no annotation is present so the
     // sidebar width doesn't jitter as live-preview annotations flip in/out.
@@ -499,7 +560,31 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
     const needsReview = components.filter((c) => c.status === 'needs-review').length;
     const propCount = selected ? Object.keys(selected.entry.$properties).length : 0;
     const slotCount = selected?.entry.$slots ? Object.keys(selected.entry.$slots).length : 0;
-    return (_jsxs(Box, { flexDirection: "column", children: [showFinalize && (_jsx(FinalizeDialog, { accepted: accepted, rejected: rejected, needsReview: needsReview, onConfirm: handleFinalizeConfirm, onCancel: () => setShowFinalize(false) })), showQuit && _jsx(QuitDialog, { hasUnsavedDrafts: false, onConfirm: onQuit, onCancel: () => setShowQuit(false) }), showRemovedPanel && !dialogOpen && (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: `Removed components (${removedComponents.length})` }), _jsx(Text, { dimColor: true, children: "these will be DELETED from the target space" }), _jsx(Text, { children: " " }), removedComponents.map((rc) => (_jsx(Text, { children: `- ${rc.name}${rc.id ? `  (${rc.id})` : ''}` }, rc.id))), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "press d or Esc to close" })] })), !dialogOpen &&
+    return (_jsxs(Box, { flexDirection: "column", children: [showFinalize && (_jsx(FinalizeDialog, { accepted: accepted, rejected: rejected, needsReview: needsReview, onConfirm: handleFinalizeConfirm, onCancel: () => setShowFinalize(false) })), showQuit && _jsx(QuitDialog, { hasUnsavedDrafts: false, onConfirm: onQuit, onCancel: () => setShowQuit(false) }), showRemovedPanel && !dialogOpen && (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: `Removed components (${removedComponents.length})` }), _jsx(Text, { dimColor: true, children: "these will be DELETED from the target space" }), _jsx(Text, { children: " " }), removedComponents.map((rc) => (_jsx(Text, { children: `- ${rc.name}${rc.id ? `  (${rc.id})` : ''}` }, rc.id))), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "press d or Esc to close" })] })), showCyclePanel &&
+                !dialogOpen &&
+                (() => {
+                    // Materialize the full panel body as a flat list of Text lines,
+                    // then slice by cyclePanelScroll so ↑↓ can walk arbitrarily long
+                    // content. Each cycle contributes 3-4 lines: heading, path,
+                    // suggested fix (if any), and a blank separator.
+                    const PANEL_H = 20;
+                    const lines = [];
+                    lines.push(_jsx(Text, { bold: true, color: "yellow", children: `SLOT DEPENDENCY CYCLES (${slotCycles.length})` }, "cyc-title"));
+                    lines.push(_jsx(Text, { dimColor: true, children: 'push will fail until these are resolved' }, "cyc-sub"));
+                    lines.push(_jsx(Text, { children: " " }, "cyc-space"));
+                    slotCycles.forEach((cycle, idx) => {
+                        const nodeCount = new Set(cycle.path).size;
+                        lines.push(_jsx(Text, { bold: true, children: `▸ Cycle ${idx + 1} (${nodeCount} component${nodeCount === 1 ? '' : 's'}):` }, `cyc-h-${idx}`));
+                        lines.push(_jsx(Text, { children: `    ${formatCyclePath(cycle, 16)}` }, `cyc-p-${idx}`));
+                        if (cycle.suggestedBreak) {
+                            const b = cycle.suggestedBreak;
+                            lines.push(_jsx(Text, { dimColor: true, children: `    Suggested fix: remove '${b.toComponent}' from ${b.fromComponent}.$slots.${b.slotName}.$allowedComponents` }, `cyc-f-${idx}`));
+                        }
+                        lines.push(_jsx(Text, { children: " " }, `cyc-s-${idx}`));
+                    });
+                    const visible = lines.slice(cyclePanelScroll, cyclePanelScroll + PANEL_H);
+                    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "yellow", paddingX: 1, children: [visible, _jsx(Text, { dimColor: true, children: '[↑↓/j/k] scroll  [c/q/Esc] close' })] }));
+                })(), !dialogOpen &&
                 livePreview &&
                 (() => {
                     // Pilot-2026-06-23 R2: at-a-glance diff summary at the top of the
@@ -522,7 +607,7 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
                     if (!hasCounts)
                         return null;
                     return (_jsxs(Box, { children: [_jsx(Text, { children: 'Preview: ' }), _jsx(Text, { color: "green", children: `${counts.new} new` }), _jsx(Text, { children: ' · ' }), _jsx(Text, { color: "yellow", children: `${counts.changed} changed` }), _jsx(Text, { children: ' · ' }), _jsx(Text, { dimColor: true, children: `${counts.removed} removed` }), removedComponents.length > 0 && _jsx(Text, { dimColor: true, children: ' ([d] removed list)' }), _jsx(Text, { children: ' · ' }), _jsx(Text, { color: "red", bold: true, children: `${counts.breaking} breaking` })] }));
-                })(), !dialogOpen && emptyCount > 0 && (_jsx(Text, { color: "yellow", children: `⚠ ${emptyCount} component${emptyCount === 1 ? '' : 's'} had no classifiable props — review with care` })), !dialogOpen && finalizeError && _jsx(Text, { color: "red", children: `⚠ ${finalizeError}` }), !dialogOpen && (_jsxs(Box, { children: [_jsx(Sidebar, { components: sidebarItems, selectedId: selected?.key ?? null, focused: sidebarFocused, scrollOffset: sidebarScrollOffset, visibleCount: VISIBLE_COUNT, onSelect: (id) => {
+                })(), !dialogOpen && slotCycles.length > 0 && !showCyclePanel && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "yellow", children: `⚠ ${slotCycles.length} slot dependency cycle${slotCycles.length === 1 ? '' : 's'} detected — push will fail` }), slotCycles.slice(0, 3).map((cycle, idx) => (_jsx(Text, { color: "yellow", children: `  Cycle: ${formatCyclePath(cycle)}` }, `cyc-banner-${idx}`))), slotCycles.length > 3 && _jsx(Text, { color: "yellow", children: `  …${slotCycles.length - 3} more` }), _jsx(Text, { dimColor: true, children: '  press [c] for detail' })] })), !dialogOpen && emptyCount > 0 && (_jsx(Text, { color: "yellow", children: `⚠ ${emptyCount} component${emptyCount === 1 ? '' : 's'} had no classifiable props — review with care` })), !dialogOpen && finalizeError && _jsx(Text, { color: "red", children: `⚠ ${finalizeError}` }), !dialogOpen && (_jsxs(Box, { children: [_jsx(Sidebar, { components: sidebarItems, selectedId: selected?.key ?? null, focused: sidebarFocused, scrollOffset: sidebarScrollOffset, visibleCount: VISIBLE_COUNT, onSelect: (id) => {
                             const idx = components.findIndex((c) => c.key === id);
                             if (idx >= 0) {
                                 setSelectedIdx(idx);
@@ -576,6 +661,7 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
                                                 (showJson ? 'hide JSON' : 'show JSON') +
                                                 '  [F] finalize  [e/Tab] focus panel' +
                                                 (livePreview && removedComponents.length > 0 ? '  [d] removed list' : '') +
+                                                (slotCycles.length > 0 ? '  [c] cycles' : '') +
                                                 '  [q] quit'
                                             : showJson
                                                 ? '  [j/k] scroll  [Ctrl+u/d] half-page  [gg/G] top/bottom  [Tab] focus list'

package/dist/src/session/db.d.ts

@@ -3,6 +3,7 @@ import type { RawComponentDefinition } from '../types.js';
 import type { CDFComponentEntry, DTCGTokenEntry, DTCGTokenGroup } from '@contentful/experience-design-system-types';
 import type { ToolCall, TokenToolCall } from '../generate/agent-runner.js';
 import type { ComponentTypeSummary } from '@contentful/experience-design-system-types';
+import type { SlotCycle, SlotEdge } from '../analyze/cycle-detection.js';
 export type StepStatus = 'pending' | 'complete' | 'failed' | 'interrupted';
 export type CommandName = 'analyze extract' | 'analyze select' | 'generate components' | 'generate tokens' | 'generate edit' | 'apply preview' | 'apply select' | 'apply push' | 'print components' | 'print tokens' | 'import';
 export interface SessionRow {
@@ -176,6 +177,14 @@ export declare function lookupCacheByEntity(db: DatabaseSync, entityType: 'compo
 export declare function storeCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, sourceSessionId: string, humanEdited: boolean, promptHash?: string): void;
 export declare function storeScannedFiles(db: DatabaseSync, sessionId: string, filePaths: string[]): void;
 export declare function loadScannedFiles(db: DatabaseSync, sessionId: string): string[];
+export declare function storeSlotCycles(db: DatabaseSync, sessionId: string, cycles: Array<SlotCycle & {
+    suggestedBreak?: SlotEdge | null;
+}>): void;
+export interface StoredSlotCycle extends SlotCycle {
+    suggestedBreak: SlotEdge | null;
+}
+export declare function loadSlotCycles(db: DatabaseSync, sessionId: string): StoredSlotCycle[];
+export declare function clearSlotCycles(db: DatabaseSync, sessionId: string): void;
 export declare function markCacheHumanEdited(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): void;
 export declare function copyComponentFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string, componentId: string): void;
 export declare function copyTokensFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string): void;

package/dist/src/session/db.js

@@ -138,6 +138,15 @@ CREATE TABLE IF NOT EXISTS scanned_files (
   PRIMARY KEY (session_id, path)
 );
 
+CREATE TABLE IF NOT EXISTS slot_cycles (
+  session_id             TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  cycle_index            INTEGER NOT NULL,
+  path_json              TEXT NOT NULL,
+  edges_json             TEXT NOT NULL,
+  suggested_break_json   TEXT,
+  PRIMARY KEY (session_id, cycle_index)
+);
+
 CREATE INDEX IF NOT EXISTS idx_steps_session            ON steps(session_id);
 CREATE INDEX IF NOT EXISTS idx_steps_command            ON steps(session_id, command);
 CREATE INDEX IF NOT EXISTS idx_raw_components_session   ON raw_components(session_id);
@@ -1388,6 +1397,43 @@ export function loadScannedFiles(db, sessionId) {
     const rows = db.prepare('SELECT path FROM scanned_files WHERE session_id = ? ORDER BY path').all(sessionId);
     return rows.map((r) => r.path);
 }
+// --- Slot-dependency cycle persistence (INTEG-4401) ---
+//
+// The `slot_cycles` table caches the result of running the cycle detector
+// over the extractor's slot output so the TUI can render sidebar badges,
+// a banner, and an expandable detail panel without re-running the analysis
+// on every render. Rows are session-scoped and rewritten wholesale on each
+// re-extract via `storeSlotCycles`.
+export function storeSlotCycles(db, sessionId, cycles) {
+    db.exec('BEGIN');
+    try {
+        db.prepare('DELETE FROM slot_cycles WHERE session_id = ?').run(sessionId);
+        const insert = db.prepare(`INSERT INTO slot_cycles (session_id, cycle_index, path_json, edges_json, suggested_break_json)
+       VALUES (?, ?, ?, ?, ?)`);
+        for (let i = 0; i < cycles.length; i += 1) {
+            const cycle = cycles[i];
+            insert.run(sessionId, i, JSON.stringify(cycle.path), JSON.stringify(cycle.edges), cycle.suggestedBreak ? JSON.stringify(cycle.suggestedBreak) : null);
+        }
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        db.exec('ROLLBACK');
+        throw e;
+    }
+}
+export function loadSlotCycles(db, sessionId) {
+    const rows = db
+        .prepare('SELECT cycle_index, path_json, edges_json, suggested_break_json FROM slot_cycles WHERE session_id = ? ORDER BY cycle_index')
+        .all(sessionId);
+    return rows.map((r) => ({
+        path: JSON.parse(r.path_json),
+        edges: JSON.parse(r.edges_json),
+        suggestedBreak: r.suggested_break_json ? JSON.parse(r.suggested_break_json) : null,
+    }));
+}
+export function clearSlotCycles(db, sessionId) {
+    db.prepare('DELETE FROM slot_cycles WHERE session_id = ?').run(sessionId);
+}
 export function markCacheHumanEdited(db, entityType, entityId) {
     const now = new Date().toISOString();
     db.prepare(`UPDATE generation_cache SET human_edited = 1, updated_at = ? WHERE entity_type = ? AND entity_id = ?`).run(now, entityType, entityId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.12.4-dev-build-a1a979f.0",
+  "version": "2.12.4-dev-build-9c819d8.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.12.4-dev-build-a1a979f.0"
+    "@contentful/experience-design-system-types": "2.12.4-dev-build-9c819d8.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",