@chongyan/autospec 1.0.1

package/scripts/install/hook-logger.js

@@ -0,0 +1,536 @@
+/**
+ * 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
+ */
+export function info(message, meta = {}) {
+  if (currentLevel >= LOG_LEVELS.INFO) {
+    console.log(formatMessage(LOG_LEVELS.INFO, message, meta));
+  }
+}
+
+/**
+ * Log debug message (only in verbose mode)
+ */
+export function debug(message, meta = {}) {
+  if (currentLevel >= LOG_LEVELS.DEBUG) {
+    console.log(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/scripts/install/hooks.js

@@ -0,0 +1,110 @@
+/**
+ * Hooks generator for Claude Code integration
+ *
+ * Generates hooks configuration for deterministic guardrails
+ * (frozen zone, Layer 1, practice log, etc.)
+ *
+ * Note: Hook scripts are in plugins/hooks/ and are copied
+ * as part of the init process.
+ *
+ * Using inline bash command to support working from subdirectories.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { HOOKS_CONFIG } from '../config/hooks.config.js';
+
+/**
+ * Generate hooks configuration using declarative config
+ * @param {string} claudeDir - Target .claude directory path
+ * @param {string} autospecDir - Target .autospec directory path
+ */
+export function generateHooksConfig(claudeDir, autospecDir) {
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  for (const [eventName, hooks] of Object.entries(HOOKS_CONFIG)) {
+    if (!settings.hooks[eventName]) {
+      settings.hooks[eventName] = [];
+    }
+
+    for (const hook of hooks) {
+      const hookName = extractHookName(hook.script);
+      // 使用内联 bash 命令，从当前目录向上查找 .autospec 目录
+      // 这样可以支持在子目录中工作
+      const command = buildHookCommand(hookName);
+
+      upsertHookByName(
+        settings.hooks[eventName],
+        hook.matcher || '',
+        command,
+        hook.name
+      );
+    }
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+}
+
+/**
+ * 构建 hook 命令 - 支持从子目录执行
+ * @param {string} hookName - Hook 名称
+ * @returns {string} 完整的命令字符串
+ */
+function buildHookCommand(hookName) {
+  // 使用内联 bash 命令：
+  // 1. 从当前目录向上查找 .autospec 目录
+  // 2. 找到后执行对应的 hook 脚本
+  return `bash -c 'DIR=$(pwd); while [ "$DIR" != "/" ] && [ ! -d "$DIR/.autospec" ]; do DIR=$(dirname "$DIR"); done; [ -d "$DIR/.autospec" ] && node "$DIR/.autospec/plugins/hooks/lib/hook-runner.js" ${hookName} || true'`;
+}
+
+/**
+ * 从脚本路径提取 hook 名称
+ * 例如: 'plugins/hooks/pipeline-observer.js' -> 'pipeline-observer'
+ */
+function extractHookName(scriptPath) {
+  const filename = path.basename(scriptPath, '.js');
+  return filename;
+}
+
+/**
+ * Add or update a named hook entry
+ * @param {Array} hookArray - Array of hook configurations
+ * @param {string} matcher - Tool matcher pattern
+ * @param {string} command - Hook command to execute
+ * @param {string} name - Hook name for identification
+ */
+function upsertHookByName(hookArray, matcher, command, name) {
+  const existing = hookArray.findIndex(h =>
+    h.hooks?.some(hook =>
+      (typeof hook === 'string' ? hook : hook.command || '').includes(name)
+    )
+  );
+
+  const entry = {
+    matcher,
+    hooks: [{ type: 'command', command }]
+  };
+
+  if (existing >= 0) {
+    hookArray[existing] = entry;
+  } else {
+    hookArray.push(entry);
+  }
+}
+
+/**
+ * Note: copyHookScripts function has been removed.
+ * Hook scripts are now in plugins/hooks/ and are copied
+ * as part of the init process.
+ */

package/scripts/install/index.js

@@ -0,0 +1,39 @@
+/**
+ * Generators module
+ *
+ * Exports all generator functions for Claude Code integration.
+ */
+
+import path from 'path';
+import { generateSkills } from './skills.js';
+import { generateAgents } from './agents.js';
+import { generateHooksConfig } from './hooks.js';
+
+export { generateSkills } from './skills.js';
+export { generateAgents } from './agents.js';
+export { generateHooksConfig } from './hooks.js';
+
+// Re-export commands module
+export {
+  generateCommands,
+  clearTemplateCache,
+  getTemplateCacheStats,
+  getInternalCommandNames,
+  generateInternalCommands
+} from './commands.js';
+
+/**
+ * Generate all Claude Code integration files (skills + agents + hooks)
+ * This is the main entry point for generating Claude Code integration.
+ *
+ * Note: Hook scripts are in plugins/hooks/ and are copied
+ * as part of the init process.
+ */
+export function generateIntegration(targetDir) {
+  const claudeDir = path.join(targetDir, '.claude');
+  const autospecDir = path.join(targetDir, '.autospec');
+
+  generateSkills(claudeDir);
+  generateAgents(claudeDir);
+  generateHooksConfig(claudeDir, autospecDir);
+}