@localsummer/incspec 0.0.1

package/commands/cursor-sync.mjs

@@ -0,0 +1,116 @@
+/**
+ * cursor-sync command - Sync Cursor slash commands
+ */
+
+import * as path from 'path';
+import {
+  findProjectRoot,
+  INCSPEC_DIR,
+} from '../lib/config.mjs';
+import {
+  syncToProject,
+  syncToGlobal,
+  checkCursorCommands,
+} from '../lib/cursor.mjs';
+import {
+  colors,
+  colorize,
+  print,
+  printSuccess,
+  printWarning,
+  printInfo,
+  confirm,
+  select,
+} from '../lib/terminal.mjs';
+
+/**
+ * Execute cursor-sync command
+ * @param {Object} ctx - Command context
+ */
+export async function cursorSyncCommand(ctx) {
+  const { cwd, options } = ctx;
+
+  print('');
+  print(colorize('  incspec Cursor 命令同步', colors.bold, colors.cyan));
+  print(colorize('  ──────────────────────', colors.dim));
+  print('');
+
+  // Determine sync target
+  let syncTarget = null;
+
+  if (options.project) {
+    syncTarget = 'project';
+  } else if (options.global) {
+    syncTarget = 'global';
+  } else {
+    // Interactive selection
+    const projectRoot = findProjectRoot(cwd);
+    
+    const choices = [
+      {
+        name: '项目目录 (.cursor/commands/incspec/)',
+        value: 'project',
+        description: '仅对当前项目生效',
+      },
+      {
+        name: '全局目录 (~/.cursor/commands/incspec/)',
+        value: 'global',
+        description: '对所有项目生效',
+      },
+    ];
+
+    if (!projectRoot) {
+      // No project found, only allow global
+      printWarning('未检测到 incspec 项目，将同步到全局目录。');
+      syncTarget = 'global';
+    } else {
+      syncTarget = await select({
+        message: '选择同步目标:',
+        choices,
+      });
+    }
+  }
+
+  // Execute sync
+  if (syncTarget === 'project') {
+    const projectRoot = findProjectRoot(cwd);
+    
+    if (!projectRoot) {
+      printWarning('未检测到 incspec 项目。请先运行 incspec init 或使用 --global 选项。');
+      return;
+    }
+
+    print(colorize(`同步到项目: ${projectRoot}`, colors.dim));
+    print('');
+
+    const count = syncToProject(projectRoot);
+    
+    printSuccess(`已同步 ${count} 个 Cursor 命令到 .cursor/commands/incspec/`);
+    print('');
+    print(colorize('已创建的命令:', colors.bold));
+    print(colorize('  /incspec/inc-analyze      步骤1: 分析代码流程', colors.dim));
+    print(colorize('  /incspec/inc-collect-req  步骤2: 收集结构化需求', colors.dim));
+    print(colorize('  /incspec/inc-collect-dep  步骤3: UI依赖采集', colors.dim));
+    print(colorize('  /incspec/inc-design       步骤4: 增量设计', colors.dim));
+    print(colorize('  /incspec/inc-apply        步骤5: 应用代码变更', colors.dim));
+    print(colorize('  /incspec/inc-merge        步骤6: 合并到基线', colors.dim));
+    print(colorize('  /incspec/inc-archive      归档规范文件', colors.dim));
+    print(colorize('  /incspec/inc-status       查看工作流状态', colors.dim));
+    print(colorize('  /incspec/inc-help         显示帮助', colors.dim));
+
+  } else if (syncTarget === 'global') {
+    print(colorize('同步到全局目录...', colors.dim));
+    print('');
+
+    const count = syncToGlobal();
+    
+    printSuccess(`已同步 ${count} 个 Cursor 命令到 ~/.cursor/commands/incspec/`);
+    print('');
+    print(colorize('全局命令将对所有项目生效。', colors.dim));
+    print(colorize('在项目中运行 incspec cursor-sync --project 可覆盖全局命令。', colors.dim));
+  }
+
+  print('');
+  printInfo('请重启 Cursor 以加载新命令。');
+  print('');
+}

package/commands/design.mjs

@@ -0,0 +1,131 @@
+/**
+ * design command - Step 4: Design increment
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  ensureInitialized,
+  INCSPEC_DIR,
+  DIRS,
+} from '../lib/config.mjs';
+import {
+  readWorkflow,
+  updateStep,
+  STATUS,
+} from '../lib/workflow.mjs';
+import { getNextVersion, listSpecs } from '../lib/spec.mjs';
+import {
+  colors,
+  colorize,
+  print,
+  printSuccess,
+  printWarning,
+  printInfo,
+  prompt,
+} from '../lib/terminal.mjs';
+
+const STEP_NUMBER = 4;
+
+/**
+ * Execute design command
+ * @param {Object} ctx - Command context
+ */
+export async function designCommand(ctx) {
+  const { cwd, options } = ctx;
+
+  // Ensure initialized
+  const projectRoot = ensureInitialized(cwd);
+
+  // Get workflow state
+  const workflow = readWorkflow(projectRoot);
+
+  if (!workflow?.currentWorkflow) {
+    printWarning('没有活跃的工作流。请先运行 incspec analyze 开始新工作流。');
+    return;
+  }
+
+  // Get feature name
+  let featureName = typeof options.feature === 'string' ? options.feature : '';
+  if (!featureName) {
+    featureName = workflow.currentWorkflow.replace(/^analyze-/, '');
+  }
+
+  // Calculate output file
+  const version = getNextVersion(projectRoot, 'increments', featureName);
+  const outputFile = `${featureName}-increment-v${version}.md`;
+  const outputPath = path.join(INCSPEC_DIR, DIRS.increments, outputFile);
+
+  // Find input files
+  const baselines = listSpecs(projectRoot, 'baselines');
+  const latestBaseline = baselines[0]?.name || '[无基线文件]';
+  if (baselines.length === 0) {
+    printWarning('未找到基线文件。请先运行步骤 1 (analyze)。');
+    return;
+  }
+
+  const reqFile = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, 'structured-requirements.md');
+  const depFile = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, 'ui-dependencies.md');
+  const missingInputs = [];
+  if (!fs.existsSync(reqFile)) {
+    missingInputs.push('structured-requirements.md');
+  }
+  if (!fs.existsSync(depFile)) {
+    missingInputs.push('ui-dependencies.md');
+  }
+  if (missingInputs.length > 0) {
+    printWarning(`缺少需求输入文件: ${missingInputs.join(', ')}`);
+    printWarning('请先完成步骤 2 (collect-req) 和步骤 3 (collect-dep)。');
+    return;
+  }
+
+  print('');
+  print(colorize('步骤 4: 增量设计', colors.bold, colors.cyan));
+  print(colorize('────────────────', colors.dim));
+  print('');
+  print(colorize(`当前工作流: ${workflow.currentWorkflow}`, colors.dim));
+  print(colorize(`功能名称: ${featureName}`, colors.dim));
+  print(colorize(`输出文件: ${outputPath}`, colors.dim));
+  print('');
+  print(colorize('输入文件:', colors.bold));
+  print(colorize(`  基线快照: ${INCSPEC_DIR}/${DIRS.baselines}/${latestBaseline}`, colors.dim));
+  print(colorize(`  结构化需求: ${INCSPEC_DIR}/${DIRS.requirements}/structured-requirements.md`, colors.dim));
+  print(colorize(`  UI依赖: ${INCSPEC_DIR}/${DIRS.requirements}/ui-dependencies.md`, colors.dim));
+  print('');
+
+  // Update workflow status
+  updateStep(projectRoot, STEP_NUMBER, STATUS.IN_PROGRESS);
+
+  print(colorize('使用说明:', colors.bold));
+  print('');
+  print(colorize('请在 Cursor 中运行以下命令:', colors.cyan));
+  print('');
+  print(colorize(`  /incspec/inc-design --feature=${featureName}`, colors.bold, colors.white));
+  print('');
+  print(colorize('或使用 Claude Code 命令:', colors.cyan));
+  print('');
+  const baselinePath = path.join(projectRoot, INCSPEC_DIR, DIRS.baselines, latestBaseline);
+  const reqPath = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, 'structured-requirements.md');
+  const depPath = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, 'ui-dependencies.md');
+  const outDir = path.join(projectRoot, INCSPEC_DIR, DIRS.increments);
+  print(colorize(`  /ai-increment:analyze-increment-codeflow ${baselinePath} ${reqPath} ${depPath} ${outDir}`, colors.bold, colors.white));
+  print('');
+  print(colorize('该命令将生成包含 7 大模块的增量设计蓝图:', colors.dim));
+  print(colorize('  1. 一句话摘要', colors.dim));
+  print(colorize('  2. 变更链条设计表', colors.dim));
+  print(colorize('  3. 规划后的 API 调用时序图', colors.dim));
+  print(colorize('  4. 规划后的依赖关系图', colors.dim));
+  print(colorize('  5. 文件清单', colors.dim));
+  print(colorize('  6. 风险预警', colors.dim));
+  print(colorize('  7. 测试用例', colors.dim));
+  print('');
+  printInfo(`完成后运行 'incspec status' 查看进度`);
+  print('');
+
+  // Handle --complete flag
+  if (options.complete) {
+    const output = typeof options.output === 'string' ? options.output : outputFile;
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, output);
+    printSuccess(`步骤 4 已标记为完成: ${output}`);
+  }
+}

package/commands/help.mjs

@@ -0,0 +1,235 @@
+/**
+ * help command - Display help information
+ */
+
+import {
+  colors,
+  colorize,
+  print,
+} from '../lib/terminal.mjs';
+import { STEPS } from '../lib/workflow.mjs';
+
+/**
+ * Command definitions for help
+ */
+const COMMANDS = {
+  init: {
+    usage: 'incspec init [--force]',
+    description: '初始化 incspec 项目结构',
+    options: [
+      ['--force', '强制重新初始化'],
+    ],
+  },
+  update: {
+    usage: 'incspec update [-y|--yes]',
+    aliases: ['up'],
+    description: '更新模板文件到最新版本',
+    options: [
+      ['-y, --yes', '跳过确认提示'],
+    ],
+  },
+  status: {
+    usage: 'incspec status',
+    aliases: ['st'],
+    description: '显示当前工作流状态',
+  },
+  analyze: {
+    usage: 'incspec analyze <source-path> [--module=name]',
+    aliases: ['a'],
+    description: '步骤1: 分析代码流程，生成基线快照',
+    options: [
+      ['-m, --module=<name>', '指定模块名称'],
+      ['-w, --workflow=<name>', '指定工作流名称(避免交互提示)'],
+      ['--complete', '标记步骤完成'],
+      ['-o, --output=<file>', '完成时指定输出文件'],
+    ],
+  },
+  'collect-req': {
+    usage: 'incspec collect-req',
+    aliases: ['cr'],
+    description: '步骤2: 收集结构化需求',
+    options: [
+      ['--complete', '标记步骤完成'],
+    ],
+  },
+  'collect-dep': {
+    usage: 'incspec collect-dep',
+    aliases: ['cd'],
+    description: '步骤3: 采集 UI 依赖',
+    options: [
+      ['--complete', '标记步骤完成'],
+    ],
+  },
+  design: {
+    usage: 'incspec design [--feature=name]',
+    aliases: ['d'],
+    description: '步骤4: 生成增量设计蓝图',
+    options: [
+      ['-f, --feature=<name>', '指定功能名称'],
+      ['--complete', '标记步骤完成'],
+      ['-o, --output=<file>', '完成时指定输出文件'],
+    ],
+  },
+  apply: {
+    usage: 'incspec apply [increment-path]',
+    aliases: ['ap'],
+    description: '步骤5: 应用代码变更',
+    options: [
+      ['-s, --source-dir=<path>', '指定源代码目录'],
+      ['--complete', '标记步骤完成'],
+    ],
+  },
+  merge: {
+    usage: 'incspec merge [increment-path]',
+    aliases: ['m'],
+    description: '步骤6: 合并到新基线',
+    options: [
+      ['--complete', '标记步骤完成'],
+      ['-o, --output=<file>', '完成时指定输出文件'],
+    ],
+  },
+  list: {
+    usage: 'incspec list [type] [-l|--long] [-a|--all]',
+    aliases: ['ls'],
+    description: '列出规范文件',
+    options: [
+      ['type', 'baselines | requirements | increments | archives'],
+      ['-l, --long', '显示详细信息'],
+      ['-a, --all', '包含归档文件'],
+    ],
+  },
+  validate: {
+    usage: 'incspec validate [--strict]',
+    aliases: ['v'],
+    description: '验证规范完整性',
+    options: [
+      ['--strict', '严格模式，有错误时返回非零退出码'],
+    ],
+  },
+  archive: {
+    usage: 'incspec archive [file-path] [--workflow] [-k|--keep] [-y|--yes]',
+    aliases: ['ar'],
+    description: '归档规范文件 (默认归档当前工作流产出)',
+    options: [
+      ['--workflow', '归档当前工作流全部产出文件'],
+      ['-k, --keep', '复制而非移动'],
+      ['-y, --yes', '跳过确认提示'],
+    ],
+  },
+  'cursor-sync': {
+    usage: 'incspec cursor-sync [--project|--global]',
+    aliases: ['cs'],
+    description: '同步 Cursor slash commands',
+    options: [
+      ['--project', '同步到项目目录'],
+      ['--global', '同步到全局目录'],
+    ],
+  },
+  help: {
+    usage: 'incspec help [command]',
+    aliases: ['h'],
+    description: '显示帮助信息',
+  },
+};
+
+/**
+ * Execute help command
+ * @param {Object} ctx - Command context
+ */
+export async function helpCommand(ctx = {}) {
+  const { command } = ctx;
+
+  print('');
+
+  if (command && COMMANDS[command]) {
+    // Show specific command help
+    showCommandHelp(command);
+  } else if (command) {
+    print(colorize(`未知命令: ${command}`, colors.red));
+    print('');
+    showGeneralHelp();
+  } else {
+    showGeneralHelp();
+  }
+}
+
+/**
+ * Show general help
+ */
+function showGeneralHelp() {
+  print(colorize('  incspec - 增量规范驱动开发工具', colors.bold, colors.cyan));
+  print(colorize('  ────────────────────────────', colors.dim));
+  print('');
+  print(colorize('用法:', colors.bold));
+  print(colorize('  incspec <command> [options]', colors.white));
+  print('');
+
+  print(colorize('工作流命令:', colors.bold));
+  print('');
+  
+  const workflowCommands = ['analyze', 'collect-req', 'collect-dep', 'design', 'apply', 'merge'];
+  workflowCommands.forEach((cmd, index) => {
+    const def = COMMANDS[cmd];
+    const aliases = def.aliases ? colorize(` (${def.aliases.join(', ')})`, colors.dim) : '';
+    print(`  ${colorize(`${index + 1}.`, colors.cyan)} ${colorize(cmd, colors.white)}${aliases}`);
+    print(colorize(`     ${def.description}`, colors.dim));
+  });
+
+  print('');
+  print(colorize('管理命令:', colors.bold));
+  print('');
+
+  const mgmtCommands = ['init', 'update', 'status', 'list', 'validate', 'archive', 'cursor-sync', 'help'];
+  mgmtCommands.forEach(cmd => {
+    const def = COMMANDS[cmd];
+    const aliases = def.aliases ? colorize(` (${def.aliases.join(', ')})`, colors.dim) : '';
+    print(`  ${colorize(cmd, colors.white)}${aliases}`);
+    print(colorize(`     ${def.description}`, colors.dim));
+  });
+
+  print('');
+  print(colorize('选项:', colors.bold));
+  print(colorize('  -h, --help     显示帮助', colors.dim));
+  print(colorize('  -v, --version  显示版本', colors.dim));
+  print('');
+  print(colorize('示例:', colors.bold));
+  print(colorize('  incspec init                    # 初始化项目', colors.dim));
+  print(colorize('  incspec update                  # 更新模板文件', colors.dim));
+  print(colorize('  incspec analyze src/views/Home  # 分析代码流程', colors.dim));
+  print(colorize('  incspec status                  # 查看工作流状态', colors.dim));
+  print(colorize('  incspec cursor-sync             # 同步 Cursor 命令', colors.dim));
+  print('');
+  print(colorize(`运行 'incspec help <command>' 查看命令详情。`, colors.dim));
+  print('');
+}
+
+/**
+ * Show specific command help
+ * @param {string} command
+ */
+function showCommandHelp(command) {
+  const def = COMMANDS[command];
+
+  print(colorize(`incspec ${command}`, colors.bold, colors.cyan));
+  print('');
+  print(colorize(def.description, colors.white));
+  print('');
+  print(colorize('用法:', colors.bold));
+  print(colorize(`  ${def.usage}`, colors.white));
+
+  if (def.aliases && def.aliases.length > 0) {
+    print('');
+    print(colorize('别名:', colors.bold));
+    print(colorize(`  ${def.aliases.join(', ')}`, colors.dim));
+  }
+
+  if (def.options && def.options.length > 0) {
+    print('');
+    print(colorize('选项:', colors.bold));
+    def.options.forEach(([opt, desc]) => {
+      print(`  ${colorize(opt.padEnd(20), colors.cyan)} ${colorize(desc, colors.dim)}`);
+    });
+  }
+
+  print('');
+}

package/commands/init.mjs

@@ -0,0 +1,127 @@
+/**
+ * init command - Initialize incspec in a project
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  isInitialized,
+  createIncspecStructure,
+  getDefaultConfig,
+  INCSPEC_DIR,
+  findProjectRoot,
+} from '../lib/config.mjs';
+import { initWorkflow } from '../lib/workflow.mjs';
+import { updateProjectAgentsFile } from '../lib/agents.mjs';
+import {
+  colors,
+  colorize,
+  print,
+  printSuccess,
+  printWarning,
+  printInfo,
+  prompt,
+  confirm,
+} from '../lib/terminal.mjs';
+
+/**
+ * Execute init command
+ * @param {Object} ctx - Command context
+ */
+export async function initCommand(ctx) {
+  const { cwd, options } = ctx;
+
+  // Check if already initialized
+  if (isInitialized(cwd) && !options.force) {
+    printWarning(`incspec 已在此目录初始化。`);
+    printInfo(`如需重新初始化，请使用 --force 选项。`);
+    return;
+  }
+
+  const existingRoot = findProjectRoot(cwd);
+  if (existingRoot && existingRoot !== cwd && !options.force) {
+    printWarning(`检测到上级目录已初始化 incspec: ${existingRoot}`);
+    printInfo('请在项目根目录执行，或使用 --force 在当前目录初始化。');
+    return;
+  }
+
+  print('');
+  print(colorize('  incspec 初始化向导', colors.bold, colors.cyan));
+  print(colorize('  ─────────────────', colors.dim));
+  print('');
+
+  // Collect project info
+  const projectName = await prompt('项目名称', path.basename(cwd));
+
+  // Select tech stack
+  const techStackStr = await prompt('技术栈 (逗号分隔)', 'React, TypeScript');
+  const techStack = techStackStr.split(',').map(s => s.trim()).filter(Boolean);
+
+  const sourceDir = await prompt('源代码目录', 'src');
+
+  // Create config
+  const config = getDefaultConfig({
+    name: projectName,
+    tech_stack: techStack,
+    source_dir: sourceDir,
+  });
+
+  print('');
+  print(colorize('配置预览:', colors.bold));
+  print(colorize(`  项目名称: ${config.name}`, colors.dim));
+  print(colorize(`  技术栈: ${config.tech_stack.join(', ')}`, colors.dim));
+  print(colorize(`  源代码目录: ${config.source_dir}`, colors.dim));
+  print('');
+
+  const shouldProceed = await confirm('确认创建 incspec 目录结构?');
+
+  if (!shouldProceed) {
+    print(colorize('已取消初始化。', colors.dim));
+    return;
+  }
+
+  // If force mode and directory exists, remove it first
+  const incspecPath = path.join(cwd, INCSPEC_DIR);
+  if (options.force && fs.existsSync(incspecPath)) {
+    fs.rmSync(incspecPath, { recursive: true, force: true });
+    printInfo('已删除旧的 incspec 目录。');
+  }
+
+  // Create structure
+  createIncspecStructure(cwd, config);
+
+  // Initialize workflow
+  initWorkflow(cwd);
+
+  // Update project AGENTS.md with incspec block
+  const agentsResult = updateProjectAgentsFile(cwd);
+  if (agentsResult.created) {
+    printInfo('已创建项目 AGENTS.md 文件。');
+  } else if (agentsResult.updated) {
+    printInfo('已更新项目 AGENTS.md 中的 incspec 指令块。');
+  } else {
+    printInfo('已添加 incspec 指令块到项目 AGENTS.md。');
+  }
+
+  print('');
+  printSuccess('incspec 初始化完成!');
+  print('');
+  print(colorize('创建的目录结构:', colors.bold));
+  print(colorize(`  ${INCSPEC_DIR}/`, colors.cyan));
+  print(colorize(`  ├── project.md`, colors.dim));
+  print(colorize(`  ├── WORKFLOW.md`, colors.dim));
+  print(colorize(`  ├── AGENTS.md`, colors.dim));
+  print(colorize(`  ├── baselines/`, colors.dim));
+  print(colorize(`  ├── requirements/`, colors.dim));
+  print(colorize(`  ├── increments/`, colors.dim));
+  print(colorize(`  └── archives/`, colors.dim));
+  print('');
+  print(colorize(`  AGENTS.md (项目根目录)`, colors.cyan));
+  print(colorize(`  └── incspec 指令块已添加`, colors.dim));
+  print('');
+  print(colorize('下一步:', colors.bold));
+  print(colorize(`  1. 运行 'incspec status' 查看工作流状态`, colors.dim));
+  print(colorize(`  2. 运行 'incspec cursor-sync' 同步 Cursor 命令`, colors.dim));
+  print(colorize(`  3. 使用 /incspec/inc-analyze 开始第一个工作流`, colors.dim));
+  print('');
+}