4 +title: Pi Extension Architecture
9 +Make each Pi extension independently developable, testable, installable, releasable, and upgradable without sacrificing fast local work or complete collection use.
10 +Keep runtime behavior close to Pi's Node execution model and reduce startup and reload work through built artifacts.
12 +##
Source and package boundaries 14 +The repository root is a development workspace, not a Pi package.
15 +Each extension owns its source, metadata, tests, runtime resources, and generated package.
16 +Extensions neither import sibling extensions nor depend on sibling output paths.
17 +Shared development tooling is allowed; shared runtime files outside an extension package are not.
19 +Every extension emits a complete package under `dist/<extension>`.
20 +Pi settings list each generated extension package explicitly.
21 +The same package boundary is used for local development, verification, npm distribution, and Git distribution.
23 +Extension and shipped runtime code is authored in TypeScript.
24 +Generated JavaScript is allowed.
25 +Bootstrap automation may remain JavaScript when TypeScript would introduce a build-before-build cycle.
27 +##
Runtime dependencies 29 +A generated package runs without repository source, workspace links, ancestor `node_modules`, or undeclared ambient files.
30 +Node built-ins, Pi-provided modules, TypeBox modules supplied by Pi, and explicitly declared system executables may remain external.
31 +Portable third-party JavaScript is bundled by default.
32 +An external runtime dependency requires demonstrated bundling incompatibility or a clearly superior explicit integration.
34 +Workers, browser code, templates, filters, executable helpers, and other runtime assets remain inside their owning package.
35 +Pi extensions, skills, prompts, and themes are exposed only when explicitly declared.
36 +Generated manifests map declared resources to generated paths and never expose internal guidance accidentally.
38 +Packages preserve intentional lazy-loading boundaries through package-private generated chunks where useful.
39 +Package loading must not depend on removing or replacing Pi's jiti importer.
43 +On-demand builds are the primary development interface.
44 +A watcher may invoke the same development build but has no protocol with Pi.
45 +After a successful build, the developer invokes Pi reload explicitly.
47 +Development and release builds emit to the same canonical package directory and intentionally replace one another.
48 +They preserve the same module boundaries, dependency policy, manifest shape, resources, and observable behavior.
49 +They may differ only in debugging information and behavior-neutral optimization.
51 +A failed or interrupted build leaves the last complete package usable.
52 +A successful build publishes the new entrypoint only after its required chunks and resources are complete.
53 +Content-addressed chunks may coexist temporarily so an already loaded extension can finish lazy imports during replacement.
55 +Release verification snapshots the exact generated bytes.
56 +Publication uses that verified snapshot or rejects a digest mismatch.
60 +Mise is the stable public automation API and a thin delegation layer.
61 +Mise manages runtimes and tools that the JavaScript package system does not own.
62 +It does not contain the extension build system.
64 +npm owns dependency installation, workspaces, the lockfile, and JavaScript task delegation.
65 +Rolldown owns extension bundling and is a direct development dependency.
66 +Vitest runs source tests on Node.
67 +Playwright owns browser acceptance.
68 +Pi on Node owns generated-package and compatibility verification.
69 +Bun is not part of the toolchain.
71 +Root package scripts and tooling own repository automation.
72 +Extension package scripts remain absent.
76 +Tests are separated by the guarantee they provide.
78 +Unit and component tests exercise pure source behavior with deterministic inputs and no real Pi session unless necessary.
79 +Property tests belong to this layer and use reproducible seeds, shrinking, and retained regression cases.
80 +Small inline snapshots and readable file snapshots may protect stable rendered output after volatile data is normalized.
82 +Pi contract tests load extension entrypoints through Pi's real loader and exercise registration, lifecycle, dispatch, and provider routing through public APIs.
83 +Every extension has a path-loaded contract and fails on unexpected extension errors.
85 +Native integration tests exercise Node, filesystem, subprocess, Git, HTTP, cancellation, and platform behavior using owned temporary resources and controlled real processes.
86 +Tests requiring distinct process environments run in distinct processes.
88 +Generated-package tests execute immutable package snapshots outside the checkout with independently installed Pi versions.
89 +They verify relocation, manifests, resources, lazy first use, workers, allowed externals, and absence of workspace dependency leakage.
90 +Each extension is tested independently, and the complete configured collection is tested for composition conflicts.
92 +UI acceptance tests exercise generated browser or terminal artifacts through the real UI runner.
94 +##
Test fixture constraints 96 +The shared Pi fixture uses public, strongly typed Pi APIs and deterministic scripted providers.
97 +It owns environment, temporary paths, sockets, processes, timers, shutdown, and cleanup explicitly.
98 +Unexpected asynchronous and extension errors fail the test.
99 +Concurrent sessions never pretend to own distinct environments inside one process.
101 +Test correctness does not depend on text-patching installed dependencies or private Pi properties.
102 +An upstream harness is acceptable only when it satisfies the same contract; otherwise the repository owns the narrow fixture it needs.
104 +All maintained TypeScript is checked, including runtime code, tests, fixtures, configuration, workers, browser entrypoints, and TypeScript automation.
105 +Focused checking covers one extension and shared inputs without repeating repository-wide checking.
106 +Root checking covers the union once.
108 +##
Verification cadence 110 +Commit hooks contain only quick, deterministic, network-independent checks over the changed scope.
111 +Push hooks may add complete static checking and deterministic source tests.
112 +Hooks exclude browser installation, compatibility matrices, package publication, coverage instrumentation, mutation campaigns, and fuzz campaigns.
114 +Normal CI runs complete static checks, one coordinated source-test run, release builds, current-Pi package verification, and applicable native and UI integration.
115 +Release verification runs the immutable artifacts across the declared Pi, Node, and operating-system matrix.
116 +Current configured Pi compatibility is mandatory.
117 +The minimum supported Pi version is established empirically from an initially broad matrix.
119 +##
Test-quality techniques 121 +Coverage reports include unimported owned production files and report line, branch, and function coverage per extension.
122 +Coverage guides investigation and is not initially a percentage gate.
123 +The V8 and Istanbul providers are selected by measured suite behavior.
125 +Property testing is preferred for parsers, normalization, path safety, bounded rendering, serialization, and state machines.
126 +Failures record replay information and yield permanent minimal regression cases.
128 +Mutation testing is selective, incremental, and author-driven while test context is fresh.
129 +It targets pure unit-testable code by file or line range, retains a correctly invalidated per-extension cache, and is not a commit, push, or CI gate.
130 +Occasional full mutation runs may report repository health without imposing a score target.
132 +Snapshot testing protects concise, reviewable output contracts and never replaces semantic assertions.
133 +Snapshots exclude volatile paths, timestamps, identifiers, dependency diagnostics, and generated bundles.
134 +Snapshot updates are explicit and reviewed.
136 +Coverage-guided fuzzing is reserved for narrow hostile-input or security boundaries where property testing is insufficient.
137 +Long fuzz campaigns run manually or on a schedule.
138 +Minimized corpus findings become normal deterministic regression tests.
140 +##
Distribution and compatibility 142 +Public distribution uses Pi's normal npm and Git package channels.
143 +Consumers receive built packages and never need the source workspace or build toolchain.
144 +Generated packages contain no lifecycle installation scripts.
146 +Extensions remain independently releasable.
147 +Publication eligibility is independent from local loading, and releases publish only explicitly selected extensions.
148 +Versioning and compatibility metadata have one authoritative source and generated manifests do not become a second source of truth.
150 +The architecture supports Windows, macOS, and Linux.
151 +Platform tools are detected through normal extension behavior and unsupported optional capabilities degrade explicitly.
153 +##
Acceptance criteria 155 +- The repository root is not discoverable as a Pi package.
156 +- Pi loads the configured collection from one explicit local package entry per extension.
157 +- A focused development build updates only the selected extension package and leaves a complete reloadable result.
158 +- A release build overwrites the same package location without changing observable behavior.
159 +- Every generated package loads independently outside the checkout with zero unexpected diagnostics.
160 +- No generated package resolves sibling output, repository source, workspace links, or ancestor dependencies.
161 +- Declared resources and lazy first-use paths work after relocation.
162 +- The complete generated collection loads without identity, tool, command, flag, or resource conflicts.
163 +- Current configured Pi passes generated-package verification.
164 +- Compatibility results identify an explicit minimum supported Pi version before public release.
165 +- Focused tests and checking avoid unrelated extension work.
166 +- Root tests use one Vitest coordinator while retaining required worker and process isolation.
167 +- Maintained TypeScript is completely typechecked.
168 +- Release publication consumes the exact verified artifact bytes.
169 +- npm and Git consumers can install selected extensions without compiling source.