contextdevkit 1.8.0

package/templates/contextkit/runtime/hooks/session-start.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook (Level >= 1) — injects project context at session start.
+ *
+ * Behavior:
+ *   1. `git fetch origin` silently to surface ahead/behind divergence.
+ *   2. Detects drift from prior sessions (ledgers with unregistered important
+ *      modifications) and emits a banner. Cleans up resolved ledgers.
+ *   3. Includes the latest registered session, the CHANGELOG `[Unreleased]`,
+ *      and active workspace claims when present.
+ *
+ * Constraints: concise output, all errors silent (NEVER block a session),
+ * zero third-party deps.
+ */
+import { rm } from 'node:fs/promises';
+import {
+  digestLatestSession,
+  exists,
+  extractUnreleased,
+  readChangelog,
+  readSessionsIndex,
+  readWorkspaceSummary,
+} from './boot-context-readers.mjs';
+import {
+  activeBranches,
+  checkGitDivergence,
+  getBranch,
+  isGreenfield,
+  predictionsReviewDue,
+  projectName,
+  securityModeDue,
+} from './boot-signals.mjs';
+import {
+  freshLedger,
+  ledgerPathFor,
+  listAllLedgers,
+  pendingImportantPaths,
+  resolveSessionId,
+  wasRegisteredDuringSession,
+  writeLedger,
+} from './ledger.mjs';
+import { getLevel, loadConfigSync } from '../config/load.mjs';
+import { CONTEXT_SNAPSHOT } from '../config/paths.mjs';
+
+const ROOT = process.cwd();
+
+async function readStdin() {
+  return new Promise((res) => {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => res(buf));
+    setTimeout(() => res(buf), 500).unref?.();
+  });
+}
+
+/** A ledger touched within this window may belong to a LIVE concurrent session. */
+const ACTIVE_GRACE_MS = 15 * 60 * 1000;
+
+/** Most recent activity timestamp for a ledger (its start, or its last edit). */
+function lastActivityAt(ledger) {
+  const mods = Array.isArray(ledger.modifications) ? ledger.modifications : [];
+  const lastMod = mods.reduce((mx, m) => (typeof m?.at === 'number' && m.at > mx ? m.at : mx), 0);
+  return Math.max(typeof ledger.startedAt === 'number' ? ledger.startedAt : 0, lastMod);
+}
+
+async function analyzePriorLedgers(currentSessionId) {
+  const all = await listAllLedgers();
+  const drift = [];
+  const now = Date.now();
+  for (const { sessionId, ledger } of all) {
+    if (sessionId === currentSessionId) continue;
+    const mods = Array.isArray(ledger.modifications) ? ledger.modifications : [];
+    const registered = ledger.registered || wasRegisteredDuringSession(ledger);
+    const pending = pendingImportantPaths(ledger);
+    if (registered || pending.length === 0) {
+      // Reap a resolved ledger — but NEVER an empty one, nor one touched within the
+      // grace window: that may be a LIVE concurrent session that just wrote its
+      // fresh (empty) ledger. Deleting it was the race (008): a booting session
+      // wiped a live peer. The owning session cleans up its own ledger.
+      const maybeLive = mods.length === 0 || now - lastActivityAt(ledger) < ACTIVE_GRACE_MS;
+      if (!maybeLive) await rm(ledgerPathFor(sessionId), { force: true }).catch(() => {});
+      continue;
+    }
+    drift.push({ sessionId, paths: pending });
+  }
+  return drift;
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    /* keep empty */
+  }
+  const sessionId = resolveSessionId(payload);
+  const level = getLevel(ROOT);
+  const needsSetup = loadConfigSync(ROOT)?.setup?.completed !== true;
+
+  // Fresh ledger for this session (Level >= 2 uses it; harmless at L1).
+  await writeLedger(sessionId, freshLedger(sessionId));
+
+  const drift = level >= 2 ? await analyzePriorLedgers(sessionId) : [];
+  const sessions = await readSessionsIndex(ROOT);
+  const changelog = await readChangelog(ROOT);
+  const latest = await digestLatestSession(ROOT);
+  const workspace = level >= 3 ? await readWorkspaceSummary(ROOT) : null;
+  const branches = level >= 3 ? activeBranches(ROOT, getBranch(ROOT)) : null;
+  const hasSnapshot = await exists(ROOT, CONTEXT_SNAPSHOT);
+  const divergence = checkGitDivergence(ROOT);
+  const secDue = securityModeDue(ROOT);
+  const predDue = predictionsReviewDue(ROOT);
+
+  if (!needsSetup && !sessions && !changelog && !latest && drift.length === 0 && !secDue && !predDue) return;
+
+  const out = [];
+  out.push('<project-context-boot>');
+  out.push(`# 📚 Boot context — ${await projectName(ROOT)}`);
+  out.push('');
+  out.push(`Session id: \`${sessionId.slice(0, 16)}\` · Branch: \`${getBranch(ROOT)}\` · ContextDevKit level: \`L${level}\``);
+  out.push('');
+
+  if (needsSetup) {
+    const empty = isGreenfield(ROOT);
+    out.push('## 🚀 First run — ContextDevKit not configured yet');
+    out.push('');
+    if (empty) {
+      out.push('This folder looks **empty (no code yet)**. Run **`/aidevtool-from0`** — it interviews you');
+      out.push('about the product, suggests/refines the stack, drafts a roadmap, adopts the best-practices');
+      out.push('constitution, and seeds the DevPipeline. From zero, the kit stays ACTIVE: it keeps');
+      out.push('suggesting the next practice/level as the product takes shape.');
+    } else {
+      out.push('This project already has code. Run **`/setupcontextdevkit`** — it inspects the project, tunes');
+      out.push('the config to this stack, fills in `CLAUDE.md`, flags high-risk paths, installs what is');
+      out.push('needed, and records a baseline ADR. (Empty project instead? use `/aidevtool-from0`.)');
+    }
+    out.push('');
+  }
+
+  if (loadConfigSync(ROOT)?.practices?.active === true) {
+    out.push('## 🧠 Best-practices skill is ACTIVE');
+    out.push('');
+    out.push('Honor `contextkit/best-practices.md` (file-size budget, intelligent refactor by responsibility,');
+    out.push('SoC, naming, docs). Run `/analyze-code-ia-practices` to audit + get refactor proposals.');
+    out.push('');
+  }
+
+  if (loadConfigSync(ROOT)?.behaviors?.active === true) {
+    out.push('## 🧭 Behavioral discipline is ACTIVE');
+    out.push('');
+    out.push('Honor `contextkit/behaviors.md` while coding: **think before coding** (surface assumptions,');
+    out.push('ask when ambiguous), **simplicity first**, **surgical changes** (match the surrounding style,');
+    out.push('no drive-by refactor), **goal-driven** (reproduce-test first, loop to green).');
+    out.push('');
+  }
+
+  if (secDue) {
+    out.push('## 🛡️ Security mode — time for a deep sweep');
+    out.push('');
+    out.push(`**${secDue} sessions** in. Run **\`/deep-analysis\`** — full code + security + deps + bug`);
+    out.push('sweep → report → ADRs → backlog. (Active by default; disable via `securityMode.active`.)');
+    out.push('');
+  }
+
+  if (predDue) {
+    out.push('## 🔮 Predictions — close the loop');
+    out.push('');
+    out.push(`**${predDue} sessions** in with **unreviewed** \`/simulate-impact\` predictions. Run`);
+    out.push('**`/predictions-review`** to fill their *Actual* section (predicted vs actual). It also');
+    out.push('auto-runs at `/log-session`; disable the reminder via `predictionsReview.active`.');
+    out.push('');
+  }
+
+  if (divergence && (divergence.ahead > 0 || divergence.behind > 0)) {
+    out.push('## 🔄 Git status vs upstream');
+    out.push('');
+    if (divergence.behind > 0) out.push(`- ⚠️  Behind upstream by **${divergence.behind}** commit(s). Consider \`git pull\` before editing.`);
+    if (divergence.ahead > 0) out.push(`- ℹ️  Ahead of upstream by **${divergence.ahead}** commit(s) (unpushed).`);
+    out.push('');
+  }
+
+  if (drift.length > 0) {
+    out.push('## 🚨 Drift from previous session(s)');
+    out.push('');
+    for (const d of drift) {
+      out.push(`Session \`${d.sessionId.slice(0, 8)}\` ended without \`/log-session\` and left ${d.paths.length} important file(s) modified:`);
+      for (const p of d.paths.slice(0, 8)) out.push(`  - ${p}`);
+      if (d.paths.length > 8) out.push(`  (… and ${d.paths.length - 8} more)`);
+      out.push('');
+    }
+    out.push('If those changes still matter, **offer to retroactively register them** before new work.');
+    out.push('');
+  }
+
+  if (workspace) {
+    out.push('## 👥 Active workspace claims');
+    out.push('');
+    out.push(workspace);
+    out.push('');
+  }
+
+  if (branches) {
+    out.push('## 🌿 Other active branches (parallel work)');
+    out.push('');
+    out.push(branches);
+    out.push('');
+    out.push('If you will touch files another branch changed, coordinate (or `/claim`) — the pre-push');
+    out.push('hook will also block a conflicting push.');
+    out.push('');
+  }
+
+  if (latest) {
+    out.push('## 🗓️ Last registered session');
+    out.push('');
+    out.push(latest.content);
+    if (latest.mode === 'digest') out.push('\n_(digest — open the full log in `contextkit/memory/sessions/` if you need detail) [ADR-0027]_');
+    out.push('');
+  }
+
+  if (changelog) {
+    const unreleased = extractUnreleased(changelog);
+    if (unreleased) {
+      out.push('## 📝 Unreleased changes (CHANGELOG `[Unreleased]`)');
+      out.push('');
+      out.push(unreleased);
+      out.push('');
+    }
+  }
+
+  out.push('## ⚠️ Process rules');
+  out.push('');
+  out.push('1. Read SESSIONS index + relevant ADR before non-trivial changes.');
+  out.push('2. New architectural decision → `/new-adr <title>` BEFORE implementing.');
+  if (level >= 3) out.push('3. Reserve area before parallel work → `/claim <path>`. Free with `/release`.');
+  out.push('4. End of productive session → `/log-session`.');
+  out.push('5. `/state` for a quick state summary at any time.');
+  if (hasSnapshot) out.push('6. `.context-snapshot.md` available for a full-project view.');
+  out.push('</project-context-boot>');
+
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(`[session-start] ${err?.message ?? err}\n`);
+  process.exit(0);
+});

package/templates/contextkit/runtime/hooks/simulate-gate.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook (Level 5) — high-risk path gate.
+ *
+ * Wired with matcher `Edit|Write|MultiEdit`. When the file being edited
+ * matches the `l5.highRiskPaths` allowlist from `contextkit/config.json` AND the
+ * current session's ledger has no covering `/simulate-impact` record, it emits
+ * a `decision: "block"` with instructions.
+ *
+ * Defensive: any error path exits 0 silently. A broken hook MUST NEVER block
+ * real work.
+ *
+ * Bypass: record a deliberate skip by calling `markSimulation` with
+ * `objective: 'BYPASS: <reason>'` and `coveredPaths: [highRiskPath]` — an
+ * auditable escape hatch for trivial edits.
+ */
+import { getLevel, loadConfig } from '../config/load.mjs';
+import { hasSimulationFor, readLedger, resolveSessionId, toRepoRelative } from './ledger.mjs';
+
+const ROOT = process.cwd();
+
+async function readStdin() {
+  return new Promise((res) => {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => res(buf));
+    setTimeout(() => res(buf), 500).unref?.();
+  });
+}
+
+function extractFilePath(payload) {
+  const tool = payload?.tool_name;
+  const input = payload?.tool_input ?? {};
+  if ((tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') && typeof input.file_path === 'string') {
+    return input.file_path;
+  }
+  return null;
+}
+
+/** Returns the matching high-risk entry (or null). Dir entries match by prefix. */
+function matchHighRisk(targetPath, highRiskPaths) {
+  if (!Array.isArray(highRiskPaths)) return null;
+  for (const entry of highRiskPaths) {
+    if (typeof entry !== 'string' || entry.length === 0) continue;
+    if (entry.endsWith('/')) {
+      if (targetPath.startsWith(entry)) return entry;
+    } else if (targetPath === entry) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+function buildBlockReason(targetPath, matchedEntry) {
+  return [
+    '🛑 L5 gate — high-risk path detected.',
+    '',
+    'You are about to modify:',
+    `  • ${targetPath}`,
+    '',
+    `That path matches the configured high-risk entry \`${matchedEntry}\` and the`,
+    'current session has no `/simulate-impact` record covering it.',
+    '',
+    'Required next step — pick ONE:',
+    '  1. Run `/simulate-impact "<one-sentence objective>"` first. It produces a',
+    '     Blast Radius Report and marks the ledger, unblocking edits inside the',
+    '     covered paths.',
+    '  2. If this edit is genuinely trivial (typo / comment), record an explicit',
+    '     bypass via markSimulation (objective "BYPASS: <reason>") then retry.',
+    '',
+    'Why the gate exists: high-risk paths (schema, shared contracts, auth surface,',
+    'core services) have outsized blast radius. The gate converts "architecture',
+    'before syntax" from a suggestion into executable governance.',
+  ].join('\n');
+}
+
+async function main() {
+  if (getLevel(ROOT) < 5) return; // Inert below Level 5.
+
+  const raw = await readStdin();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  const filePath = extractFilePath(payload);
+  if (!filePath) return;
+  const targetPath = toRepoRelative(filePath);
+  if (!targetPath) return;
+
+  const config = await loadConfig(ROOT);
+  const matched = matchHighRisk(targetPath, config?.l5?.highRiskPaths ?? []);
+  if (!matched) return;
+
+  const ledger = await readLedger(resolveSessionId(payload));
+  if (hasSimulationFor(ledger, targetPath)) return;
+
+  process.stdout.write(JSON.stringify({ decision: 'block', reason: buildBlockReason(targetPath, matched) }));
+}
+
+main().catch((err) => {
+  process.stderr.write(`[simulate-gate] ${err?.message ?? err}\n`);
+  process.exit(0);
+});

package/templates/contextkit/runtime/hooks/track-edits.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook (Level >= 2) — appends file modifications to the
+ * per-session ledger and warns about cross-session claim collisions (L3).
+ *
+ * Wired with matcher "Edit|Write|MultiEdit". Receives the tool payload via
+ * stdin (JSON). Silent on stdout UNLESS a cross-claim is detected.
+ *
+ * Side effects:
+ *   1. Updates `.claude/.sessions/<sid>.json`.
+ *   2. Renews the heartbeat in `.claude/.workspace/<sid>.json` (if claimed).
+ *   3. Surfaces a cross-claim warning when editing another session's claim.
+ *
+ * Defensive: any failure exits 0 with a stderr note. Zero third-party deps.
+ */
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { isTrackable, readLedger, resolveSessionId, sanitizeSid, toRepoRelative, writeLedger } from './ledger.mjs';
+import { writeFileAtomic } from './safe-io.mjs';
+import { WORKSPACE_STATE_DIR } from '../config/paths.mjs';
+
+const ROOT = process.cwd();
+const WORKSPACE_DIR = resolve(ROOT, WORKSPACE_STATE_DIR);
+
+async function readStdin() {
+  return new Promise((res) => {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => res(buf));
+    setTimeout(() => res(buf), 500).unref?.();
+  });
+}
+
+/** Extracts file paths from an Edit/Write/MultiEdit payload. */
+function extractPaths(payload) {
+  const tool = payload?.tool_name;
+  const input = payload?.tool_input ?? {};
+  if (tool === 'Edit' || tool === 'Write') return input.file_path ? [input.file_path] : [];
+  if (tool === 'MultiEdit') {
+    if (input.file_path) return [input.file_path];
+    if (Array.isArray(input.edits)) return input.edits.map((e) => e?.file_path).filter(Boolean);
+  }
+  return [];
+}
+
+async function renewHeartbeat(sessionId) {
+  const path = resolve(WORKSPACE_DIR, `${sanitizeSid(sessionId)}.json`);
+  try {
+    const claimRecord = JSON.parse(await readFile(path, 'utf-8'));
+    claimRecord.lastHeartbeat = Date.now();
+    await writeFileAtomic(path, JSON.stringify(claimRecord, null, 2));
+  } catch {
+    /* no claim file — nothing to renew */
+  }
+}
+
+async function loadOtherClaims(mySessionId) {
+  const claims = new Map();
+  let files = [];
+  try {
+    files = await readdir(WORKSPACE_DIR);
+  } catch {
+    return claims;
+  }
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const otherSid = f.slice(0, -5);
+    if (otherSid === mySessionId) continue;
+    try {
+      const claimRecord = JSON.parse(await readFile(resolve(WORKSPACE_DIR, f), 'utf-8'));
+      if (Array.isArray(claimRecord?.claims)) {
+        for (const cl of claimRecord.claims) if (typeof cl?.path === 'string') claims.set(cl.path, otherSid);
+      }
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return claims;
+}
+
+function pathCollides(editedPath, claimedPath) {
+  if (editedPath === claimedPath) return true;
+  const claimAsDir = claimedPath.endsWith('/') ? claimedPath : `${claimedPath}/`;
+  return editedPath.startsWith(claimAsDir);
+}
+
+function buildWarning(collisions) {
+  const list = collisions.map((c) => `  - \`${c.path}\` (claimed by session \`${c.owner.slice(0, 8)}\`)`).join('\n');
+  return [
+    '<cross-claim-warning>',
+    '⚠️  You just edited a path claimed by ANOTHER active session:',
+    list,
+    '',
+    'Coordinate before continuing. If the claim is stale, ask the user to /release it.',
+    '</cross-claim-warning>',
+  ].join('\n');
+}
+
+async function main() {
+  const raw = await readStdin();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  // Sanitize once up front: session id is external input and is used to build
+  // ledger + workspace paths (defense-in-depth against `../` traversal).
+  const sessionId = sanitizeSid(resolveSessionId(payload));
+  const paths = extractPaths(payload).map(toRepoRelative).filter(isTrackable);
+  if (paths.length === 0) return;
+
+  // 1. Append to ledger (recording each file's post-edit mtime so the L3
+  //    concurrency guard can later detect an EXTERNAL change to the same file).
+  const ledger = await readLedger(sessionId);
+  const tool = payload.tool_name ?? 'unknown';
+  const now = Date.now();
+  for (const p of paths) {
+    let mtime = null;
+    try {
+      mtime = (await stat(resolve(ROOT, p))).mtimeMs;
+    } catch {
+      /* file may not exist yet */
+    }
+    ledger.modifications.push({ path: p, tool, at: now, mtime });
+  }
+  await writeLedger(sessionId, ledger);
+
+  // 2. Renew heartbeat (if this session has a claim file).
+  await mkdir(WORKSPACE_DIR, { recursive: true }).catch(() => {});
+  await renewHeartbeat(sessionId);
+
+  // 3. Cross-claim detection (L3).
+  const otherClaims = await loadOtherClaims(sessionId);
+  if (otherClaims.size === 0) return;
+  const collisions = [];
+  for (const editedPath of paths) {
+    for (const [claimedPath, owner] of otherClaims) {
+      if (pathCollides(editedPath, claimedPath)) {
+        collisions.push({ path: editedPath, owner });
+        break;
+      }
+    }
+  }
+  if (collisions.length > 0) process.stdout.write(buildWarning(collisions));
+}
+
+main().catch((err) => {
+  process.stderr.write(`[track-edits] ${err?.message ?? err}\n`);
+  process.exit(0);
+});

package/templates/contextkit/runtime/providers/media/_adapter.mjs

@@ -0,0 +1,120 @@
+/**
+ * Media-provider adapter contract — ADR-0024.
+ *
+ * Each `*.mjs` file in this directory (except this one) is a concrete
+ * adapter for image or video generation. The kit ships two seeds:
+ *   - nano-banana.mjs  (image — Google AI Studio / Imagen)
+ *   - veo.mjs          (video — Google AI Studio / Veo)
+ *
+ * Adapter shape (all required):
+ *
+ *   export const id = 'nano-banana' | 'veo';
+ *   export const kind = 'image' | 'video';
+ *   export const envVar = 'GOOGLE_AI_API_KEY';
+ *   export const requiredEnv = ['GOOGLE_AI_API_KEY'];
+ *   export async function generate({ prompt, options, outPath }) { ... }
+ *
+ * Five contract points (ADR-0024):
+ *   1. No SDK dependency. Adapters use `node:fetch` against the REST
+ *      endpoint.
+ *   2. Refuse-on-missing-creds — `generate()` checks `requiredEnv` first
+ *      and throws MediaProviderError('NO_CREDENTIALS', ...) before any
+ *      network call.
+ *   3. `generate()` returns
+ *      `{ outPath, durationMs, costEstimateUsd, providerRequestId }`.
+ *   4. Refuse-on-content-policy. Google's API rejects some prompts;
+ *      the adapter throws MediaProviderError('CONTENT_POLICY', ...).
+ *   5. Cost-cap guard — process-level tally via CONTEXTDEVKIT_MEDIA_MAX_USD.
+ */
+
+/** Stable error codes thrown by adapters. Kept narrow on purpose. */
+export const MEDIA_ERROR_CODES = Object.freeze({
+  NO_CREDENTIALS:   'NO_CREDENTIALS',
+  CONTENT_POLICY:   'CONTENT_POLICY',
+  COST_CAP_REACHED: 'COST_CAP_REACHED',
+  RATE_LIMIT:       'RATE_LIMIT',
+  PROVIDER_ERROR:   'PROVIDER_ERROR',
+  BAD_INPUT:        'BAD_INPUT',
+  IO:               'IO',
+});
+
+export class MediaProviderError extends Error {
+  constructor(code, message, { providerRequestId } = {}) {
+    super(message);
+    this.name = 'MediaProviderError';
+    this.code = code;
+    if (providerRequestId) this.providerRequestId = providerRequestId;
+  }
+}
+
+/**
+ * Validate the shape of a media adapter module.
+ *
+ * @param {object} mod
+ * @returns {{ ok: true } | { ok: false, reasons: string[] }}
+ */
+export function validateAdapter(mod) {
+  const reasons = [];
+  if (typeof mod.id !== 'string' || mod.id.length === 0) reasons.push('missing `id` export');
+  if (mod.kind !== 'image' && mod.kind !== 'video') reasons.push('`kind` must be "image" or "video"');
+  if (typeof mod.envVar !== 'string' || mod.envVar.length === 0) reasons.push('missing `envVar` export');
+  if (!Array.isArray(mod.requiredEnv) || mod.requiredEnv.length === 0) reasons.push('`requiredEnv` must be a non-empty array');
+  if (typeof mod.generate !== 'function') reasons.push('missing `generate(input)` export');
+  return reasons.length ? { ok: false, reasons } : { ok: true };
+}
+
+/* ──────────────────────────────────────────────────────────────────────── */
+/* Cost-cap guard — single shared tally for the lifetime of the process.    */
+/* Adapters call `noteCostOrThrow(estimate)` BEFORE making the network call.*/
+/* ──────────────────────────────────────────────────────────────────────── */
+
+let _runningCostUsd = 0;
+
+/** Reads the per-process USD cap from CONTEXTDEVKIT_MEDIA_MAX_USD; null = no cap. */
+export function readCostCapUsd() {
+  const raw = process.env.CONTEXTDEVKIT_MEDIA_MAX_USD;
+  if (!raw) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * Throws MediaProviderError('COST_CAP_REACHED') if adding `estimateUsd` to
+ * the running tally would exceed the cap. Otherwise adds and returns the
+ * new running total.
+ *
+ * @param {number} estimateUsd
+ * @returns {number}  new running total
+ */
+export function noteCostOrThrow(estimateUsd) {
+  const cap = readCostCapUsd();
+  const next = _runningCostUsd + Math.max(0, estimateUsd);
+  if (cap !== null && next > cap) {
+    throw new MediaProviderError(
+      MEDIA_ERROR_CODES.COST_CAP_REACHED,
+      `cost cap reached: this call (~$${estimateUsd.toFixed(2)}) + running ($${_runningCostUsd.toFixed(2)}) would exceed CONTEXTDEVKIT_MEDIA_MAX_USD ($${cap.toFixed(2)})`,
+    );
+  }
+  _runningCostUsd = next;
+  return _runningCostUsd;
+}
+
+/** Test hook — resets the cost tally. NOT exposed to adapters. */
+export function _resetCostTallyForTests() { _runningCostUsd = 0; }
+
+/**
+ * Asserts every required env var is present; throws NO_CREDENTIALS otherwise.
+ * Adapters call this first thing in `generate()` (rule 8 — default-refuse).
+ *
+ * @param {string[]} requiredEnv
+ * @param {string}   templatePath  hint for the error message
+ */
+export function assertCredentials(requiredEnv, templatePath = 'contextkit/.env.example') {
+  const missing = requiredEnv.filter((name) => !process.env[name]);
+  if (missing.length) {
+    throw new MediaProviderError(
+      MEDIA_ERROR_CODES.NO_CREDENTIALS,
+      `missing env var(s): ${missing.join(', ')}. See ${templatePath} for the template and set them (e.g. run with \`node --env-file=contextkit/.env ...\` on Node 20.6+).`,
+    );
+  }
+}