@forwardimpact/libwiki 0.2.11 → 0.2.12

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;
-  }
-}

package/src/wiki-repo.js

@@ -1,167 +0,0 @@
-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";
-    this.stderr = stderr;
-  }
-}
-
-/** Prepend credential-helper config arguments to a git command when a token is available. */
-export function buildAuthArgs(args, token) {
-  if (token) {
-    return [
-      "-c",
-      "credential.helper=",
-      "-c",
-      `credential.helper=${CREDENTIAL_HELPER_BODY}`,
-      ...args,
-    ];
-  }
-  return [...args];
-}
-
-/** Git operations wrapper for the GitHub wiki repository used as agent team memory. */
-export class WikiRepo {
-  #wikiDir;
-  #parentDir;
-  #resolveToken;
-
-  /**
-   * 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",
-      ["-C", this.#wikiDir, "rev-parse", "--git-dir"],
-      {
-        stdio: "pipe",
-      },
-    );
-    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]);
-    if (r.status !== 0) {
-      return {
-        cloned: false,
-        reason: r.stderr?.toString().trim() || "clone failed",
-      };
-    }
-    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");
-    if (name) this.#git(["config", "user.name", name]);
-    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"]);
-    if (r.status !== 0) {
-      this.#git(["rebase", "--abort"]);
-      throw new WikiPullConflict(r.stderr?.toString().trim() || "");
-    }
-  }
-
-  /** 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) {
-    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) {
-      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" };
-  }
-
-  #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",
-      ["-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 = this.#resolveToken();
-    const fullArgs = buildAuthArgs(args, token);
-    // 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 });
-  }
-}