cc-devflow 4.3.0 → 4.5.0

package/lib/compiler/resource-copier.js

@@ -14,6 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const matter = require('gray-matter');
 
 // ============================================================
 // Platform Directory Mapping
@@ -120,12 +121,6 @@ function scanInlineClaudePaths(content) {
     let cleanPath = match[0];
     // 移除末尾的常见标点
     cleanPath = cleanPath.replace(/[,;:.\s]+$/, '');
-
-    // 跳过 glob 模式（例如 *.jsonl.template），避免误判为单文件资源
-    if (cleanPath.includes('*')) {
-      continue;
-    }
-
     paths.add(cleanPath);
   }
 
@@ -304,6 +299,180 @@ function hashFile(filePath) {
   }
 }
 
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function toRepoRelativePath(absolutePath) {
+  return path.relative(process.cwd(), absolutePath).split(path.sep).join('/');
+}
+
+function rewriteCodexSkillReads(content, sourceSkillDir, targetSkillDir) {
+  const parsed = matter(content);
+  const reads = Array.isArray(parsed.data.reads) ? parsed.data.reads : [];
+
+  parsed.data.reads = reads.map((entry) => {
+    const relativeEntry = String(entry || '').trim();
+    if (!relativeEntry || path.isAbsolute(relativeEntry)) {
+      return relativeEntry;
+    }
+
+    const bundledSourcePath = path.join(sourceSkillDir, relativeEntry);
+    if (!fs.existsSync(bundledSourcePath)) {
+      return relativeEntry;
+    }
+
+    return toRepoRelativePath(path.join(targetSkillDir, relativeEntry));
+  });
+
+  return matter.stringify(parsed.content, parsed.data);
+}
+
+async function copyMirroredFile(sourcePath, targetPath, platform, options = {}) {
+  const { sourceSkillDir = null, targetSkillDir = null } = options;
+  const stat = await fs.promises.stat(sourcePath);
+  await fs.promises.mkdir(path.dirname(targetPath), { recursive: true, mode: 0o755 });
+
+  if (
+    platform === 'codex' &&
+    path.basename(sourcePath) === 'SKILL.md' &&
+    sourceSkillDir &&
+    targetSkillDir
+  ) {
+    const sourceContent = await fs.promises.readFile(sourcePath, 'utf8');
+    const rewritten = rewriteCodexSkillReads(sourceContent, sourceSkillDir, targetSkillDir);
+    await fs.promises.writeFile(targetPath, rewritten, 'utf8');
+  } else {
+    await fs.promises.copyFile(sourcePath, targetPath);
+  }
+
+  await fs.promises.chmod(targetPath, stat.mode & 0o777);
+}
+
+async function getExpectedMirroredHash(sourcePath, targetPath, platform, options = {}) {
+  const { sourceSkillDir = null, targetSkillDir = null } = options;
+
+  if (
+    platform === 'codex' &&
+    path.basename(sourcePath) === 'SKILL.md' &&
+    sourceSkillDir &&
+    targetSkillDir
+  ) {
+    const sourceContent = await fs.promises.readFile(sourcePath, 'utf8');
+    const rewritten = rewriteCodexSkillReads(sourceContent, sourceSkillDir, targetSkillDir);
+    return hashContent(rewritten);
+  }
+
+  return hashFile(sourcePath);
+}
+
+// ============================================================
+// mirrorSkillDirectoriesForPlatform - 镜像 skills 目录到平台目录
+// ============================================================
+async function mirrorSkillDirectoriesForPlatform(skillsDir, platform, skillNames, options = {}) {
+  const { verbose = false, dryRun = false } = options;
+  const result = {
+    platform,
+    copied: 0,
+    skipped: 0,
+    errors: []
+  };
+
+  const platformDir = PLATFORM_DIRS[platform];
+  if (!platformDir) {
+    throw new Error(`Unknown platform: ${platform}`);
+  }
+
+  const sourceRoot = path.resolve(process.cwd(), skillsDir);
+  const targetRoot = path.resolve(process.cwd(), platformDir, 'skills');
+
+  for (const skillName of skillNames) {
+    const sourceSkillDir = path.join(sourceRoot, skillName);
+    const targetSkillDir = path.join(targetRoot, skillName);
+
+    if (!fs.existsSync(sourceSkillDir)) {
+      result.errors.push({ skill: skillName, error: 'Source skill directory not found' });
+      continue;
+    }
+
+    const mirrorResult = await mirrorDirectoryRecursive(sourceSkillDir, targetSkillDir, {
+      verbose,
+      dryRun,
+      platform,
+      sourceSkillDir,
+      targetSkillDir
+    });
+    result.copied += mirrorResult.copied;
+    result.skipped += mirrorResult.skipped;
+    result.errors.push(...mirrorResult.errors.map((error) => ({ skill: skillName, error })));
+  }
+
+  return result;
+}
+
+async function mirrorDirectoryRecursive(sourceDir, targetDir, options = {}) {
+  const { verbose = false, dryRun = false, platform, sourceSkillDir, targetSkillDir } = options;
+  const result = {
+    copied: 0,
+    skipped: 0,
+    errors: []
+  };
+
+  let entries;
+  try {
+    entries = await fs.promises.readdir(sourceDir, { withFileTypes: true });
+  } catch (error) {
+    result.errors.push(error.message);
+    return result;
+  }
+
+  if (!dryRun) {
+    await fs.promises.mkdir(targetDir, { recursive: true, mode: 0o755 });
+  }
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      const nested = await mirrorDirectoryRecursive(sourcePath, targetPath, options);
+      result.copied += nested.copied;
+      result.skipped += nested.skipped;
+      result.errors.push(...nested.errors);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const sourceHash = await getExpectedMirroredHash(sourcePath, targetPath, platform, {
+      sourceSkillDir,
+      targetSkillDir
+    });
+    const targetHash = fs.existsSync(targetPath) ? hashFile(targetPath) : null;
+
+    if (sourceHash && targetHash && sourceHash === targetHash) {
+      result.skipped++;
+      if (verbose) {
+        console.log(`Skipped skill file (unchanged): ${path.relative(process.cwd(), targetPath)}`);
+      }
+      continue;
+    }
+
+    if (!dryRun) {
+      await copyMirroredFile(sourcePath, targetPath, platform, { sourceSkillDir, targetSkillDir });
+    }
+
+    result.copied++;
+    if (verbose) {
+      console.log(`Mirrored skill file: ${path.relative(process.cwd(), targetPath)}`);
+    }
+  }
+
+  return result;
+}
+
 // ============================================================
 // clearResourceCache - 清除资源缓存（用于测试）
 // ============================================================
@@ -321,6 +490,7 @@ module.exports = {
   copyResourceFile,
   copyResourcesForPlatform,
   copyResourcesForAllPlatforms,
+  mirrorSkillDirectoriesForPlatform,
   rewritePathsInContent,
   clearResourceCache
 };

package/lib/compiler/rules-emitters/__tests__/antigravity-rules-emitter.test.js

@@ -37,7 +37,7 @@ describe('AntigravityRulesEmitter', () => {
       expect(parsed.data).toHaveProperty('description');
     });
 
-    test('should include skills and commands content', async () => {
+    test('should include skills and optional command summaries', async () => {
       const { AntigravityRulesEmitter } = require('../../rules-emitters/antigravity-rules-emitter');
 
       const emitter = new AntigravityRulesEmitter();
@@ -48,13 +48,13 @@ describe('AntigravityRulesEmitter', () => {
         ]
       };
       const commands = [
-        { name: 'flow-init', description: 'Initialize' }
+        { name: 'cc-plan', description: 'Plan one requirement' }
       ];
 
       const content = emitter.format(registry, commands);
 
       expect(content).toContain('cc-devflow-orchestrator');
-      expect(content).toContain('flow-init');
+      expect(content).toContain('cc-plan');
     });
   });
 

package/lib/compiler/rules-emitters/__tests__/cursor-rules-emitter.test.js

@@ -78,8 +78,8 @@ describe('CursorRulesEmitter', () => {
 
       const emitter = new CursorRulesEmitter();
       const commands = [
-        { name: 'flow-init', description: 'Initialize requirement' },
-        { name: 'flow-prd', description: 'Generate PRD' }
+        { name: 'cc-plan', description: 'Plan one requirement' },
+        { name: 'cc-check', description: 'Verify with evidence' }
       ];
 
       const content = emitter.format({ skills: [] }, commands);
@@ -87,8 +87,18 @@ describe('CursorRulesEmitter', () => {
 
       // Markdown body 应包含 Commands 部分
       expect(parsed.content).toMatch(/## Key Commands|## Commands/i);
-      expect(parsed.content).toContain('flow-init');
-      expect(parsed.content).toContain('flow-prd');
+      expect(parsed.content).toContain('cc-plan');
+      expect(parsed.content).toContain('cc-check');
+    });
+
+    test('should omit Commands section when command list is empty', async () => {
+      const { CursorRulesEmitter } = require('../../rules-emitters/cursor-rules-emitter');
+
+      const emitter = new CursorRulesEmitter();
+      const content = emitter.format({ skills: [] }, []);
+      const parsed = matter(content);
+
+      expect(parsed.content).not.toMatch(/## Commands/i);
     });
   });
 

package/lib/compiler/rules-emitters/__tests__/qwen-rules-emitter.test.js

@@ -3,7 +3,7 @@
  *
  * 测试 QwenRulesEmitter TOML 格式输出:
  * 1. 输出为有效 TOML (可被 @iarna/toml 解析)
- * 2. 包含 [skill] 和 [commands] 段
+ * 2. 包含 [skill] 段，存在命令摘要时包含 [commands] 段
  * 3. 输出路径为 .qwen/commands/devflow.toml
  *
  * Reference: contracts/cli-spec.yaml#qwen
@@ -74,13 +74,13 @@ describe('QwenRulesEmitter', () => {
       expect(parsed.skills['cc-devflow-orchestrator'].type).toBe('domain');
     });
 
-    test('should contain [commands] section', async () => {
+    test('should contain [commands] section when command summaries exist', async () => {
       const { QwenRulesEmitter } = require('../../rules-emitters/qwen-rules-emitter');
 
       const emitter = new QwenRulesEmitter();
       const commands = [
-        { name: 'flow-init', description: 'Initialize' },
-        { name: 'flow-prd', description: 'Generate PRD' }
+        { name: 'cc-plan', description: 'Plan one requirement' },
+        { name: 'cc-check', description: 'Verify with evidence' }
       ];
 
       const content = emitter.format({ skills: [] }, commands);
@@ -88,10 +88,19 @@ describe('QwenRulesEmitter', () => {
 
       // 验证 [commands] 段存在
       expect(parsed).toHaveProperty('commands');
-      expect(parsed.commands).toHaveProperty('flow-init');
-      expect(parsed.commands).toHaveProperty('flow-prd');
+      expect(parsed.commands).toHaveProperty('cc-plan');
+      expect(parsed.commands).toHaveProperty('cc-check');
 
-      expect(parsed.commands['flow-init'].description).toBe('Initialize');
+      expect(parsed.commands['cc-plan'].description).toBe('Plan one requirement');
+    });
+
+    test('should omit [commands] section when command summaries are empty', async () => {
+      const { QwenRulesEmitter } = require('../../rules-emitters/qwen-rules-emitter');
+
+      const emitter = new QwenRulesEmitter();
+      const parsed = TOML.parse(emitter.format({ skills: [] }, []));
+
+      expect(parsed.commands).toBeUndefined();
     });
   });
 

package/lib/compiler/rules-emitters/antigravity-rules-emitter.js

@@ -33,9 +33,9 @@ class AntigravityRulesEmitter extends BaseRulesEmitter {
   // ----------------------------------------------------------
   // format() - 生成 Markdown 格式内容
   // ----------------------------------------------------------
-  format(registry, commands) {
+  format(registry, promptSummaries = []) {
     const frontmatter = this.buildFrontmatter(registry);
-    const body = this.buildBody(registry, commands);
+    const body = this.buildBody(registry, promptSummaries);
 
     return `---
 ${frontmatter}---
@@ -55,7 +55,7 @@ ${body}`;
   // ----------------------------------------------------------
   // buildBody() - 构建 Markdown 正文
   // ----------------------------------------------------------
-  buildBody(registry, commands) {
+  buildBody(registry, promptSummaries = []) {
     const sections = [];
 
     // 标题
@@ -81,20 +81,15 @@ ${body}`;
       sections.push('');
     }
 
-    // 命令章节
-    sections.push('## Commands');
-    sections.push('');
-
-    if (commands && commands.length > 0) {
-      for (const cmd of commands) {
+    if (promptSummaries.length > 0) {
+      sections.push('## Commands');
+      sections.push('');
+      for (const cmd of promptSummaries) {
         sections.push(`### /${cmd.name}`);
         sections.push('');
         sections.push(cmd.description || 'No description');
         sections.push('');
       }
-    } else {
-      sections.push('No commands available.');
-      sections.push('');
     }
 
     return sections.join('\n');
@@ -103,8 +98,8 @@ ${body}`;
   // ----------------------------------------------------------
   // emit() - 写入文件，超过 12K 时分块
   // ----------------------------------------------------------
-  async emit(registry, commands) {
-    const content = this.format(registry, commands);
+  async emit(registry, promptSummaries = []) {
+    const content = this.format(registry, promptSummaries);
 
     // 检查是否需要分块
     if (content.length <= MAX_FILE_CHARS) {
@@ -113,7 +108,7 @@ ${body}`;
     }
 
     // 分块输出
-    return this.emitMultipleFiles(content, registry, commands);
+    return this.emitMultipleFiles(content, registry, promptSummaries);
   }
 
   // ----------------------------------------------------------

package/lib/compiler/rules-emitters/base-rules-emitter.js

@@ -4,8 +4,8 @@
  * 定义 RulesEmitter 接口:
  * - platform: 平台标识符
  * - outputPath: 输出文件路径
- * - format(registry, commands): 格式化规则内容
- * - emit(registry, commands): 写入规则入口文件
+ * - format(registry, promptSummaries): 格式化规则内容
+ * - emit(registry, promptSummaries): 写入规则入口文件
  *
  * Reference: REQ-006/TECH_DESIGN.md#RulesEmitter
  */
@@ -33,15 +33,15 @@ class BaseRulesEmitter {
   // ----------------------------------------------------------
   // format() - 子类必须实现
   // ----------------------------------------------------------
-  format(registry, commands) {
+  format(registry, promptSummaries = []) {
     throw new Error('Not implemented: format()');
   }
 
   // ----------------------------------------------------------
   // emit() - 写入规则入口文件
   // ----------------------------------------------------------
-  async emit(registry, commands) {
-    const content = this.format(registry, commands);
+  async emit(registry, promptSummaries = []) {
+    const content = this.format(registry, promptSummaries);
     const outputPath = this.outputPath;
 
     // 安全检查: 输出大小限制

package/lib/compiler/rules-emitters/cursor-rules-emitter.js

@@ -23,9 +23,9 @@ class CursorRulesEmitter extends BaseRulesEmitter {
   // ----------------------------------------------------------
   // format() - 生成 MDC 格式内容
   // ----------------------------------------------------------
-  format(registry, commands) {
+  format(registry, promptSummaries = []) {
     const frontmatter = this.buildFrontmatter(registry);
-    const body = this.buildBody(registry, commands);
+    const body = this.buildBody(registry, promptSummaries);
 
     return `---
 ${frontmatter}---
@@ -49,7 +49,7 @@ ${body}`;
   // ----------------------------------------------------------
   // buildBody() - 构建 Markdown 正文
   // ----------------------------------------------------------
-  buildBody(registry, commands) {
+  buildBody(registry, promptSummaries = []) {
     const sections = [];
 
     // 标题
@@ -77,18 +77,13 @@ ${body}`;
       sections.push('');
     }
 
-    // 命令章节
-    sections.push('## Commands');
-    sections.push('');
-
-    if (commands && commands.length > 0) {
-      for (const cmd of commands) {
+    if (promptSummaries.length > 0) {
+      sections.push('## Commands');
+      sections.push('');
+      for (const cmd of promptSummaries) {
         sections.push(`- \`/${cmd.name}\`: ${cmd.description || 'No description'}`);
       }
       sections.push('');
-    } else {
-      sections.push('No commands available.');
-      sections.push('');
     }
 
     return sections.join('\n');

package/lib/compiler/rules-emitters/index.js

@@ -8,7 +8,6 @@
  * Reference: TECH_DESIGN.md#RulesEmitter
  */
 const { CursorRulesEmitter } = require('./cursor-rules-emitter');
-const { CodexRulesEmitter } = require('./codex-rules-emitter');
 const { QwenRulesEmitter } = require('./qwen-rules-emitter');
 const { AntigravityRulesEmitter } = require('./antigravity-rules-emitter');
 const { PLATFORMS } = require('../platforms');
@@ -18,7 +17,6 @@ const { PLATFORMS } = require('../platforms');
 // ============================================================
 const EMITTER_REGISTRY = {
   cursor: CursorRulesEmitter,
-  codex: CodexRulesEmitter,
   qwen: QwenRulesEmitter,
   antigravity: AntigravityRulesEmitter
 };
@@ -44,8 +42,13 @@ async function emitAllRules(registry, commands, options = {}) {
   const results = [];
 
   for (const platform of platforms) {
+    const EmitterClass = EMITTER_REGISTRY[platform];
+    if (!EmitterClass) {
+      continue;
+    }
+
     try {
-      const emitter = getRulesEmitter(platform);
+      const emitter = new EmitterClass();
       const result = await emitter.emit(registry, commands);
 
       // 处理多文件输出（Antigravity 分块）

package/lib/compiler/rules-emitters/qwen-rules-emitter.js

@@ -24,23 +24,22 @@ class QwenRulesEmitter extends BaseRulesEmitter {
   // ----------------------------------------------------------
   // format() - 生成 TOML 格式内容
   // ----------------------------------------------------------
-  format(registry, commands) {
-    const tomlObj = this.buildTomlObject(registry, commands);
+  format(registry, promptSummaries = []) {
+    const tomlObj = this.buildTomlObject(registry, promptSummaries);
     return TOML.stringify(tomlObj);
   }
 
   // ----------------------------------------------------------
   // buildTomlObject() - 构建 TOML 对象
   // ----------------------------------------------------------
-  buildTomlObject(registry, commands) {
+  buildTomlObject(registry, promptSummaries = []) {
     const obj = {
       skill: {
         name: 'cc-devflow',
         description: 'CC-DevFlow development workflow system',
         version: '1.0.0'
       },
-      skills: {},
-      commands: {}
+      skills: {}
     };
 
     // 添加技能
@@ -55,8 +54,9 @@ class QwenRulesEmitter extends BaseRulesEmitter {
     }
 
     // 添加命令
-    if (commands && commands.length > 0) {
-      for (const cmd of commands) {
+    if (promptSummaries.length > 0) {
+      obj.commands = {};
+      for (const cmd of promptSummaries) {
         obj.commands[cmd.name] = {
           description: cmd.description || ''
         };

package/lib/compiler/schemas.js

@@ -1,10 +1,10 @@
 /**
- * T023: Zod Schemas for Command Emitter
+ * T023: Zod Schemas for Skills-First Compiler
  *
  * Defines validation schemas for:
  * - PlaceholderSchema: {SCRIPT:*}, {AGENT_SCRIPT}, $ARGUMENTS
  * - FrontmatterSchema: YAML frontmatter fields
- * - CommandIRSchema: Intermediate Representation
+ * - PromptIRSchema: Intermediate representation
  * - ManifestEntrySchema: Single compilation record
  * - ManifestSchema: Complete manifest file
  */
@@ -95,15 +95,18 @@ const SourceSchema = z.object({
 });
 
 // ============================================================
-// CommandIRSchema - 命令中间表示
+// PromptIRSchema - 提示词中间表示
 // ============================================================
-const CommandIRSchema = z.object({
+const PromptIRSchema = z.object({
   source: SourceSchema,
   frontmatter: FrontmatterSchema,
   body: z.string(),
   placeholders: z.array(PlaceholderSchema)
 });
 
+// 保留旧导出名，避免外部调用方立即断裂。
+const CommandIRSchema = PromptIRSchema;
+
 // ============================================================
 // ManifestEntrySchema - 单条编译记录
 // ============================================================
@@ -138,6 +141,7 @@ module.exports = {
   AgentScriptsSchema,
   FrontmatterSchema,
   SourceSchema,
+  PromptIRSchema,
   CommandIRSchema,
   ManifestEntrySchema,
   ManifestSchema