@localsummer/incspec 0.0.1

package/lib/config.mjs

@@ -0,0 +1,343 @@
+/**
+ * Configuration management for incspec
+ * - Find project root
+ * - Read/write project.md
+ * - Default configurations
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+/** incspec directory name */
+export const INCSPEC_DIR = 'incspec';
+
+/** Default subdirectories */
+export const DIRS = {
+  baselines: 'baselines',
+  requirements: 'requirements',
+  increments: 'increments',
+  archives: 'archives',
+};
+
+/** Core files */
+export const FILES = {
+  project: 'project.md',
+  workflow: 'WORKFLOW.md',
+  agents: 'AGENTS.md',
+};
+
+/**
+ * Get the templates directory path
+ * @returns {string}
+ */
+export function getTemplatesDir() {
+  // Get the directory of this module file
+  const currentFileUrl = import.meta.url;
+  const currentFilePath = fileURLToPath(currentFileUrl);
+  const libDir = path.dirname(currentFilePath);
+  const cliRoot = path.dirname(libDir);
+  return path.join(cliRoot, 'templates');
+}
+
+/**
+ * Find project root by looking for incspec/ directory
+ * @param {string} startDir - Starting directory
+ * @returns {string|null} Project root path or null if not found
+ */
+export function findProjectRoot(startDir) {
+  let currentDir = path.resolve(startDir);
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    const incspecPath = path.join(currentDir, INCSPEC_DIR);
+    if (fs.existsSync(incspecPath) && fs.statSync(incspecPath).isDirectory()) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+/**
+ * Get incspec directory path
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getIncspecDir(projectRoot) {
+  return path.join(projectRoot, INCSPEC_DIR);
+}
+
+/**
+ * Check if incspec is initialized in directory
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function isInitialized(cwd) {
+  const incspecDir = path.join(cwd, INCSPEC_DIR);
+  const projectFile = path.join(incspecDir, FILES.project);
+  return fs.existsSync(incspecDir) && fs.existsSync(projectFile);
+}
+
+/**
+ * Parse frontmatter from markdown content
+ * @param {string} content
+ * @returns {{frontmatter: Object, body: string}}
+ */
+export function parseFrontmatter(content) {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+
+  // Simple YAML-like parsing
+  const frontmatter = {};
+  const lines = frontmatterStr.split('\n');
+  let currentKey = null;
+  let currentArray = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Array item
+    if (trimmed.startsWith('- ')) {
+      if (currentArray !== null) {
+        currentArray.push(trimmed.slice(2).trim());
+      }
+      continue;
+    }
+
+    // Key-value pair
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex !== -1) {
+      const key = trimmed.slice(0, colonIndex).trim();
+      const value = trimmed.slice(colonIndex + 1).trim();
+
+      if (value === '') {
+        // Start of array or nested object
+        frontmatter[key] = [];
+        currentKey = key;
+        currentArray = frontmatter[key];
+      } else {
+        frontmatter[key] = value;
+        currentKey = key;
+        currentArray = null;
+      }
+    }
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Serialize frontmatter to YAML-like string
+ * @param {Object} frontmatter
+ * @returns {string}
+ */
+export function serializeFrontmatter(frontmatter) {
+  const lines = ['---'];
+
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (Array.isArray(value)) {
+      lines.push(`${key}:`);
+      value.forEach(item => lines.push(`  - ${item}`));
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+
+  lines.push('---');
+  return lines.join('\n');
+}
+
+/**
+ * Read project configuration
+ * @param {string} projectRoot
+ * @returns {Object|null}
+ */
+export function readProjectConfig(projectRoot) {
+  const projectPath = path.join(projectRoot, INCSPEC_DIR, FILES.project);
+
+  if (!fs.existsSync(projectPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(projectPath, 'utf-8');
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  return {
+    ...frontmatter,
+    _body: body,
+    _path: projectPath,
+  };
+}
+
+/**
+ * Write project configuration
+ * @param {string} projectRoot
+ * @param {Object} config
+ */
+export function writeProjectConfig(projectRoot, config) {
+  const projectPath = path.join(projectRoot, INCSPEC_DIR, FILES.project);
+  const content = generateProjectContent(config);
+  fs.writeFileSync(projectPath, content, 'utf-8');
+}
+
+/**
+ * Generate project.md content from template
+ * @param {Object} config
+ * @returns {string}
+ */
+function generateProjectContent(config) {
+  const templatePath = path.join(getTemplatesDir(), 'project.md');
+  
+  if (fs.existsSync(templatePath)) {
+    let content = fs.readFileSync(templatePath, 'utf-8');
+    
+    // Replace variables
+    content = content.replace(/\{\{name\}\}/g, config.name || '');
+    content = content.replace(/\{\{version\}\}/g, config.version || '1.0.0');
+    content = content.replace(/\{\{source_dir\}\}/g, config.source_dir || 'src');
+    content = content.replace(/\{\{created_at\}\}/g, config.created_at || new Date().toISOString().split('T')[0]);
+    
+    // Handle tech_stack array
+    const techStackLines = (config.tech_stack || []).map(item => `  - ${item}`).join('\n');
+    content = content.replace(/\{\{tech_stack\}\}/g, techStackLines);
+    
+    return content;
+  }
+  
+  // Fallback to hardcoded content if template not found
+  return generateFallbackProjectContent(config);
+}
+
+/**
+ * Fallback project content generator
+ * @param {Object} config
+ * @returns {string}
+ */
+function generateFallbackProjectContent(config) {
+  const { _body, _path, ...frontmatter } = config;
+  return serializeFrontmatter(frontmatter) + '\n' + getDefaultProjectBody();
+}
+
+/**
+ * Get default project configuration
+ * @param {Object} options
+ * @returns {Object}
+ */
+export function getDefaultConfig(options = {}) {
+  const now = new Date().toISOString().split('T')[0];
+
+  return {
+    name: options.name || path.basename(process.cwd()),
+    version: '1.0.0',
+    tech_stack: options.tech_stack || [],
+    source_dir: options.source_dir || 'src',
+    created_at: now,
+  };
+}
+
+/**
+ * Get default project.md body content
+ * @returns {string}
+ */
+function getDefaultProjectBody() {
+  return `
+# Project Overview
+
+## 模块列表
+
+| 模块名 | 路径 | 描述 | 当前基线版本 |
+|--------|------|------|-------------|
+| - | - | - | - |
+
+## 技术约束
+
+- [添加项目特定的技术约束]
+
+## 备注
+
+[项目特定的说明和注意事项]
+`;
+}
+
+/**
+ * Create incspec directory structure
+ * @param {string} projectRoot
+ * @param {Object} config
+ */
+export function createIncspecStructure(projectRoot, config) {
+  const incspecDir = path.join(projectRoot, INCSPEC_DIR);
+
+  // Create main directory
+  if (!fs.existsSync(incspecDir)) {
+    fs.mkdirSync(incspecDir, { recursive: true });
+  }
+
+  // Create subdirectories
+  for (const dir of Object.values(DIRS)) {
+    const dirPath = path.join(incspecDir, dir);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  }
+
+  // Write project.md
+  writeProjectConfig(projectRoot, config);
+
+  // Write AGENTS.md from template
+  writeAgentsFile(projectRoot);
+}
+
+/**
+ * Write AGENTS.md file from template
+ * @param {string} projectRoot
+ */
+function writeAgentsFile(projectRoot) {
+  const agentsPath = path.join(projectRoot, INCSPEC_DIR, FILES.agents);
+  const templatePath = path.join(getTemplatesDir(), 'AGENTS.md');
+
+  // Read template content
+  if (fs.existsSync(templatePath)) {
+    const content = fs.readFileSync(templatePath, 'utf-8');
+    fs.writeFileSync(agentsPath, content, 'utf-8');
+  } else {
+    // Fallback: write a minimal AGENTS.md if template not found
+    const fallbackContent = `# IncSpec 使用指南
+
+请参阅 incspec-cli 文档获取完整的 AI 编码助手使用指南。
+
+## 快速开始
+
+1. 运行 \`incspec status\` 查看当前工作流状态
+2. 按顺序执行6步工作流: analyze → collect-req → collect-dep → design → apply → merge
+3. 使用 \`incspec help\` 获取更多帮助
+`;
+    fs.writeFileSync(agentsPath, fallbackContent, 'utf-8');
+  }
+}
+
+/**
+ * Ensure incspec is initialized, throw error if not
+ * @param {string} cwd
+ * @returns {string} Project root path
+ */
+export function ensureInitialized(cwd) {
+  const projectRoot = findProjectRoot(cwd);
+  
+  if (!projectRoot || !isInitialized(projectRoot)) {
+    throw new Error(
+      `incspec 未初始化。请先运行 'incspec init' 初始化项目。`
+    );
+  }
+
+  return projectRoot;
+}

package/lib/cursor.mjs

@@ -0,0 +1,307 @@
+/**
+ * Cursor integration utilities
+ * - Generate Cursor slash commands
+ * - Sync to project or global
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { fileURLToPath } from 'url';
+import { INCSPEC_DIR, DIRS } from './config.mjs';
+
+/** Cursor commands directory */
+const CURSOR_COMMANDS_DIR = '.cursor/commands/incspec';
+
+/** Global Cursor commands directory */
+const GLOBAL_CURSOR_DIR = path.join(os.homedir(), '.cursor', 'commands', 'incspec');
+
+/** Claude commands source directory (user local) */
+const CLAUDE_COMMANDS_DIR = path.join(os.homedir(), '.claude', 'commands', 'ai-increment');
+
+/** Built-in templates directory (fallback when Claude commands not installed) */
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates/cursor-commands', import.meta.url));
+
+/**
+ * Command mapping from Claude to Cursor
+ */
+const COMMAND_MAP = [
+  {
+    source: 'analyze-codeflow.md',
+    target: 'inc-analyze.md',
+    step: 1,
+    label: '步骤1: 分析代码流程',
+    description: '[incspec] 分析代码工作流,生成API时序图和依赖关系基线快照',
+  },
+  {
+    source: 'structured-requirements-collection.md',
+    target: 'inc-collect-req.md',
+    step: 2,
+    label: '步骤2: 结构化需求收集',
+    description: '[incspec] 交互式收集需求,生成5列结构化表格',
+  },
+  {
+    source: 'ui-dependency-collection.md',
+    target: 'inc-collect-dep.md',
+    step: 3,
+    label: '步骤3: UI依赖采集',
+    description: '[incspec] 交互式采集6维度UI依赖信息',
+  },
+  {
+    source: 'analyze-increment-codeflow.md',
+    target: 'inc-design.md',
+    step: 4,
+    label: '步骤4: 增量设计',
+    description: '[incspec] 基于需求和依赖生成增量设计蓝图(7大模块)',
+  },
+  {
+    source: 'apply-increment-code.md',
+    target: 'inc-apply.md',
+    step: 5,
+    label: '步骤5: 应用代码变更',
+    description: '[incspec] 根据增量设计执行代码变更',
+  },
+  {
+    source: 'merge-to-baseline.md',
+    target: 'inc-merge.md',
+    step: 6,
+    label: '步骤6: 合并到基线',
+    description: '[incspec] 将增量融合为新的代码流基线快照',
+  },
+];
+
+/**
+ * Generate Cursor command content
+ * Templates already contain complete Cursor command format with CLI sync instructions,
+ * so we just pass through the source content directly.
+ * @param {Object} cmd - Command definition
+ * @param {string} sourceContent - Original template content (already complete)
+ * @param {string} projectRoot - Project root path (optional, unused)
+ * @returns {string}
+ */
+function generateCursorCommand(cmd, sourceContent, projectRoot = null) {
+  // Templates are already complete Cursor commands, pass through directly
+  return sourceContent;
+}
+
+/**
+ * Get source file path with fallback to user local commands
+ * @param {string} fileName - Source file name
+ * @returns {string|null} Path to source file or null if not found
+ */
+function getSourcePath(fileName) {
+  // Try built-in templates first (preferred)
+  const templatePath = path.join(TEMPLATES_DIR, fileName);
+  if (fs.existsSync(templatePath)) {
+    return templatePath;
+  }
+
+  // Fallback to user local Claude commands
+  const claudePath = path.join(CLAUDE_COMMANDS_DIR, fileName);
+  if (fs.existsSync(claudePath)) {
+    return claudePath;
+  }
+
+  return null;
+}
+
+/**
+ * Generate all Cursor commands
+ * @param {string} projectRoot - Optional project root for customization
+ * @returns {Array<{name: string, content: string}>}
+ */
+export function generateCursorCommands(projectRoot = null) {
+  const commands = [];
+
+  for (const cmd of COMMAND_MAP) {
+    const sourcePath = getSourcePath(cmd.source);
+
+    let content;
+    if (sourcePath) {
+      const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
+      content = generateCursorCommand(cmd, sourceContent, projectRoot);
+    } else {
+      // Generate placeholder if source doesn't exist
+      content = `---
+description: ${cmd.description}
+---
+
+# ${cmd.label}
+
+> 源命令文件不存在: ${cmd.source}
+> 请确保已正确安装 incspec-cli 或 ai-incremental-coding 技能。
+
+请参考 incspec 文档手动执行此步骤。
+`;
+    }
+
+    commands.push({
+      name: cmd.target,
+      content,
+    });
+  }
+
+  // Add utility commands
+  commands.push({
+    name: 'inc-status.md',
+    content: `---
+description: [incspec] 查看当前工作流状态
+---
+
+# 查看工作流状态
+
+请运行以下命令查看当前工作流状态:
+
+\`\`\`bash
+incspec status
+\`\`\`
+
+或直接读取状态文件:
+
+\`\`\`bash
+cat ${INCSPEC_DIR}/WORKFLOW.md
+\`\`\`
+`,
+  });
+
+  commands.push({
+    name: 'inc-help.md',
+    content: `---
+description: [incspec] 显示帮助信息
+---
+
+# incspec 帮助
+
+## 工作流步骤
+
+1. \`/incspec/inc-analyze\` - 分析代码流程,生成基线快照
+2. \`/incspec/inc-collect-req\` - 收集结构化需求
+3. \`/incspec/inc-collect-dep\` - 采集UI依赖
+4. \`/incspec/inc-design\` - 生成增量设计蓝图
+5. \`/incspec/inc-apply\` - 应用代码变更
+6. \`/incspec/inc-merge\` - 合并到新基线
+
+## 辅助命令
+
+- \`/incspec/inc-archive\` - 归档规范文件到 archives 目录
+- \`/incspec/inc-status\` - 查看当前工作流状态
+- \`/incspec/inc-help\` - 显示帮助信息
+
+## CLI 命令
+
+\`\`\`bash
+incspec init          # 初始化项目
+incspec status        # 查看工作流状态
+incspec list          # 列出规范文件
+incspec validate      # 验证规范完整性
+incspec cursor-sync   # 同步 Cursor 命令
+incspec help          # 显示帮助
+\`\`\`
+
+## 目录结构
+
+\`\`\`
+${INCSPEC_DIR}/
+├── project.md        # 项目配置
+├── WORKFLOW.md       # 工作流状态
+├── baselines/        # 基线快照
+├── requirements/     # 需求文档
+├── increments/       # 增量设计
+└── archives/         # 历史归档 (YYYY-MM/{module}/)
+\`\`\`
+`,
+  });
+
+  // Add archive command from template
+  const archiveSourcePath = getSourcePath('inc-archive.md');
+  if (archiveSourcePath) {
+    const archiveContent = fs.readFileSync(archiveSourcePath, 'utf-8');
+    commands.push({
+      name: 'inc-archive.md',
+      content: archiveContent,
+    });
+  } else {
+    commands.push({
+      name: 'inc-archive.md',
+      content: `---
+description: [incspec] 归档规范文件到 archives 目录
+---
+
+# 归档规范文件
+
+请运行以下命令归档规范文件:
+
+\`\`\`bash
+# 归档当前工作流全部产出文件（默认模式）
+incspec archive --yes
+
+# 归档指定文件（默认移动模式，删除原文件）
+incspec archive <file-path> --yes
+
+# 归档并保留原文件（复制模式）
+incspec archive <file-path> --keep --yes
+\`\`\`
+`,
+    });
+  }
+
+  return commands;
+}
+
+/**
+ * Sync commands to project directory
+ * @param {string} projectRoot
+ * @returns {number} Number of files written
+ */
+export function syncToProject(projectRoot) {
+  const targetDir = path.join(projectRoot, CURSOR_COMMANDS_DIR);
+  
+  // Create directory
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  const commands = generateCursorCommands(projectRoot);
+  
+  for (const cmd of commands) {
+    const filePath = path.join(targetDir, cmd.name);
+    fs.writeFileSync(filePath, cmd.content, 'utf-8');
+  }
+
+  return commands.length;
+}
+
+/**
+ * Sync commands to global Cursor directory
+ * @returns {number} Number of files written
+ */
+export function syncToGlobal() {
+  // Create directory
+  if (!fs.existsSync(GLOBAL_CURSOR_DIR)) {
+    fs.mkdirSync(GLOBAL_CURSOR_DIR, { recursive: true });
+  }
+
+  const commands = generateCursorCommands();
+  
+  for (const cmd of commands) {
+    const filePath = path.join(GLOBAL_CURSOR_DIR, cmd.name);
+    fs.writeFileSync(filePath, cmd.content, 'utf-8');
+  }
+
+  return commands.length;
+}
+
+/**
+ * Check if Cursor commands exist
+ * @param {string} projectRoot
+ * @returns {{project: boolean, global: boolean}}
+ */
+export function checkCursorCommands(projectRoot) {
+  const projectDir = path.join(projectRoot, CURSOR_COMMANDS_DIR);
+  const globalDir = GLOBAL_CURSOR_DIR;
+
+  return {
+    project: fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0,
+    global: fs.existsSync(globalDir) && fs.readdirSync(globalDir).length > 0,
+  };
+}