@contentful/experience-design-system-cli 2.2.1

package/dist/src/generate/prompt-builder.js

@@ -0,0 +1,202 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SKILL_FILES = {
+    components: 'generate-components.md',
+    tokens: 'generate-tokens.md',
+    select: 'select-components.md',
+};
+const OUTPUT_FILES = {
+    components: 'components.json',
+    tokens: 'tokens.json',
+    select: 'select.json',
+};
+export async function buildPrompt(options) {
+    const skillContent = await readSkillFile(options.skill);
+    const preamble = buildPreamble(options);
+    return `${preamble}\n\nSkill instructions follow:\n---\n${skillContent}`;
+}
+export function resolveSkillPath(skill) {
+    if (!(skill in SKILL_FILES))
+        throw new Error(`Invalid skill: ${skill}`);
+    // Walk up until we find the skills/ directory (works from both src/ and dist/src/ contexts)
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    let dir = thisDir;
+    for (;;) {
+        const candidate = join(dir, 'skills');
+        if (existsSync(candidate))
+            return join(candidate, SKILL_FILES[skill]);
+        const parent = resolve(dir, '..');
+        if (parent === dir) {
+            throw new Error(`skill file missing from CLI installation (could not locate skills/ directory from: ${thisDir})`);
+        }
+        dir = parent;
+    }
+}
+async function readSkillFile(skill) {
+    const skillPath = resolveSkillPath(skill);
+    try {
+        return await readFile(skillPath, 'utf8');
+    }
+    catch {
+        throw new Error(`skill file missing from CLI installation — try reinstalling the CLI (looked for: ${skillPath})`);
+    }
+}
+function inferFenceLang(filename) {
+    if (!filename)
+        return 'json';
+    const ext = filename.split('.').pop()?.toLowerCase() ?? '';
+    const map = {
+        js: 'js',
+        mjs: 'js',
+        cjs: 'js',
+        ts: 'ts',
+        mts: 'ts',
+        cts: 'ts',
+        scss: 'scss',
+        sass: 'scss',
+        css: 'css',
+        json: 'json',
+        json5: 'json',
+    };
+    return map[ext] ?? 'text';
+}
+function buildPreamble(options) {
+    const { skill, mode, rawComponentsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, outDir } = options;
+    const outputFile = OUTPUT_FILES[skill];
+    const outputPath = join(resolve(outDir), outputFile);
+    const sections = [];
+    if (rawComponentsInline) {
+        sections.push(`Raw component data (JSON):\n\`\`\`json\n${rawComponentsInline}\n\`\`\``);
+    }
+    if (rawTokensInline) {
+        const lang = inferFenceLang(rawTokensFilename);
+        const label = rawTokensFilename ? `Raw token source (${rawTokensFilename})` : 'Raw token source';
+        sections.push(`${label}:\n\`\`\`${lang}\n${rawTokensInline}\n\`\`\``);
+    }
+    if (tokensInline) {
+        sections.push(`DTCG token data (for token kind lookups):\n\`\`\`json\n${tokensInline}\n\`\`\``);
+    }
+    if (tokenMapInline) {
+        sections.push(`Token-name sidecar (raw name → DTCG path):\n\`\`\`json\n${tokenMapInline}\n\`\`\``);
+    }
+    const inputBlock = sections.length > 0 ? `\n\n${sections.join('\n\n')}` : '';
+    if (mode === 'autonomous') {
+        if (skill === 'components') {
+            return buildComponentsAutonomousPreamble(inputBlock);
+        }
+        if (skill === 'select') {
+            return buildSelectAutonomousPreamble(inputBlock);
+        }
+        return buildTokensAutonomousPreamble(inputBlock);
+    }
+    else {
+        return `You are running as part of the experience-design-system-cli generate pipeline in INTERACTIVE mode. The developer is present and will answer your questions.
+
+Your task: follow the skill instructions below, working collaboratively with the developer. Ask for confirmation on category corrections, prop exclusions, and grouping choices as the skill instructs.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+Output:
+Write the final ${outputFile} directly to: ${outputPath}`;
+    }
+}
+function buildComponentsAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Context: You are classifying a React component for **Contentful Experience Orchestration**. The result is a Component Type — a schema that tells Contentful what a marketer can configure. Properties fall into three categories:
+- **design**: controls how the component looks (variant, size, color, layout toggles)
+- **content**: the data a content editor fills in (text, images, URLs, rich text)
+- **state**: runtime behavioral flags (disabled, loading, expanded, identifiers)
+
+For props with complex TypeScript types (named types, enums): reason from the prop name and type name to classify them. Do not automatically exclude a prop just because its type is a named reference — infer the likely values and classify it as enum if it controls appearance.
+
+Your task: classify every prop and slot in the component below. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a "description" field on each tool call to document your reasoning so the developer can review it afterward.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per line to stdout for each classification decision. The CLI reads your stdout line by line and writes each decision directly to the pipeline database.
+
+The four tool calls you may emit are:
+
+\`\`\`
+{"tool":"classify_component","description":"<optional component-level description>"}
+
+{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<reason>","values":["a","b"],"token_kind":"color","default":"<value>"}
+
+{"tool":"exclude_prop","prop":"<propName>","reason":"<why excluded>"}
+
+{"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<reason>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences around the lines.
+- Every prop in the input must have exactly one call: either classify_prop or exclude_prop.
+- Every slot in the input must have exactly one classify_slot call.
+- Valid cdf_type values: string, richtext, media, enum, token, boolean
+- Valid cdf_category values: content, design, state
+- For enum type, always include "values" (non-empty string array).
+- For token type, always include "token_kind" (DTCG \$type, e.g. "color").
+- href and URL props → cdf_type "string", cdf_category "content". Do NOT use cdf_type "link" — it is not valid.
+- Framework internals (ref, event handlers, test IDs) → exclude_prop.
+- CSS design props (className, style, styles, positional/geometric props: top, bottom, left, right, rotation, offset, etc.) → classify_prop, cdf_type: "string", cdf_category: "design".
+- You may emit prose lines (not starting with {) anywhere — they are ignored by the parser and serve as your reasoning log.`;
+}
+function buildSelectAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli import pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Your task: review the single component provided below and decide whether it belongs in Contentful Experience Orchestration as a Component Type. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a brief "reason" to document your reasoning.
+
+Key rule: accept any component that renders visible UI — atoms, molecules, and organisms are all valid Component Types in Contentful Experience Orchestration. Reject only components that produce zero visual output: React hooks, pure context providers, A/B testing or variant-routing wrappers, analytics trackers, and security utilities. Do NOT reject a component because it has few props, is low-level, or has some A/B testing or personalization-related props mixed in — those props are handled in the generate step.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object on a single line to stdout. The CLI reads your stdout line by line.
+
+The two tool calls — emit exactly one:
+
+\`\`\`
+{"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>"}
+
+{"tool":"reject_component","name":"<ComponentName>","reason":"<brief reason>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object, on one line. No multi-line JSON. No markdown fences.
+- The name must match the component name in the input exactly.
+- You may emit prose lines (not starting with {) to reason before the final tool call — they are ignored by the parser.`;
+}
+function buildTokensAutonomousPreamble(inputBlock) {
+    return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
+
+Your task: classify every raw token from the input below into a DTCG token tree. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a "description" field on each set_token call to document your reasoning.
+
+All input data is provided inline below — do not read any additional files.${inputBlock}
+
+## Output protocol
+
+Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per line to stdout for each token or group. The CLI reads your stdout line by line and writes each entry directly to the pipeline database.
+
+The two tool calls you may emit are:
+
+\`\`\`
+{"tool":"set_group","path":"<dot.notation.path>","description":"<optional group description>"}
+
+{"tool":"set_token","path":"<dot.notation.path>","type":"<DTCG type>","value":<value>,"description":"<reason>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit a set_group call for every intermediate group node in the tree.
+- Emit a set_token call for every leaf token.
+- "path" is dot-notation, e.g. "colors.brand.primary" — no leading dots or slashes.
+- "type" must be one of the 13 valid DTCG types: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, strokeStyle, border, transition, shadow, gradient, typography.
+- "value" must be valid JSON (string, number, array, or object depending on the type). Do NOT wrap it in quotes if it is a complex type.
+- Emit set_group calls before the set_token calls that fall under them.
+- You may emit prose lines (not starting with {) anywhere — they are ignored by the parser and serve as your reasoning log.`;
+}

package/dist/src/generate/tui/GenerateView.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+export interface GenerateViewResult {
+    skill: string;
+    agent: string;
+    sessionId: string;
+}
+interface GenerateViewProps {
+    result: GenerateViewResult;
+    onExit: () => void;
+}
+export declare function GenerateView({ result, onExit }: GenerateViewProps): React.ReactElement;
+export {};

package/dist/src/generate/tui/GenerateView.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { Box, Text } from 'ink';
+export function GenerateView({ result, onExit }) {
+    React.useEffect(() => {
+        const timer = setTimeout(onExit, 100);
+        return () => clearTimeout(timer);
+    }, [onExit]);
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsx(Text, { color: "green", children: "\u2713 generate complete" }), _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "skill " }), _jsx(Text, { children: result.skill })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "agent " }), _jsx(Text, { children: result.agent })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "session " }), _jsx(Text, { children: result.sessionId })] })] }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "Run " }), _jsxs(Text, { children: ["experience-design-system-cli print ", result.skill] }), _jsx(Text, { dimColor: true, children: " to write the output file." })] })] }));
+}

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

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

package/dist/src/import/command.js

@@ -0,0 +1,96 @@
+import { resolve, join } from 'node:path';
+import { runPipeline } from './orchestrator.js';
+import { readExoCredentials } from '../credentials-store.js';
+export function registerImportCommand(program) {
+    program
+        .command('import')
+        .description('Run the full pipeline: analyze → select → generate → push')
+        .option('--space-id <id>', 'Contentful space ID (required unless --skip-apply)')
+        .option('--environment-id <id>', 'Contentful environment ID (required unless --skip-apply)')
+        .option('--cma-token <token>', 'CMA personal access token (or set CONTENTFUL_MANAGEMENT_TOKEN)')
+        .option('--project <path>', 'Path to the project root to analyze', '.')
+        .option('--out <path>', 'Output directory for pipeline artifacts')
+        .option('--agent <name>', 'Agent to use for generate components', 'claude')
+        .option('--model <name>', 'Model to use for generate components (defaults to a small/fast model per agent)')
+        .option('--tokens <path>', 'Path to a DTCG tokens.json file to push alongside generated components')
+        .option('--select-all', 'Select all extracted components for generation (default)')
+        .option('--select <pattern>', 'Select components matching pattern (repeatable)', (v, a) => [...a, v], [])
+        .option('--deselect <pattern>', 'Deselect components matching pattern (repeatable)', (v, a) => [...a, v], [])
+        .option('--skip-analyze', 'Skip the analyze step (uses most recent extract session)')
+        .option('--skip-generate', 'Skip the generate step (uses most recent generate session)')
+        .option('--print', 'Write components.json to --out after generation')
+        .option('--skip-apply', 'Skip pushing to Contentful (stops after generate)')
+        .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('--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')
+        .action(async (opts) => {
+        const isHeadless = opts.skipAnalyze ||
+            opts.skipGenerate ||
+            opts.skipApply ||
+            !!opts.spaceId ||
+            !!opts.environmentId ||
+            !!opts.cmaToken ||
+            opts.yes ||
+            opts.dryRun ||
+            false;
+        if (process.stdout.isTTY && !isHeadless) {
+            const { render } = await import('ink');
+            const { createElement } = await import('react');
+            const { WizardApp } = await import('./tui/WizardApp.js');
+            const creds = await readExoCredentials();
+            const { waitUntilExit } = render(createElement(WizardApp, {
+                initialSpaceId: creds.spaceId,
+                initialEnvironmentId: creds.environmentId || 'master',
+                initialCmaToken: creds.cmaToken,
+                initialAgent: opts.agent !== 'claude' ? opts.agent : undefined,
+                initialProjectPath: opts.project !== '.' ? resolve(opts.project) : undefined,
+                host: opts.host,
+            }));
+            await waitUntilExit();
+            return;
+        }
+        const skipApply = opts.skipApply ?? false;
+        const spaceId = opts.spaceId ?? process.env['CONTENTFUL_SPACE_ID'];
+        const environmentId = opts.environmentId ?? process.env['CONTENTFUL_ENVIRONMENT_ID'];
+        const cmaToken = opts.cmaToken ?? process.env['CONTENTFUL_MANAGEMENT_TOKEN'];
+        if (!skipApply && (!spaceId || !environmentId || !cmaToken)) {
+            process.stderr.write('Error: --space-id (or CONTENTFUL_SPACE_ID), --environment-id (or CONTENTFUL_ENVIRONMENT_ID), and --cma-token (or CONTENTFUL_MANAGEMENT_TOKEN) are required unless --skip-apply is set.\n');
+            process.exit(1);
+            return;
+        }
+        const projectRoot = resolve(opts.project);
+        const outDir = opts.out ? resolve(opts.out) : join(projectRoot, '.contentful');
+        const result = await runPipeline({
+            project: projectRoot,
+            out: outDir,
+            spaceId,
+            environmentId,
+            cmaToken,
+            agent: opts.agent,
+            model: opts.model,
+            tokens: opts.tokens,
+            selectAll: opts.selectAll,
+            select: opts.select.length > 0 ? opts.select : undefined,
+            deselect: opts.deselect.length > 0 ? opts.deselect : undefined,
+            skipAnalyze: opts.skipAnalyze ?? false,
+            skipGenerate: opts.skipGenerate ?? false,
+            print: opts.print ?? false,
+            skipApply,
+            noCache: opts.cache === false,
+            yes: opts.yes ?? false,
+            verbose: opts.verbose ?? false,
+            viewports: opts.viewports,
+            host: opts.host,
+            dryRun: opts.dryRun,
+        }, (line) => process.stderr.write(line + '\n'));
+        const hasFailed = result.steps.some((s) => s.status === 'failed');
+        if (!process.stdout.isTTY) {
+            const json = JSON.stringify(result, null, 2) + '\n';
+            await new Promise((res) => process.stdout.write(json, () => res()));
+        }
+        process.exit(hasFailed ? 1 : 0);
+    });
+}

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

@@ -0,0 +1,37 @@
+export interface PipelineOptions {
+    project: string;
+    out: string;
+    spaceId?: string;
+    environmentId?: string;
+    cmaToken?: string;
+    agent: string;
+    model?: string;
+    skipAnalyze: boolean;
+    skipGenerate: boolean;
+    print: boolean;
+    skipApply: boolean;
+    noCache: boolean;
+    yes: boolean;
+    verbose: boolean;
+    tokens?: string;
+    viewports?: string;
+    host?: string;
+    dryRun?: boolean;
+    selectAll?: boolean;
+    select?: string[];
+    deselect?: string[];
+}
+export interface StepResult {
+    step: string;
+    status: 'complete' | 'failed' | 'skipped';
+    durationMs?: number;
+    reason?: string;
+    detail?: Record<string, unknown>;
+    error?: string;
+}
+export interface PipelineResult {
+    session: string;
+    project: string;
+    steps: StepResult[];
+}
+export declare function runPipeline(opts: PipelineOptions, progressWriter: (line: string) => void, cliPathOverride?: string): Promise<PipelineResult>;