@shortlink-org/portolan 0.1.0

package/scripts/plugin-host.mjs

@@ -0,0 +1,419 @@
+// Runs a portolan generator 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.
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { Worker } from "node:worker_threads";
+
+const PORTOLAN_VERSION = "0.1.0";
+const HOST_LIMITS = Object.freeze({
+  requestBytes: 4 * 1024 * 1024,
+  responseBytes: 16 * 1024 * 1024,
+  stderrBytes: 1024 * 1024,
+  wasmBytes: 64 * 1024 * 1024,
+  timeoutMs: 120_000,
+});
+
+/**
+ * Runs one plugin.
+ *
+ * @param {{name: string, wasm?: {url: string, sha256?: string}, process?: {command: string, args?: string[]}}} plugin
+ * @param {unknown} request
+ * @returns {Promise<{files: {name: string, contents: string}[], describe?: object}>}
+ */
+export async function runPlugin(plugin, request, requestedLimits = {}) {
+  const limits = lowerLimits(requestedLimits);
+  let payload;
+  try {
+    payload = JSON.stringify(request);
+  } catch (cause) {
+    throw new Error(`plugin ${plugin.name}: request is not JSON-serializable: ${cause.message}`);
+  }
+  if (typeof payload !== "string") {
+    throw new Error(`plugin ${plugin.name}: request is not a JSON value`);
+  }
+  if (Buffer.byteLength(payload) > limits.requestBytes) {
+    throw new Error(`plugin ${plugin.name}: request exceeds ${limits.requestBytes} bytes`);
+  }
+
+  const result = plugin.wasm
+    ? await runWasm(plugin, payload, limits)
+    : await runProcess(plugin, payload, limits);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  let response;
+  try {
+    response = JSON.parse(result.stdout);
+  } catch (cause) {
+    throw new Error(
+      `plugin ${plugin.name} did not answer with JSON: ${cause.message}`,
+    );
+  }
+
+  return { ...validateResponse(plugin.name, response), warnings: warningsIn(result.stderr) };
+}
+
+/**
+ * The warnings a plugin wrote to stderr, one per `warning: ` line, without the
+ * prefix.
+ *
+ * They are not part of the response - the protocol has no advisory property a
+ * caller may accidentally ignore - but for a service whose tree the extractor
+ * only half understood they are the whole story: which packages were not read
+ * as aggregates, which record was left out and why. Printed once as they
+ * arrive, they scroll off; kept beside the step in the build report, they are
+ * the list of what to fix.
+ *
+ * @param {string} stderr
+ * @returns {string[]}
+ */
+export function warningsIn(stderr) {
+  const warnings = [];
+  for (const line of String(stderr ?? "").split(/\r?\n/)) {
+    const warning = line.startsWith("warning: ") ? line.slice("warning: ".length).trim() : "";
+    if (warning) warnings.push(warning);
+  }
+  return warnings;
+}
+
+function lowerLimits(requested) {
+  const limits = {};
+  for (const [name, maximum] of Object.entries(HOST_LIMITS)) {
+    const value = requested[name];
+    limits[name] = Number.isSafeInteger(value) && value > 0
+      ? Math.min(value, maximum)
+      : maximum;
+  }
+  return limits;
+}
+
+/** Reject malformed or over-broad responses before they reach the filesystem. */
+export function validateResponse(name, response) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new Error(`plugin ${name} answered with a non-object response`);
+  }
+  const unexpected = Object.keys(response).filter((key) => !["files", "describe"].includes(key));
+  if (unexpected.length > 0) {
+    throw new Error(`plugin ${name} answered with unsupported properties: ${unexpected.join(", ")}`);
+  }
+  if (!Array.isArray(response.files)) {
+    throw new Error(`plugin ${name} answered without a files list`);
+  }
+
+  const seen = new Set();
+  const files = response.files.map((file, index) => {
+    if (!file || typeof file !== "object" || Array.isArray(file)) {
+      throw new Error(`plugin ${name}: files[${index}] is not an object`);
+    }
+    const keys = Object.keys(file);
+    if (keys.some((key) => !["name", "contents"].includes(key))) {
+      throw new Error(`plugin ${name}: files[${index}] has unsupported properties`);
+    }
+    if (typeof file.name !== "string" || !safeFileName(file.name)) {
+      throw new Error(`plugin ${name}: files[${index}] has an unsafe name`);
+    }
+    if (typeof file.contents !== "string") {
+      throw new Error(`plugin ${name}: files[${index}].contents is not a string`);
+    }
+    if (seen.has(file.name)) {
+      throw new Error(`plugin ${name}: duplicate output file ${file.name}`);
+    }
+    seen.add(file.name);
+    return { name: file.name, contents: file.contents };
+  });
+
+  if (response.describe !== undefined) validateDescriptor(name, response.describe);
+  return { files, ...(response.describe === undefined ? {} : { describe: response.describe }) };
+}
+
+function safeFileName(name) {
+  if (!name || name.includes("\0") || isAbsolute(name) || /^[A-Za-z]:[\\/]/.test(name)) return false;
+  const parts = name.split(/[\\/]/);
+  return parts.every((part) => part !== "" && part !== "." && part !== "..");
+}
+
+function validateDescriptor(pluginName, descriptor) {
+  if (!descriptor || typeof descriptor !== "object" || Array.isArray(descriptor)) {
+    throw new Error(`plugin ${pluginName}: describe is not an object`);
+  }
+  if (typeof descriptor.name !== "string" || descriptor.name.length === 0) {
+    throw new Error(`plugin ${pluginName}: describe.name is missing`);
+  }
+  if (typeof descriptor.summary !== "string") {
+    throw new Error(`plugin ${pluginName}: describe.summary is missing`);
+  }
+  if (!Array.isArray(descriptor.phases) || descriptor.phases.some((phase) => !["extract", "verify", "generate"].includes(phase))) {
+    throw new Error(`plugin ${pluginName}: describe.phases is invalid`);
+  }
+  if (!descriptor.options || typeof descriptor.options !== "object" || Array.isArray(descriptor.options)) {
+    throw new Error(`plugin ${pluginName}: describe.options is invalid`);
+  }
+}
+
+/**
+ * Asks a plugin what it is and what it can be told.
+ *
+ * The answer is a descriptor with a JSON Schema for its options, which is what
+ * schema/portolan.schema.json is composed from. A plugin written against an
+ * older protocol answers without one; that comes back as null rather than as
+ * an error, because a manifest naming it is not wrong, it is just a manifest
+ * nothing can check.
+ *
+ * @param {{name: string, wasm?: {url: string, sha256?: string}, process?: {command: string, args?: string[]}}} plugin
+ */
+export async function describePlugin(plugin) {
+  const { describe } = await runPlugin(plugin, {
+    portolanVersion: PORTOLAN_VERSION,
+    kind: "describe",
+  });
+
+  return describe ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// wasm
+//
+// 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.
+// ---------------------------------------------------------------------------
+
+async function runWasm(plugin, payload, limits) {
+  const bytes = await loadWasm(plugin, limits);
+
+  const dir = await mkdtemp(join(tmpdir(), "portolan-plugin-"));
+  const inPath = join(dir, "request.json");
+  const outPath = join(dir, "response.json");
+  const errPath = join(dir, "stderr.txt");
+
+  writeFileSync(inPath, payload);
+  writeFileSync(outPath, "");
+  writeFileSync(errPath, "");
+
+  try {
+    const worker = new Worker(new URL("./plugin-wasm-worker.mjs", import.meta.url), {
+      workerData: { name: plugin.name, bytes, inPath, outPath, errPath },
+    });
+    const code = await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (cause, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        cause ? reject(cause) : resolve(value);
+      };
+      const timer = setTimeout(async () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        try {
+          await worker.terminate();
+        } finally {
+          reject(new Error(`plugin ${plugin.name}: timed out after ${limits.timeoutMs} ms`));
+        }
+      }, limits.timeoutMs);
+      worker.once("message", (message) => {
+        if (message.error) finish(new Error(`plugin ${plugin.name}: ${message.error}`));
+        else finish(null, message.code);
+      });
+      worker.once("error", (cause) => finish(new Error(`plugin ${plugin.name}: ${cause.message}`)));
+      worker.once("exit", (exitCode) => {
+        finish(new Error(`plugin ${plugin.name}: wasm worker exited ${exitCode} without a response`));
+      });
+    });
+
+    if (code !== 0 && code !== undefined) {
+      const message = readFileSync(errPath, "utf8").trim();
+      throw new Error(
+        `plugin ${plugin.name} exited ${code}${message ? `: ${message}` : ""}`,
+      );
+    }
+
+    if (statSync(outPath).size > limits.responseBytes) {
+      throw new Error(`plugin ${plugin.name}: response exceeds ${limits.responseBytes} bytes`);
+    }
+    if (statSync(errPath).size > limits.stderrBytes) {
+      throw new Error(`plugin ${plugin.name}: stderr exceeds ${limits.stderrBytes} bytes`);
+    }
+    const stdoutText = readFileSync(outPath, "utf8");
+    const stderrText = readFileSync(errPath, "utf8");
+    return { stdout: stdoutText, stderr: stderrText };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function loadWasm(plugin, limits) {
+  const { url, sha256 } = plugin.wasm;
+
+  if (url.startsWith("file://")) {
+    // Repo-relative, not a URL host. `file://plugins/x.wasm` means the file at
+    // plugins/x.wasm next to the manifest, which is the only thing anyone
+    // writing that line means.
+    const bytes = readFileSync(url.slice("file://".length));
+    // A checksum on a local file is optional: it protects a download, not a
+    // module that was just built from the source next to it.
+    if (sha256) verifyDigest(plugin.name, bytes, sha256);
+
+    verifyWasmSize(plugin.name, bytes, limits.wasmBytes);
+    return bytes;
+  }
+
+  if (!url.startsWith("https://")) {
+    throw new Error(
+      `plugin ${plugin.name}: wasm url must be https:// or file://, got ${url}`,
+    );
+  }
+  if (!sha256) {
+    throw new Error(
+      `plugin ${plugin.name}: a downloaded plugin must declare its sha256`,
+    );
+  }
+
+  const cacheDir = join("node_modules", ".cache", "portolan-plugins");
+  const cached = join(cacheDir, `${sha256}.wasm`);
+  try {
+    const bytes = readFileSync(cached);
+    verifyDigest(plugin.name, bytes, sha256);
+
+    verifyWasmSize(plugin.name, bytes, limits.wasmBytes);
+    return bytes;
+  } catch {
+    // Not cached yet, or cached wrongly. Either way, fetch it again.
+  }
+
+  const response = await fetch(url, {
+    redirect: "error",
+    signal: AbortSignal.timeout(limits.timeoutMs),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `plugin ${plugin.name}: ${url} answered ${response.status}`,
+    );
+  }
+
+  const declaredSize = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredSize) && declaredSize > limits.wasmBytes) {
+    throw new Error(`plugin ${plugin.name}: wasm module exceeds ${limits.wasmBytes} bytes`);
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.byteLength;
+    if (size > limits.wasmBytes) {
+      throw new Error(`plugin ${plugin.name}: wasm module exceeds ${limits.wasmBytes} bytes`);
+    }
+    chunks.push(Buffer.from(chunk));
+  }
+  const bytes = Buffer.concat(chunks);
+  verifyWasmSize(plugin.name, bytes, limits.wasmBytes);
+  verifyDigest(plugin.name, bytes, sha256);
+
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(cached, bytes);
+
+  return bytes;
+}
+
+function verifyWasmSize(name, bytes, maximum) {
+  if (bytes.byteLength > maximum) {
+    throw new Error(`plugin ${name}: wasm module exceeds ${maximum} bytes`);
+  }
+}
+
+function verifyDigest(name, bytes, expected) {
+  const actual = createHash("sha256").update(bytes).digest("hex");
+  if (actual !== expected) {
+    throw new Error(
+      `plugin ${name}: sha256 is ${actual}, the manifest says ${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.
+// ---------------------------------------------------------------------------
+
+function runProcess(plugin, payload, limits) {
+  const { command, args = [] } = plugin.process ?? {};
+  if (typeof command !== "string" || command.length === 0 || !Array.isArray(args) || args.some((arg) => typeof arg !== "string")) {
+    throw new Error(`plugin ${plugin.name}: process must declare command and string args`);
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+
+    const finish = (cause, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cause ? reject(cause) : resolve(value);
+    };
+    const stopForLimit = (stream, limit) => {
+      child.kill("SIGKILL");
+      finish(new Error(`plugin ${plugin.name}: ${stream} exceeds ${limit} bytes`));
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > limits.responseBytes) return stopForLimit("response", limits.responseBytes);
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes > limits.stderrBytes) return stopForLimit("stderr", limits.stderrBytes);
+      stderr.push(chunk);
+    });
+
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(new Error(`plugin ${plugin.name}: timed out after ${limits.timeoutMs} ms`));
+    }, limits.timeoutMs);
+
+    child.on("error", (cause) => finish(new Error(`plugin ${plugin.name} did not start: ${cause.message}`)));
+    child.on("close", (code) => {
+      const stdoutText = Buffer.concat(stdout).toString("utf8");
+      const stderrText = Buffer.concat(stderr).toString("utf8");
+      if (code !== 0) {
+        finish(
+          new Error(
+            `plugin ${plugin.name} exited ${code}${stderrText ? `: ${stderrText.trim()}` : ""}`,
+          ),
+        );
+
+        return;
+      }
+      finish(null, { stdout: stdoutText, stderr: stderrText });
+    });
+
+    child.stdin.end(payload);
+  });
+}

package/scripts/plugin-host.test.mjs

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import { runPlugin, validateResponse, warningsIn } from "./plugin-host.mjs";
+
+describe("plugin response validation", () => {
+  it("accepts only named text files", () => {
+    expect(validateResponse("fixture", { files: [{ name: "nested/result.json", contents: "{}" }] })).toEqual({
+      files: [{ name: "nested/result.json", contents: "{}" }],
+    });
+  });
+
+  it.each(["../secret", "/tmp/result", "C:\\tmp\\result", "a/../../secret", "./result"])(
+    "rejects unsafe output name %s",
+    (name) => {
+      expect(() => validateResponse("fixture", { files: [{ name, contents: "" }] })).toThrow("unsafe name");
+    },
+  );
+
+  it("rejects duplicate files and removed protocol properties", () => {
+    expect(() =>
+      validateResponse("fixture", {
+        files: [
+          { name: "same", contents: "one" },
+          { name: "same", contents: "two" },
+        ],
+      }),
+    ).toThrow("duplicate output file");
+    expect(() => validateResponse("fixture", { files: [], diagnostics: [] })).toThrow("unsupported properties");
+  });
+});
+
+describe("process plugins", () => {
+  it("passes arguments directly and parses a bounded response", async () => {
+    const script = `
+      process.stdin.resume();
+      process.stdin.on("end", () => process.stdout.write(JSON.stringify({files:[{name:process.argv[1],contents:"ok"}]})));
+    `;
+    const response = await runPlugin(
+      { name: "fixture", process: { command: process.execPath, args: ["-e", script, "name with spaces.txt"] } },
+      { portolanVersion: "0.1.0" },
+    );
+    expect(response.files).toEqual([{ name: "name with spaces.txt", contents: "ok" }]);
+    expect(response.warnings).toEqual([]);
+  });
+
+  it("keeps the warnings a plugin wrote to stderr beside its response", async () => {
+    const script = `
+      process.stderr.write("warning: shop.cart: internal/domain/errors has no struct called Errors\\n");
+      process.stderr.write("a note that is not a warning\\n");
+      process.stderr.write("warning: docs/adr/0004.md: left out of the fragment\\n");
+      process.stdin.resume();
+      process.stdin.on("end", () => process.stdout.write(JSON.stringify({files:[]})));
+    `;
+    const response = await runPlugin(
+      { name: "fixture", process: { command: process.execPath, args: ["-e", script] } },
+      { portolanVersion: "0.1.0" },
+    );
+    expect(response.warnings).toEqual([
+      "shop.cart: internal/domain/errors has no struct called Errors",
+      "docs/adr/0004.md: left out of the fragment",
+    ]);
+  });
+
+  it("kills a zip-bomb-like response before buffering it", async () => {
+    const script = `process.stdout.write("x".repeat(4096));`;
+    await expect(
+      runPlugin(
+        { name: "bomb", process: { command: process.execPath, args: ["-e", script] } },
+        {},
+        { responseBytes: 1024 },
+      ),
+    ).rejects.toThrow("response exceeds 1024 bytes");
+  });
+});
+
+describe("wasm plugins", () => {
+  it("terminates a module whose _start never returns", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "portolan-plugin-host-"));
+    const path = join(dir, "hang.wasm");
+    // (module (memory (export "memory") 1)
+    //   (func (export "_start") (loop br 0)))
+    writeFileSync(path, Buffer.from(
+      "0061736d01000000010401600000030201000503010001071302066d656d6f72790200065f737461727400000a0901070003400c000b0b",
+      "hex",
+    ));
+    try {
+      await expect(
+        runPlugin(
+          { name: "hang", wasm: { url: `file://${path}` } },
+          {},
+          { timeoutMs: 100 },
+        ),
+      ).rejects.toThrow("timed out after 100 ms");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("warningsIn", () => {
+  it("reads only the warning lines, and nothing from an empty stderr", () => {
+    expect(warningsIn("")).toEqual([]);
+    expect(warningsIn(undefined)).toEqual([]);
+    expect(warningsIn("warning: one\r\nnote\nwarning:   two  \nwarning: \n")).toEqual(["one", "two"]);
+  });
+});

package/scripts/plugin-wasm-worker.mjs

@@ -0,0 +1,34 @@
+import { closeSync, openSync } from "node:fs";
+import { parentPort, workerData } from "node:worker_threads";
+import { WASI } from "node:wasi";
+
+async function run() {
+  const stdin = openSync(workerData.inPath, "r");
+  const stdout = openSync(workerData.outPath, "w");
+  const stderr = openSync(workerData.errPath, "w");
+  try {
+    const wasi = new WASI({
+      version: "preview1",
+      args: [workerData.name],
+      env: {},
+      preopens: {},
+      stdin,
+      stdout,
+      stderr,
+    });
+    const module = await WebAssembly.compile(workerData.bytes);
+    const instance = await WebAssembly.instantiate(module, wasi.getImportObject());
+    return wasi.start(instance);
+  } finally {
+    closeSync(stdin);
+    closeSync(stdout);
+    closeSync(stderr);
+  }
+}
+
+try {
+  const code = await run();
+  parentPort.postMessage({ code });
+} catch (cause) {
+  parentPort.postMessage({ error: cause instanceof Error ? cause.message : String(cause) });
+}

package/scripts/run-builtin.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+// 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.
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const installRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const workspace = process.cwd();
+const name = process.argv[2];
+const manifest = JSON.parse(readFileSync(resolve(installRoot, "portolan.json"), "utf8"));
+const plugin = (manifest.plugins ?? []).find((candidate) => candidate.name === name);
+
+if (!plugin?.process) {
+  console.error(`portolan: built-in process plugin ${JSON.stringify(name)} does not exist`);
+  process.exit(2);
+}
+
+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"))) {
+  run(resolve(installRoot, "plugins/extract-rust/target/release/portolan-extract-rust"), []);
+} else {
+  if (command === "cargo") {
+    process.env.CARGO_TARGET_DIR = resolve(workspace, ".portolan", "bin", "cargo");
+  }
+  const resolved = args.map((arg, index) => {
+    if (!arg || arg.startsWith("-") || resolveArgument(command, index) === false) return arg;
+    return resolve(installRoot, arg);
+  });
+  run(command, resolved);
+}
+
+function resolveArgument(executable, index) {
+  if (["node", "python", "python3"].includes(executable)) return index === 0;
+  if (executable === "java") return index === 1;
+  if (executable === "cargo") return index === 3;
+  return false;
+}
+
+function run(executable, argv) {
+  const child = spawn(executable, argv, { cwd: workspace, stdio: "inherit" });
+  child.once("error", (cause) => {
+    console.error(`portolan: built-in ${name} did not start: ${cause.message}`);
+    process.exitCode = 1;
+  });
+  child.once("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}