4 +title: Built Extension Packages
5 +spec: PX-SPEC-DZLVGRW4
11 +Pi loads every extension from a self-contained generated package under `dist/<extension>` produced by Rolldown from the extension's own source.
12 +The repository root stops being a Pi package.
13 +Development builds are on-demand, focused, atomic, and reloadable.
15 +Verified current state: root `package.json` carries `pi.extensions` globbing `extensions/*/index.ts`; user settings list `~/Workspace/pi-ext` as a package; Pi loads TypeScript through jiti; no bundler dependency; no `dist/`.
19 +Order is delivery value; each behavior crosses build, manifest, settings, and verification.
23 + b1["1. ultra loads from dist/ultra"] --> b2["2. Focused rebuild replaces one package atomically"]
24 + b1 --> b3["3. the-system bundles third-party deps"]
25 + b2 --> b4["4. Whole collection loads from explicit dist entries; root not a package"]
27 + b4 --> b5["5. Every package loads relocated with zero unexpected diagnostics"]
30 +1. Pilot `extensions/ultra`: Rolldown build emits `dist/ultra/` with `package.json`, entry chunk, package-private lazy chunks for `implementation.ts`, worker chunk for `dynamic-validator-worker.ts`, copied `prompts/`, and a generated `pi` manifest declaring only the entry and prompts.
31 + User settings gain one explicit local package entry for `dist/ultra`; the root package entry stays until behavior 4.
32 + Proof: Pi with only `dist/ultra` configured runs `run_workflow` and dynamic validation.
33 +2. Build task `//:build-ext <name>` (Mise → root npm script → Node build driver) writes into a staging directory, then swaps into `dist/<name>` only after all chunks and resources exist.
34 + Interrupted builds leave the previous package intact.
35 + Content-addressed chunk names let a loaded extension finish lazy imports across a swap; stale chunks are pruned on the next successful build.
36 + Development build keeps sourcemaps and no minification.
37 +3. Pilot `extensions/the-system`: bundle `mermaid`, `unified`, `rehype-*`, `remark-*`, `minisearch`, `dagre`, `yaml` into package-private chunks; copy `skills/`; declare `pi.skills` explicitly; keep Node built-ins, `@earendil-works/*`, and `typebox` external.
38 + Any dependency left external requires a recorded incompatibility note in the build config.
39 + Proof: `dist/the-system` renders `/system view` and `/system book` outside the checkout with no `node_modules` ancestor.
40 +4. Extend the build driver to all extensions; `pi.extensions`, `pi.skills`, `pi.prompts`, `pi.themes` removed from root `package.json`; `scripts/extensions.mjs` static check inverted to forbid root Pi keys and require per-extension declared resources.
41 + Codegen adds a settings snippet or `//:settings-entries` task that prints the explicit `dist/<name>` package list; the human applies it to `~/.pi/agent/settings.json`.
42 + Resources: `firefox-bidi/skills`, `pfui/skills`, `mockup/guidance` (internal, not exposed), `strata/assets`, executable helpers from `pi-ext-executable` targets.
43 +5. Relocation gate: copy each `dist/<name>` to a temp directory without ancestors, load through Pi on Node, assert zero extension errors, working lazy first use, worker start, and manifest-declared resources only.
44 + Run as `//:verify-packages`; per-extension via `//extensions/<name>:verify-package`.
50 + src["extensions/name/*.ts + resources"] --> driver["scripts/build/driver (Rolldown API)"]
51 + policy["scripts/build/policy: externals, resources, entries"] --> driver
52 + driver --> staging["dist/.staging/name"] -->|atomic swap| pkg["dist/name"]
53 + pkg --> manifest["dist/name/package.json pi.*"]
54 + pkg --> settings["user settings packages[]"]
55 + pkg --> verify["scripts/verify-packages: relocate + Pi load"]
58 +Touched: `package.json` (add `rolldown` devDependency, remove `pi.*`), `mise.toml` (`build-ext`, `build-all`, `verify-packages`), `scripts/build/*`, `scripts/extensions.mjs` static check, each `extensions/<name>/package.json` (declared resources, `main` stays source for tests), `tsconfig.json` include for build scripts, `.gitignore` for `dist/`.
62 +- Pi's jiti importer stays; packages are plain ESM JavaScript that jiti passes through.
63 +- No lifecycle scripts in generated `package.json`.
64 +- Generated manifest derives from extension `package.json` declarations; the source manifest remains the single authority.
65 +- `extensions/*/package.json` keep `main: index.ts` for source tests; generated packages set their own `main`.
66 +- Watcher (optional) calls the same build; no Pi protocol.
70 +- [ ] `dist/ultra` alone runs a workflow with a dynamic extension after relocation.
71 +- [ ] Interrupting `build-ext` mid-write leaves the previous `dist/<name>` loadable.
72 +- [ ] `dist/the-system` has no external third-party import and renders Markdown with Mermaid outside the checkout.
73 +- [ ] Root `package.json` has no `pi` key; static check fails if it returns.
74 +- [ ] `verify-packages` passes for all extensions and for the full collection with no identity, tool, command, flag, or resource conflicts.
75 +- [ ] Focused `//extensions/<name>:check` builds only that extension.