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

package/dist/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",

package/dist/src/analyze/build-analyze-view-rows.d.ts

@@ -0,0 +1,23 @@
+import type { RawComponentDefinition } from '../types.js';
+import type { AnalyzeViewResult } from './tui/AnalyzeView.js';
+type AnalyzeViewRow = AnalyzeViewResult['components'][number];
+/**
+ * Build the per-component rows shown in the analyze TUI / non-TTY summary,
+ * pairing each filtered component with its corresponding validation result.
+ *
+ * IMPORTANT — positional indexing is intentional and load-bearing.
+ * `validateExtractedComponents` is implemented as `.map()` over its input,
+ * so `validatedComponents[i]` always corresponds to `filteredComponents[i]`.
+ *
+ * We previously keyed validated components by `name` to "avoid a positional
+ * dependency" — that got the tradeoff exactly backwards. `Map.set` overwrites
+ * by key, so for two components named "Button" only the second's
+ * `validationIssues` survived in the Map. The first row's errors then
+ * disappeared from `analyzeResult` entirely: no Errors-section entry, no
+ * row badge, no count. Pairing by index restores correctness.
+ */
+export declare function buildAnalyzeViewRows(filteredComponents: RawComponentDefinition[], validatedComponents: RawComponentDefinition[], allWarnings: string[]): {
+    rows: AnalyzeViewRow[];
+    totalErrors: number;
+};
+export {};

package/dist/src/analyze/build-analyze-view-rows.js

@@ -0,0 +1,39 @@
+/**
+ * Build the per-component rows shown in the analyze TUI / non-TTY summary,
+ * pairing each filtered component with its corresponding validation result.
+ *
+ * IMPORTANT — positional indexing is intentional and load-bearing.
+ * `validateExtractedComponents` is implemented as `.map()` over its input,
+ * so `validatedComponents[i]` always corresponds to `filteredComponents[i]`.
+ *
+ * We previously keyed validated components by `name` to "avoid a positional
+ * dependency" — that got the tradeoff exactly backwards. `Map.set` overwrites
+ * by key, so for two components named "Button" only the second's
+ * `validationIssues` survived in the Map. The first row's errors then
+ * disappeared from `analyzeResult` entirely: no Errors-section entry, no
+ * row badge, no count. Pairing by index restores correctness.
+ */
+export function buildAnalyzeViewRows(filteredComponents, validatedComponents, allWarnings) {
+    if (validatedComponents.length !== filteredComponents.length) {
+        // Defensive: caller must pass aligned arrays. If this ever fires we want
+        // to know loudly rather than silently mis-pair rows with their issues.
+        throw new Error(`buildAnalyzeViewRows: validatedComponents length (${validatedComponents.length}) does not match filteredComponents length (${filteredComponents.length})`);
+    }
+    let totalErrors = 0;
+    const rows = filteredComponents.map((c, i) => {
+        const validated = validatedComponents[i];
+        const errorIssues = (validated.validationIssues ?? []).filter((issue) => issue.severity === 'error');
+        totalErrors += errorIssues.length;
+        return {
+            name: c.name,
+            framework: c.framework,
+            propCount: c.props.length,
+            slotCount: c.slots.length,
+            warnings: allWarnings.filter((w) => w.startsWith(c.name + ':')),
+            errors: errorIssues.map((issue) => issue.message),
+            extractionConfidence: c.extractionConfidence ?? null,
+            needsReview: c.needsReview ?? false,
+        };
+    });
+    return { rows, totalErrors };
+}

package/dist/src/analyze/command.js

@@ -11,6 +11,8 @@ import { preClassifyComponent } from './pre-classify.js';
 import { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
 import { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
 import { describeReviewReasons, inspectComponentSource } from './extract/source-inspection.js';
+import { validateExtractedComponents } from './extract/validate.js';
+import { buildAnalyzeViewRows } from './build-analyze-view-rows.js';
 const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.ts', '.tsx', '.vue']);
 const IGNORED_DIRECTORY_NAMES = new Set([
     '.git',
@@ -168,25 +170,20 @@ export function registerAnalyzeCommand(program) {
                 needsReview: deriveNeedsReview(confidence) || inspection.wrapperConfidence >= 4 || inspection.keepDespiteZeroSurface,
             });
         }
-        storeRawComponents(db, sessionId, filteredComponents);
+        const validatedComponents = validateExtractedComponents(filteredComponents);
+        storeRawComponents(db, sessionId, validatedComponents);
         storeScannedFiles(db, sessionId, sourceFiles.map((f) => relative(projectRoot, f)));
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();
         const allWarnings = [...extraction.warnings, ...filterWarnings];
+        const { rows: componentRows, totalErrors } = buildAnalyzeViewRows(filteredComponents, validatedComponents, allWarnings);
         const analyzeResult = {
             sourceDirectory,
             sessionId,
             fileCount: sourceFiles.length,
-            components: filteredComponents.map((c) => ({
-                name: c.name,
-                framework: c.framework,
-                propCount: c.props.length,
-                slotCount: c.slots.length,
-                warnings: allWarnings.filter((w) => w.startsWith(c.name + ':')),
-                extractionConfidence: c.extractionConfidence ?? null,
-                needsReview: c.needsReview ?? false,
-            })),
+            components: componentRows,
             totalWarnings: allWarnings.length,
+            totalErrors,
         };
         if (process.stdout.isTTY) {
             const { waitUntilExit } = render(createElement(AnalyzeView, {
@@ -202,11 +199,19 @@ export function registerAnalyzeCommand(program) {
                 `Scanned ${pluralize(sourceFiles.length, 'source file')} in ${sourceDirectory}`,
                 `Extracted ${pluralize(extraction.components.length, 'component')}`,
             ];
+            if (totalErrors > 0) {
+                summaryLines.push(`Errors (${totalErrors}):`);
+                for (const c of componentRows) {
+                    for (const e of c.errors) {
+                        summaryLines.push(`- ${c.name}: ${e}`);
+                    }
+                }
+            }
             if (allWarnings.length > 0) {
                 summaryLines.push(`Warnings (${allWarnings.length}):`);
                 summaryLines.push(...allWarnings.map((w) => `- ${w}`));
             }
-            else {
+            else if (totalErrors === 0) {
                 summaryLines.push('Warnings: none');
             }
             process.stderr.write(summaryLines.join('\n') + '\n');

package/dist/src/analyze/extract/validate.d.ts

@@ -0,0 +1,16 @@
+import type { RawComponentDefinition, ExtractionValidationIssue } from '../../types.js';
+export type { ExtractionValidationIssue } from '../../types.js';
+export declare function validateExtractedComponents(components: RawComponentDefinition[]): RawComponentDefinition[];
+export declare function shouldExcludeDueToValidation(component: RawComponentDefinition): boolean;
+/**
+ * Format a stderr-ready warning describing components auto-rejected by the
+ * extraction gate. Used by `analyze select --select-all --exclude-invalid`
+ * and `analyze select-agent --exclude-invalid` so both opt-in paths emit a
+ * consistent message — non-interactive callers (CI, orchestrator, scripted
+ * pipeline) need to see WHICH components were excluded and WHY, not just
+ * the bare counts.
+ */
+export declare function formatExclusionWarning(rejected: Array<{
+    name: string;
+    validationIssues?: ExtractionValidationIssue[];
+}>): string;

package/dist/src/analyze/extract/validate.js

@@ -0,0 +1,94 @@
+export function validateExtractedComponents(components) {
+    const nameCounts = new Map();
+    for (const component of components) {
+        const key = component.name.trim();
+        nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    return components.map((component) => {
+        const issues = [];
+        if (!component.name.trim()) {
+            issues.push({
+                severity: 'error',
+                code: 'EMPTY_COMPONENT_NAME',
+                message: 'Component name must not be empty',
+            });
+        }
+        for (let i = 0; i < component.props.length; i++) {
+            if (!component.props[i].name.trim()) {
+                issues.push({
+                    severity: 'error',
+                    code: 'EMPTY_PROP_NAME',
+                    message: `Prop at index ${i} has an empty name`,
+                    field: `props[${i}].name`,
+                });
+            }
+        }
+        for (let i = 0; i < component.slots.length; i++) {
+            if (!component.slots[i].name.trim()) {
+                // Warning, not error: SP-2's renameEmptySlots auto-recovers empty slot
+                // names to children/slot_<n> before the LLM prompt, so the component
+                // can still be generated. Asymmetric with EMPTY_PROP_NAME (still error)
+                // because that path silently drops empty-named props in
+                // loadCDFComponents — real data loss — instead of recovering them.
+                issues.push({
+                    severity: 'warning',
+                    code: 'EMPTY_SLOT_NAME',
+                    message: `Slot at index ${i} has an empty name`,
+                    field: `slots[${i}].name`,
+                });
+            }
+        }
+        const propNames = new Set(component.props.map((p) => p.name.trim()).filter(Boolean));
+        for (let i = 0; i < component.slots.length; i++) {
+            const slotName = component.slots[i].name.trim();
+            if (slotName && propNames.has(slotName)) {
+                issues.push({
+                    severity: 'error',
+                    code: 'PROP_SLOT_NAME_COLLISION',
+                    message: `"${slotName}" is used as both a prop name and a slot name`,
+                    field: `slots[${i}].name`,
+                });
+            }
+        }
+        const nameKey = component.name.trim();
+        if (nameKey && (nameCounts.get(nameKey) ?? 0) > 1) {
+            issues.push({
+                severity: 'error',
+                code: 'DUPLICATE_COMPONENT_NAME',
+                message: `Component name "${component.name}" appears more than once in the extracted set`,
+            });
+        }
+        if (component.props.length === 0 && component.slots.length === 0) {
+            issues.push({
+                severity: 'warning',
+                code: 'EMPTY_COMPONENT',
+                message: 'Component has no props or slots and will be filtered out during generation',
+            });
+        }
+        return { ...component, validationIssues: issues };
+    });
+}
+export function shouldExcludeDueToValidation(component) {
+    return (component.validationIssues ?? []).some((i) => i.severity === 'error');
+}
+/**
+ * Format a stderr-ready warning describing components auto-rejected by the
+ * extraction gate. Used by `analyze select --select-all --exclude-invalid`
+ * and `analyze select-agent --exclude-invalid` so both opt-in paths emit a
+ * consistent message — non-interactive callers (CI, orchestrator, scripted
+ * pipeline) need to see WHICH components were excluded and WHY, not just
+ * the bare counts.
+ */
+export function formatExclusionWarning(rejected) {
+    if (rejected.length === 0)
+        return '';
+    const lines = [`Warning: ${rejected.length} component(s) excluded due to validation errors:`];
+    for (const comp of rejected) {
+        const codes = (comp.validationIssues ?? [])
+            .filter((i) => i.severity === 'error')
+            .map((i) => i.code)
+            .join(', ');
+        lines.push(`  ✗  ${comp.name}  ${codes}`);
+    }
+    return lines.join('\n') + '\n';
+}

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

@@ -1,2 +1,49 @@
 import type { Command } from 'commander';
+import type { ReviewSessionSnapshot } from './types.js';
+import type { PreviewValidationError } from '../../apply/api-client.js';
+/**
+ * Load components from the pipeline DB and re-run extraction validation.
+ *
+ * `validationIssues` is intentionally not persisted (the validator is pure
+ * and cheap to re-run), so any cold-start of `analyze select` from a prior
+ * `analyze extract` session needs to recompute it before building the
+ * review snapshot — otherwise the TUI sees no validation errors at all.
+ */
+export declare function loadAndValidateForReview(sessionId: string, projectRoot: string | undefined): Promise<ReviewSessionSnapshot>;
+/**
+ * Synthesize SERVER_VALIDATION_FAILED issues onto the review state file's
+ * matching components. Used by the wizard's 422 recovery path: after a
+ * preview-API validation error, this runs before re-launching the
+ * analyze-select TUI so the Sidebar's existing red-warning rendering
+ * pins the offenders to the top.
+ *
+ * Idempotent on identical input is NOT a contract: each call appends.
+ * The wizard's 422 path is a one-shot per preview attempt, so duplicate
+ * issues only matter if a caller invokes this twice without the user
+ * round-tripping through the TUI in between.
+ */
+export declare function patchReviewStateWithValidationErrors(sessionId: string, errors: PreviewValidationError[], opts?: {
+    artifactsRoot?: string;
+}): Promise<{
+    patchedNames: string[];
+    missingNames: string[];
+}>;
+/**
+ * Exclude components whose names appear in `names` from the next preview/push.
+ * Used by the wizard's "skip and retry" path after a 422.
+ *
+ * Two stores are updated:
+ *   - Pipeline DB (`raw_components.status` → `'generate-rejected'`) so that
+ *     `loadCDFComponents()` excludes them from the next manifest. This is the
+ *     load-bearing change — preview reads from the DB, not the JSON file.
+ *   - Review state JSON (`status` → `'rejected'`) so that if the user re-enters
+ *     the analyze-select TUI later, the rejected status is reflected.
+ *
+ * `'generate-rejected'` matches the existing convention for "component was
+ * generated successfully but later excluded" (see GenerateReviewStep) — the
+ * component generated fine locally but failed server-side validation.
+ */
+export declare function rejectComponentsByName(sessionId: string, names: string[], opts?: {
+    artifactsRoot?: string;
+}): Promise<void>;
 export declare function registerAnalyzeEditCommand(program: Command): void;

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

@@ -1,11 +1,12 @@
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { access, readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
 import { createElement } from 'react';
 import { render } from 'ink';
 import { getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState } from './persistence.js';
 import { loadReviewInput } from './parser.js';
 import { App } from './tui/App.js';
 import { openPipelineDb, loadRawComponents, storeRawComponents, createStep, updateStep } from '../../session/db.js';
+import { validateExtractedComponents, shouldExcludeDueToValidation, formatExclusionWarning, } from '../extract/validate.js';
 const SAFE_PATH_RE = /^[a-zA-Z0-9_.$[\]=]+$/;
 const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function applyDotPath(obj, path, value) {
@@ -72,10 +73,66 @@ function applyPatch(snapshot, ops) {
     return { ...snapshot, components };
 }
 async function runNonInteractive(snapshot, opts, paths, sessionId) {
+    // --exclude-components on its own (no --select-all / --select / --deselect /
+    // --reject / --patch) is the orchestrator's 422 retry-loop invocation: only
+    // the named components should change. The rebuild path below calls
+    // storeRawComponents which DELETEs all rows and re-inserts with default
+    // status='extracted', wiping the post-generate state required by
+    // loadCDFComponents (status='generated' + raw_props.cdf_type populated).
+    // Short-circuit through rejectComponentsByName, which is a pure UPDATE.
+    const onlyExcludeComponents = !!opts.excludeComponents &&
+        !opts.acceptAll &&
+        !opts.selectAll &&
+        !(opts.select ?? []).length &&
+        !(opts.deselect ?? []).length &&
+        !(opts.reject ?? []).length &&
+        !opts.patch;
+    if (onlyExcludeComponents) {
+        const names = opts
+            .excludeComponents.split(',')
+            .map((n) => n.trim())
+            .filter(Boolean);
+        if (names.length > 0) {
+            // paths.sessionDir = resolve(artifactsRoot, sessionId), so dirname gives
+            // back the artifactsRoot — keeps rejectComponentsByName from re-resolving
+            // it via env var when the caller already knows it.
+            const artifactsRoot = dirname(paths.sessionDir);
+            await rejectComponentsByName(sessionId, names, { artifactsRoot });
+        }
+        const accepted = snapshot.components.filter((c) => c.status === 'accepted').length;
+        const rejected = snapshot.components.filter((c) => c.status === 'rejected').length + (names.length || 0);
+        process.stderr.write(`Accepted: ${accepted}  Rejected: ${rejected}\n`);
+        return;
+    }
     let result = { ...snapshot };
     const rejectPatterns = [...(opts.reject ?? []), ...(opts.deselect ?? [])].map((p) => p.toLowerCase());
     const selectPatterns = (opts.select ?? []).map((p) => p.toLowerCase());
     const selectAll = opts.acceptAll || opts.selectAll;
+    // Fail-loud gate: --select-all stops with a non-zero exit when ANY component
+    // has error-severity validation issues. The user must opt in to auto-rejection
+    // with --exclude-invalid. Silent exclusion in CI / orchestrator contexts is
+    // dangerous — the caller should see and acknowledge that components are
+    // being dropped from the import.
+    if (selectAll && !opts.excludeInvalid) {
+        const invalid = result.components.filter((c) => shouldExcludeDueToValidation(c.originalProposal));
+        if (invalid.length > 0) {
+            const lines = [
+                `Error: ${invalid.length} component(s) failed validation; refusing --select-all without --exclude-invalid:`,
+            ];
+            for (const c of invalid) {
+                const codes = (c.originalProposal.validationIssues ?? [])
+                    .filter((i) => i.severity === 'error')
+                    .map((i) => i.code)
+                    .join(', ');
+                lines.push(`  ✗  ${c.name}  ${codes}`);
+            }
+            lines.push('');
+            lines.push('Re-run with --exclude-invalid to auto-reject these components, or run analyze select interactively to fix them.');
+            process.stderr.write(lines.join('\n') + '\n');
+            process.exit(1);
+            return;
+        }
+    }
     if (selectAll || rejectPatterns.length > 0 || selectPatterns.length > 0) {
         result = {
             ...result,
@@ -84,6 +141,9 @@ async function runNonInteractive(snapshot, opts, paths, sessionId) {
                 if (rejectPatterns.some((p) => nameLower.includes(p))) {
                     return { ...c, status: 'rejected' };
                 }
+                if (selectAll && opts.excludeInvalid && shouldExcludeDueToValidation(c.originalProposal)) {
+                    return { ...c, status: 'rejected' };
+                }
                 if (selectAll || selectPatterns.some((p) => nameLower.includes(p))) {
                     return { ...c, status: 'accepted' };
                 }
@@ -91,6 +151,21 @@ async function runNonInteractive(snapshot, opts, paths, sessionId) {
             }),
         };
     }
+    // Apply --exclude-components: force-reject the named components regardless of
+    // how --select-all / --select / --deselect classified them. Used by the
+    // orchestrator's 422 retry loop to exclude server-validation offenders.
+    if (opts.excludeComponents) {
+        const excludeNames = new Set(opts.excludeComponents
+            .split(',')
+            .map((n) => n.trim())
+            .filter(Boolean));
+        if (excludeNames.size > 0) {
+            result = {
+                ...result,
+                components: result.components.map((c) => excludeNames.has(c.name) ? { ...c, status: 'rejected' } : c),
+            };
+        }
+    }
     // Apply --patch
     if (opts.patch) {
         let patchOps;
@@ -120,10 +195,31 @@ async function runNonInteractive(snapshot, opts, paths, sessionId) {
     }
     const accepted = result.components.filter((c) => c.status === 'accepted');
     const rejected = result.components.filter((c) => c.status === 'rejected');
+    // Surface what was excluded by --select-all --exclude-invalid so the
+    // non-interactive caller (CI, orchestrator, scripted pipeline) doesn't
+    // have to guess what failed validation. The warning is printed BEFORE
+    // saveReviewState so the message lands ahead of the bare counts.
+    if (selectAll && opts.excludeInvalid) {
+        const autoRejected = rejected
+            .filter((c) => shouldExcludeDueToValidation(c.originalProposal))
+            .map((c) => ({ name: c.name, validationIssues: c.originalProposal.validationIssues }));
+        process.stderr.write(formatExclusionWarning(autoRejected));
+    }
     // Persist decisions to session state so pipeline orchestrator can read them
     await saveReviewState(paths.statePath, result);
-    // Sync edited proposals back to the DB so generation uses the user's edits
-    if (accepted.length > 0) {
+    // Sync edited proposals back to the DB so generation uses the user's edits.
+    //
+    // Only --patch can mutate editedProposal — the other non-interactive flags
+    // (--select-all / --select / --deselect / --reject / --exclude-invalid)
+    // change status only. Calling storeRawComponents in the no-edit case is
+    // not just wasteful: it's destructive. storeRawComponents starts with
+    // `DELETE FROM raw_components WHERE session_id = ?` and re-inserts only
+    // the components passed in — so on a --select-all run, every rejected
+    // component (including its raw_slots / raw_props children) is physically
+    // removed. A second invocation of the same command would then see a
+    // smaller snapshot, lose the rejected component(s), and report different
+    // counts.
+    if (opts.patch && accepted.length > 0) {
         const db = openPipelineDb();
         try {
             storeRawComponents(db, sessionId, accepted.map((c) => c.editedProposal));
@@ -134,6 +230,120 @@ async function runNonInteractive(snapshot, opts, paths, sessionId) {
     }
     process.stderr.write(`Accepted: ${accepted.length}  Rejected: ${rejected.length}\n`);
 }
+/**
+ * Load components from the pipeline DB and re-run extraction validation.
+ *
+ * `validationIssues` is intentionally not persisted (the validator is pure
+ * and cheap to re-run), so any cold-start of `analyze select` from a prior
+ * `analyze extract` session needs to recompute it before building the
+ * review snapshot — otherwise the TUI sees no validation errors at all.
+ */
+export async function loadAndValidateForReview(sessionId, projectRoot) {
+    const db = openPipelineDb();
+    let rawComponents;
+    try {
+        rawComponents = loadRawComponents(db, sessionId);
+    }
+    finally {
+        db.close();
+    }
+    const validatedComponents = validateExtractedComponents(rawComponents);
+    return loadReviewInput(validatedComponents, { reviewRoot: projectRoot });
+}
+/**
+ * Synthesize SERVER_VALIDATION_FAILED issues onto the review state file's
+ * matching components. Used by the wizard's 422 recovery path: after a
+ * preview-API validation error, this runs before re-launching the
+ * analyze-select TUI so the Sidebar's existing red-warning rendering
+ * pins the offenders to the top.
+ *
+ * Idempotent on identical input is NOT a contract: each call appends.
+ * The wizard's 422 path is a one-shot per preview attempt, so duplicate
+ * issues only matter if a caller invokes this twice without the user
+ * round-tripping through the TUI in between.
+ */
+export async function patchReviewStateWithValidationErrors(sessionId, errors, opts = {}) {
+    const artifactsRoot = opts.artifactsRoot ?? getRefineArtifactsRoot();
+    const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+    let snapshot;
+    try {
+        await access(paths.statePath);
+        snapshot = JSON.parse(await readFile(paths.statePath, 'utf8'));
+    }
+    catch {
+        snapshot = await loadAndValidateForReview(sessionId, undefined);
+        snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);
+    }
+    const errorsByName = new Map();
+    for (const err of errors) {
+        const list = errorsByName.get(err.componentName) ?? [];
+        list.push(err);
+        errorsByName.set(err.componentName, list);
+    }
+    const patchedNames = [];
+    const knownNames = new Set(snapshot.components.map((c) => c.name));
+    const components = snapshot.components.map((c) => {
+        const matched = errorsByName.get(c.name);
+        if (!matched || matched.length === 0)
+            return c;
+        patchedNames.push(c.name);
+        const newIssues = matched.map((err) => ({
+            severity: 'error',
+            code: 'SERVER_VALIDATION_FAILED',
+            message: err.message,
+        }));
+        const existing = c.originalProposal.validationIssues ?? [];
+        return {
+            ...c,
+            originalProposal: {
+                ...c.originalProposal,
+                validationIssues: [...existing, ...newIssues],
+            },
+        };
+    });
+    const missingNames = [...errorsByName.keys()].filter((n) => !knownNames.has(n));
+    await saveReviewState(paths.statePath, { ...snapshot, components });
+    return { patchedNames, missingNames };
+}
+/**
+ * Exclude components whose names appear in `names` from the next preview/push.
+ * Used by the wizard's "skip and retry" path after a 422.
+ *
+ * Two stores are updated:
+ *   - Pipeline DB (`raw_components.status` → `'generate-rejected'`) so that
+ *     `loadCDFComponents()` excludes them from the next manifest. This is the
+ *     load-bearing change — preview reads from the DB, not the JSON file.
+ *   - Review state JSON (`status` → `'rejected'`) so that if the user re-enters
+ *     the analyze-select TUI later, the rejected status is reflected.
+ *
+ * `'generate-rejected'` matches the existing convention for "component was
+ * generated successfully but later excluded" (see GenerateReviewStep) — the
+ * component generated fine locally but failed server-side validation.
+ */
+export async function rejectComponentsByName(sessionId, names, opts = {}) {
+    if (names.length === 0)
+        return;
+    const db = openPipelineDb();
+    try {
+        const placeholders = names.map(() => '?').join(',');
+        db.prepare(`UPDATE raw_components SET status = 'generate-rejected' WHERE session_id = ? AND name IN (${placeholders})`).run(sessionId, ...names);
+    }
+    finally {
+        db.close();
+    }
+    const artifactsRoot = opts.artifactsRoot ?? getRefineArtifactsRoot();
+    const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+    const nameSet = new Set(names);
+    let snapshot;
+    try {
+        snapshot = JSON.parse(await readFile(paths.statePath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const components = snapshot.components.map((c) => (nameSet.has(c.name) ? { ...c, status: 'rejected' } : c));
+    await saveReviewState(paths.statePath, { ...snapshot, components });
+}
 function resolveSessionId(sessionFlag) {
     if (sessionFlag)
         return sessionFlag;
@@ -170,17 +380,19 @@ export function registerAnalyzeEditCommand(program) {
         .option('--accept-all', 'Alias for --select-all', false)
         .option('--reject <pattern>', 'Alias for --deselect <pattern> (repeatable)', collect, [])
         .option('--patch <path>', 'Path to a JSON patch file for structured component overrides')
-        .action(async ({ session: sessionFlag, projectRoot, acceptAll, selectAll, reject, deselect, select, patch, }) => {
+        .option('--exclude-invalid', 'With --select-all: auto-reject components with validation errors instead of failing loud (opt-in bypass for the gate)')
+        .option('--exclude-components <names>', 'Comma-separated component names to force-reject, regardless of other selection flags')
+        .action(async ({ session: sessionFlag, projectRoot, acceptAll, selectAll, reject, deselect, select, patch, excludeInvalid, excludeComponents, }) => {
         const sessionId = resolveSessionId(sessionFlag);
         const db = openPipelineDb();
-        let rawComponents;
+        let rawComponentCount = 0;
         try {
-            rawComponents = loadRawComponents(db, sessionId);
+            rawComponentCount = loadRawComponents(db, sessionId).length;
         }
         finally {
             db.close();
         }
-        if (rawComponents.length === 0) {
+        if (rawComponentCount === 0) {
             process.stderr.write(`Error: session '${sessionId}' has no raw components. Run analyze extract first.\n`);
             process.exit(1);
             return;
@@ -191,13 +403,12 @@ export function registerAnalyzeEditCommand(program) {
             (reject ?? []).length > 0 ||
             (deselect ?? []).length > 0 ||
             (select ?? []).length > 0 ||
-            !!patch;
+            !!patch ||
+            !!excludeComponents;
         let paths;
         let snapshot;
         try {
-            snapshot = await loadReviewInput(rawComponents, {
-                reviewRoot: projectRoot,
-            });
+            snapshot = await loadAndValidateForReview(sessionId, projectRoot);
             paths = await getRefineSessionPaths(sessionId, artifactsRoot);
             if (!nonInteractive) {
                 snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);
@@ -214,9 +425,22 @@ export function registerAnalyzeEditCommand(program) {
         // Non-interactive path
         if (nonInteractive) {
             const stepDb = openPipelineDb();
-            const stepId = createStep(stepDb, sessionId, 'analyze select', { sessionId });
+            const stepId = createStep(stepDb, sessionId, 'analyze select', {
+                sessionId,
+            });
             try {
-                await runNonInteractive(snapshot, { session: sessionFlag, projectRoot, acceptAll, selectAll, reject, deselect, select, patch }, paths, sessionId);
+                await runNonInteractive(snapshot, {
+                    session: sessionFlag,
+                    projectRoot,
+                    acceptAll,
+                    selectAll,
+                    reject,
+                    deselect,
+                    select,
+                    patch,
+                    excludeInvalid,
+                    excludeComponents,
+                }, paths, sessionId);
                 updateStep(stepDb, stepId, 'complete', { sessionId });
             }
             catch (err) {