@contentful/experience-design-system-cli 2.7.4 → 2.11.0

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

@@ -1,7 +1,7 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { useImmediateInput } from '../../../analyze/select/tui/hooks/useImmediateInput.js';
-export function GateStep({ successMessage, summary, context, continueLabel = 'Continue', skipLabel = 'Approve all and skip', onContinue, onSkip, onQuit, showSkip = true, }) {
+export function GateStep({ successMessage, summary, context, continueLabel = 'Continue', skipLabel = 'Approve all and skip', onContinue, onSkip, onQuit, showSkip = true, intent = 'success', }) {
     useImmediateInput((input, key) => {
         if (key.return) {
             onContinue();
@@ -16,5 +16,7 @@ export function GateStep({ successMessage, summary, context, continueLabel = 'Co
             return;
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { color: "green", children: ["\u2713 ", successMessage] }), summary && _jsx(Text, { dimColor: true, children: summary }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: context }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: ["[Enter] ", continueLabel] }), showSkip && onSkip && _jsxs(Text, { dimColor: true, children: ["[a] ", skipLabel] }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
+    const headerColor = intent === 'error' ? 'red' : 'green';
+    const headerIcon = intent === 'error' ? '✗' : '✓';
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { color: headerColor, children: [headerIcon, " ", successMessage] }), summary && _jsx(Text, { dimColor: true, children: summary }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: context }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: ["[Enter] ", continueLabel] }), showSkip && onSkip && _jsxs(Text, { dimColor: true, children: ["[a] ", skipLabel] }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
 }

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

@@ -187,6 +187,8 @@ export function GenerateReviewStep({ extractSessionId, onFinalize, onQuit, }) {
         status: c.status,
         extractionConfidence: null,
         needsReview: false,
+        validationErrorCount: 0,
+        validationWarningCount: 0,
     }));
     const longestName = components.reduce((m, c) => Math.max(m, c.key.length), 0);
     const sidebarWidth = Math.min(Math.max(longestName + 4, 14), 22);

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

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { PreviewValidationError } from '../../../apply/api-client.js';
+type PreviewValidationErrorStepProps = {
+    errors: PreviewValidationError[];
+    missingNames: string[];
+    onEdit: () => void;
+    onSkip: () => void;
+    onQuit: () => void;
+};
+export declare function PreviewValidationErrorStep({ errors, missingNames, onEdit, onSkip, onQuit, }: PreviewValidationErrorStepProps): React.ReactElement;
+export {};

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

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { GateStep } from './GateStep.js';
+export function PreviewValidationErrorStep({ errors, missingNames, onEdit, onSkip, onQuit, }) {
+    const uniqueNames = [...new Set(errors.map((e) => e.componentName))];
+    const matchedNames = uniqueNames.filter((n) => !missingNames.includes(n));
+    const errorLines = errors.map((e) => `  ${e.componentName}: ${e.message}`).join('\n');
+    const missingNote = missingNames.length > 0
+        ? `\n\nNote: ${missingNames.length} component name${missingNames.length === 1 ? '' : 's'} from the server (${missingNames.join(', ')}) ${missingNames.length === 1 ? 'does' : 'do'} not match anything in this session — they cannot be edited or skipped from here.`
+        : '';
+    const skipLabel = matchedNames.length === 0
+        ? 'No matching components to skip'
+        : `Skip ${matchedNames.length === 1 ? matchedNames[0] : `${matchedNames.length} components`} and retry`;
+    return (_jsx(GateStep, { intent: "error", successMessage: "Preview validation failed", summary: errorLines, context: `${uniqueNames.length} component${uniqueNames.length === 1 ? '' : 's'} failed server validation. Edit their definitions in the review TUI, or skip them and retry preview without them.${missingNote}`, continueLabel: "Edit definitions", skipLabel: skipLabel, showSkip: matchedNames.length > 0, onContinue: onEdit, onSkip: onSkip, onQuit: onQuit }));
+}

package/dist/src/import/tui/wizard-422-helpers.d.ts

@@ -0,0 +1,48 @@
+import { ApiError, type PreviewValidationError } from '../../apply/api-client.js';
+import { patchReviewStateWithValidationErrors, rejectComponentsByName } from '../../analyze/select/command.js';
+export type Preview422Outcome = {
+    kind: 'validation-error';
+    errors: PreviewValidationError[];
+    missingNames: string[];
+} | {
+    kind: 'unparseable';
+    message: string;
+} | {
+    kind: 'not-422';
+};
+/**
+ * Decide what to do with an `ApiError` raised by `previewImport()`.
+ * Returns `not-422` if the caller should fall through to its other branches
+ * (404 / 401 / 403 / generic), `unparseable` if the body cannot be parsed
+ * into structured component-level errors (caller should route to the generic
+ * error step), or `validation-error` with the patched-state side effects
+ * already applied.
+ *
+ * Pure decision logic + a single delegated side effect to
+ * `patchReviewStateWithValidationErrors`. Extracted from `WizardApp.runPreview`
+ * so the routing is unit-testable without driving the full TUI.
+ */
+export declare function handlePreview422(err: ApiError, extractSessionId: string | null, patchFn?: typeof patchReviewStateWithValidationErrors): Promise<Preview422Outcome>;
+/**
+ * The WizardState patch the wizard should spread into any update that
+ * transitions OUT of the preview-validation-error step (e.g. into
+ * preview-gate after a successful retry). Without this, the validation-error
+ * arrays linger in state and any future code path that reads them sees stale
+ * data from a prior failed attempt.
+ */
+export declare function clearedValidationErrorState(): {
+    previewValidationErrors: PreviewValidationError[];
+    previewValidationMissingNames: string[];
+};
+/**
+ * Run the "skip and retry" side effect: dedup the offending component
+ * names from a list of errors and call `rejectComponentsByName`. Returns
+ * the deduped names so the caller can log them or include them in test
+ * assertions. No-op when sessionId is null or errors are empty.
+ *
+ * The DB update inside `rejectComponentsByName` is what makes the next
+ * preview see a manifest with the offenders excluded — see SP-3 retro
+ * Bug 1: writing to the JSON state file alone is not enough because
+ * `loadCDFComponents` reads from the pipeline DB.
+ */
+export declare function applySkipValidationErrors(sessionId: string | null, errors: PreviewValidationError[], rejectFn?: typeof rejectComponentsByName): Promise<string[]>;

package/dist/src/import/tui/wizard-422-helpers.js

@@ -0,0 +1,60 @@
+import { parsePreviewValidationErrors } from '../../apply/api-client.js';
+import { patchReviewStateWithValidationErrors, rejectComponentsByName } from '../../analyze/select/command.js';
+/**
+ * Decide what to do with an `ApiError` raised by `previewImport()`.
+ * Returns `not-422` if the caller should fall through to its other branches
+ * (404 / 401 / 403 / generic), `unparseable` if the body cannot be parsed
+ * into structured component-level errors (caller should route to the generic
+ * error step), or `validation-error` with the patched-state side effects
+ * already applied.
+ *
+ * Pure decision logic + a single delegated side effect to
+ * `patchReviewStateWithValidationErrors`. Extracted from `WizardApp.runPreview`
+ * so the routing is unit-testable without driving the full TUI.
+ */
+export async function handlePreview422(err, extractSessionId, patchFn = patchReviewStateWithValidationErrors) {
+    if (err.status !== 422)
+        return { kind: 'not-422' };
+    const errors = parsePreviewValidationErrors(err.body);
+    if (errors.length === 0)
+        return { kind: 'unparseable', message: err.message };
+    let missingNames = [];
+    if (extractSessionId) {
+        const result = await patchFn(extractSessionId, errors);
+        missingNames = result.missingNames;
+    }
+    return { kind: 'validation-error', errors, missingNames };
+}
+/**
+ * The WizardState patch the wizard should spread into any update that
+ * transitions OUT of the preview-validation-error step (e.g. into
+ * preview-gate after a successful retry). Without this, the validation-error
+ * arrays linger in state and any future code path that reads them sees stale
+ * data from a prior failed attempt.
+ */
+export function clearedValidationErrorState() {
+    return {
+        previewValidationErrors: [],
+        previewValidationMissingNames: [],
+    };
+}
+/**
+ * Run the "skip and retry" side effect: dedup the offending component
+ * names from a list of errors and call `rejectComponentsByName`. Returns
+ * the deduped names so the caller can log them or include them in test
+ * assertions. No-op when sessionId is null or errors are empty.
+ *
+ * The DB update inside `rejectComponentsByName` is what makes the next
+ * preview see a manifest with the offenders excluded — see SP-3 retro
+ * Bug 1: writing to the JSON state file alone is not enough because
+ * `loadCDFComponents` reads from the pipeline DB.
+ */
+export async function applySkipValidationErrors(sessionId, errors, rejectFn = rejectComponentsByName) {
+    if (!sessionId)
+        return [];
+    const names = [...new Set(errors.map((e) => e.componentName))];
+    if (names.length === 0)
+        return [];
+    await rejectFn(sessionId, names);
+    return names;
+}

package/dist/src/program.d.ts

@@ -1,2 +1,19 @@
 import { Command } from 'commander';
+type SpawnedChild = {
+    on(event: 'error', listener: (err: unknown) => void): unknown;
+    on(event: 'exit', listener: (code: number | null) => void): unknown;
+};
+/**
+ * Run the spawn lifecycle for the build command. Extracted so the
+ * error-surfacing path is testable: previously `child.on('error', ...)`
+ * silently returned exit code 1 with no context, leaving the user
+ * staring at a generic non-zero exit when `pnpm` wasn't on PATH.
+ */
+export declare function runBuild(opts: {
+    spawnFn: () => SpawnedChild;
+    stderrWrite: (chunk: string) => void;
+}): Promise<{
+    exitCode: number;
+}>;
 export declare function createProgram(): Command;
+export {};

package/dist/src/program.js

@@ -12,6 +12,30 @@ import { registerImportCommand } from './import/command.js';
 import { registerSetupCommand } from './setup/command.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
+/**
+ * Run the spawn lifecycle for the build command. Extracted so the
+ * error-surfacing path is testable: previously `child.on('error', ...)`
+ * silently returned exit code 1 with no context, leaving the user
+ * staring at a generic non-zero exit when `pnpm` wasn't on PATH.
+ */
+export async function runBuild(opts) {
+    return new Promise((resolvePromise) => {
+        const child = opts.spawnFn();
+        let settled = false;
+        const settle = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise({ exitCode });
+        };
+        child.on('error', (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            opts.stderrWrite(`Error: failed to spawn build subprocess: ${message}\n`);
+            settle(1);
+        });
+        child.on('exit', (code) => settle(code ?? 1));
+    });
+}
 function registerBuildCommand(program) {
     program
         .command('build')
@@ -19,10 +43,9 @@ function registerBuildCommand(program) {
         .action(async () => {
         const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
         process.stderr.write('⚙  Building from source...\n');
-        const exitCode = await new Promise((resolvePromise) => {
-            const child = spawn('pnpm', ['build'], { cwd: pkgRoot, stdio: 'inherit' });
-            child.on('error', () => resolvePromise(1));
-            child.on('exit', (code) => resolvePromise(code ?? 1));
+        const { exitCode } = await runBuild({
+            spawnFn: () => spawn('pnpm', ['build'], { cwd: pkgRoot, stdio: 'inherit' }),
+            stderrWrite: (s) => process.stderr.write(s),
         });
         process.exit(exitCode);
     });

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

@@ -53,6 +53,19 @@ export type RawComponentWithId = RawComponentDefinition & {
     component_id: string;
 };
 export declare function loadRawComponents(db: DatabaseSync, sessionId: string, allowedNames?: Set<string>): RawComponentWithId[];
+/**
+ * Rename empty-named slots in the DB to heuristic names before generation.
+ * The LLM classify_slot tool call is matched back to the DB row by name, so a
+ * row with name="" can never be updated by the LLM — renaming it here makes it
+ * classifiable. Returns one warning string per renamed slot.
+ */
+export declare function renameEmptySlots(db: DatabaseSync, sessionId: string, componentId: string, componentName: string, slotCount: number): {
+    renames: Array<{
+        oldName: string;
+        newName: string;
+    }>;
+    warnings: string[];
+};
 export declare function storeCDFComponents(db: DatabaseSync, sessionId: string, components: Array<{
     key: string;
     entry: CDFComponentEntry;

package/dist/src/session/db.js

@@ -563,6 +563,45 @@ export function loadRawComponents(db, sessionId, allowedNames) {
         }),
     }));
 }
+/**
+ * Rename empty-named slots in the DB to heuristic names before generation.
+ * The LLM classify_slot tool call is matched back to the DB row by name, so a
+ * row with name="" can never be updated by the LLM — renaming it here makes it
+ * classifiable. Returns one warning string per renamed slot.
+ */
+export function renameEmptySlots(db, sessionId, componentId, componentName, slotCount) {
+    const emptySlots = db
+        .prepare(`SELECT name, position FROM raw_slots
+       WHERE session_id = ? AND component_id = ? AND trim(name) = ''
+       ORDER BY position`)
+        .all(sessionId, componentId);
+    if (emptySlots.length === 0)
+        return { renames: [], warnings: [] };
+    const renames = [];
+    const warnings = [];
+    const rename = db.prepare(`UPDATE raw_slots SET name = ? WHERE session_id = ? AND component_id = ? AND name = ? AND position = ?`);
+    // Multi-statement write — wrap in a transaction so a SIGINT or driver error
+    // mid-loop leaves raw_slots either fully renamed or fully untouched, never
+    // half-renamed (which would corrupt the prompt-vs-DB invariant the LLM
+    // relies on for classify_slot). Matches the existing BEGIN/COMMIT pattern
+    // throughout this file (see storeRawComponents, createStep, etc.).
+    db.exec('BEGIN');
+    try {
+        for (const slot of emptySlots) {
+            // Single unnamed slot → "children". Multiple → positional names.
+            const newName = slotCount === 1 ? 'children' : `slot_${slot.position}`;
+            rename.run(newName, sessionId, componentId, slot.name, slot.position);
+            renames.push({ oldName: slot.name, newName });
+            warnings.push(`${componentName}: slot at position ${slot.position} had empty name — renamed to "${newName}" for classification`);
+        }
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        db.exec('ROLLBACK');
+        throw e;
+    }
+    return { renames, warnings };
+}
 function groupBy(items, key) {
     const map = new Map();
     for (const item of items) {
@@ -676,6 +715,12 @@ export function loadCDFComponents(db, sessionId) {
             return null;
         const $properties = {};
         for (const p of compProps) {
+            // Hallucination insurance: drop any prop whose name didn't survive trim.
+            // The pre-generate rename guard catches empty-named slots, but if the LLM
+            // hallucinated a classify_prop with an empty name into the DB, surface
+            // nothing to the manifest builder rather than emitting "$properties: { '': ... }".
+            if (!p.name.trim())
+                continue;
             const av = allowedValuesByProp.get(`${component_id}::${p.name}`);
             const propDef = {
                 $type: p.cdf_type,
@@ -702,6 +747,11 @@ export function loadCDFComponents(db, sessionId) {
         const compSlots = slotsByComponent.get(component_id) ?? [];
         const $slots = {};
         for (const s of compSlots) {
+            // Hallucination insurance: same as $properties — drop empty-named slots
+            // before they reach buildManifest, which faithfully passes empty keys
+            // through and triggers a 422 from the preview API.
+            if (!s.name.trim())
+                continue;
             const ac = allowedComponentsBySlot.get(`${component_id}::${s.name}`);
             const slotDef = {};
             if (s.description !== null)

package/dist/src/types.d.ts

@@ -1,4 +1,11 @@
 import type { DesignTokenType } from '@contentful/experience-design-system-types';
+export type ExtractionValidationIssueCode = 'EMPTY_COMPONENT_NAME' | 'EMPTY_PROP_NAME' | 'EMPTY_SLOT_NAME' | 'PROP_SLOT_NAME_COLLISION' | 'DUPLICATE_COMPONENT_NAME' | 'EMPTY_COMPONENT' | 'SERVER_VALIDATION_FAILED';
+export type ExtractionValidationIssue = {
+    severity: 'error' | 'warning';
+    code: ExtractionValidationIssueCode;
+    message: string;
+    field?: string;
+};
 export interface RawTokenDefinition {
     name: string;
     value: string;
@@ -37,6 +44,7 @@ export interface RawComponentDefinition {
     extractionConfidence?: number | null;
     reviewReasons?: string[];
     needsReview?: boolean;
+    validationIssues?: ExtractionValidationIssue[];
 }
 export interface ComponentExtractionResult {
     components: RawComponentDefinition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.7.4",
+  "version": "2.11.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "react-dom": "^18.3.1",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.7.4"
+    "@contentful/experience-design-system-types": "2.11.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/skills/generate-components.md

@@ -251,6 +251,8 @@ For each `RawSlotDefinition`:
   - `false` if clearly optional (icon slot, footer slot with a default, decorative slot)
   - Default to `true` when the source gives no signal
 
+**Pre-named slots:** If the input contains a slot whose `name` was already inferred by the pipeline (e.g. `"children"`, `"slot_0"`), treat it as you would any named slot — classify it normally. The pipeline renames empty-named slots to heuristic names before passing them to you; your job is to confirm or enrich the classification (set `required`, `description`, `allowed_components`), not to rename again.
+
 ---
 
 ## Examples