@ijfw/memory-server 1.4.4 → 1.5.1

package/src/lib/a11y-contract.js

@@ -0,0 +1,117 @@
+// a11y-contract.js -- v1.5.0 audit-MED-design-#11.
+//
+// Accessibility as part of the design contract.  Mirrors lighthouse-pillar.js:
+// the actual axe-core run is performed by a peer tool (chrome-devtools-mcp's
+// axe runner, the user's own playwright + @axe-core/playwright, etc.).  This
+// module is the pure-stdlib evaluator that:
+//
+//   1. Reads `a11y_target: <WCAG-id>` + `max_violations: <N>` from UI-SPEC.md
+//      (already parsed by uispec-drift.js → parseUISpec).
+//   2. Takes the raw axe-core result (array of violations) from the caller.
+//   3. Returns {pass, violations, target, count, reason} where pass=false when
+//      violations.length > maxViolations (default 0).
+//
+// Graceful-degrade: missing axe results → pass=null reason='axe-unavailable'.
+//
+// Exports:
+//   - DEFAULT_A11Y_TARGET  -- 'WCAG-2.2-AA'
+//   - DEFAULT_MAX_VIOLATIONS -- 0
+//   - evaluateA11y(axeReport, contract?)
+//   - axePromptFor(url, target)
+
+export const DEFAULT_A11Y_TARGET = 'WCAG-2.2-AA';
+export const DEFAULT_MAX_VIOLATIONS = 0;
+
+/**
+ * Evaluate an axe-core violations report.
+ *
+ * Accepts shapes:
+ *   - axe-core full result: { violations: [...], passes: [...], incomplete: [...] }
+ *   - bare array of violations: [{ id, impact, ... }, ...]
+ *   - { violations: [...] }
+ *
+ * @param {object|Array|null|undefined} axeReport
+ * @param {object} [contract]
+ * @param {string} [contract.target]          a11y_target ID
+ * @param {number} [contract.maxViolations]   max allowed
+ * @param {string[]} [contract.severityFilter]  Only count violations whose
+ *   `impact` is in this set; default ['critical','serious'].  Pass `['*']`
+ *   to count all severities.
+ * @returns {{pass: boolean|null, count: number|null, violations: Array, target: string, reason: string, maxViolations: number, severityFilter: string[]}}
+ */
+export function evaluateA11y(axeReport, contract = {}) {
+  const target = contract.target || DEFAULT_A11Y_TARGET;
+  const maxViolations =
+    typeof contract.maxViolations === 'number' ? contract.maxViolations : DEFAULT_MAX_VIOLATIONS;
+  const severityFilter =
+    Array.isArray(contract.severityFilter) && contract.severityFilter.length > 0
+      ? contract.severityFilter
+      : ['critical', 'serious'];
+
+  if (axeReport == null) {
+    return {
+      pass: null,
+      count: null,
+      violations: [],
+      target,
+      reason: 'axe-unavailable',
+      maxViolations,
+      severityFilter,
+    };
+  }
+
+  const raw = Array.isArray(axeReport)
+    ? axeReport
+    : Array.isArray(axeReport.violations)
+      ? axeReport.violations
+      : null;
+
+  if (!Array.isArray(raw)) {
+    return {
+      pass: null,
+      count: null,
+      violations: [],
+      target,
+      reason: 'violations-array-missing',
+      maxViolations,
+      severityFilter,
+    };
+  }
+
+  const counted = severityFilter.includes('*')
+    ? raw
+    : raw.filter((v) => v && severityFilter.includes(v.impact));
+
+  const pass = counted.length <= maxViolations;
+  const reason = pass
+    ? `${counted.length} violation(s) within budget`
+    : `${counted.length} violation(s) exceed budget ${maxViolations}`;
+
+  return {
+    pass,
+    count: counted.length,
+    violations: counted,
+    target,
+    reason,
+    maxViolations,
+    severityFilter,
+  };
+}
+
+/**
+ * Build the prompt fragment ijfw-ui-auditor uses to run axe-core via
+ * chrome-devtools-mcp (or fallback to @axe-core/cli locally).
+ *
+ * @param {string} url
+ * @param {string} [target]
+ */
+export function axePromptFor(url, target = DEFAULT_A11Y_TARGET) {
+  return [
+    `Run axe-core for ${target} compliance against:`,
+    `  url: ${url}`,
+    'Prefer chrome-devtools-mcp:evaluate_script with the axe-core CDN bundle,',
+    'or run `npx @axe-core/cli ${url}` locally if the peer is installed.',
+    'Pipe the resulting violations[] through evaluateA11y() from',
+    'mcp-server/src/lib/a11y-contract.js.  BLOCK the review if pass=false.',
+  ].join('\n');
+}

package/src/lib/atomic-io.js

@@ -11,7 +11,7 @@
 //   5s default wait with 50ms retry. On timeout returns {status:'locked', pid}.
 
 import { writeFileSync, openSync, closeSync, fsyncSync, renameSync, readFileSync,
-  existsSync, mkdirSync, unlinkSync, statSync, chmodSync } from 'node:fs';
+  existsSync, mkdirSync, unlinkSync, statSync, lstatSync, chmodSync } from 'node:fs';
 import { dirname, resolve as pathResolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { platform } from 'node:os';
@@ -25,15 +25,36 @@ export function writeAtomic(targetPath, data, opts = {}) {
 
   if (ensureDir && !existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
 
-  // Refuse symlinks at target -- supply-chain hygiene per v3 sec 1
+  // Refuse symlinks at target -- supply-chain hygiene per v3 sec 1.
+  //
+  // v1.5.1 H1.3 (audit update-install-trust.md F-COR-1): was `statSync`, which
+  // follows symlinks. On a symlink target's stat, `isSymbolicLink()` always
+  // returns false, so the check was dead code. Fixed to `lstatSync`.
+  //
+  // v1.5.1 H1.3-followup (Trident r18): the throw was nested inside a try/
+  // catch that string-matched `e.message.startsWith('refusing')` to decide
+  // whether to rethrow. Functionally correct but fragile — if the message
+  // string ever changes the catch swallows the symlink refusal. Restructured
+  // so the throw is OUTSIDE any try/catch: only the lstatSync probe is
+  // try-wrapped (to tolerate a race where the file vanishes between
+  // existsSync and lstatSync), and the refusal throw runs unconditionally
+  // when isSymbolicLink() is true.
+  //
+  // NB: the rename pattern below (write tmp, rename to abs) is already
+  // symlink-safe at the POSIX `rename(2)` level — rename replaces a symlink
+  // rather than writing through it. This check is defense-in-depth: it makes
+  // symlink-replacement an explicit refusal instead of a silent overwrite.
   if (existsSync(abs)) {
+    let st = null;
     try {
-      const st = statSync(abs);
-      if (st.isSymbolicLink && st.isSymbolicLink()) {
-        throw new Error(`refusing to overwrite symlink at ${abs}`);
-      }
-    } catch (e) {
-      if (e.message.startsWith('refusing')) throw e;
+      st = lstatSync(abs);
+    } catch {
+      // Race: file vanished between existsSync and lstatSync. Tolerate —
+      // the subsequent rename will either succeed cleanly or surface its own
+      // error. We do NOT silently allow a symlink overwrite via this path.
+    }
+    if (st && st.isSymbolicLink && st.isSymbolicLink()) {
+      throw new Error(`refusing to overwrite symlink at ${abs}`);
     }
   }
 

package/src/lib/cache-keepalive.js

@@ -0,0 +1,150 @@
+// v1.5.0 audit-MED-tok-M2 — Cache-keepalive heartbeat.
+//
+// Anthropic's ephemeral prompt cache has a 5-minute TTL. A long Trident
+// wave (5+ minutes of sequential calls separated by network/CLI latency)
+// can therefore start LOSING cache hits mid-wave even though every call
+// re-sends the same cache-eligible prefix. A "keepalive" heartbeat keeps
+// the cache warm by sending a tiny dummy request to the same prefix on
+// a configurable interval.
+//
+// This module is OPT-IN and OFF by default. Enable via env:
+//
+//     IJFW_CACHE_KEEPALIVE_MS=60000   # 60s -> fire heartbeat every minute
+//
+// Set to 0 or unset to disable (default).
+//
+// The heartbeat is a NO-OP when:
+//   - env is unset, empty, or non-numeric
+//   - parsed value is ≤ 0 or > 300_000 (5 min cap matches the cache TTL)
+//   - no callback is supplied
+//   - process.env.IJFW_DISABLE_CACHE_KEEPALIVE is truthy (override)
+//
+// Callers receive a `cancel()` function. The cancel is idempotent: calling
+// it twice (or after the heartbeat already finished) is safe.
+//
+// The CALLER supplies the actual "send a tiny request" logic via the
+// `onTick` callback. This keeps the lib zero-dep on api-client.js and lets
+// tests inject a deterministic stub.
+
+// Lower bound is intentionally generous: 1s minimum so a fat-fingered "1"
+// env var doesn't spin the loop tighter than the runtime needs.
+const MIN_INTERVAL_MS = 1_000;
+// Upper bound matches the Anthropic ephemeral-cache TTL. Beyond 5 min the
+// next request would be a fresh-cache call regardless, so the heartbeat
+// has no effect.
+const MAX_INTERVAL_MS = 300_000;
+
+/**
+ * Parse the keepalive interval from env. Returns 0 (disabled) when the env
+ * var is missing, unparseable, or out of bounds — never throws.
+ *
+ * @param {object} [env] - defaults to process.env
+ * @returns {number}      - interval in ms; 0 means disabled
+ */
+export function parseKeepaliveInterval(env = process.env) {
+  if (env.IJFW_DISABLE_CACHE_KEEPALIVE && env.IJFW_DISABLE_CACHE_KEEPALIVE !== 'false' && env.IJFW_DISABLE_CACHE_KEEPALIVE !== '0') {
+    return 0;
+  }
+  const raw = env.IJFW_CACHE_KEEPALIVE_MS;
+  if (raw === undefined || raw === null || raw === '') return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 0;
+  if (n < MIN_INTERVAL_MS) return 0;
+  if (n > MAX_INTERVAL_MS) return MAX_INTERVAL_MS;
+  return Math.floor(n);
+}
+
+/**
+ * Start a keepalive heartbeat. Returns a cancel function (idempotent).
+ *
+ * Contract:
+ *   - When `intervalMs === 0` or `onTick` is not a function, returns a
+ *     no-op cancel so the caller never has to branch on enable/disable.
+ *   - The heartbeat NEVER throws back to the caller; onTick errors are
+ *     swallowed (and optionally surfaced via `onError`) so a transient
+ *     network blip during keepalive can't crash the Trident wave.
+ *   - The timer is `.unref()`'d so it never holds the event loop open.
+ *
+ * @param {object} args
+ * @param {number} args.intervalMs           - 0 = disabled, else MIN..MAX
+ * @param {() => Promise<void>|void} args.onTick   - sender; runs each interval
+ * @param {(err: Error) => void} [args.onError]    - optional error sink
+ * @param {AbortSignal} [args.signal]              - external cancel propagation
+ * @returns {{ cancel: () => void, isActive: () => boolean, ticks: () => number }}
+ */
+export function startKeepalive({ intervalMs, onTick, onError, signal } = {}) {
+  const noop = { cancel: () => {}, isActive: () => false, ticks: () => 0 };
+
+  if (typeof intervalMs !== 'number' || intervalMs <= 0) return noop;
+  if (typeof onTick !== 'function') return noop;
+  if (signal && signal.aborted) return noop;
+
+  let tickCount = 0;
+  let cancelled = false;
+  let timer = null;
+  let running = false;
+
+  const fire = async () => {
+    if (cancelled) return;
+    if (running) return; // overlap guard — if the previous tick still in flight, skip
+    running = true;
+    tickCount++;
+    try {
+      await onTick();
+    } catch (err) {
+      if (typeof onError === 'function') {
+        try { onError(err); } catch { /* swallow */ }
+      }
+    } finally {
+      running = false;
+    }
+  };
+
+  // Use setInterval (not setTimeout chain) so a slow onTick can't drift the
+  // schedule indefinitely; combined with the `running` overlap guard, the
+  // worst case is "skipped tick" rather than "overlapping ticks".
+  timer = setInterval(fire, intervalMs);
+  if (typeof timer.unref === 'function') timer.unref();
+
+  const cancel = () => {
+    if (cancelled) return;
+    cancelled = true;
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  if (signal) {
+    if (signal.aborted) {
+      cancel();
+    } else {
+      signal.addEventListener('abort', cancel, { once: true });
+    }
+  }
+
+  return {
+    cancel,
+    isActive: () => !cancelled,
+    ticks: () => tickCount,
+  };
+}
+
+/**
+ * Convenience wrapper for the common Trident-wave case: read env, start
+ * keepalive (or no-op), and return the cancel handle.
+ *
+ * @param {object} args
+ * @param {() => Promise<void>|void} args.onTick
+ * @param {(err: Error) => void} [args.onError]
+ * @param {AbortSignal} [args.signal]
+ * @param {object} [args.env]
+ * @returns {{ cancel: () => void, isActive: () => boolean, ticks: () => number }}
+ */
+export function startKeepaliveFromEnv({ onTick, onError, signal, env = process.env } = {}) {
+  const intervalMs = parseKeepaliveInterval(env);
+  return startKeepalive({ intervalMs, onTick, onError, signal });
+}
+
+// Constants exported for tests + docs.
+export const KEEPALIVE_BOUNDS = { minIntervalMs: MIN_INTERVAL_MS, maxIntervalMs: MAX_INTERVAL_MS };

package/src/lib/jsonl-rotation.js

@@ -0,0 +1,104 @@
+// F-PRF-1 (audit-MED-teams-#10): JSONL rotation helper.
+//
+// Generic append-only JSONL rotator. When the target file's size crosses a
+// threshold, the rotator:
+//   1. Reads the current file bytes.
+//   2. Gzips them via node:zlib.
+//   3. Writes <prefix>.<YYYY-MM-DD>.jsonl.gz alongside the original (uniquify
+//      with a numeric suffix if the date-stamped archive already exists).
+//   4. Truncates the original to zero bytes.
+//
+// All writes are atomic-friendly (final rename) so concurrent readers either
+// see the full pre-rotation file or the empty post-rotation file -- never a
+// half-written archive.
+//
+// Used by the blackboard event/permission writers + any caller that does
+// `appendFileSync(path, JSON.stringify(entry) + '\n')`. ESM, zero external deps.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { gzipSync } from 'node:zlib';
+
+// Default rotation threshold (4 MB). Configurable per-call.
+export const DEFAULT_ROTATE_SIZE = 4 * 1024 * 1024;
+
+function isoDate(now = new Date()) {
+  // YYYY-MM-DD in UTC for stable archive names across timezones.
+  return now.toISOString().slice(0, 10);
+}
+
+function strippedJsonlName(file) {
+  const base = basename(file);
+  // Trim a trailing .jsonl so callers like events.jsonl rotate to events.<date>.jsonl.gz
+  // (not events.jsonl.<date>.jsonl.gz).
+  return base.endsWith('.jsonl') ? base.slice(0, -'.jsonl'.length) : base;
+}
+
+function archivePath(file, now) {
+  const dir = dirname(file);
+  const stem = strippedJsonlName(file);
+  const date = isoDate(now);
+  let candidate = join(dir, `${stem}.${date}.jsonl.gz`);
+  if (!existsSync(candidate)) return candidate;
+  // Collision (multiple rotations same day) -- append a numeric suffix.
+  for (let i = 1; i < 1000; i += 1) {
+    candidate = join(dir, `${stem}.${date}.${i}.jsonl.gz`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  throw new Error(`jsonl-rotation: too many same-day archives for ${file}`);
+}
+
+/**
+ * Check whether `path` is over the rotation threshold and, if so, archive
+ * it to a gzipped sibling and truncate the original. Returns an object
+ * describing the action -- callers can ignore the result safely.
+ *
+ * options.maxBytes  -- rotate when file size > this. Default 4 MB.
+ * options.now       -- override the date used in the archive name (testing).
+ */
+export function rotateJsonlIfNeeded(path, options = {}) {
+  const maxBytes = Number.isFinite(options.maxBytes) && options.maxBytes > 0
+    ? Math.floor(options.maxBytes)
+    : DEFAULT_ROTATE_SIZE;
+  const now = options.now instanceof Date ? options.now : new Date();
+
+  let stat;
+  try { stat = statSync(path); }
+  catch { return { rotated: false, reason: 'missing' }; }
+  if (!stat.isFile()) return { rotated: false, reason: 'not-a-file' };
+  if (stat.size <= maxBytes) return { rotated: false, reason: 'under-threshold', size: stat.size };
+
+  let bytes;
+  try { bytes = readFileSync(path); }
+  catch (err) { return { rotated: false, reason: 'read-failed', error: String(err?.message || err) }; }
+
+  const dest = archivePath(path, now);
+  const gz = gzipSync(bytes);
+  // Write to a temp file then rename so a partial gzip never appears at the
+  // archive path. Truncation of the live file happens after the rename so
+  // a crash mid-rotation loses at most one batch of pending writes.
+  const tmp = `${dest}.tmp`;
+  const destDir = dirname(dest);
+  if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+  writeFileSync(tmp, gz, { mode: 0o600 });
+  try { renameSync(tmp, dest); }
+  catch (err) {
+    try { unlinkSync(tmp); } catch {}
+    return { rotated: false, reason: 'rename-failed', error: String(err?.message || err) };
+  }
+  // Truncate the original. writeFileSync('') replaces the inode contents in
+  // place; readers that opened the fd before the rotation keep their view.
+  writeFileSync(path, '', { mode: 0o600 });
+  return { rotated: true, archive: dest, archivedBytes: bytes.length, gzippedBytes: gz.length };
+}
+
+/**
+ * Convenience wrapper: rotateJsonlIfNeeded(path, options) then append `line`
+ * with a trailing newline. Used by event/permission writers that already
+ * batch their own JSON.stringify.
+ */
+export function appendJsonlWithRotation(path, line, options = {}) {
+  const result = rotateJsonlIfNeeded(path, options);
+  // Caller still appends; we just signal whether rotation fired.
+  return result;
+}

package/src/lib/lighthouse-pillar.js

@@ -0,0 +1,121 @@
+// lighthouse-pillar.js -- v1.5.0 audit-MED-design-#7.
+//
+// Mandatory Lighthouse pillar for the IJFW UI-review pipeline.
+//
+// Wraps a chrome-devtools-mcp `lighthouse_audit` result and returns a
+// deterministic PASS / FAIL verdict per the audit MED:
+//
+//   FAIL if LCP > 2.5s  OR  CLS > 0.1
+//   PASS otherwise.
+//
+// The actual MCP call is made by the caller (auditor agent or workflow
+// dispatcher) because IJFW core has zero external deps.  This module is a
+// pure-stdlib evaluator + a result-shape contract the auditor can rely on.
+//
+// Exports:
+//   - evaluateLighthouse(report, opts?)   -> {pass, lcpMs, clsScore, reason, thresholds}
+//   - LIGHTHOUSE_THRESHOLDS               -- default LCP/CLS cutoffs
+//
+// Graceful-degrade: if `report` is null, undefined, or missing the relevant
+// audits, returns {pass: null, reason: 'lighthouse-unavailable'}.  Callers
+// treat null verdict as "skip" (no peer tool installed) rather than FAIL.
+
+/** Default WCAG/Core-Web-Vitals thresholds. */
+export const LIGHTHOUSE_THRESHOLDS = Object.freeze({
+  lcpMs: 2500,       // Largest Contentful Paint, milliseconds
+  clsScore: 0.1,     // Cumulative Layout Shift, unitless
+});
+
+/**
+ * Evaluate a Lighthouse audit report against IJFW's CWV gates.
+ *
+ * Accepts several shapes for robustness:
+ *   - The raw Lighthouse JSON: { audits: { 'largest-contentful-paint': { numericValue }, 'cumulative-layout-shift': { numericValue } } }
+ *   - A pre-extracted summary: { lcpMs, clsScore }
+ *   - A chrome-devtools-mcp wrapper: { lighthouse: <raw>, ... }
+ *
+ * @param {object|null|undefined} report
+ * @param {object} [opts]
+ * @param {number} [opts.lcpMs]    Override LCP threshold (ms)
+ * @param {number} [opts.clsScore] Override CLS threshold
+ * @returns {{pass: boolean|null, lcpMs: number|null, clsScore: number|null, reason: string, thresholds: typeof LIGHTHOUSE_THRESHOLDS}}
+ */
+export function evaluateLighthouse(report, opts = {}) {
+  const thresholds = {
+    lcpMs: typeof opts.lcpMs === 'number' ? opts.lcpMs : LIGHTHOUSE_THRESHOLDS.lcpMs,
+    clsScore: typeof opts.clsScore === 'number' ? opts.clsScore : LIGHTHOUSE_THRESHOLDS.clsScore,
+  };
+
+  if (report == null) {
+    return { pass: null, lcpMs: null, clsScore: null, reason: 'lighthouse-unavailable', thresholds };
+  }
+
+  const { lcpMs, clsScore } = extractMetrics(report);
+
+  if (lcpMs == null && clsScore == null) {
+    return { pass: null, lcpMs: null, clsScore: null, reason: 'metrics-missing', thresholds };
+  }
+
+  const reasons = [];
+  let pass = true;
+  if (lcpMs != null && lcpMs > thresholds.lcpMs) {
+    pass = false;
+    reasons.push(`LCP ${Math.round(lcpMs)}ms > ${thresholds.lcpMs}ms`);
+  }
+  if (clsScore != null && clsScore > thresholds.clsScore) {
+    pass = false;
+    reasons.push(`CLS ${clsScore.toFixed(3)} > ${thresholds.clsScore}`);
+  }
+
+  return {
+    pass,
+    lcpMs: lcpMs ?? null,
+    clsScore: clsScore ?? null,
+    reason: pass ? 'within-budget' : reasons.join('; '),
+    thresholds,
+  };
+}
+
+function extractMetrics(report) {
+  // Pre-extracted summary form.
+  if (typeof report.lcpMs === 'number' || typeof report.clsScore === 'number') {
+    return {
+      lcpMs: typeof report.lcpMs === 'number' ? report.lcpMs : null,
+      clsScore: typeof report.clsScore === 'number' ? report.clsScore : null,
+    };
+  }
+  // chrome-devtools-mcp wrapper form.
+  const lh = report.lighthouse || report.lhr || report;
+  const audits = lh && typeof lh === 'object' ? lh.audits : null;
+  if (!audits || typeof audits !== 'object') {
+    return { lcpMs: null, clsScore: null };
+  }
+  const lcpAudit = audits['largest-contentful-paint'] || audits.lcp;
+  const clsAudit = audits['cumulative-layout-shift'] || audits.cls;
+  const lcpMs =
+    lcpAudit && typeof lcpAudit.numericValue === 'number'
+      ? lcpAudit.numericValue
+      : null;
+  const clsScore =
+    clsAudit && typeof clsAudit.numericValue === 'number'
+      ? clsAudit.numericValue
+      : null;
+  return { lcpMs, clsScore };
+}
+
+/**
+ * Build the prompt fragment the ijfw-ui-auditor agent uses to invoke the MCP
+ * tool.  Kept here so the verdict-logic and the call-site stay co-located.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function lighthousePromptFor(url) {
+  return [
+    'Invoke chrome-devtools-mcp:lighthouse_audit on the dev server URL:',
+    `  url: ${url}`,
+    'Then pipe the result through evaluateLighthouse() from',
+    'mcp-server/src/lib/lighthouse-pillar.js.  FAIL the review if the',
+    'returned `pass` is false; record `reason` in UI-REVIEW.md.',
+  ].join('\n');
+}

package/src/lib/llm-call.js

@@ -0,0 +1,121 @@
+// mcp-server/src/lib/llm-call.js
+// IJFW v1.5.0 -- minimal LLM-call wrapper for the M2 auto-linker.
+//
+// Defaults to Claude Haiku 4.5 (claude-haiku-4-5-20251001). Env overrides:
+//   IJFW_AUTOLINK_OFF=1                 -> never call; return skipped.
+//   IJFW_AUTOLINK_BUDGET_USD=<float>    -> per-day cap; 0 disables.
+//   IJFW_AUTOLINK_MODEL=<model-id>      -> override default.
+//   IJFW_AUTOLINK_API_KEY=<key>         -> if absent, falls back to
+//                                          ANTHROPIC_API_KEY; if both
+//                                          absent, returns skipped=no_key.
+//
+// Budget tracking is a simple JSONL spend log at
+// `<repoRoot>/.ijfw/.llm-spend.jsonl` rolled by day. Approximate USD per
+// call uses Haiku pricing.
+
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+const DEFAULT_PRICE_IN = 0.80;
+const DEFAULT_PRICE_OUT = 4.00;
+
+function isoDay(d = new Date()) {
+  return d.toISOString().slice(0, 10);
+}
+
+function spendPath(root) {
+  return join(root, '.ijfw', '.llm-spend.jsonl');
+}
+
+function todaySpend(root) {
+  const p = spendPath(root);
+  if (!existsSync(p)) return 0;
+  const day = isoDay();
+  let usd = 0;
+  for (const line of readFileSync(p, 'utf8').split('\n')) {
+    if (!line) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row.day === day && typeof row.usd === 'number') usd += row.usd;
+    } catch { /* skip corrupt */ }
+  }
+  return usd;
+}
+
+function recordSpend(root, usd, model, inTok, outTok) {
+  const p = spendPath(root);
+  mkdirSync(dirname(p), { recursive: true });
+  appendFileSync(
+    p,
+    JSON.stringify({
+      day: isoDay(),
+      ts: new Date().toISOString(),
+      model,
+      input_tokens: inTok,
+      output_tokens: outTok,
+      usd,
+    }) + '\n',
+  );
+}
+
+export async function llmCall({
+  system,
+  user,
+  maxTokens = 512,
+  root = process.cwd(),
+  model,
+  apiKey,
+} = {}) {
+  if (process.env.IJFW_AUTOLINK_OFF === '1') {
+    return { skipped: true, reason: 'autolink_off' };
+  }
+  const budget = process.env.IJFW_AUTOLINK_BUDGET_USD;
+  if (budget !== undefined && Number(budget) <= 0) {
+    return { skipped: true, reason: 'budget_exhausted' };
+  }
+  if (budget !== undefined && todaySpend(root) >= Number(budget)) {
+    return { skipped: true, reason: 'budget_exhausted' };
+  }
+  const key = apiKey || process.env.IJFW_AUTOLINK_API_KEY || process.env.ANTHROPIC_API_KEY;
+  if (!key) return { skipped: true, reason: 'no_key' };
+  const m = model || process.env.IJFW_AUTOLINK_MODEL || DEFAULT_MODEL;
+  const priceIn = Number(process.env.IJFW_AUTOLINK_PRICE_IN_PER_MTOK || DEFAULT_PRICE_IN);
+  const priceOut = Number(process.env.IJFW_AUTOLINK_PRICE_OUT_PER_MTOK || DEFAULT_PRICE_OUT);
+
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-api-key': key,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: m,
+      max_tokens: maxTokens,
+      system,
+      messages: [{ role: 'user', content: user }],
+    }),
+  });
+  if (!res.ok) return { skipped: true, reason: `http_${res.status}` };
+  const json = await res.json();
+  const text = (json.content || []).map((c) => c.text || '').join('');
+  const inTok = json.usage?.input_tokens || 0;
+  const outTok = json.usage?.output_tokens || 0;
+  const usd = (inTok / 1e6) * priceIn + (outTok / 1e6) * priceOut;
+  recordSpend(root, usd, m, inTok, outTok);
+  return { skipped: false, text, usd, model: m, input_tokens: inTok, output_tokens: outTok };
+}
+
+export function parseLlmJsonResponse(raw) {
+  if (typeof raw !== 'string') throw new Error('parseLlmJsonResponse: input not a string');
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const body = fenced ? fenced[1].trim() : raw.trim();
+  try {
+    return JSON.parse(body);
+  } catch (e) {
+    throw new Error(`parseLlmJsonResponse: parse failed -- ${e.message}`);
+  }
+}
+
+export default { llmCall, parseLlmJsonResponse };