@ree-auz/nook 0.1.0 → 0.1.1

package/src/generate-hooks.mjs

@@ -1,367 +1,367 @@
-/**
- * Writes workspace hooks from a CI plan (see ci.mjs). Each hook is one
- * self-contained .mjs file, so it runs the same on Windows, macOS and Linux
- * and its whole content is what nk asks you to allow.
- */
-
-export const GENERATED_MARK = "// Generated by nk hooks write";
-
-const RUNTIME = String.raw`
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, delimiter, dirname, isAbsolute, join } from "node:path";
-import { parseEnv } from "node:util";
-
-// Only nk runs this, inside a workspace; never in the main checkout.
-if (!process.env.NOOK_PATH || !process.env.NOOK_WORKSPACE) {
-  console.error("Run by nk only (nk -b, nk <name>, nk rm, nk hooks test)");
-  process.exit(1);
-}
-const ws = process.env.NOOK_PATH;
-const firstPort = Number(process.env.NOOK_PORT);
-const slug = (text) => String(text).toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-const prefix = slug("nook-" + basename(process.env.NOOK_REPO ?? "repo") + "-" + process.env.NOOK_WORKSPACE);
-
-/**
- * Each CI service port, then each Compose port variable, gets one of this
- * workspace's ten ports in order: NOOK_PORT, NOOK_PORT + 1, ...
- */
-function portMap() {
-  const map = {};
-  let next = firstPort;
-  const take = (fallback) => (Number.isInteger(next) && next < firstPort + 10 ? next++ : fallback);
-  for (const service of plan.services) for (const port of service.ports) map["ci:" + service.name + ":" + port.host] = take(null);
-  for (const [name, fallback] of Object.entries(plan.compose?.ports ?? {})) map[name] = take(fallback);
-  for (const [service, entries] of Object.entries(plan.compose?.remap ?? {})) for (const entry of entries) map[service + ":" + entry.host] = take(null);
-  return map;
-}
-
-/**
- * Host ports this workspace moved → its own: CI's 5432, a Compose file's fixed
- * 5432:5432 or \${DB_PORT:-5432}, and the services' own ports (32768:3306 moves 3306 too). An address that still points at the old one
- * would reach the main checkout's service, maybe the real database.
- */
-function movedPorts(ports) {
-  const moved = {};
-  const add = (from, to) => {
-    if (to && String(from) !== String(to)) moved[from] ??= to;
-  };
-  for (const service of plan.services) for (const port of service.ports) add(port.host, ports["ci:" + service.name + ":" + port.host]);
-  for (const [service, entries] of Object.entries(plan.compose?.remap ?? {})) for (const entry of entries) add(entry.host, ports[service + ":" + entry.host]);
-  for (const [name, fallback] of Object.entries(plan.compose?.ports ?? {})) if (/^\d+$/.test(fallback)) add(fallback, ports[name]);
-  // A service's own port too, when no host port is already 3306: CI publishes mariadb's 3306 on 32768, but
-  // .env.example says DB_PORT=3306, the port a database on this machine usually takes (invoiceninja).
-  for (const service of plan.services) for (const port of service.ports) add(port.container, ports["ci:" + service.name + ":" + port.host]);
-  for (const [service, entries] of Object.entries(plan.compose?.remap ?? {})) for (const entry of entries) add(String(entry.target).split("/")[0], ports[service + ":" + entry.host]);
-  return moved;
-}
-
-/**
- * The Compose files for this workspace: the repository's, plus one that moves
- * fixed host ports (5432:5432) to this workspace's ports and gives fixed
- * container names (container_name: plane-redis) a workspace prefix, and takes
- * services off the host network. That one lives in
- * the worktree's git folder, so it is not a change in the workspace.
- */
-function composeFiles(ports) {
-  const files = plan.compose.files.map((file) => join(ws, file));
-  const remap = plan.compose.remap;
-  const named = plan.compose.named ?? [];
-  const ownNetwork = plan.compose.ownNetwork ?? [];
-  const fixed = plan.compose.fixed ?? { networks: [], volumes: [] };
-  if (!Object.keys(remap).length && !named.length && !ownNetwork.length && !fixed.networks.length && !fixed.volumes.length) return files;
-  const lines = ["# Written by nk: this workspace's own host ports, container names, networks and volumes."];
-  const services = [...new Set([...Object.keys(remap), ...named, ...ownNetwork])];
-  if (services.length) lines.push("services:");
-  for (const service of services) {
-    lines.push("  " + JSON.stringify(service) + ":");
-    if (named.includes(service)) lines.push("    container_name: " + JSON.stringify(prefix + "-" + service));
-    if (ownNetwork.includes(service)) lines.push("    network_mode: !reset null");
-    if (!remap[service]) continue;
-    lines.push("    ports: !override");
-    for (const entry of remap[service]) {
-      const port = ports[service + ":" + entry.host];
-      if (!port) {
-        console.error("No free port left for " + service + " " + entry.host + ": a workspace has ten");
-        process.exit(1);
-      }
-      lines.push("      - " + JSON.stringify("127.0.0.1:" + port + ":" + entry.target));
-    }
-  }
-  // A network or volume with a fixed name gets this workspace's own, as Compose would name it.
-  for (const kind of ["networks", "volumes"]) {
-    if (!fixed[kind].length) continue;
-    lines.push(kind + ":");
-    for (const key of fixed[kind]) lines.push("  " + JSON.stringify(key) + ":", "    name: " + JSON.stringify(prefix + "_" + key));
-  }
-  const git = spawnSync("git", ["rev-parse", "--absolute-git-dir"], { cwd: ws, encoding: "utf8" });
-  const file = join(git.status === 0 ? git.stdout.trim() : ws, "nook-compose.yaml");
-  writeFileSync(file, lines.join("\n") + "\n");
-  return [...files, file];
-}
-
-/** docker compose for this workspace's own project, never the main checkout's. */
-function compose(args, { check = true } = {}) {
-  const env = { ...process.env, COMPOSE_PROJECT_NAME: prefix, COMPOSE_FILE: composeFiles(portMap()).join(delimiter) };
-  const result = spawnSync("docker", ["compose", "--project-name", prefix, ...args], { cwd: ws, env, stdio: "inherit" });
-  if (check && result.status !== 0) {
-    console.error("Failed (exit " + result.status + "): docker compose " + args.join(" "));
-    process.exit(result.status || 1);
-  }
-}
-
-function startCompose() {
-  if (!plan.compose?.start.length) return;
-  const env = existsSync(join(ws, ".env")) ? parseEnv(readFileSync(join(ws, ".env"), "utf8")) : {};
-  const missing = plan.compose.required.filter((key) => !env[key] && !process.env[key]);
-  if (missing.length) {
-    console.error(plan.compose.file + " needs " + missing.join(", ") + " in .env. Set it once in the shared .env (nk copies it into every workspace), then create the workspace again.");
-    process.exit(1);
-  }
-  // A service that mounts a repository file not there yet (made by composer install and the like) would get a
-  // root-owned folder in its place: leave it for later.
-  const waiting = plan.compose.start.filter((name) => (plan.compose.mounts?.[name] ?? []).some((path) => !existsSync(join(ws, path))));
-  for (const name of waiting) {
-    const path = plan.compose.mounts[name].find((file) => !existsSync(join(ws, file)));
-    console.warn(name + " not started: it mounts " + path + ", which is not in the workspace yet (an install makes it). Start it afterwards with docker compose up -d " + name);
-  }
-  const start = plan.compose.start.filter((name) => !waiting.includes(name));
-  if (start.length) compose(["up", "--detach", "--wait", "--quiet-pull", ...start]);
-}
-
-/** localhost:5432 in a value becomes localhost:<this workspace's port>; so does a bare 5432 in a *_PORT key. */
-function withPorts(value, ports, key = "") {
-  const next = String(value).replace(/\b(localhost|127\.0\.0\.1):(\d+)\b/g, (all, host, port) => (ports[port] ? host + ":" + ports[port] : all));
-  const bare = /^(["']?)(\d+)\1$/.exec(next.trim());
-  return bare && /PORT$/i.test(key) && ports[bare[2]] ? next.replace(bare[2], String(ports[bare[2]])) : next;
-}
-
-// Shell built-ins (sh and cmd.exe) are not programs on PATH.
-const BUILTINS = new Set(["cd", "echo", "export", "set", "unset", "source", ".", "eval", "exec", "printf", "test", "[", "true", "false", "if", "for", "while", "case", "call", "rem", "copy", "del", "md", "mkdir", "type", "exit"]);
-const HINTS = { corepack: "Node 25 and later no longer include it; install it with npm install -g corepack" };
-
-/** The program a one-line command starts, when this machine does not have it. */
-function missingProgram(command) {
-  const word = command.trim().split(/\s+/)[0];
-  if (!word || /[\/\\=$%"'&|<>()]/.test(word) || BUILTINS.has(word.toLowerCase())) return null;
-  const found = process.platform === "win32" ? spawnSync("where", [word], { stdio: "ignore" }) : spawnSync("sh", ["-c", "command -v " + word], { stdio: "ignore" });
-  return found.status === 0 ? null : word;
-}
-
-function sh(command, { cwd = ws, env = {}, check = true } = {}) {
-  // Multi-line CI scripts are written for bash; on Windows, Git for Windows provides it.
-  const shell = process.platform === "win32" && command.includes("\n") ? "bash" : true;
-  // A missing program fails with the shell's message, which on Windows is in the system code page; say it plainly instead.
-  const missing = check && !command.includes("\n") && missingProgram(command);
-  if (missing) {
-    console.error(missing + " is not installed or not on PATH" + (HINTS[missing] ? "; " + HINTS[missing] : "") + ". Needed by: " + command);
-    process.exit(127);
-  }
-  // Any docker compose a step runs gets this workspace's own project, never the main checkout's.
-  const result = spawnSync(command, { cwd, env: { ...process.env, COMPOSE_PROJECT_NAME: prefix, ...env }, stdio: "inherit", shell });
-  if (check && result.status !== 0) {
-    console.error("Failed (exit " + result.status + "): " + command.split("\n")[0]);
-    process.exit(result.status || 1);
-  }
-  return result.status;
-}
-
-function docker(args, { quiet = false } = {}) {
-  const result = spawnSync("docker", args, { encoding: "utf8", stdio: quiet ? "pipe" : ["ignore", "pipe", "inherit"] });
-  return { ok: result.status === 0, out: (result.stdout ?? "").trim() };
-}
-
-function waitHealthy(name) {
-  for (let i = 0; i < 120; i++) {
-    const state = docker(["inspect", "-f", "{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}", name], { quiet: true }).out;
-    if (state === "healthy" || state === "running") return;
-    if (state === "unhealthy" || state === "exited") break;
-    spawnSync(process.execPath, ["-e", "setTimeout(() => {}, 1000)"]);
-  }
-  console.error("Service " + name + " did not become ready");
-  process.exit(1);
-}
-
-function startServices({ ports, reuse }) {
-  for (const service of plan.services) {
-    const name = prefix + "-" + slug(service.name);
-    if (reuse && docker(["container", "inspect", name], { quiet: true }).ok) {
-      docker(["start", name]);
-    } else {
-      const args = ["run", "-d", "--name", name, "--label", "dev.nook.workspace=" + ws];
-      for (const port of service.ports) {
-        const own = ports["ci:" + service.name + ":" + port.host];
-        if (!own) {
-          console.error("No free port left for " + service.name + " " + port.host + ": a workspace has ten");
-          process.exit(1);
-        }
-        args.push("-p", "127.0.0.1:" + own + ":" + port.container);
-      }
-      for (const [key, value] of Object.entries(service.env)) args.push("-e", key + "=" + value);
-      if (Array.isArray(service.options)) args.push(...service.options);
-      else if (service.options) args.push(...service.options.split(" "));
-      args.push(service.image);
-      if (!docker(args).ok) process.exit(1);
-    }
-    waitHealthy(name);
-    console.log(service.name + ": " + service.ports.map((port) => "localhost:" + ports["ci:" + service.name + ":" + port.host]).join(", "));
-  }
-}
-`;
-
-const sources = (plan) => [plan.job && `${plan.source} (job ${plan.job})`, plan.compose?.file].filter(Boolean).join(" and ");
-
-function header(plan, event, what) {
-  return `${GENERATED_MARK} from ${sources(plan)}.
-// ${what}
-// Edit freely. Running nk hooks write again replaces this file only while the first line is unchanged.
-`;
-}
-
-const planText = (plan) =>
-  `const plan = ${JSON.stringify({ tools: plan.tools, env: plan.env, services: plan.services, compose: plan.compose && { file: plan.compose.file, files: plan.compose.files, start: plan.compose.start, ports: plan.compose.ports, remap: plan.compose.remap, named: plan.compose.named ?? [], ownNetwork: plan.compose.ownNetwork ?? [], fixed: plan.compose.fixed ?? { networks: [], volumes: [] }, required: plan.compose.required, mounts: plan.compose.mounts ?? {} }, create: plan.create, remove: plan.remove }, null, 2)};\n`;
-
-export function createHook(plan) {
-  return `${header(plan, "create", "create: checks the tools CI installs, sets this workspace's ports in .env, starts its services, then runs the setup steps.")}${RUNTIME}
-${planText(plan)}
-const ports = portMap();
-
-for (const tool of plan.tools) {
-  // On Windows a shell finds pnpm.cmd and the like; it takes one command line, not arguments.
-  // go takes "version"; the others take --version.
-  const flag = tool.name === "go" ? "version" : "--version";
-  const result = process.platform === "win32" ? spawnSync(tool.name + " " + flag, { encoding: "utf8", shell: true }) : spawnSync(tool.name, [flag], { encoding: "utf8" });
-  if (result.status !== 0) {
-    if (!result.error && missingProgram(tool.name) === null) {
-      // The last line says why; the first is often progress, such as corepack downloading.
-      console.error(tool.name + " " + flag + " failed: " + (result.stderr || result.stdout).trim().split("\\n").pop());
-      process.exit(1);
-    }
-    console.error(tool.name + " is not installed" + (tool.version ? " (CI uses " + tool.version + ")" : "") + (HINTS[tool.name] ? "; " + HINTS[tool.name] : ""));
-    process.exit(1);
-  }
-  const found = (result.stdout || result.stderr).trim().split("\\n")[0];
-  if (tool.version && !found.includes(String(tool.version))) console.warn(tool.name + ": CI uses " + tool.version + ", this machine has " + found);
-}
-
-startServices({ ports, reuse: false });
-
-// .env: this workspace's Compose project and ports replace whatever the copied file says; CI's values fill gaps.
-const envFile = join(ws, ".env");
-const assignment = (key) => new RegExp("^\\\\s*(export\\\\s+)?" + key + "\\\\s*=");
-const own = plan.compose
-  ? {
-      COMPOSE_PROJECT_NAME: prefix,
-      // So a docker compose you run in the workspace uses its ports too.
-      ...((Object.keys(plan.compose.remap).length || plan.compose.named?.length || plan.compose.ownNetwork?.length || plan.compose.fixed?.networks.length || plan.compose.fixed?.volumes.length) && { COMPOSE_FILE: composeFiles(ports).join(delimiter) }),
-      ...Object.fromEntries(Object.keys(plan.compose.ports).map((key) => [key, ports[key]])),
-    }
-  : {};
-const moved = movedPorts(ports);
-const repointed = [];
-const repoint = (line) => {
-  const match = /^(\\s*(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*)(.*)$/.exec(line);
-  if (!match) return line;
-  const [, head, key, value] = match;
-  // localhost:5432 and 127.0.0.1:5432 in a URL; a bare 5432 only in a *_PORT key.
-  const next = withPorts(value, moved, key);
-  if (next === value) return line;
-  repointed.push(key);
-  return head + next;
-};
-// CI's values for its own services (the containers nk starts) carry those services' users and passwords:
-// they replace what a template says. Its other values only fill gaps.
-const ciPorts = new Set(plan.services.flatMap((service) => service.ports.map((port) => String(port.host))));
-const fromCi = Object.keys(plan.env).filter((key) => [...plan.env[key].matchAll(/\\b(?:localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0):(\\d+)\\b/g)].some((match) => ciPorts.has(match[1])));
-const original = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
-const replaced = fromCi.filter((key) => original.split(/\\r?\\n/).some((line) => assignment(key).test(line)));
-if (replaced.length) console.log("Set " + replaced.join(", ") + " in .env from CI, to match the services nk starts for this workspace");
-let text = original
-  .split(/\\r?\\n/)
-  .filter((line) => ![...Object.keys(own), ...fromCi].some((key) => assignment(key).test(line)))
-  .map(repoint)
-  .join("\\n")
-  .trimEnd();
-if (repointed.length) console.log("Pointed .env at this workspace's ports: " + repointed.splice(0).join(", "));
-const missing = Object.entries(plan.env).filter(([key]) => !text.split("\\n").some((line) => assignment(key).test(line)));
-if (Object.keys(own).length) text += (text ? "\\n\\n" : "") + "# This workspace's Compose project and ports (nk hooks write)\\n" + Object.entries(own).map(([key, value]) => key + "=" + value).join("\\n");
-if (missing.length) text += (text ? "\\n\\n" : "") + "# From CI (nk hooks write)\\n" + missing.map(([key, value]) => key + "=" + withPorts(value, moved, key)).join("\\n");
-// A file the repository commits now holds this workspace's ports: keep that change out of git status and commits.
-// A new file the repository does not ignore goes in git's local exclude list (never committed).
-const hideFromGit = (name) => {
-  if (spawnSync("git", ["ls-files", "--error-unmatch", name], { cwd: ws, stdio: "ignore" }).status !== 0) {
-    if (spawnSync("git", ["check-ignore", "-q", name], { cwd: ws, stdio: "ignore" }).status === 0) return;
-    const exclude = spawnSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: ws, encoding: "utf8" }).stdout.trim();
-    if (!exclude) return;
-    const path = isAbsolute(exclude) ? exclude : join(ws, exclude);
-    mkdirSync(dirname(path), { recursive: true });
-    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
-    writeFileSync(path, current + (current && !current.endsWith("\\n") ? "\\n" : "") + "/" + name + "\\n");
-    return;
-  }
-  spawnSync("git", ["update-index", "--skip-worktree", name], { cwd: ws, stdio: "ignore" });
-  console.log(name + " is committed in this repository; git now ignores this workspace's changes to it (git update-index --no-skip-worktree " + name + " to undo)");
-};
-if (text) {
-  writeFileSync(envFile, text + "\\n");
-  hideFromGit(".env");
-}
-// Files such as .env.development or .env.test override .env in many projects: point them at this workspace's ports too.
-// Templates (.env.example, .env.sample) are left as they are.
-for (const name of readdirSync(ws).filter((file) => /^\.env\..+/.test(file) && !/example|sample|template|dist/i.test(file)).sort()) {
-  const file = join(ws, name);
-  if (!statSync(file).isFile()) continue;
-  const before = readFileSync(file, "utf8");
-  const after = before.split(/(\\r?\\n)/).map((part) => (/^\\r?\\n$/.test(part) ? part : repoint(part))).join("");
-  if (after === before) continue;
-  writeFileSync(file, after);
-  console.log("Pointed " + name + " at this workspace's ports: " + repointed.splice(0).join(", "));
-  hideFromGit(name);
-}
-startCompose();
-
-const env = Object.fromEntries(Object.entries(plan.env).map(([key, value]) => [key, withPorts(value, moved, key)]));
-for (const step of plan.create) {
-  console.log("> " + step.name);
-  const stepEnv = Object.fromEntries(Object.entries(step.env ?? {}).map(([key, value]) => [key, withPorts(value, moved, key)]));
-  sh(step.run, { cwd: step.cwd ? join(ws, step.cwd) : ws, env: { ...env, ...stepEnv } });
-}
-`;
-}
-
-export function openHook(plan) {
-  return `${header(plan, "open", "open: starts this workspace's services again; safe to run any number of times.")}${RUNTIME}
-${planText(plan)}
-startServices({ ports: portMap(), reuse: true });
-startCompose();
-`;
-}
-
-export function removeHook(plan) {
-  return `${header(plan, "remove", "remove: runs the cleanup steps, then deletes this workspace's service containers, Compose project and their volumes.")}${RUNTIME}
-${planText(plan)}
-for (const step of plan.remove) {
-  console.log("> " + step.name);
-  const moved = movedPorts(portMap());
-  const env = Object.fromEntries(Object.entries({ ...plan.env, ...step.env }).map(([key, value]) => [key, withPorts(value, moved, key)]));
-  sh(step.run, { cwd: step.cwd ? join(ws, step.cwd) : ws, env, check: false });
-}
-for (const service of plan.services) {
-  const name = prefix + "-" + slug(service.name);
-  if (docker(["container", "inspect", name], { quiet: true }).ok) docker(["rm", "-f", "-v", name]);
-}
-// Everything this workspace's Compose project made: containers, networks, volumes.
-if (plan.compose) compose(["down", "--volumes", "--remove-orphans"], { check: false });
-`;
-}
-
-/** The hook files a plan needs: open only with services, remove only with something to clean. */
-export { sources };
-
-export function hookFiles(plan) {
-  const files = { "create.mjs": createHook(plan) };
-  const composed = plan.compose?.start.length > 0;
-  if (plan.services.length || composed) files["open.mjs"] = openHook(plan);
-  if (plan.services.length || plan.remove.length || plan.compose) files["remove.mjs"] = removeHook(plan);
-  return files;
-}
+/**
+ * Writes workspace hooks from a CI plan (see ci.mjs). Each hook is one
+ * self-contained .mjs file, so it runs the same on Windows, macOS and Linux
+ * and its whole content is what nk asks you to allow.
+ */
+
+export const GENERATED_MARK = "// Generated by nk hooks write";
+
+const RUNTIME = String.raw`
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, delimiter, dirname, isAbsolute, join } from "node:path";
+import { parseEnv } from "node:util";
+
+// Only nk runs this, inside a workspace; never in the main checkout.
+if (!process.env.NOOK_PATH || !process.env.NOOK_WORKSPACE) {
+  console.error("Run by nk only (nk -b, nk <name>, nk rm, nk hooks test)");
+  process.exit(1);
+}
+const ws = process.env.NOOK_PATH;
+const firstPort = Number(process.env.NOOK_PORT);
+const slug = (text) => String(text).toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
+const prefix = slug("nook-" + basename(process.env.NOOK_REPO ?? "repo") + "-" + process.env.NOOK_WORKSPACE);
+
+/**
+ * Each CI service port, then each Compose port variable, gets one of this
+ * workspace's ten ports in order: NOOK_PORT, NOOK_PORT + 1, ...
+ */
+function portMap() {
+  const map = {};
+  let next = firstPort;
+  const take = (fallback) => (Number.isInteger(next) && next < firstPort + 10 ? next++ : fallback);
+  for (const service of plan.services) for (const port of service.ports) map["ci:" + service.name + ":" + port.host] = take(null);
+  for (const [name, fallback] of Object.entries(plan.compose?.ports ?? {})) map[name] = take(fallback);
+  for (const [service, entries] of Object.entries(plan.compose?.remap ?? {})) for (const entry of entries) map[service + ":" + entry.host] = take(null);
+  return map;
+}
+
+/**
+ * Host ports this workspace moved → its own: CI's 5432, a Compose file's fixed
+ * 5432:5432 or \${DB_PORT:-5432}, and the services' own ports (32768:3306 moves 3306 too). An address that still points at the old one
+ * would reach the main checkout's service, maybe the real database.
+ */
+function movedPorts(ports) {
+  const moved = {};
+  const add = (from, to) => {
+    if (to && String(from) !== String(to)) moved[from] ??= to;
+  };
+  for (const service of plan.services) for (const port of service.ports) add(port.host, ports["ci:" + service.name + ":" + port.host]);
+  for (const [service, entries] of Object.entries(plan.compose?.remap ?? {})) for (const entry of entries) add(entry.host, ports[service + ":" + entry.host]);
+  for (const [name, fallback] of Object.entries(plan.compose?.ports ?? {})) if (/^\d+$/.test(fallback)) add(fallback, ports[name]);
+  // A service's own port too, when no host port is already 3306: CI publishes mariadb's 3306 on 32768, but
+  // .env.example says DB_PORT=3306, the port a database on this machine usually takes (invoiceninja).
+  for (const service of plan.services) for (const port of service.ports) add(port.container, ports["ci:" + service.name + ":" + port.host]);
+  for (const [service, entries] of Object.entries(plan.compose?.remap ?? {})) for (const entry of entries) add(String(entry.target).split("/")[0], ports[service + ":" + entry.host]);
+  return moved;
+}
+
+/**
+ * The Compose files for this workspace: the repository's, plus one that moves
+ * fixed host ports (5432:5432) to this workspace's ports and gives fixed
+ * container names (container_name: plane-redis) a workspace prefix, and takes
+ * services off the host network. That one lives in
+ * the worktree's git folder, so it is not a change in the workspace.
+ */
+function composeFiles(ports) {
+  const files = plan.compose.files.map((file) => join(ws, file));
+  const remap = plan.compose.remap;
+  const named = plan.compose.named ?? [];
+  const ownNetwork = plan.compose.ownNetwork ?? [];
+  const fixed = plan.compose.fixed ?? { networks: [], volumes: [] };
+  if (!Object.keys(remap).length && !named.length && !ownNetwork.length && !fixed.networks.length && !fixed.volumes.length) return files;
+  const lines = ["# Written by nk: this workspace's own host ports, container names, networks and volumes."];
+  const services = [...new Set([...Object.keys(remap), ...named, ...ownNetwork])];
+  if (services.length) lines.push("services:");
+  for (const service of services) {
+    lines.push("  " + JSON.stringify(service) + ":");
+    if (named.includes(service)) lines.push("    container_name: " + JSON.stringify(prefix + "-" + service));
+    if (ownNetwork.includes(service)) lines.push("    network_mode: !reset null");
+    if (!remap[service]) continue;
+    lines.push("    ports: !override");
+    for (const entry of remap[service]) {
+      const port = ports[service + ":" + entry.host];
+      if (!port) {
+        console.error("No free port left for " + service + " " + entry.host + ": a workspace has ten");
+        process.exit(1);
+      }
+      lines.push("      - " + JSON.stringify("127.0.0.1:" + port + ":" + entry.target));
+    }
+  }
+  // A network or volume with a fixed name gets this workspace's own, as Compose would name it.
+  for (const kind of ["networks", "volumes"]) {
+    if (!fixed[kind].length) continue;
+    lines.push(kind + ":");
+    for (const key of fixed[kind]) lines.push("  " + JSON.stringify(key) + ":", "    name: " + JSON.stringify(prefix + "_" + key));
+  }
+  const git = spawnSync("git", ["rev-parse", "--absolute-git-dir"], { cwd: ws, encoding: "utf8" });
+  const file = join(git.status === 0 ? git.stdout.trim() : ws, "nook-compose.yaml");
+  writeFileSync(file, lines.join("\n") + "\n");
+  return [...files, file];
+}
+
+/** docker compose for this workspace's own project, never the main checkout's. */
+function compose(args, { check = true } = {}) {
+  const env = { ...process.env, COMPOSE_PROJECT_NAME: prefix, COMPOSE_FILE: composeFiles(portMap()).join(delimiter) };
+  const result = spawnSync("docker", ["compose", "--project-name", prefix, ...args], { cwd: ws, env, stdio: "inherit" });
+  if (check && result.status !== 0) {
+    console.error("Failed (exit " + result.status + "): docker compose " + args.join(" "));
+    process.exit(result.status || 1);
+  }
+}
+
+function startCompose() {
+  if (!plan.compose?.start.length) return;
+  const env = existsSync(join(ws, ".env")) ? parseEnv(readFileSync(join(ws, ".env"), "utf8")) : {};
+  const missing = plan.compose.required.filter((key) => !env[key] && !process.env[key]);
+  if (missing.length) {
+    console.error(plan.compose.file + " needs " + missing.join(", ") + " in .env. Set it once in the shared .env (nk copies it into every workspace), then create the workspace again.");
+    process.exit(1);
+  }
+  // A service that mounts a repository file not there yet (made by composer install and the like) would get a
+  // root-owned folder in its place: leave it for later.
+  const waiting = plan.compose.start.filter((name) => (plan.compose.mounts?.[name] ?? []).some((path) => !existsSync(join(ws, path))));
+  for (const name of waiting) {
+    const path = plan.compose.mounts[name].find((file) => !existsSync(join(ws, file)));
+    console.warn(name + " not started: it mounts " + path + ", which is not in the workspace yet (an install makes it). Start it afterwards with docker compose up -d " + name);
+  }
+  const start = plan.compose.start.filter((name) => !waiting.includes(name));
+  if (start.length) compose(["up", "--detach", "--wait", "--quiet-pull", ...start]);
+}
+
+/** localhost:5432 in a value becomes localhost:<this workspace's port>; so does a bare 5432 in a *_PORT key. */
+function withPorts(value, ports, key = "") {
+  const next = String(value).replace(/\b(localhost|127\.0\.0\.1):(\d+)\b/g, (all, host, port) => (ports[port] ? host + ":" + ports[port] : all));
+  const bare = /^(["']?)(\d+)\1$/.exec(next.trim());
+  return bare && /PORT$/i.test(key) && ports[bare[2]] ? next.replace(bare[2], String(ports[bare[2]])) : next;
+}
+
+// Shell built-ins (sh and cmd.exe) are not programs on PATH.
+const BUILTINS = new Set(["cd", "echo", "export", "set", "unset", "source", ".", "eval", "exec", "printf", "test", "[", "true", "false", "if", "for", "while", "case", "call", "rem", "copy", "del", "md", "mkdir", "type", "exit"]);
+const HINTS = { corepack: "Node 25 and later no longer include it; install it with npm install -g corepack" };
+
+/** The program a one-line command starts, when this machine does not have it. */
+function missingProgram(command) {
+  const word = command.trim().split(/\s+/)[0];
+  if (!word || /[\/\\=$%"'&|<>()]/.test(word) || BUILTINS.has(word.toLowerCase())) return null;
+  const found = process.platform === "win32" ? spawnSync("where", [word], { stdio: "ignore" }) : spawnSync("sh", ["-c", "command -v " + word], { stdio: "ignore" });
+  return found.status === 0 ? null : word;
+}
+
+function sh(command, { cwd = ws, env = {}, check = true } = {}) {
+  // Multi-line CI scripts are written for bash; on Windows, Git for Windows provides it.
+  const shell = process.platform === "win32" && command.includes("\n") ? "bash" : true;
+  // A missing program fails with the shell's message, which on Windows is in the system code page; say it plainly instead.
+  const missing = check && !command.includes("\n") && missingProgram(command);
+  if (missing) {
+    console.error(missing + " is not installed or not on PATH" + (HINTS[missing] ? "; " + HINTS[missing] : "") + ". Needed by: " + command);
+    process.exit(127);
+  }
+  // Any docker compose a step runs gets this workspace's own project, never the main checkout's.
+  const result = spawnSync(command, { cwd, env: { ...process.env, COMPOSE_PROJECT_NAME: prefix, ...env }, stdio: "inherit", shell });
+  if (check && result.status !== 0) {
+    console.error("Failed (exit " + result.status + "): " + command.split("\n")[0]);
+    process.exit(result.status || 1);
+  }
+  return result.status;
+}
+
+function docker(args, { quiet = false } = {}) {
+  const result = spawnSync("docker", args, { encoding: "utf8", stdio: quiet ? "pipe" : ["ignore", "pipe", "inherit"] });
+  return { ok: result.status === 0, out: (result.stdout ?? "").trim() };
+}
+
+function waitHealthy(name) {
+  for (let i = 0; i < 120; i++) {
+    const state = docker(["inspect", "-f", "{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}", name], { quiet: true }).out;
+    if (state === "healthy" || state === "running") return;
+    if (state === "unhealthy" || state === "exited") break;
+    spawnSync(process.execPath, ["-e", "setTimeout(() => {}, 1000)"]);
+  }
+  console.error("Service " + name + " did not become ready");
+  process.exit(1);
+}
+
+function startServices({ ports, reuse }) {
+  for (const service of plan.services) {
+    const name = prefix + "-" + slug(service.name);
+    if (reuse && docker(["container", "inspect", name], { quiet: true }).ok) {
+      docker(["start", name]);
+    } else {
+      const args = ["run", "-d", "--name", name, "--label", "dev.nook.workspace=" + ws];
+      for (const port of service.ports) {
+        const own = ports["ci:" + service.name + ":" + port.host];
+        if (!own) {
+          console.error("No free port left for " + service.name + " " + port.host + ": a workspace has ten");
+          process.exit(1);
+        }
+        args.push("-p", "127.0.0.1:" + own + ":" + port.container);
+      }
+      for (const [key, value] of Object.entries(service.env)) args.push("-e", key + "=" + value);
+      if (Array.isArray(service.options)) args.push(...service.options);
+      else if (service.options) args.push(...service.options.split(" "));
+      args.push(service.image);
+      if (!docker(args).ok) process.exit(1);
+    }
+    waitHealthy(name);
+    console.log(service.name + ": " + service.ports.map((port) => "localhost:" + ports["ci:" + service.name + ":" + port.host]).join(", "));
+  }
+}
+`;
+
+const sources = (plan) => [plan.job && `${plan.source} (job ${plan.job})`, plan.compose?.file].filter(Boolean).join(" and ");
+
+function header(plan, event, what) {
+  return `${GENERATED_MARK} from ${sources(plan)}.
+// ${what}
+// Edit freely. Running nk hooks write again replaces this file only while the first line is unchanged.
+`;
+}
+
+const planText = (plan) =>
+  `const plan = ${JSON.stringify({ tools: plan.tools, env: plan.env, services: plan.services, compose: plan.compose && { file: plan.compose.file, files: plan.compose.files, start: plan.compose.start, ports: plan.compose.ports, remap: plan.compose.remap, named: plan.compose.named ?? [], ownNetwork: plan.compose.ownNetwork ?? [], fixed: plan.compose.fixed ?? { networks: [], volumes: [] }, required: plan.compose.required, mounts: plan.compose.mounts ?? {} }, create: plan.create, remove: plan.remove }, null, 2)};\n`;
+
+export function createHook(plan) {
+  return `${header(plan, "create", "create: checks the tools CI installs, sets this workspace's ports in .env, starts its services, then runs the setup steps.")}${RUNTIME}
+${planText(plan)}
+const ports = portMap();
+
+for (const tool of plan.tools) {
+  // On Windows a shell finds pnpm.cmd and the like; it takes one command line, not arguments.
+  // go takes "version"; the others take --version.
+  const flag = tool.name === "go" ? "version" : "--version";
+  const result = process.platform === "win32" ? spawnSync(tool.name + " " + flag, { encoding: "utf8", shell: true }) : spawnSync(tool.name, [flag], { encoding: "utf8" });
+  if (result.status !== 0) {
+    if (!result.error && missingProgram(tool.name) === null) {
+      // The last line says why; the first is often progress, such as corepack downloading.
+      console.error(tool.name + " " + flag + " failed: " + (result.stderr || result.stdout).trim().split("\\n").pop());
+      process.exit(1);
+    }
+    console.error(tool.name + " is not installed" + (tool.version ? " (CI uses " + tool.version + ")" : "") + (HINTS[tool.name] ? "; " + HINTS[tool.name] : ""));
+    process.exit(1);
+  }
+  const found = (result.stdout || result.stderr).trim().split("\\n")[0];
+  if (tool.version && !found.includes(String(tool.version))) console.warn(tool.name + ": CI uses " + tool.version + ", this machine has " + found);
+}
+
+startServices({ ports, reuse: false });
+
+// .env: this workspace's Compose project and ports replace whatever the copied file says; CI's values fill gaps.
+const envFile = join(ws, ".env");
+const assignment = (key) => new RegExp("^\\\\s*(export\\\\s+)?" + key + "\\\\s*=");
+const own = plan.compose
+  ? {
+      COMPOSE_PROJECT_NAME: prefix,
+      // So a docker compose you run in the workspace uses its ports too.
+      ...((Object.keys(plan.compose.remap).length || plan.compose.named?.length || plan.compose.ownNetwork?.length || plan.compose.fixed?.networks.length || plan.compose.fixed?.volumes.length) && { COMPOSE_FILE: composeFiles(ports).join(delimiter) }),
+      ...Object.fromEntries(Object.keys(plan.compose.ports).map((key) => [key, ports[key]])),
+    }
+  : {};
+const moved = movedPorts(ports);
+const repointed = [];
+const repoint = (line) => {
+  const match = /^(\\s*(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*)(.*)$/.exec(line);
+  if (!match) return line;
+  const [, head, key, value] = match;
+  // localhost:5432 and 127.0.0.1:5432 in a URL; a bare 5432 only in a *_PORT key.
+  const next = withPorts(value, moved, key);
+  if (next === value) return line;
+  repointed.push(key);
+  return head + next;
+};
+// CI's values for its own services (the containers nk starts) carry those services' users and passwords:
+// they replace what a template says. Its other values only fill gaps.
+const ciPorts = new Set(plan.services.flatMap((service) => service.ports.map((port) => String(port.host))));
+const fromCi = Object.keys(plan.env).filter((key) => [...plan.env[key].matchAll(/\\b(?:localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0):(\\d+)\\b/g)].some((match) => ciPorts.has(match[1])));
+const original = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
+const replaced = fromCi.filter((key) => original.split(/\\r?\\n/).some((line) => assignment(key).test(line)));
+if (replaced.length) console.log("Set " + replaced.join(", ") + " in .env from CI, to match the services nk starts for this workspace");
+let text = original
+  .split(/\\r?\\n/)
+  .filter((line) => ![...Object.keys(own), ...fromCi].some((key) => assignment(key).test(line)))
+  .map(repoint)
+  .join("\\n")
+  .trimEnd();
+if (repointed.length) console.log("Pointed .env at this workspace's ports: " + repointed.splice(0).join(", "));
+const missing = Object.entries(plan.env).filter(([key]) => !text.split("\\n").some((line) => assignment(key).test(line)));
+if (Object.keys(own).length) text += (text ? "\\n\\n" : "") + "# This workspace's Compose project and ports (nk hooks write)\\n" + Object.entries(own).map(([key, value]) => key + "=" + value).join("\\n");
+if (missing.length) text += (text ? "\\n\\n" : "") + "# From CI (nk hooks write)\\n" + missing.map(([key, value]) => key + "=" + withPorts(value, moved, key)).join("\\n");
+// A file the repository commits now holds this workspace's ports: keep that change out of git status and commits.
+// A new file the repository does not ignore goes in git's local exclude list (never committed).
+const hideFromGit = (name) => {
+  if (spawnSync("git", ["ls-files", "--error-unmatch", name], { cwd: ws, stdio: "ignore" }).status !== 0) {
+    if (spawnSync("git", ["check-ignore", "-q", name], { cwd: ws, stdio: "ignore" }).status === 0) return;
+    const exclude = spawnSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: ws, encoding: "utf8" }).stdout.trim();
+    if (!exclude) return;
+    const path = isAbsolute(exclude) ? exclude : join(ws, exclude);
+    mkdirSync(dirname(path), { recursive: true });
+    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+    writeFileSync(path, current + (current && !current.endsWith("\\n") ? "\\n" : "") + "/" + name + "\\n");
+    return;
+  }
+  spawnSync("git", ["update-index", "--skip-worktree", name], { cwd: ws, stdio: "ignore" });
+  console.log(name + " is committed in this repository; git now ignores this workspace's changes to it (git update-index --no-skip-worktree " + name + " to undo)");
+};
+if (text) {
+  writeFileSync(envFile, text + "\\n");
+  hideFromGit(".env");
+}
+// Files such as .env.development or .env.test override .env in many projects: point them at this workspace's ports too.
+// Templates (.env.example, .env.sample) are left as they are.
+for (const name of readdirSync(ws).filter((file) => /^\.env\..+/.test(file) && !/example|sample|template|dist/i.test(file)).sort()) {
+  const file = join(ws, name);
+  if (!statSync(file).isFile()) continue;
+  const before = readFileSync(file, "utf8");
+  const after = before.split(/(\\r?\\n)/).map((part) => (/^\\r?\\n$/.test(part) ? part : repoint(part))).join("");
+  if (after === before) continue;
+  writeFileSync(file, after);
+  console.log("Pointed " + name + " at this workspace's ports: " + repointed.splice(0).join(", "));
+  hideFromGit(name);
+}
+startCompose();
+
+const env = Object.fromEntries(Object.entries(plan.env).map(([key, value]) => [key, withPorts(value, moved, key)]));
+for (const step of plan.create) {
+  console.log("> " + step.name);
+  const stepEnv = Object.fromEntries(Object.entries(step.env ?? {}).map(([key, value]) => [key, withPorts(value, moved, key)]));
+  sh(step.run, { cwd: step.cwd ? join(ws, step.cwd) : ws, env: { ...env, ...stepEnv } });
+}
+`;
+}
+
+export function openHook(plan) {
+  return `${header(plan, "open", "open: starts this workspace's services again; safe to run any number of times.")}${RUNTIME}
+${planText(plan)}
+startServices({ ports: portMap(), reuse: true });
+startCompose();
+`;
+}
+
+export function removeHook(plan) {
+  return `${header(plan, "remove", "remove: runs the cleanup steps, then deletes this workspace's service containers, Compose project and their volumes.")}${RUNTIME}
+${planText(plan)}
+for (const step of plan.remove) {
+  console.log("> " + step.name);
+  const moved = movedPorts(portMap());
+  const env = Object.fromEntries(Object.entries({ ...plan.env, ...step.env }).map(([key, value]) => [key, withPorts(value, moved, key)]));
+  sh(step.run, { cwd: step.cwd ? join(ws, step.cwd) : ws, env, check: false });
+}
+for (const service of plan.services) {
+  const name = prefix + "-" + slug(service.name);
+  if (docker(["container", "inspect", name], { quiet: true }).ok) docker(["rm", "-f", "-v", name]);
+}
+// Everything this workspace's Compose project made: containers, networks, volumes.
+if (plan.compose) compose(["down", "--volumes", "--remove-orphans"], { check: false });
+`;
+}
+
+/** The hook files a plan needs: open only with services, remove only with something to clean. */
+export { sources };
+
+export function hookFiles(plan) {
+  const files = { "create.mjs": createHook(plan) };
+  const composed = plan.compose?.start.length > 0;
+  if (plan.services.length || composed) files["open.mjs"] = openHook(plan);
+  if (plan.services.length || plan.remove.length || plan.compose) files["remove.mjs"] = removeHook(plan);
+  return files;
+}