@fcon-tech/portolan 0.4.5

package/core/src/chart-io.rollback-fixture.ts

@@ -0,0 +1,55 @@
+/**
+ * Fixture for chart-io.rollback.test.ts — runs in its OWN process because
+ * mock.module("node:fs") must not leak into the main test runner's module
+ * registry (it deadlocked the full-suite run). Applies the sabotaged
+ * renameSync, performs the failing write, and prints the resulting
+ * directory state as JSON on stdout.
+ *
+ *   bun src/chart-io.rollback-fixture.ts <dir> <sabotageAt>
+ */
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const [dir, sabotageArg] = process.argv.slice(2);
+if (!dir || !sabotageArg) throw new Error("usage: rollback-fixture.ts <dir> <sabotageAt>");
+const sabotageAt = Number(sabotageArg);
+
+const real = await import("node:fs");
+let renameCalls = 0;
+const { mock } = await import("bun:test");
+mock.module("node:fs", () => ({
+  ...real,
+  renameSync: (from: string, to: string) => {
+    renameCalls += 1;
+    if (renameCalls === sabotageAt) throw new Error("sabotaged rename (simulated ENOSPC)");
+    return real.renameSync(from, to);
+  },
+}));
+
+const { writeFilesAtomically } = await import("./chart-io");
+
+// Two existing files (each replace costs two renames: final→bak,
+// tmp→final) plus one new file.
+writeFileSync(join(dir, "a.md"), "old a\n");
+writeFileSync(join(dir, "b.md"), "old b\n");
+const files = new Map<string, string>([
+  ["a.md", "new a\n"],
+  ["b.md", "new b\n"],
+  ["c.md", "new c\n"],
+]);
+
+let threw: string | null = null;
+try {
+  writeFilesAtomically(dir, files);
+} catch (err) {
+  threw = (err as Error).message;
+}
+
+const ls = readdirSync(dir).sort();
+const contents: Record<string, string> = {};
+for (const name of ls) {
+  contents[name] = readFileSync(join(dir, name), "utf8");
+}
+process.stdout.write(
+  `${JSON.stringify({ threw, ls, contents }, null, 1)}\n`
+);

package/core/src/chart-io.ts

@@ -0,0 +1,121 @@
+/**
+ * Low-level chart file IO shared by the store and the staleness refresher:
+ * paths, index (de)serialization, and the atomic stage-temp-then-rename
+ * writer. All writes stay under `<target>/.portolan/chart/`.
+ */
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import type { IndexedEntry } from "./types";
+
+export const INDEX_FILE = "index.jsonl";
+export const NOTICES_FILE = "notices.txt";
+
+/** Where the Chart lives for a given target root. */
+export function chartDir(targetRoot: string): string {
+  return join(targetRoot, ".portolan", "chart");
+}
+
+export function entryKey(entry: { kind: string; id: string }): string {
+  return `${entry.kind}/${entry.id}`;
+}
+
+export function sortEntries<T extends { kind: string; id: string }>(entries: T[]): T[] {
+  return [...entries].sort((a, b) => {
+    const ka = entryKey(a);
+    const kb = entryKey(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+}
+
+/** Read the machine index. Throws with a remediation hint when absent. */
+export function readChart(targetRoot: string): IndexedEntry[] {
+  const indexPath = join(chartDir(targetRoot), INDEX_FILE);
+  if (!existsSync(indexPath)) {
+    throw new Error(`no chart index at ${indexPath} — write a chart first`);
+  }
+  const lines = readFileSync(indexPath, "utf8")
+    .split("\n")
+    .filter((line) => line.trim().length > 0);
+  return lines.map((line, i) => {
+    let entry: IndexedEntry;
+    try {
+      entry = JSON.parse(line) as IndexedEntry;
+    } catch (err) {
+      // Same remediation shape as the check below: the corruption message
+      // names the file and the line, so index repair knows where to look.
+      throw new Error(
+        `corrupt chart index ${indexPath} line ${i + 1}: not valid JSON (${(err as Error).message})`,
+      );
+    }
+    if (typeof entry?.kind !== "string" || typeof entry?.id !== "string") {
+      throw new Error(`corrupt chart index ${indexPath} line ${i + 1}`);
+    }
+    return entry;
+  });
+}
+
+export function readChartOrNull(targetRoot: string): IndexedEntry[] | null {
+  try {
+    return readChart(targetRoot);
+  } catch {
+    return null;
+  }
+}
+
+export function indexJsonl(entries: IndexedEntry[]): string {
+  return `${sortEntries(entries).map((e) => JSON.stringify(e)).join("\n")}\n`;
+}
+
+/**
+ * Stage every file to a temp name first, then rename them all into place.
+ * A failure before the renames (validation, full disk, ...) leaves the
+ * previous chart untouched; staged temps are removed on failure. A failure
+ * during the renames rolls back: every replaced file's previous content is
+ * held aside as a backup until all renames are through, so the previous
+ * chart stays byte-identical — not just the machine index.
+ */
+export function writeFilesAtomically(dir: string, files: Map<string, string>): void {
+  const staged: Array<{ tmp: string; final: string }> = [];
+  try {
+    for (const [name, text] of files) {
+      const final = join(dir, name);
+      const tmp = `${final}.tmp-${randomBytes(6).toString("hex")}`;
+      writeFileSync(tmp, text);
+      staged.push({ tmp, final });
+    }
+  } catch (err) {
+    for (const { tmp } of staged) rmSync(tmp, { force: true });
+    throw err;
+  }
+  // Preflight: every occupied target must be a regular file a backup can
+  // restore. Anything else (a directory squatting on a sheet name) fails
+  // before a single original is touched.
+  for (const { final } of staged) {
+    if (existsSync(final) && !statSync(final).isFile()) {
+      for (const { tmp } of staged) rmSync(tmp, { force: true });
+      throw new Error(`writeFilesAtomically: ${final} exists and is not a regular file`);
+    }
+  }
+  const backups: Array<{ bak: string; final: string }> = [];
+  const placed = new Set<string>();
+  try {
+    for (const { tmp, final } of staged) {
+      if (existsSync(final)) {
+        const bak = `${final}.bak-${randomBytes(6).toString("hex")}`;
+        renameSync(final, bak);
+        backups.push({ bak, final });
+      }
+      renameSync(tmp, final);
+      placed.add(final);
+    }
+  } catch (err) {
+    for (const final of placed) rmSync(final, { force: true });
+    for (const { bak, final } of backups) renameSync(bak, final);
+    for (const { tmp, final } of staged) {
+      if (!placed.has(final)) rmSync(tmp, { force: true });
+    }
+    throw err;
+  }
+  for (const { bak } of backups) rmSync(bak, { force: true });
+}

package/core/src/chart-store.ts

@@ -0,0 +1,137 @@
+/**
+ * The chart store: read/write of `<target>/.portolan/chart/` — one markdown
+ * sheet per vessel plus the machine index `index.jsonl` (authoritative for
+ * machines; sheets are rendered outputs). Writes are atomic by
+ * stage-to-temp + rename (design.md, decision 4): a write either persists
+ * completely or leaves the previous chart byte-identical. Each vessel entry
+ * is stamped with a source tree signature for staleness detection.
+ */
+import { mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import type { ChartEntry, IndexedEntry, Notice } from "./types";
+import { validateEntries } from "./validate";
+import { renderSheets } from "./sheets";
+import { treeSignature } from "./staleness";
+import { diffNotices, renderNotices } from "./notices";
+import {
+  INDEX_FILE,
+  NOTICES_FILE,
+  chartDir,
+  entryKey,
+  indexJsonl,
+  readChartOrNull,
+  sortEntries,
+  writeFilesAtomically,
+} from "./chart-io";
+
+export { INDEX_FILE, NOTICES_FILE, chartDir, readChart } from "./chart-io";
+
+/** Result of a chart write: where the chart lives, the index, and the notices it produced. */
+export interface WriteResult {
+  dir: string;
+  index: IndexedEntry[];
+  notices: Notice[];
+  noticesText: string;
+  /** Set when post-write cleanup failed: the write persisted, its cleanup did not. */
+  cleanupError?: string;
+}
+
+export interface WriteOptions {
+  /**
+   * Accept a full-replace that drops more than a quarter of the existing
+   * entries (chart-write-shrink-guard). Default false: silent mass shrink
+   * is how a partial rewrite clobbers a whole chart (live incident,
+   * receipt r43).
+   */
+  allowShrink?: boolean;
+}
+
+/**
+ * Write the whole chart (full-replace semantics: entries absent from the
+ * batch are retired). Validates the batch first — a rejection or a late
+ * duplicate-id failure persists nothing. Vessel sheets are re-rendered from
+ * the entries; sheets of retired vessels are removed.
+ */
+export function writeChart(
+  targetRoot: string,
+  rawEntries: ChartEntry[],
+  options: WriteOptions = {},
+): WriteResult {
+  // Round-trip rule: entries read back from the chart carry `stale` and
+  // `signature` metadata the store owns and re-stamps on every write, so a
+  // read → modify → write repair cycle must not be rejected for them.
+  const entries = rawEntries.map((entry) => {
+    const { stale: _stale, signature: _signature, ...clean } = entry as ChartEntry & {
+      stale?: unknown;
+      signature?: unknown;
+    };
+    return clean as ChartEntry;
+  });
+  if (entries.length === 0) {
+    throw new Error("writeChart: refusing to write an empty chart");
+  }
+  // Shrink guard (chart-write-shrink-guard): a full-replace that drops more
+  // than a quarter of the existing entries is refused unless explicitly
+  // allowed — a partial rewrite must not clobber a whole chart silently.
+  // The threshold is compared as a float: flooring it would admit a
+  // 74.9% shrink as "not below 75%".
+  const previous = readChartOrNull(targetRoot);
+  if (previous && !options.allowShrink) {
+    if (entries.length < previous.length * 0.75) {
+      throw new Error(
+        `writeChart refused: ${entries.length} entries would shrink the chart from ${previous.length} ` +
+          `(allowShrink to override a deliberate retire-heavy correction)`,
+      );
+    }
+  }
+  validateEntries(entries);
+  // Late batch check, after per-entry validation: duplicate ids would
+  // corrupt the index. Reaching this throw proves nothing was persisted.
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    const key = entryKey(entry);
+    if (seen.has(key)) {
+      throw new Error(`writeChart: duplicate chart entry id ${key}`);
+    }
+    seen.add(key);
+  }
+
+  const dir = chartDir(targetRoot);
+  const indexed = sortEntries(
+    entries.map((entry) => {
+      const base = { ...entry, stale: false } as IndexedEntry;
+      if (entry.kind === "vessel") {
+        base.signature = treeSignature(targetRoot, entry.paths);
+      }
+      return base;
+    })
+  );
+  const notices = diffNotices(previous ?? [], indexed);
+  const noticesText = renderNotices(notices);
+  const sheets = renderSheets(indexed);
+
+  mkdirSync(dir, { recursive: true });
+  const files = new Map<string, string>(sheets);
+  files.set(INDEX_FILE, indexJsonl(indexed));
+  if (notices.length > 0) files.set(NOTICES_FILE, noticesText);
+  writeFilesAtomically(dir, files);
+
+  // Cleanup runs after the atomic rename: the write has persisted, so a
+  // failing cleanup is reported in the result, never thrown — a throw here
+  // would surface a tool error for a write that in fact landed, and leave
+  // the caller assuming the previous chart.
+  let cleanupError: string | undefined;
+  try {
+    // Remove sheets the new chart no longer owns (retired vessels).
+    for (const name of readdirSync(dir)) {
+      if (name.endsWith(".md") && !sheets.has(name)) {
+        unlinkSync(join(dir, name));
+      }
+    }
+    // An empty report is removed: the notices file reflects the latest write.
+    if (notices.length === 0) rmSync(join(dir, NOTICES_FILE), { force: true });
+  } catch (err) {
+    cleanupError = err instanceof Error ? err.message : String(err);
+  }
+  return { dir, index: indexed, notices, noticesText, ...(cleanupError !== undefined ? { cleanupError } : {}) };
+}

package/core/src/chartroom/cli.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+/**
+ * The Chart Room CLI — human/scheduler entries (the MCP tool `chart.render`
+ * is the single-province one; both call the same core functions).
+ *
+ *   bun core/src/chartroom/cli.ts render --target <province root>
+ *       One-file Chart Room export for one province.
+ *
+ *   bun core/src/chartroom/cli.ts review --target <t1> [--target <t2> ...]
+ *       Fleet review: a multi-province index page, written into the FIRST
+ *       named target's .portolan/fleet-review.html ("the reviewing
+ *       harbor"). Targets are read-only; nothing is discovered by scanning.
+ *
+ * Both commands are deterministic over unchanged inputs. Any failure (no
+ * chart, bad arguments) exits 1 with the error on stderr.
+ */
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { renderChartRoom } from "./render";
+import { buildFleetReview } from "./review";
+
+const usage = `usage:
+  bun core/src/chartroom/cli.ts render --target <province root>
+  bun core/src/chartroom/cli.ts review --target <t1> [--target <t2> ...]`;
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: {
+    target: { type: "string", multiple: true, default: [] },
+  },
+});
+
+const command = positionals[0];
+if (
+  !command ||
+  (command !== "render" && command !== "review") ||
+  positionals.length > 1 ||
+  values.target.length === 0
+) {
+  console.error(usage);
+  process.exit(1);
+}
+// render takes exactly one province; silently ignoring the rest would
+// pretend the extra targets were served.
+if (command === "render" && values.target.length > 1) {
+  console.error("render takes one --target; to assemble several provinces use review");
+  process.exit(1);
+}
+
+try {
+  if (command === "render") {
+    const result = renderChartRoom(resolve(values.target[0]!));
+    console.log(`chart-room.html written: ${result.path}`);
+    console.log(`entries: ${result.entries} — ${JSON.stringify(result.counts)}`);
+  } else {
+    const result = buildFleetReview(values.target.map((t) => resolve(t)));
+    console.log(`fleet-review.html written: ${result.path}`);
+    console.log(`provinces: ${result.provinces}`);
+  }
+} catch (err) {
+  console.error(String(err instanceof Error ? err.message : err));
+  process.exit(1);
+}

package/core/src/chartroom/render.ts

@@ -0,0 +1,213 @@
+/**
+ * The Chart Room renderer — the byproduct export of the Chart
+ * (openspec/changes/chart-room).
+ *
+ * Reads the machine index (and, when present, the Sailing Directions) and
+ * writes one self-contained `<target>/.portolan/chart-room.html`: nautical
+ * archipelago map + engineering layered graph over the same embedded data,
+ * deterministic (same chart in → same bytes out), zero runtime dependencies.
+ * The layout lives in the page; core owns only reading, inlining, and
+ * writing. Reads the Chart, writes exactly one file, never the storage.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readChart, chartDir } from "../chart-store";
+import { writeFilesAtomically } from "../chart-io";
+import type { IndexedEntry, NoticeAction } from "../types";
+
+/** Where the artifact lands — inside the write perimeter, never the chart dir. */
+export function chartRoomPath(targetRoot: string): string {
+  return resolve(targetRoot, ".portolan/chart-room.html");
+}
+
+/** One parsed notice line group from notices.txt. */
+export interface ParsedNotice {
+  action: NoticeAction;
+  key: string;
+  note?: string;
+  anchors: string[];
+}
+
+/**
+ * Dependency tangles: strongly connected components (size ≥ 2) of the
+ * fairway graph over vessel ids. Self-loops and singletons are not
+ * tangles. Deterministic — members sorted by id, groups by first member.
+ */
+export function findTangles(entries: IndexedEntry[]): string[][] {
+  const vesselIds = new Set(
+    entries.filter((e) => e.kind === "vessel").map((e) => e.id),
+  );
+  const adj = new Map<string, string[]>();
+  for (const e of entries) {
+    if (e.kind !== "fairway") continue;
+    const f = e as IndexedEntry & { from: string; to: string };
+    if (!vesselIds.has(f.from) || !vesselIds.has(f.to)) continue;
+    if (!adj.has(f.from)) adj.set(f.from, []);
+    adj.get(f.from)!.push(f.to);
+  }
+  // Tarjan SCC
+  let index = 0;
+  const idx = new Map<string, number>();
+  const low = new Map<string, number>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const sccs: string[][] = [];
+  const strong = (v: string): void => {
+    idx.set(v, index);
+    low.set(v, index);
+    index += 1;
+    stack.push(v);
+    onStack.add(v);
+    for (const w of adj.get(v) ?? []) {
+      if (!idx.has(w)) {
+        strong(w);
+        low.set(v, Math.min(low.get(v)!, low.get(w)!));
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v)!, idx.get(w)!));
+      }
+    }
+    if (low.get(v) === idx.get(v)) {
+      const component: string[] = [];
+      let w: string;
+      do {
+        w = stack.pop()!;
+        onStack.delete(w);
+        component.push(w);
+      } while (w !== v);
+      sccs.push(component);
+    }
+  };
+  for (const v of vesselIds) if (!idx.has(v)) strong(v);
+  return sccs
+    .filter((c) => c.length > 1)
+    .map((c) => c.sort())
+    .sort((a, b) => (a[0]! < b[0]! ? -1 : 1));
+}
+
+/**
+ * Parse the plain-text grammar produced by `renderNotices` (notices.ts):
+ * header + per-notice entry lines (label padded to 14 columns) followed by
+ * indented `anchor:` continuation lines. Absent or empty file → [].
+ */
+export function parseNotices(text: string): ParsedNotice[] {
+  const labels = new Set(["ADDED", "CORRECTED", "MARKED STALE", "RETIRED"]);
+  const actionOf = (word: string): NoticeAction | undefined => {
+    if (word === "ADDED") return "added";
+    if (word === "CORRECTED") return "corrected";
+    if (word === "MARKED STALE") return "markedStale";
+    if (word === "RETIRED") return "retired";
+    return undefined;
+  };
+  const notices: ParsedNotice[] = [];
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    const entryMatch = raw.match(/^(ADDED|CORRECTED|MARKED STALE|RETIRED)\s+(.*)$/);
+    if (entryMatch && labels.has(entryMatch[1]!)) {
+      const rest = entryMatch[2]!;
+      const dash = rest.indexOf(" — ");
+      const key = dash === -1 ? rest : rest.slice(0, dash);
+      const notice: ParsedNotice = { action: actionOf(entryMatch[1]!)!, key, anchors: [] };
+      if (dash !== -1) notice.note = rest.slice(dash + 3);
+      notices.push(notice);
+      continue;
+    }
+    const anchorMatch = raw.match(/^\s+anchor:\s*(.+)$/);
+    if (anchorMatch && notices.length > 0) {
+      notices[notices.length - 1]!.anchors.push(anchorMatch[1]!);
+    }
+    // anything else (e.g. the header line) is skipped
+  }
+  return notices;
+}
+
+/** Render the Sailing Directions (markdown) into the briefing panel HTML. */
+export function inlineMd(md: string): string {
+  const esc = (s: string) =>
+    s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const out: string[] = [];
+  let inList = false;
+  for (const raw of md.split("\n")) {
+    const line = raw.trimEnd();
+    const inline = (s: string) =>
+      esc(s)
+        .replace(/\*\*([^*]+)\*\*/g, "<b>$1</b>")
+        .replace(/`([^`]+)`/g, "<code>$1</code>");
+    const h = line.match(/^(#{1,3})\s+(.*)$/);
+    const li = line.match(/^[-*]\s+(.*)$/);
+    if (li) {
+      if (!inList) { out.push("<ul>"); inList = true; }
+      out.push(`<li>${inline(li[1]!)}</li>`);
+    } else {
+      if (inList) { out.push("</ul>"); inList = false; }
+      if (h) out.push(`<h3>${inline(h[2]!)}</h3>`);
+      else if (line.trim()) out.push(`<p>${inline(line)}</p>`);
+    }
+  }
+  if (inList) out.push("</ul>");
+  return out.join("\n");
+}
+
+/**
+ * JSON for inlining into a <script> block: no `</script>` breakout, no
+ * U+2028/2029. The caller MUST substitute with a function replacement so
+ * `$`-sequences in chart notes (`$(hadoop classpath)`, `${...}`) reach the
+ * page verbatim — a plain string replace would interpret them.
+ */
+export function safeInlineJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+function loadTemplate(): string {
+  const here = fileURLToPath(import.meta.url);
+  return readFileSync(resolve(here, "..", "template.html"), "utf8");
+}
+
+export interface ChartRoomResult {
+  path: string;
+  entries: number;
+  counts: Record<string, number>;
+  bytes: number;
+}
+
+/** Render the Chart Room for one province. Throws (loudly) when no chart. */
+export function renderChartRoom(targetRoot: string): ChartRoomResult {
+  const entries: IndexedEntry[] = readChart(targetRoot); // loud when absent
+  const sdPath = resolve(targetRoot, ".portolan/sailing-directions.md");
+  const sd = existsSync(sdPath) ? readFileSync(sdPath, "utf8") : "";
+  const expedition = (sd.match(/Expedition (\S+)/) || [])[1] ?? "—";
+
+  const noticesPath = join(chartDir(targetRoot), "notices.txt");
+  const notices = existsSync(noticesPath)
+    ? parseNotices(readFileSync(noticesPath, "utf8"))
+    : [];
+
+  const briefMd = sd.replace(/^# .*\n/, "");
+  const briefHtml = briefMd
+    ? inlineMd(briefMd)
+    : "<p>No sailing directions on this province.</p>";
+
+  const meta = {
+    province: basename(resolve(targetRoot)),
+    targetPath: resolve(targetRoot),
+    expedition,
+  };
+
+  const html = loadTemplate()
+    .replace("__CHART_DATA__", () =>
+      safeInlineJson({ entries, notices, tangles: findTangles(entries) }))
+    .replace("__BRIEF_HTML__", () => JSON.stringify(briefHtml))
+    .replace("__META__", () => safeInlineJson(meta));
+
+  const counts: Record<string, number> = {};
+  for (const e of entries) counts[e.kind] = (counts[e.kind] ?? 0) + 1;
+
+  const path = chartRoomPath(targetRoot);
+  // Same stage-temp-then-rename discipline as the chart itself: a crash
+  // mid-write leaves the previous room intact, never a truncated file.
+  writeFilesAtomically(dirname(path), new Map([[basename(path), html]]));
+  return { path, entries: entries.length, counts, bytes: html.length };
+}