@forwardimpact/libwiki 0.2.24 → 0.2.25

package/bin/fit-wiki.js

@@ -6,8 +6,13 @@ import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
 import { GitClient } from "@forwardimpact/libutil/git-client";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { createCli } from "@forwardimpact/libcli";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { WikiSync } from "../src/wiki-sync.js";
-import { resolveProjectRoot, resolveWikiRoot } from "../src/util/wiki-dir.js";
+import {
+  resolveProjectRoot,
+  resolveWikiRoot,
+  wikiExists,
+} from "../src/util/wiki-dir.js";
 import { createDefinition } from "../src/cli-definition.js";
 
 // Commands that mutate or sync the remote wiki need a constructed WikiSync
@@ -37,6 +42,21 @@ async function main() {
     return runtime.proc.exit(2);
   }
 
+  // Every command except `init` operates on an existing wiki tree. When it is
+  // absent (e.g. a fresh worktree where bootstrap.sh never ran), degrade
+  // gracefully: warn and exit 0 so the session Stop hook and other callers do
+  // not fail loudly. `init` is exempt — it creates the tree.
+  if (command !== "init") {
+    const wikiDir = resolveWikiRoot(runtime, parsed.values);
+    if (!wikiExists(runtime, wikiDir)) {
+      createLogger("wiki", runtime).warn(
+        command,
+        `no wiki at ${wikiDir}; skipping (run \`fit-wiki init\` to create one)`,
+      );
+      return runtime.proc.exit(0);
+    }
+  }
+
   const gitClient = new GitClient({ runtime });
   let wikiSync;
   if (NEEDS_WIKI_SYNC.has(command)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
   "keywords": [
     "wiki",
@@ -49,6 +49,7 @@
     "@forwardimpact/libconfig": "^0.1.77",
     "@forwardimpact/libeval": "^0.1.49",
     "@forwardimpact/libpreflight": "^0.1.0",
+    "@forwardimpact/libtelemetry": "^0.1.47",
     "@forwardimpact/libutil": "^0.1.0",
     "@forwardimpact/libxmr": "^2.0.0"
   },

package/src/commands/claim.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { addDays } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import {
   appendClaim,
   removeClaim,
@@ -28,7 +29,10 @@ async function pushWiki(wikiSync, runtime, message) {
     if (result.pushed)
       runtime.proc.stdout.write("push: committed and pushed\n");
   } catch (err) {
-    runtime.proc.stderr.write(`push failed (saved locally): ${err.message}\n`);
+    createLogger("wiki", runtime).warn(
+      "claim",
+      `push failed (saved locally): ${err.message}`,
+    );
   }
 }
 
@@ -64,8 +68,9 @@ export async function runClaimCommand(ctx) {
     expires_at: expires,
   });
   if (!result.inserted) {
-    runtime.proc.stderr.write(
-      `claim already exists for ${agent}/${options.target}\n`,
+    createLogger("wiki", runtime).warn(
+      "claim",
+      `claim already exists for ${agent}/${options.target}`,
     );
     return { ok: false, code: 2 };
   }

package/src/commands/fix.js

@@ -16,6 +16,7 @@ import {
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 import { FAST_MODEL } from "@forwardimpact/libutil/models";
+import { createLogger } from "@forwardimpact/libtelemetry";
 
 // Pipeline: audit → deterministic rotation (the one fix needing a file seal the
 // agent can't do) → re-audit → Haiku agent on the prose-judgment residual →
@@ -276,7 +277,8 @@ export async function runFixCommand(ctx) {
   const wikiRoot = ctx.options["wiki-root"] || path.join(projectRoot, "wiki");
   const today = ctx.options.today || currentDayIso(runtime);
   const out = (s) => runtime.proc.stdout.write(s);
-  const err = (s) => runtime.proc.stderr.write(s);
+  const logger = createLogger("wiki", runtime);
+  const err = (s) => logger.warn("fix", String(s).replace(/\n+$/, ""));
 
   // The agent's edits change the result, so re-read and re-audit each round.
   const audit = () =>

package/src/commands/inbox.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import {
   MEMO_INBOX_MARKER,
   PRIORITY_INDEX_HEADING,
@@ -11,8 +12,9 @@ function paths(runtime, options) {
   const wikiRoot = resolveWikiRoot(runtime, options);
   const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    runtime.proc.stderr.write(
-      "inbox requires --agent or LIBEVAL_AGENT_PROFILE\n",
+    createLogger("wiki", runtime).warn(
+      "inbox",
+      "inbox requires --agent or LIBEVAL_AGENT_PROFILE",
     );
     return { error: { ok: false, code: 2 } };
   }
@@ -67,13 +69,13 @@ function ackOrDropCmd(runtime, options) {
   const { summaryPath } = p;
   const idx = Number.parseInt(options.index ?? "", 10);
   if (!Number.isInteger(idx) || idx < 0) {
-    runtime.proc.stderr.write("inbox requires --index <n>\n");
+    createLogger("wiki", runtime).warn("inbox", "inbox requires --index <n>");
     return { ok: false, code: 2 };
   }
   const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { lines, bulletIdxs } = readInboxBullets(text);
   if (idx >= bulletIdxs.length) {
-    runtime.proc.stderr.write(`no bullet at index ${idx}\n`);
+    createLogger("wiki", runtime).warn("inbox", `no bullet at index ${idx}`);
     return { ok: false, code: 2 };
   }
   removeBulletAt(lines, bulletIdxs[idx]);
@@ -134,13 +136,16 @@ function promoteCmd(runtime, options) {
   const { summaryPath, memoryPath, agent } = p;
   const idx = Number.parseInt(options.index ?? "", 10);
   if (!Number.isInteger(idx) || idx < 0) {
-    runtime.proc.stderr.write("inbox promote requires --index <n>\n");
+    createLogger("wiki", runtime).warn(
+      "inbox",
+      "inbox promote requires --index <n>",
+    );
     return { ok: false, code: 2 };
   }
   const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { lines, bullets, bulletIdxs } = readInboxBullets(text);
   if (idx >= bullets.length) {
-    runtime.proc.stderr.write(`no bullet at index ${idx}\n`);
+    createLogger("wiki", runtime).warn("inbox", `no bullet at index ${idx}`);
     return { ok: false, code: 2 };
   }
   const bulletText = bullets[idx].replace(/^[-*]\s+/, "");

package/src/commands/init.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { listSkills } from "../skill-roster.js";
 import { resolveProjectRoot, resolveWikiRoot } from "../util/wiki-dir.js";
 import {
@@ -53,19 +54,19 @@ function scaffoldActiveClaims(runtime, memoryPath) {
 }
 
 async function maybeCloneWiki(wikiSync, gitClient, projectRoot, runtime) {
+  const logger = createLogger("wiki", runtime);
   const wikiUrl = await deriveWikiUrl(gitClient, projectRoot, runtime.proc.env);
   if (!wikiUrl) {
-    runtime.proc.stderr.write(
-      "init: could not determine wiki URL from origin remote\n",
-    );
+    logger.warn("init", "could not determine wiki URL from origin remote");
     return;
   }
   const cloneResult = await wikiSync.ensureCloned(wikiUrl);
   if (cloneResult.cloned) {
     await wikiSync.inheritIdentity();
   } else {
-    runtime.proc.stderr.write(
-      "init: could not clone wiki, continuing with local-only steps\n",
+    logger.warn(
+      "init",
+      "could not clone wiki, continuing with local-only steps",
     );
   }
 }

package/src/commands/log.js

@@ -1,3 +1,4 @@
+import { createLogger } from "@forwardimpact/libtelemetry";
 import {
   weeklyLogPath,
   rotateIfOverBudget,
@@ -10,8 +11,9 @@ import { resolveWikiRoot } from "../util/wiki-dir.js";
 function commonContext(runtime, options) {
   const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    runtime.proc.stderr.write(
-      "log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n",
+    createLogger("wiki", runtime).warn(
+      "log",
+      "log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var",
     );
     return { error: { ok: false, code: 2 } };
   }
@@ -49,14 +51,15 @@ function rotateBeforeAppend(wikiRoot, agent, today, appendLines, runtime) {
       runtime.fsSync,
     );
     if (res.status === "incomplete") {
-      runtime.proc.stderr.write(
-        `note: day-section ${res.residue.section} alone exceeds the budget ` +
+      createLogger("wiki", runtime).warn(
+        "log",
+        `day-section ${res.residue.section} alone exceeds the budget ` +
           `(${res.residue.lines} lines, ${res.residue.words} words); ` +
-          `sealed as ${res.residue.path} for manual recovery\n`,
+          `sealed as ${res.residue.path} for manual recovery`,
       );
     }
   } catch (e) {
-    runtime.proc.stderr.write(`note: rotation failed: ${e.message}\n`);
+    createLogger("wiki", runtime).warn("log", `rotation failed: ${e.message}`);
   }
 }
 
@@ -95,7 +98,10 @@ function runNote(runtime, options) {
   if (ctx.error) return ctx.error;
   const { agent, wikiRoot, today } = ctx;
   if (!options.field || !options.body) {
-    runtime.proc.stderr.write("log note requires --field and --body\n");
+    createLogger("wiki", runtime).warn(
+      "log",
+      "log note requires --field and --body",
+    );
     return { ok: false, code: 2 };
   }
   const fieldBlock = `### ${options.field}\n\n${options.body}\n`;

package/src/commands/memo.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { writeMemo } from "../memo-writer.js";
 import { listAgents } from "../agent-roster.js";
 import { BROADCAST_TARGET } from "../constants.js";
@@ -11,8 +12,9 @@ function writeAndCheck(runtime, summaryPath, sender, message, today) {
     runtime.fsSync,
   );
   if (!result.written) {
-    runtime.proc.stderr.write(
-      `summary lacks memo:inbox marker: ${result.path}\n`,
+    createLogger("wiki", runtime).warn(
+      "memo",
+      `summary lacks memo:inbox marker: ${result.path}`,
     );
     return { ok: false, code: 2 };
   }

package/src/commands/refresh.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { yearMonth } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { createScriptConfig } from "@forwardimpact/libconfig";
 import { scanMarkers } from "../marker-scanner.js";
 import { renderBlock, BlockRenderError } from "../block-renderer.js";
@@ -69,6 +70,7 @@ function readStoryboardOrNull(runtime, storyboardPath) {
 export async function runRefreshCommand(ctx) {
   const { runtime, gitClient } = ctx.deps;
   const options = ctx.options;
+  const logger = createLogger("wiki", runtime);
   const projectRoot = resolveProjectRoot(runtime);
 
   const storyboardPath = path.resolve(
@@ -77,11 +79,11 @@ export async function runRefreshCommand(ctx) {
   );
   const text = readStoryboardOrNull(runtime, storyboardPath);
   if (text === null) {
-    runtime.proc.stderr.write(`refresh: no storyboard at ${storyboardPath}\n`);
+    logger.warn("refresh", `no storyboard at ${storyboardPath}`);
     return { ok: true };
   }
   const blocks = scanMarkers(text, {
-    warn: (message) => runtime.proc.stderr.write(message),
+    warn: (message) => logger.warn("refresh", message),
   });
   if (blocks.length === 0) return { ok: true };
 
@@ -122,8 +124,9 @@ export async function runRefreshCommand(ctx) {
       spliced = true;
     } catch (err) {
       if (!(err instanceof BlockRenderError)) throw err;
-      runtime.proc.stderr.write(
-        `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}\n`,
+      logger.error(
+        "refresh",
+        `refresh-error ${storyboardPath}:${block.openLine + 1} ${err.message}`,
       );
     }
   }

package/src/commands/rotate.js

@@ -1,3 +1,4 @@
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { rotateIfOverBudget, weeklyLogPath } from "../weekly-log.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
@@ -5,6 +6,7 @@ import { resolveWikiRoot } from "../util/wiki-dir.js";
 /** Force-rotate the current weekly log to a sealed part file. */
 export function runRotateCommand(ctx) {
   const { runtime } = ctx.deps;
+  const logger = createLogger("wiki", runtime);
   const options = ctx.options;
   const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
@@ -34,7 +36,7 @@ export function runRotateCommand(ctx) {
       runtime.fsSync,
     );
   } catch (e) {
-    runtime.proc.stderr.write(`rotate failed: ${e.message}\n`);
+    logger.error("rotate", `rotate failed: ${e.message}`);
     return { ok: false, code: 1 };
   }
   switch (result.status) {
@@ -51,12 +53,13 @@ export function runRotateCommand(ctx) {
         runtime.proc.stdout.write(`sealed → ${part}\n`);
       }
       const { section, lines, words, path: residuePath } = result.residue;
-      runtime.proc.stderr.write(
+      logger.error(
+        "rotate",
         `day-section ${section} alone exceeds the budget ` +
           `(${lines} lines, ${words} words) and cannot be split at a day ` +
           `seam: ${residuePath}\n` +
           `recover it by hand — bisect the section at a finer seam ` +
-          `(see the memory protocol's manual-recovery convention)\n`,
+          `(see the memory protocol's manual-recovery convention)`,
       );
       return { ok: false, code: 1 };
     }

package/src/commands/sync.js

@@ -1,3 +1,4 @@
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { WikiPullConflict } from "../wiki-sync.js";
 
 /** Commit all wiki changes and push them to the remote wiki repository. */
@@ -25,8 +26,9 @@ export async function runPullCommand(ctx) {
     return { ok: true };
   } catch (err) {
     if (err instanceof WikiPullConflict) {
-      runtime.proc.stderr.write(
-        "fit-wiki pull: rebase conflict — local divergence detected; resolve manually or push first\n",
+      createLogger("wiki", runtime).error(
+        "pull",
+        "rebase conflict — local divergence detected; resolve manually or push first",
       );
       return { ok: false, code: 1 };
     }

package/src/issue-list-renderer.js

@@ -1,4 +1,5 @@
 import { addDays } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
 
 /** 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) {
@@ -54,8 +55,9 @@ export async function renderIssueList({
   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`,
+    createLogger("wiki", runtime).warn(
+      "refresh",
+      `gh issue list failed for ${topic}:${state}`,
     );
     return [];
   }
@@ -63,8 +65,9 @@ export async function renderIssueList({
   try {
     issues = JSON.parse(result.stdout || "[]");
   } catch {
-    runtime.proc.stderr.write(
-      `refresh: gh issue list JSON parse failed for ${topic}:${state}\n`,
+    createLogger("wiki", runtime).warn(
+      "refresh",
+      `gh issue list JSON parse failed for ${topic}:${state}`,
     );
     return [];
   }

package/src/util/wiki-dir.js

@@ -22,3 +22,16 @@ export function resolveProjectRoot(runtime) {
 export function resolveWikiRoot(runtime, options = {}) {
   return options["wiki-root"] || path.join(resolveProjectRoot(runtime), "wiki");
 }
+
+/**
+ * Report whether the resolved wiki root exists on disk. Commands that read or
+ * sync an existing wiki use this to degrade gracefully (warn and exit 0) when
+ * the tree was never bootstrapped — e.g. a fresh worktree where
+ * `scripts/bootstrap.sh` did not run.
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} runtime
+ * @param {string} wikiDir - The resolved wiki root.
+ * @returns {boolean}
+ */
+export function wikiExists(runtime, wikiDir) {
+  return runtime.fsSync.existsSync(wikiDir);
+}