@ree-auz/nook 0.0.0-stage → 0.1.1

package/src/commands/rm.mjs

@@ -0,0 +1,190 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { NookError } from "../errors.mjs";
+import { exists, isInside, samePath } from "../home.mjs";
+import { baseRef, gitTry, listWorktrees, remoteUrl } from "../git.mjs";
+import { githubPrs } from "../forge.mjs";
+import { findHook } from "../hooks.mjs";
+import { backupDir, createBackup, inspectWorkspace, needsBackup } from "../backup.mjs";
+import { describeOccupants, findOccupants, stopProcesses } from "../occupancy.mjs";
+import { createPrompter } from "../prompt.mjs";
+import { branchOf, resolveWorkspace } from "../context.mjs";
+import { toName } from "../names.mjs";
+import { approveHooks, hook } from "./workspace.mjs";
+import { listFiles } from "../shared.mjs";
+import { setupChanges } from "./check-hooks.mjs";
+import { describeProject, dockerCli, findComposeProjects, removeComposeProject } from "../compose.mjs";
+
+function occupants(ctx, path, scan) {
+  const result = scan(path);
+  if (result.unsupported) ctx.warn(`Could not check for running programs: ${result.unsupported}`);
+  return result.processes;
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+/**
+ * Backs up what would be lost, runs the remove hook, deletes the folder and
+ * the branch, and forgets the workspace. Programs must already be stopped.
+ */
+export async function deleteWorkspace(ctx, target, { state, base, backupRoot, prompter, scan = findOccupants, docker = dockerCli }) {
+  const { repo, ws, name } = target;
+  const branchName = branchOf(name, ws);
+  if (needsBackup(state)) {
+    const dir = createBackup({ repo: repo.path, path: ws.path, branch: branchName, base, state, dir: backupDir(backupRoot, name) });
+    ctx.ok(`Backed up changes to ${dir}`);
+  }
+  if (state.present) {
+    try {
+      await hook(ctx, target, "remove", { prompter });
+    } catch (error) {
+      if (error instanceof NookError) error.message += "\nStopped; nothing was deleted";
+      throw error;
+    }
+  }
+  // What the workspace started with Docker Compose goes too, so no remove hook is needed for it.
+  // Checked again after the hook, which may have removed some of it already.
+  for (const project of findComposeProjects(ws.path, docker).projects) {
+    try {
+      removeComposeProject(project, docker);
+    } catch (error) {
+      throw new NookError(`${error.message}\nStopped; the folder was not deleted`);
+    }
+    ctx.ok(`Removed ${describeProject(project)}`);
+  }
+  if (state.present) {
+    const after = occupants(ctx, ws.path, scan);
+    if (after.length) throw new NookError(`Programs started running in ${ws.path}:\n${describeOccupants(after)}\nNothing was deleted`);
+    // Changes are backed up by now, so the folder goes even when git cannot remove the worktree
+    // (a damaged one, say); prune below then drops git's record of it.
+    const removed = gitTry(["worktree", "remove", "--force", ws.path], { cwd: repo.path });
+    if (!removed.ok) ctx.warn(`git worktree remove failed (${removed.err.split("\n")[0]}); deleting the folder instead`);
+    // git can leave ignored folders behind on Windows (node_modules, .venv), even when it reports success.
+    deleteFolder(ws.path);
+  }
+  gitTry(["worktree", "prune"], { cwd: repo.path });
+  if (listWorktrees(repo.path).some((tree) => samePath(tree.path, ws.path)))
+    throw new NookError(`git still lists ${ws.path} as a worktree. Run git worktree prune in ${repo.path}, then nk rm ${name} again`);
+  if (branchName) {
+    const branch = gitTry(["branch", "-D", branchName], { cwd: repo.path });
+    if (!branch.ok && !/not found/i.test(branch.err)) ctx.warn(`Branch ${branchName} was kept: ${branch.err}`);
+  }
+  delete repo.workspaces[name];
+  ctx.save();
+}
+
+// Folders a project rebuilds from its own files, and files nobody keeps: losing them loses nothing.
+const REBUILT = new Set(["node_modules", ".venv", "venv", "vendor", "dist", "build", "out", "target", "coverage", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache", ".parcel-cache", ".gradle", ".tox", "_build", "deps", "tmp", "log", "logs", ".idea", ".vscode", ".DS_Store"]);
+
+/** Ignored files and folders in a workspace that hold more than a rebuild or a shared copy: a local database, say. */
+export function ignoredData(path, sharedDir) {
+  const listed = gitTry(["ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "--no-empty-directory"], { cwd: path });
+  if (!listed.ok) return [];
+  const shared = new Set(listFiles(sharedDir));
+  return listed.out
+    .split(/\r?\n/)
+    .filter((entry) => entry && !shared.has(entry) && !/\.(log|pyc)$/.test(entry) && !entry.split("/").some((part) => REBUILT.has(part)));
+}
+
+/** Deletes a folder and everything in it, retrying while Windows still holds a file open. */
+export function deleteFolder(path) {
+  if (!exists(path)) return;
+  try {
+    rmSync(path, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+  } catch (error) {
+    // A container that mounts the workspace and runs as root leaves files this user cannot delete.
+    if (error.code === "EACCES" || (error.code === "EPERM" && process.platform !== "win32"))
+      throw new NookError(`Could not delete ${path}: ${error.message}\nA container probably wrote these files as another user (often root). Delete the folder with sudo rm -rf, or have the remove hook delete them from inside the container`);
+    throw new NookError(`Could not delete ${path}: ${error.message}\nClose what uses it and run the command again`);
+  }
+  if (exists(path)) throw new NookError(`Could not delete ${path}; close what uses it and run the command again`);
+}
+
+/** What removing one workspace involves, checked before anything changes. */
+async function planRemoval(ctx, input, { repoFlag, scan, prs, docker }) {
+  const name = toName(input);
+  const target = resolveWorkspace(ctx, name, repoFlag);
+  const { repo, ws } = target;
+  if (target.main) throw new NookError(`${ws.path} is the main checkout of ${target.repoName}; git cannot remove it`);
+  if (ws.locked) throw new NookError(`${ws.path} is locked. Unlock it first: git worktree unlock ${ws.path}`);
+  if (exists(ws.path) && isInside(ctx.cwd, ws.path))
+    throw new NookError(`You are inside ${ws.path}. Change to another folder first, e.g. cd ${repo.path}`);
+
+  const base = baseRef(repo.path, repo.default_branch);
+  const branchName = branchOf(target.name, ws);
+  const state = inspectWorkspace({ repo: repo.path, path: ws.path, branch: branchName ?? "", base });
+  const backupRoot = join(ctx.paths.backup, target.repoName);
+  const removeHook = state.present ? findHook(repo.path, "remove") : null;
+
+  ctx.info(`Removing ${target.name} @ ${ws.path}${state.present ? "" : " (folder already missing)"}${!branchName ? "" : branchName === target.name ? " and its branch" : ` and its branch ${branchName}`}`);
+  if (removeHook) ctx.info(`Runs .nook/${removeHook.name} first`);
+  const changed = setupChanges(repo).changes.filter((what) => what.startsWith(".nook/"));
+  if (state.present && changed.length) ctx.warn(`${changed.join(", ")} changed since nk hooks test last passed; remove may leave things behind`);
+  const compose = findComposeProjects(ws.path, docker);
+  for (const project of compose.projects) ctx.info(`Removes ${describeProject(project)}`);
+  for (const name of compose.shared) ctx.warn(`Compose project ${name} also has containers outside this workspace; it is kept`);
+  if (compose.unavailable && compose.unavailable !== "not installed") ctx.warn(`Could not check for Docker containers: ${compose.unavailable}`);
+  if (needsBackup(state)) ctx.info(`Backs up changes to ${backupRoot}`);
+  const lost = state.present ? ignoredData(ws.path, join(ctx.paths.shared, target.repoName)) : [];
+  if (lost.length) ctx.warn(`Not backed up, since git ignores them: ${lost.slice(0, 8).join(", ")}${lost.length > 8 ? ` and ${lost.length - 8} more` : ""}`);
+  if (state.changes.length) {
+    ctx.warn(`${plural(state.changes.length, "uncommitted change")}:`);
+    for (const change of state.changes.slice(0, 10)) ctx.item(change);
+    if (state.changes.length > 10) ctx.item(`... ${state.changes.length - 10} more`);
+  }
+  if (state.unpushed.length) ctx.warn(`${plural(state.unpushed.length, "commit")} not pushed`);
+  if (branchName && !state.merged) {
+    // A squash merge leaves the branch outside the base; the PR says whether it was merged.
+    const pr = remoteUrl(repo.path) ? (await prs(repo.path, ctx.env)).prs?.get(branchName) : null;
+    if (pr?.state === "merged") ctx.info(`PR #${pr.number} is merged`);
+    else ctx.warn(`Branch ${branchName} is not merged into ${base}`);
+  }
+  const running = state.present ? occupants(ctx, ws.path, scan) : [];
+  return { target, state, base, backupRoot, removeHook, running };
+}
+
+/** nk rm <name>... [-n] [-y]: checks every workspace first, asks once, then removes them in turn. */
+export async function removeWorkspace(ctx, { name, names = [name], repo: repoFlag, dryRun = false, yes = false, scan = findOccupants, stop = stopProcesses, prompter = createPrompter(), prs = githubPrs, docker = dockerCli }) {
+  const plans = [];
+  for (const input of [...new Set(names.map(toName))]) plans.push(await planRemoval(ctx, input, { repoFlag, scan, prs, docker }));
+  if (dryRun) {
+    ctx.info("Dry run; nothing was removed");
+    return 0;
+  }
+
+  const running = plans.flatMap((plan) => plan.running);
+  if (running.length) {
+    ctx.warn(`${plural(running.length, "program")} running in ${plans.length === 1 ? "the workspace" : "these workspaces"}:`);
+    for (const item of running) ctx.item(`${item.pid} ${item.name}`);
+  }
+  // Hook approval comes before anything is stopped or deleted.
+  const approved = new Set();
+  for (const { target, removeHook } of plans)
+    if (removeHook && !approved.has(target.repoName)) {
+      approved.add(target.repoName);
+      await approveHooks(ctx, target, prompter);
+    }
+  if (!yes) {
+    const what = plans.map((plan) => plan.target.name).join(", ");
+    const question = running.length ? `Stop ${running.length === 1 ? "it" : "them"} and remove ${what}?` : `Remove ${what}?`;
+    let ok;
+    try {
+      ok = await prompter.confirm(question, false);
+    } catch {
+      throw new NookError("Confirmation needs a terminal; pass -y to remove without asking");
+    }
+    if (!ok) throw new NookError("Nothing was removed");
+  }
+  if (running.length) {
+    await stop(running);
+    const left = plans.flatMap((plan) => (plan.state.present ? occupants(ctx, plan.target.ws.path, scan) : []));
+    if (left.length) throw new NookError(`Could not stop:\n${describeOccupants(left)}\nNothing was removed`);
+    ctx.ok(`Stopped ${plural(running.length, "program")}`);
+  }
+
+  for (const { target, state, base, backupRoot } of plans) {
+    await deleteWorkspace(ctx, target, { state, base, backupRoot, prompter, scan, docker });
+    ctx.ok(`Removed ${target.name}`);
+  }
+  return 0;
+}

package/src/commands/workspace.mjs

@@ -0,0 +1,163 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { agentCommand, launch } from "../agents.mjs";
+import { NookError } from "../errors.mjs";
+import { exists } from "../home.mjs";
+import { baseRef, git, gitTry, refExists, remoteUrl } from "../git.mjs";
+import { ensureTrusted, findHook, findHooks, runHook } from "../hooks.mjs";
+import { nameProblem, normalizeName, toName } from "../names.mjs";
+import { allocatePort } from "../ports.mjs";
+import { createPrompter } from "../prompt.mjs";
+import { copyShared } from "../shared.mjs";
+import { resolveRepo, resolveWorkspace, workspaceEnv } from "../context.mjs";
+import { setupChanges } from "./check-hooks.mjs";
+
+/**
+ * Before work starts: hooks or CI that changed since nk hooks test last passed
+ * stop a new workspace (they may no longer set it up or clean it up), unless
+ * `untested` is passed; an existing workspace only gets a warning.
+ */
+function checkSetup(ctx, repo, { stop, untested }) {
+  const { tested, changes } = setupChanges(repo);
+  if (!changes.length) return;
+  if (!tested) {
+    if (findHooks(repo.path).length) ctx.warn("The hooks have never passed nk hooks test");
+    return;
+  }
+  const what = `${changes.join(" and ")} changed since nk hooks test last passed`;
+  if (stop && !untested) throw new NookError(`${what}\nRun nk hooks test first, or pass --untested to start anyway`);
+  ctx.warn(`${what} (run: nk hooks test)`);
+}
+
+/** Asks once for hooks that are new or changed; nothing when all are allowed. */
+export function approveHooks(ctx, { repoName, repo }, prompter = createPrompter()) {
+  return ensureTrusted({ repoName, repoConfig: repo, hooks: findHooks(repo.path), prompter, save: () => ctx.save(), ui: ctx });
+}
+
+/**
+ * Runs one hook of the repository in the workspace. Hooks are read from the
+ * main checkout, like worktrunk reads its project config from where the
+ * command runs, so a branch made before the hooks existed still gets them.
+ * Throws on a non-zero exit.
+ */
+export async function hook(ctx, target, event, { prompter = createPrompter() } = {}) {
+  const found = findHook(target.repo.path, event);
+  if (!found) return null;
+  await approveHooks(ctx, target, prompter);
+  const result = await runHook(found, {
+    cwd: target.ws.path,
+    env: workspaceEnv(ctx, target),
+    logsDir: ctx.paths.logs,
+    label: `${target.repoName}-${target.name}`,
+    output: ctx.err,
+  });
+  if (result.status !== 0)
+    throw new NookError(`.nook/${found.name} failed (exit ${result.status}). Log: ${result.log}`, { code: result.status || 1 });
+  return result;
+}
+
+async function finish(ctx, target, { agent, prompt, extra }) {
+  if (!agent) {
+    if (prompt || extra.length) throw new NookError("-p and extra arguments need an agent, e.g. nk <name> <agent> -p ...");
+    // On a terminal the path is a line like the others; captured (cd "$(nk …)"), it is the bare path.
+    if (ctx.out.isTTY) ctx.ok(`Ready at ${target.ws.path}`);
+    else ctx.print(target.ws.path);
+    return 0;
+  }
+  const command = agentCommand(ctx.config, agent, { prompt, extra }, ctx.env);
+  ctx.step(`Starting ${agent} in ${target.ws.path}`);
+  return launch(command, { cwd: target.ws.path, env: workspaceEnv(ctx, target) });
+}
+
+/** An existing local or origin branch spelled exactly like `input`, or null. */
+function existingBranch(repoPath, input) {
+  if (!gitTry(["check-ref-format", "--branch", input], { cwd: repoPath }).ok) return null;
+  return refExists(repoPath, `refs/heads/${input}`) || refExists(repoPath, `refs/remotes/origin/${input}`) ? input : null;
+}
+
+function addWorktree(repoPath, name, path, defaultBranch) {
+  if (refExists(repoPath, `refs/heads/${name}`)) git(["worktree", "add", path, name], { cwd: repoPath });
+  else if (refExists(repoPath, `refs/remotes/origin/${name}`))
+    git(["worktree", "add", "--track", "-b", name, path, `origin/${name}`], { cwd: repoPath });
+  else git(["worktree", "add", "--no-track", "-b", name, path, baseRef(repoPath, defaultBranch)], { cwd: repoPath });
+}
+
+/**
+ * The name for a new workspace. When nk had to change what was passed in and
+ * there is a terminal, the converted name is shown ready to edit.
+ */
+async function pickName(ctx, input, prompter) {
+  let name = toName(input);
+  if (name === input) return name;
+  if (!prompter.interactive) {
+    ctx.info(`Using the name ${name}`);
+    return name;
+  }
+  for (;;) {
+    const edited = normalizeName(await prompter.edit("Workspace name (edit or press Enter)", name));
+    const problem = nameProblem(edited);
+    if (!problem) return edited;
+    ctx.warn(problem);
+  }
+}
+
+/** nk -b <name> [agent] */
+export async function createWorkspace(ctx, { name: input, repo: repoFlag, agent, prompt, extra = [], prompter = createPrompter(), untested = false }) {
+  const { name: repoName, repo } = resolveRepo(ctx, repoFlag);
+  checkSetup(ctx, repo, { stop: true, untested });
+  // Asked before anything is made, so hooks that are not allowed leave no half-made workspace.
+  await approveHooks(ctx, { repoName, repo }, prompter);
+  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}; using what is local`);
+  }
+  // A branch that already exists keeps its own name, "/" and all; the folder uses the converted name.
+  const existing = existingBranch(repo.path, String(input));
+  const name = existing ? toName(existing) : await pickName(ctx, input, prompter);
+  if (existing && existing !== name) ctx.info(`Using the name ${name} for branch ${existing}`);
+  const branch = existing ?? name;
+  const dir = join(ctx.paths.workspaces, repoName);
+  const path = join(dir, name);
+  // The name and ports are taken under the lock, so two nk -b at once never get the same ones.
+  const ws = await ctx.update(async (config) => {
+    const fresh = config.repos[repoName];
+    if (fresh.workspaces[name]) throw new NookError(`Workspace "${name}" already exists. Open it with: nk ${name}`);
+    if (exists(path)) throw new NookError(`${path} already exists`);
+    const port = await allocatePort(config);
+    fresh.workspaces[name] = { path, port, created: new Date().toISOString(), ...(branch !== name && { branch }) };
+    return fresh.workspaces[name];
+  });
+  const { port } = ws;
+  mkdirSync(dir, { recursive: true });
+  try {
+    addWorktree(repo.path, branch, path, repo.default_branch);
+  } catch (error) {
+    delete repo.workspaces[name];
+    ctx.save();
+    throw error;
+  }
+  const target = { repoName, repo, name, ws };
+  ctx.ok(`Created workspace ${name} @ ${path} (ports ${port}–${port + 9})`);
+
+  const shared = copyShared(join(ctx.paths.shared, repoName), path);
+  if (shared.copied.length) ctx.info(`Copied shared files: ${shared.copied.join(", ")}`);
+  if (shared.skipped.length) ctx.warn(`Not copied (git does not ignore them here): ${shared.skipped.join(", ")}`);
+
+  try {
+    await hook(ctx, target, "create");
+    await hook(ctx, target, "open");
+  } catch (error) {
+    if (error instanceof NookError) error.message += `\nThe workspace is kept at ${path}; remove it with: nk rm ${name}`;
+    throw error;
+  }
+  return finish(ctx, target, { agent, prompt, extra });
+}
+
+/** nk <name> [agent] */
+export async function openWorkspace(ctx, { name, repo: repoFlag, agent, prompt, extra = [] }) {
+  const target = resolveWorkspace(ctx, toName(name), repoFlag);
+  if (!exists(target.ws.path)) throw new NookError(`${target.ws.path} is missing. Run nk doctor`);
+  if (!target.main) checkSetup(ctx, target.repo, { stop: false });
+  await hook(ctx, target, "open");
+  return finish(ctx, target, { agent, prompt, extra });
+}

package/src/commands/write-hooks.mjs

@@ -0,0 +1,185 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parseEnv } from "node:util";
+import { resolveRepo } from "../context.mjs";
+import { exists } from "../home.mjs";
+import { gitTry } from "../git.mjs";
+import { HOOK_EVENTS, findHooks } from "../hooks.mjs";
+import { NookError } from "../errors.mjs";
+import { planFromCi } from "../ci.mjs";
+import { planCompose } from "../compose-plan.mjs";
+import { GENERATED_MARK, hookFiles, sources } from "../generate-hooks.mjs";
+import { listFiles } from "../shared.mjs";
+import { agentCommand, launch } from "../agents.mjs";
+
+/** Files that say how a project is installed, run or served. */
+const MARKERS = new Set([
+  "package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock", "bun.lockb", "pnpm-workspace.yaml",
+  "pyproject.toml", "uv.lock", "poetry.lock", "requirements.txt", "Pipfile.lock",
+  "Gemfile.lock", "go.mod", "Cargo.toml", "composer.lock", "mix.lock",
+  "compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml", "Dockerfile", "devcontainer.json",
+  "Makefile", "justfile", "Taskfile.yml", "Procfile", "mise.toml", ".tool-versions", ".nvmrc", ".python-version",
+]);
+const DOC = "https://github.com/ree-auz/nook/blob/main/docs/setup-hooks.md";
+
+/** CI configuration: it already lists, step by step, how a clean machine gets the project running. */
+const CI_FILE = /^(\.github\/workflows\/[^/]+\.ya?ml|\.gitlab-ci\.yml|\.circleci\/config\.yml|azure-pipelines\.yml|bitbucket-pipelines\.yml|\.buildkite\/pipeline\.ya?ml|\.woodpecker\.ya?ml|\.woodpecker\/[^/]+\.ya?ml)$/;
+
+function ciFiles(repoPath) {
+  const listed = gitTry(["ls-files"], { cwd: repoPath });
+  return listed.ok ? listed.out.split(/\r?\n/).filter((file) => CI_FILE.test(file)) : [];
+}
+
+/** Tracked marker files up to two folders deep, skipping vendored code. */
+function markerFiles(repoPath) {
+  const listed = gitTry(["ls-files"], { cwd: repoPath });
+  if (!listed.ok) return [];
+  return listed.out
+    .split(/\r?\n/)
+    .filter((file) => file.split("/").length <= 3 && !/(^|\/)(node_modules|vendor)\//.test(file) && MARKERS.has(basename(file)));
+}
+
+/** Names of the shared files, and keys in them left empty. Values are never read out. */
+function sharedSummary(sharedDir) {
+  if (!exists(sharedDir)) return [];
+  return listFiles(sharedDir).map((file) => {
+    if (!/(^|\/)\.env[^/]*$/.test(file)) return file;
+    try {
+      const values = parseEnv(readFileSync(join(sharedDir, file), "utf8"));
+      const empty = Object.keys(values).filter((key) => values[key] === "");
+      return empty.length ? `${file} (empty: ${empty.join(", ")})` : file;
+    } catch {
+      return file;
+    }
+  });
+}
+
+/** Hook files in `<dir>/.nook`, with whether nk generated them. */
+function existingHooks(dir) {
+  const folder = join(dir, ".nook");
+  if (!exists(folder)) return [];
+  return readdirSync(folder)
+    .filter((file) => HOOK_EVENTS.some((event) => file.startsWith(`${event}.`)))
+    .map((file) => ({ file, generated: readFileSync(join(folder, file), "utf8").startsWith(GENERATED_MARK) }));
+}
+
+/**
+ * Writes hooks into `<dir>/.nook` from the repository's CI. Never replaces a
+ * hook someone wrote by hand. Returns { plan, written } or { reason }.
+ */
+export function generateHooks(dir) {
+  // Compose services nk would start, so CI's addresses that point at them count as the workspace's own.
+  const candidate = planCompose(dir);
+  const known = candidate ? [...Object.values(candidate.remap).flat().map((entry) => entry.host), ...Object.values(candidate.ports).filter((port) => /^\d+$/.test(port))] : [];
+  const ci = planFromCi(dir, known);
+  // CI that starts its own services says what the project needs; the Compose file is then for other uses.
+  const ciPorts = ci.best?.services.flatMap((service) => service.ports).length ?? 0;
+  const compose = candidate && (ci.best?.services.length ? planCompose(dir, { start: false, reserved: ciPorts }) : candidate);
+  if (!ci.files.length && !compose) return { reason: "no GitHub Actions workflow (.github/workflows/*.yml) and no Compose file" };
+  if (!ci.best && !compose) return { reason: `could not read ${ci.errors.map((e) => `${e.source} (${e.error.split("\n")[0]})`).join(", ")}` };
+  const base = ci.best ?? { source: compose.file, job: null, tools: [], env: {}, services: [], create: [], remove: [], skipped: [], untranslated: [] };
+  const plan = compose ? { ...base, compose, untranslated: [...base.untranslated, ...compose.untranslated] } : base;
+  const handWritten = existingHooks(dir).filter((hook) => !hook.generated);
+  if (handWritten.length) return { reason: `.nook already has hooks written by hand: ${handWritten.map((h) => h.file).join(", ")}`, plan };
+  const files = hookFiles(plan);
+  const folder = join(dir, ".nook");
+  mkdirSync(folder, { recursive: true });
+  for (const hook of existingHooks(dir)) if (!files[hook.file]) rmSync(join(folder, hook.file));
+  for (const [file, text] of Object.entries(files)) writeFileSync(join(folder, file), text);
+  return { plan, written: Object.keys(files), others: ci.others };
+}
+
+function report(ctx, result) {
+  const { plan } = result;
+  ctx.ok(`Wrote ${result.written.map((file) => `.nook/${file}`).join(", ")} from ${sources(plan)}`);
+  if (result.others.length) ctx.info(`Other CI jobs not used: ${result.others.slice(0, 5).join(", ")}${result.others.length > 5 ? ` and ${result.others.length - 5} more` : ""}`);
+  if (plan.tools.length) ctx.info(`Checks the tools CI installs: ${plan.tools.map((t) => (t.version ? `${t.name} ${t.version}` : t.name)).join(", ")}`);
+  if (plan.services.length) ctx.info(`Starts for each workspace, on its own ports: ${plan.services.map((s) => `${s.name} (${s.image.split("@")[0]})`).join(", ")}`);
+  if (plan.compose) {
+    const { file, start, ports, notStarted } = plan.compose;
+    if (start.length) ctx.info(`Starts from ${file} in each workspace's own Compose project: ${start.join(", ")}`);
+    if (Object.keys(ports).length) ctx.info(`Gives each workspace its own ports in .env: ${Object.keys(ports).join(", ")}`);
+    const moved = Object.entries(plan.compose.remap).map(([name, entries]) => `${name} ${entries.map((e) => e.host).join(", ")}`);
+    if (moved.length) ctx.info(`Moves fixed host ports to each workspace's own: ${moved.join("; ")}`);
+    if (plan.compose.ownNetwork?.length) ctx.info(`Runs on each workspace's own network instead of the host's: ${plan.compose.ownNetwork.join(", ")}`);
+    if (notStarted.length) ctx.info(`Not started (start them yourself when needed): ${notStarted.map((s) => `${s.name} (${s.why})`).join(", ")}`);
+  }
+  if (Object.keys(plan.env).length) ctx.info(`Adds to .env: ${Object.keys(plan.env).join(", ")}`);
+  if (plan.create.length) {
+    ctx.info("Setup steps (create):");
+    for (const step of plan.create) ctx.item(step.run.split("\n")[0]);
+  }
+  if (plan.remove.length) {
+    ctx.info("Cleanup steps (remove):");
+    for (const step of plan.remove) ctx.item(step.run.split("\n")[0]);
+  }
+  if (plan.skipped.length) ctx.info(`Left out ${plan.skipped.length} CI-only steps (checkout, tests, lint, build, uploads)`);
+  if (plan.untranslated.length) {
+    ctx.warn("Not added; review these and add what is safe by hand (or nk hooks write <agent>):");
+    for (const item of plan.untranslated) ctx.item(`${item.step}: ${item.why}`);
+  }
+}
+
+/** The prompt for an agent that writes or finishes this repository's hooks, filled with what nk knows. */
+export function setupPrompt(ctx, { repoName, repo, dir = repo.path, generated = null }) {
+  const markers = markerFiles(dir);
+  const ci = ciFiles(dir);
+  const shared = sharedSummary(join(ctx.paths.shared, repoName));
+  const hooks = findHooks(dir).map((hook) => `.nook/${hook.name}`);
+  const list = (items, none) => (items.length ? items.map((item) => `- ${item}`).join("\n") : `- ${none}`);
+  const start = generated?.written
+    ? `nk already wrote ${generated.written.map((f) => `.nook/${f}`).join(", ")} from ${sources(generated.plan)}, without AI. What it could not translate:
+${list(generated.plan.untranslated.map((i) => `${i.step}: ${i.why}`), "nothing")}
+
+Your task, in this folder:
+1. Read the generated hooks and the CI file. Add what was not translated, adapted to a workspace (its own ports from NOOK_PORT, its own container and project names, started again by open, cleaned up by remove). Keep the rest as generated. Once you edit a hook, remove its first line, so nk hooks write will not replace your work.`
+    : `Your task, in this folder:
+1. Start from the CI configuration: take its setup steps (runtime versions, dependency install, services such as databases, environment variables, migrations or seed data) and leave out what only CI needs (tests, lint, builds, releases, caches, uploads). Then adapt it to a workspace, which differs from a CI machine in three ways: several workspaces run at once, so ports and container or Compose project names must be this workspace's own; a workspace is kept and reopened, so services must start again; and nothing is thrown away afterwards, so remove has to clean up. Without CI, use the files below and the README.
+   Write .nook/create.mjs and .nook/remove.mjs as a pair, and .nook/open.mjs if services must start again when the workspace is reopened (it runs every time, so it must be safe to repeat).`;
+  return `Set up Nook hooks for the repository ${repoName}. Nook (nk) gives each task its own git worktree (a workspace) and runs scripts from .nook/ in it: create once, open on every open, remove before deletion. Rules and examples: ${DOC}
+
+${start}
+2. Never use the main checkout's .env or services, never print secrets, and never run docker compose config.
+3. Run nk hooks test here. It runs create, open twice and remove in a temporary workspace and lists whatever remove left behind. Fix the hooks until it passes.
+4. Do not commit or push. Tell me what each hook runs and what I must fill in once in the shared files.
+
+What nk knows about this repository:
+
+CI configuration:
+${list(ci, "none found")}
+
+Other files that show how it is set up:
+${list(markers, "none found; read the README")}
+
+Shared files, copied into every new workspace before create runs (from ~/nook/shared/${repoName}/):
+${list(shared, "none")}
+
+Hooks there now:
+${list(hooks, "none")}
+
+What nk does itself: it copies the shared files and gives the workspace ten free ports (NOOK_PORT to NOOK_PORT + 9). On removal it stops programs running in the folder and, as a safety net, removes Docker Compose projects started in it.`;
+}
+
+/**
+ * nk hooks write [agent]. nk translates the repository's CI into hooks in the
+ * folder you are in (usually the main checkout). With an agent, it then starts
+ * the agent in the same folder to finish what was not translated.
+ */
+export async function writeHooks(ctx, { repo: repoFlag, agent, extra = [] }) {
+  const target = resolveRepo(ctx, repoFlag);
+  const top = gitTry(["rev-parse", "--show-toplevel"], { cwd: ctx.cwd });
+  const dir = top.ok ? top.out : target.repo.path;
+  const result = generateHooks(dir);
+  if (!agent) {
+    if (!result.written)
+      throw new NookError(`Cannot write hooks from CI: ${result.reason}\nTo have an agent write them instead: nk hooks write <agent>`);
+    report(ctx, result);
+    ctx.info(`Next: nk hooks test${result.plan.untranslated.length ? `, or nk hooks write <agent> to have an agent finish them` : ""}`);
+    return 0;
+  }
+  if (result.written) report(ctx, result);
+  else ctx.info(`The agent writes the hooks itself (${result.reason})`);
+  const prompt = setupPrompt(ctx, { repoName: target.name, repo: target.repo, dir, generated: result });
+  ctx.info(`Starting ${agent} in ${dir}`);
+  return launch(agentCommand(ctx.config, agent, { prompt, extra }, ctx.env), { cwd: dir, env: ctx.env });
+}