grounder 0.2.0 → 0.3.0

package/dist/vault/list-plans.d.ts

@@ -0,0 +1,11 @@
+export interface ListPlansOptions {
+    /** Max paths to return (newest first). Omit to return all. */
+    limit?: number;
+}
+/**
+ * Lists plan markdown files under `plansDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename descending for stable output.
+ */
+export declare function listPlans(plansDir: string, options?: ListPlansOptions): Promise<string[]>;
+//# sourceMappingURL=list-plans.d.ts.map

package/dist/vault/list-plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.d.ts","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCnB"}

package/dist/vault/list-plans.js

@@ -0,0 +1,40 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Lists plan markdown files under `plansDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename descending for stable output.
+ */
+export async function listPlans(plansDir, options = {}) {
+    let entries;
+    try {
+        entries = await readdir(plansDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const mdNames = entries.filter((name) => name.endsWith(".md"));
+    const withMtime = await Promise.all(mdNames.map(async (name) => {
+        const filePath = path.join(plansDir, name);
+        const { mtimeMs } = await stat(filePath);
+        return { filePath, name, mtimeMs };
+    }));
+    withMtime.sort((a, b) => {
+        if (a.mtimeMs !== b.mtimeMs) {
+            return b.mtimeMs - a.mtimeMs;
+        }
+        return a.name < b.name ? 1 : a.name > b.name ? -1 : 0;
+    });
+    const paths = withMtime.map((entry) => entry.filePath);
+    if (options.limit === undefined) {
+        return paths;
+    }
+    if (options.limit <= 0) {
+        return [];
+    }
+    return paths.slice(0, options.limit);
+}
+//# sourceMappingURL=list-plans.js.map

package/dist/vault/list-plans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.js","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC,CACH,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEvD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/vault/write-plan.d.ts

@@ -0,0 +1,28 @@
+/** Options for {@link writePlan}. */
+export interface WritePlanOptions {
+    /** Project id written into YAML frontmatter. */
+    projectId: string;
+    /** When true, overwrite an existing plan (preserving original `created`). */
+    force?: boolean;
+    /** Timestamp for `created` / `updated` (default: now). */
+    now?: Date;
+}
+export type WritePlanStatus = "created" | "overwritten" | "exists";
+export interface WritePlanResult {
+    path: string;
+    status: WritePlanStatus;
+}
+/**
+ * Overwrites an existing plan at an absolute path.
+ * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * Caller must validate the path (e.g. inside this project's `plans/` dir).
+ */
+export declare function updatePlanAtPath(filePath: string, body: string, options: Omit<WritePlanOptions, "force">): Promise<WritePlanResult>;
+/**
+ * Writes or updates a named plan markdown file under `plansDir` (created if missing).
+ * Target is always `plansDir/<name>.md` — no collision suffixes.
+ * Without `force`, an existing file is left untouched and status `"exists"` is returned.
+ * With `force`, overwrites the body, preserves original `created`, and sets `updated`.
+ */
+export declare function writePlan(plansDir: string, name: string, body: string, options: WritePlanOptions): Promise<WritePlanResult>;
+//# sourceMappingURL=write-plan.d.ts.map

package/dist/vault/write-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-plan.d.ts","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;CACzB;AAmBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAuB1B"}

package/dist/vault/write-plan.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseHandoffFrontmatter } from "../util/frontmatter.js";
+import { fileExists } from "../util/fs.js";
+import { yamlDoubleQuoted } from "../util/yaml.js";
+function buildFrontmatter(options) {
+    const lines = [
+        "---",
+        `project: ${yamlDoubleQuoted(options.projectId)}`,
+        `created: ${yamlDoubleQuoted(options.created)}`,
+    ];
+    if (options.updated) {
+        lines.push(`updated: ${yamlDoubleQuoted(options.updated)}`);
+    }
+    lines.push("---");
+    return `${lines.join("\n")}\n\n`;
+}
+/**
+ * Overwrites an existing plan at an absolute path.
+ * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * Caller must validate the path (e.g. inside this project's `plans/` dir).
+ */
+export async function updatePlanAtPath(filePath, body, options) {
+    const now = options.now ?? new Date();
+    const existing = await readFile(filePath, "utf8");
+    const fm = parseHandoffFrontmatter(existing);
+    const created = fm.created ?? now.toISOString();
+    const updated = now.toISOString();
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        created,
+        updated,
+    }) + body;
+    await writeFile(filePath, content, "utf8");
+    return { path: filePath, status: "overwritten" };
+}
+/**
+ * Writes or updates a named plan markdown file under `plansDir` (created if missing).
+ * Target is always `plansDir/<name>.md` — no collision suffixes.
+ * Without `force`, an existing file is left untouched and status `"exists"` is returned.
+ * With `force`, overwrites the body, preserves original `created`, and sets `updated`.
+ */
+export async function writePlan(plansDir, name, body, options) {
+    const now = options.now ?? new Date();
+    await mkdir(plansDir, { recursive: true });
+    const filePath = path.join(plansDir, `${name}.md`);
+    const exists = await fileExists(filePath);
+    if (exists && !options.force) {
+        return { path: filePath, status: "exists" };
+    }
+    if (exists && options.force) {
+        return updatePlanAtPath(filePath, body, { projectId: options.projectId, now });
+    }
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        created: now.toISOString(),
+    }) + body;
+    await writeFile(filePath, content, "utf8");
+    return { path: filePath, status: "created" };
+}
+//# sourceMappingURL=write-plan.js.map

package/dist/vault/write-plan.js.map

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

package/package.json

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

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

@@ -2,7 +2,7 @@ Save a note to the Obsidian vault for this project.
 
 Run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder note "<user text>"
+  {{GROUNDER_CLI}} note "<user text>"
 
 The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
 

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

@@ -0,0 +1,65 @@
+Write a named, updatable plan document to the Obsidian vault for this project.
+
+Distill the instruction after `/grounder-plan` into a structured plan — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
+
+Build a markdown body with these sections:
+
+```markdown
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…
+```
+
+Update vs create — never guess a `--title` for an update:
+
+**1. Path known** (attached/open in chat, or printed by an earlier `grounder plan` this conversation): update that exact file.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path-to-existing-plan.md>
+```
+
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+
+**2. Path unknown** (e.g. "update the plan" with nothing attached and no prior path this conversation): look it up, then update as in (1).
+
+```bash
+{{GROUNDER_CLI}} plan list --limit 5
+```
+
+Pick the path matching the user's intent; ask if none or several match.
+
+**3. Genuinely new plan** (not an update): derive a `--title`.
+- If the instruction names one explicitly (e.g. `save as "implementation-phase-1"` or `…phase-1.md`), use it (strip a trailing `.md`).
+- Otherwise derive a short kebab-case name from the plan's title/goal and confirm it with the user before writing.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --title <name>
+```
+
+If the CLI refuses because that name already exists (non-zero exit; stderr names the conflict), tell the user and ask whether to overwrite (`--force`) or pick a different name. `--force` only resolves this title collision — it is never how you update a plan you already meant to target (use `--path` for that). **Never** silently pass `--force`.
+
+Run from the linked project folder or any subdirectory beneath it.
+The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
+
+Do not compute vault paths or write files yourself — the CLI handles it.
+Report the CLI output path from stdout to the user.

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

@@ -32,16 +32,16 @@ Rules:
 
 Then run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder handoff "<body>"
+  {{GROUNDER_CLI}} handoff "<body>"
 
 Optional short title slug (filename + frontmatter):
 
-  npx grounder handoff --title <slug> "<body>"
+  {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash
-npx grounder handoff "$(cat <<'EOF'
+{{GROUNDER_CLI}} handoff "$(cat <<'EOF'
 # Handoff: …
 …
 EOF

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

@@ -6,11 +6,11 @@ From the linked project folder or any subdirectory beneath it:
 
 1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
-   npx grounder handoff list --head
+   {{GROUNDER_CLI}} handoff list --head
 
 2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-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.
+3. Otherwise, read that file. If the user names a specific session instead, run `{{GROUNDER_CLI}} 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-note.md

@@ -2,7 +2,7 @@ Save a note to the Obsidian vault for this project.
 
 Run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder note "<user text>"
+  {{GROUNDER_CLI}} note "<user text>"
 
 The vault is outside the workspace — approve shell permissions if Cursor prompts you.
 

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

@@ -0,0 +1,65 @@
+Write a named, updatable plan document to the Obsidian vault for this project.
+
+Distill the instruction after `/grounder-plan` into a structured plan — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
+
+Build a markdown body with these sections:
+
+```markdown
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…
+```
+
+Update vs create — never guess a `--title` for an update:
+
+**1. Path known** (attached/open in chat, or printed by an earlier `grounder plan` this conversation): update that exact file.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path-to-existing-plan.md>
+```
+
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+
+**2. Path unknown** (e.g. "update the plan" with nothing attached and no prior path this conversation): look it up, then update as in (1).
+
+```bash
+{{GROUNDER_CLI}} plan list --limit 5
+```
+
+Pick the path matching the user's intent; ask if none or several match.
+
+**3. Genuinely new plan** (not an update): derive a `--title`.
+- If the instruction names one explicitly (e.g. `save as "implementation-phase-1"` or `…phase-1.md`), use it (strip a trailing `.md`).
+- Otherwise derive a short kebab-case name from the plan's title/goal and confirm it with the user before writing.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --title <name>
+```
+
+If the CLI refuses because that name already exists (non-zero exit; stderr names the conflict), tell the user and ask whether to overwrite (`--force`) or pick a different name. `--force` only resolves this title collision — it is never how you update a plan you already meant to target (use `--path` for that). **Never** silently pass `--force`.
+
+Run from the linked project folder or any subdirectory beneath it.
+The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+
+Do not compute vault paths or write files yourself — the CLI handles it.
+Report the CLI output path from stdout to the user.

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

@@ -32,16 +32,16 @@ Rules:
 
 Then run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder handoff "<body>"
+  {{GROUNDER_CLI}} handoff "<body>"
 
 Optional short title slug (filename + frontmatter):
 
-  npx grounder handoff --title <slug> "<body>"
+  {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash
-npx grounder handoff "$(cat <<'EOF'
+{{GROUNDER_CLI}} handoff "$(cat <<'EOF'
 # Handoff: …
 …
 EOF

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

@@ -6,11 +6,11 @@ From the linked project folder or any subdirectory beneath it:
 
 1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
-   npx grounder handoff list --head
+   {{GROUNDER_CLI}} handoff list --head
 
 2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-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.
+3. Otherwise, read that file. If the user names a specific session instead, run `{{GROUNDER_CLI}} handoff list --limit 5` and read the path they mean.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).
 

package/templates/vault/plan.md

@@ -0,0 +1,16 @@
+<!-- Reference shape for /grounder-plan. Not installed or filled by the CLI — slash commands embed this structure. -->
+
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…