repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

system: plan the Pi extension architecture as five ordered plans

dd8ce3aa5ff97d2cc3cf056fd5bb050fcc7a1e42

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

PX-SPEC-DZLVGRW4 decomposes into built packages, release publication, layered tests with an owned fixture, verification cadence with a compatibility matrix, and test-quality tooling. PX-PLAN-RMJ8BIOX is approved; the rest stay draft.

Changed files (5)

.system/plans/PX-PLAN-IRCFFLM3-test-quality-tooling/index.md

Added
new file mode 100644
1 +---
2 +id: PX-PLAN-IRCFFLM3
3 +type: plan
4 +title: Test Quality Tooling
5 +spec: PX-SPEC-DZLVGRW4
6 +status: draft
7 +depends_on:
8 + - PX-PLAN-XQFSKHHG
9 +---
11 +## Outcome
13 +Coverage, property testing, mutation testing, snapshot discipline, and fuzzing are available as non-gating, author-driven tools with per-extension reporting.
15 +Verified current state: `@vitest/coverage-istanbul` installed but no coverage task; no property, mutation, or fuzz tooling.
17 +## Behaviors
19 +```mermaid
20 +flowchart TB
21 + q1["1. Per-extension coverage report with unimported files"] --> q2["2. Seeded property tests in unit layer"]
22 + q2 --> q3["3. Selective mutation runs with cache"]
23 + q1 --> q4["4. Snapshot policy enforced"]
24 + q2 --> q5["5. Fuzz harness for hostile-input boundaries"]
25 +```
27 +1. `//:coverage` and `//extensions/<name>:coverage` run the `unit` and `contract` projects with `all: true` scoped to owned production files, reporting line, branch, function per extension; provider chosen after timing V8 vs Istanbul on the full suite and recorded in the task description.
28 +2. Add `fast-check` as devDependency; `test/property.ts` supplies a seeded runner that records seed and counterexample on failure and stores minimal cases under `__tests__/regressions/`.
29 + First targets: `the-system` frontmatter and Markdown normalization, `nushell` argument rendering, `web` URL and path safety, `strata` state machine.
30 +3. `//extensions/<name>:mutate <file|range>` via Stryker with Vitest runner, incremental cache per extension invalidated by source and test hashes; `//:mutate-all` optional report; never in hooks or CI.
31 +4. Snapshot rules: inline or file snapshots only for normalized rendered output; a lint test rejects snapshots containing absolute paths, timestamps, IDs, or bundle content; updates require an explicit `--update` task.
32 +5. `//extensions/<name>:fuzz <target>` wraps a coverage-guided runner for parsers exposed to hostile input (`web` fetch parsing, `the-system` document parsing); findings minimized into deterministic regression tests.
34 +## Structure
36 +```mermaid
37 +flowchart LR
38 + unit["unit project"] --> cov["coverage per extension"]
39 + prop["test/property seeded runner"] --> unit
40 + prop --> reg["__tests__/regressions"]
41 + mut["Stryker per-extension cache"] --> unit
42 + fuzz["fuzz runner"] --> reg
43 + snap["snapshot lint"] --> unit
44 +```
46 +Touched: `package.json` (fast-check, Stryker, fuzz runner devDependencies), `vitest.config.ts` coverage block, `test/property.ts`, `test/snapshot-lint.test.ts`, `mise.toml` and `extensions/*/mise.toml` (`coverage`, `mutate`, `fuzz`, `snapshot-update`), `stryker.config.*` per extension template.
48 +## Constraints
50 +- No percentage gate; coverage guides investigation.
51 +- Mutation targets pure unit-testable code only.
52 +- Long fuzz campaigns run manually or on a schedule, never in hooks or normal CI.
54 +## Verification
56 +- [ ] Coverage report lists unimported owned files and per-extension line, branch, function numbers.
57 +- [ ] A failing property test prints a replay seed and yields a stored minimal regression case.
58 +- [ ] Repeated mutation run on unchanged code uses the cache; a source change invalidates it.
59 +- [ ] Snapshot lint fails on a snapshot containing an absolute path.
60 +- [ ] Fuzz run on a target completes and any finding lands as a normal test.

.system/plans/PX-PLAN-RMJ8BIOX-built-extension-packages/index.md

Added
new file mode 100644
1 +---
2 +id: PX-PLAN-RMJ8BIOX
3 +type: plan
4 +title: Built Extension Packages
5 +spec: PX-SPEC-DZLVGRW4
6 +status: approved
7 +---
9 +## Outcome
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/`.
17 +## Behaviors
19 +Order is delivery value; each behavior crosses build, manifest, settings, and verification.
21 +```mermaid
22 +flowchart TB
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"]
26 + b3 --> b4
27 + b4 --> b5["5. Every package loads relocated with zero unexpected diagnostics"]
28 +```
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`.
46 +## Module structure
48 +```mermaid
49 +flowchart LR
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"]
56 +```
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/`.
60 +## Constraints
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.
68 +## Verification
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.

.system/plans/PX-PLAN-TXNM7OUB-verification-cadence-and-compatibility-matrix/index.md

Added
new file mode 100644
1 +---
2 +id: PX-PLAN-TXNM7OUB
3 +type: plan
4 +title: Verification Cadence and Compatibility Matrix
5 +spec: PX-SPEC-DZLVGRW4
6 +status: draft
7 +depends_on:
8 + - PX-PLAN-_BUERPCN
9 + - PX-PLAN-XQFSKHHG
10 +---
12 +## Outcome
14 +Hooks, normal CI, and release CI each run the checks matching their cost budget.
15 +Release artifacts are verified across a Pi, Node, and OS matrix that yields an explicit minimum supported Pi version.
17 +Verified current state: pre-commit and pre-push both run `check` + `lint` repository-wide; `.ci/ci.kdl` runs `check`, `lint`, `test`, `e2e` on push to `trunk` in a Playwright image; Pi pinned at 0.87.0.
19 +## Behaviors
21 +```mermaid
22 +flowchart TB
23 + v1["1. Hooks scope to changed extensions"] --> v2["2. Normal CI adds release build + package verification"]
24 + v2 --> v3["3. Release CI runs matrix on snapshot"]
25 + v3 --> v4["4. Minimum Pi version recorded and enforced"]
26 +```
28 +1. `pre-commit`: changed-scope lint and focused typecheck (deterministic, offline); `pre-push`: full `check` and `unit` + `contract` projects.
29 + Hook tasks derive scope from `git diff --name-only`; unchanged extensions are skipped.
30 +2. `.ci/ci.kdl`: `check`, `lint`, one `//:test`, `build-all --release`, `packages` project on current Pi, native and UI suites.
31 +3. `.ci/release.kdl` on `vX.Y.Z` tags: restore snapshot, run `packages` project across Pi versions × Node LTS/current × Linux, Windows, macOS where Luci provides runners; missing OS runners are reported as gaps, not silently passed.
32 + Initial Pi range starts broad (several minor versions back) and narrows empirically.
33 +4. Minimum supported Pi version lives in extension source manifests as the `peerDependencies` range and in the root `package.json`; a check fails when the matrix result and the declared range disagree.
35 +## Gate structure
37 +```mermaid
38 +flowchart LR
39 + commit["pre-commit: changed lint + focused tsc"] --> push["pre-push: check + unit + contract"]
40 + push --> ci["ci.kdl: full static + test + release build + current Pi packages + native + UI"]
41 + ci --> release["release.kdl: matrix over snapshot"]
42 + release --> min["declared minimum Pi"]
43 +```
45 +Touched: `mise.toml` (`pre-commit`, `pre-push`, `ci`, `release-ci`, changed-scope helper task), `.ci/ci.kdl`, `.ci/release.kdl`, `scripts/scope.ts`, `package.json` and `extensions/*/package.json` version ranges, `scripts/extensions.mjs` compatibility check.
47 +## Constraints
49 +- Hooks never install browsers, run matrices, publish, instrument coverage, or run mutation and fuzz campaigns.
50 +- Hook management stays through `mise generate git-pre-commit`.
51 +- Luci job definitions delegate to Mise tasks; no logic in KDL beyond environment setup.
53 +## Verification
55 +- [ ] Committing a change in one extension runs lint and typecheck for that extension only.
56 +- [ ] Pushing runs complete static checks and source tests without browser installs.
57 +- [ ] `ci.kdl` run includes release build and current-Pi package verification.
58 +- [ ] Release job output lists pass/fail per Pi × Node × OS cell and derived minimum.
59 +- [ ] Declared Pi range mismatch with matrix results fails `check`.

.system/plans/PX-PLAN-XQFSKHHG-layered-test-architecture-and-owned-fixture/index.md

Added
new file mode 100644
1 +---
2 +id: PX-PLAN-XQFSKHHG
3 +type: plan
4 +title: Layered Test Architecture and Owned Fixture
5 +spec: PX-SPEC-DZLVGRW4
6 +status: draft
7 +depends_on:
8 + - PX-PLAN-RMJ8BIOX
9 +---
11 +## Outcome
13 +Tests are separated by guarantee: unit, Pi contract, native integration, generated package, UI acceptance.
14 +A repository-owned fixture replaces the text-patched `@marcfargas/pi-test-harness`.
15 +One Vitest coordinator runs all source layers with required isolation; TypeScript checking covers every maintained file.
17 +Verified current state: `scripts/patch_pi_test_harness.mjs` rewrites installed harness files at install; 37 extensions have `__tests__/harness.test.ts`; `test/harness.ts` wraps the harness; `vitest.config.ts` has four projects; `tsconfig.json` excludes tests, benches, scripts, and `the-system/index.ts`.
19 +## Behaviors
21 +```mermaid
22 +flowchart TB
23 + t1["1. Owned fixture runs ultra contract test unpatched"] --> t2["2. All harness tests migrate; patch script deleted"]
24 + t2 --> t3["3. Layer projects in one Vitest coordinator"]
25 + t3 --> t4["4. Generated-package project runs snapshots outside checkout"]
26 + t3 --> t5["5. Complete typecheck; focused check per extension"]
27 + t4 --> t6["6. UI acceptance runs against generated browser artifacts"]
28 +```
30 +1. `test/fixture/` exposes `createPiSession` built on public `createAgentSession`, `SessionManager.inMemory`, `ModelRuntime`, and a deterministic scripted provider; owns temp dirs, env, sockets, timers, shutdown; rejects on any unexpected extension or async error.
31 + `extensions/ultra/__tests__/harness.test.ts` becomes `contract.test.ts` on the fixture.
32 +2. Migrate remaining `harness.test.ts` files; remove the harness devDependency from every extension manifest, `test/harness.ts`, `scripts/patch_pi_test_harness.mjs`, and the install step; static check requires `__tests__/contract.test.ts`.
33 +3. `vitest.config.ts` projects by guarantee: `unit` (isolate false, workers), `contract` (isolate true), `native` (isolate true, one worker, per-file process env), `web`, `strata` retained as native members; `validator` folds into `native`.
34 + Property tests live in `unit` with seeded runners and retained regression cases.
35 +4. `packages` project: for each `dist/<name>` snapshot in a temp root, install an independent Pi version, load, assert manifests, resources, lazy first use, workers, allowed externals, no workspace leakage; one composite run for the complete collection.
36 + Runs only when `dist` exists; `//:verify-packages` from the packages plan becomes this project.
37 +5. `tsconfig.json` includes tests, benches, fixtures, workers, browser entrypoints, build and codegen TypeScript; per-extension `tsconfig.json` extends root and includes shared `test/` inputs; `//extensions/<name>:check` runs focused `tsc -p`; root `//:check` runs the union once.
38 + Convert remaining `.mjs` automation to TypeScript unless it bootstraps the build.
39 +6. Playwright suites (`mockup`, `strata`, `the-system`, `chrome-cdp`, `klaus`) serve generated browser assets from `dist/<name>` rather than source.
41 +## Fixture structure
43 +```mermaid
44 +classDiagram
45 + PiSession --> ScriptedProvider : streams
46 + PiSession --> ResourceOwner : owns
47 + PiSession --> ErrorSink : fails on
48 + ContractTest --> PiSession : loads entrypoint
49 + PackageTest --> PiSession : loads dist snapshot
50 +```
52 +Touched: `test/fixture/*`, `test/harness.ts` (removed), `scripts/patch_pi_test_harness.mjs` (removed), `mise.toml` install task, `vitest.config.ts`, `tsconfig.json`, `extensions/*/tsconfig.json`, `extensions/*/__tests__/*`, `extensions/*/package.json`, `scripts/extensions.mjs` static check, `extensions/*/playwright.config.ts`.
54 +## Constraints
56 +- No private Pi properties, no `as any` reach into agent internals; if the public API lacks a hook, the fixture narrows scope rather than patching.
57 +- Concurrent sessions in one process share `process.env`; tests needing distinct env run in `native` with process isolation.
58 +- Snapshots normalize volatile paths, timestamps, identifiers.
60 +## Verification
62 +- [ ] `mise run //:install` performs no dependency patching.
63 +- [ ] No extension depends on `@marcfargas/pi-test-harness`.
64 +- [ ] `//:test` runs one coordinator with layered projects; contract and native retain isolation.
65 +- [ ] `packages` project passes for every extension and the composed collection.
66 +- [ ] `tsc` covers all maintained TypeScript; `//extensions/ultra:check` typechecks only ultra plus shared inputs.
67 +- [ ] UI acceptance loads assets from `dist`.

.system/plans/PX-PLAN-_BUERPCN-release-build-and-verified-publication/index.md

Added
new file mode 100644
1 +---
2 +id: PX-PLAN-_BUERPCN
3 +type: plan
4 +title: Release Build and Verified Publication
5 +spec: PX-SPEC-DZLVGRW4
6 +status: draft
7 +depends_on:
8 + - PX-PLAN-RMJ8BIOX
9 +---
11 +## Outcome
13 +A release build produces the same package boundary as the development build, is verified as immutable bytes, and only those bytes are published to npm and Git for explicitly selected extensions.
14 +Consumers install without source or toolchain.
16 +Verified current state: `//:publish` is Git-only; release commits README, CHANGELOG, `package.json`, lockfile; version lives in root `package.json`; extension packages are `private: true` without versions.
18 +## Behaviors
20 +```mermaid
21 +flowchart TB
22 + r1["1. Release build of ultra behaves identically to dev build"] --> r2["2. Snapshot digest gates publication"]
23 + r2 --> r3["3. Selected extensions publish to npm"]
24 + r2 --> r4["4. Git distribution branch carries built packages"]
25 + r3 --> r5["5. Consumer install smoke without checkout"]
26 + r4 --> r5
27 +```
29 +1. `build-ext --release` emits into the same `dist/<name>` with minification and no sourcemaps; chunk boundaries, externals, manifest, and resources are asserted equal to a dev build by a structural diff test.
30 + Reload of a release package after a dev package shows no behavior change in the contract suite.
31 +2. `//:release-snapshot` copies `dist/<selected>` into an immutable snapshot directory keyed by content digest, runs `verify-packages` on the snapshot, and records digests in a release manifest file.
32 + `//:publish` refuses when the current `dist` digest differs from the manifest.
33 +3. Publication eligibility is a per-extension declaration (`publishConfig` or `pi-ext.publish: true` in the source `package.json`); private stays default.
34 + npm publish packs the snapshot directory; generated `package.json` gets the root version, the public name, and no scripts.
35 +4. Git channel: a `release/<version>` tag or `dist` branch containing only built packages so `pi install git:…/dist/<name>` works.
36 +5. Consumer smoke: temp directory, independently installed Pi, `pi install` from the npm tarball and from Git, load, run one tool per extension.
38 +## Module structure
40 +```mermaid
41 +flowchart LR
42 + build["scripts/build driver --release"] --> dist["dist/name"]
43 + dist --> snap["scripts/release/snapshot: digest + manifest"]
44 + snap --> gate{"digest match?"}
45 + gate -->|yes| npm["npm publish snapshot"]
46 + gate -->|yes| git["Git dist tag"]
47 + gate -->|no| reject["reject"]
48 + select["per-extension publish declaration"] --> snap
49 +```
51 +Touched: `scripts/build/*` (release mode), `scripts/release/*`, `scripts/extensions.mjs` (`publish`, `release-prepare`), `mise.toml` (`release-snapshot`, `publish`), `extensions/<name>/package.json` (publish declaration, public name), `.ci/*.kdl` later plan.
53 +## Constraints
55 +- Root `package.json` version remains the single version source; generated manifests copy it at build time.
56 +- Compatibility metadata (`peerDependencies` on Pi) is authored once in the extension source manifest.
57 +- Release verification uses the snapshot, never a rebuilt `dist`.
59 +## Verification
61 +- [ ] Structural diff between dev and release builds shows only sourcemap and minification differences.
62 +- [ ] Publish with a modified `dist` after snapshot is rejected with a digest mismatch.
63 +- [ ] npm pack contents equal the snapshot byte-for-byte.
64 +- [ ] Only extensions declared publishable appear in the release plan.
65 +- [ ] npm and Git consumer smoke passes in a temp directory without repository source.