autosnippet 3.2.1 → 3.2.2

package/lib/cli/SetupService.js

@@ -5,7 +5,8 @@
  *
  *   Step 1  .autosnippet/ 运行时目录 + config.json + .gitignore
  *   Step 2  AutoSnippet/ 子仓库（核心数据 + 权限能力 + skills/）
- *   Step 3  IDE 集成（VSCode MCP + Cursor MCP + copilot-instructions + cursor-rules + skills-template）
+ *   Step 3  IDE 集成（VSCode MCP + Cursor MCP + copilot-instructions + cursor-rules
+ *           + skills-template + cursor-workflow + claude-hooks + guard-ci + pre-commit-hook）
  *   Step 4  SQLite 数据库 + V1 数据迁移
  *   Step 5  平台相关初始化（macOS → Xcode Snippets）
  *
@@ -432,24 +433,26 @@ export class SetupService {
   /* ═══ Step 3: IDE 集成 ═══════════════════════════════ */
 
   stepIDE() {
+    const configured = [];
+
+    // MCP 配置（总是写入/合并，不会跳过）
     this._configureVSCodeMCP();
+    configured.push('vscode-mcp');
     this._configureCursorMCP();
-    this._copyCopilotInstructions();
-    this._generateAgentInstructionFiles();
-    this._copyCursorRules();
-    this._copySkillsTemplate();
+    configured.push('cursor-mcp');
+
+    // 模板文件（可能因已存在/用户文件而跳过）
+    if (this._copyCopilotInstructions()) configured.push('copilot-instructions');
+    if (this._generateAgentInstructionFiles()) configured.push('agent-instructions');
+    if (this._copyCursorRules()) configured.push('cursor-rules');
+    if (this._copySkillsTemplate()) configured.push('skills-template');
+    if (this._copyCursorWorkflow()) configured.push('cursor-workflow');
+    if (this._copyClaudeHooks()) configured.push('claude-hooks');
+    if (this._copyGuardCI()) configured.push('guard-ci');
+    if (this._installPreCommitHook()) configured.push('pre-commit-hook');
     // NOTE: .qoder/ .trae/ 不再自动创建，用户可通过 `asd mirror` 按需生成
 
     const extResult = this._installVSCodeExtension();
-
-    const configured = [
-      'vscode-mcp',
-      'cursor-mcp',
-      'copilot-instructions',
-      'agent-instructions',
-      'cursor-rules',
-      'skills-template',
-    ];
     if (extResult) {
       configured.push(...extResult);
     }
@@ -711,23 +714,24 @@ export class SetupService {
   _copyCopilotInstructions() {
     const src = join(REPO_ROOT, 'templates', 'copilot-instructions.md');
     if (!existsSync(src)) {
-      return;
+      return false;
     }
 
     const destDir = join(this.projectRoot, '.github');
     const dest = join(destDir, 'copilot-instructions.md');
     if (existsSync(dest) && !this.force) {
-      return;
+      return false;
     }
 
     // 即使 --force，也不覆盖用户原有的非 AutoSnippet 文件
     const { canWrite } = checkWriteSafety(dest);
     if (!canWrite) {
-      return;
+      return false;
     }
 
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
+    return true;
   }
 
   /**
@@ -737,6 +741,7 @@ export class SetupService {
    */
   _generateAgentInstructionFiles() {
     const projectName = this.projectRoot.split('/').pop();
+    let wrote = false;
 
     // AGENTS.md
     const agentsPath = join(this.projectRoot, 'AGENTS.md');
@@ -771,6 +776,7 @@ export class SetupService {
           '',
         ].join('\n');
         writeFileSync(agentsPath, agentsContent);
+        wrote = true;
       } else {
       }
     }
@@ -803,44 +809,169 @@ export class SetupService {
           '',
         ].join('\n');
         writeFileSync(claudePath, claudeContent);
+        wrote = true;
       } else {
       }
     }
+    return wrote;
   }
 
   /** @private .cursor/rules/autosnippet-conventions.mdc */
   _copyCursorRules() {
     const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-conventions.mdc');
     if (!existsSync(src)) {
-      return;
+      return false;
     }
 
     const destDir = join(this.projectRoot, '.cursor', 'rules');
     const dest = join(destDir, 'autosnippet-conventions.mdc');
     if (existsSync(dest) && !this.force) {
-      return;
+      return false;
     }
 
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
+    return true;
   }
 
   /** @private .cursor/rules/autosnippet-skills.mdc — Project Skills 索引模板 */
   _copySkillsTemplate() {
     const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-skills.mdc');
     if (!existsSync(src)) {
-      return;
+      return false;
     }
 
     const destDir = join(this.projectRoot, '.cursor', 'rules');
     const dest = join(destDir, 'autosnippet-skills.mdc');
     if (existsSync(dest) && !this.force) {
-      return;
+      return false;
+    }
+
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    return true;
+  }
+  /** @private .cursor/rules/autosnippet-workflow.mdc — TaskGraph & Guard 工作流 */
+  _copyCursorWorkflow() {
+    const src = join(REPO_ROOT, 'templates', 'cursor-rules', 'autosnippet-workflow.mdc');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    const destDir = join(this.projectRoot, '.cursor', 'rules');
+    const dest = join(destDir, 'autosnippet-workflow.mdc');
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    return true;
+  }
+
+  /**
+   * @private .claude/hooks.yaml — Claude Code SessionStart hook
+   * 会话开始时自动 prime TaskGraph 上下文
+   */
+  _copyClaudeHooks() {
+    const src = join(REPO_ROOT, 'templates', 'claude-hooks.yaml');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    const claudeDir = join(this.projectRoot, '.claude');
+    const dest = join(claudeDir, 'hooks.yaml');
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    // 即使 --force，也不覆盖用户自己的 hooks 文件
+    const { canWrite } = checkWriteSafety(dest);
+    if (!canWrite) {
+      return false;
+    }
+
+    mkdirSync(claudeDir, { recursive: true });
+    copyFileSync(src, dest);
+    return true;
+  }
+
+  /**
+   * @private .github/workflows/autosnippet-guard.yml — Guard CI/CD workflow
+   * 在 push/PR 时自动运行 Guard 合规检查
+   */
+  _copyGuardCI() {
+    const src = join(REPO_ROOT, 'templates', 'guard-ci.yml');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    const destDir = join(this.projectRoot, '.github', 'workflows');
+    const dest = join(destDir, 'autosnippet-guard.yml');
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    const { canWrite } = checkWriteSafety(dest);
+    if (!canWrite) {
+      return false;
     }
 
     mkdirSync(destDir, { recursive: true });
     copyFileSync(src, dest);
+    return true;
   }
+
+  /**
+   * @private .git/hooks/pre-commit — Guard pre-commit hook
+   * 如果项目使用 husky，则安装到 .husky/pre-commit
+   * 否则安装到 .git/hooks/pre-commit
+   * 已存在 pre-commit hook 时不覆盖（避免破坏用户现有 hook）
+   */
+  _installPreCommitHook() {
+    const src = join(REPO_ROOT, 'templates', 'pre-commit-guard.sh');
+    if (!existsSync(src)) {
+      return false;
+    }
+
+    // 优先检查 husky
+    const huskyDir = join(this.projectRoot, '.husky');
+    const gitHooksDir = join(this.projectRoot, '.git', 'hooks');
+
+    let dest;
+    if (existsSync(huskyDir)) {
+      // 项目使用 husky — 安装到 .husky/pre-commit
+      dest = join(huskyDir, 'pre-commit');
+    } else if (existsSync(join(this.projectRoot, '.git'))) {
+      // 普通 git 项目 — 安装到 .git/hooks/pre-commit
+      dest = join(gitHooksDir, 'pre-commit');
+      mkdirSync(gitHooksDir, { recursive: true });
+    } else {
+      // 非 git 项目，跳过
+      return false;
+    }
+
+    // 已存在 pre-commit hook 时不覆盖（可能是用户自己的 hook）
+    if (existsSync(dest) && !this.force) {
+      return false;
+    }
+
+    // 即使 --force，也不覆盖用户自己的 pre-commit hook
+    const { canWrite } = checkWriteSafety(dest);
+    if (!canWrite) {
+      return false;
+    }
+
+    copyFileSync(src, dest);
+    // 确保可执行
+    try {
+      execSync(`chmod +x "${dest}"`, { stdio: 'pipe' });
+    } catch {
+      /* Windows 不需要 chmod */
+    }
+    return true;
+  }
+
   /** @private 镜像 .cursor/rules/ 中的 autosnippet-* 文件到目标 IDE 目录（Qoder / Trae 兼容）
    *  只复制 autosnippet- 前缀的文件，不触碰用户自己创建的规则 */
   _mirrorCursorToIDE(targetDirName) {

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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autosnippet",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Extract code patterns into a knowledge base for AI coding assistants",
   "type": "module",
   "main": "lib/bootstrap.js",

package/templates/claude-hooks.yaml

@@ -1,4 +1,5 @@
 # AutoSnippet Claude Code Hooks
+# Auto-generated by AutoSnippet. Do not edit manually.
 #
 # 用法：将此文件放到项目 .claude/ 目录下
 # Claude Code 在会话开始时会自动执行 SessionStart hook

package/templates/copilot-instructions.md

@@ -1,5 +1,7 @@
 # AutoSnippet Copilot Instructions
 
+> Auto-generated by AutoSnippet. Do not edit manually — regenerated on `asd setup` / `asd bootstrap`.
+
 ## 项目概览
 - 项目名称：AutoSnippet
 - 版本：V3（ESM, SQLite, MCP 11 工具 — 整合版）

package/templates/guard-ci.yml

@@ -1,4 +1,5 @@
 # AutoSnippet Guard CI/CD Check
+# Auto-generated by AutoSnippet. Do not edit manually.
 # 在 push 和 PR 时自动运行 Guard 合规检查
 #
 # 使用方法：将此文件复制到项目的 .github/workflows/ 目录

package/templates/pre-commit-guard.sh

@@ -1,6 +1,7 @@
 #!/bin/sh
 # AutoSnippet Guard pre-commit hook
-# 
+# Auto-generated by AutoSnippet. Do not edit manually.
+#
 # 安装方法：
 #   cp templates/pre-commit-guard.sh .git/hooks/pre-commit
 #   chmod +x .git/hooks/pre-commit