@shortlink-org/portolan 0.2.4 → 0.3.0

package/scripts/local-api.test.mjs

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { rmSync } from "node:fs";
 
-import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, readLocalSource, removeProject, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, writeProject } from "./local-api.mjs";
+import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, readLocalSource, removeProject, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, workspaceFingerprint, writeProject } from "./local-api.mjs";
 import { installDeliveryPreset, planDeliveryPreset, providerFromRemote, publicDeliveryPreset } from "./delivery-presets.mjs";
 
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -140,13 +140,18 @@ describe("local project setup", () => {
     writeFileSync(join(root, ".gitlab-ci.yml"), "lint:\n  script: echo lint\n");
     const preview = planDeliveryPreset(root);
     expect(preview).toMatchObject({ provider: "gitlab", detectedProvider: "gitlab", status: "available" });
-    expect(preview.files[0].diff).toContain("+\"portolan:check\":");
+    expect(preview.features.filter((feature) => feature.selected).map((feature) => feature.id)).toEqual(["pages"]);
+    expect(preview.files[0].diff).not.toContain("+\"portolan:check\":");
     const installed = installDeliveryPreset(root, { provider: "gitlab", revision: preview.revision });
     expect(installed.status).toBe("installed");
     const pipeline = readFileSync(join(root, ".gitlab-ci.yml"), "utf8");
     expect(pipeline).toContain("lint:\n  script: echo lint");
     expect(pipeline).toContain("# >>> Portolan delivery preset >>>");
-    expect(pipeline).toContain("pages:\n    publish: dist");
+    expect(pipeline).toContain("\npages:\n");
+    expect(pipeline).toContain("stage: deploy");
+    expect(pipeline).toContain("tags:\n    - runner-type:docker");
+    expect(pipeline).toContain("portolan build --output public");
+    expect(pipeline).toContain("artifacts:\n    paths:\n      - public");
     expect(existsSync(join(root, ".github"))).toBe(false);
   });
 
@@ -239,6 +244,33 @@ describe("local project setup", () => {
     expect(discovery.detections.find((item) => item.plugin === "adr")?.selected).toBe(false);
   });
 
+  it("recognizes common ADR markdown variants and previews extracted fields", () => {
+    const root = workspace();
+    const adrRoot = join(root, "services/billing/docs/adr");
+    rmSync(join(adrRoot, "0001.md"));
+    writeFileSync(join(adrRoot, "0001-store-invoices.md"), "# 1. Store invoices\n\nDate: 2025-01-02\n\n## Status\n\nAccepted\n\n## Decision\n\nUse Postgres.\n");
+    writeFileSync(join(adrRoot, "02-package-layout.md"), "# ADR-2. Архитектура пакетов\n\n#### Статус: на рассмотрении\n\n### Решение\n\nУпростить структуру.\n");
+
+    const discovery = discoverProject(root, "services/billing");
+    const adr = discovery.detections.find((item) => item.plugin === "adr");
+    expect(adr).toMatchObject({
+      selected: true,
+      confidence: "high",
+      evidence: "docs/adr/*.md",
+      options: { files: ["docs/adr/*.md"] },
+    });
+    expect(adr?.preview).toEqual([
+      { file: "docs/adr/0001-store-invoices.md", fields: { number: "1", title: "Store invoices", status: "accepted", date: "2025-01-02" } },
+      { file: "docs/adr/02-package-layout.md", fields: { number: "2", title: "Архитектура пакетов", status: "proposed", date: "from git history" } },
+    ]);
+
+    const manifest = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    const plan = planProject(root, manifest, {
+      root: "services/billing", id: "billing", name: "Billing", group: "finance", component: "billing", plugins: ["adr"],
+    });
+    expect(plan.steps[0].options).toEqual({ files: ["docs/adr/*.md"], scope: "finance.billing", out: "adr.json" });
+  });
+
   it("names external projects from the repository or selected component instead of the inspection cache", () => {
     expect(externalProjectDefaults("https://github.com/batazor/microservice-template-ddd")).toEqual({
       id: "microservice-template-ddd",
@@ -691,7 +723,7 @@ describe("local project setup", () => {
       plugins: ["openapi", "redis"],
       steps: [{ plugin: "openapi", out: output }, { plugin: "redis", out: output }],
     }, [
-      { type: "step-finished", phase: "extract", plugin: "openapi", output, status: "written", durationMs: 4, fileCount: 1, changedCount: 1, files: [`${output}/api.json`], warnings: ["one route has no description"] },
+      { type: "step-finished", phase: "extract", plugin: "openapi", output, status: "written", durationMs: 4, fileCount: 1, changedCount: 1, files: [`${output}/api.json`], warnings: ["one route has no description"], diagnostics: [{ plugin: "openapi", rule: "plugin.openapi.other-test", severity: "warning", action: "Inspect it.", message: "one route has no description", count: 1, project: "billing", phase: "extract", suppressed: true, suppressionReason: "Owned upstream." }] },
       { type: "step-finished", phase: "extract", plugin: "redis", output, status: "written", durationMs: 3, fileCount: 1, changedCount: 1, files: [`${output}/redis.json`], warnings: [] },
       { type: "step-finished", phase: "generate", plugin: "markdown", output: "docs", status: "written", durationMs: 2, fileCount: 10, changedCount: 10, files: ["docs/index.md"], warnings: [] },
     ]);
@@ -709,6 +741,33 @@ describe("local project setup", () => {
     });
     expect(result.steps.map((step) => step.plugin)).toEqual(["openapi", "redis"]);
     expect(result.warnings).toEqual([{ plugin: "openapi", message: "one route has no description" }]);
+    expect(result.diagnostics).toEqual([expect.objectContaining({ rule: "plugin.openapi.other-test", suppressed: true })]);
     expect(result.generatedFiles).toBe(2);
   });
 });
+
+describe("workspaceFingerprint", () => {
+  it("reads a repository before its first commit without complaint, and moves when a file does", () => {
+    const root = workspace();
+    execFileSync("git", ["init", "-q", "-b", "main"], { cwd: root });
+    execFileSync("git", ["add", "services/billing/go.mod"], { cwd: root });
+
+    const before = workspaceFingerprint(root);
+    expect(workspaceFingerprint(root)).toBe(before);
+
+    writeFileSync(join(root, "services/billing/go.mod"), "module example.com/billing\n\ngo 1.22\n");
+    const staged = workspaceFingerprint(root);
+    expect(staged).not.toBe(before);
+
+    writeFileSync(join(root, "services/billing/api/handlers.go"), "package api\n");
+    expect(workspaceFingerprint(root)).not.toBe(staged);
+  });
+
+  it("is the same whether or not the repository has a commit, for the same tree", () => {
+    const root = workspace();
+    execFileSync("git", ["init", "-q", "-b", "main"], { cwd: root });
+    const unborn = workspaceFingerprint(root);
+    execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "--allow-empty", "-m", "empty"], { cwd: root });
+    expect(workspaceFingerprint(root)).toBe(unborn);
+  });
+});

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 } : {},