@aliou/pi-guardrails 0.11.2 → 0.12.0

package/README.md

@@ -2,11 +2,13 @@
 
 # Guardrails
 
-Security hooks for Pi to reduce accidental destructive actions and secret-file access.
+Guardrails adds safety checks to Pi so agents are less likely to read secrets, write protected files, access paths outside the workspace, or run dangerous shell commands by accident.
 
-## Demo
+This package installs three Pi extensions:
 
-<video src="https://assets.aliou.me/pi-extensions/demos/pi-guardrails.mp4" controls playsinline muted></video>
+- **guardrails** for file protection policies, settings, onboarding, and examples.
+- **path-access** for controlling access outside the current workspace.
+- **permission-gate** for confirming or blocking risky shell commands.
 
 ## Install
 
@@ -14,185 +16,112 @@ Security hooks for Pi to reduce accidental destructive actions and secret-file a
 pi install npm:@aliou/pi-guardrails
 ```
 
-Or from git:
+## First run
 
-```bash
-pi install git:github.com/aliou/pi-guardrails
+After installing, run the onboarding command to choose a starting setup:
+
+```text
+/guardrails:onboarding
 ```
 
-## Documentation
+![Guardrails onboarding walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/onboarding.gif)
 
-- [Default configuration](docs/defaults.md) — built-in policy rules and permission gate patterns
-- [Example presets](docs/examples.md) — pre-configured presets available in settings
+You can change everything later with:
 
-## What it does
+```text
+/guardrails:settings
+```
 
-- **policies**: named file-protection rules with per-rule protection levels.
-- **permission-gate**: detects dangerous bash commands and asks for confirmation.
-- **path-access**: restricts tool access to the current working directory with allow/ask/block modes.
-- **optional command explainer**: can call a small LLM to explain a dangerous command inline in the confirmation dialog.
+## Included extensions
 
-## Config locations
+### guardrails
 
-Guardrails reads and merges config from:
+The `guardrails` extension owns file protection policies and the user-facing commands.
 
-- Global: `~/.pi/agent/extensions/guardrails.json`
-- Project: `.pi/extensions/guardrails.json`
-- Memory (session): internal temporary scope used by settings/commands
-
-Priority: `memory > local > global > defaults`.
-
-Use `/guardrails:settings` to edit config interactively.
-
-## Current schema
-
-```json
-{
-  "enabled": true,
-  "features": {
-    "policies": true,
-    "permissionGate": true,
-    "pathAccess": false
-  },
-  "pathAccess": {
-    "mode": "ask",
-    "allowedPaths": []
-  },
-  "policies": {
-    "rules": [
-      {
-        "id": "secret-files",
-        "description": "Files containing secrets",
-        "patterns": [
-          { "pattern": ".env" },
-          { "pattern": ".env.local" },
-          { "pattern": ".env.production" },
-          { "pattern": ".env.prod" },
-          { "pattern": ".dev.vars" }
-        ],
-        "allowedPatterns": [
-          { "pattern": ".env.example" },
-          { "pattern": ".env.sample" },
-          { "pattern": ".env.test" },
-          { "pattern": "*.example.env" },
-          { "pattern": "*.sample.env" },
-          { "pattern": "*.test.env" }
-        ],
-        "protection": "noAccess",
-        "onlyIfExists": true
-      }
-    ]
-  },
-  "permissionGate": {
-    "patterns": [
-      { "pattern": "rm -rf", "description": "recursive force delete" },
-      { "pattern": "sudo", "description": "superuser command" }
-    ],
-    "customPatterns": [],
-    "requireConfirmation": true,
-    "allowedPatterns": [],
-    "autoDenyPatterns": [],
-    "explainCommands": false,
-    "explainModel": null,
-    "explainTimeout": 5000
-  }
-}
-```
+Use it to protect files like `.env`, private keys, local credentials, generated logs, database dumps, or any project-specific path you do not want Pi to read or modify without clear intent.
+
+![Guardrails policies and settings walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/policies.gif)
 
-All fields optional. Missing fields use defaults.
+Useful commands:
 
-## Policies
+```text
+/guardrails:settings
+/guardrails:onboarding
+/guardrails:examples
+```
 
-Each rule has:
+### path-access
 
-- `id`: stable identifier used for overrides across scopes.
-- `patterns`: files to match (glob by default, regex if `regex: true`). Glob semantics: patterns containing `/` match the full relative path; patterns without `/` match basename only.
-- `allowedPatterns`: exceptions.
-- `protection`:
-  - `noAccess`: block `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
-  - `readOnly`: block `write`, `edit`, `bash`
-  - `none`: explicit no protection
-- `onlyIfExists` (default true)
-- `blockMessage` with `{file}` placeholder
-- `enabled` (default true)
+The `path-access` extension checks tool calls that target paths outside the current working directory.
 
-When multiple rules match the same file, strongest protection wins:
-`noAccess > readOnly > none`.
+It can allow, block, or ask before Pi accesses files elsewhere on your machine. In ask mode, you can allow one file or a directory once, for the session, or always.
 
-### Add rule with AI
+![Guardrails path access prompt walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/path-access.gif)
 
-Use:
+### permission-gate
 
-```text
-/guardrails:add-policy
-```
+The `permission-gate` extension detects dangerous bash commands before they run.
 
-This starts a subagent that helps build and save one policy rule.
+It catches built-in risky patterns like recursive deletes, privileged commands, disk formatting, broad permission changes, and configured custom patterns. You can allow once, allow for the session, deny, or configure auto-deny rules.
 
-## Path access
+![Guardrails permission gate walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/permission-gate.gif)
 
-Restrict tool access to the current working directory. When enabled, any tool call targeting a path outside `cwd` is checked against the configured mode:
+## Configuration
 
-- **allow**: no restrictions
-- **ask**: prompt with options to grant access (file or directory, for session or always)
-- **block**: deny all outside access
+Most configuration should happen through the interactive settings UI:
 
-```jsonc
-{
-  "features": { "pathAccess": true },
-  "pathAccess": {
-    "mode": "ask",
-    "allowedPaths": ["~/code/shared-libs/", "~/.config/myapp"]
-  }
-}
+```text
+/guardrails:settings
 ```
 
-Grants are stored in project config (always) or session memory (session). The `allowedPaths` array is merged across all config scopes.
+Advanced users can edit the settings file directly:
 
-Limitations:
-- Symlinks are not resolved (lexical path comparison only).
-- Bash path extraction is best-effort (AST-based heuristics).
-- In non-interactive mode, `ask` mode degrades to `block`.
+- Global: `~/.pi/agent/extensions/guardrails.json`
+- Project: `.pi/extensions/guardrails.json`
 
-## Permission gate
+Guardrails writes a `$schema` field to saved settings files, so modern editors provide autocomplete and validation. The generated schema is committed at [`schema.json`](schema.json).
 
-Detects dangerous bash commands and prompts user confirmation.
+## Examples
 
-Built-in dangerous patterns are matched structurally (AST-based) for better accuracy:
+Use the examples command to add common policy and command presets without replacing your existing config:
 
-- `rm -rf`
-- `sudo`
-- `dd if=`
-- `mkfs.`
-- `chmod -R 777`
-- `chown -R`
+```text
+/guardrails:examples
+```
 
-You can also add custom dangerous patterns.
+![Guardrails examples command walkthrough](https://assets.aliou.me/pi-extensions/demos/guardrails/v0.12.0/examples.gif)
 
-### Explain commands (opt-in)
+The available presets live in [`extensions/guardrails/commands/settings/examples.ts`](extensions/guardrails/commands/settings/examples.ts).
 
-If enabled, guardrails calls an LLM before showing the confirmation dialog and displays a short explanation.
+## Similar but different
 
-Config fields:
+Pi is designed to make agent safety extensible. Guardrails focuses on deterministic, configurable file policies, outside-workspace path access, and dangerous-command prompts. Other packages tend to fall into two useful groups.
 
-- `permissionGate.explainCommands` (boolean)
-- `permissionGate.explainModel` (`provider/model-id`)
-- `permissionGate.explainTimeout` (ms)
+### Make one yourself!
 
-Failures/timeouts degrade gracefully: dialog still shows without explanation.
+If Guardrails or the alternatives below do not fit your needs, you can also make your own. Start from the [Pi permission gate example](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/permission-gate.ts), then ask Pi to customize it for your workflow.
 
-## Migration notes
+### Permission and policy gates
 
-Legacy fields are auto-migrated:
+These packages add checks around tool calls before they run. They are closest to Guardrails when you want policy enforcement without changing where Pi executes.
 
-- `features.protectEnvFiles` -> `features.policies`
-- `envFiles` -> `policies.rules` (migrated into `secret-files`)
+- [@gotgenes/pi-permission-system](https://pi.dev/packages/%40gotgenes/pi-permission-system): broad permission enforcement for Pi tool calls.
+- [@vtstech/pi-security](https://pi.dev/packages/%40vtstech/pi-security): command, path, network, mode, and audit controls.
+- [pi-control](https://github.com/mcowger/pi-control/blob/main/README.md): location-scoped, action-based policies for tool calls, with allow, log, ask, and deny outcomes before execution.
+- [@casualjim/pi-heimdall](https://pi.dev/packages/%40casualjim/pi-heimdall): secret exposure guards, command policies, protected `.env` files, and a sandbox guard.
+- [pi-file-permissions](https://pi.dev/packages/pi-file-permissions): file-level permissions for read, write, edit, find, grep, and ls tools.
+- [pi-secret-guard](https://pi.dev/packages/pi-secret-guard): focused protection against committing or pushing secrets to git.
 
-`config.version` is a schema marker, not npm package version.
+### Sandboxes and containment
 
-Also note:
+These packages reduce blast radius by running Pi, subagents, or tool calls inside a constrained environment. They can be a better fit when you want isolation first and prompts second.
 
-- `preventBrew`, `preventPython`, `enforcePackageManager`, `packageManager` were removed from guardrails and moved to `@aliou/pi-toolchain`.
+- [Pi + Gondolin sandbox example](https://github.com/earendil-works/gondolin/blob/main/host/examples/pi-gondolin.ts): upstream example that runs Pi tools inside a Gondolin micro-VM.
+- [pi-sandbox](https://pi.dev/packages/pi-sandbox): OS-level sandboxing for bash, with allow/deny checks and prompts for file tools.
+- [pi-container-sandbox](https://pi.dev/packages/pi-container-sandbox): runs read, write, edit, bash, and user bash operations inside a Docker or Apple container session.
+- [@alexanderfortin/pi-freestyle-sandbox](https://pi.dev/packages/%40alexanderfortin/pi-freestyle-sandbox): runs sandboxed subagents in Freestyle cloud VMs.
+- [@the-agency/vmpi](https://pi.dev/packages/%40the-agency/vmpi): runs Pi inside a QEMU microVM with limited filesystem and network access.
+- [pi-claude-sandbox](https://pi.dev/packages/pi-claude-sandbox): Claude-style OS sandboxing with interactive permission prompts.
 
 ## Development
 
@@ -202,30 +131,6 @@ pnpm test:watch   # Run tests in watch mode
 pnpm typecheck    # Type check
 pnpm lint         # Lint
 pnpm format       # Format
+pnpm gen:schema   # Regenerate schema.json
+pnpm check:schema # Verify schema.json is current
 ```
-
-## Events
-
-Guardrails emits events for other extensions:
-
-### `guardrails:blocked`
-
-```ts
-interface GuardrailsBlockedEvent {
-  feature: "policies" | "permissionGate" | "pathAccess";
-  toolName: string;
-  input: Record<string, unknown>;
-  reason: string;
-  userDenied?: boolean;
-}
-```
-
-### `guardrails:dangerous`
-
-```ts
-interface GuardrailsDangerousEvent {
-  command: string;
-  description: string;
-  pattern: string;
-}
-```