@ree-auz/nook 0.1.0 → 0.1.2

package/src/cli.mjs

@@ -1,151 +1,151 @@
-import { readFileSync } from "node:fs";
-import { parseArgs } from "node:util";
-import { createContext } from "./context.mjs";
-import { NookError } from "./errors.mjs";
-import { doctor } from "./commands/doctor.mjs";
-import { init } from "./commands/init.mjs";
-import { createPrompter } from "./prompt.mjs";
-import { line, useColor } from "./ui.mjs";
-import { cleanWorkspaces } from "./commands/clean.mjs";
-import { listWorkspaces } from "./commands/ls.mjs";
-import { removeWorkspace } from "./commands/rm.mjs";
-import { createWorkspace, openWorkspace } from "./commands/workspace.mjs";
-import { writeHooks } from "./commands/write-hooks.mjs";
-import { listHooks } from "./commands/hooks.mjs";
-import { testHooks } from "./commands/check-hooks.mjs";
-import { forgetRepo } from "./commands/forget.mjs";
-
-const HELP = `nk - one home for your git worktrees
-
-Usage:
-  nk init [--yes] [--allow-hooks] [--name <short-name>]   register this repository (once per repository)
-  nk -b <name> [agent] [-p <prompt>] [-y] create a workspace; start the agent if given
-                                         (-y: keep the converted name without asking;
-                                         --untested: start even if hooks or CI changed
-                                         since nk hooks test last passed)
-  nk <name> [agent] [-p <prompt>]         open a workspace; start the agent if given
-  nk ls [--json]                          list workspaces: changes, commits, PR and CI
-  nk rm <name>... [-n] [-y]               back up and remove workspaces
-  nk clean [-n] [-y]                      remove workspaces whose work is merged, and leftover folders
-  nk hooks                                the repository's .nook hooks: allowed? tested?
-  nk hooks write [agent]                  write the hooks from the repository's CI (GitHub Actions)
-                                         and Compose file; with an agent: then starts it in the
-                                         same folder to finish what they could not tell
-  nk hooks test                           run this folder's hooks in a temporary workspace;
-                                         fails if remove leaves anything behind
-  nk forget [<short-name>] [-y]           stop knowing a repository: its registration and shared
-                                         files go; the repository folder and backups stay
-  nk doctor                               check nk's tools: node, git, gh, docker, agents
-
-Options:
-  --repo <short-name>   act on another registered repository (otherwise: the one you are in)
-  -- <args...>          extra arguments for the agent
-Home folder: ~/nook (set NOOK_HOME to move it)`;
-
-function version() {
-  return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-}
-
-/** Splits argv at "--": everything after it goes to the agent untouched. */
-function splitExtra(argv) {
-  const index = argv.indexOf("--");
-  return index === -1 ? [argv, []] : [argv.slice(0, index), argv.slice(index + 1)];
-}
-
-function parse(argv, options) {
-  try {
-    return parseArgs({ args: argv, options, allowPositionals: true, strict: true });
-  } catch (error) {
-    throw new NookError(`${error.message}\nRun nk --help for usage`);
-  }
-}
-
-export async function run(argv, io = {}) {
-  const [args, extra] = splitExtra(argv);
-  const [first] = args;
-  if (!args.length || first === "help" || first === "--help" || first === "-h") {
-    (io.out ?? process.stdout).write(`${HELP}\n`);
-    return 0;
-  }
-  if (first === "version" || first === "--version" || first === "-v") {
-    (io.out ?? process.stdout).write(`${version()}\n`);
-    return 0;
-  }
-  const ctx = createContext(io);
-
-  switch (first) {
-    case "init": {
-      const { values } = parse(args.slice(1), { yes: { type: "boolean", short: "y" }, "allow-hooks": { type: "boolean" }, name: { type: "string" } });
-      return init(ctx, { yes: values.yes, allowHooks: values["allow-hooks"], name: values.name });
-    }
-    case "ls": {
-      const { values } = parse(args.slice(1), { repo: { type: "string" }, json: { type: "boolean" } });
-      return listWorkspaces(ctx, values);
-    }
-    case "rm": {
-      const { values, positionals } = parse(args.slice(1), {
-        "dry-run": { type: "boolean", short: "n" },
-        yes: { type: "boolean", short: "y" },
-        repo: { type: "string" },
-      });
-      if (!positionals.length) throw new NookError("Usage: nk rm <name>... [-n] [-y]");
-      return removeWorkspace(ctx, { names: positionals, repo: values.repo, dryRun: values["dry-run"], yes: values.yes });
-    }
-    case "hooks": {
-      const { values, positionals } = parse(args.slice(1), { repo: { type: "string" }, yes: { type: "boolean", short: "y" } });
-      const [action, agent, ...rest] = positionals;
-      if (!action && !agent) return listHooks(ctx, values);
-      if (action === "write" && !rest.length) return writeHooks(ctx, { repo: values.repo, agent, extra });
-      if (action === "test" && !agent) return testHooks(ctx, { repo: values.repo });
-      throw new NookError("Usage: nk hooks | nk hooks write [agent] | nk hooks test");
-    }
-    case "forget": {
-      const { values, positionals } = parse(args.slice(1), { yes: { type: "boolean", short: "y" }, repo: { type: "string" } });
-      if (positionals.length > 1) throw new NookError("Usage: nk forget [<short-name>] [-y]");
-      return forgetRepo(ctx, { name: positionals[0] ?? values.repo, yes: values.yes });
-    }
-    case "doctor":
-      parse(args.slice(1), {});
-      return doctor(ctx);
-    case "clean": {
-      const { values } = parse(args.slice(1), {
-        "dry-run": { type: "boolean", short: "n" },
-        yes: { type: "boolean", short: "y" },
-        repo: { type: "string" },
-      });
-      return cleanWorkspaces(ctx, { repo: values.repo, dryRun: values["dry-run"], yes: values.yes });
-    }
-    default: {
-      const { values, positionals } = parse(args, {
-        b: { type: "string", short: "b" },
-        prompt: { type: "string", short: "p" },
-        repo: { type: "string" },
-        yes: { type: "boolean", short: "y" },
-        untested: { type: "boolean" },
-      });
-      const create = values.b !== undefined;
-      const name = create ? values.b : positionals.shift();
-      if (!name || positionals.length > 1) throw new NookError("Usage: nk [-b] <name> [agent] [-p <prompt>]");
-      const options = { name, repo: values.repo, agent: positionals[0], prompt: values.prompt, extra };
-      return create ? createWorkspace(ctx, { ...options, untested: values.untested, prompter: createPrompter({ yes: values.yes }) }) : openWorkspace(ctx, options);
-    }
-  }
-}
-
-export async function main(argv, io = {}) {
-  try {
-    return await run(argv, io);
-  } catch (error) {
-    if (error instanceof NookError) {
-      const err = io.err ?? process.stderr;
-      const color = useColor(err, io.env ?? process.env);
-      // First line says what failed; later lines say why and what to do next.
-      const [first, ...rest] = error.message.split("\n");
-      const lines = [line("fail", first, color)];
-      for (const text of rest) lines.push(/^\s/.test(text) ? line("item", text.trim(), color) : line("info", text, color));
-      err.write(`${lines.join("\n")}\n`);
-      return error.code;
-    }
-    throw error;
-  }
-}
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { createContext } from "./context.mjs";
+import { NookError } from "./errors.mjs";
+import { doctor } from "./commands/doctor.mjs";
+import { init } from "./commands/init.mjs";
+import { createPrompter } from "./prompt.mjs";
+import { line, useColor } from "./ui.mjs";
+import { cleanWorkspaces } from "./commands/clean.mjs";
+import { listWorkspaces } from "./commands/ls.mjs";
+import { removeWorkspace } from "./commands/rm.mjs";
+import { createWorkspace, openWorkspace } from "./commands/workspace.mjs";
+import { writeHooks } from "./commands/write-hooks.mjs";
+import { listHooks } from "./commands/hooks.mjs";
+import { testHooks } from "./commands/check-hooks.mjs";
+import { forgetRepo } from "./commands/forget.mjs";
+
+const HELP = `nk - one home for your git worktrees
+
+Usage:
+  nk init [--yes] [--allow-hooks] [--name <short-name>]   register this repository (once per repository)
+  nk -b <name> [agent] [-p <prompt>] [-y] create a workspace; start the agent if given
+                                         (-y: keep the converted name without asking;
+                                         --untested: start even if hooks or CI changed
+                                         since nk hooks test last passed)
+  nk <name> [agent] [-p <prompt>]         open a workspace; start the agent if given
+  nk ls [--json]                          list workspaces: changes, commits, PR and CI
+  nk rm <name>... [-n] [-y]               back up and remove workspaces
+  nk clean [-n] [-y]                      remove workspaces whose work is merged, and leftover folders
+  nk hooks                                the repository's .nook hooks: allowed? tested?
+  nk hooks write [agent]                  write the hooks from the repository's CI (GitHub Actions)
+                                         and Compose file; with an agent: then starts it in the
+                                         same folder to finish what they could not tell
+  nk hooks test                           run this folder's hooks in a temporary workspace;
+                                         fails if remove leaves anything behind
+  nk forget [<short-name>] [-y]           stop knowing a repository: its registration and shared
+                                         files go; the repository folder and backups stay
+  nk doctor                               check nk's tools: node, git, gh, docker, agents
+
+Options:
+  --repo <short-name>   act on another registered repository (otherwise: the one you are in)
+  -- <args...>          extra arguments for the agent
+Home folder: ~/nook (set NOOK_HOME to move it)`;
+
+function version() {
+  return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+}
+
+/** Splits argv at "--": everything after it goes to the agent untouched. */
+function splitExtra(argv) {
+  const index = argv.indexOf("--");
+  return index === -1 ? [argv, []] : [argv.slice(0, index), argv.slice(index + 1)];
+}
+
+function parse(argv, options) {
+  try {
+    return parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+  } catch (error) {
+    throw new NookError(`${error.message}\nRun nk --help for usage`);
+  }
+}
+
+export async function run(argv, io = {}) {
+  const [args, extra] = splitExtra(argv);
+  const [first] = args;
+  if (!args.length || first === "help" || first === "--help" || first === "-h") {
+    (io.out ?? process.stdout).write(`${HELP}\n`);
+    return 0;
+  }
+  if (first === "version" || first === "--version" || first === "-v") {
+    (io.out ?? process.stdout).write(`${version()}\n`);
+    return 0;
+  }
+  const ctx = createContext(io);
+
+  switch (first) {
+    case "init": {
+      const { values } = parse(args.slice(1), { yes: { type: "boolean", short: "y" }, "allow-hooks": { type: "boolean" }, name: { type: "string" } });
+      return init(ctx, { yes: values.yes, allowHooks: values["allow-hooks"], name: values.name });
+    }
+    case "ls": {
+      const { values } = parse(args.slice(1), { repo: { type: "string" }, json: { type: "boolean" } });
+      return listWorkspaces(ctx, values);
+    }
+    case "rm": {
+      const { values, positionals } = parse(args.slice(1), {
+        "dry-run": { type: "boolean", short: "n" },
+        yes: { type: "boolean", short: "y" },
+        repo: { type: "string" },
+      });
+      if (!positionals.length) throw new NookError("Usage: nk rm <name>... [-n] [-y]");
+      return removeWorkspace(ctx, { names: positionals, repo: values.repo, dryRun: values["dry-run"], yes: values.yes });
+    }
+    case "hooks": {
+      const { values, positionals } = parse(args.slice(1), { repo: { type: "string" }, yes: { type: "boolean", short: "y" } });
+      const [action, agent, ...rest] = positionals;
+      if (!action && !agent) return listHooks(ctx, values);
+      if (action === "write" && !rest.length) return writeHooks(ctx, { repo: values.repo, agent, extra });
+      if (action === "test" && !agent) return testHooks(ctx, { repo: values.repo });
+      throw new NookError("Usage: nk hooks | nk hooks write [agent] | nk hooks test");
+    }
+    case "forget": {
+      const { values, positionals } = parse(args.slice(1), { yes: { type: "boolean", short: "y" }, repo: { type: "string" } });
+      if (positionals.length > 1) throw new NookError("Usage: nk forget [<short-name>] [-y]");
+      return forgetRepo(ctx, { name: positionals[0] ?? values.repo, yes: values.yes });
+    }
+    case "doctor":
+      parse(args.slice(1), {});
+      return doctor(ctx);
+    case "clean": {
+      const { values } = parse(args.slice(1), {
+        "dry-run": { type: "boolean", short: "n" },
+        yes: { type: "boolean", short: "y" },
+        repo: { type: "string" },
+      });
+      return cleanWorkspaces(ctx, { repo: values.repo, dryRun: values["dry-run"], yes: values.yes });
+    }
+    default: {
+      const { values, positionals } = parse(args, {
+        b: { type: "string", short: "b" },
+        prompt: { type: "string", short: "p" },
+        repo: { type: "string" },
+        yes: { type: "boolean", short: "y" },
+        untested: { type: "boolean" },
+      });
+      const create = values.b !== undefined;
+      const name = create ? values.b : positionals.shift();
+      if (!name || positionals.length > 1) throw new NookError("Usage: nk [-b] <name> [agent] [-p <prompt>]");
+      const options = { name, repo: values.repo, agent: positionals[0], prompt: values.prompt, extra };
+      return create ? createWorkspace(ctx, { ...options, untested: values.untested, prompter: createPrompter({ yes: values.yes }) }) : openWorkspace(ctx, options);
+    }
+  }
+}
+
+export async function main(argv, io = {}) {
+  try {
+    return await run(argv, io);
+  } catch (error) {
+    if (error instanceof NookError) {
+      const err = io.err ?? process.stderr;
+      const color = useColor(err, io.env ?? process.env);
+      // First line says what failed; later lines say why and what to do next.
+      const [first, ...rest] = error.message.split("\n");
+      const lines = [line("fail", first, color)];
+      for (const text of rest) lines.push(/^\s/.test(text) ? line("item", text.trim(), color) : line("info", text, color));
+      err.write(`${lines.join("\n")}\n`);
+      return error.code;
+    }
+    throw error;
+  }
+}

package/src/commands/check-hooks.mjs

@@ -1,128 +1,128 @@
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { NookError } from "../errors.mjs";
-import { exists } from "../home.mjs";
-import { git, gitTry } from "../git.mjs";
-import { findHooks, hookHash, runHook } from "../hooks.mjs";
-import { allocatePort } from "../ports.mjs";
-import { copyShared } from "../shared.mjs";
-import { resolveRepo, workspaceEnv } from "../context.mjs";
-import { describeOccupants, findOccupants, stopProcesses } from "../occupancy.mjs";
-import { ciHash } from "../ci.mjs";
-import { dockerCli, dockerSnapshot, findComposeProjects, removeComposeProject, snapshotDiff } from "../compose.mjs";
-import { deleteFolder } from "./rm.mjs";
-
-const CHECK_NAME = "nook-hooks-test";
-
-/** Hooks of the main checkout that changed since they last passed a check. */
-export function uncheckedHooks(repo) {
-  return findHooks(repo.path).filter((hook) => repo.checked?.[hook.name] !== hookHash(hook.file));
-}
-
-/** CI changed since the hooks last passed a test (only known once a test has passed). */
-export function ciChanged(repo) {
-  return Boolean(repo.checked_ci) && ciHash(repo.path) !== repo.checked_ci;
-}
-
-/**
- * What changed since nk hooks test last passed, as short phrases; empty when
- * nothing did. `tested` says whether a test ever passed for this repository.
- */
-export function setupChanges(repo) {
-  const changes = uncheckedHooks(repo).map((hook) => `.nook/${hook.name}`);
-  if (ciChanged(repo)) changes.push("the CI configuration");
-  return { tested: Boolean(repo.checked), changes };
-}
-
-/**
- * nk hooks test: runs the hooks of the folder you are in (an agent's
- * branch, say) in a throwaway workspace: create, open twice, then remove.
- * Passes when the hooks succeed, open can repeat, git sees no changed files,
- * and Docker is back to what it was. Hooks that pass are recorded, so doctor and rm can tell when a hook
- * changed without being checked again.
- */
-export async function testHooks(ctx, { repo: repoFlag, docker = dockerCli, scan = findOccupants, stop = stopProcesses }) {
-  const { name: repoName, repo } = resolveRepo(ctx, repoFlag);
-  const top = gitTry(["rev-parse", "--show-toplevel"], { cwd: ctx.cwd });
-  const source = top.ok ? top.out : repo.path;
-  const hooks = findHooks(source);
-  if (!hooks.length) throw new NookError(`No hooks in ${join(source, ".nook")}. Write them first: nk hooks write <agent>`);
-  const byEvent = Object.fromEntries(hooks.map((hook) => [hook.event, hook]));
-
-  const path = join(ctx.paths.workspaces, repoName, CHECK_NAME);
-  if (exists(path)) throw new NookError(`${path} is left from an earlier check. Delete it, then run the check again`);
-  ctx.info(`Checking ${hooks.map((hook) => `.nook/${hook.name}`).join(", ")} from ${source} in a temporary workspace`);
-  const before = dockerSnapshot(docker);
-  if (!before) ctx.info("Docker is not available; only the hooks' exit codes are checked");
-
-  mkdirSync(join(ctx.paths.workspaces, repoName), { recursive: true });
-  // Recorded while the check runs, so an nk -b at the same time does not take the same ports.
-  const port = await ctx.update(async (config) => {
-    const taken = await allocatePort(config);
-    config.repos[repoName].workspaces[CHECK_NAME] = { path, port: taken, created: new Date().toISOString() };
-    return taken;
-  });
-  try {
-    git(["worktree", "add", "--detach", path, git(["rev-parse", "HEAD"], { cwd: source })], { cwd: repo.path });
-  } catch (error) {
-    delete repo.workspaces[CHECK_NAME];
-    ctx.save();
-    throw error;
-  }
-  const target = { repoName, repo, name: CHECK_NAME, ws: { path, port } };
-  copyShared(join(ctx.paths.shared, repoName), path);
-
-  // A file git already shows as changed in a fresh checkout (line endings the repository's .gitattributes
-  // would change, as awesome-kotlin's gradlew.bat) is the repository's, not the hooks'.
-  const status = () => {
-    const result = gitTry(["status", "--porcelain", "--untracked-files=all"], { cwd: path });
-    return result.ok ? result.out.split(/\r?\n/).filter((line) => line.trim()) : [];
-  };
-  const fresh = new Set(status());
-  const problems = [];
-  const run = async (event, label = event) => {
-    const hook = byEvent[event];
-    if (!hook) return true;
-    const result = await runHook(hook, { cwd: path, env: workspaceEnv(ctx, target), logsDir: ctx.paths.logs, label: `${repoName}-${CHECK_NAME}`, output: ctx.err });
-    if (result.status === 0) return true;
-    problems.push(`${label} failed (exit ${result.status}). Log: ${result.log}`);
-    return false;
-  };
-  try {
-    if (await run("create")) if (await run("open")) await run("open", "open, run a second time,");
-    // Hooks set up the workspace; they must not change what git tracks, or every commit would carry it.
-    const changed = status().filter((line) => !fresh.has(line));
-    if (changed.length)
-      problems.push(`The hooks changed files in the workspace that git would commit (ignore them in .gitignore, or do not write them):\n${changed.slice(0, 10).map((line) => `  ${line.trim()}`).join("\n")}`);
-  } finally {
-    await run("remove");
-    const running = scan(path).processes ?? [];
-    if (running.length) {
-      problems.push(`Programs were still running in the workspace after remove:\n${describeOccupants(running)}`);
-      await stop(running);
-    }
-    const after = before && dockerSnapshot(docker);
-    if (after)
-      for (const item of snapshotDiff(before, after)) problems.push(`remove left a Docker ${item.kind}: ${item.name}`);
-    // Clean up whatever is left, so the check itself leaves nothing behind.
-    for (const project of findComposeProjects(path, docker).projects) removeComposeProject(project, docker);
-    gitTry(["worktree", "remove", "--force", path], { cwd: repo.path });
-    delete repo.workspaces[CHECK_NAME];
-    ctx.save();
-    try {
-      deleteFolder(path);
-    } catch (error) {
-      problems.push(error.message);
-    }
-    gitTry(["worktree", "prune"], { cwd: repo.path });
-  }
-
-  if (problems.length) throw new NookError(`The hooks did not pass:\n${problems.map((text) => `  ${text}`).join("\n")}`);
-  repo.checked = Object.fromEntries(hooks.map((hook) => [hook.name, hookHash(hook.file)]));
-  const ci = ciHash(source);
-  if (ci) repo.checked_ci = ci;
-  else delete repo.checked_ci;
-  ctx.save();
-  ctx.ok(`The hooks passed: create, open twice and remove ran, and ${before ? "Docker is as it was" : "all exited with 0"}`);
-  return 0;
-}
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { NookError } from "../errors.mjs";
+import { exists } from "../home.mjs";
+import { git, gitTry } from "../git.mjs";
+import { findHooks, hookHash, runHook } from "../hooks.mjs";
+import { allocatePort } from "../ports.mjs";
+import { copyShared } from "../shared.mjs";
+import { resolveRepo, workspaceEnv } from "../context.mjs";
+import { describeOccupants, findOccupants, stopProcesses } from "../occupancy.mjs";
+import { ciHash } from "../ci.mjs";
+import { dockerCli, dockerSnapshot, findComposeProjects, removeComposeProject, snapshotDiff } from "../compose.mjs";
+import { deleteFolder } from "./rm.mjs";
+
+const CHECK_NAME = "nook-hooks-test";
+
+/** Hooks of the main checkout that changed since they last passed a check. */
+export function uncheckedHooks(repo) {
+  return findHooks(repo.path).filter((hook) => repo.checked?.[hook.name] !== hookHash(hook.file));
+}
+
+/** CI changed since the hooks last passed a test (only known once a test has passed). */
+export function ciChanged(repo) {
+  return Boolean(repo.checked_ci) && ciHash(repo.path) !== repo.checked_ci;
+}
+
+/**
+ * What changed since nk hooks test last passed, as short phrases; empty when
+ * nothing did. `tested` says whether a test ever passed for this repository.
+ */
+export function setupChanges(repo) {
+  const changes = uncheckedHooks(repo).map((hook) => `.nook/${hook.name}`);
+  if (ciChanged(repo)) changes.push("the CI configuration");
+  return { tested: Boolean(repo.checked), changes };
+}
+
+/**
+ * nk hooks test: runs the hooks of the folder you are in (an agent's
+ * branch, say) in a throwaway workspace: create, open twice, then remove.
+ * Passes when the hooks succeed, open can repeat, git sees no changed files,
+ * and Docker is back to what it was. Hooks that pass are recorded, so doctor and rm can tell when a hook
+ * changed without being checked again.
+ */
+export async function testHooks(ctx, { repo: repoFlag, docker = dockerCli, scan = findOccupants, stop = stopProcesses }) {
+  const { name: repoName, repo } = resolveRepo(ctx, repoFlag);
+  const top = gitTry(["rev-parse", "--show-toplevel"], { cwd: ctx.cwd });
+  const source = top.ok ? top.out : repo.path;
+  const hooks = findHooks(source);
+  if (!hooks.length) throw new NookError(`No hooks in ${join(source, ".nook")}. Write them first: nk hooks write <agent>`);
+  const byEvent = Object.fromEntries(hooks.map((hook) => [hook.event, hook]));
+
+  const path = join(ctx.paths.workspaces, repoName, CHECK_NAME);
+  if (exists(path)) throw new NookError(`${path} is left from an earlier check. Delete it, then run the check again`);
+  ctx.info(`Checking ${hooks.map((hook) => `.nook/${hook.name}`).join(", ")} from ${source} in a temporary workspace`);
+  const before = dockerSnapshot(docker);
+  if (!before) ctx.info("Docker is not available; only the hooks' exit codes are checked");
+
+  mkdirSync(join(ctx.paths.workspaces, repoName), { recursive: true });
+  // Recorded while the check runs, so an nk -b at the same time does not take the same ports.
+  const port = await ctx.update(async (config) => {
+    const taken = await allocatePort(config);
+    config.repos[repoName].workspaces[CHECK_NAME] = { path, port: taken, created: new Date().toISOString() };
+    return taken;
+  });
+  try {
+    git(["worktree", "add", "--detach", path, git(["rev-parse", "HEAD"], { cwd: source })], { cwd: repo.path });
+  } catch (error) {
+    delete repo.workspaces[CHECK_NAME];
+    ctx.save();
+    throw error;
+  }
+  const target = { repoName, repo, name: CHECK_NAME, ws: { path, port } };
+  copyShared(join(ctx.paths.shared, repoName), path);
+
+  // A file git already shows as changed in a fresh checkout (line endings the repository's .gitattributes
+  // would change, as awesome-kotlin's gradlew.bat) is the repository's, not the hooks'.
+  const status = () => {
+    const result = gitTry(["status", "--porcelain", "--untracked-files=all"], { cwd: path });
+    return result.ok ? result.out.split(/\r?\n/).filter((line) => line.trim()) : [];
+  };
+  const fresh = new Set(status());
+  const problems = [];
+  const run = async (event, label = event) => {
+    const hook = byEvent[event];
+    if (!hook) return true;
+    const result = await runHook(hook, { cwd: path, env: workspaceEnv(ctx, target), logsDir: ctx.paths.logs, label: `${repoName}-${CHECK_NAME}`, output: ctx.err });
+    if (result.status === 0) return true;
+    problems.push(`${label} failed (exit ${result.status}). Log: ${result.log}`);
+    return false;
+  };
+  try {
+    if (await run("create")) if (await run("open")) await run("open", "open, run a second time,");
+    // Hooks set up the workspace; they must not change what git tracks, or every commit would carry it.
+    const changed = status().filter((line) => !fresh.has(line));
+    if (changed.length)
+      problems.push(`The hooks changed files in the workspace that git would commit (ignore them in .gitignore, or do not write them):\n${changed.slice(0, 10).map((line) => `  ${line.trim()}`).join("\n")}`);
+  } finally {
+    await run("remove");
+    const running = scan(path).processes ?? [];
+    if (running.length) {
+      problems.push(`Programs were still running in the workspace after remove:\n${describeOccupants(running)}`);
+      await stop(running);
+    }
+    const after = before && dockerSnapshot(docker);
+    if (after)
+      for (const item of snapshotDiff(before, after)) problems.push(`remove left a Docker ${item.kind}: ${item.name}`);
+    // Clean up whatever is left, so the check itself leaves nothing behind.
+    for (const project of findComposeProjects(path, docker).projects) removeComposeProject(project, docker);
+    gitTry(["worktree", "remove", "--force", path], { cwd: repo.path });
+    delete repo.workspaces[CHECK_NAME];
+    ctx.save();
+    try {
+      deleteFolder(path);
+    } catch (error) {
+      problems.push(error.message);
+    }
+    gitTry(["worktree", "prune"], { cwd: repo.path });
+  }
+
+  if (problems.length) throw new NookError(`The hooks did not pass:\n${problems.map((text) => `  ${text}`).join("\n")}`);
+  repo.checked = Object.fromEntries(hooks.map((hook) => [hook.name, hookHash(hook.file)]));
+  const ci = ciHash(source);
+  if (ci) repo.checked_ci = ci;
+  else delete repo.checked_ci;
+  ctx.save();
+  ctx.ok(`The hooks passed: create, open twice and remove ran, and ${before ? "Docker is as it was" : "all exited with 0"}`);
+  return 0;
+}