@contentful/experience-design-system-cli 2.2.1

package/dist/src/print/command.js

@@ -0,0 +1,199 @@
+import { createElement } from 'react';
+import { render } from 'ink';
+import { access, mkdir, stat, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { openPipelineDb, loadCDFComponents, loadDTCGTokens, findLatestSessionForCommand } from '../session/db.js';
+import { validateCDFFile } from './validate/validators/cdf-validator.js';
+import { validateDTCGTokenFile } from './validate/validators/dtcg-validator.js';
+import { formatDiagnostics } from './validate/validators/format-errors.js';
+import { ValidateView } from './validate/tui/ValidateView.js';
+function die(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+async function pathExists(p) {
+    return access(p)
+        .then(() => true)
+        .catch(() => false);
+}
+async function assertOutIsNotDirectory(outPath) {
+    if (await pathExists(outPath)) {
+        const s = await stat(outPath);
+        if (s.isDirectory())
+            die(`Error: --out must be a file path, not a directory: ${outPath}`);
+    }
+}
+function resolveSession(sessionFlag, command) {
+    const db = openPipelineDb();
+    try {
+        const sessionId = sessionFlag ?? findLatestSessionForCommand(db, command);
+        if (!sessionId) {
+            const hint = command === 'generate components' ? 'generate components' : 'generate tokens';
+            die(`Error: no completed ${hint} session found. Run ${hint} first, or pass --session <id>.`);
+        }
+        return sessionId;
+    }
+    finally {
+        db.close();
+    }
+}
+function rebuildDTCGTree(groups, tokens) {
+    const root = {};
+    // Apply group descriptions
+    for (const group of groups) {
+        const segments = group.path.split('.');
+        let node = root;
+        for (const seg of segments) {
+            if (typeof node[seg] !== 'object' || node[seg] === null) {
+                node[seg] = {};
+            }
+            node = node[seg];
+        }
+        if (group.$description) {
+            node['$description'] = group.$description;
+        }
+    }
+    // Place leaf tokens
+    for (const token of tokens) {
+        const segments = token.path.split('.');
+        const leafKey = segments[segments.length - 1];
+        const parentSegments = segments.slice(0, -1);
+        let node = root;
+        for (const seg of parentSegments) {
+            if (typeof node[seg] !== 'object' || node[seg] === null) {
+                node[seg] = {};
+            }
+            node = node[seg];
+        }
+        const leaf = { $type: token.$type, $value: token.$value };
+        if (token.$description)
+            leaf['$description'] = token.$description;
+        node[leafKey] = leaf;
+    }
+    return root;
+}
+export function registerPrintCommand(program) {
+    const print = program.command('print').description('Write pipeline artifacts to JSON files or validate them');
+    // print components
+    print
+        .command('components')
+        .description('Write generated components to a CDF JSON file')
+        .option('--session <id>', 'Session ID to print from (default: most recent generate components session)')
+        .option('--out <path>', 'Output file path', 'components.json')
+        .action(async (opts) => {
+        const outPath = resolve(opts.out);
+        await assertOutIsNotDirectory(outPath);
+        const sessionId = resolveSession(opts.session, 'generate components');
+        const db = openPipelineDb();
+        let components;
+        let generateStepStatus = null;
+        try {
+            components = loadCDFComponents(db, sessionId);
+            const stepRow = db
+                .prepare(`SELECT status FROM steps WHERE session_id = ? AND command = 'generate components' ORDER BY id DESC LIMIT 1`)
+                .get(sessionId);
+            generateStepStatus = stepRow?.status ?? null;
+        }
+        finally {
+            db.close();
+        }
+        if (components.length === 0) {
+            die(`Error: no generated components in session '${sessionId}'. Run generate components first.`);
+        }
+        if (generateStepStatus === 'failed') {
+            process.stderr.write(`Warning: session '${sessionId}' generate step failed — output may be incomplete (${components.length} components found)\n`);
+        }
+        const cdfObj = { $schema: 'https://contentful.com/schemas/cdf/v1' };
+        const missingDescription = [];
+        for (const { key, entry } of components) {
+            cdfObj[key] = entry;
+            if (!entry.$description)
+                missingDescription.push(key);
+        }
+        if (missingDescription.length > 0) {
+            process.stderr.write(`Warning: ${missingDescription.length} component${missingDescription.length === 1 ? '' : 's'} missing $description (will fail at apply push): ${missingDescription.join(', ')}\n`);
+        }
+        await mkdir(resolve(outPath, '..'), { recursive: true });
+        await writeFile(outPath, `${JSON.stringify(cdfObj, null, 2)}\n`);
+        process.stdout.write(`wrote ${basename(outPath)} (${components.length} component${components.length === 1 ? '' : 's'})\n`);
+    });
+    // print tokens
+    print
+        .command('tokens')
+        .description('Write generated tokens to a DTCG JSON file')
+        .option('--session <id>', 'Session ID to print from (default: most recent generate tokens session)')
+        .option('--out <path>', 'Output file path', 'tokens.json')
+        .action(async (opts) => {
+        const outPath = resolve(opts.out);
+        await assertOutIsNotDirectory(outPath);
+        const sessionId = resolveSession(opts.session, 'generate tokens');
+        const db = openPipelineDb();
+        let result;
+        try {
+            result = loadDTCGTokens(db, sessionId);
+        }
+        finally {
+            db.close();
+        }
+        if (result.tokens.length === 0) {
+            die(`Error: no generated tokens in session '${sessionId}'. Run generate tokens first.`);
+        }
+        const tree = rebuildDTCGTree(result.groups, result.tokens);
+        await mkdir(resolve(outPath, '..'), { recursive: true });
+        await writeFile(outPath, `${JSON.stringify(tree, null, 2)}\n`);
+        process.stdout.write(`wrote ${basename(outPath)} (${result.tokens.length} token${result.tokens.length === 1 ? '' : 's'})\n`);
+    });
+    // print validate
+    print
+        .command('validate')
+        .description('Validate CDF or DTCG files against their schemas')
+        .option('--components <path>', 'Path to CDF components file')
+        .option('--tokens <path>', 'Path to DTCG tokens file')
+        .action(async (opts) => {
+        if (!opts.components && !opts.tokens) {
+            process.stderr.write('Error: at least one of --components or --tokens is required.\n\nUsage: print validate [--components <path>] [--tokens <path>]\n');
+            process.exit(1);
+        }
+        const viewResults = [];
+        if (opts.components) {
+            const r = await validateCDFFile(opts.components);
+            viewResults.push({
+                filePath: opts.components,
+                format: 'CDF v1',
+                valid: r.valid,
+                summary: r.summary,
+                diagnostics: r.diagnostics,
+            });
+        }
+        if (opts.tokens) {
+            const r = await validateDTCGTokenFile(opts.tokens);
+            viewResults.push({
+                filePath: opts.tokens,
+                format: 'DTCG',
+                valid: r.valid,
+                summary: r.summary,
+                diagnostics: r.diagnostics,
+            });
+        }
+        const failed = viewResults.some((r) => !r.valid);
+        const exitCode = failed ? 1 : 0;
+        if (process.stdout.isTTY) {
+            const { waitUntilExit } = render(createElement(ValidateView, {
+                results: viewResults,
+                onExit: () => process.exit(exitCode),
+            }));
+            await waitUntilExit();
+        }
+        else {
+            const output = viewResults
+                .map((r) => formatDiagnostics({
+                valid: r.valid,
+                summary: r.summary ?? r.filePath,
+                diagnostics: r.diagnostics,
+            }))
+                .join('\n\n');
+            process.stdout.write(output + '\n');
+            process.exit(exitCode);
+        }
+    });
+}

package/dist/src/print/validate/tui/ValidateView.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { ValidationDiagnostic } from '../validators/format-errors.js';
+export type ValidateViewEntry = {
+    filePath: string;
+    format: 'CDF v1' | 'DTCG';
+    valid: boolean;
+    summary?: string;
+    diagnostics: ValidationDiagnostic[];
+};
+type ValidateViewProps = {
+    results: ValidateViewEntry[];
+    onExit: () => void;
+};
+export declare function ValidateView({ results, onExit }: ValidateViewProps): React.ReactElement;
+export {};

package/dist/src/print/validate/tui/ValidateView.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text } from 'ink';
+import { TopBar } from '../../../analyze/select/tui/components/TopBar.js';
+import { useImmediateInput } from '../../../analyze/select/tui/hooks/useImmediateInput.js';
+export function ValidateView({ results, onExit }) {
+    const [scrollOffset, setScrollOffset] = useState(0);
+    const allValid = results.every((r) => r.valid);
+    useImmediateInput((input, key) => {
+        if (input === 'q' || key.return) {
+            onExit();
+            return;
+        }
+        if (key.upArrow || input === 'k') {
+            setScrollOffset((o) => Math.max(0, o - 1));
+        }
+        else if (key.downArrow || input === 'j') {
+            setScrollOffset((o) => o + 1);
+        }
+        else if (input === 'g') {
+            setScrollOffset(0);
+        }
+        else if (input === 'G') {
+            setScrollOffset(100);
+        }
+    });
+    const invalidResults = results.filter((r) => !r.valid);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(TopBar, { subcommand: "validate", hints: [
+                    { key: '?', label: 'help' },
+                    { key: 'q', label: 'quit' },
+                ] }), _jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [results.map((r) => {
+                        const summaryText = r.summary || (r.valid ? 'valid' : (r.diagnostics[0]?.message ?? 'invalid'));
+                        return (_jsxs(Box, { children: [_jsx(Text, { color: r.valid ? 'green' : 'red', children: r.valid ? '✓' : '✗' }), _jsx(Text, { children: ' ' + r.filePath.split('/').pop() }), _jsx(Text, { dimColor: true, children: '   ' + r.format + '   ' }), _jsx(Text, { color: r.valid ? 'green' : 'red', children: summaryText })] }, r.filePath));
+                    }), invalidResults.length > 0 && (_jsx(_Fragment, { children: invalidResults.map((r) => (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { bold: true, children: r.filePath.split('/').pop() + ' errors' }), _jsx(Text, { dimColor: true, children: '─'.repeat(70) }), _jsx(Text, { children: " " }), r.diagnostics.slice(scrollOffset).map((d, i) => (_jsx(Box, { children: _jsx(Text, { color: "red", children: '  ✗ ' + d.path + ': ' + d.message }) }, i)))] }, r.filePath))) }))] }), _jsxs(Box, { borderStyle: "single", paddingX: 1, justifyContent: "space-between", children: [_jsx(Text, { dimColor: true, children: allValid
+                            ? 'All files valid'
+                            : invalidResults.length + ' file' + (invalidResults.length === 1 ? '' : 's') + ' invalid' }), _jsx(Text, { dimColor: true, children: allValid ? '[q]' : 'scroll ↑↓ [q]' })] })] }));
+}

package/dist/src/print/validate/validators/cdf-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationResult } from './format-errors.js';
+export declare function validateCDFFile(filePath: string): Promise<ValidationResult>;

package/dist/src/print/validate/validators/cdf-validator.js

@@ -0,0 +1,104 @@
+import { readFile } from 'node:fs/promises';
+import { validateCDF } from '@contentful/experience-design-system-types';
+function extractValue(input, path) {
+    if (path === '/')
+        return undefined;
+    const parts = path.split('/').filter(Boolean);
+    let current = input;
+    for (const part of parts) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[part];
+    }
+    if (current === undefined)
+        return undefined;
+    return typeof current === 'string' ? current : JSON.stringify(current);
+}
+function inferParamsShape(expected) {
+    if (!expected)
+        return null;
+    try {
+        return JSON.parse(expected);
+    }
+    catch {
+        return null;
+    }
+}
+function rewriteDiagnostic(error, input) {
+    const params = inferParamsShape(error.expected);
+    if (!params) {
+        return { ...error };
+    }
+    let { path } = error;
+    let message = error.message;
+    let expected = error.expected;
+    let actual = error.actual;
+    if ('missingProperty' in params) {
+        const prop = params.missingProperty;
+        path = `${path}/${prop}`;
+        message = `Missing required property "${prop}"`;
+        expected = undefined;
+        actual = undefined;
+    }
+    else if ('allowedValues' in params) {
+        const values = params.allowedValues;
+        const fieldName = path.split('/').pop() ?? path;
+        message = `Invalid ${fieldName.replace(/^\$/, '')}`;
+        expected = values.join(', ');
+        actual = extractValue(input, path);
+    }
+    else if ('allowedValue' in params) {
+        message = 'Invalid value';
+        expected = String(params.allowedValue);
+        actual = extractValue(input, path);
+    }
+    else {
+        expected = JSON.stringify(params);
+    }
+    return {
+        path,
+        message,
+        ...(expected !== undefined && { expected }),
+        ...(actual !== undefined && { actual }),
+    };
+}
+export async function validateCDFFile(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        return {
+            valid: false,
+            summary: '',
+            diagnostics: [{ path: filePath, message: err.message }],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            summary: '',
+            diagnostics: [{ path: filePath, message: `Invalid JSON: ${err.message}` }],
+        };
+    }
+    const cdfResult = validateCDF(parsed);
+    if (!cdfResult.valid) {
+        const diagnostics = cdfResult.errors
+            .filter((e) => {
+            const params = inferParamsShape(e.expected);
+            return !params || !('passingSchemas' in params);
+        })
+            .map((e) => rewriteDiagnostic(e, parsed));
+        return { valid: false, summary: '', diagnostics };
+    }
+    const count = cdfResult.components.length;
+    return {
+        valid: true,
+        summary: `Valid CDF v1 — ${count} component${count === 1 ? '' : 's'} found`,
+        diagnostics: [],
+    };
+}

package/dist/src/print/validate/validators/dtcg-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationResult } from './format-errors.js';
+export declare function validateDTCGTokenFile(filePath: string): Promise<ValidationResult>;

package/dist/src/print/validate/validators/dtcg-validator.js

@@ -0,0 +1,110 @@
+import { readFile } from 'node:fs/promises';
+import { DESIGN_TOKEN_TYPES } from '@contentful/experience-design-system-types';
+/*
+ * Strict DTCG subset validation.
+ *
+ * This validator is intentionally stricter than both the W3C DTCG spec and the
+ * TypeScript types in @contentful/experience-design-system-types:
+ *
+ * - No group-level type inheritance. The DTCG spec allows $type on a group to
+ *   be inherited by descendants. This validator requires explicit $type on
+ *   every leaf token.
+ *
+ * - No string values at non-$ keys. DTCGTokenGroupNode allows string | undefined
+ *   at arbitrary keys, but this validator rejects non-object values at non-$
+ *   positions.
+ *
+ * Both restrictions exist because agent-generated files should be maximally
+ * explicit and self-describing.
+ */
+function walkDTCG(obj, path, diagnostics, counts) {
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.startsWith('$'))
+            continue;
+        const currentPath = `${path}/${key}`;
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            diagnostics.push({
+                path: currentPath,
+                message: `Expected object, got ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value}`,
+            });
+            continue;
+        }
+        const node = value;
+        const hasValue = '$value' in node;
+        const hasType = '$type' in node;
+        if (hasValue) {
+            counts.tokens++;
+            if (!hasType) {
+                diagnostics.push({
+                    path: currentPath,
+                    message: 'Token has "$value" but missing required "$type"',
+                });
+            }
+            else if (typeof node.$type !== 'string' || !DESIGN_TOKEN_TYPES.includes(node.$type)) {
+                diagnostics.push({
+                    path: `${currentPath}/$type`,
+                    message: 'Invalid design token type',
+                    expected: DESIGN_TOKEN_TYPES.join(', '),
+                    actual: String(node.$type),
+                });
+            }
+        }
+        else if (hasType) {
+            diagnostics.push({
+                path: currentPath,
+                message: 'Node has "$type" but missing required "$value" (leaf tokens must have both)',
+            });
+        }
+        else {
+            counts.groups++;
+            walkDTCG(node, currentPath, diagnostics, counts);
+        }
+    }
+}
+export async function validateDTCGTokenFile(filePath) {
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        return {
+            valid: false,
+            summary: '',
+            diagnostics: [{ path: filePath, message: err.message }],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            summary: '',
+            diagnostics: [{ path: filePath, message: `Invalid JSON: ${err.message}` }],
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            valid: false,
+            summary: '',
+            diagnostics: [
+                {
+                    path: '/',
+                    message: `Expected object, got ${parsed === null ? 'null' : Array.isArray(parsed) ? 'array' : typeof parsed}`,
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    const counts = { tokens: 0, groups: 0 };
+    walkDTCG(parsed, '', diagnostics, counts);
+    if (diagnostics.length > 0) {
+        return { valid: false, summary: '', diagnostics };
+    }
+    return {
+        valid: true,
+        summary: `Valid DTCG token file — ${counts.tokens} token${counts.tokens === 1 ? '' : 's'} in ${counts.groups} group${counts.groups === 1 ? '' : 's'}`,
+        diagnostics: [],
+    };
+}

package/dist/src/print/validate/validators/format-errors.d.ts

@@ -0,0 +1,12 @@
+export interface ValidationDiagnostic {
+    path: string;
+    message: string;
+    expected?: string;
+    actual?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    summary: string;
+    diagnostics: ValidationDiagnostic[];
+}
+export declare function formatDiagnostics(result: ValidationResult): string;

package/dist/src/print/validate/validators/format-errors.js

@@ -0,0 +1,18 @@
+export function formatDiagnostics(result) {
+    if (result.valid) {
+        return `✓ ${result.summary}`;
+    }
+    const count = result.diagnostics.length;
+    const header = `✗ ${count} error${count === 1 ? '' : 's'} found`;
+    const entries = result.diagnostics.map((d, i) => {
+        const lines = [`  ${i + 1}. ${d.path}`, `     ${d.message}`];
+        if (d.expected !== undefined) {
+            lines.push(`     expected: ${d.expected}`);
+        }
+        if (d.actual !== undefined) {
+            lines.push(`     actual:   ${d.actual}`);
+        }
+        return lines.join('\n');
+    });
+    return `${header}\n\n${entries.join('\n\n')}`;
+}

package/dist/src/program.d.ts

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

package/dist/src/program.js

@@ -0,0 +1,25 @@
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { registerAnalyzeCommand } from './analyze/command.js';
+import { registerGenerateCommand } from './generate/command.js';
+import { registerApplyCommand } from './apply/command.js';
+import { registerSessionCommand } from './session/command.js';
+import { registerPrintCommand } from './print/command.js';
+import { registerImportCommand } from './import/command.js';
+import { registerSetupCommand } from './setup/command.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export function createProgram() {
+    const program = new Command()
+        .name('experience-design-system-cli')
+        .description('Static analysis, validation, generation, and import of Contentful design system artifacts')
+        .version(pkg.version, '--version', 'Print version number');
+    registerAnalyzeCommand(program);
+    registerGenerateCommand(program);
+    registerPrintCommand(program);
+    registerApplyCommand(program);
+    registerSessionCommand(program);
+    registerImportCommand(program);
+    registerSetupCommand(program);
+    return program;
+}

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

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