@shortlink-org/portolan 0.1.0 → 0.2.1

package/scripts/local-api.mjs

@@ -18,9 +18,9 @@ import { tmpdir } from "node:os";
 import { createServer as createNetServer } from "node:net";
 import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
 
-import { publicSetupFrom } from "../src/lib/setup-info.ts";
 import { loadManifest } from "./manifest.mjs";
 import { builtinPluginNames } from "./builtin-plugins.mjs";
+import { installDeliveryPreset, planDeliveryPreset, publicDeliveryPreset } from "./delivery-presets.mjs";
 
 export const LOCAL_API_PREFIX = "/__portolan";
 export const GENERATOR_EVENT_PREFIX = "::portolan-event::";
@@ -34,6 +34,15 @@ const repositoryCredentials = new Map();
 const SNAPSHOT_SKIP = new Set([".git", ".portolan", "dist", "node_modules", "target"]);
 const PROJECT_PREVIEW_TTL_MS = 15 * 60 * 1000;
 
+/** Remove Vite's configured base before matching a local control-plane route. */
+export function localApiPath(pathname, base = "/") {
+  const root = base.endsWith("/") ? base : `${base}/`;
+  if (root !== "/" && pathname.startsWith(root)) {
+    return `/${pathname.slice(root.length)}`;
+  }
+  return pathname;
+}
+
 function safeRoot(workspace, input) {
   if (typeof input !== "string" || !input.trim()) throw new Error("Project path is required.");
   const clean = input.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
@@ -651,7 +660,7 @@ export function planProject(workspace, manifest, request) {
     ...(String(request.componentKind ?? "").trim() ? { componentKind: String(request.componentKind).trim() } : {}),
     ...(String(request.repository ?? "").trim() ? { repository: String(request.repository).trim() } : {}),
   };
-  const out = `${finalRoot}/portolan`;
+  const out = posix.join(finalRoot, "portolan");
   const detectionByPlugin = new Map(discovery.detections.map((item) => [item.plugin, item]));
   const hasDomainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin));
   const steps = plugins.map((plugin) => ({
@@ -671,7 +680,7 @@ export function planProject(workspace, manifest, request) {
   return { project, plugins, steps, source, discovery, fetch };
 }
 
-function manifestWithProject(manifest, plan, { isolated = false } = {}) {
+export function manifestWithProject(manifest, plan, { isolated = false } = {}) {
   const fetchIndex = (manifest.extract ?? []).findIndex((step) => step.plugin === "git");
   const extract = isolated ? [] : [...(manifest.extract ?? [])];
   if (plan.fetch) {
@@ -695,7 +704,7 @@ function manifestWithProject(manifest, plan, { isolated = false } = {}) {
   };
 }
 
-function writeManifest(path, manifest) {
+export function writeManifest(path, manifest) {
   const staging = mkdtempSync(join(dirname(path), ".portolan-manifest-"));
   const temp = join(staging, "portolan.json");
   try {
@@ -716,7 +725,7 @@ export function writeProject(workspace, request) {
   return plan;
 }
 
-function setup(workspace) {
+function setup(workspace, publicSetupFrom) {
   const manifestText = readFileSync(join(workspace, "portolan.json"), "utf8");
   let report;
   try { report = JSON.parse(readFileSync(join(workspace, ".portolan/build-report.json"), "utf8")); } catch {}
@@ -1085,19 +1094,23 @@ function startProjectTrial(workspace, request) {
   catch (cause) { rmSync(prepared.holder, { recursive: true, force: true }); throw cause; }
 }
 
-export function localApiPlugin(workspace = process.cwd()) {
+export function localApiPlugin(workspace = process.cwd(), publicSetupFrom) {
   return {
     name: "portolan-local-api",
     apply: "serve",
     configureServer(server) {
       server.middlewares.use(async (req, res, next) => {
         const url = new URL(req.url ?? "/", "http://localhost");
+        url.pathname = localApiPath(url.pathname, server.config.base);
         if (!url.pathname.startsWith(LOCAL_API_PREFIX)) return next();
         if (!localRequest(req)) return send(res, 403, { error: "The local API is available only through localhost." });
         try {
           if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/status`) {
             const active = [...jobs.values()].find((job) => job.status === "running");
-            return send(res, 200, { local: true, workspace: realpathSync(workspace), setup: setup(workspace), activeRun: active ? { id: active.id, mode: active.mode } : null });
+            return send(res, 200, { local: true, workspace: realpathSync(workspace), setup: setup(workspace, publicSetupFrom), activeRun: active ? { id: active.id, mode: active.mode } : null });
+          }
+          if (req.method === "GET" && url.pathname === `${LOCAL_API_PREFIX}/delivery-presets`) {
+            return send(res, 200, publicDeliveryPreset(planDeliveryPreset(workspace, url.searchParams.get("provider"))));
           }
           const eventMatch = url.pathname.match(/^\/__portolan\/runs\/([^/]+)\/events$/);
           if (req.method === "GET" && eventMatch) {
@@ -1113,6 +1126,9 @@ export function localApiPlugin(workspace = process.cwd()) {
             return send(res, 405, { error: "Use a local JSON request." });
           }
           const input = await body(req);
+          if (url.pathname === `${LOCAL_API_PREFIX}/delivery-presets/install`) {
+            return send(res, 201, installDeliveryPreset(workspace, input));
+          }
           if (url.pathname === `${LOCAL_API_PREFIX}/source`) return send(res, 200, readLocalSource(workspace, input.path));
           if (url.pathname === `${LOCAL_API_PREFIX}/repositories/credentials`) return send(res, 201, storeRepositoryCredential(input));
           if (url.pathname === `${LOCAL_API_PREFIX}/repositories/credentials/forget`) return send(res, 200, forgetRepositoryCredential(input));
@@ -1134,7 +1150,7 @@ export function localApiPlugin(workspace = process.cwd()) {
             const result = writeProject(workspace, trial.projectRequest);
             trial.applied = true;
             const generation = input.generate ? startJob(workspace, "write", trial) : null;
-            return send(res, 201, { ...result, setup: setup(workspace), run: generation ? { runId: generation.id, mode: generation.mode } : null });
+            return send(res, 201, { ...result, setup: setup(workspace, publicSetupFrom), run: generation ? { runId: generation.id, mode: generation.mode } : null });
           }
           const disposeTrialMatch = url.pathname.match(/^\/__portolan\/projects\/trials\/([^/]+)\/dispose$/);
           if (disposeTrialMatch) {
@@ -1150,7 +1166,7 @@ export function localApiPlugin(workspace = process.cwd()) {
           }
           if (url.pathname === `${LOCAL_API_PREFIX}/projects`) {
             const result = writeProject(workspace, input);
-            return send(res, 201, { ...result, setup: setup(workspace) });
+            return send(res, 201, { ...result, setup: setup(workspace, publicSetupFrom) });
           }
           if (url.pathname === `${LOCAL_API_PREFIX}/runs`) {
             if ([...jobs.values()].some((job) => job.status === "running")) return send(res, 409, { error: "A generator run is already active." });
@@ -1174,7 +1190,8 @@ export function localApiPlugin(workspace = process.cwd()) {
           }
           return send(res, 404, { error: "Local API route not found." });
         } catch (error) {
-          return send(res, error instanceof LocalApiError ? error.status : 400, {
+          const status = error instanceof LocalApiError ? error.status : Number.isInteger(error?.status) ? error.status : 400;
+          return send(res, status, {
             error: error instanceof Error ? error.message : String(error),
             ...(error instanceof LocalApiError ? {
               code: error.code,

package/scripts/local-api.test.mjs

@@ -1,11 +1,14 @@
-import { mkdtempSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { rmSync } from "node:fs";
 
-import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, forgetRepositoryCredential, inspectionRoot, planProject, readLocalSource, resolveRepositoryCommit, storeRepositoryCredential, summarizeProjectTrial, writeProject } from "./local-api.mjs";
+import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, forgetRepositoryCredential, inspectionRoot, localApiPath, planProject, readLocalSource, resolveRepositoryCommit, storeRepositoryCredential, summarizeProjectTrial, 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;
 const roots = [];
 afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
 
@@ -28,7 +31,87 @@ function workspace() {
   return root;
 }
 
+function gitWorkspace(provider = "github") {
+  const root = workspace();
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: root });
+  const remote = provider === "github" ? "git@github.com:acme/shop.git" : "https://gitlab.com/acme/shop.git";
+  execFileSync("git", ["remote", "add", "origin", remote], { cwd: root });
+  return root;
+}
+
+describe("local API base path", () => {
+  it("matches control-plane routes below the configured site base", () => {
+    expect(localApiPath("/portolan/__portolan/status", "/portolan/")).toBe("/__portolan/status");
+    expect(localApiPath("/portolan/__portolan/status", "/portolan")).toBe("/__portolan/status");
+    expect(localApiPath("/__portolan/status", "/portolan/")).toBe("/__portolan/status");
+    expect(localApiPath("/another/status", "/portolan/")).toBe("/another/status");
+  });
+});
+
 describe("local project setup", () => {
+  it("detects GitHub and GitLab remotes without treating arbitrary hosts as a forge", () => {
+    expect(providerFromRemote("git@github.com:acme/shop.git")).toBe("github");
+    expect(providerFromRemote("https://gitlab.example.com/acme/shop.git")).toBe("gitlab");
+    expect(providerFromRemote("ssh://git@example.com/acme/shop.git")).toBeNull();
+  });
+
+  it("previews and installs GitHub delivery workflows idempotently", () => {
+    const root = gitWorkspace("github");
+    const preview = planDeliveryPreset(root);
+    expect(preview).toMatchObject({ provider: "github", detectedProvider: "github", repository: "shop", defaultBranch: "main", status: "available" });
+    expect(preview.files.map((file) => [file.path, file.status])).toEqual([
+      [".github/workflows/portolan-check.yml", "added"],
+      [".github/workflows/portolan-pages.yml", "added"],
+    ]);
+    expect(publicDeliveryPreset(preview).files[0]).not.toHaveProperty("next");
+    const installed = installDeliveryPreset(root, { provider: "github", revision: preview.revision });
+    expect(installed.written).toHaveLength(2);
+    expect(installed.status).toBe("installed");
+    expect(readFileSync(join(root, ".github/workflows/portolan-check.yml"), "utf8")).toContain(`shortlink-org/portolan@${PACKAGE_VERSION}`);
+    expect(readFileSync(join(root, ".github/workflows/portolan-pages.yml"), "utf8")).toContain("base: /${{ github.event.repository.name }}/");
+    expect(installDeliveryPreset(root, { provider: "github", revision: installed.revision }).written).toEqual([]);
+  });
+
+  it("refuses to overwrite an unmanaged GitHub workflow or apply a stale preview", () => {
+    const root = gitWorkspace("github");
+    mkdirSync(join(root, ".github/workflows"), { recursive: true });
+    writeFileSync(join(root, ".github/workflows/portolan-check.yml"), "name: Mine\n");
+    const conflict = planDeliveryPreset(root, "github");
+    expect(conflict.status).toBe("conflict");
+    expect(() => installDeliveryPreset(root, { provider: "github", revision: conflict.revision })).toThrow(/was not created by Portolan/);
+    const clean = gitWorkspace("github");
+    const preview = planDeliveryPreset(clean, "github");
+    mkdirSync(join(clean, ".github/workflows"), { recursive: true });
+    writeFileSync(join(clean, ".github/workflows/portolan-check.yml"), "name: Arrived later\n");
+    expect(() => installDeliveryPreset(clean, { provider: "github", revision: preview.revision })).toThrow(/Preview it again/);
+  });
+
+  it("refuses a delivery target below a symlinked directory", () => {
+    const root = gitWorkspace("github");
+    const outside = mkdtempSync(join(tmpdir(), "portolan-preset-outside-"));
+    roots.push(outside);
+    symlinkSync(outside, join(root, ".github"), "dir");
+    const preview = planDeliveryPreset(root, "github");
+    expect(preview.status).toBe("conflict");
+    expect(() => installDeliveryPreset(root, { provider: "github", revision: preview.revision })).toThrow(/was not created by Portolan/);
+    expect(existsSync(join(outside, "workflows/portolan-check.yml"))).toBe(false);
+  });
+
+  it("adds and updates one managed GitLab region while preserving the pipeline", () => {
+    const root = gitWorkspace("gitlab");
+    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\":");
+    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(existsSync(join(root, ".github"))).toBe(false);
+  });
+
   it("classifies repository authentication, authorization, and timeout failures", () => {
     expect(classifyRepositoryFailure(new Error("fatal: Authentication failed"), "GitHub")).toMatchObject({
       code: "repository_auth_required", status: 401, retryable: true, provider: "GitHub",

package/scripts/manifest.mjs

@@ -13,7 +13,8 @@ import { normalize } from "node:path";
 
 import Ajv from "ajv/dist/2020.js";
 
-const SCHEMA = process.env.PORTOLAN_SCHEMA || "schema/portolan.schema.json";
+// Read when asked, not when loaded: the CLI sets PORTOLAN_SCHEMA after its imports.
+const schemaFile = () => process.env.PORTOLAN_SCHEMA || "schema/portolan.schema.json";
 
 /**
  * Reads the manifest and validates it.
@@ -28,7 +29,7 @@ export function loadManifest(path = "portolan.json") {
 
   let schema;
   try {
-    schema = JSON.parse(readFileSync(SCHEMA, "utf8"));
+    schema = JSON.parse(readFileSync(schemaFile(), "utf8"));
   } catch {
     return { manifest, problems: [] };
   }

package/scripts/package-smoke.mjs

@@ -2,18 +2,38 @@
 // This catches accidental cwd coupling before the same package reaches npm.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
-const cli = resolve(root, "cli/portolan.mjs");
 const fixture = mkdtempSync(resolve(tmpdir(), "portolan-package-smoke-"));
+const install = mkdtempSync(resolve(tmpdir(), "portolan-package-install-"));
 
 try {
+  // Exercise the tarball from a real node_modules path. Node permits native
+  // TypeScript stripping in a checkout but rejects it below node_modules, so
+  // invoking the source-tree CLI did not catch broken published entry graphs.
+  const tarball = execFileSync("npm", ["pack", "--ignore-scripts", "--pack-destination", install], {
+    cwd: root,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"],
+  }).trim().split("\n").at(-1);
+  const scope = resolve(install, "node_modules/@shortlink-org");
+  mkdirSync(scope, { recursive: true });
+  execFileSync("tar", ["-xzf", resolve(install, tarball), "-C", scope]);
+  const installed = resolve(scope, "portolan");
+  renameSync(resolve(scope, "package"), installed);
+  symlinkSync(resolve(root, "node_modules"), resolve(installed, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+  const cli = resolve(installed, "cli/portolan.mjs");
+
   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");
+  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");
   run("git", ["init", "--quiet"]);
   run("git", ["config", "user.email", "portolan@example.invalid"]);
   run("git", ["config", "user.name", "Portolan smoke test"]);
@@ -24,12 +44,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", "docs/README.md", "dist/index.html", "dist/404.html"]) {
+  for (const path of ["portolan/project.json", "portolan/domain.json", "docs/README.md", "dist/index.html", "dist/404.html"]) {
     if (!existsSync(resolve(fixture, path))) throw new Error(`smoke test did not write ${path}`);
   }
   console.log("package smoke: init, generate, check, and build passed outside the repository");
 } finally {
   rmSync(fixture, { recursive: true, force: true });
+  rmSync(install, { recursive: true, force: true });
 }
 
 function run(command, args) {

package/scripts/plugin-host.mjs

@@ -1,11 +1,12 @@
-// Runs a portolan generator plugin and returns what it wants written.
+// Runs a portolan plugin and returns what it wants written.
 //
-// A plugin never touches the tree (portolan.0001). It is handed a request on stdin and answers
-// with named files on stdout; writing them - and refusing a name that climbs
-// out of the output directory - is this file's job. That split is what lets the
-// same plugin run as a sandboxed wasm module with no directory preopened at
-// all, and it is why `--check` can compare a render against disk without the
-// plugin knowing there is a disk.
+// A plugin never writes the tree (portolan.0001). It is handed a request on
+// stdin and answers with named files on stdout; writing them - and refusing a
+// name that climbs out of the output directory - is this file's job. That split
+// is what lets a generator run as a wasm module with no directory preopened at
+// all, an extractor as one with only the workspace preopened (portolan.0006),
+// and it is why `--check` can compare a render against disk without the plugin
+// knowing there is a disk.
 
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -18,7 +19,7 @@ import {
 } from "node:fs";
 import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { Worker } from "node:worker_threads";
 
 const PORTOLAN_VERSION = "0.1.0";
@@ -35,9 +36,14 @@ const HOST_LIMITS = Object.freeze({
  *
  * @param {{name: string, wasm?: {url: string, sha256?: string}, process?: {command: string, args?: string[]}}} plugin
  * @param {unknown} request
+ * @param {{workspace?: string}} [access] `workspace` is the directory a wasm
+ *   module may read, preopened as `/` (portolan.0006). Left out, the module
+ *   gets no filesystem at all, which is what a generator and a describe
+ *   request should get. A process plugin is unaffected: it already has the
+ *   whole machine.
  * @returns {Promise<{files: {name: string, contents: string}[], describe?: object}>}
  */
-export async function runPlugin(plugin, request, requestedLimits = {}) {
+export async function runPlugin(plugin, request, requestedLimits = {}, access = {}) {
   const limits = lowerLimits(requestedLimits);
   let payload;
   try {
@@ -52,8 +58,13 @@ export async function runPlugin(plugin, request, requestedLimits = {}) {
     throw new Error(`plugin ${plugin.name}: request exceeds ${limits.requestBytes} bytes`);
   }
 
+  if (plugin.host) {
+    const { response, warnings } = await runHost(plugin, request);
+    return { ...validateResponse(plugin.name, response), warnings };
+  }
+
   const result = plugin.wasm
-    ? await runWasm(plugin, payload, limits)
+    ? await runWasm(plugin, payload, limits, access)
     : await runProcess(plugin, payload, limits);
   if (result.stderr) process.stderr.write(result.stderr);
 
@@ -69,6 +80,31 @@ export async function runPlugin(plugin, request, requestedLimits = {}) {
   return { ...validateResponse(plugin.name, response), warnings: warningsIn(result.stderr) };
 }
 
+// ---------------------------------------------------------------------------
+// host
+//
+// A plugin that needs what only the host has - a socket, a git binary - and
+// so runs inside it (portolan.0008). It speaks the same protocol as any other:
+// a request in, named files out, warnings beside them; the host writes and
+// validates exactly as it would for a module. Only the modules shipped here
+// can be named, so a manifest cannot point the host at arbitrary code.
+// ---------------------------------------------------------------------------
+
+const HOST_PLUGINS = new Set(["fetch-git", "fetch-bsr", "fetch-csr"]);
+
+async function runHost(plugin, request) {
+  const name = String(plugin.host);
+  if (!HOST_PLUGINS.has(name)) throw new Error(`plugin ${plugin.name}: the host has no plugin named ${JSON.stringify(name)}`);
+  const module = await import(`./host-plugins/${name}.mjs`);
+  if (request?.kind === "describe") return { response: { files: [], describe: module.describe() }, warnings: [] };
+  const { files, warnings = [] } = await module.run(request);
+  // Said the way a module says it on stderr, and kept the way warningsIn
+  // keeps it, so the build report reads the same whoever ran the step.
+  const lines = warnings.map((warning) => `${warning.ref ? `${warning.ref}: ` : ""}${warning.message}`);
+  for (const line of lines) process.stderr.write(`warning: ${line}\n`);
+  return { response: { files }, warnings: lines };
+}
+
 /**
  * The warnings a plugin wrote to stderr, one per `warning: ` line, without the
  * prefix.
@@ -164,6 +200,9 @@ function validateDescriptor(pluginName, descriptor) {
   if (!descriptor.options || typeof descriptor.options !== "object" || Array.isArray(descriptor.options)) {
     throw new Error(`plugin ${pluginName}: describe.options is invalid`);
   }
+  if (descriptor.needs !== undefined && (!Array.isArray(descriptor.needs) || descriptor.needs.some((need) => need !== "history"))) {
+    throw new Error(`plugin ${pluginName}: describe.needs may only name "history"`);
+  }
 }
 
 /**
@@ -191,12 +230,29 @@ export async function describePlugin(plugin) {
 //
 // Node's WASI takes file descriptors rather than pipes, so the request and the
 // response go through a scratch directory. That is the only place the sandbox
-// leaks, and it leaks into a temporary directory the plugin is not told about:
-// `preopens` stays empty, so the module cannot open a path even if it tries.
+// leaks, and it leaks into a temporary directory the plugin is not told about.
+// A generator gets no preopen at all. An extract or verify step gets the
+// workspace as `/` (portolan.0006) - read-write, because that is all WASI
+// offers, and nothing beyond it: no network, no environment, no way to spawn.
 // ---------------------------------------------------------------------------
 
-async function runWasm(plugin, payload, limits) {
+/** Compiled modules by digest: one module answers for every built-in plugin. */
+const compiled = new Map();
+
+async function compileWasm(plugin, limits) {
   const bytes = await loadWasm(plugin, limits);
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  let module = compiled.get(digest);
+  if (!module) {
+    module = await WebAssembly.compile(bytes);
+    compiled.set(digest, module);
+  }
+  return module;
+}
+
+async function runWasm(plugin, payload, limits, access) {
+  const module = await compileWasm(plugin, limits);
+  const workspace = access.workspace ? resolve(access.workspace) : "";
 
   const dir = await mkdtemp(join(tmpdir(), "portolan-plugin-"));
   const inPath = join(dir, "request.json");
@@ -209,7 +265,10 @@ async function runWasm(plugin, payload, limits) {
 
   try {
     const worker = new Worker(new URL("./plugin-wasm-worker.mjs", import.meta.url), {
-      workerData: { name: plugin.name, bytes, inPath, outPath, errPath },
+      workerData: { name: plugin.name, module, workspace, inPath, outPath, errPath },
+      // node:wasi announces itself as experimental on every import; once per
+      // step, that is sixty lines of noise in a generate.
+      execArgv: [...process.execArgv, "--disable-warning=ExperimentalWarning"],
     });
     const code = await new Promise((resolve, reject) => {
       let settled = false;
@@ -350,10 +409,10 @@ function verifyDigest(name, bytes, expected) {
 // ---------------------------------------------------------------------------
 // process
 //
-// The escape hatch for a generator that needs a toolchain - one reading Go
-// source has to run `go list`, which no wasm module can. It gets the same
-// protocol and none of the sandbox, which is the trade being made and the
-// reason it is not the default.
+// The escape hatch for a plugin that needs a toolchain or a socket - the Rust
+// extractor runs under Cargo, `adr` asks git for history, `fetch-git` clones.
+// It gets the same protocol and none of the sandbox, which is the trade being
+// made and the reason it is not the default.
 // ---------------------------------------------------------------------------
 
 function runProcess(plugin, payload, limits) {

package/scripts/plugin-host.test.mjs

@@ -1,7 +1,8 @@
 import { describe, expect, it } from "vitest";
 import { join } from "node:path";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 
 import { runPlugin, validateResponse, warningsIn } from "./plugin-host.mjs";
 
@@ -100,6 +101,54 @@ describe("wasm plugins", () => {
   });
 });
 
+// The built-in module, when `npm run plugins:build` has produced it. These
+// tests read a tree through it, which is what portolan.0006 allows an extract
+// step and denies everything else.
+const builtinModule = fileURLToPath(new URL("../plugins/portolan-go.wasm", import.meta.url));
+const describeBuiltin = existsSync(builtinModule) ? describe : describe.skip;
+
+describeBuiltin("wasm preopen", () => {
+  const plugin = { name: "project", wasm: { url: `file://${builtinModule}` } };
+  const request = {
+    portolanVersion: "0.1.0",
+    input: { root: ".", output: "portolan", commit: "abc1234", generatedAt: "2026-09-08T00:00:00Z" },
+    options: { group: "fixture", component: "fixture", componentName: "Fixture", out: "project.json" },
+  };
+  const workspace = () => {
+    const dir = mkdtempSync(join(tmpdir(), "portolan-preopen-"));
+    writeFileSync(join(dir, "README.md"), "# Fixture\n");
+    writeFileSync(join(dir, "go.mod"), "module example.com/fixture\n\ngo 1.24\n");
+    return dir;
+  };
+  const serviceIn = (result) => JSON.parse(result.files[0].contents).contexts[0].services[0];
+
+  it("reads the workspace an extract step is given", async () => {
+    const dir = workspace();
+    try {
+      const service = serviceIn(await runPlugin(plugin, request, {}, { workspace: dir }));
+      expect(service.readme).toBe("# Fixture");
+      expect(service.technologies).toContain("Go");
+      expect(service.repo).toBe("example.com/fixture");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("sees nothing when no workspace is given, as a generator or describe never should", async () => {
+    const dir = workspace();
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      const service = serviceIn(await runPlugin(plugin, request));
+      expect(service.readme).toBe("");
+      expect(service.technologies ?? []).not.toContain("Go");
+    } finally {
+      process.chdir(cwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("warningsIn", () => {
   it("reads only the warning lines, and nothing from an empty stderr", () => {
     expect(warningsIn("")).toEqual([]);

package/scripts/plugin-wasm-worker.mjs

@@ -11,13 +11,16 @@ async function run() {
       version: "preview1",
       args: [workerData.name],
       env: {},
-      preopens: {},
+      // 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 } : {},
       stdin,
       stdout,
       stderr,
     });
-    const module = await WebAssembly.compile(workerData.bytes);
-    const instance = await WebAssembly.instantiate(module, wasi.getImportObject());
+    // The module was compiled once by the host and shared; a 20 MB module
+    // compiled per step would cost more than the step.
+    const instance = await WebAssembly.instantiate(workerData.module, wasi.getImportObject());
     return wasi.start(instance);
   } finally {
     closeSync(stdin);

package/scripts/run-builtin.mjs

@@ -2,12 +2,12 @@
 
 // Process adapter for plugins bundled in the npm package. It keeps the
 // plugin's cwd in the user's workspace while resolving source and toolchain
-// files from the installation. Go plugins are compiled into the ignored
-// `.portolan/bin` directory because `go run` changes the child cwd to the
-// module containing the plugin.
+// files from the installation. The Go plugins no longer come through here:
+// they are one wasm module (portolan.0006), and the fetchers run inside the
+// host (portolan.0008).
 
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -25,27 +25,7 @@ if (!plugin?.process) {
 const command = plugin.process.command;
 const args = [...(plugin.process.args ?? [])];
 
-if (command === "go" && args[0] === "run" && args[1]) {
-  const binDir = resolve(workspace, ".portolan", "bin");
-  const suffix = process.platform === "win32" ? ".exe" : "";
-  const binary = resolve(binDir, `${name}${suffix}`);
-  mkdirSync(binDir, { recursive: true });
-
-  // Rebuilding is deliberately left to Go's build cache. Package upgrades can
-  // change shared extractor code without changing this plugin directory, so a
-  // timestamp shortcut here would make an old binary look current.
-  const built = spawnSync(
-    "go",
-    ["build", "-o", binary, args[1]],
-    { cwd: installRoot, stdio: ["ignore", "ignore", "inherit"] },
-  );
-  if (built.error) {
-    console.error(`portolan: could not start Go to build ${name}: ${built.error.message}`);
-    process.exit(1);
-  }
-  if (built.status !== 0 || !existsSync(binary)) process.exit(built.status ?? 1);
-  run(binary, []);
-} else if (command === "cargo" && existsSync(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"))) {
+if (command === "cargo" && existsSync(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"))) {
   run(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"), []);
 } else {
   if (command === "cargo") {

package/scripts/schema.mjs

@@ -226,12 +226,17 @@ function compose() {
         type: "object",
         additionalProperties: false,
         required: ["name"],
-        oneOf: [{ required: ["wasm"] }, { required: ["process"] }],
+        oneOf: [{ required: ["wasm"] }, { required: ["process"] }, { required: ["host"] }],
         properties: {
           name: {
             type: "string",
             description: "What the steps below call this plugin. It need not be the plugin's own name.",
           },
+          host: {
+            enum: ["fetch-git", "fetch-bsr", "fetch-csr"],
+            description:
+              "A plugin the host runs inside its own process, because it needs a socket or a git binary (portolan.0008). Only the ones shipped with Portolan can be named.",
+          },
           wasm: {
             type: "object",
             additionalProperties: false,