grounder 0.1.0 → 0.2.0

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.1.0",
+  "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).