@forwardimpact/libwiki 0.2.11 → 0.2.13

package/src/marker-migrator.js

@@ -1,13 +1,14 @@
-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 },
-) {
-  const agents = listAgents({ agentsDir, wikiRoot });
+/**
+ * Insert memo:inbox markers into agent summary files that have an inbox heading
+ * but no marker yet.
+ * @param {{agentsDir: string, wikiRoot: string}} dirs
+ * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
+ */
+export function insertMarkers({ agentsDir, wikiRoot }, fs) {
+  const agents = listAgents({ agentsDir, wikiRoot }, fs);
   const inserted = [];
   const skipped = [];
   const errors = [];

package/src/marker-scanner.js

@@ -12,10 +12,8 @@ function openLabel(open) {
   return open.kind === "xmr" ? open.metric : open.topic;
 }
 
-function warnDangling(open) {
-  process.stderr.write(
-    `dangling-marker ${openLabel(open)} at line ${open.openLine + 1}\n`,
-  );
+function warnDangling(open, warn) {
+  warn(`dangling-marker ${openLabel(open)} at line ${open.openLine + 1}\n`);
 }
 
 function tryOpen(line, i) {
@@ -68,8 +66,15 @@ function matchClose(line, open) {
   return Boolean(m && open.kind === "issue-list" && open.topic === m[1]);
 }
 
-/** Scan text for paired marker blocks (xmr or issue-list). Returns positions and metadata. */
-export function scanMarkers(text) {
+/**
+ * Scan text for paired marker blocks (xmr or issue-list). Returns positions and
+ * metadata. Dangling open markers are reported through the injected `warn`
+ * callback (default: discard) instead of writing to the process directly.
+ * @param {string} text - The storyboard text to scan.
+ * @param {{warn?: (message: string) => void}} [options]
+ * @returns {Array<object>} The paired marker blocks.
+ */
+export function scanMarkers(text, { warn = () => {} } = {}) {
   const lines = text.split("\n");
   const pairs = [];
   let open = null;
@@ -78,7 +83,7 @@ export function scanMarkers(text) {
     const line = lines[i];
     const newOpen = tryOpen(line, i);
     if (newOpen) {
-      if (open) warnDangling(open);
+      if (open) warnDangling(open, warn);
       open = newOpen;
       continue;
     }
@@ -88,7 +93,7 @@ export function scanMarkers(text) {
     }
   }
 
-  if (open) warnDangling(open);
+  if (open) warnDangling(open, warn);
 
   return pairs;
 }

package/src/memo-writer.js

@@ -1,11 +1,12 @@
-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 },
-) {
+/**
+ * Append a timestamped memo bullet below the inbox marker in an agent's summary
+ * file.
+ * @param {{summaryPath: string, sender: string, message: string, today: string}} memo
+ * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
+ */
+export function writeMemo({ summaryPath, sender, message, today }, fs) {
   const content = fs.readFileSync(summaryPath, "utf-8");
   const lines = content.split("\n");
 

package/src/skill-roster.js

@@ -1,8 +1,12 @@
-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 }) {
+/**
+ * List all kata-prefixed skill directory names under the skills directory,
+ * sorted alphabetically.
+ * @param {{skillsDir: string}} dirs
+ * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
+ */
+export function listSkills({ skillsDir }, fs) {
   const entries = fs.readdirSync(skillsDir);
   const skills = [];
 

package/src/status.js

@@ -0,0 +1,19 @@
+// STATUS.md row ids may carry a `/<unit>` suffix denoting a
+// per-migration-unit sub-row of a master spec (`1370/libutil`, …). The master
+// `NNNN` row advances only when every sub-row reads `plan implemented`.
+
+/** Matches a status-row id: four digits, optionally a `/<unit>` suffix. */
+export const STATUS_ID_REGEX = /^\d{4}(\/[a-z0-9-]+)?$/;
+
+/**
+ * Parse a status-row id into its master spec id and optional unit suffix.
+ * @param {string} id - The id field of a STATUS.md row.
+ * @returns {{ specId: string, unit: string|null }|null} Parsed parts, or null
+ *   when the id does not match {@link STATUS_ID_REGEX}.
+ */
+export function parseStatusRowId(id) {
+  if (typeof id !== "string" || !STATUS_ID_REGEX.test(id)) return null;
+  const slash = id.indexOf("/");
+  if (slash === -1) return { specId: id, unit: null };
+  return { specId: id.slice(0, slash), unit: id.slice(slash + 1) };
+}

package/src/util/clock.js

@@ -0,0 +1,13 @@
+import { isoDate } from "@forwardimpact/libutil";
+
+/**
+ * Today's ISO calendar date (`YYYY-MM-DD`) read from the injected clock.
+ * Commands that previously inlined `new Date().toISOString().slice(0, 10)` (or
+ * libwiki's `io.today()`) call this instead so the wall-clock read flows
+ * through `runtime.clock`.
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
+ * @returns {string}
+ */
+export function currentDayIso(runtime) {
+  return isoDate(runtime.clock.now());
+}

package/src/util/wiki-dir.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+
+/**
+ * Find the project root by upward `package.json` discovery from the current
+ * working directory, using the injected `runtime.finder` (the one canonical
+ * Finder — SC9 keeps `new Finder(...)` inside libutil).
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
+ * @returns {string}
+ */
+export function resolveProjectRoot(runtime) {
+  return runtime.finder.findProjectRoot(runtime.proc.cwd());
+}
+
+/**
+ * Resolve the wiki root, preserving the pre-1370 order: the `--wiki-root`
+ * option when given, else `<projectRoot>/wiki`. The finder is consulted only
+ * when no explicit `--wiki-root` is supplied.
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
+ * @param {Record<string, unknown>} [options] - Parsed CLI options (`ctx.options`).
+ * @returns {string}
+ */
+export function resolveWikiRoot(runtime, options = {}) {
+  return options["wiki-root"] || path.join(resolveProjectRoot(runtime), "wiki");
+}

package/src/weekly-log.js

@@ -1,29 +1,14 @@
-import { readFileSync, writeFileSync, existsSync, renameSync } from "node:fs";
 import path from "node:path";
+import { isoWeekString } from "@forwardimpact/libutil";
 import { WEEKLY_LOG_LINE_BUDGET } from "./constants.js";
 
-/** Compute ISO 8601 year-week for a Date. Returns { year, week } where year is the ISO week-year (not necessarily the calendar year for edge weeks). */
-export function isoWeek(date) {
-  const d = new Date(
-    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
-  );
-  // Thursday of week: ISO weeks are anchored on Thursday.
-  const day = d.getUTCDay() || 7;
-  d.setUTCDate(d.getUTCDate() + 4 - day);
-  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
-  const week = Math.ceil(((d - yearStart) / 86400000 + 1) / 7);
-  return { year: d.getUTCFullYear(), week };
-}
-
-function formatIsoWeek(date) {
-  const { year, week } = isoWeek(date);
-  return `${year}-W${String(week).padStart(2, "0")}`;
-}
+// ISO week computation lives in libutil's calendar util (the one place a
+// `new Date` is allowed); re-exported here for the existing public surface.
+export { isoWeek } from "@forwardimpact/libutil";
 
 /** Return the path of the current weekly log file for an agent. */
 export function weeklyLogPath(wikiRoot, agent, today) {
-  const date = today instanceof Date ? today : new Date(today);
-  return path.join(wikiRoot, `${agent}-${formatIsoWeek(date)}.md`);
+  return path.join(wikiRoot, `${agent}-${isoWeekString(today)}.md`);
 }
 
 function countLines(text) {
@@ -34,11 +19,11 @@ function countLines(text) {
   return n;
 }
 
-function nextPartPath(filePath) {
+function nextPartPath(filePath, fs) {
   const dir = path.dirname(filePath);
   const base = path.basename(filePath, ".md");
   let n = 1;
-  while (existsSync(path.join(dir, `${base}-part${n}.md`))) n++;
+  while (fs.existsSync(path.join(dir, `${base}-part${n}.md`))) n++;
   return path.join(dir, `${base}-part${n}.md`);
 }
 
@@ -49,42 +34,57 @@ function agentTitle(agent) {
     .join(" ");
 }
 
-function defaultH1(filePath, agent, isoWeekStr) {
+function defaultH1(agent, isoWeekStr) {
   return `# ${agentTitle(agent)} — ${isoWeekStr}\n`;
 }
 
-/** Rotate the current weekly log if next append would exceed the budget. Returns { rotated, fromPath, toPath }. */
+/**
+ * Rotate the current weekly log if next append would exceed the budget.
+ * @returns {{rotated: boolean, fromPath: string, toPath?: string}}
+ * @param {string} wikiRoot
+ * @param {string} agent
+ * @param {string} today - ISO date string.
+ * @param {number} [appendLines=0]
+ * @param {{force?: boolean}} [options]
+ * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
+ */
 export function rotateIfOverBudget(
   wikiRoot,
   agent,
   today,
   appendLines = 0,
   options = {},
+  fs,
 ) {
   const filePath = weeklyLogPath(wikiRoot, agent, today);
   const { force = false } = options;
-  if (!existsSync(filePath)) return { rotated: false, fromPath: filePath };
-  const text = readFileSync(filePath, "utf-8");
+  if (!fs.existsSync(filePath)) return { rotated: false, fromPath: filePath };
+  const text = fs.readFileSync(filePath, "utf-8");
   const current = countLines(text);
   if (!force && current + appendLines <= WEEKLY_LOG_LINE_BUDGET) {
     return { rotated: false, fromPath: filePath };
   }
-  const toPath = nextPartPath(filePath);
-  renameSync(filePath, toPath);
-  const date = today instanceof Date ? today : new Date(today);
-  writeFileSync(filePath, defaultH1(filePath, agent, formatIsoWeek(date)));
+  const toPath = nextPartPath(filePath, fs);
+  fs.renameSync(filePath, toPath);
+  fs.writeFileSync(filePath, defaultH1(agent, isoWeekString(today)));
   return { rotated: true, fromPath: filePath, toPath };
 }
 
-/** Append a body to a weekly log file. Creates it with an H1 if missing. */
-export function appendEntry(filePath, body, agent, today) {
-  const date = today instanceof Date ? today : new Date(today);
-  if (!existsSync(filePath)) {
-    writeFileSync(filePath, defaultH1(filePath, agent, formatIsoWeek(date)));
+/**
+ * Append a body to a weekly log file. Creates it with an H1 if missing.
+ * @param {string} filePath
+ * @param {string} body
+ * @param {string} agent
+ * @param {string} today - ISO date string.
+ * @param {object} fs - Sync filesystem surface (`runtime.fsSync`).
+ */
+export function appendEntry(filePath, body, agent, today, fs) {
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, defaultH1(agent, isoWeekString(today)));
   }
-  const text = readFileSync(filePath, "utf-8");
+  const text = fs.readFileSync(filePath, "utf-8");
   const separator = text.endsWith("\n") ? "\n" : "\n\n";
-  writeFileSync(
+  fs.writeFileSync(
     filePath,
     text + separator + body + (body.endsWith("\n") ? "" : "\n"),
   );

package/src/wiki-sync.js

@@ -0,0 +1,164 @@
+import path from "node:path";
+
+/** 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";
+    this.stderr = stderr;
+  }
+}
+
+/**
+ * Consolidates the wiki repository's pull / rebase / conflict-resolve / push
+ * flow over an injected {@link import('@forwardimpact/libutil').GitClient}.
+ * Replaces the pre-1370 `WikiRepo`: all shelling-out flows through
+ * `gitClient` (itself over `runtime.subprocess`), so libwiki never imports
+ * `node:child_process` and tests inject `createMockGitClient`.
+ *
+ * Network operations (fetch / clone / push) authenticate by resolving a token
+ * lazily through `resolveToken` and threading it via `gitClient.withAuth`;
+ * local operations never call `resolveToken`. The callback owns the entire
+ * resolution policy and its throws propagate to the caller.
+ */
+export class WikiSync {
+  #runtime;
+  #git;
+  #wikiDir;
+  #parentDir;
+  #resolveToken;
+
+  /**
+   * @param {object} options
+   * @param {import('@forwardimpact/libutil/runtime').Runtime} options.runtime
+   * @param {import('@forwardimpact/libutil').GitClient} options.gitClient
+   * @param {string} options.wikiDir - The wiki clone directory.
+   * @param {string} options.parentDir - The parent project directory (identity source).
+   * @param {() => (string|null)} [options.resolveToken] - Lazy token resolver
+   *   for network operations; returns a token string or null for anonymous.
+   */
+  constructor({ runtime, gitClient, wikiDir, parentDir, resolveToken }) {
+    if (!runtime) throw new Error("WikiSync: runtime is required");
+    if (!gitClient) throw new Error("WikiSync: gitClient is required");
+    if (typeof wikiDir !== "string" || wikiDir === "") {
+      throw new TypeError("WikiSync: wikiDir must be a non-empty string");
+    }
+    this.#runtime = runtime;
+    this.#git = gitClient;
+    this.#wikiDir = wikiDir;
+    this.#parentDir = parentDir;
+    this.#resolveToken = resolveToken ?? (() => null);
+  }
+
+  /** A GitClient authenticated with the lazily-resolved token, or the bare client when none. */
+  #authed() {
+    const token = this.#resolveToken();
+    return token ? this.#git.withAuth(token) : this.#git;
+  }
+
+  /** Whether the wiki directory is an initialized git clone. */
+  isCloned() {
+    return this.#runtime.fsSync.existsSync(path.join(this.#wikiDir, ".git"));
+  }
+
+  /** Clone the wiki from `url` if it is not already cloned. */
+  async ensureCloned(url) {
+    if (this.isCloned()) return { cloned: true, reason: "already-cloned" };
+    try {
+      await this.#authed().clone(url, this.#wikiDir);
+      return { cloned: true, reason: "cloned" };
+    } catch (err) {
+      return { cloned: false, reason: err.stderr?.trim() || err.message };
+    }
+  }
+
+  /** Copy git user.name and user.email from the parent repository into the wiki repository. */
+  async inheritIdentity() {
+    const name = await this.#git.configGet("user.name", {
+      cwd: this.#parentDir,
+    });
+    const email = await this.#git.configGet("user.email", {
+      cwd: this.#parentDir,
+    });
+    if (name)
+      await this.#git.configSet("user.name", name, { cwd: this.#wikiDir });
+    if (email) {
+      await this.#git.configSet("user.email", email, { cwd: this.#wikiDir });
+    }
+  }
+
+  /** Fetch origin/master using token auth when available. */
+  async fetch() {
+    // Resolve auth first so a misconfigured `resolveToken` still surfaces.
+    const client = this.#authed();
+    try {
+      await client.fetch("origin", "master", { cwd: this.#wikiDir });
+    } catch {
+      // WikiRepo treated fetch as fire-and-forget (it ignored the git result);
+      // a failed fetch leaves the local origin/master ref in place and the
+      // rebase proceeds against it. Preserved so push/pull degrade gracefully
+      // rather than crash when the network or credentials are unavailable.
+    }
+  }
+
+  /** Whether the wiki working tree has no uncommitted changes. */
+  async isClean() {
+    const r = await this.#git.status({ cwd: this.#wikiDir });
+    return r.stdout.trim() === "";
+  }
+
+  /** Fetch and rebase on origin/master, throwing WikiPullConflict if the rebase fails. */
+  async pull() {
+    await this.fetch();
+    const r = await this.#git.rebase("origin/master", { cwd: this.#wikiDir });
+    if (r.exitCode !== 0) {
+      await this.#git.rebaseAbort({ cwd: this.#wikiDir });
+      throw new WikiPullConflict(r.stderr?.trim() || "");
+    }
+  }
+
+  /**
+   * Stage and commit any working-tree changes, then fetch, rebase on
+   * origin/master (falling back to a merge with -X ours if the 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.
+   */
+  async commitAndPush(message) {
+    if (!(await this.isClean())) {
+      await this.#git.commitAll(message, { cwd: this.#wikiDir });
+    }
+    if (!(await this.#hasCommitsAhead())) {
+      return { pushed: false, reason: "clean" };
+    }
+    await this.fetch();
+    const rebase = await this.#git.rebase("origin/master", {
+      cwd: this.#wikiDir,
+    });
+    if (rebase.exitCode !== 0) {
+      await this.#git.rebaseAbort({ cwd: this.#wikiDir });
+      await this.#git.mergeOursStrategy({
+        cwd: this.#wikiDir,
+        ref: "origin/master",
+      });
+    }
+    // Resolve auth first so a misconfigured `resolveToken` still surfaces; the
+    // push itself is fire-and-forget like WikiRepo (which ignored the push
+    // result and reported pushed:true regardless), so a network/credential
+    // failure degrades to "saved locally" rather than crashing the command.
+    const client = this.#authed();
+    try {
+      await client.push("origin", "master", { cwd: this.#wikiDir });
+    } catch {
+      // Intentionally ignored — preserves WikiRepo's fire-and-forget push.
+    }
+    return { pushed: true, reason: "pushed" };
+  }
+
+  async #hasCommitsAhead() {
+    const count = await this.#git.revListCount("origin/master..HEAD", {
+      cwd: this.#wikiDir,
+    });
+    return count > 0;
+  }
+}

package/src/build-repo.js

@@ -1,20 +0,0 @@
-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";
-
-/** Construct a WikiRepo from CLI values and the working directory. */
-export async function buildRepo(values, cwd = process.cwd()) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, { cwd: () => cwd });
-  const projectRoot = finder.findProjectRoot(cwd);
-  const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
-
-  const config = await createScriptConfig("wiki");
-  return new WikiRepo({
-    wikiDir,
-    parentDir: projectRoot,
-    resolveToken: () => config.ghToken(),
-  });
-}

package/src/io.js

@@ -1,77 +0,0 @@
-/**
- * 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;
-  }
-}