@forwardimpact/libwiki 0.2.9 → 0.2.10

package/bin/fit-wiki.js

@@ -15,6 +15,7 @@ import { runClaimCommand, runReleaseCommand } from "../src/commands/claim.js";
 import { runInboxCommand } from "../src/commands/inbox.js";
 import { runRotateCommand } from "../src/commands/rotate.js";
 import { runAuditCommand } from "../src/commands/audit.js";
+import { runFixCommand } from "../src/commands/fix.js";
 
 const { version: VERSION } = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -156,6 +157,15 @@ const definition = {
         },
       },
     },
+    {
+      name: "fix",
+      description:
+        "Auto-fix wiki audit findings using an AI agent (technical-writer, Haiku)",
+      options: {
+        ...wikiRootOpt,
+        ...todayOpt,
+      },
+    },
     {
       name: "memo",
       description: "Send a cross-team memo into a teammate's Message Inbox",
@@ -228,6 +238,7 @@ const definition = {
     "fit-wiki inbox list --agent staff-engineer",
     "fit-wiki rotate --agent staff-engineer",
     "fit-wiki audit",
+    "fit-wiki fix",
     'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
     "fit-wiki refresh",
     "fit-wiki init",
@@ -260,6 +271,7 @@ const COMMANDS = {
   inbox: runInboxCommand,
   rotate: runRotateCommand,
   audit: runAuditCommand,
+  fix: runFixCommand,
   memo: runMemoCommand,
   refresh: runRefreshCommand,
   init: runInitCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",
@@ -47,12 +47,13 @@
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
     "@forwardimpact/libconfig": "^0.1.77",
+    "@forwardimpact/libeval": "^0.1.49",
     "@forwardimpact/libpreflight": "^0.1.0",
     "@forwardimpact/libutil": "^0.1.0",
     "@forwardimpact/libxmr": "^1.1.0"
   },
   "devDependencies": {
-    "@forwardimpact/libharness": "^0.1.5"
+    "@forwardimpact/libmock": "^0.1.0"
   },
   "engines": {
     "bun": ">=1.2.0",

package/src/commands/claim.js

@@ -8,15 +8,16 @@ import {
   parseClaims,
   filterExpired,
 } from "../active-claims.js";
+import { createDefaultIo } from "../io.js";
 
-function projectRoot() {
+function projectRoot(io) {
   const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  return finder.findProjectRoot(process.cwd());
+  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
+  return finder.findProjectRoot(io.cwd());
 }
 
-function memoryPath(values) {
-  const root = projectRoot();
+function memoryPath(values, io) {
+  const root = projectRoot(io);
   const wikiRoot = values["wiki-root"] || path.join(root, "wiki");
   return path.join(wikiRoot, "MEMORY.md");
 }
@@ -33,19 +34,19 @@ function addDays(today, n) {
 }
 
 /** Insert a row into MEMORY.md `## Active Claims`. Refuses if (agent, target) already present. */
-export function runClaimCommand(values, _args, cli) {
-  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+export function runClaimCommand(values, _args, cli, io = createDefaultIo()) {
+  const agent = values.agent || io.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
     cli.usageError("claim requires --agent or LIBEVAL_AGENT_PROFILE");
-    process.exit(2);
+    return io.exit(2);
   }
   if (!values.target || !values.branch) {
     cli.usageError("claim requires --target and --branch");
-    process.exit(2);
+    return io.exit(2);
   }
-  const today = values.today || new Date().toISOString().slice(0, 10);
+  const today = values.today || io.today();
   const expires = values["expires-at"] || addDays(today, 7);
-  const memPath = memoryPath(values);
+  const memPath = memoryPath(values, io);
   const text = readMemory(memPath);
   const result = appendClaim(text, {
     agent,
@@ -56,22 +57,20 @@ export function runClaimCommand(values, _args, cli) {
     expires_at: expires,
   });
   if (!result.inserted) {
-    process.stderr.write(
-      `claim already exists for ${agent}/${values.target}\n`,
-    );
-    process.exit(2);
+    io.stderr(`claim already exists for ${agent}/${values.target}\n`);
+    return io.exit(2);
   }
   writeFileSync(memPath, result.text);
-  process.stdout.write(`claimed ${values.target} (expires ${expires})\n`);
+  io.stdout(`claimed ${values.target} (expires ${expires})\n`);
 }
 
 /** Remove a claim row. `--expired` cleans every row past expires_at. */
-export function runReleaseCommand(values, _args, cli) {
-  const memPath = memoryPath(values);
+export function runReleaseCommand(values, _args, cli, io = createDefaultIo()) {
+  const memPath = memoryPath(values, io);
   const text = readMemory(memPath);
 
   if (values.expired) {
-    const today = values.today || new Date().toISOString().slice(0, 10);
+    const today = values.today || io.today();
     const claims = parseClaims(text);
     const { expired } = filterExpired(claims, today);
     let current = text;
@@ -84,24 +83,24 @@ export function runReleaseCommand(values, _args, cli) {
       }
     }
     writeFileSync(memPath, current);
-    process.stdout.write(`released ${count} expired claim(s)\n`);
+    io.stdout(`released ${count} expired claim(s)\n`);
     return;
   }
 
-  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+  const agent = values.agent || io.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
     cli.usageError("release requires --agent or --expired");
-    process.exit(2);
+    return io.exit(2);
   }
   if (!values.target) {
     cli.usageError("release requires --target (or --expired)");
-    process.exit(2);
+    return io.exit(2);
   }
   const result = removeClaim(text, { agent, target: values.target });
   writeFileSync(memPath, result.text);
   if (!result.removed) {
-    process.stdout.write(`no matching claim for ${agent}/${values.target}\n`);
+    io.stdout(`no matching claim for ${agent}/${values.target}\n`);
   } else {
-    process.stdout.write(`released ${values.target}\n`);
+    io.stdout(`released ${values.target}\n`);
   }
 }

package/src/commands/fix.js

@@ -0,0 +1,64 @@
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { Writable } from "node:stream";
+import { Finder, emitFindingsText, runRules } from "@forwardimpact/libutil";
+import {
+  createAgentRunner,
+  composeProfilePrompt,
+  createRedactor,
+} from "@forwardimpact/libeval";
+import { RULES } from "../audit/rules.js";
+import { buildContext, resolveScope } from "../audit/scopes.js";
+
+/** Run the wiki audit and auto-fix findings via a Haiku-powered AgentRunner. */
+export async function runFixCommand(values, _args, _cli) {
+  const finder = new Finder(fsAsync, { debug() {} }, process);
+  const projectRoot = finder.findProjectRoot(process.cwd());
+  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = values.today || new Date().toISOString().slice(0, 10);
+
+  const ctx = buildContext({ wikiRoot, today });
+  const findings = runRules(RULES, ctx, { resolveScope });
+
+  if (findings.length === 0) {
+    process.stdout.write("nothing to fix\n");
+    return;
+  }
+
+  const auditText = emitFindingsText(findings, { cwd: projectRoot });
+  const redactor = createRedactor();
+  const devNull = new Writable({
+    write(_c, _e, cb) {
+      cb();
+    },
+  });
+
+  const systemPrompt = composeProfilePrompt("technical-writer", {
+    profilesDir: path.resolve(projectRoot, ".claude/agents"),
+  });
+
+  const { query } = await import("@anthropic-ai/claude-agent-sdk");
+
+  const runner = createAgentRunner({
+    cwd: projectRoot,
+    query,
+    output: devNull,
+    model: "claude-haiku-4-5-20251001",
+    maxTurns: 15,
+    allowedTools: ["Read", "Write", "Edit"],
+    settingSources: ["project"],
+    systemPrompt,
+    redactor,
+  });
+
+  const task = [
+    `Fix these wiki audit findings.`,
+    `The wiki root is ${wikiRoot}.`,
+    ``,
+    auditText,
+  ].join("\n");
+
+  const result = await runner.run(task);
+  if (result.text) process.stdout.write(result.text + "\n");
+  process.exit(result.success ? 0 : 1);
+}

package/src/commands/init.js

@@ -6,6 +6,7 @@ import { Finder } from "@forwardimpact/libutil";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { WikiRepo } from "../wiki-repo.js";
 import { listSkills } from "../skill-roster.js";
+import { createDefaultIo } from "../io.js";
 import {
   ACTIVE_CLAIMS_HEADING,
   ACTIVE_CLAIMS_TABLE_HEADER,
@@ -13,8 +14,8 @@ import {
 } from "../constants.js";
 
 /** Resolve the wiki clone URL. Honors the FIT_WIKI_URL env var as an explicit override (for sandboxed environments where `origin` is rewritten to a local proxy that does not serve wiki repos); otherwise derives the URL by appending `.wiki.git` to the parent repo's `origin` remote. */
-export function deriveWikiUrl(parentDir) {
-  if (process.env.FIT_WIKI_URL) return process.env.FIT_WIKI_URL;
+export function deriveWikiUrl(parentDir, env = process.env) {
+  if (env.FIT_WIKI_URL) return env.FIT_WIKI_URL;
 
   const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
     encoding: "utf-8",
@@ -55,12 +56,10 @@ function scaffoldActiveClaims(memoryPath) {
   return true;
 }
 
-async function maybeCloneWiki(projectRoot, wikiDir) {
-  const wikiUrl = deriveWikiUrl(projectRoot);
+async function maybeCloneWiki(projectRoot, wikiDir, io) {
+  const wikiUrl = deriveWikiUrl(projectRoot, io.env);
   if (!wikiUrl) {
-    process.stderr.write(
-      "init: could not determine wiki URL from origin remote\n",
-    );
+    io.stderr("init: could not determine wiki URL from origin remote\n");
     return;
   }
   const config = await createScriptConfig("wiki");
@@ -73,17 +72,20 @@ async function maybeCloneWiki(projectRoot, wikiDir) {
   if (cloneResult.cloned) {
     repo.inheritIdentity();
   } else {
-    process.stderr.write(
-      "init: could not clone wiki, continuing with local-only steps\n",
-    );
+    io.stderr("init: could not clone wiki, continuing with local-only steps\n");
   }
 }
 
 /** Clone the wiki if not already present, scaffold Active Claims in MEMORY.md, and create per-skill metric directories. */
-export async function runInitCommand(values, _args, _cli) {
+export async function runInitCommand(
+  values,
+  _args,
+  _cli,
+  io = createDefaultIo(),
+) {
   const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
+  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
+  const projectRoot = finder.findProjectRoot(io.cwd());
 
   const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
   const skillsDir = path.resolve(
@@ -91,7 +93,7 @@ export async function runInitCommand(values, _args, _cli) {
     values["skills-dir"] ?? path.join(".claude", "skills"),
   );
 
-  await maybeCloneWiki(projectRoot, wikiDir);
+  await maybeCloneWiki(projectRoot, wikiDir, io);
 
   if (existsSync(skillsDir)) {
     for (const slug of listSkills({ skillsDir })) {
@@ -102,11 +104,9 @@ export async function runInitCommand(values, _args, _cli) {
   if (existsSync(wikiDir)) {
     const memoryPath = path.join(wikiDir, "MEMORY.md");
     if (scaffoldActiveClaims(memoryPath)) {
-      process.stdout.write(
-        `init: scaffolded ${ACTIVE_CLAIMS_HEADING} in ${memoryPath}\n`,
-      );
+      io.stdout(`init: scaffolded ${ACTIVE_CLAIMS_HEADING} in ${memoryPath}\n`);
     }
   }
 
-  process.stdout.write(`init: wiki ready at ${wikiDir}\n`);
+  io.stdout(`init: wiki ready at ${wikiDir}\n`);
 }

package/src/commands/log.js

@@ -8,24 +8,24 @@ import {
   appendEntry,
 } from "../weekly-log.js";
 import { DECISION_HEADING } from "../constants.js";
+import { createDefaultIo } from "../io.js";
 
-function projectRootForCommand() {
+function projectRootForCommand(io) {
   const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  return finder.findProjectRoot(process.cwd());
+  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
+  return finder.findProjectRoot(io.cwd());
 }
 
-function commonContext(values) {
-  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+function commonContext(values, io) {
+  const agent = values.agent || io.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    process.stderr.write(
-      "log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n",
-    );
-    process.exit(2);
+    io.stderr("log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n");
+    io.exit(2);
+    return null;
   }
-  const projectRoot = projectRootForCommand();
+  const projectRoot = projectRootForCommand(io);
   const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
-  const today = values.today || new Date().toISOString().slice(0, 10);
+  const today = values.today || io.today();
   return { agent, wikiRoot, today };
 }
 
@@ -39,8 +39,10 @@ function lastDateHeading(text) {
   return last;
 }
 
-function runDecision(values) {
-  const { agent, wikiRoot, today } = commonContext(values);
+function runDecision(values, io) {
+  const ctx = commonContext(values, io);
+  if (!ctx) return;
+  const { agent, wikiRoot, today } = ctx;
   const surveyed = values.surveyed || "—";
   const chosen = values.chosen || "—";
   const rationale = values.rationale || "—";
@@ -63,14 +65,17 @@ function runDecision(values) {
   rotateIfOverBudget(wikiRoot, agent, today, lineCount);
   const target = weeklyLogPath(wikiRoot, agent, today);
   appendEntry(target, body, agent, today);
-  process.stdout.write(`logged decision to ${target}\n`);
+  io.stdout(`logged decision to ${target}\n`);
 }
 
-function runNote(values) {
-  const { agent, wikiRoot, today } = commonContext(values);
+function runNote(values, io) {
+  const ctx = commonContext(values, io);
+  if (!ctx) return;
+  const { agent, wikiRoot, today } = ctx;
   if (!values.field || !values.body) {
-    process.stderr.write("log note requires --field and --body\n");
-    process.exit(2);
+    io.stderr("log note requires --field and --body\n");
+    io.exit(2);
+    return;
   }
   const fieldBlock = `### ${values.field}\n\n${values.body}\n`;
   // Conservative line budget: assume we'll prepend a date heading.
@@ -82,28 +87,30 @@ function runNote(values) {
   const existing = existsSync(target) ? readFileSync(target, "utf-8") : "";
   const body = lastDateHeading(existing) === today ? fieldBlock : withHeading;
   appendEntry(target, body, agent, today);
-  process.stdout.write(`logged note to ${target}\n`);
+  io.stdout(`logged note to ${target}\n`);
 }
 
-function runDone(values) {
-  const { agent, wikiRoot, today } = commonContext(values);
+function runDone(values, io) {
+  const ctx = commonContext(values, io);
+  if (!ctx) return;
+  const { agent, wikiRoot, today } = ctx;
   const body = `### Closed\n\nRun closed ${today}.\n`;
   const lineCount = body.split("\n").length;
   rotateIfOverBudget(wikiRoot, agent, today, lineCount);
   const target = weeklyLogPath(wikiRoot, agent, today);
   appendEntry(target, body, agent, today);
-  process.stdout.write(`closed entry in ${target}\n`);
+  io.stdout(`closed entry in ${target}\n`);
 }
 
 const SUBS = { decision: runDecision, note: runNote, done: runDone };
 
 /** Dispatch `log {decision|note|done}` to the matching sub-handler. */
-export function runLogCommand(values, args, cli) {
+export function runLogCommand(values, args, cli, io = createDefaultIo()) {
   const sub = args[0];
   const handler = SUBS[sub];
   if (!handler) {
     cli.usageError("log requires subcommand: decision | note | done");
-    process.exit(2);
+    return io.exit(2);
   }
-  handler(values);
+  handler(values, io);
 }

package/src/commands/refresh.js

@@ -7,16 +7,16 @@ import { createScriptConfig } from "@forwardimpact/libconfig";
 import { scanMarkers } from "../marker-scanner.js";
 import { renderBlock, BlockRenderError } from "../block-renderer.js";
 import { renderIssueList, parseRepoSlug } from "../issue-list-renderer.js";
+import { createDefaultIo } from "../io.js";
 
-function currentStoryboardPath() {
-  const now = new Date();
+function currentStoryboardPath(now = new Date()) {
   const yyyy = now.getFullYear();
   const mm = String(now.getMonth() + 1).padStart(2, "0");
   return `wiki/storyboard-${yyyy}-M${mm}.md`;
 }
 
-function deriveParentRepo(parentDir) {
-  if (process.env.FIT_GH_REPO) return process.env.FIT_GH_REPO;
+function deriveParentRepo(parentDir, env) {
+  if (env.FIT_GH_REPO) return env.FIT_GH_REPO;
   const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
     encoding: "utf-8",
     stdio: "pipe",
@@ -55,10 +55,15 @@ function spliceBlock(lines, block, rendered) {
 }
 
 /** Re-render XmR chart blocks and issue-list blocks in a storyboard file. */
-export async function runRefreshCommand(values, args, _cli) {
+export async function runRefreshCommand(
+  values,
+  args,
+  _cli,
+  io = createDefaultIo(),
+) {
   const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
+  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
+  const projectRoot = finder.findProjectRoot(io.cwd());
 
   const storyboardPath = path.resolve(
     projectRoot,
@@ -84,7 +89,7 @@ export async function runRefreshCommand(values, args, _cli) {
   // overrides the parsed origin.
   const ghContext = {
     cwd: projectRoot,
-    repo: deriveParentRepo(projectRoot),
+    repo: deriveParentRepo(projectRoot, io.env),
     token,
   };
 
@@ -100,7 +105,7 @@ export async function runRefreshCommand(values, args, _cli) {
       spliced = true;
     } catch (err) {
       if (!(err instanceof BlockRenderError)) throw err;
-      process.stderr.write(
+      io.stderr(
         `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}\n`,
       );
     }
@@ -108,8 +113,6 @@ export async function runRefreshCommand(values, args, _cli) {
 
   if (spliced) writeFileSync(storyboardPath, lines.join("\n"));
   if (values && values.format === "json") {
-    process.stdout.write(
-      JSON.stringify({ blocks: blocks.length, spliced }) + "\n",
-    );
+    io.stdout(JSON.stringify({ blocks: blocks.length, spliced }) + "\n");
   }
 }

package/src/io.js

@@ -0,0 +1,77 @@
+/**
+ * Process-bound I/O collaborators shared across libwiki commands.
+ *
+ * Each command accepts an optional `io` argument; when omitted, the
+ * bound `process.*` defaults run. Tests construct a synthetic `io`
+ * (e.g. capturing stdout into a string and recording exit codes
+ * instead of terminating the runner) and call command handlers
+ * directly, avoiding `execFileSync("node", [...])`.
+ */
+export function createDefaultIo() {
+  return {
+    stdout: (s) => process.stdout.write(s),
+    stderr: (s) => process.stderr.write(s),
+    exit: (code) => process.exit(code),
+    cwd: () => process.cwd(),
+    env: process.env,
+    today: () => new Date().toISOString().slice(0, 10),
+  };
+}
+
+/**
+ * Test helper: synthetic `io` that captures stdout/stderr into strings
+ * and records exit codes instead of terminating the process. After a
+ * handler returns, inspect `out`/`err`/`exitCode` to assert behavior.
+ *
+ * @param {object} overrides - Per-test overrides (cwd, env, today).
+ * @returns {object} `{ stdout, stderr, exit, cwd, env, today, out, err, exitCode }`
+ */
+export function createTestIo(overrides = {}) {
+  const io = {
+    out: "",
+    err: "",
+    exitCode: null,
+    stdout(s) {
+      io.out += s;
+    },
+    stderr(s) {
+      io.err += s;
+    },
+    exit(code) {
+      io.exitCode = code;
+      throw new IoExit(code);
+    },
+    cwd: overrides.cwd ?? (() => process.cwd()),
+    env: overrides.env ?? process.env,
+    today: overrides.today ?? (() => new Date().toISOString().slice(0, 10)),
+  };
+  return io;
+}
+
+/**
+ * Thrown by `createTestIo`'s `exit` so handlers stop unwinding the way
+ * `process.exit` would. Tests can catch it or wrap calls in
+ * `runWithIo(() => handler(...), io)`.
+ */
+export class IoExit extends Error {
+  /** @param {number} code - Exit code the handler asked the process to exit with. */
+  constructor(code) {
+    super(`IoExit(${code})`);
+    this.name = "IoExit";
+    this.code = code;
+  }
+}
+
+/**
+ * Run a handler that may call `io.exit()`; swallow the synthetic
+ * IoExit so callers can inspect `io.exitCode` linearly without
+ * try/catch boilerplate.
+ */
+export async function runWithIo(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof IoExit) return undefined;
+    throw err;
+  }
+}