@contentful/experience-design-system-cli 2.2.1

package/dist/src/analyze/pre-classify.d.ts

@@ -0,0 +1,17 @@
+import type { RawPropDefinition, RawComponentDefinition } from '../types.js';
+export interface PreClassification {
+    category: 'content' | 'design' | 'state' | 'exclude';
+    cdfTypeHint?: 'string' | 'enum' | 'richtext' | 'media';
+}
+/**
+ * Deterministic pre-classification rule engine.
+ * Applies rules in priority order and returns on the first match.
+ */
+export declare function preClassifyProp(prop: RawPropDefinition): PreClassification | undefined;
+/**
+ * Applies pre-classification to all props in a component definition.
+ * - Leaves existing category values unchanged
+ * - Sets category for content/design/state matches
+ * - Does NOT set category for 'exclude' results (leaves undefined)
+ */
+export declare function preClassifyComponent(component: RawComponentDefinition): RawComponentDefinition;

package/dist/src/analyze/pre-classify.js

@@ -0,0 +1,144 @@
+/**
+ * Determines whether a type string represents a simple/primitive type
+ * (string, boolean, number, or string literal union) vs a complex type
+ * (object, function, array, generic, etc.).
+ */
+function isSimpleType(type) {
+    const t = type.trim();
+    if (t === 'string' || t === 'boolean' || t === 'number')
+        return true;
+    // String literal union (e.g., "'a' | 'b'")
+    if (isStringLiteralUnion(t))
+        return true;
+    return false;
+}
+function isStringLiteralUnion(type) {
+    return type.includes('|') && type.includes("'");
+}
+function isBooleanType(type) {
+    return type.trim() === 'boolean';
+}
+function isStringType(type) {
+    return type.trim() === 'string';
+}
+function isNumberType(type) {
+    return type.trim() === 'number';
+}
+function isComplexType(type) {
+    return !isSimpleType(type);
+}
+/**
+ * Deterministic pre-classification rule engine.
+ * Applies rules in priority order and returns on the first match.
+ */
+export function preClassifyProp(prop) {
+    const { name, type } = prop;
+    // Rule 1: Event handlers
+    // name starts with `on` + uppercase, OR type contains `=> void` or `EventHandler`
+    if (/^on[A-Z]/.test(name) || type.includes('=> void') || type.includes('EventHandler')) {
+        return { category: 'exclude' };
+    }
+    // Rule 2: Refs
+    if (name === 'ref' || name === 'innerRef' || type.includes('Ref<') || type.includes('RefObject<')) {
+        return { category: 'exclude' };
+    }
+    // Rule 3: Test IDs
+    if (name === 'testId' || name === 'data-testid' || name === 'dataTestId') {
+        return { category: 'exclude' };
+    }
+    // Rule 4: Key prop
+    if (name === 'key') {
+        return { category: 'exclude' };
+    }
+    // Rule 5: Dispatch/setter
+    if (type.includes('Dispatch<') || type.includes('SetStateAction')) {
+        return { category: 'exclude' };
+    }
+    // Rule 6: className, style, styles
+    if (name === 'className' || name === 'style' || name === 'styles') {
+        return { category: 'design', cdfTypeHint: 'string' };
+    }
+    // Rule 7: String literal union
+    if (isStringLiteralUnion(type)) {
+        return { category: 'design', cdfTypeHint: 'enum' };
+    }
+    // Rule 8: Design name patterns (only for simple types)
+    if (!isComplexType(type)) {
+        const designNameStart = /^(variant|size|spacing|gap|color|bg|theme|align|layout|orientation|position)/i;
+        const designNameEnd = /(Color|Size|Variant|Style)$/;
+        if (designNameStart.test(name) || designNameEnd.test(name)) {
+            return { category: 'design', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 10: Boolean + state names (checked before rule 9 since state names
+    // like "disabled" would otherwise match the visual toggle prefix "disable")
+    if (isBooleanType(type)) {
+        const stateNames = ['disabled', 'loading', 'expanded', 'isOpen', 'selected', 'checked', 'active', 'preview'];
+        if (stateNames.includes(name)) {
+            return { category: 'state', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 9: Boolean + visual toggle name
+    if (isBooleanType(type)) {
+        const visualToggle = /^(hide|show|enable|disable|vertical|horizontal|reverse|bold|italic|imageOn|with)/i;
+        if (visualToggle.test(name)) {
+            return { category: 'design', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 11: State identifiers
+    if (name === 'componentId' || name === 'sectionKey' || name === 'locale' || name === 'variantIndex') {
+        return { category: 'state', cdfTypeHint: 'string' };
+    }
+    // Rule 12: URL patterns (string type only)
+    if (isStringType(type)) {
+        const urlNameStart = /^(href|url|link|src)/i;
+        const urlNameEnd = /(Url|Href|Link|Src)$/;
+        if (urlNameStart.test(name) || urlNameEnd.test(name)) {
+            return { category: 'content', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 13: Text patterns (string type only)
+    if (isStringType(type)) {
+        const textNameStart = /^(label|title|text|description|caption|heading|subheading|body|alt|name|placeholder|summary)/i;
+        const textNameEnd = /(Text|Label|Title|Name)$/;
+        if (textNameStart.test(name) || textNameEnd.test(name)) {
+            return { category: 'content', cdfTypeHint: 'string' };
+        }
+    }
+    // Rule 14: Remaining strings
+    if (isStringType(type)) {
+        return { category: 'content', cdfTypeHint: 'string' };
+    }
+    // Rule 15: Remaining booleans
+    if (isBooleanType(type)) {
+        return { category: 'design', cdfTypeHint: 'string' };
+    }
+    // Rule 16: Remaining numbers
+    if (isNumberType(type)) {
+        return { category: 'design', cdfTypeHint: 'string' };
+    }
+    // Rule 17: Complex/object/function/array types — no hint
+    return undefined;
+}
+/**
+ * Applies pre-classification to all props in a component definition.
+ * - Leaves existing category values unchanged
+ * - Sets category for content/design/state matches
+ * - Does NOT set category for 'exclude' results (leaves undefined)
+ */
+export function preClassifyComponent(component) {
+    const props = component.props.map((prop) => {
+        // If category is already set, leave unchanged
+        if (prop.category) {
+            return prop;
+        }
+        const result = preClassifyProp(prop);
+        // If no result or excluded, leave unchanged
+        if (!result || result.category === 'exclude') {
+            return prop;
+        }
+        // Set category hint
+        return { ...prop, category: result.category };
+    });
+    return { ...component, props };
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerAnalyzeEditCommand(program: Command): void;

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

@@ -0,0 +1,256 @@
+import { readFile } from 'node:fs/promises';
+import { 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';
+const SAFE_PATH_RE = /^[a-zA-Z0-9_.$[\]=]+$/;
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function applyDotPath(obj, path, value) {
+    if (!SAFE_PATH_RE.test(path)) {
+        process.stderr.write(`Warning: --patch path contains invalid characters: '${path}', skipping\n`);
+        return;
+    }
+    const parts = path.split('.');
+    if (parts.some((p) => PROTO_KEYS.has(p))) {
+        process.stderr.write(`Warning: --patch path contains forbidden key: '${path}', skipping\n`);
+        return;
+    }
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        // Handle array predicate syntax: field[name=value]
+        const arrayMatch = /^(.+)\[name=(.+)\]$/.exec(part);
+        if (arrayMatch) {
+            const [, fieldName, matchValue] = arrayMatch;
+            const arr = current[fieldName];
+            if (Array.isArray(arr)) {
+                const item = arr.find((el) => el['name'] === matchValue);
+                if (item) {
+                    current = item;
+                }
+                else {
+                    process.stderr.write(`Warning: --patch array item [name=${matchValue}] not found in '${fieldName}', skipping\n`);
+                    return;
+                }
+            }
+        }
+        else {
+            if (typeof current[part] !== 'object' || current[part] === null) {
+                process.stderr.write(`Warning: --patch path '${path}' — '${part}' is not an object, skipping\n`);
+                return;
+            }
+            current = current[part];
+        }
+    }
+    const lastPart = parts[parts.length - 1];
+    current[lastPart] = value;
+}
+function applyPatch(snapshot, ops) {
+    const components = snapshot.components.map((c) => {
+        const op = ops.find((o) => o.component === c.name);
+        if (!op)
+            return c;
+        let updated = { ...c };
+        if (op.status) {
+            updated = { ...updated, status: op.status };
+        }
+        if (op.set) {
+            const editedProposal = structuredClone(updated.editedProposal);
+            for (const [path, value] of Object.entries(op.set)) {
+                applyDotPath(editedProposal, path, value);
+            }
+            updated = {
+                ...updated,
+                editedProposal: editedProposal,
+            };
+        }
+        return updated;
+    });
+    return { ...snapshot, components };
+}
+async function runNonInteractive(snapshot, opts, paths, sessionId) {
+    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;
+    if (selectAll || rejectPatterns.length > 0 || selectPatterns.length > 0) {
+        result = {
+            ...result,
+            components: result.components.map((c) => {
+                const nameLower = c.name.toLowerCase();
+                if (rejectPatterns.some((p) => nameLower.includes(p))) {
+                    return { ...c, status: 'rejected' };
+                }
+                if (selectAll || selectPatterns.some((p) => nameLower.includes(p))) {
+                    return { ...c, status: 'accepted' };
+                }
+                return c;
+            }),
+        };
+    }
+    // Apply --patch
+    if (opts.patch) {
+        let patchOps;
+        try {
+            const raw = await readFile(resolve(opts.patch), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed)) {
+                process.stderr.write(`Error: --patch file must be a JSON array of patch operations: ${opts.patch}\n`);
+                process.exit(1);
+                return;
+            }
+            patchOps = parsed;
+        }
+        catch {
+            process.stderr.write(`Error: cannot read or parse --patch file: ${opts.patch}\n`);
+            process.exit(1);
+            return;
+        }
+        // Warn on unknown component names
+        const knownNames = new Set(result.components.map((c) => c.name));
+        for (const op of patchOps) {
+            if (!knownNames.has(op.component)) {
+                process.stderr.write(`Warning: --patch targets unknown component '${op.component}', skipping\n`);
+            }
+        }
+        result = applyPatch(result, patchOps);
+    }
+    const accepted = result.components.filter((c) => c.status === 'accepted');
+    const rejected = result.components.filter((c) => c.status === 'rejected');
+    // 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) {
+        const db = openPipelineDb();
+        try {
+            storeRawComponents(db, sessionId, accepted.map((c) => c.editedProposal));
+        }
+        finally {
+            db.close();
+        }
+    }
+    process.stderr.write(`Accepted: ${accepted.length}  Rejected: ${rejected.length}\n`);
+}
+function resolveSessionId(sessionFlag) {
+    if (sessionFlag)
+        return sessionFlag;
+    const db = openPipelineDb();
+    try {
+        const row = db
+            .prepare(`SELECT s.id FROM sessions s
+         JOIN steps st ON st.session_id = s.id
+         WHERE st.command = 'analyze extract'
+           AND st.status = 'complete'
+         ORDER BY st.started_at DESC
+         LIMIT 1`)
+            .get();
+        if (!row) {
+            process.stderr.write('Error: no completed analyze extract session found. Run analyze extract first, or pass --session <id>.\n');
+            process.exit(1);
+        }
+        return row.id;
+    }
+    finally {
+        db.close();
+    }
+}
+export function registerAnalyzeEditCommand(program) {
+    program
+        .command('select')
+        .alias('edit')
+        .description('Select components for generation and optionally patch their definitions')
+        .option('--session <id>', 'Session ID from analyze extract (defaults to most recent)')
+        .option('--project-root <path>', 'Project root for resolving component source files')
+        .option('--select-all', 'Select all components without launching the TUI')
+        .option('--select <pattern>', 'Select components whose name contains pattern (repeatable)', collect, [])
+        .option('--deselect <pattern>', 'Deselect components whose name contains pattern (repeatable)', collect, [])
+        .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, }) => {
+        const sessionId = resolveSessionId(sessionFlag);
+        const db = openPipelineDb();
+        let rawComponents;
+        try {
+            rawComponents = loadRawComponents(db, sessionId);
+        }
+        finally {
+            db.close();
+        }
+        if (rawComponents.length === 0) {
+            process.stderr.write(`Error: session '${sessionId}' has no raw components. Run analyze extract first.\n`);
+            process.exit(1);
+            return;
+        }
+        const artifactsRoot = getRefineArtifactsRoot();
+        const nonInteractive = acceptAll ||
+            selectAll ||
+            (reject ?? []).length > 0 ||
+            (deselect ?? []).length > 0 ||
+            (select ?? []).length > 0 ||
+            !!patch;
+        let paths;
+        let snapshot;
+        try {
+            snapshot = await loadReviewInput(rawComponents, {
+                reviewRoot: projectRoot,
+            });
+            paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+            if (!nonInteractive) {
+                snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);
+            }
+            else {
+                await ensureRefineSession(sessionId, artifactsRoot, snapshot);
+            }
+        }
+        catch (error) {
+            process.stderr.write(`Error: unable to initialize refine session.\n${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+            return;
+        }
+        // Non-interactive path
+        if (nonInteractive) {
+            const stepDb = openPipelineDb();
+            const stepId = createStep(stepDb, sessionId, 'analyze select', { sessionId });
+            try {
+                await runNonInteractive(snapshot, { session: sessionFlag, projectRoot, acceptAll, selectAll, reject, deselect, select, patch }, paths, sessionId);
+                updateStep(stepDb, stepId, 'complete', { sessionId });
+            }
+            catch (err) {
+                updateStep(stepDb, stepId, 'failed', {}, err instanceof Error ? err.message : String(err));
+                stepDb.close();
+                throw err;
+            }
+            stepDb.close();
+            return;
+        }
+        // Test mode: print launch contract and return without launching TUI
+        if (process.env.EDS_REVIEW_TEST_MODE === '1') {
+            process.stdout.write(`session=${sessionId}\n` +
+                `session_dir=${paths.sessionDir}\n` +
+                `events.jsonl=${paths.eventsPath}\n` +
+                `current-review-state.json=${paths.statePath}\n`);
+            return;
+        }
+        if (!process.stdout.isTTY) {
+            process.stderr.write('Error: analyze select requires an interactive terminal\n');
+            process.exit(1);
+        }
+        if (process.stdout.columns !== undefined && process.stdout.columns < 60) {
+            process.stderr.write(`Error: terminal too narrow (${process.stdout.columns} cols). Resize to 60+ columns.\n`);
+            process.exit(1);
+        }
+        const { waitUntilExit } = render(createElement(App, {
+            sessionId,
+            artifactsRoot,
+            reviewRoot: projectRoot,
+        }));
+        await waitUntilExit();
+    });
+}
+function collect(val, prev) {
+    return [...prev, val];
+}

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

@@ -0,0 +1,6 @@
+export { registerAnalyzeEditCommand } from './command.js';
+export { loadReviewInput } from './parser.js';
+export { appendReviewEvent, ensureRefineSession, getRefineArtifactsRoot, getRefineSessionPaths, saveReviewState, } from './persistence.js';
+export { formatFinalizeContract } from './stdout.js';
+export type { ReviewComponentRecord, ReviewComponentSummary, ReviewComponentStatus, ReviewEvent, ReviewSessionPaths, ReviewSessionSnapshot, ReviewSessionSummary, } from './types.js';
+export { createReviewSessionSummary } from './types.js';

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

@@ -0,0 +1,5 @@
+export { registerAnalyzeEditCommand } from './command.js';
+export { loadReviewInput } from './parser.js';
+export { appendReviewEvent, ensureRefineSession, getRefineArtifactsRoot, getRefineSessionPaths, saveReviewState, } from './persistence.js';
+export { formatFinalizeContract } from './stdout.js';
+export { createReviewSessionSummary } from './types.js';

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

@@ -0,0 +1,6 @@
+import type { RawComponentDefinition } from '../../types.js';
+import type { ReviewSessionSnapshot } from './types.js';
+export type LoadReviewInputOptions = {
+    reviewRoot?: string;
+};
+export declare function loadReviewInput(components: RawComponentDefinition[], options?: LoadReviewInputOptions): Promise<ReviewSessionSnapshot>;

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

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+import { access } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+function createComponentId(name, resolvedSourcePath) {
+    const sourceHash = createHash('sha256').update(`${name}:${resolvedSourcePath}`).digest('hex').slice(0, 12);
+    return `${name}-${sourceHash}`;
+}
+async function resolveComponentSourcePath(source, reviewRoot) {
+    // Absolute paths stored in the DB are used directly — no reviewRoot boundary check needed.
+    if (isAbsolute(source)) {
+        try {
+            await access(source);
+            return source;
+        }
+        catch {
+            throw new Error(`Unable to access component source at ${source}`);
+        }
+    }
+    const candidate = resolve(reviewRoot, source);
+    const relativeToRoot = relative(reviewRoot, candidate);
+    if (relativeToRoot.startsWith('..') || relativeToRoot === '..' || isAbsolute(relativeToRoot)) {
+        throw new Error(`Resolved component source is outside the review root: ${source}. Pass --project-root <path> to set the correct base.`);
+    }
+    try {
+        await access(candidate);
+        return candidate;
+    }
+    catch {
+        throw new Error(`Unable to access component source at ${candidate}`);
+    }
+}
+export async function loadReviewInput(components, options = {}) {
+    const reviewRoot = resolve(options.reviewRoot ?? process.cwd());
+    const records = await Promise.all(components.map(async (component) => {
+        let resolvedSourcePath;
+        try {
+            resolvedSourcePath = await resolveComponentSourcePath(component.source, reviewRoot);
+        }
+        catch (error) {
+            throw new Error(`Unable to access component source for ${component.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return {
+            id: createComponentId(component.name, resolvedSourcePath),
+            name: component.name,
+            resolvedSourcePath,
+            sourceCode: null,
+            originalProposal: component,
+            editedProposal: structuredClone(component),
+            status: 'needs-review',
+        };
+    }));
+    return { components: records };
+}

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

@@ -0,0 +1,9 @@
+import type { ReviewSessionPaths, ReviewSessionSnapshot } from './types.js';
+export declare function getRefineArtifactsRoot(): string;
+export declare function getRefineSessionPaths(sessionId: string, artifactsRoot: string): Promise<ReviewSessionPaths>;
+export declare function saveReviewState(statePath: string, session: ReviewSessionSnapshot): Promise<void>;
+export declare function appendReviewEvent(eventsPath: string, event: {
+    type: string;
+    payload: Record<string, unknown>;
+}): Promise<void>;
+export declare function ensureRefineSession(sessionId: string, artifactsRoot: string, initialSnapshot: ReviewSessionSnapshot): Promise<ReviewSessionSnapshot>;

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

@@ -0,0 +1,42 @@
+import { access, appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+export function getRefineArtifactsRoot() {
+    if (process.env.EDS_REVIEW_ARTIFACTS_DIR) {
+        return resolve(process.env.EDS_REVIEW_ARTIFACTS_DIR);
+    }
+    return resolve(homedir(), '.contentful', 'experience-design-system-cli', 'reviews');
+}
+export async function getRefineSessionPaths(sessionId, artifactsRoot) {
+    const sessionDir = resolve(artifactsRoot, sessionId);
+    return {
+        sessionDir,
+        eventsPath: resolve(sessionDir, 'events.jsonl'),
+        statePath: resolve(sessionDir, 'current-review-state.json'),
+    };
+}
+export async function saveReviewState(statePath, session) {
+    await writeFile(statePath, JSON.stringify(session, null, 2), 'utf8');
+}
+export async function appendReviewEvent(eventsPath, event) {
+    const record = {
+        type: event.type,
+        timestamp: new Date().toISOString(),
+        payload: event.payload,
+    };
+    await appendFile(eventsPath, JSON.stringify(record) + '\n', 'utf8');
+}
+export async function ensureRefineSession(sessionId, artifactsRoot, initialSnapshot) {
+    const paths = await getRefineSessionPaths(sessionId, artifactsRoot);
+    await mkdir(paths.sessionDir, { recursive: true });
+    try {
+        await access(paths.statePath);
+        const savedState = await readFile(paths.statePath, 'utf8');
+        return JSON.parse(savedState);
+    }
+    catch {
+        await writeFile(paths.statePath, JSON.stringify(initialSnapshot, null, 2), 'utf8');
+        await writeFile(paths.eventsPath, '', 'utf8');
+        return initialSnapshot;
+    }
+}

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

@@ -0,0 +1,7 @@
+export type FinalizeContractInput = {
+    sessionDir: string;
+    accepted: number;
+    rejected: number;
+    excluded: number;
+};
+export declare function formatFinalizeContract(input: FinalizeContractInput): string;

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

@@ -0,0 +1,3 @@
+export function formatFinalizeContract(input) {
+    return JSON.stringify({ status: 'finalized', ...input }, null, 2) + '\n';
+}

package/dist/src/analyze/select/tui/App.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+type AppProps = {
+    sessionId: string;
+    artifactsRoot: string;
+    reviewRoot?: string;
+};
+export declare function App({ sessionId, artifactsRoot, reviewRoot }: AppProps): React.ReactElement;
+export {};