@zhushanwen/pi-unified-hooks 0.0.1 → 0.0.3

package/README.md

@@ -1,55 +1,42 @@
-# unified-hooks — Unified Hooks Extension
+# unified-hooks
 
-Collect scattered hooks in one place for easy maintenance. Each hook is a self-contained module that can be enabled/disabled independently.
+统一 hooks 管理器 — 将散落的 hooks 收集到一个扩展中统一维护，每个 hook 可独立启用/禁用。
 
-## Installation
+## 功能
 
-```bash
-ln -s /path/to/xyz-pi-extensions/unified-hooks ~/.pi/agent/extensions/unified-hooks
-```
-
-## Available Hooks
-
-### edit-whitespace-autofix
-
-When edit tool fails due to whitespace mismatch, injects a steering message that tells the AI to fix whitespace and retry.
+### 内置 Hooks
 
-**Trigger patterns:**
-- `Could not find the exact text`
-- `oldText must match exactly`
-- `Could not find edits[`
+| Hook | 说明 |
+|------|------|
+| `edit-whitespace-autofix` | edit 工具因空白字符不匹配失败时，自动注入 steering 让 AI 修复空白并重试 |
+| `tool-error-handler` | 记录所有工具执行错误到控制台，方便调试 |
 
-**Behavior:**
-1. Detect whitespace mismatch error from edit tool
-2. Extract the file path from tool args
-3. Inject steer message with `fix_whitespace.py --fix <file>` command
-4. AI automatically fixes whitespace and retries the edit
+### 扩展方式
 
-### tool-error-handler
+在 `src/hooks/` 下新建 hook 模块，然后在 `src/index.ts` 的 `hookModules` 数组中注册即可。
 
-Logs all tool execution errors to console for debugging.
+## 安装
 
-## Adding New Hooks
-
-1. Create `src/hooks/my-hook.ts`:
-   ```typescript
-   import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+```bash
+# symlink 方式（开发推荐）
+ln -s /path/to/xyz-pi-extensions-workspace/main/packages/unified-hooks \
+      ~/.pi/agent/extensions/unified-hooks
 
-   export function setupMyHook(pi: ExtensionAPI): void {
-     pi.on("tool_execution_end", async (event) => {
-       if (event.toolName === "edit" && event.isError) {
-         // Your logic
-       }
-     });
-   }
-   ```
+# npm 方式（正式）
+pi install npm:@zhushanwen/pi-unified-hooks
+```
 
-2. Register in `src/index.ts` hookModules array
+## 使用
 
-3. Type check: `npx tsc --noEmit`
+安装后自动生效。edit 空白修复无需配置，工具错误日志自动输出到控制台。
 
-## Important API Notes
+## 文件结构
 
-- Use `pi.sendUserMessage()` in event handlers, **not** `ctx.sendUserMessage()` (only available in command context)
-- `tool_execution_end` event has `{ toolCallId, toolName, args, result, isError }`
-- Inject direct instructions in steer messages, don't try to invoke `/skill-name` via text
+```
+unified-hooks/
+├── index.ts
+└── src/
+    ├── index.ts               # 入口 — hook 注册
+    └── hooks/
+        └── tool-error-handler.ts  # 工具错误处理
+```

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@zhushanwen/pi-unified-hooks",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Unified hooks extension - collect scattered hooks in one place for easy maintenance",
-  "main": "index.js",
+  "main": "index.ts",
   "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
   "keywords": [
-    "pi",
+    "pi-package",
     "extension",
     "hooks"
   ],

package/src/hooks/network-timeout-guard.ts

@@ -0,0 +1,64 @@
+/**
+ * Network Timeout Guard Hook
+ *
+ * Intercepts bash tool calls that involve network operations.
+ * Blocks execution if no timeout is set and the command appears to be network-bound,
+ * prompting the AI to add timeout or use async mode.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Commands that indicate network activity.
+ * Matched against any segment of the bash command string (supports &&/||/; chaining).
+ */
+const NETWORK_COMMAND_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(pnpm|npm|yarn|bun)\s+(install|add|i|ci|update|upgrade|dlx|exec|create|init)/, label: "package manager" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(pip|pip3|uv|poetry|conda)\s+(install|add|sync|download|run)/, label: "Python package manager" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*curl\s/, label: "curl" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*wget\s/, label: "wget" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*git\s+(clone|fetch|pull|push|submodule)/, label: "git network" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*gh\s+(repo\s+clone|api|run|release|pr\s+checkout)/, label: "gh CLI" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*docker\s+(pull|push|build|run|compose\s+(pull|up|build))/, label: "docker" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*cargo\s+(install|update|build|check|fetch)/, label: "cargo" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*go\s+(install|get|mod\s+(download|tidy))/, label: "go" },
+];
+
+/**
+ * Check if a command involves network operations.
+ */
+function detectNetworkCommand(command: string): string | null {
+  for (const { pattern, label } of NETWORK_COMMAND_PATTERNS) {
+    if (pattern.test(command)) {
+      return label;
+    }
+  }
+  return null;
+}
+
+export function setupNetworkTimeoutGuard(pi: ExtensionAPI): void {
+  pi.on("tool_call", async (event: any) => {
+    // Only intercept bash tool calls
+    if (event.toolName !== "bash") return;
+
+    const { command, timeout } = event.input as { command: string; timeout?: number };
+
+    // No network command detected — let it through
+    const networkLabel = detectNetworkCommand(command);
+    if (!networkLabel) return;
+
+    // Timeout is already set — good, let it through
+    if (timeout != null && timeout > 0) return;
+
+    // Block and ask AI to add timeout
+    return {
+      block: true,
+      reason:
+        `[network-timeout-guard] Detected network command (${networkLabel}) without timeout.\n` +
+        `Please do one of the following:\n` +
+        `1. Set the bash tool's timeout parameter (recommended: 60-120s)\n` +
+        `2. If duration is unclear, start with timeout: 30 to probe, then adjust after timeout\n` +
+        `3. Accessing overseas sites (npmjs.org / GitHub / PyPI) may require a proxy — on timeout, run 'proxy' to enable proxy and retry`,
+    };
+  });
+}

package/src/hooks/test-timeout-guard.ts

@@ -0,0 +1,97 @@
+/**
+ * Test Timeout Guard Hook
+ *
+ * Intercepts bash tool calls that execute tests across various frameworks.
+ * Blocks execution if no timeout is set, prompting the AI to add one.
+ *
+ * Covered ecosystems: Node.js (vitest, jest, mocha, cypress, playwright),
+ * Python (pytest, unittest), Java (maven, gradle), Go, Rust, .NET, Ruby.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Patterns that indicate test execution.
+ * Designed to match via pipe/semicolon/&& chaining as well as direct invocation.
+ */
+const TEST_COMMAND_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  // === Node.js / JS / TS ===
+  // Package manager test scripts: npm test, pnpm test, yarn test
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(pnpm|npm|yarn|bun)\s+test\b/, label: "npm test" },
+  // pnpm/npm run with test-related script names
+  {
+    pattern: /(^|\s|&&|\|{1,2}|;)\s*(pnpm|npm)\s+(--filter\s+\S+\s+)?run\s+\S*test/,
+    label: "npm run test",
+  },
+  // Direct test runner invocation via npx
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*npx\s+vitest\b/, label: "vitest" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*npx\s+jest\b/, label: "jest" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*npx\s+mocha\b/, label: "mocha" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*npx\s+(cypress|playwright)\s/, label: "e2e runner" },
+  // vue-cli-service / react-scripts test
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*npx\s+vue-cli-service\s+test/, label: "vue-cli test" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*npx\s+react-scripts\s+test/, label: "react-scripts test" },
+  // Direct vitest/jest from node_modules
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*\.\/?node_modules\/\.bin\/(vitest|jest|mocha)\b/, label: "direct test runner" },
+
+  // === Python ===
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*pytest\b/, label: "pytest" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*python[3]?\s+-m\s+(pytest|unittest)\b/, label: "python test" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(uv|poetry)\s+run\s+pytest\b/, label: "uv/poetry pytest" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*nosetests\b/, label: "nosetests" },
+
+  // === Java / JVM ===
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(mvn|\.\/mvnw)\s+\S*test/, label: "maven test" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(gradle|\.\/gradlew)\s+\S*test/, label: "gradle test" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*sbt\s+test\b/, label: "sbt test" },
+
+  // === Go ===
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*go\s+test\b/, label: "go test" },
+
+  // === Rust ===
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*cargo\s+test\b/, label: "cargo test" },
+
+  // === .NET ===
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*dotnet\s+test\b/, label: "dotnet test" },
+
+  // === Ruby ===
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*(rspec|bundle\s+exec\s+rspec)\b/, label: "rspec" },
+  { pattern: /(^|\s|&&|\|{1,2}|;)\s*rake\s+test\b/, label: "rake test" },
+];
+
+/**
+ * Check if a command executes tests.
+ */
+function detectTestCommand(command: string): string | null {
+  for (const { pattern, label } of TEST_COMMAND_PATTERNS) {
+    if (pattern.test(command)) {
+      return label;
+    }
+  }
+  return null;
+}
+
+export function setupTestTimeoutGuard(pi: ExtensionAPI): void {
+  pi.on("tool_call", async (event: any) => {
+    if (event.toolName !== "bash") return;
+
+    const { command, timeout } = event.input as { command: string; timeout?: number };
+
+    const testLabel = detectTestCommand(command);
+    if (!testLabel) return;
+
+    // Timeout already set — let it through
+    if (timeout != null && timeout > 0) return;
+
+    // Block and require timeout
+    return {
+      block: true,
+      reason:
+        `[test-timeout-guard] Detected test command (${testLabel}) without timeout.\n` +
+        `Test duration is unpredictable — without timeout the process may hang indefinitely. Please do one of the following:\n` +
+        `1. Set the bash tool's timeout parameter (60-120s for unit tests, 180-300s for E2E tests)\n` +
+        `2. If test suite size or duration is unknown, start with a short timeout (e.g. 30s) to probe\n` +
+        `3. For known slow tests (cargo test, gradle test, etc.), allow up to 300s`,
+    };
+  });
+}

package/src/hooks/tool-error-handler.ts

@@ -8,7 +8,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 export function setupToolErrorHandler(pi: ExtensionAPI): void {
-  pi.on("tool_execution_end", async (event) => {
+  pi.on("tool_execution_end", async (event: any) => {
     if (!event.isError) return;
     console.log(`[unified-hooks] ${event.toolName} error (callId=${event.toolCallId})`);
   });

package/src/index.ts

@@ -9,8 +9,12 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 // Re-export hook modules for easy access
 export { setupToolErrorHandler } from "./hooks/tool-error-handler";
+export { setupNetworkTimeoutGuard } from "./hooks/network-timeout-guard";
+export { setupTestTimeoutGuard } from "./hooks/test-timeout-guard";
 
 import { setupToolErrorHandler } from "./hooks/tool-error-handler";
+import { setupNetworkTimeoutGuard } from "./hooks/network-timeout-guard";
+import { setupTestTimeoutGuard } from "./hooks/test-timeout-guard";
 
 /**
  * Extension factory - registers all unified hooks
@@ -23,6 +27,8 @@ export default function unifiedHooksExtension(pi: ExtensionAPI): void {
   // with hash-anchor mode, making oldText-based guard unreachable
   const hookModules = [
     { name: "tool-error-handler", setup: setupToolErrorHandler },
+    { name: "network-timeout-guard", setup: setupNetworkTimeoutGuard },
+    { name: "test-timeout-guard", setup: setupTestTimeoutGuard },
   ];
 
   for (const hook of hookModules) {