@contentful/experience-design-system-cli 2.14.2 → 2.15.0

package/README.md

@@ -34,6 +34,46 @@ All intermediate data flows through a local SQLite session database (`~/.content
 
 ---
 
+## Composite components & composition
+
+A **composite component** is one that renders other components inside it — a `Card` that slots a `Button` and an `Icon`, a `Tabs` that slots `Tab` panels. When you import composite components, the CLI can populate each slot's `$allowedComponents` so the parent→child relationships survive into Contentful.
+
+### Atomic vs. composite
+
+Imports are **atomic by default** — flat components, no embedded hierarchy. This is the right choice when you just want each component registered on its own. Opt into hierarchy resolution with `--composite` (or any composition flag, which implies it).
+
+| Mode | Flag | Behavior |
+|---|---|---|
+| Atomic | `--atomic` (default) | Flat import; composition stripped before push |
+| Composite | `--composite` | Resolve and import the parent→child hierarchy |
+
+### How composition is resolved
+
+Under `--composite`, relationships are resolved from the highest-confidence source available, in this precedence order:
+
+1. **Typed slots (code)** — slots the source already declares, e.g. React `ReactElement<XProps>` / `children`, Svelte `Snippet<[XProps]>`, or an explicit `@allowedComponents` JSDoc tag. Fully deterministic; picked up automatically.
+2. **Mapping map** — a hand-authored parent→children interchange map you feed with `--composition-map <path>`. Use `--generate-map <path>` to emit a skeleton from whatever was resolved, then hand-edit it and feed it back.
+3. **Agent (`--composition-agent`)** — for codebases that encode composition in *code patterns* rather than typed slots (common in real-world design systems). Only runs when the deterministic sources above find nothing.
+
+When more than one source speaks to the same relationship, the higher-precedence one wins (**code slots > map > agent**).
+
+### The composition agent
+
+`--composition-agent` doesn't ask the model to *list* relationships (which would be non-deterministic and unauditable). Instead the agent **writes a small parser** — a pure `(ctx) => Edge[]` function — which the CLI runs in a locked-down sandbox (separate process, no filesystem/network, memory + wall-clock limits), caches by the parser's own source, and replays. Repeated runs over the same code are stable and inspectable.
+
+- `--composition-agent-mode <parser|edges>` — `parser` (default; the sandboxed-parser design above) or `edges` (agent lists relationships directly; less robust).
+- `--composition-refresh` — ignore the cache and re-resolve from scratch, forcing the agent to run.
+- `--agent <name>` — which coding agent authors the parser (`claude`, `codex`, `opencode`, `cursor`).
+- `--prompt composition=<file-or-text>` — override the composition stage's prompt.
+
+Because the agent path spawns a coding agent, it adds latency and cost and is best-effort (parser quality can vary run to run). For reproducible results, prefer `--composition-map`.
+
+### Slot cycles
+
+If the resolved graph contains a circular slot dependency (A slots B, B slots A), it is detected before push. `apply push` and the wizard's push path **refuse to send a manifest with cycles**; the cycle path is reported so you can break it. In headless `import`, pass `--auto-reject-cycles` to auto-reject the components in a cycle and retry instead of failing.
+
+---
+
 ## Prerequisites
 
 ### Coding agent
@@ -80,7 +120,8 @@ experiences import [flags]
 ```
 welcome
   ↓
-extracting             — runs analyze extract; spawns generate in parallel (prefetch)
+extracting             — runs analyze extract (atomic by default; resolves composition
+                         under --composite, see below); spawns generate in parallel (prefetch)
   ↓
 [auto-filter]          — analyze select-agent runs automatically (skip with --no-auto-filter)
   ↓
@@ -139,6 +180,15 @@ Pass `--select-prompt-path <path>` and/or `--generate-prompt-path <path>` to swa
 | `--model <name>`                  | agent default                          | Model name                                                                                                   |
 | `--tokens <path>`                 | —                                      | DTCG `tokens.json` to push alongside generated components                                                    |
 | `--auto-accept-scope`             | off                                    | Accept all extracted components without prompting (required for non-TTY without other headless flags)        |
+| `--atomic`                        | **default**                            | Flat import, no embedded-component hierarchy (composition stripped on push)                                   |
+| `--composite`                     | —                                      | Import the embedded-component hierarchy (any composition flag implies this)                                   |
+| `--composition-map <path>`        | —                                      | Consume a hand-authored parent→children interchange map (implies `--composite`)                              |
+| `--generate-map <path>`           | —                                      | Also write a composition-map skeleton from the resolved composition (implies `--composite`)                  |
+| `--composition-agent`             | —                                      | Opt into agentic resolution when deterministic sources find no groups (implies `--composite`)                |
+| `--composition-refresh`           | —                                      | Bypass the composition cache and re-resolve from scratch, forcing the agent to run (implies `--composite`)   |
+| `--composition-agent-mode <mode>` | `parser`                               | `parser` (agent writes a sandboxed parser) or `edges` (agent lists edges directly)                           |
+| `--prompt <stage=value>`          | —                                      | Override a stage prompt (repeatable); value is a file path or literal text, e.g. `--prompt composition=./p.md` |
+| `--auto-reject-cycles`            | off (fail loud)                        | Auto-reject components in slot cycles and retry, instead of stopping with the cycle path                     |
 | `--auto-filter` / `--no-auto-filter` | persisted in `credentials.json`     | Force AI auto-filter on or off; overrides saved preference                                                   |
 | `--no-live-preview`               | live preview on                        | Skip the automatic preview re-run after each FieldEditor save                                                |
 | `--no-push`                       | push on                                | Run extract → scope-gate → generate → final-review and exit without pushing                                  |
@@ -224,13 +274,23 @@ The standalone subcommands below are pinned by snapshot test (`test/analyze/sele
 Extract component definitions from a project source tree.
 
 ```bash
-experiences analyze extract --project <path> [--dir <src-dir>]
+experiences analyze extract --project <path> [--dir <src-dir>] [composition flags]
 ```
 
 | Option | Default | Description |
 |---|---|---|
 | `--project <path>` | _(required)_ | Path to the project root |
 | `--dir <path>` | `src` (falls back to project root) | Source directory relative to project root |
+| `--resolve-unreachable <mode>` | `auto` | Retry pass for unresolved Svelte `Props` types: `auto`, `always`, or `never` |
+| `--atomic` | **default** | Skip composition resolution — flat components only |
+| `--composite` | — | Resolve embedded-component composition (any composition flag implies this) |
+| `--composition-map <path>` | — | Consume a hand-authored parent→children interchange map (implies `--composite`) |
+| `--generate-map <path>` | — | Write a skeleton interchange map from the resolved composition (implies `--composite`) |
+| `--composition-agent` | — | Opt into agentic resolution when deterministic sources find no groups (implies `--composite`) |
+| `--composition-refresh` | — | Bypass the composition cache and re-resolve from scratch, forcing the agent to run (implies `--composite`) |
+| `--composition-agent-mode <mode>` | `parser` | `parser` (agent writes a sandboxed parser — deterministic) or `edges` (agent lists edges directly) |
+| `--agent <name>` | saved by setup | Coding agent for composition resolution: `claude`, `codex`, `opencode`, `cursor` |
+| `--prompt <stage=value>` | — | Override a stage prompt (repeatable); value is a file path or literal text, e.g. `--prompt composition=./p.md` |
 
 Scans `.tsx`, `.ts`, `.jsx`, `.js`, `.vue`, and `.astro` files. Ignores `node_modules`, `dist`, `build`, `.next`, `.nuxt`, `coverage`, `storybook-static`, `out`, `demo(s)`, and `example(s)` directories. Also ignores `*.stories.*`, `*.story.*`, `*.spec.*`, and `*.test.*` files.
 
@@ -238,6 +298,8 @@ Writes extracted components to the session database and prints `session=<id>` to
 
 The deterministic non-authorable filter drops infrastructure components with no authoring surface (Context providers, refs-only wrappers, etc.); each drop is reported as a warning so the operator can audit.
 
+Extraction is **atomic by default** — flat components, no embedded hierarchy. See [Composite components & composition](#composite-components--composition) for how `--composite` and the composition flags resolve parent→child relationships.
+
 ---
 
 ### `analyze select`

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,8 @@
   "files": [
     "bin/",
     "dist/",
-    "skills/"
+    "skills/",
+    "prompts/"
   ],
   "scripts": {
     "build": "nx build experience-design-system-cli && BINDIR=$(dirname $(which node)) && for cmd in exo experiences experience-design-system-cli; do ln -sf \"$(pwd)/bin/cli.js\" \"$BINDIR/$cmd\"; done",

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

@@ -1,3 +1,14 @@
 import type { Command } from 'commander';
+import type { InterchangeMap } from './composition/interchange-schema.js';
+import type { RawSlotDefinition } from '../types.js';
 export declare function collectSourceFiles(directory: string, onProgress?: (scannedCount: number) => void): Promise<string[]>;
+/**
+ * Build a { version, groups } interchange skeleton (spec T1) from the resolved
+ * components' slot allowedComponents — reflecting BOTH typed-slot edges the
+ * extractor found and anything the mapping resolver added.
+ */
+export declare function componentsToInterchangeMap(components: Array<{
+    name: string;
+    slots: RawSlotDefinition[];
+}>): InterchangeMap;
 export declare function registerAnalyzeCommand(program: Command): void;

package/dist/src/analyze/command.js

@@ -1,12 +1,25 @@
 import { createElement } from 'react';
 import { render } from 'ink';
-import { mkdir, readdir, stat } from 'node:fs/promises';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { extractComponents, preClassifyComponent, isNonAuthorableComponent, computeExtractionScore, deriveNeedsReview, describeReviewReasons, inspectComponentSource, validateExtractedComponents, } from '@contentful/experience-design-system-extraction';
 import { AnalyzeView } from './tui/AnalyzeView.js';
 import { registerAnalyzeEditCommand } from './select/command.js';
 import { registerAnalyzeSelectAgentCommand } from './select-agent/command.js';
-import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, } from '../session/db.js';
+import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, storeSlotCycles, getCliCacheVersion, lookupCompositionCache, storeCompositionCache, } from '../session/db.js';
+import { findSlotCycles, suggestCycleBreakEdge } from './cycle-detection.js';
+import { resolveCompositionMode } from '../lib/composition-mode.js';
+import { resolveMapping } from './composition/resolve-mapping.js';
+import { loadUserMap, resolveCompositionSources } from './composition/resolve-mapping-cli.js';
+import { selectCandidateFiles, capCandidatesToPromptBudget } from './composition/candidate-files.js';
+import { critiqueCandidates } from './composition/candidate-critic.js';
+import { buildDirCriticPrompt, parseDirCriticReply } from './composition/candidate-critic-agent.js';
+import { buildCompositionInputHash } from './composition/composition-cache-key.js';
+import { runParserInSandbox } from './composition/agent-parser/sandbox.js';
+import { resolveViaAgentParser } from './composition/agent-parser/resolve-via-parser.js';
+import { parsePromptOverrides, resolvePromptOverride } from '../lib/prompt-overrides.js';
+import { runAgent } from '../generate/agent-runner.js';
+import { readExperiencesCredentials } from '../credentials-store.js';
 import { buildAnalyzeViewRows, partitionGlobalWarnings } from './build-analyze-view-rows.js';
 const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.svelte', '.ts', '.tsx', '.vue']);
 const IGNORED_DIRECTORY_NAMES = new Set([
@@ -85,6 +98,69 @@ export async function collectSourceFiles(directory, onProgress) {
     await visit(directory);
     return files.sort();
 }
+/** Read the persisted default composition mode; missing config is fine. */
+async function safeReadCompositionMode() {
+    try {
+        return (await readExperiencesCredentials()).compositionMode;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a { version, groups } interchange skeleton (spec T1) from the resolved
+ * components' slot allowedComponents — reflecting BOTH typed-slot edges the
+ * extractor found and anything the mapping resolver added.
+ */
+export function componentsToInterchangeMap(components) {
+    const groups = {};
+    for (const c of components) {
+        const children = new Set();
+        for (const slot of c.slots) {
+            for (const child of slot.allowedComponents ?? [])
+                children.add(child);
+        }
+        if (children.size > 0)
+            groups[c.name] = [...children].sort();
+    }
+    const sorted = {};
+    for (const parent of Object.keys(groups).sort())
+        sorted[parent] = groups[parent];
+    return { version: 1, groups: sorted };
+}
+/** Resolve which coding-agent runs mapping resolution: `--agent` flag > env > default. */
+function resolveCompositionAgentName(flagValue) {
+    const valid = ['claude', 'codex', 'opencode', 'cursor'];
+    if (flagValue && valid.includes(flagValue))
+        return flagValue;
+    const env = process.env['EDS_COMPOSITION_AGENT'];
+    if (env && valid.includes(env))
+        return env;
+    return 'claude';
+}
+/**
+ * Read the source files of the extracted components plus nearby mapping/meta
+ * files, so the candidate pre-filter (T3) can pick the relevant ones. Reads
+ * each unique `sourcePath` once; missing files are skipped.
+ */
+async function readCandidateFiles(components, extraFiles = []) {
+    const paths = new Set(extraFiles);
+    for (const c of components) {
+        if (c.sourcePath)
+            paths.add(c.sourcePath);
+    }
+    const out = [];
+    await Promise.all([...paths].map(async (p) => {
+        try {
+            const content = await readFile(p, 'utf8');
+            out.push({ path: p, content });
+        }
+        catch {
+            void 0;
+        }
+    }));
+    return out;
+}
 export function registerAnalyzeCommand(program) {
     const analyze = program
         .command('analyze')
@@ -95,6 +171,15 @@ export function registerAnalyzeCommand(program) {
         .requiredOption('--project <path>', 'Path to the project root')
         .option('--dir <path>', 'Path to the component source directory relative to the project root')
         .option('--resolve-unreachable <mode>', "Retry pass for unresolved Svelte Props types: 'auto' (default), 'always', or 'never'", 'auto')
+        .option('--composite', 'Resolve embedded-component composition (opt in; default is atomic)')
+        .option('--atomic', 'Skip composition resolution — flat components only (default)')
+        .option('--composition-map <path>', 'Consume a hand-authored parent→children interchange map (implies --composite)')
+        .option('--composition-agent', 'Opt into agentic mapping resolution when deterministic sources find no groups (implies --composite)')
+        .option('--composition-refresh', 'Force the mapping agent to run even where deterministic sources answered (implies --composite)')
+        .option('--generate-map <path>', 'Write a skeleton interchange map from resolved composition (implies --composite)')
+        .option('--prompt <stage=value>', 'Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md', (v, acc) => [...acc, v], [])
+        .option('--agent <name>', 'Coding agent for composition mapping resolution (claude|codex|opencode|cursor)')
+        .option('--composition-agent-mode <mode>', "Agent resolution mode: 'parser' (agent writes a sandboxed parser — deterministic, default) or 'edges' (agent lists edges directly)", 'parser')
         .action(async (opts) => {
         const resolveUnreachable = (() => {
             const v = opts.resolveUnreachable ?? 'auto';
@@ -184,8 +269,218 @@ export function registerAnalyzeCommand(program) {
                     (component.needsReview ?? false),
             });
         }
-        const validatedComponents = validateExtractedComponents(filteredComponents);
+        let validatedComponents = validateExtractedComponents(filteredComponents);
+        // Composition mapping resolution (spec U2). Only in composite mode and
+        // only when a source is provided (user map / agent opt-in).
+        // Atomic (default) never resolves — it would only be stripped later.
+        const compositionMode = resolveCompositionMode(opts, (await safeReadCompositionMode()) ?? undefined);
+        if (compositionMode === 'composite') {
+            const sources = resolveCompositionSources(opts);
+            const { overrides: promptOverrides, errors: promptErrors } = parsePromptOverrides(opts.prompt ?? []);
+            for (const err of promptErrors) {
+                process.stderr.write(`Error: ${err}\n`);
+                process.exit(1);
+            }
+            let compositionPrompt;
+            const compositionOverride = promptOverrides.get('composition');
+            if (compositionOverride) {
+                try {
+                    compositionPrompt = await resolvePromptOverride(compositionOverride);
+                }
+                catch (e) {
+                    process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+                    process.exit(1);
+                }
+            }
+            let userMap;
+            if (opts.compositionMap) {
+                const loaded = await loadUserMap(opts.compositionMap);
+                if (!loaded.ok) {
+                    process.stderr.write(`Error: ${loaded.error}\n`);
+                    process.exit(1);
+                }
+                userMap = loaded.map;
+            }
+            const hasSource = !!userMap || sources.useAgent || sources.forceAgent;
+            if (hasSource || opts.generateMap) {
+                // Composition progress mirrors the scan/extract progress convention:
+                // emit `progress=composition:<phase>` on stderr so the wizard can
+                // render a second progress line during the (potentially slow, agent-
+                // backed) resolution instead of appearing frozen.
+                const emitCompositionProgress = (phase) => {
+                    if (!process.stdout.isTTY)
+                        process.stderr.write(`progress=composition:${phase}\n`);
+                };
+                emitCompositionProgress('resolving');
+                const allFiles = await readCandidateFiles(validatedComponents, sourceFiles);
+                // Decouple the two file sets (design: candidate-heuristic fragility):
+                //  - `promptFiles`: a bounded candidate SAMPLE inlined into the agent
+                //    prompt so it sees the convention without ingesting the whole repo.
+                //  - `allFiles`: EVERY scanned file, handed to the authored parser at
+                //    runtime. The parser is deterministic code — give it everything so
+                //    a candidate-filter miss can never starve it of a definition file.
+                const selectedCandidates = selectCandidateFiles(allFiles).map((c) => ({ path: c.path, content: c.content }));
+                // Cap the inlined set so a large design system can't overflow the
+                // agent's context window and fail resolution outright (see the budget
+                // constant). The runtime parser still sees EVERY file.
+                const capped = capCandidatesToPromptBudget(selectedCandidates);
+                let promptFiles = capped.kept;
+                if (capped.dropped.length > 0) {
+                    process.stderr.write(`Warning: composition — ${capped.dropped.length} candidate file(s) omitted from the agent prompt to fit the context budget; resolution runs on the ${promptFiles.length} highest-value files.\n`);
+                }
+                const runtimeFiles = allFiles.map((c) => ({ path: c.path, content: c.content }));
+                const resolverAgent = resolveCompositionAgentName(opts.agent);
+                const parserMode = (opts.compositionAgentMode ?? 'parser') !== 'edges';
+                const componentNameSet = new Set(validatedComponents.map((c) => c.name));
+                const cacheVersion = await getCliCacheVersion();
+                // Tracks the exit code of the most recent spawnAgent call so the
+                // caching sites can refuse to persist a failed run (a non-zero exit —
+                // e.g. a context-window overflow — otherwise poisons the cache and
+                // replays the error on every subsequent run).
+                let lastAgentExitCode = 0;
+                const spawnAgent = async (prompt) => {
+                    const res = await runAgent({
+                        agent: resolverAgent,
+                        prompt,
+                        interactive: false,
+                        timeoutMs: 120_000,
+                        promptViaStdin: true,
+                    });
+                    lastAgentExitCode = res.exitCode;
+                    if (res.exitCode !== 0 && res.stderr.trim()) {
+                        process.stderr.write(`Warning: composition — agent exited ${res.exitCode}: ${res.stderr.trim()}\n`);
+                    }
+                    return res.stdout;
+                };
+                // Completeness critic: let the agent flag composition-relevant dirs
+                // the keyword filter missed (by path/name alone — cheap). It can only
+                // ADD to the prompt sample. Runs ONLY on a genuine authoring pass (see
+                // the cache-miss branch below) so a parser cache hit pays nothing.
+                const runCandidateCritic = async () => {
+                    const critic = await critiqueCandidates(runtimeFiles, promptFiles, async (dirs) => parseDirCriticReply(await spawnAgent(buildDirCriticPrompt(dirs)), dirs));
+                    if (critic.addedDirs.length > 0) {
+                        promptFiles = critic.files;
+                        if (process.env['EDS_DEBUG']) {
+                            process.stderr.write(`[composition-debug] critic added dirs: ${critic.addedDirs.join(', ')}\n`);
+                        }
+                    }
+                };
+                // Agent-authored parser path (default): the agent writes a sandboxed
+                // (ctx) => Edge[] parser we run deterministically, cached by parser
+                // SOURCE. Falls back to direct edge-emission if authoring fails.
+                let parserEdges;
+                if (sources.useAgent && parserMode) {
+                    const parserCacheKey = buildCompositionInputHash({
+                        files: runtimeFiles,
+                        agent: resolverAgent,
+                        kind: 'parser',
+                    });
+                    const cachedSource = opts.compositionRefresh
+                        ? null
+                        : lookupCompositionCache(db, parserCacheKey, cacheVersion);
+                    if (cachedSource !== null) {
+                        emitCompositionProgress('cache-hit');
+                        const ran = await runParserInSandbox(cachedSource, {
+                            files: runtimeFiles,
+                            componentNames: [...componentNameSet],
+                        });
+                        if (!ran.error) {
+                            parserEdges = ran.edges.filter((e) => e.parent !== e.child && componentNameSet.has(e.parent) && componentNameSet.has(e.child));
+                        }
+                    }
+                    if (parserEdges === undefined) {
+                        await runCandidateCritic();
+                        const pr = await resolveViaAgentParser({
+                            files: promptFiles,
+                            runtimeFiles,
+                            componentNames: componentNameSet,
+                            runAgentFn: ({ prompt }) => spawnAgent(prompt),
+                            ...(compositionPrompt ? { instructionOverride: compositionPrompt } : {}),
+                            onPhase: (phase) => emitCompositionProgress(phase),
+                            // The candidate filter selected these files because they carry
+                            // composition markers, so a clean 0-edge parse is suspicious —
+                            // let the resolver spend its one repair round on it.
+                            retryOnEmpty: promptFiles.length > 0,
+                        });
+                        for (const w of pr.warnings)
+                            process.stderr.write(`Warning: composition — ${w}\n`);
+                        if (!pr.usedFallback) {
+                            parserEdges = pr.edges;
+                            if (pr.parserSource && lastAgentExitCode === 0) {
+                                storeCompositionCache(db, parserCacheKey, cacheVersion, pr.parserSource);
+                            }
+                        }
+                        else {
+                            process.stderr.write('Warning: composition — parser mode failed; falling back to edge emission\n');
+                        }
+                    }
+                }
+                if (process.env['EDS_DEBUG'] && parserEdges) {
+                    process.stderr.write(`[composition-debug] prompt files: ${promptFiles.length}; runtime files: ${runtimeFiles.length}; componentNames: ${componentNameSet.size}; parser edges: ${parserEdges.length}\n`);
+                    for (const e of parserEdges)
+                        process.stderr.write(`[composition-debug]   edge ${e.parent} -> ${e.child}\n`);
+                }
+                // Edge-emission cache (used for both explicit edges-mode and the
+                // parser-mode fallback). Keyed on prompt files + agent identity — the
+                // agent emits edges directly from what it reads in the prompt.
+                const agentCacheKey = buildCompositionInputHash({
+                    files: promptFiles,
+                    agent: resolverAgent,
+                    kind: 'edges',
+                });
+                const useEdgeEmission = sources.useAgent && parserEdges === undefined;
+                const result = await resolveMapping({
+                    components: validatedComponents,
+                    ...(userMap ? { userMap } : {}),
+                    ...(parserEdges ? { extraEdges: parserEdges } : {}),
+                    useAgent: useEdgeEmission,
+                    forceAgent: sources.forceAgent && useEdgeEmission,
+                    files: promptFiles,
+                    ...(compositionPrompt ? { promptOverride: compositionPrompt } : {}),
+                    runAgentFn: async ({ prompt }) => {
+                        if (!opts.compositionRefresh) {
+                            const cached = lookupCompositionCache(db, agentCacheKey, cacheVersion);
+                            if (cached !== null) {
+                                emitCompositionProgress('cache-hit');
+                                return cached;
+                            }
+                        }
+                        emitCompositionProgress(`agent:${resolverAgent}`);
+                        const stdout = await spawnAgent(prompt);
+                        if (lastAgentExitCode === 0) {
+                            storeCompositionCache(db, agentCacheKey, cacheVersion, stdout);
+                        }
+                        return stdout;
+                    },
+                });
+                emitCompositionProgress('done');
+                for (const w of result.warnings)
+                    process.stderr.write(`Warning: composition — ${w}\n`);
+                for (const c of result.conflicts) {
+                    process.stderr.write(`Warning: composition conflict on ${c.parent}→${c.child}: kept ${c.winner}, dropped ${c.loser}\n`);
+                }
+                validatedComponents = result.components;
+                if (opts.generateMap) {
+                    // Reflect the FULL resolved composition — typed-slot edges already
+                    // on the extracted components PLUS anything the resolver added — not
+                    // just the resolver's own contributed edges.
+                    const skeleton = componentsToInterchangeMap(validatedComponents);
+                    await writeFile(opts.generateMap, JSON.stringify(skeleton, null, 2) + '\n');
+                    process.stderr.write(`Wrote composition map skeleton to ${opts.generateMap}\n`);
+                }
+            }
+        }
         storeRawComponents(db, sessionId, validatedComponents);
+        const cycleInput = validatedComponents.map((c) => ({
+            name: c.name,
+            slots: c.slots.map((s) => ({ name: s.name, allowedComponents: s.allowedComponents })),
+        }));
+        const cycles = findSlotCycles(cycleInput);
+        const withBreaks = cycles.map((cycle) => ({
+            ...cycle,
+            suggestedBreak: suggestCycleBreakEdge(cycle, cycles),
+        }));
+        storeSlotCycles(db, sessionId, withBreaks);
         storeScannedFiles(db, sessionId, sourceFiles.map((f) => relative(projectRoot, f)));
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();

package/dist/src/analyze/composite-closure.d.ts

@@ -0,0 +1,25 @@
+export interface ComponentGraphNode {
+    name: string;
+    slots: Array<{
+        name: string;
+        allowedComponents?: string[];
+    }>;
+}
+export interface ClosureNode {
+    name: string;
+    depth: number;
+    path: string[];
+    parents: string[];
+}
+export interface Closure {
+    root: string;
+    nodes: ClosureNode[];
+    containsCycle: boolean;
+    cyclePath?: string[];
+}
+export type NodeStatus = 'ok' | 'warning' | 'error';
+export declare function findRoots(components: ComponentGraphNode[], selected?: Set<string>): string[];
+export declare function computeClosure(root: string, components: ComponentGraphNode[]): Closure;
+export declare function computeAllClosures(components: ComponentGraphNode[], selected?: Set<string>): Map<string, Closure>;
+export declare function aggregateStatus(closure: Closure, perNodeStatus: Map<string, NodeStatus>): NodeStatus;
+export declare function findSharedDeps(closures: Map<string, Closure>): Map<string, string[]>;

package/dist/src/analyze/composition/agent-parser/author-prompt.d.ts

@@ -0,0 +1,4 @@
+export declare function buildAuthorPrompt(files: Array<{
+    path: string;
+    content: string;
+}>, componentNames: string[], instructionOverride?: string): string;

package/dist/src/analyze/composition/agent-parser/author-prompt.js

@@ -0,0 +1,22 @@
+import { loadPrompt } from './load-prompt.js';
+/**
+ * Build the prompt that asks the agent to WRITE a pure parser function (spec:
+ * agent-authored-parser, Phase 2) rather than list edges. The static
+ * instruction + contract live in `prompts/composition-parser.md`; this
+ * appends the dynamic candidate files + component names. The authored parser
+ * runs in the sandbox (sandbox.ts), so the contract forbids all I/O.
+ */
+const PROMPT_FILE = 'composition-parser.md';
+export function buildAuthorPrompt(files, componentNames, instructionOverride) {
+    const fileBlocks = files.map((f) => `--- ${f.path} ---\n${f.content}`).join('\n\n');
+    const instruction = instructionOverride?.trim() ? instructionOverride.trim() : loadPrompt(PROMPT_FILE).trim();
+    return [
+        instruction,
+        '',
+        'Component names (use ONLY these):',
+        componentNames.join(', '),
+        '',
+        'Candidate files:',
+        fileBlocks,
+    ].join('\n');
+}

package/dist/src/analyze/composition/agent-parser/extract-parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cheap structural check that source matches the parser contract:
+ * `export default` of a function (declaration or arrow) that takes at least
+ * one parameter. Not a full parse — just enough to reject JSON samples, prose,
+ * and no-arg functions before we spend a sandbox spawn on them.
+ */
+export declare function looksLikeParser(source: string): boolean;
+export declare function extractParserSource(stdout: string): string | null;

package/dist/src/analyze/composition/agent-parser/extract-parser.js

@@ -0,0 +1,44 @@
+/**
+ * Pull the parser function source out of the agent's stdout (spec:
+ * agent-authored-parser, Phase 2). Agents typically wrap code in a fenced
+ * block, but often emit a non-parser block first (a JSON sample, prose). We
+ * return the first block that is actually SHAPED like the contract — a
+ * default-exported function taking one param — so a stray sample never reaches
+ * the sandbox. Lenient by design: no parser-shaped source → null → caller
+ * falls back.
+ */
+const FENCE = /```(?:[a-zA-Z]+)?\n([\s\S]*?)```/g;
+/**
+ * Cheap structural check that source matches the parser contract:
+ * `export default` of a function (declaration or arrow) that takes at least
+ * one parameter. Not a full parse — just enough to reject JSON samples, prose,
+ * and no-arg functions before we spend a sandbox spawn on them.
+ */
+export function looksLikeParser(source) {
+    const s = source.trim();
+    if (!/export\s+default\b/.test(s))
+        return false;
+    // export default function [name] (param...) { ... }
+    const fnDecl = /export\s+default\s+(?:async\s+)?function\b[^(]*\(\s*[A-Za-z_$][\w$]*/;
+    // export default (param...) => ...   OR   export default param => ...
+    const arrow = /export\s+default\s+(?:async\s+)?(?:\(\s*[A-Za-z_$][\w$]*|[A-Za-z_$][\w$]*\s*=>)/;
+    return fnDecl.test(s) || arrow.test(s);
+}
+export function extractParserSource(stdout) {
+    FENCE.lastIndex = 0;
+    let m;
+    while ((m = FENCE.exec(stdout)) !== null) {
+        const candidate = m[1].trim();
+        if (candidate !== '' && looksLikeParser(candidate))
+            return candidate;
+    }
+    // No parser-shaped fenced block — accept bare source only if it, too, is
+    // shaped like the contract.
+    const idx = stdout.indexOf('export default');
+    if (idx !== -1) {
+        const bare = stdout.slice(idx).trim();
+        if (looksLikeParser(bare))
+            return bare;
+    }
+    return null;
+}

package/dist/src/analyze/composition/agent-parser/load-prompt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve a bundled prompt file from the package-root `prompts/` directory.
+ * Walks up from this module so it works from both `src/` and `dist/src/`,
+ * mirroring `resolveSkillPath` for the skills/ directory.
+ */
+export declare function resolvePromptPath(fileName: string): string;
+export declare function loadPrompt(fileName: string): string;

package/dist/src/analyze/composition/agent-parser/load-prompt.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve a bundled prompt file from the package-root `prompts/` directory.
+ * Walks up from this module so it works from both `src/` and `dist/src/`,
+ * mirroring `resolveSkillPath` for the skills/ directory.
+ */
+export function resolvePromptPath(fileName) {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    let dir = thisDir;
+    for (;;) {
+        const candidate = join(dir, 'prompts');
+        if (existsSync(candidate))
+            return join(candidate, fileName);
+        const parent = resolve(dir, '..');
+        if (parent === dir) {
+            throw new Error(`prompt file missing from CLI installation (could not locate prompts/ directory from: ${thisDir})`);
+        }
+        dir = parent;
+    }
+}
+export function loadPrompt(fileName) {
+    const path = resolvePromptPath(fileName);
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        throw new Error(`prompt file missing from CLI installation — try reinstalling the CLI (looked for: ${path})`);
+    }
+}