@forwardimpact/libwiki 0.2.10 → 0.2.12

package/src/commands/memo.js

@@ -1,18 +1,23 @@
-import { existsSync } from "node:fs";
-import fsAsync from "node:fs/promises";
 import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
 import { writeMemo } from "../memo-writer.js";
 import { listAgents } from "../agent-roster.js";
 import { BROADCAST_TARGET } from "../constants.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveProjectRoot } from "../util/wiki-dir.js";
 
-function writeAndCheck(summaryPath, sender, message, today) {
-  const result = writeMemo({ summaryPath, sender, message, today });
+function writeAndCheck(runtime, summaryPath, sender, message, today) {
+  const result = writeMemo(
+    { summaryPath, sender, message, today },
+    runtime.fsSync,
+  );
   if (!result.written) {
-    process.stderr.write(`summary lacks memo:inbox marker: ${result.path}\n`);
-    process.exit(2);
+    runtime.proc.stderr.write(
+      `summary lacks memo:inbox marker: ${result.path}\n`,
+    );
+    return { ok: false, code: 2 };
   }
-  process.stdout.write(`wrote ${result.path}\n`);
+  runtime.proc.stdout.write(`wrote ${result.path}\n`);
+  return { ok: true };
 }
 
 function resolveTargetPath(wikiRoot, target) {
@@ -25,72 +30,76 @@ function resolveTargetPath(wikiRoot, target) {
   return { summaryPath, escapesRoot };
 }
 
-function writeSingleTarget({ wikiRoot, target, sender, message, today, cli }) {
+function writeSingleTarget(
+  runtime,
+  { wikiRoot, target, sender, message, today },
+) {
   const { summaryPath, escapesRoot } = resolveTargetPath(wikiRoot, target);
   if (escapesRoot) {
-    cli.usageError(`target escapes wiki root: ${target}`);
-    process.exit(2);
+    return { ok: false, code: 2, error: `target escapes wiki root: ${target}` };
   }
-  if (!existsSync(summaryPath)) {
-    cli.usageError(`target summary not found: ${summaryPath}`);
-    process.exit(2);
+  if (!runtime.fsSync.existsSync(summaryPath)) {
+    return {
+      ok: false,
+      code: 2,
+      error: `target summary not found: ${summaryPath}`,
+    };
   }
-  writeAndCheck(summaryPath, sender, message, today);
+  return writeAndCheck(runtime, summaryPath, sender, message, today);
 }
 
-function writeBroadcast({ agentsDir, wikiRoot, sender, message, today }) {
-  const agents = listAgents({ agentsDir, wikiRoot });
+function writeBroadcast(
+  runtime,
+  { agentsDir, wikiRoot, sender, message, today },
+) {
+  const agents = listAgents({ agentsDir, wikiRoot }, runtime.fsSync);
   for (const { agent, summaryPath } of agents) {
     if (agent === sender) continue;
-    writeAndCheck(summaryPath, sender, message, today);
+    const result = writeAndCheck(runtime, summaryPath, sender, message, today);
+    if (!result.ok) return result;
   }
+  return { ok: true };
 }
 
 /** 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;
+export function runMemoCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const options = ctx.options;
+  const sender = options.from || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
 
   if (!sender) {
-    cli.usageError(
-      "memo requires --from <sender> or LIBEVAL_AGENT_PROFILE env var",
-    );
-    process.exit(2);
+    return {
+      ok: false,
+      code: 2,
+      error: "memo requires --from <sender> or LIBEVAL_AGENT_PROFILE env var",
+    };
   }
-
-  if (!values.to) {
-    cli.usageError("memo requires --to <target|all>");
-    process.exit(2);
+  if (!options.to) {
+    return { ok: false, code: 2, error: "memo requires --to <target|all>" };
   }
-
-  if (!values.message) {
-    cli.usageError("memo requires --message <text>");
-    process.exit(2);
+  if (!options.message) {
+    return { ok: false, code: 2, error: "memo requires --message <text>" };
   }
 
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
-
-  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
+  const projectRoot = resolveProjectRoot(runtime);
+  const wikiRoot = options["wiki-root"] || path.join(projectRoot, "wiki");
   const agentsDir = path.join(projectRoot, ".claude", "agents");
-  const today = new Date().toISOString().slice(0, 10);
+  const today = currentDayIso(runtime);
 
-  if (values.to === BROADCAST_TARGET) {
-    writeBroadcast({
+  if (options.to === BROADCAST_TARGET) {
+    return writeBroadcast(runtime, {
       agentsDir,
       wikiRoot,
       sender,
-      message: values.message,
-      today,
-    });
-  } else {
-    writeSingleTarget({
-      wikiRoot,
-      target: values.to,
-      sender,
-      message: values.message,
+      message: options.message,
       today,
-      cli,
     });
   }
+  return writeSingleTarget(runtime, {
+    wikiRoot,
+    target: options.to,
+    sender,
+    message: options.message,
+    today,
+  });
 }

package/src/commands/refresh.js

@@ -1,36 +1,33 @@
-import { readFileSync, writeFileSync } 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 { yearMonth } from "@forwardimpact/libutil";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { scanMarkers } from "../marker-scanner.js";
 import { renderBlock, BlockRenderError } from "../block-renderer.js";
 import { renderIssueList, parseRepoSlug } from "../issue-list-renderer.js";
-import { createDefaultIo } from "../io.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveProjectRoot } from "../util/wiki-dir.js";
 
-function currentStoryboardPath(now = new Date()) {
-  const yyyy = now.getFullYear();
-  const mm = String(now.getMonth() + 1).padStart(2, "0");
-  return `wiki/storyboard-${yyyy}-M${mm}.md`;
+function currentStoryboardRelPath(runtime) {
+  return `wiki/storyboard-${yearMonth(currentDayIso(runtime))}.md`;
 }
 
-function deriveParentRepo(parentDir, env) {
+async function deriveParentRepo(gitClient, parentDir, env) {
   if (env.FIT_GH_REPO) return env.FIT_GH_REPO;
-  const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
-    encoding: "utf-8",
-    stdio: "pipe",
-  });
-  if (r.status !== 0) return null;
-  return parseRepoSlug(r.stdout);
+  try {
+    const url = await gitClient.remoteGetUrl("origin", { cwd: parentDir });
+    return parseRepoSlug(url);
+  } catch {
+    return null;
+  }
 }
 
-function renderForBlock(block, projectRoot, ghContext) {
+async function renderForBlock(block, projectRoot, ghContext, runtime) {
   if (block.kind === "xmr") {
     return renderBlock({
       metric: block.metric,
       csvPath: block.csvPath,
       projectRoot,
+      fs: runtime.fsSync,
     });
   }
   if (block.kind === "issue-list") {
@@ -41,6 +38,8 @@ function renderForBlock(block, projectRoot, ghContext) {
       cwd: ghContext.cwd,
       repo: ghContext.repo,
       token: ghContext.token,
+      today: currentDayIso(runtime),
+      runtime,
     });
   }
   return null;
@@ -55,23 +54,20 @@ function spliceBlock(lines, block, rendered) {
 }
 
 /** Re-render XmR chart blocks and issue-list blocks in a storyboard file. */
-export async function runRefreshCommand(
-  values,
-  args,
-  _cli,
-  io = createDefaultIo(),
-) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
-  const projectRoot = finder.findProjectRoot(io.cwd());
+export async function runRefreshCommand(ctx) {
+  const { runtime, gitClient } = ctx.deps;
+  const options = ctx.options;
+  const projectRoot = resolveProjectRoot(runtime);
 
   const storyboardPath = path.resolve(
     projectRoot,
-    args[0] || currentStoryboardPath(),
+    ctx.args["storyboard-path"] || currentStoryboardRelPath(runtime),
   );
-  const text = readFileSync(storyboardPath, "utf-8");
-  const blocks = scanMarkers(text);
-  if (blocks.length === 0) return;
+  const text = runtime.fsSync.readFileSync(storyboardPath, "utf-8");
+  const blocks = scanMarkers(text, {
+    warn: (message) => runtime.proc.stderr.write(message),
+  });
+  if (blocks.length === 0) return { ok: true };
 
   const config = await createScriptConfig("wiki");
   let token = null;
@@ -89,7 +85,7 @@ export async function runRefreshCommand(
   // overrides the parsed origin.
   const ghContext = {
     cwd: projectRoot,
-    repo: deriveParentRepo(projectRoot, io.env),
+    repo: await deriveParentRepo(gitClient, projectRoot, runtime.proc.env),
     token,
   };
 
@@ -99,20 +95,28 @@ export async function runRefreshCommand(
   for (let i = blocks.length - 1; i >= 0; i--) {
     const block = blocks[i];
     try {
-      const rendered = renderForBlock(block, projectRoot, ghContext);
+      const rendered = await renderForBlock(
+        block,
+        projectRoot,
+        ghContext,
+        runtime,
+      );
       if (!rendered) continue;
       spliceBlock(lines, block, rendered);
       spliced = true;
     } catch (err) {
       if (!(err instanceof BlockRenderError)) throw err;
-      io.stderr(
+      runtime.proc.stderr.write(
         `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}\n`,
       );
     }
   }
 
-  if (spliced) writeFileSync(storyboardPath, lines.join("\n"));
-  if (values && values.format === "json") {
-    io.stdout(JSON.stringify({ blocks: blocks.length, spliced }) + "\n");
+  if (spliced) runtime.fsSync.writeFileSync(storyboardPath, lines.join("\n"));
+  if (options.format === "json") {
+    runtime.proc.stdout.write(
+      JSON.stringify({ blocks: blocks.length, spliced }) + "\n",
+    );
   }
+  return { ok: true };
 }

package/src/commands/rotate.js

@@ -1,25 +1,36 @@
-import fsAsync from "node:fs/promises";
-import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
 import { rotateIfOverBudget } from "../weekly-log.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 /** Force-rotate the current weekly log to a sealed part file. */
-export function runRotateCommand(values, _args, cli) {
-  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+export function runRotateCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const options = ctx.options;
+  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    cli.usageError("rotate requires --agent or LIBEVAL_AGENT_PROFILE");
-    process.exit(2);
+    return {
+      ok: false,
+      code: 2,
+      error: "rotate requires --agent or LIBEVAL_AGENT_PROFILE",
+    };
   }
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
-  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
-  const today = values.today || new Date().toISOString().slice(0, 10);
+  const wikiRoot = resolveWikiRoot(runtime, options);
+  const today = options.today || currentDayIso(runtime);
 
-  const result = rotateIfOverBudget(wikiRoot, agent, today, 0, { force: true });
+  const result = rotateIfOverBudget(
+    wikiRoot,
+    agent,
+    today,
+    0,
+    { force: true },
+    runtime.fsSync,
+  );
   if (result.rotated) {
-    process.stdout.write(`rotated ${result.fromPath} → ${result.toPath}\n`);
+    runtime.proc.stdout.write(
+      `rotated ${result.fromPath} → ${result.toPath}\n`,
+    );
   } else {
-    process.stdout.write(`no rotation needed for ${agent}\n`);
+    runtime.proc.stdout.write(`no rotation needed for ${agent}\n`);
   }
+  return { ok: true };
 }

package/src/commands/sync.js

@@ -1,50 +1,34 @@
-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";
-
-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 config = await createScriptConfig("wiki");
-  return new WikiRepo({
-    wikiDir,
-    parentDir: projectRoot,
-    resolveToken: () => config.ghToken(),
-  });
-}
+import { WikiPullConflict } from "../wiki-sync.js";
 
 /** 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();
+export async function runPushCommand(ctx) {
+  const { runtime, wikiSync } = ctx.deps;
+  await wikiSync.inheritIdentity();
 
-  const result = repo.commitAndPush("wiki: update from session");
+  const result = await wikiSync.commitAndPush("wiki: update from session");
   if (result.pushed) {
-    process.stdout.write("push: committed and pushed\n");
+    runtime.proc.stdout.write("push: committed and pushed\n");
   } else {
-    process.stdout.write("push: nothing to push\n");
+    runtime.proc.stdout.write("push: nothing to push\n");
   }
+  return { ok: true };
 }
 
-/** 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();
+/** Fetch and rebase the local wiki on origin/master; on rebase conflict, return a non-zero envelope with a message to resolve manually or push first. */
+export async function runPullCommand(ctx) {
+  const { runtime, wikiSync } = ctx.deps;
+  await wikiSync.inheritIdentity();
 
   try {
-    repo.pull();
-    process.stdout.write("pull: up to date\n");
+    await wikiSync.pull();
+    runtime.proc.stdout.write("pull: up to date\n");
+    return { ok: true };
   } catch (err) {
     if (err instanceof WikiPullConflict) {
-      process.stderr.write(
+      runtime.proc.stderr.write(
         "fit-wiki pull: rebase conflict — local divergence detected; resolve manually or push first\n",
       );
-      process.exit(1);
+      return { ok: false, code: 1 };
     }
     throw err;
   }

package/src/index.js

@@ -20,7 +20,7 @@ export {
 export { scanMarkers } from "./marker-scanner.js";
 export { renderBlock } from "./block-renderer.js";
 export { renderIssueList } from "./issue-list-renderer.js";
-export { WikiRepo } from "./wiki-repo.js";
+export { WikiSync, WikiPullConflict } from "./wiki-sync.js";
 export { listSkills } from "./skill-roster.js";
 export {
   parseClaims,

package/src/issue-list-renderer.js

@@ -1,22 +1,4 @@
-import { spawnSync } from "node:child_process";
-
-function defaultGh(args, options) {
-  const env = options?.token
-    ? { ...process.env, GH_TOKEN: options.token }
-    : undefined;
-  return spawnSync("gh", args, {
-    encoding: "utf-8",
-    stdio: ["ignore", "pipe", "pipe"],
-    cwd: options?.cwd,
-    env,
-  });
-}
-
-function daysAgo(today, n) {
-  const d = today instanceof Date ? new Date(today.getTime()) : new Date(today);
-  d.setUTCDate(d.getUTCDate() - n);
-  return d.toISOString().slice(0, 10);
-}
+import { addDays } from "@forwardimpact/libutil";
 
 /** Parse `owner/repo` from a git origin URL. Tolerates http(s), ssh, and proxy-rewritten URLs (e.g. `http://host/git/owner/repo`) by taking the last two path segments after stripping `.git`. Returns null when nothing parseable is found. */
 export function parseRepoSlug(originUrl) {
@@ -27,16 +9,34 @@ export function parseRepoSlug(originUrl) {
   return `${match[1]}/${match[2]}`;
 }
 
-/** Render an issue-list block for an obstacles/experiments marker. Returns markdown lines. `cwd` should be the parent monorepo's project root so `gh` resolves the correct origin; `repo` is an explicit `owner/name` slug used when the origin remote is unparseable by `gh` (e.g. sandbox proxy URLs); `token` is the resolved GH token (e.g. via `Config.ghToken()`). */
-export function renderIssueList({
+/**
+ * Render an issue-list block for an obstacles/experiments marker. Returns
+ * markdown lines. `cwd` should be the parent monorepo's project root so `gh`
+ * resolves the correct origin; `repo` is an explicit `owner/name` slug used when
+ * the origin remote is unparseable by `gh` (e.g. sandbox proxy URLs); `token`
+ * is the resolved GH token (e.g. via `Config.ghToken()`). The `gh` command runs
+ * through `runtime.subprocess`, and stderr warnings through `runtime.proc`.
+ *
+ * @param {object} options
+ * @param {string} options.topic
+ * @param {string} options.state
+ * @param {string|null} options.window
+ * @param {string} options.cwd
+ * @param {string} [options.repo]
+ * @param {string} [options.token]
+ * @param {string} options.today - ISO date string used for the closed-window cutoff.
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} options.runtime
+ * @returns {Promise<string[]>}
+ */
+export async function renderIssueList({
   topic,
   state,
   window,
   cwd,
   repo,
   token,
-  today = new Date(),
-  gh = defaultGh,
+  today,
+  runtime,
 }) {
   const ghState = state === "closed" ? "closed" : "open";
   const args = ["issue", "list"];
@@ -51,9 +51,10 @@ export function renderIssueList({
     "--limit",
     "100",
   );
-  const result = gh(args, { cwd, token });
-  if (result.status !== 0) {
-    process.stderr.write(
+  const env = token ? { ...runtime.proc.env, GH_TOKEN: token } : undefined;
+  const result = await runtime.subprocess.run("gh", args, { cwd, env });
+  if (result.exitCode !== 0) {
+    runtime.proc.stderr.write(
       `refresh: gh issue list failed for ${topic}:${state}\n`,
     );
     return [];
@@ -62,7 +63,7 @@ export function renderIssueList({
   try {
     issues = JSON.parse(result.stdout || "[]");
   } catch {
-    process.stderr.write(
+    runtime.proc.stderr.write(
       `refresh: gh issue list JSON parse failed for ${topic}:${state}\n`,
     );
     return [];
@@ -72,7 +73,7 @@ export function renderIssueList({
     const windowDays = window
       ? Number.parseInt(window.replace("d", ""), 10)
       : 7;
-    const cutoff = daysAgo(today, windowDays);
+    const cutoff = addDays(today, -windowDays);
     issues = issues.filter(
       (i) => i.closedAt && i.closedAt.slice(0, 10) >= cutoff,
     );

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());
+}