@ree-auz/nook 0.1.0 → 0.1.2

package/src/commands/clean.mjs

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

@@ -1,91 +1,100 @@
-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;
-}
+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";
+import { DEFAULT_PORT_BASE, ephemeralRange, inEphemeral } from "../ports.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}`);
+  const range = ephemeralRange();
+  const base = ctx.config.port_base ?? DEFAULT_PORT_BASE;
+  // A range that starts well above the workspace ports (Linux: 32768) leaves plenty of room below it.
+  if (range && range.end >= base && range.start < base + 1000) {
+    const fix = process.platform === "win32" ? "; Windows' default is 49152-65535 (as administrator: netsh int ipv4 set dynamicport tcp start=49152 num=16384, then restart)" : "";
+    warn(`outgoing connections take ports ${range.start}-${range.end}, which overlaps the workspace ports from ${base}; new workspaces avoid them where they can${fix}`);
+  } else if (range) ok(`outgoing connections take ports ${range.start}-${range.end}`);
+
+  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 if (inEphemeral(ws.port, range)) warn(`workspace ${name}: ports ${ws.port}-${ws.port + 9} are among those outgoing connections take, so one may be in use by another program`);
+      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;
+}