@carter-mcalister/pi-mise-toolchain 0.6.2

package/README.md

@@ -0,0 +1,182 @@
+# `@carter-mcalister/pi-mise-toolchain`
+
+Opinionated, mise-driven toolchain enforcement for Pi. Transparently rewrites commands to use preferred tools instead of blocking and forcing retries.
+
+## Installation
+
+```bash
+pi install npm:@carter-mcalister/pi-mise-toolchain
+```
+
+Or install directly from this monorepo during local development:
+
+```bash
+pi install /absolute/path/to/pi-packages/packages/pi-mise-toolchain
+```
+
+## Features
+
+### Rewriters (transparent, via spawn hook)
+
+These 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.
+
+- **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]`.
+- **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.
+- **gitRebaseEditor**: Injects `GIT_EDITOR=true` and `GIT_SEQUENCE_EDITOR=:` env vars for `git rebase` commands so they run non-interactively.
+
+### Blockers (via tool_call hooks)
+
+Blockers are still used when a rewrite is not safe to apply automatically.
+
+- **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.
+
+Dangerous command presets such as `brew` and Docker secret blocking now live in `@aliou/pi-guardrails`.
+
+## Settings Command
+
+Run `/toolchain:settings` to open an interactive settings UI with two tabs:
+
+- **Global**: edit global extension config (`~/.pi/agent/extensions/toolchain.json`)
+- **Memory**: edit session-only overrides (not persisted)
+
+Use `Tab` / `Shift+Tab` to switch tabs. The settings UI controls extension-owned settings such as `gitRebaseEditor` and `bash.sourceMode`.
+
+Package-manager and Python rewrites are derived from the nearest `mise.toml` and are not editable in the settings UI.
+
+## Configuration
+
+Configuration is split by responsibility:
+
+- **Global JSON config**: `~/.pi/agent/extensions/toolchain.json`
+- **Memory config**: session-only overrides via `/toolchain:settings`
+- **Project toolchain config**: nearest `mise.toml`
+
+### Global JSON Configuration Schema
+
+```json
+{
+  "enabled": true,
+  "features": {
+    "gitRebaseEditor": "rewrite"
+  },
+  "bash": {
+    "sourceMode": "override-bash"
+  },
+  "ui": {
+    "showRewriteNotifications": false
+  }
+}
+```
+
+All fields are optional. Missing fields use the defaults shown above.
+
+### Project `mise.toml` Rules
+
+The nearest `mise.toml` controls project-level rewrites:
+
+- If `[tools]` declares `uv`, Python rewrites are enabled.
+- If `[tools]` declares exactly one of `bun`, `pnpm`, or `npm`, package-manager rewrites are enabled and that manager is selected.
+- If `[tools]` declares zero or multiple supported package managers, package-manager rewrites are disabled.
+
+### Defaults
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `features.gitRebaseEditor` | `"rewrite"` | On by default. Injects non-interactive env vars for git rebase. |
+| `bash.sourceMode` | `"override-bash"` | Select how rewrite hooks reach bash at runtime. Only matters when at least one rewrite is active. |
+| `ui.showRewriteNotifications` | `false` | Show a visible Pi notification each time a rewrite happens. |
+| Python rewrites | derived from `mise.toml` | Enabled when `uv` is declared in `[tools]`. |
+| Package-manager rewrites | derived from `mise.toml` | Enabled only when exactly one of `bun`, `pnpm`, or `npm` is declared in `[tools]`. |
+
+### Examples
+
+Use composed bash integration with an external bash composer:
+
+```json
+{
+  "bash": {
+    "sourceMode": "composed-bash"
+  }
+}
+```
+
+Enable rewrite notifications in global config:
+
+```json
+{
+  "ui": {
+    "showRewriteNotifications": true
+  }
+}
+```
+
+Enable project-level rewrites through `mise.toml`:
+
+```toml
+[tools]
+uv = "latest"
+bun = "1.3.12"
+```
+
+## How It Works
+
+### Rewriters vs Blockers
+
+The extension uses two Pi mechanisms:
+
+1. **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.
+2. **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.
+3. **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.
+
+### Execution Order
+
+1. Guardrails `tool_call` hooks run first (permission gate, env protection)
+2. Toolchain `tool_call` hooks run (blockers, optional rewrite notifications)
+3. If not blocked and at least one feature is in `rewrite` mode, runtime routing depends on `bash.sourceMode`:
+   - `override-bash`: toolchain registers its own bash tool with spawn hook
+   - `composed-bash`: toolchain waits for an external composer to request and compose its spawn hook
+4. Shell executes the rewritten command
+
+### AST-Based Rewriting
+
+All 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.
+
+## Bash Source Mode
+
+`bash.sourceMode` controls how rewrite hooks attach to bash at runtime.
+
+- `override-bash` (default): toolchain registers bash when rewrite is active.
+- `composed-bash`: toolchain contributes its rewrite hook to an external bash composer.
+
+Important:
+
+- Source mode matters only when at least one feature is set to `"rewrite"`.
+- Features set to `"block"` are unaffected.
+- 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.
+- In `composed-bash` mode, rewrites run only if an external composer emits `ad:bash:spawn-hook:request` and collects contributors.
+- If no composer exists, rewrites will not run in `composed-bash` mode by design.
+
+## Migration from Guardrails
+
+If you were using `preventBrew`, `preventPython`, or `enforcePackageManager` in your guardrails config:
+
+1. Install `@carter-mcalister/pi-mise-toolchain`
+2. Add the project tool choices to `mise.toml` (`uv` for Python, exactly one of `bun` / `pnpm` / `npm` for package-manager rewrites)
+3. Optionally configure extension-owned settings in `~/.pi/agent/extensions/toolchain.json`
+4. Remove the deprecated features from your guardrails config
+
+The guardrails extension will continue to honor these features with a deprecation warning until they are removed in a future version.
+
+## Credits
+
+This package is a maintained fork of [`@aliou/pi-toolchain`](https://github.com/aliou/pi-toolchain).
+
+Credit to Aliou for the original project, design, and implementation this fork builds on.
+
+## Development
+
+```bash
+mise install
+bun install
+mise run check
+```

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@carter-mcalister/pi-mise-toolchain",
+  "version": "0.6.2",
+  "description": "Mise-driven toolchain enforcement for Pi",
+  "author": "Carter McAlister",
+  "repository": {
+    "type": "git",
+    "url": "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"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "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
+    }
+  }
+}

package/src/blockers/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Sets up all blocking hooks (tool_call event handlers).
+ *
+ * Blockers run before the spawn hook. A blocked command never reaches
+ * the rewriters. Only features with mode "block" register a blocker.
+ */
+
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent'
+import type { ResolvedToolchainConfig } from '../config'
+import { setupPackageManagerBlocker } from './package-manager'
+import { setupPythonBlocker } from './python'
+
+export function setupBlockers(
+  pi: ExtensionAPI,
+  config: ResolvedToolchainConfig,
+): void {
+  if (config.features.enforcePackageManager === 'block') {
+    setupPackageManagerBlocker(pi, config)
+  }
+  if (config.features.rewritePython === 'block') {
+    setupPythonBlocker(pi)
+  }
+}

package/src/blockers/package-manager.ts

@@ -0,0 +1,62 @@
+/**
+ * Package manager blocker.
+ *
+ * Used when enforcePackageManager is set to "block" instead of "rewrite".
+ * Blocks commands using a non-selected package manager and tells the model
+ * to use the configured one instead.
+ *
+ * Uses AST-based matching. Falls back to regex on parse failure.
+ */
+
+import { parse } from '@aliou/sh'
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent'
+import type { ResolvedToolchainConfig } from '../config'
+import { walkCommands, wordToString } from '../utils/shell-utils'
+
+const ALL_MANAGERS = new Set(['bun', 'pnpm', 'npm', 'npx', 'yarn'])
+
+export function setupPackageManagerBlocker(
+  pi: ExtensionAPI,
+  config: ResolvedToolchainConfig,
+): void {
+  const selected = config.packageManager.selected
+
+  pi.on('tool_call', async (event, ctx) => {
+    if (event.toolName !== 'bash') return
+
+    const command = String(event.input.command ?? '')
+
+    let detected: string | null = null
+    try {
+      const { ast } = parse(command)
+      walkCommands(ast, (cmd) => {
+        const name = cmd.words?.[0] ? wordToString(cmd.words[0]) : undefined
+        if (name && ALL_MANAGERS.has(name) && name !== selected) {
+          detected = name
+          return true
+        }
+        return false
+      })
+    } catch {
+      for (const mgr of ALL_MANAGERS) {
+        if (mgr !== selected && new RegExp(`\\b${mgr}\\b`).test(command)) {
+          detected = mgr
+          break
+        }
+      }
+    }
+
+    if (!detected) return
+
+    ctx.ui.notify(
+      `Blocked ${detected} command. Use ${selected} instead.`,
+      'warning',
+    )
+
+    const reason =
+      `This project uses ${selected} as the package manager. ` +
+      `Replace \`${detected}\` with \`${selected}\` (or \`${selected} dlx\` for npx-style commands).`
+
+    return { block: true, reason }
+  })
+}

package/src/blockers/python.ts

@@ -0,0 +1,61 @@
+/**
+ * Python command blocker.
+ *
+ * Used when rewritePython is set to "block" instead of "rewrite".
+ * Blocks python/pip/poetry/pyenv/virtualenv commands and tells the model
+ * to use uv instead.
+ *
+ * Uses AST-based matching. Falls back to regex on parse failure.
+ */
+
+import { parse } from '@aliou/sh'
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent'
+import { walkCommands, wordToString } from '../utils/shell-utils'
+
+const BLOCKED_COMMANDS = new Set([
+  'python',
+  'python3',
+  'pip',
+  'pip3',
+  'poetry',
+  'pyenv',
+  'virtualenv',
+])
+
+const FALLBACK_PATTERN = /\b(python|python3|pip|pip3|poetry|pyenv|virtualenv)\b/
+
+export function setupPythonBlocker(pi: ExtensionAPI): void {
+  pi.on('tool_call', async (event, ctx) => {
+    if (event.toolName !== 'bash') return
+
+    const command = String(event.input.command ?? '')
+
+    let detected: string | null = null
+    try {
+      const { ast } = parse(command)
+      walkCommands(ast, (cmd) => {
+        const name = cmd.words?.[0] ? wordToString(cmd.words[0]) : undefined
+        if (name && BLOCKED_COMMANDS.has(name)) {
+          detected = name
+          return true
+        }
+        return false
+      })
+    } catch {
+      const match = FALLBACK_PATTERN.exec(command)
+      if (match?.[1]) detected = match[1]
+    }
+
+    if (!detected) return
+
+    ctx.ui.notify(`Blocked ${detected} command. Use uv instead.`, 'warning')
+
+    const reason =
+      'Use uv for Python package management instead. ' +
+      'Run `uv init` to create a new Python project, ' +
+      '`uv run python` to run Python scripts, ' +
+      'or `uv add` to install packages (replaces pip/poetry).'
+
+    return { block: true, reason }
+  })
+}

package/src/commands/settings-command.ts

@@ -0,0 +1,72 @@
+import {
+  registerSettingsCommand,
+  type SettingsSection,
+} from '@aliou/pi-utils-settings'
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent'
+import type {
+  BashSourceMode,
+  FeatureMode,
+  ResolvedExtensionConfig,
+  ToolchainConfig,
+} from '../config'
+import { configLoader } from '../config'
+
+type FeatureKey = keyof ResolvedExtensionConfig['features']
+
+const FEATURE_UI: Record<
+  FeatureKey,
+  { label: string; description: string; modes: FeatureMode[] }
+> = {
+  gitRebaseEditor: {
+    label: 'Git rebase editor',
+    description:
+      'Inject GIT_EDITOR and GIT_SEQUENCE_EDITOR for non-interactive rebase (rewrite only)',
+    modes: ['disabled', 'rewrite'],
+  },
+}
+
+const BASH_SOURCE_MODES: BashSourceMode[] = ['override-bash', 'composed-bash']
+
+export function registerToolchainSettings(pi: ExtensionAPI): void {
+  registerSettingsCommand<ToolchainConfig, ResolvedExtensionConfig>(pi, {
+    commandName: 'toolchain:settings',
+    title: 'Toolchain Settings',
+    configStore: configLoader,
+    buildSections: (
+      tabConfig: ToolchainConfig | null,
+      resolved: ResolvedExtensionConfig,
+      _ctx,
+    ): SettingsSection[] => {
+      const featureItems = (Object.keys(FEATURE_UI) as FeatureKey[]).map(
+        (key) => ({
+          id: `features.${key}`,
+          label: FEATURE_UI[key].label,
+          description: FEATURE_UI[key].description,
+          currentValue: tabConfig?.features?.[key] ?? resolved.features[key],
+          values: FEATURE_UI[key].modes,
+        }),
+      )
+
+      return [
+        {
+          label: 'Features',
+          items: featureItems,
+        },
+        {
+          label: 'Bash Integration',
+          items: [
+            {
+              id: 'bash.sourceMode',
+              label: 'Source mode',
+              description:
+                'override-bash: toolchain registers bash when rewrite is active. composed-bash: toolchain contributes rewrite hook to external bash composer.',
+              currentValue:
+                tabConfig?.bash?.sourceMode ?? resolved.bash.sourceMode,
+              values: [...BASH_SOURCE_MODES],
+            },
+          ],
+        },
+      ]
+    },
+  })
+}