adspecs 0.1.12

package/bin/adspecs.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const path = require('path');
+const fs = require('fs');
+
+// 读取 package.json 获取版本号
+const pkgPath = path.resolve(__dirname, '..', 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+
+const program = new Command();
+
+program
+  .name('adspecs')
+  .description('adspecs — AI first 工程规范驱动开发 CLI')
+  .version(pkg.version, '-v, --version', '输出版本号');
+
+// ============ init 命令 ============
+program
+  .command('init')
+  .description('初始化项目目录结构（等价于 Claude Code 的 /project-init 技能）')
+  .option('--project-name <name>', '项目名称')
+  .option('--project-dir <dir>', '项目目录名（留空=当前目录）')
+  .option('--company <name>', '公司名称', 'XX有限公司')
+  .option('--confidentiality <level>', '文件密级: 公开|内部资料|机密|绝密', '内部资料')
+  .option('--mode <mode>', '初始化模式: simple|classic|full|demo')
+  .option('--front-demo <stack>', '前端演示技术栈: vue|antd', 'vue')
+  .option('--modules <list>', '后端模块列表（逗号分隔，格式 {port}-crm-{name}:{package}）')
+  .option('--non-interactive', '非交互模式，所有未提供的参数使用默认值')
+  .option('--force', '跳过冲突决策，所有已存在区域直接重新创建')
+  .option('-y, --yes', '自动确认执行（跳过执行前确认步骤，但保留冲突决策提示）')
+  .action(async (options) => {
+    try {
+      const initCmd = require('../src/commands/init');
+      await initCmd(options);
+    } catch (err) {
+      console.error('❌ 初始化失败:', err.message);
+      if (process.env.DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+// ============ plugin 命令组 ============
+const pluginCmd = program
+  .command('plugin')
+  .description('Claude Code 插件管理');
+
+pluginCmd
+  .command('install')
+  .description('注册当前 adspecs 为 Claude Code 插件')
+  .option('--scope <scope>', '安装范围: user|project', 'user')
+  .action(async (options) => {
+    try {
+      const pluginCmd = require('../src/commands/plugin');
+      await pluginCmd.install(options);
+    } catch (err) {
+      console.error('❌ 插件注册失败:', err.message);
+      if (process.env.DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+pluginCmd
+  .command('uninstall')
+  .description('从 Claude Code 中卸载 adspecs 插件')
+  .option('--scope <scope>', '卸载范围: user|project', 'user')
+  .action(async (options) => {
+    try {
+      const pluginCmd = require('../src/commands/plugin');
+      await pluginCmd.uninstall(options);
+    } catch (err) {
+      console.error('❌ 插件卸载失败:', err.message);
+      if (process.env.DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+// ============ doctor 命令 ============
+program
+  .command('doctor')
+  .description('检查环境依赖（Node.js、git、Python、PowerShell 等）')
+  .action(async () => {
+    try {
+      const doctorCmd = require('../src/commands/doctor');
+      await doctorCmd();
+    } catch (err) {
+      console.error('❌ 环境检查失败:', err.message);
+      if (process.env.DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+// ============ update 命令 ============
+program
+  .command('update')
+  .description('升级 adspecs 到最新版本（等价于 npm install -g adspecs@latest）')
+  .option('--version <version>', '升级到指定版本（默认 latest）')
+  .action(async (options) => {
+    try {
+      const updateCmd = require('../src/commands/update');
+      await updateCmd(options);
+    } catch (err) {
+      console.error('❌ 升级失败:', err.message);
+      if (process.env.DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  });
+
+// ============ 帮助信息增强 ============
+program.addHelpText('after', `
+示例:
+  $ adspecs init                              # 交互式初始化
+  $ adspecs init --mode simple                # 快速初始化（交互选择其余参数）
+  $ adspecs init --non-interactive            # 完全非交互（使用默认值）
+  $ adspecs init --project-name "我的项目" --mode full --front-demo antd
+  $ adspecs plugin install                    # 注册为 Claude Code 插件
+  $ adspecs doctor                            # 检查环境依赖
+  $ adspecs update                            # 升级到最新版本
+  $ adspecs update --version 0.2.0            # 升级到指定版本
+
+文档:
+  https://gitee.com/yuebon/adspecs
+`);
+
+program.parse();

package/hooks/commit-queue.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+
+/**
+ * Commit Queue — 跨平台 Hook 脚本
+ *
+ * 在 SessionStart / PostToolUse / Stop 三个 Hook 事件中管理 .commit-candidates 队列文件。
+ * 当检测到 pipeline-manifest.json 写入（且 status=completed + mvn_compile=pass），
+ * 自动将 feature 信息加入提交候选队列，Stop 时提示用户执行提交。
+ *
+ * 用法:
+ *   node hooks/commit-queue.js init      — SessionStart: 创建队列文件
+ *   node hooks/commit-queue.js enqueue   — PostToolUse: 检测 manifest 写入并入队
+ *   node hooks/commit-queue.js report    — Stop:        检查队列并输出提示
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── 配置 ──────────────────────────────────────────────
+// 队列文件放在目标项目根目录的 .claude/ 下。
+// 使用 process.cwd() 获取目标项目根目录（Claude Code 运行 hook 时 CWD 即为目标项目）。
+// 注意：不能用 __dirname，因为 __dirname 指向的是插件安装目录，而非用户的目标项目。
+const PROJECT_ROOT = process.cwd();
+const QUEUE_DIR = path.join(PROJECT_ROOT, '.claude');
+const QUEUE_FILE = path.join(QUEUE_DIR, '.commit-candidates');
+
+// ── 工具函数 ──────────────────────────────────────────
+
+/** 确保 .claude 目录和队列文件存在 */
+function ensureQueueFile() {
+  fs.mkdirSync(QUEUE_DIR, { recursive: true });
+  if (!fs.existsSync(QUEUE_FILE)) {
+    fs.writeFileSync(QUEUE_FILE, '', 'utf8');
+  }
+}
+
+/**
+ * 解析 pipeline-manifest.json 文件，提取提交候选信息。
+ * 返回 null 表示不满足提交条件（未完成或编译未通过）。
+ *
+ * @param {string} filePath - pipeline-manifest.json 的绝对路径
+ * @returns {object|null}
+ */
+function parseManifest(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  var manifest;
+  try {
+    var raw = fs.readFileSync(filePath, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (_err) {
+    // JSON 解析失败（文件可能正在写入），跳过
+    return null;
+  }
+
+  // 检查基本完成状态
+  if (!manifest || manifest.status !== 'completed') {
+    return null;
+  }
+
+  // 检查 TDD 验证中编译是否通过
+  var tdd = manifest.tdd_verification;
+  if (!tdd) {
+    // 没有 tdd_verification 字段时，检查是否有其他编译通过标记
+    if (!manifest.mvn_compile || manifest.mvn_compile !== 'pass') {
+      return null;
+    }
+  } else {
+    if (tdd.mvn_compile !== 'pass' && tdd.compile !== 'pass') {
+      return null;
+    }
+  }
+
+  // 提取候选信息
+  var feature = manifest.feature || '';
+  var modulePath = manifest.module_path || '';
+  var specDir = manifest.spec_dir || '';
+
+  // 尝试从文件路径推导 feature 和模块路径
+  if (!feature || !modulePath) {
+    var dirParts = path.dirname(filePath).split(path.sep);
+    // 从 45-specs/{feature}/ 路径推导
+    for (var i = 0; i < dirParts.length; i++) {
+      if (dirParts[i] === '45-specs' && i + 1 < dirParts.length) {
+        feature = feature || dirParts[i + 1];
+        break;
+      }
+    }
+    // 从 {code}-{name}-model-app/ 路径推导模块路径
+    for (var j = 0; j < dirParts.length; j++) {
+      if (dirParts[j].endsWith('-model-app')) {
+        modulePath = modulePath || dirParts.slice(0, j + 1).join(path.sep);
+        break;
+      }
+    }
+  }
+
+  if (!feature) {
+    return null; // 无法推导 feature 名称，跳过
+  }
+
+  return {
+    feature: feature,
+    modulePath: modulePath,
+    specDir: specDir || path.dirname(filePath),
+    manifestPath: filePath,
+    enrolledAt: new Date().toISOString()
+  };
+}
+
+/**
+ * 从 CLAUDE_TOOL_OUTPUT_FILES 环境变量中筛选 pipeline-manifest.json 文件，
+ * 解析并加入提交候选队列。
+ */
+function enqueueFromManifests(files) {
+  if (!files || (typeof files === 'string' && files.trim() === '')) {
+    return;
+  }
+
+  fs.mkdirSync(QUEUE_DIR, { recursive: true });
+
+  var candidatePaths = files
+    .split(/\r?\n/)
+    .map(function (f) { return f.trim(); })
+    .filter(function (f) { return f && f.endsWith('pipeline-manifest.json'); });
+
+  if (candidatePaths.length === 0) {
+    return;
+  }
+
+  // 读取已有队列，按 feature 名称去重
+  /** @type {Set<string>} */
+  var seen = new Set();
+  if (fs.existsSync(QUEUE_FILE)) {
+    var existingLines = fs.readFileSync(QUEUE_FILE, 'utf8')
+      .split(/\r?\n/)
+      .map(function (f) { return f.trim(); })
+      .filter(Boolean);
+    existingLines.forEach(function (f) {
+      try {
+        var entry = JSON.parse(f);
+        if (entry.feature) {
+          seen.add(entry.feature);
+        }
+      } catch (_err) {
+        // 兼容旧格式（非 JSON 行），按原值去重
+        seen.add(f);
+      }
+    });
+  }
+
+  var appended = 0;
+  candidatePaths.forEach(function (filePath) {
+    var candidate = parseManifest(filePath);
+    if (!candidate) {
+      return;
+    }
+
+    // 使用 feature 名称作为去重键
+    var key = candidate.feature;
+    if (seen.has(key)) {
+      return;
+    }
+
+    // 以 JSON 行格式写入队列
+    fs.appendFileSync(QUEUE_FILE, JSON.stringify(candidate) + '\n', 'utf8');
+    seen.add(key);
+    appended++;
+  });
+
+  if (appended > 0) {
+    console.log('[commit-queue] ' + appended + ' feature(s) ready for commit.');
+  }
+}
+
+/** 检查队列并在有待处理项时输出提示 */
+function checkAndReport() {
+  if (!fs.existsSync(QUEUE_FILE)) {
+    return;
+  }
+
+  var content;
+  try {
+    content = fs.readFileSync(QUEUE_FILE, 'utf8').trim();
+  } catch (_err) {
+    return;
+  }
+
+  if (!content) {
+    return;
+  }
+
+  var lines = content.split(/\r?\n/).filter(Boolean);
+  var count = lines.length;
+
+  if (count > 0) {
+    console.log('');
+    console.log('═══ [commit-queue] ═══════════════════════════════════');
+    console.log('[commit-queue] ' + count + ' feature(s) compiled and ready to commit:');
+    console.log('');
+
+    lines.forEach(function (line) {
+      try {
+        var candidate = JSON.parse(line);
+        console.log('  • ' + candidate.feature + (candidate.modulePath ? ' (' + candidate.modulePath + ')' : ''));
+      } catch (_err) {
+        console.log('  • ' + line);
+      }
+    });
+
+    console.log('');
+    console.log('[commit-queue] To commit with worktree isolation:');
+    console.log('[commit-queue]   /ai-softengineer:git-worktree-manager');
+    console.log('[commit-queue] To commit directly (no worktree):');
+    console.log('[commit-queue]   /ai-softengineer:git-commit');
+    console.log('══════════════════════════════════════════════════════');
+    console.log('');
+  }
+}
+
+// ── 主入口 ────────────────────────────────────────────
+
+var action = process.argv[2];
+
+switch (action) {
+  case 'init':
+    ensureQueueFile();
+    break;
+
+  case 'enqueue':
+    // CLAUDE_TOOL_OUTPUT_FILES 由 Claude Code Hook 运行时注入为环境变量
+    enqueueFromManifests(process.env.CLAUDE_TOOL_OUTPUT_FILES || '');
+    break;
+
+  case 'report':
+    checkAndReport();
+    break;
+
+  default:
+    console.error('[commit-queue] Unknown action: ' + (action || '(none)'));
+    console.error('[commit-queue] Usage: node hooks/commit-queue.js init|enqueue|report');
+    process.exit(1);
+}

package/hooks/hooks.json

@@ -0,0 +1,63 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/wiki-queue.js init"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js init"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/wiki-queue.js enqueue"
+          }
+        ],
+        "conditions": {
+          "filePattern": "\\.(java|py|ts|js|go|rs|cs|md)$"
+        }
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js enqueue"
+          }
+        ],
+        "conditions": {
+          "filePattern": "pipeline-manifest\\.json$"
+        }
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/wiki-queue.js report"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js report"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook — 注入 using-adspecs 技能引导内容
+ *
+ * 在每次会话启动时，读取 using-adspecs/SKILL.md 并输出为
+ * Claude Code hook additionalContext，确保 Agent 在任何任务开始前
+ * 都知道需要检查并使用 ADSpecs 技能。
+ *
+ * 机制参考：Superpowers hooks/session-start
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── 路径解析 ──────────────────────────────────────────
+// hooks/ 在项目根下，__dirname 总是指向 hooks/ 目录
+const PLUGIN_ROOT = path.join(__dirname, '..');
+const SKILL_PATH = path.join(PLUGIN_ROOT, 'skills', 'using-adspecs', 'SKILL.md');
+
+// ── 读取技能内容 ──────────────────────────────────────
+var skillContent;
+try {
+  skillContent = fs.readFileSync(SKILL_PATH, 'utf8');
+} catch (err) {
+  // 技能文件不存在，静默跳过
+  process.exit(0);
+}
+
+if (!skillContent || skillContent.trim() === '') {
+  process.exit(0);
+}
+
+// ── 输出 Hook Context ─────────────────────────────────
+// Claude Code hook command 输出 JSON 到 stdout，
+// hookSpecificOutput.additionalContext 会被注入到 Agent 上下文
+var output = {
+  hookSpecificOutput: {
+    hookEventName: 'SessionStart',
+    additionalContext: '<EXTREMELY-IMPORTANT>\n' + skillContent + '\n</EXTREMELY-IMPORTANT>'
+  }
+};
+
+process.stdout.write(JSON.stringify(output));

package/hooks/wiki-queue.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/**
+ * Wiki Update Queue — 跨平台 Hook 脚本
+ *
+ * 在 SessionStart / PostToolUse / Stop 三个 Hook 事件中管理 .wiki-update-queue 队列文件。
+ * 使用 Node.js（而非平台特定 Shell）确保 Windows / macOS / Linux 三平台兼容。
+ *
+ * 用法:
+ *   node hooks/wiki-queue.js init      — SessionStart: 创建队列文件
+ *   node hooks/wiki-queue.js enqueue   — PostToolUse: 追加变更文件路径到队列
+ *   node hooks/wiki-queue.js report    — Stop:        检查队列并输出提示
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── 配置 ──────────────────────────────────────────────
+// 队列文件放在目标项目根目录的 .claude/ 下。
+// 使用 process.cwd() 获取目标项目根目录（Claude Code 运行 hook 时 CWD 即为目标项目）。
+// 注意：不能用 __dirname，因为 __dirname 指向的是插件安装目录，而非用户的目标项目。
+const PROJECT_ROOT = process.cwd();
+const QUEUE_DIR = path.join(PROJECT_ROOT, '.claude');
+const QUEUE_FILE = path.join(QUEUE_DIR, '.wiki-update-queue');
+
+// ── 工具函数 ──────────────────────────────────────────
+
+/** 确保 .claude 目录和队列文件存在 */
+function ensureQueueFile() {
+  fs.mkdirSync(QUEUE_DIR, { recursive: true });
+  if (!fs.existsSync(QUEUE_FILE)) {
+    fs.writeFileSync(QUEUE_FILE, '', 'utf8');
+  }
+}
+
+/** 追加文件路径到队列（去重、过滤空行） */
+function appendToQueue(files) {
+  if (!files || (typeof files === 'string' && files.trim() === '')) {
+    return;
+  }
+
+  fs.mkdirSync(QUEUE_DIR, { recursive: true });
+
+  // 标准化：按行拆分，过滤空行
+  const newFiles = files
+    .split(/\r?\n/)
+    .map(function (f) { return f.trim(); })
+    .filter(Boolean);
+
+  if (newFiles.length === 0) {
+    return;
+  }
+
+  // 读取已有队列，去重追加
+  /** @type {Set<string>} */
+  var seen = new Set();
+  if (fs.existsSync(QUEUE_FILE)) {
+    var existing = fs.readFileSync(QUEUE_FILE, 'utf8')
+      .split(/\r?\n/)
+      .map(function (f) { return f.trim(); })
+      .filter(Boolean);
+    existing.forEach(function (f) { seen.add(f); });
+  }
+
+  var appended = 0;
+  newFiles.forEach(function (f) {
+    if (!seen.has(f)) {
+      fs.appendFileSync(QUEUE_FILE, f + '\n', 'utf8');
+      seen.add(f);
+      appended++;
+    }
+  });
+
+  if (appended > 0) {
+    console.log('[wiki-update] ' + appended + ' file(s) added to sync queue.');
+  }
+}
+
+/** 检查队列并在有待处理项时输出提示 */
+function checkAndReport() {
+  if (!fs.existsSync(QUEUE_FILE)) {
+    return;
+  }
+
+  var content;
+  try {
+    content = fs.readFileSync(QUEUE_FILE, 'utf8').trim();
+  } catch (_err) {
+    return;
+  }
+
+  if (!content) {
+    return;
+  }
+
+  var lines = content.split(/\r?\n/).filter(Boolean);
+  var count = lines.length;
+
+  if (count > 0) {
+    console.log('[wiki-update] ' + count + ' file(s) queued for wiki sync.');
+    console.log('[wiki-update] Run: /wiki-update --mode=incremental --flush');
+  }
+}
+
+// ── 主入口 ────────────────────────────────────────────
+
+var action = process.argv[2];
+
+switch (action) {
+  case 'init':
+    ensureQueueFile();
+    break;
+
+  case 'enqueue':
+    // CLAUDE_TOOL_OUTPUT_FILES 由 Claude Code Hook 运行时注入为环境变量
+    appendToQueue(process.env.CLAUDE_TOOL_OUTPUT_FILES || '');
+    break;
+
+  case 'report':
+    checkAndReport();
+    break;
+
+  default:
+    console.error('[wiki-update] Unknown action: ' + (action || '(none)'));
+    console.error('[wiki-update] Usage: node hooks/wiki-queue.js init|enqueue|report');
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "adspecs",
+  "version": "0.1.12",
+  "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
+  "bin": {
+    "adspecs": "./bin/adspecs.js"
+  },
+  "main": "./src/utils.js",
+  "files": [
+    "bin/",
+    "src/",
+    ".claude-plugin/",
+    ".qoder-plugin/",
+    ".adspecs/",
+    "skills/",
+    "hooks/",
+    "references/",
+    "scripts/postinstall.js",
+    "scripts/sync-version.js",
+    "CLAUDE.md",
+    "README.md",
+    "INSTALL.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "node scripts/prepublish-check.js",
+    "preversion": "node scripts/sync-version.js",
+    "sync-version": "node scripts/sync-version.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^4.1.2"
+  },
+  "devDependencies": {},
+  "keywords": [
+    "adspecs",
+    "claude-code",
+    "plugin",
+    "scaffold",
+    "cli",
+    "project-init",
+    "ai-first"
+  ],
+  "author": "Qingwen Chen <cqinwn@qq.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/yuebon/adspecs.git"
+  },
+  "homepage": "https://gitee.com/yuebon/adspecs#readme",
+  "bugs": {
+    "url": "https://gitee.com/yuebon/adspecs/issues"
+  }
+}