@localsummer/incspec 0.0.1

package/commands/validate.mjs

@@ -0,0 +1,181 @@
+/**
+ * validate command - Validate spec files
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  ensureInitialized,
+  INCSPEC_DIR,
+  DIRS,
+  FILES,
+  parseFrontmatter,
+} from '../lib/config.mjs';
+import { listSpecs, readSpec } from '../lib/spec.mjs';
+import { readWorkflow, STEPS } from '../lib/workflow.mjs';
+import {
+  colors,
+  colorize,
+  print,
+  printSuccess,
+  printWarning,
+  printError,
+} from '../lib/terminal.mjs';
+
+/**
+ * Execute validate command
+ * @param {Object} ctx - Command context
+ */
+export async function validateCommand(ctx) {
+  const { cwd, options } = ctx;
+
+  // Ensure initialized
+  const projectRoot = ensureInitialized(cwd);
+
+  print('');
+  print(colorize('  incspec 规范验证', colors.bold, colors.cyan));
+  print(colorize('  ────────────────', colors.dim));
+  print('');
+
+  const errors = [];
+  const warnings = [];
+
+  // 1. Check core files
+  print(colorize('检查核心文件...', colors.bold));
+
+  const projectPath = path.join(projectRoot, INCSPEC_DIR, FILES.project);
+  if (!fs.existsSync(projectPath)) {
+    errors.push(`缺少 ${FILES.project} 文件`);
+  } else {
+    const content = fs.readFileSync(projectPath, 'utf-8');
+    const { frontmatter } = parseFrontmatter(content);
+
+    if (!frontmatter.name) {
+      warnings.push(`${FILES.project}: 缺少 name 字段`);
+    }
+    if (!frontmatter.tech_stack || frontmatter.tech_stack.length === 0) {
+      warnings.push(`${FILES.project}: 缺少 tech_stack 字段`);
+    }
+    printSuccess(`${FILES.project} 存在`);
+  }
+
+  const workflowPath = path.join(projectRoot, INCSPEC_DIR, FILES.workflow);
+  if (!fs.existsSync(workflowPath)) {
+    warnings.push(`缺少 ${FILES.workflow} 文件 (将在首次使用时创建)`);
+  } else {
+    printSuccess(`${FILES.workflow} 存在`);
+  }
+
+  // 2. Check directories
+  print('');
+  print(colorize('检查目录结构...', colors.bold));
+
+  for (const [key, dir] of Object.entries(DIRS)) {
+    const dirPath = path.join(projectRoot, INCSPEC_DIR, dir);
+    if (!fs.existsSync(dirPath)) {
+      warnings.push(`缺少目录: ${dir}/`);
+    } else {
+      printSuccess(`${dir}/ 存在`);
+    }
+  }
+
+  // 3. Check spec files format
+  print('');
+  print(colorize('检查规范文件格式...', colors.bold));
+
+  const specTypes = ['baselines', 'increments'];
+  let checkedCount = 0;
+
+  for (const type of specTypes) {
+    const specs = listSpecs(projectRoot, type);
+    for (const spec of specs) {
+      checkedCount++;
+      try {
+        const { frontmatter, body } = readSpec(spec.path);
+
+        // Check for required sections in baselines
+        if (type === 'baselines') {
+          if (!body.includes('## 1.') && !body.includes('# ')) {
+            warnings.push(`${spec.name}: 可能缺少标准章节结构`);
+          }
+          if (!body.includes('sequenceDiagram') && !body.includes('graph ')) {
+            warnings.push(`${spec.name}: 未检测到 Mermaid 图表`);
+          }
+        }
+
+        // Check for required sections in increments
+        if (type === 'increments') {
+          const requiredSections = ['模块1', '模块2', '模块3', '模块4', '模块5'];
+          const missingSections = requiredSections.filter(s => !body.includes(s));
+          if (missingSections.length > 0) {
+            warnings.push(`${spec.name}: 可能缺少模块 ${missingSections.join(', ')}`);
+          }
+        }
+      } catch (e) {
+        errors.push(`${spec.name}: 读取失败 - ${e.message}`);
+      }
+    }
+  }
+
+  if (checkedCount > 0) {
+    printSuccess(`已检查 ${checkedCount} 个规范文件`);
+  } else {
+    print(colorize('  (暂无规范文件)', colors.dim));
+  }
+
+  // 4. Check workflow consistency
+  print('');
+  print(colorize('检查工作流一致性...', colors.bold));
+
+  const workflow = readWorkflow(projectRoot);
+  if (workflow?.currentWorkflow) {
+    printSuccess(`当前工作流: ${workflow.currentWorkflow}`);
+
+    // Check step outputs exist
+    workflow.steps.forEach((step, index) => {
+      if (step.output && step.status === 'completed') {
+        // Determine expected path based on step
+        let expectedPath;
+        if (index === 0 || index === 5) {
+          expectedPath = path.join(projectRoot, INCSPEC_DIR, DIRS.baselines, step.output);
+        } else if (index === 1 || index === 2) {
+          expectedPath = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, step.output);
+        } else if (index === 3) {
+          expectedPath = path.join(projectRoot, INCSPEC_DIR, DIRS.increments, step.output);
+        }
+
+        if (expectedPath && !fs.existsSync(expectedPath)) {
+          warnings.push(`步骤 ${index + 1} 输出文件不存在: ${step.output}`);
+        }
+      }
+    });
+  } else {
+    print(colorize('  (无活跃工作流)', colors.dim));
+  }
+
+  // Summary
+  print('');
+  print(colorize('验证结果:', colors.bold));
+  print('');
+
+  if (errors.length === 0 && warnings.length === 0) {
+    printSuccess('所有检查通过!');
+  } else {
+    if (errors.length > 0) {
+      print(colorize(`错误 (${errors.length}):`, colors.red, colors.bold));
+      errors.forEach(e => print(colorize(`  ✗ ${e}`, colors.red)));
+      print('');
+    }
+
+    if (warnings.length > 0) {
+      print(colorize(`警告 (${warnings.length}):`, colors.yellow, colors.bold));
+      warnings.forEach(w => print(colorize(`  ⚠ ${w}`, colors.yellow)));
+      print('');
+    }
+  }
+
+  // Exit with error code if strict mode
+  if (options.strict && errors.length > 0) {
+    process.exit(1);
+  }
+}

package/index.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * incspec CLI
+ * Incremental spec-driven development workflow tool
+ */
+
+import { initCommand } from './commands/init.mjs';
+import { updateCommand } from './commands/update.mjs';
+import { statusCommand } from './commands/status.mjs';
+import { analyzeCommand } from './commands/analyze.mjs';
+import { collectReqCommand } from './commands/collect-req.mjs';
+import { collectDepCommand } from './commands/collect-dep.mjs';
+import { designCommand } from './commands/design.mjs';
+import { applyCommand } from './commands/apply.mjs';
+import { mergeCommand } from './commands/merge.mjs';
+import { listCommand } from './commands/list.mjs';
+import { validateCommand } from './commands/validate.mjs';
+import { archiveCommand } from './commands/archive.mjs';
+import { cursorSyncCommand } from './commands/cursor-sync.mjs';
+import { helpCommand } from './commands/help.mjs';
+import { colors, colorize } from './lib/terminal.mjs';
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args
+ * @returns {{command: string, args: string[], options: Object}}
+ */
+function parseArgs(args) {
+  const result = {
+    command: '',
+    args: [],
+    options: {},
+  };
+
+  const valueOptions = new Set(['module', 'feature', 'source-dir', 'output', 'workflow']);
+  const shortValueMap = new Map([
+    ['m', 'module'],
+    ['f', 'feature'],
+    ['s', 'source-dir'],
+    ['o', 'output'],
+    ['w', 'workflow'],
+  ]);
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--') {
+      result.args.push(...args.slice(i + 1));
+      break;
+    }
+
+    const shortValueMatch = arg.match(/^-([a-zA-Z0-9])=(.+)$/);
+    if (shortValueMatch) {
+      const key = shortValueMatch[1];
+      const value = shortValueMatch[2];
+      const longKey = shortValueMap.get(key);
+      if (longKey) {
+        result.options[longKey] = value;
+      } else {
+        result.options[key] = value;
+      }
+    } else if (arg.startsWith('--')) {
+      // Long option: --key=value or --key
+      const eqIndex = arg.indexOf('=');
+      if (eqIndex !== -1) {
+        const key = arg.slice(2, eqIndex);
+        const value = arg.slice(eqIndex + 1);
+        result.options[key] = value;
+      } else {
+        const key = arg.slice(2);
+        const nextArg = args[i + 1];
+        if (valueOptions.has(key) && nextArg && !nextArg.startsWith('-')) {
+          result.options[key] = nextArg;
+          i += 2;
+          continue;
+        }
+        result.options[key] = true;
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      // Short option: -k
+      const key = arg.slice(1);
+      const nextArg = args[i + 1];
+      const longKey = shortValueMap.get(key);
+      if (longKey && nextArg && !nextArg.startsWith('-')) {
+        result.options[longKey] = nextArg;
+        i += 2;
+        continue;
+      }
+      result.options[key] = true;
+    } else if (!result.command) {
+      result.command = arg;
+    } else {
+      result.args.push(arg);
+    }
+
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Main CLI entry point
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const parsed = parseArgs(args);
+
+  // Handle --help or -h flag
+  if (parsed.options.help || parsed.options.h) {
+    await helpCommand({ command: parsed.command || undefined });
+    return;
+  }
+
+  // Handle --version or -v flag
+  if (parsed.options.version || parsed.options.v) {
+    const { createRequire } = await import('module');
+    const require = createRequire(import.meta.url);
+    try {
+      const pkg = require('./package.json');
+      console.log(pkg.version);
+    } catch {
+      console.log('unknown');
+    }
+    return;
+  }
+
+  // Default to help if no command
+  if (!parsed.command) {
+    await helpCommand();
+    return;
+  }
+
+  // Route to appropriate command
+  const cwd = process.cwd();
+  const commandContext = { cwd, args: parsed.args, options: parsed.options };
+
+  try {
+    switch (parsed.command) {
+      // Initialize
+      case 'init':
+        await initCommand(commandContext);
+        break;
+
+      // Update templates
+      case 'update':
+      case 'up':
+        await updateCommand(commandContext);
+        break;
+
+      // Status
+      case 'status':
+      case 'st':
+        await statusCommand(commandContext);
+        break;
+
+      // Workflow commands (Step 1-6)
+      case 'analyze':
+      case 'a':
+        await analyzeCommand(commandContext);
+        break;
+
+      case 'collect-req':
+      case 'cr':
+        await collectReqCommand(commandContext);
+        break;
+
+      case 'collect-dep':
+      case 'cd':
+        await collectDepCommand(commandContext);
+        break;
+
+      case 'design':
+      case 'd':
+        await designCommand(commandContext);
+        break;
+
+      case 'apply':
+      case 'ap':
+        await applyCommand(commandContext);
+        break;
+
+      case 'merge':
+      case 'm':
+        await mergeCommand(commandContext);
+        break;
+
+      // Management commands
+      case 'list':
+      case 'ls':
+        await listCommand(commandContext);
+        break;
+
+      case 'validate':
+      case 'v':
+        await validateCommand(commandContext);
+        break;
+
+      case 'archive':
+      case 'ar':
+        await archiveCommand(commandContext);
+        break;
+
+      // Cursor integration
+      case 'cursor-sync':
+      case 'cs':
+        await cursorSyncCommand(commandContext);
+        break;
+
+      // Help
+      case 'help':
+      case 'h':
+        await helpCommand({ command: parsed.args[0] });
+        break;
+
+      default:
+        console.error(colorize(`Unknown command: ${parsed.command}`, colors.red));
+        console.error(colorize("Run 'incspec help' for usage information.", colors.dim));
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(colorize(`Error: ${error.message}`, colors.red));
+    if (parsed.options.debug) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the CLI
+main().catch((error) => {
+  console.error(colorize(`Fatal error: ${error.message}`, colors.red));
+  process.exit(1);
+});

package/lib/agents.mjs

@@ -0,0 +1,163 @@
+/**
+ * AGENTS.md file read/write utilities for incspec
+ * Handles managed block insertion/update in project AGENTS.md
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getTemplatesDir } from './config.mjs';
+
+const INCSPEC_BLOCK_START = '<!-- INCSPEC:START -->';
+const INCSPEC_BLOCK_END = '<!-- INCSPEC:END -->';
+
+/**
+ * Get the project AGENTS.md file path
+ * @param {string} projectRoot - Project root directory
+ * @returns {string}
+ */
+export function getProjectAgentsFilePath(projectRoot) {
+  return path.join(projectRoot, 'AGENTS.md');
+}
+
+/**
+ * Read the incspec block template content
+ * @returns {string}
+ */
+export function getIncspecBlockTemplate() {
+  const templatePath = path.join(getTemplatesDir(), 'INCSPEC_BLOCK.md');
+  
+  if (fs.existsSync(templatePath)) {
+    return fs.readFileSync(templatePath, 'utf-8');
+  }
+  
+  // Fallback content if template not found
+  return `<!-- INCSPEC:START -->
+# IncSpec 指令
+
+本指令适用于在此项目中工作的 AI 助手。
+
+当请求符合以下情况时，请始终打开 \`@/incspec/AGENTS.md\`：
+- 涉及增量开发或编码工作流
+- 引入需要分步实现的新功能
+- 需要基线分析、需求收集或代码生成
+- 请求含义模糊，需要先了解规范工作流再编码
+
+通过 \`@/incspec/AGENTS.md\` 可以了解：
+- 如何使用 6 步增量编码工作流
+- 规范格式与约定
+- 项目结构与指南
+
+请保留此托管块，以便 'incspec init' 可以刷新指令内容。
+
+<!-- INCSPEC:END -->
+`;
+}
+
+/**
+ * Update or create AGENTS.md with incspec managed block
+ * - If file doesn't exist, create it with the block
+ * - If file exists but no markers, append the block
+ * - If file exists with markers, replace content between markers
+ * @param {string} projectRoot - Project root directory
+ * @returns {{created: boolean, updated: boolean}}
+ */
+export function updateProjectAgentsFile(projectRoot) {
+  const filePath = getProjectAgentsFilePath(projectRoot);
+  const blockContent = getIncspecBlockTemplate();
+  
+  let existingContent = '';
+  let fileExists = false;
+  
+  if (fs.existsSync(filePath)) {
+    existingContent = fs.readFileSync(filePath, 'utf-8');
+    fileExists = true;
+  }
+  
+  let newContent;
+  let updated = false;
+  
+  if (!fileExists) {
+    // File doesn't exist, create new with block content
+    newContent = blockContent;
+  } else {
+    // File exists, check for markers
+    const startIndex = existingContent.indexOf(INCSPEC_BLOCK_START);
+    const endIndex = existingContent.indexOf(INCSPEC_BLOCK_END);
+    
+    if (startIndex !== -1 && endIndex !== -1 && startIndex < endIndex) {
+      // Markers found, replace content between markers (inclusive)
+      const endMarkerLength = INCSPEC_BLOCK_END.length;
+      newContent =
+        existingContent.substring(0, startIndex) +
+        blockContent.trim() +
+        existingContent.substring(endIndex + endMarkerLength);
+      updated = true;
+    } else {
+      // Markers not found, append block to end of file
+      const separator = existingContent.endsWith('\n') ? '\n' : '\n\n';
+      newContent = existingContent + separator + blockContent;
+      updated = true;
+    }
+  }
+  
+  fs.writeFileSync(filePath, newContent, 'utf-8');
+  
+  return {
+    created: !fileExists,
+    updated: updated,
+  };
+}
+
+/**
+ * Check if AGENTS.md has incspec block
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean}
+ */
+export function hasIncspecBlock(projectRoot) {
+  const filePath = getProjectAgentsFilePath(projectRoot);
+  
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+  
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return content.includes(INCSPEC_BLOCK_START) && content.includes(INCSPEC_BLOCK_END);
+}
+
+/**
+ * Remove incspec block from AGENTS.md
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean} True if block was removed
+ */
+export function removeIncspecBlock(projectRoot) {
+  const filePath = getProjectAgentsFilePath(projectRoot);
+  
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+  
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const startIndex = content.indexOf(INCSPEC_BLOCK_START);
+  const endIndex = content.indexOf(INCSPEC_BLOCK_END);
+  
+  if (startIndex === -1 || endIndex === -1 || startIndex >= endIndex) {
+    return false;
+  }
+  
+  const endMarkerLength = INCSPEC_BLOCK_END.length;
+  let newContent =
+    content.substring(0, startIndex) +
+    content.substring(endIndex + endMarkerLength);
+  
+  // Clean up extra newlines
+  newContent = newContent.replace(/\n{3,}/g, '\n\n').trim();
+  
+  if (newContent) {
+    fs.writeFileSync(filePath, newContent + '\n', 'utf-8');
+  } else {
+    // If file is empty after removal, delete it
+    fs.unlinkSync(filePath);
+  }
+  
+  return true;
+}