grounder 0.5.0 → 0.6.0

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

package/dist/agents/hook-fragment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-fragment.js","sourceRoot":"","sources":["../../src/agents/hook-fragment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAe,EAAE,KAAa;IAC7D,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAI,MAAkC,CAAC,KAAK,CAAC;IACxD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAI,KAAiC,CAAC,KAAK,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgC,EAChC,QAAgB;IAEhB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,sBAAsB,QAAQ,iCAAiC,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,EAAE,GAAI,KAAiC,EAAE,CAAC;AACnD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CACnC,OAAqB,EACrB,OAA8B;IAE9B,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAqB,EACrB,OAA8B,EAC9B,SAAY;IAEZ,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;AAC1F,CAAC"}

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

@@ -0,0 +1,62 @@
+/**
+ * The I/O scaffolding both hook adapters run around their own merge functions:
+ * read, converge, write, and report which of created/overwritten/skipped
+ * happened. Kept out of `hook-fragment.ts` so that module stays pure — the
+ * same split `reconcile/` draws between `core.ts` and `apply.ts`.
+ *
+ * What stays adapter-specific is the fragment shape itself: the recognizer
+ * predicate, where a canonical entry belongs, and what "already converged"
+ * means (Cursor: exactly one match in a flat array; Claude Code: exactly one
+ * match, under the canonical matcher group). Those arrive here as callbacks.
+ */
+import type { AgentInstallOptions, AgentInstallResult } from "./types.js";
+export interface HookFragmentInstall {
+    /** The shared JSON config this fragment lives in. */
+    dest: string;
+    /**
+     * Skip the write entirely — exactly one canonical entry is already present
+     * *and* the shared runtime is current. Anything else converges.
+     */
+    isUpToDate(filePath: string): Promise<boolean>;
+    /**
+     * Does the file already list any Grounder entry (in any form, including a
+     * legacy `npx` one)? Decides whether a write reports `overwritten` rather
+     * than `created`. Only consulted when the file exists.
+     */
+    hasGrounderEntry(filePath: string): Promise<boolean>;
+    /**
+     * Converge the fragment into a parsed config root, returning the new root.
+     * `fileExisted` is passed through for the one thing that depends on it
+     * (Cursor stamps `version: 1` only onto a file it is creating).
+     */
+    merge(current: Record<string, unknown>, fileExisted: boolean): Record<string, unknown>;
+}
+/**
+ * Install (or converge) a hook fragment, also materializing `~/.grounder/runtime`
+ * on a real run if it's stale. Always converges the fragment itself — no
+ * `--force` gate; `force` only affects whole-file skill artifacts, never a
+ * shared-JSON fragment.
+ *
+ * The runtime materialization is gated on {@link isHookRuntimeStale}, not
+ * unconditional: an invocation running through the materialized runtime's
+ * own `dist/cli.js` (e.g. `{{GROUNDER_CLI}}` in a skill) has
+ * `defaultPackageRoot` resolve to the runtime itself, which
+ * {@link installHookRuntime} refuses to materialize from (see its doc
+ * comment) — skipping the call here when the runtime is already current
+ * avoids that throw.
+ *
+ * Never clobbers: an unparseable config backs off inside {@link mergeJsonFile},
+ * and a `merge` that refuses (see `readHooksObject`) throws before any write.
+ */
+export declare function installHookFragment(install: HookFragmentInstall, opts: AgentInstallOptions): Promise<AgentInstallResult>;
+/**
+ * Remove a hook fragment entirely (`--no-hooks`). Reports an artifact only
+ * when something actually changed, so an agent that never had the entry
+ * contributes no row to the install table.
+ *
+ * `remove` is expected to return its argument by reference when there is
+ * nothing to remove — that is what stops {@link mergeJsonFile} from
+ * reformatting an unrelated config file on its way to a no-op.
+ */
+export declare function removeHookFragment(dest: string, remove: (current: Record<string, unknown>) => Record<string, unknown>, opts: AgentInstallOptions): Promise<AgentInstallResult>;
+//# sourceMappingURL=hook-install.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hook-install.d.ts","sourceRoot":"","sources":["../../src/agents/hook-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAkB,MAAM,YAAY,CAAC;AAE1F,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAS7B"}

package/dist/agents/hook-install.js

@@ -0,0 +1,74 @@
+/**
+ * The I/O scaffolding both hook adapters run around their own merge functions:
+ * read, converge, write, and report which of created/overwritten/skipped
+ * happened. Kept out of `hook-fragment.ts` so that module stays pure — the
+ * same split `reconcile/` draws between `core.ts` and `apply.ts`.
+ *
+ * What stays adapter-specific is the fragment shape itself: the recognizer
+ * predicate, where a canonical entry belongs, and what "already converged"
+ * means (Cursor: exactly one match in a flat array; Claude Code: exactly one
+ * match, under the canonical matcher group). Those arrive here as callbacks.
+ */
+import { fileExists } from "../util/fs.js";
+import { mergeJsonFile } from "../util/merge-json.js";
+import { installHookRuntime, isHookRuntimeStale } from "./hook-runtime.js";
+/**
+ * Install (or converge) a hook fragment, also materializing `~/.grounder/runtime`
+ * on a real run if it's stale. Always converges the fragment itself — no
+ * `--force` gate; `force` only affects whole-file skill artifacts, never a
+ * shared-JSON fragment.
+ *
+ * The runtime materialization is gated on {@link isHookRuntimeStale}, not
+ * unconditional: an invocation running through the materialized runtime's
+ * own `dist/cli.js` (e.g. `{{GROUNDER_CLI}}` in a skill) has
+ * `defaultPackageRoot` resolve to the runtime itself, which
+ * {@link installHookRuntime} refuses to materialize from (see its doc
+ * comment) — skipping the call here when the runtime is already current
+ * avoids that throw.
+ *
+ * Never clobbers: an unparseable config backs off inside {@link mergeJsonFile},
+ * and a `merge` that refuses (see `readHooksObject`) throws before any write.
+ */
+export async function installHookFragment(install, opts) {
+    const dest = install.dest;
+    if (await install.isUpToDate(dest)) {
+        return { artifacts: { [dest]: "skipped" } };
+    }
+    if (!opts.dryRun && (await isHookRuntimeStale(opts.homeDir))) {
+        await installHookRuntime({ homeDir: opts.homeDir });
+    }
+    const fileExisted = await fileExists(dest);
+    const hadGrounderEntry = fileExisted && (await install.hasGrounderEntry(dest));
+    const result = await mergeJsonFile(dest, (current) => install.merge(current, fileExisted), {
+        dryRun: opts.dryRun,
+    });
+    if (!result.ok) {
+        throw new Error(result.message);
+    }
+    const status = !result.changed
+        ? "skipped"
+        : hadGrounderEntry
+            ? "overwritten"
+            : "created";
+    return { artifacts: { [dest]: status } };
+}
+/**
+ * Remove a hook fragment entirely (`--no-hooks`). Reports an artifact only
+ * when something actually changed, so an agent that never had the entry
+ * contributes no row to the install table.
+ *
+ * `remove` is expected to return its argument by reference when there is
+ * nothing to remove — that is what stops {@link mergeJsonFile} from
+ * reformatting an unrelated config file on its way to a no-op.
+ */
+export async function removeHookFragment(dest, remove, opts) {
+    if (!(await fileExists(dest))) {
+        return { artifacts: {} };
+    }
+    const result = await mergeJsonFile(dest, remove, { dryRun: opts.dryRun });
+    if (!result.ok) {
+        throw new Error(result.message);
+    }
+    return result.changed ? { artifacts: { [dest]: "overwritten" } } : { artifacts: {} };
+}
+//# sourceMappingURL=hook-install.js.map

package/dist/agents/hook-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-install.js","sourceRoot":"","sources":["../../src/agents/hook-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAyB3E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA4B,EAC5B,IAAyB;IAEzB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1B,IAAI,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QAC7D,MAAM,kBAAkB,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,gBAAgB,GAAG,WAAW,IAAI,CAAC,MAAM,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE;QACzF,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,MAAM,GAAmB,CAAC,MAAM,CAAC,OAAO;QAC5C,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,gBAAgB;YAChB,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,MAAqE,EACrE,IAAyB;IAEzB,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAC3B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1E,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;AACvF,CAAC"}

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

@@ -1,14 +1,14 @@
 /**
- * Home-local runtime shared by session hooks *and* slash commands (originally
+ * Home-local runtime shared by session hooks *and* skills (originally
  * "Issue 2 — replace `npx grounder` in session hooks"; later extended to cover
- * slash-command templates too, since they had the identical problem).
+ * skill templates too, since they had the identical problem).
  *
  * ## Why
  * Both surfaces used to shell out via `npx grounder …`. `npx <pkg>` (no
  * version specifier) matches against whatever `grounder` version exists in
  * the *current project's own dependencies*; only when the project doesn't
  * declare `grounder` as a dependency does it fall back to fetching
- * `grounder@latest` from the registry. Session hooks and slash commands both
+ * `grounder@latest` from the registry. Session hooks and skills both
  * run from arbitrary linked projects, which normally have no reason to depend
  * on `grounder` themselves, so contributors (and anyone ahead of the last
  * publish, or deliberately pinned to an older version) get the wrong binary.
@@ -18,7 +18,7 @@
  * ## Design
  * On `setup`, materialize this package's `dist/` at
  * `~/.grounder/runtime/dist/` and point both host hook configs *and* the
- * commands copied into `~/.cursor/commands/` / `~/.claude/commands/` at:
+ * skills copied into `~/.cursor/skills/` / `~/.claude/skills/` at:
  *   `process.execPath` + `~/.grounder/runtime/dist/cli.js` + `<subcommand> …`
  * No global install and no registry fetch at invocation time, for either
  * surface. This mirrors how Corepack (packageManager shims) and Husky/lint-staged
@@ -32,7 +32,9 @@
  *   pick up new code immediately — no re-run of `setup` ever needed.
  * - **Ephemeral source** (bare `npx grounder …`, no install — each invocation
  *   resolves to an immutable, version-keyed npx cache dir that can be evicted
- *   or swapped out from under a symlink) → **copy** `dist/`. Re-run
+ *   or swapped out from under a symlink) → **copy** `dist/`, plus
+ *   `package.json` and `templates/` alongside it (see {@link installHookRuntime}'s
+ *   doc comment for why those siblings are needed). Re-run
  *   `grounder setup <vault>` after upgrading to refresh; this is an
  *   inherent limitation of using npx with no install for something that must
  *   persist, not something we can engineer around.
@@ -84,14 +86,14 @@ export declare function shellQuote(value: string): string;
  */
 export declare function extractRuntimeNodePath(command: unknown): string | null;
 /**
- * Find every baked Node interpreter path embedded in free-form text (slash-command
+ * Find every baked Node interpreter path embedded in free-form text (skill
  * markdown, etc.). Scans for the same `'<abs node>' '<abs …/cli.js>'` shape as
  * {@link extractRuntimeNodePath}, including mid-line / backtick-wrapped uses.
  */
 export declare function findRuntimeNodePathsInText(text: string): string[];
 /**
  * Quoted `<node> <runtime cli.js>` prefix, shared by every home-runtime
- * invocation (session hooks and slash-command templates alike). Append
+ * invocation (session hooks and skill templates alike). Append
  * subcommand args to build a full command string.
  */
 export declare function runtimeInvocation(homeDir?: string): string;
@@ -119,24 +121,89 @@ export declare function hookFileHasGrounderEntry(filePath: string): Promise<bool
 /**
  * True when the materialized runtime is missing or out of date for the given
  * source package:
+ * - **Self-referential** (`packageRoot` is `~/.grounder/runtime` itself —
+ *   see {@link isSelfReferential}): never stale. There is no real source to
+ *   compare against from inside this invocation, so the only sound answer is
+ *   "leave it alone."
  * - **Symlink mode** (durable source): stale iff `dist/` isn't currently a
  *   symlink resolving to this source's `dist/` (cheap `realpath` compare — no
  *   staleness window, since a matching symlink is *always* current).
  * - **Copy mode** (ephemeral `npx` source): stale iff the manifest is
- *   missing/unreadable or its recorded version differs from this source's.
+ *   missing/unreadable, its recorded version differs from this source's, or
+ *   `package.json` / `templates/` (when the source has one) are missing
+ *   alongside `dist/` — a same-version repair case a version-only check
+ *   would otherwise skip forever (e.g. a runtime materialized before these
+ *   siblings were added, or one left mid-way by a partial install).
  *
  * @param packageRoot - Source package root to compare against (defaults to the
  *   currently running package — override only in tests)
  */
 export declare function isHookRuntimeStale(homeDir?: string, packageRoot?: string): Promise<boolean>;
+/**
+ * Materialization mode this source would use — symlink (durable) or copy
+ * (ephemeral `npx` cache) — without writing anything (read-only `realpath`
+ * checks only). Lets callers label a skipped/dry-run install the same way
+ * {@link installHookRuntime} would.
+ */
+export declare function runtimeMode(packageRoot?: string): Promise<"symlink" | "copy">;
+/**
+ * Materialize every artifact via `populate(stagingPath)` first — a
+ * populate/symlink/cp failure on any one of them leaves every `dest`
+ * untouched, since none have been promoted yet. Only once all of them are
+ * staged does promotion (backup-aside + rename-in) run for each in turn.
+ *
+ * If a promote fails partway through, every artifact already promoted in
+ * this call is rolled back (its backup renamed back over `dest`) before
+ * rethrowing — so a failure on, say, `package.json` after `dist/` has
+ * already promoted doesn't leave a new `dist/` sitting next to an old
+ * `package.json`. This isn't a true single filesystem transaction (POSIX
+ * has no atomic rename across independent paths), but it narrows the
+ * mixed-state window down to the renames themselves rather than leaving one
+ * as a visible end state after this function returns (successfully or not).
+ *
+ * A restore rename (`backup` back over `dest`) can itself fail — e.g. the
+ * same fault that broke the promote also blocks the rename back. When that
+ * happens `dest` is left in whatever state the failed renames put it in, but
+ * `backup` is deliberately *not* deleted by the cleanup below: it's the only
+ * remaining copy of what was there before this call, so a double failure
+ * degrades to "manual recovery from `<dest>.bak`" rather than silent data
+ * loss.
+ *
+ * `populate` decides how each artifact's staging gets filled (symlink vs.
+ * plain copy) — everything else (staging, backup, promote, rollback,
+ * cleanup) is identical for every artifact {@link installHookRuntime}
+ * materializes (`dist/`, and in copy mode, `package.json` / `templates/`).
+ */
+export declare function installArtifacts(artifacts: Array<{
+    dest: string;
+    populate: (staging: string) => Promise<void>;
+}>): Promise<void>;
 /**
  * Materialize this package's `dist/` at `~/.grounder/runtime/dist/` — symlinked
  * when the source is durable, copied when it's an ephemeral `npx` cache — and
  * write a manifest recording how.
  *
+ * Copy mode also copies `package.json` and `templates/` alongside `dist/`:
+ * `src/index.ts` reads `VERSION` from `<pkgRoot>/package.json` eagerly at
+ * import (every invocation), and `home-skills.ts` reads `<pkgRoot>/templates`
+ * on demand (`desiredArtifacts()` — real installs, and the drift check
+ * `status`/`doctor`/`peek` run). Neither exists under a copied `dist/`'s
+ * parent otherwise, so the materialized runtime crashed at import for every
+ * copy-mode (bare `npx grounder setup`) user. Symlink mode needs neither —
+ * Node resolves `import.meta.url` through `dist/`'s own symlink back to the
+ * real package root, package.json and templates included — and actively
+ * removes them if a previous copy-mode install left them behind, so
+ * `~/.grounder/runtime` never ends up with stale copy-mode siblings next to
+ * a symlinked `dist/`.
+ *
  * Callers should gate on {@link isHookRuntimeStale} (or `force`) before calling —
- * this always replaces whatever is currently at the destination, staging the
- * new materialization first so a failed symlink/cp leaves the live runtime intact.
+ * this always replaces whatever is currently at the destination. All
+ * artifacts (`dist/`, and in copy mode, `package.json` / `templates/`) are
+ * staged and promoted together via {@link installArtifacts}, which rolls
+ * back any artifact already promoted if a later one fails to promote.
+ * Refuses outright (see {@link isSelfReferential}) rather than attempting a
+ * self-symlink that would corrupt the runtime with an `ELOOP`-inducing link
+ * to itself.
  *
  * @param options.packageRoot - Source package root to materialize (defaults to
  *   the currently running package — override only in tests)

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

@@ -1 +1 @@
-{"version":3,"file":"hook-runtime.d.ts","sourceRoot":"","sources":["../../src/agents/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAkBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjD,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAgCD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAyBtE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAcjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAE3F;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAanE;AAED,mFAAmF;AACnF,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAqBxE;AAED,mFAAmF;AACnF,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvE;AAED,qGAAqG;AACrG,wBAAsB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUtF;AAED,gFAAgF;AAChF,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjF;AA2DD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,GAAE,MAA2B,GACvC,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC,CAkEjF"}
+{"version":3,"file":"hook-runtime.d.ts","sourceRoot":"","sources":["../../src/agents/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAkBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjD,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AA+DD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKtE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAcjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAE3F;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAanE;AAED,mFAAmF;AACnF,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAqBxE;AAED,mFAAmF;AACnF,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvE;AAED,qGAAqG;AACrG,wBAAsB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUtF;AAED,gFAAgF;AAChF,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjF;AAuGD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,GAAE,MAA2B,GACvC,OAAO,CAAC,OAAO,CAAC,CAmClB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,WAAW,GAAE,MAA2B,GACvC,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,CAE7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,GAC/E,OAAO,CAAC,IAAI,CAAC,CAqEf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;CAAE,CAAC,CA0EjF"}