@forwardimpact/libwiki 0.2.26 → 0.2.28

package/src/commands/refresh.js

@@ -4,7 +4,12 @@ import { createLogger } from "@forwardimpact/libtelemetry";
 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 {
+  renderIssueList,
+  renderAgentExperiments,
+  TrackerQueryError,
+  parseRepoSlug,
+} from "../issue-list-renderer.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 
@@ -22,7 +27,33 @@ async function deriveParentRepo(gitClient, parentDir, env) {
   }
 }
 
-async function renderForBlock(block, projectRoot, ghContext, runtime) {
+// Compose the agent-experiments block body. On a successful tracker query the
+// body is a fresh last-successful-sync stamp followed by freshly rendered,
+// label-re-checked, sanitized item lines. On a tracker failure the previously
+// materialized body (stamp + items) is preserved verbatim so boot keeps serving
+// the last good routing surface instead of an empty one, and the timestamp is
+// not advanced, so staleness stays auditable from the stamp.
+async function renderAgentExperimentsBlock(block, lines, ghContext, runtime) {
+  const priorBody = lines.slice(block.openLine + 1, block.closeLine);
+  try {
+    const items = await renderAgentExperiments({
+      cwd: ghContext.cwd,
+      repo: ghContext.repo,
+      token: ghContext.token,
+      runtime,
+    });
+    const today = currentDayIso(runtime);
+    return [`<!-- last-successful-sync: ${today} -->`, ...items];
+  } catch (err) {
+    if (!(err instanceof TrackerQueryError)) throw err;
+    runtime.proc.stderr.write(
+      "refresh: gh issue list failed for agent-experiments; keeping previous materialized items\n",
+    );
+    return priorBody;
+  }
+}
+
+async function renderForBlock(block, lines, projectRoot, ghContext, runtime) {
   if (block.kind === "xmr") {
     return renderBlock({
       metric: block.metric,
@@ -44,6 +75,9 @@ async function renderForBlock(block, projectRoot, ghContext, runtime) {
       runtime,
     });
   }
+  if (block.kind === "agent-experiments") {
+    return renderAgentExperimentsBlock(block, lines, ghContext, runtime);
+  }
   return null;
 }
 
@@ -116,6 +150,7 @@ export async function runRefreshCommand(ctx) {
     try {
       const rendered = await renderForBlock(
         block,
+        lines,
         projectRoot,
         ghContext,
         runtime,

package/src/commands/sync.js

@@ -1,6 +1,10 @@
 import { createLogger } from "@forwardimpact/libtelemetry";
 import { refusalEnvelope } from "../secret-gate.js";
-import { AncestryRefusal, WikiPullConflict } from "../wiki-sync.js";
+import {
+  AncestryRefusal,
+  WikiPullConflict,
+  WikiPushFailure,
+} from "../wiki-sync.js";
 import { sweepTier2, renderDetections } from "../integrity.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
@@ -19,7 +23,10 @@ export async function runPushCommand(ctx) {
   try {
     result = await wikiSync.commitAndPush("wiki: update from session");
   } catch (err) {
-    if (err instanceof AncestryRefusal) {
+    // Honest CLI contract (the honest-CLI contract): non-zero on any non-land push
+    // failure, and on the ancestry guard's refusal (the ancestry guard). The Stop-hook
+    // recipe maps this to a stop-blocking exit; CI steps see a loud failure.
+    if (err instanceof WikiPushFailure || err instanceof AncestryRefusal) {
       runtime.proc.stderr.write(`${err.message}\n`);
       return { ok: false, code: 1 };
     }
@@ -29,7 +36,7 @@ export async function runPushCommand(ctx) {
   // unavailable); a clean push falls through to the normal reporting below.
   const refusal = refusalEnvelope(runtime, result);
   if (refusal) return refusal;
-  if (result.pushed) {
+  if (result.landed) {
     runtime.proc.stdout.write("push: committed and pushed\n");
   } else {
     runtime.proc.stdout.write("push: nothing to push\n");

package/src/constants.js

@@ -94,3 +94,21 @@ export const ISSUE_OPEN_RE =
   /^<!--\s*(obstacles|experiments):(open|closed)(?::(\d+d))?(?:\s+[^>]*?)?\s*-->\s*$/;
 export const ISSUE_CLOSE_RE =
   /^<!--\s*\/(obstacles|experiments)(?:\s+[^>]*?)?\s*-->\s*$/;
+
+// Materialized per-agent experiments surface. A distinct marker
+// kind from `experiments:open` — it carries attributed, sanitized items plus a
+// last-successful-sync stamp, and is read offline by `fit-wiki boot`. One home
+// so the scanner (marker-scanner.js), the refresh renderer (commands/refresh.js),
+// the boot parser (boot.js), and the audit balance check (audit/rules.js) cannot
+// drift on the syntax.
+export const AGENT_EXPERIMENTS_OPEN_RE =
+  /^<!--\s*agent-experiments(?:\s+[^>]*?)?\s*-->\s*$/;
+export const AGENT_EXPERIMENTS_CLOSE_RE =
+  /^<!--\s*\/agent-experiments(?:\s+[^>]*?)?\s*-->\s*$/;
+export const LAST_SYNC_RE =
+  /^<!--\s*last-successful-sync:\s*(\d{4}-\d{2}-\d{2})\s*-->\s*$/;
+// Attributed item line: `- #<n> [<agent>] <title> (by <author>)`. The author
+// suffix is mandatory and anchored at end; the title group is greedy, which is
+// unambiguous because sanitizeTitle defuses any embedded ` (by ` token.
+export const AGENT_EXPERIMENT_ITEM_RE =
+  /^- #(\d+) \[([a-z][a-z-]*)\] (.*) \(by (.+)\)$/;

package/src/issue-list-renderer.js

@@ -1,5 +1,22 @@
 import { addDays } from "@forwardimpact/libutil";
 import { createLogger } from "@forwardimpact/libtelemetry";
+import { sanitizeCrossingField, sanitizeTitle } from "./sanitize.js";
+
+/**
+ * Thrown when the tracker query for the agent-experiments materialization fails
+ * (non-zero exit or unparseable JSON). Distinct from returning `[]` so the
+ * refresh command can keep the previously materialized block instead of wiping
+ * the routing surface when the tracker is briefly unavailable.
+ */
+export class TrackerQueryError extends Error {
+  /** @param {string} reason */
+  constructor(reason) {
+    super(reason);
+    this.name = "TrackerQueryError";
+  }
+}
+
+const AGENT_LABEL_RE = /^agent:([a-z][a-z-]*)$/;
 
 /** 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) {
@@ -88,3 +105,57 @@ export async function renderIssueList({
   }
   return lines;
 }
+
+/**
+ * Render the attributed per-agent experiments surface. Fetches open
+ * issues labeled `experiment`, keeps only those also carrying an
+ * `agent:{name}` label, and emits one sanitized, body-free line per issue:
+ * `- #<number> [<agent>] <title> (by <author>)`. Issue bodies are never read.
+ * Throws {@link TrackerQueryError} on tracker failure so the caller can keep the
+ * previously materialized block; never returns `[]` on failure.
+ *
+ * @param {object} options
+ * @param {string} options.cwd
+ * @param {string} [options.repo]
+ * @param {string} [options.token]
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} options.runtime
+ * @returns {Promise<string[]>}
+ */
+export async function renderAgentExperiments({ cwd, repo, token, runtime }) {
+  const args = ["issue", "list"];
+  if (repo) args.push("--repo", repo);
+  args.push(
+    "--label",
+    "experiment",
+    "--state",
+    "open",
+    "--json",
+    "number,title,labels,author",
+    "--limit",
+    "100",
+  );
+  const env = token ? { ...runtime.proc.env, GH_TOKEN: token } : undefined;
+  const result = await runtime.subprocess.run("gh", args, { cwd, env });
+  if (result.exitCode !== 0) {
+    throw new TrackerQueryError("gh issue list failed for agent-experiments");
+  }
+  let issues;
+  try {
+    issues = JSON.parse(result.stdout || "[]");
+  } catch {
+    throw new TrackerQueryError("gh issue list JSON parse failed");
+  }
+
+  const lines = [];
+  for (const issue of issues) {
+    const agentLabel = (issue.labels || [])
+      .map((l) => (typeof l === "string" ? l : l.name))
+      .map((name) => name?.match(AGENT_LABEL_RE)?.[1])
+      .find(Boolean);
+    if (!agentLabel) continue;
+    const title = sanitizeTitle(issue.title);
+    const author = sanitizeCrossingField(issue.author?.login?.toLowerCase());
+    lines.push(`- #${issue.number} [${agentLabel}] ${title} (by ${author})`);
+  }
+  return lines;
+}

package/src/marker-scanner.js

@@ -1,4 +1,6 @@
 import {
+  AGENT_EXPERIMENTS_CLOSE_RE,
+  AGENT_EXPERIMENTS_OPEN_RE,
   ISSUE_CLOSE_RE,
   ISSUE_OPEN_RE,
   XMR_CLOSE_RE,
@@ -6,7 +8,9 @@ import {
 } from "./constants.js";
 
 function openLabel(open) {
-  return open.kind === "xmr" ? open.metric : open.topic;
+  if (open.kind === "xmr") return open.metric;
+  if (open.kind === "agent-experiments") return "agent-experiments";
+  return open.topic;
 }
 
 function warnDangling(open, warn) {
@@ -34,6 +38,9 @@ function tryOpen(line, i) {
       openLine: i,
     };
   }
+  if (AGENT_EXPERIMENTS_OPEN_RE.test(line)) {
+    return { kind: "agent-experiments", openLine: i };
+  }
   return null;
 }
 
@@ -48,6 +55,13 @@ function closePair(open, i) {
       closeLine: i,
     };
   }
+  if (open.kind === "agent-experiments") {
+    return {
+      kind: "agent-experiments",
+      openLine: open.openLine,
+      closeLine: i,
+    };
+  }
   return {
     kind: "issue-list",
     topic: open.topic,
@@ -61,6 +75,9 @@ function closePair(open, i) {
 function matchClose(line, open) {
   if (!open) return false;
   if (open.kind === "xmr") return XMR_CLOSE_RE.test(line);
+  if (open.kind === "agent-experiments") {
+    return AGENT_EXPERIMENTS_CLOSE_RE.test(line);
+  }
   const m = line.match(ISSUE_CLOSE_RE);
   return Boolean(m && open.kind === "issue-list" && open.topic === m[1]);
 }

package/src/sanitize.js

@@ -0,0 +1,53 @@
+const FIELD_CAP = 200;
+const ELLIPSIS = "…";
+const ZERO_WIDTH_SPACE = "\u200b";
+
+// Replace every newline, control character, or whitespace code point with a
+// single space, then collapse runs. Done by code-point inspection rather than a
+// character-class range so no literal hyphen is ever folded into a range and
+// hyphenated identifiers ("staff-engineer", "dick-olsson") survive intact.
+function flattenWhitespace(input) {
+  let out = "";
+  for (const ch of input) {
+    const code = ch.codePointAt(0);
+    const isControl = code <= 0x1f || code === 0x7f;
+    const isSpace = /\s/.test(ch);
+    out += isControl || isSpace ? " " : ch;
+  }
+  return out.replace(/ {2,}/g, " ");
+}
+
+/**
+ * Neutralize an anyone-editable issue-tracker field before it crosses into a
+ * boot-readable wiki surface. Flattens newlines / control characters /
+ * whitespace to single spaces (a multi-line value is what would let a field
+ * inject a heading or block marker and move section boundaries), escapes a
+ * leading protocol sigil ("[" or "<") so "[ask#N]" / "<tag>" / HTML-comment
+ * lookalikes render inert, and length-caps the result.
+ * @param {string|null|undefined} value
+ * @param {number} [maxLen]
+ * @returns {string}
+ */
+export function sanitizeCrossingField(value, maxLen = FIELD_CAP) {
+  if (value == null) return "";
+  let s = flattenWhitespace(String(value)).trim();
+  s = s.replace(/^\[/, "\\[").replace(/^</, "\\<");
+  if (s.length > maxLen) s = s.slice(0, maxLen - 1) + ELLIPSIS;
+  return s;
+}
+
+/**
+ * Sanitize a materialized item title. Beyond {@link sanitizeCrossingField}, it
+ * defuses the literal author-suffix token " (by " by inserting a zero-width
+ * space after "(by", so a title can never be mistaken for the trailing
+ * "(by <author>)" provenance suffix when the line is parsed back at boot.
+ * @param {string|null|undefined} value
+ * @param {number} [maxLen]
+ * @returns {string}
+ */
+export function sanitizeTitle(value, maxLen = FIELD_CAP) {
+  return sanitizeCrossingField(value, maxLen).replace(
+    / \(by /g,
+    " (by" + ZERO_WIDTH_SPACE + " ",
+  );
+}

package/src/status.js

@@ -1,19 +1,46 @@
-// 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`.
+// STATUS.md rows come in two kinds. A spec row's id is four digits with an
+// optional `/<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`. An experiment row's id is `exp:<issue>`
+// and the row carries four tab cells — `exp:<issue><TAB><state><TAB><pin>
+// <TAB><plan-ref>` — keying the merge-gate approval path for a spec-less
+// experiment PR. The `exp:` namespace cannot match the spec id's `^\d{4}`
+// anchor, so the two kinds never collide for any issue-number width.
 
-/** Matches a status-row id: four digits, optionally a `/<unit>` suffix. */
-export const STATUS_ID_REGEX = /^\d{4}(\/[a-z0-9-]+)?$/;
+/** Matches a status-row id: a four-digit spec id (optional `/<unit>`) or `exp:<issue>`. */
+export const STATUS_ID_REGEX = /^(\d{4}(\/[a-z0-9-]+)?|exp:\d+)$/;
 
 /**
- * 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}.
+ * Classify a status-row id into its kind and parts. Experiment rows are
+ * identified by an `exp:` id together with a four-cell row; the optional
+ * `cells` array supplies that count (a bare `exp:` id without four cells is
+ * not a valid row and yields null).
+ * @param {string} id - The id field (cell 0) of a STATUS.md row.
+ * @param {string[]} [cells] - The full tab-separated cells of the row, when
+ *   available. Required to classify an experiment row.
+ * @returns {(
+ *   {kind: "spec", specId: string, unit: string|null} |
+ *   {kind: "experiment", issue: string, state: string, pin: string, planRef: string} |
+ *   null
+ * )} Parsed parts, or null when the id/row does not match a known kind.
  */
-export function parseStatusRowId(id) {
+export function parseStatusRowId(id, cells) {
   if (typeof id !== "string" || !STATUS_ID_REGEX.test(id)) return null;
+  if (id.startsWith("exp:")) {
+    if (!Array.isArray(cells) || cells.length !== 4) return null;
+    return {
+      kind: "experiment",
+      issue: id.slice("exp:".length),
+      state: cells[1],
+      pin: cells[2],
+      planRef: cells[3],
+    };
+  }
   const slash = id.indexOf("/");
-  if (slash === -1) return { specId: id, unit: null };
-  return { specId: id.slice(0, slash), unit: id.slice(slash + 1) };
+  if (slash === -1) return { kind: "spec", specId: id, unit: null };
+  return {
+    kind: "spec",
+    specId: id.slice(0, slash),
+    unit: id.slice(slash + 1),
+  };
 }