@ree-auz/nook 0.0.0-stage → 0.1.0

package/src/forge.mjs

@@ -0,0 +1,75 @@
+import spawn from "cross-spawn";
+import { which } from "./agents.mjs";
+
+const FAILED = new Set(["FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"]);
+const PENDING = new Set(["PENDING", "EXPECTED", "QUEUED", "IN_PROGRESS", "WAITING", "REQUESTED"]);
+
+/** One word for a PR's checks: passed, failed, running or no-ci. */
+export function ciState(checks = []) {
+  if (!checks.length) return "no-ci";
+  let running = false;
+  for (const check of checks) {
+    const result = check.conclusion || check.state || "";
+    if (FAILED.has(result)) return "failed";
+    if ((check.status && check.status !== "COMPLETED") || PENDING.has(result)) running = true;
+  }
+  return running ? "running" : "passed";
+}
+
+/** Newest PR per head branch, from `gh pr list --json` output (newest first). */
+export function parsePrList(text) {
+  const prs = new Map();
+  for (const pr of JSON.parse(text)) {
+    if (prs.has(pr.headRefName)) continue;
+    prs.set(pr.headRefName, {
+      number: pr.number,
+      state: pr.state.toLowerCase(),
+      head: pr.headRefOid,
+      url: pr.url,
+      ci: pr.state === "OPEN" ? ciState(pr.statusCheckRollup) : null,
+    });
+  }
+  return prs;
+}
+
+function explain(output) {
+  if (/auth login|not logged|authentication/i.test(output)) return "gh is not logged in (run gh auth login)";
+  if (/none of the git remotes|not a git repository|no git remotes/i.test(output)) return null;
+  return `gh failed: ${output.split(/\r?\n/)[0] || "no output"}`;
+}
+
+/**
+ * PRs of a repository from GitHub, keyed by branch, through the gh CLI.
+ * Resolves to { prs } or { error } (null error: the repository is not on GitHub).
+ */
+export function githubPrs(repoPath, env = process.env) {
+  const gh = which("gh", env);
+  if (!gh) return Promise.resolve({ error: "gh is not installed" });
+  const fields = "number,state,headRefName,headRefOid,url,statusCheckRollup";
+  return new Promise((done) => {
+    const child = spawn(gh, ["pr", "list", "--state", "all", "--limit", "200", "--json", fields], {
+      cwd: repoPath,
+      env: { ...env, GH_PROMPT_DISABLED: "1", NO_COLOR: "1" },
+      windowsHide: true,
+    });
+    let out = "";
+    let err = "";
+    const timer = setTimeout(() => child.kill(), 20000);
+    child.stdout.on("data", (chunk) => (out += chunk));
+    child.stderr.on("data", (chunk) => (err += chunk));
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      done({ error: `gh failed: ${error.message}` });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (signal) return done({ error: "gh timed out" });
+      if (code !== 0) return done({ error: explain(err.trim()) });
+      try {
+        done({ prs: parsePrList(out) });
+      } catch {
+        done({ error: "gh returned output nk could not read" });
+      }
+    });
+  });
+}

package/src/generate-hooks.mjs

@@ -0,0 +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;
+}

package/src/git.mjs

@@ -0,0 +1,86 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { NookError } from "./errors.mjs";
+
+export function gitTry(args, { cwd, input } = {}) {
+  const result = spawnSync("git", args, {
+    cwd,
+    input,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error) throw new NookError(`Cannot run git: ${result.error.message}`);
+  return { ok: result.status === 0, status: result.status, out: result.stdout.trimEnd(), err: result.stderr.trim() };
+}
+
+export function git(args, options) {
+  const result = gitTry(args, options);
+  if (!result.ok) throw new NookError(`git ${args.join(" ")} failed: ${result.err || `exit ${result.status}`}`);
+  return result.out;
+}
+
+/** Parses `git worktree list --porcelain`. The first entry is the main worktree. */
+export function listWorktrees(repo) {
+  const out = git(["worktree", "list", "--porcelain"], { cwd: repo });
+  const items = [];
+  let current = null;
+  for (const line of out.split(/\r?\n/)) {
+    if (line.startsWith("worktree ")) {
+      current = { path: resolve(line.slice(9)), branch: null, head: null, bare: false, locked: false };
+      items.push(current);
+    } else if (current && line.startsWith("HEAD ")) current.head = line.slice(5);
+    else if (current && line.startsWith("branch ")) current.branch = line.slice(7).replace(/^refs\/heads\//, "");
+    else if (current && line === "bare") current.bare = true;
+    else if (current && (line === "locked" || line.startsWith("locked "))) current.locked = true;
+  }
+  return items;
+}
+
+/** The main worktree of the repository that contains `cwd`. */
+export function mainWorktree(cwd) {
+  const inside = gitTry(["rev-parse", "--is-inside-work-tree"], { cwd });
+  if (!inside.ok || inside.out !== "true") throw new NookError("Not inside a git repository");
+  const [main] = listWorktrees(cwd);
+  if (!main || main.bare) throw new NookError("Bare repositories are not supported");
+  return main.path;
+}
+
+export function remoteUrl(repo, remote = "origin") {
+  const result = gitTry(["remote", "get-url", remote], { cwd: repo });
+  return result.ok ? result.out : "";
+}
+
+export function refExists(repo, ref) {
+  return gitTry(["show-ref", "--verify", "--quiet", ref], { cwd: repo }).ok;
+}
+
+export function defaultBranch(repo) {
+  const head = gitTry(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: repo });
+  if (head.ok && head.out) return head.out.replace(/^origin\//, "");
+  const current = gitTry(["symbolic-ref", "--short", "HEAD"], { cwd: repo });
+  if (current.ok && current.out) return current.out;
+  return "main";
+}
+
+/** The ref new workspaces start from: origin/<default> when it exists, else <default>. */
+export function baseRef(repo, branch) {
+  return refExists(repo, `refs/remotes/origin/${branch}`) ? `origin/${branch}` : branch;
+}
+
+export function statusLines(path) {
+  const out = git(["status", "--porcelain", "--untracked-files=all"], { cwd: path });
+  return out ? out.split(/\r?\n/) : [];
+}
+
+/** Which of `paths` (relative to cwd) git ignores. */
+export function ignoredPaths(cwd, paths) {
+  if (!paths.length) return new Set();
+  const result = gitTry(["check-ignore", "-z", "--stdin"], { cwd, input: paths.join("\0") + "\0" });
+  if (!result.ok && result.status !== 1) throw new NookError(`git check-ignore failed: ${result.err}`);
+  return new Set(result.out.split("\0").filter(Boolean));
+}
+
+export function isTracked(cwd, path) {
+  return gitTry(["ls-files", "--error-unmatch", "--", path], { cwd }).ok;
+}

package/src/home.mjs

@@ -0,0 +1,48 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, resolve, isAbsolute } from "node:path";
+
+/** Nook keeps everything in one folder. Only NOOK_HOME can move it. */
+export function nookHome(env = process.env) {
+  return resolve(env.NOOK_HOME || join(homedir(), "nook"));
+}
+
+export function homePaths(home) {
+  return {
+    home,
+    config: join(home, "config.toml"),
+    workspaces: join(home, "workspace"),
+    shared: join(home, "shared"),
+    backup: join(home, "backup"),
+    logs: join(home, "logs"),
+  };
+}
+
+/** Resolves symlinks (macOS /var -> /private/var) when the path exists. */
+export function realPath(path) {
+  const full = resolve(path);
+  try {
+    return realpathSync.native(full);
+  } catch {
+    return full;
+  }
+}
+
+function comparable(path, platform) {
+  const full = realPath(path);
+  return platform === "win32" ? full.toLowerCase() : full;
+}
+
+export function samePath(a, b, platform = process.platform) {
+  return comparable(a, platform) === comparable(b, platform);
+}
+
+/** True when `child` is `parent` or anywhere below it. */
+export function isInside(child, parent, platform = process.platform) {
+  const rel = relative(comparable(parent, platform), comparable(child, platform));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+export function exists(path) {
+  return existsSync(path);
+}