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

package/dist/src/analyze/select/tui/App.js

@@ -4,7 +4,8 @@ import { Box, Text, useStdout } from 'ink';
 import { readFile } from 'node:fs/promises';
 import { createReviewSessionDetail } from '../types.js';
 import { TopBar } from './components/TopBar.js';
-import { Sidebar } from './components/Sidebar.js';
+import { Sidebar, sortComponentsForSidebar } from './components/Sidebar.js';
+import { countValidationIssues } from '../types.js';
 import { ComponentDetail } from './components/ComponentDetail.js';
 import { StatusBar } from './components/StatusBar.js';
 import { HelpOverlay } from './components/HelpOverlay.js';
@@ -316,22 +317,19 @@ export function App({ sessionId, artifactsRoot, reviewRoot }) {
         onToggleHelp: () => setShowHelp((prev) => !prev),
     });
     // Must be before early returns — Rules of Hooks
-    const sessionSummary = useMemo(() => (session?.components ?? [])
-        .map((c) => ({
-        id: c.id,
-        name: c.name,
-        status: c.status,
-        previewAnnotation: previewAnnotations[c.name],
-        extractionConfidence: c.originalProposal.extractionConfidence ?? null,
-        needsReview: c.originalProposal.needsReview ?? false,
-    }))
-        .sort((a, b) => {
-        const aF = a.needsReview && a.status === 'needs-review' ? 0 : 1;
-        const bF = b.needsReview && b.status === 'needs-review' ? 0 : 1;
-        if (aF !== bF)
-            return aF - bF;
-        return (a.extractionConfidence ?? 6) - (b.extractionConfidence ?? 6);
-    }), [session?.components, previewAnnotations]);
+    const sessionSummary = useMemo(() => sortComponentsForSidebar((session?.components ?? []).map((c) => {
+        const counts = countValidationIssues(c.originalProposal);
+        return {
+            id: c.id,
+            name: c.name,
+            status: c.status,
+            previewAnnotation: previewAnnotations[c.name],
+            extractionConfidence: c.originalProposal.extractionConfidence ?? null,
+            needsReview: c.originalProposal.needsReview ?? false,
+            validationErrorCount: counts.errors,
+            validationWarningCount: counts.warnings,
+        };
+    })), [session?.components, previewAnnotations]);
     if (loading) {
         return _jsx(Text, { children: "Loading session..." });
     }

package/dist/src/analyze/select/tui/components/Sidebar.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { ReviewComponentSummary } from '../../types.js';
+import type { ReviewComponentSummary, ReviewComponentStatus } from '../../types.js';
 type SidebarProps = {
     components: ReviewComponentSummary[];
     selectedId: string | null;
@@ -11,5 +11,8 @@ type SidebarProps = {
     collapsed?: boolean;
     width?: number;
 };
+export declare function statusIcon(status: ReviewComponentStatus, validationErrorCount: number, _validationWarningCount: number): string;
+export declare function statusColor(status: ReviewComponentStatus, validationErrorCount: number, validationWarningCount: number): string;
+export declare function sortComponentsForSidebar(components: ReviewComponentSummary[]): ReviewComponentSummary[];
 export declare function Sidebar({ components, selectedId, focused, scrollOffset, visibleCount, collapsed, width: widthProp, }: SidebarProps): React.ReactElement;
 export {};

package/dist/src/analyze/select/tui/components/Sidebar.js

@@ -1,6 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
-function statusIcon(status) {
+export function statusIcon(status, validationErrorCount, 
+// Warnings deliberately do NOT override the icon — the user's accept/reject
+// decision must remain visible. Color is already yellow via statusColor for
+// warning-only components, so the warning cue is preserved.
+_validationWarningCount) {
+    // Errors override — a structurally broken component should never render as ✓/✗.
+    if (validationErrorCount > 0)
+        return '⚠';
     switch (status) {
         case 'accepted':
             return '✓';
@@ -12,7 +19,11 @@ function statusIcon(status) {
             return '·';
     }
 }
-function statusColor(status) {
+export function statusColor(status, validationErrorCount, validationWarningCount) {
+    if (validationErrorCount > 0)
+        return 'red';
+    if (validationWarningCount > 0)
+        return 'yellow';
     switch (status) {
         case 'accepted':
             return 'green';
@@ -29,15 +40,40 @@ function truncateName(name, maxLen) {
         return name;
     return name.slice(0, maxLen) + '…';
 }
+/**
+ * Sort key for stable secondary ordering within a validation tier:
+ * needs-review components first, then by extractionConfidence ascending
+ * (lowest confidence first, null treated as highest = last). Used to be
+ * applied inline in App.tsx, then this helper sorted again — pulled in
+ * here so the sort happens once.
+ */
+function withinTierComparator(a, b) {
+    const aPending = a.needsReview && a.status === 'needs-review' ? 0 : 1;
+    const bPending = b.needsReview && b.status === 'needs-review' ? 0 : 1;
+    if (aPending !== bPending)
+        return aPending - bPending;
+    return (a.extractionConfidence ?? 6) - (b.extractionConfidence ?? 6);
+}
+export function sortComponentsForSidebar(components) {
+    const withErrors = components.filter((c) => c.validationErrorCount > 0);
+    const withWarnings = components.filter((c) => c.validationErrorCount === 0 && c.validationWarningCount > 0);
+    const clean = components.filter((c) => c.validationErrorCount === 0 && c.validationWarningCount === 0);
+    return [
+        ...[...withErrors].sort(withinTierComparator),
+        ...[...withWarnings].sort(withinTierComparator),
+        ...[...clean].sort(withinTierComparator),
+    ];
+}
 export function Sidebar({ components, selectedId, focused, scrollOffset, visibleCount, collapsed = false, width: widthProp, }) {
-    const visible = components.slice(scrollOffset, scrollOffset + visibleCount);
+    const sorted = sortComponentsForSidebar(components);
+    const visible = sorted.slice(scrollOffset, scrollOffset + visibleCount);
     const showScrollUp = scrollOffset > 0;
-    const showScrollDown = scrollOffset + visibleCount < components.length;
+    const showScrollDown = scrollOffset + visibleCount < sorted.length;
     const width = collapsed ? 3 : (widthProp ?? 18);
     return (_jsxs(Box, { flexDirection: "column", width: width, borderStyle: "single", borderColor: focused ? 'white' : undefined, children: [showScrollUp && !collapsed && _jsx(Text, { dimColor: true, children: "\u25B2" }), visible.map((component) => {
                 const isSelected = component.id === selectedId;
-                const icon = statusIcon(component.status);
-                const color = statusColor(component.status);
+                const icon = statusIcon(component.status, component.validationErrorCount, component.validationWarningCount);
+                const color = statusColor(component.status, component.validationErrorCount, component.validationWarningCount);
                 const maxNameLen = Math.max(1, width - 4);
                 const name = truncateName(component.name, maxNameLen);
                 if (collapsed) {

package/dist/src/analyze/select/types.d.ts

@@ -24,6 +24,8 @@ export type ReviewComponentSummary = {
     previewAnnotation?: PreviewAnnotation;
     extractionConfidence: number | null;
     needsReview: boolean;
+    validationErrorCount: number;
+    validationWarningCount: number;
 };
 export type ReviewSessionSnapshot = {
     components: ReviewComponentRecord[];
@@ -44,5 +46,9 @@ export type ReviewSessionPaths = {
     eventsPath: string;
     statePath: string;
 };
+export declare function countValidationIssues(component: RawComponentDefinition): {
+    errors: number;
+    warnings: number;
+};
 export declare function createReviewSessionSummary(session: ReviewSessionSnapshot): ReviewSessionSummary;
 export declare function createReviewSessionDetail(session: ReviewSessionSnapshot): ReviewSessionDetail;

package/dist/src/analyze/select/types.js

@@ -1,12 +1,29 @@
+export function countValidationIssues(component) {
+    const issues = component.validationIssues ?? [];
+    let errors = 0;
+    let warnings = 0;
+    for (const issue of issues) {
+        if (issue.severity === 'error')
+            errors++;
+        else if (issue.severity === 'warning')
+            warnings++;
+    }
+    return { errors, warnings };
+}
 export function createReviewSessionSummary(session) {
     return {
-        components: session.components.map((component) => ({
-            id: component.id,
-            name: component.name,
-            status: component.status,
-            extractionConfidence: component.originalProposal.extractionConfidence ?? null,
-            needsReview: component.originalProposal.needsReview ?? false,
-        })),
+        components: session.components.map((component) => {
+            const counts = countValidationIssues(component.originalProposal);
+            return {
+                id: component.id,
+                name: component.name,
+                status: component.status,
+                extractionConfidence: component.originalProposal.extractionConfidence ?? null,
+                needsReview: component.originalProposal.needsReview ?? false,
+                validationErrorCount: counts.errors,
+                validationWarningCount: counts.warnings,
+            };
+        }),
     };
 }
 export function createReviewSessionDetail(session) {

package/dist/src/analyze/select-agent/command.js

@@ -6,6 +6,7 @@ import { parseSelectToolCallLines, runAgent } from '../../generate/agent-runner.
 import { OutputFormatter, c } from '../../output/format.js';
 import { buildRepoContextIndex, buildSelectionContext } from './context-builder.js';
 import { isAbsolute, resolve } from 'node:path';
+import { validateExtractedComponents, shouldExcludeDueToValidation, formatExclusionWarning, } from '../extract/validate.js';
 const VALID_AGENTS = new Set(['claude', 'codex', 'opencode', 'cursor']);
 const DEFAULT_TIMEOUT_MS = Number(process.env.EDS_AGENT_TIMEOUT_MS ?? 3 * 60 * 1000);
 const DEFAULT_CONCURRENCY = 5;
@@ -177,6 +178,7 @@ export function registerAnalyzeSelectAgentCommand(program) {
         .option('--model <name>', 'Model to use (defaults to a small/fast model per agent)')
         .option('--verbose', 'Show full agent output including reasoning text')
         .option('--dry-run', 'Print the prompt for the first component without invoking the agent')
+        .option('--exclude-invalid', 'Auto-reject components with validation errors instead of failing loud (LLM cannot fix structural issues)')
         .action(async (opts) => {
         if (!VALID_AGENTS.has(opts.agent)) {
             process.stderr.write(`Error: unknown agent '${opts.agent}'. Accepted values: claude, codex, opencode, cursor\n`);
@@ -201,6 +203,35 @@ export function registerAnalyzeSelectAgentCommand(program) {
             process.exit(1);
             return;
         }
+        // Re-run validation (not persisted to DB, so always recompute).
+        const validatedComponents = validateExtractedComponents(rawComponents);
+        // Fail-loud gate: if any component has validation errors, refuse to
+        // proceed unless --exclude-invalid is set. The LLM cannot fix
+        // structural issues (empty names, slot/prop collisions, etc.) — silent
+        // exclusion in this CI-style command would drop components without the
+        // caller noticing.
+        const invalidComponents = validatedComponents.filter(shouldExcludeDueToValidation);
+        if (invalidComponents.length > 0 && !opts.excludeInvalid) {
+            const lines = [
+                `Error: ${invalidComponents.length} component(s) failed validation; refusing select-agent without --exclude-invalid:`,
+            ];
+            for (const comp of invalidComponents) {
+                const codes = (comp.validationIssues ?? [])
+                    .filter((i) => i.severity === 'error')
+                    .map((i) => i.code)
+                    .join(', ');
+                lines.push(`  ✗  ${comp.name}  ${codes}`);
+            }
+            lines.push('');
+            lines.push('Re-run with --exclude-invalid to auto-reject these components, or fix them in source first.');
+            process.stderr.write(lines.join('\n') + '\n');
+            process.exit(1);
+            return;
+        }
+        const componentsForAgent = validatedComponents.filter((comp) => !shouldExcludeDueToValidation(comp));
+        if (invalidComponents.length > 0) {
+            process.stderr.write(c.yellow(formatExclusionWarning(invalidComponents)));
+        }
         if (selectionRoot && scannedFiles.length > 0) {
             scannedFiles = scannedFiles.map((f) => (isAbsolute(f) ? f : resolve(selectionRoot, f)));
         }
@@ -208,17 +239,22 @@ export function registerAnalyzeSelectAgentCommand(program) {
             process.stderr.write('warn: session has no scanned-files index (likely extracted on an older CLI version). ' +
                 'Re-run `analyze extract` to enable data-fetch wrapper detection during selection.\n');
         }
-        let selectionCandidates = rawComponents.map((component) => ({ component }));
+        let selectionCandidates = componentsForAgent.map((component) => ({ component }));
         if (selectionRoot && scannedFiles.length > 0) {
             const repoIndex = await buildRepoContextIndex(selectionRoot, scannedFiles).catch(() => null);
             if (repoIndex) {
-                selectionCandidates = rawComponents.map((component) => ({
+                selectionCandidates = componentsForAgent.map((component) => ({
                     component,
                     selectionContext: buildSelectionContext(repoIndex, component),
                 }));
             }
         }
         if (opts.dryRun) {
+            if (selectionCandidates.length === 0) {
+                process.stderr.write('No valid components to preview — all components were excluded due to validation errors.\n');
+                process.exit(0);
+                return;
+            }
             const first = selectionCandidates[0];
             const prompt = await buildPrompt({
                 skill: 'select',
@@ -231,14 +267,18 @@ export function registerAnalyzeSelectAgentCommand(program) {
             return;
         }
         const selectResults = await selectAllComponents(agent, opts.model, selectionCandidates, opts.verbose ?? false);
+        // Build decision map from results. Seed auto-rejections from validation exclusions first.
         const decisions = new Map();
+        for (const comp of invalidComponents) {
+            decisions.set(componentKey(comp), 'rejected');
+        }
         for (const r of selectResults) {
             decisions.set(r.componentKey, r.decision);
         }
         const artifactsRoot = getRefineArtifactsRoot();
         let snapshot;
         try {
-            snapshot = await loadReviewInput(rawComponents, {
+            snapshot = await loadReviewInput(validatedComponents, {
                 reviewRoot: selectionRoot ?? undefined,
             });
             snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);

package/dist/src/analyze/tui/AnalyzeView.d.ts

@@ -9,10 +9,18 @@ export type AnalyzeViewResult = {
         propCount: number;
         slotCount: number;
         warnings: string[];
+        /**
+         * Error-severity validation messages. Components with any errors will be
+         * auto-rejected by the next step (`analyze select --select-all`), so the
+         * extract TUI surfaces them prominently — both with a per-row ✗ badge
+         * and a dedicated Errors section below the component list.
+         */
+        errors: string[];
         extractionConfidence: number | null;
         needsReview: boolean;
     }>;
     totalWarnings: number;
+    totalErrors: number;
 };
 type AnalyzeViewProps = {
     result: AnalyzeViewResult;

package/dist/src/analyze/tui/AnalyzeView.js

@@ -53,8 +53,11 @@ export function AnalyzeView({ result, onExit }) {
                         const conf = component.extractionConfidence;
                         const confColor = conf === null ? 'gray' : component.needsReview ? 'red' : conf >= 4 ? 'white' : conf >= 3 ? 'yellow' : 'red';
                         const confLabel = conf === null ? '—' : (component.needsReview ? '⚑ ' : '') + String(conf);
-                        return (_jsxs(Box, { children: [component.warnings.length > 0 && _jsx(Text, { color: "yellow", children: "\u26A0 " }), component.warnings.length === 0 && _jsx(Text, { children: " " }), _jsx(Text, { children: truncateName(component.name).padEnd(20) }), _jsx(Text, { dimColor: true, children: component.framework.padEnd(10) }), _jsx(Text, { children: (component.propCount + ' props').padEnd(10) }), _jsx(Text, { children: (component.slotCount + ' ' + (component.slotCount === 1 ? 'slot' : 'slots')).padEnd(8) }), _jsx(Text, { color: confColor, children: confLabel }), component.warnings.length > 0 && (_jsx(Text, { color: "yellow", children: '  ⚠ ' + component.warnings.length + ' warning' + (component.warnings.length === 1 ? '' : 's') }))] }, component.name));
-                    }), showScrollDown && _jsx(Text, { dimColor: true, children: " \u25BC scroll down" }), result.totalWarnings > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Warnings (' + result.totalWarnings + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components
+                        return (_jsxs(Box, { children: [component.errors.length > 0 && _jsx(Text, { color: "red", children: "\u2717 " }), component.errors.length === 0 && component.warnings.length > 0 && _jsx(Text, { color: "yellow", children: "\u26A0 " }), component.errors.length === 0 && component.warnings.length === 0 && _jsx(Text, { children: " " }), _jsx(Text, { children: truncateName(component.name).padEnd(20) }), _jsx(Text, { dimColor: true, children: component.framework.padEnd(10) }), _jsx(Text, { children: (component.propCount + ' props').padEnd(10) }), _jsx(Text, { children: (component.slotCount + ' ' + (component.slotCount === 1 ? 'slot' : 'slots')).padEnd(8) }), _jsx(Text, { color: confColor, children: confLabel }), component.errors.length > 0 && (_jsx(Text, { color: "red", children: '  ✗ ' + component.errors.length + ' error' + (component.errors.length === 1 ? '' : 's') })), component.errors.length === 0 && component.warnings.length > 0 && (_jsx(Text, { color: "yellow", children: '  ⚠ ' + component.warnings.length + ' warning' + (component.warnings.length === 1 ? '' : 's') }))] }, component.name));
+                    }), showScrollDown && _jsx(Text, { dimColor: true, children: " \u25BC scroll down" }), result.totalErrors > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "red", children: 'Errors (' + result.totalErrors + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components
+                                .filter((c) => c.errors.length > 0)
+                                .flatMap((c) => c.errors.map((e) => ({ component: c.name, error: e })))
+                                .map((e, i) => (_jsx(Text, { color: "red", children: '  ✗ ' + e.component + ': ' + e.error }, i)))] })), result.totalWarnings > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, color: "yellow", children: 'Warnings (' + result.totalWarnings + ')' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), result.components
                                 .filter((c) => c.warnings.length > 0)
                                 .flatMap((c) => c.warnings.map((w) => ({ component: c.name, warning: w })))
                                 .map((w, i) => (_jsx(Text, { color: "yellow", children: '  ⚠ ' + w.component + ': ' + w.warning }, i)))] })), _jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: 'Run: analyze select --session ' + result.sessionId }), _jsx(Text, { children: " " })] }), _jsx(Box, { borderStyle: "single", paddingX: 1, children: _jsx(Text, { dimColor: true, children: "Press Enter or q to exit" }) })] }));

package/dist/src/apply/api-client.d.ts

@@ -1,5 +1,8 @@
 import type { ManifestPayload, ServerPreviewResponse, ApplyOperationResponse } from '@contentful/experience-design-system-types';
 export declare const DEFAULT_HOST = "https://api.contentful.com";
+export declare const PREVIEW_ERROR_PREFIX = "preview failed:";
+export declare const APPLY_ERROR_PREFIX = "apply failed:";
+export declare const VALIDATION_FAILED_CODE = "\"ValidationFailed\"";
 export interface ApiClientOptions {
     host?: string;
     cmaToken: string;
@@ -11,6 +14,23 @@ export declare class ApiError extends Error {
     readonly body: string;
     constructor(message: string, status: number, body: string);
 }
+export interface PreviewValidationError {
+    componentName: string;
+    path: string;
+    message: string;
+}
+/**
+ * Parse the JSON body of a 422 from `previewImport()` into structured
+ * per-component validation errors. Returns [] for any malformed input
+ * so callers can fall back to the generic error path without try/catch.
+ *
+ * Path shape: `manifest:components/<Name>/$slots/<key>` or
+ * `manifest:components/<Name>/$properties/<key>`. Only the component
+ * name is extracted today; `path` and `message` are kept verbatim so
+ * future surfaces (debug logging, headless retry in SP-4) can render
+ * the field-level detail.
+ */
+export declare function parsePreviewValidationErrors(body: string): PreviewValidationError[];
 export declare class ImportApiClient {
     private host;
     private token;

package/dist/src/apply/api-client.js

@@ -1,5 +1,26 @@
 import { DEFAULT_API_HOST, toApiHost } from '../host-utils.js';
 export const DEFAULT_HOST = DEFAULT_API_HOST;
+// Phase-prefix constants used at the two ApiError throw sites below and
+// imported by orchestrator.ts to identify preview-phase 422s for retry.
+export const PREVIEW_ERROR_PREFIX = 'preview failed:';
+export const APPLY_ERROR_PREFIX = 'apply failed:';
+// Substring match the orchestrator uses to distinguish a parseable
+// component-level validation failure from generic 422s. Quoted because the
+// match runs against the raw JSON body (which contains `"code":"ValidationFailed"`).
+// If the server ever changes the casing or naming, isPreviewValidationError
+// silently returns false and the retry loop never fires — so this lives next
+// to the prefixes as a deliberate, named contract rather than an inline
+// magic string in the orchestrator.
+export const VALIDATION_FAILED_CODE = '"ValidationFailed"';
+// Cap on the body slice appended to ApiError.message. Bumped from 1000 →
+// 16384 so realistic 422 ValidationFailed reports (which list every
+// offending component, ~100 chars per error, easily exceeds 1KB once you
+// cross ~10 components) survive intact through subprocess stderr. The
+// orchestrator's parseOffendingComponentNames does JSON.parse on this slice
+// and silently fails to recover any offenders if the JSON is mid-truncated.
+// The cap stays in place to keep a runaway server response from blowing up
+// log output.
+const ERROR_BODY_LOG_CAP = 16384;
 export class ApiError extends Error {
     status;
     body;
@@ -8,13 +29,58 @@ export class ApiError extends Error {
         this.status = status;
         this.body = body;
         if (body) {
-            // Append a trimmed version of the response body so callers that only
-            // log e.message don't silently swallow the server's error detail.
-            const trimmed = body.length > 1000 ? body.slice(0, 1000) + '…' : body;
+            // Append a (possibly trimmed) version of the response body so callers
+            // that only log e.message don't silently swallow the server's error
+            // detail.
+            const trimmed = body.length > ERROR_BODY_LOG_CAP ? body.slice(0, ERROR_BODY_LOG_CAP) + '…' : body;
             this.message = `${message}\n${trimmed}`;
         }
     }
 }
+const COMPONENT_PATH_PREFIX = 'manifest:components/';
+/**
+ * Parse the JSON body of a 422 from `previewImport()` into structured
+ * per-component validation errors. Returns [] for any malformed input
+ * so callers can fall back to the generic error path without try/catch.
+ *
+ * Path shape: `manifest:components/<Name>/$slots/<key>` or
+ * `manifest:components/<Name>/$properties/<key>`. Only the component
+ * name is extracted today; `path` and `message` are kept verbatim so
+ * future surfaces (debug logging, headless retry in SP-4) can render
+ * the field-level detail.
+ */
+export function parsePreviewValidationErrors(body) {
+    if (!body)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return [];
+    }
+    const details = parsed?.details;
+    const errors = details?.errors;
+    if (!Array.isArray(errors))
+        return [];
+    const out = [];
+    for (const raw of errors) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const entry = raw;
+        if (typeof entry.path !== 'string' || typeof entry.message !== 'string')
+            continue;
+        if (!entry.path.startsWith(COMPONENT_PATH_PREFIX))
+            continue;
+        const tail = entry.path.slice(COMPONENT_PATH_PREFIX.length);
+        const slash = tail.indexOf('/');
+        const componentName = slash === -1 ? tail : tail.slice(0, slash);
+        if (!componentName)
+            continue;
+        out.push({ componentName, path: entry.path, message: entry.message });
+    }
+    return out;
+}
 async function request(url, options) {
     const headers = {
         Authorization: `Bearer ${options.token}`,
@@ -68,7 +134,7 @@ export class ImportApiClient {
             body: JSON.stringify(manifest),
         });
         if (!res.ok) {
-            throw new ApiError(`preview failed: ${res.status}`, res.status, await res.text());
+            throw new ApiError(`${PREVIEW_ERROR_PREFIX} ${res.status}`, res.status, await res.text());
         }
         return (await res.json());
     }
@@ -80,7 +146,7 @@ export class ImportApiClient {
             body: JSON.stringify({ ...manifest, acknowledgeBreakingChanges }),
         });
         if (!res.ok) {
-            throw new ApiError(`apply failed: ${res.status}`, res.status, await res.text());
+            throw new ApiError(`${APPLY_ERROR_PREFIX} ${res.status}`, res.status, await res.text());
         }
         return (await res.json());
     }

package/dist/src/generate/command.js

@@ -9,7 +9,7 @@ import { OutputFormatter, c } from '../output/format.js';
 import { buildPrompt, resolveSkillPath } from './prompt-builder.js';
 import { GenerateView } from './tui/GenerateView.js';
 import { registerGenerateEditCommand } from './edit/command.js';
-import { openPipelineDb, loadRawComponents, applyToolCalls, applyTokenToolCalls, computeComponentInputHash, computeTokenInputHash, lookupCache, lookupCacheByEntity, storeCache, copyComponentFromCache, copyTokensFromCache, } from '../session/db.js';
+import { openPipelineDb, loadRawComponents, applyToolCalls, applyTokenToolCalls, computeComponentInputHash, computeTokenInputHash, lookupCache, lookupCacheByEntity, storeCache, copyComponentFromCache, copyTokensFromCache, renameEmptySlots, } from '../session/db.js';
 import { getRefineArtifactsRoot, getRefineSessionPaths } from '../analyze/select/persistence.js';
 const execFileAsync = promisify(execFile);
 const VALID_AGENTS = new Set(['claude', 'codex', 'opencode', 'cursor']);
@@ -119,6 +119,7 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
                 warnings: [],
                 failed: false,
                 cached: true,
+                renamedSlotsCount: 0,
             };
         }
         // Check for pinned (human-edited) entry with a different hash
@@ -134,16 +135,28 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
                 warnings: [`${component.name}: source changed but human edits preserved`],
                 failed: false,
                 cached: true,
+                renamedSlotsCount: 0,
             };
         }
     }
+    // Rename empty-named slots in the DB and patch the in-memory component so the
+    // prompt sees the heuristic names. applyToolCalls matches by name — a row with
+    // name="" would never be reachable by a classify_slot call otherwise.
+    const { renames, warnings: renameWarnings } = renameEmptySlots(db, sessionId, component.component_id, component.name, component.slots.length);
+    let effectiveSlots = component.slots;
+    if (renames.length > 0) {
+        const renameMap = new Map(renames.map((r) => [r.oldName, r.newName]));
+        effectiveSlots = component.slots.map((s) => (renameMap.has(s.name) ? { ...s, name: renameMap.get(s.name) } : s));
+        for (const w of renameWarnings)
+            process.stderr.write(`  ${c.yellow('⚠')}  ${w}\n`);
+    }
     const rawComponentsInline = JSON.stringify([
         {
             name: component.name,
             source: component.source,
             framework: component.framework,
             props: component.props,
-            slots: component.slots,
+            slots: effectiveSlots,
         },
     ], null, 2);
     const prompt = await buildPrompt({
@@ -186,6 +199,7 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
                 warnings: [],
                 failed: true,
                 error: `timed out after ${DEFAULT_TIMEOUT_MS / 60000} minutes`,
+                renamedSlotsCount: renames.length,
             };
         }
         if (result.exitCode !== 0) {
@@ -209,6 +223,7 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
             slots: applied.slots,
             warnings: applied.warnings,
             failed: false,
+            renamedSlotsCount: renames.length,
         };
     }
     return {
@@ -219,6 +234,7 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
         warnings: [],
         failed: true,
         error: lastError,
+        renamedSlotsCount: renames.length,
     };
 }
 async function runAllComponents(agent, model, db, sessionId, components, tokensInline, tokenMapInline, verbose, noCache) {
@@ -390,6 +406,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
         }
         const totalClassified = generated.reduce((s, r) => s + r.classified, 0);
         const totalExcluded = generated.reduce((s, r) => s + r.excluded, 0);
+        const totalRenamedSlots = componentResults.reduce((s, r) => s + r.renamedSlotsCount, 0);
         const allOk = failed.length === 0;
         const cachedNote = cachedResults.length > 0 ? c.dim(`  (${cachedResults.length} cached)`) : '';
         process.stderr.write((allOk ? c.green('✓') : c.yellow('⚠')) +
@@ -397,6 +414,8 @@ async function runGenerateSkill(skill, opts, verbose = false) {
             cachedNote +
             c.dim(`  ${totalClassified} classified, ${totalExcluded} excluded`) +
             '\n');
+        // Machine-parseable summary on stdout for the wizard / orchestrator.
+        process.stdout.write(`renamed-slots: ${totalRenamedSlots}\n`);
         if (generated.length === 0 && cachedResults.length === 0) {
             die('Error: all components failed to generate — check agent output above');
         }

package/dist/src/import/command.js

@@ -24,6 +24,7 @@ export function registerImportCommand(program) {
         .option('--no-cache', 'Re-run all steps even if output already exists')
         .option('--yes', 'Skip interactive confirmation in apply push')
         .option('--verbose', 'Show full agent output and all entity progress')
+        .option('--exclude-invalid', 'Automatically reject components with validation errors (empty names, collisions)')
         .option('--viewports <path>', 'JSON file with viewport array (passed to apply push)')
         .option('--host <url>', 'Override API base URL (passed to apply push)')
         .option('--dry-run', 'Print generate components prompt without invoking the agent')
@@ -84,6 +85,7 @@ export function registerImportCommand(program) {
             noCache: opts.cache === false,
             yes: opts.yes ?? false,
             verbose: opts.verbose ?? false,
+            excludeInvalid: opts.excludeInvalid ?? false,
             viewports: opts.viewports,
             host: opts.host,
             dryRun: opts.dryRun,

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

@@ -17,6 +17,7 @@ export interface PipelineOptions {
     viewports?: string;
     host?: string;
     dryRun?: boolean;
+    excludeInvalid?: boolean;
     selectAll?: boolean;
     select?: string[];
     deselect?: string[];
@@ -34,4 +35,25 @@ export interface PipelineResult {
     project: string;
     steps: StepResult[];
 }
+export declare function isPreviewValidationError(result: {
+    exitCode: number;
+    stderr: string;
+}): boolean;
+export declare function parseOffendingComponentNames(output: string): string[];
+/**
+ * Build the apply-push StepResult record. Centralizes the success/failure
+ * shape so excludedByValidationRetry is recorded consistently in both
+ * branches — previously the total-failure branch dropped it, leaving users
+ * with a failed pipeline and no audit trail of what was auto-excluded
+ * before the retry loop gave up.
+ */
+export declare function buildPushStepResult(args: {
+    created: number;
+    updated: number;
+    failed: number;
+    durationMs: number;
+    stderr: string;
+    excludedByRetry: string[];
+    totalFailure?: boolean;
+}): StepResult;
 export declare function runPipeline(opts: PipelineOptions, progressWriter: (line: string) => void, cliPathOverride?: string): Promise<PipelineResult>;