@vs4vijay/piverse 0.1.0 → 0.6.0

package/extensions/pi-notes/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vs4vijay/pi-notes",
+  "version": "0.6.0",
+  "description": "Project-level notes for the Pi coding agent — /notes command with CLI and TUI",
+  "type": "module",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vs4vijay/piverse.git"
+  },
+  "author": "vs4vijay",
+  "homepage": "https://github.com/vs4vijay/piverse",
+  "bugs": {
+    "url": "https://github.com/vs4vijay/piverse/issues"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/extensions/pi-notes/plan.md

@@ -0,0 +1,151 @@
+# pi-notes — Feature Plan
+
+## Current State
+
+Project-level note-taking extension for Pi coding agent. Persists notes as JSON in `.pi/notes/notes.json`. Primary interface is a TUI opened via `/notes`, with CLI fallbacks for common operations.
+
+**Implemented:** MVP (store, core commands, TUI), CLI + TUI search, tags, pinning, external-editor title/content editing (`edit`), and JSON export/import. Stores are cached per-project so multi-project sessions don't collide.
+
+---
+
+## Planned Features
+
+### Phase 1: Foundation (MVP)
+
+#### 1.1 Note Store & Persistence
+- Load notes from `.pi/notes/notes.json` on `session_start`
+- Save notes after every mutation (create/update/delete)
+- Also save on `session_shutdown` (safety net)
+- Create directory `.pi/notes/` if missing
+- Note schema: `{ id: string, title: string, content: string, createdAt: ISO, updatedAt: ISO }`
+- ID generation: `crypto.randomUUID()`
+
+#### 1.2 Core Commands
+| Command | Behavior |
+|---------|----------|
+| `/notes` | Open TUI (list/view/edit/create) |
+| `/notes <title>` | Quick-add note with title (opens editor for content) |
+| `/notes list` | CLI: list all notes with index, title, preview |
+| `/notes show <id>` | CLI: print full note content (markdown) |
+| `/notes rm <id>` | CLI: delete note by ID (with confirmation) |
+
+#### 1.3 TUI — List View
+- Full-screen overlay via `ctx.ui.custom()`
+- Left pane: `SelectList` of notes (title + first 60 chars of content)
+- Right pane: `Markdown` preview of selected note
+- Keys: `↑/↓` navigate, `Enter` view full, `n` new, `e` edit, `d` delete, `q` quit
+- Header: "Pi Notes  [n] new  [q] quit"
+- Fuzzy filter on type (like session selector)
+
+#### 1.4 TUI — View Mode
+- Full-screen markdown render of selected note
+- Keys: `q`/`Esc` back to list, `e` edit
+
+#### 1.5 TUI — Create/Edit Mode
+- `ctx.ui.editor(title, prefill)` for title + content
+- On save: persist, return to list with new/updated note selected
+- On cancel: return to list unchanged
+
+---
+
+### Phase 2: Quality of Life
+
+#### 2.1 Search & Filter
+- `/notes search <query>` — CLI: filter notes by title/content match
+- TUI: live filter as you type (`/` to start, type to filter, `Esc`/`Enter` to finish)
+- Show match count in header
+
+#### 2.2 Tags (Frontmatter Extension)
+- Optional tags in note frontmatter: `tags: ["architecture", "decision"]`
+- `/notes tag <id> <tag>` — add tag
+- `/notes untag <id> <tag>` — remove tag
+- TUI: filter by tag (`t` key cycles tag filters)
+- CLI: `/notes list --tag <tag>`
+
+#### 2.3 Pinning
+- `/notes pin <id>` / `/notes unpin <id>` — pin to top of list
+- TUI: `p` toggles pin, pinned notes show 📌 prefix
+- Pinned notes sort above unpinned (both by updatedAt desc)
+
+---
+
+### Phase 3: Power Features
+
+#### 3.1 Linking & References
+- `[[note-id]]` or `[[note-title]]` syntax in content
+- TUI: `Enter` on link navigates to linked note
+- CLI: `/notes links <id>` — show backlinks
+
+#### 3.2 Templates
+- `/notes template <name>` — create note from template
+- Built-in templates: `decision`, `meeting`, `todo`, `snippet`
+- Templates stored in `.pi/notes/templates/*.md`
+
+---
+
+### Completed
+
+#### Export/Import (CLI)
+- `/notes export [path]` — export all notes as JSON (default `./notes.json` in cwd)
+- `/notes import <path>` — import and merge from JSON; incoming notes whose `id` already exists are skipped (existing notes win)
+- Reuses the atomic (temp + rename) write; validates the imported file shape
+
+#### Title/Content Editing (CLI)
+- `/notes edit <id>` — edit a note's title/content via external editor, prefilled with current values
+
+#### Per-Project Store Caching
+- `getNoteStore` caches one `NoteStore` per `cwd` (was a single global instance), so notes for different projects in one session don't collide
+- `getNoteStore()` (no arg) defaults to `process.cwd()`
+
+---
+
+## Implementation Priority
+
+| Phase | Features | Why |
+|-------|----------|-----|
+| 1 | Store, Core Commands, TUI (List/View/Edit) | Working note system end-to-end |
+| 2 | Search, Tags, Pinning | Daily workflow improvements |
+| 3 | Linking, Templates, Export | Advanced organization |
+
+---
+
+## Technical Notes
+
+- All commands register via `pi.registerCommand("notes", ...)`
+- Subcommands parsed from `args` string in handler
+- TUI uses pi-tui: `SelectList`, `Markdown`, `Editor`, `VStack`, `HStack`, `Box`, `Text`
+- Persistence: JSON file, atomic write (write temp → rename)
+- Error handling: notify user via `ctx.ui.notify()`, never throw
+- Follows Pi Queue patterns for `session_start`/`session_shutdown`
+
+---
+
+## File Structure
+
+```
+extensions/pi-notes/
+├── src/
+│   ├── index.ts        # Extension entry, command registration, hooks
+│   ├── store.ts        # NoteStore class: load/save/CRUD
+│   ├── tui.ts          # TUI components: ListView, ViewMode, EditorMode
+│   └── types.ts        # Note interface, CommandArgs types
+├── package.json
+├── README.md
+└── plan.md             # This file
+```
+
+---
+
+## Acceptance Criteria (Phase 1)
+
+- [ ] `/notes` opens TUI with empty list (first run)
+- [ ] `/notes "My Title"` creates note, opens editor for content
+- [ ] TUI: list shows notes, preview updates on selection
+- [ ] TUI: `n` → editor → save → note appears in list
+- [ ] TUI: `e` on selected → editor → save → updates note
+- [ ] TUI: `d` on selected → confirm → removes note
+- [ ] `/notes list` prints formatted table in CLI
+- [ ] `/notes show <id>` prints full markdown
+- [ ] `/notes rm <id>` confirms then deletes
+- [ ] Notes persist across `/reload` and session restart
+- [ ] TypeScript compiles without errors

package/extensions/pi-notes/src/index.ts

@@ -0,0 +1,369 @@
+/**
+ * pi-notes — Project-level notes for Pi coding agent
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getNoteStore, resetNoteStore } from "./store.js";
+import type { Note } from "./types.js";
+import { parseNotesCommand, type ParsedCommand } from "./types.js";
+import { createNotesTUI } from "./tui.js";
+import { isAbsolute, join } from "path";
+
+let tuiHandle: (() => void) | null = null;
+
+export default async function (pi: ExtensionAPI) {
+  // Initialize store on session start
+  pi.on("session_start", async (_event, ctx) => {
+    resetNoteStore(); // Ensure fresh instance per session
+    const store = getNoteStore(ctx.cwd);
+    await store.load();
+  });
+
+  // Save on shutdown
+  pi.on("session_shutdown", async () => {
+    // Store auto-saves on mutations, but ensure final flush
+    const store = getNoteStore();
+    const notes = await store.getAll();
+    await store.save(notes);
+  });
+
+  // Main /notes command
+  pi.registerCommand("notes", {
+    description: "Project notes — TUI (no args) or quick-add: /notes <title>",
+    handler: async (args, ctx) => {
+      const parsed = parseNotesCommand(args);
+      const store = getNoteStore(ctx.cwd);
+      const notes = await store.getAll();
+
+      // Handle subcommands
+      switch (parsed.subcommand) {
+        case "list":
+          await handleList(notes, ctx);
+          return;
+        case "show":
+          await handleShow(parsed.args, notes, ctx);
+          return;
+        case "rm":
+          await handleRemove(parsed.args, store, ctx);
+          return;
+        case "edit":
+          await handleEdit(parsed.args, store, ctx);
+          return;
+        case "search":
+          await handleSearch(parsed.args, notes, ctx);
+          return;
+        case "tag":
+          await handleTag(parsed.args, store, ctx);
+          return;
+        case "untag":
+          await handleUntag(parsed.args, store, ctx);
+          return;
+        case "pin":
+          await handlePin(parsed.args, store, ctx);
+          return;
+        case "unpin":
+          await handleUnpin(parsed.args, store, ctx);
+          return;
+        case "export":
+          await handleExport(parsed.args, store, ctx);
+          return;
+        case "import":
+          await handleImport(parsed.args, store, ctx);
+          return;
+        default:
+          // Quick-add or open TUI
+          if (parsed.args.length > 0) {
+            await handleQuickAdd(parsed.args.join(" "), store, ctx);
+          } else {
+            await openTUI(ctx, notes);
+          }
+      }
+    },
+  });
+}
+
+async function handleList(notes: Note[], ctx: ExtensionCommandContext): Promise<void> {
+  if (notes.length === 0) {
+    ctx.ui.notify("No notes yet. Use /notes <title> to create one.", "info");
+    return;
+  }
+
+  const lines = notes.map((n, i) => {
+    const pin = n.pinned ? "📌 " : "";
+    const tags = n.tags?.length ? ` [${n.tags.join(", ")}]` : "";
+    const preview = n.content.slice(0, 50).replace(/\n/g, " ");
+    return `${i + 1}. ${pin}${n.title}${tags} — ${preview}`;
+  });
+
+  ctx.ui.notify(`Notes (${notes.length}):\n${lines.join("\n")}`, "info");
+}
+
+async function handleShow(args: string[], notes: Note[], ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes show <id>", "error");
+    return;
+  }
+
+  const id = args[0];
+  const note = notes.find((n) => n.id === id || n.id.startsWith(id));
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  const meta = `📌 ${note.pinned ? "pinned" : ""}  |  Tags: ${note.tags?.join(", ") || "none"}  |  Created: ${note.createdAt}  |  Updated: ${note.updatedAt}`;
+  ctx.ui.notify(`# ${note.title}\n${meta}\n\n${note.content || "*(empty)*"}`, "info");
+}
+
+async function handleRemove(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes rm <id>", "error");
+    return;
+  }
+
+  const id = args[0];
+  const notes = await store.getAll();
+  const note = notes.find((n) => n.id === id || n.id.startsWith(id));
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  // Confirm via TUI confirm dialog
+  const confirmed = await ctx.ui.confirm(
+    "Delete note",
+    `Delete "${note.title}"? This cannot be undone.`
+  );
+
+  if (confirmed) {
+    const deleted = await store.delete(id);
+    if (deleted) {
+      ctx.ui.notify(`Deleted note: ${note.title}`, "info");
+    } else {
+      ctx.ui.notify("Delete failed", "error");
+    }
+  }
+}
+
+async function handleEdit(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes edit <id>", "error");
+    return;
+  }
+
+  const id = args[0];
+  const notes = await store.getAll();
+  const note = notes.find((n) => n.id === id || n.id.startsWith(id));
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  const title = await ctx.ui.editor(`Edit: ${note.title}`, note.title);
+  if (title === undefined) {
+    ctx.ui.notify("Cancelled", "info");
+    return;
+  }
+
+  const content = await ctx.ui.editor(`Content for: ${title}`, note.content);
+  if (content === undefined) {
+    ctx.ui.notify("Cancelled", "info");
+    return;
+  }
+
+  await store.update(note.id, { title, content });
+  ctx.ui.notify(`Updated note: ${title}`, "info");
+}
+
+async function handleSearch(args: string[], notes: Note[], ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes search <query>", "error");
+    return;
+  }
+
+  const query = args.join(" ").toLowerCase();
+  const results = notes.filter(
+    (n) => n.title.toLowerCase().includes(query) || n.content.toLowerCase().includes(query)
+  );
+
+  if (results.length === 0) {
+    ctx.ui.notify(`No notes matching: ${query}`, "info");
+    return;
+  }
+
+  const lines = results.map((n, i) => {
+    const pin = n.pinned ? "📌 " : "";
+    const preview = n.content.slice(0, 50).replace(/\n/g, " ");
+    return `${i + 1}. ${pin}${n.title} — ${preview}`;
+  });
+
+  ctx.ui.notify(`Search results (${results.length}):\n${lines.join("\n")}`, "info");
+}
+
+async function handleTag(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length < 2) {
+    ctx.ui.notify("Usage: /notes tag <id> <tag>", "error");
+    return;
+  }
+
+  const [id, tag] = args;
+  const note = await store.getById(id);
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  const tags = [...new Set([...(note.tags || []), tag])];
+  await store.update(id, { tags });
+  ctx.ui.notify(`Added tag "${tag}" to "${note.title}"`, "info");
+}
+
+async function handleUntag(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length < 2) {
+    ctx.ui.notify("Usage: /notes untag <id> <tag>", "error");
+    return;
+  }
+
+  const [id, tag] = args;
+  const note = await store.getById(id);
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  const tags = (note.tags || []).filter((t) => t !== tag);
+  await store.update(id, { tags });
+  ctx.ui.notify(`Removed tag "${tag}" from "${note.title}"`, "info");
+}
+
+async function handlePin(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes pin <id>", "error");
+    return;
+  }
+
+  const id = args[0];
+  const note = await store.getById(id);
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  await store.update(id, { pinned: true });
+  ctx.ui.notify(`Pinned "${note.title}"`, "info");
+}
+
+async function handleUnpin(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes unpin <id>", "error");
+    return;
+  }
+
+  const id = args[0];
+  const note = await store.getById(id);
+
+  if (!note) {
+    ctx.ui.notify(`Note not found: ${id}`, "error");
+    return;
+  }
+
+  await store.update(id, { pinned: false });
+  ctx.ui.notify(`Unpinned "${note.title}"`, "info");
+}
+
+async function handleQuickAdd(title: string, store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  // Strip surrounding quotes from a quoted title
+  title = title.replace(/^(['"])(.*)\1$/, "$2");
+
+  // Open external editor for content
+  const content = await ctx.ui.editor(`New note: ${title}`, "");
+
+  if (content === undefined) {
+    ctx.ui.notify("Cancelled", "info");
+    return;
+  }
+
+  const note = await store.create(title, content);
+  ctx.ui.notify(`Created note: ${note.title}`, "info");
+}
+
+async function handleExport(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  const filePath = resolvePath(ctx.cwd, args[0] ?? "notes.json");
+  const count = await store.exportTo(filePath);
+  ctx.ui.notify(`Exported ${count} notes to ${filePath}`, "info");
+}
+
+async function handleImport(args: string[], store: ReturnType<typeof getNoteStore>, ctx: ExtensionCommandContext): Promise<void> {
+  if (args.length === 0) {
+    ctx.ui.notify("Usage: /notes import <path>", "error");
+    return;
+  }
+
+  const filePath = resolvePath(ctx.cwd, args[0]);
+  try {
+    const { imported, skipped } = await store.importFrom(filePath);
+    const skippedText = skipped > 0 ? ` (${skipped} already present, skipped)` : "";
+    ctx.ui.notify(`Imported ${imported} note(s) from ${filePath}${skippedText}`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Import failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+  }
+}
+
+function resolvePath(cwd: string, p: string): string {
+  return isAbsolute(p) ? p : join(cwd, p);
+}
+
+async function openTUI(ctx: ExtensionCommandContext, initialNotes: Note[]): Promise<void> {
+  const store = getNoteStore(ctx.cwd);
+
+  const component = createNotesTUI(
+    initialNotes,
+    ctx.ui.theme,
+    () => {
+      // onClose
+      tuiHandle?.();
+      tuiHandle = null;
+    },
+    async (note?: Note): Promise<Note[] | undefined> => {
+      // External editor: create or edit a note
+      if (note) {
+        const title = await ctx.ui.editor(`Edit: ${note.title}`, note.title);
+        if (title === undefined) return undefined;
+        const content = await ctx.ui.editor(`Content for: ${title}`, note.content);
+        if (content === undefined) return undefined;
+        await store.update(note.id, { title, content });
+      } else {
+        const title = await ctx.ui.editor("New Note", "");
+        if (title === undefined) return undefined;
+        const content = await ctx.ui.editor(`Content for: ${title}`, "");
+        if (content === undefined) return undefined;
+        await store.create(title, content);
+      }
+      return store.getAll();
+    },
+    async (id: string): Promise<Note[]> => {
+      await store.delete(id);
+      return store.getAll();
+    },
+    async (note: Note): Promise<Note[]> => {
+      await store.update(note.id, { pinned: !note.pinned });
+      return store.getAll();
+    }
+  );
+
+  // Show custom overlay
+  await ctx.ui.custom(
+    (tui, theme, keybindings, done) => {
+      // The component is already a Focusable Component
+      tuiHandle = () => done(undefined);
+      return component;
+    },
+    { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%" } }
+  );
+}