# Pi Extensions Workspace Monorepo for Pi extensions under `extensions/*`. ## Automation law - Mise is the only public automation interface. - `mise.toml` files are the source of truth for tools, tasks, dependencies, and orchestration. - Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly. - Root npm scripts are task implementation details. - Extension package scripts are prohibited. - Add missing automation to the appropriate `mise.toml`; do not create ad hoc scripts or bypass Mise. - If Mise or its project config blocks progress, report the exact failure and stop rather than working around it. ## Task discovery Run `mise tasks --all` to list root and extension-local tasks. Use monorepo-root paths when referring to tasks from automation or documentation: - `//:test` addresses a root task. - `//extensions/angel:test` addresses an extension task. - `//extensions/...:bench` selects a task across matching extension config roots. Task-name groups and wildcards select tasks; they do not create dependencies or ordering. Use `mise task info ` for task details, `mise tasks deps ` for declared dependency edges, and `mise run --dry-run ` to inspect execution. Run `mise tasks validate` after changing the root config. Run `mise -C extensions/ tasks validate` after changing an extension config. ## Choosing tasks | Need | Command | | --- | --- | | Install exact locked dependencies | `mise run //:install` | | Regenerate `package-lock.json` | `mise run //:lock` | | Format the repository | `mise run //:fmt` | | Verify repository formatting and lint | `mise run //:lint` | | Run the complete test suite once | `mise run //:test` | | Run one extension's tests | `mise run //extensions/:test` | | Lint one extension | `mise run //extensions/:lint` | | Typecheck and statically check one extension | `mise run //extensions/:check` | | Typecheck and statically check all extensions | `mise run //:check` | | Run property tests | `mise run //:fuzz` | | Run all benchmarks sequentially | `mise run //:bench` | | Run all browser E2E suites | `mise run //:e2e` | | Run the release gate | `mise run //:ci` | Use `mise run //:test -- extensions/` and `mise run //:build -- ` only when implementing a local task or diagnosing its root delegate. Normal agent workflows should use the extension-local task names. Root operation tasks are `//:list`, `//:changelog`, `//:readme`, `//:demo`, `//:release-plan`, `//:release-prepare`, and `//:publish`. Invoke one with `mise run`, passing extension names after `--`, for example `mise run //:readme -- angel`. ## Efficient execution Choose the smallest task that proves the change, then run the required wider gate. - During iteration, use one extension's local `lint`, `test`, or `check` task. - For complete tests, run root `//:test` once; do not fan out all extension `test` wrappers into one Vitest process per extension. - For complete static validation, run root `//:check` once; do not fan out all extension `check` wrappers because each repeats repository-wide TypeScript checking. - Before pushing, run `mise run //:ci`. Mise task jobs and tool workers multiply. Set `--jobs` deliberately when invoking multiple independent tasks, because Vitest, Playwright, and other tools manage their own workers. Use `:::` only for independent ad hoc tasks that should run concurrently. ## Task authoring Use `depends` for prerequisites so Mise can deduplicate shared work and schedule independent dependencies concurrently. Use structured task references instead of spawning nested Mise processes: ```toml run = [{ task = "//:test", args = ["extensions/angel"] }] ``` A `run` array is sequential. Use `{ tasks = ["check", "lint"] }` for an explicit parallel stage inside that sequence. Structured task references execute their own dependencies but do not appear as edges in `mise tasks deps`. Use a nested `mise run` command only when a required CLI scheduler option, such as `--jobs 1`, has no structured-task equivalent. Do not set `raw = true` unless a task requires stdin. Raw tasks serialize against other tasks and disable output redaction. ## CI hosting Luci at `ci.bugabinga.net` auto-discovers `.ci/*.kdl` from the public Soft Serve repository. Repository CI must delegate to `CI=true mise run //:ci`; do not duplicate gates in Luci configuration. **`mise run //:ci` must pass before pushing.** It runs check and lint concurrently, then test, fuzz, and E2E sequentially. ## Extension engineering ### Startup performance - Treat every Win32 process spawn as expensive. - Prefer native Node APIs and defer unavoidable spawns until first use. - Keep entry modules thin and lazy-load command or tool implementations. - Gate optional domain work with cheap relevance checks before imports. - Never block startup or reload on subprocess probes, broad filesystem scans, or Git status. - Abort asynchronous startup work on reload and ignore stale results. - Check executable presence through native `PATH` access, not version subprocesses. - Preserve registration, validation, rendering, and first-use behavior when deferring work. - Measure performance with the complete extension set on Win32 and WSL. ### Tool widget rendering Tool widgets must match Pi built-ins: compact by default, expanded details on `app.tools.expand` (`ctrl+o` by default). Collapsed `renderResult` output may show status, counts, paths, IDs, and tiny bounded summaries only. Full content, previews, snippets, verbose logs, structured bodies, and per-result lists require `expanded === true`. Expansion hints must use `keyHint("app.tools.expand", "to expand")`; do not use legacy `expandTools`. ### Cross-platform requirements All extensions must work on Windows, macOS, and Linux. Do not add OS-scoped extensions. Do not rely on shell helpers such as `which`, `bash`, `sed`, `grep`, or `/tmp` when Node APIs can do the job. If an extension uses platform tools, check availability when the extension loads. Notify missing required tools with warning severity and missing optional tools with info severity. Tests for platform-tool behavior must exercise the real extension or tool path with controlled fake binaries on `PATH`, not only mocked helpers. ## Markdown style Use one sentence per line for prose. Keep semantic line breaks unless rewording the sentence. Let `rumdl` handle Markdown structure; do not manually reflow paragraphs for visual width. ## Git hooks - `pre-commit` runs format, lint, and test. - `pre-push` runs full CI. Hooks are managed through `mise generate git-pre-commit`. Reinstall them with `mise generate git-pre-commit --write`, then `mise generate git-pre-commit --hook pre-push --task pre-push --write`. ## Troubleshooting Run `mise doctor` when a task fails because a command is unavailable. Common causes are missing activation, missing shims, or a mismatched tool binary name.