@gonxped31/agent-kit 0.2.0 → 0.3.0

package/README.md

@@ -72,6 +72,34 @@ file as the kit wrote it, so `agk update` can tell the files you changed:
 
 It commits nothing: review the changes and commit them on a branch, like any change.
 
+### Presets: your own setup, in every new repo
+
+Once a repo is set up the way you like (your skills, rules, check steps, CI), save
+that as a preset and start new repos from it:
+
+    agk preset save web               # lists what the repo has beyond the kit
+    agk preset save web --only 1-3,6  # keeps the parts you pick
+    agk setup shop --preset web       # the kit, plus your preset
+
+- **What's saved**: setup files the kit doesn't have (in `.claude/`, `.github/`,
+  `.githooks/`, `scripts/hooks/`, `.gitignore`, `.mcp.json`), and what you added to the
+  kit's files: settings rules, check steps, `CLAUDE.md` bullets. Additions are kept
+  apart from the files, so they still apply when the kit's files change. Project code
+  is never looked at. In a terminal, `save` asks which parts to keep.
+- **Where**: `~/.config/agk/presets/<name>/` on every OS (`$XDG_CONFIG_HOME` moves it).
+  A preset named `default` is used by every `agk setup`, unless `--no-preset`.
+- **Defaults**: `agk preset save web --github [--public]` makes `agk setup --preset
+  web` create the GitHub repo too. `--no-github` and `--private` override it.
+- **Updates**: improve the preset (save it again), then `agk update` in each repo. A
+  repo cloned on a machine without the preset still updates the kit's files.
+- **Sharing**: a preset is a folder; make it a git repo and push it. Someone else
+  runs `agk preset add <its URL>`: agk shows the code it runs and the permissions it
+  gives Claude, asks first, and pins the commit. `agk preset pull web` fetches later
+  changes the same way.
+- **Copying a repo's setup**: `agk preset add <URL of a repo agk set up>` lists what
+  that repo has beyond the kit, and keeps the parts you pick as a preset of your own.
+- `agk preset list` shows your presets; `agk preset remove web` deletes one.
+
 Your own habits, the ones that hold in every repo, go in `~/.claude/CLAUDE.md`, not in
 the kit.
 

package/bin/agk.mjs

@@ -1,323 +1,56 @@
 #!/usr/bin/env node
 // agk: sets up git repos for Claude Code, and brings the kit's later changes into them.
-// - `agk setup` copies template/ into a folder, then the agent there follows BOOTSTRAP.md. Where
-//   the folder has one of the kit's files already, the kit's version goes next to it as
-//   <file>.kit, for the agent to merge. With --github it also creates the repo on GitHub, via gh.
-// - `agk update` updates the kit's files that a repo hasn't changed, and puts the kit's version
-//   next to the others as <file>.kit. The repo's .claude/agk.json says what the kit wrote.
+// - `agk setup` (lib/setup.mjs) copies template/, and a preset if any, into a folder; the agent
+//   there follows BOOTSTRAP.md.
+// - `agk update` (lib/update.mjs) brings in the kit's and the preset's later changes.
+// - `agk preset ...` (lib/preset-commands.mjs) saves, shares and fetches presets: a user's own
+//   setup, layered over the kit's (lib/presets.mjs).
 // Installed with `npm install -g @gonxped31/agent-kit` (or `npm link` in a clone); template/ is next
-// to this file.
-// AGK_GH=<path> runs that instead of gh, with node if it ends in .mjs (the kit's tests only).
-import { spawn, spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { PACKAGE, RECORD, SETUP_ONLY, VERSION, hashAt, kitCopy, kitFiles, newer, put, readRecord, remove, setUpAlready, writeRecord } from "../lib/kit.mjs";
-import { Failure, blank, clip, count, details, header, line, list, ok, out, showFailure, step, warn } from "../lib/ui.mjs";
-
-const NOTHING_CHANGED = "Nothing was changed.";
-
-const git = (cwd, ...args) => spawnSync("git", args, { cwd, encoding: "utf8" });
-const noGit = () => new Failure("git isn't installed, or isn't on the PATH", { hint: "The kit needs it: https://git-scm.com" });
-
-/** Runs a command without blocking (so the spinner moves). `error` is set if it couldn't start. */
-function run(cmd, args, options = {}) {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => (stdout += d));
-    child.stderr.on("data", (d) => (stderr += d));
-    child.on("error", (error) => resolve({ status: null, stdout, stderr, error }));
-    child.on("close", (status) => resolve({ status, stdout, stderr }));
-  });
-}
-
-function gh(...args) {
-  const env = { ...process.env, GH_PROMPT_DISABLED: "1" };
-  const fake = process.env.AGK_GH;
-  return fake?.endsWith(".mjs") ? run(process.execPath, [fake, ...args], { env }) : run(fake || "gh", args, { env });
-}
-
-/** The last lines of what a command said, to show under a failure. */
-const said = (r) => (r.stderr || r.stdout).trim().split(/\r?\n/).filter(Boolean).slice(-3);
-
-/** A command's options and its one folder (default: the current one). */
-function parse(cmd, args, allowed) {
-  const options = args.filter((a) => a.startsWith("-"));
-  const folders = args.filter((a) => !a.startsWith("-"));
-  const bad = options.find((o) => !allowed.includes(o));
-  if (bad) throw new Failure(`Unknown option '${bad}'`, { hint: "Run agk help for the options." });
-  if (folders.length > 1) throw new Failure(`${cmd} takes one folder, got ${folders.length}: ${folders.join(", ")}`);
-  const folder = path.resolve(folders[0] ?? ".");
-  return { options, folder, shown: path.relative(process.cwd(), folder) || "." };
-}
-
-/** The nearest folder at or above `dir` that exists. */
-function nearestExisting(dir) {
-  while (!fs.existsSync(dir)) dir = path.dirname(dir);
-  return dir;
-}
-
-/**
- * What setup would do in `root`, changing nothing: whether to create it and run git init, and
- * what to do with each of the kit's files. The folder is a repo's root (set it up as it is),
- * outside any repo (git init), or inside one: part of that project (refused: the hooks and
- * CLAUDE.md work only at a repo's root), or a new project that merely sits under it, such as
- * under a home folder that's a repo.
- */
-function inspect(root, shown) {
-  if (fs.existsSync(root) && !fs.statSync(root).isDirectory()) throw new Failure(`${root} is a file, not a folder`);
-  const base = nearestExisting(root);
-  const probe = git(base, "rev-parse", "--show-toplevel");
-  if (probe.error) throw noGit();
-  const plan = { exists: fs.existsSync(root), init: probe.status !== 0, note: "", origin: "" };
-  if (!plan.init) {
-    // Compare real paths: git resolves symlinks, and path.relative ignores case on Windows.
-    const top = fs.realpathSync.native(probe.stdout.trim());
-    const here = path.join(fs.realpathSync.native(base), path.relative(base, root));
-    if (path.relative(top, here) !== "") {
-      if (plan.exists && git(root, "ls-files", "-z").stdout) {
-        throw new Failure(`${root} holds files of the repo at ${top}`, {
-          hint: `The kit sets up a whole repo, from its root: run agk setup there. ${NOTHING_CHANGED}`,
-        });
-      }
-      plan.init = true;
-      plan.note = `It's inside the repo at ${top} but holds none of its files, so it gets a repo of its own.`;
-    } else {
-      plan.origin = git(root, "remote", "get-url", "origin").stdout?.trim() ?? "";
-    }
-  }
-
-  const place = shown === "." ? "here" : `in ${shown}`;
-  if (plan.exists && setUpAlready(root)) {
-    throw new Failure(`The kit is set up ${place} already`, { hint: `To bring in its changes since, run agk update. ${NOTHING_CHANGED}` });
-  }
-  // A file the folder has already stays as it is: the kit's version goes next to it, to merge.
-  plan.files = kitFiles().map((f) => {
-    const here = hashAt(root, f.to);
-    return { ...f, state: here === null ? "new" : here === f.hash ? "same" : "differs" };
-  });
-  if (plan.files.some((f) => f.to === SETUP_ONLY && f.state === "differs")) {
-    throw new Failure(`There's a ${SETUP_ONLY} ${place} already`, {
-      hint: `The setup's instructions go in that file, for Claude Code to follow: rename yours first.\n${NOTHING_CHANGED}`,
-    });
-  }
-  const inTheWay = plan.files.filter((f) => f.state === "differs" && fs.existsSync(path.join(root, kitCopy(f.to))));
-  if (inTheWay.length) {
-    throw new Failure(`${count(inTheWay.length, "file")} in the way ${place}`, {
-      details: clip(inTheWay.map((f) => kitCopy(f.to))),
-      hint: `The kit's version of a file you have goes next to it, as <file>.kit: move these aside first.\n${NOTHING_CHANGED}`,
-    });
-  }
-  return plan;
-}
-
-/** The GitHub repo name for a folder: GitHub allows letters, digits, ".", "-" and "_". */
-function repoName(root) {
-  const name = path.basename(root).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-  if (!name || /^\.+$/.test(name)) throw new Failure(`Can't make a GitHub repo name from the folder name "${path.basename(root)}"`);
-  return name;
-}
-
-/** The GitHub account gh is logged in to, once it's clear `name` is free there. */
-async function checkGitHub(name) {
-  const user = await gh("api", "user", "--jq", ".login");
-  if (user.error) {
-    throw new Failure("--github needs gh, GitHub's command line tool, and it isn't installed", {
-      hint: `Install it from https://cli.github.com and run gh auth login, or leave out --github. ${NOTHING_CHANGED}`,
-    });
-  }
-  if (user.status !== 0) {
-    throw new Failure("gh couldn't reach your GitHub account", {
-      details: said(user),
-      hint: `Run gh auth login (or check your connection), then run this again. ${NOTHING_CHANGED}`,
-    });
-  }
-  const login = user.stdout.trim();
-  const view = await gh("repo", "view", `${login}/${name}`, "--json", "url");
-  if (view.status === 0) {
-    throw new Failure(`github.com/${login}/${name} already exists`, {
-      hint: `Name the folder differently, or leave out --github. ${NOTHING_CHANGED}`,
-    });
-  }
-  if (!/could not resolve to a repository/i.test(view.stderr)) {
-    throw new Failure(`gh couldn't check whether github.com/${login}/${name} exists`, { details: said(view), hint: NOTHING_CHANGED });
-  }
-  return login;
-}
-
-const each = (n) => (n === 1 ? "it" : "each");
-
-async function setup(args) {
-  const { options, folder: root, shown } = parse("setup", args, ["--github", "--public"]);
-  const github = options.includes("--github");
-  const visibility = options.includes("--public") ? "public" : "private";
-  if (visibility === "public" && !github) throw new Failure("--public goes with --github");
-  header(VERSION, "Setting up a repo for Claude Code");
-
-  // 1. Look, changing nothing: anything that would stop the setup stops it here.
-  const plan = inspect(root, shown);
-  let repo = "";
-  if (github) {
-    if (plan.origin) {
-      throw new Failure(`This repo already has a remote origin: ${plan.origin}`, { hint: `Leave out --github. ${NOTHING_CHANGED}` });
-    }
-    const name = repoName(root);
-    await step("Checking GitHub", async () => {
-      repo = `${await checkGitHub(name)}/${name}`;
-      return `GitHub: github.com/${repo} is free`;
-    });
-  }
-
-  // 2. Set up the folder.
-  if (!plan.exists) {
-    fs.mkdirSync(root, { recursive: true });
-    ok(`Created the folder ${out.cyan(shown)}`);
-  }
-  if (plan.init) {
-    const r = git(root, "init", "-q", "-b", "main");
-    if (r.status !== 0) throw new Failure("git init failed", { details: said(r) });
-    ok("Created a git repo on main");
-    if (plan.note) warn(plan.note);
-  }
-  const fresh = plan.files.filter((f) => f.state === "new");
-  const same = plan.files.filter((f) => f.state === "same");
-  const differs = plan.files.filter((f) => f.state === "differs");
-  for (const f of fresh) put(root, f.to, f.text);
-  for (const f of differs) put(root, kitCopy(f.to), f.text);
-  writeRecord(root, plan.files);
-  const total = plan.files.length;
-  if (fresh.length === total) {
-    ok(`Copied the kit's ${total} files ${out.dim("(CLAUDE.md, BOOTSTRAP.md, .claude/, scripts/ and more)")}`);
-  } else {
-    ok(`Copied ${fresh.length} of the kit's ${total} files`);
-    if (same.length) ok(`${count(same.length, "file")} already here, the same as the kit's`);
-    if (differs.length) {
-      warn(`${count(differs.length, "file")} already here, different: the kit's version is next to ${each(differs.length)}, as <file>.kit`);
-      details(differs.map((f) => f.to));
-    }
-  }
-
-  // 3. Create the GitHub repo. Its first push waits for the bootstrap's first commit.
-  if (github) {
-    await step(`Creating github.com/${repo} (${visibility})`, async () => {
-      const r = await gh("repo", "create", repo, `--${visibility}`, "--source", root, "--remote", "origin");
-      if (r.status !== 0) {
-        throw new Failure("GitHub didn't create the repo", {
-          details: said(r),
-          hint: `The local setup is done. To try again, from the folder:\ngh repo create ${repo} --${visibility} --source . --remote origin`,
-        });
-      }
-      return `Created github.com/${repo} (${visibility}) as remote origin`;
-    });
-  }
-
-  const cd = shown === "." ? [] : [`cd ${/\s/.test(shown) ? `"${shown}"` : shown}`];
-  const merging = differs.length ? ", merges the .kit files into yours" : "";
-  const push = github ? `\nThen it pushes main to github.com/${repo}, once you agree.` : "";
-  list("Next", [
-    ...cd,
-    `Open Claude Code (${out.cyan("claude")}) and say ${out.cyan('"follow BOOTSTRAP.md"')}\nIt asks a few questions${merging}, fills in the setup and makes the first commit.${push}`,
-  ]);
-}
-
-/**
- * Compares each of the kit's files with the repo's and with the record of what the kit wrote:
- * - the kit's file hasn't changed, or the repo has it already: nothing to do;
- * - the repo didn't change it: updated (or added, if the kit's is new);
- * - the repo changed it: the kit's version goes next to it, as <file>.kit, to merge;
- * - the repo deleted it: it stays deleted.
- * A file the kit no longer has is removed, unless the repo changed it.
- * Without a record (agk 0.1.0 kept none), a file that differs from the kit's counts as changed.
- */
-async function update(args) {
-  const { folder, shown } = parse("update", args, []);
-  header(VERSION, "Bringing the kit's changes into a repo");
-  if (!fs.existsSync(folder) || !fs.statSync(folder).isDirectory()) throw new Failure(`${shown} isn't a folder`);
-  const probe = git(folder, "rev-parse", "--show-toplevel");
-  if (probe.error) throw noGit();
-  if (probe.status !== 0) {
-    throw new Failure(`${shown === "." ? "This folder" : shown} isn't in a git repo`, {
-      hint: "agk update works in a repo the kit set up. To set one up, run agk setup.",
-    });
-  }
-  const root = path.resolve(probe.stdout.trim());
-  const record = readRecord(root);
-  if (!record && !setUpAlready(root)) {
-    throw new Failure("The kit isn't set up in this repo", { hint: `To set it up, run agk setup. ${NOTHING_CHANGED}` });
-  }
-  if (record && newer(record.version, VERSION)) {
-    throw new Failure(`This repo has the kit of agk v${record.version}, newer than this agk (v${VERSION})`, {
-      hint: `Update agk first: npm install -g ${PACKAGE} (or git pull, in a clone). ${NOTHING_CHANGED}`,
-    });
-  }
-
-  const files = kitFiles().filter((f) => f.to !== SETUP_ONLY);
-  const wrote = record?.files ?? {};
-  const c = { updated: [], added: [], merge: [], deleted: [], removed: [], kept: [] };
-  for (const f of files) {
-    const here = hashAt(root, f.to);
-    const before = wrote[f.to] ?? null;
-    if ((record && f.hash === before) || here === f.hash) continue;
-    if (here === null) (before === null ? c.added : c.deleted).push(f.to);
-    else (here === before ? c.updated : c.merge).push(f.to);
-  }
-  const kit = new Map(files.map((f) => [f.to, f]));
-  for (const [rel, before] of Object.entries(wrote)) {
-    const here = kit.has(rel) || rel === SETUP_ONLY ? null : hashAt(root, rel);
-    if (here !== null) (here === before ? c.removed : c.kept).push(rel);
-  }
-
-  for (const rel of [...c.updated, ...c.added]) put(root, rel, kit.get(rel).text);
-  for (const rel of c.merge) put(root, kitCopy(rel), kit.get(rel).text);
-  for (const rel of c.removed) remove(root, rel);
-  const recorded = writeRecord(root, files);
-
-  if (!record) warn(`No ${RECORD} (agk 0.1.0 kept none), so a file that differs from the kit's counts as yours`);
-  const report = (paths, say, text) => {
-    if (!paths.length) return;
-    say(text(count(paths.length, "file"), paths.length));
-    details(paths);
-  };
-  report(c.updated, ok, (n) => `Updated ${n} you hadn't changed`);
-  report(c.added, ok, (n) => `Added ${n} new in the kit`);
-  report(c.removed, ok, (n) => `Removed ${n} the kit no longer has`);
-  const how = record ? "changed both here and in the kit" : "differ from the kit's";
-  report(c.merge, warn, (n, k) => `${n} ${how}: the kit's version is next to ${each(k)}, as <file>.kit`);
-  report(c.kept, warn, (n, k) => `Kept ${n} you changed, though the kit no longer has ${k === 1 ? "it" : "them"}`);
-  report(c.deleted, warn, (n, k) => `Left ${n} deleted, as you had ${k === 1 ? "it" : "them"}, though the kit changed ${k === 1 ? "it" : "them"}`);
-  const touched = c.updated.length + c.added.length + c.removed.length + c.merge.length;
-  if (!touched && !recorded) {
-    ok(`Up to date with the kit (v${VERSION})`);
-    blank();
-    return;
-  }
-  if (recorded) ok(`Recorded the kit's files (v${VERSION}) in ${RECORD}`);
-  const merge = `Open Claude Code (${out.cyan("claude")}) and say ${out.cyan('"merge the .kit files"')}\nIt brings what's new in each into your file, then deletes the .kit file.\ndoctor reports them until then.`;
-  list("Next", [
-    ...(c.merge.length ? [merge] : []),
-    `Review the changes (${out.cyan("git status")}), then commit them on a branch, as any change`,
-  ]);
-}
+// to this file. AGK_GH=<path> runs that instead of gh (the kit's tests only).
+import { VERSION } from "../lib/kit.mjs";
+import { presetCommand } from "../lib/preset-commands.mjs";
+import { setup } from "../lib/setup.mjs";
+import { Failure, blank, header, line, out, showFailure } from "../lib/ui.mjs";
+import { update } from "../lib/update.mjs";
 
 function help() {
   header(VERSION, "Sets up git repos for Claude Code");
   const row = (a, b) => line(`  ${out.cyan(a.padEnd(30))}${b}`);
-  line(out.bold("Usage"));
-  row("agk setup [folder] [options]", "Set up folder (default: this one): git init if needed,");
-  row("", "then the kit's files. For a file it has already, the");
-  row("", "kit's version goes next to it, as <file>.kit, to merge");
-  row("agk update [folder]", "Bring in the kit's changes: updates the files the repo");
-  row("", "hasn't changed, and puts the kit's next to the others");
-  row("agk help", "Show this help");
-  row("agk --version", "Print the version");
-  blank();
-  line(out.bold("Setup options"));
-  row("--github", "Also create the repo on GitHub (with gh), as remote origin");
-  row("--public", "With --github: make it public (default: private)");
-  blank();
+  const section = (title, rows) => {
+    line(out.bold(title));
+    for (const [a, b] of rows) row(a, b);
+    blank();
+  };
+  section("Usage", [
+    ["agk setup [folder] [options]", "Set up folder (default: this one): git init if needed,"],
+    ["", "then the kit's files. For a file it has already, the"],
+    ["", "kit's version goes next to it, as <file>.kit, to merge"],
+    ["agk update [folder]", "Bring in the kit's changes: updates the files the repo"],
+    ["", "hasn't changed, and puts the kit's next to the others"],
+    ["agk preset <command>", "Your own setup on top of the kit's (below)"],
+    ["agk help", "Show this help"],
+    ["agk --version", "Print the version"],
+  ]);
+  section("Setup options", [
+    ["--github", "Also create the repo on GitHub (with gh), as remote origin"],
+    ["--public, --private", "With --github: its visibility (default: private)"],
+    ["--preset <name>", "Set up with that preset"],
+    ["--no-preset", "Leave out your default preset"],
+    ["--no-github", "No GitHub repo, even if the preset asks for one"],
+  ]);
+  section("Presets", [
+    ["preset save <name> [folder]", "Save what a repo has beyond the kit, as a preset"],
+    ["", "(--list, --only 1,3-5, --all; --github [--public]: defaults)"],
+    ["preset list", "Your presets"],
+    ["preset add <git-url|folder>", "Add a shared preset, or copy the setup of a repo agk"],
+    ["", "set up (--name <name>, --yes)"],
+    ["preset pull <name>", "Fetch a shared preset's changes, for you to review"],
+    ["preset remove <name>", "Delete a preset (repos set up with it keep their files)"],
+  ]);
   line(out.bold("Examples"));
-  for (const e of ["agk setup", "agk setup my-app --github", "agk update"]) line(`  ${out.dim("$")} ${e}`);
+  for (const e of ["agk setup", "agk setup my-app --github", "agk update", "agk preset save web", "agk setup shop --preset web"]) {
+    line(`  ${out.dim("$")} ${e}`);
+  }
   blank();
 }
 
@@ -328,6 +61,8 @@ async function main([cmd, ...args]) {
       return wantsHelp ? help() : setup(args);
     case "update":
       return wantsHelp ? help() : update(args);
+    case "preset":
+      return wantsHelp ? help() : presetCommand(args);
     case undefined:
     case "help":
     case "--help":

package/lib/cli.mjs

@@ -0,0 +1,90 @@
+// What agk's commands share: running git and gh, reading arguments, asking the user.
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { Failure, ask, interactive } from "./ui.mjs";
+
+export const NOTHING_CHANGED = "Nothing was changed.";
+
+export const git = (cwd, ...args) => spawnSync("git", args, { cwd, encoding: "utf8" });
+export const noGit = () => new Failure("git isn't installed, or isn't on the PATH", { hint: "The kit needs it: https://git-scm.com" });
+
+/** Runs a command without blocking (so the spinner moves). `error` is set if it couldn't start. */
+export function run(cmd, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (error) => resolve({ status: null, stdout, stderr, error }));
+    child.on("close", (status) => resolve({ status, stdout, stderr }));
+  });
+}
+
+/** gh, or the command in AGK_GH (run with node if it ends in .mjs: the kit's tests only). */
+export function gh(...args) {
+  const env = { ...process.env, GH_PROMPT_DISABLED: "1" };
+  const fake = process.env.AGK_GH;
+  return fake?.endsWith(".mjs") ? run(process.execPath, [fake, ...args], { env }) : run(fake || "gh", args, { env });
+}
+
+/** The last lines of what a command said, to show under a failure. */
+export const said = (r) => (r.stderr || r.stdout).trim().split(/\r?\n/).filter(Boolean).slice(-3);
+
+export const each = (n) => (n === 1 ? "it" : "each");
+
+/**
+ * A command's arguments: `flags` take no value, `values` take one (`--preset web` or
+ * `--preset=web`), and up to `max` positional arguments, described by `what` when there are more.
+ */
+export function parse(cmd, args, { flags = [], values = [], max = 1, what = "one folder" } = {}) {
+  const opts = new Set();
+  const vals = {};
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("-") || a === "-") {
+      pos.push(a);
+      continue;
+    }
+    const [name, inline] = a.split(/=(.*)/s);
+    if (values.includes(name)) {
+      const value = inline ?? args[++i];
+      if (value === undefined || value === "" || value.startsWith("-")) throw new Failure(`${name} needs a value`, { hint: "Run agk help for the options." });
+      vals[name] = value;
+    } else if (flags.includes(name) && inline === undefined) {
+      opts.add(name);
+    } else {
+      throw new Failure(`Unknown option '${a}'`, { hint: "Run agk help for the options." });
+    }
+  }
+  if (pos.length > max) throw new Failure(`${cmd} takes ${what}, got ${pos.length}: ${pos.join(", ")}`);
+  return { opts, vals, pos };
+}
+
+/** Both of two options that exclude each other: refused. */
+export function exclusive(opts, a, b) {
+  if (opts.has(a) && opts.has(b)) throw new Failure(`${a} and ${b} don't go together`);
+}
+
+export const shownPath = (folder) => path.relative(process.cwd(), folder) || ".";
+
+/** The root of the git repo `folder` is in. */
+export function repoRoot(folder, command) {
+  const shown = shownPath(folder);
+  const probe = git(folder, "rev-parse", "--show-toplevel");
+  if (probe.error) throw noGit();
+  if (probe.status !== 0) {
+    throw new Failure(`${shown === "." ? "This folder" : shown} isn't in a git repo`, {
+      hint: `agk ${command} works in a repo the kit set up. To set one up, run agk setup.`,
+    });
+  }
+  return path.resolve(probe.stdout.trim());
+}
+
+/** The user's OK: --yes, or a yes in a terminal. Without a terminal, --yes is needed. */
+export async function confirm(question, opts) {
+  if (opts.has("--yes")) return true;
+  if (!interactive) throw new Failure(`${question.replace(/\?$/, "")}: that needs your OK`, { hint: "Run it in a terminal to answer, or add --yes." });
+  return /^y(es)?$/i.test(await ask(`${question} [y/N]`));
+}

package/lib/kit.mjs

@@ -25,15 +25,15 @@ const RENAMED = { "CLAUDE.template.md": "CLAUDE.md", "dot-claude": ".claude" };
 /** Where the kit puts its version of a file a repo already has, or changed: next to it. */
 export const kitCopy = (rel) => `${rel}.kit`;
 
-function walk(dir, rel = "") {
+export function walk(dir, rel = "") {
   return fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).flatMap((e) => {
     const child = path.join(rel, e.name);
     return e.isDirectory() ? walk(dir, child) : [child];
   });
 }
 
-const lf = (file) => fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
-const hash = (text) => crypto.createHash("sha256").update(text).digest("hex");
+export const lf = (file) => fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+export const hash = (text) => crypto.createHash("sha256").update(text).digest("hex");
 
 /**
  * The kit's files, sorted by `to`: where each is in template/ (`from`), its path in a repo (`to`,
@@ -75,7 +75,7 @@ export function remove(root, rel) {
 }
 
 /** A path in a repo, as the record may hold one: relative, inside the repo, and not in .git. */
-const inRepo = (rel) => !/^[\\/]|^[a-z]:|\\/i.test(rel) && !rel.split("/").some((p) => p === ".." || p === "") && !/^\.git(\/|$)/.test(rel);
+export const inRepo = (rel) => !/^[\\/]|^[a-z]:|\\/i.test(rel) && !rel.split("/").some((p) => p === ".." || p === "") && !/^\.git(\/|$)/.test(rel);
 
 /** A repo's record, or null if it has none. */
 export function readRecord(root) {
@@ -86,11 +86,14 @@ export function readRecord(root) {
     record = JSON.parse(fs.readFileSync(file, "utf8"));
   } catch {}
   const files = record?.files;
+  const preset = record?.preset;
   const valid =
     typeof record?.version === "string" &&
     files &&
     typeof files === "object" &&
-    Object.entries(files).every(([rel, h]) => inRepo(rel) && typeof h === "string");
+    Object.entries(files).every(([rel, h]) => inRepo(rel) && typeof h === "string") &&
+    (preset === undefined ||
+      (typeof preset?.name === "string" && Array.isArray(preset.files ?? []) && (preset.files ?? []).every((rel) => typeof rel === "string" && inRepo(rel))));
   if (!valid) {
     throw new Failure(`${RECORD} isn't what agk wrote`, {
       hint: `agk reads it to tell the files you changed. Restore it from git, or delete it to update\nas if the repo had none. Nothing was changed.`,
@@ -99,12 +102,18 @@ export function readRecord(root) {
   return record;
 }
 
-/** Records the kit's files (but the setup's instructions) in a repo. False if it held that already. */
-export function writeRecord(root, files) {
+/**
+ * Records the files agk wrote (all but the setup's instructions) in a repo, and the preset they
+ * came with. `keep` holds entries to keep as they are (a preset's files, when it's missing).
+ * False if the record held all that already.
+ */
+export function writeRecord(root, files, { preset = null, keep = {} } = {}) {
+  const wrote = { ...keep, ...Object.fromEntries(files.filter((f) => f.to !== SETUP_ONLY).map((f) => [f.to, f.hash])) };
   const record = {
     about: "Written by agk setup and agk update: the kit's files as it wrote them, so agk update can tell the ones you changed.",
     version: VERSION,
-    files: Object.fromEntries(files.filter((f) => f.to !== SETUP_ONLY).map((f) => [f.to, f.hash])),
+    ...(preset && { preset }),
+    files: Object.fromEntries(Object.entries(wrote).sort(([a], [b]) => (a < b ? -1 : 1))),
   };
   const text = `${JSON.stringify(record, null, 2)}\n`;
   const file = path.join(root, RECORD);