@dev-tren/mapd 0.21.0

package/src/config/index.js

@@ -0,0 +1,197 @@
+/**
+ * config/index.js — .mapdrc loading, precedence, and validation.
+ *
+ * Precedence (later wins): DEFAULTS < user `~/.mapdrc` < project `.mapdrc`
+ * < `MAPD_*` env vars < explicit CLI overrides.
+ *
+ * Format: JSONC-lite — plain JSON with `//` and /* *\/ comments stripped,
+ * respecting string literals so a `//` inside a string value is never
+ * mistaken for a comment. No YAML dependency.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { DEFAULTS, validateAgainstSchema, ANNOTATION_CLASSIFICATIONS } from "./schema.js";
+import { applyRealTreeWrite } from "../core/changes.js";
+
+/** Strip //-line and /* *\/-block comments from JSONC, respecting string literals. */
+export function stripJsonComments(text) {
+  let out = "";
+  let inString = false;
+  let stringQuote = null;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    const next = text[i + 1];
+
+    if (inString) {
+      out += c;
+      if (c === "\\") { out += next ?? ""; i++; continue; }
+      if (c === stringQuote) inString = false;
+      continue;
+    }
+    if (c === '"' || c === "'") { inString = true; stringQuote = c; out += c; continue; }
+    if (c === "/" && next === "/") { while (i < text.length && text[i] !== "\n") i++; out += "\n"; continue; }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i++; // consume the closing '/'
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+function readMapdrc(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(stripJsonComments(fs.readFileSync(filePath, "utf8")));
+  } catch (e) {
+    throw new Error(`Failed to parse ${filePath}: ${e.message}`);
+  }
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+export function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) return override ?? base;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(override)) {
+    out[k] = isPlainObject(v) && isPlainObject(base[k]) ? deepMerge(base[k], v) : v;
+  }
+  return out;
+}
+
+function setPath(obj, dotted, value) {
+  const parts = dotted.split(".");
+  let node = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    node[parts[i]] = isPlainObject(node[parts[i]]) ? node[parts[i]] : {};
+    node = node[parts[i]];
+  }
+  node[parts[parts.length - 1]] = value;
+}
+
+/** Recognized MAPD_* env overrides, mapped onto config paths. Documented, not "magic generic". */
+const ENV_MAP = {
+  MAPD_PROVIDER: { path: "chat.provider", parse: (v) => v },
+  MAPD_MODEL: { path: "chat.model", parse: (v) => v },
+  MAPD_FIX_MAX_ATTEMPTS: { path: "fix.maxAttempts", parse: (v) => parseInt(v, 10) },
+  MAPD_MCP_TRANSPORT: { path: "mcp.transport", parse: (v) => v },
+  MAPD_ALLOW_DESTRUCTIVE: { path: "security.allowDestructiveCommands", parse: (v) => v === "true" || v === "1" },
+  MAPD_ALLOW_NETWORK: { path: "security.allowNetworkCommands", parse: (v) => v === "true" || v === "1" },
+};
+
+function envOverrides(env) {
+  const out = {};
+  for (const [key, { path: p, parse }] of Object.entries(ENV_MAP)) {
+    if (env[key] !== undefined) setPath(out, p, parse(env[key]));
+  }
+  return out;
+}
+
+/**
+ * Load and merge configuration. Never throws for missing files; throws only
+ * on a malformed .mapdrc so the user gets an actionable parse error.
+ */
+export function loadConfig(rootDir, { cliOverrides = {}, env = process.env, homeDir = os.homedir() } = {}) {
+  const abs = path.resolve(rootDir);
+  const userRc = readMapdrc(path.join(homeDir, ".mapdrc")) ?? {};
+  const projectRc = readMapdrc(path.join(abs, ".mapdrc")) ?? {};
+  const envRc = envOverrides(env);
+
+  let merged = deepMerge(DEFAULTS, userRc);
+  merged = deepMerge(merged, projectRc);
+  merged = deepMerge(merged, envRc);
+  merged = deepMerge(merged, cliOverrides);
+  return merged;
+}
+
+/** Structural + schema validation. Never throws — returns {ok, errors}. */
+export function validateConfig(config) {
+  const errors = [];
+  if (!isPlainObject(config)) return { ok: false, errors: ["config must be an object"] };
+  for (const section of ["project", "mapping", "chat", "fix", "mcp", "security", "providers"]) {
+    if (config[section] !== undefined && !isPlainObject(config[section])) {
+      errors.push(`${section}: must be an object`);
+    }
+  }
+  errors.push(...validateAgainstSchema(config));
+  return { ok: errors.length === 0, errors };
+}
+
+export function mapdrcPath(rootDir) {
+  return path.join(path.resolve(rootDir), ".mapdrc");
+}
+
+/**
+ * Annotation memory (`mapd annotate ...`) — user-asserted classifications for
+ * things static analysis structurally cannot know, persisted in the PROJECT
+ * .mapdrc under project.annotations so every surface (cli/chat/mcp/handoff/
+ * solutions) sees them through the normal config merge. Editing rewrites the
+ * file as pretty JSON; if the existing .mapdrc had JSONC comments they are
+ * not preserved, and `hadComments` is returned so callers can say so instead
+ * of silently eating documentation. The write goes through
+ * applyRealTreeWrite — .mapdrc is a real project file, so the edit is
+ * recorded as a rollback-able change like every other real-tree mutation.
+ */
+export function setAnnotation(rootDir, pattern, classification) {
+  if (!ANNOTATION_CLASSIFICATIONS.includes(classification)) {
+    return { ok: false, reason: `classification must be one of ${ANNOTATION_CLASSIFICATIONS.map((c) => `"${c}"`).join(", ")} (got "${classification}")` };
+  }
+  const p = mapdrcPath(rootDir);
+  const raw = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : null;
+  let rc;
+  try {
+    rc = raw === null ? {} : JSON.parse(stripJsonComments(raw));
+  } catch (e) {
+    return { ok: false, reason: `cannot edit ${p}: ${e.message}` };
+  }
+  rc.project = isPlainObject(rc.project) ? rc.project : {};
+  rc.project.annotations = isPlainObject(rc.project.annotations) ? rc.project.annotations : {};
+  const replaced = Object.prototype.hasOwnProperty.call(rc.project.annotations, pattern);
+  rc.project.annotations[pattern] = classification;
+  const change = applyRealTreeWrite(rootDir, ".mapdrc", JSON.stringify(rc, null, 2) + "\n", "annotate");
+  return { ok: true, path: p, pattern, classification, replaced, changeId: change.id, hadComments: raw !== null && stripJsonComments(raw) !== raw };
+}
+
+export function removeAnnotation(rootDir, pattern) {
+  const p = mapdrcPath(rootDir);
+  if (!fs.existsSync(p)) return { ok: false, reason: `no .mapdrc at ${p}` };
+  const raw = fs.readFileSync(p, "utf8");
+  let rc;
+  try {
+    rc = JSON.parse(stripJsonComments(raw));
+  } catch (e) {
+    return { ok: false, reason: `cannot edit ${p}: ${e.message}` };
+  }
+  if (!isPlainObject(rc.project?.annotations) || !Object.prototype.hasOwnProperty.call(rc.project.annotations, pattern)) {
+    return { ok: false, reason: `no annotation for pattern "${pattern}" in ${p}` };
+  }
+  delete rc.project.annotations[pattern];
+  const change = applyRealTreeWrite(rootDir, ".mapdrc", JSON.stringify(rc, null, 2) + "\n", "annotate");
+  return { ok: true, path: p, pattern, changeId: change.id, hadComments: stripJsonComments(raw) !== raw };
+}
+
+/** The fully-resolved annotation map (defaults + user + project + env), for listing. */
+export function listAnnotations(rootDir) {
+  const resolved = loadConfig(rootDir);
+  return resolved.project?.annotations ?? {};
+}
+
+/** `mapd config init` — writes a commented starter .mapdrc from DEFAULTS. Never overwrites silently. */
+export function initConfig(rootDir, { force = false } = {}) {
+  const p = mapdrcPath(rootDir);
+  if (fs.existsSync(p) && !force) {
+    return { ok: false, path: p, reason: "already exists (use --force to overwrite)" };
+  }
+  const body =
+    "// Map'd project configuration (JSONC — // and /* */ comments are stripped before parsing).\n" +
+    "// See README.md \"Configuration\" for the full field reference.\n" +
+    JSON.stringify(DEFAULTS, null, 2) + "\n";
+  fs.writeFileSync(p, body);
+  return { ok: true, path: p };
+}

package/src/config/schema.js

@@ -0,0 +1,119 @@
+/**
+ * config/schema.js — the .mapdrc shape and defaults.
+ *
+ * Format: JSONC-lite. Plain JSON with `//` and `/* *\/` comments stripped
+ * before JSON.parse (see index.js). Chosen over YAML to avoid adding a new
+ * dependency; every field below maps 1:1 onto the project's documented
+ * configuration surface.
+ */
+
+export const DEFAULTS = Object.freeze({
+  project: {
+    root: ".",
+    include: [],
+    exclude: ["node_modules/**", "dist/**", "build/**", "coverage/**", "eval/results/**", ".next/**", ".git/**"],
+    // User-asserted classifications for things static analysis structurally
+    // cannot know: glob pattern -> "generated" | "dynamically-loaded".
+    // e.g. { "eval/results/**": "generated", "electron/tools/**": "dynamically-loaded" }
+    // Output always labels these as user-asserted, never as detected.
+    annotations: {},
+  },
+  mapping: {
+    confidenceThreshold: 0.8,
+    orphanThreshold: 0.5,
+    maxFileSizeBytes: 1_000_000,
+    cache: true,
+    // Heuristic mapping of non-JS/TS languages (Python/Go/Rust/Ruby/Java/PHP)
+    // — see core/polyglot.js. Set false to tell Map'd to stop mapping those
+    // languages entirely; they revert to the honest "unsupported" bucket.
+    polyglot: true,
+  },
+  chat: {
+    provider: "auto",
+    model: "auto",
+    autoRunReadOnly: true,
+    requireApprovalForWrites: true,
+    allowShell: false,
+    maxContextTokens: 30_000,
+    maxCommandOutputCharacters: 30_000,
+  },
+  fix: {
+    maxAttempts: 2,
+    requireApproval: true,
+    allowedPaths: [],
+    forbiddenPaths: [".env", ".env.*", "secrets/**"],
+    runTests: true,
+    runTypecheck: true,
+    runLint: true,
+  },
+  mcp: {
+    enabled: true,
+    transport: "stdio",
+  },
+  security: {
+    allowNetworkCommands: false,
+    allowDestructiveCommands: false,
+    allowedCommands: [],
+    deniedCommands: [],
+  },
+  providers: {
+    anthropic: { model: "" },
+    openai: { model: "" },
+    kimi: { model: "" },
+  },
+});
+
+/**
+ * The only annotation classifications Map'd accepts — shared by the schema
+ * validator and `mapd annotate`. These are the "tell Map'd" levers for what
+ * static analysis structurally cannot know:
+ *   generated           — build/tool output; quarantined from scans
+ *   dynamically-loaded  — loaded at runtime by a pattern no detector sees
+ *   entrypoint          — a real entry point (any language); grows a workflow
+ *   intentional-dormant — deliberately kept code; never reported as an orphan
+ */
+export const ANNOTATION_CLASSIFICATIONS = Object.freeze(["generated", "dynamically-loaded", "entrypoint", "intentional-dormant"]);
+
+/** Field-level validators. Each returns an error string, or null if valid. */
+const VALIDATORS = {
+  "project.include": (v) => (Array.isArray(v) && v.every((x) => typeof x === "string") ? null : "must be an array of glob strings"),
+  "project.exclude": (v) => (Array.isArray(v) && v.every((x) => typeof x === "string") ? null : "must be an array of glob strings"),
+  "mapping.confidenceThreshold": (v) => (typeof v === "number" && v >= 0 && v <= 1 ? null : "must be a number between 0 and 1"),
+  "mapping.orphanThreshold": (v) => (typeof v === "number" && v >= 0 && v <= 1 ? null : "must be a number between 0 and 1"),
+  "mapping.maxFileSizeBytes": (v) => (typeof v === "number" && v > 0 ? null : "must be a positive number"),
+  "chat.maxContextTokens": (v) => (typeof v === "number" && v > 0 ? null : "must be a positive number"),
+  "chat.maxCommandOutputCharacters": (v) => (typeof v === "number" && v > 0 ? null : "must be a positive number"),
+  "fix.maxAttempts": (v) => (Number.isInteger(v) && v >= 1 ? null : "must be an integer >= 1"),
+  "mapping.polyglot": (v) => (typeof v === "boolean" ? null : "must be a boolean"),
+  "mcp.transport": (v) => (v === "stdio" ? null : "only 'stdio' transport is currently supported"),
+  "project.annotations": (v) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) return "must be an object mapping glob patterns to classifications";
+    const allowed = new Set(ANNOTATION_CLASSIFICATIONS);
+    for (const [pattern, raw] of Object.entries(v)) {
+      // an annotation value may be a bare classification string, or an object
+      // { classification, reason?, source?, date? } carrying attribution
+      // (see `mapd config lint` — attribution is optional but recommended).
+      const cls = typeof raw === "string" ? raw : (raw && typeof raw === "object" && !Array.isArray(raw) ? raw.classification : undefined);
+      if (typeof cls !== "string" || !allowed.has(cls)) {
+        return `"${pattern}": classification must be one of ${[...allowed].map((a) => `"${a}"`).join(", ")} (got "${typeof raw === "object" ? JSON.stringify(raw) : raw}")`;
+      }
+      if (raw && typeof raw === "object") {
+        for (const k of Object.keys(raw)) {
+          if (!["classification", "reason", "source", "date"].includes(k)) return `"${pattern}": unknown attribution field "${k}" (allowed: classification, reason, source, date)`;
+        }
+      }
+    }
+    return null;
+  },
+};
+
+export function validateAgainstSchema(config) {
+  const errors = [];
+  for (const [pathKey, validate] of Object.entries(VALIDATORS)) {
+    const value = pathKey.split(".").reduce((o, k) => o?.[k], config);
+    if (value === undefined) continue;
+    const err = validate(value);
+    if (err) errors.push(`${pathKey}: ${err}`);
+  }
+  return errors;
+}

package/src/core/assist.js

@@ -0,0 +1,64 @@
+/**
+ * assist.js — bare `mapd` (no subcommand) guidance. Inspects real project
+ * state (config presence, baseline presence, open findings) and returns the
+ * one or two commands that actually move things forward next — never a
+ * generic help dump. Every claim here is read from the same deterministic
+ * sources the rest of Map'd uses (buildScoredGraph, loadBaseline, the review
+ * queue) — nothing here is guessed or narrated by an LLM.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { buildScoredGraph } from "./intelligence.js";
+import { loadBaseline } from "./regression.js";
+import { loadQueueWithStates, pending } from "./review.js";
+
+export function buildAssist(abs) {
+  const hasConfig = fs.existsSync(path.join(abs, ".mapdrc"));
+  const g = buildScoredGraph(abs);
+  const baseline = loadBaseline(abs);
+  const { items } = loadQueueWithStates(abs);
+  const open = pending(items);
+  const highSeverity = open.filter((i) => i.severity === "high");
+
+  const steps = [];
+  if (!hasConfig) {
+    steps.push({ cmd: "mapd config init", why: "No .mapdrc yet — write starter config with documented defaults." });
+  }
+  if (!baseline) {
+    steps.push({ cmd: "mapd check --save-baseline", why: "No regression baseline yet — snapshot the current map so future changes can be diffed." });
+  } else if (baseline.schemaMismatch) {
+    steps.push({ cmd: "mapd check --save-baseline", why: `Baseline schema v${baseline.schemaMismatch.found} predates this Map'd (v${baseline.schemaMismatch.expected}) — re-snapshot.` });
+  }
+  if (highSeverity.length) {
+    steps.push({ cmd: "mapd fix --propose", why: `${highSeverity.length} high-severity finding(s) open — auto-selects and proposes a gate-verified fix for the strongest one.` });
+  } else if (open.length) {
+    steps.push({ cmd: "mapd fix review", why: `${open.length} item(s) awaiting approval.` });
+  }
+  if (baseline && !baseline.schemaMismatch) {
+    steps.push({ cmd: "mapd check", why: "Re-check for regressions against the saved baseline." });
+  }
+  steps.push({ cmd: "mapd chat", why: "Ask questions, get a ranked \"what should I work on\" plan, or explore the score breakdown." });
+
+  return {
+    root: abs,
+    summary: { fileCount: g.stats.fileCount, workflowCount: g.workflows.length, repoConfidence: g.repoConfidence },
+    openFindings: open.length,
+    steps: steps.slice(0, 4),
+  };
+}
+
+export function renderAssist(data, { bold, dim, cyan, confidenceColor }) {
+  const lines = [];
+  lines.push(`${bold("Map'd")} — ${dim(data.root)}`);
+  lines.push(`  files: ${data.summary.fileCount}  workflows: ${data.summary.workflowCount}  repo confidence: ${confidenceColor(data.summary.repoConfidence)(data.summary.repoConfidence)}  open findings: ${data.openFindings}`);
+  lines.push("");
+  lines.push(bold("What to run next:"));
+  for (const s of data.steps) {
+    lines.push(`  ${cyan(s.cmd)}`);
+    lines.push(`      ${dim(s.why)}`);
+  }
+  lines.push("");
+  lines.push(dim("mapd --help lists every command; mapd chat answers plain-English questions about this project."));
+  return lines.join("\n");
+}

package/src/core/audit.js

@@ -0,0 +1,63 @@
+/**
+ * audit.js — structured, append-only audit records for every command that
+ * touches the project (fix attempts, integrate applies, chat mutations, mcp
+ * tool calls). Human-readable via `mapd audit <id>`, machine-readable via
+ * `--json`. Secrets are redacted before anything is written.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { redactSecrets } from "./security.js";
+
+const MAPD = ".mapd";
+const SCHEMA = 1;
+
+function auditsDir(rootDir) { return path.join(path.resolve(rootDir), MAPD, "audits"); }
+
+function redactDeep(value) {
+  if (typeof value === "string") return redactSecrets(value);
+  if (Array.isArray(value)) return value.map(redactDeep);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v)]));
+  }
+  return value;
+}
+
+/**
+ * `record` should include: command, initiator, sessionId?, changeId?,
+ * provider?, model?, contextSources?, filesInspected?, filesChanged?,
+ * approvalStatus?, attempt?, gates?, commandsRun?, exitCodes?, durationMs?,
+ * tokenUsage?, finalStatus, rollbackStatus?.
+ */
+export function recordAudit(rootDir, record) {
+  const dir = auditsDir(rootDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const id = crypto.randomUUID();
+  const full = redactDeep({
+    mapdSchema: SCHEMA,
+    id,
+    timestamp: new Date().toISOString(),
+    ...record,
+  });
+  const file = path.join(dir, `${full.timestamp.replace(/[:.]/g, "-")}-${id.slice(0, 8)}.json`);
+  fs.writeFileSync(file, JSON.stringify(full, null, 2));
+  return full;
+}
+
+export function loadAudits(rootDir) {
+  const dir = auditsDir(rootDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((n) => n.endsWith(".json"))
+    .map((n) => {
+      try { return JSON.parse(fs.readFileSync(path.join(dir, n), "utf8")); }
+      catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+
+export function getAudit(rootDir, id) {
+  return loadAudits(rootDir).find((a) => a.id === id || a.id.startsWith(id)) ?? null;
+}

package/src/core/changes.js

@@ -0,0 +1,110 @@
+/**
+ * changes.js — the single funnel for every real-tree mutation Map'd makes
+ * (fix apply, integrate apply, review approve). Every write through here is
+ * also recorded as a stable, rollback-able change record — approval state
+ * is never allowed to stand in for an actual recorded, reversible write.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { sanitizeRelPath, isProtectedPath } from "./security.js";
+
+const MAPD = ".mapd";
+
+function changesDir(rootDir) { return path.join(rootDir, MAPD, "changes"); }
+function blobsDir(rootDir) { return path.join(changesDir(rootDir), "blobs"); }
+
+function newChangeId() {
+  return `chg-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+function hashOf(content) {
+  return content == null ? null : crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/**
+ * Write `newSource` to `file` (relative to rootDir) and record a change entry
+ * with a full before/after blob backup. Refuses protected paths and path
+ * traversal outright — this is the last line of defense before a real-tree
+ * write, independent of whatever upstream gates already ran.
+ *
+ * `source` identifies the origin ("fix" | "integrate" | "review") for the audit trail.
+ */
+export function applyRealTreeWrite(rootDir, file, newSource, source, { forbiddenPaths = [] } = {}) {
+  const abs = path.resolve(rootDir);
+  if (isProtectedPath(file, forbiddenPaths)) {
+    throw new Error(`Refusing to write a protected path: ${file}`);
+  }
+  const target = sanitizeRelPath(abs, file);
+
+  let before = null;
+  try { before = fs.readFileSync(target, "utf8"); } catch { /* new file */ }
+
+  const id = newChangeId();
+  fs.mkdirSync(blobsDir(abs), { recursive: true });
+  const beforePath = before != null ? path.join(blobsDir(abs), `${id}.before`) : null;
+  const afterPath = path.join(blobsDir(abs), `${id}.after`);
+  if (beforePath) fs.writeFileSync(beforePath, before);
+  fs.writeFileSync(afterPath, newSource);
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, newSource);
+
+  const record = {
+    mapdSchema: 1,
+    id,
+    at: new Date().toISOString(),
+    file,
+    source,
+    beforeHash: hashOf(before),
+    afterHash: hashOf(newSource),
+    beforePath, afterPath,
+    rolledBack: false,
+  };
+  fs.writeFileSync(path.join(changesDir(abs), `${id}.json`), JSON.stringify(record, null, 2));
+  return record;
+}
+
+export function loadChanges(rootDir) {
+  const dir = changesDir(path.resolve(rootDir));
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((n) => n.endsWith(".json"))
+    .map((n) => readJson(path.join(dir, n)))
+    .filter(Boolean)
+    .sort((a, b) => a.at.localeCompare(b.at));
+}
+
+export function getChange(rootDir, changeId) {
+  return loadChanges(rootDir).find((c) => c.id === changeId) ?? null;
+}
+
+/**
+ * Restore the file this change touched to its pre-change content (or delete
+ * it, if the change created a new file). Append-only: the original record is
+ * never deleted, only marked rolledBack, and a new rollback record is appended.
+ */
+export function rollbackChange(rootDir, changeId) {
+  const abs = path.resolve(rootDir);
+  const record = getChange(abs, changeId);
+  if (!record) return { ok: false, detail: `no change with id ${changeId}` };
+  if (record.rolledBack) return { ok: false, detail: `change ${changeId} was already rolled back` };
+
+  const target = sanitizeRelPath(abs, record.file);
+  if (record.beforePath && fs.existsSync(record.beforePath)) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, fs.readFileSync(record.beforePath));
+  } else {
+    try { fs.rmSync(target, { force: true }); } catch { /* best effort */ }
+  }
+
+  record.rolledBack = true;
+  record.rolledBackAt = new Date().toISOString();
+  fs.writeFileSync(path.join(changesDir(abs), `${changeId}.json`), JSON.stringify(record, null, 2));
+  return { ok: true, detail: `${record.file} restored to its state before change ${changeId}` };
+}