codeloop-mcp-server 0.1.14 → 0.1.15

package/dist/evidence/run_lineage.js

@@ -0,0 +1,138 @@
+/**
+ * Run lineage — enriches every run with ancestry and Git context so that
+ * artifacts can be traced back to the commit, branch, and section that
+ * produced them.
+ *
+ * Also maintains `run_index.json` at the artifacts root for fast lookups
+ * without scanning every `meta.json` file.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+const INDEX_FILE = "run_index.json";
+function gitField(cwd, cmd) {
+    try {
+        return execSync(cmd, { cwd, encoding: "utf-8", timeout: 3000 }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function captureGitContext(cwd) {
+    return {
+        commit_sha: gitField(cwd, "git rev-parse --short HEAD"),
+        branch: gitField(cwd, "git rev-parse --abbrev-ref HEAD"),
+    };
+}
+export function loadRunIndex(artifactsBase) {
+    const p = join(artifactsBase, INDEX_FILE);
+    if (!existsSync(p)) {
+        return { version: 1, entries: [], updated_at: new Date().toISOString() };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(p, "utf-8"));
+        if (!Array.isArray(raw.entries)) {
+            return { version: 1, entries: [], updated_at: new Date().toISOString() };
+        }
+        return raw;
+    }
+    catch {
+        return { version: 1, entries: [], updated_at: new Date().toISOString() };
+    }
+}
+export function saveRunIndex(artifactsBase, index) {
+    mkdirSync(artifactsBase, { recursive: true });
+    index.updated_at = new Date().toISOString();
+    writeFileSync(join(artifactsBase, INDEX_FILE), JSON.stringify(index, null, 2));
+}
+export function appendToIndex(artifactsBase, entry) {
+    const index = loadRunIndex(artifactsBase);
+    const existing = index.entries.findIndex((e) => e.run_id === entry.run_id);
+    if (existing >= 0) {
+        index.entries[existing] = { ...index.entries[existing], ...entry };
+    }
+    else {
+        index.entries.push(entry);
+    }
+    saveRunIndex(artifactsBase, index);
+    return index;
+}
+export function buildLineage(artifactsBase, opts) {
+    const index = loadRunIndex(artifactsBase);
+    const git = captureGitContext(opts.cwd ?? process.cwd());
+    return {
+        parent_run_id: opts.parent_run_id,
+        section_id: opts.section_id,
+        commit_sha: git.commit_sha,
+        branch: git.branch,
+        trigger: opts.trigger,
+        run_index: index.entries.length + 1,
+    };
+}
+/**
+ * Rebuild `run_index.json` by scanning every `meta.json` in the artifacts base.
+ * Useful for migrating existing runs that pre-date the lineage feature.
+ */
+export function rebuildIndex(artifactsBase) {
+    const entries = [];
+    if (!existsSync(artifactsBase)) {
+        return { version: 1, entries, updated_at: new Date().toISOString() };
+    }
+    const dirs = readdirSync(artifactsBase, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name.startsWith("run_"))
+        .map((d) => d.name)
+        .sort();
+    for (const dir of dirs) {
+        const metaPath = join(artifactsBase, dir, "meta.json");
+        if (!existsSync(metaPath))
+            continue;
+        try {
+            const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+            entries.push({
+                run_id: meta.run_id ?? dir,
+                started_at: meta.started_at ?? "",
+                finished_at: meta.finished_at,
+                trigger: meta.lineage?.trigger ?? "manual",
+                section_id: meta.lineage?.section_id ?? meta.section_id,
+                parent_run_id: meta.lineage?.parent_run_id,
+                commit_sha: meta.lineage?.commit_sha,
+                branch: meta.lineage?.branch,
+                confidence: meta.confidence,
+                pass_count: meta.test_summary?.passed ?? meta.deterministic_results?.tests?.passed,
+                fail_count: meta.test_summary?.failed ?? meta.deterministic_results?.tests?.failed,
+                platform: meta.platform,
+            });
+        }
+        catch { /* skip corrupt metas */ }
+    }
+    const index = { version: 1, entries, updated_at: new Date().toISOString() };
+    saveRunIndex(artifactsBase, index);
+    return index;
+}
+export function queryRunHistory(artifactsBase, query = {}) {
+    const index = loadRunIndex(artifactsBase);
+    let filtered = index.entries;
+    if (query.section_id) {
+        filtered = filtered.filter((e) => e.section_id === query.section_id);
+    }
+    if (query.branch) {
+        filtered = filtered.filter((e) => e.branch === query.branch);
+    }
+    if (query.since) {
+        const since = new Date(query.since).getTime();
+        filtered = filtered.filter((e) => {
+            const t = new Date(e.started_at).getTime();
+            return !isNaN(t) && t >= since;
+        });
+    }
+    filtered.sort((a, b) => {
+        const ta = new Date(a.started_at).getTime();
+        const tb = new Date(b.started_at).getTime();
+        return tb - ta;
+    });
+    const limit = query.limit ?? 50;
+    const total = filtered.length;
+    const entries = filtered.slice(0, limit);
+    return { total, returned: entries.length, entries };
+}
+//# sourceMappingURL=run_lineage.js.map

package/dist/evidence/run_lineage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_lineage.js","sourceRoot":"","sources":["../../src/evidence/run_lineage.ts"],"names":[],"mappings":"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"}

package/dist/evidence/screenshot_diff.d.ts

@@ -15,13 +15,17 @@ export interface ScreenshotDiffSummary {
 /**
  * Compare two PNG images pixel-by-pixel.
  * Size mismatches are handled by padding both images to the larger width and height (white fill), then comparing.
+ *
+ * When `cwd` is provided, region masks defined in `.codeloop/baseline_masks.json`
+ * for the matching screen are applied to BOTH buffers before pixelmatch.
+ * This neutralises dynamic UI regions (timestamps, avatars, ads).
  */
-export declare function compareScreenshot(screenshotPath: string, baselinePath: string, diffOutputPath: string, threshold?: number): DiffResult;
+export declare function compareScreenshot(screenshotPath: string, baselinePath: string, diffOutputPath: string, threshold?: number, cwd?: string): DiffResult;
 /**
  * Compare every PNG in `screenshotsDir` to the same filename under `baselinesDir`.
  * Writes diff images to `diffsDir` using the same base filename.
  */
-export declare function diffAllScreenshots(screenshotsDir: string, baselinesDir: string, diffsDir: string, threshold?: number): ScreenshotDiffSummary;
+export declare function diffAllScreenshots(screenshotsDir: string, baselinesDir: string, diffsDir: string, threshold?: number, cwd?: string): ScreenshotDiffSummary;
 /**
  * Copy current screenshots into `baselinesDir` (creates the directory if needed).
  * If `screens` is set, only those screen names (without `.png`) are updated; otherwise all PNGs are copied.

package/dist/evidence/screenshot_diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot_diff.d.ts","sourceRoot":"","sources":["../../src/evidence/screenshot_diff.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAqDD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,MAA0B,GACpC,UAAU,CAmCZ;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAA0B,GACpC,qBAAqB,CA+CvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,EAAE,CAwBV"}
+{"version":3,"file":"screenshot_diff.d.ts","sourceRoot":"","sources":["../../src/evidence/screenshot_diff.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAqDD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,GAAE,MAA0B,EACrC,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,CAoEZ;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAA0B,EACrC,GAAG,CAAC,EAAE,MAAM,GACX,qBAAqB,CA+CvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,MAAM,EAAE,CAwBV"}

package/dist/evidence/screenshot_diff.js

@@ -2,6 +2,7 @@ import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, } from "fs";
 import { join, basename, dirname } from "path";
+import { loadMasks, getMaskForScreen, applyMaskToBuffer, } from "./baseline_governance.js";
 const DEFAULT_THRESHOLD = 0.1;
 function screenNameFromPath(filePath) {
     const base = basename(filePath);
@@ -42,8 +43,12 @@ function prepareCompareBuffers(a, b) {
 /**
  * Compare two PNG images pixel-by-pixel.
  * Size mismatches are handled by padding both images to the larger width and height (white fill), then comparing.
+ *
+ * When `cwd` is provided, region masks defined in `.codeloop/baseline_masks.json`
+ * for the matching screen are applied to BOTH buffers before pixelmatch.
+ * This neutralises dynamic UI regions (timestamps, avatars, ads).
  */
-export function compareScreenshot(screenshotPath, baselinePath, diffOutputPath, threshold = DEFAULT_THRESHOLD) {
+export function compareScreenshot(screenshotPath, baselinePath, diffOutputPath, threshold = DEFAULT_THRESHOLD, cwd) {
     const screen = screenNameFromPath(screenshotPath);
     if (!existsSync(screenshotPath) || !existsSync(baselinePath)) {
         throw new Error(`compareScreenshot: missing file(s) — screenshot: ${screenshotPath}, baseline: ${baselinePath}`);
@@ -53,6 +58,38 @@ export function compareScreenshot(screenshotPath, baselinePath, diffOutputPath,
     const { width, height, buf1, buf2 } = prepareCompareBuffers(img1, img2);
     const totalPixels = width * height;
     mkdirSync(dirname(diffOutputPath), { recursive: true });
+    // Apply region masks (if any) to both buffers before pixel matching.
+    // Both buffers MUST be masked identically so pixelmatch sees zeros on
+    // both sides of any dynamic region and never counts them as diffs.
+    if (cwd) {
+        const masks = loadMasks(cwd);
+        const regions = getMaskForScreen(masks, screen);
+        if (regions.length > 0) {
+            // Buffers from prepareCompareBuffers may share memory with the source
+            // PNG.data when no padding was needed; clone first to avoid mutating
+            // the original images for downstream consumers.
+            const safeBuf1 = Buffer.from(buf1);
+            const safeBuf2 = Buffer.from(buf2);
+            applyMaskToBuffer(safeBuf1, width, height, regions);
+            applyMaskToBuffer(safeBuf2, width, height, regions);
+            const diff = Buffer.alloc(totalPixels * 4);
+            const diffPixels = pixelmatch(safeBuf1, safeBuf2, diff, width, height, {
+                threshold,
+            });
+            const outPng = new PNG({ width, height });
+            diff.copy(outPng.data);
+            writeFileSync(diffOutputPath, PNG.sync.write(outPng));
+            const diffScore = totalPixels === 0 ? 0 : diffPixels / totalPixels;
+            return {
+                screen,
+                diffScore,
+                diffPixels,
+                totalPixels,
+                diffImagePath: diffOutputPath,
+                baselineExists: true,
+            };
+        }
+    }
     const diff = Buffer.alloc(totalPixels * 4);
     const diffPixels = pixelmatch(buf1, buf2, diff, width, height, {
         threshold,
@@ -74,7 +111,7 @@ export function compareScreenshot(screenshotPath, baselinePath, diffOutputPath,
  * Compare every PNG in `screenshotsDir` to the same filename under `baselinesDir`.
  * Writes diff images to `diffsDir` using the same base filename.
  */
-export function diffAllScreenshots(screenshotsDir, baselinesDir, diffsDir, threshold = DEFAULT_THRESHOLD) {
+export function diffAllScreenshots(screenshotsDir, baselinesDir, diffsDir, threshold = DEFAULT_THRESHOLD, cwd) {
     const pngFiles = listPngFiles(screenshotsDir);
     const results = [];
     let allHaveBaselines = true;
@@ -104,7 +141,7 @@ export function diffAllScreenshots(screenshotsDir, baselinesDir, diffsDir, thres
             continue;
         }
         const diffOutputPath = join(diffsDir, file);
-        const result = compareScreenshot(screenshotPath, baselinePath, diffOutputPath, threshold);
+        const result = compareScreenshot(screenshotPath, baselinePath, diffOutputPath, threshold, cwd);
         results.push(result);
     }
     const screensAboveThreshold = results

package/dist/evidence/screenshot_diff.js.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot_diff.js","sourceRoot":"","sources":["../../src/evidence/screenshot_diff.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAkB/C,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,SAAS,kBAAkB,CAAC,QAAgB;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;AAC7C,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED,kFAAkF;AAClF,SAAS,YAAY,CAAC,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,KAAa,EAAE,MAAc;IAC3F,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAC9B,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,qBAAqB,CAC5B,CAAM,EACN,CAAM;IAEN,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACzF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,IAAI,GACR,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC7G,MAAM,IAAI,GACR,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAE7G,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,cAAsB,EACtB,YAAoB,EACpB,cAAsB,EACtB,YAAoB,iBAAiB;IAErC,MAAM,MAAM,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;IAElD,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,oDAAoD,cAAc,eAAe,YAAY,EAAE,CAChG,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;IAEnC,SAAS,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAExD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE;QAC7D,SAAS;KACV,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvB,aAAa,CAAC,cAAc,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAEtD,MAAM,SAAS,GAAG,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,WAAW,CAAC;IAEnE,OAAO;QACL,MAAM;QACN,SAAS;QACT,UAAU;QACV,WAAW;QACX,aAAa,EAAE,cAAc;QAC7B,cAAc,EAAE,IAAI;KACrB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,cAAsB,EACtB,YAAoB,EACpB,QAAgB,EAChB,YAAoB,iBAAiB;IAErC,MAAM,QAAQ,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,IAAI,gBAAgB,GAAG,IAAI,CAAC;IAE5B,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QAExC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9B,gBAAgB,GAAG,KAAK,CAAC;YACzB,IAAI,WAAW,GAAG,CAAC,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;gBACpC,WAAW,GAAG,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,WAAW,GAAG,CAAC,CAAC;YAClB,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,SAAS,EAAE,CAAC;gBACZ,UAAU,EAAE,CAAC;gBACb,WAAW;gBACX,aAAa,EAAE,IAAI;gBACnB,cAAc,EAAE,KAAK;aACtB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,iBAAiB,CAAC,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;QAC1F,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,MAAM,qBAAqB,GAAG,OAAO;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;SAC1D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAExB,OAAO;QACL,OAAO;QACP,mBAAmB,EAAE,OAAO,CAAC,MAAM;QACnC,cAAc,EAAE,gBAAgB;QAChC,qBAAqB;KACtB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,cAAsB,EACtB,YAAoB,EACpB,OAAkB;IAElB,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAG,OAAO,EAAE,MAAM;QAC3B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzE,CAAC,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAEjC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACtC,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"screenshot_diff.js","sourceRoot":"","sources":["../../src/evidence/screenshot_diff.ts"],"names":[],"mappings":"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"}

package/dist/evidence/visual_attribution.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Visual change attribution — maps visual diffs to the commit, branch,
+ * and section that introduced them. Uses the run lineage index to
+ * correlate diff scores across consecutive runs.
+ */
+export interface VisualAttribution {
+    screen: string;
+    diff_score: number;
+    introduced_by: {
+        run_id: string;
+        commit_sha?: string;
+        branch?: string;
+        section_id?: string;
+        started_at: string;
+    };
+    previous_run_id?: string;
+    previous_diff_score?: number;
+}
+export interface AttributionReport {
+    attributions: VisualAttribution[];
+    total_screens: number;
+    screens_with_changes: number;
+}
+/**
+ * Build a visual attribution report by comparing diff scores across
+ * consecutive runs in the index.
+ */
+export declare function buildAttribution(artifactsBase: string, opts?: {
+    section_id?: string;
+    limit?: number;
+}): AttributionReport;
+//# sourceMappingURL=visual_attribution.d.ts.map

package/dist/evidence/visual_attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual_attribution.d.ts","sourceRoot":"","sources":["../../src/evidence/visual_attribution.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE;QACb,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAiCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE;IACJ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,GACL,iBAAiB,CAuDnB"}

package/dist/evidence/visual_attribution.js

@@ -0,0 +1,88 @@
+/**
+ * Visual change attribution — maps visual diffs to the commit, branch,
+ * and section that introduced them. Uses the run lineage index to
+ * correlate diff scores across consecutive runs.
+ */
+import { loadRunIndex } from "./run_lineage.js";
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join, basename } from "path";
+function loadDiffScores(runDir) {
+    const scores = new Map();
+    const diffsDir = join(runDir, "diffs");
+    if (!existsSync(diffsDir))
+        return scores;
+    const summaryPath = join(runDir, "design_compare_summary.json");
+    if (existsSync(summaryPath)) {
+        try {
+            const summary = JSON.parse(readFileSync(summaryPath, "utf-8"));
+            if (Array.isArray(summary.per_screen)) {
+                for (const s of summary.per_screen) {
+                    if (s.screen && typeof s.score === "number") {
+                        scores.set(s.screen, 1 - s.score);
+                    }
+                }
+            }
+            return scores;
+        }
+        catch { /* fall through to PNG scanning */ }
+    }
+    try {
+        const files = readdirSync(diffsDir).filter((f) => f.endsWith(".png"));
+        for (const f of files) {
+            const screen = basename(f, ".png");
+            scores.set(screen, -1);
+        }
+    }
+    catch { /* empty */ }
+    return scores;
+}
+/**
+ * Build a visual attribution report by comparing diff scores across
+ * consecutive runs in the index.
+ */
+export function buildAttribution(artifactsBase, opts = {}) {
+    const index = loadRunIndex(artifactsBase);
+    let entries = [...index.entries].sort((a, b) => new Date(a.started_at).getTime() - new Date(b.started_at).getTime());
+    if (opts.section_id) {
+        entries = entries.filter((e) => e.section_id === opts.section_id);
+    }
+    const attributions = [];
+    const allScreens = new Set();
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const runDir = join(artifactsBase, entry.run_id);
+        const current = loadDiffScores(runDir);
+        let previous = new Map();
+        if (i > 0) {
+            const prevDir = join(artifactsBase, entries[i - 1].run_id);
+            previous = loadDiffScores(prevDir);
+        }
+        for (const [screen, score] of current.entries()) {
+            allScreens.add(screen);
+            const prevScore = previous.get(screen);
+            if (score > 0 && (prevScore === undefined || prevScore === 0 || score > prevScore * 1.1)) {
+                attributions.push({
+                    screen,
+                    diff_score: score,
+                    introduced_by: {
+                        run_id: entry.run_id,
+                        commit_sha: entry.commit_sha,
+                        branch: entry.branch,
+                        section_id: entry.section_id,
+                        started_at: entry.started_at,
+                    },
+                    previous_run_id: i > 0 ? entries[i - 1].run_id : undefined,
+                    previous_diff_score: prevScore,
+                });
+            }
+        }
+    }
+    const limit = opts.limit ?? 50;
+    attributions.sort((a, b) => b.diff_score - a.diff_score);
+    return {
+        attributions: attributions.slice(0, limit),
+        total_screens: allScreens.size,
+        screens_with_changes: new Set(attributions.map((a) => a.screen)).size,
+    };
+}
+//# sourceMappingURL=visual_attribution.js.map

package/dist/evidence/visual_attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual_attribution.js","sourceRoot":"","sources":["../../src/evidence/visual_attribution.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,6 +7,7 @@ import { join, basename } from "path";
 import { loadConfig } from "./config.js";
 import { validateApiKey, isActivationRequired } from "./auth/api_key.js";
 import { trackUsage } from "./auth/usage_tracker.js";
+import { isLocalMode } from "./auth/local_mode.js";
 import { discoverProjectDir } from "./project-discovery.js";
 function readImageAsBase64(path) {
     if (!existsSync(path))
@@ -59,6 +60,12 @@ const server = new McpServer({
     ].join(" "),
 });
 async function withAuth(fn) {
+    // Local / self-hosted mode (CODELOOP_MODE=local): skip API-key validation
+    // entirely. All cloud-side checks are bypassed; usage events are queued
+    // to disk via trackUsage's local-mode branch.
+    if (isLocalMode()) {
+        return fn();
+    }
     const result = await validateApiKey(apiKey);
     if (isActivationRequired(result)) {
         return result;
@@ -490,6 +497,121 @@ Returns: list of affected sections, new states, and recommended next actions.`,
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
+server.tool("codeloop_visual_attribution", TOOL_BOOTSTRAP + `Identify which commit, branch, and section introduced each visual diff. Use this tool when:
+- You want to understand why a screenshot diff appeared
+- You need to trace a visual regression to its source commit
+- You want a report of all visual changes across runs
+Returns: list of visual changes attributed to specific commits and sections.`, {
+    section_id: z.string().optional(),
+    limit: z.number().optional(),
+}, async (params) => {
+    const result = await withAuth(async () => {
+        const { buildAttribution } = await import("./evidence/visual_attribution.js");
+        const { getArtifactsBaseDir } = await import("./evidence/artifacts.js");
+        return buildAttribution(getArtifactsBaseDir(projectDir), {
+            section_id: params.section_id,
+            limit: params.limit,
+        });
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("codeloop_generate_spec", TOOL_BOOTSTRAP + `Generate a design specification from Figma design tokens. Use this tool when:
+- A .codeloop/figma.json exists and you want to extract colors, typography, and spacing tokens
+- You need to create docs/specs/design_tokens.json and docs/ui_rules.md from the Figma file
+- You want to enforce design consistency by comparing code against extracted tokens
+Returns: extracted tokens, generated file paths, and any errors from the Figma API.`, {}, async () => {
+    const result = await withAuth(async () => {
+        const { generateSpec } = await import("./runners/figma_spec_generator.js");
+        return generateSpec(projectDir);
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("codeloop_list_env_presets", TOOL_BOOTSTRAP + `List available environment normalization presets. Use this tool when:
+- You need to know available viewport sizes (mobile_se, tablet_portrait, desktop_1920, etc.)
+- You want to configure network throttling (3g, 4g, wifi, offline)
+- You need locale/timezone presets (en_us, ja_jp, de_de, etc.)
+- You want to see simulator targets (iphone_15, pixel_7, etc.)
+Returns: lists of named presets for viewports, networks, locales, simulators, seed data, and API modes.`, {}, async () => {
+    const result = await withAuth(async () => {
+        const { listPresets } = await import("./environment/presets.js");
+        return listPresets();
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("codeloop_run_history", TOOL_BOOTSTRAP + `Query the run history for this project. Use this tool when:
+- You need to review past verification runs and their outcomes
+- You want to track confidence trends over time
+- You need to find a specific run by section, branch, or date range
+Returns: list of runs with lineage fields (commit, branch, section, parent run), confidence, and pass/fail counts.`, {
+    section_id: z.string().optional(),
+    branch: z.string().optional(),
+    limit: z.number().optional(),
+    since: z.string().optional(),
+    rebuild_index: z.boolean().optional(),
+}, async (params) => {
+    const result = await withAuth(async () => {
+        const { queryRunHistory, rebuildIndex } = await import("./evidence/run_lineage.js");
+        const { getArtifactsBaseDir } = await import("./evidence/artifacts.js");
+        const base = getArtifactsBaseDir(projectDir);
+        if (params.rebuild_index) {
+            rebuildIndex(base);
+        }
+        return queryRunHistory(base, {
+            section_id: params.section_id,
+            branch: params.branch,
+            limit: params.limit,
+            since: params.since,
+        });
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("codeloop_get_prompt", TOOL_BOOTSTRAP + `Retrieve a context-aware prompt template for the current stage of multi-section app development. Use this tool when:
+- You need guidance on what to do next (planning, implementing, repairing, or integrating)
+- You want a structured prompt for a specific development phase
+- codeloop_section_status or codeloop_diagnose suggested calling this tool
+
+Layers:
+  master_human       — top-level framing when a user goal is first received
+  planning           — translate master spec into an ordered build plan
+  section_implement  — per-section build prompt with acceptance criteria
+  repair             — constrained fix loop when verify/gate fails
+  integration        — cross-section verification at checkpoints
+
+Returns: rendered prompt text with metadata about any missing required variables.`, {
+    layer: z.enum(["master_human", "planning", "section_implement", "repair", "integration"]),
+    context: z.record(z.unknown()).optional(),
+}, async (params) => {
+    const result = await withAuth(async () => {
+        const { getPrompt } = await import("./prompt_manager/index.js");
+        return getPrompt({
+            layer: params.layer,
+            context: params.context ?? {},
+        });
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.tool("codeloop_list_prompts", TOOL_BOOTSTRAP + `List all available prompt template layers and their metadata. Use this tool when:
+- You want to understand what prompt layers are available
+- You need to know the required variables for a specific layer before calling codeloop_get_prompt
+Returns: array of prompt layers with IDs, descriptions, and required variables.`, {}, async () => {
+    const result = await withAuth(async () => {
+        const { describeAllPrompts } = await import("./prompt_manager/index.js");
+        return describeAllPrompts();
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
 server.tool("codeloop_interaction_replay", TOOL_BOOTSTRAP + `Analyze a recorded video of a user interaction flow to verify it completes as expected. Use this tool when:
 - You have recorded yourself interacting with ALL elements of the app via codeloop_start_recording
 - You want to verify that every page loaded, every button worked, every form submitted
@@ -1918,6 +2040,34 @@ project. After it completes, proceed directly with \`codeloop_verify\`.`, {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
+server.tool("codeloop_flush_usage", TOOL_BOOTSTRAP + `Drain the persisted offline usage queue and POST events to the CodeLoop backend.
+Use this tool when:
+- The MCP server was running in local/self-hosted mode and the user has switched to cloud
+- A previous session had networking issues and queued events to disk
+- You want to confirm there is no pending billing data to reconcile
+
+Returns: counts for attempted / succeeded / requeued events and the queue location.`, {
+    project_dir: z.string().optional().describe("Absolute path to the project root. Defaults to CODELOOP_PROJECT_DIR or cwd."),
+}, async (params) => {
+    const cwd = params.project_dir || projectDir;
+    const { flushPersistedUsage } = await import("./auth/usage_tracker.js");
+    const result = await flushPersistedUsage(cwd);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    ...result,
+                    local_mode: isLocalMode(),
+                    project_dir: cwd,
+                }, null, 2),
+            },
+        ],
+    };
+});
+if (isLocalMode()) {
+    console.error(`[CodeLoop] Running in local mode (CODELOOP_MODE=local). API-key validation skipped; usage events queued to .codeloop/offline_queue.json.`);
+}
 // ── Start Server ─────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);