grounder 0.0.2 → 0.2.0

package/dist/commands/handoff/peek.js

@@ -0,0 +1,120 @@
+import path from "node:path";
+import { readCursorHookWorkspaceRoot } from "../../agents/cursor-hook-input.js";
+import { withHomeDir } from "../../connector/home.js";
+import { resolveLinkedProject } from "../../connector/linked.js";
+import { resolveLogsDir } from "../../connector/vault.js";
+import { parseHandoffFrontmatter } from "../../util/frontmatter.js";
+import { flagBool, parseArgs } from "../../util/parse-args.js";
+import { findUsableHandoff } from "../../vault/find-usable-handoff.js";
+/** `YYYY-MM-DD-HHmm` or `YYYY-MM-DD-HHmmss`, optionally followed by `-slug`. */
+const TIMESTAMP_STEM = /^(\d{4}-\d{2}-\d{2})-\d{4}(?:\d{2})?(?:-(.*))?$/;
+/**
+ * Derive a display label from a handoff filename when frontmatter has no title:
+ * strip the timestamp prefix and `.md`, replace `-` with spaces.
+ */
+export function labelFromHandoffFilename(filePath) {
+    const stem = path.basename(filePath, ".md");
+    const match = TIMESTAMP_STEM.exec(stem);
+    if (!match) {
+        return stem.replace(/-/g, " ");
+    }
+    const slug = match[2];
+    if (!slug) {
+        return "";
+    }
+    return slug.replace(/-/g, " ");
+}
+function createdDateFromFilename(filePath) {
+    const stem = path.basename(filePath, ".md");
+    const match = TIMESTAMP_STEM.exec(stem);
+    return match?.[1];
+}
+/** Prefer frontmatter `created` ISO prefix; else filename date. */
+function formatCreatedDate(created, filePath) {
+    if (created) {
+        const match = /^(\d{4}-\d{2}-\d{2})/.exec(created);
+        if (match) {
+            return match[1];
+        }
+    }
+    return createdDateFromFilename(filePath);
+}
+function writePeekOutput(teaser, json) {
+    if (json) {
+        process.stdout.write(teaser === undefined ? "{}\n" : `${JSON.stringify({ additional_context: teaser })}\n`);
+        return;
+    }
+    if (teaser !== undefined) {
+        process.stdout.write(`${teaser}\n`);
+    }
+}
+/**
+ * Resolve the workspace root for a Cursor sessionStart hook.
+ * Prefer stdin `workspace_roots[0]`, then `CURSOR_PROJECT_DIR` (always set for
+ * Cursor hook scripts), else leave undefined so callers fall back to `cwd`.
+ */
+function resolveCursorHookCwd(stdinWorkspaceRoot) {
+    if (stdinWorkspaceRoot !== undefined) {
+        return stdinWorkspaceRoot;
+    }
+    const fromEnv = process.env.CURSOR_PROJECT_DIR?.trim();
+    return fromEnv || undefined;
+}
+/**
+ * CLI entry for `grounder handoff peek`.
+ * Silent by default: prints nothing and exits 0 when unlinked, empty, or on any error.
+ * Used by session-start hooks — must never crash or print noise.
+ * Reads Cursor hook stdin for `workspace_roots[0]` when present; falls back to
+ * `CURSOR_PROJECT_DIR` (user-level hooks often run with cwd under `~/.cursor`).
+ * Pass `--json` for Cursor's `additional_context` stdout contract.
+ * @returns Always `0`.
+ */
+export async function runHandoffPeek(argv) {
+    const { flags } = parseArgs(argv);
+    const stdinWorkspaceRoot = await readCursorHookWorkspaceRoot(process.stdin);
+    return runHandoffPeekWithOptions({
+        cwd: resolveCursorHookCwd(stdinWorkspaceRoot),
+        json: flagBool(flags, "json"),
+    });
+}
+/**
+ * Resolves the linked project and prints a one-line teaser for the newest *usable*
+ * handoff, or nothing. "Usable" (via {@link findUsableHandoff}) skips empty/unreadable
+ * files and falls back to the next-newest — the same selection `grounder handoff list
+ * --head` uses, so the teaser and `/grounder-task` never disagree about which handoff
+ * is current.
+ * Uses {@link resolveLinkedProject} directly (not `requireLinkedProject`) so failures stay silent.
+ * @returns Always `0`.
+ */
+export async function runHandoffPeekWithOptions(options = {}) {
+    try {
+        return await withHomeDir(options.homeDir, async () => {
+            let teaser;
+            try {
+                const resolved = await resolveLinkedProject(options.cwd ?? process.cwd());
+                if (resolved.ok) {
+                    const logsDir = resolveLogsDir(resolved.value.home, resolved.value.repo);
+                    const usable = await findUsableHandoff(logsDir);
+                    if (usable) {
+                        const fm = parseHandoffFrontmatter(usable.content);
+                        const label = fm.title?.trim() || labelFromHandoffFilename(usable.path);
+                        const createdDate = formatCreatedDate(fm.created, usable.path);
+                        if (createdDate) {
+                            teaser = `[grounder] Latest handoff: "${label}" (${createdDate}). Run /grounder-task to load it, or ignore if unrelated.`;
+                        }
+                    }
+                }
+            }
+            catch {
+                teaser = undefined;
+            }
+            writePeekOutput(teaser, options.json);
+            return 0;
+        });
+    }
+    catch {
+        writePeekOutput(undefined, options.json);
+        return 0;
+    }
+}
+//# sourceMappingURL=peek.js.map

package/dist/commands/handoff/peek.js.map

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

package/dist/commands/status.d.ts

@@ -0,0 +1,7 @@
+export interface StatusOptions {
+    cwd?: string;
+    homeDir?: string;
+}
+export declare function runStatus(_argv: string[]): Promise<number>;
+export declare function runStatusWithOptions(options?: StatusOptions): Promise<number>;
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8CD,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhE;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEvF"}

package/dist/commands/status.js

@@ -0,0 +1,101 @@
+import path from "node:path";
+import { currentBranch, findGitRoot } from "../connector/git.js";
+import { homeConfigPath, readHomeConfig, withHomeDir } from "../connector/home.js";
+import { findLinkedRepoRoot, readRepoConfig, repoConfigPath, } from "../connector/repo.js";
+import { resolveLogsDir, resolveNotesDir, resolveVaultRoot } from "../connector/vault.js";
+const LABEL_WIDTH = 12;
+const VAULT_INIT = "grounder vault init <path>";
+const REPO_INIT = "grounder init";
+const REPO_INIT_FORCE = "grounder init --force";
+function section(title) {
+    return `${title}\n`;
+}
+function statusLine(label, value) {
+    return `  ${label.padEnd(LABEL_WIDTH)}${value}\n`;
+}
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function writeGitLine(gitRoot) {
+    if (!gitRoot) {
+        return;
+    }
+    const branch = await currentBranch(gitRoot);
+    const gitValue = branch !== undefined ? `${gitRoot}  (branch: ${branch})` : gitRoot;
+    process.stdout.write(statusLine("Git:", gitValue));
+}
+async function tryReadHome() {
+    try {
+        return { home: await readHomeConfig(), invalid: null };
+    }
+    catch (error) {
+        return { home: null, invalid: errorDetail(error) };
+    }
+}
+async function tryReadRepo(linkedRoot) {
+    try {
+        return { repo: await readRepoConfig(linkedRoot), invalid: null };
+    }
+    catch (error) {
+        return { repo: null, invalid: errorDetail(error) };
+    }
+}
+export async function runStatus(_argv) {
+    return runStatusWithOptions({});
+}
+export async function runStatusWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const cwd = path.resolve(options.cwd ?? process.cwd());
+        const { home, invalid: homeInvalid } = await tryReadHome();
+        const gitRoot = await findGitRoot(cwd);
+        const linkedRoot = await findLinkedRepoRoot(cwd, gitRoot);
+        const { repo, invalid: repoInvalid } = linkedRoot
+            ? await tryReadRepo(linkedRoot)
+            : { repo: null, invalid: null };
+        process.stdout.write(section("Machine"));
+        if (homeInvalid) {
+            process.stdout.write(statusLine("Config:", `invalid → run: ${VAULT_INIT}`));
+        }
+        else if (!home) {
+            process.stdout.write(statusLine("Config:", `missing → run: ${VAULT_INIT}`));
+        }
+        else {
+            process.stdout.write(statusLine("Config:", homeConfigPath()));
+            process.stdout.write(statusLine("Vault:", resolveVaultRoot(home)));
+        }
+        process.stdout.write("\n");
+        process.stdout.write(section("Project"));
+        if (!linkedRoot) {
+            process.stdout.write(statusLine("Linked:", "no"));
+            if (home) {
+                process.stdout.write(statusLine("Config:", `missing → run: ${REPO_INIT}`));
+            }
+            return 0;
+        }
+        if (repoInvalid || !repo) {
+            const fix = home ? REPO_INIT_FORCE : VAULT_INIT;
+            process.stdout.write(statusLine("Linked:", `incomplete → run: ${fix}`));
+            process.stdout.write(statusLine("Folder:", linkedRoot));
+            process.stdout.write(statusLine("Config:", repoInvalid ? `invalid → run: ${REPO_INIT_FORCE}` : `missing → run: ${REPO_INIT}`));
+            await writeGitLine(gitRoot);
+            return 0;
+        }
+        if (!home) {
+            process.stdout.write(statusLine("Linked:", `incomplete → run: ${VAULT_INIT}`));
+            process.stdout.write(statusLine("Folder:", linkedRoot));
+            process.stdout.write(statusLine("Config:", repoConfigPath(linkedRoot)));
+            process.stdout.write(statusLine("Id:", repo.projectId));
+            await writeGitLine(gitRoot);
+            return 0;
+        }
+        process.stdout.write(statusLine("Linked:", "yes"));
+        process.stdout.write(statusLine("Folder:", linkedRoot));
+        process.stdout.write(statusLine("Config:", repoConfigPath(linkedRoot)));
+        process.stdout.write(statusLine("Id:", repo.projectId));
+        process.stdout.write(statusLine("Notes:", resolveNotesDir(home, repo)));
+        process.stdout.write(statusLine("Logs:", resolveLogsDir(home, repo)));
+        await writeGitLine(gitRoot);
+        return 0;
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/status.js.map

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

package/dist/commands/vault/init.d.ts

@@ -2,6 +2,8 @@ export interface VaultInitOptions {
     vaultPath: string;
     yes?: boolean;
     force?: boolean;
+    /** Also install session-start teaser hooks for adapters that support them. */
+    hooks?: boolean;
     homeDir?: string;
     /** Agent ids to install for. Defaults to auto-detecting installed agents. */
     agents?: string[];

package/dist/commands/vault/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/vault/init.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBlE;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DxF"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/vault/init.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBlE;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuFxF"}

package/dist/commands/vault/init.js

@@ -1,4 +1,5 @@
 import { mkdir } from "node:fs/promises";
+import { installHookRuntime, runtimeCliPath } from "../../agents/hook-runtime.js";
 import { resolveAgents } from "../../agents/index.js";
 import { homeConfigPath, readHomeConfig, withHomeDir, writeHomeConfig, } from "../../connector/home.js";
 import { flagBool, flagStrings, parseArgs } from "../../util/parse-args.js";
@@ -10,6 +11,7 @@ export async function runVaultInit(argv) {
     const vaultPathArg = positional[0];
     const yes = flagBool(flags, "yes", "y");
     const force = flagBool(flags, "force", "f");
+    const hooks = flagBool(flags, "hooks");
     const agents = flagStrings(repeated, "agent");
     if (!vaultPathArg) {
         process.stderr.write("Usage: grounder vault init <path>\n");
@@ -19,6 +21,7 @@ export async function runVaultInit(argv) {
         vaultPath: vaultPathArg,
         yes,
         force,
+        hooks,
         agents: agents.length > 0 ? agents : undefined,
     });
 }
@@ -27,6 +30,7 @@ export async function runVaultInitWithOptions(options) {
         const vaultRoot = resolveUserPath(options.vaultPath);
         const yes = options.yes ?? false;
         const force = options.force ?? false;
+        const hooks = options.hooks ?? false;
         const homeDir = options.homeDir;
         const existingHome = await readHomeConfig();
         const projectsDir = projectsParent(vaultRoot);
@@ -39,8 +43,18 @@ export async function runVaultInitWithOptions(options) {
         process.stdout.write("Will write:\n");
         process.stdout.write(`  home   ${homeConfigPath(homeDir)}\n`);
         process.stdout.write("  vault  10-Projects/ (if missing)\n");
+        const hookAgents = hooks ? agents.filter((agent) => agent.installHooks) : [];
+        if (hookAgents.length > 0) {
+            // Shared across agents — list once (not under each adapter).
+            process.stdout.write(`  grounder runtime ${runtimeCliPath(homeDir)}\n`);
+        }
         for (const agent of agents) {
             process.stdout.write(`  ${agent.id.padEnd(8)} (${agent.name} artifacts)\n`);
+            if (hooks && agent.expectedHookArtifacts) {
+                for (const hookPath of agent.expectedHookArtifacts(homeDir)) {
+                    process.stdout.write(`  ${agent.id.padEnd(8)} hook ${hookPath}\n`);
+                }
+            }
         }
         if (agents.length === 0) {
             process.stdout.write("  (no supported agents detected — skipping agent artifacts)\n");
@@ -57,6 +71,13 @@ export async function runVaultInitWithOptions(options) {
         await mkdir(projectsDir, { recursive: true });
         process.stdout.write("✓ Wrote home config\n");
         process.stdout.write(`✓ Vault scaffold: ${projectsDir}\n`);
+        if (hookAgents.length > 0) {
+            const runtime = await installHookRuntime({ homeDir });
+            const runtimeLabel = runtime.status === "skipped"
+                ? "already exists (skipped)"
+                : `installed (${runtime.mode}): ${runtime.cliPath}`;
+            process.stdout.write(`✓ Grounder hook runtime ${runtimeLabel}\n`);
+        }
         for (const agent of agents) {
             const result = await agent.install({ force, homeDir });
             for (const [artifactPath, status] of Object.entries(result.artifacts)) {
@@ -66,6 +87,13 @@ export async function runVaultInitWithOptions(options) {
             if (Object.keys(result.artifacts).length === 0) {
                 process.stdout.write(`✓ ${agent.name}: no artifacts to install yet\n`);
             }
+            if (hooks && agent.installHooks) {
+                const hookResult = await agent.installHooks({ force, homeDir });
+                for (const [artifactPath, status] of Object.entries(hookResult.artifacts)) {
+                    const label = status === "skipped" ? "already exists (skipped)" : `installed: ${artifactPath}`;
+                    process.stdout.write(`✓ ${agent.name} hook ${label}\n`);
+                }
+            }
         }
         return 0;
     });

package/dist/commands/vault/init.js.map

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

package/dist/util/frontmatter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Parse `title` / `created` from Grounder handoff frontmatter.
+ * Accepts the quoted `key: "value"` shape {@link writeHandoff} writes today, and
+ * unquoted `key: value` from earlier handoffs. Not a general YAML parser.
+ * Returns `{}` on anything unexpected; never throws.
+ */
+export declare function parseHandoffFrontmatter(content: string): {
+    title?: string;
+    created?: string;
+};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/util/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqC7F"}

package/dist/util/frontmatter.js

@@ -0,0 +1,69 @@
+/**
+ * Unescape sequences produced by {@link yamlDoubleQuoted}: `\\`, `\"`, `\r`, `\n`.
+ */
+function unescapeYamlDoubleQuoted(value) {
+    let result = "";
+    for (let i = 0; i < value.length; i++) {
+        if (value[i] === "\\" && i + 1 < value.length) {
+            const next = value[i + 1];
+            if (next === "\\" || next === '"') {
+                result += next;
+                i++;
+                continue;
+            }
+            if (next === "n") {
+                result += "\n";
+                i++;
+                continue;
+            }
+            if (next === "r") {
+                result += "\r";
+                i++;
+                continue;
+            }
+        }
+        result += value[i];
+    }
+    return result;
+}
+/**
+ * Parse `title` / `created` from Grounder handoff frontmatter.
+ * Accepts the quoted `key: "value"` shape {@link writeHandoff} writes today, and
+ * unquoted `key: value` from earlier handoffs. Not a general YAML parser.
+ * Returns `{}` on anything unexpected; never throws.
+ */
+export function parseHandoffFrontmatter(content) {
+    try {
+        const lines = content.split(/\r?\n/);
+        if (lines[0] !== "---") {
+            return {};
+        }
+        const result = {};
+        for (let i = 1; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            if (line === "---") {
+                break;
+            }
+            const quoted = /^(title|created):\s*"(.*)"\s*$/.exec(line);
+            if (quoted) {
+                const key = quoted[1];
+                result[key] = unescapeYamlDoubleQuoted(quoted[2] ?? "");
+                continue;
+            }
+            // Opening quote without a closing pair — ignore rather than treat as unquoted.
+            if (/^(title|created):\s*"/.test(line)) {
+                continue;
+            }
+            const unquoted = /^(title|created):\s*(.+?)\s*$/.exec(line);
+            if (unquoted) {
+                const key = unquoted[1];
+                result[key] = unquoted[2] ?? "";
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/util/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,SAAS,wBAAwB,CAAC,KAAa;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBAClC,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;YACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBACjB,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;YACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBACjB,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,MAAM,GAAyC,EAAE,CAAC;QACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBACnB,MAAM;YACR,CAAC;YAED,MAAM,MAAM,GAAG,gCAAgC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAwB,CAAC;gBAC7C,MAAM,CAAC,GAAG,CAAC,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACxD,SAAS;YACX,CAAC;YAED,+EAA+E;YAC/E,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5D,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAwB,CAAC;gBAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAClC,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/util/merge-json.d.ts

@@ -0,0 +1,15 @@
+export type MergeJsonResult = {
+    ok: true;
+    created: boolean;
+} | {
+    ok: false;
+    error: "unparseable";
+    message: string;
+};
+/**
+ * Read a JSON object file (default `{}` if missing), apply `merge`, write pretty-printed.
+ * On parse failure or non-object root: leaves the file untouched and returns an error
+ * so callers can warn without clobbering shared config.
+ */
+export declare function mergeJsonFile(filePath: string, merge: (current: Record<string, unknown>) => Record<string, unknown>): Promise<MergeJsonResult>;
+//# sourceMappingURL=merge-json.d.ts.map

package/dist/util/merge-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-json.d.ts","sourceRoot":"","sources":["../../src/util/merge-json.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnE,OAAO,CAAC,eAAe,CAAC,CAiC1B"}

package/dist/util/merge-json.js

@@ -0,0 +1,40 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileExists } from "./fs.js";
+/**
+ * Read a JSON object file (default `{}` if missing), apply `merge`, write pretty-printed.
+ * On parse failure or non-object root: leaves the file untouched and returns an error
+ * so callers can warn without clobbering shared config.
+ */
+export async function mergeJsonFile(filePath, merge) {
+    const existed = await fileExists(filePath);
+    let current = {};
+    if (existed) {
+        const raw = await readFile(filePath, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                error: "unparseable",
+                message: `Refusing to modify ${filePath}: invalid JSON (${detail})`,
+            };
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                ok: false,
+                error: "unparseable",
+                message: `Refusing to modify ${filePath}: root value must be a JSON object`,
+            };
+        }
+        current = parsed;
+    }
+    const next = merge(current);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return { ok: true, created: !existed };
+}
+//# sourceMappingURL=merge-json.js.map

package/dist/util/merge-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-json.js","sourceRoot":"","sources":["../../src/util/merge-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAMrC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,KAAoE;IAEpE,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,OAAO,GAA4B,EAAE,CAAC;IAE1C,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,mBAAmB,MAAM,GAAG;aACpE,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,oCAAoC;aAC5E,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAiC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,SAAS,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;AACzC,CAAC"}

package/dist/vault/find-usable-handoff.d.ts

@@ -0,0 +1,19 @@
+export interface FindUsableHandoffOptions {
+    /** Max newest-first candidates to scan (default: 5). */
+    limit?: number;
+}
+export interface UsableHandoff {
+    /** Absolute path of the resolved handoff file. */
+    path: string;
+    /** Already-read file contents (avoids a second read by callers). */
+    content: string;
+}
+/**
+ * Resolves the newest-first handoff under `logsDir` that actually has content,
+ * skipping empty or unreadable files along the way (e.g. an interrupted write).
+ * Single source of truth for "which handoff is current" — shared by
+ * `grounder handoff peek` and `grounder handoff list --head` so both agree.
+ * Returns `undefined` when no candidate within the scan window is usable.
+ */
+export declare function findUsableHandoff(logsDir: string, options?: FindUsableHandoffOptions): Promise<UsableHandoff | undefined>;
+//# sourceMappingURL=find-usable-handoff.d.ts.map

package/dist/vault/find-usable-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-usable-handoff.d.ts","sourceRoot":"","sources":["../../src/vault/find-usable-handoff.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAcpC"}

package/dist/vault/find-usable-handoff.js

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { listHandoffs } from "./list-handoffs.js";
+/** Newest-first candidates scanned for a usable handoff before giving up. */
+const DEFAULT_SCAN_LIMIT = 5;
+/**
+ * Resolves the newest-first handoff under `logsDir` that actually has content,
+ * skipping empty or unreadable files along the way (e.g. an interrupted write).
+ * Single source of truth for "which handoff is current" — shared by
+ * `grounder handoff peek` and `grounder handoff list --head` so both agree.
+ * Returns `undefined` when no candidate within the scan window is usable.
+ */
+export async function findUsableHandoff(logsDir, options = {}) {
+    const paths = await listHandoffs(logsDir, { limit: options.limit ?? DEFAULT_SCAN_LIMIT });
+    for (const filePath of paths) {
+        let content;
+        try {
+            content = await readFile(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.trim().length > 0) {
+            return { path: filePath, content };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=find-usable-handoff.js.map

package/dist/vault/find-usable-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-usable-handoff.js","sourceRoot":"","sources":["../../src/vault/find-usable-handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,6EAA6E;AAC7E,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAc7B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,UAAoC,EAAE;IAEtC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,kBAAkB,EAAE,CAAC,CAAC;IAC1F,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grounder",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "Connect git projects to Obsidian dev vaults for AI agent memory",
   "type": "module",
   "bin": {

package/templates/agents/claude/commands/grounder-task.md

@@ -4,13 +4,13 @@ Read-only — do not write to the vault. Do not invent vault paths.
 
 From the linked project folder or any subdirectory beneath it:
 
-1. List recent handoffs (newest first):
+1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
-   npx grounder handoff list --limit 5
+   npx grounder handoff list --head
 
-2. If the list is empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
+2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-3. If handoffs exist: read the newest file (first path). Optionally skim other listed paths if the user names a session or the newest is clearly wrong.
+3. Otherwise, read that file. If the user names a specific session instead, run `npx grounder handoff list --limit 5` and read the path they mean.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).
 

package/templates/agents/cursor/commands/grounder-task.md

@@ -4,13 +4,13 @@ Read-only — do not write to the vault. Do not invent vault paths.
 
 From the linked project folder or any subdirectory beneath it:
 
-1. List recent handoffs (newest first):
+1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
-   npx grounder handoff list --limit 5
+   npx grounder handoff list --head
 
-2. If the list is empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
+2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-3. If handoffs exist: read the newest file (first path). Optionally skim other listed paths if the user names a session or the newest is clearly wrong.
+3. Otherwise, read that file. If the user names a specific session instead, run `npx grounder handoff list --limit 5` and read the path they mean.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).