@ngockhoale/ukit 1.6.4 → 1.6.6

package/templates/.claude/ukit/index/extract-image.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+/**
+ * extract-image.mjs — materialise transcript images so a subagent can Read them.
+ *
+ * A spawned subagent receives TEXT ONLY and does not inherit the parent's image
+ * blocks, so pasted images are invisible unless this script first decodes them
+ * to disk. This is the single home of the sha256 key: `pending-<sha>` markers
+ * (written by --mark-pending) and `<sha>.<ext>` image files (written by a normal
+ * extract) MUST agree exactly, or the TASK-008 gate deadlocks forever. Both
+ * paths call the same hashPayload() function on the exact base64 string as it
+ * appears in the transcript — no trimming, no normalising, no decoding first.
+ *
+ * Usage:
+ *   node extract-image.mjs [options]
+ *     --session <path>   explicit transcript .jsonl (default: auto-discover)
+ *     --detect           count only; decode nothing, write nothing
+ *     --mark-pending     write pending-<sha>.json markers; NO decode, NO image write
+ *     --json             machine-readable stdout
+ *     --limit <n>        max images, default 3 (most recent first)
+ *     --out <dir>        default <projectRoot>/.ukit/storage/cache/vision
+ *     --session-id <id>  marker subdirectory (default: from transcript filename, else "default")
+ *     --ref <path|url>   repeatable; arm a marker for an image named in the prompt text
+ *                        rather than pasted. Pasted images hash their base64 payload;
+ *                        a local file hashes its bytes and a URL hashes the URL string.
+ *                        Different domains, but the sha only has to be stable and unique.
+ *
+ * Builtins only (fs, path, crypto, os). No dependencies, no network calls.
+ * Never throws: always exits 0, including "no images found" and missing session file.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const MEDIA_EXT = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+};
+
+const DEFAULT_LIMIT = 3;
+const MAX_DECODED_BYTES = 10 * 1024 * 1024; // 10 MB
+const RETENTION_MAX_IMAGE_FILES = 20;
+const MARKER_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * Single shared hash function for both the image filename sha and the
+ * pending-<sha> marker sha. Hashes the base64 payload string EXACTLY as it
+ * appears in the transcript (no trim/normalise/decode) so the two paths can
+ * never diverge.
+ */
+export function hashPayload(base64Data) {
+  return crypto.createHash('sha256').update(base64Data, 'utf8').digest('hex');
+}
+
+const REF_EXT_RE = /\.(png|jpe?g|gif|webp|bmp)(?:[?#].*)?$/i;
+const EXT_MEDIA = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+};
+
+/**
+ * Turns --ref values (local paths and URLs named in the prompt) into markers.
+ *
+ * Pasted images hash their base64 payload; these have no payload to hash, so a local
+ * file hashes its bytes and a URL hashes the URL string. The domains differ, but the
+ * sha only has to be stable and unique — the gate matches pending-<sha> to
+ * analyzed-<sha> by filename and never recomputes it. Still routed through
+ * crypto.createHash here so this file remains the single owner of the hash.
+ *
+ * Silently drops anything that is not an image ref or cannot be read: this feeds a
+ * hook that must never wedge a prompt.
+ */
+export function resolveRefs(values) {
+  const out = [];
+  const seen = new Set();
+  for (const value of values ?? []) {
+    const match = REF_EXT_RE.exec(value);
+    if (!match) continue;
+    const mediaType = EXT_MEDIA[match[1].toLowerCase()] ?? 'application/octet-stream';
+    const isUrl = /^https?:\/\//i.test(value);
+    let sha;
+    if (isUrl) {
+      sha = crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+    } else {
+      let bytes;
+      try {
+        bytes = fs.readFileSync(path.resolve(value));
+      } catch {
+        continue; // path named in the prompt but not present on disk: nothing to analyse
+      }
+      if (bytes.length > MAX_DECODED_BYTES) continue;
+      sha = crypto.createHash('sha256').update(bytes).digest('hex');
+    }
+    if (seen.has(sha)) continue;
+    seen.add(sha);
+    out.push({ sha, mediaType, source: isUrl ? 'url' : 'path', value });
+  }
+  return out;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    session: null,
+    detect: false,
+    markPending: false,
+    json: false,
+    limit: DEFAULT_LIMIT,
+    out: null,
+    sessionId: null,
+    refs: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--session') {
+      opts.session = argv[i + 1];
+      i += 1;
+    } else if (arg === '--detect') {
+      opts.detect = true;
+    } else if (arg === '--mark-pending') {
+      opts.markPending = true;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--limit') {
+      const n = Number(argv[i + 1]);
+      if (Number.isFinite(n) && n > 0) opts.limit = Math.floor(n);
+      i += 1;
+    } else if (arg === '--out') {
+      opts.out = argv[i + 1];
+      i += 1;
+    } else if (arg === '--session-id') {
+      opts.sessionId = argv[i + 1];
+      i += 1;
+    } else if (arg === '--ref') {
+      const value = argv[i + 1];
+      if (typeof value === 'string' && value.trim()) opts.refs.push(value.trim());
+      i += 1;
+    }
+  }
+  return opts;
+}
+
+function slugifyCwd(cwd) {
+  return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+function discoverSessionFile(cwd) {
+  const slug = slugifyCwd(cwd);
+  const dir = path.join(os.homedir(), '.claude', 'projects', slug);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  let newestPath = null;
+  let newestMtimeMs = -Infinity;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+    const full = path.join(dir, entry.name);
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.mtimeMs > newestMtimeMs) {
+      newestMtimeMs = stat.mtimeMs;
+      newestPath = full;
+    }
+  }
+  return newestPath;
+}
+
+function readLines(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+  return raw.split('\n').filter((line) => line.trim().length > 0);
+}
+
+/**
+ * Parses each JSONL line independently. A malformed line is skipped via its
+ * own try/catch and never throws out to the caller.
+ */
+function extractImageBlocks(lines) {
+  const blocks = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    try {
+      const obj = JSON.parse(lines[i]);
+      const content = obj?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block?.type !== 'image') continue;
+        const source = block.source;
+        if (!source || source.type !== 'base64') continue;
+        const mediaType = source.media_type;
+        const data = source.data;
+        if (typeof mediaType !== 'string' || typeof data !== 'string' || !data) continue;
+        blocks.push({ mediaType, data, lineIndex: i });
+      }
+    } catch {
+      // malformed line: skip and continue
+    }
+  }
+  return blocks;
+}
+
+/**
+ * Filters to the allowlisted media types, dedupes by sha (content-addressed —
+ * same payload always produces the same key), and orders most-recent-first.
+ */
+function selectImages(blocks, limit) {
+  const allowed = blocks.filter((b) => MEDIA_EXT[b.mediaType]);
+  const bySha = new Map();
+  for (const block of allowed) {
+    const sha = hashPayload(block.data);
+    bySha.set(sha, { sha, mediaType: block.mediaType, data: block.data, lineIndex: block.lineIndex });
+  }
+  const deduped = Array.from(bySha.values());
+  deduped.sort((a, b) => b.lineIndex - a.lineIndex);
+  return deduped.slice(0, limit);
+}
+
+function pruneImageFiles(outDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(outDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const imageFiles = entries
+    .filter((e) => e.isFile() && /^[0-9a-f]{64}\.(png|jpg|gif|webp)$/.test(e.name))
+    .map((e) => {
+      const full = path.join(outDir, e.name);
+      let mtimeMs = 0;
+      try {
+        mtimeMs = fs.statSync(full).mtimeMs;
+      } catch {
+        // ignore
+      }
+      return { full, mtimeMs };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const f of imageFiles.slice(RETENTION_MAX_IMAGE_FILES)) {
+    try {
+      fs.unlinkSync(f.full);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function pruneMarkerDirs(outDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(outDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const full = path.join(outDir, entry.name);
+    let mtimeMs;
+    try {
+      mtimeMs = fs.statSync(full).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (now - mtimeMs > MARKER_MAX_AGE_MS) {
+      try {
+        fs.rmSync(full, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+function printResult(opts, result) {
+  if (opts.json) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  console.log(`imageCount: ${result.imageCount}`);
+  for (const img of result.images) {
+    if (img.path) console.log(img.path);
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+
+  const sessionPath = opts.session ? path.resolve(opts.session) : discoverSessionFile(cwd);
+  const outDir = opts.out
+    ? path.resolve(opts.out)
+    : path.join(cwd, '.ukit', 'storage', 'cache', 'vision');
+
+  const sessionId = opts.sessionId
+    || (sessionPath ? path.basename(sessionPath, path.extname(sessionPath)) : 'default');
+
+  const lines = sessionPath ? readLines(sessionPath) : [];
+  const blocks = extractImageBlocks(lines);
+  const selected = selectImages(blocks, opts.limit);
+  const refs = resolveRefs(opts.refs);
+
+  // --detect is report-only, so it must not short-circuit --mark-pending when both are
+  // passed together. vision-router.sh combines them; short-circuiting here would arm
+  // nothing and leave the TASK-008 write gate permanently open.
+  if (opts.detect && !opts.markPending) {
+    printResult(opts, { imageCount: selected.length + refs.length, sessionId, images: [] });
+    return;
+  }
+
+  if (opts.markPending) {
+    const markerDir = path.join(outDir, sessionId);
+    if (selected.length > 0 || refs.length > 0) {
+      try {
+        fs.mkdirSync(markerDir, { recursive: true });
+      } catch (err) {
+        process.stderr.write(`extract-image: failed to create marker dir ${markerDir}: ${err.message}\n`);
+        printResult(opts, { imageCount: 0, sessionId, images: [] });
+        return;
+      }
+    }
+
+    const written = [];
+    for (const img of selected) {
+      const markerPath = path.join(markerDir, `pending-${img.sha}.json`);
+      const marker = { sha: img.sha, mediaType: img.mediaType, ts: Date.now(), sessionId };
+      try {
+        fs.writeFileSync(markerPath, JSON.stringify(marker));
+        written.push({ sha: img.sha, path: markerPath, mediaType: img.mediaType, bytes: 0 });
+      } catch (err) {
+        process.stderr.write(`extract-image: failed to write marker ${markerPath}: ${err.message}\n`);
+      }
+    }
+    for (const ref of refs) {
+      const markerPath = path.join(markerDir, `pending-${ref.sha}.json`);
+      const marker = {
+        sha: ref.sha,
+        mediaType: ref.mediaType,
+        ts: Date.now(),
+        sessionId,
+        source: ref.source,
+        ref: ref.value,
+      };
+      try {
+        fs.writeFileSync(markerPath, JSON.stringify(marker));
+        written.push({ sha: ref.sha, path: markerPath, mediaType: ref.mediaType, bytes: 0, source: ref.source, ref: ref.value });
+      } catch (err) {
+        process.stderr.write(`extract-image: failed to write marker ${markerPath}: ${err.message}\n`);
+      }
+    }
+    pruneMarkerDirs(outDir);
+    printResult(opts, { imageCount: written.length, sessionId, images: written });
+    return;
+  }
+
+  // default: decode + write image files
+  if (selected.length > 0) {
+    try {
+      fs.mkdirSync(outDir, { recursive: true });
+    } catch (err) {
+      process.stderr.write(`extract-image: failed to create out dir ${outDir}: ${err.message}\n`);
+      printResult(opts, { imageCount: 0, sessionId, images: [] });
+      return;
+    }
+  }
+
+  const images = [];
+  for (const img of selected) {
+    let decoded;
+    try {
+      decoded = Buffer.from(img.data, 'base64');
+    } catch (err) {
+      process.stderr.write(`extract-image: failed to decode image (sha=${img.sha}): ${err.message}\n`);
+      continue;
+    }
+    if (decoded.length > MAX_DECODED_BYTES) {
+      process.stderr.write(
+        `extract-image: skipping oversized image (sha=${img.sha}, bytes=${decoded.length} > ${MAX_DECODED_BYTES})\n`
+      );
+      continue;
+    }
+    const ext = MEDIA_EXT[img.mediaType];
+    const filePath = path.join(outDir, `${img.sha}.${ext}`);
+    try {
+      fs.writeFileSync(filePath, decoded);
+    } catch (err) {
+      process.stderr.write(`extract-image: failed to write ${filePath}: ${err.message}\n`);
+      continue;
+    }
+    images.push({ sha: img.sha, path: filePath, mediaType: img.mediaType, bytes: decoded.length });
+  }
+  pruneImageFiles(outDir);
+  printResult(opts, { imageCount: images.length, sessionId, images });
+}
+
+// Only run as a CLI. Importing this module (tests import resolveRefs/hashPayload) must
+// not decode images, write markers, or prune the real cache as a side effect.
+const invokedDirectly = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  try {
+    main();
+    process.exitCode = 0;
+  } catch (err) {
+    process.stderr.write(`extract-image: unexpected error: ${err?.message ?? err}\n`);
+    process.exitCode = 0;
+  }
+}