@contentful/experience-design-system-cli 2.18.1-dev-build-180092e.0 → 2.18.1-dev-build-0f85b83.0

package/dist/src/generate/prompt-builder.js

@@ -0,0 +1,213 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SKILL_FILES = {
+    components: 'generate-components.md',
+    tokens: 'generate-tokens.md',
+    select: 'select-components.md',
+};
+const OUTPUT_FILES = {
+    components: 'components.json',
+    tokens: 'tokens.json',
+    select: 'select.json',
+};
+export async function buildPrompt(options) {
+    const skillContent = await readSkillFile(options.skill, options.skillPathOverride);
+    const preamble = buildPreamble(options);
+    return `${preamble}\n\nSkill instructions follow:\n---\n${skillContent}`;
+}
+export function resolveSkillPath(skill) {
+    if (!(skill in SKILL_FILES))
+        throw new Error(`Invalid skill: ${skill}`);
+    // Walk up until we find the skills/ directory (works from both src/ and dist/src/ contexts)
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    let dir = thisDir;
+    for (;;) {
+        const candidate = join(dir, 'skills');
+        if (existsSync(candidate))
+            return join(candidate, SKILL_FILES[skill]);
+        const parent = resolve(dir, '..');
+        if (parent === dir) {
+            throw new Error(`skill file missing from CLI installation (could not locate skills/ directory from: ${thisDir})`);
+        }
+        dir = parent;
+    }
+}
+async function readSkillFile(skill, override) {
+    if (override) {
+        const skillPath = resolve(override);
+        try {
+            return await readFile(skillPath, 'utf8');
+        }
+        catch {
+            throw new Error(`custom prompt file not found (skill: ${skill}, path: ${skillPath})`);
+        }
+    }
+    const skillPath = resolveSkillPath(skill);
+    try {
+        return await readFile(skillPath, 'utf8');
+    }
+    catch {
+        throw new Error(`skill file missing from CLI installation — try reinstalling the CLI (looked for: ${skillPath})`);
+    }
+}
+function inferFenceLang(filename) {
+    if (!filename)
+        return 'json';
+    const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+    const map = {
+        js: 'js',
+        mjs: 'js',
+        cjs: 'js',
+        ts: 'ts',
+        mts: 'ts',
+        cts: 'ts',
+        scss: 'scss',
+        sass: 'scss',
+        css: 'css',
+        json: 'json',
+        json5: 'json',
+    };
+    return map[ext] ?? 'text';
+}
+function buildPreamble(options) {
+    const { skill, mode, rawComponentsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, outDir } = options;
+    const outputFile = OUTPUT_FILES[skill];
+    const outputPath = join(resolve(outDir), outputFile);
+    const sections = [];
+    if (rawComponentsInline) {
+        sections.push(`Raw component data (JSON):\n\`\`\`json\n${rawComponentsInline}\n\`\`\``);
+    }
+    if (rawTokensInline) {
+        const lang = inferFenceLang(rawTokensFilename);
+        const label = rawTokensFilename ? `Raw token source (${rawTokensFilename})` : 'Raw token source';
+        sections.push(`${label}:\n\`\`\`${lang}\n${rawTokensInline}\n\`\`\``);
+    }
+    if (tokensInline) {
+        sections.push(`DTCG token data (for token kind lookups):\n\`\`\`json\n${tokensInline}\n\`\`\``);
+    }
+    if (tokenMapInline) {
+        sections.push(`Token-name sidecar (raw name → DTCG path):\n\`\`\`json\n${tokenMapInline}\n\`\`\``);
+    }
+    const inputBlock = sections.length > 0 ? `\n\n${sections.join('\n\n')}` : '';
+    if (mode === 'autonomous') {
+        if (skill === 'components') {
+            return buildComponentsAutonomousPreamble(inputBlock);
+        }
+        if (skill === 'select') {
+            return buildSelectAutonomousPreamble(inputBlock);
+        }
+        return buildTokensAutonomousPreamble(inputBlock);
+    }
+    else {
+        return `You are running as part of the experience-design-system-cli generate pipeline in INTERACTIVE mode. The developer is present and will answer your questions.
+
+Your task: follow the skill instructions below, working collaboratively with the developer. Ask for confirmation on category corrections, prop exclusions, and grouping choices as the skill instructs.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+Output:
+Write the final ${outputFile} directly to: ${outputPath}`;
+    }
+}
+function buildComponentsAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Context: You are classifying a React component for **Contentful Experience Orchestration**. The result is a Component Type — a schema that tells Contentful what a marketer can configure. Properties fall into three categories:
+- **design**: controls how the component looks (variant, size, color, layout toggles)
+- **content**: the data a content editor fills in (text, images, URLs, rich text)
+- **state**: runtime behavioral flags (disabled, loading, expanded, identifiers)
+
+For props with complex TypeScript types (named types, enums): reason from the prop name and type name to classify them. Do not automatically exclude a prop just because its type is a named reference — infer the likely values and classify it as enum if it controls appearance.
+
+Your task: classify every prop and slot in the component below. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a "description" field on each tool call to document your reasoning so the developer can review it afterward.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per line to stdout for each classification decision. The CLI reads your stdout line by line and writes each decision directly to the pipeline database.
+
+The four tool calls you may emit are:
+
+\`\`\`
+{"tool":"classify_component","description":"<optional component-level description>","rationale":{"description":"<why this component is classified the way it is>","props":"<why these props were chosen>","slots":"<why these slots were chosen>"}}
+
+{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<short customer-facing description>","reason":"<full internal rationale; not customer-facing>","values":["a","b"],"token_kind":"color","default":"<value>"}
+
+{"tool":"exclude_prop","prop":"<propName>","reason":"<why excluded>"}
+
+{"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<reason>","rationale":"<why this slot was kept in the catalog>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences around the lines.
+- Every prop in the input must have exactly one call: either classify_prop or exclude_prop.
+- Every slot in the input must have exactly one classify_slot call.
+- Valid cdf_type values: string, richtext, media, enum, token, boolean
+- Valid cdf_category values: content, design, state
+- For enum type, always include "values" (non-empty string array).
+- For token type, always include "token_kind" (DTCG \$type, e.g. "color").
+- href and URL props → cdf_type "string", cdf_category "content". Do NOT use cdf_type "link" — it is not valid.
+- Framework internals (ref, event handlers, test IDs) → exclude_prop.
+- CSS design props (className, style, styles, positional/geometric props: top, bottom, left, right, rotation, offset, etc.) → classify_prop, cdf_type: "string", cdf_category: "design".
+- On classify_component, "rationale" fields are operator-facing (read-only) but may surface in customer-facing exports. The "rationale.description" field is subject to the description content rules in the skill prompt (no internal initiative names). "rationale.props" and "rationale.slots" describe your reasoning about scope; "classify_slot.rationale" explains why each slot was kept.
+- On classify_prop, "reason" is REQUIRED and is the LLM's internal rationale — shown to the developer reviewing the import, never to end-users. "description" is the customer-facing copy and is subject to the description content rules in the skill prompt. Keep them distinct: "description" is short and customer-facing; "reason" explains your reasoning in detail.
+- You may emit prose lines (not starting with {) anywhere — they are ignored by the parser and serve as your reasoning log.`;
+}
+function buildSelectAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli import pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Your task: review the components provided below and decide whether each belongs in Contentful Experience Orchestration as a Component Type. The input is a JSON array — you may receive 1–N components in a single message. Emit one tool call per input component, named after the component. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a brief "reason" to document your reasoning for each decision.
+
+Key rule: accept any component that renders visible UI — atoms, molecules, and organisms are all valid Component Types in Contentful Experience Orchestration. Reject only components that produce zero visual output: React hooks, pure context providers, A/B testing or variant-routing wrappers, analytics trackers, and security utilities. Do NOT reject a component because it has few props, is low-level, or has some A/B testing or personalization-related props mixed in — those props are handled in the generate step.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit JSON tool calls one per line to stdout. The CLI reads your stdout line by line.
+
+The two tool calls — emit exactly one per input component:
+
+\`\`\`
+{"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>"}
+
+{"tool":"reject_component","name":"<ComponentName>","reason":"<brief reason>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit exactly one tool call per input component. The "name" field must match a component name from the input array exactly. Tool calls may appear in any order.
+- You may emit prose lines (not starting with {) to reason before each tool call — they are ignored by the parser.`;
+}
+function buildTokensAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Your task: classify every raw token from the input below into a DTCG token tree. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a "description" field on each set_token call to document your reasoning.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per line to stdout for each token or group. The CLI reads your stdout line by line and writes each entry directly to the pipeline database.
+
+The two tool calls you may emit are:
+
+\`\`\`
+{"tool":"set_group","path":"<dot.notation.path>","description":"<optional group description>"}
+
+{"tool":"set_token","path":"<dot.notation.path>","type":"<DTCG type>","value":<value>,"description":"<reason>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit a set_group call for every intermediate group node in the tree.
+- Emit a set_token call for every leaf token.
+- "path" is dot-notation, e.g. "colors.brand.primary" — no leading dots or slashes.
+- "type" must be one of the 13 valid DTCG types: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, strokeStyle, border, transition, shadow, gradient, typography.
+- "value" must be valid JSON (string, number, array, or object depending on the type). Do NOT wrap it in quotes if it is a complex type.
+- Emit set_group calls before the set_token calls that fall under them.
+- You may emit prose lines (not starting with {) anywhere — they are ignored by the parser and serve as your reasoning log.`;
+}

package/dist/src/import/command.js

@@ -4,7 +4,7 @@ import { resolveAutoFilter } from './auto-filter-resolve.js';
 import { resolveAgent, resolveModel } from './agent-model-resolve.js';
 import { addAgentModelOptions } from '../lib/agent-model-options.js';
 import { resolveCompositionMode } from '../lib/composition-mode.js';
-import { addCompositionOptions } from '../lib/command-options.js';
+import { addAllowDeletionsOption, addCompositionOptions } from '../lib/command-options.js';
 import { isConflictMode } from '../runs/save-path-resolver.js';
 import { readExperiencesCredentials } from '../credentials-store.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../host-utils.js';
@@ -46,6 +46,7 @@ export function registerImportCommand(program) {
         .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)');
     addCompositionOptions(cmd);
+    addAllowDeletionsOption(cmd);
     cmd
         .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)')
@@ -136,6 +137,7 @@ export function registerImportCommand(program) {
                     ...(opts.host ? { host: opts.host } : {}),
                     interactive: interactiveTerminalSupported,
                     ...(opts.force ? { force: true } : {}),
+                    ...(opts.allowDeletions ? { allowDeletions: true } : {}),
                 });
                 return;
             }
@@ -166,6 +168,7 @@ export function registerImportCommand(program) {
                     ...(opts.saveAsNew ? { saveAsNew: true } : {}),
                     ...(opts.outDir ? { outDir: opts.outDir } : {}),
                     ...(opts.force ? { force: true } : {}),
+                    ...(opts.allowDeletions ? { allowDeletions: true } : {}),
                 });
                 return;
             }
@@ -297,6 +300,7 @@ export function registerImportCommand(program) {
                 selectPromptPath: opts.selectPromptPath ?? creds.selectPromptPath,
                 generatePromptPath: opts.generatePromptPath ?? creds.generatePromptPath,
                 ...(opts.rawTokens ? { initialRawTokensPath: resolve(opts.rawTokens) } : {}),
+                allowDeletions: opts.allowDeletions === true,
                 ...pickerProps,
             }));
             unmountInk = unmount;
@@ -357,6 +361,7 @@ export function registerImportCommand(program) {
             dryRun: dryRunForward,
             selectPromptPath: opts.selectPromptPath,
             autoRejectCycles: opts.autoRejectCycles ?? false,
+            allowDeletions: opts.allowDeletions ?? false,
             compositionMode: headlessCompositionMode,
             ...(opts.compositionMap ? { compositionMap: opts.compositionMap } : {}),
             ...(opts.compositionAgent ? { compositionAgent: true } : {}),

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

@@ -26,6 +26,7 @@ export interface PipelineOptions {
     selectPromptPath?: string;
     /** When true, auto-reject cycle participants and retry push instead of surfacing an error. */
     autoRejectCycles?: boolean;
+    allowDeletions?: boolean;
     compositionMode?: CompositionMode;
     compositionMap?: string;
     compositionAgent?: boolean;

package/dist/src/import/orchestrator.js

@@ -418,6 +418,8 @@ export async function runPipeline(opts, progressWriter, cliPathOverride) {
             pushArgs.push('--host', opts.host);
         if (opts.verbose)
             pushArgs.push('--verbose');
+        if (opts.allowDeletions)
+            pushArgs.push('--allow-deletions');
         pushArgs.push('--yes');
         const pushStepId = createStep(db, sessionId, 'apply push', {
             components: componentsPath,

package/dist/src/import/tui/WizardApp.d.ts

@@ -66,5 +66,6 @@ export type WizardAppProps = {
     initialRawTokensPath?: string;
     initialRuns?: RunRecord[];
     onRunPicked?: (selection: RunPickerSelection) => void;
+    allowDeletions?: boolean;
 };
-export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope, autoRejectCycles, compositionMode, compositionMap, compositionAgent, compositionAgentMode, compositionRefresh, generateMap, promptOverrides, noCache, autoFilter, livePreview, noPush, noSave, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, }?: WizardAppProps): React.ReactElement;
+export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope, autoRejectCycles, compositionMode, compositionMap, compositionAgent, compositionAgentMode, compositionRefresh, generateMap, promptOverrides, noCache, autoFilter, livePreview, noPush, noSave, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, allowDeletions, }?: WizardAppProps): React.ReactElement;

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

@@ -50,7 +50,7 @@ import { mergeAiDecisions } from './merge-ai-decisions.js';
 import { FinalReviewHost } from './final-review-host.js';
 import { runScopeGate } from './runScopeGate.js';
 import { buildAutoFilterErrorTail } from './auto-filter-error.js';
-import { checkAgentAuth } from '@contentful/experience-design-system-generation';
+import { checkAgentAuth } from '../../generate/agent-runner.js';
 import { normalizePath } from '../path-utils.js';
 import { DEFAULT_CONFIGURED_HOST, toConfiguredHost } from '../../host-utils.js';
 import { writeExperiencesCredentials } from '../../credentials-store.js';
@@ -138,7 +138,7 @@ function logStep(entry) {
     appendFileSync(WIZARD_LOG, line);
     getDebugLogger().event('wizard', 'step', entry);
 }
-export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope = false, autoRejectCycles = false, compositionMode = 'atomic', compositionMap, compositionAgent = false, compositionAgentMode, compositionRefresh = false, generateMap, promptOverrides, noCache = false, autoFilter = true, livePreview = true, noPush = false, noSave = false, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, } = {}) {
+export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master', initialCmaToken = '', initialHost, initialAgent, initialModel, initialProjectPath, host, autoAcceptScope = false, autoRejectCycles = false, compositionMode = 'atomic', compositionMap, compositionAgent = false, compositionAgentMode, compositionRefresh = false, generateMap, promptOverrides, noCache = false, autoFilter = true, livePreview = true, noPush = false, noSave = false, outDirOverride, onConflictMode, selectPromptPath, generatePromptPath, seedExtractSessionId, seedGenerateSessionId, seedTokenSessionId, seedTokensPath, initialStep, initialRawTokensPath, initialRuns, onRunPicked, allowDeletions = false, } = {}) {
     const defaultConfiguredHost = toConfiguredHost(host || process.env['EDS_HOST']) ?? DEFAULT_CONFIGURED_HOST;
     const resolveWizardHost = (hostValue) => hostValue || defaultConfiguredHost;
     const { stdout } = useStdout();
@@ -826,7 +826,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 tokens = await readTokensFromPath('tokens', tokensPath);
             }
             let manifest = buildManifest(components, tokens, { deleteAllComponents: allowEmptyDeleteAllRef.current });
-            let preview = await client.previewImport(manifest);
+            let preview = await client.previewImport(manifest, allowDeletions);
             if (extractSessionId) {
                 let needsRepreview = false;
                 const db = openPipelineDb();
@@ -848,7 +848,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                     if (needsRepreview) {
                         components = loadCDFComponents(db, extractSessionId);
                         manifest = buildManifest(components, tokens, { deleteAllComponents: allowEmptyDeleteAllRef.current });
-                        preview = await client.previewImport(manifest);
+                        preview = await client.previewImport(manifest, allowDeletions);
                     }
                 }
                 finally {
@@ -942,7 +942,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
             });
         }
     };
-    const runPush = async (manifest, spaceId, environmentId, cmaToken, host, acknowledgeBreakingChanges, preview) => {
+    const runPush = async (manifest, spaceId, environmentId, cmaToken, host, acknowledgeBreakingChanges, allowDeletions, preview) => {
         if (shouldRefusePush(state)) {
             update(buildSkippedPushTransition());
             return;
@@ -982,7 +982,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 environmentId,
                 host: resolvedHost,
             });
-            let operation = await client.applyImport(manifest, acknowledgeBreakingChanges);
+            let operation = await client.applyImport(manifest, { acknowledgeBreakingChanges, allowDeletions });
             try {
                 logStep({
                     applyResponse: {
@@ -1433,7 +1433,7 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 return (_jsx(RunningStep, { stepNumber: stepNum, totalSteps: totalSteps, title: "Generating definitions", description: `${formatAcceptanceSummary({ accepted: state.acceptedCount, autoRejected: state.autoRejectedCount })} ${state.agent} is mapping your TypeScript types to Contentful's CDF format.${hasTokens ? ' Using your design tokens for prop resolution.' : ''}`, detail: progressDetail }));
             }
             case 'final-review': {
-                return (_jsx(FinalReviewHost, { extractSessionId: state.extractSessionId, generatedCount: state.generatedCount, autoAccept: autoAcceptScope, compositionMode: compositionMode, livePreview: livePreview, spaceId: state.spaceId, environmentId: state.environmentId, cmaToken: state.cmaToken, host: state.host, tokensPath: state.tokensPath, initialFinalizeError: state.finalizeErrorBanner, onFinalize: (accepted, rejected, unresolved) => {
+                return (_jsx(FinalReviewHost, { extractSessionId: state.extractSessionId, generatedCount: state.generatedCount, autoAccept: autoAcceptScope, compositionMode: compositionMode, livePreview: livePreview, spaceId: state.spaceId, environmentId: state.environmentId, cmaToken: state.cmaToken, host: state.host, tokensPath: state.tokensPath, initialFinalizeError: state.finalizeErrorBanner, allowDeletions: allowDeletions, onFinalize: (accepted, rejected, unresolved) => {
                         process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}  Unresolved: ${unresolved}\n`);
                         let acceptedCount = accepted;
                         const detectAcceptedCycles = () => {
@@ -1601,8 +1601,8 @@ export function WizardApp({ initialSpaceId = '', initialEnvironmentId = 'master'
                 // present-but-empty (only $schema), so editing would dead-end on the
                 // "No generated definitions found" screen.
                 const editableComponentCount = Object.keys(state.manifest?.componentsManifest ?? {}).filter((k) => k !== '$schema').length;
-                return (_jsx(WizardPreviewStep, { preview: state.serverPreview, spaceId: state.spaceId, environmentId: state.environmentId, stepNumber: totalSteps, totalSteps: totalSteps, onConfirm: (acknowledge) => {
-                        void runPush(state.manifest, state.spaceId, state.environmentId, state.cmaToken, state.host, acknowledge, state.serverPreview);
+                return (_jsx(WizardPreviewStep, { preview: state.serverPreview, spaceId: state.spaceId, environmentId: state.environmentId, stepNumber: totalSteps, totalSteps: totalSteps, allowDeletions: allowDeletions, onConfirm: (acknowledge, deleteMissing) => {
+                        void runPush(state.manifest, state.spaceId, state.environmentId, state.cmaToken, state.host, acknowledge, deleteMissing, state.serverPreview);
                     }, ...(editableComponentCount > 0 ? { onEdit: () => void runEditFromPreview() } : {}), onSaveFiles: () => {
                         void startSaveFlow();
                     }, onQuit: () => process.exit(0) }));

package/dist/src/import/tui/final-review-host.d.ts

@@ -14,5 +14,6 @@ export type FinalReviewHostProps = {
     host?: string;
     tokensPath?: string;
     initialFinalizeError?: string | null;
+    allowDeletions?: boolean;
 };
-export declare function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, compositionMode, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: FinalReviewHostProps): React.ReactElement;
+export declare function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, compositionMode, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, allowDeletions, }: FinalReviewHostProps): React.ReactElement;

package/dist/src/import/tui/final-review-host.js

@@ -4,7 +4,7 @@ import { PALETTE } from '../../analyze/select/tui/theme.js';
 import React from 'react';
 import { GenerateReviewStep } from './steps/GenerateReviewStep.js';
 import { AtomicGenerateReviewStep } from './steps/AtomicGenerateReviewStep.js';
-export function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, compositionMode = 'atomic', onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }) {
+export function FinalReviewHost({ extractSessionId, generatedCount, autoAccept, compositionMode = 'atomic', onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, allowDeletions, }) {
     if (!extractSessionId) {
         return (_jsx(Box, { paddingX: 2, paddingY: 1, children: _jsx(Text, { color: PALETTE.error, children: "Error: no session ID \u2014 cannot load generated definitions." }) }));
     }
@@ -15,7 +15,7 @@ export function FinalReviewHost({ extractSessionId, generatedCount, autoAccept,
     // passes projectSlotGraph to FieldEditor and never walks closures/cycles, so
     // slot-composition editing and every hierarchy affordance stay absent.
     const StepComponent = compositionMode === 'atomic' ? AtomicGenerateReviewStep : GenerateReviewStep;
-    return (_jsx(StepComponent, { extractSessionId: extractSessionId, onFinalize: onFinalize, onQuit: onQuit, livePreview: livePreview, spaceId: spaceId, environmentId: environmentId, cmaToken: cmaToken, host: host, tokensPath: tokensPath, initialFinalizeError: initialFinalizeError }));
+    return (_jsx(StepComponent, { extractSessionId: extractSessionId, onFinalize: onFinalize, onQuit: onQuit, livePreview: livePreview, spaceId: spaceId, environmentId: environmentId, cmaToken: cmaToken, host: host, tokensPath: tokensPath, initialFinalizeError: initialFinalizeError, ...(compositionMode !== 'atomic' ? { allowDeletions } : {}) }));
 }
 function FinalReviewAutoAccept({ generatedCount, onFinalize, }) {
     React.useEffect(() => {

package/dist/src/import/tui/runLivePreview.d.ts

@@ -26,6 +26,9 @@ export type RunLivePreviewOptions = {
      *  full delete. Lets the Finalize dialog show exactly what the accepted push
      *  would delete, independent of the session's on-disk generated rows. */
     acceptedKeys?: ReadonlySet<string>;
+    /** Forwarded verbatim to `previewImport`. Governs whether the response
+     *  includes removed entities or a suppressed-count summary instead. */
+    allowDeletions?: boolean;
 };
 /**
  * Pure async helper used by `useLivePreview` to re-fire `previewImport` after a

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

@@ -60,7 +60,10 @@ export async function runLivePreview(opts) {
         timeoutHandle = setTimeout(() => reject(new TimeoutError()), timeoutMs);
     });
     try {
-        const response = (await Promise.race([client.previewImport(manifest), timeoutPromise]));
+        const response = (await Promise.race([
+            client.previewImport(manifest, opts.allowDeletions === true),
+            timeoutPromise,
+        ]));
         if (process.env['EDS_VERBOSE']) {
             const durationMs = Date.now() - startedAt;
             try {

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

@@ -11,6 +11,7 @@ type GenerateReviewStepProps = {
     host?: string;
     tokensPath?: string;
     initialFinalizeError?: string | null;
+    allowDeletions?: boolean;
 };
 export declare function sortComponentsForSidebar<T extends {
     key: string;
@@ -33,4 +34,4 @@ export interface BreakingRow {
 }
 export declare function buildBreakingRows(breakingChanges: BreakingComponent[]): BreakingRow[];
 export declare function deriveBreakingChanges(response: ServerPreviewResponse): BreakingComponent[];
-export declare function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, }: GenerateReviewStepProps): React.ReactElement;
+export declare function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview, spaceId, environmentId, cmaToken, host, tokensPath, initialFinalizeError, allowDeletions, }: GenerateReviewStepProps): React.ReactElement;

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

@@ -174,7 +174,7 @@ export function deriveBreakingChanges(response) {
     }
     return out;
 }
-export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview = true, spaceId = '', environmentId = '', cmaToken = '', host = '', tokensPath = '', initialFinalizeError = null, }) {
+export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, livePreview = true, spaceId = '', environmentId = '', cmaToken = '', host = '', tokensPath = '', initialFinalizeError = null, allowDeletions = false, }) {
     const { stdout } = useStdout();
     const terminalWidth = stdout?.columns ?? 80;
     const [components, setComponents] = useState([]);
@@ -271,9 +271,8 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
         cmaToken,
         host,
         onResult: handleLivePreviewResult,
-        // With nothing accepted, preview the delete-all diff so the review UI shows
-        // which existing components a push would remove (instead of an empty preview).
         deleteAllComponents: acceptedCountForPreview === 0,
+        allowDeletions,
     });
     const SPINNER_FRAMES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏';
     const [spinnerTick, setSpinnerTick] = useState(0);
@@ -352,6 +351,7 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, liveP
         cmaToken,
         host,
         acceptedKeys: new Set(components.filter((c) => c.status === 'accepted').map((c) => c.key)),
+        allowDeletions,
     });
     const handleFinalizeConfirm = () => {
         const acceptedCount = components.filter((c) => c.status === 'accepted').length;

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

@@ -12,10 +12,14 @@ type WizardPreviewStepProps = {
     environmentId: string;
     stepNumber: number;
     totalSteps: number;
-    onConfirm: (acknowledge: boolean) => void;
+    /** The value the preview was actually fetched with — not a hint. When
+     *  `false`, the server never returned removed entities, so there is
+     *  nothing to render item-by-item or toggle over. */
+    allowDeletions?: boolean;
+    onConfirm: (acknowledge: boolean, allowDeletions: boolean) => void;
     onEdit?: () => void;
     onSaveFiles?: () => void;
     onQuit: () => void;
 };
-export declare function WizardPreviewStep({ preview, spaceId, environmentId, stepNumber, totalSteps, onConfirm, onEdit, onSaveFiles, onQuit, }: WizardPreviewStepProps): React.ReactElement;
+export declare function WizardPreviewStep({ preview, spaceId, environmentId, stepNumber, totalSteps, allowDeletions: fetchedAllowDeletions, onConfirm, onEdit, onSaveFiles, onQuit, }: WizardPreviewStepProps): React.ReactElement;
 export {};

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

@@ -89,10 +89,14 @@ export function buildPreviewDiffLines(preview) {
     }
     return lines;
 }
-export function WizardPreviewStep({ preview, spaceId, environmentId, stepNumber, totalSteps, onConfirm, onEdit, onSaveFiles, onQuit, }) {
+export function WizardPreviewStep({ preview, spaceId, environmentId, stepNumber, totalSteps, allowDeletions: fetchedAllowDeletions = false, onConfirm, onEdit, onSaveFiles, onQuit, }) {
     const breakingWithImpact = hasBreakingChangesWithImpact(preview);
     const [diffExpanded, setDiffExpanded] = useState(false);
     const [scrollOffset, setScrollOffset] = useState(0);
+    // Local state exists only to let the user opt OUT of a deletion the fetch
+    // already surfaced — it can never turn true when the fetch used false,
+    // because there's nothing in `preview` to reveal in that case.
+    const [allowDeletions, setAllowDeletions] = useState(fetchedAllowDeletions);
     const { stdout } = useStdout();
     const terminalRows = stdout?.rows ?? 40;
     const viewportHeight = Math.max(terminalRows - 14, 10);
@@ -105,9 +109,14 @@ export function WizardPreviewStep({ preview, spaceId, environmentId, stepNumber,
         }));
     }, [diffExpanded, preview]);
     const maxScroll = Math.max(0, allDiffLines.length - viewportHeight);
+    const removedCount = preview.components.removed.length + preview.tokens.removed.length;
     useImmediateInput((input, key) => {
         if (key.return) {
-            onConfirm(breakingWithImpact);
+            onConfirm(breakingWithImpact, allowDeletions);
+            return;
+        }
+        if ((input === 'x' || input === 'X') && fetchedAllowDeletions && removedCount > 0) {
+            setAllowDeletions((prev) => !prev);
             return;
         }
         if (input === 'd' || input === 'D') {
@@ -156,5 +165,5 @@ export function WizardPreviewStep({ preview, spaceId, environmentId, stepNumber,
                                     })] })), components.changed.length > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.warning, children: " \uFF5E" }), _jsxs(Text, { children: [components.changed.length, " will be updated"] })] }), components.changed.map((item, i) => {
                                         const isBreaking = item.changeClassification?.classification === 'breaking';
                                         return (_jsxs(Text, { color: isBreaking ? PALETTE.error : PALETTE.warning, children: [' ', isBreaking ? '⚠' : '~', " ", item.current.name] }, `chg-${i}`));
-                                    })] })), components.removed.length > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.error, children: " \u2717" }), _jsxs(Text, { children: [components.removed.length, " will be removed"] })] }), components.removed.map((item, i) => (_jsxs(Text, { color: PALETTE.error, children: [' ', "\u2717 ", item.name] }, `rm-${i}`)))] })), components.unchanged.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: " \u00B7" }), _jsxs(Text, { dimColor: true, children: [components.unchanged.length, " unchanged"] })] }))] })), hasTokens && (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Box, { gap: 1, marginTop: 1, children: _jsx(Text, { bold: true, dimColor: true, children: "Design Tokens" }) }), tokens.new.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.success, children: " \uFF0B" }), _jsxs(Text, { children: [tokens.new.length, " will be created"] })] })), tokens.changed.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.warning, children: " \uFF5E" }), _jsxs(Text, { children: [tokens.changed.length, " will be updated"] })] })), tokens.removed.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.error, children: " \u2717" }), _jsxs(Text, { children: [tokens.removed.length, " will be removed"] })] })), tokens.unchanged.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: " \u00B7" }), _jsxs(Text, { dimColor: true, children: [tokens.unchanged.length, " unchanged"] })] }))] })), diffExpanded && allDiffLines.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { dimColor: true, children: '─'.repeat(40) }), _jsxs(Text, { dimColor: true, children: [' ', "Diff (", allDiffLines.length, " lines) \u2014 line ", scrollOffset + 1, "\u2013", Math.min(scrollOffset + viewportHeight, allDiffLines.length), " of ", allDiffLines.length] }), _jsx(Box, { flexDirection: "column", children: allDiffLines.slice(scrollOffset, scrollOffset + viewportHeight).map((line) => (_jsx(Box, { children: line.element }, line.key))) }), maxScroll > 0 && _jsx(Text, { dimColor: true, children: " \u2195 j/k to scroll, f/b to page" })] }))] })) : (_jsx(Text, { dimColor: true, children: "Nothing to push \u2014 everything is already up to date." })), _jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "Space:" }), _jsx(Text, { children: spaceId }), _jsx(Text, { dimColor: true, children: "/" }), _jsx(Text, { dimColor: true, children: "Environment:" }), _jsx(Text, { children: environmentId })] }), breakingWithImpact && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: PALETTE.error, bold: true, children: "\u26A0 Breaking changes will affect downstream entities. Press Enter to acknowledge and apply." }) })), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[Enter] Push to Contentful" }), _jsxs(Text, { dimColor: true, children: ["[d] ", diffExpanded ? 'Hide' : 'Show', " diff"] }), diffExpanded && _jsx(Text, { dimColor: true, children: "[j/k] Scroll [f/b] Page" }), onEdit && _jsx(Text, { dimColor: true, children: "[e] Edit definitions" }), onSaveFiles && _jsx(Text, { dimColor: true, children: "[s] Save files instead" }), _jsx(Text, { dimColor: true, children: "[q] Cancel" })] })] }));
+                                    })] })), components.removed.length > 0 && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: allowDeletions ? PALETTE.error : PALETTE.warning, children: allowDeletions ? ' ✗' : ' ⊘' }), _jsxs(Text, { children: [components.removed.length, " will be ", allowDeletions ? 'deleted' : 'skipped'] })] }), components.removed.map((item, i) => (_jsxs(Text, { color: allowDeletions ? PALETTE.error : PALETTE.warning, dimColor: !allowDeletions, children: [' ', allowDeletions ? '✗' : '⊘', " ", item.name] }, `rm-${i}`)))] })), components.unchanged.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: " \u00B7" }), _jsxs(Text, { dimColor: true, children: [components.unchanged.length, " unchanged"] })] }))] })), hasTokens && (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Box, { gap: 1, marginTop: 1, children: _jsx(Text, { bold: true, dimColor: true, children: "Design Tokens" }) }), tokens.new.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.success, children: " \uFF0B" }), _jsxs(Text, { children: [tokens.new.length, " will be created"] })] })), tokens.changed.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.warning, children: " \uFF5E" }), _jsxs(Text, { children: [tokens.changed.length, " will be updated"] })] })), tokens.removed.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: allowDeletions ? PALETTE.error : PALETTE.warning, children: allowDeletions ? ' ✗' : ' ⊘' }), _jsxs(Text, { children: [tokens.removed.length, " will be ", allowDeletions ? 'deleted' : 'skipped'] })] })), tokens.unchanged.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: " \u00B7" }), _jsxs(Text, { dimColor: true, children: [tokens.unchanged.length, " unchanged"] })] }))] })), diffExpanded && allDiffLines.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { dimColor: true, children: '─'.repeat(40) }), _jsxs(Text, { dimColor: true, children: [' ', "Diff (", allDiffLines.length, " lines) \u2014 line ", scrollOffset + 1, "\u2013", Math.min(scrollOffset + viewportHeight, allDiffLines.length), " of ", allDiffLines.length] }), _jsx(Box, { flexDirection: "column", children: allDiffLines.slice(scrollOffset, scrollOffset + viewportHeight).map((line) => (_jsx(Box, { children: line.element }, line.key))) }), maxScroll > 0 && _jsx(Text, { dimColor: true, children: " \u2195 j/k to scroll, f/b to page" })] }))] })) : (_jsx(Text, { dimColor: true, children: "Nothing to push \u2014 everything is already up to date." })), !fetchedAllowDeletions && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: PALETTE.warning, children: " \u2298" }), _jsx(Text, { children: "Deletions are hidden by default \u2014 rerun with --allow-deletions to see them." })] })), _jsxs(Box, { gap: 1, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "Space:" }), _jsx(Text, { children: spaceId }), _jsx(Text, { dimColor: true, children: "/" }), _jsx(Text, { dimColor: true, children: "Environment:" }), _jsx(Text, { children: environmentId })] }), breakingWithImpact && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: PALETTE.error, bold: true, children: "\u26A0 Breaking changes will affect downstream entities. Press Enter to acknowledge and apply." }) })), allowDeletions && removedCount > 0 && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: PALETTE.error, bold: true, children: ["\u26A0 ", removedCount, " missing ", removedCount === 1 ? 'entity' : 'entities', " will be permanently deleted. Press Enter to confirm."] }) })), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[Enter] Push to Contentful" }), _jsxs(Text, { dimColor: true, children: ["[d] ", diffExpanded ? 'Hide' : 'Show', " diff"] }), diffExpanded && _jsx(Text, { dimColor: true, children: "[j/k] Scroll [f/b] Page" }), onEdit && _jsx(Text, { dimColor: true, children: "[e] Edit definitions" }), onSaveFiles && _jsx(Text, { dimColor: true, children: "[s] Save files instead" }), fetchedAllowDeletions && removedCount > 0 && (_jsxs(Text, { dimColor: true, children: ["[x] ", allowDeletions ? '[✓]' : '[ ]', " Also delete ", removedCount, " ", removedCount === 1 ? 'entity' : 'entities'] })), _jsx(Text, { dimColor: true, children: "[q] Cancel" })] })] }));
 }

package/dist/src/import/tui/useFinalizePreview.d.ts

@@ -11,6 +11,8 @@ export type UseFinalizePreviewOptions = {
     host: string;
     /** Component keys the operator has accepted; drives the scoped preview. */
     acceptedKeys: ReadonlySet<string>;
+    /** Forwarded verbatim to `runLivePreview`/`previewImport`. */
+    allowDeletions?: boolean;
 };
 export type UseFinalizePreviewReturn = {
     status: FinalizePreviewStatus;

package/dist/src/import/tui/useLivePreview.d.ts

@@ -12,6 +12,8 @@ export type UseLivePreviewOptions = {
     /** Preview an empty-but-present manifest (delete-all diff) when nothing is
      *  accepted, so the final-review UI can show what a push would delete. */
     deleteAllComponents?: boolean;
+    /** Forwarded verbatim to `runLivePreview`/`previewImport`. */
+    allowDeletions?: boolean;
 };
 export type LivePreviewStatus = 'idle' | 'running';
 export type UseLivePreviewReturn = {

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

@@ -82,6 +82,7 @@ export function useLivePreview(opts) {
                 host: current.host,
                 generation,
                 deleteAllComponents: current.deleteAllComponents === true,
+                allowDeletions: current.allowDeletions === true,
             });
             // Discard stale responses (generation tag).
             if (result.generation !== latestRef.current)

package/dist/src/lib/agent-model-options.js

@@ -1,4 +1,4 @@
-import { AGENT_NAMES } from '@contentful/experience-design-system-generation';
+import { AGENT_NAMES } from './agent-names.js';
 export const AGENT_DESCRIPTION = `Agent to use: ${AGENT_NAMES.join(', ')} (defaults to value saved by experiences setup)`;
 export const MODEL_DESCRIPTION = 'Model to use (defaults to a lightweight per-agent model; override with EDS_AGENT_MODEL_<AGENT>)';
 /**

package/dist/src/lib/agent-names.d.ts

@@ -0,0 +1,4 @@
+export declare const AGENT_NAMES: readonly ["claude", "codex", "opencode", "cursor"];
+export type AgentName = (typeof AGENT_NAMES)[number];
+export declare const DEFAULT_AGENT_NAME: AgentName;
+export declare function isAgentName(value: string): value is AgentName;

package/dist/src/lib/agent-names.js

@@ -0,0 +1,5 @@
+export const AGENT_NAMES = ['claude', 'codex', 'opencode', 'cursor'];
+export const DEFAULT_AGENT_NAME = 'claude';
+export function isAgentName(value) {
+    return AGENT_NAMES.includes(value);
+}

package/dist/src/lib/command-options.d.ts

@@ -3,3 +3,4 @@ export declare function addArtifactInputOptions(cmd: Command): Command;
 export declare function addContentfulTargetOptions(cmd: Command): Command;
 export declare function addCompositionOptions(cmd: Command): Command;
 export declare function addSelectionOptions(cmd: Command): Command;
+export declare function addAllowDeletionsOption(cmd: Command): Command;

package/dist/src/lib/command-options.js

@@ -25,3 +25,6 @@ export function addSelectionOptions(cmd) {
         .option('--select <pattern>', 'Select entities by ID pattern (repeatable)', collectOptionValue, [])
         .option('--deselect <pattern>', 'Deselect entities by ID pattern (repeatable)', collectOptionValue, []);
 }
+export function addAllowDeletionsOption(cmd) {
+    return cmd.option('--allow-deletions', 'Allow the push to delete remote ComponentTypes/DesignTokens missing from the manifest (default: skip them)');
+}

package/dist/src/runs/modify-launcher.d.ts

@@ -26,5 +26,7 @@ export type ModifyLauncherInput = {
     initialHost?: string;
     /** Pre-fill CMA token (from credentials.json / env). */
     initialCmaToken?: string;
+    /** From `--allow-deletions` flag. Forwarded to wizard's push step. */
+    allowDeletions?: boolean;
 };
 export declare function launchModifyWizard(input: ModifyLauncherInput): Promise<void>;