@fcon-tech/portolan 0.4.5

package/core/src/server/server.ts

@@ -0,0 +1,123 @@
+/**
+ * The Portolan MCP server: one stdio server exposing the whole v1 toolset
+ * through the registry table. Two rules live here and nowhere else
+ * (design.md, decisions 1 and 4):
+ *
+ * 1. Pass-through. A tool's result is returned verbatim — structured
+ *    (`structuredContent`) plus the same value as JSON text for older
+ *    clients. The server never renames, reinterprets, or flattens.
+ * 2. The not-crash/not-swallow split. A rejection from an underlying tool
+ *    becomes an MCP tool error (`isError: true`) carrying the tool's own
+ *    message verbatim; the process keeps serving. Only transport-level
+ *    failures may terminate the server. A global catch-and-log is
+ *    deliberately absent: rejections must stay loud.
+ *
+ * specs/harness/spec.md
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type CallToolResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { resolve } from "node:path";
+import pkg from "../../package.json";
+import { TOOL_TABLE, type ToolContext } from "./registry";
+
+export const SERVER_INFO = { name: "portolan", version: pkg.version } as const;
+
+export interface PortolanServerOptions {
+  /** The one province this server serves; every tool is scoped to it. */
+  targetRoot: string;
+}
+
+/**
+ * Raised when a tool call tries to carry its own target root. The spec's
+ * words: the server is bound to one province, and changing provinces means
+ * launching a new server.
+ */
+export class TargetRedirectError extends Error {
+  constructor(launchedRoot: string, requested: string) {
+    super(
+      `this server is bound to the province at ${launchedRoot} and cannot be redirected ` +
+        `to ${requested}; changing provinces means launching a new server`,
+    );
+    this.name = "TargetRedirectError";
+  }
+}
+
+/**
+ * The province binding, enforced once at the handler boundary: a call that
+ * echoes the launched root passes; a call naming any other root is refused
+ * with an error naming the launched target.
+ */
+export function guardTarget(
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): void {
+  if (args.targetRoot === undefined) return;
+  if (typeof args.targetRoot !== "string") {
+    throw new TargetRedirectError(ctx.targetRoot, JSON.stringify(args.targetRoot));
+  }
+  const requested = resolve(args.targetRoot);
+  if (requested !== ctx.targetRoot) {
+    throw new TargetRedirectError(ctx.targetRoot, requested);
+  }
+}
+
+/** A successful tool call: the tool's result, enveloped for MCP. */
+export function toolSuccess(result: unknown): CallToolResult {
+  const value = result as Record<string, unknown>;
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    ...(value !== null && typeof value === "object" ? { structuredContent: value } : {}),
+  };
+}
+
+/** A rejected tool call: the rejection's message, verbatim, as a tool error. */
+export function toolError(err: unknown): CallToolResult {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
+/** Build the server bound to one province. Connect it to a transport. */
+export function createPortolanServer(options: PortolanServerOptions): Server {
+  const ctx: ToolContext = { targetRoot: options.targetRoot };
+  const server = new Server(SERVER_INFO, {
+    capabilities: { tools: {} },
+    instructions:
+      `Portolan — the Cartographer's tools for the province at ${options.targetRoot}. ` +
+      `Every result is anchored and trust-labeled; every write lands under ` +
+      `.portolan/ inside the province. Tool errors carry the underlying ` +
+      `tool's message; they never mean the server died.`,
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: TOOL_TABLE.map((spec) => ({
+      name: spec.name,
+      description: spec.description,
+      inputSchema: spec.inputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const spec = TOOL_TABLE.find((tool) => tool.name === name);
+    if (spec === undefined) {
+      // An unknown tool is a malformed call, not a tool rejection: report it
+      // as a protocol error while the server keeps serving.
+      throw new Error(`unknown tool ${JSON.stringify(name)}; call tools/list for the v1 toolset`);
+    }
+    try {
+      guardTarget(args ?? {}, ctx);
+      return toolSuccess(await spec.handler(args ?? {}, ctx));
+    } catch (err) {
+      return toolError(err);
+    }
+  });
+
+  return server;
+}

package/core/src/server/test-harness.ts

@@ -0,0 +1,161 @@
+/**
+ * Test harness for the MCP server: builds provinces, launches the real
+ * entry point as a subprocess over stdio, and hands a connected SDK client
+ * to the test. Every server launch in the suite goes through here, so the
+ * parity tests and the integration tests exercise the identical artifact.
+ */
+import { afterAll, expect } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, readFileSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { findBinary } from "../tools/shared";
+
+export const SERVER_ENTRY = join(import.meta.dir, "main.ts");
+
+/** The repo's test doubles (ctags) and fixtures root. */
+export const fixturesBin = join(import.meta.dir, "..", "..", "test", "fixtures", "bin");
+export const manifestFixtures = join(
+  import.meta.dir,
+  "..",
+  "..",
+  "test",
+  "fixtures",
+  "manifests",
+);
+
+const targets: string[] = [];
+afterAll(() => {
+  while (targets.length > 0) rmSync(targets.pop() as string, { recursive: true, force: true });
+});
+
+/**
+ * Build a small province: two TypeScript sources, all five manifests, a
+ * README. The same shape the probe-tool tests use, so results here are
+ * comparable with the direct tool results asserted in those suites.
+ */
+export function makeProvince(): string {
+  const target = mkdtempSync(join(tmpdir(), "portolan-mcp-"));
+  targets.push(target);
+  mkdirSync(join(target, "src"), { recursive: true });
+  writeFileSync(
+    join(target, "src", "cart.ts"),
+    [
+      "// A small cart service used by MCP server tests.",
+      "",
+      "/** CartService is the symbol under survey. */",
+      "export class CartService {",
+      "  items: string[] = [];",
+      "",
+      "  addItem(item: string): void {",
+      "    this.items.push(item);",
+      "  }",
+      "}",
+    ].join("\n") + "\n",
+  );
+  writeFileSync(
+    join(target, "src", "checkout.ts"),
+    [
+      'import { CartService } from "./cart";',
+      "",
+      "export function checkout(cart: CartService): number {",
+      "  return cart.items.length;",
+      "}",
+    ].join("\n") + "\n",
+  );
+  for (const manifest of [
+    "go.mod",
+    "pom.xml",
+    "package.json",
+    "Cargo.toml",
+    "pubspec.yaml",
+  ]) {
+    writeFileSync(
+      join(target, manifest),
+      readFileSync(join(manifestFixtures, manifest), "utf8"),
+    );
+  }
+  writeFileSync(join(target, "README.md"), "# province\n\nCartService lives in src/cart.ts.\n");
+  return target;
+}
+
+/** The full parent environment, optionally with extra PATH entries prepended. */
+export function childEnv(...pathPrefixes: string[]): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) env[key] = value;
+  }
+  if (pathPrefixes.length > 0) {
+    env.PATH = `${pathPrefixes.join(":")}:${env.PATH ?? ""}`;
+  }
+  return env;
+}
+
+/**
+ * An environment whose PATH contains ripgrep but provably no ctags: a temp
+ * bin directory holding only an rg symlink, REPLACING the inherited PATH —
+ * prepending would still reach a system ctags where one is installed.
+ */
+export function envWithoutCtags(): Record<string, string> | undefined {
+  const rg = findBinary("rg");
+  if (rg === undefined) return undefined;
+  const bin = mkdtempSync(join(tmpdir(), "portolan-mcp-bin-"));
+  targets.push(bin);
+  symlinkSync(rg, join(bin, "rg"));
+  const env = childEnv();
+  env.PATH = bin;
+  return env;
+}
+
+/** An environment with the ctags test double on PATH (rg inherited). */
+export function envWithCtagsDouble(): Record<string, string> {
+  return childEnv(fixturesBin);
+}
+
+/** Launch the real server entry point and run `fn` with a connected client. */
+export async function withServer(
+  options: {
+    targetRoot: string;
+    /** Exact launch vector; defaults to `bun main.ts --target <root>`. */
+    command?: { command: string; args: string[] };
+    /** Child environment; defaults to the parent env. PATH-sensitive tests override. */
+    env?: Record<string, string>;
+    name?: string;
+  },
+  fn: (client: Client) => Promise<void>,
+): Promise<void> {
+  const targetRoot = options.targetRoot;
+  const launch =
+    options.command ?? { command: process.execPath, args: [SERVER_ENTRY, "--target", targetRoot] };
+  const client = new Client(
+    { name: options.name ?? "portolan-tests", version: "0.0.0" },
+    { capabilities: {} },
+  );
+  const transport = new StdioClientTransport({
+    command: launch.command,
+    args: launch.args,
+    env: options.env ?? childEnv(),
+    stderr: "pipe",
+  });
+  try {
+    await client.connect(transport);
+    await fn(client);
+  } finally {
+    await client.close();
+  }
+}
+
+/** The structured content of a successful call, as the tool produced it. */
+export function structuredOf(result: Record<string, unknown>): unknown {
+  expect(result.structuredContent).toBeObject();
+  return result.structuredContent;
+}
+
+/** Assert a call came back as a tool error and return its verbatim message. */
+export function errorTextOf(result: Record<string, unknown>): string {
+  expect(result.isError).toBe(true);
+  const content = result.content as Array<{ type: string; text?: string }>;
+  expect(content.length).toBeGreaterThan(0);
+  return content.map((part) => part.text ?? "").join("\n");
+}

package/core/src/sheets.ts

@@ -0,0 +1,151 @@
+/**
+ * Markdown sheet rendering — the human layer of the Chart.
+ *
+ * Sheets are derived outputs: the store renders them from index entries on
+ * every write, so hand-edited sheets are overwritten by the next expedition
+ * (design.md, trade-offs). One sheet per vessel; behavior absence is always
+ * rendered as unsurveyed, never omitted.
+ */
+import { formatAnchor, type Anchor, type IndexedEntry } from "./types";
+
+type VesselIndexed = Extract<IndexedEntry, { kind: "vessel" }>;
+
+/** File name for a vessel's sheet (sanitized; lives in `.portolan/chart/`). */
+export function sheetFileName(vesselId: string): string {
+  return `${vesselId.replace(/[^a-zA-Z0-9._-]+/g, "-")}.md`;
+}
+
+function anchorList(anchors: Anchor[]): string {
+  return anchors.map(formatAnchor).join("; ");
+}
+
+function entryLine(entry: IndexedEntry, label: string): string {
+  return `- ${label} (\`${entry.kind}/${entry.id}\`, trust: ${entry.trust}) — anchor: ${anchorList(entry.anchors)}`;
+}
+
+function section(title: string, lines: string[]): string[] {
+  if (lines.length === 0) return [];
+  return [`## ${title}`, ...lines, ""];
+}
+
+function renderVesselSheet(
+  vessel: VesselIndexed,
+  owned: IndexedEntry[],
+  stale: boolean
+): string {
+  const byKind = (kind: IndexedEntry["kind"]) =>
+    owned.filter((e) => e.kind === kind);
+
+  const fairwaysIn = owned.filter((e) => e.kind === "fairway" && e.to === vessel.id);
+  const fairwaysOut = owned.filter((e) => e.kind === "fairway" && e.from === vessel.id);
+  const unsurveyedEntries = owned.filter((e) => e.trust === "unsurveyed");
+
+  const parts: string[] = [];
+  parts.push(`# Vessel ${vessel.id} — ${vessel.name}`, "");
+  if (stale) {
+    parts.push("> **Pending correction** — sources changed since the last survey.", "");
+  }
+  parts.push("```chart", JSON.stringify(vessel, null, 2), "```", "");
+  parts.push(`**Trust:** ${vessel.trust}`, "");
+  parts.push("## Behavior", "");
+  parts.push(vessel.behavior ?? "Unsurveyed — no behavior recorded.", "");
+  parts.push(
+    ...section(
+      "Fairways in",
+      fairwaysIn.map((e) =>
+        entryLine(e, `from \`${(e as Extract<IndexedEntry, { kind: "fairway" }>).from}\``)
+      )
+    )
+  );
+  parts.push(
+    ...section(
+      "Fairways out",
+      fairwaysOut.map((e) =>
+        entryLine(e, `to \`${(e as Extract<IndexedEntry, { kind: "fairway" }>).to}\``)
+      )
+    )
+  );
+  parts.push(
+    ...section(
+      "Ports of entry",
+      byKind("portOfEntry").map((e) => {
+        const p = e as Extract<IndexedEntry, { kind: "portOfEntry" }>;
+        return entryLine(e, `\`${p.protocol}\`${p.note ? ` — ${p.note}` : ""}`);
+      })
+    )
+  );
+  parts.push(
+    ...section(
+      "Lights",
+      byKind("light").map((e) =>
+        entryLine(
+          e,
+          `\`${(e as Extract<IndexedEntry, { kind: "light" }>).name}\``
+        )
+      )
+    )
+  );
+  parts.push(
+    ...section(
+      "Beacons",
+      byKind("beacon").map((e) => {
+        const b = e as Extract<IndexedEntry, { kind: "beacon" }>;
+        return entryLine(e, `${b.surface} \`${b.key}\``);
+      })
+    )
+  );
+  parts.push(
+    ...section(
+      "Dangers",
+      byKind("danger").map((e) => {
+        const d = e as Extract<IndexedEntry, { kind: "danger" }>;
+        return entryLine(e, `${d.category} — ${d.note}`);
+      })
+    )
+  );
+  const unsurveyedLines: string[] = [];
+  if (vessel.behavior === undefined) unsurveyedLines.push("- behavior not recorded");
+  for (const e of unsurveyedEntries) {
+    unsurveyedLines.push(`- \`${e.kind}/${e.id}\` — anchor: ${anchorList(e.anchors)}`);
+  }
+  parts.push(...section("Unsurveyed", unsurveyedLines));
+
+  return `${parts.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * Render one markdown sheet per vessel. `staleVessels` marks sheets with the
+ * pending-correction banner (set by refreshStaleness; a fresh write passes
+ * nothing).
+ */
+export function renderSheets(
+  entries: IndexedEntry[],
+  staleVessels: ReadonlySet<string> = new Set()
+): Map<string, string> {
+  const sheets = new Map<string, string>();
+  const vessels = entries.filter((e): e is VesselIndexed => e.kind === "vessel");
+  const owner = new Map<string, string>();
+  for (const vessel of vessels) {
+    const file = sheetFileName(vessel.id);
+    // The sanitization is many-to-one: ids like `foo/bar` and `foo:bar`
+    // collapse to the same file name. Refuse rather than let one vessel's
+    // sheet silently document another.
+    const prior = owner.get(file);
+    if (prior !== undefined) {
+      throw new Error(
+        `sheet file name collision: vessel ids ${JSON.stringify(prior)} and ${JSON.stringify(vessel.id)} ` +
+          `both render to ${file} — give the vessels distinct ids`
+      );
+    }
+    owner.set(file, vessel.id);
+    const owned = entries.filter(
+      (e) =>
+        e.kind !== "vessel" &&
+        (e.kind === "fairway"
+          ? e.from === vessel.id || e.to === vessel.id
+          : e.vessel === vessel.id)
+    );
+    sheets.set(file, renderVesselSheet(vessel, owned, staleVessels.has(vessel.id)));
+  }
+  return sheets;
+}

package/core/src/staleness.ts

@@ -0,0 +1,203 @@
+/**
+ * Staleness: per-vessel source signatures and the refresh that flips changed
+ * vessels' entries to `pending correction`.
+ *
+ * The signature is a cheap tree hash (design.md, decision 3): the file list,
+ * sizes, and mtimes under the vessel's paths, sorted and hashed. Content
+ * hashing is deliberately avoided — the repair expedition re-reads content
+ * anyway.
+ */
+import { lstatSync, readdirSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import type { IndexedEntry, Notice, VesselSignature } from "./types";
+import {
+  INDEX_FILE,
+  NOTICES_FILE,
+  chartDir,
+  indexJsonl,
+  readChart,
+  writeFilesAtomically,
+} from "./chart-io";
+import { renderSheets, sheetFileName } from "./sheets";
+import { diffNotices, renderNotices } from "./notices";
+
+interface FileFact {
+  path: string;
+  size: number;
+  mtime: number;
+}
+
+function collect(root: string, rel: string, out: FileFact[]): void {
+  if (escapesRoot(root, rel)) return; // never walk past the target perimeter
+  let stats;
+  try {
+    stats = statSync(join(root, rel));
+  } catch {
+    return; // a path that no longer exists contributes nothing
+  }
+  if (stats.isFile()) {
+    out.push({ path: rel, size: stats.size, mtime: Math.round(stats.mtimeMs) });
+    return;
+  }
+  if (!stats.isDirectory()) return;
+  const entries = readdirSync(join(root, rel), { withFileTypes: true }).sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+  );
+  for (const de of entries) {
+    if (de.isDirectory()) collect(root, `${rel}/${de.name}`, out);
+    else if (de.isFile()) {
+      const s = statSync(join(root, rel, de.name));
+      out.push({
+        path: `${rel}/${de.name}`,
+        size: s.size,
+        mtime: Math.round(s.mtimeMs),
+      });
+    }
+  }
+}
+
+/** True when a charted path resolves outside the target root. A `..`
+ * segment escapes lexically, and so does an absolute path: resolve() keeps
+ * the absolute, which then fails the prefix check. */
+function escapesRoot(root: string, rel: string): boolean {
+  const abs = resolve(root, rel);
+  return abs !== root && !abs.startsWith(root + sep);
+}
+
+/**
+ * A charted top-level path the province cannot vouch for: one that escapes
+ * the root, or one that is itself a symlink (a link's metadata and target
+ * live outside what the survey read). Such a vessel is never provably
+ * fresh — it always counts as changed.
+ */
+function unprovablePath(root: string, rel: string): boolean {
+  if (escapesRoot(root, rel)) return true;
+  try {
+    return lstatSync(join(root, rel)).isSymbolicLink();
+  } catch {
+    return false; // absent: collect() contributes nothing, detection decides
+  }
+}
+
+/**
+ * Cheap tree hash over the given paths (relative to the target root):
+ * sorted `path\tsize\tmtime` lines, SHA-256. A top-level path is stat'ed as
+ * given, so a symlinked vessel root resolves; symlinked entries found
+ * during the walk are not followed (only dirents reporting file or dir are
+ * descended/collected). Paths that escape the root contribute nothing.
+ */
+export function treeSignature(targetRoot: string, paths: string[]): VesselSignature {
+  // Resolve once: collect() compares paths against the root lexically, so a
+  // relative targetRoot would classify every path as escaping and sign the
+  // empty set — "always drifted" for the whole chart. Callers may pass
+  // either form; the signature must not depend on it.
+  const root = resolve(targetRoot);
+  const facts: FileFact[] = [];
+  for (const p of paths) {
+    // A symlinked top-level path would be stat'ed through the link, signing
+    // metadata the province never surveyed; it contributes nothing here (the
+    // refresh already treats such a vessel as never provably fresh).
+    try {
+      if (lstatSync(join(root, p)).isSymbolicLink()) continue;
+    } catch {
+      // absent — collect() contributes nothing either
+    }
+    collect(root, p, facts);
+  }
+  facts.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const text = facts.map((f) => `${f.path}\t${f.size}\t${f.mtime}`).join("\n");
+  return { hash: createHash("sha256").update(text).digest("hex"), files: facts.length };
+}
+
+/** Result of a staleness refresh. */
+export interface StalenessResult {
+  /** Vessel ids whose source signature changed since the last survey. */
+  changedVessels: string[];
+  /** Entries now marked `pending correction`. */
+  staleEntries: IndexedEntry[];
+  /** Notices to Mariners produced by this refresh. */
+  notices: Notice[];
+  noticesText: string;
+}
+
+/**
+ * Re-verify every vessel's source signature against the index and recompute
+ * the pending-correction marks: an entry is stale exactly while its vessel's
+ * sources differ from the survey — a drift sets the mark, a reverted drift
+ * clears it (chart spec: entries whose sources are unchanged MUST NOT be
+ * marked). With no flag flip in either direction, nothing is written at all.
+ *
+ * The refresh never deletes `notices.txt`: when a re-detection finds no flag
+ * transitions, the outstanding report from the earlier refresh still
+ * describes the still-pending vessels and stays on the chart. Only a chart
+ * write replaces the report (its own contract).
+ */
+export function refreshStaleness(targetRoot: string): StalenessResult {
+  const entries = readChart(targetRoot);
+
+  const changed = new Set<string>();
+  const root = resolve(targetRoot);
+  for (const entry of entries) {
+    if (entry.kind !== "vessel") continue;
+    // A vessel charted through an escaping or symlinked path can never prove
+    // freshness: it counts as changed, so the chart never vouches for what
+    // it cannot see.
+    if (entry.paths.some((p) => unprovablePath(root, p))) {
+      changed.add(entry.id);
+      continue;
+    }
+    const current = treeSignature(targetRoot, entry.paths);
+    // A vessel without a recorded signature counts as changed: never claim
+    // freshness we cannot prove.
+    if (entry.signature?.hash !== current.hash) changed.add(entry.id);
+  }
+
+  // Recompute, never accumulate: the mark states the province's present
+  // drift, not its history. entries.map keeps order and length, so the
+  // before/after flag comparison below is index-aligned by construction.
+  const next = entries.map((entry): IndexedEntry => {
+    const stale =
+      entry.kind === "vessel"
+        ? changed.has(entry.id)
+        : entry.kind === "fairway"
+          ? changed.has(entry.from) || changed.has(entry.to)
+          : changed.has(entry.vessel);
+    return stale === entry.stale ? entry : { ...entry, stale };
+  });
+  const flipped = next.filter((entry, i) => entry.stale !== entries[i]!.stale);
+
+  if (flipped.length === 0) {
+    return {
+      changedVessels: [...changed].sort(),
+      staleEntries: next.filter((e) => e.stale),
+      notices: [],
+      noticesText: "",
+    };
+  }
+
+  const dir = chartDir(targetRoot);
+  const notices = diffNotices(entries, next);
+  const noticesText = renderNotices(notices);
+  const files = new Map<string, string>();
+  files.set(INDEX_FILE, indexJsonl(next));
+  if (notices.length > 0) files.set(NOTICES_FILE, noticesText);
+  const staleNow = new Set(
+    next.filter((e) => e.kind === "vessel" && e.stale).map((e) => e.id),
+  );
+  const sheets = renderSheets(next, staleNow);
+  for (const entry of flipped) {
+    if (entry.kind !== "vessel") continue;
+    const name = sheetFileName(entry.id);
+    const sheet = sheets.get(name);
+    if (sheet) files.set(name, sheet);
+  }
+  writeFilesAtomically(dir, files);
+
+  return {
+    changedVessels: [...changed].sort(),
+    staleEntries: next.filter((e) => e.stale),
+    notices,
+    noticesText,
+  };
+}