cc-devflow 1.0.1

package/lib/compiler/parser.js

@@ -0,0 +1,258 @@
+/**
+ * T025: Parser Module
+ *
+ * Parses .claude/commands/*.md files:
+ * - Extracts YAML frontmatter using gray-matter
+ * - Validates frontmatter with Zod schema
+ * - Detects placeholders ({SCRIPT:*}, {TEMPLATE:*}, {GUIDE:*}, {AGENT_SCRIPT}, $ARGUMENTS)
+ * - Computes SHA-256 content hash
+ * - Returns CommandIR structure
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const matter = require('gray-matter');
+
+const { FrontmatterSchema, CommandIRSchema } = require('./schemas.js');
+const {
+  MissingFrontmatterError,
+  InvalidFrontmatterError,
+  UnknownAliasError,
+  UnknownTemplateAliasError,
+  UnknownGuideAliasError
+} = require('./errors.js');
+
+// ============================================================
+// SECURITY CONFIGURATION (FINDING-002, FINDING-003)
+// ============================================================
+const MAX_FILE_SIZE = 1024 * 1024; // 1MB limit (FINDING-003: Resource Exhaustion)
+
+// ============================================================
+// Placeholder Detection Patterns
+// ============================================================
+const SCRIPT_PATTERN = /\{SCRIPT:([^}]+)\}/g;
+const TEMPLATE_PATTERN = /\{TEMPLATE:([^}]+)\}/g;
+const GUIDE_PATTERN = /\{GUIDE:([^}]+)\}/g;
+const AGENT_SCRIPT_PATTERN = /\{AGENT_SCRIPT\}/g;
+const ARGUMENTS_PATTERN = /\$ARGUMENTS/g;
+
+// ============================================================
+// hashContent - 计算 SHA-256 哈希
+// ============================================================
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+// ============================================================
+// detectPlaceholders - 检测正文中的占位符
+// ============================================================
+function detectPlaceholders(body) {
+  const placeholders = [];
+
+  // 检测 {SCRIPT:alias}
+  let match;
+  const scriptPattern = new RegExp(SCRIPT_PATTERN.source, 'g');
+  while ((match = scriptPattern.exec(body)) !== null) {
+    placeholders.push({
+      type: 'SCRIPT',
+      raw: match[0],
+      alias: match[1],
+      position: { start: match.index, end: match.index + match[0].length }
+    });
+  }
+
+  // 检测 {TEMPLATE:alias}
+  const templatePattern = new RegExp(TEMPLATE_PATTERN.source, 'g');
+  while ((match = templatePattern.exec(body)) !== null) {
+    placeholders.push({
+      type: 'TEMPLATE',
+      raw: match[0],
+      alias: match[1],
+      position: { start: match.index, end: match.index + match[0].length }
+    });
+  }
+
+  // 检测 {GUIDE:alias}
+  const guidePattern = new RegExp(GUIDE_PATTERN.source, 'g');
+  while ((match = guidePattern.exec(body)) !== null) {
+    placeholders.push({
+      type: 'GUIDE',
+      raw: match[0],
+      alias: match[1],
+      position: { start: match.index, end: match.index + match[0].length }
+    });
+  }
+
+  // 检测 {AGENT_SCRIPT}
+  const agentPattern = new RegExp(AGENT_SCRIPT_PATTERN.source, 'g');
+  while ((match = agentPattern.exec(body)) !== null) {
+    placeholders.push({
+      type: 'AGENT_SCRIPT',
+      raw: match[0],
+      position: { start: match.index, end: match.index + match[0].length }
+    });
+  }
+
+  // 检测 $ARGUMENTS
+  const argsPattern = new RegExp(ARGUMENTS_PATTERN.source, 'g');
+  while ((match = argsPattern.exec(body)) !== null) {
+    placeholders.push({
+      type: 'ARGUMENTS',
+      raw: match[0],
+      position: { start: match.index, end: match.index + match[0].length }
+    });
+  }
+
+  return placeholders;
+}
+
+// ============================================================
+// validateScriptAliases - 验证 SCRIPT alias 是否在 frontmatter 中定义
+// ============================================================
+function validateScriptAliases(placeholders, scripts, filePath) {
+  const scriptPlaceholders = placeholders.filter(p => p.type === 'SCRIPT');
+
+  for (const placeholder of scriptPlaceholders) {
+    if (!scripts || !scripts[placeholder.alias]) {
+      throw new UnknownAliasError(filePath, placeholder.alias);
+    }
+  }
+}
+
+// ============================================================
+// validateTemplateAliases - 验证 TEMPLATE alias 是否在 frontmatter 中定义
+// ============================================================
+function validateTemplateAliases(placeholders, templates, filePath) {
+  const templatePlaceholders = placeholders.filter(p => p.type === 'TEMPLATE');
+
+  for (const placeholder of templatePlaceholders) {
+    if (!templates || !templates[placeholder.alias]) {
+      throw new UnknownTemplateAliasError(filePath, placeholder.alias);
+    }
+  }
+}
+
+// ============================================================
+// validateGuideAliases - 验证 GUIDE alias 是否在 frontmatter 中定义
+// ============================================================
+function validateGuideAliases(placeholders, guides, filePath) {
+  const guidePlaceholders = placeholders.filter(p => p.type === 'GUIDE');
+
+  for (const placeholder of guidePlaceholders) {
+    if (!guides || !guides[placeholder.alias]) {
+      throw new UnknownGuideAliasError(filePath, placeholder.alias);
+    }
+  }
+}
+
+// ============================================================
+// parseCommand - 解析单个命令文件
+// ============================================================
+function parseCommand(filePath) {
+  // 读取文件内容
+  const absolutePath = path.resolve(filePath);
+
+  // ✅ SECURITY FIX (FINDING-003): Check file size before reading
+  const stats = fs.statSync(absolutePath);
+  if (stats.size > MAX_FILE_SIZE) {
+    throw new Error(`File too large: ${filePath} (${stats.size} bytes > ${MAX_FILE_SIZE} bytes)`);
+  }
+
+  const content = fs.readFileSync(absolutePath, 'utf8');
+  const hash = hashContent(content);
+
+  // ✅ SECURITY FIX (FINDING-002): Enable YAML safe mode (CORE_SCHEMA)
+  const yaml = require('js-yaml');
+  const parsed = matter(content, {
+    engines: {
+      yaml: (s) => yaml.load(s, { schema: yaml.CORE_SCHEMA })
+    }
+  });
+
+  // 检查是否有 frontmatter
+  if (!parsed.data || Object.keys(parsed.data).length === 0) {
+    throw new MissingFrontmatterError(filePath);
+  }
+
+  // 验证 frontmatter schema
+  const frontmatterResult = FrontmatterSchema.safeParse(parsed.data);
+  if (!frontmatterResult.success) {
+    const errorMessages = frontmatterResult.error.issues
+      .map(issue => `${issue.path.join('.')}: ${issue.message}`)
+      .join(', ');
+    throw new InvalidFrontmatterError(filePath, errorMessages);
+  }
+
+  const frontmatter = frontmatterResult.data;
+  const body = parsed.content;
+
+  // 检测占位符
+  const placeholders = detectPlaceholders(body);
+
+  // 验证 SCRIPT alias 存在性
+  validateScriptAliases(placeholders, frontmatter.scripts, filePath);
+
+  // 验证 TEMPLATE alias 存在性
+  validateTemplateAliases(placeholders, frontmatter.templates, filePath);
+
+  // 验证 GUIDE alias 存在性
+  validateGuideAliases(placeholders, frontmatter.guides, filePath);
+
+  // 构建 CommandIR
+  const ir = {
+    source: {
+      path: absolutePath,
+      filename: path.basename(filePath, '.md'),
+      hash
+    },
+    frontmatter,
+    body,
+    placeholders
+  };
+
+  // 最终验证 CommandIR
+  const irResult = CommandIRSchema.safeParse(ir);
+  if (!irResult.success) {
+    throw new InvalidFrontmatterError(filePath, 'Invalid CommandIR structure');
+  }
+
+  return irResult.data;
+}
+
+// ============================================================
+// parseAllCommands - 批量解析命令目录
+// ============================================================
+async function parseAllCommands(dirPath) {
+  const absoluteDir = path.resolve(dirPath);
+
+  // 读取目录中的所有文件
+  const files = fs.readdirSync(absoluteDir);
+
+  // 过滤 .md 文件
+  const mdFiles = files.filter(file => file.endsWith('.md'));
+
+  // 解析每个文件
+  const results = [];
+  for (const file of mdFiles) {
+    const filePath = path.join(absoluteDir, file);
+    try {
+      const ir = parseCommand(filePath);
+      results.push(ir);
+    } catch (error) {
+      // 重新抛出以便调用者处理
+      throw error;
+    }
+  }
+
+  return results;
+}
+
+module.exports = {
+  parseCommand,
+  parseAllCommands,
+  hashContent,
+  detectPlaceholders,
+  validateScriptAliases,
+  validateTemplateAliases,
+  validateGuideAliases
+};

package/lib/compiler/platforms.js

@@ -0,0 +1,113 @@
+/**
+ * T001: Platform Configuration Registry
+ *
+ * 定义四个目标平台的编译配置:
+ * - cursor: Cursor IDE (.mdc format)
+ * - codex: Codex CLI (SKILL.md format)
+ * - qwen: Qwen Code (.toml format)
+ * - antigravity: Antigravity (.md with 12K limit)
+ *
+ * Reference: data-model.md#PlatformConfig
+ */
+
+// ============================================================
+// PLATFORM_CONFIG - 平台配置注册表
+// ============================================================
+const PLATFORM_CONFIG = {
+  cursor: {
+    name: 'Cursor IDE',
+    folder: '.cursor/',
+    rulesEntry: {
+      path: 'rules/devflow.mdc',
+      format: 'mdc'
+    },
+    commandsDir: 'commands/',
+    commandExt: '.md',
+    argumentPattern: '$ARGUMENTS',
+    hasHooks: false,
+    limits: {}
+  },
+
+  codex: {
+    name: 'Codex CLI',
+    folder: '.codex/',
+    rulesEntry: {
+      path: 'skills/cc-devflow/SKILL.md',
+      format: 'markdown'
+    },
+    commandsDir: 'prompts/',
+    commandExt: '.md',
+    argumentPattern: '$ARGUMENTS',
+    hasHooks: false,
+    limits: {}
+  },
+
+  qwen: {
+    name: 'Qwen Code',
+    folder: '.qwen/',
+    rulesEntry: {
+      path: 'commands/devflow.toml',
+      format: 'toml'
+    },
+    commandsDir: 'commands/',
+    commandExt: '.toml',
+    argumentPattern: '{{args}}',
+    hasHooks: false,
+    limits: {}
+  },
+
+  antigravity: {
+    name: 'Antigravity',
+    folder: '.agent/',
+    rulesEntry: {
+      path: 'rules/rules.md',
+      format: 'markdown'
+    },
+    commandsDir: 'workflows/',
+    commandExt: '.md',
+    argumentPattern: '$ARGUMENTS',
+    hasHooks: false,
+    limits: {
+      maxFileChars: 12000
+    }
+  }
+};
+
+// ============================================================
+// PLATFORMS - 平台名称列表
+// ============================================================
+const PLATFORMS = Object.keys(PLATFORM_CONFIG);
+
+// ============================================================
+// getPlatformConfig - 获取平台配置
+// ============================================================
+function getPlatformConfig(platform) {
+  const config = PLATFORM_CONFIG[platform];
+  if (!config) {
+    throw new Error(`Unknown platform: ${platform}. Valid: ${PLATFORMS.join(', ')}`);
+  }
+  return config;
+}
+
+// ============================================================
+// isValidPlatform - 验证平台名有效性
+// ============================================================
+function isValidPlatform(platform) {
+  return PLATFORMS.includes(platform);
+}
+
+// ============================================================
+// getRulesEntryPath - 获取规则入口文件完整路径
+// ============================================================
+function getRulesEntryPath(platform) {
+  const config = getPlatformConfig(platform);
+  return `${config.folder}${config.rulesEntry.path}`;
+}
+
+module.exports = {
+  PLATFORM_CONFIG,
+  PLATFORMS,
+  getPlatformConfig,
+  isValidPlatform,
+  getRulesEntryPath
+};

package/lib/compiler/resource-copier.js

@@ -0,0 +1,320 @@
+/**
+ * T050: Resource Copier Module
+ *
+ * 资源文件复制与路径重写:
+ * - 收集 IR 中引用的 scripts/templates/guides 文件
+ * - 复制到各平台对应目录
+ * - 提供路径映射表供 transformer 重写内容中的路径
+ *
+ * 目录映射规则:
+ *   .claude/scripts/       → .{platform}/scripts/
+ *   .claude/docs/templates/ → .{platform}/docs/templates/
+ *   .claude/docs/guides/    → .{platform}/docs/guides/
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ============================================================
+// Platform Directory Mapping
+// ============================================================
+const PLATFORM_DIRS = {
+  codex: '.codex',
+  cursor: '.cursor',
+  qwen: '.qwen',
+  antigravity: '.agent'
+};
+
+// ============================================================
+// Patterns for inline .claude/ path detection
+// ============================================================
+const INLINE_CLAUDE_PATH_PATTERN = /\.claude\/(scripts|docs\/templates|docs\/guides)\/[^\s"'`<>)}\]]+/g;
+
+// ============================================================
+// collectReferencedResources - 收集 IR 中引用的资源文件
+// 包括 frontmatter 定义的和内容中直接硬编码的
+// ============================================================
+function collectReferencedResources(irs) {
+  const resources = {
+    scripts: new Set(),
+    templates: new Set(),
+    guides: new Set()
+  };
+
+  for (const ir of irs) {
+    const fm = ir.frontmatter;
+
+    // 1. 收集 frontmatter 中定义的 scripts
+    if (fm.scripts) {
+      for (const scriptPath of Object.values(fm.scripts)) {
+        resources.scripts.add(scriptPath);
+      }
+    }
+
+    // 2. 收集 frontmatter 中定义的 templates
+    if (fm.templates) {
+      for (const templatePath of Object.values(fm.templates)) {
+        resources.templates.add(templatePath);
+      }
+    }
+
+    // 3. 收集 frontmatter 中定义的 guides
+    if (fm.guides) {
+      for (const guidePath of Object.values(fm.guides)) {
+        resources.guides.add(guidePath);
+      }
+    }
+
+    // 4. 收集 agent_scripts 中的脚本路径
+    if (fm.agent_scripts) {
+      if (fm.agent_scripts.sh) {
+        // 提取脚本路径（去掉 __AGENT__ 等参数）
+        const shPath = extractScriptPath(fm.agent_scripts.sh);
+        if (shPath && shPath.startsWith('.claude/scripts/')) {
+          resources.scripts.add(shPath);
+        }
+      }
+    }
+
+    // 5. 扫描内容中直接硬编码的 .claude/ 路径
+    const inlinePaths = scanInlineClaudePaths(ir.body);
+    for (const inlinePath of inlinePaths) {
+      if (inlinePath.startsWith('.claude/scripts/')) {
+        resources.scripts.add(inlinePath);
+      } else if (inlinePath.startsWith('.claude/docs/templates/')) {
+        resources.templates.add(inlinePath);
+      } else if (inlinePath.startsWith('.claude/docs/guides/')) {
+        resources.guides.add(inlinePath);
+      }
+    }
+  }
+
+  return {
+    scripts: Array.from(resources.scripts),
+    templates: Array.from(resources.templates),
+    guides: Array.from(resources.guides)
+  };
+}
+
+// ============================================================
+// extractScriptPath - 从命令字符串中提取脚本路径
+// 例如：".claude/scripts/foo.sh __AGENT__" → ".claude/scripts/foo.sh"
+// ============================================================
+function extractScriptPath(commandString) {
+  if (!commandString) return null;
+  // 匹配 .claude/ 开头的路径
+  const match = commandString.match(/^(\.claude\/[^\s]+)/);
+  return match ? match[1] : null;
+}
+
+// ============================================================
+// scanInlineClaudePaths - 扫描内容中直接硬编码的 .claude/ 路径
+// ============================================================
+function scanInlineClaudePaths(content) {
+  const paths = new Set();
+  const pattern = new RegExp(INLINE_CLAUDE_PATH_PATTERN.source, 'g');
+
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    // 清理路径末尾可能的标点符号
+    let cleanPath = match[0];
+    // 移除末尾的常见标点
+    cleanPath = cleanPath.replace(/[,;:.\s]+$/, '');
+    paths.add(cleanPath);
+  }
+
+  return Array.from(paths);
+}
+
+// ============================================================
+// mapPathToPlatform - 将 .claude/ 路径映射到平台路径
+// ============================================================
+function mapPathToPlatform(sourcePath, platform) {
+  const platformDir = PLATFORM_DIRS[platform];
+  if (!platformDir) {
+    throw new Error(`Unknown platform: ${platform}`);
+  }
+
+  // 将 .claude/xxx 替换为 .{platform}/xxx
+  if (sourcePath.startsWith('.claude/')) {
+    return sourcePath.replace(/^\.claude\//, `${platformDir}/`);
+  }
+
+  // 如果不是 .claude 开头，保持原样
+  return sourcePath;
+}
+
+// ============================================================
+// copyResourceFile - 复制单个资源文件
+// ============================================================
+async function copyResourceFile(sourcePath, targetPath, options = {}) {
+  const { verbose = false, dryRun = false } = options;
+
+  // 解析绝对路径
+  const absoluteSource = path.resolve(process.cwd(), sourcePath);
+  const absoluteTarget = path.resolve(process.cwd(), targetPath);
+
+  // 检查源文件是否存在
+  if (!fs.existsSync(absoluteSource)) {
+    if (verbose) {
+      console.warn(`Warning: Source file not found: ${sourcePath}`);
+    }
+    return { success: false, error: 'Source not found' };
+  }
+
+  if (dryRun) {
+    if (verbose) {
+      console.log(`[DRY-RUN] Would copy: ${sourcePath} → ${targetPath}`);
+    }
+    return { success: true, dryRun: true };
+  }
+
+  try {
+    // 确保目标目录存在
+    const targetDir = path.dirname(absoluteTarget);
+    await fs.promises.mkdir(targetDir, { recursive: true, mode: 0o755 });
+
+    // 复制文件
+    await fs.promises.copyFile(absoluteSource, absoluteTarget);
+
+    // 设置权限
+    await fs.promises.chmod(absoluteTarget, 0o644);
+
+    if (verbose) {
+      console.log(`Copied: ${sourcePath} → ${targetPath}`);
+    }
+
+    return { success: true, source: sourcePath, target: targetPath };
+  } catch (error) {
+    if (verbose) {
+      console.error(`Error copying ${sourcePath}: ${error.message}`);
+    }
+    return { success: false, error: error.message };
+  }
+}
+
+// ============================================================
+// copyResourcesForPlatform - 为单个平台复制所有资源
+// ============================================================
+async function copyResourcesForPlatform(resources, platform, options = {}) {
+  const { verbose = false, dryRun = false } = options;
+  const results = {
+    platform,
+    copied: 0,
+    skipped: 0,
+    errors: [],
+    pathMap: {} // 源路径 → 目标路径 映射
+  };
+
+  // 合并所有资源
+  const allResources = [
+    ...resources.scripts,
+    ...resources.templates,
+    ...resources.guides
+  ];
+
+  for (const sourcePath of allResources) {
+    const targetPath = mapPathToPlatform(sourcePath, platform);
+    results.pathMap[sourcePath] = targetPath;
+
+    // 检查目标文件是否已存在且相同
+    const absoluteSource = path.resolve(process.cwd(), sourcePath);
+    const absoluteTarget = path.resolve(process.cwd(), targetPath);
+
+    if (fs.existsSync(absoluteTarget) && fs.existsSync(absoluteSource)) {
+      const sourceHash = hashFile(absoluteSource);
+      const targetHash = hashFile(absoluteTarget);
+      if (sourceHash === targetHash) {
+        results.skipped++;
+        if (verbose) {
+          console.log(`Skipped (unchanged): ${targetPath}`);
+        }
+        continue;
+      }
+    }
+
+    const copyResult = await copyResourceFile(sourcePath, targetPath, { verbose, dryRun });
+
+    if (copyResult.success) {
+      results.copied++;
+    } else {
+      results.errors.push({ source: sourcePath, error: copyResult.error });
+    }
+  }
+
+  return results;
+}
+
+// ============================================================
+// copyResourcesForAllPlatforms - 为所有平台复制资源
+// ============================================================
+async function copyResourcesForAllPlatforms(irs, platforms, options = {}) {
+  const resources = collectReferencedResources(irs);
+  const results = {
+    totalCopied: 0,
+    totalSkipped: 0,
+    platforms: {},
+    allPathMaps: {} // platform → pathMap
+  };
+
+  for (const platform of platforms) {
+    const platformResult = await copyResourcesForPlatform(resources, platform, options);
+    results.platforms[platform] = platformResult;
+    results.allPathMaps[platform] = platformResult.pathMap;
+    results.totalCopied += platformResult.copied;
+    results.totalSkipped += platformResult.skipped;
+  }
+
+  return results;
+}
+
+// ============================================================
+// rewritePathsInContent - 重写内容中的 .claude/ 路径
+// ============================================================
+function rewritePathsInContent(content, pathMap) {
+  let result = content;
+
+  // 按路径长度降序排序，避免短路径替换长路径的部分
+  const sortedPaths = Object.keys(pathMap).sort((a, b) => b.length - a.length);
+
+  for (const sourcePath of sortedPaths) {
+    const targetPath = pathMap[sourcePath];
+    // 全局替换
+    result = result.split(sourcePath).join(targetPath);
+  }
+
+  return result;
+}
+
+// ============================================================
+// hashFile - 计算文件哈希
+// ============================================================
+function hashFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================
+// clearResourceCache - 清除资源缓存（用于测试）
+// ============================================================
+function clearResourceCache() {
+  // 目前没有缓存，预留接口
+}
+
+module.exports = {
+  PLATFORM_DIRS,
+  INLINE_CLAUDE_PATH_PATTERN,
+  collectReferencedResources,
+  scanInlineClaudePaths,
+  extractScriptPath,
+  mapPathToPlatform,
+  copyResourceFile,
+  copyResourcesForPlatform,
+  copyResourcesForAllPlatforms,
+  rewritePathsInContent,
+  clearResourceCache
+};