@vs4vijay/piverse 0.1.0 → 0.6.0

package/.agents/skills/pi-extension/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: pi-extension
+description: Scaffold a new Pi coding-agent extension in the piverse monorepo following the established project structure, naming, and code conventions. Use when adding a new extension (a `pi-<name>` package under `extensions/`), creating its src/index.ts entry, README, and package.json, or when asked to "add another extension", "onboard a new extension", or "create a pi extension".
+---
+
+# Creating a Pi extension in piverse
+
+This skill encodes the conventions used by the existing extensions in this repo
+(`pi-queue`, `pi-notes`). Follow them exactly so new extensions are consistent,
+publishable to npm, and discoverable on the [pi.dev gallery](https://pi.dev/packages).
+
+Read `extensions/pi-queue/` and `extensions/pi-notes/` as living references before
+and while you scaffold.
+
+---
+
+## 1. Project structure & naming
+
+Each extension is its own npm package inside the monorepo root:
+
+```
+extensions/
+├── pi-queue/               # /queue  — message queueing
+├── pi-notes/               # /notes  — project notes (CLI + TUI)
+└── pi-<name>/              # <-- NEW extension lives here
+    ├── src/
+    │   └── index.ts        # required extension entry point
+    ├── README.md           # required
+    ├── package.json        # required
+    └── plan.md             # optional (planning notes; tracked like others)
+```
+
+### Naming rules
+
+- Folder: `extensions/pi-<name>/` — always the `pi-` prefix, lowercase, hyphenated.
+- npm name: `@vs4vijay/pi-<name>` — **always the `@vs4vijay` scope**.
+- Default export registers one or more `/` slash commands. Pick clear, short command
+  names. If the extension has several related commands, prefix them (e.g. `pi-queue`
+  registers `/queue-*` and `/q-*` aliases).
+- `keywords` must include `"pi-package"` for pi.dev gallery discovery.
+
+### tsconfig conventions (repo root, no per-extension change needed)
+
+`strict: true`, `module: ESNext`, `moduleResolution: bundler`, `noEmit: true`,
+`verbatimModuleSyntax: true`, `isolatedModules: true`. The root tsconfig includes
+`extensions/*/src/**/*.ts`.
+
+---
+
+## 2. package.json template
+
+Copy this shape exactly (values change per extension). Match the existing files'
+field ordering for consistency:
+
+```json
+{
+  "name": "@vs4vijay/pi-<name>",
+  "version": "0.1.0",
+  "description": "<one-line: what the /<command> does>",
+  "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"
+  }
+}
+```
+
+- The `pi` manifest tells Pi where the resources live: `"extensions": ["./src/index.ts"]`.
+- `peerDependencies` **must** use `"*"` ranges for the bundled Pi core packages
+  (`@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`) — Pi provides
+  them at runtime; do not bundle them.
+- If the extension only ships as part of the parent `@vs4vijay/piverse` package, list
+  the same resource path in the root `package.json` `pi.extensions` array. Each
+  extension normally also ships standalone via its own package (the repo's
+  `.github/workflows/release.yml` publishes every `extensions/*/` sub-package).
+
+---
+
+## 3. src/index.ts — extension entry point
+
+Use the `ExtensionAPI` type and a default export. This is the canonical structure
+(see `extensions/pi-queue/src/index.ts` and `extensions/pi-notes/src/index.ts`):
+
+```ts
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export default async function (pi: ExtensionAPI) {
+  // Register /<command>
+  pi.registerCommand("<command>", {
+    description: "<one line: what it does and how to use it>",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      // args: the raw string after the command name
+      // ctx.ui.notify(message, level) — levels: "info" | "warning" | "error"
+      ctx.ui.notify(`Hello: ${args}`, "info");
+    },
+  });
+}
+```
+
+### Key rules
+
+- **`import type` for types**: with `verbatimModuleSyntax`, use `import type` when
+  importing only types (e.g. `ExtensionAPI`, `ExtensionCommandContext`).
+- **`.js` extensions on relative imports**: ESM/NodeNext-style — `from "./store.js"`,
+  not `"./store"`.
+- **No build step**: Pi loads TypeScript extensions directly (via jiti). No compile.
+- **State in closure scope**: keep per-extension state as module/closure variables
+  inside the default export (see `pi-queue`'s `let queue`).
+
+### Lifecycle hooks
+
+Use `pi.on("<event>", handler)` for session lifecycle (see both extensions):
+
+```ts
+pi.on("session_start", async (_event, ctx) => { /* reset/load state */ });
+pi.on("session_shutdown", async () => { /* flush/persist */ });
+pi.on("agent_settled", async (_event, ctx) => { /* run after each turn */ });
+pi.on("tool_result", async (event) => { /* observe tool outcomes */ });
+```
+
+When you need state to survive across turns, persist it — either to a file (see the
+store pattern) or to the session (`pi.appendEntry(type, data)` and read it back in
+`session_start` via `ctx.sessionManager.getEntries()` — see `pi-queue`).
+
+---
+
+## 4. Persistence store pattern (file-backed)
+
+For persisted data, create a small `src/store.ts` following `pi-notes/src/store.ts`:
+
+- A `class` that wraps read/write, with `load()`, `save()`, `getAll()`, `getById()`,
+  `create()`, `update()`, `delete()`, and any domain methods.
+- **Atomic writes**: write to a temp path then `fs.rename` (never write in place).
+- A module-level singleton (`getNoteStore`) with a `reset` function so a fresh
+  instance is created per session.
+- **Lifecycle ordering matters**: on `session_start`, `reset()` the store **first**,
+  then `getStore(cwd)` and `await store.load()`, so the same loaded instance is used
+  all session and the `session_shutdown` flush writes real data (not an emptied one).
+
+---
+
+## 5. CLI UX
+
+- Use `ctx.ui.notify(message, level)` for all user feedback (`info | warning | error`).
+- Use `ctx.ui.confirm(title, message)` for destructive actions that need confirmation.
+- Use `ctx.ui.editor(title, initial)` to open the external editor for multi-line content.
+- Validate input and return early with a usage/error message:
+  `ctx.ui.notify("Usage: /<command> <arg>", "error")`.
+- For slash-command dispatch helpers, see `pi-queue/src/index.ts`.
+
+---
+
+## 6. TUI (optional)
+
+For interactive full-screen UI, follow `pi-notes/src/tui.ts`:
+
+- Build a component class implementing `Focusable` using primitives from
+  `@earendil-works/pi-tui` (`VStack`, `HStack`, `Box`, `Text`, `ScrollView`,
+  `Markdown`, `SelectList`).
+- Export a factory function (e.g. `create<Name>TUI`) returning `Component & Focusable`.
+- Show it from the extension via `ctx.ui.custom(fn, { overlay: true, overlayOptions })`.
+  Note: `OverlayOptions` supports `width`/`maxHeight` (percentages), **not** `height`.
+- Keep a module-level `tuiHandle` you can call to programmatically close/reopen it.
+- Keep TUI state in the component; persist via the store.
+
+---
+
+## 7. README.md
+
+Include, in this order (match `pi-queue/README.md` and `pi-notes/README.md`):
+
+1. `# @vs4vijay/pi-<name>` heading
+2. One-paragraph description
+3. **Install** — `pi install npm:@vs4vijay/pi-<name>`
+4. **Commands** table (command → description)
+5. **Usage / Examples** — transcript-style examples with realistic output
+6. Any additional sections (How it works, Features, Persistence, TUI, etc.)
+
+---
+
+## 8. Verification
+
+Before finishing:
+
+1. Run the typecheck from the repo root and confirm it passes:
+   ```bash
+   npm run typecheck
+   ```
+2. Quick-test without installing:
+   ```bash
+   pi -e ./extensions/pi-<name>/src/index.ts
+   ```
+3. Confirm the `package.json` has all required fields (name scope, `pi-package`
+   keyword, `pi` manifest, repository, license, peerDependencies with `"*"`).
+4. Add the new extension under `extensions/` and, if it should ship with the parent
+   ecosystem package, register it in the root `package.json` `pi.extensions`.
+
+---
+
+## Checklist
+
+- [ ] Folder named `extensions/pi-<name>/`
+- [ ] npm name `@vs4vijay/pi-<name>`
+- [ ] `src/index.ts` with default `export default function(pi)` and `registerCommand`
+- [ ] `package.json` with `pi-package` keyword, `pi` manifest, repository/license, peerDeps `"*"`
+- [ ] `README.md` with install + commands + usage examples
+- [ ] `npm run typecheck` passes
+- [ ] Tested with `pi -e`

package/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Typecheck
+        run: npx tsc --noEmit

package/.github/workflows/release.yml

@@ -0,0 +1,106 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g., v1.0.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Validate version consistency
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            TAG_VERSION=${GITHUB_REF#refs/tags/v}
+            PKG_VERSION=$(node -p "require('./package.json').version")
+            if [[ "$TAG_VERSION" != "$PKG_VERSION" ]]; then
+              echo "Error: Tag version ($TAG_VERSION) doesn't match package.json version ($PKG_VERSION)"
+              exit 1
+            fi
+          fi
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: validate
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
+          CURRENT_TAG=${GITHUB_REF#refs/tags/}
+
+          if [[ -n "$PREV_TAG" ]]; then
+            echo "## Changes since $PREV_TAG" > CHANGELOG.md
+            git log --pretty=format:"- %s (%h)" $PREV_TAG..HEAD >> CHANGELOG.md
+          else
+            echo "## Initial Release" > CHANGELOG.md
+          fi
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          body_path: CHANGELOG.md
+          draft: false
+          prerelease: ${{ contains(github.ref_name, 'alpha') || contains(github.ref_name, 'beta') || contains(github.ref_name, 'rc') }}
+
+  publish-npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: [validate, create-release]
+    if: startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, 'alpha') && !contains(github.ref_name, 'beta')
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          # npm trusted publishing (OIDC) requires npm >= 11.5.1 / Node >= 22.14
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish root package
+        run: npm publish --access public --provenance
+
+      - name: Publish sub-packages
+        run: |
+          for dir in extensions/*/; do
+            if [ -f "$dir/package.json" ]; then
+              echo "Publishing $dir"
+              cd "$dir"
+              npm publish --access public --provenance
+              cd -
+            fi
+          done

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vijay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,64 +1,107 @@
-# Piverse
+# Piverse 🌌
 
-A multi-extension ecosystem for the [Pi coding agent](https://github.com/earendil-works/pi).
+A multi-extension ecosystem for the [Pi coding agent](https://pi.dev).
 
-## Install
+## Extensions
+
+| Extension | Command | Description |
+|-----------|---------|-------------|
+| [pi-queue](./extensions/pi-queue) | `/queue` | Queue messages to run after the current agent turn settles |
+| [pi-notes](./extensions/pi-notes) | `/notes` | Project-level notes with TUI, tags, search, and pinning |
 
-**All extensions:**
+## Install
 
 ```bash
 pi install npm:@vs4vijay/piverse
 ```
 
-**Individual extensions:**
+## Usage
 
-```bash
-pi install npm:@vs4vijay/pi-queue
-```
+### `/queue <message>`
 
-**From git (latest):**
+Queue a message that automatically sends after the current turn finishes.
 
-```bash
-pi install git:github.com/vs4vijay/piverse
+```
+/queue refactor the auth module next
+/queue run the test suite
 ```
 
-## Extensions
+- `/queue` (no args) — show pending messages
+- `/queue-clear` — empty the queue
 
-| Extension | Package | Description |
-|-----------|---------|-------------|
-| [pi-queue](./extensions/pi-queue) | `@vs4vijay/pi-queue` | Queue messages to run after the current turn settles |
+Messages fire one at a time, in order, after each `agent_settled` event.
 
-## Development
+### `/notes`
 
-### Quick test (single extension)
+Project-level notes persisted in `.pi/notes/notes.json` (committed to git, team-shared).
 
-```bash
-pi -e ./extensions/pi-queue/src/index.ts
+```
+/notes                  # Open the full-screen TUI (list, view, create, edit, delete)
+/notes "API contract"   # Quick-add a note with that title (opens editor for content)
+/notes list             # List all notes in the CLI
+/notes show <id>        # Show a note's full content
+/notes edit <id>        # Edit a note's title/content via external editor
+/notes search <query>   # Search notes by title/content
+/notes tag <id> <tag>   # Add a tag to a note
+/notes pin <id>         # Pin a note to the top of the list
+/notes rm <id>          # Delete a note (with confirmation)
+/notes export [path]    # Export all notes to a JSON file
+/notes import <path>    # Import and merge notes from a JSON file
 ```
 
-### Hot-reload via symlink
+- Persists as JSON, auto-saves on every mutation
+- Loads on `session_start`, flushes on `session_shutdown`
+- TUI keys: `↑/↓` or `j/k` to navigate, `Enter` to view, `n` new, `e` edit, `d` delete, `p` pin, `/` to filter by typing, `q`/`Esc` to quit
 
-Link an extension into Pi's auto-discovery directory:
+## Development
+
+```bash
+git clone git@github.com:vs4vijay/piverse.git ~/GitHub/piverse
+```
+
+### Hot-reload (symlink into Pi)
 
 ```bash
 ln -sf ~/GitHub/piverse/extensions/pi-queue ~/.pi/agent/extensions/pi-queue
 ```
 
-Then `/reload` inside Pi to pick up changes.
+Edit source → `/reload` in Pi → changes are live. No build step.
+
+### Quick test (no install)
+
+```bash
+pi -e ./extensions/pi-queue/src/index.ts
+```
 
 ### Type checking
 
 ```bash
+npm install
 npm run typecheck
 ```
 
-## Structure
+## Project Structure
 
 ```
 piverse/
 ├── extensions/
-│   ├── pi-queue/        # /queue - message queueing
-│   └── ...              # future extensions
-├── package.json         # pi-package root
-└── tsconfig.json        # shared type checking
+│   ├── pi-queue/          # /queue - message queueing
+│   ├── pi-notes/          # /notes - project notes
+│   └── ...                # more extensions coming
+├── package.json           # workspace root
+├── tsconfig.json          # shared type checking
+└── README.md
 ```
+
+## Contributing
+
+1. Fork & clone
+2. `mkdir extensions/pi-<name>/src`
+3. Add `package.json` with `"pi": { "extensions": ["./src/index.ts"] }`
+4. Implement in `src/index.ts`
+5. Test with `pi -e ./extensions/pi-<name>/src/index.ts`
+6. PR
+
+## License
+
+MIT

package/extensions/pi-notes/README.md

@@ -0,0 +1,152 @@
+# @vs4vijay/pi-notes
+
+Project-level notes for the Pi coding agent. Persists notes as JSON in `.pi/notes/notes.json` (committed to git, team-shared).
+
+## Install
+
+```sh
+pi install npm:@vs4vijay/pi-notes
+```
+
+Or add to your Pi config:
+
+```json
+{
+  "pi": {
+    "extensions": [
+      "./extensions/pi-queue/src/index.ts",
+      "./extensions/pi-notes/src/index.ts"
+    ]
+  }
+}
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/notes` | Open TUI (list, view, create, edit, delete) |
+| `/notes <title>` | Quick-add note with title (opens editor for content) |
+| `/notes list` | List all notes in CLI |
+| `/notes show <id>` | Show full note content |
+| `/notes edit <id>` | Edit a note's title/content via external editor |
+| `/notes rm <id>` | Delete note (with confirmation) |
+| `/notes search <query>` | Search notes by title/content |
+| `/notes tag <id> <tag>` | Add tag to note |
+| `/notes untag <id> <tag>` | Remove tag from note |
+| `/notes pin <id>` | Pin note to top of list |
+| `/notes unpin <id>` | Unpin note |
+| `/notes export [path]` | Export all notes to a JSON file (default: `./notes.json`) |
+| `/notes import <path>` | Import and merge notes from a JSON file |
+
+## TUI Interface
+
+```
+/notes
+```
+
+Opens full-screen TUI with:
+
+- **Left pane**: Note list (title + preview, live filter as you type)
+- **Right pane**: Markdown preview of selected note
+- **Keys**:
+  - `↑/↓` / `j/k` — navigate
+  - `Enter` — view full note
+  - `n` — new note
+  - `e` — edit selected
+  - `d` — delete selected (with confirmation)
+  - `p` — toggle pin
+  - `/` — start filtering: type to filter the list live, `Esc`/`Enter` to finish
+  - `q` / `Esc` — quit (or back from view/edit)
+
+### View Mode
+Full markdown render. Keys: `e` to edit, `q`/`Esc` back to list.
+
+### Create/Edit Mode
+Opens external editor via `ctx.ui.editor()` for title and content. On save, persists and returns to list.
+
+## Persistence
+
+- File: `.pi/notes/notes.json` in project root
+- Format:
+```json
+{
+  "notes": [
+    {
+      "id": "uuid",
+      "title": "Architecture decisions",
+      "content": "# Architecture decisions\n\nKey choices...",
+      "createdAt": "2025-01-15T10:30:00.000Z",
+      "updatedAt": "2025-01-15T10:30:00.000Z",
+      "tags": ["architecture", "decision"],
+      "pinned": false
+    }
+  ],
+  "version": 1
+}
+```
+- Auto-saves on every mutation
+- Loads on `session_start`, flushes on `session_shutdown`
+
+## Usage / Examples
+
+```
+> /notes
+# Opens the full-screen TUI (list, view, create, edit, delete)
+
+> /notes "API contract"
+# Quick-add: title is "API contract" (quotes stripped), opens editor for content
+
+> /notes list
+Notes (3):
+1. 📌 API contract — Endpoint specs for v2...
+2. TODO: refactor auth [backend] — Pending work items...
+3. Architecture decisions — Summary of key choices...
+
+> /notes show a1b2c3
+# API contract
+Pinned  |  Tags: none  |  Created: 2025-01-15T10:30:00.000Z  |  Updated: 2025-01-16T09:12:00.000Z
+
+## Endpoints
+...
+
+> /notes search refactor
+Search results (1):
+1. TODO: refactor auth [backend] — Pending work items...
+
+> /notes tag a1b2c3 api
+Added tag "api" to "API contract"
+
+> /notes untag a1b2c3 api
+Removed tag "api" from "API contract"
+
+> /notes pin a1b2c3
+Pinned "API contract"
+
+> /notes unpin a1b2c3
+Unpinned "API contract"
+
+> /notes edit a1b2c3
+# Opens external editors prefilled with the note's current title and content
+Updated note: API contract
+
+> /notes export
+Exported 3 notes to /path/to/project/notes.json
+
+> /notes export backup.json
+Exported 3 notes to /path/to/project/backup.json
+
+> /notes import backup.json
+Imported 2 note(s) from /path/to/project/backup.json (1 already present, skipped)
+
+> /notes rm a1b2c3
+# Confirmation dialog... "Deleted note: API contract"
+```
+
+### Export/Import format
+
+`/notes export` writes the same JSON shape used for persistence. `/notes import` reads a file shaped like `{ "notes": [...], "version": 1 }` and **merges** it into the store: notes whose `id` already exists locally are skipped (existing notes win), new ids are appended.
+
+## Roadmap
+
+See [plan.md](./plan.md) for planned features: linking, templates, and other ideas.