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

package/dist/src/import/tui/wizard-state-transitions.js

@@ -1,45 +1,9 @@
-/**
- * Pure state-machine helpers for the wizard. Extracted from WizardApp.tsx so the
- * transitions can be unit-tested without rendering ink.
- *
- * Bug fix (2026-06): credentials moved BEFORE generate so:
- *   1. Bad creds (401/403) are caught upfront — before the operator pays the cost
- *      of extract + LLM classification (potentially many minutes).
- *   2. Live preview in final-review actually fires, because the validated creds
- *      are present in WizardApp state when GenerateReviewStep mounts.
- *
- * New order:
- *   welcome → token-input → path-validation → extracting → scope-gate
- *          → credentials (validates inline) → generating
- *          → generating → final-review → push-decision-gate → previewing
- *          → preview-gate → pushing → done
- *
- * `--no-push` short-circuits the credentials/preview/push branch — the operator
- * just wants extract + classify + final-review without ever touching Contentful.
- */
-/**
- * Transition target after the scope-gate confirms.
- *
- * - acceptedCount > 0:
- *   - !noPush → `credentials` (gather + validate creds upfront, before LLM cost)
- *   - noPush  → `generating` (skip creds entirely; live preview no-ops gracefully)
- * - acceptedCount === 0 (everything rejected):
- *   - !noPush → `credentials` (still need creds to push tokens / removals)
- *   - noPush  → `print-gate` (nothing to do; let the operator save files and exit)
- */
 export function nextStepAfterScopeGate(opts) {
     if (opts.acceptedCount > 0) {
         return opts.noPush ? 'generating' : 'credentials';
     }
     return opts.noPush ? 'print-gate' : 'credentials';
 }
-/**
- * Transition target after credentials are validated (or skipped via the
- * inline validation pings the API). Drives the post-credentials branch:
- *   - acceptedCount > 0 → `generating` (run the generator now that creds are good)
- *   - acceptedCount === 0 → `push-decision-gate` (no components to generate;
- *     skip straight to push-decision and preview)
- */
 export function nextStepAfterCredentialsValidated(opts) {
     return opts.acceptedCount > 0 ? 'generating' : 'push-decision-gate';
 }
@@ -47,38 +11,19 @@ export function shouldSkipFinalReviewAfterCredentials(state) {
     return state.finalReviewPassed && state.generateSessionId != null;
 }
 export function resolveNoCacheForGenerate(opts) {
-    if (opts.isFreshSession)
-        return true;
     return opts.cliNoCache;
 }
-/**
- * Skip-credentials spec — Task 2. When the operator pressed `s` on the
- * credentials screen, the wizard advanced without validating creds. That
- * makes `previewImport` impossible (no working token) and undesirable (the
- * whole point is to inspect locally without touching the server). Callers
- * check this before issuing the API call and route to
- * `buildSkippedPreviewTransition()` instead.
- */
 export function shouldBypassPreview(state) {
     return state.credentialsSkipped === true;
 }
-/**
- * State patch applied when `shouldBypassPreview` is true: skip the preview
- * step entirely, surface no server preview to downstream consumers, and
- * hand control to the push-decision-gate (which will render with push
- * disabled — see Task 3).
- */
 export function buildSkippedPreviewTransition() {
     return { step: 'push-decision-gate', serverPreview: null };
 }
-/**
- * Skip-credentials spec — Task 4 (defensive guard). The push-decision-gate
- * disables "Save AND push" and "Push only" when credentialsSkipped is true,
- * so `runPush` should never be reached. If a state-machine regression ever
- * routed an operator past that guard, `runPush` checks this helper and
- * refuses to issue the API call — instead it routes back to the print-files
- * local-save path via `buildSkippedPushTransition`.
- */
+export function resolveCycleGateAction(opts) {
+    if (!opts.hasCycles)
+        return 'proceed';
+    return opts.autoRejectCycles ? 'auto-reject' : 'block';
+}
 export function shouldRefusePush(state) {
     return state.credentialsSkipped === true;
 }

package/dist/src/lib/composition-mode.d.ts

@@ -0,0 +1,28 @@
+export type CompositionMode = 'composite' | 'atomic';
+/**
+ * Options that, when present, IMPLY composite mode — passing any of them is a
+ * clear opt-in, so requiring an explicit `--composite` alongside is redundant.
+ */
+export type CompositionSourceOptions = {
+    compositionMap?: string;
+    compositionAgent?: boolean;
+    compositionRefresh?: boolean;
+    generateMap?: string;
+};
+/**
+ * Resolve the effective composition mode with precedence
+ * `explicit flag > implied source > env > persisted config > default`.
+ * Default is `atomic` (composition OFF); `--composite` opts into the hierarchy
+ * machinery.
+ *
+ * `--atomic` is accepted for symmetry and wins when passed — even alongside a
+ * composition source, since it's an explicit "no" that overrides the implicit
+ * opt-in. If both `--composite` and `--atomic` are present, `--composite`
+ * wins. Passing a composition source (`--composition-map/-agent`,
+ * `--composition-refresh`, or `--generate-map`) implies composite without a
+ * separate `--composite`.
+ */
+export declare function resolveCompositionMode(opts: {
+    composite?: boolean;
+    atomic?: boolean;
+} & CompositionSourceOptions, configMode?: CompositionMode): CompositionMode;

package/dist/src/lib/composition-mode.js

@@ -0,0 +1,37 @@
+function hasCompositionSource(opts) {
+    return !!opts.compositionMap || !!opts.compositionAgent || !!opts.compositionRefresh || !!opts.generateMap;
+}
+/**
+ * Resolve the effective composition mode with precedence
+ * `explicit flag > implied source > env > persisted config > default`.
+ * Default is `atomic` (composition OFF); `--composite` opts into the hierarchy
+ * machinery.
+ *
+ * `--atomic` is accepted for symmetry and wins when passed — even alongside a
+ * composition source, since it's an explicit "no" that overrides the implicit
+ * opt-in. If both `--composite` and `--atomic` are present, `--composite`
+ * wins. Passing a composition source (`--composition-map/-agent`,
+ * `--composition-refresh`, or `--generate-map`) implies composite without a
+ * separate `--composite`.
+ */
+export function resolveCompositionMode(opts, configMode) {
+    if (opts.composite)
+        return 'composite';
+    if (opts.atomic)
+        return 'atomic';
+    // A composition source is an explicit opt-in for this invocation — it beats
+    // env/config, but not an explicit --atomic (handled above).
+    if (hasCompositionSource(opts))
+        return 'composite';
+    const env = process.env['EXPERIENCES_COMPOSITION_MODE'];
+    if (env !== undefined && env !== '') {
+        const v = env.toLowerCase();
+        if (v === 'composite')
+            return 'composite';
+        if (v === 'atomic')
+            return 'atomic';
+    }
+    if (configMode === 'composite' || configMode === 'atomic')
+        return configMode;
+    return 'atomic';
+}

package/dist/src/lib/prompt-overrides.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic `--prompt <stage>=<value>` override parser.
+ *
+ * One repeatable flag overrides the prompt for any named pipeline stage
+ * (e.g. `composition`, `select`, `generate`). The value is classified by
+ * string SHAPE only — no filesystem access here: a value that looks like a
+ * path is resolved+read by the consumer; otherwise it is treated as the
+ * literal prompt text. This keeps the parser pure and testable.
+ */
+export type PromptOverride = {
+    kind: 'path';
+    value: string;
+} | {
+    kind: 'text';
+    value: string;
+};
+/**
+ * Heuristic: does this value look like a file path (vs. literal prompt text)?
+ * Path if it contains a path separator, starts with `~`, or ends with a known
+ * prompt-file extension. Deliberately does NOT touch the filesystem.
+ */
+export declare function looksLikePath(value: string): boolean;
+export type ParsePromptOverridesResult = {
+    overrides: Map<string, PromptOverride>;
+    errors: string[];
+};
+/**
+ * Parse repeated `stage=value` flag inputs into a stage→override map. Splits on
+ * the FIRST `=` so values may contain `=`. Last write wins for a repeated
+ * stage. Malformed entries are collected in `errors` (caller decides fatality).
+ */
+export declare function parsePromptOverrides(inputs: string[]): ParsePromptOverridesResult;
+/**
+ * Resolve an override to its prompt text: read the file for a `path` override
+ * (resolved against cwd), or return the literal `text` value. Throws with a
+ * clear message if a path override can't be read.
+ */
+export declare function resolvePromptOverride(override: PromptOverride): Promise<string>;

package/dist/src/lib/prompt-overrides.js

@@ -0,0 +1,69 @@
+/**
+ * Generic `--prompt <stage>=<value>` override parser.
+ *
+ * One repeatable flag overrides the prompt for any named pipeline stage
+ * (e.g. `composition`, `select`, `generate`). The value is classified by
+ * string SHAPE only — no filesystem access here: a value that looks like a
+ * path is resolved+read by the consumer; otherwise it is treated as the
+ * literal prompt text. This keeps the parser pure and testable.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+const PROMPT_FILE_EXTENSIONS = ['.md', '.txt', '.prompt'];
+/**
+ * Heuristic: does this value look like a file path (vs. literal prompt text)?
+ * Path if it contains a path separator, starts with `~`, or ends with a known
+ * prompt-file extension. Deliberately does NOT touch the filesystem.
+ */
+export function looksLikePath(value) {
+    if (value.includes('/') || value.includes('\\'))
+        return true;
+    if (value.startsWith('~'))
+        return true;
+    const lower = value.toLowerCase();
+    return PROMPT_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+/**
+ * Parse repeated `stage=value` flag inputs into a stage→override map. Splits on
+ * the FIRST `=` so values may contain `=`. Last write wins for a repeated
+ * stage. Malformed entries are collected in `errors` (caller decides fatality).
+ */
+export function parsePromptOverrides(inputs) {
+    const overrides = new Map();
+    const errors = [];
+    for (const raw of inputs) {
+        const eq = raw.indexOf('=');
+        if (eq === -1) {
+            errors.push(`--prompt "${raw}" must be in the form stage=value`);
+            continue;
+        }
+        const stage = raw.slice(0, eq).trim();
+        const value = raw.slice(eq + 1);
+        if (stage === '') {
+            errors.push(`--prompt "${raw}" has an empty stage (expected stage=value)`);
+            continue;
+        }
+        if (value === '') {
+            errors.push(`--prompt "${raw}" has an empty value`);
+            continue;
+        }
+        overrides.set(stage, looksLikePath(value) ? { kind: 'path', value } : { kind: 'text', value });
+    }
+    return { overrides, errors };
+}
+/**
+ * Resolve an override to its prompt text: read the file for a `path` override
+ * (resolved against cwd), or return the literal `text` value. Throws with a
+ * clear message if a path override can't be read.
+ */
+export async function resolvePromptOverride(override) {
+    if (override.kind === 'text')
+        return override.value;
+    const abs = resolve(override.value);
+    try {
+        return await readFile(abs, 'utf8');
+    }
+    catch {
+        throw new Error(`--prompt: could not read prompt file: ${abs}`);
+    }
+}

package/dist/src/print/command.js

@@ -80,6 +80,7 @@ export function registerPrintCommand(program) {
         .description('Write generated components to a CDF JSON file')
         .option('--session <id>', 'Session ID to print from (default: most recent generate components session)')
         .option('--out <path>', 'Output file path', 'components.json')
+        .option('--allow-empty', 'Write an empty-but-present components manifest when no components are accepted (a subsequent push then removes ALL components from the target space). Without this, an empty accepted set is an error.')
         .action(async (opts) => {
         const outPath = resolve(opts.out);
         await assertOutIsNotDirectory(outPath);
@@ -87,18 +88,35 @@ export function registerPrintCommand(program) {
         const db = openPipelineDb();
         let components;
         let generateStepStatus = null;
+        let rejectedCount = 0;
         try {
             components = loadCDFComponents(db, sessionId);
             const stepRow = db
                 .prepare(`SELECT status FROM steps WHERE session_id = ? AND command = 'generate components' ORDER BY id DESC LIMIT 1`)
                 .get(sessionId);
             generateStepStatus = stepRow?.status ?? null;
+            const rejectedRow = db
+                .prepare(`SELECT COUNT(*) AS n FROM raw_components WHERE session_id = ? AND status = 'generate-rejected'`)
+                .get(sessionId);
+            rejectedCount = rejectedRow?.n ?? 0;
         }
         finally {
             db.close();
         }
         if (components.length === 0) {
-            die(`Error: no generated components in session '${sessionId}'. Run generate components first.`);
+            if (rejectedCount > 0) {
+                // Components WERE generated, but final review left none accepted — every
+                // component was rejected or left unresolved. This is a legitimate
+                // "clear the space" intent, but it's destructive, so require --allow-empty.
+                if (!opts.allowEmpty) {
+                    die(`Error: all ${rejectedCount} generated component${rejectedCount === 1 ? ' was' : 's were'} rejected or left unresolved at final review in session '${sessionId}', so there is nothing to save. Accept at least one component (press [a] on a row, or [A] to accept all), or pass --allow-empty to write an empty manifest that will DELETE all components from the target space on push.`);
+                }
+                // Fall through: write an empty-but-present components manifest so a
+                // subsequent push removes every component from the target space.
+            }
+            else {
+                die(`Error: no generated components in session '${sessionId}'. Run generate components first.`);
+            }
         }
         if (generateStepStatus === 'failed') {
             process.stderr.write(`Warning: session '${sessionId}' generate step failed — output may be incomplete (${components.length} components found)\n`);

package/dist/src/runs/modify-launcher.d.ts

@@ -13,6 +13,9 @@ export type ModifyLauncherInput = {
     savePath: string;
     entryStep: 'scope-gate' | 'final-review';
     saveMode: 'overwrite' | 'new' | 'prompt';
+    /** Composition mode from the run record, so the modify wizard resumes in the
+     *  same mode. Omitted → the wizard's default (`atomic`). */
+    compositionMode?: 'composite' | 'atomic';
     outDirOverride?: string;
     /** Pre-fill space id (from the run record's pushedTo). */
     initialSpaceId?: string;

package/dist/src/runs/modify-launcher.js

@@ -21,6 +21,8 @@ export async function launchModifyWizard(input) {
         props.seedGenerateSessionId = input.generateSessionId;
     if (input.tokenSessionId)
         props.seedTokenSessionId = input.tokenSessionId;
+    if (input.compositionMode)
+        props.compositionMode = input.compositionMode;
     if (input.saveMode === 'overwrite')
         props.outDirOverride = input.savePath;
     if (input.outDirOverride)

package/dist/src/runs/replay-helpers.js

@@ -151,6 +151,7 @@ export async function modifyRun(opts) {
         savePath: run.savePath,
         entryStep: 'final-review',
         saveMode,
+        ...(run.compositionMode ? { compositionMode: run.compositionMode } : {}),
         ...(opts.outDir ? { outDirOverride: resolve(opts.outDir) } : {}),
         ...(mergedSpaceId ? { initialSpaceId: mergedSpaceId } : {}),
         ...(mergedEnvironmentId ? { initialEnvironmentId: mergedEnvironmentId } : {}),

package/dist/src/runs/run-picker.js

@@ -2,18 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { Box, Text } from 'ink';
 import { useImmediateInput } from '../analyze/select/tui/hooks/useImmediateInput.js';
-const COLLAPSED_LIMIT = 3;
-/**
- * The picker collapses to top 3 + Show all only when there are 5+ total.
- * Four or fewer runs render in full.
- */
-const COLLAPSE_THRESHOLD = 5;
-/**
- * Format the createdAt timestamp as `YYYY-MM-DD HH:MM` in the operator's
- * local timezone. We intentionally use local time (not UTC) because the
- * picker is for human recognition — operators expect to see times in the
- * same zone they were when the run happened.
- */
+const COLLAPSED_LIMIT = 10;
+const COLLAPSE_THRESHOLD = 12;
 function formatCreatedAt(iso) {
     const d = new Date(iso);
     if (Number.isNaN(d.getTime()))
@@ -78,15 +68,12 @@ function buildRows(runs, expanded) {
 export function RunPicker({ runs, staleRunIds, onSelect, onCancel }) {
     const [expanded, setExpanded] = useState(false);
     const [focusIdx, setFocusIdx] = useState(0);
-    // When non-null, render the Push/Modify/Cancel sub-screen for this run.
     const [actionRunId, setActionRunId] = useState(null);
     const rows = buildRows(runs, expanded);
-    // Clamp focus if the row count shrinks (e.g. after expansion changes layout).
     const clampedFocus = Math.min(focusIdx, rows.length - 1);
     const selectRow = (row) => {
         if (row.kind === 'show-all') {
             setExpanded(true);
-            // Keep cursor on the first newly-revealed run for continuity.
             setFocusIdx(COLLAPSED_LIMIT);
             return;
         }
@@ -98,9 +85,6 @@ export function RunPicker({ runs, staleRunIds, onSelect, onCancel }) {
     };
     useImmediateInput((rawInput, key) => {
         if (actionRunId !== null) {
-            // Sub-screen owns input while it's active. (ActionScreen also installs
-            // its own useImmediateInput; only one is mounted at a time so there's
-            // no double-handle.)
             return;
         }
         if (key.upArrow || rawInput === 'k') {

package/dist/src/runs/store.d.ts

@@ -55,6 +55,10 @@ export type RunRecord = {
      *  writers always populate. Added in runs.json v3. Optional for the same
      *  reason as `sourceFingerprint`. */
     savedFingerprint?: SavedFingerprint | null;
+    /** Composition mode the run was produced in, so modify/replay resumes in the
+     *  same mode (`composite` vs `atomic`). Absent on records written before this
+     *  field existed; callers treat a missing value as `atomic` (the default). */
+    compositionMode?: 'composite' | 'atomic';
     notes?: string;
 };
 export type RunsFile = {

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

@@ -3,6 +3,7 @@ import type { RawComponentDefinition } from '../types.js';
 import type { CDFComponentEntry, DTCGTokenEntry, DTCGTokenGroup } from '@contentful/experience-design-system-types';
 import type { ToolCall, TokenToolCall } from '../generate/agent-runner.js';
 import type { ComponentTypeSummary } from '@contentful/experience-design-system-types';
+import type { SlotCycle, SlotEdge } from '../analyze/cycle-detection.js';
 export type StepStatus = 'pending' | 'complete' | 'failed' | 'interrupted';
 export type CommandName = 'analyze extract' | 'analyze select' | 'generate components' | 'generate tokens' | 'generate edit' | 'apply preview' | 'apply select' | 'apply push' | 'print components' | 'print tokens' | 'import';
 export interface SessionRow {
@@ -31,12 +32,6 @@ export interface ApplyToolCallsResult {
     slots: number;
     warnings: string[];
 }
-/**
- * Feature 1: load per-component metadata for surfacing in the review UI —
- * source path, full source text, and per-prop rationale + source-location.
- * Returns null when no row matches. Decoupled from loadCDFComponents so
- * the CDF projection stays unaffected.
- */
 export interface ComponentReviewMetadata {
     sourcePath: string | null;
     componentSource: string | null;
@@ -65,13 +60,6 @@ export interface ComponentRationale {
         rationale: string | null;
     }>;
 }
-/**
- * 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 declare function loadComponentRationale(db: DatabaseSync, sessionId: string, componentName: string): ComponentRationale | null;
 export declare function applyToolCalls(db: DatabaseSync, sessionId: string, componentId: string, componentName: string, calls: ToolCall[], incomingWarnings: string[]): ApplyToolCallsResult;
 export interface MatchHints {
@@ -95,12 +83,6 @@ export type RawComponentWithId = RawComponentDefinition & {
     component_id: string;
 };
 export declare function loadRawComponents(db: DatabaseSync, sessionId: string, allowedNames?: Set<string>): RawComponentWithId[];
-/**
- * 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 declare function renameEmptySlots(db: DatabaseSync, sessionId: string, componentId: string, componentName: string, slotCount: number): {
     renames: Array<{
         oldName: string;
@@ -121,6 +103,10 @@ export type ScopeComponentRow = {
     componentId: string;
     aiDecision: 'accepted' | 'rejected' | null;
     aiReason: string | null;
+    slots: Array<{
+        name: string;
+        allowedComponents: string[];
+    }>;
 };
 export declare function loadScopeComponents(db: DatabaseSync, sessionId: string): ScopeComponentRow[];
 export declare function applyScopeDecisions(db: DatabaseSync, sessionId: string, decisions: {
@@ -141,22 +127,10 @@ export declare function loadDTCGTokens(db: DatabaseSync, sessionId: string): {
 export declare function findLatestSessionForCommand(db: DatabaseSync, command: CommandName): string | null;
 export declare function seedCDFFromPriorSession(db: DatabaseSync, targetSessionId: string): number;
 export declare function seedCDFFromPreviewResponse(db: DatabaseSync, sessionId: string, removedItems: ComponentTypeSummary[]): number;
-/**
- * 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 declare function seedDefaultsFromChangedItems(db: DatabaseSync, sessionId: string, changedItems: Array<{
     current: ComponentTypeSummary;
     proposed: object;
 }>): number;
-/**
- * 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 declare function backfillUnclassifiedProps(db: DatabaseSync, sessionId: string): number;
 export interface CacheEntry {
     inputHash: string;
@@ -164,7 +138,6 @@ export interface CacheEntry {
     entityId: string;
     sourceSessionId: string;
     humanEdited: boolean;
-    /** sha256 of the prompt content. '' for pre-upgrade rows that predate the fine-grained cache. */
     promptHash: string;
     createdAt: string;
     updatedAt: string;
@@ -176,17 +149,17 @@ export declare function lookupCacheByEntity(db: DatabaseSync, entityType: 'compo
 export declare function storeCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, sourceSessionId: string, humanEdited: boolean, promptHash?: string): void;
 export declare function storeScannedFiles(db: DatabaseSync, sessionId: string, filePaths: string[]): void;
 export declare function loadScannedFiles(db: DatabaseSync, sessionId: string): string[];
+export declare function storeSlotCycles(db: DatabaseSync, sessionId: string, cycles: Array<SlotCycle & {
+    suggestedBreak?: SlotEdge | null;
+}>): void;
+export interface StoredSlotCycle extends SlotCycle {
+    suggestedBreak: SlotEdge | null;
+}
+export declare function loadSlotCycles(db: DatabaseSync, sessionId: string): StoredSlotCycle[];
+export declare function clearSlotCycles(db: DatabaseSync, sessionId: string): void;
 export declare function markCacheHumanEdited(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): void;
 export declare function copyComponentFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string, componentId: string): void;
 export declare function copyTokensFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string): void;
-/**
- * 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 declare function getCliCacheVersion(): Promise<string>;
 export interface ExtractCacheEntry {
     filePath: string;
@@ -198,6 +171,16 @@ export interface ExtractCacheEntry {
 }
 export declare function storeExtractCache(db: DatabaseSync, filePath: string, fileHash: string, cliVersion: string, components: RawComponentDefinition[]): void;
 export declare function lookupExtractCache(db: DatabaseSync, fileHash: string, cliVersion: string): ExtractCacheEntry | null;
+/**
+ * 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 declare function storeCompositionCache(db: DatabaseSync, inputHash: string, cliVersion: string, agentOutput: string): void;
+export declare function lookupCompositionCache(db: DatabaseSync, inputHash: string, cliVersion: string): string | null;
 export type SelectDecision = 'accepted' | 'rejected';
 export interface SelectCacheEntry {
     componentHash: string;