flagrm 0.1.0

package/dist/core/doctor.js

@@ -0,0 +1,141 @@
+/**
+ * `flagrm doctor`: is this repository ready for an agent to remove a flag?
+ * Config, build/test commands, git, .gitignore, the installed skills and
+ * hook, and baselines left behind by abandoned removals.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { errorExcerpt, incrementalBuildGap, projectCommands, runCheck, templateCheckGap } from "./baseline.js";
+import { findConfigFile, loadConfig } from "./config.js";
+import { gitState, isAncestor } from "./git.js";
+import { AGENT_SKILL_DIRS, installedSkillVersion, SKILLS, stopHookState } from "./install.js";
+import { packageVersion } from "./package.js";
+import { resolveProjects } from "./registry.js";
+import { readJson, relativePath } from "./util.js";
+/** Check the setup in `cwd`: config and commands, git, .gitignore, skills, hook and abandoned baselines. */
+export async function runDoctor(cwd, options = {}) {
+    const checks = [];
+    const add = (status, message, details) => checks.push({ status, message, ...(details?.length ? { details } : {}) });
+    // Skills, hook and .gitignore live next to the config, which may be in a parent of `cwd`.
+    const configFile = options.config ? path.resolve(cwd, options.config) : findConfigFile(cwd);
+    const root = configFile ? path.dirname(configFile) : cwd;
+    await configChecks(cwd, configFile, options, add);
+    const git = gitState(root);
+    if (git.sha === null)
+        add("warn", "not a git repository: verify can't diff against the baseline");
+    else if (git.dirty)
+        add("warn", `${git.dirtyFiles?.length ?? 0} uncommitted files — commit or stash before a removal`);
+    else
+        add("ok", "working tree clean");
+    const gitignore = path.join(root, ".gitignore");
+    const ignored = fs.existsSync(gitignore) && /^\/?\.flagrm\/?\s*$/m.test(fs.readFileSync(gitignore, "utf8"));
+    add(ignored ? "ok" : "warn", ignored ? ".flagrm/ is gitignored" : "add .flagrm/ to .gitignore (flagrm init does this)");
+    const version = packageVersion();
+    for (const dir of AGENT_SKILL_DIRS) {
+        const versions = SKILLS.map((s) => installedSkillVersion(path.join(root, dir, s)));
+        if (versions.every((v) => v === undefined))
+            add("warn", `${dir}: skills not installed (run flagrm init)`);
+        else if (versions.some((v) => v !== version)) {
+            const found = versions.find((v) => v !== version) ?? "missing";
+            add("warn", `${dir}: skills from flagrm ${found}, this is ${version} (run flagrm update)`);
+        }
+        else
+            add("ok", `${dir}: skills ${version}`);
+    }
+    const hook = stopHookState(root);
+    if (hook === "current")
+        add("ok", "Claude Code Stop hook installed");
+    else if (hook === "outdated")
+        add("warn", "Claude Code Stop hook runs an outdated command (run flagrm update)");
+    else
+        add("warn", "Claude Code Stop hook missing from .claude/settings.json (run flagrm init)");
+    if (git.sha !== null)
+        abandonedBaselines(root, add);
+    return { status: checks.some((c) => c.status === "fail") ? "fail" : "ok", checks };
+}
+/** Config, project paths and commands of `configFile` (from --config or found from `cwd`). */
+async function configChecks(cwd, configFile, options, add) {
+    if (!configFile) {
+        add("fail", "no flagrm.config.yaml (run flagrm init)");
+        return;
+    }
+    let root;
+    let projects;
+    try {
+        const config = loadConfig({ config: configFile }, cwd);
+        root = config.root;
+        projects = resolveProjects(config);
+    }
+    catch (err) {
+        add("fail", `config: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    for (const { adapter, ctx } of projects) {
+        const commands = projectCommands(adapter, ctx);
+        for (const check of ["build", "test"]) {
+            const command = commands[check];
+            if (!command) {
+                add("warn", `${ctx.name}: no ${check} command — verify can't ${check === "build" ? "check the build" : "compare tests"}`);
+                continue;
+            }
+            const missing = simpleCommandProgram(command);
+            if (missing && !onPath(missing, ctx.root)) {
+                add("fail", `${ctx.name}: \`${missing}\` (from \`${command}\`) is not on PATH`);
+                continue;
+            }
+            if (check === "build") {
+                for (const gap of [templateCheckGap(adapter, command), incrementalBuildGap(adapter, command)]) {
+                    if (gap)
+                        add("warn", `${ctx.name}: ${gap}`);
+                }
+            }
+            if (!options.run) {
+                add("ok", `${ctx.name}: ${check} command \`${command}\``);
+                continue;
+            }
+            const run = await runCheck(ctx, check, command, path.join(root, ".flagrm", "doctor", `${ctx.name}.${check}.log`));
+            if (run.exitCode === 0) {
+                add("ok", `${ctx.name}: \`${command}\` passed`);
+                continue;
+            }
+            add("fail", `${ctx.name}: \`${command}\` failed (exit ${run.exitCode}, log ${relativePath(cwd, run.log ?? "")})`, errorExcerpt(run.log, 3));
+        }
+    }
+}
+/**
+ * The program of a simple command (`dotnet build`, `CI=1 npm test`), for the
+ * PATH check, or undefined when the command uses shell syntax (`&&`, `|`,
+ * quotes, `$VAR`, redirections, ...). Those are left to the build and test
+ * runs: parsing shell well enough to find every program is not worth it.
+ */
+export function simpleCommandProgram(command) {
+    if (/[;&|()<>`$"'\n{}]/.test(command))
+        return undefined;
+    return command
+        .trim()
+        .split(/\s+/)
+        .find((word) => !/^\w+=/.test(word));
+}
+function onPath(exe, cwd) {
+    if (exe.includes("/") || exe.includes("\\"))
+        return fs.existsSync(path.resolve(cwd, exe));
+    const exts = process.platform === "win32" ? ["", ...(process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+    return (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .filter(Boolean)
+        .some((dir) => exts.some((ext) => fs.existsSync(path.join(dir, exe + ext))));
+}
+/** `.flagrm/<flag>/` entries whose baseline commit is not in this branch's history. */
+function abandonedBaselines(root, add) {
+    const dir = path.join(root, ".flagrm");
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const sha = readJson(path.join(dir, entry.name, "baseline.json"))?.git?.sha;
+        if (sha && !isAncestor(root, sha)) {
+            add("warn", `.flagrm/${entry.name}: baseline commit ${sha.slice(0, 7)} is not in this branch's history — delete it if that removal was abandoned`);
+        }
+    }
+}

package/dist/core/git.js

@@ -0,0 +1,101 @@
+/**
+ * Git plumbing for baselines and `verify`. Every path is relative
+ * to the config root (`cwd`), and flagrm's own `.flagrm/` directory is ignored.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Excludes flagrm's own output from every diff. */
+const PATHSPEC = ["--", ".", ":(exclude).flagrm"];
+function git(cwd, ...args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    return { ok: result.status === 0, stdout: result.stdout ?? "" };
+}
+/** NUL-separated paths (`-z`), which git never quotes or escapes, whatever the file name. */
+const paths = (text) => text.split("\0").filter(Boolean);
+/** Untracked (and not ignored) files under `cwd`. */
+function untracked(cwd) {
+    return paths(git(cwd, "ls-files", "-z", "--others", "--exclude-standard", ...PATHSPEC).stdout);
+}
+/** HEAD commit and the files with uncommitted changes (`sha: null` outside a git repository). */
+export function gitState(cwd) {
+    const head = git(cwd, "rev-parse", "HEAD");
+    if (!head.ok)
+        return { sha: null, dirty: false };
+    const dirtyFiles = changedFilesSince(cwd, "HEAD") ?? [];
+    return { sha: head.stdout.trim(), dirty: dirtyFiles.length > 0, dirtyFiles };
+}
+/** Files added, modified or deleted in the working tree since `sha` (tracked diff plus untracked files). */
+export function changedFilesSince(cwd, sha) {
+    const diff = git(cwd, "diff", "-z", "--name-only", "--no-renames", "--relative", sha, ...PATHSPEC);
+    if (!diff.ok)
+        return undefined;
+    return [...new Set([...paths(diff.stdout), ...untracked(cwd)])].sort();
+}
+/** A file's content at `sha`, or undefined when it did not exist there. */
+export function fileAt(cwd, sha, relativePath) {
+    const result = git(cwd, "show", `${sha}:./${relativePath.split(path.sep).join("/")}`);
+    return result.ok ? result.stdout : undefined;
+}
+function gitWithIndex(cwd, index, ...args) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 256 * 1024 * 1024,
+        env: { ...process.env, GIT_INDEX_FILE: index },
+    });
+    return { ok: result.status === 0, stdout: result.stdout ?? "" };
+}
+/** `cwd` relative to the repository root with a trailing slash (`""` at the root); undefined outside git. */
+function repoPrefix(cwd) {
+    const result = git(cwd, "rev-parse", "--show-prefix");
+    return result.ok ? result.stdout.trim() : undefined;
+}
+/**
+ * The git tree id of the working tree under `cwd` as it would be committed:
+ * tracked and untracked files, not ignored ones, without `.flagrm/`. Built in a
+ * temporary copy of the index, so the user's index is untouched. Committing
+ * the tree doesn't change it; any edit does. Before any edit it equals
+ * {@link treeAt} of HEAD.
+ */
+export function treeFingerprint(cwd) {
+    const prefix = repoPrefix(cwd);
+    if (prefix === undefined)
+        return undefined;
+    const realIndex = git(cwd, "rev-parse", "--path-format=absolute", "--git-path", "index").stdout.trim();
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "flagrm-index-"));
+    const index = path.join(dir, "index");
+    try {
+        // Keep the index's mtime: git compares it with entry mtimes to catch same-second ("racy") edits.
+        if (realIndex && fs.existsSync(realIndex))
+            fs.cpSync(realIndex, index, { preserveTimestamps: true });
+        // Not PATHSPEC: `git add` exits 1 when an exclude pathspec names an ignored path (`.flagrm/` usually is).
+        if (!gitWithIndex(cwd, index, "add", "-A", "--", ".").ok)
+            return undefined;
+        if (!gitWithIndex(cwd, index, "rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", ".flagrm").ok)
+            return undefined;
+        const tree = gitWithIndex(cwd, index, "write-tree", ...(prefix ? [`--prefix=${prefix}`] : []));
+        return tree.ok ? tree.stdout.trim() : undefined;
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** The tree id of `cwd` at commit `sha`. */
+export function treeAt(cwd, sha) {
+    const prefix = repoPrefix(cwd);
+    if (prefix === undefined)
+        return undefined;
+    const result = git(cwd, "rev-parse", "--verify", "--quiet", `${sha}:${prefix}`);
+    return result.ok ? result.stdout.trim() : undefined;
+}
+/** The HEAD commit, or undefined outside a git repository or before the first commit. */
+export function headSha(cwd) {
+    const result = git(cwd, "rev-parse", "--verify", "--quiet", "HEAD");
+    return result.ok ? result.stdout.trim() : undefined;
+}
+/** Whether `sha` is HEAD or one of its ancestors. */
+export function isAncestor(cwd, sha) {
+    return git(cwd, "merge-base", "--is-ancestor", sha, "HEAD").ok;
+}

package/dist/core/hook.js

@@ -0,0 +1,83 @@
+/**
+ * `flagrm hook stop`: the Claude Code Stop hook. It blocks the agent from
+ * finishing while a flag removal is underway and not verified. It never runs
+ * builds or tests, and anything unexpected allows the stop: a broken hook
+ * must never trap the user.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { findConfigRoot } from "./config.js";
+import { headSha, treeAt, treeFingerprint } from "./git.js";
+import { readJson } from "./util.js";
+/** The hook's stdin: only a JSON object counts, and only fields of the expected type are kept. */
+export function parseHookInput(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return {};
+    const { stop_hook_active, cwd } = raw;
+    const input = {};
+    if (typeof stop_hook_active === "boolean")
+        input.stop_hook_active = stop_hook_active;
+    if (typeof cwd === "string")
+        input.cwd = cwd;
+    return input;
+}
+/** The config root for a hook run in `cwd`: Claude Code may run it from a subdirectory of the repository. */
+export function hookRoot(cwd) {
+    return findConfigRoot(cwd) ?? cwd;
+}
+/**
+ * Whether to block the stop: a removal is in progress (HEAD is still its
+ * baseline commit and the tree has changed) and no passing verify matches the
+ * current tree. Once HEAD moves (a commit, a branch switch, a merge), that
+ * removal is no longer guarded.
+ */
+export function stopDecision(root, input) {
+    if (input.stop_hook_active)
+        return { block: false };
+    try {
+        const dir = path.join(root, ".flagrm");
+        if (!fs.existsSync(dir))
+            return { block: false };
+        const head = headSha(root);
+        if (!head)
+            return { block: false };
+        const active = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => path.join(dir, e.name))
+            .filter((flagDir) => readJson(path.join(flagDir, "baseline.json"))?.git?.sha === head);
+        if (active.length === 0)
+            return { block: false };
+        const current = treeFingerprint(root);
+        if (!current || current === treeAt(root, head))
+            return { block: false };
+        const reasons = active.map((flagDir) => unverified(flagDir, current)).filter((r) => r !== undefined);
+        return reasons.length ? { block: true, reason: reasons.join("\n") } : { block: false };
+    }
+    catch {
+        return { block: false };
+    }
+}
+/** Why the in-progress removal in `flagDir` is not verified, or undefined when a full verify passed on `current`. */
+function unverified(flagDir, current) {
+    const baseline = readJson(path.join(flagDir, "baseline.json"));
+    if (!baseline)
+        return undefined;
+    const verify = readJson(path.join(flagDir, "verify.json"));
+    const run = `run flagrm verify ${baseline.flag} --json`;
+    // A report without `skipped` comes from an older flagrm, which didn't record skips.
+    if (verify?.status !== "pass" || verify.fingerprint !== current || !Array.isArray(verify.skipped)) {
+        return `flagrm: ${baseline.flag} removal not verified — ${run}`;
+    }
+    if (verify.skipped.length) {
+        return `flagrm: ${baseline.flag} verified with --skip ${verify.skipped.join(",")} — ${run} without --skip`;
+    }
+    return undefined;
+}

package/dist/core/install.js

@@ -0,0 +1,257 @@
+/**
+ * What `flagrm init` and `flagrm update` write into a repository: the config
+ * template, the agent skills, the AGENTS.md pointer for Codex, the Claude
+ * Code Stop hook and the `.flagrm/` gitignore entry. Every step reports what
+ * it did; nothing the user wrote is overwritten.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_BACKEND_ATTRIBUTES, DEFAULT_BACKEND_METHODS, DEFAULT_FRONTEND_METHODS, findConfigRoot, findDefaultConfigFile, repositoryRoot, } from "./config.js";
+import { detectProjects } from "./detect.js";
+import { packageRoot, packageVersion } from "./package.js";
+import { relativePath } from "./util.js";
+export const SKILLS = ["flagrm-remove", "flagrm-verify"];
+/** Where each supported agent discovers repository skills: Claude Code, GitHub Copilot, Codex. */
+export const AGENT_SKILL_DIRS = [".claude/skills", ".github/skills", ".agents/skills"];
+/**
+ * The Stop hook command. npx runs the project's own flagrm (a dev dependency)
+ * and falls back to a global install. `--no-install` matters: the `flagrm` name
+ * on npm belongs to an unrelated package, and a hook must never download code.
+ * No redirects or `||`: Claude Code runs hooks in PowerShell on Windows
+ * without Git Bash, so the command must parse in both shells.
+ */
+export const HOOK_COMMAND = "npx --no-install flagrm hook stop";
+/** Matches any flagrm Stop hook command, including older or version-pinned ones (`npx flagrm@0.1.0 hook stop`). */
+const OUR_HOOK = /\bflagrm(@\S+)? hook stop\b/;
+const AGENTS_START = "<!-- flagrm:start -->";
+const AGENTS_END = "<!-- flagrm:end -->";
+export const AGENTS_BLOCK = [
+    AGENTS_START,
+    "## Feature flag removal (flagrm)",
+    "",
+    "To remove a feature flag, follow `.agents/skills/flagrm-remove/SKILL.md`. To check a removal and get its",
+    "commit message, follow `.agents/skills/flagrm-verify/SKILL.md`.",
+    AGENTS_END,
+].join("\n");
+const CONFIG_HEADER = [
+    "# flagrm configuration, used by the flagrm agent skills (Claude Code, GitHub Copilot, Codex).",
+    "# Paths are relative to this file. build/test commands run inside each project's path.",
+    "projects:",
+];
+const CONFIG_FOOTER = [
+    "  # Any other stack: the generic adapter",
+    "  # - name: service",
+    "  #   adapter: generic",
+    "  #   path: ./service",
+    "  #   globs: ['**/*.go', 'config/**/*.yaml']",
+    "  #   methods: [IsEnabled]",
+    "",
+    "# Optional: extra globs, unioned with the built-in ignore list / language globs",
+    "# exclude: ['**/Migrations/**', '**/*.g.cs']",
+    "# include: ['**/*.razor.cs']",
+    "",
+];
+/** Used when nothing is detected: one project per supported stack, for the user to adjust. */
+const EXAMPLE_PROJECTS = [
+    { name: "frontend", adapter: "angular", path: "frontend", marker: "frontend/angular.json" },
+    { name: "backend", adapter: "dotnet", path: "backend", marker: "backend/Backend.sln" },
+];
+/** The config lines for one project, with commented-out commands that fit it. */
+function projectLines(p) {
+    const dir = p.path === "." ? "." : `./${p.path}`;
+    const inDir = (rel) => (p.path === "." ? `./${rel}` : `${dir}/${rel}`);
+    const lines = [`  - name: ${p.name}`, `    adapter: ${p.adapter}`, `    path: ${dir}`];
+    if (p.adapter === "angular") {
+        lines.push("    # build: npx ng build", p.jest
+            ? "    # test: JEST_JUNIT_OUTPUT_DIR=test-results npx jest --ci --reporters=default --reporters=jest-junit"
+            : "    # test: npx ng test --watch=false", `    # testResults: ${inDir("test-results/junit.xml")}   # JUnit XML, so verify can count tests`, `    # methods: [${DEFAULT_FRONTEND_METHODS.join(", ")}]   # flag evaluation methods (defaults shown)`);
+    }
+    else {
+        const solution = /\.slnx?$/.test(p.marker) ? ` ${path.posix.basename(p.marker)}` : "";
+        lines.push(`    # build: dotnet build${solution} --no-incremental`, `    # test: dotnet test${solution} --logger trx`, `    # testResults: ${inDir("**/TestResults/*.trx")}`, `    # methods: [${DEFAULT_BACKEND_METHODS.join(", ")}]`, `    # attributes: [${DEFAULT_BACKEND_ATTRIBUTES.join(", ")}]`);
+    }
+    return lines;
+}
+export function configTemplate(projects) {
+    const listed = projects.length ? projects : EXAMPLE_PROJECTS;
+    return [...CONFIG_HEADER, ...listed.flatMap(projectLines), ...CONFIG_FOOTER].join("\n");
+}
+/** Write `flagrm.config.yaml` for the projects found in `cwd` (an example when none are) unless a config file exists. */
+export function writeConfigTemplate(cwd) {
+    const existing = findDefaultConfigFile(cwd);
+    if (existing)
+        return { path: relativePath(cwd, existing), status: "skipped" };
+    const file = path.join(cwd, "flagrm.config.yaml");
+    const projects = detectProjects(cwd);
+    fs.writeFileSync(file, configTemplate(projects), "utf8");
+    const note = projects.length
+        ? `detected ${projects.map((p) => `${p.adapter} (${p.marker})`).join(", ")}`
+        : "no Angular or .NET project found: edit the example projects";
+    return { path: relativePath(cwd, file), status: "created", note };
+}
+/** Copy each skill into each agent's skills directory and stamp it with the flagrm version. */
+export function installSkills(cwd, mode, version = packageVersion(), source = path.join(packageRoot(), "skills")) {
+    const results = [];
+    for (const dir of AGENT_SKILL_DIRS) {
+        for (const skill of SKILLS) {
+            const target = path.join(cwd, dir, skill);
+            const exists = fs.existsSync(target);
+            if (mode === "init" && exists) {
+                results.push({ path: relativePath(cwd, target), status: "skipped" });
+                continue;
+            }
+            if (mode === "update" && !exists)
+                continue;
+            const before = exists ? snapshot(target) : undefined;
+            fs.rmSync(target, { recursive: true, force: true });
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.cpSync(path.join(source, skill), target, { recursive: true });
+            stampSkill(path.join(target, "SKILL.md"), version);
+            const status = !exists ? "created" : before === snapshot(target) ? "unchanged" : "updated";
+            results.push({ path: relativePath(cwd, target), status });
+        }
+    }
+    return results;
+}
+/** Every file under `dir` with its content, for telling an update from a no-op. */
+function snapshot(dir) {
+    return fs.readdirSync(dir, { recursive: true })
+        .filter((f) => fs.statSync(path.join(dir, f)).isFile())
+        .sort()
+        .map((f) => `${f}\0${fs.readFileSync(path.join(dir, f), "utf8")}`)
+        .join("\0");
+}
+/** Record the flagrm version in a SKILL.md's frontmatter (`metadata.flagrm-version`), replacing an earlier stamp. */
+export function stampSkill(file, version) {
+    const text = fs.readFileSync(file, "utf8");
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const lf = text.replace(/\r\n/g, "\n").replace(/\nmetadata:\n {2}flagrm-version: .*(?=\n)/, "");
+    const end = lf.indexOf("\n---", 3);
+    if (!lf.startsWith("---\n") || end === -1)
+        throw new Error(`${file} has no frontmatter.`);
+    const stamped = `${lf.slice(0, end)}\nmetadata:\n  flagrm-version: "${version}"${lf.slice(end)}`;
+    fs.writeFileSync(file, stamped.replace(/\n/g, eol), "utf8");
+}
+/** The flagrm version an installed skill was stamped with, or undefined when it isn't installed. */
+export function installedSkillVersion(skillDir) {
+    try {
+        const text = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
+        return /^ {2}flagrm-version: "?([^"\r\n]+)"?/m.exec(text)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The marked flagrm block in AGENTS.md, which Codex reads. */
+export function installAgentsBlock(cwd, mode) {
+    const file = path.join(cwd, "AGENTS.md");
+    const exists = fs.existsSync(file);
+    const text = exists ? fs.readFileSync(file, "utf8") : "";
+    const start = text.indexOf(AGENTS_START);
+    const end = text.indexOf(AGENTS_END);
+    if (start !== -1 && end > start) {
+        if (mode === "init")
+            return { path: "AGENTS.md", status: "skipped" };
+        const next = text.slice(0, start) + AGENTS_BLOCK + text.slice(end + AGENTS_END.length);
+        if (next === text)
+            return { path: "AGENTS.md", status: "unchanged" };
+        fs.writeFileSync(file, next, "utf8");
+        return { path: "AGENTS.md", status: "updated" };
+    }
+    if (mode === "update")
+        return { path: "AGENTS.md", status: "skipped" };
+    if (!exists) {
+        fs.writeFileSync(file, `${AGENTS_BLOCK}\n`, "utf8");
+        return { path: "AGENTS.md", status: "created" };
+    }
+    fs.writeFileSync(file, `${text}${text.endsWith("\n") ? "\n" : "\n\n"}${AGENTS_BLOCK}\n`, "utf8");
+    return { path: "AGENTS.md", status: "updated" };
+}
+function ourStopHooks(settings) {
+    return (settings.hooks?.Stop ?? []).flatMap((g) => g.hooks ?? []).filter((h) => OUR_HOOK.test(h.command ?? ""));
+}
+/** Whether `.claude/settings.json` has flagrm's Stop hook, and whether it runs this version's command. */
+export function stopHookState(cwd) {
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(path.join(cwd, ".claude", "settings.json"), "utf8"));
+    }
+    catch {
+        return "missing";
+    }
+    const ours = ourStopHooks(settings);
+    if (ours.length === 0)
+        return "missing";
+    return ours.every((h) => h.command === HOOK_COMMAND) ? "current" : "outdated";
+}
+/** The Claude Code Stop hook in `.claude/settings.json`, merged with whatever else is there. */
+export function installStopHook(cwd, mode) {
+    const file = path.join(cwd, ".claude", "settings.json");
+    const step = relativePath(cwd, file);
+    const exists = fs.existsSync(file);
+    let settings = {};
+    if (exists) {
+        try {
+            settings = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            return {
+                path: step,
+                status: "skipped",
+                note: `not valid JSON; add a Stop hook running \`${HOOK_COMMAND}\` by hand`,
+            };
+        }
+    }
+    const stop = settings.hooks?.Stop ?? [];
+    const ours = ourStopHooks(settings);
+    if (mode === "update") {
+        if (ours.length === 0)
+            return { path: step, status: "skipped" };
+        if (ours.every((h) => h.command === HOOK_COMMAND))
+            return { path: step, status: "unchanged" };
+        for (const h of ours)
+            h.command = HOOK_COMMAND;
+    }
+    else {
+        if (ours.length)
+            return { path: step, status: "skipped" };
+        settings.hooks = { ...settings.hooks, Stop: [...stop, { hooks: [{ type: "command", command: HOOK_COMMAND }] }] };
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+    return { path: step, status: exists ? "updated" : "created" };
+}
+/** Add `.flagrm/` to `.gitignore` unless it's already listed. */
+export function ensureGitignore(cwd) {
+    const file = path.join(cwd, ".gitignore");
+    const exists = fs.existsSync(file);
+    const text = exists ? fs.readFileSync(file, "utf8") : "";
+    if (/^\/?\.flagrm\/?\s*$/m.test(text))
+        return { path: ".gitignore", status: "skipped" };
+    fs.writeFileSync(file, `${text}${text && !text.endsWith("\n") ? "\n" : ""}.flagrm/\n`, "utf8");
+    return { path: ".gitignore", status: exists ? "updated" : "created" };
+}
+/**
+ * Where `init` and `update` install: next to the nearest config up to the git
+ * repository root, which every other command also uses; without one, at the
+ * repository root, where Claude Code loads the Stop hook from (or `cwd`
+ * outside a repository). Installing in a subdirectory would add a second
+ * config that shadows it there.
+ */
+export function installRoot(cwd) {
+    return findConfigRoot(cwd) ?? repositoryRoot(cwd) ?? cwd;
+}
+/** `flagrm init`: everything the agent needs in `root` (see {@link installRoot}), added where missing. */
+export function initProject(root) {
+    return [
+        writeConfigTemplate(root),
+        ...installSkills(root, "init"),
+        installAgentsBlock(root, "init"),
+        installStopHook(root, "init"),
+        ensureGitignore(root),
+    ];
+}
+/** `flagrm update`: refresh what `init` installed in `root` from this flagrm version; adds nothing new. */
+export function updateProject(root) {
+    return [...installSkills(root, "update"), installAgentsBlock(root, "update"), installStopHook(root, "update")];
+}