1 1 #
Pi Extensions Workspace 3 -Monorepo for Pi extensions.
4 -Extensions live in `extensions/*`.
3 +Monorepo for Pi extensions under `extensions/*`.
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.
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.
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.
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.
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:
72 +run = [{ task = "//:test", args = ["extensions/angel"] }]
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.
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.
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.
91 +##
Extension engineering 48 -Use `mise run ...` for listed repo tasks.
49 -Do not bypass mise when a task exists.
93 +###
Startup performance 53 -If the build system itself (`mise.toml`, scripts, or tooling) blocks progress,
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.
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
124 +Keep semantic line breaks unless rewording the sentence.
125 +Let `rumdl` handle Markdown structure; do not manually reflow paragraphs for visual width.
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`.
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.