@zeldrisho/pi-gate 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-25
+
+### Added
+
+- gate bash tool calls against a user-provided JSON configuration
+- ship without any default rules and notify the user to configure after install
+- write a `pi-gate.json.example` next to the config on first run
+- support `prompt`, `block`, and `allow` actions, with longest-pattern-wins resolution
+- block rather than auto-approve in non-UI modes
+
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.1.0...HEAD
+[0.1.0]: https://github.com/zeldrisho/pi-packages/releases/tag/pi-gate-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeldris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @zeldrisho/pi-gate
+
+Pi extension that blocks or confirms bash tool calls based on a user-provided JSON configuration.
+
+## Install
+
+```bash
+pi install npm:@zeldrisho/pi-gate
+```
+
+Install only for the current project:
+
+```bash
+pi install -l npm:@zeldrisho/pi-gate
+```
+
+## Configure
+
+The extension ships with **no default rules**. On first load, an example configuration is written to `~/.pi/agent/pi-gate.json.example` and a warning notifies you that no configuration is active. Every bash command is allowed until you create a configuration.
+
+Copy the example and edit it:
+
+```bash
+cp ~/.pi/agent/pi-gate.json.example ~/.pi/agent/pi-gate.json
+```
+
+Then edit `~/.pi/agent/pi-gate.json` to add your rules. Each rule is a substring pattern and one of three actions:
+
+- `prompt` — ask the user to allow or deny the command
+- `block` — deny the command without asking
+- `allow` — explicitly allow (use to carve out an exception to a broader rule)
+
+```json
+{
+  "operations": {
+    "rm -rf": "prompt",
+    "sudo": "prompt",
+    "chmod 777": "block",
+    "corepack enable": "block"
+  }
+}
+```
+
+Patterns use simple substring matching. When several patterns match the same command, the longest pattern wins, so a narrow `allow` rule can override a broader `block` or `prompt` rule.
+
+After editing, run `/reload` to apply the new rules in the current session.
+
+## Behavior
+
+- Only the built-in `bash` tool is gated. Other tools pass through unchanged.
+- `prompt` rules ask the user with a two-button confirmation (`Allow` / `Deny`).
+- `block` rules never ask and always deny.
+- `allow` rules are explicit pass-throughs, useful for carving out exceptions.
+- In non-interactive modes (`-p`, JSON), `prompt` and `block` rules both block the command instead of auto-approving.
+
+## Uninstall
+
+```bash
+pi remove npm:@zeldrisho/pi-gate
+```
+
+For a project-local installation:
+
+```bash
+pi remove -l npm:@zeldrisho/pi-gate
+```
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@zeldrisho/pi-gate",
+  "version": "0.0.0",
+  "description": "Pi extension that blocks or confirms bash commands based on a user-provided JSON configuration",
+  "keywords": [
+    "command-blocking",
+    "command-confirmation",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "tool-gate"
+  ],
+  "homepage": "https://github.com/zeldrisho/pi-packages/tree/main/packages/pi-gate#readme",
+  "bugs": {
+    "url": "https://github.com/zeldrisho/pi-packages/issues"
+  },
+  "license": "MIT",
+  "author": "Zeldris",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zeldrisho/pi-packages.git",
+    "directory": "packages/pi-gate"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
+    "vite-plus": "0.3.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "vp check",
+    "test": "vp test",
+    "test:watch": "vp test --watch",
+    "lint": "vp lint",
+    "lint:fix": "vp lint --fix",
+    "format": "vp fmt --write",
+    "typecheck": "vp check --no-fmt --no-lint"
+  }
+}

package/src/index.ts

@@ -0,0 +1,223 @@
+/**
+ * pi-gate Extension
+ *
+ * Intercepts the built-in `bash` tool and gates each command against a
+ * user-provided JSON configuration. Without a configuration file, every
+ * command is allowed and the extension posts a warning on `session_start`
+ * reminding the user to create one.
+ *
+ * Configuration file: `~/.pi/agent/pi-gate.json`
+ *
+ * The configuration has a single section, `operations`, which maps a
+ * substring pattern to one of three actions:
+ *
+ * - `prompt` - ask the user to allow or deny the command
+ * - `block`  - deny the command without asking
+ * - `allow`  - explicitly allow (use to carve out an exception)
+ *
+ * When multiple patterns match a command, the longest pattern wins, so a
+ * narrow `allow` rule can override a broader `prompt` or `block` rule.
+ *
+ * On first run, an example configuration is written next to the real one
+ * at `~/.pi/agent/pi-gate.json.example` to document the format.
+ *
+ * Non-UI modes (print, JSON) never auto-approve. A `prompt` or `block` rule
+ * in non-UI mode always blocks the command.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type Action = "prompt" | "block" | "allow";
+
+export interface GateConfig {
+  operations: Record<string, Action>;
+}
+
+const CONFIG_FILE_NAME = "pi-gate.json";
+const EXAMPLE_FILE_NAME = "pi-gate.json.example";
+const ACTIONS: readonly Action[] = ["prompt", "block", "allow"] as const;
+
+const EXAMPLE_CONFIG: GateConfig = {
+  operations: {
+    "rm -rf": "prompt",
+    sudo: "prompt",
+    "chmod 777": "block",
+  },
+};
+
+function agentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+function configPath(): string {
+  return join(agentDir(), CONFIG_FILE_NAME);
+}
+
+function examplePath(): string {
+  return join(agentDir(), EXAMPLE_FILE_NAME);
+}
+
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- type-guard helper intentionally narrows untrusted JSON values at the parse boundary
+function isAction(value: unknown): value is Action {
+  return (
+    typeof value === "string" &&
+    // SAFETY: ACTIONS is the source-of-truth tuple of supported action strings; widening
+    // it to readonly string[] lets Array.prototype.includes perform a runtime check
+    // before the type predicate narrows the value to Action.
+    (ACTIONS as readonly string[]).includes(value)
+  );
+}
+
+// oxlint-disable-next-line anti-slop/no-unknown-parameters, anti-slop/no-unsafe-dictionary-type -- type-guard helper intentionally narrows untrusted JSON values at the parse boundary
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parses the user configuration file. Returns an empty configuration (no
+ * rules) when the file is missing, unreadable, malformed, or fails
+ * validation; an explicit empty `operations` object is also valid.
+ *
+ * Invalid entries are skipped so a single bad rule does not disable the
+ * entire gate; parsing continues for the remaining rules.
+ */
+export function parseConfig(content: string): GateConfig {
+  const rules: Record<string, Action> = {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { operations: rules };
+  }
+  if (!isJsonObject(parsed)) {
+    return { operations: rules };
+  }
+  const operations = parsed["operations"];
+  if (!isJsonObject(operations)) {
+    return { operations: rules };
+  }
+  for (const [pattern, action] of Object.entries(operations)) {
+    if (isAction(action)) {
+      rules[pattern] = action;
+    }
+  }
+  return { operations: rules };
+}
+
+/**
+ * Loads the configuration from disk. Returns an empty configuration when the
+ * file is missing; returns the parsed configuration otherwise.
+ */
+export function loadConfig(): GateConfig {
+  const path = configPath();
+  if (!existsSync(path)) {
+    return { operations: {} };
+  }
+  let content: string;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return { operations: {} };
+  }
+  return parseConfig(content);
+}
+
+/**
+ * Writes the example configuration next to the real one. Existing example
+ * files are left alone so the user can rely on them to track the latest
+ * supported shape.
+ */
+export function ensureExampleConfig(): void {
+  const path = examplePath();
+  if (existsSync(path)) return;
+  try {
+    mkdirSync(agentDir(), { recursive: true });
+  } catch {
+    return;
+  }
+  const example = JSON.stringify(EXAMPLE_CONFIG, null, 2) + "\n";
+  try {
+    writeFileSync(path, example, "utf-8");
+  } catch {
+    // Best-effort: the warning banner still surfaces the missing config.
+  }
+}
+
+/**
+ * Resolves the action that applies to a command against the configured rules.
+ *
+ * Returns `null` when no rule matches, in which case the caller should let the
+ * command through. When multiple rules match, the longest pattern wins so
+ * that narrow rules can override broader ones.
+ */
+export function resolveAction(command: string, rules: Record<string, Action>): Action | null {
+  let bestPattern: string | null = null;
+  for (const pattern of Object.keys(rules)) {
+    if (!command.includes(pattern)) continue;
+    if (bestPattern === null || pattern.length > bestPattern.length) {
+      bestPattern = pattern;
+    }
+  }
+  if (bestPattern === null) return null;
+  return rules[bestPattern];
+}
+
+/** Gate the built-in `bash` tool against the user-provided rules. */
+export default function piGate(pi: ExtensionAPI): void {
+  ensureExampleConfig();
+  const config = loadConfig();
+
+  pi.on("session_start", (_event, ctx) => {
+    const path = configPath();
+    const ruleCount = Object.keys(config.operations).length;
+    if (existsSync(path)) {
+      if (ruleCount === 0) {
+        ctx.ui.notify(
+          `pi-gate: ${path} is empty; no commands are gated. Add rules to the "operations" object to start gating.`,
+          "warning",
+        );
+      } else {
+        ctx.ui.notify(
+          `pi-gate: ${ruleCount} operation rule${ruleCount === 1 ? "" : "s"} loaded from ${path}`,
+          "info",
+        );
+      }
+    } else {
+      ctx.ui.notify(
+        `pi-gate: no configuration found at ${path}; all commands are allowed. Copy ${examplePath()} to ${path} to start gating.`,
+        "warning",
+      );
+    }
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName !== "bash") return undefined;
+    if (!isToolCallEventType("bash", event)) return undefined;
+    const command = event.input.command;
+    const action = resolveAction(command, config.operations);
+    if (action === null || action === "allow") return undefined;
+
+    if (action === "block") {
+      if (ctx.hasUI) {
+        ctx.ui.notify(`pi-gate: blocked command matching a rule`, "warning");
+      }
+      return { block: true, reason: `pi-gate: command matches a "block" rule` };
+    }
+
+    // action === "prompt"
+    if (!ctx.hasUI) {
+      return { block: true, reason: "pi-gate: prompt required but no UI is available" };
+    }
+    const choice = await ctx.ui.select(
+      `pi-gate: allow this command?\n\n  ${command}\n\nA rule in pi-gate.json requests confirmation.`,
+      ["Allow", "Deny"],
+    );
+    if (choice !== "Allow") {
+      return { block: true, reason: "pi-gate: denied by user" };
+    }
+    return undefined;
+  });
+}