repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: define extension automation contract

5b2ff2e1c0d6577ee1cc745a6cf174f14080e66f

Oliver Krylow <o.krylow@isp-insoft.de> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (2)

AGENTS.md

Modified
1 1 # Pi Extensions Workspace
3 -Monorepo for Pi extensions.
4 -Extensions live in `extensions/*`.
3 +Monorepo for Pi extensions under `extensions/*`.
6 -## Build System
5 +## Automation law
8 -`mise` is the singular interface.
9 -`mise.toml` is the source of truth.
10 -Prefer targeted Mise tasks for fmt/lint/test/check.
11 -If missing, follow Mise/project rules to add or enable one; never bypass Mise.
7 +- Mise is the only public automation interface.
8 +- `mise.toml` files are the source of truth for tools, tasks, dependencies, and orchestration.
9 +- Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly.
10 +- Root npm scripts are task implementation details.
11 +- Extension package scripts are prohibited.
12 +- Add missing automation to the appropriate `mise.toml`; do not create ad hoc scripts or bypass Mise.
13 +- If Mise or its project config blocks progress, report the exact failure and stop rather than working around it.
13 -### Tasks
15 +## Task discovery
15 -| Task | Command | Description |
16 -| ------------ | ------------------------------------ | ----------------------------------------- |
17 -| List | `mise run list` | List extensions |
18 -| Format | `mise run fmt` | Format repo |
19 -| Lint | `mise run lint` | Verify formatting and lint |
20 -| Test | `mise run test` | Run tests |
21 -| Bench | `mise run bench` | Run extension benchmarks sequentially |
22 -| E2E | `mise run e2e` | Run extension E2E in Chromium and Firefox |
23 -| Check | `mise run check` | Typecheck and static extension checks |
24 -| CI | `mise run ci` | Release gate (check + lint + test + e2e) |
25 -| Changelog | `mise run changelog -- {name}` | Generate changelog for extension |
26 -| README | `mise run readme -- {name}` | Generate/update README for extension |
27 -| Demo | `mise run demo -- {name}` | Record demo GIFs |
28 -| Release plan | `mise run release-plan -- {name}` | Preview release artifacts |
29 -| Prepare | `mise run release-prepare -- {name}` | Generate release artifacts |
30 -| Publish | `mise run publish -- {name}` | Publish prepared release artifacts |
17 +Run `mise tasks --all` to list root and extension-local tasks.
18 +Use monorepo-root paths when referring to tasks from automation or documentation:
32 -Extension-specific tasks live in extension-local `mise.toml` files.
33 -Every new extension must expose local `lint`, `test`, and `check` tasks.
34 -Add `bench` when it has performance-sensitive behavior, and keep local tasks aligned as extension capabilities evolve.
35 -Run one from the root with `mise //extensions/<name>:<task>`.
36 -Use `mise tasks --all` to list root and extension-local tasks.
20 +- `//:test` addresses a root task.
21 +- `//extensions/angel:test` addresses an extension task.
22 +- `//extensions/...:bench` selects a task across matching extension config roots.
38 -### CI hosting
24 +Task-name groups and wildcards select tasks; they do not create dependencies or ordering.
25 +Use `mise task info <task>` for task details, `mise tasks deps <task>` for declared dependency edges, and `mise run --dry-run <task>` to inspect execution.
26 +Run `mise tasks validate` after changing the root config.
27 +Run `mise -C extensions/<name> tasks validate` after changing an extension config.
29 +## Choosing tasks
31 +| Need | Command |
32 +| --- | --- |
33 +| Install exact locked dependencies | `mise run //:install` |
34 +| Regenerate `package-lock.json` | `mise run //:lock` |
35 +| Format the repository | `mise run //:fmt` |
36 +| Verify repository formatting and lint | `mise run //:lint` |
37 +| Run the complete test suite once | `mise run //:test` |
38 +| Run one extension's tests | `mise run //extensions/<name>:test` |
39 +| Lint one extension | `mise run //extensions/<name>:lint` |
40 +| Typecheck and statically check one extension | `mise run //extensions/<name>:check` |
41 +| Typecheck and statically check all extensions | `mise run //:check` |
42 +| Run property tests | `mise run //:fuzz` |
43 +| Run all benchmarks sequentially | `mise run //:bench` |
44 +| Run all browser E2E suites | `mise run //:e2e` |
45 +| Run the release gate | `mise run //:ci` |
47 +Use `mise run //:test -- extensions/<name>` and `mise run //:build -- <name>` only when implementing a local task or diagnosing its root delegate.
48 +Normal agent workflows should use the extension-local task names.
50 +Root operation tasks are `//:list`, `//:changelog`, `//:readme`, `//:demo`, `//:release-plan`, `//:release-prepare`, and `//:publish`.
51 +Invoke one with `mise run`, passing extension names after `--`, for example `mise run //:readme -- angel`.
53 +## Efficient execution
55 +Choose the smallest task that proves the change, then run the required wider gate.
57 +- During iteration, use one extension's local `lint`, `test`, or `check` task.
58 +- For complete tests, run root `//:test` once; do not fan out all extension `test` wrappers into one Vitest process per extension.
59 +- For complete static validation, run root `//:check` once; do not fan out all extension `check` wrappers because each repeats repository-wide TypeScript checking.
60 +- Before pushing, run `mise run //:ci`.
62 +Mise task jobs and tool workers multiply.
63 +Set `--jobs` deliberately when invoking multiple independent tasks, because Vitest, Playwright, and other tools manage their own workers.
64 +Use `:::` only for independent ad hoc tasks that should run concurrently.
66 +## Task authoring
68 +Use `depends` for prerequisites so Mise can deduplicate shared work and schedule independent dependencies concurrently.
69 +Use structured task references instead of spawning nested Mise processes:
71 +```toml
72 +run = [{ task = "//:test", args = ["extensions/angel"] }]
73 +```
75 +A `run` array is sequential.
76 +Use `{ tasks = ["check", "lint"] }` for an explicit parallel stage inside that sequence.
77 +Structured task references execute their own dependencies but do not appear as edges in `mise tasks deps`.
78 +Use a nested `mise run` command only when a required CLI scheduler option, such as `--jobs 1`, has no structured-task equivalent.
80 +Do not set `raw = true` unless a task requires stdin.
81 +Raw tasks serialize against other tasks and disable output redaction.
83 +## CI hosting
40 85 Luci at `ci.bugabinga.net` auto-discovers `.ci/*.kdl` from the public Soft Serve repository.
41 -The repository CI job must delegate to `CI=true mise run ci`; do not duplicate checks in Luci config.
86 +Repository CI must delegate to `CI=true mise run //:ci`; do not duplicate gates in Luci configuration.
43 -### Invariant
88 +**`mise run //:ci` must pass before pushing.**
89 +It runs check and lint concurrently, then test, fuzz, and E2E sequentially.
45 -`mise run ci` must pass before pushing.
46 -No exceptions.
91 +## Extension engineering
48 -Use `mise run ...` for listed repo tasks.
49 -Do not bypass mise when a task exists.
93 +### Startup performance
51 -### Escalation
53 -If the build system itself (`mise.toml`, scripts, or tooling) blocks progress,
54 -escalate to a human.
55 -Do not work around `mise` or add ad-hoc scripts.
57 -## Startup performance
59 -- Treat every Win32 process spawn as expensive; prefer native Node APIs and defer unavoidable spawns to first use.
60 -- Keep entry modules thin; lazy-load command and tool implementations on first use.
61 -- Gate optional domain work with cheap relevance checks before importing implementations.
95 +- Treat every Win32 process spawn as expensive.
96 +- Prefer native Node APIs and defer unavoidable spawns until first use.
97 +- Keep entry modules thin and lazy-load command or tool implementations.
98 +- Gate optional domain work with cheap relevance checks before imports.
62 99 - Never block startup or reload on subprocess probes, broad filesystem scans, or Git status.
63 100 - Abort asynchronous startup work on reload and ignore stale results.
64 -- Check executable presence through native PATH access, not version subprocesses.
101 +- Check executable presence through native `PATH` access, not version subprocesses.
65 102 - Preserve registration, validation, rendering, and first-use behavior when deferring work.
66 -- Measure performance only with the complete extension set on Win32 and WSL.
103 +- Measure performance with the complete extension set on Win32 and WSL.
68 -## Tool Widget Rendering
105 +### Tool widget rendering
70 107 Tool widgets must match Pi built-ins: compact by default, expanded details on `app.tools.expand` (`ctrl+o` by default).
71 108 Collapsed `renderResult` output may show status, counts, paths, IDs, and tiny bounded summaries only.
72 109 Full content, previews, snippets, verbose logs, structured bodies, and per-result lists require `expanded === true`.
73 110 Expansion hints must use `keyHint("app.tools.expand", "to expand")`; do not use legacy `expandTools`.
75 -## Cross-platform Requirements
112 +### Cross-platform requirements
77 114 All extensions must work on Windows, macOS, and Linux.
78 115 Do not add OS-scoped extensions.
79 -Do not rely on shell-specific helpers such as `which`, `bash`, `sed`, `grep`, or `/tmp` when Node APIs can do the job.
80 -If an extension uses platform tools, check their availability when the extension loads.
81 -Notify missing required tools with warning severity.
82 -Notify missing optional tools with info severity.
83 -Tests for platform-tool behavior must exercise the real extension/tool path with controlled fake binaries on `PATH`, not only mocked helpers.
116 +Do not rely on shell helpers such as `which`, `bash`, `sed`, `grep`, or `/tmp` when Node APIs can do the job.
117 +If an extension uses platform tools, check availability when the extension loads.
118 +Notify missing required tools with warning severity and missing optional tools with info severity.
119 +Tests for platform-tool behavior must exercise the real extension or tool path with controlled fake binaries on `PATH`, not only mocked helpers.
85 -## Markdown Style
121 +## Markdown style
87 123 Use one sentence per line for prose.
88 -Keep existing semantic line breaks unless rewording the sentence.
89 -Let `rumdl` handle Markdown structure; do not manually reflow paragraphs for
90 -visual width only.
124 +Keep semantic line breaks unless rewording the sentence.
125 +Let `rumdl` handle Markdown structure; do not manually reflow paragraphs for visual width.
92 -## Git Hooks
127 +## Git hooks
94 -- `pre-commit` — runs `fmt` + `lint` + `test`
95 -- `pre-push` — runs full `ci`
129 +- `pre-commit` runs format, lint, and test.
130 +- `pre-push` runs full CI.
97 -Managed via `mise generate git-pre-commit`.
98 -To reinstall after clone:
99 -`mise generate git-pre-commit --write && mise generate git-pre-commit --hook
100 -pre-push --task pre-push --write`.
132 +Hooks are managed through `mise generate git-pre-commit`.
133 +Reinstall them with `mise generate git-pre-commit --write`, then `mise generate git-pre-commit --hook pre-push --task pre-push --write`.
102 135 ## Troubleshooting
104 -If `mise run` tasks fail with command-not-found errors, run `mise doctor`.
105 -Common causes:
106 -mise not activated, shims missing, tool binary name mismatch.
137 +Run `mise doctor` when a task fails because a command is unavailable.
138 +Common causes are missing activation, missing shims, or a mismatched tool binary name.

extensions/AGENTS.md

Modified
1 -# Pi Extensions Workspace
1 +# Extension Packages
3 -## New extension
3 +These rules apply to every package under `extensions/*`.
4 +The workspace automation and execution rules in the root `AGENTS.md` also apply.
5 -1. `extensions/{name}/package.json` — template below
6 -2. `extensions/{name}/index.ts`
7 -3. `npm install`
6 +## New extension checklist
9 -## package.json
8 +Create:
11 -```json
12 -{
13 - "name": "@bugabinga/pi-ext-{name}",
14 - "version": "0.0.0",
15 - "private": true,
16 - "type": "module",
17 - "main": "index.ts",
18 - "peerDependencies": {
19 - "@earendil-works/pi-coding-agent": "*"
20 - }
21 -}
10 +1. `extensions/<name>/package.json`
11 +2. `extensions/<name>/index.ts`
12 +3. `extensions/<name>/README.md`
13 +4. `extensions/<name>/__tests__/harness.test.ts`
14 +5. `extensions/<name>/mise.toml`
16 +Then run `mise run //:lock` and the extension-local `lint`, `test`, and `check` tasks.
17 +Do not run `npm install` directly.
19 +## Package manifest contract
21 +Every extension package must declare:
23 +- name `@bugabinga/pi-ext-<name>`
24 +- `private: true`
25 +- `type: "module"`
26 +- `main: "index.ts"`
27 +- `license: "MIT"`
28 +- development dependencies on `@marcfargas/pi-test-harness` and Vitest
30 +Do not declare a per-extension version.
31 +The root package owns the repository version.
32 +Do not declare package scripts.
33 +Extension automation belongs in `mise.toml`.
35 +Declare only packages imported by the extension, including development and test code.
36 +Put Pi packages under `peerDependencies` with range `"*"`.
37 +Never depend on another `@bugabinga/pi-ext-*` package.
38 +`scripts/extensions.mjs` enforces this contract.
40 +## Mandatory harness test
42 +Every extension must include a pi-test-harness test that loads `index.ts` through the real Pi extension runtime.
43 +Mocks around helper functions do not replace this test.
44 +Run it through `mise run //extensions/<name>:test`.
46 +## Mandatory local tasks
48 +Every extension must expose `lint`, `test`, and `check` in its local `mise.toml`.
49 +Root tools and environment are inherited, so do not redeclare them locally.
50 +Use this baseline, replacing `angel` with the package directory name:
52 +```toml
53 +[tasks.lint]
54 +description = "Lint angel extension"
55 +depends = ["//:install"]
56 +run = [
57 + "biome ci --config-path ../.. .",
58 + "rumdl check --config ../../.rumdl.toml .",
59 + "taplo format --check --config ../../.taplo.toml mise.toml",
62 +[tasks.test]
63 +description = "Test angel extension"
64 +depends = ["//:install"]
65 +run = [
66 + { task = "//:test", args = ["extensions/angel"] },
69 +[tasks.check]
70 +description = "Check angel extension"
71 +depends = ["//:install"]
72 +run = [
73 + { task = "//:build", args = ["angel"] },
24 -Add only deps actually imported by the extension.
25 -Prefer `peerDependencies` for Pi packages (`@earendil-works/*`).
26 -Do not add package scripts; extension automation belongs in `mise.toml`.
27 -Run `npm install` after any structural change.
29 -## Mandatory test harness
31 -- Every extension must dev-depend on `@marcfargas/pi-test-harness`.
32 -- Every extension must include a pi-test-harness test that loads `index.ts`
33 - through the real Pi extension runtime.
34 -- Run extension tests through the extension-local Mise `test` task.
77 +Keep optional package automation, such as `bench`, `e2e`, or `dev`, in the same local `mise.toml`.
78 +Do not replace structured task references with command strings that spawn `mise run`.
36 80 ## Independence
38 -- Extensions must be standalone packages.
39 -- Never import from another `@bugabinga/pi-ext-*` package.
40 -- Optional integration must be capability/event based and degrade cleanly.
41 -- If behavior is important, provide a native fallback; decorative integration
42 - may no-op.
44 -## Startup
46 -- `session_start` must be fast.
47 -- No awaited network, git, FS scans, or subprocesses.
48 -- Publish minimal UI now; defer slow work with bg task + generation/stale guard.
49 -- Never block other extensions for telemetry, recovery, decoration, or cache
50 - warming.
52 -## Checks
54 -- Source of truth:
55 - `mise.toml` → `scripts/extensions.mjs`.
56 -- Run `mise run build -- [{name}]` before sharing or extracting an extension.
57 -- `mise run build` = static checks + build.
58 -- `mise run test` = pi-test-harness.
59 -- `mise run changelog -- {name}` = ephemeral Pi agent writes a changelog section
60 - after reading git commits + extension source.
61 -- `mise run publish -- {name}` = ci + demos + agent changelog + commit + tag +
62 - push.
63 -- Publish is git-only.
64 - No npm registry flow.
65 -- License is MIT.
67 -## Commands
69 -- Commands with subcommands must provide argument autocomplete.
71 -## Documentation
73 -- READMEs must be terse.
74 -- Do not duplicate source-of-truth docs/config/API details.
75 -- Link to canonical source files, commands, settings, or upstream docs instead.
76 -- Package README should answer:
77 - what, install/load, commands/tools, settings link, optional integrations.
82 +Extensions must remain standalone packages.
83 +Never import from another `@bugabinga/pi-ext-*` package or another extension directory.
84 +Optional integration must use capabilities or events and degrade cleanly.
85 +Important behavior needs a native fallback; decorative integration may no-op.
79 87 ## Imports
81 -| Package | Provides | Use |
82 -| --------------------------------- | ------------------------------------ | ----------------- |
83 -| `@earendil-works/pi-coding-agent` | SDK — ExtensionAPI, types, ctx | Always (peer dep) |
84 -| `@earendil-works/pi-tui` | TUI components, truncateToWidth, Key | Rendering |
85 -| `@bugabinga/pi-ext-*` | — | **Never |
86 -| import | | |
87 -| from | | |
88 -| other | | |
89 -| extensions** | | |
89 +| Package | Provides | Placement |
90 +| --- | --- | --- |
91 +| `@earendil-works/pi-coding-agent` | Extension API, context, and coding-agent types | peer dependency when imported |
92 +| `@earendil-works/pi-ai` | model and message APIs | peer dependency when imported |
93 +| `@earendil-works/pi-tui` | terminal UI components and rendering helpers | peer dependency when imported |
94 +| `typebox` | tool parameter schemas | peer dependency when imported |
95 +| `@bugabinga/pi-ext-*` | sibling extension implementation | never |
97 +## Startup
99 +`session_start` must be fast.
100 +Do not await network access, Git, filesystem scans, or subprocesses during startup.
101 +Publish minimal UI immediately, then defer slow work with a background task and generation or stale-result guard.
102 +Never block other extensions for telemetry, recovery, decoration, or cache warming.
104 +## Commands
106 +Commands with subcommands must provide argument autocomplete.
108 +## Documentation
110 +Keep READMEs terse.
111 +Do not duplicate source-of-truth configuration, API details, or implementation documentation.
112 +Link to canonical source files, commands, settings, or upstream documentation.
113 +A package README should explain purpose, installation or loading, commands and tools, settings, and optional integrations.
115 +## Publishing
117 +Use the root `//:publish` task.
118 +Publishing is Git-only; there is no npm registry flow.