jb/harness-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: package Pi extensions as Bun workspaces

Browse Source
This commit is contained in:
jb
2026-09-01 17:24:46 -04:00
parent 90f8090f61
commit 118b5bee06
214 changed files with 19566 additions and 5876 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+52 -62
View File
@@ -9,14 +9,12 @@ Personal [Pi](https://github.com/earendil-works/pi-mono) extensions, skills, glo
- global agent instructions for Pi, Codex, and Claude;
- 34 shared skills under `~/.agents/skills/`;
- the `manage-pi-links` and `nono-profiles` project-only skills under `.pi/skills/`;
- five global Pi extensions under `~/.pi/agent/extensions/`:
- three global Pi extensions under `~/.pi/agent/extensions/`:
- **dictate**: local Linux voice dictation;
- **effort-controls**: `/effort` reasoning selection and `/fast` priority mode;
- **pi-workflow**: persisted, gated feature workflows;
- **prompt-snippets**: per-message prompt rule toggles;
- **update**: `/update` and `--update` support.
- **prompt-snippets**: per-message prompt rule toggles.
The repository also contains `copy-all`, `file-search`, and `subagents` extensions, but the normal manifest does not install them globally. The `pptx`, `stop-slop`, `subagents`, and `xlsx` skills are also intentionally excluded. Archived resources under `__archived/` are never installed. Update `config/pi-links.json` deliberately if that policy changes.
The repository also contains `copy-all`, `file-search`, `interactive-subagents`, `lm-studio`, `native-hooks`, `subagents`, `todo-herdr`, `update`, and the private `workflow` extension, but the normal manifest does not install them globally. The `pptx`, `stop-slop`, `subagents`, and `xlsx` skills are also intentionally excluded. Archived resources under `__archived/` are never installed. Update `config/pi-links.json` deliberately if that policy changes.
## Fresh-machine setup
@@ -27,7 +25,8 @@ The commands below reproduce the normal setup. They assume Linux, a systemd user
Required:
- Git with access to `git.jb.codes`;
- Node.js 22.19 or newer with npm;
- Node.js 22.19 or newer;
- Bun 1.3.14 or newer;
- Pi Coding Agent;
- a configured model provider.
@@ -84,11 +83,11 @@ The linked TypeScript extensions resolve runtime dependencies from this checkout
```bash
cd /srv/data/code/harness-tools
npm ci
npm run typecheck
bun install --frozen-lockfile
bun run typecheck
```
Use `npm ci` after pulling a lockfile change. Node.js must satisfy the version in [`package.json`](package.json).
Use `bun install --frozen-lockfile` after pulling a lockfile change and plain `bun install` only when intentionally updating [`bun.lock`](bun.lock). Node.js and Bun must satisfy the versions in [`package.json`](package.json).
### 4. Install instructions, skills, and extensions
@@ -109,7 +108,7 @@ A successful check currently reports 44 links and zero local package entries. Th
Resolve any reported collision manually instead of deleting it blindly. Run `/reload` in an active Pi session, or restart Pi, after the sync.
Do not also run `pi install /path/to/harness-tools` for the normal setup. That installs the root as a Pi package and applies the broader `package.json` resource globs, which is different from the curated `config/pi-links.json` policy and can duplicate resources. It remains useful for a temporary package-development test in an isolated Pi agent directory.
The repository root is a private Bun workspace and is not installable as a Pi package. Use the curated `config/pi-links.json` policy for live development, or install one independently published `@_jb/pi-*` package. See [Bun workspace packages and Gitea npm publishing](docs/npm-packages.md).
### 5. Verify Pi
@@ -120,44 +119,39 @@ pi
Inside Pi:
1. Run `/reload`.
2. Confirm `/effort`, `/snippets`, `/update`, and `/workflow` are available.
2. Confirm `/effort` and `/snippets` are available.
3. Ask Pi to list its available skills and confirm a shared skill such as `tdd` appears.
4. From this repository, confirm the project-only `manage-pi-links` and `nono-profiles` skills appear.
## Additional Pi packages from Gitea
## Optional Pi packages from Gitea
Two extensions are maintained in separate Gitea repositories rather than `harness-tools`. Install them as Pi-managed Git packages after completing the canonical link sync above. Pi clones each package into its agent directory and installs its package dependencies.
The monorepo contains three optional packages that are not enabled by the curated link policy:
Run these commands from a normal host terminal. A restrictive nono session may intentionally lack the SSH key or agent socket needed to clone private repositories.
- `@_jb/pi-interactive-subagents`;
- `@_jb/pi-native-hooks`;
- `@_jb/pi-todo-herdr`.
### Verify Gitea SSH access
After publishing them, configure the scoped Gitea npm registry and install only the packages you want. Keep the token in the user environment or user-level npm configuration; never commit it:
Both repositories use SSH on port 7722. Confirm access without changing either checkout:
```bash
GIT_TERMINAL_PROMPT=0 git ls-remote \
ssh://git@git.jb.codes:7722/jb/pi-interactive-subagents.git HEAD
GIT_TERMINAL_PROMPT=0 git ls-remote \
ssh://git@git.jb.codes:7722/jb/pi-todo-herdr.git HEAD
```ini
@_jb:registry=https://git.jb.codes/api/packages/jb/npm/
//git.jb.codes/api/packages/jb/npm/:_authToken=${GITEA_NPM_TOKEN}
```
Each command should print a commit hash and `HEAD`. Configure the machine's SSH key and `git.jb.codes` host key before continuing if either command fails.
### Install both packages
```bash
pi install ssh://git@git.jb.codes:7722/jb/pi-interactive-subagents.git
pi install ssh://git@git.jb.codes:7722/jb/pi-todo-herdr.git
pi install npm:@_jb/pi-interactive-subagents
pi install npm:@_jb/pi-native-hooks
pi install npm:@_jb/pi-todo-herdr
pi list
```
Confirm both Gitea URLs appear under `User packages`, then restart Pi or run `/reload`. These package entries are independent of `config/pi-links.json`, so `./scripts/pi-links.mjs check` still reports zero local package entries.
Restart Pi or run `/reload` afterward. These package entries remain independent of `config/pi-links.json`, so `./scripts/pi-links.mjs check` still reports zero local package entries.
Do not globally enable `harness-tools/extensions/subagents` at the same time as `pi-interactive-subagents`. They provide overlapping subagent tools. The curated harness-tools manifest leaves its in-repository implementation disabled for this reason.
### Configure interactive subagents
[`pi-interactive-subagents`](https://git.jb.codes/jb/pi-interactive-subagents) creates asynchronous child Pi sessions in Herdr tabs or tmux panes. It requires one terminal backend:
[`@_jb/pi-interactive-subagents`](extensions/interactive-subagents) creates asynchronous child Pi sessions in Herdr tabs or tmux panes. It requires one terminal backend:
- **Herdr:** install its Pi integration, then launch Pi inside a Herdr-managed pane;
- **tmux:** launch Pi inside tmux when Herdr is unavailable.
@@ -188,11 +182,15 @@ Inside Pi, verify and try the extension:
4. Run `/subagent scout Summarize this repository` from a disposable test checkout.
5. Confirm a Herdr tab or tmux pane opens and the completed result returns to the parent session.
The status widget is enabled by the package's example configuration when no local `config.json` exists. Copy and edit `config.json.example` beside the installed package only when a status override is needed. Treat Pi's managed Git checkout as disposable because package updates may reset it; prefer global or project agent overrides for durable customization.
The status widget is enabled by the package's example configuration when no local `config.json` exists. Copy and edit `config.json.example` beside the installed package only when a status override is needed. Treat Pi's managed package installation as disposable because package updates may reset it; prefer global or project agent overrides for durable customization.
### Configure Native Hooks
[`@_jb/pi-native-hooks`](extensions/native-hooks) coordinates trusted personal diagnostic and verification policies after workspace mutations. Review its [trust model and initialization workflow](extensions/native-hooks/README.md) before use. Preview with `/hooks-init --dry-run`; do not run `/hooks-init --apply` until every destination and executable policy has been reviewed.
### Configure Pi Todo Herdr
[`pi-todo-herdr`](https://git.jb.codes/jb/pi-todo-herdr) provides the `set_tasks`, `update_task`, `rm_task`, `list_task`, and `get_task` tools plus a session-local Pi task widget. Herdr is optional for the tools and widget.
[`@_jb/pi-todo-herdr`](extensions/todo-herdr) provides the `set_tasks`, `patch_tasks`, `rm_task`, `list_task`, and `get_task` tools plus a session-local Pi task widget. Herdr is optional for the tools and widget.
Inside Pi after `/reload`:
@@ -224,41 +222,33 @@ herdr status client
### Update or remove the Gitea packages
Use the same source strings stored by Pi:
```bash
pi update ssh://git@git.jb.codes:7722/jb/pi-interactive-subagents.git
pi update ssh://git@git.jb.codes:7722/jb/pi-todo-herdr.git
```
pi update npm:@_jb/pi-interactive-subagents
pi update npm:@_jb/pi-native-hooks
pi update npm:@_jb/pi-todo-herdr
Remove them with:
```bash
pi remove ssh://git@git.jb.codes:7722/jb/pi-interactive-subagents.git
pi remove ssh://git@git.jb.codes:7722/jb/pi-todo-herdr.git
pi remove npm:@_jb/pi-interactive-subagents
pi remove npm:@_jb/pi-native-hooks
pi remove npm:@_jb/pi-todo-herdr
```
Run `/reload` after an update or removal.
### Optional development checkouts
### Imported source provenance
A Pi-managed package clone is enough for normal use. For source development, use separate durable checkouts so Pi package updates cannot discard work:
The three packages were imported as snapshots of their source repositories' `main` branches. [`config/imported-packages.json`](config/imported-packages.json) records each source and exact commit. Check for upstream movement without changing this checkout:
```bash
mkdir -p /srv/data/repo-store
git clone ssh://git@git.jb.codes:7722/jb/pi-interactive-subagents.git \
/srv/data/repo-store/pi-interactive-subagents
git clone ssh://git@git.jb.codes:7722/jb/pi-todo-herdr.git \
/srv/data/repo-store/pi-todo-herdr
npm ci --prefix /srv/data/repo-store/pi-interactive-subagents
npm test --prefix /srv/data/repo-store/pi-interactive-subagents
npm ci --prefix /srv/data/repo-store/pi-todo-herdr
npm run typecheck --prefix /srv/data/repo-store/pi-todo-herdr
npm test --prefix /srv/data/repo-store/pi-todo-herdr
bun run imports:check
```
Both repositories are separate projects. Keep their changes and releases out of the `harness-tools` checkout.
Stage fresh snapshots outside the repository for review and reconciliation:
```bash
bun scripts/import-package-snapshots.mjs stage all --output /tmp/harness-tools-imports
```
The stage command deliberately does not overwrite monorepo files. Review upstream changes, preserve the scoped package manifests and catalog dependencies, run the full validation suite, and then update the recorded commit.
## Companion tools used by installed skills
@@ -475,11 +465,11 @@ After pulling repository changes:
```bash
cd /srv/data/code/harness-tools
git pull --rebase
npm ci
bun install --frozen-lockfile
./scripts/pi-links.mjs sync --dry-run
./scripts/pi-links.mjs sync
./scripts/pi-links.mjs check
npm run typecheck
bun run typecheck
```
Run `/reload` after skill, extension, instruction, or separately installed Gitea package changes. Re-run `./services/dictate/install.sh` when Dictate's host service or protocol changes.
@@ -497,9 +487,9 @@ Only run `./scripts/pi-links.mjs prune` after reviewing every removal. The manag
Extensions are TypeScript modules loaded directly by Pi; no build step is required.
```bash
npm ci
npm run typecheck
npm test
bun install --frozen-lockfile
bun run typecheck
bun run test
```
For a one-off extension development run:
@@ -514,7 +504,7 @@ pi -e ./extensions/update
```text
config/ Installation and launcher manifests
docs/ Usage guides, plans, and ADRs
extensions/ Pi extensions
extensions/ Bun workspace packages for Pi extensions and shared runtime code
profiles/nono/ Repository-managed nono profiles
scripts/ Link manager and sandbox launch helpers
services/ Host-side services used by extensions