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

package/dist/src/apply/command.js

@@ -5,10 +5,14 @@ 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';
 import { buildPostPushUrl } from '../lib/contentful-urls.js';
+import { resolveCompositionMode } from '../lib/composition-mode.js';
+import { stripAllowedComponents } from '../import/strip-allowed-components.js';
+import { readExperiencesCredentials } from '../credentials-store.js';
 function die(message) {
     process.stderr.write(`${message}\n`);
     process.exit(1);
@@ -158,6 +162,21 @@ async function resolveSharedInputs(opts) {
         }
         components = result.components;
     }
+    // Atomic mode (spec T8/T12): strip embedded-component composition at the
+    // single serialization boundary, regardless of load path. Normalizing here
+    // (rather than only in loadCDFComponents) also covers hand-authored
+    // `--components` files. Starving `$allowedComponents` at this one point
+    // means slot-cycle detection downstream structurally returns zero.
+    let configMode;
+    try {
+        configMode = (await readExperiencesCredentials()).compositionMode;
+    }
+    catch {
+        // Missing credentials.json → resolver falls through to default (atomic).
+    }
+    if (resolveCompositionMode(opts, configMode) === 'atomic') {
+        components = stripAllowedComponents(components);
+    }
     let tokens = [];
     if (opts.tokens) {
         tokens = await readTokensFromPath('--tokens', opts.tokens);
@@ -170,7 +189,48 @@ async function resolveSharedInputs(opts) {
     });
     return { components, tokens, client };
 }
-// --- Output helpers ---
+export function detectSlotCycles(components) {
+    const cycleInput = components.map(({ key, entry }) => ({
+        name: key,
+        slots: Object.entries(entry.$slots ?? {}).map(([slotName, slotDef]) => ({
+            name: slotName,
+            allowedComponents: slotDef.$allowedComponents ?? [],
+        })),
+    }));
+    return findSlotCycles(cycleInput);
+}
+export function formatSlotCycleReport(cycles) {
+    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`);
+    }
+    return lines;
+}
+export function assertNoSlotCycles(components) {
+    const cycles = detectSlotCycles(components);
+    if (cycles.length === 0)
+        return;
+    process.stderr.write(formatSlotCycleReport(cycles).join('\n') + '\n');
+    process.exit(1);
+}
+export function extractComponentsFromManifest(manifest) {
+    const componentsManifest = manifest?.componentsManifest;
+    if (!componentsManifest)
+        return [];
+    const out = [];
+    for (const [key, value] of Object.entries(componentsManifest)) {
+        if (key === '$schema')
+            continue;
+        if (!value || typeof value !== 'object')
+            continue;
+        out.push({ key, entry: value });
+    }
+    return out;
+}
 export function hasBreakingChangesWithImpact(preview) {
     const allChanged = [...preview.components.changed, ...preview.tokens.changed];
     return allChanged.some((c) => c.changeClassification?.classification === 'breaking' &&
@@ -233,7 +293,6 @@ function buildApplyOutput(operation, spaceId, environmentId, host) {
         })),
     };
 }
-// --- Selection helpers ---
 function getSelectableEntities(preview) {
     const entities = [];
     for (const token of preview.tokens.new) {
@@ -350,7 +409,6 @@ function SelectApp({ entities, spaceId, environmentId, onApply }) {
         importing,
     });
 }
-// --- Command registration ---
 function collect(val, prev) {
     return [...prev, val];
 }
@@ -358,7 +416,6 @@ export function registerApplyCommand(program) {
     const applyCmd = program
         .command('apply')
         .description('Preview, select, or push design system entities to Contentful ExO');
-    // --- apply preview ---
     applyCmd
         .command('preview')
         .description('Show a read-only diff of what apply push would do')
@@ -369,6 +426,8 @@ export function registerApplyCommand(program) {
         .requiredOption('--environment-id <id>', 'Contentful environment ID')
         .option('--cma-token <token>', 'CMA personal access token (or set CONTENTFUL_MANAGEMENT_TOKEN)')
         .option('--host <url>', 'Override API base URL')
+        .option('--composite', 'Import embedded-component hierarchy (opt in; default is atomic)')
+        .option('--atomic', 'Import flat components with no embedded-component hierarchy (default)')
         .action(async (opts) => {
         let inputs;
         try {
@@ -414,7 +473,6 @@ export function registerApplyCommand(program) {
             process.exit(0);
         }
     });
-    // --- apply push ---
     applyCmd
         .command('push')
         .description('Write component types and design tokens to Contentful ExO')
@@ -425,6 +483,8 @@ export function registerApplyCommand(program) {
         .requiredOption('--environment-id <id>', 'Contentful environment ID')
         .option('--cma-token <token>', 'CMA personal access token (or set CONTENTFUL_MANAGEMENT_TOKEN)')
         .option('--host <url>', 'Override API base URL')
+        .option('--composite', 'Import embedded-component hierarchy (opt in; default is atomic)')
+        .option('--atomic', 'Import flat components with no embedded-component hierarchy (default)')
         .option('--yes', 'Skip interactive confirmation')
         .option('--verbose', 'Show all entity progress including skipped/unchanged')
         .option('--force', 'Skip confirmation for breaking changes (for CI)')
@@ -445,6 +505,7 @@ export function registerApplyCommand(program) {
             throw e;
         }
         const { components, tokens, client } = inputs;
+        assertNoSlotCycles(components);
         try {
             await client.validateToken();
         }
@@ -465,7 +526,6 @@ export function registerApplyCommand(program) {
         }
         const spaceId = opts.spaceId;
         const environmentId = opts.environmentId;
-        // --- Dry run: print preview and exit ---
         if (opts.dryRun) {
             if (isTTY) {
                 const { waitUntilExit } = render(createElement(ServerPreviewApp, {
@@ -480,7 +540,6 @@ export function registerApplyCommand(program) {
             }
             process.exit(0);
         }
-        // --- Nothing to do: exit early without calling apply ---
         if (isEmptyPreview(preview)) {
             if (isTTY && !opts.yes) {
                 process.stderr.write('Nothing to change — design system is up to date.\n');
@@ -491,7 +550,6 @@ export function registerApplyCommand(program) {
             process.exit(0);
         }
         const breakingWithImpact = hasBreakingChangesWithImpact(preview);
-        // --- Non-interactive: require --force for breaking changes ---
         if (!isTTY || opts.yes) {
             if (breakingWithImpact && !opts.force) {
                 process.stderr.write('Error: breaking changes with downstream impact detected. Use --force to acknowledge.\n');
@@ -525,7 +583,6 @@ export function registerApplyCommand(program) {
             process.exit(operation.sys.status === 'succeeded' ? 0 : 1);
             return;
         }
-        // --- Interactive (TTY, no --yes) flow ---
         await new Promise((resolvePromise) => {
             const runApply = async (acknowledge) => {
                 instance.rerender(createElement(ServerApplyProgress, {
@@ -593,7 +650,6 @@ export function registerApplyCommand(program) {
             void instance.waitUntilExit().then(() => resolvePromise());
         });
     });
-    // --- apply select ---
     applyCmd
         .command('select')
         .description('Select a subset of entities and push to Contentful ExO')
@@ -604,6 +660,8 @@ export function registerApplyCommand(program) {
         .requiredOption('--environment-id <id>', 'Contentful environment ID')
         .option('--cma-token <token>', 'CMA personal access token (or set CONTENTFUL_MANAGEMENT_TOKEN)')
         .option('--host <url>', 'Override API base URL')
+        .option('--composite', 'Import embedded-component hierarchy (opt in; default is atomic)')
+        .option('--atomic', 'Import flat components with no embedded-component hierarchy (default)')
         .option('--select-all', 'Select all entities without launching TUI')
         .option('--select <pattern>', 'Select entities by ID pattern (repeatable)', collect, [])
         .option('--deselect <pattern>', 'Deselect entities by ID pattern (repeatable)', collect, [])
@@ -623,6 +681,7 @@ export function registerApplyCommand(program) {
             throw e;
         }
         const { components, tokens, client } = inputs;
+        assertNoSlotCycles(components);
         try {
             await client.validateToken();
         }
@@ -693,7 +752,6 @@ export function registerApplyCommand(program) {
             process.exit(operation.sys.status === 'succeeded' ? 0 : 1);
             return;
         }
-        // --- Interactive flow ---
         await new Promise((resolvePromise) => {
             const runSelectApply = async (selectedKeys) => {
                 const selectedComponentKeys = new Set();

package/dist/src/apply/error-parser.d.ts

@@ -0,0 +1,16 @@
+export interface ParsedEdsiError {
+    /** Server-side error code, if we could extract one. */
+    code: string | null;
+    /** Human-readable message, stripped of log/trace decoration. */
+    message: string;
+    /** Cycle participants, when `code === 'TopoSortCycleError'`. */
+    cycle: string[] | null;
+    /** True when the message survived cleaning as-is (no parseable structure). */
+    raw: boolean;
+}
+export declare function stripLambdaLogPrefix(body: string): string;
+export declare function parseEdsiError(rawInput: string | undefined | null): ParsedEdsiError;
+export declare function formatParsedEdsiError(parsed: ParsedEdsiError, opts?: {
+    verbose?: boolean;
+    raw?: string;
+}): string;

package/dist/src/apply/error-parser.js

@@ -0,0 +1,117 @@
+const LAMBDA_LOG_PREFIX_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\s+[0-9a-f-]+\s+ERROR\s+(?:\[dd\.[^\]]*\]\s*)?/;
+const DD_TAG_RE = /\[dd\.(?:trace_id|span_id)=[^\]]*\]\s*/g;
+export function stripLambdaLogPrefix(body) {
+    let out = body.replace(LAMBDA_LOG_PREFIX_RE, '');
+    out = out.replace(DD_TAG_RE, '');
+    return out.trim();
+}
+function parseObjectLiteralTail(body) {
+    const braceStart = body.lastIndexOf('{');
+    if (braceStart === -1)
+        return null;
+    const tail = body.slice(braceStart);
+    const codeMatch = tail.match(/code:\s*['"]([^'"]+)['"]/);
+    const cycleMatch = tail.match(/cycle:\s*\[\s*([^\]]*)\s*\]/);
+    if (!codeMatch && !cycleMatch)
+        return null;
+    const code = codeMatch ? codeMatch[1] : null;
+    let cycle = null;
+    if (cycleMatch) {
+        cycle = cycleMatch[1]
+            .split(',')
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+            .filter((s) => s.length > 0);
+        if (cycle.length === 0)
+            cycle = null;
+    }
+    return { code, cycle };
+}
+function parseJsonBody(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    const details = (p.details && typeof p.details === 'object' ? p.details : {});
+    const pick = (k) => (p[k] !== undefined ? p[k] : details[k]);
+    const codeRaw = pick('code');
+    const messageRaw = pick('message');
+    const cycleRaw = pick('cycle');
+    const out = {};
+    if (typeof codeRaw === 'string')
+        out.code = codeRaw;
+    if (typeof messageRaw === 'string')
+        out.message = messageRaw;
+    if (Array.isArray(cycleRaw)) {
+        const strs = cycleRaw.filter((x) => typeof x === 'string');
+        if (strs.length > 0)
+            out.cycle = strs;
+    }
+    return out;
+}
+// ApiError.message shape: `${phasePrefix}\n${body}` where phasePrefix looks
+// like `apply failed: 400`, `preview failed: 422`, `poll failed: 500`. We
+// only strip the prefix line when the first line matches this shape —
+// otherwise a raw body that happens to contain a newline (e.g. a Lambda log
+// spill with a multi-line object literal) gets truncated mid-structure.
+const API_ERROR_PREFIX_RE = /^(?:apply|preview|poll) failed: \d+$/;
+export function parseEdsiError(rawInput) {
+    if (!rawInput)
+        return { code: null, message: '', cycle: null, raw: true };
+    const nlIndex = rawInput.indexOf('\n');
+    let body = rawInput;
+    let prefix = '';
+    if (nlIndex !== -1) {
+        const firstLine = rawInput.slice(0, nlIndex);
+        if (API_ERROR_PREFIX_RE.test(firstLine)) {
+            prefix = firstLine;
+            body = rawInput.slice(nlIndex + 1);
+        }
+    }
+    const cleaned = stripLambdaLogPrefix(body);
+    const json = parseJsonBody(cleaned) ?? parseJsonBody(body);
+    if (json && (json.code || json.message || json.cycle)) {
+        return {
+            code: json.code ?? null,
+            message: json.message ?? (cleaned || prefix),
+            cycle: json.cycle ?? null,
+            raw: false,
+        };
+    }
+    const literal = parseObjectLiteralTail(cleaned);
+    if (literal && (literal.code || literal.cycle)) {
+        const braceStart = cleaned.lastIndexOf('{');
+        const head = braceStart === -1 ? cleaned : cleaned.slice(0, braceStart).trim();
+        return {
+            code: literal.code ?? null,
+            message: head || cleaned,
+            cycle: literal.cycle ?? null,
+            raw: false,
+        };
+    }
+    return { code: null, message: cleaned || prefix || rawInput, cycle: null, raw: true };
+}
+export function formatParsedEdsiError(parsed, opts = {}) {
+    const lines = [];
+    if (parsed.code) {
+        lines.push(`[${parsed.code}]`);
+    }
+    if (parsed.message) {
+        lines.push(parsed.message);
+    }
+    if (parsed.cycle && parsed.cycle.length > 0) {
+        lines.push(`Cycle: ${parsed.cycle.join(' → ')} → ${parsed.cycle[0]}`);
+        lines.push('Break the cycle by removing at least one $allowedComponents entry.');
+    }
+    if (opts.verbose && opts.raw) {
+        lines.push('');
+        lines.push('--- raw ---');
+        lines.push(opts.raw);
+    }
+    return lines.filter(Boolean).join('\n');
+}

package/dist/src/apply/tui/ServerPreviewView.js

@@ -3,7 +3,9 @@ import { Box, Text } from 'ink';
 function BreakingBadge({ item }) {
     if (!item.changeClassification || item.changeClassification.classification !== 'breaking')
         return null;
-    const reasons = item.changeClassification.breakingChanges.map((bc) => `${bc.propertyId}: ${bc.reason}`).join(', ');
+    const reasons = item.changeClassification.breakingChanges
+        .map((bc) => `${'slotId' in bc ? bc.slotId : bc.propertyId}: ${bc.reason}`)
+        .join(', ');
     return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: "red", children: [" \u26A0 BREAKING: ", reasons] }), item.impact && (item.impact.affectedFragments > 0 || item.impact.affectedExperiences > 0) && (_jsxs(Text, { color: "red", children: [' ', "\u2192 affects ", item.impact.affectedFragments, " Fragments, ", item.impact.affectedExperiences, " Experiences"] }))] }));
 }
 function DraftWarning({ hasDraft }) {

package/dist/src/credentials-store.d.ts

@@ -12,6 +12,12 @@ export type ExperiencesCredentials = {
     autoFilter?: boolean;
     /** Feature: default debug-mode (writes JSONL trace of every decision) for all commands. */
     debug?: boolean;
+    /**
+     * Feature (atomic mode): default composition mode. `atomic` (default) imports
+     * flat components with no embedded-component hierarchy; `composite` opts into
+     * the slot-graph machinery. Resolved `flag > env > this > default`.
+     */
+    compositionMode?: 'composite' | 'atomic';
 };
 /**
  * Read persisted Contentful credentials.

package/dist/src/credentials-store.js

@@ -35,6 +35,9 @@ export async function readExperiencesCredentials() {
             ...(parsed.generatePromptPath ? { generatePromptPath: parsed.generatePromptPath } : {}),
             ...(typeof parsed.autoFilter === 'boolean' ? { autoFilter: parsed.autoFilter } : {}),
             ...(typeof parsed.debug === 'boolean' ? { debug: parsed.debug } : {}),
+            ...(parsed.compositionMode === 'composite' || parsed.compositionMode === 'atomic'
+                ? { compositionMode: parsed.compositionMode }
+                : {}),
         };
     }
     catch {
@@ -48,7 +51,7 @@ export async function readExperiencesCredentials() {
     }
 }
 export async function writeExperiencesCredentials(creds) {
-    const { host: _host, agent, agentModel, selectPromptPath, generatePromptPath, autoFilter, debug, ...rest } = creds;
+    const { host: _host, agent, agentModel, selectPromptPath, generatePromptPath, autoFilter, debug, compositionMode, ...rest } = creds;
     const host = toConfiguredHost(creds.host);
     await mkdir(CREDENTIALS_DIR, { recursive: true });
     await writeFile(CREDENTIALS_PATH, JSON.stringify({
@@ -60,6 +63,7 @@ export async function writeExperiencesCredentials(creds) {
         ...(generatePromptPath ? { generatePromptPath } : {}),
         ...(typeof autoFilter === 'boolean' ? { autoFilter } : {}),
         ...(typeof debug === 'boolean' ? { debug } : {}),
+        ...(compositionMode === 'composite' || compositionMode === 'atomic' ? { compositionMode } : {}),
     }, null, 2) + '\n', { mode: 0o600 });
 }
 export function experiencesCredentialsPath() {

package/dist/src/generate/agent-runner.d.ts

@@ -96,6 +96,12 @@ export declare function runAgent(options: {
     timeoutMs: number;
     model?: string;
     onOutput?: (chunk: string) => void;
+    /**
+     * Deliver the prompt on stdin instead of as an argv positional. Required for
+     * large prompts (e.g. the composition resolver inlining candidate files),
+     * which overflow ARG_MAX when passed as an argument. Non-interactive only.
+     */
+    promptViaStdin?: boolean;
 }): Promise<AgentRunResult>;
 export type AgentAuthStatus = 'ok' | 'unauthenticated' | 'not-found';
 export declare function checkAgentAuth(agent: AgentName): Promise<AgentAuthStatus>;

package/dist/src/generate/agent-runner.js

@@ -225,25 +225,30 @@ export function resolveBinary(agent) {
         return override.trim();
     return AGENT_BINARIES[agent];
 }
-function buildArgs(agent, prompt, model) {
+function buildArgs(agent, prompt, model, promptViaStdin = false) {
     const m = model ?? DEFAULT_MODELS[agent];
+    // When the prompt is delivered on stdin, omit it from argv — a large prompt
+    // as a command-line argument overflows ARG_MAX (spawn E2BIG). All four CLIs
+    // read the prompt from stdin when it isn't passed positionally.
+    const promptArg = promptViaStdin ? [] : [prompt];
     switch (agent) {
         case 'claude':
-            return ['--print', '--model', m, prompt];
+            return ['--print', '--model', m, ...promptArg];
         case 'codex':
             // --dangerously-bypass-approvals-and-sandbox required for non-interactive use
-            return ['exec', '--model', m, '--dangerously-bypass-approvals-and-sandbox', prompt];
+            return ['exec', '--model', m, '--dangerously-bypass-approvals-and-sandbox', ...promptArg];
         case 'opencode':
-            return ['run', '--model', m, prompt];
+            return ['run', '--model', m, ...promptArg];
         case 'cursor':
             // cursor-agent uses --print for non-interactive stdout output
-            return ['--print', '--model', m, prompt];
+            return ['--print', '--model', m, ...promptArg];
     }
 }
 export async function runAgent(options) {
-    const { agent, prompt, interactive, timeoutMs, model, onOutput } = options;
+    const { agent, prompt, interactive, timeoutMs, model, onOutput, promptViaStdin } = options;
     const binary = resolveBinary(agent);
-    const args = buildArgs(agent, prompt, model);
+    const useStdin = !!promptViaStdin && !interactive;
+    const args = buildArgs(agent, prompt, model, useStdin);
     const debug = getDebugLogger();
     const startedAt = Date.now();
     debug.event('agent', 'run.start', {
@@ -260,7 +265,18 @@ export async function runAgent(options) {
             stdio: interactive ? 'inherit' : ['pipe', 'pipe', 'pipe'],
         });
         if (!interactive) {
-            child.stdin?.end();
+            if (useStdin && child.stdin) {
+                // Guard against EPIPE: the child may close stdin before we finish
+                // writing (fast exit, or it stops reading). Swallow the write error —
+                // the child's own exit code/stderr is the source of truth.
+                child.stdin.on('error', () => { });
+                child.stdin.write(prompt, () => {
+                    child.stdin?.end();
+                });
+            }
+            else {
+                child.stdin?.end();
+            }
         }
         let stdout = '';
         let stderr = '';