@shortlink-org/portolan 0.1.0 → 0.2.0

package/scripts/local-api.test.mjs

@@ -1,10 +1,12 @@
-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 roots = [];
 afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
@@ -28,7 +30,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@0.2.0");
+    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,7 +2,7 @@
 // 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, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,6 +14,10 @@ const fixture = mkdtempSync(resolve(tmpdir(), "portolan-package-smoke-"));
 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");
+  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,7 +28,7 @@ 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");

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,