grounder 0.0.1 → 0.1.0

package/dist/vault/write-handoff.js

@@ -0,0 +1,40 @@
+import { mkdir } from "node:fs/promises";
+import { writeUniqueMarkdown } from "../util/fs.js";
+import { timestampedBasename } from "../util/timestamp-slug.js";
+import { yamlDoubleQuoted } from "../util/yaml.js";
+function buildFrontmatter(options) {
+    const lines = ["---", `project: ${yamlDoubleQuoted(options.projectId)}`];
+    if (options.branch) {
+        lines.push(`branch: ${yamlDoubleQuoted(options.branch)}`);
+    }
+    lines.push(`created: ${yamlDoubleQuoted(options.created)}`);
+    if (options.title) {
+        lines.push(`title: ${yamlDoubleQuoted(options.title)}`);
+    }
+    lines.push("---");
+    return `${lines.join("\n")}\n\n`;
+}
+/**
+ * Writes a new handoff markdown file under `logsDir` (created if missing).
+ * Prepends YAML frontmatter (`project`, optional `branch`/`title`, `created`)
+ * ahead of `body`. Never overwrites — exclusive create with `_NN` on collision.
+ * @param logsDir - Absolute project logs directory.
+ * @param body - Agent-supplied markdown (sections such as Done / Next); not validated here.
+ * @returns Absolute path of the written file.
+ */
+export async function writeHandoff(logsDir, body, options) {
+    const now = options.now ?? new Date();
+    await mkdir(logsDir, { recursive: true });
+    const basename = timestampedBasename(body, {
+        title: options.title,
+        now,
+    });
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        branch: options.branch,
+        created: now.toISOString(),
+        title: options.title,
+    }) + body;
+    return writeUniqueMarkdown(logsDir, basename, content);
+}
+//# sourceMappingURL=write-handoff.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-handoff.js","sourceRoot":"","sources":["../../src/vault/write-handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAcnD,SAAS,gBAAgB,CAAC,OAKzB;IACC,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,YAAY,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,WAAW,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,YAAY,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,UAAU,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,IAAY,EACZ,OAA4B;IAE5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE;QACzC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG;KACJ,CAAC,CAAC;IACH,MAAM,OAAO,GACX,gBAAgB,CAAC;QACf,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,GAAG,CAAC,WAAW,EAAE;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,GAAG,IAAI,CAAC;IAEZ,OAAO,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC"}

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

@@ -0,0 +1,11 @@
+export interface WriteNoteOptions {
+    title?: string;
+    now?: Date;
+}
+/**
+ * Writes a new note markdown file under `notesDir` (created if missing).
+ * Never overwrites — exclusive create with `_NN` on collision.
+ * @returns Absolute path of the written file.
+ */
+export declare function writeNote(notesDir: string, text: string, options?: WriteNoteOptions): Promise<string>;
+//# sourceMappingURL=write-note.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-note.d.ts","sourceRoot":"","sources":["../../src/vault/write-note.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/dist/vault/write-note.js

@@ -0,0 +1,15 @@
+import { mkdir } from "node:fs/promises";
+import { writeUniqueMarkdown } from "../util/fs.js";
+import { timestampedBasename } from "../util/timestamp-slug.js";
+/**
+ * Writes a new note markdown file under `notesDir` (created if missing).
+ * Never overwrites — exclusive create with `_NN` on collision.
+ * @returns Absolute path of the written file.
+ */
+export async function writeNote(notesDir, text, options = {}) {
+    const now = options.now ?? new Date();
+    await mkdir(notesDir, { recursive: true });
+    const basename = timestampedBasename(text, { title: options.title, now });
+    return writeUniqueMarkdown(notesDir, basename, text);
+}
+//# sourceMappingURL=write-note.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-note.js","sourceRoot":"","sources":["../../src/vault/write-note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAOhE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,IAAY,EACZ,UAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE3C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1E,OAAO,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,13 +1,48 @@
 {
   "name": "grounder",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.1.0",
+  "description": "Connect git projects to Obsidian dev vaults for AI agent memory",
+  "type": "module",
+  "bin": {
+    "grounder": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "obsidian",
+    "cursor",
+    "mcp",
+    "ai",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrej-kolic/grounder.git",
+    "directory": "packages/grounder"
+  },
+  "bugs": {
+    "url": "https://github.com/andrej-kolic/grounder/issues"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
-}
+  "homepage": "https://github.com/andrej-kolic/grounder/tree/main/packages/grounder#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "pnpm run build",
+    "test": "vitest run"
+  }
+}

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

@@ -0,0 +1,11 @@
+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>"
+
+The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
+
+Use the text after `/grounder-note` as the note body.
+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

@@ -0,0 +1,54 @@
+Write a session handoff checkpoint to the Obsidian vault for this project.
+
+Summarize the session into a structured handoff — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
+
+Build a markdown body with these sections (lean; roughly half a screen to one screen):
+
+```markdown
+# Handoff: <short label>
+
+## Done
+- …
+
+## Next
+1. …   # ordered; most important section for resume — required
+2. …
+
+## Blockers
+- None | …
+
+## Decisions
+- …    # include rejected alternatives / pitfalls when useful
+
+## Files
+- path/to/relevant.ts
+```
+
+Rules:
+- **Next is mandatory and ordered** — if only one section is read, this is it
+- Empty sections are OK (`Blockers: None` beats omission)
+- Few concrete file paths, not an exhaustive diff
+
+Then run from the linked project folder or any subdirectory beneath it:
+
+  npx grounder handoff "<body>"
+
+Optional short title slug (filename + frontmatter):
+
+  npx grounder handoff --title <slug> "<body>"
+
+For multi-line bodies, prefer a shell heredoc so quoting does not break:
+
+```bash
+npx grounder handoff "$(cat <<'EOF'
+# Handoff: …
+…
+EOF
+)"
+```
+
+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.md

@@ -0,0 +1,20 @@
+Hydrate this session from the latest vault handoff and repo truth.
+
+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):
+
+   npx grounder handoff list --limit 5
+
+2. If the list is 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.
+
+4. Read repo `AGENTS.md` (project conventions and constraints).
+
+5. Summarize briefly what is next (from the handoff `## Next` section when present), then start work.
+
+The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
+Use free-text after `/grounder-task` as optional focus (session name, index, or task hint).

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

@@ -0,0 +1,11 @@
+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>"
+
+The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+
+Use the text after `/grounder-note` as the note body.
+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

@@ -0,0 +1,54 @@
+Write a session handoff checkpoint to the Obsidian vault for this project.
+
+Summarize the session into a structured handoff — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
+
+Build a markdown body with these sections (lean; roughly half a screen to one screen):
+
+```markdown
+# Handoff: <short label>
+
+## Done
+- …
+
+## Next
+1. …   # ordered; most important section for resume — required
+2. …
+
+## Blockers
+- None | …
+
+## Decisions
+- …    # include rejected alternatives / pitfalls when useful
+
+## Files
+- path/to/relevant.ts
+```
+
+Rules:
+- **Next is mandatory and ordered** — if only one section is read, this is it
+- Empty sections are OK (`Blockers: None` beats omission)
+- Few concrete file paths, not an exhaustive diff
+
+Then run from the linked project folder or any subdirectory beneath it:
+
+  npx grounder handoff "<body>"
+
+Optional short title slug (filename + frontmatter):
+
+  npx grounder handoff --title <slug> "<body>"
+
+For multi-line bodies, prefer a shell heredoc so quoting does not break:
+
+```bash
+npx grounder handoff "$(cat <<'EOF'
+# Handoff: …
+…
+EOF
+)"
+```
+
+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.md

@@ -0,0 +1,20 @@
+Hydrate this session from the latest vault handoff and repo truth.
+
+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):
+
+   npx grounder handoff list --limit 5
+
+2. If the list is 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.
+
+4. Read repo `AGENTS.md` (project conventions and constraints).
+
+5. Summarize briefly what is next (from the handoff `## Next` section when present), then start work.
+
+The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+Use free-text after `/grounder-task` as optional focus (session name, index, or task hint).

package/templates/vault/session-handoff.md

@@ -0,0 +1,19 @@
+<!-- Reference shape for /grounder-task-handoff. Not installed or filled by the CLI — slash commands embed this structure. -->
+
+# Handoff: <title or short label>
+
+## Done
+- …
+
+## Next
+1. …
+2. …
+
+## Blockers
+- None
+
+## Decisions
+- …
+
+## Files
+- path/to/relevant.ts

package/index.js

@@ -1 +0,0 @@
-module.exports = {};