{"_id":"@carter-mcalister/pi-mise-toolchain","name":"@carter-mcalister/pi-mise-toolchain","dist-tags":{"latest":"0.6.2"},"versions":{"0.6.2":{"name":"@carter-mcalister/pi-mise-toolchain","version":"0.6.2","description":"Mise-driven toolchain enforcement for Pi","author":{"name":"Carter McAlister"},"repository":{"type":"git","url":"git+https://github.com/CarterMcAlister/pi-packages.git","directory":"packages/pi-mise-toolchain"},"bugs":{"url":"https://github.com/CarterMcAlister/pi-packages/issues"},"homepage":"https://github.com/CarterMcAlister/pi-packages/tree/main/packages/pi-mise-toolchain#readme","keywords":["pi-package","pi-extension","pi","toolchain","mise","bun"],"pi":{"extensions":["./src/index.ts"]},"publishConfig":{"access":"public"},"type":"module","license":"MIT","private":false,"dependencies":{"@aliou/pi-utils-settings":"^0.13.0","@aliou/sh":"^0.1.0","@iarna/toml":"^2.2.5"},"peerDependencies":{"@mariozechner/pi-coding-agent":"0.61.0"},"devDependencies":{"@biomejs/biome":"^2.3.13","@changesets/cli":"^2.27.11","@mariozechner/pi-coding-agent":"0.61.0","@mariozechner/pi-tui":"0.61.0","@sinclair/typebox":"^0.34.48","@types/node":"^25.0.10","bun-types":"latest","typescript":"^5.9.3"},"overrides":{"@mariozechner/pi-ai":"$@mariozechner/pi-coding-agent","@mariozechner/pi-tui":"$@mariozechner/pi-coding-agent"},"scripts":{"format":"bunx @biomejs/biome check --write .","lint":"bunx @biomejs/biome check .","typecheck":"bunx tsc -p tsconfig.json --noEmit","test":"bun test","check":"bun run lint && bun run typecheck && bun run test","check:lockfile":"bun install --frozen-lockfile","changeset":"bunx changeset","version":"bunx changeset version","release":"bunx changeset publish"},"peerDependenciesMeta":{"@mariozechner/pi-coding-agent":{"optional":true}},"_id":"@carter-mcalister/pi-mise-toolchain@0.6.2","gitHead":"3d213b108520e8a3216a6a390cc250c3aa1c1329","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-oZhdK4ucln1tZiIGQtJBP+smGSBkIgFMUlhqFygCyPfJw4CTYAYlgOX0fo3V/CGn+sg/Zel06N6M3vJc9pCpKg==","shasum":"1ac5923e0569e09bf2616548917e6f1de66e12e3","tarball":"https://registry.npmjs.org/@carter-mcalister/pi-mise-toolchain/-/pi-mise-toolchain-0.6.2.tgz","fileCount":22,"unpackedSize":64389,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@carter-mcalister%2fpi-mise-toolchain@0.6.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCGf4cldUN2jgno/Pw6wmAfyYdI5xM9yvDmXDila7uAWQIgdWizU/seWLRKnJqNzS6dieQxAbLWkw+bQ8AHEFaoo8E="}]},"_npmUser":{"name":"carter-mcalister","email":"carterm126@gmail.com"},"directories":{},"maintainers":[{"name":"carter-mcalister","email":"carterm126@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-mise-toolchain_0.6.2_1775993113682_0.9825921157205995"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-12T11:25:13.559Z","0.6.2":"2026-04-12T11:25:13.833Z","modified":"2026-04-12T11:25:14.198Z"},"maintainers":[{"name":"carter-mcalister","email":"carterm126@gmail.com"}],"description":"Mise-driven toolchain enforcement for Pi","homepage":"https://github.com/CarterMcAlister/pi-packages/tree/main/packages/pi-mise-toolchain#readme","keywords":["pi-package","pi-extension","pi","toolchain","mise","bun"],"repository":{"type":"git","url":"git+https://github.com/CarterMcAlister/pi-packages.git","directory":"packages/pi-mise-toolchain"},"author":{"name":"Carter McAlister"},"bugs":{"url":"https://github.com/CarterMcAlister/pi-packages/issues"},"license":"MIT","readme":"# `@carter-mcalister/pi-mise-toolchain`\n\nOpinionated, mise-driven toolchain enforcement for Pi. Transparently rewrites commands to use preferred tools instead of blocking and forcing retries.\n\n## Installation\n\n```bash\npi install npm:@carter-mcalister/pi-mise-toolchain\n```\n\nOr install directly from this monorepo during local development:\n\n```bash\npi install /absolute/path/to/pi-packages/packages/pi-mise-toolchain\n```\n\n## Features\n\n### Rewriters (transparent, via spawn hook)\n\nThese features rewrite commands before shell execution. By default the agent does not see that the command was changed, but you can enable optional rewrite notifications in the config.\n\n- **enforcePackageManager**: Rewrites `npm`/`yarn`/`bun` commands to the package manager derived from the nearest `mise.toml`. Also handles `npx` -> `pnpm dlx`/`bunx`. Activates only when exactly one of `bun`, `pnpm`, or `npm` is declared in `[tools]`.\n- **rewritePython**: Rewrites `python`/`python3` to `uv run python` and `pip`/`pip3` to `uv pip`. Activates when `uv` is declared in the nearest `mise.toml` `[tools]` table.\n- **gitRebaseEditor**: Injects `GIT_EDITOR=true` and `GIT_SEQUENCE_EDITOR=:` env vars for `git rebase` commands so they run non-interactively.\n\n### Blockers (via tool_call hooks)\n\nBlockers are still used when a rewrite is not safe to apply automatically.\n\n- **python confirm** (part of `rewritePython`): When python/pip is used outside a uv project (no `pyproject.toml`), shows a confirmation dialog. Also blocks `poetry`/`pyenv`/`virtualenv` unconditionally.\n\nDangerous command presets such as `brew` and Docker secret blocking now live in `@aliou/pi-guardrails`.\n\n## Settings Command\n\nRun `/toolchain:settings` to open an interactive settings UI with two tabs:\n\n- **Global**: edit global extension config (`~/.pi/agent/extensions/toolchain.json`)\n- **Memory**: edit session-only overrides (not persisted)\n\nUse `Tab` / `Shift+Tab` to switch tabs. The settings UI controls extension-owned settings such as `gitRebaseEditor` and `bash.sourceMode`.\n\nPackage-manager and Python rewrites are derived from the nearest `mise.toml` and are not editable in the settings UI.\n\n## Configuration\n\nConfiguration is split by responsibility:\n\n- **Global JSON config**: `~/.pi/agent/extensions/toolchain.json`\n- **Memory config**: session-only overrides via `/toolchain:settings`\n- **Project toolchain config**: nearest `mise.toml`\n\n### Global JSON Configuration Schema\n\n```json\n{\n  \"enabled\": true,\n  \"features\": {\n    \"gitRebaseEditor\": \"rewrite\"\n  },\n  \"bash\": {\n    \"sourceMode\": \"override-bash\"\n  },\n  \"ui\": {\n    \"showRewriteNotifications\": false\n  }\n}\n```\n\nAll fields are optional. Missing fields use the defaults shown above.\n\n### Project `mise.toml` Rules\n\nThe nearest `mise.toml` controls project-level rewrites:\n\n- If `[tools]` declares `uv`, Python rewrites are enabled.\n- If `[tools]` declares exactly one of `bun`, `pnpm`, or `npm`, package-manager rewrites are enabled and that manager is selected.\n- If `[tools]` declares zero or multiple supported package managers, package-manager rewrites are disabled.\n\n### Defaults\n\n| Setting | Default | Description |\n| --- | --- | --- |\n| `features.gitRebaseEditor` | `\"rewrite\"` | On by default. Injects non-interactive env vars for git rebase. |\n| `bash.sourceMode` | `\"override-bash\"` | Select how rewrite hooks reach bash at runtime. Only matters when at least one rewrite is active. |\n| `ui.showRewriteNotifications` | `false` | Show a visible Pi notification each time a rewrite happens. |\n| Python rewrites | derived from `mise.toml` | Enabled when `uv` is declared in `[tools]`. |\n| Package-manager rewrites | derived from `mise.toml` | Enabled only when exactly one of `bun`, `pnpm`, or `npm` is declared in `[tools]`. |\n\n### Examples\n\nUse composed bash integration with an external bash composer:\n\n```json\n{\n  \"bash\": {\n    \"sourceMode\": \"composed-bash\"\n  }\n}\n```\n\nEnable rewrite notifications in global config:\n\n```json\n{\n  \"ui\": {\n    \"showRewriteNotifications\": true\n  }\n}\n```\n\nEnable project-level rewrites through `mise.toml`:\n\n```toml\n[tools]\nuv = \"latest\"\nbun = \"1.3.12\"\n```\n\n## How It Works\n\n### Rewriters vs Blockers\n\nThe extension uses two Pi mechanisms:\n\n1. **Spawn hook** (`createBashTool` with `spawnHook`): rewrites commands before shell execution. The agent sees the original command in the tool call UI but gets the output of the rewritten command.\n2. **tool_call event hooks**: block commands entirely. The agent sees a block reason and retries with the correct command. Used for commands that have no safe rewrite target.\n3. **Optional rewrite notifications**: when `ui.showRewriteNotifications` is enabled, a warning-level Pi notification is shown before the rewritten command runs. The message is prefixed with `[override-bash]` or `[composed-bash]` for debug clarity.\n\n### Execution Order\n\n1. Guardrails `tool_call` hooks run first (permission gate, env protection)\n2. Toolchain `tool_call` hooks run (blockers, optional rewrite notifications)\n3. If not blocked and at least one feature is in `rewrite` mode, runtime routing depends on `bash.sourceMode`:\n   - `override-bash`: toolchain registers its own bash tool with spawn hook\n   - `composed-bash`: toolchain waits for an external composer to request and compose its spawn hook\n4. Shell executes the rewritten command\n\n### AST-Based Rewriting\n\nAll rewriters use structural shell parsing via `@aliou/sh` to identify command names in the AST. This avoids false positives where tool names appear in URLs, file paths, or strings. If the parser fails, the command passes through unchanged — a missed rewrite is safe, a false positive rewrite corrupts the command.\n\n## Bash Source Mode\n\n`bash.sourceMode` controls how rewrite hooks attach to bash at runtime.\n\n- `override-bash` (default): toolchain registers bash when rewrite is active.\n- `composed-bash`: toolchain contributes its rewrite hook to an external bash composer.\n\nImportant:\n\n- Source mode matters only when at least one feature is set to `\"rewrite\"`.\n- Features set to `\"block\"` are unaffected.\n- In `override-bash` mode, Pi core still uses first-wins tool registration. If another extension earlier in load order already registered `bash`, toolchain cannot replace it.\n- In `composed-bash` mode, rewrites run only if an external composer emits `ad:bash:spawn-hook:request` and collects contributors.\n- If no composer exists, rewrites will not run in `composed-bash` mode by design.\n\n## Migration from Guardrails\n\nIf you were using `preventBrew`, `preventPython`, or `enforcePackageManager` in your guardrails config:\n\n1. Install `@carter-mcalister/pi-mise-toolchain`\n2. Add the project tool choices to `mise.toml` (`uv` for Python, exactly one of `bun` / `pnpm` / `npm` for package-manager rewrites)\n3. Optionally configure extension-owned settings in `~/.pi/agent/extensions/toolchain.json`\n4. Remove the deprecated features from your guardrails config\n\nThe guardrails extension will continue to honor these features with a deprecation warning until they are removed in a future version.\n\n## Credits\n\nThis package is a maintained fork of [`@aliou/pi-toolchain`](https://github.com/aliou/pi-toolchain).\n\nCredit to Aliou for the original project, design, and implementation this fork builds on.\n\n## Development\n\n```bash\nmise install\nbun install\nmise run check\n```\n","readmeFilename":"README.md","_rev":"1-4601bdcf13ffb8ca6a736d1ac6664dfa"}