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

- - `**` matches any number of directory levels (`a/**/b`)

- - Character classes `[abc]` match single chars

- - Escaped specials (`\#`, `\!`, `\ `, `\*`) are treated as literals

- - Trailing-slash semantics: `build/` ignores only directories; `build` ignores files and directories

- - Multiple negations in sequence (`*.log` → `!a.log` → `!b.log`)

- - Nested directory patterns (`node_modules/**/package.json`)

- - Edge: pattern `*` does NOT match path separator (`a/b` should not match `*`)

-

-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: ~120 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.*