@forwardimpact/libwiki 0.1.2 → 0.1.5

package/README.md

@@ -1,7 +1,11 @@
 # libwiki
 
-Wiki lifecycle primitives for the Kata agent system. Provides cross-team memo
-delivery, agent roster discovery, and insertion-marker migration.
+<!-- BEGIN:description — Do not edit. Generated from package.json. -->
+
+Wiki lifecycle primitives — stable memory for agent teams so coordination
+persists across sessions.
+
+<!-- END:description -->
 
 ## Getting Started
 

package/bin/fit-wiki.js

@@ -101,8 +101,14 @@ const definition = {
   ],
   documentation: [
     {
-      title: "Wiki Operations",
-      url: "https://www.forwardimpact.team/docs/libraries/wiki-operations/index.md",
+      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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.1.2",
-  "description": "Wiki lifecycle primitives for the Kata agent system: cross-team memos, storyboard XmR chart refresh, wiki bootstrap, and git sync.",
+  "version": "0.1.5",
+  "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",
     "memo",
@@ -17,16 +17,16 @@
   },
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",
-  "forwardimpact": {
-    "capability": "agent-self-improvement",
-    "needs": [
-      "Send a cross-team memo to a teammate's wiki inbox",
-      "Refresh XmR chart blocks inside a storyboard markdown file",
-      "Bootstrap a wiki working tree for a Kata installation",
-      "Push agent-authored wiki changes to the remote",
-      "Pull remote wiki changes into the local working tree"
-    ]
-  },
+  "jobs": [
+    {
+      "user": "Empowered Engineers",
+      "goal": "Operate a Predictable Agent Team",
+      "trigger": "An agent finishes a session and its findings vanish because there is no shared memory to write them to.",
+      "bigHire": "give agent teams stable memory that persists across sessions.",
+      "littleHire": "send a memo or update a storyboard without managing the wiki infrastructure.",
+      "competesWith": "git commit messages as memory; ephemeral conversation context; starting every session from scratch"
+    }
+  ],
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
+    "@forwardimpact/libconfig": "^0.1.77",
     "@forwardimpact/libutil": "^0.1.0",
     "@forwardimpact/libxmr": "^1.1.0"
   },

package/src/agent-roster.js

@@ -2,6 +2,7 @@ import { readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { BROADCAST_TARGET } from "./constants.js";
 
+/** List all agent markdown files in the agents directory, returning agent names and summary paths. */
 export function listAgents(
   { agentsDir, wikiRoot },
   fs = { readdirSync, statSync },

package/src/block-renderer.js

@@ -2,13 +2,16 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { analyze, renderChart, MIN_POINTS } from "@forwardimpact/libxmr";
 
+/** Error thrown when an XmR block cannot be rendered due to missing CSV or metric. */
 export class BlockRenderError extends Error {
+  /** Create a BlockRenderError with the given reason string. */
   constructor(reason) {
     super(reason);
     this.name = "BlockRenderError";
   }
 }
 
+/** Render an XmR chart block for a metric by reading its CSV and producing markdown lines. */
 export function renderBlock({
   metric,
   csvPath,

package/src/commands/init.js

@@ -3,10 +3,14 @@ import { spawnSync } from "node:child_process";
 import path from "node:path";
 import fsAsync from "node:fs/promises";
 import { Finder } from "@forwardimpact/libutil";
+import { createScriptConfig } from "@forwardimpact/libconfig";
 import { WikiRepo } from "../wiki-repo.js";
 import { listSkills } from "../skill-roster.js";
 
-function deriveWikiUrl(parentDir) {
+/** 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;
+
   const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
     encoding: "utf-8",
     stdio: "pipe",
@@ -17,7 +21,8 @@ function deriveWikiUrl(parentDir) {
   return base + ".wiki.git";
 }
 
-export function runInitCommand(values, _args, cli) {
+/** Clone the wiki if not already present (URL derived from origin remote), copy git identity from the parent repo, and create metric directories for each kata skill. */
+export async function runInitCommand(values, _args, cli) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);
   const projectRoot = finder.findProjectRoot(process.cwd());
@@ -36,7 +41,12 @@ export function runInitCommand(values, _args, cli) {
     return;
   }
 
-  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+  const config = await createScriptConfig("wiki");
+  const repo = new WikiRepo({
+    wikiDir,
+    parentDir: projectRoot,
+    resolveToken: () => config.ghToken(),
+  });
 
   const cloneResult = repo.ensureCloned(wikiUrl);
   if (!cloneResult.cloned) {

package/src/commands/memo.js

@@ -15,6 +15,38 @@ function writeAndCheck(summaryPath, sender, message, today) {
   process.stdout.write(`wrote ${result.path}\n`);
 }
 
+function resolveTargetPath(wikiRoot, target) {
+  const summaryPath = path.join(wikiRoot, target + ".md");
+  const resolvedRoot = path.resolve(wikiRoot);
+  const resolvedTarget = path.resolve(summaryPath);
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  const escapesRoot =
+    relative === "" || relative.startsWith("..") || path.isAbsolute(relative);
+  return { summaryPath, escapesRoot };
+}
+
+function writeSingleTarget({ wikiRoot, target, sender, message, today, cli }) {
+  const { summaryPath, escapesRoot } = resolveTargetPath(wikiRoot, target);
+  if (escapesRoot) {
+    cli.usageError(`target escapes wiki root: ${target}`);
+    process.exit(2);
+  }
+  if (!existsSync(summaryPath)) {
+    cli.usageError(`target summary not found: ${summaryPath}`);
+    process.exit(2);
+  }
+  writeAndCheck(summaryPath, sender, message, today);
+}
+
+function writeBroadcast({ agentsDir, wikiRoot, sender, message, today }) {
+  const agents = listAgents({ agentsDir, wikiRoot });
+  for (const { agent, summaryPath } of agents) {
+    if (agent === sender) continue;
+    writeAndCheck(summaryPath, sender, message, today);
+  }
+}
+
+/** Write a memo to a target agent's summary file (or broadcast to all except the sender); sender is --from or LIBEVAL_AGENT_PROFILE env var. */
 export function runMemoCommand(values, _args, cli) {
   const sender = values.from || process.env.LIBEVAL_AGENT_PROFILE;
 
@@ -44,17 +76,21 @@ export function runMemoCommand(values, _args, cli) {
   const today = new Date().toISOString().slice(0, 10);
 
   if (values.to === BROADCAST_TARGET) {
-    const agents = listAgents({ agentsDir, wikiRoot });
-    for (const { agent, summaryPath } of agents) {
-      if (agent === sender) continue;
-      writeAndCheck(summaryPath, sender, values.message, today);
-    }
+    writeBroadcast({
+      agentsDir,
+      wikiRoot,
+      sender,
+      message: values.message,
+      today,
+    });
   } else {
-    const summaryPath = path.join(wikiRoot, values.to + ".md");
-    if (!existsSync(summaryPath)) {
-      cli.usageError(`target summary not found: ${summaryPath}`);
-      process.exit(2);
-    }
-    writeAndCheck(summaryPath, sender, values.message, today);
+    writeSingleTarget({
+      wikiRoot,
+      target: values.to,
+      sender,
+      message: values.message,
+      today,
+      cli,
+    });
   }
 }

package/src/commands/refresh.js

@@ -12,6 +12,7 @@ function currentStoryboardPath() {
   return `wiki/storyboard-${yyyy}-M${mm}.md`;
 }
 
+/** Re-render all XmR chart blocks in a storyboard file by scanning markers and splicing updated content. */
 export function runRefreshCommand(values, args, cli) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);

package/src/commands/sync.js

@@ -1,15 +1,26 @@
 import path from "node:path";
 import fsAsync from "node:fs/promises";
 import { Finder } from "@forwardimpact/libutil";
+import { createScriptConfig } from "@forwardimpact/libconfig";
 import { WikiRepo, WikiPullConflict } from "../wiki-repo.js";
 
-export function runPushCommand(values, _args, cli) {
+async function buildRepo(values) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);
   const projectRoot = finder.findProjectRoot(process.cwd());
   const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
 
-  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+  const config = await createScriptConfig("wiki");
+  return new WikiRepo({
+    wikiDir,
+    parentDir: projectRoot,
+    resolveToken: () => config.ghToken(),
+  });
+}
+
+/** Commit all wiki changes and push them to the remote wiki repository. */
+export async function runPushCommand(values, _args, cli) {
+  const repo = await buildRepo(values);
   repo.inheritIdentity();
 
   const result = repo.commitAndPush("wiki: update from session");
@@ -20,13 +31,9 @@ export function runPushCommand(values, _args, cli) {
   }
 }
 
-export function runPullCommand(values, _args, cli) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
-  const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
-
-  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+/** Fetch and rebase the local wiki on origin/master; on rebase conflict, exit the process with code 1 and a message to resolve manually or push first. */
+export async function runPullCommand(values, _args, cli) {
+  const repo = await buildRepo(values);
   repo.inheritIdentity();
 
   try {

package/src/marker-migrator.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { MEMO_INBOX_MARKER, INBOX_HEADING } from "./constants.js";
 import { listAgents } from "./agent-roster.js";
 
+/** Insert memo:inbox markers into agent summary files that have an inbox heading but no marker yet. */
 export function insertMarkers(
   { agentsDir, wikiRoot },
   fs = { readFileSync, writeFileSync },

package/src/marker-scanner.js

@@ -1,6 +1,7 @@
 const OPEN_RE = /^<!--\s*xmr:([^:\s]+):([^\s]+)\s*-->\s*$/;
 const CLOSE_RE = /^<!--\s*\/xmr\s*-->\s*$/;
 
+/** Scan text for paired xmr open/close HTML comment markers and return their line positions and metadata. */
 export function scanMarkers(text) {
   const lines = text.split("\n");
   const pairs = [];

package/src/memo-writer.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { MEMO_INBOX_MARKER } from "./constants.js";
 
+/** Append a timestamped memo bullet below the inbox marker in an agent's summary file. */
 export function writeMemo(
   { summaryPath, sender, message, today },
   fs = { readFileSync, writeFileSync },

package/src/skill-roster.js

@@ -1,6 +1,7 @@
 import { readdirSync, statSync } from "node:fs";
 import path from "node:path";
 
+/** List all kata-prefixed skill directory names under the skills directory, sorted alphabetically. */
 export function listSkills({ skillsDir }, fs = { readdirSync, statSync }) {
   const entries = fs.readdirSync(skillsDir);
   const skills = [];

package/src/wiki-repo.js

@@ -3,7 +3,9 @@ import { spawnSync } from "node:child_process";
 const CREDENTIAL_HELPER_BODY =
   '!f() { echo username=x-access-token; echo "password=${GH_TOKEN:-$GITHUB_TOKEN}"; }; f';
 
+/** Error thrown when a wiki pull encounters a rebase conflict that cannot be resolved automatically. */
 export class WikiPullConflict extends Error {
+  /** Create a WikiPullConflict with the stderr output from the failed rebase. */
   constructor(stderr) {
     super("rebase conflict on pull");
     this.name = "WikiPullConflict";
@@ -11,6 +13,7 @@ export class WikiPullConflict extends Error {
   }
 }
 
+/** Prepend credential-helper config arguments to a git command when a token is available. */
 export function buildAuthArgs(args, token) {
   if (token) {
     return [
@@ -24,15 +27,38 @@ export function buildAuthArgs(args, token) {
   return [...args];
 }
 
+/** Git operations wrapper for the GitHub wiki repository used as agent team memory. */
 export class WikiRepo {
   #wikiDir;
   #parentDir;
+  #resolveToken;
 
-  constructor({ wikiDir, parentDir }) {
+  /**
+   * Create a WikiRepo targeting the given wiki directory and its parent project directory.
+   * @param {{ wikiDir: string, parentDir: string, resolveToken: () => string | null }} opts
+   *   `resolveToken` is called lazily before each network operation. Return a
+   *   GitHub token string to authenticate, or `null` to run anonymously. The
+   *   callback owns the entire resolution policy — libwiki does not read
+   *   `process.env` directly. Throws propagate to the caller so credential
+   *   misconfiguration surfaces loudly. Commands typically pass
+   *   `() => config.ghToken()` from `@forwardimpact/libconfig`.
+   */
+  constructor({ wikiDir, parentDir, resolveToken }) {
+    if (typeof wikiDir !== "string" || wikiDir === "") {
+      throw new TypeError("WikiRepo: wikiDir must be a non-empty string");
+    }
+    if (typeof parentDir !== "string" || parentDir === "") {
+      throw new TypeError("WikiRepo: parentDir must be a non-empty string");
+    }
+    if (typeof resolveToken !== "function") {
+      throw new TypeError("WikiRepo: resolveToken callback is required");
+    }
     this.#wikiDir = wikiDir;
     this.#parentDir = parentDir;
+    this.#resolveToken = resolveToken;
   }
 
+  /** Check whether the wiki directory is an initialized git repository. */
   isCloned() {
     const r = spawnSync(
       "git",
@@ -44,6 +70,7 @@ export class WikiRepo {
     return r.status === 0;
   }
 
+  /** Clone the wiki from the given URL if it is not already cloned. */
   ensureCloned(url) {
     if (this.isCloned()) return { cloned: true, reason: "already-cloned" };
     const r = this.#authGit(["clone", url, this.#wikiDir]);
@@ -56,6 +83,7 @@ export class WikiRepo {
     return { cloned: true, reason: "cloned" };
   }
 
+  /** Copy git user.name and user.email from the parent repository into the wiki repository. */
   inheritIdentity() {
     const name = this.#parentConfig("user.name");
     const email = this.#parentConfig("user.email");
@@ -63,15 +91,18 @@ export class WikiRepo {
     if (email) this.#git(["config", "user.email", email]);
   }
 
+  /** Fetch the latest master branch from the wiki remote using token auth if available. */
   fetch() {
     this.#authGit(["-C", this.#wikiDir, "fetch", "origin", "master"]);
   }
 
+  /** Return true if the wiki working tree has no uncommitted changes. */
   isClean() {
     const r = this.#git(["status", "--porcelain"]);
     return r.stdout.toString().trim() === "";
   }
 
+  /** Fetch and rebase on origin/master, throwing WikiPullConflict if the rebase fails. */
   pull() {
     this.fetch();
     const r = this.#git(["rebase", "origin/master"]);
@@ -81,10 +112,16 @@ export class WikiRepo {
     }
   }
 
+  /** Stage and commit any working-tree changes, then fetch, rebase on origin/master (falling back to a merge with -X ours if rebase fails), and push if HEAD is ahead of origin/master. The commit gate and the push gate are independent so a clean tree with local commits still pushes. */
   commitAndPush(message) {
-    if (this.isClean()) return { pushed: false, reason: "clean" };
-    this.#git(["add", "-A"]);
-    this.#git(["commit", "-m", message]);
+    const hasWorkingTreeChanges = !this.isClean();
+    if (hasWorkingTreeChanges) {
+      this.#git(["add", "-A"]);
+      this.#git(["commit", "-m", message]);
+    }
+    if (!this.#hasCommitsAhead()) {
+      return { pushed: false, reason: "clean" };
+    }
     this.fetch();
     const rebase = this.#git(["rebase", "origin/master"]);
     if (rebase.status !== 0) {
@@ -95,6 +132,12 @@ export class WikiRepo {
     return { pushed: true, reason: "pushed" };
   }
 
+  #hasCommitsAhead() {
+    const r = this.#git(["rev-list", "--count", "origin/master..HEAD"]);
+    const count = parseInt(r.stdout?.toString().trim() || "0", 10);
+    return count > 0;
+  }
+
   #parentConfig(key) {
     const r = spawnSync(
       "git",
@@ -111,11 +154,14 @@ export class WikiRepo {
   }
 
   #authGit(args) {
-    const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    const token = this.#resolveToken();
     const fullArgs = buildAuthArgs(args, token);
-    return spawnSync("git", fullArgs, {
-      stdio: "pipe",
-      env: token ? process.env : undefined,
-    });
+    // The credential helper body keeps `${GH_TOKEN:-$GITHUB_TOKEN}` literal so
+    // git's child shell expands it at auth time — the token never sits in argv.
+    // Inject the resolved token into the spawn env so the helper's lazy
+    // expansion finds it even when the resolver pulled from `.env` or
+    // `gh auth token` rather than the ambient process env.
+    const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+    return spawnSync("git", fullArgs, { stdio: "pipe", env });
   }
 }