@forwardimpact/libwiki 0.1.1 → 0.1.2

package/bin/fit-wiki.js

@@ -4,6 +4,9 @@ import { readFileSync } from "node:fs";
 import { createCli } from "@forwardimpact/libcli";
 
 import { runMemoCommand } from "../src/commands/memo.js";
+import { runRefreshCommand } from "../src/commands/refresh.js";
+import { runInitCommand } from "../src/commands/init.js";
+import { runPushCommand, runPullCommand } from "../src/commands/sync.js";
 
 const { version: VERSION } = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -38,6 +41,46 @@ const definition = {
         },
       },
     },
+    {
+      name: "refresh",
+      description:
+        "Regenerate XmR chart blocks inside a storyboard markdown file",
+      args: "[storyboard-path]",
+    },
+    {
+      name: "init",
+      description: "Bootstrap a wiki working tree for a Kata installation",
+      options: {
+        "wiki-root": {
+          type: "string",
+          description: "Override wiki root directory (default: wiki)",
+        },
+        "skills-dir": {
+          type: "string",
+          description: "Override skills directory (default: .claude/skills)",
+        },
+      },
+    },
+    {
+      name: "push",
+      description: "Commit and push local wiki changes to the remote",
+      options: {
+        "wiki-root": {
+          type: "string",
+          description: "Override wiki root directory (default: wiki)",
+        },
+      },
+    },
+    {
+      name: "pull",
+      description: "Pull remote wiki changes into the local working tree",
+      options: {
+        "wiki-root": {
+          type: "string",
+          description: "Override wiki root directory (default: wiki)",
+        },
+      },
+    },
   ],
   globalOptions: {
     help: { type: "boolean", short: "h", description: "Show this help" },
@@ -50,13 +93,18 @@ const definition = {
   examples: [
     'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
     'fit-wiki memo --from technical-writer --to all --message "new XmR baseline"',
+    "fit-wiki refresh",
+    "fit-wiki refresh wiki/storyboard-2026-M05.md",
+    "fit-wiki init",
+    "fit-wiki push",
+    "fit-wiki pull",
   ],
   documentation: [
     {
       title: "Wiki Operations",
       url: "https://www.forwardimpact.team/docs/libraries/wiki-operations/index.md",
       description:
-        "Send cross-team memos, discover agents, and manage wiki markers.",
+        "Send cross-team memos, refresh storyboard charts, and sync the wiki.",
     },
   ],
 };
@@ -65,6 +113,10 @@ const cli = createCli(definition);
 
 const COMMANDS = {
   memo: runMemoCommand,
+  refresh: runRefreshCommand,
+  init: runInitCommand,
+  push: runPushCommand,
+  pull: runPullCommand,
 };
 
 function main() {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.1.1",
-  "description": "Wiki lifecycle primitives for the Kata agent system: cross-team memos, agent roster discovery, and marker migration.",
+  "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.",
   "keywords": [
     "wiki",
     "memo",
-    "inbox",
+    "storyboard",
+    "xmr",
     "agent"
   ],
   "homepage": "https://www.forwardimpact.team",
@@ -19,7 +20,11 @@
   "forwardimpact": {
     "capability": "agent-self-improvement",
     "needs": [
-      "Send a cross-team memo to a teammate's wiki inbox"
+      "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"
     ]
   },
   "type": "module",
@@ -41,7 +46,8 @@
   },
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
-    "@forwardimpact/libutil": "^0.1.0"
+    "@forwardimpact/libutil": "^0.1.0",
+    "@forwardimpact/libxmr": "^1.1.0"
   },
   "devDependencies": {
     "@forwardimpact/libharness": "^0.1.5"

package/src/block-renderer.js

@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { analyze, renderChart, MIN_POINTS } from "@forwardimpact/libxmr";
+
+export class BlockRenderError extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "BlockRenderError";
+  }
+}
+
+export function renderBlock({
+  metric,
+  csvPath,
+  projectRoot,
+  fs = { readFileSync },
+}) {
+  const fullPath = path.resolve(projectRoot, csvPath);
+  let csvText;
+  try {
+    csvText = fs.readFileSync(fullPath, "utf-8");
+  } catch {
+    throw new BlockRenderError(`csv-not-found: ${csvPath}`);
+  }
+  const report = analyze(csvText);
+
+  const m = report.metrics.find((entry) => entry.metric === metric);
+  if (!m) {
+    throw new BlockRenderError(`metric-not-found: ${metric}`);
+  }
+
+  const latestValue = m.latest?.value ?? m.values[m.values.length - 1] ?? "—";
+  const status = m.status;
+
+  let chartLines;
+  if (status === "insufficient_data") {
+    chartLines = [
+      `Insufficient data: ${m.n} points (need at least ${MIN_POINTS}).`,
+    ];
+  } else {
+    const chartText = renderChart(m.values, m.stats, m.signals);
+    chartLines = chartText.split("\n");
+  }
+
+  const signalLine = formatSignals(m.signals);
+
+  return [
+    `**Latest:** ${latestValue} · **Status:** ${status}`,
+    "",
+    "```",
+    ...chartLines,
+    "```",
+    "",
+    `**Signals:** ${signalLine}`,
+  ];
+}
+
+function formatSignals(signals) {
+  if (!signals) return "—";
+  const fired = [];
+  for (const rule of ["xRule1", "xRule2", "xRule3", "mrRule1"]) {
+    if (signals[rule]?.length > 0) fired.push(rule);
+  }
+  return fired.length > 0 ? fired.join(", ") : "—";
+}

package/src/commands/init.js

@@ -0,0 +1,55 @@
+import { mkdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import fsAsync from "node:fs/promises";
+import { Finder } from "@forwardimpact/libutil";
+import { WikiRepo } from "../wiki-repo.js";
+import { listSkills } from "../skill-roster.js";
+
+function deriveWikiUrl(parentDir) {
+  const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
+    encoding: "utf-8",
+    stdio: "pipe",
+  });
+  if (r.status !== 0) return null;
+  const origin = r.stdout.trim();
+  const base = origin.replace(/\.git$/, "");
+  return base + ".wiki.git";
+}
+
+export function runInitCommand(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 skillsDir = path.resolve(
+    projectRoot,
+    values["skills-dir"] ?? path.join(".claude", "skills"),
+  );
+
+  const wikiUrl = deriveWikiUrl(projectRoot);
+  if (!wikiUrl) {
+    process.stderr.write(
+      "init: could not determine wiki URL from origin remote\n",
+    );
+    return;
+  }
+
+  const repo = new WikiRepo({ wikiDir, parentDir: projectRoot });
+
+  const cloneResult = repo.ensureCloned(wikiUrl);
+  if (!cloneResult.cloned) {
+    process.stderr.write("init: could not clone wiki, skipping\n");
+    return;
+  }
+
+  repo.inheritIdentity();
+
+  const skills = listSkills({ skillsDir });
+  for (const slug of skills) {
+    mkdirSync(path.join(wikiDir, "metrics", slug), { recursive: true });
+  }
+
+  process.stdout.write(`init: wiki ready at ${wikiDir}\n`);
+}

package/src/commands/refresh.js

@@ -0,0 +1,55 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import fsAsync from "node:fs/promises";
+import { Finder } from "@forwardimpact/libutil";
+import { scanMarkers } from "../marker-scanner.js";
+import { renderBlock, BlockRenderError } from "../block-renderer.js";
+
+function currentStoryboardPath() {
+  const now = new Date();
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  return `wiki/storyboard-${yyyy}-M${mm}.md`;
+}
+
+export function runRefreshCommand(values, args, cli) {
+  const logger = { debug() {} };
+  const finder = new Finder(fsAsync, logger, process);
+  const projectRoot = finder.findProjectRoot(process.cwd());
+
+  const storyboardPath = path.resolve(
+    projectRoot,
+    args[0] || currentStoryboardPath(),
+  );
+  const text = readFileSync(storyboardPath, "utf-8");
+  const blocks = scanMarkers(text);
+
+  if (blocks.length === 0) return;
+
+  const lines = text.split("\n");
+  let spliced = false;
+
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    const block = blocks[i];
+    try {
+      const rendered = renderBlock({
+        metric: block.metric,
+        csvPath: block.csvPath,
+        projectRoot,
+      });
+      lines.splice(
+        block.openLine + 1,
+        block.closeLine - block.openLine - 1,
+        ...rendered,
+      );
+      spliced = true;
+    } catch (err) {
+      if (!(err instanceof BlockRenderError)) throw err;
+      process.stderr.write(
+        `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}\n`,
+      );
+    }
+  }
+
+  if (spliced) writeFileSync(storyboardPath, lines.join("\n"));
+}

package/src/commands/sync.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+import fsAsync from "node:fs/promises";
+import { Finder } from "@forwardimpact/libutil";
+import { WikiRepo, WikiPullConflict } from "../wiki-repo.js";
+
+export function runPushCommand(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 });
+  repo.inheritIdentity();
+
+  const result = repo.commitAndPush("wiki: update from session");
+  if (result.pushed) {
+    process.stdout.write("push: committed and pushed\n");
+  } else {
+    process.stdout.write("push: nothing to push\n");
+  }
+}
+
+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 });
+  repo.inheritIdentity();
+
+  try {
+    repo.pull();
+    process.stdout.write("pull: up to date\n");
+  } catch (err) {
+    if (err instanceof WikiPullConflict) {
+      process.stderr.write(
+        "fit-wiki pull: rebase conflict — local divergence detected; resolve manually or push first\n",
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
+}

package/src/index.js

@@ -6,3 +6,7 @@ export {
   INBOX_HEADING,
   BROADCAST_TARGET,
 } from "./constants.js";
+export { scanMarkers } from "./marker-scanner.js";
+export { renderBlock } from "./block-renderer.js";
+export { WikiRepo } from "./wiki-repo.js";
+export { listSkills } from "./skill-roster.js";

package/src/marker-scanner.js

@@ -0,0 +1,42 @@
+const OPEN_RE = /^<!--\s*xmr:([^:\s]+):([^\s]+)\s*-->\s*$/;
+const CLOSE_RE = /^<!--\s*\/xmr\s*-->\s*$/;
+
+export function scanMarkers(text) {
+  const lines = text.split("\n");
+  const pairs = [];
+  let open = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const openMatch = lines[i].match(OPEN_RE);
+    if (openMatch) {
+      if (open) {
+        process.stderr.write(
+          `dangling-marker ${open.metric} at line ${open.openLine + 1}\n`,
+        );
+      }
+      open = { metric: openMatch[1], csvPath: openMatch[2], openLine: i };
+      continue;
+    }
+
+    if (CLOSE_RE.test(lines[i])) {
+      if (open) {
+        pairs.push({
+          metric: open.metric,
+          csvPath: open.csvPath,
+          openLine: open.openLine,
+          closeLine: i,
+        });
+        open = null;
+      }
+      continue;
+    }
+  }
+
+  if (open) {
+    process.stderr.write(
+      `dangling-marker ${open.metric} at line ${open.openLine + 1}\n`,
+    );
+  }
+
+  return pairs;
+}

package/src/skill-roster.js

@@ -0,0 +1,18 @@
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+export function listSkills({ skillsDir }, fs = { readdirSync, statSync }) {
+  const entries = fs.readdirSync(skillsDir);
+  const skills = [];
+
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    if (!entry.startsWith("kata-")) continue;
+    const fullPath = path.join(skillsDir, entry);
+    const stat = fs.statSync(fullPath);
+    if (!stat.isDirectory()) continue;
+    skills.push(entry);
+  }
+
+  return skills.sort();
+}

package/src/wiki-repo.js

@@ -0,0 +1,121 @@
+import { spawnSync } from "node:child_process";
+
+const CREDENTIAL_HELPER_BODY =
+  '!f() { echo username=x-access-token; echo "password=${GH_TOKEN:-$GITHUB_TOKEN}"; }; f';
+
+export class WikiPullConflict extends Error {
+  constructor(stderr) {
+    super("rebase conflict on pull");
+    this.name = "WikiPullConflict";
+    this.stderr = stderr;
+  }
+}
+
+export function buildAuthArgs(args, token) {
+  if (token) {
+    return [
+      "-c",
+      "credential.helper=",
+      "-c",
+      `credential.helper=${CREDENTIAL_HELPER_BODY}`,
+      ...args,
+    ];
+  }
+  return [...args];
+}
+
+export class WikiRepo {
+  #wikiDir;
+  #parentDir;
+
+  constructor({ wikiDir, parentDir }) {
+    this.#wikiDir = wikiDir;
+    this.#parentDir = parentDir;
+  }
+
+  isCloned() {
+    const r = spawnSync(
+      "git",
+      ["-C", this.#wikiDir, "rev-parse", "--git-dir"],
+      {
+        stdio: "pipe",
+      },
+    );
+    return r.status === 0;
+  }
+
+  ensureCloned(url) {
+    if (this.isCloned()) return { cloned: true, reason: "already-cloned" };
+    const r = this.#authGit(["clone", url, this.#wikiDir]);
+    if (r.status !== 0) {
+      return {
+        cloned: false,
+        reason: r.stderr?.toString().trim() || "clone failed",
+      };
+    }
+    return { cloned: true, reason: "cloned" };
+  }
+
+  inheritIdentity() {
+    const name = this.#parentConfig("user.name");
+    const email = this.#parentConfig("user.email");
+    if (name) this.#git(["config", "user.name", name]);
+    if (email) this.#git(["config", "user.email", email]);
+  }
+
+  fetch() {
+    this.#authGit(["-C", this.#wikiDir, "fetch", "origin", "master"]);
+  }
+
+  isClean() {
+    const r = this.#git(["status", "--porcelain"]);
+    return r.stdout.toString().trim() === "";
+  }
+
+  pull() {
+    this.fetch();
+    const r = this.#git(["rebase", "origin/master"]);
+    if (r.status !== 0) {
+      this.#git(["rebase", "--abort"]);
+      throw new WikiPullConflict(r.stderr?.toString().trim() || "");
+    }
+  }
+
+  commitAndPush(message) {
+    if (this.isClean()) return { pushed: false, reason: "clean" };
+    this.#git(["add", "-A"]);
+    this.#git(["commit", "-m", message]);
+    this.fetch();
+    const rebase = this.#git(["rebase", "origin/master"]);
+    if (rebase.status !== 0) {
+      this.#git(["rebase", "--abort"]);
+      this.#git(["merge", "origin/master", "-X", "ours", "--no-edit"]);
+    }
+    this.#authGit(["-C", this.#wikiDir, "push", "origin", "master"]);
+    return { pushed: true, reason: "pushed" };
+  }
+
+  #parentConfig(key) {
+    const r = spawnSync(
+      "git",
+      ["-C", this.#parentDir, "config", "--get", key],
+      {
+        stdio: "pipe",
+      },
+    );
+    return r.status === 0 ? r.stdout.toString().trim() : null;
+  }
+
+  #git(args) {
+    return spawnSync("git", ["-C", this.#wikiDir, ...args], { stdio: "pipe" });
+  }
+
+  #authGit(args) {
+    const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    const fullArgs = buildAuthArgs(args, token);
+    return spawnSync("git", fullArgs, {
+      stdio: "pipe",
+      env: token ? process.env : undefined,
+    });
+  }
+}