@aliou/pi-guardrails 0.9.5 → 0.11.0

package/README.md

@@ -1,3 +1,5 @@
+![banner](https://assets.aliou.me/pi-extensions/banners/pi-guardrails.png)
+
 # Guardrails
 
 Security hooks for Pi to reduce accidental destructive actions and secret-file access.
@@ -18,10 +20,16 @@ Or from git:
 pi install git:github.com/aliou/pi-guardrails
 ```
 
+## Documentation
+
+- [Default configuration](docs/defaults.md) — built-in policy rules and permission gate patterns
+- [Example presets](docs/examples.md) — pre-configured presets available in settings
+
 ## What it does
 
 - **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.
 
 ## Config locations
@@ -43,7 +51,12 @@ Use `/guardrails:settings` to edit config interactively.
   "enabled": true,
   "features": {
     "policies": true,
-    "permissionGate": true
+    "permissionGate": true,
+    "pathAccess": false
+  },
+  "pathAccess": {
+    "mode": "ask",
+    "allowedPaths": []
   },
   "policies": {
     "rules": [
@@ -116,6 +129,31 @@ Use:
 
 This starts a subagent that helps build and save one policy rule.
 
+## Path access
+
+Restrict tool access to the current working directory. When enabled, any tool call targeting a path outside `cwd` is checked against the configured mode:
+
+- **allow**: no restrictions
+- **ask**: prompt with options to grant access (file or directory, for session or always)
+- **block**: deny all outside access
+
+```jsonc
+{
+  "features": { "pathAccess": true },
+  "pathAccess": {
+    "mode": "ask",
+    "allowedPaths": ["~/code/shared-libs/", "~/.config/myapp"]
+  }
+}
+```
+
+Grants are stored in project config (always) or session memory (session). The `allowedPaths` array is merged across all config scopes.
+
+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`.
+
 ## Permission gate
 
 Detects dangerous bash commands and prompts user confirmation.
@@ -156,6 +194,16 @@ Also note:
 
 - `preventBrew`, `preventPython`, `enforcePackageManager`, `packageManager` were removed from guardrails and moved to `@aliou/pi-toolchain`.
 
+## Development
+
+```bash
+pnpm test         # Run tests
+pnpm test:watch   # Run tests in watch mode
+pnpm typecheck    # Type check
+pnpm lint         # Lint
+pnpm format       # Format
+```
+
 ## Events
 
 Guardrails emits events for other extensions:
@@ -164,7 +212,7 @@ Guardrails emits events for other extensions:
 
 ```ts
 interface GuardrailsBlockedEvent {
-  feature: "policies" | "permissionGate";
+  feature: "policies" | "permissionGate" | "pathAccess";
   toolName: string;
   input: Record<string, unknown>;
   reason: string;
@@ -180,4 +228,4 @@ interface GuardrailsDangerousEvent {
   description: string;
   pattern: string;
 }
-```
+```

package/docs/defaults.md

@@ -0,0 +1,140 @@
+# Default Configuration
+
+These are the built-in defaults that ship with guardrails. Rules marked as disabled are included but inactive by default — enable them in your config or via `/guardrails:settings`.
+
+Source: [`src/config.ts`](../src/config.ts)
+
+
+Home-directory defaults use `~` in patterns. During policy evaluation, guardrails expands `~` to the current user's home directory before checking whether a file exists or should be blocked.
+## Default Policy Rules
+
+### `secret-files` — Files containing secrets
+
+Blocks access to dotenv files and similar secret-bearing files.
+
+| Protection | Only if exists |
+|------------|---------------|
+| `noAccess` | yes           |
+
+**Patterns:**
+
+| Pattern            | Type |
+|--------------------|------|
+| `.env`             | glob |
+| `.env.local`       | glob |
+| `.env.production`  | glob |
+| `.env.prod`        | glob |
+| `.dev.vars`        | glob |
+
+**Allowed exceptions:**
+
+| Pattern            | Type |
+|--------------------|------|
+| `*.example.env`    | glob |
+| `*.sample.env`     | glob |
+| `*.test.env`       | glob |
+| `.env.example`     | glob |
+| `.env.sample`      | glob |
+| `.env.test`        | glob |
+
+---
+
+### `home-ssh` — SSH directory and keys
+
+Blocks access to SSH configuration, private keys, and related files. Disabled by default.
+
+| Protection | Only if exists | Enabled by default |
+|------------|---------------|-------------------|
+| `noAccess` | yes           | no                |
+
+**Patterns:**
+
+| Pattern               | Type |
+|-----------------------|------|
+| `~/.ssh/**`          | glob |
+| `~/.ssh/*_rsa`       | glob |
+| `~/.ssh/*_ed25519`   | glob |
+| `~/.ssh/*.pem`       | glob |
+
+**Allowed exceptions:**
+
+| Pattern  | Type |
+|----------|------|
+| `~/.ssh/*.pub` | glob |
+
+---
+
+### `home-config` — Sensitive user configuration directories
+
+Blocks access to a small set of known sensitive config directories that commonly store credentials, tokens, or encrypted material. Disabled by default — enable it if these tools are installed and you want to protect them.
+
+| Protection | Only if exists | Enabled by default |
+|------------|---------------|-------------------|
+| `noAccess` | yes           | no                |
+
+**Patterns:**
+
+| Pattern               | Type |
+|-----------------------|------|
+| `~/.config/gh/**`     | glob |
+| `~/.config/gcloud/**` | glob |
+| `~/.config/op/**`     | glob |
+| `~/.config/sops/**`   | glob |
+
+---
+
+### `home-gpg` — GPG keys and configuration
+
+Blocks access to GPG/GnuPG private keys, keyrings, and configuration. Disabled by default.
+
+| Protection | Only if exists | Enabled by default |
+|------------|---------------|-------------------|
+| `noAccess` | yes           | no                |
+
+**Patterns:**
+
+| Pattern            | Type |
+|--------------------|------|
+| `~/.gnupg/**`       | glob |
+| `~/*.gpg`           | glob |
+| `~/.gpg-agent.conf` | glob |
+
+---
+
+## Path Access
+
+| Setting | Default |
+|---|---|
+| `features.pathAccess` | `false` |
+| `pathAccess.mode` | `"ask"` |
+| `pathAccess.allowedPaths` | `[]` |
+
+Modes:
+- `allow` — no path restrictions
+- `ask` — prompt when accessing paths outside working directory
+- `block` — deny all access outside working directory
+
+Allowed paths use trailing-slash convention:
+- `/path/to/file` — exact file match
+- `/path/to/dir/` — directory and all descendants
+- Supports `~/` for home directory
+
+Limitations:
+- Bash path extraction is best-effort (AST-based heuristics). Tokens like `application/json` may trigger false-positive prompts.
+- Symlinks are not resolved. Lexical path comparison only.
+- In non-interactive mode (--print), `ask` mode degrades to `block`.
+
+---
+
+## Default Permission Gate Patterns
+
+These commands are detected using AST-based structural matching for accuracy.
+
+| Pattern         | Description                    |
+|-----------------|--------------------------------|
+| `rm -rf`        | Recursive force delete         |
+| `sudo`          | Superuser command              |
+| `dd of=`        | Disk write operation           |
+| `mkfs.`         | Filesystem format              |
+| `chmod -R 777`  | Insecure recursive permissions |
+| `chown -R`      | Recursive ownership change     |

package/docs/examples.md

@@ -0,0 +1,170 @@
+# Example Presets
+
+Pre-configured presets available in the `/guardrails:settings` Examples tab. These can be applied to any config scope (global, local, or memory).
+
+Source: [`src/commands/settings-command.ts`](../src/commands/settings-command.ts)
+
+## File Policy Presets
+
+### Secrets (.env)
+
+Block dotenv-like files using glob patterns.
+
+| Field      | Value                              |
+|------------|------------------------------------|
+| ID         | `example-secret-env-files`         |
+| Protection | `noAccess`                         |
+| Patterns   | `.env`, `.env.*`                   |
+| Exceptions | `.env.example`, `*.sample.env`     |
+
+---
+
+### Logs (*.log)
+
+Mark log files as read-only to prevent accidental modification.
+
+| Field      | Value                     |
+|------------|---------------------------|
+| ID         | `example-log-files`       |
+| Protection | `readOnly`                |
+| Patterns   | `*.log`, `*.out`          |
+
+---
+
+### Regex env
+
+Regex-based matching for `.env` and `.env.*` files. Demonstrates regex mode.
+
+| Field      | Value                                    |
+|------------|------------------------------------------|
+| ID         | `example-regex-env`                      |
+| Protection | `noAccess`                               |
+| Patterns   | `^\.env(\..+)?$` (regex)                 |
+| Exceptions | `^\.env\.example$` (regex)               |
+
+---
+
+### SSH keys
+
+Block access to SSH private key files.
+
+| Field      | Value                                |
+|------------|--------------------------------------|
+| ID         | `example-ssh-keys`                   |
+| Protection | `noAccess`                           |
+| Patterns   | `*.pem`, `*_rsa`, `*_ed25519`       |
+| Exceptions | `*.pub`                              |
+
+---
+
+### AWS credentials
+
+Block AWS CLI credentials and config files.
+
+| Field      | Value                                  |
+|------------|----------------------------------------|
+| ID         | `example-aws-credentials`              |
+| Protection | `noAccess`                             |
+| Patterns   | `.aws/credentials`, `.aws/config`      |
+
+---
+
+### Database files
+
+Mark SQLite and database files as read-only.
+
+| Field      | Value                                  |
+|------------|----------------------------------------|
+| ID         | `example-database-files`               |
+| Protection | `readOnly`                             |
+| Patterns   | `*.db`, `*.sqlite`, `*.sqlite3`        |
+
+---
+
+### Kubernetes secrets
+
+Block kubeconfig and Kubernetes secret files.
+
+| Field      | Value                                  |
+|------------|----------------------------------------|
+| ID         | `example-k8s-secrets`                  |
+| Protection | `noAccess`                             |
+| Patterns   | `.kube/config`, `*kubeconfig*`         |
+
+---
+
+### Certificates
+
+Block SSL/TLS certificate and key files.
+
+| Field      | Value                                  |
+|------------|----------------------------------------|
+| ID         | `example-certificates`                 |
+| Protection | `noAccess`                             |
+| Patterns   | `*.crt`, `*.key`, `*.p12`              |
+| Exceptions | `*.csr`                                |
+
+---
+
+## Dangerous Command Presets
+
+### General
+
+| Label              | Pattern              | Description                            |
+|--------------------|----------------------|----------------------------------------|
+| Homebrew           | `brew`               | Homebrew package manager               |
+| git push --force   | `git push --force`   | Git force push                         |
+| npm publish        | `npm publish`        | NPM package publishing                 |
+| yarn publish       | `yarn publish`       | Yarn package publishing                |
+| pnpm publish       | `pnpm publish`       | PNPM package publishing                |
+| drop database      | `DROP DATABASE`      | SQL database drop                      |
+| drop table         | `DROP TABLE`         | SQL table drop                         |
+
+### dbt
+
+| Label    | Pattern    | Description            |
+|----------|------------|------------------------|
+| dbt run  | `dbt run`  | dbt model execution    |
+| dbt seed | `dbt seed` | dbt seed data loading  |
+
+### AWS
+
+| Label                | Pattern                        | Description                  |
+|----------------------|--------------------------------|------------------------------|
+| aws s3 rm            | `aws s3 rm`                    | AWS S3 object deletion       |
+| aws iam              | `aws iam`                      | AWS IAM permission changes   |
+| aws ec2 terminate    | `aws ec2 terminate-instances`  | AWS EC2 instance termination |
+
+### Kubernetes
+
+| Label          | Pattern          | Description                    |
+|----------------|------------------|--------------------------------|
+| kubectl delete | `kubectl delete` | Kubernetes resource deletion   |
+| kubectl apply  | `kubectl apply`  | Kubernetes resource application|
+| kubectl scale  | `kubectl scale`  | Kubernetes scaling operation   |
+
+### Docker
+
+| Label                | Pattern                | Description                              |
+|----------------------|------------------------|------------------------------------------|
+| Docker secrets       | `docker inspect`       | Docker inspect (may expose env vars)     |
+| docker rm            | `docker rm`            | Docker container removal                 |
+| docker rmi           | `docker rmi`           | Docker image removal                     |
+| docker system prune  | `docker system prune`  | Docker system cleanup                    |
+| docker compose down  | `docker compose down`  | Docker Compose service teardown          |
+
+### Terraform
+
+| Label              | Pattern              | Description                        |
+|--------------------|----------------------|------------------------------------|
+| Terraform apply    | `terraform apply`    | Terraform infrastructure changes   |
+| Terraform destroy  | `terraform destroy`  | Terraform infrastructure destruction|
+| terraform import   | `terraform import`   | Terraform resource import          |
+
+### Google Cloud
+
+| Label                  | Pattern                            | Description                      |
+|------------------------|------------------------------------|----------------------------------|
+| gcloud compute delete  | `gcloud compute instances delete`  | GCP compute instance deletion    |
+| gcloud iam             | `gcloud iam`                       | GCP IAM permission changes       |
+| gcloud sql delete      | `gcloud sql instances delete`      | GCP Cloud SQL instance deletion  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.9.5",
+  "version": "0.11.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -26,10 +26,11 @@
   },
   "files": [
     "src",
+    "docs",
     "README.md"
   ],
   "dependencies": {
-    "@aliou/pi-utils-settings": "^0.10.1",
+    "@aliou/pi-utils-settings": "^0.11.2",
     "@aliou/sh": "^0.1.0"
   },
   "peerDependencies": {
@@ -48,7 +49,8 @@
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-agent-core": {
@@ -66,6 +68,8 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "biome check",
     "format": "biome check --write",
     "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",

package/src/commands/onboarding-command.ts

@@ -0,0 +1,76 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { configLoader, type GuardrailsConfig } from "../config";
+import {
+  buildOnboardedConfig,
+  createOnboardingWizard,
+  isOnboardingPending,
+  type OnboardingResult,
+} from "./onboarding";
+
+function mergeOnboarding(
+  base: GuardrailsConfig | null,
+  applyBuiltinDefaults: boolean,
+  pathAccessEnabled?: boolean | null,
+): GuardrailsConfig {
+  const next = structuredClone(base ?? {});
+  const onboarded = buildOnboardedConfig(
+    applyBuiltinDefaults,
+    pathAccessEnabled,
+  );
+  next.applyBuiltinDefaults = onboarded.applyBuiltinDefaults;
+  next.version = onboarded.version;
+  next.onboarding = onboarded.onboarding;
+  if (onboarded.features?.pathAccess !== undefined) {
+    next.features = {
+      ...next.features,
+      pathAccess: onboarded.features.pathAccess,
+    };
+  }
+  if (onboarded.pathAccess) {
+    next.pathAccess = onboarded.pathAccess;
+  }
+  return next;
+}
+
+export function registerGuardrailsOnboardingCommand(
+  pi: ExtensionAPI,
+  onCompleted?: () => void,
+): void {
+  pi.registerCommand("guardrails:onboarding", {
+    description: "Run guardrails onboarding",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+
+      const globalConfig = configLoader.getRawConfig("global");
+      if (!isOnboardingPending(globalConfig)) {
+        ctx.ui.notify(
+          "[Guardrails] onboarding already completed. Use /guardrails:settings to update behavior.",
+          "info",
+        );
+        return;
+      }
+
+      const result = await ctx.ui.custom<OnboardingResult>(
+        (_tui, theme, _keybindings, done) =>
+          createOnboardingWizard(theme, done),
+        { overlay: true },
+      );
+
+      if (!result.completed || result.applyBuiltinDefaults === null) {
+        ctx.ui.notify("[Guardrails] onboarding cancelled.", "warning");
+        return;
+      }
+
+      const merged = mergeOnboarding(
+        globalConfig,
+        result.applyBuiltinDefaults,
+        result.pathAccessEnabled,
+      );
+      await configLoader.save("global", merged);
+      await configLoader.load();
+
+      onCompleted?.();
+      ctx.ui.notify("[Guardrails] onboarding completed.", "info");
+    },
+  });
+}