@ree-auz/nook 0.0.0-stage → 0.1.0

package/src/compose-plan.mjs

@@ -0,0 +1,228 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { exists } from "./home.mjs";
+
+/**
+ * Reads the repository's Docker Compose file for what a workspace needs from
+ * it: the services it uses as they are (a database, a queue), and the
+ * variables that choose host ports. Services the repository builds itself are
+ * the app; a workspace starts those when the developer wants.
+ */
+
+/** The files Compose itself looks for, in its order. */
+export const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"];
+
+export function composeFile(repoPath) {
+  return COMPOSE_FILES.find((file) => exists(join(repoPath, file))) ?? null;
+}
+
+/** The override file Compose merges in by default: compose.override.yaml next to compose.yaml, and so on. */
+export function overrideFile(repoPath, file = composeFile(repoPath)) {
+  if (!file) return null;
+  const stem = file.replace(/\.ya?ml$/, "");
+  const override = [`${stem}.override.yaml`, `${stem}.override.yml`].find((name) => exists(join(repoPath, name)));
+  if (override) return override;
+  // A base file that cannot run alone (a service with neither image nor build, as coolify's) is meant to be
+  // combined with its development file: docker compose -f docker-compose.yml -f docker-compose.dev.yml.
+  let services = {};
+  try {
+    services = parse(readFileSync(join(repoPath, file), "utf8"))?.services ?? {};
+  } catch {}
+  if (!Object.values(services).some((service) => service && typeof service === "object" && !service.image && !service.build && !service.extends)) return null;
+  return [".dev.yaml", ".dev.yml", ".development.yaml", ".development.yml"].map((end) => stem + end).find((name) => exists(join(repoPath, name))) ?? null;
+}
+
+/**
+ * Networks and volumes the files give a fixed name (networks: { coolify: { name: coolify } }): every
+ * workspace and the main checkout would share them, data too. external ones are shared on purpose.
+ */
+function fixedNames(repoPath, files) {
+  const found = { networks: [], volumes: [] };
+  for (const file of files)
+    for (const kind of ["networks", "volumes"])
+      for (const [key, value] of Object.entries(parse(readFileSync(join(repoPath, file), "utf8"))?.[kind] ?? {}))
+        if (value?.name && !value.external && !found[kind].includes(key)) found[kind].push(key);
+  return found;
+}
+
+/** Both files, as `docker compose` reads them with no -f: ports add up, other keys are replaced. */
+function readServices(repoPath, file, override) {
+  const services = { ...(parse(readFileSync(join(repoPath, file), "utf8"))?.services ?? {}) };
+  if (override)
+    for (const [name, extra] of Object.entries(parse(readFileSync(join(repoPath, override), "utf8"))?.services ?? {})) {
+      const base = services[name] ?? {};
+      services[name] = { ...base, ...extra, ports: [...(base.ports ?? []), ...(extra?.ports ?? [])] };
+    }
+  return services;
+}
+
+/** "${PORT:-3001}" → { name: "PORT", fallback: "3001" }; a literal port → null. */
+function portVariable(text) {
+  const match = /^\$\{(\w+)(?::?-([^}]*))?\}$/.exec(text.trim());
+  return match ? { name: match[1], fallback: match[2] ?? "" } : null;
+}
+
+/**
+ * A ports entry as { host, target }: "127.0.0.1:${P:-80}:80" → { host: "${P:-80}", target: "80" },
+ * "5432:5432/tcp" → { host: "5432", target: "5432/tcp" }. host is null when Compose picks one.
+ */
+function portEntry(entry) {
+  if (typeof entry === "object" && entry) {
+    const target = `${entry.target}${entry.protocol && entry.protocol !== "tcp" ? `/${entry.protocol}` : ""}`;
+    return { host: entry.published === undefined ? null : String(entry.published), target };
+  }
+  // Split on ":" outside ${...}.
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const char of String(entry)) {
+    if (char === "{") depth++;
+    if (char === "}") depth--;
+    if (char === ":" && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += char;
+  }
+  parts.push(current);
+  return { host: parts.length >= 2 ? parts.at(-2) : null, target: parts.at(-1) };
+}
+
+/**
+ * Images a project uses as they are, beside its own code: databases, caches,
+ * queues, search, object storage, mail catchers, cloud emulators. An image the
+ * project publishes itself (its app) is not one of them.
+ */
+const BACKING = /(^|[/:_-])(postgres|postgis|pgvector|timescale(db)?|mysql|mariadb|percona|mongo(db)?|redis|valkey|keydb|dragonfly(db)?|memcached|rabbitmq|kafka|redpanda|zookeeper|nats|elasticsearch|opensearch|meilisearch|typesense|minio|clickhouse(-server)?|cassandra|scylla|neo4j|couchdb|cockroach(db)?|mssql(-server)?|azure-sql-edge|localstack|dynamodb-local|azurite|mailpit|mailhog|maildev|smtp4dev|qdrant|weaviate|milvus|chroma|influxdb|questdb|surrealdb|etcd|pubsub-emulator|firebase-emulator|spanner-emulator|garage|seaweedfs|valkey-bundle)($|[/:._@-]|\d)/i;
+
+/** Variables a service needs set: ${NAME:?message} or ${NAME?message}. */
+function requiredVariables(service) {
+  return [...JSON.stringify(service).matchAll(/\$\{(\w+):?\?/g)].map((match) => match[1]);
+}
+
+/**
+ * { file, files, start, ports, remap, required, notStarted, untranslated } for the
+ * repository's Compose file and its override file, or null without one.
+ */
+const PORTS = 10;
+
+/**
+ * The repository paths a service mounts (./vendor/x.sh:/docker-entrypoint-initdb.d/x.sh). When one is
+ * missing, docker creates it as a root-owned folder, so the create hook waits for it instead.
+ */
+function bindMounts(service) {
+  const paths = [];
+  for (const volume of service.volumes ?? []) {
+    const source = typeof volume === "string" ? volume.split(":")[0] : volume?.type === "bind" ? volume.source : null;
+    if (typeof source === "string" && /^\.\.?\//.test(source) && !source.includes("$")) paths.push(source);
+  }
+  return paths;
+}
+
+/** startAny false: start nothing (CI has its own services). reserved: ports CI's services take first. */
+export function planCompose(repoPath, { start: startAny = true, reserved = 0 } = {}) {
+  const file = composeFile(repoPath);
+  if (!file) return null;
+  const untranslated = [];
+  const override = overrideFile(repoPath, file);
+  const where = override ? `${file} + ${override}` : file;
+  let services;
+  try {
+    services = readServices(repoPath, file, override);
+  } catch (error) {
+    untranslated.push({ step: where, why: `could not be read (${error.message.split("\n")[0]})` });
+    return { file: where, files: [file, override].filter(Boolean), start: [], ports: {}, remap: {}, required: [], notStarted: [], untranslated };
+  }
+  const ports = {};
+  const remap = {};
+  const start = [];
+  const notStarted = [];
+  const required = new Set();
+  const mounts = {};
+  const named = [];
+  const ownNetwork = [];
+  for (const [name, service] of Object.entries(services)) {
+    if (!service || typeof service !== "object") continue;
+    // A fixed container_name (plane-redis) would clash between workspaces, even for a service you start yourself: each gets its own.
+    if (service.container_name) named.push(name);
+    const fixed = [];
+    // On the host's network a service listens on the host's own ports, the main checkout's too (forem's
+    // postgres and redis): a workspace runs it on its project network instead, its ports moved to its own.
+    const hostNetwork = service.network_mode === "host";
+    for (const entry of service.ports ?? []) {
+      const { host, target } = portEntry(entry);
+      if (hostNetwork && (host === null || host === "")) fixed.push({ host: target.split("/")[0], target });
+      if (host === null || host === "") continue;
+      const variable = portVariable(host);
+      if (variable) ports[variable.name] ??= variable.fallback;
+      else fixed.push({ host, target });
+    }
+    if (service.build) notStarted.push({ name, why: "built from this repository" });
+    else if (service.profiles?.length) notStarted.push({ name, why: `only with the profile ${service.profiles.join(", ")}` });
+    else if (!service.image) notStarted.push({ name, why: "no image" });
+    else if (!BACKING.test(service.image)) notStarted.push({ name, why: `${service.image} is not a database or similar service` });
+    else if (!startAny) notStarted.push({ name, why: "CI starts its own services" });
+    else if (hostNetwork && !fixed.length) notStarted.push({ name, why: "uses the host's network and names no ports, so it would share the main checkout's" });
+    else {
+      start.push(name);
+      for (const variable of requiredVariables(service)) required.add(variable);
+      const files = bindMounts(service);
+      if (files.length) mounts[name] = files;
+      // A fixed host port (5432:5432) would be the same for every workspace, and the main checkout may hold
+      // it: each workspace moves it to one of its own ports.
+      if (fixed.length) remap[name] = fixed;
+      if (hostNetwork) ownNetwork.push(name);
+    }
+  }
+  // A workspace has ten ports: services that do not fit are left out, last first.
+  const used = (extra = 0) => Object.keys(ports).length + Object.values(remap).flat().length + extra;
+  while (start.length && used() > PORTS - reserved) {
+    const name = start.pop();
+    delete remap[name];
+    if (ownNetwork.includes(name)) ownNetwork.splice(ownNetwork.indexOf(name), 1);
+    notStarted.push({ name, why: "no port left of the workspace's ten" });
+    untranslated.push({ step: `${where} › ${name}`, why: "not started: the workspace's ten ports are taken by the other services" });
+  }
+  return { file: where, files: [file, override].filter(Boolean), start, ports, remap, required: [...required], mounts, named, ownNetwork, fixed: fixedNames(repoPath, [file, override].filter(Boolean)), notStarted, untranslated };
+}
+
+/**
+ * Where the Compose services a workspace starts are reached from this machine:
+ * { "postgres:5432": "127.0.0.1:5432" }. A template written for apps running
+ * inside Docker (DATABASE_URL=...@postgres:5432) is rewritten with it, since
+ * here the app runs on the machine; each workspace then moves the port to its own.
+ * start false: CI's own services are started instead, so there is nothing to point at.
+ */
+export function hostAddresses(repoPath, { start = true } = {}) {
+  const plan = planCompose(repoPath, { start });
+  if (!plan?.start.length) return {};
+  const services = readServices(repoPath, plan.files[0], plan.files[1]);
+  const addresses = {};
+  for (const name of plan.start)
+    for (const entry of services[name]?.ports ?? []) {
+      const { host, target } = portEntry(entry);
+      if (!host) continue;
+      const variable = portVariable(host);
+      const port = variable ? variable.fallback : host;
+      if (/^\d+$/.test(port)) addresses[`${name}:${target.split("/")[0]}`] = `127.0.0.1:${port}`;
+    }
+  return addresses;
+}
+
+/** Rewrites service addresses in an env file's values; returns { text, keys } with the keys it changed. */
+export function pointAtHost(text, addresses) {
+  const keys = [];
+  const lines = text.split(/(\r?\n)/).map((line) => {
+    const match = /^(\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=)(.*)$/.exec(line);
+    if (!match) return line;
+    let value = match[3];
+    for (const [from, to] of Object.entries(addresses)) {
+      const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      value = value.replace(new RegExp(`(^|[\\s"'=/@,])${escaped}(?!\\d)`, "g"), `$1${to}`);
+    }
+    if (value === match[3]) return line;
+    keys.push(match[2]);
+    return match[1] + value;
+  });
+  return { text: lines.join(""), keys };
+}

package/src/compose.mjs

@@ -0,0 +1,123 @@
+import { homedir } from "node:os";
+import spawn from "cross-spawn";
+import { isInside } from "./home.mjs";
+
+/**
+ * Docker Compose labels every container it starts with its project and the
+ * folder it ran in (com.docker.compose.project.working_dir), and labels the
+ * volumes, networks and built images of that project too. So nk can tell what
+ * a workspace started without the repository writing a remove hook.
+ */
+const PROJECT = "com.docker.compose.project";
+const WORKING_DIR = "com.docker.compose.project.working_dir";
+
+export function dockerCli(args) {
+  // Run from the home folder, so Docker never holds a workspace folder open while it is being deleted.
+  const result = spawn.sync("docker", args, { cwd: homedir(), encoding: "utf8", timeout: 60000, windowsHide: true });
+  if (result.error) return { ok: false, out: "", err: result.error.code === "ENOENT" ? "not installed" : result.error.message };
+  return { ok: result.status === 0, out: result.stdout ?? "", err: (result.stderr ?? "").trim() };
+}
+
+const rows = (text) => text.split(/\r?\n/).filter(Boolean);
+
+/**
+ * Compose projects started inside `path`. A project that also has containers
+ * started from another folder is reported in `shared` and never removed: it
+ * may be the main checkout's (production) project under the same name.
+ */
+export function findComposeProjects(path, docker = dockerCli) {
+  const listed = docker(["container", "ls", "-a", "--filter", `label=${WORKING_DIR}`, "--format", `{{.ID}}\t{{.Label "${PROJECT}"}}\t{{.Label "${WORKING_DIR}"}}`]);
+  if (!listed.ok) return { unavailable: listed.err || "docker is not running", projects: [], shared: [] };
+  const byProject = new Map();
+  for (const row of rows(listed.out)) {
+    const [id, project, dir] = row.split("\t");
+    if (!project) continue;
+    const entry = byProject.get(project) ?? { inside: [], outside: [] };
+    (dir && isInside(dir, path) ? entry.inside : entry.outside).push(id);
+    byProject.set(project, entry);
+  }
+  const projects = [];
+  const shared = [];
+  for (const [name, { inside, outside }] of byProject) {
+    if (!inside.length) continue;
+    if (outside.length) {
+      shared.push(name);
+      continue;
+    }
+    const label = `label=${PROJECT}=${name}`;
+    const ids = (kind) => {
+      const result = docker([kind, "ls", "-q", "--filter", label]);
+      return result.ok ? [...new Set(rows(result.out))] : [];
+    };
+    projects.push({ name, containers: inside, volumes: ids("volume"), networks: ids("network"), images: ids("image") });
+  }
+  return { projects, shared };
+}
+
+const count = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+export function describeProject(project) {
+  const parts = [count(project.containers.length, "container")];
+  if (project.volumes.length) parts.push(count(project.volumes.length, "volume"));
+  if (project.networks.length) parts.push(count(project.networks.length, "network"));
+  if (project.images.length) parts.push(count(project.images.length, "built image"));
+  return `Compose project ${project.name}: ${parts.join(", ")}`;
+}
+
+/** Removes containers (with their anonymous volumes), then volumes, networks and built images. */
+export function removeComposeProject(project, docker = dockerCli) {
+  const steps = [
+    project.containers.length && ["container", "rm", "-f", "-v", ...project.containers],
+    project.volumes.length && ["volume", "rm", "-f", ...project.volumes],
+    project.networks.length && ["network", "rm", ...project.networks],
+    project.images.length && ["image", "rm", "-f", ...project.images],
+  ].filter(Boolean);
+  for (const args of steps) {
+    const result = docker(args);
+    if (!result.ok) throw new Error(`docker ${args.slice(0, 2).join(" ")} failed: ${result.err}`);
+  }
+}
+
+/** Compose projects started somewhere under `root` whose folder is not one of `live` any more. */
+export function leftoverComposeProjects(root, live, docker = dockerCli) {
+  const listed = docker(["container", "ls", "-a", "--filter", `label=${WORKING_DIR}`, "--format", `{{.Label "${PROJECT}"}}\t{{.Label "${WORKING_DIR}"}}`]);
+  if (!listed.ok) return [];
+  const found = new Map();
+  for (const row of rows(listed.out)) {
+    const [project, dir] = row.split("\t");
+    if (project && dir && isInside(dir, root) && !live.some((path) => isInside(dir, path))) found.set(project, dir);
+  }
+  return [...found].map(([name, dir]) => ({ name, dir }));
+}
+
+/**
+ * Every container, volume and network, and every image Compose built: what
+ * `nk hooks test` compares before and after the hooks. Null without Docker.
+ */
+export function dockerSnapshot(docker = dockerCli) {
+  const list = (args) => {
+    const result = docker(args);
+    if (!result.ok) return null;
+    return rows(result.out).map((row) => {
+      const [id, name] = row.split("\t");
+      return { id, name: name || id };
+    });
+  };
+  const snapshot = {
+    container: list(["container", "ls", "-a", "--format", "{{.ID}}\t{{.Names}}"]),
+    volume: list(["volume", "ls", "--format", "{{.Name}}"]),
+    network: list(["network", "ls", "--format", "{{.ID}}\t{{.Name}}"]),
+    image: list(["image", "ls", "--filter", `label=${PROJECT}`, "--format", "{{.ID}}\t{{.Repository}}:{{.Tag}}"]),
+  };
+  return Object.values(snapshot).some((items) => items === null) ? null : snapshot;
+}
+
+/** What `after` has that `before` did not: [{ kind, id, name }]. */
+export function snapshotDiff(before, after) {
+  const added = [];
+  for (const kind of Object.keys(after)) {
+    const known = new Set(before[kind].map((item) => item.id));
+    for (const item of after[kind]) if (!known.has(item.id)) added.push({ kind, ...item });
+  }
+  return added;
+}

package/src/config.mjs

@@ -0,0 +1,115 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse, stringify } from "smol-toml";
+import { NookError } from "./errors.mjs";
+
+export function emptyConfig() {
+  return { agents: {}, repos: {} };
+}
+
+export function loadConfig(file) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return emptyConfig();
+    throw error;
+  }
+  let data;
+  try {
+    data = parse(text);
+  } catch (error) {
+    throw new NookError(`Cannot read ${file}: ${error.message}`);
+  }
+  data.agents ??= {};
+  data.repos ??= {};
+  for (const repo of Object.values(data.repos)) {
+    repo.workspaces ??= {};
+    repo.hooks ??= {};
+  }
+  return data;
+}
+
+export function saveConfig(file, config) {
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, stringify(config) + "\n");
+  renameSync(temp, file);
+}
+
+// Several nk may run at once (an agent per Linear issue): config.toml changes under a lock, so no
+// two get the same ports and none writes over what another just recorded.
+const STALE_MS = 30_000;
+const WAIT_MS = 15_000;
+
+function tryLock(lock) {
+  try {
+    mkdirSync(lock);
+    return true;
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    try {
+      // A lock left by an nk that was killed: no update takes this long.
+      if (Date.now() - statSync(lock).mtimeMs > STALE_MS) rmSync(lock, { recursive: true, force: true });
+    } catch {}
+    return false;
+  }
+}
+
+const busy = (lock) => new NookError(`Another nk is updating its config and did not finish. If no nk is running, delete ${lock}`);
+
+/** Runs fn while holding the lock on `file`. */
+export function withLockSync(file, fn) {
+  const lock = `${file}.lock`;
+  mkdirSync(dirname(file), { recursive: true });
+  const until = Date.now() + WAIT_MS;
+  while (!tryLock(lock)) {
+    if (Date.now() > until) throw busy(lock);
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+  }
+  try {
+    return fn();
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+/** Async form, for updates that wait on something (checking that ports are free). */
+export async function withLock(file, fn) {
+  const lock = `${file}.lock`;
+  mkdirSync(dirname(file), { recursive: true });
+  const until = Date.now() + WAIT_MS;
+  while (!tryLock(lock)) {
+    if (Date.now() > until) throw busy(lock);
+    await new Promise((done) => setTimeout(done, 50));
+  }
+  try {
+    return await fn();
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Applies to `target` what changed from `base` to `current`: keys added, removed or changed, at any depth. */
+export function applyChanges(base, current, target) {
+  for (const key of new Set([...Object.keys(base), ...Object.keys(current)])) {
+    if (!(key in current)) delete target[key];
+    else if (!(key in base)) target[key] = structuredClone(current[key]);
+    else if (isObject(base[key]) && isObject(current[key]) && isObject(target[key])) applyChanges(base[key], current[key], target[key]);
+    else if (!same(base[key], current[key])) target[key] = structuredClone(current[key]);
+  }
+  return target;
+}
+
+/** Makes `target` equal to `source`, keeping the objects `target` already has, so references to them stay live. */
+export function syncInPlace(target, source) {
+  for (const key of Object.keys(target)) if (!(key in source)) delete target[key];
+  for (const [key, value] of Object.entries(source)) {
+    if (isObject(target[key]) && isObject(value)) syncInPlace(target[key], value);
+    else target[key] = structuredClone(value);
+  }
+  return target;
+}

package/src/context.mjs

@@ -0,0 +1,189 @@
+import { existsSync, renameSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { applyChanges, loadConfig, saveConfig, syncInPlace, withLock, withLockSync } from "./config.mjs";
+import { NookError } from "./errors.mjs";
+import { homePaths, isInside, nookHome, samePath } from "./home.mjs";
+import { normalizeName } from "./names.mjs";
+import { gitTry, listWorktrees } from "./git.mjs";
+import { line, useColor } from "./ui.mjs";
+
+/** Shared state for one command run. */
+export function createContext({ env = process.env, cwd = process.cwd(), out = process.stdout, err = process.stderr } = {}) {
+  const paths = homePaths(nookHome(env));
+  const config = loadConfig(paths.config);
+  const moveFailed = moveOldWorkspaceFolder(paths, config);
+  // What this run changed is config minus base; on save it goes onto what is on disk now,
+  // so changes another nk made meanwhile are kept.
+  let base = structuredClone(config);
+  const merge = () => {
+    const disk = applyChanges(base, config, loadConfig(paths.config));
+    saveConfig(paths.config, disk);
+    syncInPlace(config, disk);
+    base = structuredClone(config);
+  };
+  const color = useColor(err, env);
+  const say = (kind) => (text) => err.write(`${line(kind, text, color)}\n`);
+  if (moveFailed)
+    say("warn")(`Could not rename ${paths.workspaces} to ${join(paths.home, "workspace")} (${moveFailed}); still using the old folder. Close programs open in it (terminals, editors, dev servers) and run nk again.`);
+  return {
+    env,
+    cwd,
+    paths,
+    config,
+    out,
+    err,
+    save() {
+      withLockSync(paths.config, merge);
+    },
+    /**
+     * Brings config up to date with disk, runs fn on it and saves, all under the lock: for choices
+     * that must not clash with another nk running at the same time, such as a workspace's ports.
+     */
+    async update(fn) {
+      return withLock(paths.config, async () => {
+        merge();
+        const result = await fn(config);
+        merge();
+        return result;
+      });
+    },
+    print(text = "") {
+      out.write(`${text}\n`);
+    },
+    note(text = "") {
+      err.write(`${text}\n`);
+    },
+    step: say("step"),
+    ok: say("ok"),
+    warn: say("warn"),
+    info: say("info"),
+    item: say("item"),
+  };
+}
+
+/**
+ * Before 0.1 the folder was called "workspaces". Renames it once and tells git
+ * where the workspaces went. When it cannot (a file is open on Windows), keeps
+ * using the old folder and returns why.
+ */
+function moveOldWorkspaceFolder(paths, config) {
+  const old = join(paths.home, "workspaces");
+  if (!existsSync(old) || existsSync(paths.workspaces)) return;
+  const moves = [];
+  for (const repo of Object.values(config.repos ?? {}))
+    for (const ws of Object.values(repo.workspaces ?? {}))
+      if (isInside(ws.path, old)) moves.push({ repo, ws, path: join(paths.workspaces, relative(old, ws.path)) });
+  try {
+    renameSync(old, paths.workspaces);
+  } catch (error) {
+    paths.workspaces = old;
+    return error.code ?? error.message;
+  }
+  for (const move of moves) move.ws.path = move.path;
+  for (const repo of new Set(moves.map((move) => move.repo)))
+    gitTry(["worktree", "repair", ...moves.filter((move) => move.repo === repo).map((move) => move.path)], { cwd: repo.path });
+  if (moves.length) saveConfig(paths.config, config);
+  return null;
+}
+
+/** The registered repository `cwd` belongs to, or null. */
+export function repoFromCwd(ctx) {
+  for (const [name, repo] of Object.entries(ctx.config.repos)) {
+    if (isInside(ctx.cwd, join(ctx.paths.workspaces, name))) return name;
+    if (isInside(ctx.cwd, repo.path)) return name;
+    for (const ws of Object.values(repo.workspaces)) if (isInside(ctx.cwd, ws.path)) return name;
+  }
+  const top = gitTry(["rev-parse", "--show-toplevel"], { cwd: ctx.cwd });
+  if (top.ok) {
+    try {
+      const [main] = listWorktrees(ctx.cwd);
+      for (const [name, repo] of Object.entries(ctx.config.repos)) if (main && isInside(main.path, repo.path)) return name;
+    } catch {
+      /* Not a usable repository. */
+    }
+  }
+  return null;
+}
+
+function requireRepo(ctx, name) {
+  const repo = ctx.config.repos[name];
+  if (!repo) throw new NookError(`Unknown repository "${name}". Registered: ${Object.keys(ctx.config.repos).join(", ") || "none"}`);
+  return { name, repo };
+}
+
+/**
+ * The repository a command acts on: --repo, else the one the current folder
+ * belongs to (its main checkout or one of its workspaces). Like git and
+ * worktrunk, nothing is guessed outside a repository.
+ */
+export function resolveRepo(ctx, flag) {
+  if (flag) return requireRepo(ctx, flag);
+  const fromCwd = repoFromCwd(ctx);
+  if (fromCwd) return requireRepo(ctx, fromCwd);
+  if (!Object.keys(ctx.config.repos).length) throw new NookError("No repository yet. Run nk init inside a repository first");
+  throw new NookError(
+    `Not inside a registered repository. Run nk in the repository or one of its workspaces, or pass --repo (${Object.keys(ctx.config.repos).join(", ")})`,
+  );
+}
+
+/**
+ * Every worktree of a repository, as git lists them, joined with what Nook
+ * recorded (port, creation time). Git is the source of truth, like worktrunk:
+ * worktrees made by other tools show up too, without a port. The main
+ * checkout comes first with `main: true`; workspaces Nook recorded whose
+ * folder is gone come last.
+ */
+export function repoWorkspaces(repoName, repo) {
+  let trees = [];
+  try {
+    trees = listWorktrees(repo.path);
+  } catch {
+    /* Not a usable repository; nk doctor reports it. */
+  }
+  const items = [];
+  const recorded = new Set();
+  const taken = new Set(Object.keys(repo.workspaces));
+  trees.forEach((tree, index) => {
+    if (tree.bare) return;
+    const found = Object.entries(repo.workspaces).find(([, ws]) => samePath(ws.path, tree.path));
+    if (found) {
+      recorded.add(found[0]);
+      items.push({ repoName, repo, name: found[0], ws: { ...found[1], locked: tree.locked }, main: false, managed: true });
+      return;
+    }
+    let name = normalizeName(tree.branch ?? basename(tree.path));
+    if (index > 0 && (!name || taken.has(name))) name = normalizeName(basename(tree.path));
+    taken.add(name);
+    const ws = { path: tree.path, branch: tree.branch, locked: tree.locked };
+    items.push({ repoName, repo, name, ws, main: index === 0, managed: false });
+  });
+  for (const [name, ws] of Object.entries(repo.workspaces))
+    if (!recorded.has(name)) items.push({ repoName, repo, name, ws, main: false, managed: true });
+  return items;
+}
+
+/** An existing workspace of the current repository (or --repo) by name: its branch or folder name, converted the same way. */
+export function resolveWorkspace(ctx, name, flag) {
+  const { name: repoName, repo } = resolveRepo(ctx, flag);
+  const items = repoWorkspaces(repoName, repo);
+  const hit = items.find((item) => item.name === name) ?? items.find((item) => normalizeName(basename(item.ws.path)) === name);
+  if (hit) return hit;
+  throw new NookError(`No workspace named "${name}" in ${repoName}. Create it with: nk -b ${name}`);
+}
+
+/** The git branch of a workspace: its name, unless the branch had characters a name cannot use. */
+export function branchOf(name, ws) {
+  return "branch" in ws ? ws.branch : name;
+}
+
+/** Variables hooks and agents see. */
+export function workspaceEnv(ctx, { repoName, repo, name, ws }) {
+  return {
+    ...ctx.env,
+    NOOK_WORKSPACE: name,
+    NOOK_PATH: ws.path,
+    NOOK_REPO: repo.path,
+    NOOK_SHARED: join(ctx.paths.shared, repoName),
+    NOOK_PORT: String(ws.port ?? ""),
+  };
+}

package/src/errors.mjs

@@ -0,0 +1,8 @@
+/** An expected failure: printed as one line, without a stack trace. */
+export class NookError extends Error {
+  constructor(message, { code = 1 } = {}) {
+    super(message);
+    this.name = "NookError";
+    this.code = code;
+  }
+}