harness-tools/docs/adr/0004-bun-extension-workspaces-01SEP2026.md

Package Pi extensions as a Bun workspace catalog

Decision

Keep extension sources under extensions/* and make each maintained extension directory a Bun workspace with its own package manifest. Use the @jbcode/pi-* namespace, a root Bun catalog for external dependency versions, and workspace:^ for repository-owned libraries. The repository root is private and is no longer itself a Pi package.

Publish packages to the jb owner endpoint of the Gitea npm registry. Repository configuration maps @jbcode to https://git.jb.codes/api/packages/jb/npm/; credentials remain in the user environment or user-level npm configuration and are never committed. Gitea rejected the initially proposed underscore-prefixed scope as an invalid package name, so the valid @jbcode scope is part of the registry contract.

extensions/shared is the publishable @jbcode/pi-shared library. Extensions that import it declare a normal runtime dependency so Pi's production package installation receives the required code.

extensions/_workflows is reference code, not a package or publishable extension. @jbcode/pi-workflow remains a private workspace until the required reference runtime is merged under extensions/workflow; this prevents publishing two workflow packages or publishing an incomplete package.

The existing config/pi-links.json policy remains the authority for live-development exposure. Package boundaries and publication do not automatically enable extensions globally.

Consequences

• Bun owns dependency installation and bun.lock; package-lock.json is removed.
• Catalog and workspace protocols require bun publish or bun pm pack before npm publication so concrete versions are written into package metadata.
• Shared libraries must be published before extensions that depend on the same new version.
• Pi packages continue shipping TypeScript source because Pi loads extension entrypoints directly.
• The workflow merge is an explicit blocker for its first release.