@chongyan/autospec 1.0.1

package/plugins/hooks/lib/hook-logger.js

@@ -0,0 +1,538 @@
+/**
+ * AutoSpec Hooks Utilities
+ * Shared utilities for all hook scripts
+ *
+ * This file is self-contained for hooks to work independently after being copied to target projects.
+ */
+
+// ============================================================
+// Global error handlers (防止未捕获的错误导致 hook 静默失败)
+// ============================================================
+
+// 只注册一次
+let globalHandlersRegistered = false;
+
+/**
+ * 注册全局错误处理器
+ * 防止 uncaughtException 和 unhandledRejection 导致 hook 静默失败
+ */
+function registerGlobalErrorHandlers() {
+  if (globalHandlersRegistered) return;
+  globalHandlersRegistered = true;
+
+  process.on('uncaughtException', (err) => {
+    console.error('[AutoSpec Hook] Uncaught exception:', err.message);
+    if (process.env.VERBOSE || process.env.DEBUG) {
+      console.error(err.stack);
+    }
+    process.exit(0);  // 允许操作继续，但至少记录了错误
+  });
+
+  process.on('unhandledRejection', (reason, promise) => {
+    const message = reason instanceof Error ? reason.message : String(reason);
+    console.error('[AutoSpec Hook] Unhandled rejection:', message);
+    if (process.env.VERBOSE || process.env.DEBUG && reason instanceof Error) {
+      console.error(reason.stack);
+    }
+    process.exit(0);
+  });
+}
+
+// 自动注册全局错误处理器
+registerGlobalErrorHandlers();
+
+// ============================================================
+// Logger utilities
+// ============================================================
+
+export const LOG_LEVELS = {
+  ERROR: 0,
+  WARN: 1,
+  INFO: 2,
+  DEBUG: 3
+};
+
+let currentLevel = LOG_LEVELS.INFO;
+let isVerbose = false;
+
+/**
+ * Set log level
+ */
+export function setLogLevel(level) {
+  if (typeof level === 'string') {
+    currentLevel = LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+  } else {
+    currentLevel = level;
+  }
+}
+
+/**
+ * Enable verbose mode
+ */
+export function setVerbose(verbose) {
+  isVerbose = verbose;
+  if (verbose) {
+    currentLevel = LOG_LEVELS.DEBUG;
+  }
+}
+
+/**
+ * Check if verbose mode is enabled
+ */
+export function isVerboseMode() {
+  return isVerbose || currentLevel >= LOG_LEVELS.DEBUG;
+}
+
+/**
+ * Format log message with timestamp and level
+ */
+function formatMessage(level, message, meta = {}) {
+  const timestamp = new Date().toISOString();
+  const levelStr = Object.keys(LOG_LEVELS).find(k => LOG_LEVELS[k] === level) || 'UNKNOWN';
+
+  let output = `[${timestamp}] [${levelStr}] ${message}`;
+
+  if (Object.keys(meta).length > 0) {
+    output += '\n' + Object.entries(meta)
+      .map(([k, v]) => `  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`)
+      .join('\n');
+  }
+
+  return output;
+}
+
+/**
+ * Log error message
+ */
+export function error(message, meta = {}) {
+  if (currentLevel >= LOG_LEVELS.ERROR) {
+    console.error(formatMessage(LOG_LEVELS.ERROR, message, meta));
+  }
+}
+
+/**
+ * Log warning message
+ */
+export function warn(message, meta = {}) {
+  if (currentLevel >= LOG_LEVELS.WARN) {
+    console.warn(formatMessage(LOG_LEVELS.WARN, message, meta));
+  }
+}
+
+/**
+ * Log info message
+ * Note: Use console.error to avoid mixing with hook JSON output on stdout
+ */
+export function info(message, meta = {}) {
+  if (currentLevel >= LOG_LEVELS.INFO) {
+    console.error(formatMessage(LOG_LEVELS.INFO, message, meta));
+  }
+}
+
+/**
+ * Log debug message (only in verbose mode)
+ * Note: Use console.error to avoid mixing with hook JSON output on stdout
+ */
+export function debug(message, meta = {}) {
+  if (currentLevel >= LOG_LEVELS.DEBUG) {
+    console.error(formatMessage(LOG_LEVELS.DEBUG, message, meta));
+  }
+}
+
+/**
+ * Create a hook-specific logger
+ */
+export function createHookLogger(hookName) {
+  return {
+    error: (msg, meta) => error(`[${hookName}] ${msg}`, meta),
+    warn: (msg, meta) => warn(`[${hookName}] ${msg}`, meta),
+    info: (msg, meta) => info(`[${hookName}] ${msg}`, meta),
+    debug: (msg, meta) => debug(`[${hookName}] ${msg}`, meta)
+  };
+}
+
+// ============================================================
+// Hook error classification and security levels
+// ============================================================
+
+/**
+ * Hook 错误类型枚举
+ */
+export const HookErrorType = {
+  // 可恢复错误 - hook 逻辑自身无法处理，但不影响操作
+  RECOVERABLE: {
+    code: 'RECOVERABLE',
+    severity: 'low',
+    failStrategy: 'open',      // 允许操作继续
+    shouldAlert: false,
+    shouldLog: true
+  },
+
+  // 输入解析错误 - 输入数据格式问题
+  PARSE_ERROR: {
+    code: 'PARSE_ERROR',
+    severity: 'medium',
+    failStrategy: 'open',      // 允许操作继续（无法解析则跳过检查）
+    shouldAlert: true,
+    shouldLog: true
+  },
+
+  // 权限错误 - 文件系统权限问题
+  PERMISSION_ERROR: {
+    code: 'PERMISSION_ERROR',
+    severity: 'high',
+    failStrategy: 'open',      // 允许操作继续，但必须告警
+    shouldAlert: true,
+    shouldLog: true
+  },
+
+  // 运行时错误 - hook 内部逻辑错误
+  RUNTIME_ERROR: {
+    code: 'RUNTIME_ERROR',
+    severity: 'high',
+    failStrategy: 'context',   // 根据 hook 类型决定
+    shouldAlert: true,
+    shouldLog: true
+  },
+
+  // 关键错误 - 必须阻止操作
+  CRITICAL_ERROR: {
+    code: 'CRITICAL_ERROR',
+    severity: 'critical',
+    failStrategy: 'closed',    // 阻止操作
+    shouldAlert: true,
+    shouldLog: true
+  }
+};
+
+/**
+ * 根据 hook 名称获取其安全级别
+ */
+export const HookSecurityLevel = {
+  'frozen-zone-guard': 'critical',   // 关键安全 hook
+  'layer1-validator': 'critical',    // 流程门禁 hook
+  'constitution-guard': 'high',
+  'scope-sentinel': 'medium',
+  'execution-tracker': 'low',
+  'pipeline-observer': 'low',
+  'trace-initialization': 'low',
+  'artifact-evaluation-hook': 'medium',
+  'environment-manager': 'medium',
+  'ai-project-guard': 'medium'
+};
+
+/**
+ * 分类错误
+ * @param {Error} err - 错误对象
+ * @param {string} hookName - Hook 名称
+ * @returns {Object} 错误类型
+ */
+export function classifyError(err, hookName) {
+  // 权限错误
+  if (err.code === 'EACCES' ||
+      err.message?.includes('permission denied') ||
+      err.message?.includes('ENOENT')) {
+    return HookErrorType.PERMISSION_ERROR;
+  }
+
+  // 解析错误
+  if (err.message?.includes('JSON') ||
+      err.message?.includes('parse') ||
+      err.message?.includes('Unexpected token')) {
+    return HookErrorType.PARSE_ERROR;
+  }
+
+  // 根据 hook 安全级别和错误上下文判断
+  const securityLevel = HookSecurityLevel[hookName] || 'low';
+
+  // 关键 hook 的任何错误都视为严重
+  if (securityLevel === 'critical') {
+    return {
+      ...HookErrorType.RUNTIME_ERROR,
+      failStrategy: 'closed'  // 覆盖为 fail-closed
+    };
+  }
+
+  return HookErrorType.RUNTIME_ERROR;
+}
+
+/**
+ * Handle hook errors gracefully
+ * 增强版错误处理：分类错误、记录日志、决定是否阻止操作
+ * @param {string} hookName - Hook 名称
+ * @param {Error} err - 错误对象
+ * @param {Object} context - 上下文信息（包含 eventName, projectRoot, input 等）
+ * @returns {Object} 输出对象，包含是否应该阻止操作
+ */
+export function handleHookError(hookName, err, context = {}) {
+  const errorType = classifyError(err, hookName);
+  const securityLevel = HookSecurityLevel[hookName] || 'low';
+
+  // 构建详细的错误信息
+  const errorInfo = {
+    hookName,
+    errorType: errorType.code,
+    errorMessage: err.message,
+    errorCode: err.code,
+    severity: errorType.severity,
+    timestamp: new Date().toISOString(),
+    context
+  };
+
+  // 记录到控制台
+  const errorMeta = {
+    hook: hookName,
+    error: err.message,
+    code: err.code,
+    type: errorType.code,
+    severity: errorType.severity,
+    stack: isVerbose ? err.stack : undefined
+  };
+  error(`Hook execution failed`, errorMeta);
+
+  // 记录到 hook 错误日志（如果有 projectRoot）
+  if (context.projectRoot) {
+    try {
+      // 动态导入避免循环依赖
+      import('./hook-error-recorder.js').then(({ recordHookError }) => {
+        recordHookError(context.projectRoot, errorInfo);
+      }).catch(() => {
+        // 忽略导入错误
+      });
+    } catch {
+      // 忽略错误
+    }
+  }
+
+  // 决定是否阻止操作
+  let permissionDecision = 'allow';
+  let permissionDecisionReason = null;
+
+  if (errorType.failStrategy === 'closed' ||
+      (errorType.failStrategy === 'context' && securityLevel === 'critical')) {
+    permissionDecision = 'deny';
+    permissionDecisionReason =
+      `[AutoSpec] 🚨 HOOK ERROR - Operation Blocked\n` +
+      `Hook: ${hookName}\n` +
+      `Error Type: ${errorType.code}\n` +
+      `Reason: ${err.message}\n\n` +
+      `This is a critical hook that protects the project. ` +
+      `When it fails, the operation must be blocked for safety.\n` +
+      `Please check the error and try again.`;
+  }
+
+  // 构建用户提示
+  let additionalContext = buildUserMessage(hookName, errorType, err);
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: context.eventName || 'Unknown',
+      permissionDecision,
+      permissionDecisionReason,
+      additionalContext
+    },
+    // 返回错误分类信息供调用者使用
+    errorType,
+    shouldBlock: permissionDecision === 'deny'
+  };
+}
+
+/**
+ * 构建用户提示信息
+ */
+function buildUserMessage(hookName, errorType, err) {
+  // 权限错误的特殊处理
+  if (errorType.code === 'PERMISSION_ERROR') {
+    return `[AutoSpec] ⚠️ 权限错误: ${hookName} 无法写入文件
+
+可能原因：.autospec 或 .claude 目录由 root 创建
+
+修复方法：运行以下命令修复权限
+  sudo chown -R $(whoami) .autospec .claude
+
+或者重新初始化（不使用 sudo）：
+  rm -rf .autospec .claude CLAUDE.md
+  autospec init`;
+  }
+
+  // 其他错误的通用提示
+  const severity = errorType.severity;
+  const icon = severity === 'critical' ? '🚨' :
+               severity === 'high' ? '⚠️' : 'ℹ️';
+
+  return `[AutoSpec] ${icon} Hook '${hookName}' encountered an error (${errorType.code})
+
+Error: ${err.message}
+
+${errorType.failStrategy === 'closed' ?
+  'This operation has been blocked for safety.' :
+  'The operation was allowed to continue. Use --verbose for details.'}`;
+}
+
+/**
+ * Safe JSON parse with logging
+ */
+export function safeJsonParse(str, defaultValue = null, context = '') {
+  try {
+    return JSON.parse(str);
+  } catch (err) {
+    debug(`JSON parse failed${context ? ` (${context})` : ''}`, {
+      error: err.message,
+      input: str?.slice(0, 200) // Log truncated input
+    });
+    return defaultValue;
+  }
+}
+
+// ============================================================
+// Common utilities
+// ============================================================
+
+/**
+ * Read stdin safely with timeout
+ */
+export function readStdin(timeout = 1000) {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      resolve(data);
+    }, timeout);
+
+    function cleanup() {
+      clearTimeout(timeoutId);
+      process.stdin.removeListener('data', onData);
+      process.stdin.removeListener('end', onEnd);
+    }
+
+    function onData(chunk) {
+      data += chunk;
+    }
+
+    function onEnd() {
+      cleanup();
+      resolve(data);
+    }
+
+    process.stdin.on('data', onData);
+    process.stdin.on('end', onEnd);
+  });
+}
+
+/**
+ * Find project root by searching upward for .autospec directory
+ */
+export function findProjectRoot(startDir) {
+  const fs = require('fs');
+  const path = require('path');
+
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.autospec'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+/**
+ * Async version of findProjectRoot
+ */
+export async function findProjectRootAsync(startDir) {
+  const { default: fs } = await import('fs');
+  const { default: path } = await import('path');
+
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    try {
+      await fs.promises.access(path.join(dir, '.autospec'));
+      return dir;
+    } catch {
+      dir = path.dirname(dir);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Simple in-memory cache for hooks
+ */
+export class HookCache {
+  constructor(maxSize = 100) {
+    this.cache = new Map();
+    this.maxSize = maxSize;
+  }
+
+  get(key) {
+    const item = this.cache.get(key);
+    if (item && Date.now() - item.timestamp < item.ttl) {
+      return item.value;
+    }
+    this.cache.delete(key);
+    return undefined;
+  }
+
+  set(key, value, ttlMs = 60000) {
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+
+    this.cache.set(key, {
+      value,
+      timestamp: Date.now(),
+      ttl: ttlMs
+    });
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+}
+
+/**
+ * 全局单例缓存实例
+ * 供所有 hook 统一使用，避免各自实例化
+ */
+export const globalHookCache = new HookCache(200);
+
+/**
+ * Check if path matches any pattern
+ */
+export function matchesAnyPattern(path, patterns) {
+  return patterns.some(pattern => pattern.test(path));
+}
+
+/**
+ * Safe file existence check
+ */
+export async function fileExists(path) {
+  const { default: fs } = await import('fs');
+  try {
+    await fs.promises.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Safe directory sync check
+ */
+export function directoryExistsSync(path) {
+  const fs = require('fs');
+  try {
+    return fs.existsSync(path) && fs.statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/plugins/hooks/lib/hook-runner.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+/**
+ * AutoSpec Hook Runner
+ *
+ * 通用 hook 启动器，解决子目录工作时相对路径无法正确解析的问题。
+ *
+ * 工作原理：
+ * 1. 从当前工作目录向上查找 .autospec 目录
+ * 2. 找到后，动态加载指定的 hook 脚本
+ * 3. 如果找不到，静默退出（可能是非 AutoSpec 项目）
+ *
+ * 使用方式：
+ * node .autospec/plugins/hooks/lib/hook-runner.js <hook-name>
+ *
+ * 例如：
+ * node .autospec/plugins/hooks/lib/hook-runner.js pipeline-observer
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { pathToFileURL } from 'url';
+
+/**
+ * 向上查找 .autospec 目录
+ * @param {string} startDir - 开始查找的目录
+ * @returns {string|null} - 找到的项目根目录，或 null
+ */
+function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, '.autospec'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+/**
+ * 主函数
+ */
+async function main() {
+  // 获取要运行的 hook 名称
+  const hookName = process.argv[2];
+
+  if (!hookName) {
+    console.error('[Hook Runner] Error: No hook name provided');
+    console.error('Usage: node hook-runner.js <hook-name>');
+    process.exit(0);
+  }
+
+  // 从当前工作目录向上查找 .autospec 目录
+  const cwd = process.cwd();
+  const projectRoot = findProjectRoot(cwd);
+
+  if (!projectRoot) {
+    // 没有找到 .autospec 目录，静默退出
+    if (process.env.DEBUG || process.env.VERBOSE) {
+      console.error(`[Hook Runner] No .autospec directory found from ${cwd}`);
+    }
+    process.exit(0);
+  }
+
+  // 构建 hook 脚本路径
+  const hookScriptPath = path.join(projectRoot, '.autospec', 'plugins', 'hooks', `${hookName}.js`);
+
+  if (!fs.existsSync(hookScriptPath)) {
+    console.error(`[Hook Runner] Error: Hook script not found: ${hookScriptPath}`);
+    process.exit(0);
+  }
+
+  if (process.env.DEBUG || process.env.VERBOSE) {
+    console.error(`[Hook Runner] Loading hook: ${hookName} from ${hookScriptPath}`);
+  }
+
+  try {
+    // 动态导入并执行 hook 脚本（ESM）
+    const hookUrl = pathToFileURL(hookScriptPath).href;
+    await import(hookUrl);
+
+  } catch (err) {
+    console.error(`[Hook Runner] Error loading hook ${hookName}:`, err.message);
+    if (process.env.DEBUG || process.env.VERBOSE) {
+      console.error(err.stack);
+    }
+    process.exit(0);
+  }
+}
+
+main().catch((err) => {
+  console.error('[Hook Runner] Unexpected error:', err.message);
+  process.exit(0);
+});

package/plugins/hooks/lib/hook-runner.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+#
+# AutoSpec Hook Runner Shell Wrapper
+#
+# 此脚本解决子目录工作时相对路径无法正确解析的问题。
+# 它会从当前目录向上查找 .autospec 目录，然后执行对应的 hook。
+#
+# 使用方式：
+# .autospec/plugins/hooks/lib/hook-runner.sh <hook-name>
+#
+
+set -e
+
+# 获取 hook 名称
+HOOK_NAME="${1:-}"
+
+if [ -z "$HOOK_NAME" ]; then
+  echo "[Hook Runner] Error: No hook name provided" >&2
+  echo "Usage: hook-runner.sh <hook-name>" >&2
+  exit 0
+fi
+
+# 向上查找 .autospec 目录
+DIR="$(pwd)"
+while [ "$DIR" != "/" ] && [ ! -d "$DIR/.autospec" ]; do
+  DIR="$(dirname "$DIR")"
+done
+
+# 检查是否找到
+if [ ! -d "$DIR/.autospec" ]; then
+  # 没有找到 .autospec 目录，静默退出
+  exit 0
+fi
+
+# 构建 hook 脚本路径
+HOOK_SCRIPT="$DIR/.autospec/plugins/hooks/lib/hook-runner.js"
+
+if [ ! -f "$HOOK_SCRIPT" ]; then
+  echo "[Hook Runner] Error: Hook runner not found: $HOOK_SCRIPT" >&2
+  exit 0
+fi
+
+# 执行 hook
+exec node "$HOOK_SCRIPT" "$HOOK_NAME"