autosnippet 3.1.15 → 3.2.2

package/lib/http/routes/guard.js

@@ -0,0 +1,283 @@
+/**
+ * Guard 文件检查 API 路由
+ *
+ * 提供 HTTP 端点供 VS Code Extension 调用，触发 Guard 实时检查。
+ * 返回格式面向 IDE DiagnosticCollection 优化。
+ *
+ * 端点:
+ *   POST /api/v1/guard/file   — 单文件检查（Extension onDidSave 调用）
+ *   POST /api/v1/guard/batch  — 批量文件检查（Extension 工作区扫描）
+ */
+
+import { readFileSync } from 'node:fs';
+import express from 'express';
+import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import { asyncHandler } from '../middleware/errorHandler.js';
+
+const router = express.Router();
+
+/**
+ * POST /api/v1/guard/file
+ *
+ * 请求体:
+ *   { filePath: string, content?: string, language?: string }
+ *
+ *   - filePath: 必须。文件路径（用于语言检测 + 违规追踪）
+ *   - content:  可选。文件内容，若省略则从 filePath 磁盘读取
+ *   - language: 可选。语言标识，若省略则从 filePath 扩展名推断
+ *
+ * 响应:
+ *   {
+ *     success: true,
+ *     data: {
+ *       filePath, language, violations[], summary,
+ *       fixedViolations[]  // 与上次检查对比已修复的违规
+ *     }
+ *   }
+ */
+router.post(
+  '/file',
+  asyncHandler(async (req, res) => {
+    const { filePath, content, language } = req.body;
+
+    if (!filePath) {
+      return res.status(400).json({
+        success: false,
+        message: 'filePath is required',
+      });
+    }
+
+    // 获取文件内容
+    let code = content;
+    if (!code) {
+      try {
+        code = readFileSync(filePath, 'utf8');
+      } catch (err) {
+        return res.status(400).json({
+          success: false,
+          message: `Cannot read file: ${err.message}`,
+        });
+      }
+    }
+
+    const container = getServiceContainer();
+    const { GuardCheckEngine, detectLanguage } = await import(
+      '../../service/guard/GuardCheckEngine.js'
+    );
+
+    // 获取 Engine（含 EP 注入）
+    const engine = await _getEngine(container, GuardCheckEngine);
+
+    // 检测语言
+    const lang = language || detectLanguage(filePath);
+
+    // 执行检查
+    const violations = engine.checkCode(code, lang, { filePath });
+
+    // 格式化违规消息面向 Agent
+    const formattedViolations = violations.map((v) => ({
+      ...v,
+      // 面向 Agent 的诊断消息格式
+      diagnosticMessage: _buildDiagnosticMessage(v),
+    }));
+
+    const summary = {
+      total: violations.length,
+      errors: violations.filter((v) => v.severity === 'error').length,
+      warnings: violations.filter((v) => v.severity === 'warning').length,
+      infos: violations.filter((v) => v.severity === 'info').length,
+    };
+
+    // GuardFeedbackLoop: 检测修复 + confirmUsage
+    let fixedViolations = [];
+    try {
+      const feedbackLoop = container.get('guardFeedbackLoop');
+      fixedViolations = feedbackLoop.processFixDetection({ violations }, filePath);
+    } catch {
+      /* feedbackLoop not available */
+    }
+
+    // 写入 ViolationsStore（供后续对比）
+    try {
+      const violationsStore = container.get('violationsStore');
+      violationsStore.appendRun({
+        filePath,
+        violations,
+        summary: `Guard file check: ${summary.errors}E ${summary.warnings}W ${summary.infos}I`,
+      });
+    } catch {
+      /* violationsStore not available */
+    }
+
+    res.json({
+      success: true,
+      data: {
+        filePath,
+        language: lang,
+        violations: formattedViolations,
+        summary,
+        fixedViolations,
+      },
+    });
+  })
+);
+
+/**
+ * POST /api/v1/guard/batch
+ *
+ * 请求体:
+ *   { files: Array<{ filePath: string, content?: string, language?: string }> }
+ *
+ * 批量检查多个文件（工作区级 Guard 扫描）
+ */
+router.post(
+  '/batch',
+  asyncHandler(async (req, res) => {
+    const { files } = req.body;
+
+    if (!Array.isArray(files) || files.length === 0) {
+      return res.status(400).json({
+        success: false,
+        message: 'files array is required and must not be empty',
+      });
+    }
+
+    // 限制单次批量不超过 50 个文件
+    if (files.length > 50) {
+      return res.status(400).json({
+        success: false,
+        message: 'Maximum 50 files per batch',
+      });
+    }
+
+    const container = getServiceContainer();
+    const { GuardCheckEngine, detectLanguage } = await import(
+      '../../service/guard/GuardCheckEngine.js'
+    );
+
+    const engine = await _getEngine(container, GuardCheckEngine);
+
+    const results = [];
+    let totalErrors = 0;
+    let totalWarnings = 0;
+
+    for (const file of files) {
+      if (!file.filePath) continue;
+
+      let code = file.content;
+      if (!code) {
+        try {
+          code = readFileSync(file.filePath, 'utf8');
+        } catch {
+          results.push({
+            filePath: file.filePath,
+            language: 'unknown',
+            violations: [],
+            summary: { total: 0, errors: 0, warnings: 0, infos: 0 },
+            error: 'Cannot read file',
+          });
+          continue;
+        }
+      }
+
+      const lang = file.language || detectLanguage(file.filePath);
+      const violations = engine.checkCode(code, lang, { filePath: file.filePath });
+
+      const summary = {
+        total: violations.length,
+        errors: violations.filter((v) => v.severity === 'error').length,
+        warnings: violations.filter((v) => v.severity === 'warning').length,
+        infos: violations.filter((v) => v.severity === 'info').length,
+      };
+
+      totalErrors += summary.errors;
+      totalWarnings += summary.warnings;
+
+      results.push({
+        filePath: file.filePath,
+        language: lang,
+        violations: violations.map((v) => ({
+          ...v,
+          diagnosticMessage: _buildDiagnosticMessage(v),
+        })),
+        summary,
+      });
+    }
+
+    res.json({
+      success: true,
+      data: {
+        files: results,
+        summary: {
+          totalFiles: results.length,
+          totalErrors,
+          totalWarnings,
+        },
+      },
+    });
+  })
+);
+
+// ═══ 内部工具 ═══════════════════════════════════════
+
+/**
+ * 获取或创建 GuardCheckEngine，并注入 Enhancement Pack 规则
+ * @param {object} container - ServiceContainer
+ * @param {Function} GuardCheckEngine - GuardCheckEngine class
+ * @returns {object} engine
+ */
+async function _getEngine(container, GuardCheckEngine) {
+  let engine;
+  try {
+    engine = container.get('guardCheckEngine');
+  } catch {
+    const database = container.get('database');
+    engine = new GuardCheckEngine(database);
+  }
+
+  // 注入 Enhancement Pack Guard 规则
+  if (!engine.isEpInjected()) {
+    try {
+      const { getEnhancementRegistry } = await import(
+        '../../core/enhancement/index.js'
+      );
+      const registry = getEnhancementRegistry();
+      if (registry) {
+        const guardRules = registry.getGuardRules?.() || [];
+        engine.injectExternalRules(guardRules);
+        engine.markEpInjected();
+      }
+    } catch {
+      /* EP not available */
+    }
+  }
+
+  return engine;
+}
+
+/**
+ * 构建面向 Agent 优化的诊断消息
+ *
+ * 双重受众设计：
+ *   - 人类看到: 波浪线 + 违规描述
+ *   - Agent 看到: ruleId + 明确的 MCP 搜索指令
+ *
+ * @param {object} violation
+ * @returns {string}
+ */
+function _buildDiagnosticMessage(violation) {
+  const { ruleId, message, fixSuggestion } = violation;
+
+  let msg = `[AutoSnippet Guard] ${ruleId}: ${message}`;
+
+  if (fixSuggestion) {
+    msg += `\n修复建议: ${fixSuggestion}`;
+  }
+
+  // Agent 指引：嵌入 MCP 搜索建议
+  msg += `\n搜 autosnippet_search('${ruleId}') 查找正确写法。`;
+
+  return msg;
+}
+
+export default router;

package/lib/http/routes/task.js

@@ -0,0 +1,282 @@
+/**
+ * TaskGraph HTTP API 路由
+ *
+ * 为 VS Code Extension `taskTool.ts` 提供 HTTP 转发端点。
+ * Extension 通过 lm.registerTool 拦截 tokenBudget 后，
+ * 将业务逻辑转发到此端点，由 TaskGraphService 执行。
+ *
+ * 端点:
+ *   POST /api/v1/task  — 统一入口（operation 路由）
+ */
+
+import express from 'express';
+import { getServiceContainer } from '../../injection/ServiceContainer.js';
+import { asyncHandler } from '../middleware/errorHandler.js';
+
+const router = express.Router();
+
+/**
+ * POST /api/v1/task
+ *
+ * 请求体:
+ *   { operation: string, ...params }
+ *
+ * 响应:
+ *   { success: boolean, data?: any, message?: string }
+ */
+router.post(
+  '/',
+  asyncHandler(async (req, res) => {
+    const container = getServiceContainer();
+    const taskService = container.get('taskGraphService');
+
+    if (!taskService) {
+      return res.status(503).json({
+        success: false,
+        message: 'TaskGraphService not available',
+      });
+    }
+
+    const body = req.body;
+    if (!body || typeof body !== 'object') {
+      return res.status(400).json({
+        success: false,
+        message: 'JSON body is required',
+      });
+    }
+
+    const { operation, ...params } = body;
+
+    if (!operation) {
+      return res.status(400).json({
+        success: false,
+        message: 'operation is required',
+      });
+    }
+
+    try {
+      const result = await _dispatch(taskService, operation, params);
+      if (result.success === false) {
+        return res.status(400).json(result);
+      }
+      return res.json(result);
+    } catch (err) {
+      return res.status(400).json({
+        success: false,
+        message: err.message,
+        operation,
+      });
+    }
+  })
+);
+
+/**
+ * 操作路由 — 与 MCP handler/task.js 保持一致
+ */
+async function _dispatch(svc, operation, params) {
+  switch (operation) {
+    case 'create':
+      return _create(svc, params);
+    case 'ready':
+      return _ready(svc, params);
+    case 'claim':
+      return _claim(svc, params);
+    case 'close':
+      return _close(svc, params);
+    case 'fail':
+      return _fail(svc, params);
+    case 'defer':
+      return _defer(svc, params);
+    case 'progress':
+      return _progress(svc, params);
+    case 'prime':
+      return _prime(svc);
+    case 'decompose':
+      return _decompose(svc, params);
+    case 'show':
+      return _show(svc, params);
+    case 'list':
+      return _list(svc, params);
+    case 'blocked':
+      return _blocked(svc);
+    case 'dep_add':
+      return _depAdd(svc, params);
+    case 'dep_tree':
+      return _depTree(svc, params);
+    case 'stats':
+      return _stats(svc);
+    default:
+      return { success: false, message: `Unknown operation: ${operation}` };
+  }
+}
+
+// ── create ──
+
+async function _create(svc, args) {
+  if (!args.title) {
+    return { success: false, message: 'title is required' };
+  }
+  const { task, isDuplicate } = await svc.create({
+    title: args.title,
+    description: args.description || '',
+    design: args.design || '',
+    acceptance: args.acceptance || '',
+    priority: args.priority ?? 2,
+    taskType: args.taskType || 'task',
+    parentId: args.parentId || null,
+  });
+  return {
+    success: true,
+    data: task.toJSON(),
+    message: isDuplicate
+      ? `Duplicate detected: ${task.id} already exists`
+      : `Created ${task.id}: ${task.title}`,
+  };
+}
+
+// ── ready ──
+
+async function _ready(svc, args) {
+  const tasks = await svc.ready({
+    limit: args.limit || 5,
+    withKnowledge: args.withKnowledge !== false,
+  });
+  return {
+    success: true,
+    data: tasks.map((t) => (t.toJSON ? t.toJSON() : t)),
+    count: tasks.length,
+  };
+}
+
+// ── claim ──
+
+async function _claim(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const task = await svc.claim(args.id, args.assignee || 'agent');
+  return { success: true, data: task.toJSON() };
+}
+
+// ── close ──
+
+async function _close(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const { task, newlyReady } = await svc.close(args.id, args.reason || 'Completed');
+  return {
+    success: true,
+    data: task.toJSON(),
+    newlyReady,
+    message: `Closed ${task.id}. ${newlyReady.length} tasks newly ready.`,
+  };
+}
+
+// ── fail ──
+
+async function _fail(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const task = await svc.fail(args.id, args.reason || '');
+  return { success: true, data: task.toJSON() };
+}
+
+// ── defer ──
+
+async function _defer(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const task = await svc.defer(args.id, args.reason || '');
+  return { success: true, data: task.toJSON() };
+}
+
+// ── progress ──
+
+async function _progress(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const task = await svc.progress(args.id, args.note || args.description || '');
+  return { success: true, data: task.toJSON() };
+}
+
+// ── prime ──
+
+async function _prime(svc) {
+  const result = await svc.prime({ withKnowledge: true });
+  return { success: true, data: result };
+}
+
+// ── decompose ──
+
+async function _decompose(svc, args) {
+  const epicId = args.parentId || args.id;
+  const subtasks = args.children || args.subtasks;
+  if (!epicId) return { success: false, message: 'parentId (or id) is required' };
+  if (!subtasks || !Array.isArray(subtasks)) {
+    return { success: false, message: 'children (or subtasks) array is required' };
+  }
+  const tasks = await svc.decompose(epicId, subtasks);
+  return {
+    success: true,
+    data: tasks.map((t) => t.toJSON()),
+    count: tasks.length,
+  };
+}
+
+// ── show ──
+
+async function _show(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const task = await svc.show(args.id);
+  if (!task) return { success: false, message: `Task ${args.id} not found` };
+  return { success: true, data: task.toJSON() };
+}
+
+// ── list ──
+
+async function _list(svc, args) {
+  const tasks = await svc.list(
+    { status: args.status, taskType: args.taskType, parentId: args.parentId },
+    { limit: args.limit || 50 }
+  );
+  return {
+    success: true,
+    data: tasks.map((t) => t.toJSON()),
+    count: tasks.length,
+  };
+}
+
+// ── blocked ──
+
+async function _blocked(svc) {
+  const tasks = await svc.blocked();
+  return {
+    success: true,
+    data: tasks.map((t) => (t.toJSON ? t.toJSON() : t)),
+    count: tasks.length,
+  };
+}
+
+// ── dep_add ──
+
+async function _depAdd(svc, args) {
+  if (!args.taskId || !args.dependsOn) {
+    return { success: false, message: 'taskId and dependsOn are required' };
+  }
+  await svc.addDependency(args.taskId, args.dependsOn, args.depType || 'blocks');
+  return {
+    success: true,
+    message: `Dependency added: ${args.taskId} ${args.depType || 'blocks'} ${args.dependsOn}`,
+  };
+}
+
+// ── dep_tree ──
+
+async function _depTree(svc, args) {
+  if (!args.id) return { success: false, message: 'id is required' };
+  const tree = await svc.depTree(args.id);
+  return { success: true, data: tree };
+}
+
+// ── stats ──
+
+async function _stats(svc) {
+  const stats = await svc.stats();
+  return { success: true, data: stats };
+}
+
+export default router;

package/lib/infrastructure/config/Paths.js

@@ -5,15 +5,19 @@ import pathGuard from '../../shared/PathGuard.js';
 /**
  * Paths — 项目路径解析工具
  * 提供 Snippet 安装目录、缓存目录、知识库目录等路径计算能力。
- * 所有路径均自动确保目录存在。
+ *
+ * 设计原则：路径解析与目录创建分离
+ *  - 路径 getter 函数仅返回路径字符串，不产生文件系统副作用
+ *  - 需要创建目录时，调用方应使用 ensureDir() 显式确保目录存在
+ *  - 全局非项目目录（Xcode snippets、cache）在获取时自动创建
  */
 
 export const SPEC_FILENAME = 'AutoSnippet.boxspec.json';
 
 const USER_HOME = process.env.HOME || process.env.USERPROFILE || '';
 
-/** 确保目录存在（静默处理异常） */
-function ensureDir(dirPath) {
+/** 确保目录存在（静默处理异常），供写入前调用 */
+export function ensureDir(dirPath) {
   try {
     // 双层路径安全检查 — 阻止在项目允许范围外创建文件夹
     pathGuard.assertProjectWriteSafe(dirPath);
@@ -86,9 +90,10 @@ export function getKnowledgeBaseDirName(projectRoot) {
 
 /**
  * 知识库根目录 = projectRoot/{dirContainingBoxspec}
+ * 注意：仅返回路径，不创建目录
  */
 export function getProjectKnowledgePath(projectRoot) {
-  return ensureDir(path.join(projectRoot, getKnowledgeBaseDirName(projectRoot)));
+  return path.join(projectRoot, getKnowledgeBaseDirName(projectRoot));
 }
 
 /**
@@ -100,31 +105,35 @@ export function getProjectSpecPath(projectRoot) {
 
 /**
  * 项目内部隐藏数据目录 = knowledgePath/.autosnippet
+ * 注意：仅返回路径，不创建目录
  */
 export function getProjectInternalDataPath(projectRoot) {
-  return ensureDir(path.join(getProjectKnowledgePath(projectRoot), '.autosnippet'));
+  return path.join(getProjectKnowledgePath(projectRoot), '.autosnippet');
 }
 
 /**
  * 上下文存储目录 = internalData/context
+ * 注意：仅返回路径，不创建目录
  */
 export function getContextStoragePath(projectRoot) {
-  return ensureDir(path.join(getProjectInternalDataPath(projectRoot), 'context'));
+  return path.join(getProjectInternalDataPath(projectRoot), 'context');
 }
 
 /**
  * 上下文索引目录 = contextStorage/index
+ * 注意：仅返回路径，不创建目录
  */
 export function getContextIndexPath(projectRoot) {
-  return ensureDir(path.join(getContextStoragePath(projectRoot), 'index'));
+  return path.join(getContextStoragePath(projectRoot), 'index');
 }
 
 /**
  * 项目级 Skills 目录 = knowledgePath/skills
  * Skills 放在知识库目录下跟随项目走（Git-tracked，用户可见）
+ * 注意：仅返回路径，不创建目录
  */
 export function getProjectSkillsPath(projectRoot) {
-  return ensureDir(path.join(getProjectKnowledgePath(projectRoot), 'skills'));
+  return path.join(getProjectKnowledgePath(projectRoot), 'skills');
 }
 
 /**
@@ -143,6 +152,7 @@ export function getProjectRecipesPath(projectRoot, rootSpec) {
 
 export default {
   SPEC_FILENAME,
+  ensureDir,
   getSnippetsPath,
   getVSCodeSnippetsPath,
   getCachePath,