feat: package Pi extensions as Bun workspaces

2026-09-01 17:24:46 -04:00
parent 90f8090f61
commit 118b5bee06
214 changed files with 19566 additions and 5876 deletions
@@ -0,0 +1,59 @@
+# Bun workspace packages and Gitea npm publishing
+
+The repository uses Bun workspaces under `extensions/*`. External dependency versions live in the root `package.json` catalog; repository-owned dependencies use `workspace:^`.
+
+Publishable packages include the repository-native extensions plus the imported `@_jb/pi-interactive-subagents`, `@_jb/pi-native-hooks`, and `@_jb/pi-todo-herdr` snapshots. `config/imported-packages.json` records their source `main` commits; use `bun run imports:check` to detect upstream movement.
+
+## Install and verify
+
+```bash
+bun install --frozen-lockfile
+bun run typecheck
+bun run test
+```
+
+Use plain `bun install` when intentionally updating `bun.lock`.
+
+## Registry configuration
+
+The tracked `.npmrc` routes only the `@_jb` scope:
+
+```ini
+@_jb:registry=https://git.jb.codes/api/packages/jb/npm/
+```
+
+Configure a Gitea personal access token with package permissions outside the repository:
+
+```ini
+//git.jb.codes/api/packages/jb/npm/:_authToken=${GITEA_NPM_TOKEN}
+```
+
+The token line may live in `~/.npmrc`, or `GITEA_NPM_TOKEN` may be supplied by the publishing environment. Never commit a token.
+
+## Pack and publish
+
+Bun must resolve `catalog:` and `workspace:` references before publication. From a publishable workspace:
+
+```bash
+cd extensions/shared
+bun pm pack --destination ../../dist
+bun publish
+```
+
+Publish `@_jb/pi-shared` before a new version of any extension that depends on it. Gitea rejects republishing an existing name/version, so bump the changed package version first.
+
+`extensions/workflow` is intentionally private until the `_workflows` reference dependencies are merged into that package. `extensions/_workflows` must not be published.
+
+## Install with Pi
+
+After configuring the same scope and token in the npm configuration visible to Pi:
+
+```bash
+pi install npm:@_jb/pi-dictate
+pi install npm:@_jb/pi-file-search
+pi install npm:@_jb/pi-interactive-subagents
+pi install npm:@_jb/pi-native-hooks
+pi install npm:@_jb/pi-todo-herdr
+```
+
+Pi installs runtime dependencies from the same scoped registry. The repository's symlink-based development exposure remains controlled separately by `config/pi-links.json`.