@shortlink-org/portolan 0.1.0 → 0.2.0

package/cli/init.test.mjs

@@ -0,0 +1,158 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { InitError, defaultAnswers, init } from "./init.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const created = [];
+
+beforeAll(() => {
+  process.env.PORTOLAN_SCHEMA = resolve(root, "schema/portolan.schema.json");
+  process.env.PORTOLAN_INSTALL_ROOT = root;
+});
+
+afterEach(() => {
+  for (const path of created.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+function workspace(files) {
+  const dir = mkdtempSync(join(tmpdir(), "portolan-init-"));
+  created.push(dir);
+  for (const [name, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, name)), { recursive: true });
+    writeFileSync(join(dir, name), content);
+  }
+  return dir;
+}
+
+const quiet = { version: "0.0.0-test", log: () => {}, ask: { ...defaultAnswers, warn: () => {} } };
+const manifestOf = (dir) => JSON.parse(readFileSync(join(dir, "portolan.json"), "utf8"));
+const goService = {
+  "go.mod": "module example.com/orders\n\ngo 1.24\n",
+  "internal/domain/order/order.go": "package order\n\ntype Order struct{ ID string }\n",
+};
+
+describe("init with defaults", () => {
+  it("reads what the repository contains into one project at the root", async () => {
+    const dir = workspace({
+      "package.json": '{"name":"@acme/order-service","scripts":{"test":"vitest"}}\n',
+      ...goService,
+      "api/openapi.yaml": "openapi: 3.0.0\ninfo:\n  title: Orders\n  version: '1'\npaths: {}\n",
+      "docs/adr/0001-free-form.md": "# Not an ADR Portolan understands\n",
+    });
+    const result = await init(dir, quiet);
+    const manifest = manifestOf(dir);
+
+    expect(manifest.projects).toEqual([{ id: "order-service", name: "Order Service", root: ".", group: "order-service", component: "order-service" }]);
+    expect(manifest.sources).toEqual(["portolan/*.json"]);
+    expect(manifest.extract.map((step) => step.plugin)).toEqual(["project", "go-domain", "openapi"]);
+    expect(manifest.extract.every((step) => step.in === "." && step.out === "portolan")).toBe(true);
+    expect(manifest.extract[0].options).toMatchObject({ groupKind: "bounded-context", componentKind: "service" });
+    expect(manifest.extract[2].options.spec).toBe("api/openapi.yaml");
+    expect(manifest.generate.map((step) => step.plugin)).toEqual(["markdown", "mermaid"]);
+    expect(result.generate).toBe(false);
+
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    expect(pkg.scripts).toEqual({ test: "vitest", "architecture": "portolan dev", "architecture:gen": "portolan generate", "architecture:check": "portolan check", "architecture:build": "portolan build" });
+    expect(readFileSync(join(dir, ".gitignore"), "utf8")).toContain(".portolan/\n");
+  });
+
+  it("turns nested build files into one project each when the root has none", async () => {
+    const dir = workspace({
+      "README.md": "# Estate\n",
+      "services/orders/go.mod": goService["go.mod"],
+      "services/orders/internal/domain/order/order.go": goService["internal/domain/order/order.go"],
+      "services/web/package.json": '{"name":"web"}\n',
+    });
+    await init(dir, quiet);
+    const manifest = manifestOf(dir);
+    const repository = manifest.projects[0].group;
+
+    expect(manifest.projects.map((project) => [project.id, project.root, project.component])).toEqual([
+      ["orders", "services/orders", "orders"],
+      ["web", "services/web", "web"],
+    ]);
+    expect(manifest.projects.every((project) => project.group === repository)).toBe(true);
+    expect(manifest.sources).toEqual(["services/orders/portolan/*.json", "services/web/portolan/*.json"]);
+    expect(manifest.extract.map((step) => [step.plugin, step.in])).toEqual([
+      ["project", "services/orders"],
+      ["go-domain", "services/orders"],
+      ["project", "services/web"],
+    ]);
+  });
+
+  it("keeps the root as the project when it has a build file of its own", async () => {
+    const dir = workspace({
+      "package.json": '{"name":"tool"}\n',
+      "examples/demo/go.mod": goService["go.mod"],
+    });
+    await init(dir, quiet);
+    expect(manifestOf(dir).projects.map((project) => project.root)).toEqual(["."]);
+  });
+
+  it("still writes a manifest for an empty directory", async () => {
+    const dir = workspace({});
+    await init(dir, quiet);
+    const manifest = manifestOf(dir);
+    expect(manifest.extract.map((step) => step.plugin)).toEqual(["project"]);
+    expect(manifest.projects[0].root).toBe(".");
+  });
+
+  it("refuses to touch an existing manifest", async () => {
+    const dir = workspace({ "portolan.json": "{}\n" });
+    await expect(init(dir, quiet)).rejects.toThrow(InitError);
+    expect(readFileSync(join(dir, "portolan.json"), "utf8")).toBe("{}\n");
+  });
+});
+
+describe("init with answers", () => {
+  it("writes only the roots, plugins and identity that were chosen", async () => {
+    const dir = workspace({
+      "README.md": "# Estate\n",
+      "services/orders/go.mod": goService["go.mod"],
+      "services/orders/internal/domain/order/order.go": goService["internal/domain/order/order.go"],
+      "services/web/package.json": '{"name":"web"}\n',
+    });
+    const asked = [];
+    const result = await init(dir, {
+      ...quiet,
+      ask: {
+        ...quiet.ask,
+        roots: (choices) => { asked.push(["roots", choices.map((choice) => [choice.path, choice.selected])]); return ["services/orders"]; },
+        plugins: (root, detections) => { asked.push(["plugins", root, detections.map((detection) => detection.plugin)]); return ["project"]; },
+        scripts: () => false,
+        generate: () => true,
+      },
+    });
+    const manifest = manifestOf(dir);
+
+    expect(asked).toEqual([
+      ["roots", [[".", false], ["services/orders", true], ["services/web", true]]],
+      ["plugins", "services/orders", ["project", "go-domain"]],
+    ]);
+    expect(manifest.projects.map((project) => project.id)).toEqual(["orders"]);
+    expect(manifest.extract.map((step) => step.plugin)).toEqual(["project"]);
+    expect(result.generate).toBe(true);
+  });
+
+  it("uses the id the user typed for a single project", async () => {
+    const dir = workspace({ "package.json": '{"name":"@acme/whatever"}\n' });
+    await init(dir, {
+      ...quiet,
+      ask: { ...quiet.ask, identity: (defaults) => ({ ...defaults, id: "orders", name: "Orders", group: "orders", component: "orders" }) },
+    });
+    const manifest = manifestOf(dir);
+    expect(manifest.projects[0]).toMatchObject({ id: "orders", name: "Orders" });
+    expect(manifest.extract[0].options).toMatchObject({ group: "orders", component: "orders", componentName: "Orders" });
+    expect(manifest.generate[0].options.title).toBe("Orders");
+  });
+
+  it("writes nothing when the user declines", async () => {
+    const dir = workspace({ "package.json": '{"name":"x"}\n' });
+    await expect(init(dir, { ...quiet, ask: { ...quiet.ask, write: () => false } })).rejects.toThrow(/cancelled/);
+    expect(() => readFileSync(join(dir, "portolan.json"))).toThrow();
+  });
+});

package/cli/portolan.mjs

@@ -18,6 +18,8 @@ import { glob } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { InitError, commandWorks, init as runInit, isInteractive, promptAnswers, toolchainFor } from "./init.mjs";
+
 const installRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(readFileSync(resolve(installRoot, "package.json"), "utf8"));
 
@@ -84,7 +86,7 @@ function help() {
 Usage: portolan <command> [options]
 
 Commands:
-  init       create a minimal portolan.json for this repository
+  init       inspect this repository and create portolan.json
   dev        open the local architecture site
   generate   update catalog fragments, docs, and exports
   check      fail when committed generated files are out of date
@@ -99,73 +101,48 @@ Options:
   --base PATH     deployed URL base (default: /)
   --host HOST     dev server host (default: 127.0.0.1)
   --port PORT     dev server port
-  --yes, -y       accept non-destructive init defaults`);
+  --yes, -y       init without questions: take every detected default`);
 }
 
-function init(workspace) {
-  const manifestPath = resolve(workspace, "portolan.json");
-  if (existsSync(manifestPath)) fail("portolan.json already exists; init did not change it");
-
-  const projectPackage = readJson(resolve(workspace, "package.json"));
-  const rawName = String(projectPackage?.name ?? basename(workspace)).replace(/^@[^/]+\//, "");
-  const id = slug(rawName) || "project";
-  const title = titleOf(id);
-  const manifest = {
-    $schema: `https://raw.githubusercontent.com/shortlink-org/portolan/${VERSION}/schema/portolan.schema.json`,
-    sources: ["portolan/*.json"],
-    projects: [{ id, name: title, root: ".", group: id, component: id }],
-    extract: [{
-      plugin: "project",
-      in: ".",
-      out: "portolan",
-      options: { group: id, groupName: title, component: id, componentName: title },
-    }],
-    generate: [
-      { plugin: "markdown", out: "docs", options: { title } },
-      { plugin: "mermaid", out: "exports/mermaid", options: { title: `${title} flows` } },
-    ],
-  };
-  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
-
-  if (projectPackage) {
-    const scripts = { ...(projectPackage.scripts ?? {}) };
-    const defaults = {
-      "architecture": "portolan dev",
-      "architecture:gen": "portolan generate",
-      "architecture:check": "portolan check",
-      "architecture:build": "portolan build",
-    };
-    for (const [name, command] of Object.entries(defaults)) {
-      if (!(name in scripts)) scripts[name] = command;
-    }
-    writeFileSync(resolve(workspace, "package.json"), `${JSON.stringify({ ...projectPackage, scripts }, null, 2)}\n`);
-  }
-
-  const ignorePath = resolve(workspace, ".gitignore");
-  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
-  if (!ignore.split(/\r?\n/).includes(".portolan/")) {
-    writeFileSync(ignorePath, `${ignore}${ignore && !ignore.endsWith("\n") ? "\n" : ""}\n# Portolan local build state\n.portolan/\n`);
+async function init(workspace, options) {
+  const interactive = !options.yes && isInteractive();
+  let result;
+  try {
+    result = await runInit(workspace, { version: VERSION, ask: interactive ? promptAnswers(VERSION) : undefined });
+  } catch (error) {
+    if (error instanceof InitError) fail(error.message);
+    throw error;
   }
-
-  console.log("created portolan.json");
-  if (projectPackage) console.log("added architecture scripts to package.json");
-  console.log("next: portolan generate && portolan dev");
+  if (result.generate) runScript("scripts/gen.mjs", [], workspace);
 }
 
 function doctor(workspace) {
+  const manifestPath = resolve(workspace, "portolan.json");
+  const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null;
   const checks = [
     ["Node.js >= 24", Number(process.versions.node.split(".")[0]) >= 24, process.version],
-    ["portolan.json", existsSync(resolve(workspace, "portolan.json")), "required"],
+    ["portolan.json", Boolean(manifest), "required"],
     ["Git", commandWorks("git", ["--version"]), "used for deterministic source stamps"],
-    ["Go", commandWorks("go", ["version"]), "required by built-in Go extractors"],
-    ["Python 3", commandWorks("python3", ["--version"]), "required by Python extractors"],
-    ["Java", commandWorks("java", ["-version"]), "required by the Java extractor"],
-    ["Cargo", commandWorks("cargo", ["--version"]), "required by the Rust extractor"],
   ];
+
+  // A toolchain is required only when a step in this manifest names a plugin
+  // that runs in it; the built-in Go plugins run as wasm and ask for nothing.
+  const needed = new Map();
+  const steps = manifest ? ["extract", "verify", "generate"].flatMap((phase) => manifest[phase] ?? []) : [];
+  for (const name of new Set(steps.map((step) => step.plugin))) {
+    const need = toolchainFor(name, (manifest.plugins ?? []).find((plugin) => plugin.name === name));
+    if (need) needed.set(need.label, [...(needed.get(need.label) ?? []), name]);
+  }
+  for (const [label, command, args] of [["Go", "go", ["version"]], ["Python 3", "python3", ["--version"]], ["Java", "java", ["-version"]], ["Cargo", "cargo", ["--version"]]]) {
+    const plugins = needed.get(label);
+    const present = commandWorks(command, args);
+    checks.push([label, present || !plugins, plugins ? `needed by ${plugins.join(", ")}${present ? "" : "; not on PATH"}` : `${present ? "present" : "absent"}; nothing in portolan.json needs it`]);
+  }
+
   for (const [label, ok, note] of checks) {
     console.log(`${ok ? "ok" : "--"}  ${label}${note ? ` — ${note}` : ""}`);
   }
-  if (!checks[0][1] || !checks[1][1]) process.exitCode = 1;
+  if (checks.some(([, ok]) => !ok)) process.exitCode = 1;
 }
 
 async function build(workspace, options) {
@@ -194,6 +171,7 @@ async function dev(workspace, options) {
   runNode(packageBin("vite", "bin/vite.js"), args, workspace, {
     ...process.env,
     PORTOLAN_WORKSPACE: workspace,
+    BASE_PATH: options.base ?? process.env.BASE_PATH ?? "/",
   });
 }
 
@@ -248,7 +226,10 @@ async function prepareSite(workspace) {
 
 function generateLikeC4(stage) {
   runNode(resolve(stage, "scripts/gen-likec4.mjs"), [], stage);
-  runNode(packageBin("likec4", "bin/likec4.mjs"), ["gen", "react", "likec4", "-o", "src/likec4/generated.jsx"], stage);
+  // Inside a container likec4 switches to a graphviz binary by default and,
+  // finding none, reports "no views found". The wasm engine it uses
+  // everywhere else is the one wanted, so it is asked for by name.
+  runNode(packageBin("likec4", "bin/likec4.mjs"), ["gen", "react", "likec4", "-o", "src/likec4/generated.jsx", "--no-use-dot"], stage);
 }
 
 async function matchedFiles(workspace, patterns) {
@@ -341,23 +322,6 @@ function inside(root, target) {
   return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path));
 }
 
-function commandWorks(command, args) {
-  const result = spawnSync(command, args, { stdio: "ignore" });
-  return !result.error && result.status === 0;
-}
-
-function readJson(path) {
-  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
-}
-
-function slug(value) {
-  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-}
-
-function titleOf(value) {
-  return value.split("-").filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join(" ");
-}
-
 function fail(message) {
   console.error(`portolan: ${message}`);
   process.exit(1);

package/index.html

@@ -4,6 +4,25 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta
+      name="description"
+      content="Portolan turns code, specifications, schemas, traces and ADRs into a static, navigable architecture catalog."
+    />
+    <meta property="og:title" content="Portolan — architecture from code" />
+    <meta
+      property="og:description"
+      content="A navigable map of your software estate, generated from code and evidence."
+    />
+    <meta property="og:type" content="website" />
+    <meta
+      property="og:image"
+      content="https://shortlink-org.github.io/portolan/og.png"
+    />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta
+      name="twitter:image"
+      content="https://shortlink-org.github.io/portolan/og.png"
+    />
     <title>portolan</title>
   </head>
   <body>

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shortlink-org/portolan",
   "description": "Generate a navigable architecture catalog from code and specifications.",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",
@@ -26,7 +26,6 @@
     "public",
     "schema",
     "plugins/*.wasm",
-    "plugins/*/*.go",
     "plugins/*/*.py",
     "plugins/*/*.ts",
     "plugins/*/*.json",
@@ -35,15 +34,10 @@
     "plugins/*/*.lock",
     "plugins/*/src",
     "plugins/extract-java/build",
-    "plugin",
-    "catalog",
-    "internal",
     "index.html",
     "vite.config.ts",
     "tsconfig.json",
     "portolan.json",
-    "go.mod",
-    "go.sum",
     "README.md",
     "LICENSE"
   ],
@@ -61,10 +55,10 @@
     "test:package": "node scripts/package-smoke.mjs",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit && tsc -p plugins/extract-ts",
-    "likec4:gen": "node scripts/gen-likec4.mjs && likec4 gen react likec4 -o src/likec4/generated.jsx",
+    "likec4:gen": "node scripts/gen-likec4.mjs && likec4 gen react likec4 -o src/likec4/generated.jsx --no-use-dot",
     "likec4:validate": "likec4 validate likec4",
     "predev": "npm run likec4:gen",
-    "plugins:build": "GOOS=wasip1 GOARCH=wasm go build -o plugins/gen-markdown.wasm ./plugins/gen-markdown && GOOS=wasip1 GOARCH=wasm go build -o plugins/gen-mermaid.wasm ./plugins/gen-mermaid && GOOS=wasip1 GOARCH=wasm go build -o plugins/gen-backstage.wasm ./plugins/gen-backstage && javac --release 21 -d plugins/extract-java/build plugins/extract-java/src/org/portolan/extract/*.java",
+    "plugins:build": "GOOS=wasip1 GOARCH=wasm go build -trimpath -ldflags=\"-s -w\" -o plugins/portolan-go.wasm ./plugins/cmd/portolan-go && javac --release 21 -d plugins/extract-java/build plugins/extract-java/src/org/portolan/extract/*.java",
     "schema": "npm run plugins:build && node scripts/schema.mjs",
     "schema:check": "npm run plugins:build && node scripts/schema.mjs --check",
     "gen": "npm run plugins:build && node scripts/gen.mjs",
@@ -78,6 +72,7 @@
     "@ai-sdk/openai-compatible": "3.0.44",
     "@ai-sdk/react": "4.0.96",
     "@asyncapi/react-component": "^3.1.8",
+    "@clack/prompts": "^1.8.0",
     "@headlessui/react": "^2.2.10",
     "@scalar/api-reference-react": "^0.9.66",
     "@tanstack/react-query": "^5.102.8",
@@ -108,7 +103,7 @@
     "zustand": "^5.0.15"
   },
   "devDependencies": {
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.5.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^7.0.2",

package/plugins/README.md

@@ -31,6 +31,13 @@ is what makes that worth having: `encoding/json` drops a field it does not
 recognise, so before this a misspelled option was no option at all and nothing
 said so.
 
+A descriptor may also carry `needs`: what the host must put in the request
+beyond the tree, because a sandboxed module cannot reach it. The one need so
+far is `history` (portolan.0007) - when each file under the root was first
+committed and last changed, read by the host from one `git log` and handed
+over as `input.history`, keyed by the path the plugin would open. `extract-adr`
+asks for it; a plugin that does not ask is handed nothing.
+
 A generator **names** files; it never writes them. `scripts/gen.mjs` writes what
 comes back, refuses a name that points outside the output directory, and deletes
 pages that stopped being generated. That is what lets a generator run as a wasm
@@ -56,7 +63,7 @@ either be rendered or be explicitly acknowledged by the relevant exporter.
 
 ## Adding one
 
-1. Write it. In Go, a new directory here with a `main` that hands its options
+1. Write it. In Go, a new package here whose `run` hands its options
    type to `plugin.Serve`, which reads the request, answers a describe and calls
    the work; `catalog.Catalog` from `github.com/shortlink-org/portolan/catalog`
    is the mirror of the schema, and `internal/goscan` is the tree as syntax -
@@ -71,8 +78,12 @@ either be rendered or be explicitly acknowledged by the relevant exporter.
    `go:embed` and returned in the descriptor. `schematest.Check` in a test keeps
    it from drifting from the options struct: a field renamed on one side and not
    the other fails, and so does an option with no description.
-3. Build it. For a wasm plugin, `GOOS=wasip1 GOARCH=wasm go build`. Add the
-   line to `plugins:build` in `package.json`.
+3. Build it. A built-in Go plugin is a library package with
+   `Serve(io.Reader, io.Writer) error`; add it to the map in
+   `plugins/cmd/portolan-go/main.go`, and `plugins:build` in `package.json`
+   puts it in `plugins/portolan-go.wasm` with the rest (a test keeps the map
+   and `portolan.json` in step). A plugin of your own is its own module:
+   `GOOS=wasip1 GOARCH=wasm go build`.
 4. Declare it in `portolan.json`, under `plugins` (how to run it) and
    `generate` (what to run it on), then run `npm run schema` so the manifest
    schema learns its options.
@@ -80,7 +91,7 @@ either be rendered or be explicitly acknowledged by the relevant exporter.
 ```json
 {
   "plugins": [
-    { "name": "markdown", "wasm": { "url": "file://plugins/gen-markdown.wasm" } }
+    { "name": "markdown", "wasm": { "url": "file://plugins/portolan-go.wasm" } }
   ],
   "generate": [
     { "plugin": "markdown", "out": "docs", "options": { "title": "Example estate" } }
@@ -449,7 +460,7 @@ only left out of its own stamp when the output is *inside* the input root, and
 
 ```json
 {
-  "plugins": [{ "name": "adr", "process": { "cmd": "go run ./plugins/extract-adr" } }],
+  "plugins": [{ "name": "adr", "wasm": { "url": "file://plugins/portolan-go.wasm" } }],
   "extract": [
     {
       "plugin": "adr",
@@ -514,7 +525,7 @@ is the point of the id; the same word twice in one context is an error.
 
 ```json
 {
-  "plugins": [{ "name": "glossary", "process": { "cmd": "go run ./plugins/extract-glossary" } }],
+  "plugins": [{ "name": "glossary", "wasm": { "url": "file://plugins/portolan-go.wasm" } }],
   "extract": [
     {
       "plugin": "glossary",
@@ -588,7 +599,7 @@ runner files sit beside the service, so the step is told which one it is.
 
 ```json
 {
-  "plugins": [{ "name": "commands", "process": { "cmd": "go run ./plugins/extract-commands" } }],
+  "plugins": [{ "name": "commands", "wasm": { "url": "file://plugins/portolan-go.wasm" } }],
   "extract": [
     {
       "plugin": "commands",
@@ -808,15 +819,31 @@ the forge looks.
 
 ## wasm or process
 
-`wasm` is the default and should stay that way. The module gets no filesystem,
-no network and no environment; a plugin from somebody else's repository can be
-run over your source tree without reading it.
-
-`process` is the escape hatch for a generator that needs a toolchain — one
-reading Go source has to run `go list`, and no wasm module can spawn anything.
-It gets the same protocol and none of the sandbox, which is the trade being made
-and the reason it is not the default. It declares `command` and an `args` array;
-the host never feeds a command string through a shell.
+`wasm` is the default and should stay that way. The module gets no network, no
+environment and no way to start a process. A generator gets no filesystem
+either. An extract or verify step gets the workspace preopened as `/`
+(portolan.0006), which is how the built-in Go extractors read a tree without a
+Go toolchain on the machine: every one of them, and the three generators, is
+the single module `plugins/portolan-go.wasm`, which answers to the plugin name
+the host passes as `argv[0]`. WASI preopens read-write, so an extractor is
+trusted not to write the tree it reads, the same trust a process plugin has
+today; a `sha256` pins that trust to a build.
+
+`process` is the escape hatch for a plugin that needs a toolchain: the Rust,
+Java, Python and TypeScript extractors run in their own runtimes, and
+`fetch-bsr` still talks to its registry from Go. It gets the same protocol
+and none of the sandbox, which is the trade being made and the reason it is
+not the default. It declares `command` and an `args` array; the host never
+feeds a command string through a shell. A built-in Go plugin that still runs
+as a process is the same code reached as
+`go run ./plugins/cmd/portolan-go <name>`.
+
+`host` is for Portolan's own code that needs what only the host has - a git
+binary, a socket - and so runs inside the host process (portolan.0008):
+`{ "name": "git", "host": "fetch-git" }`. The name is resolved against the
+modules shipped in `scripts/host-plugins/` and nothing else, so a manifest
+cannot point the host at arbitrary code; the contract is the same as any
+plugin's, files named and never written.
 
 A plugin fetched over `https://` must declare its `sha256`; the host verifies it
 and caches by digest. A `file://` plugin may declare one, but a checksum
@@ -838,10 +865,15 @@ paths inside the copy are the repository's own, which is the point: the
 extract step that follows points its `in` at the vendored service and reads
 it exactly as it would read that service's checkout.
 
+It runs inside the host (`scripts/host-plugins/fetch-git.mjs`,
+portolan.0008) rather than as a module, because it needs a git binary and a
+socket, and a manifest names it with `host` rather than `wasm` or `process`.
+The contract is the same: it names files, the host writes them.
+
 ```json
 {
   "sources": ["data/*.json", "vendor/repos/*/*/git.repo.json"],
-  "plugins": [{ "name": "git", "process": { "command": "go", "args": ["run", "./plugins/fetch-git"] } }],
+  "plugins": [{ "name": "git", "host": "fetch-git" }],
   "extract": [
     {
       "plugin": "git",
@@ -928,8 +960,8 @@ its protos and locks are on disk by the time the parser reads them.
 ```json
 {
   "plugins": [
-    { "name": "bsr",   "process": { "command": "go", "args": ["run", "./plugins/fetch-bsr"] } },
-    { "name": "proto", "process": { "command": "go", "args": ["run", "./plugins/extract-proto"] } }
+    { "name": "bsr",   "host": "fetch-bsr" },
+    { "name": "proto", "wasm": { "url": "file://plugins/portolan-go.wasm" } }
   ],
   "extract": [
     {
@@ -966,12 +998,14 @@ decides what to do with them — and not an oversight to work around.
 
 ### Why fetch-bsr can never be wasm
 
-It needs a socket and a credential. `process` exists for exactly that trade, and
-`auth.go` is the only file in either plugin that reads the environment. The
-protocol's "no ambient state" rule is about *facts*: nothing about the estate may
-come from anywhere but the request. A credential is not a fact about the estate —
-it decides whether the fetch succeeds, never what the fetch says — and a test
-asserts the output is byte-identical with and without a token.
+It needs a socket and a credential, which is why it runs inside the host
+(`scripts/host-plugins/fetch-bsr.mjs`, portolan.0008) and is declared with
+`host`. The protocol's "no ambient state" rule is about *facts*: nothing about
+the estate may come from anywhere but the request. A credential is not a fact
+about the estate — it decides whether the fetch succeeds, never what the fetch
+says — and a test asserts the output is byte-identical with and without a
+token. The token comes from `BUF_TOKEN` or the netrc `buf registry login`
+wrote, never from the manifest.
 
 ### Pinning, and the offline rule
 
@@ -1037,6 +1071,11 @@ the reading over a tree it can verify without a registry existing at all.
 | output | one schema and a `csr.lock.json` per subject | one catalog fragment |
 | deterministic | only because it is pinned and cached | absolutely |
 
+Declared as `{ "name": "csr", "host": "fetch-csr" }` and
+`{ "name": "csr-schemas", "wasm": { "url": "file://plugins/portolan-go.wasm" } }`:
+the fetcher runs inside the host (`scripts/host-plugins/fetch-csr.mjs`,
+portolan.0008), the reader in the shared module.
+
 A registered version is immutable: subject `orders-value` at version 3 is the
 same bytes today and next year, and re-registering a changed schema makes
 version 4. That is the promise a BSR commit makes, so the same four rules govern
@@ -1050,8 +1089,8 @@ Each lands in its own directory, and the referring subject's lock is what an
 offline run follows to find them.
 
 Avro and JSON schemas arrive minified onto one line. They are written out
-indented — with `json.Indent`, which reformats without reordering, so the file
-still says what the registry said in the order it said it — because a version
+indented — re-spaced token by token, never re-parsed, so the file still says
+what the registry said in the order it said it — because a version
 bump that is one unreadable line is a review nobody can do. The digest is over
 the bytes as written, so verifying needs no reformatting of anything.