repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: add PLAN.md

9c2fe8793a641f9366a18e6bebb919dfdc4d9a0e

Oliver Krylow <o.krylow@isp-insoft.de> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

PLAN.md

Added
new file mode 100644
1 +# pi-ext Work Plan
3 +This document captures all planned work before implementation begins.
5 +---
7 +## Mission 1: Simplify README
9 +Restructure the README into two clear audiences: users who just want to install, and developers who want to hack locally.
11 +### User section (top)
13 +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.
15 +```bash
16 +pi install git:github.com/bugabinga/pi-ext@v0.0.3
17 +```
19 +Or default branch:
21 +```bash
22 +pi install git:github.com/bugabinga/pi-ext
23 +```
25 +Keep the `settings.json` filter example with its existing bullet rules.
27 +### Development section (bottom)
29 +Move local checkout instructions here. Add a note about the bun/npm subtlety.
31 +- Clone locally
32 +- Run `bun install` inside the repo (local paths do not auto-install dependencies)
33 +- Then either `pi install /absolute/path` or add to `settings.json`
34 +- Terse note: pi runs `npm install --omit=dev` for git sources; it ignores `bun.lock`. In practice npm 7+ resolves the workspace correctly.
36 +Remove local path examples from the user section.
38 +---
40 +## Mission 2: Inline `ignore` in `llmiterate`
42 +The `llmiterate` extension depends on the `ignore` npm package. Remove it by inlining a minimal gitignore matcher.
44 +### Why
46 +Only `llmiterate` and `diff-review` pull in non-pi runtime dependencies.
47 +`ignore` is tiny and used for a narrow purpose. Replacing it with a local implementation removes one `node_modules` requirement.
48 +The `@pierre/*` packages in `diff-review` are large and used for browser UI; they stay.
50 +### Surface area
52 +`watcher.ts` uses two things from the `ignore` package:
54 +- `ignore()` — factory function returning a matcher
55 +- `matcher.add(source: string)` — adds patterns from `.gitignore`/`.ignore` content
56 +- `matcher.ignores(path: string)` — checks if a path matches
58 +The watcher feeds multiline strings (file contents) into `add()`, then checks individual file paths with `ignores()`.
60 +### Steps
62 +1. **Verify baseline green**
63 + ```bash
64 + bun test extensions/llmiterate/__tests__/*.test.ts
65 + ```
67 +2. **Add isolated matcher tests**
68 + Create `extensions/llmiterate/__tests__/gitignore.test.ts` covering the semantics the watcher relies on:
69 + - Comments and blank lines are skipped
70 + - `logs/` ignores the directory and anything inside
71 + - `*.tmp` ignores files at any depth
72 + - `!important.log` negates a previous ignore
73 + - `/build/` anchors to the context root
74 + - `src/noisy/` ignores the directory and descendants
75 + - Multiple patterns from a multiline string
77 +3. **Implement replacement**
78 + Create `extensions/llmiterate/gitignore.ts` with a `GitIgnoreMatcher` class:
79 + - `add(source: string): this` — parses patterns line by line
80 + - `ignores(path: string): boolean` — checks against accumulated patterns
81 + - Tracks negation (`!`), directory-only (trailing `/`), and anchoring (leading `/`)
82 + - Converts glob patterns to regexes:
83 + - `*` → `[^/]*`
84 + - `?` → `[^/]`
85 + - Unanchored patterns match at any depth
86 + - Leading `/` anchors to the context root
87 + - Applies patterns in order; negation flips state
88 + - Estimated: ~100 lines
90 +4. **Swap dependency in `watcher.ts`**
91 + - Remove `import ignore, { type Ignore } from "ignore";`
92 + - Add `import { GitIgnoreMatcher } from "./gitignore";`
93 + - Replace `ignore()` with `new GitIgnoreMatcher()`
94 + - Update `IgnoreContext` type
96 +5. **Remove dependency**
97 + - Delete `"ignore": "^7.0.5"` from `extensions/llmiterate/package.json`
99 +6. **Verify all tests pass**
100 + ```bash
101 + bun test extensions/llmiterate/__tests__/*.test.ts
102 + ```
104 +---
106 +## Mission 3: Move pi-ext into dotfiles
108 +Your dotfiles repo (`~/Workspace/dotfiles`) already symlinks `pi/` → `~/.pi`. Add pi-ext as a tracked submodule so it lives under dotfiles control.
110 +### Git config confirmation
112 +Both your personal and work git configs already have:
114 +```ini
115 +[submodule]
116 + recurse = true
117 +```
119 +This means `git pull` in dotfiles will automatically recurse into submodules and update them to the pinned commit.
121 +### Steps
123 +1. **Add submodule**
124 + ```bash
125 + cd ~/Workspace/dotfiles
126 + git submodule add https://github.com/bugabinga/pi-ext.git pi-ext
127 + git config -f .gitmodules submodule.pi-ext.branch trunk
128 + git submodule update --init --recursive
129 + cd pi-ext
130 + git checkout trunk
131 + ```
133 +2. **Update settings.json**
134 + Edit `~/Workspace/dotfiles/pi/agent/settings.json`:
136 + ```json
138 + "packages": [
140 + "source": "~/Workspace/dotfiles/pi-ext"
144 + ```
146 +3. **Clean up old paths**
147 + - Delete `pi-ext` / `~/Workspace/pi-ext` lines from `desktop.symlinks`
148 + - Remove the old `~/Workspace/pi-ext` directory if it still exists
149 + - The canonical location becomes `~/Workspace/dotfiles/pi-ext`
151 +4. **Development workflow**
152 + ```bash
153 + cd ~/Workspace/dotfiles/pi-ext
154 + # hack, commit, push from inside the submodule
156 + # when you want dotfiles to pin the new commit:
157 + cd ~/Workspace/dotfiles
158 + git add pi-ext
159 + git commit -m "update pi-ext"
160 + ```
162 + After `git pull` in dotfiles, the submodule updates automatically.
163 + To also pull latest trunk for the submodule:
164 + ```bash
165 + git pull --recurse-submodules
166 + # or
167 + git submodule update --remote
168 + ```
170 +### Post-update ritual
172 +After pulling dotfiles updates, you may need:
174 +```bash
175 +cd ~/Workspace/dotfiles/pi-ext && bun install
176 +```
178 +Consider adding this to a `just update` recipe or similar.
180 +---
182 +## Commit plan
184 +1. `docs: add PLAN.md` (this document)
185 +2. `docs: simplify README — separate user and dev install sections`
186 +3. `refactor(llmiterate): inline gitignore matcher, remove ignore dependency`
187 +4. `chore: move pi-ext into dotfiles as submodule`
189 +---
191 +*Prepared before implementation session.*