@ree-auz/nook 0.0.0-stage → 0.1.0

package/src/commands/clean.mjs

@@ -0,0 +1,175 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { NookError } from "../errors.mjs";
+import { exists, isInside, samePath } from "../home.mjs";
+import { gitTry, listWorktrees, remoteUrl } from "../git.mjs";
+import { githubPrs } from "../forge.mjs";
+import { inspectWorkspace, isMerged } from "../backup.mjs";
+import { describeOccupants, findOccupants, stopProcesses } from "../occupancy.mjs";
+import { createPrompter } from "../prompt.mjs";
+import { branchTip, contains } from "../status.mjs";
+import { resolveRepo } from "../context.mjs";
+import { collect } from "./ls.mjs";
+import { deleteFolder, deleteWorkspace, ignoredData } from "./rm.mjs";
+import { dockerCli, findComposeProjects, removeComposeProject } from "../compose.mjs";
+import { approveHooks } from "./workspace.mjs";
+import { findHook } from "../hooks.mjs";
+
+const DAY = 24 * 60 * 60 * 1000;
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+/**
+ * Why a workspace can go, or null. A merged PR counts when the local branch
+ * has nothing the PR did not have (this covers squash merges). Without a PR,
+ * a branch already in the base counts once the workspace is a day old, so a
+ * fresh workspace that has no commits yet is kept (worktrunk's --min-age).
+ */
+export function mergedReason(item, now = Date.now()) {
+  const { branch, repo, base, pr, ws } = item;
+  if (pr?.state === "merged") {
+    const tip = branchTip(repo.path, branch);
+    if (!tip || (pr.head && contains(repo.path, pr.head, tip))) return { ok: `PR #${pr.number} merged` };
+    return { skip: `has commits that are not in PR #${pr.number}` };
+  }
+  if (pr) return null;
+  const age = now - (ws.created ? Date.parse(ws.created) : createdAt(ws.path));
+  if (!(age >= DAY)) return null;
+  if (branchTip(repo.path, branch) && isMerged(repo.path, branch, base)) return { ok: `merged into ${base}` };
+  return null;
+}
+
+/** When a folder was made, for worktrees Nook did not record; NaN when unknown. */
+function createdAt(path) {
+  try {
+    const stat = statSync(path);
+    return stat.birthtimeMs || stat.ctimeMs;
+  } catch {
+    return Number.NaN;
+  }
+}
+
+/**
+ * Folders in the repository's workspaces folder that are neither a workspace
+ * nor a git worktree: what a removal left halfway, such as node_modules that
+ * Windows would not let go of.
+ */
+export function leftoverFolders(ctx, repoName, repo) {
+  const dir = join(ctx.paths.workspaces, repoName);
+  if (!exists(dir)) return [];
+  const worktrees = listWorktrees(repo.path);
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !repo.workspaces[entry.name])
+    .map((entry) => join(dir, entry.name))
+    .filter((path) => !worktrees.some((w) => samePath(w.path, path)));
+}
+
+/** nk clean [-n] [-y]: remove workspaces whose work is merged. */
+export async function cleanWorkspaces(ctx, { repo: repoFlag, dryRun = false, yes = false, prs = githubPrs, scan = findOccupants, stop = stopProcesses, prompter = createPrompter(), now = Date.now(), docker = dockerCli } = {}) {
+  const { name, repo } = resolveRepo(ctx, repoFlag);
+  if (remoteUrl(repo.path)) {
+    const fetched = gitTry(["fetch", "--quiet", "origin", repo.default_branch], { cwd: repo.path });
+    if (!fetched.ok) ctx.warn(`Could not fetch origin/${repo.default_branch} for ${name}; using what is local`);
+  }
+  const { items, problems } = await collect(ctx, { repo: name, prs });
+  for (const problem of problems) ctx.warn(`Only checks merges in git: ${problem}`);
+
+  const remove = [];
+  const skipped = [];
+  let lost;
+  for (const item of items) {
+    if (item.main || !item.branch) continue;
+    const reason = mergedReason(item, now);
+    if (!reason) continue;
+    const label = `${item.name} (${item.repoName})`;
+    if (item.ws.locked) skipped.push(`${label}: locked (git worktree unlock to allow)`);
+    else if (reason.skip) skipped.push(`${label}: ${reason.skip}`);
+    else if (isInside(ctx.cwd, item.ws.path)) skipped.push(`${label}: you are inside it`);
+    else if (item.changes) skipped.push(`${label}: ${plural(item.changes, "uncommitted change")}`);
+    // Files git ignores (a local database, say) are not backed up, so clean leaves them to nk rm, which lists them.
+    else if ((lost = item.changes === null ? [] : ignoredData(item.ws.path, join(ctx.paths.shared, item.repoName))).length)
+      skipped.push(`${label}: files git ignores would be lost: ${lost.slice(0, 3).join(", ")}${lost.length > 3 ? ` and ${lost.length - 3} more` : ""} (nk rm ${item.name} to remove anyway)`);
+    else remove.push({ item, label, reason: reason.ok, running: item.changes === null ? [] : scan(item.ws.path).processes });
+  }
+
+  const leftovers = [];
+  for (const path of leftoverFolders(ctx, name, repo)) {
+    if (isInside(ctx.cwd, path)) skipped.push(`${path}: you are inside it`);
+    else if (scan(path).processes?.length) skipped.push(`${path}: programs are running in it`);
+    else leftovers.push(path);
+  }
+
+  if (skipped.length) {
+    ctx.warn(`Kept ${skipped.length}:`);
+    for (const text of skipped) ctx.item(text);
+  }
+  if (!remove.length && !leftovers.length) {
+    ctx.info("Nothing to clean");
+    return 0;
+  }
+  if (remove.length) {
+    ctx.info(`${remove.length === 1 ? "1 workspace is" : `${remove.length} workspaces are`} merged:`);
+    const width = Math.max(...remove.map((entry) => entry.label.length));
+    for (const entry of remove) ctx.item(`${entry.label.padEnd(width)}  ${entry.reason}`);
+  }
+  if (leftovers.length) {
+    ctx.info(`Left from earlier removals (not workspaces any more):`);
+    for (const path of leftovers) ctx.item(path);
+  }
+  const running = remove.flatMap((entry) => entry.running);
+  if (running.length) {
+    // Same as nk rm: programs inside are listed, and stopped after one yes.
+    ctx.warn(`${plural(running.length, "program")} running in them:`);
+    for (const entry of remove) for (const p of entry.running) ctx.item(`${p.pid} ${p.name} (${entry.item.name})`);
+  }
+  if (dryRun) {
+    ctx.info("Dry run; nothing was removed");
+    return 0;
+  }
+  // Hook approval comes before anything is stopped or deleted.
+  const repos = new Map(remove.map(({ item }) => [item.repoName, item]));
+  for (const item of repos.values()) if (findHook(item.repo.path, "remove")) await approveHooks(ctx, item, prompter);
+  if (!yes) {
+    let ok;
+    try {
+      const count = remove.length + leftovers.length;
+      const what = count === 1 ? "it" : `these ${count}`;
+      ok = await prompter.confirm(running.length ? `Stop the programs and remove ${what}?` : `Remove ${what}?`, false);
+    } catch {
+      throw new NookError("Confirmation needs a terminal; pass -y to remove without asking");
+    }
+    if (!ok) throw new NookError("Nothing was removed");
+  }
+
+  let failed = 0;
+  for (const { item, running: inside } of remove) {
+    const target = { repoName: item.repoName, repo: item.repo, name: item.name, ws: item.ws };
+    const state = inspectWorkspace({ repo: item.repo.path, path: item.ws.path, branch: item.branch, base: item.base });
+    try {
+      if (inside.length) {
+        await stop(inside);
+        const left = scan(item.ws.path).processes;
+        if (left.length) throw new NookError(`Could not stop:\n${describeOccupants(left)}`);
+        ctx.ok(`Stopped ${plural(inside.length, "program")} in ${item.name}`);
+      }
+      await deleteWorkspace(ctx, target, { state, base: item.base, backupRoot: join(ctx.paths.backup, item.repoName), prompter, scan });
+      ctx.ok(`Removed ${item.name}`);
+    } catch (error) {
+      if (!(error instanceof NookError)) throw error;
+      failed++;
+      ctx.warn(`${item.name} was not removed: ${error.message.split("\n").join("; ")}`);
+    }
+  }
+  for (const path of leftovers) {
+    try {
+      // Compose projects started there go too, as nk rm does for a workspace.
+      for (const project of findComposeProjects(path, docker).projects) removeComposeProject(project, docker);
+      deleteFolder(path);
+      ctx.ok(`Deleted ${path}`);
+    } catch (error) {
+      failed++;
+      ctx.warn(`${path} was not deleted: ${error.message.split("\n").join("; ")}`);
+    }
+  }
+  if (failed) throw new NookError(`${failed} of ${remove.length + leftovers.length} not removed; see the messages above`);
+  return 0;
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,91 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { which } from "../agents.mjs";
+import { exists, samePath } from "../home.mjs";
+import { gitTry, listWorktrees } from "../git.mjs";
+import { line, useColor } from "../ui.mjs";
+import { dockerCli, leftoverComposeProjects } from "../compose.mjs";
+import { ciChanged, uncheckedHooks } from "./check-hooks.mjs";
+import { HOOK_EVENTS, findHook, trustState } from "../hooks.mjs";
+import { gitVersion, toolStatus } from "../tools.mjs";
+
+/** nk doctor: checks only, changes nothing. Exit 1 when something is broken. */
+export function doctor(ctx, { docker = dockerCli } = {}) {
+  let broken = 0;
+  let warnings = 0;
+  const color = useColor(ctx.out, ctx.env);
+  const ok = (text) => ctx.print(`  ${line("ok", text, color)}`);
+  const warn = (text) => {
+    warnings++;
+    ctx.print(`  ${line("warn", text, color)}`);
+  };
+  const bad = (text) => {
+    broken++;
+    ctx.print(`  ${line("fail", text, color)}`);
+  };
+
+  ctx.print("Basics");
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  const recent = major > 20 || (major === 20 && minor >= 12);
+  (recent ? ok : bad)(`node ${process.versions.node}${recent ? "" : " (need 20.12 or newer)"}`);
+  const gv = gitVersion();
+  if (!gv) bad("git not found");
+  else (gv.major > 2 || (gv.major === 2 && gv.minor >= 20) ? ok : bad)(gv.text);
+  ok(`home ${ctx.paths.home}${ctx.env.NOOK_HOME ? " (from NOOK_HOME)" : ""}`);
+  (exists(ctx.paths.config) ? ok : warn)(`config ${ctx.paths.config}${exists(ctx.paths.config) ? "" : " (missing; run nk init)"}`);
+  const tools = toolStatus(ctx.env);
+  (tools.gh === "logged in" ? ok : warn)(`gh ${tools.gh}`);
+  (tools.docker === "running" ? ok : warn)(`docker ${tools.docker}`);
+
+  ctx.print("Agents");
+  const agents = Object.entries(ctx.config.agents);
+  if (!agents.length) warn("none recorded (nk init records them)");
+  for (const [name, agent] of agents) {
+    const found = agent.path && exists(agent.path) ? agent.path : which(name, ctx.env);
+    (found ? ok : warn)(`${name} ${found ?? "not found"}`);
+  }
+
+  for (const [repoName, repo] of Object.entries(ctx.config.repos)) {
+    ctx.print(`Repository ${repoName}`);
+    if (!exists(repo.path) || !gitTry(["rev-parse", "--git-dir"], { cwd: repo.path }).ok) {
+      bad(`${repo.path} is not a git repository`);
+      continue;
+    }
+    ok(repo.path);
+    const shared = join(ctx.paths.shared, repoName);
+    (exists(shared) ? ok : warn)(`shared folder ${shared}${exists(shared) ? "" : " (missing)"}`);
+    const hooks = HOOK_EVENTS.map((event) => findHook(repo.path, event)).filter(Boolean);
+    const notAllowed = hooks.filter((hook) => trustState(repo, hook) !== "trusted").length;
+    const untested = uncheckedHooks(repo).length;
+    const issues = [notAllowed && `${notAllowed} not allowed yet`, untested && `${untested} not tested since changed`, ciChanged(repo) && "CI changed since they were tested"].filter(Boolean);
+    if (!hooks.length) ok("no hooks (nk hooks write <agent> has an agent write them)");
+    else (issues.length ? warn : ok)(`hooks ${hooks.map((hook) => hook.event).join(", ")}${issues.length ? `: ${issues.join(", ")} (see nk hooks)` : ""}`);
+    const worktrees = listWorktrees(repo.path);
+    for (const [name, ws] of Object.entries(repo.workspaces)) {
+      const known = worktrees.find((w) => samePath(w.path, ws.path));
+      if (!exists(ws.path)) bad(`workspace ${name}: ${ws.path} is missing (nk rm ${name} cleans up)`);
+      else if (!known) bad(`workspace ${name}: ${ws.path} is not a git worktree`);
+      else if (known.branch !== (ws.branch ?? name)) warn(`workspace ${name}: checked out ${known.branch ?? "detached HEAD"}`);
+      else ok(`workspace ${name}`);
+    }
+    const dir = join(ctx.paths.workspaces, repoName);
+    if (tools.docker === "running")
+      for (const project of leftoverComposeProjects(dir, worktrees.map((w) => w.path), docker))
+        warn(`Compose project ${project.name} was started in ${project.dir}, which is no longer a workspace (remove it with: docker compose -p ${project.name} down --volumes)`);
+    if (exists(dir))
+      for (const entry of readdirSync(dir)) {
+        if (repo.workspaces[entry]) continue;
+        const path = join(dir, entry);
+        // A git worktree nk did not create, or a folder left behind when a removal failed halfway.
+        warn(
+          worktrees.some((w) => samePath(w.path, path))
+            ? `${path} is a git worktree nk did not create (remove it with: git worktree remove)`
+            : `${path} is not a workspace, only a leftover folder (nk clean deletes it)`,
+        );
+      }
+  }
+
+  const notes = warnings ? `, ${warnings} warning(s)` : "";
+  ctx.print(broken ? `${broken} problem(s) found${notes}` : `No problems found${notes}`);
+  return broken ? 1 : 0;
+}

package/src/commands/forget.mjs

@@ -0,0 +1,57 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { NookError } from "../errors.mjs";
+import { exists, isInside } from "../home.mjs";
+import { resolveRepo } from "../context.mjs";
+import { createPrompter } from "../prompt.mjs";
+import { dockerCli, findComposeProjects, removeComposeProject } from "../compose.mjs";
+import { deleteFolder } from "./rm.mjs";
+
+/**
+ * nk forget [<short-name>]: nk stops knowing a repository. Its registration
+ * and shared files go; the repository folder and backups stay. Workspaces are
+ * removed first with nk rm, which backs up their work, unless the repository
+ * folder itself is gone: then git cannot remove them and they go with it.
+ */
+export async function forgetRepo(ctx, { name: input, yes = false, prompter = createPrompter(), docker = dockerCli } = {}) {
+  const { name, repo } = resolveRepo(ctx, input);
+  const workspaces = Object.keys(repo.workspaces);
+  const present = exists(repo.path);
+  if (workspaces.length && present)
+    throw new NookError(`${name} still has workspaces: ${workspaces.join(", ")}\nRemove them first, which backs up their work: nk rm ${workspaces.join(" ")} --repo ${name}`);
+
+  const shared = join(ctx.paths.shared, name);
+  const dir = join(ctx.paths.workspaces, name);
+  const leftovers = exists(dir) ? readdirSync(dir).map((entry) => join(dir, entry)) : [];
+  ctx.info(`Forgetting ${name} (${repo.path}${present ? "" : ", which no longer exists"})`);
+  if (exists(shared)) ctx.warn(`Deletes the shared files ${shared}, with the values you filled in`);
+  if (leftovers.length) {
+    ctx.warn(`Deletes what is left in ${dir}${present ? "" : " (git cannot remove these without the repository)"}:`);
+    for (const path of leftovers) ctx.item(path);
+  }
+  ctx.info(`Keeps the repository folder${exists(join(ctx.paths.backup, name)) ? ` and the backups in ${join(ctx.paths.backup, name)}` : ""}`);
+  if (!yes) {
+    let ok;
+    try {
+      ok = await prompter.confirm(`Forget ${name}?`, false);
+    } catch {
+      throw new NookError("Confirmation needs a terminal; pass -y to forget without asking");
+    }
+    if (!ok) throw new NookError("Nothing was changed");
+  }
+
+  // What was started from those folders goes with them: Compose projects (containers, volumes, networks,
+  // built images) and the service containers generated hooks start (labelled with their workspace).
+  if (exists(dir)) {
+    for (const project of findComposeProjects(dir, docker).projects) removeComposeProject(project, docker);
+    const labelled = docker(["container", "ls", "-a", "--filter", "label=dev.nook.workspace", "--format", '{{.ID}}\t{{.Label "dev.nook.workspace"}}']);
+    const ids = labelled.ok ? labelled.out.split(/\r?\n/).filter(Boolean).map((row) => row.split("\t")).filter(([, path]) => path && isInside(path, dir)).map(([id]) => id) : [];
+    if (ids.length) docker(["container", "rm", "-f", "-v", ...ids]);
+  }
+  deleteFolder(dir);
+  deleteFolder(shared);
+  delete ctx.config.repos[name];
+  ctx.save();
+  ctx.ok(`Forgot ${name}. Register it again with nk init`);
+  return 0;
+}

package/src/commands/hooks.mjs

@@ -0,0 +1,27 @@
+import { resolveRepo } from "../context.mjs";
+import { useColor, line } from "../ui.mjs";
+import { HOOK_EVENTS, findHook, hookHash, trustState } from "../hooks.mjs";
+import { ciChanged } from "./check-hooks.mjs";
+
+/** nk hooks: each hook of the repository, whether it is allowed, and whether it passed nk hooks test. */
+export function listHooks(ctx, { repo: repoFlag }) {
+  const { name: repoName, repo } = resolveRepo(ctx, repoFlag);
+  const color = useColor(ctx.out, ctx.env);
+  const hooks = HOOK_EVENTS.map((event) => findHook(repo.path, event)).filter(Boolean);
+  ctx.print(`Hooks of ${repoName} (${repo.path}/.nook)`);
+  if (!hooks.length) {
+    ctx.print(`  ${line("info", "none yet; to have an agent write them: nk hooks write <agent>", color)}`);
+    return 0;
+  }
+  let untested = 0;
+  for (const hook of hooks) {
+    const trust = trustState(repo, hook);
+    const tested = repo.checked?.[hook.name] === hookHash(hook.file);
+    if (!tested) untested++;
+    const notes = [trust === "trusted" ? "allowed" : trust === "new" ? "not allowed yet" : "changed, will ask again", tested ? "tested" : "not tested since it changed"];
+    ctx.print(`  ${line(tested && trust === "trusted" ? "ok" : "warn", `${hook.event.padEnd(6)} .nook/${hook.name}  ${notes.join(", ")}`, color)}`);
+  }
+  if (ciChanged(repo)) ctx.print(`  ${line("warn", "CI changed since the hooks were tested; update them with nk hooks write, then nk hooks test", color)}`);
+  if (untested) ctx.print(`  ${line("info", "Test them: nk hooks test", color)}`);
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,154 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import spawn from "cross-spawn";
+import { detectAgents, which } from "../agents.mjs";
+import { NookError } from "../errors.mjs";
+import { isInside, samePath } from "../home.mjs";
+import { defaultBranch, listWorktrees, mainWorktree, remoteUrl } from "../git.mjs";
+import { ensureTrusted, findHooks, trustState } from "../hooks.mjs";
+import { assertName, suggestRepoName } from "../names.mjs";
+import { createPrompter, splitArgs } from "../prompt.mjs";
+import { copyFile, includePatterns, knownSecretFiles, listFiles, sharedCandidates, templateFiles } from "../shared.mjs";
+import { toolStatus } from "../tools.mjs";
+import { hostAddresses, pointAtHost } from "../compose-plan.mjs";
+import { planFromCi } from "../ci.mjs";
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+function openEditor(ctx, file, prompter) {
+  if (!prompter.interactive || prompter.yes) return false;
+  const editor = ctx.env.VISUAL || ctx.env.EDITOR;
+  let command;
+  if (editor) command = [...splitArgs(editor), file];
+  else if (process.platform === "win32") command = ["notepad", file];
+  else if (process.platform === "darwin") command = ["open", "-W", "-t", file];
+  else if (which("xdg-open", ctx.env)) command = ["xdg-open", file];
+  else return false;
+  spawn.sync(command[0], command.slice(1), { stdio: "inherit" });
+  return true;
+}
+
+/**
+ * Fills the shared folder. A file already there is never replaced, so running
+ * init again only adds what is new (a template added since, for example).
+ */
+async function prepareShared(ctx, { repoPath, sharedDir, prompter }) {
+  mkdirSync(sharedDir, { recursive: true });
+  const present = new Set(listFiles(sharedDir));
+  const { patterns, source } = includePatterns(repoPath);
+  ctx.info(`Shared files follow ${source === "default" ? "the default pattern .env*" : ".worktreeinclude"}; only files git ignores are used`);
+  const candidates = sharedCandidates(repoPath, patterns);
+  const templates = templateFiles(repoPath);
+  const copies = [];
+  const fill = [];
+  for (const template of templates) {
+    if (present.has(template.to)) continue;
+    // A committed template is the safe start: the same file in the main checkout may be production.
+    copies.push({ from: join(repoPath, template.from), to: template.to });
+    fill.push(join(sharedDir, template.to));
+    ctx.info(`Starting shared ${template.to} from ${template.from}`);
+  }
+  const covered = new Set([...templates.map((template) => template.to), ...present]);
+  const others = candidates.filter((file) => !covered.has(file));
+  if (others.length && (await prompter.confirm(`Copy ${others.join(", ")} from the repository into the shared folder? (only development files, not production)`, false)))
+    for (const file of others) copies.push({ from: join(repoPath, file), to: file });
+
+  for (const file of knownSecretFiles(repoPath, [...candidates, ...covered]))
+    if (!present.has(file) && (await prompter.confirm(`Found ignored ${file}. Share it with new workspaces too?`, false)))
+      copies.push({ from: join(repoPath, file), to: file });
+
+  for (const copy of copies) copyFile(copy.from, join(sharedDir, copy.to));
+  // A template for running the app inside Docker names Compose services (postgres:5432); here the app runs on
+  // this machine, so point those values at where the services are published.
+  // When the CI job has services, those are started instead of Compose's (see nk hooks write).
+  const addresses = fill.length ? hostAddresses(repoPath, { start: !planFromCi(repoPath).best?.services.length }) : {};
+  if (Object.keys(addresses).length)
+    for (const file of fill) {
+      const { text, keys } = pointAtHost(readFileSync(file, "utf8"), addresses);
+      if (!keys.length) continue;
+      writeFileSync(file, text);
+      ctx.info(`Pointed ${keys.join(", ")} in ${basename(file)} at the Compose services on this machine (each workspace then uses its own ports)`);
+    }
+  if (present.size) ctx.info(`Kept shared files: ${[...present].join(", ")} (edit them in ${sharedDir})`);
+  if (copies.length) ctx.ok(`Shared files in ${sharedDir}: ${copies.map((c) => c.to).join(", ")}`);
+  for (const file of fill) {
+    if (openEditor(ctx, file, prompter)) ctx.ok(`Saved ${file}`);
+    else ctx.warn(`Fill in ${file} once; every new workspace copies it`);
+  }
+}
+
+/**
+ * Records the agents on PATH. Nothing is asked: each starts with its own
+ * default command, and `args` in config.toml can be edited later if wanted.
+ */
+function recordAgents(ctx) {
+  const found = detectAgents(ctx.env);
+  ctx.info(found.length ? "Agents found (start one with nk <name> <agent>):" : "No known agents found on PATH");
+  for (const agent of found) {
+    ctx.item(`${agent.name}  ${agent.version || "?"}  ${agent.path}`);
+    const args = ctx.config.agents[agent.name]?.args ?? [];
+    ctx.config.agents[agent.name] = { path: agent.path, version: agent.version, args };
+  }
+}
+
+/** Worktrees other tools made need no adopting: nk ls, rm and clean read them from git. */
+function listOtherWorktrees(ctx, { repoPath, repo }) {
+  const known = Object.values(repo.workspaces).map((ws) => ws.path);
+  const others = listWorktrees(repoPath)
+    .slice(1)
+    .filter((w) => !known.some((path) => samePath(path, w.path)));
+  if (!others.length) return;
+  ctx.info(`Other worktrees of this repository (nk ls, nk rm and nk clean include them):`);
+  for (const w of others) ctx.item(`${w.branch ?? "(detached)"}  ${w.path}`);
+}
+
+/** nk init: run once per repository; safe to run again. */
+export async function init(ctx, { yes = false, allowHooks = false, name: nameFlag } = {}) {
+  const prompter = createPrompter({ yes });
+  const repoPath = mainWorktree(ctx.cwd);
+  if (isInside(repoPath, ctx.paths.home)) throw new NookError("Run nk init in the main repository, not in a workspace");
+  const registered = Object.entries(ctx.config.repos).find(([, repo]) => samePath(repo.path, repoPath));
+  let name;
+  if (registered) {
+    name = registered[0];
+    if (nameFlag && nameFlag !== name) throw new NookError(`This repository is already registered as "${name}"`);
+  } else {
+    name = assertName(nameFlag ?? (await prompter.ask("Short name for this repository", suggestRepoName(basename(repoPath)))), "repository");
+    if (ctx.config.repos[name]) throw new NookError(`"${name}" is already used for ${ctx.config.repos[name].path}`);
+  }
+
+  const repo = (ctx.config.repos[name] ??= { workspaces: {}, hooks: {} });
+  repo.path = repoPath;
+  repo.remote = remoteUrl(repoPath);
+  repo.default_branch = defaultBranch(repoPath);
+  repo.workspaces ??= {};
+  repo.hooks ??= {};
+  ctx.ok(`Registered ${name} @ ${repoPath}`);
+  ctx.info(`Remote ${repo.remote || "(none)"}, default branch ${repo.default_branch}`);
+  mkdirSync(join(ctx.paths.workspaces, name), { recursive: true });
+
+  listOtherWorktrees(ctx, { repoPath, repo });
+  recordAgents(ctx);
+  const tools = toolStatus(ctx.env);
+  ctx.info(`gh: ${tools.gh}; docker: ${tools.docker}`);
+  await prepareShared(ctx, { repoPath, sharedDir: join(ctx.paths.shared, name), prompter });
+  ctx.save();
+
+  // Allowing hooks lets this repository's scripts run on this machine: --yes skips questions, but
+  // only --allow-hooks (or a person answering in a terminal) gives that.
+  const hooks = findHooks(repoPath);
+  const pending = hooks.filter((hook) => trustState(repo, hook) !== "trusted");
+  if (pending.length && !allowHooks && (yes || !prompter.interactive)) {
+    ctx.warn(`${plural(pending.length, "hook")} not allowed yet: ${pending.map((h) => `.nook/${h.name}`).join(", ")}`);
+    ctx.info(`Read them in ${join(repoPath, ".nook")}, then run nk init --allow-hooks, or nk init in a terminal`);
+  } else {
+    const hookPrompter = allowHooks ? { confirm: async () => true } : prompter;
+    await ensureTrusted({ repoName: name, repoConfig: repo, hooks, prompter: hookPrompter, save: () => ctx.save(), ui: ctx });
+    if (allowHooks && pending.length) ctx.info(`Allowed ${pending.map((h) => `.nook/${h.name}`).join(", ")} (--allow-hooks)`);
+  }
+  if (!hooks.length) ctx.info("No .nook/ hooks yet. To have an agent write them: nk hooks write <agent>");
+  ctx.save();
+  ctx.ok(`Done. Config: ${ctx.paths.config}`);
+  ctx.info("Next: nk -b <name> [agent]");
+  return 0;
+}

package/src/commands/ls.mjs

@@ -0,0 +1,107 @@
+import { NookError } from "../errors.mjs";
+import { baseRef, remoteUrl } from "../git.mjs";
+import { githubPrs } from "../forge.mjs";
+import { aheadBehind, changeCount } from "../status.mjs";
+import { useColor } from "../ui.mjs";
+import { branchOf, repoFromCwd, repoWorkspaces } from "../context.mjs";
+import { isInside } from "../home.mjs";
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+function table(rows) {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((row) => row[i].length)));
+  return rows.map((row) => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i]))).join("  "));
+}
+
+/** Every workspace with its local state and, when gh can tell, its PR. */
+export async function collect(ctx, { repo: repoFlag, prs: lookup = githubPrs } = {}) {
+  const only = repoFlag ?? repoFromCwd(ctx);
+  if (only && !ctx.config.repos[only]) throw new NookError(`Unknown repository "${only}"`);
+  const repos = Object.entries(ctx.config.repos).filter(([name]) => !only || name === only);
+  const fetched = await Promise.all(repos.map(([, repo]) => (remoteUrl(repo.path) ? lookup(repo.path, ctx.env) : { prs: null })));
+  const items = [];
+  const problems = new Set();
+  repos.forEach(([repoName, repo], i) => {
+    const { prs, error } = fetched[i];
+    if (error) problems.add(error);
+    const base = baseRef(repo.path, repo.default_branch);
+    for (const item of repoWorkspaces(repoName, repo)) {
+      const branch = branchOf(item.name, item.ws);
+      const pr = item.main || !branch ? null : (prs?.get(branch) ?? null);
+      const commits = item.main || !branch ? null : aheadBehind(repo.path, branch, base);
+      items.push({ ...item, branch, base, changes: changeCount(item.ws.path), commits, pr });
+    }
+  });
+  return { items, problems: [...problems] };
+}
+
+const portsText = (ws) => (Number.isInteger(ws.port) ? `${ws.port}-${ws.port + 9}` : "-");
+
+function changesText(n) {
+  if (n === null) return "missing";
+  return n ? `${n} changed` : "clean";
+}
+
+function commitsText(c) {
+  if (!c) return "";
+  return [c.ahead && `↑${c.ahead}`, c.behind && `↓${c.behind}`].filter(Boolean).join(" ");
+}
+
+function prText(pr) {
+  if (!pr) return "";
+  return `#${pr.number} ${pr.state}${pr.ci ? ` ${pr.ci}` : ""}`;
+}
+
+/** nk ls [--json] */
+export async function listWorkspaces(ctx, { repo: repoFlag, json = false, prs } = {}) {
+  const { items, problems } = await collect(ctx, { repo: repoFlag, prs });
+  if (json) {
+    const data = items.map(({ name, branch, repoName, ws, base, changes, commits, pr, main, managed }) => ({
+      name,
+      branch,
+      main,
+      managed,
+      locked: Boolean(ws.locked),
+      repo: repoName,
+      path: ws.path,
+      port: ws.port ?? null,
+      base,
+      changes,
+      ahead: commits?.ahead ?? null,
+      behind: commits?.behind ?? null,
+      pr,
+    }));
+    ctx.print(JSON.stringify(data, null, 2));
+    return 0;
+  }
+  if (!items.length) {
+    ctx.info("No repositories yet. Run nk init inside one");
+    return 0;
+  }
+  // Gutter as in worktrunk: ^ main checkout, @ where you are, + another worktree.
+  const mark = (item) => (isInside(ctx.cwd, item.ws.path) && !items.some((o) => o !== item && o.ws.path.length > item.ws.path.length && isInside(ctx.cwd, o.ws.path)) ? "@" : item.main ? "^" : "+");
+  const rows = [["", "NAME", "REPO", "PORTS", "CHANGES", "BASE", "PR", "PATH"]];
+  for (const item of items) {
+    const name = item.ws.locked ? `${item.name} (locked)` : item.name;
+    rows.push([mark(item), name, item.repoName, portsText(item.ws), changesText(item.changes), commitsText(item.commits), prText(item.pr), item.ws.path]);
+  }
+  const lines = table(rows);
+  // Merged rows are dimmed, as worktrunk does for branches that are safe to delete.
+  const dim = useColor(ctx.out, ctx.env);
+  items.forEach((item, i) => {
+    if (dim && item.pr?.state === "merged") lines[i + 1] = `\x1b[2m${lines[i + 1]}\x1b[0m`;
+  });
+  ctx.print(lines.join("\n"));
+
+  const workspaces = items.filter((item) => !item.main);
+  const changed = workspaces.filter((item) => item.changes).length;
+  const merged = workspaces.filter((item) => item.pr?.state === "merged").length;
+  const outside = workspaces.filter((item) => !item.managed).length;
+  const parts = [`Showing ${plural(workspaces.length, "workspace")} and the main checkout`];
+  if (outside) parts.push(`${outside} made by other tools`);
+  if (changed) parts.push(`${changed} with changes`);
+  if (merged) parts.push(`${merged} merged (nk clean removes them)`);
+  ctx.info(parts.join(", "));
+  for (const problem of problems) ctx.warn(`No PR status: ${problem}`);
+  return 0;
+}