@contentful/experience-design-system-generation 2.35.1-dev-build-45d6c918.0 → 2.36.0

package/dist/src/prompt-builder.d.ts

@@ -0,0 +1,81 @@
+import { type CDFComponentEntry } from '@contentful/experience-design-system-types';
+/** `components` — classify component props; `tokens` — classify design tokens; `select` — decide whether a component belongs in Contentful Experience Orchestration; `map-tokens` — suggest `$token.allowed` restrictions for design-category token props */
+export type Skill = 'components' | 'tokens' | 'select' | 'map-tokens';
+export type Mode = 'autonomous';
+/**
+ * A component name paired with the source file it was extracted from, for
+ * token-mapping evidence. `content` is the real file text (bounded, see
+ * MAX_COMPONENT_SOURCE_CHARS) — this pipeline is agent-fs-free by design (see
+ * generate-components.md's "you do not write any files"), so the caller must
+ * read the file itself and inline the text here rather than handing the
+ * agent a path and expecting it to open the file. `null` when the file
+ * couldn't be read (moved/deleted since extraction) — callers fall back to
+ * inferring from the prop name and $token.kind alone in that case.
+ * `siblingFiles` carries the content of files the source file relatively
+ * imports (e.g. a co-located `.styles.ts`) — token-resolution logic often
+ * lives one hop away from the component file itself. `truncatedSiblingCount`
+ * is set when the caller found more resolvable sibling files than it inlines
+ * (see MAX_SIBLING_FILES) — surfaced in the prompt so the classifier knows
+ * evidence was dropped rather than that the search came up empty.
+ */
+export interface ComponentSourceRef {
+    component: string;
+    sourcePath: string;
+    content: string | null;
+    siblingFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    truncatedSiblingCount?: number;
+    /**
+     * Properties with at least one use that fell outside the excerpt budget of
+     * the file it sits in. The reader cannot see that use, so its absence is a
+     * gap in the evidence, not evidence of absence.
+     */
+    usesNotShown?: string[];
+}
+/** Plain-data shape of the CDF generated so far — component name -> component entry. */
+export type GeneratedCdf = Record<string, CDFComponentEntry>;
+/**
+ * Render the warning banner shown when a custom skill prompt is active.
+ * Always cites the bundled invariants that the override bypasses so the
+ * operator cannot miss it.
+ */
+export declare function formatCustomPromptBanner(skill: 'components' | 'select', path: string): string;
+export interface PromptOptions {
+    skill: Skill;
+    mode: Mode;
+    rawComponentsInline?: string;
+    rawTokensInline?: string;
+    /** Original filename for raw tokens — used to set the correct code fence language. */
+    rawTokensFilename?: string;
+    tokensInline?: string;
+    tokenMapInline?: string;
+    outDir: string;
+    /** For components skill only: the single component's name (used in error messages). */
+    componentName?: string;
+    /** For map-tokens skill: the CDF generated so far. Filtered internally to design-category token-typed props only. */
+    generatedCdf?: GeneratedCdf;
+    /** For map-tokens skill: the full DTCG token tree. Flattened internally to a path+`$type` index, with `$value` stripped. */
+    tokenTree?: Record<string, unknown>;
+    /** Component source file references — consumption evidence for the components skill, explicit-restriction evidence (comments, allowlists) for map-tokens. */
+    componentSourceRefs?: ComponentSourceRef[];
+    /**
+     * Feature 8: custom prompt path override. When set, this absolute or relative
+     * `.md` path is read in place of the bundled skill file. The bundled-prompt
+     * invariants (utility-wrapper rejection, description content rules, etc.) do
+     * NOT apply under an override — callers are responsible for showing the
+     * appropriate warning banner.
+     */
+    skillPathOverride?: string;
+    /** Inline prompt instructions, taking precedence over the bundled skill or path override. */
+    skillContentOverride?: string;
+    /** JSON-serialized summary of existing space Components. Callers pre-project the shape per skill. */
+    existingComponentsInline?: string;
+    /** JSON-serialized summary of existing space DesignTokens. Callers pre-project the shape per skill. */
+    existingTokensInline?: string;
+    /** JSON-serialized hard allowlist for generated slot allowed-components references. */
+    componentAllowlistInline?: string;
+}
+export declare function buildPrompt(options: PromptOptions): Promise<string>;
+export declare function resolveSkillPath(skill: Skill): string;

package/dist/src/prompt-builder.js

@@ -0,0 +1,344 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { flattenDTCG } from '@contentful/experience-design-system-types';
+/**
+ * Render the warning banner shown when a custom skill prompt is active.
+ * Always cites the bundled invariants that the override bypasses so the
+ * operator cannot miss it.
+ */
+export function formatCustomPromptBanner(skill, path) {
+    return (`WARNING: Custom prompt active for ${skill}: ${path}\n` +
+        `  Bundled invariants (utility-wrapper rejection, description content rules) do NOT apply.\n` +
+        `  You are responsible for the prompt's correctness.\n`);
+}
+const SKILL_FILES = {
+    components: 'generate-components.md',
+    tokens: 'generate-tokens.md',
+    select: 'select-components.md',
+    'map-tokens': 'map-tokens.md',
+};
+export async function buildPrompt(options) {
+    const skillContent = options.skillContentOverride ?? (await readSkillFile(options.skill, options.skillPathOverride));
+    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, override) {
+    if (override) {
+        const skillPath = resolve(override);
+        try {
+            return await readFile(skillPath, 'utf8');
+        }
+        catch {
+            throw new Error(`custom prompt file not found (skill: ${skill}, path: ${skillPath})`);
+        }
+    }
+    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',
+        tsx: 'tsx',
+        jsx: 'jsx',
+        vue: 'vue',
+        svelte: 'svelte',
+        astro: 'astro',
+        scss: 'scss',
+        sass: 'scss',
+        css: 'css',
+        json: 'json',
+        json5: 'json',
+    };
+    return map[ext] ?? 'text';
+}
+/**
+ * Keeps only design-category, token-typed props per component (dropping
+ * components left with none), alongside the distinct `$token.kind` values
+ * seen among them and whether any such prop has no `$token.kind` at all —
+ * collected in the same pass rather than a second walk of the raw CDF.
+ */
+function filterDesignTokenProps(cdf) {
+    const result = {};
+    const kinds = new Set();
+    let hasUnscoped = false;
+    for (const [componentName, component] of Object.entries(cdf)) {
+        const properties = component.$properties;
+        if (!properties)
+            continue;
+        const filteredProps = {};
+        for (const [propName, prop] of Object.entries(properties)) {
+            if (prop.$type === 'token' && prop.$category === 'design') {
+                const { '$token.allowed': _tokenAllowed, ...rest } = prop;
+                filteredProps[propName] = rest;
+                const kind = prop['$token.kind'];
+                if (typeof kind === 'string' && kind.length > 0) {
+                    kinds.add(kind);
+                }
+                else {
+                    hasUnscoped = true;
+                }
+            }
+        }
+        if (Object.keys(filteredProps).length > 0) {
+            result[componentName] = { ...component, $properties: filteredProps };
+        }
+    }
+    return { filtered: result, kinds: [...kinds].sort(), hasUnscoped };
+}
+/** One line per candidate, e.g. `colors.brand.primary · color` — legible and countable, unlike nested JSON. */
+function formatTokenCandidateLines(entries) {
+    return entries.map((entry) => `${entry.path} · ${entry.$type}`).join('\n');
+}
+/** Renders one kind-scoped (or, for `kind: null`, full-tree) candidate section. Sections are cumulative, never merged, so each stays independently legible. */
+function renderTokenCandidateSection(kind, entries) {
+    const label = kind
+        ? `Token path index — ${kind} candidates only`
+        : 'Token path index — full tree (no $token.kind to scope by)';
+    return `${label}, one leaf token per line as \`path · type\`, no \`$value\`:\n${formatTokenCandidateLines(entries)}`;
+}
+function buildPreamble(options) {
+    const { skill, rawComponentsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, generatedCdf, tokenTree, componentSourceRefs, existingComponentsInline, existingTokensInline, componentAllowlistInline, } = options;
+    const sections = [];
+    if (existingComponentsInline) {
+        sections.push(`Existing components in the target Contentful space (JSON) — use for alignment, not as a hard filter:\n\`\`\`json\n${existingComponentsInline}\n\`\`\``);
+    }
+    if (existingTokensInline) {
+        sections.push(`Existing design tokens in the target Contentful space (JSON) — prefer binding to these paths over inventing new ones:\n\`\`\`json\n${existingTokensInline}\n\`\`\``);
+    }
+    if (componentAllowlistInline) {
+        sections.push(`Known component names for slot allowed_components (hard allowlist; never use any other name):\n\`\`\`json\n${componentAllowlistInline}\n\`\`\``);
+    }
+    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 filteredTokenProps = generatedCdf ? filterDesignTokenProps(generatedCdf) : undefined;
+    if (filteredTokenProps && Object.keys(filteredTokenProps.filtered).length > 0) {
+        sections.push(`Generated CDF so far — design-category token props only (JSON):\n\`\`\`json\n${JSON.stringify(filteredTokenProps.filtered)}\n\`\`\``);
+    }
+    if (tokenTree) {
+        const index = flattenDTCG(tokenTree, '').sort((a, b) => a.path.localeCompare(b.path));
+        if (index.length > 0) {
+            if (filteredTokenProps) {
+                const { kinds, hasUnscoped } = filteredTokenProps;
+                for (const kind of kinds) {
+                    const scoped = index.filter((entry) => entry.$type === kind);
+                    if (scoped.length > 0)
+                        sections.push(renderTokenCandidateSection(kind, scoped));
+                }
+                if (hasUnscoped)
+                    sections.push(renderTokenCandidateSection(null, index));
+            }
+            else {
+                sections.push(renderTokenCandidateSection(null, index));
+            }
+        }
+    }
+    if (componentSourceRefs && componentSourceRefs.length > 0) {
+        const withContent = componentSourceRefs.filter((ref) => ref.content != null);
+        const withoutContent = componentSourceRefs.filter((ref) => ref.content == null);
+        if (withContent.length > 0) {
+            const blocks = withContent.map((ref) => {
+                const mainBlock = `#### ${ref.component} (\`${ref.sourcePath}\`)\n\`\`\`${inferFenceLang(ref.sourcePath)}\n${ref.content}\n\`\`\``;
+                const siblingBlocks = (ref.siblingFiles ?? []).map((sibling) => `##### ${ref.component} — imported file \`${sibling.path}\`\n\`\`\`${inferFenceLang(sibling.path)}\n${sibling.content}\n\`\`\``);
+                const truncationNote = ref.truncatedSiblingCount && ref.truncatedSiblingCount > 0
+                    ? [
+                        `##### ${ref.component} — +${ref.truncatedSiblingCount} more imported file${ref.truncatedSiblingCount === 1 ? '' : 's'} not shown (evidence may be incomplete)`,
+                    ]
+                    : [];
+                const notShownNote = ref.usesNotShown && ref.usesNotShown.length > 0
+                    ? [
+                        `##### ${ref.component} — uses not shown: ${ref.usesNotShown.join(', ')}\n\nThe files above are excerpts, and each of these properties has at least one use that fell outside the excerpt budget. Treat their consumption as unknown, not absent: do not classify them \`token\` on what is shown, and do not conclude they are unread.`,
+                    ]
+                    : [];
+                return [mainBlock, ...siblingBlocks, ...truncationNote, ...notShownNote].join('\n\n');
+            });
+            sections.push(`### Component source references\n\n${blocks.join('\n\n')}`);
+        }
+        if (withoutContent.length > 0) {
+            const guidance = skill === 'components'
+                ? 'there is no consumption evidence for these, so `token` cannot be earned for any of their props — classify from the prop signature alone, and any prop that would otherwise be enum-versus-token is `enum` (or `string`)'
+                : 'there is no source evidence to narrow from — emit nothing for their props';
+            sections.push(`Component source unavailable for (JSON) — ${guidance}:\n\`\`\`json\n${JSON.stringify(withoutContent.map((ref) => ({ component: ref.component, sourcePath: ref.sourcePath })))}\n\`\`\``);
+        }
+    }
+    const inputBlock = sections.length > 0 ? `\n\n${sections.join('\n\n')}` : '';
+    if (skill === 'components') {
+        return buildComponentsAutonomousPreamble(inputBlock);
+    }
+    if (skill === 'select') {
+        return buildSelectAutonomousPreamble(inputBlock);
+    }
+    if (skill === 'map-tokens') {
+        return buildMapTokensAutonomousPreamble(inputBlock);
+    }
+    return buildTokensAutonomousPreamble(inputBlock);
+}
+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)
+
+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>","rationale":{"description":"<why this component is classified the way it is>","props":"<why these props were chosen>","slots":"<why these slots were chosen>"}}
+
+{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<short customer-facing description>","reason":"<full internal rationale; not customer-facing>","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>","rationale":"<why this slot was kept in the catalog>"}
+\`\`\`
+
+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 of the variant names the prop accepts).
+- For token type, always include \`token_kind\` (DTCG \$type, e.g. "color"). **Never emit \`values\` for \`cdf_type: "token"\` props** — an enum prop's list holds variant names; a token prop's list holds design token paths, produced separately and never by you. Emitting \`values\` on a token prop makes the definition invalid.
+- Never emit both "values" and "token_kind" on one prop.
+- \`enum\` vs \`token\` is decided by three questions answered in order from the source shown — never from the TypeScript type. Q1: does the component look the value up, switch on it, or have a vocabulary for it (\`tokens[x]\`, \`switch (variant)\`, \`allowedValues\`)? yes → \`enum\`, stop.
+- Q2: is the value written straight into a style or attribute (\`rx={radius}\`, \`padding: \${padding}\`)? no → not \`token\`, apply the type rules.
+- Q3: is there a design-token reference at that use — a \`tokens.*\` parameter default, a \`tokenReference\`, an inline \`tokens.*\` / \`var(--*)\`? yes → \`token\` (cite both lines in "reason"); no → \`string\`. "Ambiguity resolves to \`enum\`" applies only when Q1–Q3 cannot be answered from the source shown.
+- CSS design props (className, style, styles, positional/geometric props: top, bottom, left, right, rotation, offset, etc.) → classify_prop, cdf_type: "string", cdf_category: "design".
+- For \`classify_slot.allowed_components\`, use only exact names from the hard allowlist provided below. Never invent a child from an import, JSX element, type name, icon name, or implementation helper; if a child is not listed, omit it.
+- On classify_component, "rationale" fields are operator-facing (read-only) but may surface in customer-facing exports. The "rationale.description" field is subject to the description content rules in the skill prompt (no internal initiative names). "rationale.props" and "rationale.slots" describe your reasoning about scope; "classify_slot.rationale" explains why each slot was kept.
+- On classify_prop, "reason" is REQUIRED and is the LLM's internal rationale — shown to the developer reviewing the import, never to end-users. "description" is the customer-facing copy and is subject to the description content rules in the skill prompt. Keep them distinct: "description" is short and customer-facing; "reason" explains your reasoning in detail.
+- 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 components provided below and decide whether each belongs in Contentful Experience Orchestration as a Component Type. The input is a JSON array — you may receive 1–N components in a single message. Emit one tool call per input component, named after the component. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a brief "reason" to document your reasoning for each decision.
+
+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 JSON tool calls one per line to stdout. The CLI reads your stdout line by line.
+
+The two tool calls — emit exactly one per input component:
+
+\`\`\`
+{"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>"}
+
+{"tool":"reject_component","name":"<ComponentName>","reason":"<brief reason>"}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit exactly one tool call per input component. The "name" field must match a component name from the input array exactly. Tool calls may appear in any order.
+- You may emit prose lines (not starting with {) to reason before each tool call — they are ignored by the parser.`;
+}
+function buildMapTokensAutonomousPreamble(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: The components below already have design-category, token-typed props (\`$token.kind\` set). Your task is to decide, from source evidence, whether to narrow each one to a restricted subset (\`token_allowed\`) of the tokens matching its \`$token.kind\`. Apply all judgment calls yourself — do not pause to ask for confirmation.
+
+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 prop you narrow. The CLI reads your stdout line by line and writes each decision directly to the pipeline database.
+
+The one tool call you may emit:
+
+\`\`\`
+{"tool":"map_token_prop","component":"<ComponentName>","prop":"<propName>","token_allowed":["colors.brand.primary","colors.brand.secondary"]}
+\`\`\`
+
+Rules:
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences around the lines.
+- Only emit a call for a prop that appears in the "Generated CDF so far" section.
+- Each "Token path index" section below is already scoped to one \`$token.kind\` — a prop only draws candidates from the section matching its own \`$token.kind\` (or the "full tree" section, for a prop with no \`$token.kind\`). Never cross sections, never emit a group/prefix path, and never invent a path — every entry in \`token_allowed\` must exist verbatim in the matching section.
+- \`token_allowed\` is required and must be non-empty when the call is emitted.
+- For the judgment call of whether a prop should be narrowed at all, follow the decision tree in the map-tokens skill file: it explains defaults vs. restrictions, misclassified variant-name props, and when to emit nothing.
+- You may emit prose lines (not starting with \`{\`) anywhere — they are ignored by the parser and serve as your reasoning log.`;
+}
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-generation",
-  "version": "2.35.1-dev-build-45d6c918.0",
+  "version": "2.36.0",
   "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     "skills/"
   ],
   "dependencies": {
-    "@contentful/experience-design-system-types": "2.35.1-dev-build-45d6c918.0"
+    "@contentful/experience-design-system-types": "2.36.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",

package/dist/src/controller/create-generation-endpoint.d.ts

@@ -1,3 +0,0 @@
-import type { GenerationEndpoint, GenerationEndpointOptions, GenerationEndpointRequest, GenerationEndpointResponse } from '../types/contract.js';
-export type { GenerationEndpoint, GenerationEndpointOptions, GenerationEndpointRequest, GenerationEndpointResponse };
-export declare function createGenerationEndpoint(options?: GenerationEndpointOptions): GenerationEndpoint;

package/dist/src/controller/create-generation-endpoint.js

@@ -1,15 +0,0 @@
-import { validateGenerationRequest } from './helpers/validate-generation-request.js';
-import { executeGenerationOrchestrator } from '../orchestrator/execute-generation-orchestrator.js';
-import { createLocalCliAgentInvoker } from '../services/agent/local-cli-agent-invoker.js';
-export function createGenerationEndpoint(options = {}) {
-    const invoker = createLocalCliAgentInvoker({ onDebugEvent: options.onDebugEvent });
-    return {
-        async run(request) {
-            validateGenerationRequest(request);
-            return executeGenerationOrchestrator({ ...request, invoker });
-        },
-        checkAuth(agent) {
-            return invoker.checkAuth(agent);
-        },
-    };
-}

package/dist/src/controller/helpers/validate-generation-request.d.ts

@@ -1,2 +0,0 @@
-import type { GenerationEndpointRequest } from '../../types/contract.js';
-export declare function validateGenerationRequest(request: GenerationEndpointRequest): void;

package/dist/src/controller/helpers/validate-generation-request.js

@@ -1,18 +0,0 @@
-import { isAgentName } from '../../agent-names.js';
-export function validateGenerationRequest(request) {
-    if (request === null || typeof request !== 'object') {
-        throw new TypeError('createGenerationEndpoint requires a request object');
-    }
-    if (!isAgentName(request.agent)) {
-        throw new TypeError(`createGenerationEndpoint requires agent to be a valid agent name, got: ${String(request.agent)}`);
-    }
-    if (typeof request.timeoutMs !== 'number' || request.timeoutMs <= 0) {
-        throw new TypeError('createGenerationEndpoint requires timeoutMs to be a positive number');
-    }
-    if (request.promptOptions === null || typeof request.promptOptions !== 'object') {
-        throw new TypeError('createGenerationEndpoint requires promptOptions to be an object');
-    }
-    if (request.onOutput !== undefined && typeof request.onOutput !== 'function') {
-        throw new TypeError('createGenerationEndpoint requires onOutput to be a function when provided');
-    }
-}

package/dist/src/orchestrator/execute-generation-orchestrator.d.ts

@@ -1,6 +0,0 @@
-import type { GenerationEndpointRequest, GenerationEndpointResponse } from '../types/contract.js';
-import type { AgentInvoker } from '../services/agent/local-cli-agent-invoker.js';
-export interface GenerationOrchestratorRequest extends GenerationEndpointRequest {
-    readonly invoker: AgentInvoker;
-}
-export declare function executeGenerationOrchestrator(request: GenerationOrchestratorRequest): Promise<GenerationEndpointResponse>;

package/dist/src/orchestrator/execute-generation-orchestrator.js

@@ -1,12 +0,0 @@
-import { buildPrompt } from '../services/prompts/build-prompt.js';
-export async function executeGenerationOrchestrator(request) {
-    const prompt = await buildPrompt(request.promptOptions);
-    return request.invoker.invoke({
-        agent: request.agent,
-        model: request.model,
-        bedrock: request.bedrock,
-        prompt,
-        timeoutMs: request.timeoutMs,
-        onOutput: request.onOutput,
-    });
-}

package/dist/src/services/agent/helpers/build-agent-args.d.ts

@@ -1,6 +0,0 @@
-import type { AgentName } from '../../../agent-names.js';
-/** Per-agent env vars that switch model calls to AWS Bedrock. */
-export declare const BEDROCK_ENV_BY_AGENT: Partial<Record<AgentName, Record<string, string>>>;
-export declare function agentSupportsBedrock(agent: AgentName): boolean;
-export declare function resolveAgentModel(agent: AgentName, explicit?: string, bedrock?: boolean): string | undefined;
-export declare function buildAgentArgs(agent: AgentName, prompt: string, model?: string, promptViaStdin?: boolean, bedrock?: boolean): string[];

package/dist/src/services/agent/helpers/build-agent-args.js

@@ -1,58 +0,0 @@
-/** Per-agent env vars that switch model calls to AWS Bedrock. */
-export const BEDROCK_ENV_BY_AGENT = {
-    claude: { CLAUDE_CODE_USE_BEDROCK: '1' },
-};
-const BEDROCK_CAPABLE_AGENTS = new Set(['claude', 'codex', 'opencode']);
-export function agentSupportsBedrock(agent) {
-    return BEDROCK_CAPABLE_AGENTS.has(agent);
-}
-const DEFAULT_CODEX_BEDROCK_REGION = 'us-east-1';
-const DEFAULT_OPENCODE_MODEL = 'claude-haiku-4-5';
-const DEFAULT_CODEX_BEDROCK_MODEL = 'openai.gpt-5.6-luna';
-const DEFAULT_MODELS = {
-    claude: 'haiku',
-    opencode: DEFAULT_OPENCODE_MODEL,
-    cursor: 'gpt-mini',
-    copilot: 'Auto',
-};
-function withBedrockProviderPrefix(model) {
-    return model.includes('/') ? model : `amazon-bedrock/${model}`;
-}
-export function resolveAgentModel(agent, explicit, bedrock = false) {
-    if (explicit && explicit.trim())
-        return explicit.trim();
-    const override = process.env[`EDS_AGENT_MODEL_${agent.toUpperCase()}`];
-    if (override && override.trim())
-        return override.trim();
-    if (bedrock && agent === 'codex')
-        return DEFAULT_CODEX_BEDROCK_MODEL;
-    if (bedrock && agent === 'opencode')
-        return withBedrockProviderPrefix(DEFAULT_OPENCODE_MODEL);
-    return DEFAULT_MODELS[agent];
-}
-function codexBedrockConfigArgs() {
-    const region = process.env.AWS_REGION?.trim() || process.env.AWS_DEFAULT_REGION?.trim() || DEFAULT_CODEX_BEDROCK_REGION;
-    return ['-c', 'model_provider=amazon-bedrock', '-c', `model_providers.amazon-bedrock.region=${region}`];
-}
-export function buildAgentArgs(agent, prompt, model, promptViaStdin = false, bedrock = false) {
-    const resolvedModel = resolveAgentModel(agent, model, bedrock);
-    const modelArg = resolvedModel ? ['--model', resolvedModel] : [];
-    const promptArg = promptViaStdin ? [] : [prompt];
-    switch (agent) {
-        case 'claude':
-            return ['--print', ...modelArg, ...promptArg];
-        case 'codex': {
-            const bedrockArgs = bedrock ? codexBedrockConfigArgs() : [];
-            return ['exec', ...bedrockArgs, ...modelArg, '--dangerously-bypass-approvals-and-sandbox', ...promptArg];
-        }
-        case 'opencode':
-            return ['run', ...modelArg, ...promptArg];
-        case 'cursor':
-            return ['--print', ...modelArg, ...promptArg];
-        case 'copilot': {
-            const copilotModel = resolveAgentModel('copilot', model);
-            const copilotModelArg = !copilotModel || copilotModel === 'Auto' ? [] : ['--model', copilotModel];
-            return ['-p', ...promptArg, ...copilotModelArg, '--allow-all-tools'];
-        }
-    }
-}

package/dist/src/services/agent/helpers/check-agent-auth.d.ts

@@ -1,3 +0,0 @@
-import type { AgentName } from '../../../agent-names.js';
-import type { AgentAuthStatus } from '../../../types/agent.js';
-export declare function checkAgentAuth(agent: AgentName): Promise<AgentAuthStatus>;

package/dist/src/services/agent/helpers/check-agent-auth.js

@@ -1,19 +0,0 @@
-import { spawn } from 'node:child_process';
-import { resolveAgentBinary } from './resolve-agent-binary.js';
-import { checkClaudeAuth } from './check-claude-auth.js';
-export async function checkAgentAuth(agent) {
-    const binary = resolveAgentBinary(agent);
-    const binaryExists = await new Promise((resolve) => {
-        if (binary.startsWith('/')) {
-            import('node:fs/promises').then((fs) => fs.access(binary).then(() => resolve(true), () => resolve(false)));
-            return;
-        }
-        const child = spawn(process.platform === 'win32' ? 'where' : 'which', [binary], { stdio: 'ignore' });
-        child.on('close', (code) => resolve(code === 0));
-    });
-    if (!binaryExists)
-        return 'not-found';
-    if (agent !== 'claude')
-        return 'ok';
-    return checkClaudeAuth(binary);
-}

package/dist/src/services/agent/helpers/check-claude-auth.d.ts

@@ -1,2 +0,0 @@
-import type { AgentAuthStatus } from '../../../types/agent.js';
-export declare function checkClaudeAuth(binary: string): Promise<AgentAuthStatus>;

package/dist/src/services/agent/helpers/check-claude-auth.js

@@ -1,37 +0,0 @@
-import { spawn } from 'node:child_process';
-export function checkClaudeAuth(binary) {
-    return new Promise((resolve) => {
-        const child = spawn(binary, ['auth', 'status', '--json'], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        let stdout = '';
-        let done = false;
-        const timer = setTimeout(() => {
-            if (!done) {
-                done = true;
-                child.kill('SIGTERM');
-                resolve('unauthenticated');
-            }
-        }, 5000);
-        child.stdout?.on('data', (chunk) => {
-            stdout += chunk.toString();
-        });
-        child.on('close', (code) => {
-            if (done)
-                return;
-            done = true;
-            clearTimeout(timer);
-            if (code !== 0) {
-                resolve('unauthenticated');
-                return;
-            }
-            try {
-                const status = JSON.parse(stdout);
-                resolve(status.loggedIn ? 'ok' : 'unauthenticated');
-            }
-            catch {
-                resolve('unauthenticated');
-            }
-        });
-    });
-}

package/dist/src/services/agent/helpers/describe-agent-failure.d.ts

@@ -1,2 +0,0 @@
-import type { AgentRunResult } from '../../../types/agent.js';
-export declare function describeAgentFailure(result: AgentRunResult, maxDetail?: number): string;