grounder 0.1.0 → 0.3.0

package/dist/agents/hook-runtime.js

@@ -0,0 +1,401 @@
+/**
+ * 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 { cp, lstat, mkdir, readFile, realpath, rename, rm, symlink, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHomeDir } from "../connector/home.js";
+import { fileExists } from "../util/fs.js";
+/** Package root (`packages/grounder`) when running from `dist/agents/`. */
+const defaultPackageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+/** `~/.grounder/runtime` — private materialization of the CLI used only by session hooks. */
+export function grounderRuntimeDir(homeDir) {
+    return path.join(resolveHomeDir(homeDir), ".grounder", "runtime");
+}
+/** Absolute path to the materialized CLI entry (`…/runtime/dist/cli.js`). */
+export function runtimeCliPath(homeDir) {
+    return path.join(grounderRuntimeDir(homeDir), "dist", "cli.js");
+}
+export function runtimeManifestPath(homeDir) {
+    return path.join(grounderRuntimeDir(homeDir), "manifest.json");
+}
+/**
+ * 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 function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Reverse one {@link shellQuote} token starting at `start`.
+ * Handles the close/escape/reopen sequence (`'\''`) for embedded quotes.
+ */
+function parseShellQuoted(input, start) {
+    if (input[start] !== "'") {
+        return null;
+    }
+    let i = start + 1;
+    let value = "";
+    while (i < input.length) {
+        if (input[i] === "'") {
+            // shellQuote escape: close quote, literal `'`, reopen — characters `'\''`
+            if (input[i + 1] === "\\" && input[i + 2] === "'" && input[i + 3] === "'") {
+                value += "'";
+                i += 4;
+                continue;
+            }
+            return { value, next: i + 1 };
+        }
+        value += input[i];
+        i += 1;
+    }
+    return null;
+}
+function isAbsolutePath(p) {
+    return path.posix.isAbsolute(p) || path.win32.isAbsolute(p);
+}
+/**
+ * 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 function extractRuntimeNodePath(command) {
+    if (typeof command !== "string") {
+        return null;
+    }
+    const trimmed = command.trim();
+    const first = parseShellQuoted(trimmed, 0);
+    if (!first || !isAbsolutePath(first.value)) {
+        return null;
+    }
+    let i = first.next;
+    if (trimmed[i] !== " ") {
+        return null;
+    }
+    while (trimmed[i] === " ") {
+        i += 1;
+    }
+    const second = parseShellQuoted(trimmed, i);
+    if (!second) {
+        return null;
+    }
+    const cliNormalized = second.value.replace(/\\/g, "/");
+    if (!cliNormalized.includes("/.grounder/runtime/dist/cli.js")) {
+        return null;
+    }
+    return first.value;
+}
+/**
+ * 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 function findRuntimeNodePathsInText(text) {
+    const found = [];
+    const seen = new Set();
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== "'") {
+            continue;
+        }
+        const nodePath = extractRuntimeNodePath(text.slice(i));
+        if (nodePath !== null && !seen.has(nodePath)) {
+            seen.add(nodePath);
+            found.push(nodePath);
+        }
+    }
+    return found;
+}
+/**
+ * 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 function runtimeInvocation(homeDir) {
+    return `${shellQuote(process.execPath)} ${shellQuote(runtimeCliPath(homeDir))}`;
+}
+/**
+ * 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 function peekHookCommand(homeDir, extraArgs = []) {
+    return [runtimeInvocation(homeDir), "handoff", "peek", ...extraArgs].join(" ");
+}
+/**
+ * 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 function isGrounderPeekHookCommand(command) {
+    if (typeof command !== "string") {
+        return false;
+    }
+    const trimmed = command.trim();
+    if (/^npx\s+grounder\s+handoff\s+peek(?:\s|$)/.test(trimmed)) {
+        return true;
+    }
+    // Normalize separators so Windows absolute paths still match.
+    const normalized = trimmed.replace(/\\/g, "/");
+    return (normalized.includes("/.grounder/runtime/dist/cli.js") && /\bhandoff\s+peek\b/.test(normalized));
+}
+/** Collect Grounder peek hook `command` strings nested anywhere in parsed JSON. */
+export function collectGrounderPeekHookCommands(value) {
+    const out = [];
+    const walk = (v) => {
+        if (Array.isArray(v)) {
+            for (const item of v) {
+                walk(item);
+            }
+            return;
+        }
+        if (v && typeof v === "object") {
+            const obj = v;
+            if (typeof obj.command === "string" && isGrounderPeekHookCommand(obj.command)) {
+                out.push(obj.command);
+            }
+            for (const child of Object.values(obj)) {
+                walk(child);
+            }
+        }
+    };
+    walk(value);
+    return out;
+}
+/** True when any nested `command` field in parsed JSON is Grounder's peek hook. */
+export function jsonContainsGrounderPeekCommand(value) {
+    return collectGrounderPeekHookCommands(value).length > 0;
+}
+/** Grounder peek hook command strings in a hooks/settings JSON file (empty if absent/unreadable). */
+export async function hookFileGrounderPeekCommands(filePath) {
+    try {
+        if (!(await fileExists(filePath))) {
+            return [];
+        }
+        const parsed = JSON.parse(await readFile(filePath, "utf8"));
+        return collectGrounderPeekHookCommands(parsed);
+    }
+    catch {
+        return [];
+    }
+}
+/** True when a hooks/settings JSON file contains Grounder's peek hook entry. */
+export async function hookFileHasGrounderEntry(filePath) {
+    return (await hookFileGrounderPeekCommands(filePath)).length > 0;
+}
+/**
+ * Best-effort: is `root` inside a throwaway cache (npx / pnpm dlx), where
+ * content can be evicted or swapped for a *different* version at any time?
+ * Those sources can't be symlinked durably — copy instead.
+ */
+function isEphemeralSource(root) {
+    const normalized = `${path.resolve(root).replace(/\\/g, "/")}/`;
+    const tmp = `${path.resolve(os.tmpdir()).replace(/\\/g, "/")}/`;
+    if (normalized.startsWith(tmp)) {
+        return true;
+    }
+    return /\/(_npx|\.npm\/_npx|\.pnpm-dlx-|pnpm-dlx-)[^/]*\//.test(normalized);
+}
+async function readPackageVersion(packageRoot) {
+    try {
+        const raw = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+        return typeof raw.version === "string" ? raw.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function readRuntimeManifest(homeDir) {
+    try {
+        const raw = JSON.parse(await readFile(runtimeManifestPath(homeDir), "utf8"));
+        if (typeof raw.version !== "string" || (raw.mode !== "symlink" && raw.mode !== "copy")) {
+            return null;
+        }
+        return {
+            mode: raw.mode,
+            version: raw.version,
+            sourcePackageRoot: typeof raw.sourcePackageRoot === "string" ? raw.sourcePackageRoot : "",
+            installedAt: typeof raw.installedAt === "string" ? raw.installedAt : "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Realpath of `destDist` if it's currently a directory symlink, else `null`. */
+async function currentSymlinkTarget(destDist) {
+    try {
+        const info = await lstat(destDist);
+        if (!info.isSymbolicLink()) {
+            return null;
+        }
+        return await realpath(destDist);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 async function isHookRuntimeStale(homeDir, packageRoot = defaultPackageRoot) {
+    if (!(await fileExists(runtimeCliPath(homeDir)))) {
+        return true;
+    }
+    const destDist = path.join(grounderRuntimeDir(homeDir), "dist");
+    if (isEphemeralSource(packageRoot)) {
+        const manifest = await readRuntimeManifest(homeDir);
+        if (manifest?.mode !== "copy") {
+            return true;
+        }
+        return manifest.version !== (await readPackageVersion(packageRoot));
+    }
+    const sourceDistDir = path.join(packageRoot, "dist");
+    const resolvedSource = await realpath(sourceDistDir).catch(() => path.resolve(sourceDistDir));
+    const target = await currentSymlinkTarget(destDist);
+    return target !== resolvedSource;
+}
+/**
+ * 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 async function installHookRuntime(options) {
+    const packageRoot = options.packageRoot ?? defaultPackageRoot;
+    const sourceDistDir = path.join(packageRoot, "dist");
+    const runtimeDir = grounderRuntimeDir(options.homeDir);
+    const destDist = path.join(runtimeDir, "dist");
+    const cliPath = runtimeCliPath(options.homeDir);
+    const existed = await fileExists(cliPath);
+    if (!(await fileExists(path.join(sourceDistDir, "cli.js")))) {
+        throw new Error(`Grounder dist missing at ${sourceDistDir}. Run \`pnpm build\` (or install a published package) before vault init.`);
+    }
+    await mkdir(runtimeDir, { recursive: true });
+    // Stage into a sibling path first, then swap. If symlink/cp fails, the live
+    // `dist/` (and any hooks pointing at it) stay intact.
+    const stagingDist = `${destDist}.staging`;
+    const backupDist = `${destDist}.bak`;
+    await rm(stagingDist, { recursive: true, force: true });
+    await rm(backupDist, { recursive: true, force: true });
+    const mode = isEphemeralSource(packageRoot) ? "copy" : "symlink";
+    try {
+        if (mode === "symlink") {
+            const resolvedSource = await realpath(sourceDistDir).catch(() => path.resolve(sourceDistDir));
+            await symlink(resolvedSource, stagingDist, process.platform === "win32" ? "junction" : "dir");
+        }
+        else {
+            await cp(sourceDistDir, stagingDist, { recursive: true, force: true });
+        }
+        // Move the live dest aside (if any), then promote staging. On promote
+        // failure, restore the backup so hooks keep a working cli.js.
+        try {
+            await rename(destDist, backupDist);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        try {
+            await rename(stagingDist, destDist);
+        }
+        catch (error) {
+            try {
+                await rename(backupDist, destDist);
+            }
+            catch {
+                // Best-effort restore; rethrow the promote failure below.
+            }
+            throw error;
+        }
+        await rm(backupDist, { recursive: true, force: true });
+    }
+    catch (error) {
+        await rm(stagingDist, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    const manifest = {
+        mode,
+        version: await readPackageVersion(packageRoot),
+        sourcePackageRoot: packageRoot,
+        installedAt: new Date().toISOString(),
+    };
+    await writeFile(runtimeManifestPath(options.homeDir), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { cliPath, status: existed ? "overwritten" : "created", mode };
+}
+//# sourceMappingURL=hook-runtime.js.map

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

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

package/dist/agents/index.d.ts

@@ -2,10 +2,28 @@ import type { AgentAdapter } from "./types.js";
 export { claude } from "./claude.js";
 export { cursor } from "./cursor.js";
 export type { AgentAdapter, AgentInstallOptions, AgentInstallResult, ArtifactStatus, } from "./types.js";
+/** Every agent adapter this Grounder build knows about (Cursor, Claude, …). */
+export declare const ALL_AGENTS: readonly AgentAdapter[];
 /**
  * Resolve which adapters to run:
  *  - If `ids` is provided, return those adapters (throws on unknown id).
  *  - Otherwise, auto-detect by checking isInstalled() for each adapter.
  */
 export declare function resolveAgents(ids?: string[]): Promise<AgentAdapter[]>;
+/**
+ * Write this agent's install version info into `~/.grounder/state.json` after
+ * install. If hooks were installed and the agent supports them, store the hooks
+ * version; otherwise leave any existing hooks version as-is.
+ *
+ * When `advanceCommandsSchema` is false (every command file was left alone
+ * because it looked locally edited or from an old install), do not bump the
+ * commands version in state — otherwise doctor/peek would stop warning even
+ * though the files were never updated. Use `--force` (or a real write) first.
+ */
+export declare function recordAgentInstallState(agent: AgentAdapter, opts?: {
+    hooksInstalled?: boolean;
+    homeDir?: string;
+    /** Default true. Pass false when no command file was written or already up to date. */
+    advanceCommandsSchema?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAIpB;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAc3E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,eAAO,MAAM,UAAU,EAAE,SAAS,YAAY,EAAqB,CAAC;AAEpE;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAc3E;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE;IACJ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACL,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/agents/index.js

@@ -1,8 +1,11 @@
+import { recordAgentInstall } from "../connector/state.js";
+import { VERSION } from "../index.js";
 import { claude } from "./claude.js";
 import { cursor } from "./cursor.js";
 export { claude } from "./claude.js";
 export { cursor } from "./cursor.js";
-const ALL_ADAPTERS = [cursor, claude];
+/** Every agent adapter this Grounder build knows about (Cursor, Claude, …). */
+export const ALL_AGENTS = [cursor, claude];
 /**
  * Resolve which adapters to run:
  *  - If `ids` is provided, return those adapters (throws on unknown id).
@@ -10,14 +13,34 @@ const ALL_ADAPTERS = [cursor, claude];
  */
 export async function resolveAgents(ids) {
     if (ids && ids.length > 0) {
-        const found = ALL_ADAPTERS.filter((a) => ids.includes(a.id));
-        const unknown = ids.filter((id) => !ALL_ADAPTERS.some((a) => a.id === id));
+        const found = ALL_AGENTS.filter((a) => ids.includes(a.id));
+        const unknown = ids.filter((id) => !ALL_AGENTS.some((a) => a.id === id));
         if (unknown.length > 0) {
             throw new Error(`Unknown agent id(s): ${unknown.join(", ")}`);
         }
         return found;
     }
-    const results = await Promise.all(ALL_ADAPTERS.map(async (a) => ({ adapter: a, ok: await a.isInstalled() })));
+    const results = await Promise.all(ALL_AGENTS.map(async (a) => ({ adapter: a, ok: await a.isInstalled() })));
     return results.filter((r) => r.ok).map((r) => r.adapter);
 }
+/**
+ * Write this agent's install version info into `~/.grounder/state.json` after
+ * install. If hooks were installed and the agent supports them, store the hooks
+ * version; otherwise leave any existing hooks version as-is.
+ *
+ * When `advanceCommandsSchema` is false (every command file was left alone
+ * because it looked locally edited or from an old install), do not bump the
+ * commands version in state — otherwise doctor/peek would stop warning even
+ * though the files were never updated. Use `--force` (or a real write) first.
+ */
+export async function recordAgentInstallState(agent, opts = {}) {
+    const advanceCommandsSchema = opts.advanceCommandsSchema !== false;
+    await recordAgentInstall({
+        agentId: agent.id,
+        ...(advanceCommandsSchema ? { commandsSchema: agent.commandsSchema } : {}),
+        hooksSchema: opts.hooksInstalled && agent.hooksSchema !== undefined ? agent.hooksSchema : undefined,
+        grounderVersion: VERSION,
+        homeDir: opts.homeDir,
+    });
+}
 //# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC,MAAM,YAAY,GAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAc;IAChD,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC3E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAC3E,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAA4B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAc;IAChD,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACzE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CACzE,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAmB,EACnB,OAKI,EAAE;IAEN,MAAM,qBAAqB,GAAG,IAAI,CAAC,qBAAqB,KAAK,KAAK,CAAC;IACnE,MAAM,kBAAkB,CAAC;QACvB,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,WAAW,EACT,IAAI,CAAC,cAAc,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;QACxF,eAAe,EAAE,OAAO;QACxB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,37 @@
+import type { AgentInstallOptions, ArtifactStatus } from "./types.js";
+export interface InstallCommandFileOptions extends AgentInstallOptions {
+    agentId: string;
+    commandsSchema: number;
+    templateDir: string;
+    commandsDir: string;
+    filename: string;
+}
+export interface InstallCommandFileResult {
+    dest: string;
+    status: ArtifactStatus;
+    /** Present when content was (or would be) written — for ledger updates. */
+    hash?: string;
+}
+/**
+ * Install one slash-command markdown file with chezmoi-style drift detection.
+ *
+ * When the file already exists and `--force` is off:
+ * - on-disk hash matches the ledger → safe to refresh to the new template
+ * - no ledger hash, or on-disk hash differs → treat as user-edited (`modified`)
+ */
+export declare function installCommandFile(opts: InstallCommandFileOptions): Promise<InstallCommandFileResult>;
+/**
+ * Persist per-file hashes after a command install. No-op when `files` is empty
+ * or `dryRun` is set.
+ */
+export declare function recordCommandFileHashes(opts: {
+    agentId: string;
+    commandsSchema: number;
+    files: Record<string, {
+        schema: number;
+        hash: string;
+    }>;
+    homeDir?: string;
+    dryRun?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=install-command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-command.d.ts","sourceRoot":"","sources":["../../src/agents/install-command.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CAuCnC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhB"}

package/dist/agents/install-command.js

@@ -0,0 +1,65 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readGrounderState, recordAgentInstall, recordedFileHash } from "../connector/state.js";
+import { VERSION } from "../index.js";
+import { fileExists } from "../util/fs.js";
+import { hashContent } from "../util/hash.js";
+import { runtimeInvocation } from "./hook-runtime.js";
+/**
+ * Install one slash-command markdown file with chezmoi-style drift detection.
+ *
+ * When the file already exists and `--force` is off:
+ * - on-disk hash matches the ledger → safe to refresh to the new template
+ * - no ledger hash, or on-disk hash differs → treat as user-edited (`modified`)
+ */
+export async function installCommandFile(opts) {
+    const dest = path.join(opts.commandsDir, opts.filename);
+    const existed = await fileExists(dest);
+    const template = await readFile(path.join(opts.templateDir, opts.filename), "utf8");
+    const rendered = template.replaceAll("{{GROUNDER_CLI}}", runtimeInvocation(opts.homeDir));
+    const renderedHash = hashContent(rendered);
+    if (existed && !opts.force) {
+        const onDisk = await readFile(dest, "utf8");
+        const onDiskHash = hashContent(onDisk);
+        const state = await readGrounderState(opts.homeDir);
+        const recorded = recordedFileHash(state, opts.agentId, dest);
+        if (recorded !== undefined && recorded === onDiskHash) {
+            // Untouched since Grounder last wrote it — safe to auto-update.
+            if (onDiskHash === renderedHash) {
+                return { dest, status: "skipped", hash: renderedHash };
+            }
+            if (!opts.dryRun) {
+                await writeFile(dest, rendered);
+            }
+            return { dest, status: "overwritten", hash: renderedHash };
+        }
+        // Legacy (no hash) or user-edited — protect content.
+        return { dest, status: "modified" };
+    }
+    if (!opts.dryRun) {
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, rendered);
+    }
+    return {
+        dest,
+        status: existed ? "overwritten" : "created",
+        hash: renderedHash,
+    };
+}
+/**
+ * Persist per-file hashes after a command install. No-op when `files` is empty
+ * or `dryRun` is set.
+ */
+export async function recordCommandFileHashes(opts) {
+    if (opts.dryRun || Object.keys(opts.files).length === 0) {
+        return;
+    }
+    await recordAgentInstall({
+        agentId: opts.agentId,
+        commandsSchema: opts.commandsSchema,
+        files: opts.files,
+        grounderVersion: VERSION,
+        homeDir: opts.homeDir,
+    });
+}
+//# sourceMappingURL=install-command.js.map

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

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