@mlmcps/ml-specs-mcp 1.0.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mlmcps/ml-specs-mcp",
+  "version": "1.0.0",
+  "description": "Read-only MCP server for spec-driven development: estate contract lookup, knowledge-layer checks, and spec inventory over a local repo, plus the toolkit's spec-driven commands served as MCP prompts.",
+  "type": "module",
+  "scripts": {
+    "test": "node --test 'scripts/lib/*.test.mjs' 'scripts/*.test.mjs' 'mcp/*.test.mjs'"
+  },
+  "private": false,
+  "license": "MIT",
+  "bin": {
+    "ml-specs-mcp": "mcp/ml-specs-server.mjs"
+  },
+  "files": [
+    "mcp/",
+    "commands/",
+    "agents/",
+    "scripts/",
+    "!scripts/**/*.test.mjs",
+    "!scripts/lib/*.test.mjs",
+    "!mcp/*.test.mjs",
+    "templates/ci/knowledge-check.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MLMCPS/ml-claude-plugins.git",
+    "directory": "ml-specs"
+  },
+  "keywords": [
+    "mcp",
+    "spec-driven-development",
+    "claude"
+  ],
+  "dependencies": {}
+}

package/scripts/branch-policy.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Install and audit the branch policy that makes the spec gate blocking.
+//
+//   node branch-policy.mjs audit api-neelias neelias-pos
+//   node branch-policy.mjs install api-neelias --dry-run
+//   node branch-policy.mjs audit api-neelias --json
+//
+// Credentials from the environment: ADO_ORG/ADO_PROJECT/ADO_PAT, or
+// GITHUB_OWNER/GITHUB_TOKEN with SDD_SCM_TOOL=github.
+// Branch from SDD_PROTECTED_BRANCH (default main); build ref from SDD_BUILD_ID.
+//
+// Exit code 1 if any branch is ungated.
+//
+// Why this exists: ci/azure-pipelines.yml describes the checks, but a pipeline
+// that runs and reports changes nothing. The gate is the POLICY. And the way a
+// gate stops being a gate is silent — someone sets it to advisory on a Friday to
+// unblock a release, nothing breaks, no test fails, and merges quietly stop
+// being gated until an audit finds the holes months later.
+
+import { adoPolicy, githubPolicy, auditOk, auditSummary } from './lib/policy.mjs';
+import { args, colours, transportFor, scmConfig, env, printTranscript } from './lib/cli.mjs';
+
+const { positional, json, dryRun } = args();
+const [action, ...repos] = positional;
+const C = colours(process.stdout.isTTY && !json);
+
+if (!['install', 'audit'].includes(action) || repos.length === 0) {
+  console.error('usage: branch-policy.mjs <install|audit> <repo...> [--dry-run] [--json]');
+  process.exit(1);
+}
+
+const transport = transportFor(dryRun);
+const { tool, config } = scmConfig(transport);
+const mgr = tool === 'github' ? githubPolicy(config) : adoPolicy(config);
+const branch = env('SDD_PROTECTED_BRANCH', 'main');
+const buildRef = env('SDD_BUILD_ID', 'sdd-spec-gate');
+
+if (dryRun && !json) console.log(`${C.bold('dry run')} ${C.dim('— nothing is sent')}\n`);
+
+const results = [];
+for (const repo of repos) {
+  try {
+    results.push(action === 'install'
+      ? await mgr.install(repo, branch, buildRef)
+      : await mgr.audit(repo, branch));
+  } catch (e) {
+    results.push({ repo, branch, tool, present: false, blocking: false,
+                   findings: [{ severity: 'blocker', message: e.message }] });
+  }
+}
+
+const allOk = results.every(auditOk);
+
+if (json) {
+  console.log(JSON.stringify({ action, branch, tool, ok: allOk, results }, null, 2));
+} else {
+  for (const r of results) {
+    console.log(`  ${auditOk(r) ? C.green('OK  ') : C.red('FAIL')} ${r.repo.padEnd(22)} ${C.dim(branch)}  ${auditSummary(r)}`);
+    for (const f of r.findings) {
+      const paint = f.severity === 'blocker' ? C.red : C.yellow;
+      console.log(`         ${paint(f.severity.padEnd(8))} ${C.dim(f.message)}`);
+    }
+  }
+  console.log();
+  console.log(allOk
+    ? `  ${C.green('every branch is gated')}`
+    : `  ${C.red('an ungated branch means a pull request can merge with no approved spec')}`);
+  printTranscript(transport, C);
+}
+
+process.exit(allOk ? 0 : 1);

package/scripts/fix-specs.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+// Repair spec hygiene in a repo that has been using specs/ for a while.
+// Pure Node, no dependencies. Runs entirely on your machine — no network calls.
+//
+//   node fix-specs.mjs --root /path/to/repo              # dry run: prints the plan, writes nothing
+//   node fix-specs.mjs --root /path/to/repo --apply      # actually does it
+//
+// Two repairs, both opt-outable (--no-numbering / --no-status):
+//
+//   NUMBERING  Two specs sharing a number is a filename collision — git merges those badly.
+//              The later-created file is renumbered to the next free number, across ALL
+//              branches, and references to its old filename are rewritten.
+//
+//   STATUS     A Status cell holding prose ("Implemented — all 16 ACs met, gate green…")
+//              is real information in the wrong field: /spec-advance, /repo-status, and the
+//              MCP spec_list tool all read Status as one word. The lifecycle word moves into
+//              Status; the prose is PRESERVED verbatim as a note under the header table.
+//              Nothing is ever deleted.
+//
+// Idempotent: running it twice changes nothing the second time.
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, renameSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { resolveStatus } from './lib/specs.mjs';
+
+const args = process.argv.slice(2);
+const flag = (n) => { const i = args.indexOf(n); return i === -1 ? null : args[i + 1]; };
+const ROOT = flag('--root') || process.cwd();
+const APPLY = args.includes('--apply');
+const FORCE = args.includes('--force');
+const DO_NUMBERING = !args.includes('--no-numbering');
+const DO_STATUS = !args.includes('--no-status');
+
+const LIFECYCLE = ['Draft', 'Approved', 'Implemented', 'Verified', 'Archived'];
+// A spec id is digits plus an OPTIONAL letter: 0165 and 0165b are different specs, not a clash.
+const SPEC_FILE = /^(\d{4}[a-z]?)-(.+)\.md$/;
+
+const abs = (p) => join(ROOT, p);
+const git = (...a) => {
+  try {
+    return execFileSync('git', ['-C', ROOT, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return '';
+  }
+};
+const isRepo = git('rev-parse', '--is-inside-work-tree') === 'true';
+
+// --- collect specs ----------------------------------------------------------
+
+function collect() {
+  const out = [];
+  for (const dir of ['specs', 'specs/archive']) {
+    if (!existsSync(abs(dir))) continue;
+    for (const f of readdirSync(abs(dir))) {
+      const m = f.match(SPEC_FILE);
+      if (!m) continue;
+      out.push({ dir, file: `${dir}/${f}`, name: f, id: m[1], slug: m[2] });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function addedAt(file) {
+  if (isRepo) {
+    const t = git('log', '--diff-filter=A', '--format=%at', '-1', '--', file);
+    if (t) return Number(t);
+  }
+  try { return Math.floor(statSync(abs(file)).mtimeMs / 1000); } catch { return 0; }
+}
+
+// Highest number in use anywhere — working tree plus every branch's history, so a renumber
+// can't land on an id that exists only on a branch nobody has checked out.
+function highestUsed(specs) {
+  let max = 0;
+  const consider = (name) => {
+    const m = basename(name).match(/^(\d{4})/);
+    if (m) max = Math.max(max, Number(m[1]));
+  };
+  specs.forEach((s) => consider(s.name));
+  if (isRepo) {
+    git('log', '--all', '--pretty=format:', '--name-only', '--diff-filter=A', '--', 'specs/[0-9]*')
+      .split('\n').filter(Boolean).forEach(consider);
+  }
+  return max;
+}
+
+// --- repair 1: duplicate numbers -------------------------------------------
+
+function planNumbering(specs) {
+  const byId = new Map();
+  for (const s of specs) {
+    if (!byId.has(s.id)) byId.set(s.id, []);
+    byId.get(s.id).push(s);
+  }
+
+  let next = highestUsed(specs);
+  const renames = [];
+  for (const [id, group] of byId) {
+    if (group.length < 2) continue;
+    // Keep the original; renumber everything created after it.
+    const dated = group.map((s) => ({ ...s, at: addedAt(s.file) })).sort((a, b) => a.at - b.at);
+    for (const later of dated.slice(1)) {
+      next += 1;
+      const id2 = String(next).padStart(4, '0');
+      renames.push({
+        from: later.file,
+        to: `${later.dir}/${id2}-${later.slug}.md`,
+        oldId: id,
+        newId: id2,
+        addedAt: later.at ? new Date(later.at * 1000).toISOString().slice(0, 10) : 'unknown',
+        keeping: dated[0].file,
+      });
+    }
+  }
+  return renames;
+}
+
+// Files that might mention a renamed spec by filename. Deliberately narrow: specs, docs,
+// and top-level markdown. An exact-filename rewrite is safe; guessing at prose is not.
+function referenceCandidates() {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (!existsSync(abs(dir)) || depth > 3) return;
+    for (const f of readdirSync(abs(dir))) {
+      const rel = `${dir}/${f}`;
+      let st;
+      try { st = statSync(abs(rel)); } catch { continue; }
+      if (st.isDirectory()) walk(rel, depth + 1);
+      else if (f.endsWith('.md')) out.push(rel);
+    }
+  };
+  walk('specs', 0);
+  walk('docs', 0);
+  if (existsSync(abs('CLAUDE.md'))) out.push('CLAUDE.md');
+  if (existsSync(abs('README.md'))) out.push('README.md');
+  return [...new Set(out)];
+}
+
+// --- repair 2: status normalization ----------------------------------------
+
+const STATUS_ROW = /^\|\s*\*\*Status\*\*\s*\|/;
+
+function planStatus(specs) {
+  const changes = [];
+  const skipped = [];
+
+  for (const s of specs) {
+    const text = readFileSync(abs(s.file), 'utf8');
+    const lines = text.split('\n');
+    const i = lines.findIndex((l) => STATUS_ROW.test(l));
+    if (i === -1) continue;
+
+    const line = lines[i];
+    // Take everything between the cell delimiter and the LAST pipe: the prose itself often
+    // contains pipes, and truncating at the first one would silently eat content.
+    const start = line.indexOf('|', line.indexOf('**Status**')) + 1;
+    const end = line.lastIndexOf('|');
+    if (start <= 0 || end <= start) continue;
+
+    const raw = line.slice(start, end).trim();
+    const plain = raw.replace(/\*\*/g, '').replace(/`/g, '').trim();
+    if (LIFECYCLE.includes(plain)) continue;               // already canonical
+    if (/^Draft \\?\| Approved/.test(plain)) continue;      // untouched TEMPLATE placeholder
+
+    const r = resolveStatus(plain);
+    if (!r.status) {
+      skipped.push({ file: s.file, raw, why: 'no lifecycle word at all' });
+      continue;
+    }
+    // The word must LEAD the cell. "Implemented (2026-07-07) — …" is an author declaring a
+    // status; a stage word buried mid-sentence is narration, and promoting it writes a claim
+    // they never made. This is not about ambiguity — one buried word is just as much a guess
+    // as three, and this script rewrites files.
+    if (!r.leading) {
+      skipped.push({
+        file: s.file,
+        raw,
+        why: r.candidates.length > 1
+          ? `mentions ${r.candidates.join(', ')} mid-text, none leading`
+          : `"${r.status}" appears mid-text, not as the status`,
+      });
+      continue;
+    }
+    if (text.includes('> **Status note:**')) continue;      // already normalized
+
+    changes.push({ file: s.file, from: raw, to: r.status, lineIndex: i });
+  }
+  return { changes, skipped };
+}
+
+function applyStatus(change) {
+  const lines = readFileSync(abs(change.file), 'utf8').split('\n');
+  const i = change.lineIndex;
+  const line = lines[i];
+  const start = line.indexOf('|', line.indexOf('**Status**')) + 1;
+  const end = line.lastIndexOf('|');
+  lines[i] = `${line.slice(0, start)} ${change.to} ${line.slice(end)}`;
+
+  // Insert the preserved prose immediately after the header table block.
+  let j = i;
+  while (j + 1 < lines.length && lines[j + 1].trimStart().startsWith('|')) j++;
+  lines.splice(j + 1, 0, '', `> **Status note:** ${change.from}`);
+
+  writeFileSync(abs(change.file), lines.join('\n'));
+}
+
+// --- run --------------------------------------------------------------------
+
+const specs = collect();
+if (specs.length === 0) {
+  console.log(`No specs found under ${ROOT}/specs — nothing to do.`);
+  process.exit(0);
+}
+
+if (APPLY && isRepo && !FORCE) {
+  const dirty = git('status', '--porcelain', '--', 'specs', 'docs').split('\n').filter(Boolean);
+  if (dirty.length) {
+    console.error('Refusing to --apply with uncommitted changes under specs/ or docs/.');
+    console.error('Commit or stash first so this script\'s changes are reviewable on their own,');
+    console.error('or pass --force if you know what you are doing.');
+    process.exit(1);
+  }
+}
+
+const renames = DO_NUMBERING ? planNumbering(specs) : [];
+const { changes, skipped } = DO_STATUS ? planStatus(specs) : { changes: [], skipped: [] };
+
+console.log(`repo: ${ROOT}`);
+console.log(`specs: ${specs.length}${isRepo ? '' : '   (not a git repo — using file mtimes, local branches unchecked)'}`);
+console.log(APPLY ? '\nMODE: APPLY — writing changes\n' : '\nMODE: DRY RUN — nothing will be written (pass --apply to do it)\n');
+
+// 1. numbering
+if (DO_NUMBERING) {
+  console.log(`── duplicate spec numbers: ${renames.length} file(s) to renumber`);
+  const candidates = renames.length ? referenceCandidates() : [];
+  for (const r of renames) {
+    console.log(`   ${r.from}`);
+    console.log(`     → ${r.to}     (added ${r.addedAt}; keeping ${basename(r.keeping)} on ${r.oldId})`);
+
+    const refs = candidates.filter((c) => {
+      if (c === r.from) return false;
+      try { return readFileSync(abs(c), 'utf8').includes(basename(r.from)); } catch { return false; }
+    });
+    if (refs.length) console.log(`     ${refs.length} file(s) reference the old filename and will be updated`);
+
+    if (APPLY) {
+      const tracked = isRepo && git('ls-files', '--', r.from) !== '';
+      if (tracked) git('mv', r.from, r.to);
+      else renameSync(abs(r.from), abs(r.to));
+      for (const c of refs) {
+        const t = readFileSync(abs(c), 'utf8');
+        writeFileSync(abs(c), t.split(basename(r.from)).join(basename(r.to)));
+      }
+    }
+  }
+  if (renames.length) {
+    console.log('   NOTE: only exact filename references are rewritten. Prose like "see spec 0043"');
+    console.log('         is left alone — search for the old number by hand if you use that style.');
+  }
+}
+
+// 2. status
+if (DO_STATUS) {
+  console.log(`\n── non-canonical Status values: ${changes.length} file(s)`);
+  for (const c of changes.slice(0, 8)) {
+    const preview = c.from.length > 88 ? c.from.slice(0, 88) + '…' : c.from;
+    console.log(`   ${c.file}`);
+    console.log(`     "${preview}"`);
+    console.log(`     → Status: ${c.to}   (full text preserved as a "Status note" under the table)`);
+  }
+  if (changes.length > 8) console.log(`   … and ${changes.length - 8} more`);
+  if (APPLY) changes.forEach(applyStatus);
+}
+
+if (skipped.length) {
+  console.log(`\n── needs a human: ${skipped.length} file(s) left untouched`);
+  for (const s of skipped.slice(0, 10)) {
+    console.log(`   ${s.file}  (${s.why})`);
+    console.log(`      "${s.raw.length > 70 ? s.raw.slice(0, 70) + '…' : s.raw}"`);
+  }
+  if (skipped.length > 10) console.log(`   … and ${skipped.length - 10} more`);
+}
+
+console.log(
+  APPLY
+    ? `\n✓ applied: ${renames.length} renumbered, ${changes.length} statuses normalized. Review with \`git diff\` / \`git status\` — nothing was committed.`
+    : `\nDry run complete: would renumber ${renames.length}, normalize ${changes.length}. Re-run with --apply to write.`,
+);

package/scripts/lib/cli.mjs

@@ -0,0 +1,43 @@
+// Argument and environment handling shared by the scripts that talk to a tracker
+// or a source-control host. One implementation, so --dry-run and --root behave
+// identically everywhere.
+import { recorder, request } from './http.mjs';
+
+export function args(argv = process.argv.slice(2)) {
+  const flag = (n, d = null) => { const i = argv.indexOf(`--${n}`); return i === -1 ? d : (argv[i + 1] ?? d); };
+  const has = (n) => argv.includes(`--${n}`);
+  const positional = argv.filter((a, i) => !a.startsWith('--') && !String(argv[i - 1] ?? '').startsWith('--'));
+  return { argv, flag, has, positional, root: flag('root', process.cwd()), json: has('json'), dryRun: has('dry-run') };
+}
+
+export const colours = (enabled) => enabled
+  ? { dim: (s) => `\x1b[2m${s}\x1b[0m`, red: (s) => `\x1b[31m${s}\x1b[0m`, green: (s) => `\x1b[32m${s}\x1b[0m`,
+      yellow: (s) => `\x1b[33m${s}\x1b[0m`, bold: (s) => `\x1b[1m${s}\x1b[0m` }
+  : { dim: (s) => s, red: (s) => s, green: (s) => s, yellow: (s) => s, bold: (s) => s };
+
+/** A recording transport for --dry-run, the real one otherwise. */
+export const transportFor = (dryRun) => (dryRun ? recorder() : request);
+
+export const env = (name, fallback = '') => process.env[name] ?? fallback;
+
+/** Credentials are read from the environment, never from a file in the repo. */
+export function trackerConfig(transport) {
+  const tool = env('SDD_PM_TOOL', 'ado');
+  return tool === 'jira'
+    ? { tool, config: { baseUrl: env('JIRA_BASE_URL'), email: env('JIRA_EMAIL'),
+                        apiToken: env('JIRA_API_TOKEN'), projectKey: env('JIRA_PROJECT_KEY', 'PAY'), transport } }
+    : { tool, config: { org: env('ADO_ORG'), project: env('ADO_PROJECT'), pat: env('ADO_PAT'), transport } };
+}
+
+export function scmConfig(transport) {
+  const tool = env('SDD_SCM_TOOL', 'ado-repos');
+  return tool === 'github'
+    ? { tool, config: { owner: env('GITHUB_OWNER'), token: env('GITHUB_TOKEN'), transport } }
+    : { tool, config: { org: env('ADO_ORG'), project: env('ADO_PROJECT'), pat: env('ADO_PAT'), transport } };
+}
+
+export function printTranscript(transport, C) {
+  if (!transport.calls) return;
+  console.log(`\n${C.bold(`requests that would be sent (${transport.calls.length})`)}\n`);
+  console.log(transport.transcript());
+}

package/scripts/lib/estate.mjs

@@ -0,0 +1,108 @@
+// Read docs/ESTATE.md — the index /repo-estate generates — as a contract graph,
+// and answer "who else breaks if this changes".
+//
+// Pure Node, no dependencies. Read-only.
+//
+// Parsing is tolerant by design: this file is written for humans and edited by
+// them, and a parser that demanded exact formatting would fail on the first
+// sensible edit someone makes.
+
+const ROW = /^\|(.+)\|\s*$/;
+const SEP = /^\|[\s:|-]+\|\s*$/;
+const PLACEHOLDER = /^(<.*>|_TBD_|—|-|n\/?a|none|)$/i;
+
+const clean = (v) => String(v ?? '').replace(/[`*]/g, '').replace(/\s*\(.*\)\s*$/, '').trim();
+const names = (v) => String(v ?? '').split(/[,/]| and /).map(clean).filter((n) => n && !PLACEHOLDER.test(n));
+
+function tables(raw) {
+  const out = [];
+  let current = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    // The `|---|---|` rule belongs to the table it divides. Treating it as a
+    // break splits every table in two and orphans its header.
+    if (SEP.test(t)) continue;
+    const m = ROW.exec(t);
+    if (!m) { if (current.length) out.push(current); current = []; continue; }
+    current.push(m[1].split('|').map((c) => c.trim()));
+  }
+  if (current.length) out.push(current);
+  return out;
+}
+
+const headerHas = (row, ...required) => {
+  const lower = row.map((c) => c.toLowerCase());
+  return required.every((r) => lower.some((c) => c.includes(r)));
+};
+
+export function parseEstate(raw) {
+  const publishes = new Map();
+  const consumes = new Map();
+  const note = (repo) => {
+    if (!publishes.has(repo)) { publishes.set(repo, new Set()); consumes.set(repo, new Set()); }
+    return repo;
+  };
+
+  for (const table of tables(raw)) {
+    const [header, ...rows] = table;
+    if (!header) continue;
+
+    if (headerHas(header, 'service', 'owns')) {
+      for (const row of rows) for (const n of names(row[0])) note(n);
+
+    } else if (headerHas(header, 'caller', 'callee')) {
+      for (const row of rows) {
+        const contract = clean(row[3]) || clean(row[2]);
+        if (!contract || PLACEHOLDER.test(contract)) continue;
+        for (const callee of names(row[1])) publishes.get(note(callee)).add(contract);
+        for (const caller of names(row[0])) consumes.get(note(caller)).add(contract);
+      }
+
+    } else if (headerHas(header, 'producer', 'consumer')) {
+      for (const row of rows) {
+        const event = clean(row[0]);
+        if (!event || PLACEHOLDER.test(event)) continue;
+        for (const p of names(row[1])) publishes.get(note(p)).add(event);
+        for (const c of names(row[2])) consumes.get(note(c)).add(event);
+      }
+
+    } else if (headerHas(header, 'owner', 'used by')) {
+      for (const row of rows) {
+        const thing = clean(row[0]);
+        if (!thing || PLACEHOLDER.test(thing)) continue;
+        for (const o of names(row[1])) publishes.get(note(o)).add(thing);
+        for (const u of names(row[2])) consumes.get(note(u)).add(thing);
+      }
+    }
+  }
+
+  const generatedAt = (/(?:generated|updated|refreshed)[^\n]*?(\d{4}-\d{2}-\d{2})/i.exec(raw) ?? [])[1] ?? '';
+  return {
+    generatedAt,
+    repos: [...publishes.keys()].sort().map((name) => ({
+      name,
+      publishes: [...publishes.get(name)].sort(),
+      consumes: [...consumes.get(name)].sort(),
+    })),
+  };
+}
+
+/** Who consumes what this change touches — directly, and one hop further out. */
+export function impactOf(index, changed) {
+  const owners = index.repos.filter((r) => r.publishes.some((c) => changed.includes(c))).map((r) => r.name);
+
+  const directlyAffected = index.repos
+    .filter((r) => !owners.includes(r.name))
+    .map((r) => ({ repo: r.name, via: r.consumes.filter((c) => changed.includes(c)) }))
+    .filter((r) => r.via.length);
+
+  const directNames = directlyAffected.map((d) => d.repo);
+  const secondWave = new Set(index.repos.filter((r) => directNames.includes(r.name)).flatMap((r) => r.publishes));
+
+  const transitivelyAffected = index.repos
+    .filter((r) => !owners.includes(r.name) && !directNames.includes(r.name))
+    .map((r) => ({ repo: r.name, via: r.consumes.filter((c) => secondWave.has(c)) }))
+    .filter((r) => r.via.length);
+
+  return { changed, directlyAffected, transitivelyAffected };
+}

package/scripts/lib/http.mjs

@@ -0,0 +1,73 @@
+// The seam between an adapter and the network.
+//
+// `request` is the real transport. Injecting `recorder()` instead is what makes
+// the tracker and SCM clients testable without credentials — the documents they
+// build are the part most likely to be wrong (a JSON-patch path, a field written
+// directly that Jira only moves through a transition), and all of that is
+// assertable offline.
+//
+// It also backs --dry-run, so an operator can read the exact request that would
+// hit their organisation before anyone grants an access token.
+//
+// Pure Node, no dependencies. Node 18+ for global fetch.
+
+export const basicAuth = (user, password) =>
+  'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
+
+/** The real transport. Throws with the response body, which is where the useful
+ *  part of an ADO or Jira error lives. */
+export async function request(url, { method = 'GET', headers = {}, body, contentType = 'application/json', timeout = 30000 } = {}) {
+  const init = { method, headers: { Accept: 'application/json', ...headers } };
+  if (body !== undefined) {
+    init.headers['Content-Type'] = contentType;
+    init.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeout) });
+  if (!res.ok) {
+    throw new Error(`${method} ${new URL(url).pathname} -> ${res.status} ${(await res.text()).slice(0, 500)}`);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+/**
+ * A transport that records instead of sending. Returns canned responses in
+ * order, then a default shaped so every adapter's response parser completes —
+ * which is what lets --dry-run walk a whole flow rather than stopping at the
+ * first read.
+ */
+export function recorder(responses = []) {
+  let cursor = 0;
+  const calls = [];
+
+  const fn = async (url, { method = 'GET', body, contentType = 'application/json' } = {}) => {
+    calls.push({ method, url, body, contentType });
+    return cursor < responses.length ? responses[cursor++] : DEFAULT_RESPONSE;
+  };
+
+  fn.calls = calls;
+  fn.last = () => calls[calls.length - 1];
+  fn.transcript = () => calls.map(render).join('\n\n');
+  return fn;
+}
+
+const render = (c) => {
+  const head = `${c.method} ${c.url}`;
+  if (c.body === undefined) return head;
+  return `${head}\n  content-type: ${c.contentType}\n` +
+    JSON.stringify(c.body, null, 2).split('\n').map((l) => '  ' + l).join('\n');
+};
+
+// Keys are namespaced by their API so they do not collide.
+const SHA = '0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6';
+const DEFAULT_RESPONSE = {
+  // trackers
+  id: 1847, key: 'PAY-1847',
+  fields: { 'System.Title': '[SPEC-0031] placeholder', 'System.State': 'New',
+            summary: '[SPEC-0031] placeholder', status: { name: 'To Do' } },
+  workItems: [], issues: [], transitions: [],
+  // source control — ADO returns refs under `value`, GitHub a single `object`
+  value: [{ objectId: SHA, name: 'refs/heads/main' }],
+  object: { sha: SHA },
+  pullRequestId: 4321, number: 4321, html_url: 'https://example.invalid/pull/4321',
+};