grounder 0.1.0 → 0.3.0

package/dist/agents/cursor-hook-input.js

@@ -0,0 +1,80 @@
+/** Max wait for piped Cursor hook JSON on stdin before giving up. */
+const STDIN_TIMEOUT_MS = 200;
+/**
+ * Read Cursor's sessionStart hook payload from stdin and return the first
+ * workspace root when present.
+ *
+ * Cursor pipes JSON like `{ "workspace_roots": ["/path/to/repo"] }` into
+ * user-level hooks, whose `cwd` is `~/.cursor` — not the open project.
+ *
+ * Never throws. Returns `undefined` for TTY stdin, empty/malformed input,
+ * missing `workspace_roots`, or when no data arrives within the timeout
+ * (so interactive/`grounder handoff peek` runs never hang). If data arrived
+ * but stdin has not ended yet, the buffered payload is still parsed.
+ */
+export async function readCursorHookWorkspaceRoot(stdin = process.stdin) {
+    if ("isTTY" in stdin && stdin.isTTY) {
+        return undefined;
+    }
+    const raw = await readStdinWithTimeout(stdin, STDIN_TIMEOUT_MS);
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return undefined;
+        }
+        const roots = parsed.workspace_roots;
+        if (!Array.isArray(roots) || roots.length === 0) {
+            return undefined;
+        }
+        const first = roots[0];
+        if (typeof first !== "string" || first.trim() === "") {
+            return undefined;
+        }
+        return first;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readStdinWithTimeout(stdin, timeoutMs) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let settled = false;
+        const settle = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.off("error", onError);
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        };
+        const buffered = () => {
+            if (chunks.length === 0) {
+                return undefined;
+            }
+            return Buffer.concat(chunks).toString("utf8");
+        };
+        const onEnd = () => settle(buffered());
+        const onError = () => settle(undefined);
+        // On timeout, still use whatever arrived — Cursor may flush the JSON
+        // payload before closing stdin; discarding it would lose workspace_roots.
+        const timer = setTimeout(() => settle(buffered()), timeoutMs);
+        timer.unref?.();
+        stdin.on("data", onData);
+        stdin.on("end", onEnd);
+        stdin.on("error", onError);
+        if ("readableEnded" in stdin && stdin.readableEnded) {
+            onEnd();
+        }
+    });
+}
+//# sourceMappingURL=cursor-hook-input.js.map

package/dist/agents/cursor-hook-input.js.map

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

package/dist/agents/cursor.d.ts

@@ -1,8 +1,19 @@
 import type { AgentAdapter } from "./types.js";
+/**
+ * Canonical sessionStart command for Cursor (home-local runtime, not `npx`).
+ * Always includes `--json` so stdout matches Cursor's `additional_context` contract.
+ * @see {@link peekHookCommand}
+ */
+export declare function cursorPeekHookCommand(homeDir?: string, extraArgs?: readonly string[]): string;
 export declare function cursorCommandsDir(homeDir?: string): string;
+/** Absolute path to Cursor's shared hooks config (`~/.cursor/hooks.json`). */
+export declare function cursorHooksJsonPath(homeDir?: string): string;
 export declare function grounderNoteCommandPath(homeDir?: string): string;
+export declare function grounderPlanCommandPath(homeDir?: string): string;
 export declare function grounderTaskHandoffCommandPath(homeDir?: string): string;
 export declare function grounderTaskCommandPath(homeDir?: string): string;
 export declare function expectedArtifacts(homeDir?: string): string[];
+/** Paths of hook config this adapter touches — currently just `hooks.json`. */
+export declare function expectedHookArtifacts(homeDir?: string): string[];
 export declare const cursor: AgentAdapter;
 //# sourceMappingURL=cursor.d.ts.map

package/dist/agents/cursor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AAOpB,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAkBD,eAAO,MAAM,MAAM,EAAE,YAkBpB,CAAC"}
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AAYpB;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,GAAE,SAAS,MAAM,EAAe,GACxC,MAAM,CAER;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhE;AAkLD,eAAO,MAAM,MAAM,EAAE,YAyCpB,CAAC"}

package/dist/agents/cursor.js

@@ -1,17 +1,40 @@
-import { copyFile, mkdir } from "node:fs/promises";
+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-task-handoff.md", "grounder-task.md"];
+const COMMANDS = [
+    "grounder-note.md",
+    "grounder-plan.md",
+    "grounder-task-handoff.md",
+    "grounder-task.md",
+];
+/**
+ * Canonical sessionStart command for Cursor (home-local runtime, not `npx`).
+ * Always includes `--json` so stdout matches Cursor's `additional_context` contract.
+ * @see {@link peekHookCommand}
+ */
+export function cursorPeekHookCommand(homeDir, extraArgs = ["--json"]) {
+    return peekHookCommand(homeDir, extraArgs);
+}
 export function cursorCommandsDir(homeDir) {
     return path.join(resolveHomeDir(homeDir), ".cursor", "commands");
 }
+/** 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");
 }
+export function grounderPlanCommandPath(homeDir) {
+    return path.join(cursorCommandsDir(homeDir), "grounder-plan.md");
+}
 export function grounderTaskHandoffCommandPath(homeDir) {
     return path.join(cursorCommandsDir(homeDir), "grounder-task-handoff.md");
 }
@@ -21,30 +44,202 @@ export function grounderTaskCommandPath(homeDir) {
 export function expectedArtifacts(homeDir) {
     return COMMANDS.map((filename) => path.join(cursorCommandsDir(homeDir), filename));
 }
-async function installCommand(filename, opts) {
-    const dest = path.join(cursorCommandsDir(opts.homeDir), filename);
-    const existed = await fileExists(dest);
-    if (existed && !opts.force) {
-        return { dest, status: "skipped" };
+/** Paths of hook config this adapter touches — currently just `hooks.json`. */
+export function expectedHookArtifacts(homeDir) {
+    return [cursorHooksJsonPath(homeDir)];
+}
+// ---------------------------------------------------------------------------
+// Session-start hook install (~/.cursor/hooks.json)
+//
+// Cursor hooks.json is a shared JSON object. Grounder only owns one entry in
+// `hooks.sessionStart`; unrelated keys (other hook events, version, etc.) must
+// survive merge. Relevant shape after install (path varies by home / Node):
+//
+//   {
+//     "version": 1,
+//     "hooks": {
+//       "sessionStart": [
+//         { "command": "'/path/to/node' '/path/to/.grounder/runtime/dist/cli.js' handoff peek --json" }
+//       ]
+//     }
+//   }
+//
+// Terminology used below:
+//   - hooks root     → the whole hooks.json object
+//   - hooks          → hooksRoot.hooks (map of event name → hook entries)
+//   - sessionStart   → hooks.sessionStart (flat array of { command } objects)
+//   - 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).
+// ---------------------------------------------------------------------------
+function findPeekHookIndex(sessionStart) {
+    return sessionStart.findIndex((item) => item &&
+        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) {
+    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;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+async function peekHookUpToDate(filePath, homeDir) {
+    if (!(await fileExists(filePath))) {
+        return false;
+    }
+    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 {
+        return false;
+    }
+}
+/**
+ * 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`.
+ *
+ * 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
+ * @param homeDir - Home override for the canonical command path
+ * @returns New hooks object with `hooks.sessionStart` updated
+ */
+function mergeCursorHooks(current, isFreshFile, homeDir) {
+    const next = { ...current };
+    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 };
+    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).
+ */
+async function installHooks(opts) {
+    const dest = cursorHooksJsonPath(opts.homeDir);
+    const upToDate = await peekHookUpToDate(dest, opts.homeDir);
+    if (upToDate && !opts.force) {
+        return { artifacts: { [dest]: "skipped" } };
+    }
+    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);
     }
-    await mkdir(path.dirname(dest), { recursive: true });
-    await copyFile(path.join(templateDir, filename), dest);
-    return { dest, status: existed ? "overwritten" : "created" };
+    const status = hadGrounderEntry ? "overwritten" : "created";
+    return { artifacts: { [dest]: status } };
 }
 export const cursor = {
     id: "cursor",
     name: "Cursor",
+    commandsSchema: 1,
+    hooksSchema: 1,
     async isInstalled() {
         return fileExists(path.join(resolveHomeDir(), ".cursor"));
     },
     expectedArtifacts,
+    expectedHookArtifacts,
     async install(opts) {
         const artifacts = {};
+        const files = {};
         for (const filename of COMMANDS) {
-            const { dest, status } = await installCommand(filename, opts);
+            const { dest, status, hash } = await installCommandFile({
+                ...opts,
+                agentId: cursor.id,
+                commandsSchema: cursor.commandsSchema,
+                templateDir,
+                commandsDir: cursorCommandsDir(opts.homeDir),
+                filename,
+            });
             artifacts[dest] = status;
+            if (hash) {
+                files[dest] = { schema: cursor.commandsSchema, hash };
+            }
         }
+        await recordCommandFileHashes({
+            agentId: cursor.id,
+            commandsSchema: cursor.commandsSchema,
+            files,
+            homeDir: opts.homeDir,
+            dryRun: opts.dryRun,
+        });
         return { artifacts };
     },
+    installHooks,
 };
 //# 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/hook-runtime.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Home-local runtime shared by session hooks *and* slash commands (originally
+ * "Issue 2 — replace `npx grounder` in session hooks"; later extended to cover
+ * slash-command 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
+ * 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.
+ * Global `pnpm link` / `pnpm add -g` does not change this fallback — see
+ * [npm/cli#9244](https://github.com/npm/cli/issues/9244).
+ *
+ * ## Design
+ * On `vault init`, 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:
+ *   `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
+ * (moved off bare `npx` for the same reason, see the strapi/strapi#27006 fix)
+ * solve the identical "ambient resolution isn't stable" problem.
+ *
+ * How it's materialized depends on where grounder is running from:
+ * - **Durable source** (monorepo checkout, global install, linked devDependency) →
+ *   **symlink** `dist/` straight to the source. `pnpm build` / upgrading the
+ *   global install overwrites that same path in place, so hooks and commands
+ *   pick up new code immediately — no re-run of `vault init` 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
+ *   `grounder vault init <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.
+ *
+ * This mirrors husky/pre-commit hook shims: staying current is an explicit,
+ * idempotent step (never silent self-healing inside a hook itself — session
+ * hooks must stay fast and side-effect-free), and the step is a no-op unless
+ * something has actually changed.
+ *
+ * ## REVERT
+ * To restore the previous `npx grounder …` behavior for hooks and/or commands:
+ * 1. Delete this file and its tests (`test/agents/hook-runtime.test.ts`).
+ * 2. In `cursor.ts` / `claude.ts`, set `*_PEEK_HOOK_COMMAND` back to
+ *    `"npx grounder handoff peek"` and `installCommand` back to a plain
+ *    `copyFile` (drop the `{{GROUNDER_CLI}}` template substitution), dropping
+ *    calls to {@link installHookRuntime} / {@link peekHookCommand} /
+ *    {@link runtimeInvocation} / {@link extractRuntimeNodePath} /
+ *    {@link findRuntimeNodePathsInText} /
+ *    {@link collectGrounderPeekHookCommands} / {@link hookFileGrounderPeekCommands} /
+ *    {@link isGrounderPeekHookCommand} / {@link isHookRuntimeStale}.
+ * 3. Remove runtime paths from `expectedHookArtifacts` and docs that mention
+ *    `~/.grounder/runtime`, and revert templates' `{{GROUNDER_CLI}}` back to
+ *    literal `npx grounder`.
+ */
+import type { ArtifactStatus } from "./types.js";
+/** Marker written next to the materialized runtime for debugging / staleness checks. */
+export interface HookRuntimeManifest {
+    mode: "symlink" | "copy";
+    version: string;
+    sourcePackageRoot: string;
+    installedAt: string;
+}
+/** `~/.grounder/runtime` — private materialization of the CLI used only by session hooks. */
+export declare function grounderRuntimeDir(homeDir?: string): string;
+/** Absolute path to the materialized CLI entry (`…/runtime/dist/cli.js`). */
+export declare function runtimeCliPath(homeDir?: string): string;
+export declare function runtimeManifestPath(homeDir?: string): string;
+/**
+ * POSIX-safe single-quote for embedding paths in hook `command` strings
+ * (Cursor/Claude run hooks via a shell on macOS/Linux and Git Bash on Windows).
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * Extract the baked Node interpreter path from a home-runtime invocation
+ * string (`'<abs node>' '<abs …/runtime/dist/cli.js>' …`).
+ *
+ * Returns `null` when the string is not that exact shape — including legacy
+ * `npx grounder …` entries, which have no absolute interpreter to validate.
+ */
+export declare function extractRuntimeNodePath(command: unknown): string | null;
+/**
+ * Find every baked Node interpreter path embedded in free-form text (slash-command
+ * 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
+ * subcommand args to build a full command string.
+ */
+export declare function runtimeInvocation(homeDir?: string): string;
+/**
+ * Build the sessionStart / SessionStart hook command for the home runtime.
+ *
+ * @param homeDir - Override home (tests / `GROUNDER_HOME`)
+ * @param extraArgs - Extra CLI args after `handoff peek` (e.g. `--json` for Cursor)
+ */
+export declare function peekHookCommand(homeDir?: string, extraArgs?: readonly string[]): string;
+/**
+ * True when `command` is Grounder's peek hook — current home-runtime form or
+ * legacy `npx grounder handoff peek` (with optional trailing flags).
+ * Used so upgrades replace the old entry instead of appending a duplicate.
+ */
+export declare function isGrounderPeekHookCommand(command: unknown): boolean;
+/** Collect Grounder peek hook `command` strings nested anywhere in parsed JSON. */
+export declare function collectGrounderPeekHookCommands(value: unknown): string[];
+/** True when any nested `command` field in parsed JSON is Grounder's peek hook. */
+export declare function jsonContainsGrounderPeekCommand(value: unknown): boolean;
+/** Grounder peek hook command strings in a hooks/settings JSON file (empty if absent/unreadable). */
+export declare function hookFileGrounderPeekCommands(filePath: string): Promise<string[]>;
+/** True when a hooks/settings JSON file contains Grounder's peek hook entry. */
+export declare function hookFileHasGrounderEntry(filePath: string): Promise<boolean>;
+/**
+ * True when the materialized runtime is missing or out of date for the given
+ * source package:
+ * - **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.
+ *
+ * @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>;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param options.packageRoot - Source package root to materialize (defaults to
+ *   the currently running package — override only in tests)
+ */
+export declare function installHookRuntime(options: {
+    homeDir?: string;
+    packageRoot?: string;
+}): Promise<{
+    cliPath: string;
+    status: ArtifactStatus;
+    mode: "symlink" | "copy";
+}>;
+//# sourceMappingURL=hook-runtime.d.ts.map

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

@@ -0,0 +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"}