jsharness 1.0.2 → 1.1.1

package/bin/jsharness.js

@@ -1,14 +1,16 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * jsharness CLI
  * 
  * Usage:
- *   npx jsharness init              # 初始化（自动检测 AI 工具）
- *   npx jsharness init --tool codebuddy  # 指定工具
- *   npx jsharness init --stack vue3      # 指定技术栈
- *   npx jsharness list-tools        # 列出支持的工具
- *   npx jsharness status            # 查看当前状态
+ *   npx jsharness init                        # 交互式初始化（选择工具+技术栈）
+ *   npx jsharness init --tool codebuddy       # 指定工具（跳过工具选择）
+ *   npx jsharness init --stack vue3           # 指定技术栈（跳过技术栈选择）
+ *   npx jsharness init --tool cursor --stack all  # 全部指定，无交互
+ *   npx jsharness list-tools                  # 列出支持的工具
+ *   npx jsharness status                      # 查看当前状态
+ *   npx jsharness openspec list               # 列出 OpenSpec 变更
  */
 
 import { createRequire } from 'module';
@@ -17,7 +19,7 @@ import { program } from 'commander';
 const require = createRequire(import.meta.url);
 
 // 通过包名引用主库（npm 安装后兼容）
-const { runInit, listTools, showStatus } = await import('jsharness');
+const { runInit, listTools, showStatus, listOpenSpecChanges, archiveOpenSpecChange } = await import('jsharness');
 
 program
   .name('jsharness')
@@ -27,8 +29,8 @@ program
 program
   .command('init')
   .description('初始化 Harness 到当前项目的 AI 工具中')
-  .option('-t, --tool <name>', '指定目标 AI 工具')
-  .option('-s, --stack <name>', '指定技术栈 (vue3/java/all)', 'all')
+  .option('-t, --tool <name>', '指定目标 AI 工具（跳过交互选择）')
+  .option('-s, --stack <name>', '指定技术栈 vue3/java/all（跳过交互选择）')
   .option('--rules-only', '只注入规则，不注入技能')
   .option('--skills-only', '只注入技能，不注入规则')
   .option('--force', '覆盖已有配置')
@@ -45,6 +47,22 @@ program
   .description('查看当前项目 Harness 初始化状态')
   .action(() => showStatus(process.cwd()));
 
+// OpenSpec 子命令
+const openspecCmd = program
+  .command('openspec')
+  .description('OpenSpec 变更管理');
+
+openspecCmd
+  .command('list')
+  .description('列出所有 OpenSpec 变更')
+  .action(() => listOpenSpecChanges(process.cwd()));
+
+openspecCmd
+  .command('archive')
+  .description('归档一个已完成的 OpenSpec 变更')
+  .requiredOption('-c, --change <name>', '变更名称')
+  .action((opts) => archiveOpenSpecChange(process.cwd(), opts.change));
+
 program.parse(process.argv);
 
 // 无参数时默认执行 init

package/lib/index.mjs

@@ -7,6 +7,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import readline from 'readline';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -595,10 +596,110 @@ export function injectOutputs(projectDir, outputs, options = {}) {
 // CLI 命令实现
 // ============================================================
 
+// ============================================================
+// 交互式问答辅助函数
+// ============================================================
+
+/**
+ * 通用 readline 提问
+ */
+function askQuestion(query) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * 交互式选择 AI 编程工具
+ *
+ * 先自动检测，检测结果让用户确认或修改；
+ * 检测不到则展示列表让用户选择（支持多选，逗号分隔）。
+ *
+ * @param {string} projectDir
+ * @returns {Promise<string[]>} 选中的工具 ID 列表
+ */
+async function promptSelectTools(projectDir) {
+  const detected = detectTool(projectDir);
+
+  console.log('━━━ 选择 AI 编程工具 ━━━\n');
+
+  // 展示所有支持的工具
+  SUPPORTED_TOOLS.forEach((t, i) => {
+    const isDetected = detected.some(d => d.id === t.id);
+    console.log(`  ${String(i + 1).padStart(2)}. ${isDetected ? '✅' : '○ '} ${t.name}`);
+    console.log(`      ${t.description}`);
+  });
+
+  if (detected.length > 0) {
+    console.log(`\n  🔍 自动检测到: ${detected.map(t => t.name).join(', ')}`);
+    console.log(`  按回车使用检测结果，或输入编号选择其他工具\n`);
+  } else {
+    console.log('\n  未自动检测到 AI 工具，请手动选择\n');
+  }
+
+  const answer = await askQuestion('  请选择 (多选用逗号分隔，如 1,3): ');
+
+  // 回车 = 使用检测结果
+  if (!answer && detected.length > 0) {
+    return detected.map(t => t.id);
+  }
+
+  // 解析用户输入的编号
+  const indices = answer.split(/[,，\s]+/).map(s => parseInt(s, 10)).filter(n => !isNaN(n));
+  const selected = [];
+  for (const idx of indices) {
+    if (idx >= 1 && idx <= SUPPORTED_TOOLS.length) {
+      selected.push(SUPPORTED_TOOLS[idx - 1].id);
+    }
+  }
+
+  if (selected.length === 0) {
+    console.log('  ⚠️  无有效选择，默认使用 CodeBuddy 格式\n');
+    return [SUPPORTED_TOOLS[0].id];
+  }
+
+  return selected;
+}
+
+/**
+ * 交互式选择技术栈
+ *
+ * @returns {Promise<string>} 'vue3' | 'java' | 'all'
+ */
+async function promptSelectStack() {
+  console.log('━━━ 选择项目技术栈 ━━━\n');
+  console.log('  1. 🖥️  前端 (Vue3 + TypeScript + Element Plus)');
+  console.log('  2. ☕ 后端 (Spring Boot + JDK21 + MyBatis-Plus)');
+  console.log('  3. 🔗 前后端一起\n');
+
+  const answer = await askQuestion('  请选择 [1/2/3]: ');
+
+  const map = { '1': 'vue3', '2': 'java', '3': 'all' };
+  return map[answer] || 'all';
+}
+
+function stackLabel(stack) {
+  const labels = {
+    vue3: '前端 (Vue3 + TypeScript + Element Plus)',
+    java: '后端 (Spring Boot + JDK21 + MyBatis-Plus)',
+    all: '前后端一起',
+  };
+  return labels[stack] || stack;
+}
+
+
+
 export async function runInit(projectDir, options = {}) {
   const {
     tool: requestedTool,
-    stack = 'all',
+    stack: requestedStack,
     rulesOnly = false,
     skillsOnly = false,
     force = false,
@@ -619,7 +720,6 @@ export async function runInit(projectDir, options = {}) {
     console.error('   然后重新运行：');
     console.error('     npx jsharness init --verbose');
     console.error('');
-    // 输出调试信息
     const nmPath = path.join(projectDir, 'node_modules', 'jsharness', '.harness');
     console.error(`   [DEBUG] 项目目录: ${projectDir}`);
     console.error(`   [DEBUG] node_modules/jsharness/.harness 存在: ${fs.existsSync(nmPath) ? '是' : '否'}`);
@@ -627,33 +727,39 @@ export async function runInit(projectDir, options = {}) {
   }
   if (verbose) console.log(`   📂 Harness 源: ${harnessDir}`);
 
-  // 2. 检测或指定 AI 工具
+  // 2. 交互式选择 AI 工具
   let targetTools = [];
-  if (requestedTool) {
-    const found = SUPPORTED_TOOLS.find(t => t.id === requestedTool || t.name.includes(requestedTool));
+  const selectedToolIds = requestedTool
+    ? [requestedTool]
+    : await promptSelectTools(projectDir);
+
+  for (const tid of selectedToolIds) {
+    const found = SUPPORTED_TOOLS.find(t => t.id === tid || t.name.includes(tid));
     if (found) {
-      targetTools = [{ ...found, detected: true }];
-    } else {
-      console.error(`❌ 不支持的工具: ${requestedTool}`);
-      console.log(`   可用工具: ${SUPPORTED_TOOLS.map(t => t.id).join(', ')}`);
-      process.exit(1);
-    }
-  } else {
-    targetTools = detectTool(projectDir);
-    if (targetTools.length === 0) {
-      console.log('⚠️  未自动检测到 AI 工具。将使用默认模式（CodeBuddy 格式）。\n');
-      console.log('   提示: 使用 --tool <name> 指定工具，或运行 npx hariness list-tools 查看');
-      targetTools = [{ ...SUPPORTED_TOOLS[0], detected: true }]; // 默认 CodeBuddy
+      targetTools.push({ ...found, detected: true });
     } else {
-      console.log(`🔍 检测到的 AI 工具:`);
-      for (const t of targetTools) {
-        console.log(`   • ${t.name} (${t.description})`);
-      }
-      console.log('');
+      console.warn(`⚠️  不支持的工具: ${tid}，已跳过`);
     }
   }
 
-  // 3. 扫描源文件
+  if (targetTools.length === 0) {
+    console.error('❌ 未选择任何 AI 工具，初始化终止。');
+    process.exit(1);
+  }
+
+  console.log(`\n📋 选中的 AI 工具:`);
+  for (const t of targetTools) {
+    console.log(`   • ${t.name}`);
+  }
+
+  // 3. 交互式选择技术栈
+  let stack = requestedStack;
+  if (!stack) {
+    stack = await promptSelectStack();
+  }
+  console.log(`\n🏗️  技术栈: ${stackLabel(stack)}\n`);
+
+  // 4. 扫描源文件
   const allRuleFiles = scanHarnessRules(harnessDir, stack);
   const allSkillFiles = scanHarnessSkills(harnessDir, stack);
 
@@ -661,7 +767,7 @@ export async function runInit(projectDir, options = {}) {
     console.log(`📋 扫描结果: ${allRuleFiles.length} 个规则, ${allSkillFiles.length} 个技能\n`);
   }
 
-  // 4. 对每个目标工具执行注入
+  // 5. 对每个目标工具执行注入
   const summary = [];
 
   for (const tool of targetTools) {
@@ -671,7 +777,7 @@ export async function runInit(projectDir, options = {}) {
 
     // 注入 Rules
     if (!skillsOnly && allRuleFiles.length > 0) {
-      console.log(`\n📜 注入规则 (${allRuleFiles.length} 个)...`);
+      console.log(`📜 注入规则 (${allRuleFiles.length} 个)...`);
       const result = transformRules(allRuleFiles, tool.id, { stack });
       outputs.push(...result.files);
     }
@@ -689,7 +795,18 @@ export async function runInit(projectDir, options = {}) {
     summary.push({ tool: tool.name, written, skipped });
   }
 
-  // 5. 输出总结
+  // 6. 初始化 OpenSpec 变更管理目录（内聚在 jsharness 中，无需额外依赖）
+  console.log('\n━━━ 初始化 OpenSpec ━━━');
+  const openspecResult = initOpenSpec(projectDir, { force, verbose });
+  if (openspecResult.created.length > 0) {
+    console.log(`  ✅ 创建 ${openspecResult.created.length} 项:`);
+    openspecResult.created.forEach(f => console.log(`     - ${f}`));
+  }
+  if (openspecResult.skipped.length > 0) {
+    console.log(`  ⏭  跳过 ${openspecResult.skipped.length} 项 (已存在)`);
+  }
+
+  // 7. 输出总结
   console.log('\n═════════════════════════════');
   console.log('✅ 初始化完成！');
   
@@ -705,11 +822,17 @@ export async function runInit(projectDir, options = {}) {
     }
   }
 
+  if (openspecResult.created.length > 0) {
+    console.log(`\n  [OpenSpec]`);
+    console.log(`  ✅ 创建 ${openspecResult.created.length} 项`);
+  }
+
   if (!force && summary.some(s => s.skipped.length > 0)) {
     console.log('\n💡 提示: 使用 --force 可覆盖已有配置');
   }
 
-  console.log('\n🎉 Harness 规则已注入到你的 AI 工具中！开始对话即可生效。\n');
+  console.log('\n🎉 Harness 规则已注入到你的 AI 工具中！开始对话即可生效。');
+  console.log('📋 OpenSpec 变更管理已就绪，可使用 AI 工具的 openspec skill 创建变更。\n');
 }
 
 export function listTools() {
@@ -768,9 +891,201 @@ export function showStatus(projectDir) {
     console.log(`    ${exists ? '✅' : '○ '} ${t.name.padEnd(12)} ${t.path}`);
   }
 
+  // OpenSpec 状态
+  const openspecDir = path.join(projectDir, 'openspec');
+  const hasOpenSpec = fs.existsSync(openspecDir);
+  console.log(`\n  OpenSpec:    ${hasOpenSpec ? '✅ 已初始化' : '○  未初始化'}`);
+  if (hasOpenSpec) {
+    const changesDir = path.join(openspecDir, 'changes');
+    if (fs.existsSync(changesDir)) {
+      const active = fs.readdirSync(changesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && d.name !== 'archive');
+      const archiveDir = path.join(changesDir, 'archive');
+      const archived = fs.existsSync(archiveDir)
+        ? fs.readdirSync(archiveDir, { withFileTypes: true }).filter(d => d.isDirectory()).length
+        : 0;
+      console.log(`    活跃变更: ${active.length}  归档: ${archived}`);
+    }
+  }
+
   console.log('');
 }
 
+// ============================================================
+// OpenSpec 内聚初始化（无需额外 npm 依赖，直接创建目录结构）
+// ============================================================
+
+const OPENSPEC_DIRS = [
+  'openspec',
+  'openspec/changes',
+  'openspec/changes/archive',
+  'openspec/specs',
+];
+
+const OPENSPEC_GITIGNORE = `# OpenSpec generated files
+changes/*/dist/
+*.log
+`;
+
+/**
+ * 初始化 OpenSpec 目录结构到目标项目
+ *
+ * @param {string} projectDir - 目标项目根目录
+ * @param {object} options - 选项 { force, verbose }
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function initOpenSpec(projectDir, options = {}) {
+  const { force = false, verbose = false } = options;
+  const created = [];
+  const skipped = [];
+
+  for (const dir of OPENSPEC_DIRS) {
+    const fullPath = path.join(projectDir, dir);
+    if (fs.existsSync(fullPath)) {
+      if (verbose) console.log(`  ⏭  目录已存在: ${dir}/`);
+      skipped.push(dir);
+      continue;
+    }
+    fs.mkdirSync(fullPath, { recursive: true });
+    created.push(dir);
+    if (verbose) console.log(`  ✅ 创建目录: ${dir}/`);
+  }
+
+  // .gitkeep 确保空目录可被 git 追踪
+  for (const dir of ['openspec/changes/archive', 'openspec/specs']) {
+    const gitkeepPath = path.join(projectDir, dir, '.gitkeep');
+    if (!fs.existsSync(gitkeepPath)) {
+      fs.writeFileSync(gitkeepPath, '', 'utf-8');
+    }
+  }
+
+  // openspec/.gitignore
+  const gitignorePath = path.join(projectDir, 'openspec', '.gitignore');
+  if (!fs.existsSync(gitignorePath) || force) {
+    fs.writeFileSync(gitignorePath, OPENSPEC_GITIGNORE, 'utf-8');
+    if (!created.includes('openspec')) created.push('openspec/.gitignore');
+    if (verbose) console.log(`  ✅ 创建文件: openspec/.gitignore`);
+  } else {
+    skipped.push('openspec/.gitignore');
+  }
+
+  // openspec/README.md
+  const readmePath = path.join(projectDir, 'openspec', 'README.md');
+  if (!fs.existsSync(readmePath) || force) {
+    fs.writeFileSync(readmePath, generateOpenSpecReadme(), 'utf-8');
+    created.push('openspec/README.md');
+    if (verbose) console.log(`  ✅ 创建文件: openspec/README.md`);
+  } else {
+    skipped.push('openspec/README.md');
+  }
+
+  return { created, skipped };
+}
+
+function generateOpenSpecReadme() {
+  return `# OpenSpec 变更管理
+
+本目录由 Harness Engineering 系统自动创建，用于管理结构化变更。
+
+## 目录结构
+
+\`\`\`
+openspec/
+├── changes/           # 活跃的变更（每个 change 一个子目录）
+│   └── archive/       # 已归档的变更
+└── specs/             # 功能规格定义
+\`\`\`
+
+## 使用方式
+
+在 AI 对话中使用 OpenSpec skills：
+
+- **openspec-propose** — 创建新变更提案
+- **openspec-explore** — 探索和澄清需求
+- **openspec-apply-change** — 实施变更任务
+- **openspec-archive-change** — 归档已完成变更
+
+## 命令行操作
+
+\`\`\`bash
+# 查看状态
+npx jsharness status
+
+# 列出活跃变更
+npx jsharness openspec list
+
+# 归档变更
+npx jsharness openspec archive --change "<name>"
+\`\`\`
+
+> 本目录由 Harness Engineering 系统自动管理。
+`;
+}
+
+/**
+ * 列出当前项目的 OpenSpec changes
+ */
+export function listOpenSpecChanges(projectDir) {
+  const changesDir = path.join(projectDir, 'openspec', 'changes');
+  if (!fs.existsSync(changesDir)) {
+    console.log('\n⚠️  OpenSpec 尚未初始化。请先运行: npx jsharness init\n');
+    return;
+  }
+
+  const entries = fs.readdirSync(changesDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && d.name !== 'archive');
+
+  if (entries.length === 0) {
+    console.log('\n📋 没有活跃的 OpenSpec 变更\n');
+    return;
+  }
+
+  console.log('\n📋 OpenSpec 活跃变更:\n');
+  for (const entry of entries) {
+    const yamlPath = path.join(changesDir, entry.name, '.openspec.yaml');
+    let status = '(未知)';
+    if (fs.existsSync(yamlPath)) {
+      try {
+        const yaml = fs.readFileSync(yamlPath, 'utf-8');
+        const m = yaml.match(/status:\s*(.+)/);
+        if (m) status = m[1].trim();
+      } catch { /* ignore */ }
+    }
+    console.log(`  • ${entry.name}  ${status}`);
+  }
+
+  const archiveDir = path.join(changesDir, 'archive');
+  if (fs.existsSync(archiveDir)) {
+    const archived = fs.readdirSync(archiveDir, { withFileTypes: true })
+      .filter(d => d.isDirectory());
+    if (archived.length > 0) {
+      console.log('\n📦 已归档:');
+      for (const entry of archived) {
+        console.log(`  • ${entry.name}`);
+      }
+    }
+  }
+  console.log('');
+}
+
+/**
+ * 归档一个 OpenSpec change
+ */
+export function archiveOpenSpecChange(projectDir, changeName) {
+  const changesDir = path.join(projectDir, 'openspec', 'changes');
+  const sourceDir = path.join(changesDir, changeName);
+  const archiveDir = path.join(changesDir, 'archive', `${new Date().toISOString().split('T')[0]}-${changeName}`);
+
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`\n❌ 变更 "${changeName}" 不存在\n`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(path.join(changesDir, 'archive'), { recursive: true });
+  fs.renameSync(sourceDir, archiveDir);
+  console.log(`\n✅ 变更 "${changeName}" 已归档到 openspec/changes/archive/${path.basename(archiveDir)}/\n`);
+}
+
 // ============================================================
 // 内部：查找 Harness 源
 // ============================================================
@@ -780,7 +1095,13 @@ function findHarnessSource(projectDir) {
   const localHarness = path.join(projectDir, '.harness');
   if (fs.existsSync(localHarness)) return localHarness;
 
-  // 2. 通过 node_modules 查找（npm i -D jsharness 后）
+  // 2. 本包自身的 .harness/（最可靠：基于 lib/index.mjs 的位置定位）
+  //    lib/index.mjs 所在目录 = <pkg_root>/lib/
+  //    所以 .harness/ 在 <pkg_root>/.harness/ 即 __dirname/../.harness
+  const selfHarness = path.join(__dirname, '..', '.harness');
+  if (fs.existsSync(selfHarness)) return selfHarness;
+
+  // 3. 通过 node_modules 查找（npm i -D jsharness 后）
   const nmCandidates = [
     path.join(projectDir, 'node_modules', 'jsharness', '.harness'),
     path.join(projectDir, 'node_modules', '.pnpm', 'jsharness*', 'node_modules', 'jsharness', '.harness'),
@@ -796,7 +1117,7 @@ function findHarnessSource(projectDir) {
     } catch { /* skip */ }
   }
 
-  // 3. 通过 require.resolve 定位 npm 包根
+  // 4. 通过 require.resolve 定位 npm 包根
   try {
     const _require = createRequire(import.meta.url);
     const pkgPath = _require.resolve('jsharness/package.json');
@@ -806,10 +1127,6 @@ function findHarnessSource(projectDir) {
     // require 解析失败，继续尝试其他方式
   }
 
-  // 4. __dirname 相对路径（本地开发模式）
-  const devHarness = path.join(__dirname, '..', '..', '.harness');
-  if (fs.existsSync(devHarness)) return devHarness;
-
   // 5. 最后尝试：沿 __dirname 向上搜索 .harness
   let current = __dirname;
   for (let i = 0; i < 5; i++) {

package/package.json

@@ -1 +1,53 @@
-{"name":"jsharness","version":"1.0.2","description":"Harness Engineering - AI 编程行为工程化管控系统。将 rules/skills/gate/agents 一键注入到 CodeBuddy、Cursor、Copilot 等 AI 工具中。","main":"lib/index.mjs","bin":{"jsharness":"./bin/jsharness.js"},"type":"module","scripts":{"jsharness":"node bin/jsharness.js","init":"node bin/jsharness.js init","list-tools":"node bin/jsharness.js list-tools","status":"node bin/jsharness.js status","test":"node bin/jsharness.js status"},"keywords":["harness","ai-coding","codebuddy","cursor","copilot","rules-engineering","ai-assistant","vue3","spring-boot"],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"files":["bin/","lib/",".harness/","README.md"],"dependencies":{"commander":"^12.1.0"},"devDependencies":{"openspec":"^0.0.0","webpack":"^5.107.0","webpack-cli":"^7.0.2"},"repository":{"type":"git","url":""},"homepage":""}
+{
+  "name": "jsharness",
+  "version": "1.1.1",
+  "description": "Harness Engineering - AI 编程行为工程化管控系统。将 rules/skills/gate/agents 一键注入到 CodeBuddy、Cursor、Copilot 等 AI 工具中。",
+  "main": "lib/index.mjs",
+  "bin": {
+    "jsharness": "./bin/jsharness.js"
+  },
+  "type": "module",
+  "scripts": {
+    "jsharness": "node bin/jsharness.js",
+    "init": "node bin/jsharness.js init",
+    "list-tools": "node bin/jsharness.js list-tools",
+    "status": "node bin/jsharness.js status",
+    "prepublishOnly": "echo 'Publishing jsharness to npm...'"
+  },
+  "keywords": [
+    "harness",
+    "ai-coding",
+    "codebuddy",
+    "cursor",
+    "copilot",
+    "claude",
+    "rules-engineering",
+    "ai-assistant",
+    "vue3",
+    "spring-boot",
+    "openspec"
+  ],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    ".harness/",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "webpack": "^5.107.0",
+    "webpack-cli": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": ""
+}