@gonxped31/agent-kit 0.2.0 → 0.3.0

package/lib/presets.mjs

@@ -0,0 +1,221 @@
+// Presets: a user's own setup, layered over the kit's. One folder per preset, on the user's machine:
+//
+//   ~/.config/agk/presets/<name>/     ($XDG_CONFIG_HOME/agk/presets when it's set)
+//     preset.json    { name, savedWith, from, defaults: { github, visibility } }
+//     files/         whole files, at their path in a repo (one can replace a kit file)
+//     additions/     additions to the kit's files, at the same paths (see merge.mjs)
+//
+// A preset added from a git repo is a clone of it; git config agk.source in the clone names the
+// repo, and its HEAD is the version in use until `agk preset pull`.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { RECORD, SETUP_ONLY, hash, inRepo, lf, walk } from "./kit.mjs";
+import { additionsOf, buildAdditions, describeAddition, kindOf, mergeAdditions } from "./merge.mjs";
+import { Failure } from "./ui.mjs";
+
+export function presetsDir() {
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "agk", "presets");
+}
+
+export const validName = (name) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && name.length <= 64;
+/** A preset under this name is used by agk setup unless told otherwise. */
+export const DEFAULT = "default";
+
+const gitOut = (dir, ...args) => {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf8" });
+  return r.status === 0 ? r.stdout.trim() : null;
+};
+const isRepo = (dir) => fs.existsSync(path.join(dir, ".git"));
+
+/** The files under a preset's subfolder, as { to, text }. */
+function filesUnder(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return walk(dir).map((rel) => ({ to: rel.split(path.sep).join("/"), text: lf(path.join(dir, rel)) }));
+}
+
+/** The preset in `dir`, named `name`. Throws a Failure if it can't be used. */
+export function loadPresetAt(dir, name) {
+  let meta;
+  try {
+    meta = JSON.parse(fs.readFileSync(path.join(dir, "preset.json"), "utf8"));
+  } catch (e) {
+    throw new Failure(`The preset ${name} has no readable preset.json`, { details: [e.message], hint: `It's in ${dir}.` });
+  }
+  const files = filesUnder(path.join(dir, "files"));
+  const additions = filesUnder(path.join(dir, "additions"));
+  const bad = [...files, ...additions].find((f) => !inRepo(f.to) || f.to === SETUP_ONLY || f.to === RECORD || f.to.endsWith(".kit"));
+  if (bad) throw new Failure(`The preset ${name} has a file agk won't write: ${bad.to}`, { hint: `It's in ${dir}.` });
+  const repo = isRepo(dir);
+  return {
+    name,
+    dir,
+    meta: meta && typeof meta === "object" ? meta : {},
+    files,
+    additions,
+    source: repo ? gitOut(dir, "config", "--get", "agk.source") : null,
+    commit: repo ? gitOut(dir, "rev-parse", "--short", "HEAD") : null,
+  };
+}
+
+/** The preset named `name`, or null if there's none. */
+export function loadPreset(name) {
+  const dir = path.join(presetsDir(), name);
+  return validName(name) && fs.existsSync(path.join(dir, "preset.json")) ? loadPresetAt(dir, name) : null;
+}
+
+/** Every preset, by name. One that can't be read comes with its `error`. */
+export function listPresets() {
+  const dir = presetsDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && validName(e.name) && fs.existsSync(path.join(dir, e.name, "preset.json")))
+    .map((e) => {
+      try {
+        return loadPresetAt(path.join(dir, e.name), e.name);
+      } catch (error) {
+        return { name: e.name, error };
+      }
+    })
+    .sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+/**
+ * The files agk writes: the kit's, with a preset's files and additions on top. Each is
+ * { to, text, hash, preset } (preset: the preset added or changed it). A preset's addition to a
+ * file that isn't there is skipped, with a warning.
+ */
+export function compose(kit, preset) {
+  const map = new Map(kit.map((f) => [f.to, { to: f.to, text: f.text, preset: false }]));
+  const warnings = [];
+  if (preset) {
+    for (const f of preset.files) map.set(f.to, { to: f.to, text: f.text, preset: true, replaces: map.has(f.to) });
+    for (const a of preset.additions) {
+      const base = map.get(a.to);
+      if (!base) {
+        warnings.push(`Preset ${preset.name} adds to ${a.to}, which the kit doesn't have: skipped`);
+        continue;
+      }
+      try {
+        map.set(a.to, { ...base, text: mergeAdditions(a.to, base.text, a.text), preset: true, extends: true });
+      } catch (e) {
+        warnings.push(`Preset ${preset.name}'s additions to ${a.to} don't parse (${e.message}): skipped`);
+      }
+    }
+  }
+  const files = [...map.values()].map((f) => ({ ...f, hash: hash(f.text) })).sort((a, b) => (a.to < b.to ? -1 : 1));
+  return { files, warnings };
+}
+
+/** What a preset brings, in words: "2 files of its own, 3 of the kit's extended, 1 replaced". */
+export function presetSummary(files) {
+  const own = files.filter((f) => f.preset && !f.replaces && !f.extends).length;
+  const extended = files.filter((f) => f.extends && !f.replaces).length;
+  const replaced = files.filter((f) => f.replaces).length;
+  const parts = [
+    own && `${own} file${own === 1 ? "" : "s"} of its own`,
+    extended && `${extended} of the kit's extended`,
+    replaced && `${replaced} replaced`,
+  ].filter(Boolean);
+  return parts.length ? parts.join(", ") : "nothing beyond the kit";
+}
+
+/** What the record says about the preset used. */
+export const presetRecord = (preset, files) => ({
+  name: preset.name,
+  ...(preset.source && { source: preset.source }),
+  ...(preset.commit && { commit: preset.commit }),
+  files: files.filter((f) => f.preset).map((f) => f.to),
+});
+
+// ---- Saving: what a repo has beyond the kit
+
+/** Where a repo's agent setup lives: files elsewhere are the project's own, never a preset's. */
+const IN_SETUP = (rel) =>
+  /^(\.claude|\.githooks|\.github|scripts\/hooks)\//.test(rel) || rel === ".gitignore" || rel === ".mcp.json";
+/** Setup files that are never a preset's: the record, personal settings, merges in waiting. */
+const NEVER = (rel) => rel === RECORD || rel === ".claude/settings.local.json" || rel.endsWith(".kit");
+
+/**
+ * What a repo has beyond the kit, as candidates for a preset:
+ * - { type: "file", to, text }: a setup file the kit doesn't have;
+ * - { type: "addition", to, item }: something added to one of the kit's files;
+ * - { type: "replace", to, text }: a kit file changed in a way additions can't hold (code).
+ * Files come from git: tracked, and untracked but not ignored.
+ */
+export function candidates(root, kit) {
+  const r = spawnSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd: root, encoding: "utf8" });
+  const listed = r.status === 0 ? [...new Set(r.stdout.split("\0").filter(Boolean))].sort() : [];
+  const kitPaths = new Set(kit.map((f) => f.to));
+  const isFile = (rel) => fs.existsSync(path.join(root, rel)) && fs.statSync(path.join(root, rel)).isFile();
+  const out = [];
+  for (const rel of listed) {
+    if (!kitPaths.has(rel) && IN_SETUP(rel) && !NEVER(rel) && isFile(rel)) out.push({ type: "file", to: rel, text: lf(path.join(root, rel)) });
+  }
+  for (const f of kit) {
+    if (f.to === SETUP_ONLY || !isFile(f.to)) continue;
+    const here = lf(path.join(root, f.to));
+    if (here === f.text) continue;
+    const items = additionsOf(f.to, here, f.text);
+    if (items?.length) out.push(...items.map((item) => ({ type: "addition", to: f.to, item })));
+    // CLAUDE.md always differs (the bootstrap fills it in), and the project's own text is no preset's.
+    else if (f.to !== "CLAUDE.md") out.push({ type: "replace", to: f.to, text: here });
+  }
+  return out;
+}
+
+export function describeCandidate(c) {
+  if (c.type === "file") return `file       ${c.to}`;
+  if (c.type === "replace") return `replaces   ${c.to} (the kit's version)`;
+  return `addition   ${c.to}  ${describeAddition(c.to, c.item)}`;
+}
+
+/** Writes a preset from chosen candidates, replacing what the folder had (but a .git). */
+export function writePreset(dir, meta, chosen) {
+  fs.mkdirSync(dir, { recursive: true });
+  for (const e of fs.readdirSync(dir)) if (e !== ".git") fs.rmSync(path.join(dir, e), { recursive: true, force: true });
+  const write = (rel, text) => {
+    fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+    fs.writeFileSync(path.join(dir, rel), text);
+  };
+  write("preset.json", `${JSON.stringify(meta, null, 2)}\n`);
+  const additions = new Map();
+  for (const c of chosen) {
+    if (c.type === "addition") {
+      if (!additions.has(c.to)) additions.set(c.to, []);
+      additions.get(c.to).push(c.item);
+    } else {
+      write(path.posix.join("files", c.to), c.text);
+    }
+  }
+  for (const [to, items] of additions) write(path.posix.join("additions", to), buildAdditions(to, items));
+  return { files: chosen.filter((c) => c.type !== "addition").length, additions: additions.size };
+}
+
+// ---- Trust: what a preset lets run, or lets Claude do
+
+/** The Claude hooks a settings file adds, and the commands it lets Claude run without asking. */
+function settingsPowers(text) {
+  try {
+    const s = JSON.parse(text);
+    const hooks = Object.values(s.hooks ?? {}).flatMap((entries) => (Array.isArray(entries) ? entries : []).flatMap((e) => (e.hooks ?? []).map((h) => h.command).filter(Boolean)));
+    return { hooks, allow: Array.isArray(s.permissions?.allow) ? s.permissions.allow : [] };
+  } catch {
+    return { hooks: [], allow: [] };
+  }
+}
+
+/** What in a preset can run code or widen what Claude may do, to show before using it. */
+export function powersOf(preset) {
+  const all = [...preset.files, ...preset.additions];
+  const code = preset.files.filter((f) => kindOf(f.to) === "code" || f.to.startsWith(".claude/hooks/")).map((f) => f.to);
+  const settings = all.filter((f) => f.to === ".claude/settings.json").map((f) => settingsPowers(f.text));
+  return {
+    code,
+    hooks: settings.flatMap((s) => s.hooks),
+    allow: settings.flatMap((s) => s.allow),
+    mcp: all.some((f) => f.to === ".mcp.json"),
+  };
+}

package/lib/setup.mjs

@@ -0,0 +1,205 @@
+// agk setup: copies the kit (and a preset, if any) into a folder, then the agent there follows
+// BOOTSTRAP.md. Where the folder has one of the 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.
+import fs from "node:fs";
+import path from "node:path";
+import { NOTHING_CHANGED, each, exclusive, gh, git, noGit, parse, said, shownPath } from "./cli.mjs";
+import { SETUP_ONLY, VERSION, hashAt, kitCopy, kitFiles, put, setUpAlready, writeRecord } from "./kit.mjs";
+import { DEFAULT, compose, loadPreset, presetRecord, presetSummary } from "./presets.mjs";
+import { Failure, clip, count, details, header, list, ok, out, step, warn } from "./ui.mjs";
+
+/** 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 file. 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, files) {
+  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 = files.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, leaveOut) {
+  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 ${leaveOut}. ${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 ${leaveOut}. ${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;
+}
+
+/** The preset to use: --preset's, else the default one unless --no-preset. */
+function choosePreset(opts, vals) {
+  const name = vals["--preset"];
+  if (name) {
+    const preset = loadPreset(name);
+    if (!preset) throw new Failure(`There's no preset named ${name}`, { hint: `agk preset list shows yours. ${NOTHING_CHANGED}` });
+    return { preset, note: "" };
+  }
+  if (opts.has("--no-preset")) return { preset: null, note: "" };
+  const preset = loadPreset(DEFAULT);
+  return { preset, note: preset ? out.dim(" (your default; --no-preset leaves it out)") : "" };
+}
+
+export async function setup(args) {
+  const { opts, vals, pos } = parse("setup", args, {
+    flags: ["--github", "--no-github", "--public", "--private", "--no-preset"],
+    values: ["--preset"],
+  });
+  exclusive(opts, "--github", "--no-github");
+  exclusive(opts, "--public", "--private");
+  if (vals["--preset"] && opts.has("--no-preset")) throw new Failure("--preset and --no-preset don't go together");
+  const root = path.resolve(pos[0] ?? ".");
+  const shown = shownPath(root);
+  header(VERSION, "Setting up a repo for Claude Code");
+
+  // 1. Look, changing nothing: anything that would stop the setup stops it here.
+  const { preset, note } = choosePreset(opts, vals);
+  const defaults = preset?.meta.defaults ?? {};
+  const github = opts.has("--github") || (!opts.has("--no-github") && defaults.github === true);
+  const visibility = opts.has("--public") || (!opts.has("--private") && defaults.visibility === "public") ? "public" : "private";
+  for (const flag of ["--public", "--private"]) if (opts.has(flag) && !github) throw new Failure(`${flag} goes with --github`);
+  const { files, warnings } = compose(kitFiles(), preset);
+  const plan = inspect(root, shown, files);
+  let repo = "";
+  if (github) {
+    // Said in every hint: how to do without GitHub, whether --github or the preset asked for it.
+    const leaveOut = opts.has("--github") ? "leave out --github" : `add --no-github (preset ${preset.name} asks for GitHub)`;
+    if (plan.origin) {
+      throw new Failure(`This repo already has a remote origin: ${plan.origin}`, { hint: `To set it up anyway, ${leaveOut}. ${NOTHING_CHANGED}` });
+    }
+    const name = repoName(root);
+    await step("Checking GitHub", async () => {
+      repo = `${await checkGitHub(name, leaveOut)}/${name}`;
+      return `GitHub: github.com/${repo} is free`;
+    });
+  }
+
+  // 2. Set up the folder.
+  if (preset) ok(`Preset ${out.cyan(preset.name)}: ${presetSummary(plan.files)}${note}`);
+  for (const w of warnings) warn(w);
+  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, { preset: preset && presetRecord(preset, plan.files) });
+  const total = plan.files.length;
+  const whose = preset ? "" : "the kit's ";
+  if (fresh.length === total) {
+    ok(preset ? `Copied all ${total} files` : `Copied the kit's ${total} files ${out.dim("(CLAUDE.md, BOOTSTRAP.md, .claude/, scripts/ and more)")}`);
+  } else {
+    ok(`Copied ${fresh.length} of ${whose}${total} files`);
+    if (same.length) ok(`${count(same.length, "file")} already here, the same as the ${preset ? "setup's" : "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}`,
+  ]);
+}

package/lib/ui.mjs

@@ -7,8 +7,12 @@
 // - The spinner moves only in a terminal. Elsewhere (a pipe, Claude Code) each step prints one
 //   line when it's done.
 
+import readline from "node:readline";
+
 const env = process.env;
 const tty = Boolean(process.stdout.isTTY) && env.TERM !== "dumb";
+/** True when someone can answer a question: both ends are a terminal. */
+export const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 
 function colorOn(stream) {
   if (env.FORCE_COLOR) return env.FORCE_COLOR !== "0";
@@ -42,6 +46,20 @@ export const warn = (text) => line(`${out.yellow(sym.warn)} ${text}`);
 export const details = (items) => {
   for (const item of clip(items)) line(`    ${item}`);
 };
+/** Asks a question in the terminal and returns the answer, trimmed. */
+export function ask(question) {
+  return new Promise((resolve) => {
+    // terminal: false: no raw mode, so it also reads a piped answer (the kit's tests).
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    process.stdout.write(`  ${out.bold(question)} `);
+    // Resolve before close(): it emits "close" at once, and a closed input answers "".
+    rl.once("line", (answer) => {
+      resolve(answer.trim());
+      rl.close();
+    });
+    rl.once("close", () => resolve(""));
+  });
+}
 /** "1 file", "2 files". */
 export const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
 

package/lib/update.mjs

@@ -0,0 +1,97 @@
+// agk update: brings the kit's (and the preset's) later changes into a repo the kit set up.
+//
+// It compares each file agk writes now with the repo's file and with the record of what agk wrote:
+// - agk's file hasn't changed, or the repo has it already: nothing to do;
+// - the repo didn't change it: updated (or added, if it's new);
+// - the repo changed it: agk's version goes next to it, as <file>.kit, to merge;
+// - the repo deleted it: it stays deleted.
+// A file agk no longer writes 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.
+// If the repo's preset isn't on this machine, the files it added or changed stay as they are.
+import fs from "node:fs";
+import path from "node:path";
+import { NOTHING_CHANGED, each, parse, repoRoot, shownPath } from "./cli.mjs";
+import { PACKAGE, RECORD, SETUP_ONLY, VERSION, hashAt, kitCopy, kitFiles, newer, put, readRecord, remove, setUpAlready, writeRecord } from "./kit.mjs";
+import { compose, loadPreset, presetRecord } from "./presets.mjs";
+import { Failure, blank, count, details, header, list, ok, out, warn } from "./ui.mjs";
+
+export async function update(args) {
+  const { pos } = parse("update", args);
+  const folder = path.resolve(pos[0] ?? ".");
+  const shown = shownPath(folder);
+  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 root = repoRoot(folder, "update");
+  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}`,
+    });
+  }
+
+  // The preset the repo was set up with, if it's on this machine. If not, its files are left out.
+  const used = record?.preset;
+  const preset = used ? loadPreset(used.name) : null;
+  const skip = new Set(used && !preset ? used.files ?? [] : []);
+  const composed = compose(kitFiles(), preset);
+  const files = composed.files.filter((f) => f.to !== SETUP_ONLY && !skip.has(f.to));
+  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 ours = new Map(files.map((f) => [f.to, f]));
+  for (const [rel, before] of Object.entries(wrote)) {
+    const here = ours.has(rel) || skip.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, ours.get(rel).text);
+  for (const rel of c.merge) put(root, kitCopy(rel), ours.get(rel).text);
+  for (const rel of c.removed) remove(root, rel);
+  const keep = Object.fromEntries([...skip].filter((rel) => rel in wrote).map((rel) => [rel, wrote[rel]]));
+  const recorded = writeRecord(root, files, { preset: preset ? presetRecord(preset, files) : used ?? null, keep });
+
+  if (!record) warn(`No ${RECORD} (agk 0.1.0 kept none), so a file that differs from the kit's counts as yours`);
+  if (used && !preset) {
+    warn(
+      `This repo uses preset ${used.name}, which isn't on this machine: its ${count(skip.size, "file")} stay as they are` +
+        (used.source ? `\n    To get it: agk preset add ${used.source}` : ""),
+    );
+  }
+  for (const w of composed.warnings) warn(w);
+  const source = preset ? `the kit or preset ${preset.name}` : "the kit";
+  const report = (paths, say, text) => {
+    if (!paths.length) return;
+    say(text(count(paths.length, "file"), paths.length));
+    details(paths);
+  };
+  const them = (k) => (k === 1 ? "it" : "them");
+  report(c.updated, ok, (n) => `Updated ${n} you hadn't changed`);
+  report(c.added, ok, (n) => `Added ${n} new in ${source}`);
+  report(c.removed, ok, (n) => `Removed ${n} ${source} no longer has`);
+  const how = record ? `changed both here and in ${source}` : "differ from the kit's";
+  report(c.merge, warn, (n, k) => `${n} ${how}: the ${preset ? "new" : "kit's"} version is next to ${each(k)}, as <file>.kit`);
+  report(c.kept, warn, (n, k) => `Kept ${n} you changed, though ${source} no longer has ${them(k)}`);
+  report(c.deleted, warn, (n, k) => `Left ${n} deleted, as you had ${them(k)}, though ${source} changed ${them(k)}`);
+  const touched = c.updated.length + c.added.length + c.removed.length + c.merge.length;
+  if (!touched && !recorded) {
+    ok(`Up to date with ${preset ? `the kit (v${VERSION}) and preset ${preset.name}` : `the kit (v${VERSION})`}`);
+    blank();
+    return;
+  }
+  if (recorded) ok(preset ? `Recorded the files (v${VERSION}, preset ${preset.name}) in ${RECORD}` : `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`,
+  ]);
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonxped31/agent-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sets up git repos for Claude Code, and keeps them up to date: a short CLAUDE.md, git and todo skills, hooks and checks.",
   "license": "MIT",
   "keywords": [

package/template/BOOTSTRAP.md

@@ -15,6 +15,9 @@ Find out on your own:
   `agk setup --github` adds an empty GitHub repo as `origin`.
 - The stack, from what's there: `package.json`, `pyproject.toml`, `go.mod`,
   `Cargo.toml`, a README.
+- The preset, if `.claude/agk.json` names one: the user's own setup, added to the
+  kit's. Keep what it added, and don't ask what it answers already (check steps say
+  how to test, for example).
 - Uncommitted work (`git status --short`) in `scripts/`, `docs/` or `.claude/` that
   isn't the kit's (`.claude/agk.json` lists the kit's files): step 6 stages those
   folders whole, so ask the user to commit it first.

package/template/dot-claude/skills/agent-setup/SKILL.md

@@ -67,3 +67,7 @@ agent-kit wrote the files listed in `.claude/agk.json`; change them as the repo
 `agk update` brings in the kit's later changes. Where the repo changed a file, it puts
 the kit's version next to it as `<file>.kit`: merge what's new into the file, keeping
 the repo's changes, then delete the `.kit` file (`doctor` reports it until then).
+
+To reuse this repo's setup in new repos, the user can save it as a preset:
+`agk preset save <name> --list` shows what it has beyond the kit. Help them pick what's
+generic, then `--only <numbers>`.