@forwardimpact/libwiki 0.1.2 → 0.1.3

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.3",
+  "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": {

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

@@ -17,6 +17,7 @@ function deriveWikiUrl(parentDir) {
   return base + ".wiki.git";
 }
 
+/** 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 function runInitCommand(values, _args, cli) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);

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

@@ -3,6 +3,7 @@ import fsAsync from "node:fs/promises";
 import { Finder } from "@forwardimpact/libutil";
 import { WikiRepo, WikiPullConflict } from "../wiki-repo.js";
 
+/** Commit all wiki changes and push them to the remote wiki repository. */
 export function runPushCommand(values, _args, cli) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);
@@ -20,6 +21,7 @@ export function runPushCommand(values, _args, cli) {
   }
 }
 
+/** 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 function runPullCommand(values, _args, cli) {
   const logger = { debug() {} };
   const finder = new Finder(fsAsync, logger, process);

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,18 @@ 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;
 
+  /** Create a WikiRepo targeting the given wiki directory and its parent project directory. */
   constructor({ wikiDir, parentDir }) {
     this.#wikiDir = wikiDir;
     this.#parentDir = parentDir;
   }
 
+  /** Check whether the wiki directory is an initialized git repository. */
   isCloned() {
     const r = spawnSync(
       "git",
@@ -44,6 +50,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 +63,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 +71,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,6 +92,7 @@ export class WikiRepo {
     }
   }
 
+  /** Stage all changes, commit with the given message, fetch, rebase on origin/master (falling back to a merge with -X ours if rebase fails), and push. */
   commitAndPush(message) {
     if (this.isClean()) return { pushed: false, reason: "clean" };
     this.#git(["add", "-A"]);