@gonxped31/agent-kit 0.0.0-stage → 0.2.0

package/template/scripts/check.json

@@ -0,0 +1,5 @@
+{
+  "steps": [
+    { "name": "doctor", "run": "node scripts/doctor.mjs" }
+  ]
+}

package/template/scripts/check.mjs

@@ -0,0 +1,50 @@
+// Runs the project's checks, listed in scripts/check.json. Prints only what failed, then OK or FAIL.
+// Usage: node scripts/check.mjs [--fast] [--verbose]
+//   --fast     skips steps marked "slow" (the pre-commit hook runs this)
+//   --verbose  prints every step's full output
+// A step: { "name": "test", "run": "npm test", "slow": true, "tail": 30 }. When it fails, the
+// last `tail` lines of its output are printed (default 20).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const fast = process.argv.includes("--fast");
+const verbose = process.argv.includes("--verbose");
+const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+let steps;
+try {
+  ({ steps } = JSON.parse(fs.readFileSync(path.join(ROOT, "scripts", "check.json"), "utf8")));
+  if (!Array.isArray(steps) || !steps.every((s) => typeof s.name === "string" && typeof s.run === "string")) {
+    throw new Error('needs a "steps" array of { "name", "run" }');
+  }
+} catch (e) {
+  console.log(`scripts/check.json: ${e.message}`);
+  console.log("FAIL");
+  process.exit(1);
+}
+
+const start = Date.now();
+let ran = 0;
+let failed = 0;
+for (const step of steps) {
+  if (fast && step.slow) continue;
+  ran++;
+  const r = spawnSync(step.run, { cwd: ROOT, shell: true, encoding: "utf8", maxBuffer: 1 << 28 });
+  const out = strip(`${r.stdout ?? ""}${r.stderr ?? ""}`).trimEnd();
+  if (verbose) console.log(`$ ${step.run}\n${out}`);
+  if (r.status === 0) continue;
+  failed++;
+  console.log(`${step.name}: FAIL`);
+  if (verbose) continue;
+  const lines = out.split(/\r?\n/);
+  const tail = lines.slice(-(step.tail ?? 20));
+  if (lines.length > tail.length) console.log(`  (${lines.length - tail.length} lines above; --verbose shows them)`);
+  for (const line of tail) console.log(`  ${line}`);
+}
+
+const secs = ((Date.now() - start) / 1000).toFixed(1);
+console.log(failed ? "FAIL" : `OK (${ran} step${ran === 1 ? "" : "s"}, ${secs}s)`);
+process.exit(failed ? 1 : 0);

package/template/scripts/doctor.mjs

@@ -0,0 +1,177 @@
+// Checks the agent setup: size limits, dead paths, unfilled placeholders, hooks turned on, and
+// the kit's versions of files (<file>.kit) still to merge.
+// Prints one line per problem, then OK or FAIL. The limits are the agent-setup skill's:
+// change them here, with the reason in the commit.
+// Usage: node scripts/doctor.mjs
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LIMITS = {
+  rootWords: 800, // the root CLAUDE.md: in context on every turn
+  nestedWords: 400, // a folder's CLAUDE.md: loaded when the agent works in that folder
+  descriptionWords: 30, // a skill's description: in context in every session
+  skillLines: 100, // a SKILL.md: loaded when the skill is used
+};
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const problems = [];
+const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), "utf8").replace(/\r\n/g, "\n");
+const words = (text) => text.split(/\s+/).filter(Boolean).length;
+
+function git(...args) {
+  try {
+    return execFileSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null;
+  }
+}
+
+/** A frontmatter field's value, including folded (`>`) and indented continuation lines. */
+function field(front, key) {
+  const lines = front.split("\n");
+  const i = lines.findIndex((l) => l.startsWith(`${key}:`));
+  if (i < 0) return undefined;
+  let value = lines[i].slice(key.length + 1).trim().replace(/^[>|][-+]?$/, "");
+  for (const l of lines.slice(i + 1)) {
+    if (!/^\s/.test(l)) break;
+    value += ` ${l.trim()}`;
+  }
+  return value.trim().replace(/^(["'])(.*)\1$/, "$2");
+}
+
+/** The lines outside fenced code blocks, with their line numbers. */
+function proseLines(text) {
+  let fenced = false;
+  const out = [];
+  text.split("\n").forEach((line, i) => {
+    if (/^\s*(```|~~~)/.test(line)) fenced = !fenced;
+    else if (!fenced) out.push({ line, n: i + 1 });
+  });
+  return out;
+}
+
+// Tracked and untracked-but-not-ignored files, so dependencies and build output are never walked.
+const listed = git("ls-files", "-z", "--cached", "--others", "--exclude-standard");
+if (listed === null) problems.push("not a git repository");
+const files = (listed ?? "").split("\0").filter((f) => f && exists(f));
+const markdown = files.filter((f) => f.endsWith(".md"));
+const isInstructions = (f) => path.posix.basename(f) === "CLAUDE.md";
+
+// ---- CLAUDE.md files: size, placeholders, @-imports
+if (!exists("CLAUDE.md")) problems.push("CLAUDE.md: missing at the root");
+for (const f of markdown.filter(isInstructions)) {
+  const text = read(f);
+  const max = f === "CLAUDE.md" ? LIMITS.rootWords : LIMITS.nestedWords;
+  const n = words(text);
+  if (n > max) problems.push(`${f}: ${n} words (max ${max}); move detail into a skill, a folder's CLAUDE.md or docs/`);
+  const placeholder = /\{\{[^}]*\}\}/.exec(text);
+  if (placeholder) problems.push(`${f}: unfilled placeholder ${placeholder[0]}`);
+  for (const { line, n: ln } of proseLines(text)) {
+    if (/(^|\s)@[^\s@]*[/.][^\s@]*/.test(line.replace(/`[^`]*`/g, ""))) {
+      problems.push(`${f}:${ln}: an @-import loads that file on every turn; name the path in backticks instead`);
+    }
+  }
+}
+
+// ---- Skills: frontmatter, description, size
+const skillsDir = path.join(ROOT, ".claude", "skills");
+const skillNames = fs.existsSync(skillsDir)
+  ? fs.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
+  : [];
+let descriptionWords = 0;
+for (const name of skillNames) {
+  const rel = `.claude/skills/${name}/SKILL.md`;
+  if (!exists(rel)) {
+    problems.push(`${rel}: missing`);
+    continue;
+  }
+  const text = read(rel).trimEnd();
+  const front = /^---\n([\s\S]*?)\n---/.exec(text)?.[1];
+  if (front === undefined) {
+    problems.push(`${rel}: no frontmatter (name, description)`);
+    continue;
+  }
+  const declared = field(front, "name");
+  if (declared !== name) problems.push(`${rel}: name is "${declared ?? ""}", must be "${name}" (its folder)`);
+  const description = field(front, "description") ?? "";
+  const n = words(description);
+  descriptionWords += n;
+  if (!n) problems.push(`${rel}: no description`);
+  else if (n > LIMITS.descriptionWords) problems.push(`${rel}: description is ${n} words (max ${LIMITS.descriptionWords})`);
+  else if (!/\buse (when|whenever|before|after|for)\b/i.test(description)) problems.push(`${rel}: description must say when to use it ("Use when ...")`);
+  const lines = text.split("\n").length;
+  if (lines > LIMITS.skillLines) problems.push(`${rel}: ${lines} lines (max ${LIMITS.skillLines}); move reference into files next to it`);
+}
+
+// ---- Paths named in agent docs must exist
+/**
+ * Reports a path that doesn't exist. Links are always checked. A code span can be anything
+ * (`origin/main`, `user.name`), so it counts as a path only when it has a slash and its first
+ * folder exists next to the file or at the root.
+ */
+function checkPath(from, n, raw, isLink) {
+  const p = raw.replace(/[#?].*$/, "").replace(/:\d+(:\d+)?$/, "");
+  if (!p || /^[a-z][a-z0-9+.-]*:/i.test(p) || /[\s<>*{}$|"'`()=\\]/.test(p) || /^[~-]/.test(p)) return;
+  const rel = p.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!rel) return;
+  const bases = p.startsWith("/") ? [""] : [path.posix.dirname(from), ""];
+  if (bases.some((b) => exists(path.posix.join(b, rel)))) return;
+  const first = rel.split("/")[0];
+  const anchored = isLink || (rel.includes("/") && bases.some((b) => exists(path.posix.join(b, first))));
+  if (anchored) problems.push(`${from}:${n}: ${raw} doesn't exist`);
+}
+
+const scanned = markdown.filter((f) => isInstructions(f) || f.startsWith(".claude/") || f.startsWith("docs/"));
+for (const f of scanned) {
+  for (const { line, n } of proseLines(read(f))) {
+    for (const [, span] of line.matchAll(/`([^`]+)`/g)) for (const token of span.split(/\s+/)) checkPath(f, n, token, false);
+    for (const [, target] of line.matchAll(/\]\(([^)\s]+)\)/g)) checkPath(f, n, target, true);
+  }
+}
+
+// ---- Hooks: the git hooks are on, and every Claude hook script exists
+// A CI checkout never turns the hooks on, and needn't: CI runs the checks itself. CI services set CI.
+const inCI = Boolean(process.env.CI) && !/^(false|0)$/i.test(process.env.CI);
+if (!inCI && git("config", "core.hooksPath")?.trim() !== ".githooks") {
+  problems.push("git hooks are off in this clone: git config core.hooksPath .githooks");
+}
+let settings = {};
+try {
+  settings = JSON.parse(read(".claude/settings.json"));
+} catch (e) {
+  problems.push(`.claude/settings.json: ${e.code === "ENOENT" ? "missing" : e.message}`);
+}
+for (const entries of Object.values(settings.hooks ?? {})) {
+  for (const { hooks = [] } of entries) {
+    for (const { command = "" } of hooks) {
+      for (const [, rel] of command.matchAll(/\$CLAUDE_PROJECT_DIR\/([^"'\s]+)/g)) {
+        if (!exists(rel)) problems.push(`.claude/settings.json: hook script ${rel} doesn't exist`);
+      }
+    }
+  }
+}
+
+// ---- The kit's versions of files the repo has its own of (agk setup, agk update), still to merge
+if (exists(".claude/agk.json")) {
+  let kitFiles = [];
+  try {
+    kitFiles = Object.keys(JSON.parse(read(".claude/agk.json")).files ?? {});
+  } catch (e) {
+    problems.push(`.claude/agk.json: ${e.message}`);
+  }
+  for (const f of kitFiles.filter((f) => exists(`${f}.kit`))) {
+    problems.push(`${f}.kit: the kit's version of ${f}. Merge what's new in it into ${f}, then delete it`);
+  }
+}
+
+for (const p of problems) console.log(p);
+const always = (exists("CLAUDE.md") ? words(read("CLAUDE.md")) : 0) + descriptionWords;
+console.log(
+  problems.length
+    ? "FAIL"
+    : `OK (always in context: CLAUDE.md + ${skillNames.length} skill descriptions, ~${always} words)`,
+);
+process.exit(problems.length ? 1 : 0);

package/template/scripts/hooks/block-big-read.mjs

@@ -0,0 +1,25 @@
+// PreToolUse hook for Read: refuse a whole-file read of a text file over MAX_LINES.
+// Fails open: any error, or a read with a `limit`, lets the call through. So do images and PDFs,
+// which Read shows as pictures or by page, and other binary files: their "lines" mean nothing.
+import { readFileSync, statSync } from "node:fs";
+
+const MAX_LINES = 1500;
+const SHOWN_AS_IS = /\.(png|jpe?g|gif|webp|bmp|ico|pdf)$/i;
+
+try {
+  const input = JSON.parse(readFileSync(0, "utf8"));
+  const { file_path: file, limit } = input.tool_input ?? {};
+  if (file && !limit && !SHOWN_AS_IS.test(file) && statSync(file).size > 20_000) {
+    const data = readFileSync(file);
+    const binary = data.subarray(0, 8000).includes(0); // git's test: a NUL byte near the start
+    const lines = binary ? 0 : data.toString("utf8").split("\n").length;
+    if (lines > MAX_LINES) {
+      console.error(
+        `${file} has ${lines} lines (over ${MAX_LINES}). Use Grep to find what you need, or Read with offset and limit.`,
+      );
+      process.exit(2);
+    }
+  }
+} catch {
+  // fail open
+}

package/template/scripts/hooks/guard-commands.mjs

@@ -0,0 +1,110 @@
+// PreToolUse hook for Bash and PowerShell: keeps the repo's safety nets in place.
+// Refuses (exit 2; the reason goes to Claude):
+//   --no-verify (and git commit -n), which skips the git hooks, and turning the hooks off
+//   (core.hooksPath);
+//   bulk staging (git add -A/./-u, git commit -a), which picks up changes that aren't yours.
+// Long options count in any abbreviation git accepts (--no-veri, --al).
+// Asks the user first: merging into main, pushing, and commands that discard work or move
+// branches by hand.
+// Quoted text, heredocs and here-strings are ignored, so a commit message can mention any of this.
+// Fails open: unreadable input lets the command through.
+import { readFileSync } from "node:fs";
+
+let command;
+try {
+  command = String(JSON.parse(readFileSync(0, "utf8")).tool_input?.command ?? "");
+} catch {
+  process.exit(0);
+}
+
+const code = command
+  .replace(/<<-?\s*(['"]?)(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2\s*(?=\n|$)/g, " ") // heredoc bodies
+  .replace(/@(['"])\r?\n[\s\S]*?\r?\n\1@/g, '""') // PowerShell here-strings
+  .replace(/"(?:[^"\\`]|[\\`].)*"|'[^']*'/g, '""'); // quoted strings
+
+function refuse(reason) {
+  console.error(reason);
+  process.exit(2);
+}
+
+/** A simple command's git subcommand and its arguments, skipping git's own options (-C dir, -c k=v). */
+function parseGit(segment) {
+  const words = segment.trim().split(/\s+/);
+  let i = words.findIndex((w) => /(^|[\\/])git(\.exe)?$/.test(w));
+  if (i < 0) return null;
+  for (i++; i < words.length && words[i].startsWith("-"); i++) if (words[i] === "-C" || words[i] === "-c") i++;
+  return { sub: words[i], args: words.slice(i + 1) };
+}
+const gits = code.split(/&&|\|\||[;|\n]/).map(parseGit).filter(Boolean);
+const has = (args, ...flags) => args.some((a) => flags.includes(a));
+
+/** The letters of a short-option group like -qnm, up to one that takes a value (m: -mfoo is a message). */
+function shortFlags(arg, takesValue = "") {
+  if (!/^-[a-zA-Z]+$/.test(arg)) return "";
+  let flags = "";
+  for (const ch of arg.slice(1)) {
+    flags += ch;
+    if (takesValue.includes(ch)) break;
+  }
+  return flags;
+}
+/** True for `name` or an abbreviation of it git would accept (git takes any unambiguous prefix). */
+const long = (arg, name, shortest) => arg.length >= shortest && name.startsWith(arg.split("=")[0]);
+
+// --no-veri is enough for git (--no-ve could also be --no-verbose).
+if (/(^|\s)--no-veri/.test(code)) {
+  refuse("--no-verify skips the git hooks (the checks, no commits on main). Fix what the hook reports instead.");
+}
+if (/core\.hooksPath[\s=]+(?!\.githooks\b)[^\s;&|]/i.test(code) || /\bunset(-all)?\s+core\.hooksPath\b/i.test(code)) {
+  refuse("The git hooks stay on: core.hooksPath is .githooks.");
+}
+const BULK_PATHS = [".", "./", ".\\", "*", ":/", ":/."];
+for (const { sub, args } of gits) {
+  if (
+    sub === "add" &&
+    args.some(
+      (a) =>
+        BULK_PATHS.includes(a) ||
+        /[Au]/.test(shortFlags(a)) ||
+        long(a, "--all", 3) ||
+        long(a, "--update", 3) ||
+        long(a, "--no-ignore-removal", 6),
+    )
+  ) {
+    refuse("Stage the files you changed by name (git skill): bulk staging picks up changes that aren't yours.");
+  }
+  if (sub === "commit") {
+    // Options of git commit that take a value: -m msg, -F file, -C/-c commit, -t file, -S[key], -u[mode].
+    const flags = args.map((a) => shortFlags(a, "mFCctSu")).join("");
+    if (flags.includes("n")) {
+      refuse("git commit -n is --no-verify: it skips the git hooks. Fix what the hook reports instead.");
+    }
+    if (flags.includes("a") || args.includes("--all")) {
+      refuse("git commit -a stages every changed file. Stage yours by name, then commit (git skill).");
+    }
+  }
+}
+
+const reasons = [];
+if (/\bnode(\.exe)?\s+\S*merge\.mjs\b/.test(code)) reasons.push("This merges into main: the user approves first.");
+for (const { sub, args } of gits) {
+  if (sub === "push") reasons.push("This pushes to a remote.");
+  if (sub === "merge") reasons.push("main moves only through scripts/merge.mjs; merging by hand needs the user's OK.");
+  if (sub === "reset" && has(args, "--hard")) reasons.push("reset --hard discards uncommitted work.");
+  if (sub === "clean") reasons.push("git clean deletes untracked files.");
+  if (sub === "checkout" && has(args, "--", ".")) reasons.push("This discards uncommitted changes.");
+  if (sub === "restore" && !(has(args, "--staged", "-S") && !has(args, "--worktree", "-W"))) {
+    reasons.push("git restore discards uncommitted changes.");
+  }
+  if (sub === "stash" && has(args, "drop", "clear")) reasons.push("This deletes stashed work.");
+  if (sub === "branch" && has(args, "-D", "-f", "--force")) reasons.push("Force-deleting or moving a branch can lose commits.");
+  if (sub === "update-ref") reasons.push("This moves a branch by hand.");
+  if (sub === "worktree" && args[0] === "remove" && has(args, "-f", "--force")) {
+    reasons.push("Removing a worktree by force deletes its uncommitted work.");
+  }
+}
+if (reasons.length) {
+  const output = { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: [...new Set(reasons)].join(" ") };
+  console.log(JSON.stringify({ hookSpecificOutput: output }));
+}
+process.exit(0);

package/template/scripts/merge.mjs

@@ -0,0 +1,82 @@
+// Fast-forwards main to the branch checked out here, once its checks pass. The only way main
+// moves (git skill): run it from the branch's checkout, after the user approves the merge.
+// Usage: node scripts/merge.mjs [branch]   (if given, it must be the branch checked out here)
+import { execFileSync, spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MAIN = "main";
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function git(...args) {
+  return execFileSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function tryGit(...args) {
+  try {
+    return git(...args);
+  } catch {
+    return null;
+  }
+}
+function fail(message) {
+  console.error(`merge: ${message}`);
+  process.exit(1);
+}
+
+/** The worktree that has `branch` checked out, or null. */
+function worktreeOf(branch) {
+  let dir = null;
+  for (const line of git("worktree", "list", "--porcelain").split("\n")) {
+    if (line.startsWith("worktree ")) dir = line.slice("worktree ".length);
+    else if (line === `branch refs/heads/${branch}`) return dir;
+  }
+  return null;
+}
+
+const branch = tryGit("symbolic-ref", "--short", "-q", "HEAD");
+if (!branch) fail("HEAD is detached; check out the branch to merge");
+if (branch === MAIN) fail(`this checkout is on ${MAIN}; run this from the branch to merge`);
+const named = process.argv[2];
+if (named && named !== branch) fail(`${named} isn't checked out here (${branch} is); run this from ${named}'s checkout`);
+if (tryGit("rev-parse", "--verify", "-q", `refs/heads/${MAIN}`) === null) fail(`there's no ${MAIN} branch`);
+if (git("status", "--porcelain", "--untracked-files=no")) fail("uncommitted changes; commit them first");
+
+const base = git("rev-parse", MAIN);
+const tip = git("rev-parse", "HEAD");
+if (base === tip) fail(`${branch} has nothing that ${MAIN} doesn't`);
+if (tryGit("merge-base", "--is-ancestor", MAIN, "HEAD") === null) {
+  fail(`${branch} isn't on top of ${MAIN}: git rebase ${MAIN}, then run this again`);
+}
+
+// The checks run on exactly what main is about to become.
+const check = spawnSync(process.execPath, [path.join(ROOT, "scripts", "check.mjs")], { cwd: ROOT, stdio: "inherit" });
+if (check.status !== 0) fail(`checks failed; ${MAIN} is unchanged`);
+
+// Where main is checked out (usually the main checkout, when this is a worktree), fast-forward
+// it there so its files follow. Otherwise move the ref alone, guarded by its old value.
+const mainTree = worktreeOf(MAIN);
+if (mainTree) {
+  const r = spawnSync("git", ["merge", "--ff-only", "-q", tip], { cwd: mainTree, encoding: "utf8" });
+  if (r.status !== 0) fail(`couldn't fast-forward ${MAIN} in ${mainTree}:\n${(r.stderr || r.stdout).trim()}`);
+} else {
+  git("update-ref", "-m", `merge.mjs: fast-forward to ${branch}`, `refs/heads/${MAIN}`, tip, base);
+}
+const count = Number(git("rev-list", "--count", `${base}..${tip}`));
+console.log(`merged ${branch} into ${MAIN}: ${count} commit${count === 1 ? "" : "s"} (${base.slice(0, 7)}..${tip.slice(0, 7)})`);
+
+// The branch is done: leave it and delete it. If main is checked out elsewhere, this checkout
+// can't switch to it, so say how to finish instead.
+const isWorktree = path.resolve(ROOT, git("rev-parse", "--git-dir")) !== path.resolve(ROOT, git("rev-parse", "--git-common-dir"));
+if (!mainTree) {
+  if (tryGit("switch", "-q", MAIN) !== null && tryGit("branch", "-q", "-d", branch) !== null) {
+    console.log(`deleted ${branch}; this checkout is on ${MAIN}`);
+  } else {
+    console.log(`couldn't switch this checkout to ${MAIN}; ${branch} is kept`);
+  }
+} else if (isWorktree) {
+  console.log(`this worktree is done: cd "${mainTree}" && git worktree remove "${ROOT}" && git branch -d ${branch}`);
+} else {
+  console.log(`${MAIN} is checked out in ${mainTree}; switch this checkout off ${branch}, then: git branch -d ${branch}`);
+}
+const remote = tryGit("remote")?.split("\n")[0];
+if (remote) console.log(`${remote}: push ${MAIN} once the user agrees (git push ${remote} ${MAIN})`);