# 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 `@jbcode/pi-interactive-subagents`, `@jbcode/pi-native-hooks`, and `@jbcode/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 `@jbcode` scope:

```ini
@jbcode: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 `@jbcode/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.

`__archived/extensions/workflow` and `__archived/extensions/_workflows` are historical reference, outside active workspaces, and must not be published. [ADR 0007](adr/0007-archive-legacy-workflows-05SEP2026.md) records their archival and supersedes ADR 0006's pilot-before-retirement prerequisite; new development uses the `develop-workflow` skill.

## Install with Pi

After configuring the same scope and token in the npm configuration visible to Pi, install the currently deployed release set with exact version pins:

```bash
pi install npm:@jbcode/pi-fast-browser@0.1.0
pi install npm:@jbcode/pi-dictate@0.2.0
pi install npm:@jbcode/pi-effort-controls@0.1.0
pi install npm:@jbcode/pi-prompt-snippets@0.1.0
pi install npm:@jbcode/pi-interactive-subagents@3.7.4
pi install npm:@jbcode/pi-todo-herdr@0.2.5
```

Pi installs runtime dependencies from the same scoped registry. `config/pi-links.json` deliberately exposes no extension symlinks, preventing duplicate local and published copies.

`@jbcode/pi-bash-cwd` is currently source-only and is not part of the deployed release set above. It can be packed and published through the same workspace process when a Pi 0.84.x installation needs the alternate-cwd compatibility override.