pi-ext

+# pi-ext Work Plan

+

+This document captures all planned work before implementation begins.

+

+---

+

+## Mission 1: Simplify README

+

+Restructure the README into two clear audiences: users who just want to install, and developers who want to hack locally.

+

+### User section (top)

+

+Keep it terse. Show git install first, default branch as alternative. Preserve the filtering example so users who only want a subset of extensions know how to do it.

+

+```bash

+pi install git:github.com/bugabinga/pi-ext@v0.0.3

+```

+

+Or default branch:

+

+```bash

+pi install git:github.com/bugabinga/pi-ext

+```

+

+Keep the `settings.json` filter example with its existing bullet rules.

+

+### Development section (bottom)

+

+Move local checkout instructions here. Add a note about the bun/npm subtlety.

+

+- Clone locally

+- Run `bun install` inside the repo (local paths do not auto-install dependencies)

+- Then either `pi install /absolute/path` or add to `settings.json`

+- Terse note: pi runs `npm install --omit=dev` for git sources; it ignores `bun.lock`. In practice npm 7+ resolves the workspace correctly.

+

+Remove local path examples from the user section.

+

+---

+

+## Mission 2: Inline `ignore` in `llmiterate`

+

+The `llmiterate` extension depends on the `ignore` npm package. Remove it by inlining a minimal gitignore matcher.

+

+### Why

+

+Only `llmiterate` and `diff-review` pull in non-pi runtime dependencies.

+`ignore` is tiny and used for a narrow purpose. Replacing it with a local implementation removes one `node_modules` requirement.

+The `@pierre/*` packages in `diff-review` are large and used for browser UI; they stay.

+

+### Surface area

+

+`watcher.ts` uses two things from the `ignore` package:

+

+- `ignore()` — factory function returning a matcher

+- `matcher.add(source: string)` — adds patterns from `.gitignore`/`.ignore` content

+- `matcher.ignores(path: string)` — checks if a path matches

+

+The watcher feeds multiline strings (file contents) into `add()`, then checks individual file paths with `ignores()`.

+

+### Steps

+

+1. **Verify baseline green**

+ ```bash

+ bun test extensions/llmiterate/__tests__/*.test.ts

+ ```

+

+2. **Add isolated matcher tests**

+ Create `extensions/llmiterate/__tests__/gitignore.test.ts` covering the semantics the watcher relies on:

+ - Comments and blank lines are skipped

+ - `logs/` ignores the directory and anything inside

+ - `*.tmp` ignores files at any depth

+ - `!important.log` negates a previous ignore

+ - `/build/` anchors to the context root

+ - `src/noisy/` ignores the directory and descendants

+ - Multiple patterns from a multiline string

+

+3. **Implement replacement**

+ Create `extensions/llmiterate/gitignore.ts` with a `GitIgnoreMatcher` class:

+ - `add(source: string): this` — parses patterns line by line

+ - `ignores(path: string): boolean` — checks against accumulated patterns

+ - Tracks negation (`!`), directory-only (trailing `/`), and anchoring (leading `/`)

+ - Converts glob patterns to regexes:

+ - `*` → `[^/]*`

+ - `?` → `[^/]`

+ - Unanchored patterns match at any depth

+ - Leading `/` anchors to the context root

+ - Applies patterns in order; negation flips state

+ - Estimated: ~100 lines

+

+4. **Swap dependency in `watcher.ts`**

+ - Remove `import ignore, { type Ignore } from "ignore";`

+ - Add `import { GitIgnoreMatcher } from "./gitignore";`

+ - Replace `ignore()` with `new GitIgnoreMatcher()`

+ - Update `IgnoreContext` type

+

+5. **Remove dependency**

+ - Delete `"ignore": "^7.0.5"` from `extensions/llmiterate/package.json`

+

+6. **Verify all tests pass**

+ ```bash

+ bun test extensions/llmiterate/__tests__/*.test.ts

+ ```

+

+---

+

+## Mission 3: Move pi-ext into dotfiles

+

+Your dotfiles repo (`~/Workspace/dotfiles`) already symlinks `pi/` → `~/.pi`. Add pi-ext as a tracked submodule so it lives under dotfiles control.

+

+### Git config confirmation

+

+Both your personal and work git configs already have:

+

+```ini

+[submodule]

+ recurse = true

+```

+

+This means `git pull` in dotfiles will automatically recurse into submodules and update them to the pinned commit.

+

+### Steps

+

+1. **Add submodule**

+ ```bash

+ cd ~/Workspace/dotfiles

+ git submodule add https://github.com/bugabinga/pi-ext.git pi-ext

+ git config -f .gitmodules submodule.pi-ext.branch trunk

+ git submodule update --init --recursive

+ cd pi-ext

+ git checkout trunk

+ ```

+

+2. **Update settings.json**

+ Edit `~/Workspace/dotfiles/pi/agent/settings.json`:

+

+ ```json

+ {

+ "packages": [

+ {

+ "source": "~/Workspace/dotfiles/pi-ext"

+ }

+ ]

+ }

+ ```

+

+3. **Clean up old paths**

+ - Delete `pi-ext` / `~/Workspace/pi-ext` lines from `desktop.symlinks`

+ - Remove the old `~/Workspace/pi-ext` directory if it still exists

+ - The canonical location becomes `~/Workspace/dotfiles/pi-ext`

+

+4. **Development workflow**

+ ```bash

+ cd ~/Workspace/dotfiles/pi-ext

+ # hack, commit, push from inside the submodule

+

+ # when you want dotfiles to pin the new commit:

+ cd ~/Workspace/dotfiles

+ git add pi-ext

+ git commit -m "update pi-ext"

+ ```

+

+ After `git pull` in dotfiles, the submodule updates automatically.

+ To also pull latest trunk for the submodule:

+ ```bash

+ git pull --recurse-submodules

+ # or

+ git submodule update --remote

+ ```

+

+### Post-update ritual

+

+After pulling dotfiles updates, you may need:

+

+```bash

+cd ~/Workspace/dotfiles/pi-ext && bun install

+```

+

+Consider adding this to a `just update` recipe or similar.

+

+---

+

+## Commit plan

+

+1. `docs: add PLAN.md` (this document)

+2. `docs: simplify README — separate user and dev install sections`

+3. `refactor(llmiterate): inline gitignore matcher, remove ignore dependency`

+4. `chore: move pi-ext into dotfiles as submodule`

+

+---

+

+*Prepared before implementation session.*