@contentful/experience-design-system-cli 2.12.0 → 2.12.1-dev-build-bae15c7.0

package/dist/src/runs/staleness.js

@@ -0,0 +1,140 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256Hex } from './fingerprint.js';
+const UNKNOWN = {
+    stale: false,
+    staleComponents: [],
+    staleTokens: false,
+    savedComponentsEdited: false,
+    savedTokensEdited: false,
+    missingSourceFiles: [],
+};
+/**
+ * Re-stat the source files and re-hash the saved artifacts captured by a
+ * run record's fingerprints, and report what (if anything) drifted.
+ *
+ * Returns `stale: false` when the run is missing a source fingerprint
+ * entirely (v2 records pre-dating runs.json v3 — treat as UNKNOWN, not
+ * stale, so existing runs keep replaying).
+ */
+export async function checkRunStaleness(run) {
+    if (!run.sourceFingerprint)
+        return { ...UNKNOWN };
+    const result = {
+        stale: false,
+        staleComponents: [],
+        staleTokens: false,
+        savedComponentsEdited: false,
+        savedTokensEdited: false,
+        missingSourceFiles: [],
+    };
+    // ── Per-file source check ────────────────────────────────────────────
+    for (const [absPath, entry] of Object.entries(run.sourceFingerprint.files)) {
+        try {
+            const st = await stat(absPath);
+            if (st.mtime.toISOString() !== entry.mtime) {
+                result.staleComponents.push(entry.componentName ?? absPath);
+                result.stale = true;
+            }
+        }
+        catch {
+            result.missingSourceFiles.push(absPath);
+            result.stale = true;
+        }
+    }
+    // ── Raw tokens (single file: re-stat AND re-hash) ────────────────────
+    if (run.sourceFingerprint.rawTokensPath) {
+        const absPath = run.sourceFingerprint.rawTokensPath;
+        try {
+            const [st, buf] = await Promise.all([stat(absPath), readFile(absPath)]);
+            const mtime = st.mtime.toISOString();
+            const hash = sha256Hex(buf);
+            const mtimeChanged = run.sourceFingerprint.rawTokensMtime !== null && mtime !== run.sourceFingerprint.rawTokensMtime;
+            const hashChanged = run.sourceFingerprint.rawTokensContentHash !== null && hash !== run.sourceFingerprint.rawTokensContentHash;
+            if (mtimeChanged || hashChanged) {
+                result.staleTokens = true;
+                result.stale = true;
+            }
+        }
+        catch {
+            result.staleTokens = true;
+            result.stale = true;
+        }
+    }
+    // ── Saved-file check (read & hash components.json / tokens.json) ─────
+    if (run.savedFingerprint) {
+        if (run.savedFingerprint.componentsJsonHash !== null) {
+            const compPath = join(run.savePath, 'components.json');
+            try {
+                const buf = await readFile(compPath);
+                if (sha256Hex(buf) !== run.savedFingerprint.componentsJsonHash) {
+                    result.savedComponentsEdited = true;
+                    result.stale = true;
+                }
+            }
+            catch {
+                result.savedComponentsEdited = true;
+                result.stale = true;
+            }
+        }
+        if (run.savedFingerprint.tokensJsonHash !== null) {
+            const tokensPath = run.tokensPath ?? join(run.savePath, 'tokens.json');
+            try {
+                const buf = await readFile(tokensPath);
+                if (sha256Hex(buf) !== run.savedFingerprint.tokensJsonHash) {
+                    result.savedTokensEdited = true;
+                    result.stale = true;
+                }
+            }
+            catch {
+                result.savedTokensEdited = true;
+                result.stale = true;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Render a short human-readable summary of a Staleness result, e.g.
+ * `src: 3, tokens, saved`. Returns the empty string when not stale.
+ */
+export function shortStalenessSummary(s) {
+    if (!s.stale)
+        return '';
+    const parts = [];
+    const srcCount = s.staleComponents.length + s.missingSourceFiles.length;
+    if (srcCount > 0)
+        parts.push(`src: ${srcCount}`);
+    if (s.staleTokens)
+        parts.push('tokens');
+    if (s.savedComponentsEdited || s.savedTokensEdited)
+        parts.push('saved');
+    return parts.join(', ');
+}
+/**
+ * Render a multi-line detail block for staleness output (used by `runs <id>`
+ * detail view and replay refusals). Caps long lists at 5 entries.
+ */
+export function formatStalenessDetail(s) {
+    if (!s.stale)
+        return ['Status: FRESH'];
+    const lines = ['Status: STALE'];
+    const cap = 5;
+    if (s.staleComponents.length > 0) {
+        const head = s.staleComponents.slice(0, cap).join(', ');
+        const more = s.staleComponents.length > cap ? ` and ${s.staleComponents.length - cap} more` : '';
+        lines.push(`  Source changed: ${head}${more}`);
+    }
+    if (s.missingSourceFiles.length > 0) {
+        const head = s.missingSourceFiles.slice(0, cap).join(', ');
+        const more = s.missingSourceFiles.length > cap ? ` and ${s.missingSourceFiles.length - cap} more` : '';
+        lines.push(`  Source missing: ${head}${more}`);
+    }
+    if (s.staleTokens)
+        lines.push('  Raw tokens drifted');
+    if (s.savedComponentsEdited)
+        lines.push('  Saved components.json edited');
+    if (s.savedTokensEdited)
+        lines.push('  Saved tokens.json edited');
+    return lines;
+}

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

@@ -0,0 +1,78 @@
+export declare const RUNS_FILE_VERSION: 3;
+export declare const RUNS_FILE_CAP = 200;
+/** Versions this CLI can read. v1 / v2 files are auto-migrated in memory;
+ *  new writes always use the latest version. */
+export declare const READABLE_VERSIONS: Set<number>;
+/** Per-file source fingerprint captured at save time. `files` is keyed by
+ *  absolute (path.resolve'd) source path; each entry records the file's
+ *  mtime (ISO 8601) at the moment the run record was written and, when
+ *  known, the component name extracted from it (first-seen wins on
+ *  collisions). */
+export type SourceFingerprint = {
+    files: Record<string, {
+        mtime: string;
+        componentName?: string;
+    }>;
+    rawTokensPath: string | null;
+    rawTokensMtime: string | null;
+    rawTokensContentHash: string | null;
+};
+/** SHA-256 hashes of the JSON artifacts the wizard wrote to disk. Used on
+ *  replay to detect manual edits to components.json / tokens.json. */
+export type SavedFingerprint = {
+    componentsJsonHash: string | null;
+    tokensJsonHash: string | null;
+};
+export type RunRecord = {
+    id: string;
+    createdAt: string;
+    projectPath: string;
+    savePath: string;
+    componentCount: number;
+    tokenCount: number;
+    /** Filesystem path of the saved tokens.json. Null when no tokens were
+     *  generated for the run. Added in runs.json v2. */
+    tokensPath: string | null;
+    /** Pipeline.db session id for the generated tokens. Null when no tokens
+     *  step ran. Added in runs.json v2 so replay/push and modify can re-emit
+     *  or re-push tokens. */
+    tokenSessionId: string | null;
+    agent: string;
+    pushedTo: {
+        spaceId: string;
+        environmentId: string;
+        host: string;
+    } | null;
+    extractSessionId: string;
+    generateSessionId: string | null;
+    /** Per-file source fingerprint. Null on v1/v2 records read from disk; v3
+     *  writers always populate. Added in runs.json v3. Optional in the type
+     *  so callers that don't compute it (e.g. older test fixtures) still
+     *  satisfy `RunRecord`; `appendRun` always normalizes a missing value to
+     *  null on the way to disk. */
+    sourceFingerprint?: SourceFingerprint | null;
+    /** Saved-artifact fingerprint. Null on v1/v2 records read from disk; v3
+     *  writers always populate. Added in runs.json v3. Optional for the same
+     *  reason as `sourceFingerprint`. */
+    savedFingerprint?: SavedFingerprint | null;
+    notes?: string;
+};
+export type RunsFile = {
+    version: typeof RUNS_FILE_VERSION;
+    runs: RunRecord[];
+};
+export declare function runsFilePath(): string;
+export declare function generateUlid(now?: number): string;
+export type AppendInput = Omit<RunRecord, 'id' | 'createdAt'> & Partial<Pick<RunRecord, 'id' | 'createdAt'>>;
+export declare function appendRun(input: AppendInput): Promise<RunRecord>;
+export type ListOptions = {
+    limit?: number;
+    projectPath?: string;
+    before?: string;
+    after?: string;
+};
+export declare function listRuns(opts?: ListOptions): Promise<RunRecord[]>;
+export declare function getRun(id: string): Promise<RunRecord>;
+export declare function updateRun(id: string, patch: Partial<Omit<RunRecord, 'id'>>): Promise<RunRecord>;
+export declare function findRunBySavePath(savePath: string): Promise<RunRecord | null>;
+export declare function findAllRunsBySavePath(savePath: string): Promise<RunRecord[]>;

package/dist/src/runs/store.js

@@ -0,0 +1,136 @@
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+export const RUNS_FILE_VERSION = 3;
+export const RUNS_FILE_CAP = 200;
+/** Versions this CLI can read. v1 / v2 files are auto-migrated in memory;
+ *  new writes always use the latest version. */
+export const READABLE_VERSIONS = new Set([1, 2, 3]);
+const RUNS_DIR = join(homedir(), '.config', 'experiences');
+const RUNS_PATH = join(RUNS_DIR, 'runs.json');
+export function runsFilePath() {
+    return RUNS_PATH;
+}
+// Crockford-base32 ULID (26 chars: 10 timestamp + 16 random).
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function encodeBase32(bytes, length) {
+    let out = '';
+    let bits = 0;
+    let value = 0;
+    for (const b of bytes) {
+        value = (value << 8) | b;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += CROCKFORD[(value >> bits) & 0x1f];
+        }
+    }
+    if (bits > 0)
+        out += CROCKFORD[(value << (5 - bits)) & 0x1f];
+    return out.slice(0, length);
+}
+export function generateUlid(now = Date.now()) {
+    // 48-bit timestamp -> 10 chars
+    const tsBytes = new Uint8Array(6);
+    let n = now;
+    for (let i = 5; i >= 0; i--) {
+        tsBytes[i] = n & 0xff;
+        n = Math.floor(n / 256);
+    }
+    const ts = encodeBase32(tsBytes, 10);
+    const rand = encodeBase32(randomBytes(10), 16);
+    return (ts + rand).toUpperCase();
+}
+function migrateRecord(rec) {
+    return {
+        ...rec,
+        tokensPath: rec.tokensPath ?? null,
+        tokenSessionId: rec.tokenSessionId ?? null,
+        sourceFingerprint: rec.sourceFingerprint ?? null,
+        savedFingerprint: rec.savedFingerprint ?? null,
+    };
+}
+async function readFileMaybe() {
+    try {
+        const raw = await readFile(RUNS_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!READABLE_VERSIONS.has(parsed.version)) {
+            throw new Error(`runs.json version mismatch: file is v${parsed.version}, this CLI expects v${RUNS_FILE_VERSION} (also reads: ${[...READABLE_VERSIONS].join(', ')}). Back up and remove the file to start fresh.`);
+        }
+        // Always migrate to current schema in memory; new writes will persist v2.
+        const runs = parsed.runs.map(migrateRecord);
+        return { version: RUNS_FILE_VERSION, runs };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+async function writeAtomic(file) {
+    await mkdir(RUNS_DIR, { recursive: true });
+    const body = JSON.stringify(file, null, 2) + '\n';
+    const tmp = `${RUNS_PATH}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, body, { mode: 0o600 });
+    await rename(tmp, RUNS_PATH);
+}
+export async function appendRun(input) {
+    const existing = await readFileMaybe();
+    const record = {
+        ...input,
+        id: input.id ?? generateUlid(),
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        sourceFingerprint: input.sourceFingerprint ?? null,
+        savedFingerprint: input.savedFingerprint ?? null,
+    };
+    const runs = existing ? [record, ...existing.runs] : [record];
+    if (runs.length > RUNS_FILE_CAP) {
+        const dropped = runs.length - RUNS_FILE_CAP;
+        runs.length = RUNS_FILE_CAP;
+        console.warn(`runs.json reached cap of ${RUNS_FILE_CAP}; dropped ${dropped} oldest entr${dropped === 1 ? 'y' : 'ies'}.`);
+    }
+    await writeAtomic({ version: RUNS_FILE_VERSION, runs });
+    return record;
+}
+export async function listRuns(opts = {}) {
+    const file = await readFileMaybe();
+    if (!file)
+        return [];
+    let runs = file.runs;
+    if (opts.projectPath)
+        runs = runs.filter((r) => r.projectPath === opts.projectPath);
+    if (opts.before)
+        runs = runs.filter((r) => r.createdAt < opts.before);
+    if (opts.after)
+        runs = runs.filter((r) => r.createdAt > opts.after);
+    if (typeof opts.limit === 'number')
+        runs = runs.slice(0, opts.limit);
+    return runs;
+}
+export async function getRun(id) {
+    const file = await readFileMaybe();
+    const found = file?.runs.find((r) => r.id === id);
+    if (!found)
+        throw new Error(`Run ${id} not found in ${RUNS_PATH}`);
+    return found;
+}
+export async function updateRun(id, patch) {
+    const file = (await readFileMaybe()) ?? { version: RUNS_FILE_VERSION, runs: [] };
+    const idx = file.runs.findIndex((r) => r.id === id);
+    if (idx < 0)
+        throw new Error(`Run ${id} not found in ${RUNS_PATH}`);
+    const updated = { ...file.runs[idx], ...patch, id };
+    file.runs[idx] = updated;
+    await writeAtomic(file);
+    return updated;
+}
+export async function findRunBySavePath(savePath) {
+    const file = await readFileMaybe();
+    return file?.runs.find((r) => r.savePath === savePath) ?? null;
+}
+export async function findAllRunsBySavePath(savePath) {
+    const file = await readFileMaybe();
+    return file?.runs.filter((r) => r.savePath === savePath) ?? [];
+}

package/dist/src/session/cache-keys.d.ts

@@ -0,0 +1,15 @@
+import { type Skill } from '../generate/prompt-builder.js';
+/** sha256 hex of a string. Stable across runs. */
+export declare function hashContent(content: string): string;
+/** sha256 hex of a file's UTF-8 content. */
+export declare function hashFile(filePath: string): Promise<string>;
+/**
+ * Hash the prompt content for a skill — either the bundled skill file shipped
+ * with the CLI, or a custom override path. Used to key the select_cache and
+ * generation_cache so cache entries invalidate when the prompt itself changes
+ * (including bundled-skill updates across CLI versions).
+ *
+ * @param skill — which skill (matches resolveSkillPath in prompt-builder)
+ * @param skillPathOverride — optional absolute/relative path to a custom prompt
+ */
+export declare function hashPromptForSkill(skill: Skill, skillPathOverride?: string): Promise<string>;

package/dist/src/session/cache-keys.js

@@ -0,0 +1,38 @@
+/**
+ * Hash helpers for the fine-grained LLM cache.
+ *
+ * Three layers of cache (extract, select, generate) all need stable content
+ * hashes for cache-key derivation. Keep these primitives in one place so the
+ * algorithm and encoding never drift between callers.
+ *
+ * All hashes are sha256 hex (64 chars). No npm deps — uses node:crypto.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { resolveSkillPath } from '../generate/prompt-builder.js';
+/** sha256 hex of a string. Stable across runs. */
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** sha256 hex of a file's UTF-8 content. */
+export async function hashFile(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    return hashContent(content);
+}
+/**
+ * Hash the prompt content for a skill — either the bundled skill file shipped
+ * with the CLI, or a custom override path. Used to key the select_cache and
+ * generation_cache so cache entries invalidate when the prompt itself changes
+ * (including bundled-skill updates across CLI versions).
+ *
+ * @param skill — which skill (matches resolveSkillPath in prompt-builder)
+ * @param skillPathOverride — optional absolute/relative path to a custom prompt
+ */
+export async function hashPromptForSkill(skill, skillPathOverride) {
+    if (skillPathOverride) {
+        return hashFile(resolve(skillPathOverride));
+    }
+    const bundled = resolveSkillPath(skill);
+    return hashFile(bundled);
+}

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

@@ -31,6 +31,48 @@ 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;
+    props: Record<string, {
+        rationale: string | null;
+        sourceStartLine: number | null;
+        sourceEndLine: number | null;
+    }>;
+}
+export declare function loadComponentReviewMetadata(db: DatabaseSync, sessionId: string, componentName: string): ComponentReviewMetadata | null;
+export interface ComponentRationale {
+    name: string;
+    description: string | null;
+    descriptionRationale: string | null;
+    propsRationale: string | null;
+    slotsRationale: string | null;
+    props: Array<{
+        name: string;
+        category: string | null;
+        description: string | null;
+        rationale: string | null;
+    }>;
+    slots: Array<{
+        name: string;
+        description: string | null;
+        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 {
     command: CommandName;
@@ -42,7 +84,7 @@ export interface SessionResolution {
     isNew: boolean;
     isResumed: boolean;
 }
-export declare function getOrCreateSession(db: DatabaseSync, sessionFlag: string | undefined, sessionName: string | undefined, hints: MatchHints): SessionResolution;
+export declare function getOrCreateSession(db: DatabaseSync, sessionFlag: string | undefined, sessionName: string | undefined, _hints: MatchHints): SessionResolution;
 export declare function createStep(db: DatabaseSync, sessionId: string, command: CommandName, inputs: Record<string, string>): number;
 export declare function updateStep(db: DatabaseSync, stepId: number, status: 'complete' | 'failed', outputs: Record<string, string>, error?: string): void;
 export declare function storeRawComponents(db: DatabaseSync, sessionId: string, components: RawComponentDefinition[], options?: {
@@ -74,6 +116,17 @@ export declare function loadCDFComponents(db: DatabaseSync, sessionId: string):
     key: string;
     entry: CDFComponentEntry;
 }>;
+export type ScopeComponentRow = {
+    name: string;
+    componentId: string;
+    aiDecision: 'accepted' | 'rejected' | null;
+    aiReason: string | null;
+};
+export declare function loadScopeComponents(db: DatabaseSync, sessionId: string): ScopeComponentRow[];
+export declare function applyScopeDecisions(db: DatabaseSync, sessionId: string, decisions: {
+    accepted: string[];
+    rejected: string[];
+}): void;
 export declare function storeDTCGTokens(db: DatabaseSync, sessionId: string, groups: DTCGTokenGroup[], tokens: DTCGTokenEntry[]): void;
 export interface ApplyTokenToolCallsResult {
     tokens: number;
@@ -111,16 +164,49 @@ 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;
 }
 export declare function computeComponentInputHash(component: RawComponentWithId): string;
 export declare function computeTokenInputHash(rawTokenContent: string): string;
-export declare function lookupCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string): CacheEntry | null;
+export declare function lookupCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, promptHash?: string): CacheEntry | null;
 export declare function lookupCacheByEntity(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): CacheEntry | null;
-export declare function storeCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, sourceSessionId: string, humanEdited: boolean): void;
+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 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;
+    fileHash: string;
+    cliVersion: string;
+    createdAt: string;
+    updatedAt: string;
+    components: RawComponentDefinition[];
+}
+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;
+export type SelectDecision = 'accepted' | 'rejected';
+export interface SelectCacheEntry {
+    componentHash: string;
+    promptHash: string;
+    cliVersion: string;
+    decision: SelectDecision;
+    reason: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function storeSelectCache(db: DatabaseSync, componentHash: string, promptHash: string, cliVersion: string, decision: SelectDecision, reason: string | null): void;
+export declare function lookupSelectCache(db: DatabaseSync, componentHash: string, promptHash: string, cliVersion: string): SelectCacheEntry | null;