@aliou/pi-guardrails 0.9.4 → 0.10.0

package/README.md

@@ -18,6 +18,11 @@ 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.

package/docs/defaults.md

@@ -0,0 +1,115 @@
+# 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 |
+
+---
+
+## 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 if=`        | 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.4",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -26,25 +26,26 @@
   },
   "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": {
-    "@mariozechner/pi-agent-core": ">=0.52.7",
-    "@mariozechner/pi-ai": ">=0.52.7",
-    "@mariozechner/pi-coding-agent": ">=0.52.7",
-    "@mariozechner/pi-tui": ">=0.51.0"
+    "@mariozechner/pi-agent-core": "0.61.0",
+    "@mariozechner/pi-ai": "0.61.0",
+    "@mariozechner/pi-coding-agent": "0.61.0",
+    "@mariozechner/pi-tui": "0.61.0"
   },
   "devDependencies": {
     "@aliou/biome-plugins": "^0.3.2",
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-agent-core": "0.52.7",
-    "@mariozechner/pi-ai": "0.52.7",
-    "@mariozechner/pi-coding-agent": "0.52.7",
+    "@mariozechner/pi-agent-core": "0.61.0",
+    "@mariozechner/pi-ai": "0.61.0",
+    "@mariozechner/pi-coding-agent": "0.61.0",
     "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",

package/src/commands/onboarding-command.ts

@@ -0,0 +1,59 @@
+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,
+): GuardrailsConfig {
+  const next = structuredClone(base ?? {});
+  const onboarded = buildOnboardedConfig(applyBuiltinDefaults);
+  next.applyBuiltinDefaults = onboarded.applyBuiltinDefaults;
+  next.version = onboarded.version;
+  next.onboarding = onboarded.onboarding;
+  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);
+      await configLoader.save("global", merged);
+      await configLoader.load();
+
+      onCompleted?.();
+      ctx.ui.notify("[Guardrails] onboarding completed.", "info");
+    },
+  });
+}

package/src/commands/onboarding.ts

@@ -0,0 +1,274 @@
+import {
+  getSettingsTheme,
+  type SettingsTheme,
+  Wizard,
+} from "@aliou/pi-utils-settings";
+import { getMarkdownTheme, type Theme } from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import { Box, Key, Markdown, matchesKey, Text } from "@mariozechner/pi-tui";
+import type { GuardrailsConfig } from "../config";
+import { CURRENT_VERSION } from "../utils/migration";
+
+interface OnboardingState {
+  applyBuiltinDefaults: boolean | null;
+}
+
+export interface OnboardingResult {
+  completed: boolean;
+  applyBuiltinDefaults: boolean | null;
+}
+
+class IntroStep implements Component {
+  private readonly introText = new Text("", 2, 0);
+
+  constructor(private readonly onNext: () => void) {}
+
+  invalidate() {
+    this.introText.invalidate();
+  }
+
+  render(width: number): string[] {
+    this.introText.setText(
+      "Guardrails helps prevent accidental exposure of secrets and risky actions.\n\nIt gives you two protections:\n- Policies: file access rules (`noAccess` or `readOnly`)\n- Permission gate: confirmation before dangerous commands run\n\nYou are choosing the starting defaults now. You can change them later in `/guardrails:settings`.",
+    );
+
+    return [
+      "  Welcome to Guardrails",
+      "",
+      ...this.introText.render(Math.max(1, width)),
+    ];
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.enter)) {
+      this.onNext();
+    }
+  }
+}
+
+class DefaultsChoiceStep implements Component {
+  private selectedIndex = 0;
+  private readonly settingsTheme: SettingsTheme;
+
+  constructor(
+    private readonly theme: Theme,
+    private readonly state: OnboardingState,
+    private readonly onSelect: () => void,
+  ) {
+    this.settingsTheme = getSettingsTheme(theme);
+  }
+
+  invalidate() {}
+
+  render(width: number): string[] {
+    const options = ["Recommended defaults", "Minimal setup"];
+    const explanations = [
+      [
+        "Use built-ins for common safety needs:",
+        "",
+        "- Protect secret files like `.env`, `.env.local`, `.env.production`, and `.dev.vars`",
+        "- Keep safe exceptions like `.env.example` and `*.sample.env`",
+        "- Require confirmation before running dangerous commands like `rm -rf`, `sudo`, and `dd if=`",
+      ].join("\n"),
+      [
+        "Start with no built-in file policy defaults.",
+        "",
+        "- Configure your own policies in `/guardrails:settings`",
+        "- Browse policy and command examples in `/guardrails:settings`",
+      ].join("\n"),
+    ];
+
+    const lines: string[] = [
+      "  Pick how much built-in protection to start with.",
+      "",
+    ];
+
+    for (let i = 0; i < options.length; i++) {
+      const option = options[i];
+      if (!option) continue;
+      const selected = i === this.selectedIndex;
+      const prefix = selected ? this.settingsTheme.cursor : "  ";
+      const label = this.settingsTheme.value(` ${option}`, selected);
+      lines.push(`${prefix}${label}`);
+    }
+
+    lines.push("");
+
+    const explanationBox = new Box(1, 0, (s: string) => s);
+    explanationBox.addChild(
+      new Markdown(
+        explanations[this.selectedIndex] ?? "",
+        0,
+        0,
+        getMarkdownTheme(),
+        {
+          color: (s: string) => this.theme.fg("text", s),
+        },
+      ),
+    );
+
+    lines.push(...explanationBox.render(Math.max(1, width)));
+
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.selectedIndex = this.selectedIndex === 0 ? 1 : 0;
+      return;
+    }
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.selectedIndex = this.selectedIndex === 1 ? 0 : 1;
+      return;
+    }
+
+    if (matchesKey(data, Key.enter)) {
+      this.state.applyBuiltinDefaults = this.selectedIndex === 0;
+      this.onSelect();
+    }
+  }
+}
+
+class FinishStep implements Component {
+  private readonly recapMarkdown = new Markdown("", 2, 0, getMarkdownTheme());
+
+  constructor(
+    private readonly state: OnboardingState,
+    private readonly onFinish: () => void,
+  ) {}
+
+  invalidate() {
+    this.recapMarkdown.invalidate();
+  }
+
+  render(width: number): string[] {
+    const content =
+      this.state.applyBuiltinDefaults === true
+        ? [
+            "You selected **Recommended defaults**.",
+            "",
+            "Guardrails will start with built-in protection, including:",
+            "- secret files like `.env`, `.env.local`, `.env.production`, `.dev.vars`",
+            "- safe exceptions like `.env.example` and `*.sample.env`",
+            "- confirmation before running dangerous commands like `rm -rf`, `sudo`, `dd if=`",
+          ].join("\n")
+        : [
+            "You selected **Minimal setup**.",
+            "",
+            "No built-in file policy defaults will be applied.",
+            "",
+            "You can configure policies later with `/guardrails:settings`.",
+          ].join("\n");
+
+    this.recapMarkdown.setText(content);
+    return [...this.recapMarkdown.render(Math.max(1, width)), ""];
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.enter)) {
+      this.onFinish();
+    }
+  }
+}
+
+export function createOnboardingWizard(
+  theme: Theme,
+  done: (result: OnboardingResult) => void,
+): Component {
+  const state: OnboardingState = {
+    applyBuiltinDefaults: null,
+  };
+
+  let markWelcomeComplete: (() => void) | null = null;
+  let settled = false;
+
+  const finalize = (result: OnboardingResult) => {
+    if (settled) return;
+    settled = true;
+    done(result);
+  };
+
+  const wizard = new Wizard({
+    title: "Guardrails onboarding",
+    theme,
+    steps: [
+      {
+        label: "Welcome",
+        build: (ctx) => {
+          markWelcomeComplete = ctx.markComplete;
+          return new IntroStep(() => {
+            ctx.markComplete();
+            ctx.goNext();
+          });
+        },
+      },
+      {
+        label: "Defaults",
+        build: (ctx) =>
+          new DefaultsChoiceStep(theme, state, () => {
+            ctx.markComplete();
+            ctx.goNext();
+          }),
+      },
+      {
+        label: "Recap",
+        build: (ctx) =>
+          new FinishStep(state, () => {
+            if (state.applyBuiltinDefaults === null) return;
+            ctx.markComplete();
+            finalize({
+              completed: true,
+              applyBuiltinDefaults: state.applyBuiltinDefaults,
+            });
+          }),
+      },
+    ],
+    onComplete: () => {
+      if (state.applyBuiltinDefaults === null) {
+        finalize({ completed: false, applyBuiltinDefaults: null });
+        return;
+      }
+      finalize({
+        completed: true,
+        applyBuiltinDefaults: state.applyBuiltinDefaults,
+      });
+    },
+    onCancel: () => finalize({ completed: false, applyBuiltinDefaults: null }),
+    hintSuffix: "Enter select/continue",
+    minContentHeight: 12,
+  });
+
+  return {
+    render: (width) => wizard.render(width),
+    invalidate: () => wizard.invalidate(),
+    handleInput: (data: string) => {
+      if (
+        matchesKey(data, Key.tab) &&
+        wizard.getActiveIndex() === 0 &&
+        markWelcomeComplete
+      ) {
+        markWelcomeComplete();
+      }
+      wizard.handleInput(data);
+    },
+  };
+}
+
+export function buildOnboardedConfig(
+  applyBuiltinDefaults: boolean,
+): GuardrailsConfig {
+  return {
+    version: CURRENT_VERSION,
+    applyBuiltinDefaults,
+    onboarding: {
+      completed: true,
+      completedAt: new Date().toISOString(),
+      version: CURRENT_VERSION,
+    },
+  };
+}
+
+export function isOnboardingPending(config: GuardrailsConfig | null): boolean {
+  if (!config) return true;
+  return config.onboarding?.completed !== true;
+}