@forwardimpact/libwiki 0.2.11 → 0.2.13

package/src/boot.js

@@ -1,17 +1,15 @@
-import { readFileSync, existsSync } from "node:fs";
 import path from "node:path";
+import { yearMonth } from "@forwardimpact/libutil";
 import { parseClaims, filterExpired } from "./active-claims.js";
 import { MEMO_INBOX_MARKER, PRIORITY_INDEX_HEADING } from "./constants.js";
 
-function readIfExists(filePath) {
-  if (!existsSync(filePath)) return null;
-  return readFileSync(filePath, "utf-8");
+function readIfExists(fs, filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return fs.readFileSync(filePath, "utf-8");
 }
 
-function currentStoryboardPath(wikiRoot, date) {
-  const yyyy = date.getUTCFullYear();
-  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
-  return path.join(wikiRoot, `storyboard-${yyyy}-M${mm}.md`);
+function currentStoryboardPath(wikiRoot, today) {
+  return path.join(wikiRoot, `storyboard-${yearMonth(today)}.md`);
 }
 
 function extractSummary(text) {
@@ -146,20 +144,22 @@ function mapClaim(c) {
   };
 }
 
-/** Build the boot digest JSON object. */
-export function buildDigest({ wikiRoot, agent, today, _fs, _gh }) {
-  const date = today instanceof Date ? today : new Date(today);
-  const todayStr = date.toISOString().slice(0, 10);
-
+/**
+ * Build the boot digest JSON object.
+ * @param {{wikiRoot: string, agent: string, today: string, fs: object}} options
+ *   `fs` is the sync filesystem surface (`runtime.fsSync`); `today` is an ISO
+ *   date string.
+ */
+export function buildDigest({ wikiRoot, agent, today, fs }) {
   const summaryPath = path.join(wikiRoot, `${agent}.md`);
   const memoryPath = path.join(wikiRoot, "MEMORY.md");
-  const storyboardPath = currentStoryboardPath(wikiRoot, date);
+  const storyboardPath = currentStoryboardPath(wikiRoot, today);
 
-  const summaryText = readIfExists(summaryPath);
-  const memoryText = readIfExists(memoryPath);
-  const storyboardText = readIfExists(storyboardPath);
+  const summaryText = readIfExists(fs, summaryPath);
+  const memoryText = readIfExists(fs, memoryPath);
+  const storyboardText = readIfExists(fs, storyboardPath);
 
-  const { active } = filterExpired(parseClaims(memoryText ?? ""), todayStr);
+  const { active } = filterExpired(parseClaims(memoryText ?? ""), today);
   const { owned, cross } = splitPriorities(
     parsePriorityTable(memoryText ?? ""),
     agent,
@@ -172,7 +172,7 @@ export function buildDigest({ wikiRoot, agent, today, _fs, _gh }) {
     claims: active.map(mapClaim),
     storyboard_items: parseStoryboardItems(storyboardText ?? "", agent),
     inbox_count: countInbox(summaryText),
-    storyboard_path: existsSync(storyboardPath)
+    storyboard_path: fs.existsSync(storyboardPath)
       ? path.relative(path.dirname(wikiRoot) || ".", storyboardPath)
       : "",
   };

package/src/cli-definition.js

@@ -0,0 +1,284 @@
+import { runMemoCommand } from "./commands/memo.js";
+import { runRefreshCommand } from "./commands/refresh.js";
+import { runInitCommand } from "./commands/init.js";
+import { runPushCommand, runPullCommand } from "./commands/sync.js";
+import { runBootCommand } from "./commands/boot.js";
+import { runLogCommand } from "./commands/log.js";
+import { runClaimCommand, runReleaseCommand } from "./commands/claim.js";
+import { runInboxCommand } from "./commands/inbox.js";
+import { runRotateCommand } from "./commands/rotate.js";
+import { runAuditCommand } from "./commands/audit.js";
+import { runFixCommand } from "./commands/fix.js";
+
+/**
+ * Build the `fit-wiki` libcli definition. The agent/sender defaults read the
+ * injected `env` rather than the ambient `process.env` so this module carries
+ * no ambient dependency; the bin shim passes `runtime.proc.env` and the
+ * package version. Each subcommand carries a `handler` and (for subcommand-
+ * bearing commands) `args`/`argsUsage` so `cli.dispatch` can route to the
+ * per-command handler with a frozen `ctx`.
+ *
+ * @param {Record<string, string>} env - The process env (`runtime.proc.env`).
+ * @param {string} version - The package version string.
+ * @returns {object} The libcli definition.
+ */
+export function createDefinition(env, version) {
+  const wikiRootOpt = {
+    "wiki-root": {
+      type: "string",
+      description: "Override wiki root directory (default: wiki)",
+    },
+  };
+
+  const agentOpt = {
+    agent: {
+      type: "string",
+      description:
+        "Agent name (falls back to LIBEVAL_AGENT_PROFILE, then staff-engineer)",
+      default: env.LIBEVAL_AGENT_PROFILE || "staff-engineer",
+    },
+  };
+
+  const todayOpt = {
+    today: {
+      type: "string",
+      description: "Override today's ISO date (testing)",
+    },
+  };
+
+  return {
+    name: "fit-wiki",
+    version,
+    description: "Wiki lifecycle management for the Kata agent system",
+    commands: [
+      {
+        name: "boot",
+        description:
+          "Print on-boot digest (priorities, claims, storyboard items) as JSON",
+        handler: runBootCommand,
+        options: {
+          ...agentOpt,
+          ...wikiRootOpt,
+          ...todayOpt,
+          format: {
+            type: "string",
+            description: "Output format: json (default) or markdown",
+          },
+        },
+      },
+      {
+        name: "log",
+        description:
+          "Append a decision/note/done entry to the current weekly log",
+        args: ["subcommand"],
+        argsUsage: "[subcommand]",
+        handler: runLogCommand,
+        options: {
+          ...agentOpt,
+          ...wikiRootOpt,
+          ...todayOpt,
+          surveyed: {
+            type: "string",
+            description: "Decision: routing levels surveyed",
+          },
+          chosen: { type: "string", description: "Decision: chosen action" },
+          rationale: { type: "string", description: "Decision: rationale" },
+          alternatives: {
+            type: "string",
+            description: "Decision: alternatives",
+          },
+          field: { type: "string", description: "Note: field heading" },
+          body: { type: "string", description: "Note: field body" },
+        },
+      },
+      {
+        name: "claim",
+        description:
+          "Claim a target in MEMORY.md ## Active Claims (refuses duplicates)",
+        handler: runClaimCommand,
+        options: {
+          ...agentOpt,
+          ...wikiRootOpt,
+          ...todayOpt,
+          target: {
+            type: "string",
+            description: "What is being claimed (spec id, PR id, etc.)",
+          },
+          branch: { type: "string", description: "Branch carrying the work" },
+          pr: { type: "string", description: "Optional PR id" },
+          "expires-at": {
+            type: "string",
+            description: "Override expiry ISO date (default claim+7d)",
+          },
+        },
+      },
+      {
+        name: "release",
+        description: "Release a claim (or all expired claims with --expired)",
+        handler: runReleaseCommand,
+        options: {
+          ...agentOpt,
+          ...wikiRootOpt,
+          ...todayOpt,
+          target: { type: "string", description: "Target to release" },
+          expired: {
+            type: "boolean",
+            description: "Release every row past expires_at",
+          },
+        },
+      },
+      {
+        name: "inbox",
+        description: "Triage the agent's Message Inbox (list/ack/promote/drop)",
+        args: ["subcommand"],
+        argsUsage: "[subcommand]",
+        handler: runInboxCommand,
+        options: {
+          ...agentOpt,
+          ...wikiRootOpt,
+          ...todayOpt,
+          index: {
+            type: "string",
+            description: "Bullet index (0-based) for ack/promote/drop",
+          },
+          owner: {
+            type: "string",
+            description: "Owner field when promoting (default: --agent)",
+          },
+        },
+      },
+      {
+        name: "rotate",
+        description: "Force-rotate the current weekly log to a sealed part",
+        handler: runRotateCommand,
+        options: {
+          ...agentOpt,
+          ...wikiRootOpt,
+          ...todayOpt,
+        },
+      },
+      {
+        name: "audit",
+        description:
+          "Audit the wiki against the declarative rule catalogue (line and word budgets, headings, decision blocks, storyboards, claims)",
+        handler: runAuditCommand,
+        options: {
+          ...wikiRootOpt,
+          ...todayOpt,
+          format: {
+            type: "string",
+            description: "Output format: text (default) or json",
+          },
+        },
+      },
+      {
+        name: "fix",
+        description:
+          "Auto-fix wiki audit findings using an AI agent (technical-writer, Haiku)",
+        handler: runFixCommand,
+        options: {
+          ...wikiRootOpt,
+          ...todayOpt,
+        },
+      },
+      {
+        name: "memo",
+        description: "Send a cross-team memo into a teammate's Message Inbox",
+        handler: runMemoCommand,
+        options: {
+          from: {
+            type: "string",
+            description:
+              "Sender agent name (falls back to LIBEVAL_AGENT_PROFILE env var)",
+            default: env.LIBEVAL_AGENT_PROFILE,
+          },
+          to: {
+            type: "string",
+            description:
+              'Target agent name, or "all" to broadcast (sender is skipped)',
+          },
+          message: {
+            type: "string",
+            description: "Memo text",
+          },
+          ...wikiRootOpt,
+        },
+      },
+      {
+        name: "refresh",
+        description:
+          "Regenerate XmR and obstacle/experiment marker blocks in a storyboard",
+        args: ["storyboard-path"],
+        argsUsage: "[storyboard-path]",
+        handler: runRefreshCommand,
+        options: {
+          format: {
+            type: "string",
+            description: "Output format: (default off) or json",
+          },
+        },
+      },
+      {
+        name: "init",
+        description: "Bootstrap a wiki working tree and scaffold Active Claims",
+        handler: runInitCommand,
+        options: {
+          ...wikiRootOpt,
+          "skills-dir": {
+            type: "string",
+            description: "Override skills directory (default: .claude/skills)",
+          },
+        },
+      },
+      {
+        name: "push",
+        description: "Commit and push local wiki changes to the remote",
+        handler: runPushCommand,
+        options: { ...wikiRootOpt },
+      },
+      {
+        name: "pull",
+        description: "Pull remote wiki changes into the local working tree",
+        handler: runPullCommand,
+        options: { ...wikiRootOpt },
+      },
+    ],
+    globalOptions: {
+      help: { type: "boolean", short: "h", description: "Show this help" },
+      version: { type: "boolean", description: "Show version" },
+      json: {
+        type: "boolean",
+        description: "Render --help output as JSON",
+      },
+    },
+    examples: [
+      "fit-wiki boot --agent staff-engineer",
+      'fit-wiki log decision --agent staff-engineer --surveyed "..." --chosen "..." --rationale "..."',
+      "fit-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
+      "fit-wiki release --agent staff-engineer --target spec-NNNN",
+      "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",
+      "fit-wiki push",
+      "fit-wiki pull",
+    ],
+    documentation: [
+      {
+        title: "Operate a Predictable Agent Team",
+        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/index.md",
+        description:
+          "End-to-end guide to wiki memory, XmR charts, and team coordination.",
+      },
+      {
+        title: "Send a Memo or Update a Storyboard",
+        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-operations/index.md",
+        description:
+          "Send cross-team memos, refresh storyboard charts, and sync the wiki.",
+      },
+    ],
+  };
+}

package/src/commands/audit.js

@@ -1,26 +1,27 @@
-import fsAsync from "node:fs/promises";
 import path from "node:path";
 import {
-  Finder,
   emitFindingsJson,
   emitFindingsText,
   runRules,
 } from "@forwardimpact/libutil";
 import { RULES } from "../audit/rules.js";
 import { buildContext, resolveScope } from "../audit/scopes.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveProjectRoot } from "../util/wiki-dir.js";
 
 /** Run the wiki audit and emit findings. JSON via --format json. */
-export function runAuditCommand(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);
+export function runAuditCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const options = ctx.options;
+  const projectRoot = resolveProjectRoot(runtime);
+  const wikiRoot = options["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = options.today || currentDayIso(runtime);
 
-  const ctx = buildContext({ wikiRoot, today });
-  const findings = runRules(RULES, ctx, { resolveScope });
+  const auditCtx = buildContext({ wikiRoot, today, fs: runtime.fsSync });
+  const findings = runRules(RULES, auditCtx, { resolveScope });
 
-  process.stdout.write(
-    values.format === "json"
+  runtime.proc.stdout.write(
+    options.format === "json"
       ? emitFindingsJson(findings)
       : emitFindingsText(findings, {
           cwd: projectRoot,
@@ -28,5 +29,6 @@ export function runAuditCommand(values, _args, _cli) {
         }),
   );
 
-  if (findings.some((f) => f.level === "fail")) process.exit(1);
+  if (findings.some((f) => f.level === "fail")) return { ok: false, code: 1 };
+  return { ok: true };
 }

package/src/commands/boot.js

@@ -1,7 +1,6 @@
-import fsAsync from "node:fs/promises";
-import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
 import { buildDigest } from "../boot.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 function renderMarkdown(digest) {
   const lines = [];
@@ -41,21 +40,21 @@ function renderMarkdown(digest) {
 }
 
 /** Print the on-boot digest for the calling agent. JSON by default; --format markdown renders prose. */
-export function runBootCommand(values, _args, cli) {
+export function runBootCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const options = ctx.options;
   const agent =
-    values.agent || process.env.LIBEVAL_AGENT_PROFILE || "staff-engineer";
+    options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE || "staff-engineer";
 
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, 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 wikiRoot = resolveWikiRoot(runtime, options);
+  const today = options.today || currentDayIso(runtime);
 
-  const digest = buildDigest({ wikiRoot, agent, today });
+  const digest = buildDigest({ wikiRoot, agent, today, fs: runtime.fsSync });
 
-  if ((values.format || "json") === "markdown") {
-    process.stdout.write(renderMarkdown(digest) + "\n");
+  if ((options.format || "json") === "markdown") {
+    runtime.proc.stdout.write(renderMarkdown(digest) + "\n");
   } else {
-    process.stdout.write(JSON.stringify(digest, null, 2) + "\n");
+    runtime.proc.stdout.write(JSON.stringify(digest, null, 2) + "\n");
   }
+  return { ok: true };
 }

package/src/commands/claim.js

@@ -1,102 +1,87 @@
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import fsAsync from "node:fs/promises";
 import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
+import { addDays } from "@forwardimpact/libutil";
 import {
   appendClaim,
   removeClaim,
   parseClaims,
   filterExpired,
 } from "../active-claims.js";
-import { createDefaultIo } from "../io.js";
-import { buildRepo } from "../build-repo.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
 
-function projectRoot(io) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
-  return finder.findProjectRoot(io.cwd());
+function readMemory(runtime, memPath) {
+  if (!runtime.fsSync.existsSync(memPath)) return "";
+  return runtime.fsSync.readFileSync(memPath, "utf-8");
 }
 
-function memoryPath(values, io) {
-  const root = projectRoot(io);
-  const wikiRoot = values["wiki-root"] || path.join(root, "wiki");
-  return path.join(wikiRoot, "MEMORY.md");
+function memoryPath(runtime, options) {
+  return path.join(resolveWikiRoot(runtime, options), "MEMORY.md");
 }
 
-function readMemory(memPath) {
-  if (!existsSync(memPath)) return "";
-  return readFileSync(memPath, "utf-8");
-}
-
-function addDays(today, n) {
-  const d = new Date(today);
-  d.setUTCDate(d.getUTCDate() + n);
-  return d.toISOString().slice(0, 10);
-}
-
-async function pushWiki(repoFactory, values, io, message) {
-  if (!repoFactory) return;
+async function pushWiki(wikiSync, runtime, message) {
+  if (!wikiSync) return;
   try {
-    const repo = await repoFactory(values, io.cwd());
-    repo.inheritIdentity();
-    const result = repo.commitAndPush(message);
-    if (result.pushed) io.stdout("push: committed and pushed\n");
+    await wikiSync.inheritIdentity();
+    const result = await wikiSync.commitAndPush(message);
+    if (result.pushed)
+      runtime.proc.stdout.write("push: committed and pushed\n");
   } catch (err) {
-    io.stderr(`push failed (saved locally): ${err.message}\n`);
+    runtime.proc.stderr.write(`push failed (saved locally): ${err.message}\n`);
   }
 }
 
 /** Insert a row into MEMORY.md `## Active Claims`. Refuses if (agent, target) already present. */
-export async function runClaimCommand(
-  values,
-  _args,
-  cli,
-  io = createDefaultIo(),
-  repoFactory = buildRepo,
-) {
-  const agent = values.agent || io.env.LIBEVAL_AGENT_PROFILE;
+export async function runClaimCommand(ctx) {
+  const { runtime, wikiSync } = ctx.deps;
+  const options = ctx.options;
+  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    cli.usageError("claim requires --agent or LIBEVAL_AGENT_PROFILE");
-    return io.exit(2);
+    return {
+      ok: false,
+      code: 2,
+      error: "claim requires --agent or LIBEVAL_AGENT_PROFILE",
+    };
   }
-  if (!values.target || !values.branch) {
-    cli.usageError("claim requires --target and --branch");
-    return io.exit(2);
+  if (!options.target || !options.branch) {
+    return {
+      ok: false,
+      code: 2,
+      error: "claim requires --target and --branch",
+    };
   }
-  const today = values.today || io.today();
-  const expires = values["expires-at"] || addDays(today, 7);
-  const memPath = memoryPath(values, io);
-  const text = readMemory(memPath);
+  const today = options.today || currentDayIso(runtime);
+  const expires = options["expires-at"] || addDays(today, 7);
+  const memPath = memoryPath(runtime, options);
+  const text = readMemory(runtime, memPath);
   const result = appendClaim(text, {
     agent,
-    target: values.target,
-    branch: values.branch,
-    pr: values.pr || null,
+    target: options.target,
+    branch: options.branch,
+    pr: options.pr || null,
     claimed_at: today,
     expires_at: expires,
   });
   if (!result.inserted) {
-    io.stderr(`claim already exists for ${agent}/${values.target}\n`);
-    return io.exit(2);
+    runtime.proc.stderr.write(
+      `claim already exists for ${agent}/${options.target}\n`,
+    );
+    return { ok: false, code: 2 };
   }
-  writeFileSync(memPath, result.text);
-  io.stdout(`claimed ${values.target} (expires ${expires})\n`);
-  await pushWiki(repoFactory, values, io, `wiki: claim ${values.target}`);
+  runtime.fsSync.writeFileSync(memPath, result.text);
+  runtime.proc.stdout.write(`claimed ${options.target} (expires ${expires})\n`);
+  await pushWiki(wikiSync, runtime, `wiki: claim ${options.target}`);
+  return { ok: true };
 }
 
 /** Remove a claim row. `--expired` cleans every row past expires_at. */
-export async function runReleaseCommand(
-  values,
-  _args,
-  cli,
-  io = createDefaultIo(),
-  repoFactory = buildRepo,
-) {
-  const memPath = memoryPath(values, io);
-  const text = readMemory(memPath);
+export async function runReleaseCommand(ctx) {
+  const { runtime, wikiSync } = ctx.deps;
+  const options = ctx.options;
+  const memPath = memoryPath(runtime, options);
+  const text = readMemory(runtime, memPath);
 
-  if (values.expired) {
-    const today = values.today || io.today();
+  if (options.expired) {
+    const today = options.today || currentDayIso(runtime);
     const claims = parseClaims(text);
     const { expired } = filterExpired(claims, today);
     let current = text;
@@ -108,27 +93,36 @@ export async function runReleaseCommand(
         count++;
       }
     }
-    writeFileSync(memPath, current);
-    io.stdout(`released ${count} expired claim(s)\n`);
-    await pushWiki(repoFactory, values, io, "wiki: release expired claims");
-    return;
+    runtime.fsSync.writeFileSync(memPath, current);
+    runtime.proc.stdout.write(`released ${count} expired claim(s)\n`);
+    await pushWiki(wikiSync, runtime, "wiki: release expired claims");
+    return { ok: true };
   }
 
-  const agent = values.agent || io.env.LIBEVAL_AGENT_PROFILE;
+  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    cli.usageError("release requires --agent or --expired");
-    return io.exit(2);
+    return {
+      ok: false,
+      code: 2,
+      error: "release requires --agent or --expired",
+    };
   }
-  if (!values.target) {
-    cli.usageError("release requires --target (or --expired)");
-    return io.exit(2);
+  if (!options.target) {
+    return {
+      ok: false,
+      code: 2,
+      error: "release requires --target (or --expired)",
+    };
   }
-  const result = removeClaim(text, { agent, target: values.target });
-  writeFileSync(memPath, result.text);
+  const result = removeClaim(text, { agent, target: options.target });
+  runtime.fsSync.writeFileSync(memPath, result.text);
   if (!result.removed) {
-    io.stdout(`no matching claim for ${agent}/${values.target}\n`);
+    runtime.proc.stdout.write(
+      `no matching claim for ${agent}/${options.target}\n`,
+    );
   } else {
-    io.stdout(`released ${values.target}\n`);
-    await pushWiki(repoFactory, values, io, `wiki: release ${values.target}`);
+    runtime.proc.stdout.write(`released ${options.target}\n`);
+    await pushWiki(wikiSync, runtime, `wiki: release ${options.target}`);
   }
+  return { ok: true };
 }