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

package/dist/src/session/db.js

@@ -138,6 +138,15 @@ CREATE TABLE IF NOT EXISTS scanned_files (
   PRIMARY KEY (session_id, path)
 );
 
+CREATE TABLE IF NOT EXISTS slot_cycles (
+  session_id             TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  cycle_index            INTEGER NOT NULL,
+  path_json              TEXT NOT NULL,
+  edges_json             TEXT NOT NULL,
+  suggested_break_json   TEXT,
+  PRIMARY KEY (session_id, cycle_index)
+);
+
 CREATE INDEX IF NOT EXISTS idx_steps_session            ON steps(session_id);
 CREATE INDEX IF NOT EXISTS idx_steps_command            ON steps(session_id, command);
 CREATE INDEX IF NOT EXISTS idx_raw_components_session   ON raw_components(session_id);
@@ -160,18 +169,6 @@ export function openPipelineDb(dbPath) {
     mkdirSync(dirname(path), { recursive: true });
     try {
         const db = new DatabaseSync(path);
-        // Configure connection-level pragmas BEFORE running schema/migrations.
-        // - journal_mode=WAL: persistent on the DB file; readers don't block writers
-        //   and vice versa. (Also set in SCHEMA, but harmless to assert per-open.)
-        // - busy_timeout: per-connection; SQLite waits for a lock instead of
-        //   immediately throwing 'database is locked'. Critical when the wizard
-        //   main process and select-agent subprocesses contend on writes.
-        // - synchronous=NORMAL: safe under WAL, faster than FULL.
-        // busy_timeout MUST come first. PRAGMA journal_mode = WAL needs a
-        // RESERVED lock briefly even when the DB is already WAL; if the
-        // select-agent child is mid-write at that moment, the wizard's open
-        // fails instantly without retry. Setting busy_timeout first makes
-        // SQLite wait up to 5s for the lock.
         db.exec('PRAGMA busy_timeout = 5000');
         db.exec('PRAGMA journal_mode = WAL');
         db.exec('PRAGMA synchronous = NORMAL');
@@ -182,23 +179,16 @@ export function openPipelineDb(dbPath) {
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         if (msg.includes('database is locked')) {
-            // Throw a typed-ish error rather than process.exit(1). Calling exit
-            // from inside Ink's render reconciler crashes the TUI mid-frame and
-            // emits a noisy 'setState during render' warning. The CLI entry
-            // point (src/index.ts) catches and exits cleanly for non-TUI
-            // contexts; the wizard catches and transitions to its error step.
             throw new Error('database is locked: another CLI process may be running. Retry once it exits.');
         }
         throw e;
     }
 }
 function applyDbMigrations(db) {
-    // Add raw_slots.required column if it doesn't exist yet (added in v0.5.14).
     const cols = db.prepare('PRAGMA table_info(raw_slots)').all();
     if (!cols.some((c) => c.name === 'required')) {
         db.exec('ALTER TABLE raw_slots ADD COLUMN required INTEGER NOT NULL DEFAULT 1 CHECK (required IN (0, 1))');
     }
-    // Add extraction confidence scoring columns if they don't exist yet (added in v0.6.0).
     const rawCompCols = db.prepare('PRAGMA table_info(raw_components)').all();
     const rawCompColNames = new Set(rawCompCols.map((c) => c.name));
     if (!rawCompColNames.has('extraction_confidence')) {
@@ -210,8 +200,6 @@ function applyDbMigrations(db) {
     if (!rawCompColNames.has('needs_review')) {
         db.exec('ALTER TABLE raw_components ADD COLUMN needs_review INTEGER NOT NULL DEFAULT 0');
     }
-    // Feature 1: per-component source path on raw_components, rationale + per-prop
-    // source location on raw_props. All nullable, no DEFAULT — existing rows survive.
     if (!rawCompColNames.has('source_path')) {
         db.exec('ALTER TABLE raw_components ADD COLUMN source_path TEXT');
     }
@@ -226,15 +214,9 @@ function applyDbMigrations(db) {
     if (!rawPropColNames.has('source_end_line')) {
         db.exec('ALTER TABLE raw_props ADD COLUMN source_end_line INTEGER');
     }
-    // Feature 3: persist select-agent's reject reason on raw_components. Nullable,
-    // no DEFAULT — accepted components keep NULL, rejected ones store the LLM's
-    // reason (or `validation error: <codes>` for validation auto-rejections).
     if (!rawCompColNames.has('reject_reason')) {
         db.exec('ALTER TABLE raw_components ADD COLUMN reject_reason TEXT');
     }
-    // Component rationale: WHY a component was classified, why these props,
-    // why these slots — surfaced via the `I` panel. All nullable, no DEFAULT
-    // so existing rows survive. Plus per-slot rationale on raw_slots.
     if (!rawCompColNames.has('component_description_rationale')) {
         db.exec('ALTER TABLE raw_components ADD COLUMN component_description_rationale TEXT');
     }
@@ -248,9 +230,6 @@ function applyDbMigrations(db) {
     if (!rawSlotColsForRationale.some((c) => c.name === 'rationale')) {
         db.exec('ALTER TABLE raw_slots ADD COLUMN rationale TEXT');
     }
-    // Fine-grained cache: extract_cache holds per-file extracted components keyed
-    // on (file_hash, cli_version). cli_version is a content hash of bundled skill
-    // files so cache busts on a prompt change (not on every npm patch bump).
     const hasExtractCache = db
         .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='extract_cache'`)
         .all();
@@ -268,9 +247,6 @@ function applyDbMigrations(db) {
       CREATE INDEX idx_extract_cache_file ON extract_cache(file_path);
     `);
     }
-    // Fine-grained cache: select_cache stores accept/reject decisions per
-    // (component_hash, prompt_hash, cli_version). On hit, the wizard replays the
-    // decision without an LLM call.
     const hasSelectCache = db
         .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='select_cache'`)
         .all();
@@ -288,7 +264,6 @@ function applyDbMigrations(db) {
       );
     `);
     }
-    // Add generation_cache table if it doesn't exist yet.
     const tables = db
         .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='generation_cache'`)
         .all();
@@ -308,16 +283,6 @@ function applyDbMigrations(db) {
       CREATE INDEX idx_generation_cache_session ON generation_cache(source_session_id);
     `);
     }
-    // Fine-grained cache: add prompt_hash to generation_cache so cache busts when
-    // the operator switches prompt files. Existing rows get '' (matches the
-    // historical "default bundled prompt" — note that lookups using a non-empty
-    // hash for the bundled prompt won't match, so first run after upgrade busts
-    // the cache. Documented as acceptable.
-    //
-    // The primary key also needs to expand to include prompt_hash so multiple
-    // prompt variants can coexist per (input_hash, entity_type, entity_id).
-    // SQLite doesn't allow ALTERing a PK, so when promoting the schema we rebuild
-    // the table in-place.
     const genCacheCols = db.prepare(`PRAGMA table_info(generation_cache)`).all();
     const hasPromptHash = genCacheCols.some((c) => c.name === 'prompt_hash');
     const oldPkCols = genCacheCols.filter((c) => c.pk > 0).map((c) => c.name);
@@ -356,6 +321,21 @@ function applyDbMigrations(db) {
             throw e;
         }
     }
+    const hasCompositionCache = db
+        .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='composition_cache'`)
+        .all();
+    if (hasCompositionCache.length === 0) {
+        db.exec(`
+      CREATE TABLE composition_cache (
+        input_hash   TEXT NOT NULL,
+        cli_version  TEXT NOT NULL,
+        agent_output TEXT NOT NULL,
+        created_at   TEXT NOT NULL,
+        updated_at   TEXT NOT NULL,
+        PRIMARY KEY (input_hash, cli_version)
+      );
+    `);
+    }
 }
 export function loadComponentReviewMetadata(db, sessionId, componentName) {
     const compRow = db
@@ -393,13 +373,6 @@ export function loadComponentReviewMetadata(db, sessionId, componentName) {
         props,
     };
 }
-/**
- * Component-rationale loader: data contract for the `I` ComponentRationalePanel.
- * Returns the component's description + the three component-level rationale
- * strings (why-description / why-props / why-slots), plus per-prop and per-slot
- * rationale rows for the operator-facing panel. Returns null when no component
- * matches.
- */
 export function loadComponentRationale(db, sessionId, componentName) {
     const compRow = db
         .prepare(`SELECT component_id, name, description, component_description_rationale, props_rationale, slots_rationale
@@ -458,8 +431,6 @@ export function applyToolCalls(db, sessionId, componentId, componentName, calls,
                 if (call.description !== undefined) {
                     db.prepare('UPDATE raw_components SET description = ? WHERE session_id = ? AND component_id = ?').run(call.description, sessionId, componentId);
                 }
-                // Component-level rationale: sparse-update each field only when present
-                // so missing keys don't overwrite previously-stored values.
                 if (call.rationale) {
                     if (call.rationale.description !== undefined) {
                         db.prepare('UPDATE raw_components SET component_description_rationale = ? WHERE session_id = ? AND component_id = ?').run(call.rationale.description, sessionId, componentId);
@@ -499,8 +470,6 @@ export function applyToolCalls(db, sessionId, componentId, componentName, calls,
                     warnings.push(`${componentName}: classify_slot '${call.slot}' — slot not found, skipped`);
                     continue;
                 }
-                // Per-slot rationale: sparse-update only when present so omitting it
-                // doesn't blank existing values.
                 if (call.rationale !== undefined) {
                     db.prepare('UPDATE raw_slots SET rationale = ? WHERE session_id = ? AND component_id = ? AND name = ?').run(call.rationale, sessionId, componentId, call.slot);
                 }
@@ -521,11 +490,7 @@ export function applyToolCalls(db, sessionId, componentId, componentName, calls,
     }
     return { classified, excluded, slots, warnings };
 }
-export function getOrCreateSession(db, sessionFlag, sessionName, 
-// `_hints` is retained for call-site compatibility but no longer drives an
-// implicit auto-match by inputPath/outDir — operators who want to resume must
-// pass an explicit --session <id>.
-_hints) {
+export function getOrCreateSession(db, sessionFlag, sessionName, _hints) {
     const now = new Date().toISOString();
     if (sessionFlag === 'new' || sessionFlag === undefined) {
         const id = generateSessionId();
@@ -626,7 +591,6 @@ export function storeRawComponents(db, sessionId, components, options) {
                 }
             }
         }
-        // Restore CDF classification data for props that still exist
         if (options?.preserveCDF && cdfSnapshot.length > 0) {
             const updateCDFByName = db.prepare(`UPDATE raw_props SET cdf_type = ?, cdf_category = ?, cdf_token_kind = ?
          WHERE session_id = ? AND component_id = ? AND name = ?`);
@@ -634,7 +598,6 @@ export function storeRawComponents(db, sessionId, components, options) {
          WHERE session_id = ? AND component_id = ? AND position = ? AND cdf_type IS NULL`);
             const restoredPropKeys = new Set();
             const unmatchedSnaps = [];
-            // First pass: match by name
             for (const snap of cdfSnapshot) {
                 const result = updateCDFByName.run(snap.cdf_type, snap.cdf_category, snap.cdf_token_kind, sessionId, snap.component_id, snap.name);
                 if (Number(result.changes) > 0) {
@@ -644,7 +607,6 @@ export function storeRawComponents(db, sessionId, components, options) {
                     unmatchedSnaps.push(snap);
                 }
             }
-            // Second pass: for renamed props, fall back to position-based matching
             for (const snap of unmatchedSnaps) {
                 const result = updateCDFByPosition.run(snap.cdf_type, snap.cdf_category, snap.cdf_token_kind, sessionId, snap.component_id, snap.position);
                 if (Number(result.changes) > 0) {
@@ -660,7 +622,6 @@ export function storeRawComponents(db, sessionId, components, options) {
             for (const snap of descSnapshot) {
                 updateDesc.run(snap.description, sessionId, snap.component_id);
             }
-            // Restore allowed values only for props that still exist (to avoid FK violations)
             const relevantAV = avSnapshot.filter((av) => restoredPropKeys.has(`${av.component_id}::${av.prop_name}`));
             if (relevantAV.length > 0) {
                 const deleteAV = db.prepare(`DELETE FROM raw_prop_allowed_values WHERE session_id = ? AND component_id = ? AND prop_name = ?`);
@@ -712,7 +673,6 @@ export function loadRawComponents(db, sessionId, allowedNames) {
         .prepare(`SELECT component_id, slot_name, position, allowed_component
        FROM raw_slot_allowed_components WHERE session_id = ? ORDER BY component_id, slot_name, position`)
         .all(sessionId);
-    // Group children by component_id
     const propsByComponent = groupBy(props, (p) => p.component_id);
     const allowedValuesByProp = groupBy(allowedValues, (av) => `${av.component_id}::${av.prop_name}`);
     const slotsByComponent = groupBy(slots, (s) => s.component_id);
@@ -770,12 +730,6 @@ export function loadRawComponents(db, sessionId, allowedNames) {
         }),
     }));
 }
-/**
- * Rename empty-named slots in the DB to heuristic names before generation.
- * The LLM classify_slot tool call is matched back to the DB row by name, so a
- * row with name="" can never be updated by the LLM — renaming it here makes it
- * classifiable. Returns one warning string per renamed slot.
- */
 export function renameEmptySlots(db, sessionId, componentId, componentName, slotCount) {
     const emptySlots = db
         .prepare(`SELECT name, position FROM raw_slots
@@ -787,15 +741,9 @@ export function renameEmptySlots(db, sessionId, componentId, componentName, slot
     const renames = [];
     const warnings = [];
     const rename = db.prepare(`UPDATE raw_slots SET name = ? WHERE session_id = ? AND component_id = ? AND name = ? AND position = ?`);
-    // Multi-statement write — wrap in a transaction so a SIGINT or driver error
-    // mid-loop leaves raw_slots either fully renamed or fully untouched, never
-    // half-renamed (which would corrupt the prompt-vs-DB invariant the LLM
-    // relies on for classify_slot). Matches the existing BEGIN/COMMIT pattern
-    // throughout this file (see storeRawComponents, createStep, etc.).
     db.exec('BEGIN');
     try {
         for (const slot of emptySlots) {
-            // Single unnamed slot → "children". Multiple → positional names.
             const newName = slotCount === 1 ? 'children' : `slot_${slot.position}`;
             rename.run(newName, sessionId, componentId, slot.name, slot.position);
             renames.push({ oldName: slot.name, newName });
@@ -834,6 +782,11 @@ export function storeCDFComponents(db, sessionId, components) {
      VALUES (?, ?, ?, ?, ?)`);
     const insertAllowedComponent = db.prepare(`INSERT INTO raw_slot_allowed_components (session_id, component_id, slot_name, allowed_component, position)
      VALUES (?, ?, ?, ?, ?)`);
+    const deleteSlots = db.prepare(`DELETE FROM raw_slots WHERE session_id = ? AND component_id = ?`);
+    const deleteSlotAllowedComponents = db.prepare(`DELETE FROM raw_slot_allowed_components WHERE session_id = ? AND component_id = ?`);
+    const readExistingSlotDefaults = db.prepare(`SELECT name, is_default FROM raw_slots WHERE session_id = ? AND component_id = ?`);
+    const insertSlotOnUpdate = db.prepare(`INSERT INTO raw_slots (session_id, component_id, name, is_default, required, description, position)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`);
     db.exec('BEGIN');
     try {
         for (const { key, entry } of components) {
@@ -850,9 +803,19 @@ export function storeCDFComponents(db, sessionId, components) {
                         prop.$values.forEach((v, i) => insertAllowedValue.run(sessionId, componentId, propName, v, i));
                     }
                 }
+                const existingDefaults = new Map(readExistingSlotDefaults.all(sessionId, componentId).map((r) => [r.name, r.is_default]));
+                deleteSlotAllowedComponents.run(sessionId, componentId);
+                deleteSlots.run(sessionId, componentId);
+                let slotPos = 0;
+                for (const [slotName, slot] of Object.entries(entry.$slots ?? {})) {
+                    const isDefault = existingDefaults.get(slotName) ?? 0;
+                    insertSlotOnUpdate.run(sessionId, componentId, slotName, isDefault, slot.$required ? 1 : 0, slot.$description ?? null, slotPos++);
+                    if (slot.$allowedComponents && slot.$allowedComponents.length > 0) {
+                        slot.$allowedComponents.forEach((ac, i) => insertAllowedComponent.run(sessionId, componentId, slotName, ac, i));
+                    }
+                }
             }
             else {
-                // Component not in raw_components (e.g. agent added a new one) — insert a minimal record
                 const componentId = createHash('sha256').update(`${key}:generated`).digest('hex').slice(0, 12);
                 db.prepare(`INSERT INTO raw_components (session_id, component_id, name, source, framework, extracted_at, status, description)
            VALUES (?, ?, ?, '', 'react', ?, 'generated', ?)`).run(sessionId, componentId, key, now, entry.$description ?? null);
@@ -915,20 +878,8 @@ export function loadCDFComponents(db, sessionId) {
     const allowedComponentsBySlot = groupBy(allowedComponents, (ac) => `${ac.component_id}::${ac.slot_name}`);
     return components.map(({ component_id, name, description }) => {
         const compProps = propsByComponent.get(component_id) ?? [];
-        // NOTE: Components with zero CDF-classified props are intentionally
-        // returned with an empty `$properties` object. Filtering them out here
-        // silently dropped them from the wizard's final-review (INTEG-4257),
-        // so the user couldn't see that the LLM had failed to classify anything
-        // and couldn't reject the empty component. Surface them instead — the
-        // wizard tags them with a ⚠ badge and an in-panel banner so the user
-        // can manually add props in FieldEditor or reject the component.
-        // Downstream consumers (buildManifest, push) tolerate empty $properties.
         const $properties = {};
         for (const p of compProps) {
-            // Hallucination insurance: drop any prop whose name didn't survive trim.
-            // The pre-generate rename guard catches empty-named slots, but if the LLM
-            // hallucinated a classify_prop with an empty name into the DB, surface
-            // nothing to the manifest builder rather than emitting "$properties: { '': ... }".
             if (!p.name.trim())
                 continue;
             const av = allowedValuesByProp.get(`${component_id}::${p.name}`);
@@ -957,9 +908,6 @@ export function loadCDFComponents(db, sessionId) {
         const compSlots = slotsByComponent.get(component_id) ?? [];
         const $slots = {};
         for (const s of compSlots) {
-            // Hallucination insurance: same as $properties — drop empty-named slots
-            // before they reach buildManifest, which faithfully passes empty keys
-            // through and triggers a 422 from the preview API.
             if (!s.name.trim())
                 continue;
             const ac = allowedComponentsBySlot.get(`${component_id}::${s.name}`);
@@ -981,30 +929,39 @@ export function loadCDFComponents(db, sessionId) {
     });
 }
 export function loadScopeComponents(db, sessionId) {
-    // Loads extract-stage components: those still pending operator review (`extracted`)
-    // plus those the Feature 3 auto-filter has already classified (`accepted` /
-    // `rejected`). Excludes `generated` (already past scope-gate) so re-runs of the
-    // wizard don't show already-confirmed components.
     const rows = db
         .prepare(`SELECT name, component_id, status, reject_reason FROM raw_components
        WHERE session_id = ? AND status IN ('extracted', 'accepted', 'rejected')
        ORDER BY name`)
         .all(sessionId);
+    if (rows.length === 0)
+        return [];
+    const slotRows = db
+        .prepare(`SELECT component_id, name, position
+       FROM raw_slots WHERE session_id = ? ORDER BY component_id, position`)
+        .all(sessionId);
+    const allowedRows = db
+        .prepare(`SELECT component_id, slot_name, position, allowed_component
+       FROM raw_slot_allowed_components WHERE session_id = ? ORDER BY component_id, slot_name, position`)
+        .all(sessionId);
+    const slotsByComponent = groupBy(slotRows, (s) => s.component_id);
+    const allowedBySlot = groupBy(allowedRows, (a) => `${a.component_id}::${a.slot_name}`);
     return rows.map((r) => ({
         name: r.name,
         componentId: r.component_id,
         aiDecision: r.status === 'accepted' ? 'accepted' : r.status === 'rejected' ? 'rejected' : null,
         aiReason: r.reject_reason,
+        slots: (slotsByComponent.get(r.component_id) ?? []).map((s) => ({
+            name: s.name,
+            allowedComponents: (allowedBySlot.get(`${r.component_id}::${s.name}`) ?? []).map((a) => a.allowed_component),
+        })),
     }));
 }
 export function applyScopeDecisions(db, sessionId, decisions) {
     const now = new Date().toISOString();
     const acceptedSet = new Set(decisions.accepted);
     const accepted = [...acceptedSet];
-    // Conflict precedence: accepted wins over rejected.
     const rejected = [...new Set(decisions.rejected)].filter((n) => !acceptedSet.has(n));
-    // Rejected first so accepted writes can flip back to 'generated' afterwards
-    // if a name appears in both lists.
     if (rejected.length > 0) {
         const placeholders = rejected.map(() => '?').join(',');
         db.prepare(`UPDATE raw_components SET status = 'rejected' WHERE session_id = ? AND name IN (${placeholders})`).run(sessionId, ...rejected);
@@ -1107,8 +1064,6 @@ export function findLatestSessionForCommand(db, command) {
     return row?.id ?? null;
 }
 export function seedCDFFromPriorSession(db, targetSessionId) {
-    // Find the most recent session (other than target) that has CDF data for any of the
-    // target's component_ids. This works regardless of which command produced the CDF.
     const targetComponentIds = db
         .prepare(`SELECT component_id FROM raw_components WHERE session_id = ?`)
         .all(targetSessionId);
@@ -1124,7 +1079,6 @@ export function seedCDFFromPriorSession(db, targetSessionId) {
     if (!priorRow)
         return 0;
     const priorSessionId = priorRow.session_id;
-    // Copy CDF columns from prior session's props into matching props in the target session.
     const result = db
         .prepare(`UPDATE raw_props SET
        cdf_type = (SELECT p2.cdf_type FROM raw_props p2
@@ -1141,7 +1095,6 @@ export function seedCDFFromPriorSession(db, targetSessionId) {
                    WHERE p2.session_id = ? AND p2.component_id = raw_props.component_id
                    AND p2.name = raw_props.name AND p2.cdf_type IS NOT NULL)`)
         .run(priorSessionId, priorSessionId, priorSessionId, targetSessionId, priorSessionId);
-    // Also copy descriptions from prior session's components
     db.prepare(`UPDATE raw_components SET description = (
        SELECT c2.description FROM raw_components c2
        WHERE c2.session_id = ? AND c2.component_id = raw_components.component_id
@@ -1151,7 +1104,6 @@ export function seedCDFFromPriorSession(db, targetSessionId) {
        AND EXISTS (SELECT 1 FROM raw_components c2
                    WHERE c2.session_id = ? AND c2.component_id = raw_components.component_id
                    AND c2.description IS NOT NULL)`).run(priorSessionId, targetSessionId, priorSessionId);
-    // Copy allowed values for seeded props from prior session
     if (result.changes > 0) {
         db.prepare(`INSERT OR IGNORE INTO raw_prop_allowed_values (session_id, component_id, prop_name, position, value)
        SELECT ?, av.component_id, av.prop_name, av.position, av.value
@@ -1199,12 +1151,6 @@ export function seedCDFFromPreviewResponse(db, sessionId, removedItems) {
     }
     return totalSeeded;
 }
-/**
- * Seeds server-side metadata for changed components:
- * 1. Fills in defaults the server has but we don't (prevents accidental removal)
- * 2. Seeds cdf_type/cdf_category for props that exist on server but lack CDF locally
- *    (e.g. props with non-standard source types the generation step couldn't classify)
- */
 export function seedDefaultsFromChangedItems(db, sessionId, changedItems) {
     if (changedItems.length === 0)
         return 0;
@@ -1224,13 +1170,11 @@ export function seedDefaultsFromChangedItems(db, sessionId, changedItems) {
         const contentProps = new Set(current.contentProperties);
         const designProps = new Set(current.designProperties);
         for (const [propName, propSummary] of Object.entries(current.fullProperties)) {
-            // Seed defaults
             if (propSummary.default !== undefined && propSummary.default !== null) {
                 const defaultStr = typeof propSummary.default === 'string' ? propSummary.default : JSON.stringify(propSummary.default);
                 const result = updateDefaultStmt.run(defaultStr, sessionId, localComponent.component_id, propName);
                 totalSeeded += Number(result.changes);
             }
-            // Seed CDF type/category for props that lack it
             const cdfType = mapServerTypeToCDFType(propSummary.type);
             if (!cdfType)
                 continue;
@@ -1249,14 +1193,7 @@ export function seedDefaultsFromChangedItems(db, sessionId, changedItems) {
     }
     return totalSeeded;
 }
-/**
- * Ensures all props on generated components have a cdf_type.
- * Uses the pre-classification `category` column when available.
- * Falls back to cdf_type: 'string', cdf_category: 'content' for props
- * with no pre-classification (safe default — content is the most common category).
- */
 export function backfillUnclassifiedProps(db, sessionId) {
-    // First: backfill props that HAVE a pre-classification category
     const withCategory = db
         .prepare(`UPDATE raw_props SET cdf_type = 'string', cdf_category = category
      WHERE session_id = ? AND cdf_type IS NULL AND category IS NOT NULL
@@ -1264,7 +1201,6 @@ export function backfillUnclassifiedProps(db, sessionId) {
          SELECT component_id FROM raw_components WHERE session_id = ? AND status = 'generated'
        )`)
         .run(sessionId, sessionId);
-    // Second: backfill props with NO category (complex types the rules couldn't classify)
     const withoutCategory = db
         .prepare(`UPDATE raw_props SET cdf_type = 'string', cdf_category = 'content'
      WHERE session_id = ? AND cdf_type IS NULL AND category IS NULL
@@ -1297,12 +1233,6 @@ function mapServerTypeToCDFType(serverType) {
     }
 }
 export function computeComponentInputHash(component) {
-    // Narrow the hashed payload to extractor-only fields. Any field that
-    // `applyToolCalls` may overwrite (prop description/required/default/allowed
-    // values, slot description/allowed components) is excluded so that the cache
-    // key does not depend on its own output — otherwise re-reading raw props
-    // after a generation pass would drift the hash even when the underlying
-    // source has not changed.
     const payload = {
         framework: component.framework,
         name: component.name,
@@ -1314,6 +1244,7 @@ export function computeComponentInputHash(component) {
         slots: component.slots.map((s) => ({
             name: s.name,
             isDefault: s.isDefault,
+            allowedComponents: [...(s.allowedComponents ?? [])].sort(),
         })),
     };
     return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
@@ -1388,6 +1319,36 @@ export function loadScannedFiles(db, sessionId) {
     const rows = db.prepare('SELECT path FROM scanned_files WHERE session_id = ? ORDER BY path').all(sessionId);
     return rows.map((r) => r.path);
 }
+export function storeSlotCycles(db, sessionId, cycles) {
+    db.exec('BEGIN');
+    try {
+        db.prepare('DELETE FROM slot_cycles WHERE session_id = ?').run(sessionId);
+        const insert = db.prepare(`INSERT INTO slot_cycles (session_id, cycle_index, path_json, edges_json, suggested_break_json)
+       VALUES (?, ?, ?, ?, ?)`);
+        for (let i = 0; i < cycles.length; i += 1) {
+            const cycle = cycles[i];
+            insert.run(sessionId, i, JSON.stringify(cycle.path), JSON.stringify(cycle.edges), cycle.suggestedBreak ? JSON.stringify(cycle.suggestedBreak) : null);
+        }
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        db.exec('ROLLBACK');
+        throw e;
+    }
+}
+export function loadSlotCycles(db, sessionId) {
+    const rows = db
+        .prepare('SELECT cycle_index, path_json, edges_json, suggested_break_json FROM slot_cycles WHERE session_id = ? ORDER BY cycle_index')
+        .all(sessionId);
+    return rows.map((r) => ({
+        path: JSON.parse(r.path_json),
+        edges: JSON.parse(r.edges_json),
+        suggestedBreak: r.suggested_break_json ? JSON.parse(r.suggested_break_json) : null,
+    }));
+}
+export function clearSlotCycles(db, sessionId) {
+    db.prepare('DELETE FROM slot_cycles WHERE session_id = ?').run(sessionId);
+}
 export function markCacheHumanEdited(db, entityType, entityId) {
     const now = new Date().toISOString();
     db.prepare(`UPDATE generation_cache SET human_edited = 1, updated_at = ? WHERE entity_type = ? AND entity_id = ?`).run(now, entityType, entityId);
@@ -1458,18 +1419,7 @@ export function copyTokensFromCache(db, sourceSessionId, targetSessionId) {
         throw e;
     }
 }
-// ---------------------------------------------------------------------------
-// Fine-grained cache: extract_cache helpers
-// ---------------------------------------------------------------------------
 let _cliCacheVersionCache = null;
-/**
- * Returns the CLI cache version used to namespace cache rows. To avoid busting
- * the cache on every npm patch bump, this hashes the content of the bundled
- * skill prompts. When the prompts change, cache invalidates; when only library
- * code or test fixtures change, the cache stays warm.
- *
- * Memoized per-process. Falls back to package version on any I/O error.
- */
 export async function getCliCacheVersion() {
     if (_cliCacheVersionCache)
         return _cliCacheVersionCache;
@@ -1529,6 +1479,28 @@ export function lookupExtractCache(db, fileHash, cliVersion) {
         components,
     };
 }
+/**
+ * Content-addressed cache for the composition resolver's raw agent output
+ * (authored parser source or emitted-edge JSONL). Keyed by a hash of the
+ * candidate files + producer identity (`composition-cache-key.ts`), scoped by
+ * `cli_version` so a prompt/skill change invalidates stale entries. Replaces
+ * the former on-disk `~/.contentful/.../composition-cache` store so all CLI
+ * caches live in the one pipeline DB.
+ */
+export function storeCompositionCache(db, inputHash, cliVersion, agentOutput) {
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO composition_cache (input_hash, cli_version, agent_output, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(input_hash, cli_version) DO UPDATE SET
+       agent_output = excluded.agent_output,
+       updated_at = excluded.updated_at`).run(inputHash, cliVersion, agentOutput, now, now);
+}
+export function lookupCompositionCache(db, inputHash, cliVersion) {
+    const row = db
+        .prepare(`SELECT agent_output FROM composition_cache WHERE input_hash = ? AND cli_version = ?`)
+        .get(inputHash, cliVersion);
+    return row ? row.agent_output : null;
+}
 export function storeSelectCache(db, componentHash, promptHash, cliVersion, decision, reason) {
     const now = new Date().toISOString();
     db.prepare(`INSERT INTO select_cache (component_hash, prompt_hash, cli_version, decision, reason, created_at, updated_at)

package/dist/src/setup/composition-mode-prompt.d.ts

@@ -0,0 +1,14 @@
+import type { CompositionMode } from '../lib/composition-mode.js';
+/**
+ * Setup prompts for composition (spec T10). Parallels `promptAutoFilterPreference`
+ * — injectable `ask` for TTY-free unit testing.
+ *
+ * (a) Composite-mode default. Default N → atomic (composition OFF); the
+ *     low-surprise default. `--composite` opts in per invocation.
+ */
+export declare function promptCompositeModePreference(ask: (q: string) => Promise<string>, current?: CompositionMode): Promise<CompositionMode>;
+/**
+ * (b) Agentic mapping resolution. Default N — opt-in (it costs tokens and the
+ *     output needs review), and only meaningful in composite mode.
+ */
+export declare function promptAgenticResolutionPreference(ask: (q: string) => Promise<string>, current?: boolean): Promise<boolean>;

package/dist/src/setup/composition-mode-prompt.js

@@ -0,0 +1,37 @@
+/**
+ * Setup prompts for composition (spec T10). Parallels `promptAutoFilterPreference`
+ * — injectable `ask` for TTY-free unit testing.
+ *
+ * (a) Composite-mode default. Default N → atomic (composition OFF); the
+ *     low-surprise default. `--composite` opts in per invocation.
+ */
+export async function promptCompositeModePreference(ask, current) {
+    const defaultValue = current ?? 'atomic';
+    const hint = defaultValue === 'composite' ? '[Y/n]' : '[y/N]';
+    const answer = (await ask(`  Enable composite (embedded-component) mode by default? ${hint} `)).trim().toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    if (answer.startsWith('y'))
+        return 'composite';
+    if (answer.startsWith('n'))
+        return 'atomic';
+    return defaultValue;
+}
+/**
+ * (b) Agentic mapping resolution. Default N — opt-in (it costs tokens and the
+ *     output needs review), and only meaningful in composite mode.
+ */
+export async function promptAgenticResolutionPreference(ask, current) {
+    const defaultValue = current ?? false;
+    const hint = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = (await ask(`  Enable agentic mapping resolution when no groups are found? ${hint} `))
+        .trim()
+        .toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    if (answer.startsWith('y'))
+        return true;
+    if (answer.startsWith('n'))
+        return false;
+    return defaultValue;
+}

package/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/"
   ],
   "dependencies": {
     "commander": "^13.1.0",
@@ -33,8 +34,8 @@
     "react": "^18.3.1",
     "react-devtools-core": "^4.19.1",
     "react-dom": "^18.3.1",
-    "@contentful/experience-design-system-extraction": "2.14.2",
-    "@contentful/experience-design-system-types": "2.14.2"
+    "@contentful/experience-design-system-types": "2.15.0",
+    "@contentful/experience-design-system-extraction": "2.15.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/prompts/composition-dir-critic.md

@@ -0,0 +1,7 @@
+These directories were NOT selected as composition candidates by a keyword filter.
+Judging by the PATH/NAME alone, which (if any) might contain component composition,
+mapping, or parent→child relationship declarations worth inspecting? Be selective —
+skip obvious utilities, tests, styles, and unrelated feature code.
+
+Reply with ONLY a JSON array of the directory strings to include, e.g. ["src/registry"].
+Use [] if none look relevant. Copy the strings exactly as listed.

package/prompts/composition-edges.md

@@ -0,0 +1,8 @@
+You are extracting parent→child component composition from a design system by reading the files below.
+
+STRICT RULES — follow exactly, they keep the output deterministic:
+1. Emit an edge ONLY when the candidate files contain explicit evidence that the parent renders/accepts the child (e.g. a mapping declaration, a slot/`allowedComponents` list, a `withParentType`/`requiredParent`/`allowedTagNames` entry). Direct textual evidence only.
+2. Do NOT infer, guess, or generalize from naming, category, or what "usually" nests. If the files do not state the relationship, do not emit it.
+3. Every edge MUST include a `reason` that quotes or cites the exact file + declaration that justifies it. If you cannot cite evidence, omit the edge.
+4. Emit each parent→child pair at most once. Do not repeat edges.
+5. Prefer completeness of EVIDENCED edges over quantity — a smaller, fully-justified set is correct; padding with plausible-but-unstated edges is wrong.

package/prompts/composition-parser-repair-empty.md

@@ -0,0 +1 @@
+Your previous parser ran without error but returned 0 edges, even though the candidate files clearly contain composition relationships. Re-examine the patterns (parent attribution is the usual culprit) and return only the corrected function in a single fenced code block.

package/prompts/composition-parser-repair-error.md

@@ -0,0 +1,2 @@
+Your previous parser failed with: {{error}}
+Fix it and return only the corrected function in a single fenced code block.