grounder 0.4.0 → 0.6.0

package/dist/agents/cursor.js

@@ -1,19 +1,15 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { resolveHomeDir } from "../connector/home.js";
 import { fileExists } from "../util/fs.js";
-import { mergeJsonFile } from "../util/merge-json.js";
-import { installHookRuntime, isGrounderPeekHookCommand, isHookRuntimeStale, peekHookCommand, } from "./hook-runtime.js";
-import { installCommandFile, recordCommandFileHashes } from "./install-command.js";
-const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-const templateDir = path.join(pkgRoot, "templates", "agents", "cursor", "commands");
-const COMMANDS = [
-    "grounder-note.md",
-    "grounder-plan.md",
-    "grounder-task-handoff.md",
-    "grounder-task.md",
-];
+import { homeSkillsLayout } from "./home-skills.js";
+import { isAlreadyConverged, readEventEntries, readHooksObject, removeMatchingEntries, } from "./hook-fragment.js";
+import { installHookFragment, removeHookFragment } from "./hook-install.js";
+import { isGrounderPeekHookCommand, isHookRuntimeStale, peekHookCommand } from "./hook-runtime.js";
+/** Whole-file artifacts: `~/.cursor/skills/` plus the retired `~/.cursor/commands/`. */
+const layout = homeSkillsLayout({ id: "cursor", agentDir: ".cursor" });
+/** Hook event Grounder owns in `hooks.json`. */
+const SESSION_START_EVENT = "sessionStart";
 /**
  * Canonical sessionStart command for Cursor (home-local runtime, not `npx`).
  * Always includes `--json` so stdout matches Cursor's `additional_context` contract.
@@ -22,27 +18,27 @@ const COMMANDS = [
 export function cursorPeekHookCommand(homeDir, extraArgs = ["--json"]) {
     return peekHookCommand(homeDir, extraArgs);
 }
-export function cursorCommandsDir(homeDir) {
-    return path.join(resolveHomeDir(homeDir), ".cursor", "commands");
+export function cursorSkillsDir(homeDir) {
+    return layout.skillsDir(homeDir);
 }
 /** Absolute path to Cursor's shared hooks config (`~/.cursor/hooks.json`). */
 export function cursorHooksJsonPath(homeDir) {
     return path.join(resolveHomeDir(homeDir), ".cursor", "hooks.json");
 }
 export function grounderNoteCommandPath(homeDir) {
-    return path.join(cursorCommandsDir(homeDir), "grounder-note.md");
+    return layout.skillPath("grounder-note", homeDir);
 }
 export function grounderPlanCommandPath(homeDir) {
-    return path.join(cursorCommandsDir(homeDir), "grounder-plan.md");
+    return layout.skillPath("grounder-plan", homeDir);
 }
-export function grounderTaskHandoffCommandPath(homeDir) {
-    return path.join(cursorCommandsDir(homeDir), "grounder-task-handoff.md");
+export function grounderHandoffCommandPath(homeDir) {
+    return layout.skillPath("grounder-handoff", homeDir);
 }
-export function grounderTaskCommandPath(homeDir) {
-    return path.join(cursorCommandsDir(homeDir), "grounder-task.md");
+export function grounderRecallCommandPath(homeDir) {
+    return layout.skillPath("grounder-recall", homeDir);
 }
 export function expectedArtifacts(homeDir) {
-    return COMMANDS.map((filename) => path.join(cursorCommandsDir(homeDir), filename));
+    return layout.expectedArtifacts(homeDir);
 }
 /** Paths of hook config this adapter touches — currently just `hooks.json`. */
 export function expectedHookArtifacts(homeDir) {
@@ -71,37 +67,35 @@ export function expectedHookArtifacts(homeDir) {
 //   - hook entry     → { command: string }
 //
 // Unlike Claude Code, Cursor has no matcher groups — sessionStart is a flat
-// array. Idempotency: {@link isGrounderPeekHookCommand} (runtime path or legacy npx).
+// array. Idempotency / recognizer: {@link isGrounderPeekHookCommand} (runtime
+// path or legacy npx). Always-converge (Ansible `blockinfile` / Kubernetes
+// Server-Side Apply sole-owner model): every recognizer match is removed and
+// replaced with exactly one canonical entry — no conflict / `--force` gate.
 // ---------------------------------------------------------------------------
-function findPeekHookIndex(sessionStart) {
-    return sessionStart.findIndex((item) => item &&
+function isCursorPeekEntry(item) {
+    return (item !== null &&
         typeof item === "object" &&
         !Array.isArray(item) &&
         isGrounderPeekHookCommand(item.command));
 }
-/** Whether `hooks.json` already lists any Grounder peek command (for status labeling). */
-async function peekHookHadGrounderEntry(filePath) {
+/** `hooks.sessionStart` from a hooks.json on disk; `null` if absent or unreadable. */
+async function readSessionStart(filePath) {
     try {
-        const parsed = JSON.parse(await readFile(filePath, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return false;
-        }
-        const hooks = parsed.hooks;
-        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
-            return false;
-        }
-        const sessionStart = hooks.sessionStart;
-        return Array.isArray(sessionStart) && findPeekHookIndex(sessionStart) >= 0;
+        return readEventEntries(JSON.parse(await readFile(filePath, "utf8")), SESSION_START_EVENT);
     }
     catch {
-        return false;
+        return null;
     }
 }
+/** Whether `hooks.json` already lists any Grounder peek command (for status labeling). */
+async function peekHookHadGrounderEntry(filePath) {
+    return ((await readSessionStart(filePath)) ?? []).some(isCursorPeekEntry);
+}
 /**
- * Skip only when the canonical command is already present *and* the runtime is
- * current for the running grounder version/source. Legacy `npx` entries or a
- * stale runtime (missing, or symlinked/copied from a different source) always
- * refresh — no `--force` required to migrate or to pick up an upgrade.
+ * Skip only when exactly one canonical entry is already present *and* the
+ * runtime is current for the running grounder version/source. Anything else
+ * — no entry, a legacy `npx` form, a drifted command, more than one match —
+ * always converges. No `--force` required to migrate or pick up an upgrade.
  */
 async function peekHookUpToDate(filePath, homeDir) {
     if (!(await fileExists(filePath))) {
@@ -110,39 +104,22 @@ async function peekHookUpToDate(filePath, homeDir) {
     if (await isHookRuntimeStale(homeDir)) {
         return false;
     }
-    try {
-        const parsed = JSON.parse(await readFile(filePath, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return false;
-        }
-        const hooks = parsed.hooks;
-        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
-            return false;
-        }
-        const sessionStart = hooks.sessionStart;
-        if (!Array.isArray(sessionStart)) {
-            return false;
-        }
-        const idx = findPeekHookIndex(sessionStart);
-        if (idx < 0) {
-            return false;
-        }
-        const command = sessionStart[idx].command;
-        return command === cursorPeekHookCommand(homeDir);
-    }
-    catch {
+    const sessionStart = await readSessionStart(filePath);
+    if (!sessionStart) {
         return false;
     }
+    return isAlreadyConverged(sessionStart, isCursorPeekEntry, {
+        command: cursorPeekHookCommand(homeDir),
+    });
 }
 /**
- * Deep-merge Grounder's sessionStart hook into an existing hooks.json object.
- *
- * Preserves every key except the nested path it owns. Strategy:
- * 1. If a Grounder peek hook already exists (runtime or legacy npx) → replace in place.
- * 2. Else → append Grounder's entry to `hooks.sessionStart`.
+ * Converge Grounder's sessionStart hook into an existing hooks.json object:
+ * remove every recognizer match (runtime-form or legacy npx, however many),
+ * append exactly one canonical entry.
  *
- * On a brand-new file (`isFreshFile`), also sets `version: 1` when absent.
- * Existing files keep whatever `version` (or lack of it) they already have.
+ * Preserves every key except the nested path it owns. On a brand-new file
+ * (`isFreshFile`), also sets `version: 1` when absent. Existing files keep
+ * whatever `version` (or lack of it) they already have.
  *
  * @param current - Parsed hooks.json root (object). Other top-level keys untouched.
  * @param isFreshFile - True when the file did not exist before this write
@@ -154,91 +131,68 @@ function mergeCursorHooks(current, isFreshFile, homeDir) {
     if (isFreshFile && next.version === undefined) {
         next.version = 1;
     }
-    const hooks = next.hooks && typeof next.hooks === "object" && !Array.isArray(next.hooks)
-        ? { ...next.hooks }
-        : {};
-    const existing = Array.isArray(hooks.sessionStart) ? [...hooks.sessionStart] : [];
-    const entry = { command: cursorPeekHookCommand(homeDir) };
-    const idx = findPeekHookIndex(existing);
-    if (idx >= 0) {
-        // Path 1: refresh existing Grounder hook entry in place
-        existing[idx] = entry;
-    }
-    else {
-        // Path 2: append — first install, or file had other sessionStart hooks only
-        existing.push(entry);
-    }
-    next.hooks = { ...hooks, sessionStart: existing };
+    const hooks = readHooksObject(next, cursorHooksJsonPath(homeDir));
+    const raw = hooks[SESSION_START_EVENT];
+    const existing = Array.isArray(raw) ? raw : [];
+    const cleaned = removeMatchingEntries(existing, isCursorPeekEntry);
+    cleaned.push({ command: cursorPeekHookCommand(homeDir) });
+    next.hooks = { ...hooks, [SESSION_START_EVENT]: cleaned };
     return next;
 }
 /**
- * Install (or refresh) Grounder's sessionStart teaser hook into `~/.cursor/hooks.json`.
- *
- * Also materializes `~/.grounder/runtime` (see {@link installHookRuntime}).
- *
- * Force semantics:
- * - Up-to-date canonical entry + fresh runtime and `force` false → skip
- * - Otherwise → refresh runtime + merge host config
- *
- * Unparseable hooks.json: {@link mergeJsonFile} backs off and this throws (never clobbers).
+ * Remove every Grounder peek entry from `hooks.sessionStart`, touching
+ * nothing else. Returns `current` verbatim (no restructuring at all) when
+ * there's no Grounder entry to remove, so `mergeJsonFile` sees no change and
+ * leaves an unrelated `hooks.json` untouched instead of reformatting it.
  */
-async function installHooks(opts) {
-    const dest = cursorHooksJsonPath(opts.homeDir);
-    const upToDate = await peekHookUpToDate(dest, opts.homeDir);
-    if (upToDate && !opts.force) {
-        return { artifacts: { [dest]: "skipped" } };
+function removeCursorHooks(current) {
+    const hooks = current.hooks && typeof current.hooks === "object" && !Array.isArray(current.hooks)
+        ? current.hooks
+        : undefined;
+    const raw = hooks?.[SESSION_START_EVENT];
+    const existing = Array.isArray(raw) ? raw : [];
+    const cleaned = removeMatchingEntries(existing, isCursorPeekEntry);
+    if (cleaned.length === existing.length) {
+        return current;
     }
-    if (opts.dryRun) {
-        const fileExisted = await fileExists(dest);
-        const hadGrounderEntry = fileExisted && (await peekHookHadGrounderEntry(dest));
-        const status = hadGrounderEntry ? "overwritten" : "created";
-        return { artifacts: { [dest]: status } };
-    }
-    await installHookRuntime({ homeDir: opts.homeDir });
-    const fileExisted = await fileExists(dest);
-    const hadGrounderEntry = fileExisted && (await peekHookHadGrounderEntry(dest));
-    const result = await mergeJsonFile(dest, (current) => mergeCursorHooks(current, !fileExisted, opts.homeDir));
-    if (!result.ok) {
-        throw new Error(result.message);
-    }
-    const status = hadGrounderEntry ? "overwritten" : "created";
-    return { artifacts: { [dest]: status } };
+    return {
+        ...current,
+        hooks: { ...hooks, [SESSION_START_EVENT]: cleaned },
+    };
+}
+/**
+ * Install (or converge) Grounder's sessionStart teaser hook into `~/.cursor/hooks.json`.
+ * @see {@link installHookFragment} for the shared install/report scaffolding.
+ */
+async function installHooks(opts) {
+    return installHookFragment({
+        dest: cursorHooksJsonPath(opts.homeDir),
+        isUpToDate: (filePath) => peekHookUpToDate(filePath, opts.homeDir),
+        hasGrounderEntry: peekHookHadGrounderEntry,
+        merge: (current, fileExisted) => mergeCursorHooks(current, !fileExisted, opts.homeDir),
+    }, opts);
+}
+/**
+ * Remove Grounder's sessionStart hook entry entirely (`--no-hooks`) — the
+ * opt-out must also remove the fragment, not just flip `hooksEnabled` false,
+ * or the session hook keeps firing and the next plain `migrate` would find
+ * nothing to converge against (an absent entry looks like "never installed",
+ * which is exactly what makes the tri-state's `false` sticky in the first
+ * place).
+ */
+async function removeHooks(opts) {
+    return removeHookFragment(cursorHooksJsonPath(opts.homeDir), removeCursorHooks, opts);
 }
 export const cursor = {
     id: "cursor",
     name: "Cursor",
-    commandsSchema: 2,
-    hooksSchema: 1,
-    async isInstalled() {
-        return fileExists(path.join(resolveHomeDir(), ".cursor"));
-    },
+    isInstalled: layout.isInstalled,
     expectedArtifacts,
     expectedHookArtifacts,
-    async install(opts) {
-        const artifacts = {};
-        const files = {};
-        for (const filename of COMMANDS) {
-            const { dest, status, hash } = await installCommandFile({
-                ...opts,
-                agentId: cursor.id,
-                templateDir,
-                commandsDir: cursorCommandsDir(opts.homeDir),
-                filename,
-            });
-            artifacts[dest] = status;
-            if (hash) {
-                files[dest] = { hash };
-            }
-        }
-        await recordCommandFileHashes({
-            agentId: cursor.id,
-            commandsSchema: cursor.commandsSchema,
-            files,
-            homeDir: opts.homeDir,
-            dryRun: opts.dryRun,
-        });
-        return { artifacts };
-    },
+    desiredArtifacts: layout.desiredArtifacts,
+    tombstones: layout.tombstones,
+    ownedPrefixes: layout.ownedPrefixes,
     installHooks,
+    removeHooks,
 };
 //# sourceMappingURL=cursor.js.map

package/dist/agents/cursor.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"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"}

package/dist/agents/home-skills.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The whole-file install layout Cursor and Claude Code share: Grounder's
+ * skills live at `~/<agentDir>/skills/<skill>/SKILL.md`, and the
+ * pre-Agent-Skills command files they replaced lived at
+ * `~/<agentDir>/commands/<skill>.md`. Give {@link homeSkillsLayout} the two
+ * names that differ between the two agents and it derives every path, template
+ * render, tombstone, and owned prefix an adapter needs for those artifacts.
+ *
+ * Hook config is deliberately not here. `~/.cursor/hooks.json` and
+ * `~/.claude/settings.json` differ in filename, in JSON shape (a flat array
+ * vs. matcher groups), and in what "already converged" even means, so each
+ * adapter keeps its own fragment reconciler; `hook-fragment.ts` and
+ * `hook-install.ts` hold the parts of *that* job which genuinely are shared.
+ */
+/** Skill directory names. Both adapters ship the same set. */
+declare const SKILL_NAMES: readonly ["grounder-note", "grounder-search", "grounder-overview", "grounder-plan", "grounder-handoff", "grounder-recall"];
+export type SkillName = (typeof SKILL_NAMES)[number];
+export interface HomeSkillsLayout {
+    /** `~/<agentDir>/skills` — where today's `SKILL.md` files live. */
+    skillsDir(homeDir?: string): string;
+    /** `~/<agentDir>/commands` — where the retired pre-skill command files lived. */
+    legacyCommandsDir(homeDir?: string): string;
+    /** Absolute path to one skill's `SKILL.md`. */
+    skillPath(skill: SkillName, homeDir?: string): string;
+    /** @see AgentAdapter.expectedArtifacts */
+    expectedArtifacts(homeDir?: string): string[];
+    /** @see AgentAdapter.desiredArtifacts */
+    desiredArtifacts(homeDir?: string, options?: {
+        invocation?: string;
+    }): Promise<Record<string, string>>;
+    /** @see AgentAdapter.tombstones */
+    tombstones(homeDir?: string): string[];
+    /** @see AgentAdapter.ownedPrefixes */
+    ownedPrefixes(homeDir?: string): string[];
+    /** @see AgentAdapter.isInstalled */
+    isInstalled(): Promise<boolean>;
+}
+export interface HomeSkillsLayoutOptions {
+    /** Adapter id — names the template directory (`templates/agents/<id>/skills`). */
+    id: string;
+    /** This agent's config directory, relative to home (e.g. `.cursor`). */
+    agentDir: string;
+}
+export declare function homeSkillsLayout(options: HomeSkillsLayoutOptions): HomeSkillsLayout;
+export {};
+//# sourceMappingURL=home-skills.d.ts.map

package/dist/agents/home-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-skills.d.ts","sourceRoot":"","sources":["../../src/agents/home-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,8DAA8D;AAC9D,QAAA,MAAM,WAAW,4HAOP,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAsBrD,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,iFAAiF;IACjF,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5C,+CAA+C;IAC/C,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtD,0CAA0C;IAC1C,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9C,yCAAyC;IACzC,gBAAgB,CACd,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnC,mCAAmC;IACnC,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvC,sCAAsC;IACtC,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1C,oCAAoC;IACpC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CA4CnF"}

package/dist/agents/home-skills.js

@@ -0,0 +1,83 @@
+/**
+ * The whole-file install layout Cursor and Claude Code share: Grounder's
+ * skills live at `~/<agentDir>/skills/<skill>/SKILL.md`, and the
+ * pre-Agent-Skills command files they replaced lived at
+ * `~/<agentDir>/commands/<skill>.md`. Give {@link homeSkillsLayout} the two
+ * names that differ between the two agents and it derives every path, template
+ * render, tombstone, and owned prefix an adapter needs for those artifacts.
+ *
+ * Hook config is deliberately not here. `~/.cursor/hooks.json` and
+ * `~/.claude/settings.json` differ in filename, in JSON shape (a flat array
+ * vs. matcher groups), and in what "already converged" even means, so each
+ * adapter keeps its own fragment reconciler; `hook-fragment.ts` and
+ * `hook-install.ts` hold the parts of *that* job which genuinely are shared.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHomeDir } from "../connector/home.js";
+import { fileExists } from "../util/fs.js";
+import { runtimeInvocation } from "./hook-runtime.js";
+/** Package root (`packages/grounder`) when running from `dist/agents/`. */
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+/** Skill directory names. Both adapters ship the same set. */
+const SKILL_NAMES = [
+    "grounder-note",
+    "grounder-search",
+    "grounder-overview",
+    "grounder-plan",
+    "grounder-handoff",
+    "grounder-recall",
+];
+/** Relative `<skill>/SKILL.md` paths, resolved under whichever agent's skills dir. */
+const SKILL_FILES = SKILL_NAMES.map((name) => path.join(name, "SKILL.md"));
+/**
+ * Frozen historical fact about the schema-3 (pre-skill) install layout —
+ * deliberately spelled out rather than derived from {@link SKILL_NAMES}, which
+ * describes today's Agent Skills layout. Deriving it would rewrite history the
+ * moment a skill is added or renamed, retiring paths that never existed while
+ * forgetting one that does. Safe to delete once schema-3 installs are assumed
+ * extinct in the wild — a maintainer call, not something to automate via a
+ * version check.
+ */
+const LEGACY_COMMAND_FILENAMES = [
+    "grounder-note.md",
+    "grounder-search.md",
+    "grounder-plan.md",
+    "grounder-task-handoff.md",
+    "grounder-task.md",
+];
+export function homeSkillsLayout(options) {
+    const templateDir = path.join(pkgRoot, "templates", "agents", options.id, "skills");
+    const agentRoot = (homeDir) => path.join(resolveHomeDir(homeDir), options.agentDir);
+    const skillsDir = (homeDir) => path.join(agentRoot(homeDir), "skills");
+    const legacyCommandsDir = (homeDir) => path.join(agentRoot(homeDir), "commands");
+    return {
+        skillsDir,
+        legacyCommandsDir,
+        skillPath: (skill, homeDir) => path.join(skillsDir(homeDir), skill, "SKILL.md"),
+        expectedArtifacts: (homeDir) => SKILL_FILES.map((filename) => path.join(skillsDir(homeDir), filename)),
+        // Arrow function, not a shorthand method — every member of this object
+        // must be reachable with no bound `this` (see the file-level doc comment
+        // on why `cursor.ts`/`claude.ts` detach these off the closure), and a
+        // shorthand method is the one member shape that can silently start using
+        // `this` and type-check fine while breaking only at those detached call
+        // sites.
+        desiredArtifacts: async (homeDir, renderOptions) => {
+            const cli = renderOptions?.invocation ?? runtimeInvocation(homeDir);
+            const dir = skillsDir(homeDir);
+            const templates = await Promise.all(SKILL_FILES.map((filename) => readFile(path.join(templateDir, filename), "utf8")));
+            const desired = {};
+            SKILL_FILES.forEach((filename, i) => {
+                desired[path.join(dir, filename)] = templates[i].replaceAll("{{GROUNDER_CLI}}", cli);
+            });
+            return desired;
+        },
+        tombstones: (homeDir) => LEGACY_COMMAND_FILENAMES.map((filename) => path.join(legacyCommandsDir(homeDir), filename)),
+        ownedPrefixes: (homeDir) => [skillsDir(homeDir), legacyCommandsDir(homeDir)],
+        // No `homeDir` argument on purpose: detection runs before any per-call
+        // home override exists, off `GROUNDER_HOME` / `withHomeDir` alone.
+        isInstalled: async () => fileExists(agentRoot()),
+    };
+}
+//# sourceMappingURL=home-skills.js.map

package/dist/agents/home-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-skills.js","sourceRoot":"","sources":["../../src/agents/home-skills.ts"],"names":[],"mappings":"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"}

package/dist/agents/hook-fragment.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Generic pieces of the session-hook fragment reconciler shared by
+ * `cursor.ts` (flat `hooks.sessionStart` array) and `claude.ts` (nested
+ * `hooks.SessionStart` matcher groups, each with its own `hooks` array).
+ *
+ * Model: Ansible `blockinfile` / Kubernetes Server-Side Apply's sole-owner
+ * case — locate every entry a recognizer predicate matches (there may be
+ * more than one: a legacy `npx grounder handoff peek` entry alongside a
+ * runtime-form one, say), remove all of them, and always converge to exactly
+ * one canonical entry. No conflict / `--force` gate — Grounder solely owns
+ * this one nested entry, there is nothing a user could have "locally edited"
+ * the way a whole skill file can be.
+ */
+/**
+ * The entries registered for one hook event (`hooks.<event>`) in an
+ * already-parsed config root, or `null` when the file has no such array —
+ * a non-object root, no `hooks` key, a `hooks` that isn't an object, or an
+ * event key that is absent or not an array.
+ *
+ * `null` rather than `[]` because the two callers want opposite things from
+ * "nothing there": counting existing entries treats it as empty, while
+ * "already converged?" must answer `false` and go on to converge.
+ */
+export declare function readEventEntries(parsed: unknown, event: string): unknown[] | null;
+/**
+ * Grounder's fragment lives at `hooks.<event>`, so a merge has to read `hooks`
+ * as a JSON object. A present-but-non-object `hooks` (an array, a string, a
+ * number) is refused rather than replaced: these are shared config files whose
+ * unrelated keys Grounder promises to preserve, and silently dropping a value
+ * it can't interpret is the one way a merge could destroy user data. Refusing
+ * matches how {@link mergeJsonFile} already backs off an unparseable root or a
+ * non-object top level — same contract, one level deeper.
+ *
+ * `null` and absent both mean "nothing there yet" and yield a fresh `{}` —
+ * neither carries content a user could lose.
+ *
+ * Returns a shallow copy, so callers can mutate the result without touching
+ * the parsed original (`mergeJsonFile` compares by reference to decide whether
+ * anything changed).
+ */
+export declare function readHooksObject(current: Record<string, unknown>, filePath: string): Record<string, unknown>;
+/** Remove every entry `isMatch` accepts, preserving order of the rest. */
+export declare function removeMatchingEntries<T>(entries: readonly T[], isMatch: (entry: T) => boolean): T[];
+/**
+ * True when `entries` already holds exactly one match and it is byte-for-byte
+ * the canonical entry (same keys, same order) — the only case a fragment
+ * reconciler should report as already-converged (no write needed). Two
+ * matches, zero matches, or a single match with drifted content all count as
+ * "not yet converged."
+ */
+export declare function isAlreadyConverged<T>(entries: readonly T[], isMatch: (entry: T) => boolean, canonical: T): boolean;
+//# sourceMappingURL=hook-fragment.d.ts.map

package/dist/agents/hook-fragment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-fragment.d.ts","sourceRoot":"","sources":["../../src/agents/hook-fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,IAAI,CAUjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAC7B,CAAC,EAAE,CAEL;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAC9B,SAAS,EAAE,CAAC,GACX,OAAO,CAGT"}

package/dist/agents/hook-fragment.js

@@ -0,0 +1,76 @@
+/**
+ * Generic pieces of the session-hook fragment reconciler shared by
+ * `cursor.ts` (flat `hooks.sessionStart` array) and `claude.ts` (nested
+ * `hooks.SessionStart` matcher groups, each with its own `hooks` array).
+ *
+ * Model: Ansible `blockinfile` / Kubernetes Server-Side Apply's sole-owner
+ * case — locate every entry a recognizer predicate matches (there may be
+ * more than one: a legacy `npx grounder handoff peek` entry alongside a
+ * runtime-form one, say), remove all of them, and always converge to exactly
+ * one canonical entry. No conflict / `--force` gate — Grounder solely owns
+ * this one nested entry, there is nothing a user could have "locally edited"
+ * the way a whole skill file can be.
+ */
+/**
+ * The entries registered for one hook event (`hooks.<event>`) in an
+ * already-parsed config root, or `null` when the file has no such array —
+ * a non-object root, no `hooks` key, a `hooks` that isn't an object, or an
+ * event key that is absent or not an array.
+ *
+ * `null` rather than `[]` because the two callers want opposite things from
+ * "nothing there": counting existing entries treats it as empty, while
+ * "already converged?" must answer `false` and go on to converge.
+ */
+export function readEventEntries(parsed, event) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
+        return null;
+    }
+    const entries = hooks[event];
+    return Array.isArray(entries) ? entries : null;
+}
+/**
+ * Grounder's fragment lives at `hooks.<event>`, so a merge has to read `hooks`
+ * as a JSON object. A present-but-non-object `hooks` (an array, a string, a
+ * number) is refused rather than replaced: these are shared config files whose
+ * unrelated keys Grounder promises to preserve, and silently dropping a value
+ * it can't interpret is the one way a merge could destroy user data. Refusing
+ * matches how {@link mergeJsonFile} already backs off an unparseable root or a
+ * non-object top level — same contract, one level deeper.
+ *
+ * `null` and absent both mean "nothing there yet" and yield a fresh `{}` —
+ * neither carries content a user could lose.
+ *
+ * Returns a shallow copy, so callers can mutate the result without touching
+ * the parsed original (`mergeJsonFile` compares by reference to decide whether
+ * anything changed).
+ */
+export function readHooksObject(current, filePath) {
+    const hooks = current.hooks;
+    if (hooks === undefined || hooks === null) {
+        return {};
+    }
+    if (typeof hooks !== "object" || Array.isArray(hooks)) {
+        throw new Error(`Refusing to modify ${filePath}: "hooks" must be a JSON object`);
+    }
+    return { ...hooks };
+}
+/** Remove every entry `isMatch` accepts, preserving order of the rest. */
+export function removeMatchingEntries(entries, isMatch) {
+    return entries.filter((entry) => !isMatch(entry));
+}
+/**
+ * True when `entries` already holds exactly one match and it is byte-for-byte
+ * the canonical entry (same keys, same order) — the only case a fragment
+ * reconciler should report as already-converged (no write needed). Two
+ * matches, zero matches, or a single match with drifted content all count as
+ * "not yet converged."
+ */
+export function isAlreadyConverged(entries, isMatch, canonical) {
+    const matches = entries.filter(isMatch);
+    return matches.length === 1 && JSON.stringify(matches[0]) === JSON.stringify(canonical);
+}
+//# sourceMappingURL=hook-fragment.js.map