@zeldrisho/pi-gate 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-24
+
+### Changed
+
+- Use `gate.json` as the default configuration filename, retaining `pi-gate.json` as a legacy fallback only when `gate.json` is absent; existing files are never automatically renamed or overwritten.
+
+## [0.4.1] - 2026-09-17
+
+### Security
+
+- prompt for all commands when an existing configuration cannot be read or parsed instead of allowing every command through unblocked
+
 ## [0.4.0] - 2026-09-12
 
 ### Changed
@@ -50,7 +62,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.4.0...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.5.0...HEAD
+[0.5.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.4.1...pi-gate-v0.5.0
+[0.4.1]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.4.0...pi-gate-v0.4.1
 [0.4.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.3.0...pi-gate-v0.4.0
 [0.3.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.2.0...pi-gate-v0.3.0
 [0.2.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.1.1...pi-gate-v0.2.0

package/README.md

@@ -12,7 +12,9 @@ pi install -l npm:@zeldrisho/pi-gate
 
 ## Configure
 
-On first load, the extension creates `~/.pi/agent/pi-gate.json` with starter rules and a 30-second prompt timeout. Existing files are never overwritten. The published package includes [`config.schema.json`](config.schema.json); use this schema URL for editor completion:
+The extension reads `~/.pi/agent/gate.json`, falling back to legacy `~/.pi/agent/pi-gate.json` only when `gate.json` is absent. Set `PI_CODING_AGENT_DIR` to use a different configuration directory. If both files exist, only `gate.json` is used—even if it is invalid. To migrate, rename `pi-gate.json` to `gate.json` and run `/reload`; existing files are never automatically renamed, merged, or overwritten.
+
+On first load, if neither file exists, the extension creates `gate.json` with starter rules and a 30-second prompt timeout. If no configuration can be created yet, pi-gate warns at session start and allows commands until the file is created. If an existing configuration cannot be read or parsed, pi-gate warns and prompts for every command until it is fixed. The published package includes [`config.schema.json`](config.schema.json); use this schema URL for editor completion:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension that blocks or confirms bash commands based on a user-provided JSON configuration",
   "keywords": [
     "command-blocking",
@@ -25,19 +25,17 @@
   "files": [
     "src",
     "config.schema.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "CHANGELOG.md"
   ],
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
     "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
-    "vite-plus": "0.3.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.3",
+    "vite-plus": "0.3.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/src/config.ts

@@ -9,13 +9,28 @@ export interface GateConfig {
   promptTimeoutMs: number;
 }
 
-const CONFIG_FILE_NAME = "pi-gate.json";
+export type ConfigLoadStatus = "missing" | "loaded" | "failed";
+
+export interface ConfigLoadResult {
+  config: GateConfig;
+  status: ConfigLoadStatus;
+}
+
+const CONFIG_FILE_NAME = "gate.json";
+
+const LEGACY_CONFIG_FILE_NAME = "pi-gate.json";
+
 export const CONFIG_SCHEMA_URL =
   "https://raw.githubusercontent.com/zeldrisho/pi-packages/main/packages/pi-gate/config.schema.json";
+
 const ACTIONS: readonly Action[] = ["prompt", "block", "allow"] as const;
+
 export const DEFAULT_PROMPT_TIMEOUT_MS = 30_000;
+
 export const MAX_RULE_COUNT = 1_000;
+
 export const MAX_RULE_PATTERN_LENGTH = 1_024;
+
 export const MAX_PROMPT_TIMEOUT_MS = 86_400_000;
 
 const DEFAULT_CONFIG: GateConfig = {
@@ -41,10 +56,18 @@ function agentDir(): string {
 /**
  * Returns the full path to the pi-gate configuration file.
  *
- * @returns The absolute path to pi-gate.json
+ * Prefers gate.json, falling back to pi-gate.json only when gate.json is absent.
+ *
+ * @returns The selected configuration path, or gate.json for first-run creation
  */
 export function configPath(): string {
-  return join(agentDir(), CONFIG_FILE_NAME);
+  const path = join(agentDir(), CONFIG_FILE_NAME);
+
+  if (existsSync(path)) return path;
+
+  const legacyPath = join(agentDir(), LEGACY_CONFIG_FILE_NAME);
+
+  return existsSync(legacyPath) ? legacyPath : path;
 }
 
 /**
@@ -87,15 +110,19 @@ export function parseConfig(content: string): GateConfig {
   const rules: Record<string, Action> = {};
   let acceptedRuleCount = 0;
   let parsed: unknown;
+
   try {
     parsed = JSON.parse(content);
   } catch {
     return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
   }
+
   if (!isJsonObject(parsed)) {
     return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
   }
+
   const configuredTimeout = parsed["promptTimeoutMs"];
+
   const promptTimeoutMs =
     // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validate the optional numeric field at the untrusted JSON boundary before applying range checks
     typeof configuredTimeout === "number" &&
@@ -104,18 +131,24 @@ export function parseConfig(content: string): GateConfig {
     configuredTimeout <= MAX_PROMPT_TIMEOUT_MS
       ? configuredTimeout
       : DEFAULT_PROMPT_TIMEOUT_MS;
+
   const operations = parsed["operations"];
+
   if (!isJsonObject(operations)) {
     return { operations: rules, promptTimeoutMs };
   }
+
   for (const [pattern, action] of Object.entries(operations)) {
     if (acceptedRuleCount >= MAX_RULE_COUNT) break;
+
     if (pattern.length === 0 || pattern.length > MAX_RULE_PATTERN_LENGTH) continue;
+
     if (isAction(action)) {
       rules[pattern] = action;
       acceptedRuleCount += 1;
     }
   }
+
   return { operations: rules, promptTimeoutMs };
 }
 
@@ -123,18 +156,38 @@ export function parseConfig(content: string): GateConfig {
  * Loads the configuration from disk. Returns an empty configuration when the
  * file is missing; returns the parsed configuration otherwise.
  */
-export function loadConfig(): GateConfig {
+export function loadConfigResult(): ConfigLoadResult {
+  const emptyConfig = { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
   const path = configPath();
+
   if (!existsSync(path)) {
-    return { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
+    return { config: emptyConfig, status: "missing" };
   }
+
   let content: string;
+
   try {
     content = readFileSync(path, "utf-8");
   } catch {
-    return { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
+    return { config: emptyConfig, status: "failed" };
   }
-  return parseConfig(content);
+
+  try {
+    const parsed: unknown = JSON.parse(content);
+
+    if (!isJsonObject(parsed) || !isJsonObject(parsed["operations"])) {
+      return { config: parseConfig(content), status: "failed" };
+    }
+  } catch {
+    return { config: emptyConfig, status: "failed" };
+  }
+
+  return { config: parseConfig(content), status: "loaded" };
+}
+
+/** Loads the configuration, preserving the historical empty-config fallback. */
+export function loadConfig(): GateConfig {
+  return loadConfigResult().config;
 }
 
 /**
@@ -143,13 +196,17 @@ export function loadConfig(): GateConfig {
  */
 export function ensureConfig(): void {
   const path = configPath();
+
   if (existsSync(path)) return;
+
   try {
     mkdirSync(agentDir(), { recursive: true });
   } catch {
     return;
   }
+
   const content = JSON.stringify({ $schema: CONFIG_SCHEMA_URL, ...DEFAULT_CONFIG }, null, 2) + "\n";
+
   try {
     writeFileSync(path, content, { encoding: "utf-8", flag: "wx", mode: 0o600 });
   } catch {

package/src/display.ts

@@ -1,8 +1,11 @@
 import type { RuleMatch } from "./rules";
 
 export const MAX_DISPLAY_COMMAND_CHARACTERS = 2_000;
+
 export const MAX_DISPLAY_COMMAND_LINES = 20;
+
 const DISPLAY_TRUNCATION_MARKER = "\n  … [command display truncated]";
+
 const BIDI_CONTROL_CODE_POINTS = new Set([
   0x061c, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069,
 ]);
@@ -10,7 +13,9 @@ const BIDI_CONTROL_CODE_POINTS = new Set([
 /** Converts terminal controls and bidirectional formatting characters to visible escapes. */
 function escapeUnsafeDisplayCharacter(character: string): string {
   const codePoint = character.codePointAt(0);
+
   if (codePoint === undefined) return "";
+
   if (
     codePoint < 0x20 ||
     (codePoint >= 0x7f && codePoint <= 0x9f) ||
@@ -18,6 +23,7 @@ function escapeUnsafeDisplayCharacter(character: string): string {
   ) {
     return `\\u{${codePoint.toString(16).padStart(4, "0")}}`;
   }
+
   return character;
 }
 
@@ -31,12 +37,15 @@ function findMatchRanges(command: string, pattern?: string): MatchRange[] {
   if (!pattern) return [];
   const ranges: MatchRange[] = [];
   let offset = 0;
+
   while (offset <= command.length - pattern.length) {
     const start = command.indexOf(pattern, offset);
+
     if (start === -1) break;
     ranges.push({ start, end: start + pattern.length });
     offset = start + pattern.length;
   }
+
   return ranges;
 }
 
@@ -57,6 +66,7 @@ function renderCommandForDisplay(command: string, pattern?: string): string {
     let rawEnd: number;
     let rendered: string;
     const codePoint = command.codePointAt(offset);
+
     if (codePoint === 0x0d) {
       rawEnd = offset + (command.codePointAt(offset + 1) === 0x0a ? 2 : 1);
       rendered = "\n";
@@ -68,11 +78,13 @@ function renderCommandForDisplay(command: string, pattern?: string): string {
 
     const nextRange = ranges[rangeIndex];
     const wasInsideRange = activeRange !== undefined;
+
     const opensRange =
       activeRange === undefined &&
       nextRange !== undefined &&
       nextRange.start < rawEnd &&
       nextRange.end > rawStart;
+
     if (opensRange) activeRange = nextRange;
     const closesRange = activeRange !== undefined && activeRange.end <= rawEnd;
     const decorated = `${opensRange ? "»" : ""}${rendered}${closesRange ? "«" : ""}`;
@@ -81,17 +93,21 @@ function renderCommandForDisplay(command: string, pattern?: string): string {
       if (lineCount >= MAX_DISPLAY_COMMAND_LINES) return truncate(wasInsideRange);
       lineCount += 1;
     }
+
     if (output.length + decorated.length > MAX_DISPLAY_COMMAND_CHARACTERS) {
       return truncate(wasInsideRange);
     }
 
     output += decorated;
+
     if (closesRange) {
       activeRange = undefined;
       rangeIndex += 1;
     }
+
     offset = rawEnd;
   }
+
   return output;
 }
 

package/src/index.ts

@@ -5,7 +5,7 @@
  * user-provided JSON configuration. Without a configuration file, the
  * extension creates one with starter rules and a default prompt timeout.
  *
- * Configuration file: `~/.pi/agent/pi-gate.json`
+ * Configuration file: `~/.pi/agent/gate.json` (legacy fallback: `pi-gate.json`)
  *
  * The configuration has an `operations` section, which maps a substring
  * pattern to one of three actions, and an optional `promptTimeoutMs` setting:
@@ -18,7 +18,7 @@
  * narrow `allow` rule can override a broader `prompt` or `block` rule.
  *
  * On first run, a configuration with the default prompt timeout and starter
- * operation rules is written to `~/.pi/agent/pi-gate.json`.
+ * operation rules is written to `~/.pi/agent/gate.json` when neither file exists.
  *
  * Non-UI modes (print, JSON) never auto-approve. A `prompt` or `block` rule
  * in non-UI mode always blocks and requests termination of the agent turn.
@@ -26,9 +26,8 @@
  * indefinitely.
  */
 
-import { existsSync } from "node:fs";
 import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { configPath, ensureConfig, loadConfig } from "./config";
+import { configPath, ensureConfig, loadConfigResult } from "./config";
 import { resolveRule } from "./rules";
 import { formatPromptCommand, formatRule } from "./display";
 
@@ -58,6 +57,7 @@ function reportHerdrBlocked(pi: ExtensionAPI, ctx: { mode?: string }, active: bo
 }
 
 export type { Action, GateConfig } from "./config";
+
 export {
   CONFIG_SCHEMA_URL,
   DEFAULT_PROMPT_TIMEOUT_MS,
@@ -66,10 +66,16 @@ export {
   MAX_RULE_PATTERN_LENGTH,
   ensureConfig,
   loadConfig,
+  loadConfigResult,
   parseConfig,
 } from "./config";
+
+export type { ConfigLoadResult, ConfigLoadStatus } from "./config";
+
 export type { RuleMatch } from "./rules";
+
 export { resolveAction, resolveRule } from "./rules";
+
 export {
   MAX_DISPLAY_COMMAND_CHARACTERS,
   MAX_DISPLAY_COMMAND_LINES,
@@ -80,12 +86,14 @@ export {
 /** Gate the built-in `bash` tool against the user-provided rules. */
 export default function piGate(pi: ExtensionAPI): void {
   ensureConfig();
-  const config = loadConfig();
+  let loadResult = loadConfigResult();
+  const { config } = loadResult;
 
   pi.on("session_start", (_event, ctx) => {
     const path = configPath();
     const ruleCount = Object.keys(config.operations).length;
-    if (existsSync(path)) {
+
+    if (loadResult.status === "loaded") {
       if (ruleCount === 0) {
         ctx.ui.notify(
           `pi-gate: ${path} is empty; no commands are gated. Add rules to the "operations" object to start gating.`,
@@ -97,9 +105,14 @@ export default function piGate(pi: ExtensionAPI): void {
           "info",
         );
       }
+    } else if (loadResult.status === "failed") {
+      ctx.ui.notify(
+        "pi-gate: configuration exists but could not be loaded; prompting for all commands until it is fixed.",
+        "warning",
+      );
     } else {
       ctx.ui.notify(
-        `pi-gate: could not create configuration at ${path}; all commands are allowed until that file is created.`,
+        `pi-gate: no configuration found at ${configPath()}; all commands are allowed until it is created.`,
         "warning",
       );
     }
@@ -107,17 +120,29 @@ export default function piGate(pi: ExtensionAPI): void {
 
   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 match = resolveRule(command, config.operations);
+
+    if (loadResult.status === "failed") {
+      loadResult = loadConfigResult();
+    }
+
+    const match =
+      loadResult.status === "failed"
+        ? { pattern: "configuration unavailable", action: "prompt" as const }
+        : resolveRule(command, loadResult.config.operations);
+
     if (match === null || match.action === "allow") return undefined;
     const rule = formatRule(match);
 
     if (match.action === "block") {
       const reason = `pi-gate: command blocked by rule ${rule}`;
+
       if (ctx.hasUI) {
         ctx.ui.notify(reason, "warning");
       }
+
       return { block: true, reason, terminate: true };
     }
 
@@ -129,17 +154,20 @@ export default function piGate(pi: ExtensionAPI): void {
         terminate: true,
       };
     }
+
     reportHerdrBlocked(pi, ctx, true);
     let choice: string | undefined;
+
     try {
       choice = await ctx.ui.select(
         `pi-gate: allow this command?\n\n${formatPromptCommand(command, match.pattern)}\n\nMatched rule: ${rule}\nMatched command text is wrapped in »…«`,
         ["Allow", "Deny"],
-        { timeout: config.promptTimeoutMs },
+        { timeout: loadResult.config.promptTimeoutMs },
       );
     } finally {
       reportHerdrBlocked(pi, ctx, false);
     }
+
     if (choice !== "Allow") {
       return {
         block: true,
@@ -147,6 +175,7 @@ export default function piGate(pi: ExtensionAPI): void {
         terminate: true,
       };
     }
+
     return undefined;
   });
 }

package/src/rules.ts

@@ -18,13 +18,17 @@ export interface RuleMatch {
  */
 export function resolveRule(command: string, rules: Record<string, Action>): RuleMatch | 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 { pattern: bestPattern, action: rules[bestPattern] };
 }