@shortlink-org/portolan 0.2.3 → 0.3.0

package/scripts/local-discovery.mjs

@@ -169,7 +169,7 @@ function goDeployables(root, files) {
   return out;
 }
 
-function detected(plugin, candidates, options = {}, label = candidates[0], ambiguous = false, selected = true) {
+function detected(plugin, candidates, options = {}, label = candidates[0], ambiguous = false, selected = true, preview = []) {
   if (!candidates.length) return null;
   return {
     plugin,
@@ -178,15 +178,74 @@ function detected(plugin, candidates, options = {}, label = candidates[0], ambig
     candidates,
     options,
     selected,
+    ...(preview.length ? { preview } : {}),
+  };
+}
+
+const ADR_STATUSES = new Map([
+  ["proposed", "proposed"], ["draft", "proposed"], ["pending", "proposed"], ["на рассмотрении", "proposed"],
+  ["accepted", "accepted"], ["approved", "accepted"], ["adopted", "accepted"], ["принято", "accepted"], ["принят", "accepted"],
+  ["superseded", "superseded"], ["заменено", "superseded"], ["заменён", "superseded"],
+  ["deprecated", "deprecated"], ["obsolete", "deprecated"], ["устарело", "deprecated"],
+  ["rejected", "rejected"], ["declined", "rejected"], ["отклонено", "rejected"],
+]);
+
+function normalizedAdrStatus(value) {
+  return ADR_STATUSES.get(value.trim().replace(/[.:]+$/, "").toLowerCase()) ?? "";
+}
+
+// Discovery mirrors the tolerant shapes accepted by extract-adr closely
+// enough to enable the capability with confidence and to show what it found.
+// Git-backed dates are resolved by the extractor, so a format without an
+// explicit Date can still be previewed here without inventing one.
+function adrPreview(root, name) {
+  let source = "";
+  try { source = readFileSync(join(root, name), "utf8").replaceAll("\r\n", "\n"); } catch { return null; }
+  const lines = source.split("\n");
+  const heading = lines.find((line) => line.trim()) ?? "";
+  const base = posix.basename(name, ".md");
+  const numberedFile = /^(\d+)-([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(base);
+
+  let number = "";
+  let title = "";
+  let match = /^#\s+[a-z][a-z0-9.-]*\.(\d{4})\s+—\s+(.+?)\s*$/i.exec(heading);
+  if (match) [number, title] = match.slice(1);
+  else if ((match = /^#\s+(\d+)\.\s+(.+?)\s*$/.exec(heading))) [number, title] = match.slice(1);
+  else if ((match = /^#\s+ADR[-\s]?0*(\d+)\s*[.:—-]\s*(.+?)\s*$/i.exec(heading))) [number, title] = match.slice(1);
+  else if (numberedFile && (match = /^#\s+(.+?)\s*$/.exec(heading))) {
+    number = numberedFile[1];
+    title = match[1];
+  }
+  if (!number || !title || !numberedFile || Number(numberedFile[1]) !== Number(number)) return null;
+  if (!lines.some((line) => /^#{2,6}\s/.test(line))) return null;
+
+  let status = "";
+  const bullet = /^-\s+\*\*Status:\*\*\s*(.*?)\s*$/mi.exec(source);
+  if (bullet) status = normalizedAdrStatus(bullet[1]);
+  if (!status) {
+    const at = lines.findIndex((line) => /^#{2,6}\s+(?:Status|Статус)\s*:?/i.test(line));
+    if (at >= 0) {
+      const inline = /^#{2,6}\s+(?:Status|Статус)\s*:?\s*(.*?)\s*$/i.exec(lines[at])?.[1] ?? "";
+      const following = lines.slice(at + 1).find((line) => line.trim() && !/^#{1,6}\s/.test(line)) ?? "";
+      status = normalizedAdrStatus(inline || following);
+    }
+  }
+  if (!status) return null;
+
+  const writtenDate = /^(?:-\s+\*\*Date:\*\*|Date:)\s*(\S.*?)\s*$/mi.exec(source)?.[1];
+  if (writtenDate) {
+    const stamp = new Date(`${writtenDate}T00:00:00Z`);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(writtenDate) || Number.isNaN(stamp.getTime()) || stamp.toISOString().slice(0, 10) !== writtenDate) return null;
+  }
+  const date = writtenDate ?? "from git history";
+  return {
+    file: name,
+    fields: { number: String(Number(number)), title: title.trim(), status, date },
   };
 }
 
 function compatibleAdrs(root, candidates) {
-  return candidates.filter((name) => {
-    let source = "";
-    try { source = readFileSync(join(root, name), "utf8"); } catch { return false; }
-    return /^#\s+[^\n]+\.\d{4}\s+[—-]/m.test(source) && /^-\s+\*\*Status:\*\*/mi.test(source) && /^-\s+\*\*Date:\*\*/mi.test(source);
-  });
+  return candidates.map((name) => adrPreview(root, name)).filter(Boolean);
 }
 
 function goDomainEvidence(root, files) {
@@ -211,6 +270,18 @@ function goDomainEvidence(root, files) {
   return "";
 }
 
+// This is a discovery hint; the Go AST extractor proves the handler binding.
+function goHTTPServerEvidence(root, files) {
+  for (const name of matches(files, /\.go$/).filter((name) => !/(?:_test|\.gen|_generated)\.go$/.test(name) && !/(?:^|\/)(?:testdata|vendor)\//.test(name))) {
+    let source;
+    try { source = readFileSync(join(root, name), "utf8"); } catch { continue; }
+    if (/Code generated .*DO NOT EDIT/.test(source)) continue;
+    if (/"net\/http"/.test(source) && /\.Handle(?:Func)?\s*\(/.test(source)) return name;
+    if (/"github\.com\/(?:go-chi\/chi|gin-gonic\/gin|labstack\/echo)(?:\/v\d+)?"/.test(source) && /\.(?:Get|Post|Put|Patch|Delete|GET|POST|PUT|PATCH|DELETE)\s*\(/.test(source)) return name;
+  }
+  return "";
+}
+
 function laidOutDomainEvidence(root, files, language) {
   const extension = language === "typescript" ? "ts" : language === "rust" ? "rs" : "java";
   const prefix = language === "java" ? /(?:^|\/)domain\/([^/]+)\/[^/]+\.java$/i : /^src\/domain\/([^/]+)\/[^/]+\.(?:ts|rs)$/i;
@@ -291,8 +362,9 @@ function detectionsFor(root, files) {
   const graphql = matches(files, /\.graphqls?$/i);
   const protos = matches(files, /\.proto$/i);
   const sql = matches(files, /(^|\/)(migrations?|repository)(\/|.*\/).*\.sql$/i);
-  const adrs = matches(files, /(^|\/)(docs\/adr|adr)\/.*\.md$/i);
-  const supportedAdrs = compatibleAdrs(root, adrs);
+  const adrs = matches(files, /(^|\/)(docs\/adr|adr)\/.*\.md$/i).filter((name) => posix.basename(name).toLowerCase() !== "readme.md");
+  const adrPreviews = compatibleAdrs(root, adrs);
+  const supportedAdrs = adrPreviews.map((item) => item.file);
   const glossaries = matches(files, /(^|\/)glossary\.md$/i);
   // The app module is the one file a Celery project always has; the tasks
   // and the calls that enqueue them are found from there.
@@ -308,7 +380,7 @@ function detectionsFor(root, files) {
   const protoDirs = compactDirectories(protos);
   const projectMarkers = ["go.mod", "package.json", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts", "manage.py", "Dockerfile", "README.md"].filter((name) => files.has(name));
   const projectEvidence = projectMarkers.length ? projectMarkers : [[...files].sort()[0]].filter(Boolean);
-  const goDomain = files.has("go.mod") ? goDomainEvidence(root, files) : "";
+  const goDomain = files.has("go.mod") ? goDomainEvidence(root, files) || goHTTPServerEvidence(root, files) : "";
   const goHTTPClient = files.has("go.mod") ? goHTTPClientEvidence(root, files) : "";
   const goSOAPClient = files.has("go.mod") ? goSOAPClientEvidence(root, files) : "";
   const goRedis = files.has("go.mod") ? goRedisEvidence(root, files) : "";
@@ -349,6 +421,7 @@ function detectionsFor(root, files) {
       supportedAdrs[0] ? `${posix.dirname(supportedAdrs[0])}/*.md` : `${posix.dirname(adrs[0] ?? "docs/adr/x.md")}/*.md (format not recognized)`,
       !supportedAdrs.length,
       supportedAdrs.length > 0,
+      adrPreviews,
     ),
     detected("glossary", glossaries, glossaries.length ? { files: glossaries } : {}, glossaries.join(", ")),
   ].filter(Boolean);

package/scripts/manifest.mjs

@@ -12,6 +12,7 @@ import { readFileSync } from "node:fs";
 import { normalize } from "node:path";
 
 import Ajv from "ajv/dist/2020.js";
+import { warningPolicyProblems } from "./warning-policy.mjs";
 
 // Read when asked, not when loaded: the CLI sets PORTOLAN_SCHEMA after its imports.
 const schemaFile = () => process.env.PORTOLAN_SCHEMA || "schema/portolan.schema.json";
@@ -38,20 +39,21 @@ export function loadManifest(path = "portolan.json") {
  */
 export function parseManifest(text, path = "portolan.json") {
   const manifest = JSON.parse(text);
+  const policyProblems = warningPolicyProblems(manifest.warningPolicies, path);
 
   let schema;
   try {
     schema = JSON.parse(readFileSync(schemaFile(), "utf8"));
   } catch {
-    return { manifest, problems: [] };
+    return { manifest, problems: policyProblems };
   }
 
   const ajv = new Ajv({ allErrors: true, strictSchema: false });
   const validate = ajv.compile(schema);
 
-  if (validate(manifest)) return { manifest, problems: [] };
+  if (validate(manifest)) return { manifest, problems: policyProblems };
 
-  return { manifest, problems: explain(validate.errors ?? [], manifest, schema, path) };
+  return { manifest, problems: [...explain(validate.errors ?? [], manifest, schema, path), ...policyProblems] };
 }
 
 /**

package/scripts/manifest.test.mjs

@@ -58,6 +58,30 @@ describe("the manifest schema", () => {
     expect(check(good)).toEqual([]);
   });
 
+  it("accepts a typed CEL warning policy only with an action and reason", () => {
+    expect(check({
+      ...good,
+      warningPolicies: [{
+        when: "plugin == 'openapi' && rule == 'openapi.missing-operation-id' && count > 10",
+        action: "suppress",
+        reason: "The contract is owned upstream.",
+      }],
+    })).toEqual([]);
+
+    const problems = check({
+      ...good,
+      warningPolicies: [{ when: "plugin == 'openapi'", action: "suppress" }],
+    });
+    expect(problems.join("\n")).toContain('warningPolicies/0: "reason" is missing');
+  });
+
+  it("refuses a CEL warning policy with unknown variables or a non-boolean result", () => {
+    expect(check({ ...good, warningPolicies: [{ when: "owner == 'team'", action: "suppress", reason: "test" }] }).join("\n"))
+      .toContain("Unknown variable: owner");
+    expect(check({ ...good, warningPolicies: [{ when: "plugin", action: "suppress", reason: "test" }] }).join("\n"))
+      .toContain("CEL expression must return bool");
+  });
+
   it("refuses an unstable project id", () => {
     const problems = check({
       ...good,

package/scripts/output-diff.mjs

@@ -0,0 +1,94 @@
+// Why a generated file is not what the generator produces now, in one line.
+//
+// `gen --check` used to say "changed docs/x.md" and nothing else, which sent
+// the reader to a diff of the whole file to learn that one number moved.
+// The first difference is usually the whole story: a JSON fragment names the
+// path that differs and both values, a page names the line.
+
+/**
+ * @param {string | Buffer | null} current  what is on disk, null when absent
+ * @param {string | Buffer} wanted          what the generator produced
+ * @param {string} name                     the file's name, for its format
+ * @returns {string}
+ */
+export function explainChange(current, wanted, name) {
+  if (current === null) return "not on disk yet";
+  if (Buffer.isBuffer(current) || Buffer.isBuffer(wanted)) return "binary contents differ";
+  if (name.endsWith(".json")) {
+    const found = jsonDifference(current, wanted);
+    if (found) return found;
+  }
+  return lineDifference(current, wanted);
+}
+
+/** The first path where two JSON documents disagree, or "" when either does not parse. */
+export function jsonDifference(current, wanted) {
+  let a;
+  let b;
+  try {
+    a = JSON.parse(current);
+    b = JSON.parse(wanted);
+  } catch {
+    return "";
+  }
+  return firstDifference(a, b, "") ?? "same value, different formatting";
+}
+
+function firstDifference(a, b, path) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const shared = Math.min(a.length, b.length);
+    for (let i = 0; i < shared; i++) {
+      const found = firstDifference(a[i], b[i], `${path}[${i}]`);
+      if (found) return found;
+    }
+    if (a.length !== b.length) {
+      return `${path || "the document"}: ${a.length} item${a.length === 1 ? "" : "s"} → ${b.length}`;
+    }
+    return null;
+  }
+  if (isObject(a) && isObject(b)) {
+    for (const key of Object.keys(b)) {
+      const at = path ? `${path}.${key}` : key;
+      if (!(key in a)) return `${at}: added ${short(b[key])}`;
+      const found = firstDifference(a[key], b[key], at);
+      if (found) return found;
+    }
+    for (const key of Object.keys(a)) {
+      if (!(key in b)) return `${path ? `${path}.${key}` : key}: removed`;
+    }
+    return null;
+  }
+  if (Object.is(a, b)) return null;
+  return `${path || "the document"}: ${short(a)} → ${short(b)}`;
+}
+
+/** The first line that differs, with both sides, or the extra lines when one is a prefix of the other. */
+export function lineDifference(current, wanted) {
+  const a = current.split("\n");
+  const b = wanted.split("\n");
+  const shared = Math.min(a.length, b.length);
+  for (let i = 0; i < shared; i++) {
+    if (a[i] !== b[i]) return `line ${i + 1}: ${short(a[i])} → ${short(b[i])}`;
+  }
+  if (a.length === b.length) return "identical";
+  const extra = Math.abs(a.length - b.length);
+  return a.length < b.length
+    ? `line ${shared + 1}: ${extra} line${extra === 1 ? "" : "s"} added`
+    : `line ${shared + 1}: ${extra} line${extra === 1 ? "" : "s"} removed`;
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A value as one short token: strings quoted, structures summarised. */
+function short(value) {
+  const text = typeof value === "string" ? JSON.stringify(value) : isObject(value) || Array.isArray(value) ? summarise(value) : String(value);
+  return text.length > 60 ? `${text.slice(0, 57)}…` : text;
+}
+
+function summarise(value) {
+  if (Array.isArray(value)) return `[${value.length} item${value.length === 1 ? "" : "s"}]`;
+  const keys = Object.keys(value);
+  return `{${keys.slice(0, 3).join(", ")}${keys.length > 3 ? ", …" : ""}}`;
+}

package/scripts/output-diff.test.mjs

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+
+import { explainChange, jsonDifference, lineDifference } from "./output-diff.mjs";
+
+describe("explainChange", () => {
+  it("names the JSON path and both values", () => {
+    const current = JSON.stringify({ contexts: [{ services: [{ commands: [{ source: "package.json:58" }] }] }] });
+    const wanted = JSON.stringify({ contexts: [{ services: [{ commands: [{ source: "package.json:59" }] }] }] });
+    expect(explainChange(current, wanted, "commands.json")).toBe(
+      'contexts[0].services[0].commands[0].source: "package.json:58" → "package.json:59"',
+    );
+  });
+
+  it("says what was added, what was removed, and when a list grew", () => {
+    expect(jsonDifference('{"a":1}', '{"a":1,"b":{"x":1,"y":2}}')).toBe("b: added {x, y}");
+    expect(jsonDifference('{"a":1,"b":2}', '{"a":1}')).toBe("b: removed");
+    expect(jsonDifference('{"flows":[1]}', '{"flows":[1,2,3]}')).toBe("flows: 1 item → 3");
+  });
+
+  it("falls back to lines for text, and for JSON that does not parse", () => {
+    expect(lineDifference("a\nb\nc", "a\nB\nc")).toBe('line 2: "b" → "B"');
+    expect(lineDifference("a\nb", "a\nb\nc\nd")).toBe("line 3: 2 lines added");
+    expect(lineDifference("a\nb\nc", "a")).toBe("line 2: 2 lines removed");
+    expect(explainChange("{not json", "{still not", "x.json")).toBe('line 1: "{not json" → "{still not"');
+  });
+
+  it("knows a file that is not there yet, and a binary one", () => {
+    expect(explainChange(null, "x", "x.md")).toBe("not on disk yet");
+    expect(explainChange(Buffer.from([1]), Buffer.from([2]), "x.png")).toBe("binary contents differ");
+  });
+
+  it("keeps a long value readable", () => {
+    const long = "x".repeat(200);
+    expect(jsonDifference('{"a":"short"}', `{"a":"${long}"}`)).toMatch(/^a: "short" → "x{56}…$/);
+  });
+});

package/scripts/package-smoke.mjs

@@ -2,9 +2,9 @@
 // This catches accidental cwd coupling before the same package reaches npm.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -31,9 +31,58 @@ try {
   writeFileSync(resolve(fixture, "package.json"), '{"name":"package-smoke","version":"1.0.0"}\n');
   writeFileSync(resolve(fixture, "README.md"), "# Package smoke\n");
   // A Go domain layout: init should notice it and wire the extractor without being asked.
-  writeFileSync(resolve(fixture, "go.mod"), "module example.com/smoke\n\ngo 1.24\n");
+  writeFileSync(resolve(fixture, "go.mod"), "module example.com/smoke\n\ngo 1.27.0\n");
   mkdirSync(resolve(fixture, "internal/domain/order"), { recursive: true });
   writeFileSync(resolve(fixture, "internal/domain/order/order.go"), "package order\n\ntype Order struct{ ID string }\n");
+  writeGoFixture("app/main.go", `package app
+import (
+  "example.com/smoke/actions/rules"
+  "example.com/smoke/connector"
+)
+type Router struct{}
+func (*Router) POST(string, func()) {}
+type Requester interface { ConnExec(connector.API) }
+func Start(r *Router) { r.POST("/rules", RulesAction) }
+func RulesAction() {
+  request := &rules.Request{}
+  Dispatch(request)
+}
+func Dispatch(request Requester) { Invoke(request) }
+func Invoke(request Requester) {
+  conn := connector.Build("runtime")
+  request.ConnExec(conn)
+}
+`);
+  writeGoFixture("actions/rules/request.go", `package rules
+import "example.com/smoke/connector"
+type Request struct{}
+func (*Request) ConnExec(conn connector.API) { conn.Rules() }
+`);
+  writeGoFixture("connector/factory.go", `package connector
+import "example.com/smoke/provider/alpha"
+type API interface { Rules() }
+func Build(name string) API {
+  switch name { case "alpha": return alpha.New(); default: return nil }
+}
+`);
+  writeGoFixture("provider/alpha/connector.go", `package alpha
+import "example.com/smoke/provider/alpha/client"
+type rulesClient interface { FetchRules() }
+type Connector struct { client rulesClient }
+func New() *Connector { return &Connector{client: &client.Client{}} }
+func (c *Connector) Rules() { c.client.FetchRules() }
+`);
+  writeGoFixture("provider/alpha/client/client.go", `package client
+import "net/http"
+type Client struct{}
+func (c *Client) FetchRules() { c.fetchRules() }
+func (c *Client) fetchRules() { c.finishRules() }
+func (c *Client) finishRules() {
+  _, _ = http.Get("https://alpha.example/v1/rules")
+  if false { c.fetchRules() }
+}
+func (*Client) CheckRules() { _, _ = http.Get("https://alpha.example/v1/check-rules") }
+`);
   run("git", ["init", "--quiet"]);
   run("git", ["config", "user.email", "portolan@example.invalid"]);
   run("git", ["config", "user.name", "Portolan smoke test"]);
@@ -44,9 +93,13 @@ try {
   run(process.execPath, [cli, "check", "--cwd", fixture]);
   run(process.execPath, [cli, "build", "--cwd", fixture, "--output", "dist", "--base", "/architecture/"]);
 
-  for (const path of ["portolan/project.json", "portolan/domain.json", "docs/README.md", "dist/index.html", "dist/404.html"]) {
+  for (const path of ["portolan/project.json", "portolan/domain.json", "portolan/http-clients.json", "docs/README.md", "dist/index.html", "dist/404.html"]) {
     if (!existsSync(resolve(fixture, path))) throw new Error(`smoke test did not write ${path}`);
   }
+  const calls = JSON.parse(readFileSync(resolve(fixture, "portolan/http-clients.json"), "utf8"));
+  if (!calls.flows.some((flow) => flow.name === "POST /rules → provider APIs")) {
+    throw new Error(`package smoke did not preserve the typed HTTP provider flow; got ${calls.flows.map((flow) => flow.name).join(", ")}`);
+  }
   console.log("package smoke: init, generate, check, and build passed outside the repository");
 } finally {
   rmSync(fixture, { recursive: true, force: true });
@@ -56,3 +109,8 @@ try {
 function run(command, args) {
   execFileSync(command, args, { cwd: fixture, stdio: "inherit" });
 }
+
+function writeGoFixture(path, contents) {
+  mkdirSync(dirname(resolve(fixture, path)), { recursive: true });
+  writeFileSync(resolve(fixture, path), contents);
+}

package/scripts/plugin-host.mjs

@@ -185,8 +185,28 @@ export function validateResponse(name, response) {
 }
 
 function validBase64(value) {
-  return value.length % 4 === 0
-    && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+  if (value.length % 4 !== 0) return false;
+
+  let payloadLength = value.length;
+  if (value.endsWith("==")) payloadLength -= 2;
+  else if (value.endsWith("=")) payloadLength -= 1;
+
+  // A repeated-group regexp over a multi-megabyte binary can exhaust V8's
+  // regexp stack. Validate the same alphabet iteratively so vendoring a large
+  // file remains bounded by its bytes rather than the JavaScript call stack.
+  for (let index = 0; index < payloadLength; index += 1) {
+    const code = value.charCodeAt(index);
+    const alphabet = code >= 65 && code <= 90
+      || code >= 97 && code <= 122
+      || code >= 48 && code <= 57
+      || code === 43
+      || code === 47;
+    if (!alphabet) return false;
+  }
+  for (let index = payloadLength; index < value.length; index += 1) {
+    if (value.charCodeAt(index) !== 61) return false;
+  }
+  return true;
 }
 
 function safeFileName(name) {

package/scripts/plugin-host.test.mjs

@@ -21,6 +21,15 @@ describe("plugin response validation", () => {
     expect(() => validateResponse("fixture", { files: [{ name: "image.png", contents: "x", encoding: "binary" }] })).toThrow("encoding is not supported");
   });
 
+  it("validates multi-megabyte base64 without overflowing the regexp stack", () => {
+    const contents = "A".repeat(13 * 1024 * 1024);
+    expect(validateResponse("fixture", { files: [{ name: "large.bin", contents, encoding: "base64" }] }).files[0]).toEqual({
+      name: "large.bin",
+      contents,
+      encoding: "base64",
+    });
+  });
+
   it.each(["../secret", "/tmp/result", "C:\\tmp\\result", "a/../../secret", "./result"])(
     "rejects unsafe output name %s",
     (name) => {

package/scripts/plugin-wasm-worker.mjs

@@ -10,7 +10,10 @@ async function run() {
     const wasi = new WASI({
       version: "preview1",
       args: [workerData.name],
-      env: {},
+      env: {
+        GOOS: process.env.GOOS || ({ win32: "windows" }[process.platform] ?? process.platform),
+        GOARCH: process.env.GOARCH || ({ x64: "amd64", ia32: "386" }[process.arch] ?? process.arch),
+      },
       // Empty for a generator or a describe request. An extract or verify
       // step gets the workspace as `/`, and nothing else (portolan.0006).
       preopens: workerData.workspace ? { "/": workerData.workspace } : {},

package/scripts/provenance.mjs

@@ -0,0 +1,72 @@
+// Where each catalog source last changed, for the site's stamp.
+//
+// A fragment carries no provenance of its own (portolan.0010); the history of
+// the checkout does. The browser cannot ask git, so this Vite plugin asks at
+// build time - and again under the dev server whenever a source changes -
+// and answers with one virtual module, keyed by the path `src/data.ts` gives
+// a source. Nothing watches `.git`: a commit made while the dev server runs
+// shows after a restart, or after the next change to a source.
+
+import { existsSync, globSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { forgetHistory, stampsFor } from "./history.mjs";
+import { readManifest } from "./manifest.mjs";
+
+export const PROVENANCE_MODULE = "virtual:portolan-provenance";
+const RESOLVED = `\0${PROVENANCE_MODULE}`;
+
+/**
+ * The stamp of every source the manifest's patterns find under `workspace`,
+ * keyed by its path as the manifest spells it.
+ *
+ * A staged site (`portolan dev`, `portolan build`) imports its sources under
+ * flattened names, `portolan/source-0007.json`, and keeps the way back in
+ * `.portolan/source-paths.json`. Such a stamp is keyed by the staged name the
+ * browser imports and carries `source`, the path the file has in the
+ * workspace - the one a project's root is a prefix of, and the one a link to
+ * the file has to name. Without it the site would know its sources only by
+ * names nobody typed.
+ *
+ * @param {string} workspace
+ * @param {string} siteRoot  Vite's root, which may contain flattened sources
+ * @returns {Record<string, {commit: string, generatedAt: string, source?: string}>}
+ */
+export function provenance(workspace, siteRoot = workspace) {
+  const sourceMap = join(siteRoot, ".portolan/source-paths.json");
+  if (existsSync(sourceMap)) {
+    const paths = JSON.parse(readFileSync(sourceMap, "utf8"));
+    const stamps = stampsFor(workspace, Object.values(paths));
+    return Object.fromEntries(Object.entries(paths).map(([staged, source]) => [staged, { ...stamps.get(source), source }]));
+  }
+  const manifest = readManifest(join(workspace, "portolan.json"));
+  const paths = [];
+  for (const pattern of manifest.sources ?? []) {
+    for (const path of globSync(pattern, { cwd: workspace })) paths.push(path.split("\\").join("/"));
+  }
+  return Object.fromEntries(stampsFor(workspace, paths.sort()));
+}
+
+/** @param {string} workspace */
+export function provenancePlugin(workspace) {
+  let siteRoot = workspace;
+  return {
+    name: "portolan-provenance",
+    configResolved(config) {
+      siteRoot = config.root;
+    },
+    resolveId(id) {
+      return id === PROVENANCE_MODULE ? RESOLVED : undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED) return undefined;
+      return `export default ${JSON.stringify(provenance(workspace, siteRoot))};\n`;
+    },
+    handleHotUpdate({ file, server }) {
+      if (!file.endsWith(".json") || file.includes("/node_modules/")) return;
+      forgetHistory();
+      const mod = server.moduleGraph.getModuleById(RESOLVED);
+      if (mod) server.moduleGraph.invalidateModule(mod);
+    },
+  };
+}