cc-devflow 1.0.1

package/lib/compiler/schemas.js

@@ -0,0 +1,144 @@
+/**
+ * T023: Zod Schemas for Command Emitter
+ *
+ * Defines validation schemas for:
+ * - PlaceholderSchema: {SCRIPT:*}, {AGENT_SCRIPT}, $ARGUMENTS
+ * - FrontmatterSchema: YAML frontmatter fields
+ * - CommandIRSchema: Intermediate Representation
+ * - ManifestEntrySchema: Single compilation record
+ * - ManifestSchema: Complete manifest file
+ */
+const { z } = require('zod');
+
+// ============================================================
+// PlaceholderSchema - 占位符定义
+// ============================================================
+const PlaceholderSchema = z.object({
+  type: z.enum(['SCRIPT', 'TEMPLATE', 'GUIDE', 'AGENT_SCRIPT', 'ARGUMENTS']),
+  raw: z.string(),
+  alias: z.string().optional(),
+  position: z.object({
+    start: z.number(),
+    end: z.number()
+  })
+});
+
+// ============================================================
+// ScriptPathSchema - 脚本路径安全验证 (SECURITY FIX: FINDING-001)
+// ============================================================
+const ScriptPathSchema = z.string()
+  .min(1, 'Script path cannot be empty')
+  .refine(
+    (p) => !p.includes('../') && !p.startsWith('/'),
+    { message: 'Script path must not contain ../ or be absolute' }
+  )
+  .refine(
+    (p) => p.startsWith('.claude/scripts/'),
+    { message: 'Script path must be within .claude/scripts/' }
+  );
+
+// ============================================================
+// TemplatePathSchema - 模板路径验证
+// ============================================================
+const TemplatePathSchema = z.string()
+  .min(1, 'Template path cannot be empty')
+  .refine(
+    (p) => !p.includes('../') && !p.startsWith('/'),
+    { message: 'Template path must not contain ../ or be absolute' }
+  )
+  .refine(
+    (p) => p.startsWith('.claude/docs/templates/'),
+    { message: 'Template path must be within .claude/docs/templates/' }
+  );
+
+// ============================================================
+// GuidePathSchema - 指南路径验证
+// ============================================================
+const GuidePathSchema = z.string()
+  .min(1, 'Guide path cannot be empty')
+  .refine(
+    (p) => !p.includes('../') && !p.startsWith('/'),
+    { message: 'Guide path must not contain ../ or be absolute' }
+  )
+  .refine(
+    (p) => p.startsWith('.claude/docs/guides/'),
+    { message: 'Guide path must be within .claude/docs/guides/' }
+  );
+
+// ============================================================
+// AgentScriptsSchema - 跨平台脚本定义
+// ============================================================
+const AgentScriptsSchema = z.object({
+  sh: z.string().optional(),
+  ps: z.string().optional()
+}).optional();
+
+// ============================================================
+// FrontmatterSchema - YAML frontmatter 验证
+// ============================================================
+const FrontmatterSchema = z.object({
+  name: z.string().min(1, 'name is required'),
+  description: z.string().min(1, 'description is required'),
+  scripts: z.record(ScriptPathSchema).optional(),     // ✅ SECURITY: Use strict path validation
+  templates: z.record(TemplatePathSchema).optional(), // ✅ NEW: Template references
+  guides: z.record(GuidePathSchema).optional(),       // ✅ NEW: Guide references
+  agent_scripts: AgentScriptsSchema
+});
+
+// ============================================================
+// SourceSchema - 源文件信息
+// ============================================================
+const SourceSchema = z.object({
+  path: z.string(),
+  filename: z.string(),
+  hash: z.string()
+});
+
+// ============================================================
+// CommandIRSchema - 命令中间表示
+// ============================================================
+const CommandIRSchema = z.object({
+  source: SourceSchema,
+  frontmatter: FrontmatterSchema,
+  body: z.string(),
+  placeholders: z.array(PlaceholderSchema)
+});
+
+// ============================================================
+// ManifestEntrySchema - 单条编译记录
+// ============================================================
+const ManifestEntrySchema = z.object({
+  source: z.string(),
+  target: z.string(),
+  hash: z.string(),
+  timestamp: z.string().refine(
+    (val) => !isNaN(Date.parse(val)),
+    { message: 'timestamp must be a valid ISO 8601 date' }
+  ),
+  platform: z.enum(['codex', 'cursor', 'qwen', 'antigravity'])
+});
+
+// ============================================================
+// ManifestSchema - 完整 manifest 文件
+// ============================================================
+const ManifestSchema = z.object({
+  version: z.string(),
+  generatedAt: z.string().refine(
+    (val) => !isNaN(Date.parse(val)),
+    { message: 'generatedAt must be a valid ISO 8601 date' }
+  ),
+  entries: z.array(ManifestEntrySchema)
+});
+
+module.exports = {
+  PlaceholderSchema,
+  ScriptPathSchema,
+  TemplatePathSchema,
+  GuidePathSchema,
+  AgentScriptsSchema,
+  FrontmatterSchema,
+  SourceSchema,
+  CommandIRSchema,
+  ManifestEntrySchema,
+  ManifestSchema
+};

package/lib/compiler/skills-registry.js

@@ -0,0 +1,225 @@
+/**
+ * Skills Registry Generator V2
+ *
+ * 从 .claude/skills/ 生成 Skills Registry:
+ * - 扫描技能目录提取 SKILL.md frontmatter
+ * - 合并 skill-rules.json 触发规则
+ * - 输出标准化 SkillRegistry JSON
+ *
+ * Reference: REQ-006/data-model.md#SkillRegistry
+ */
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+// ============================================================
+// Constants
+// ============================================================
+const REGISTRY_VERSION = '1.0';
+const REGISTRY_OUTPUT_PATH = 'devflow/.generated/skills-registry.json';
+
+// ============================================================
+// generateSkillsRegistry - 保留向后兼容
+// ============================================================
+function generateSkillsRegistry(skillsDir) {
+  const registry = [];
+  const absoluteDir = path.resolve(skillsDir);
+
+  if (!fs.existsSync(absoluteDir)) {
+    return registry;
+  }
+
+  const entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('_')) {
+      continue;
+    }
+
+    const skillDir = path.join(absoluteDir, entry.name);
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+
+    if (!fs.existsSync(skillMdPath)) {
+      continue;
+    }
+
+    try {
+      const skillMdContent = fs.readFileSync(skillMdPath, 'utf8');
+      const parsed = matter(skillMdContent);
+
+      registry.push({
+        name: parsed.data.name || entry.name,
+        description: parsed.data.description || '',
+        type: parsed.data.type || 'utility',
+        path: skillDir,
+        triggers: []
+      });
+    } catch (error) {
+      console.warn(`Warning: Failed to parse skill ${entry.name}: ${error.message}`);
+    }
+  }
+
+  return registry;
+}
+
+// ============================================================
+// generateSkillsRegistryV2 - 合并 skill-rules.json + SKILL.md
+// ============================================================
+async function generateSkillsRegistryV2(skillsDir) {
+  const absoluteDir = path.resolve(skillsDir);
+  const skills = [];
+
+  // 读取顶层 skill-rules.json
+  const skillRulesPath = path.join(absoluteDir, 'skill-rules.json');
+  let skillRules = { skills: {} };
+
+  if (fs.existsSync(skillRulesPath)) {
+    try {
+      const content = fs.readFileSync(skillRulesPath, 'utf8');
+      skillRules = JSON.parse(content);
+    } catch (error) {
+      console.warn(`Warning: Failed to parse skill-rules.json: ${error.message}`);
+    }
+  }
+
+  // 扫描技能目录
+  if (!fs.existsSync(absoluteDir)) {
+    return createRegistry(skills);
+  }
+
+  const entries = fs.readdirSync(absoluteDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    // 跳过非目录和 _ 前缀目录
+    if (!entry.isDirectory() || entry.name.startsWith('_')) {
+      continue;
+    }
+
+    const skillDir = path.join(absoluteDir, entry.name);
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+
+    // 必须有 SKILL.md
+    if (!fs.existsSync(skillMdPath)) {
+      continue;
+    }
+
+    try {
+      const skillEntry = parseSkillEntry(entry.name, skillDir, skillMdPath, skillRules);
+      if (skillEntry) {
+        skills.push(skillEntry);
+      }
+    } catch (error) {
+      console.warn(`Warning: Failed to parse skill ${entry.name}: ${error.message}`);
+    }
+  }
+
+  return createRegistry(skills);
+}
+
+// ============================================================
+// parseSkillEntry - 解析单个技能
+// ============================================================
+function parseSkillEntry(skillName, _skillDir, skillMdPath, skillRules) {
+  const skillMdContent = fs.readFileSync(skillMdPath, 'utf8');
+  const parsed = matter(skillMdContent);
+
+  // 从 skill-rules.json 获取额外配置
+  const ruleConfig = skillRules.skills?.[skillName] || {};
+
+  // 合并 SKILL.md frontmatter 与 skill-rules.json
+  const entry = {
+    name: parsed.data.name || skillName,
+    description: parsed.data.description || ruleConfig.description || '',
+    type: ruleConfig.type || parsed.data.type || 'utility',
+    enforcement: ruleConfig.enforcement || 'suggest',
+    priority: ruleConfig.priority || 'medium',
+    skillPath: path.relative(process.cwd(), skillMdPath),
+    triggers: buildTriggers(ruleConfig)
+  };
+
+  return entry;
+}
+
+// ============================================================
+// buildTriggers - 构建触发器结构
+// ============================================================
+function buildTriggers(ruleConfig) {
+  const triggers = {};
+
+  // Prompt triggers
+  if (ruleConfig.promptTriggers) {
+    triggers.prompt = {
+      keywords: ruleConfig.promptTriggers.keywords || [],
+      intentPatterns: ruleConfig.promptTriggers.intentPatterns || []
+    };
+  }
+
+  // File triggers
+  if (ruleConfig.fileTriggers) {
+    triggers.file = {
+      pathPatterns: ruleConfig.fileTriggers.pathPatterns || [],
+      contentPatterns: ruleConfig.fileTriggers.contentPatterns || []
+    };
+  }
+
+  return triggers;
+}
+
+// ============================================================
+// createRegistry - 创建注册表结构
+// ============================================================
+function createRegistry(skills) {
+  return {
+    version: REGISTRY_VERSION,
+    generatedAt: new Date().toISOString(),
+    skills
+  };
+}
+
+// ============================================================
+// writeSkillsRegistry - 写入注册表文件
+// ============================================================
+async function writeSkillsRegistry(registry) {
+  const outputDir = path.dirname(REGISTRY_OUTPUT_PATH);
+
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(REGISTRY_OUTPUT_PATH, JSON.stringify(registry, null, 2));
+
+  return REGISTRY_OUTPUT_PATH;
+}
+
+// ============================================================
+// formatAsMarkdownTable - 转换为 Markdown 表格
+// ============================================================
+function formatAsMarkdownTable(registry) {
+  const skills = registry.skills || registry;
+
+  if (skills.length === 0) {
+    return 'No skills registered.';
+  }
+
+  const lines = [
+    '| Name | Description | Type | Enforcement | Priority |',
+    '|------|-------------|------|-------------|----------|'
+  ];
+
+  for (const skill of skills) {
+    lines.push(
+      `| ${skill.name} | ${skill.description} | ${skill.type} | ${skill.enforcement || 'suggest'} | ${skill.priority || 'medium'} |`
+    );
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateSkillsRegistry,
+  generateSkillsRegistryV2,
+  writeSkillsRegistry,
+  formatAsMarkdownTable,
+  REGISTRY_VERSION,
+  REGISTRY_OUTPUT_PATH
+};

package/lib/compiler/transformer.js

@@ -0,0 +1,236 @@
+/**
+ * T028: Transformer Module
+ *
+ * Transforms CommandIR for target platforms:
+ * - Expands {SCRIPT:alias} to "bash <path>"
+ * - Inlines {TEMPLATE:alias} with template file content
+ * - Inlines {GUIDE:alias} with guide file content
+ * - Expands {AGENT_SCRIPT} with platform-specific __AGENT__ substitution
+ * - Maps $ARGUMENTS to platform-specific syntax:
+ *   - codex/cursor: $ARGUMENTS (unchanged)
+ *   - qwen: {{args}}
+ *   - antigravity: [arguments]
+ * - Rewrites .claude/ paths to platform-specific paths via pathMap
+ */
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================
+// Platform Argument Mapping
+// ============================================================
+const ARGUMENT_MAPPING = {
+  codex: '$ARGUMENTS',
+  cursor: '$ARGUMENTS',
+  qwen: '{{args}}',
+  antigravity: '[arguments]'
+};
+
+// ============================================================
+// readFileContent - 读取文件内容，带缓存
+// ============================================================
+const fileCache = new Map();
+
+function readFileContent(filePath) {
+  // 检查缓存
+  if (fileCache.has(filePath)) {
+    return fileCache.get(filePath);
+  }
+
+  // 解析相对路径
+  const absolutePath = path.resolve(process.cwd(), filePath);
+
+  try {
+    if (!fs.existsSync(absolutePath)) {
+      console.warn(`Warning: File not found: ${absolutePath}`);
+      return `[File not found: ${filePath}]`;
+    }
+
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    fileCache.set(filePath, content);
+    return content;
+  } catch (error) {
+    console.warn(`Warning: Cannot read file: ${absolutePath} - ${error.message}`);
+    return `[Cannot read: ${filePath}]`;
+  }
+}
+
+// ============================================================
+// clearFileCache - 清除文件缓存（用于测试）
+// ============================================================
+function clearFileCache() {
+  fileCache.clear();
+}
+
+// ============================================================
+// expandScriptPlaceholders - 展开 {SCRIPT:alias} 占位符
+// 智能处理：如果前面已有 bash，则只替换路径；否则加 bash 前缀
+// ============================================================
+function expandScriptPlaceholders(content, scripts) {
+  if (!scripts) return content;
+
+  // 先处理已有 bash 前缀的情况: bash {SCRIPT:xxx} → bash path
+  content = content.replace(/bash\s+\{SCRIPT:([^}]+)\}/g, (match, alias) => {
+    const scriptPath = scripts[alias];
+    if (scriptPath) {
+      return `bash ${scriptPath}`;
+    }
+    return match;
+  });
+
+  // 再处理没有 bash 前缀的情况: {SCRIPT:xxx} → bash path
+  return content.replace(/\{SCRIPT:([^}]+)\}/g, (match, alias) => {
+    const scriptPath = scripts[alias];
+    if (scriptPath) {
+      return `bash ${scriptPath}`;
+    }
+    return match; // 保留原样，由 parser 阶段验证
+  });
+}
+
+// ============================================================
+// expandTemplatePlaceholders - 展开 {TEMPLATE:alias} 占位符
+// 将占位符替换为模板文件的实际内容
+// ============================================================
+function expandTemplatePlaceholders(content, templates, options = {}) {
+  if (!templates) return content;
+
+  const { inline = false } = options;
+
+  return content.replace(/\{TEMPLATE:([^}]+)\}/g, (match, alias) => {
+    const templatePath = templates[alias];
+    if (templatePath) {
+      if (inline) {
+        // 内联模式：读取文件内容并嵌入
+        const templateContent = readFileContent(templatePath);
+        return `\n<!-- Inlined from: ${templatePath} -->\n${templateContent}\n<!-- End of: ${templatePath} -->\n`;
+      }
+      // 默认模式：返回路径
+      return templatePath;
+    }
+    return match;
+  });
+}
+
+// ============================================================
+// expandGuidePlaceholders - 展开 {GUIDE:alias} 占位符
+// 将占位符替换为指南文件的实际内容
+// ============================================================
+function expandGuidePlaceholders(content, guides, options = {}) {
+  if (!guides) return content;
+
+  const { inline = false } = options;
+
+  return content.replace(/\{GUIDE:([^}]+)\}/g, (match, alias) => {
+    const guidePath = guides[alias];
+    if (guidePath) {
+      if (inline) {
+        // 内联模式：读取文件内容并嵌入
+        const guideContent = readFileContent(guidePath);
+        return `\n<!-- Inlined from: ${guidePath} -->\n${guideContent}\n<!-- End of: ${guidePath} -->\n`;
+      }
+      // 默认模式：返回路径
+      return guidePath;
+    }
+    return match;
+  });
+}
+
+// ============================================================
+// expandAgentScript - 展开 {AGENT_SCRIPT} 占位符
+// ============================================================
+function expandAgentScript(content, agentScripts, platform) {
+  if (!agentScripts || !agentScripts.sh) {
+    return content;
+  }
+
+  // 替换 __AGENT__ 为平台名称
+  const scriptContent = agentScripts.sh.replace(/__AGENT__/g, platform);
+
+  // 展开 {AGENT_SCRIPT}
+  return content.replace(/\{AGENT_SCRIPT\}/g, scriptContent);
+}
+
+// ============================================================
+// mapArguments - 映射 $ARGUMENTS 到平台语法
+// ============================================================
+function mapArguments(content, platform) {
+  const targetSyntax = ARGUMENT_MAPPING[platform];
+  if (!targetSyntax || targetSyntax === '$ARGUMENTS') {
+    return content;
+  }
+
+  return content.replace(/\$ARGUMENTS/g, targetSyntax);
+}
+
+// ============================================================
+// rewritePaths - 重写内容中的 .claude/ 路径为平台路径
+// ============================================================
+function rewritePaths(content, pathMap) {
+  if (!pathMap || Object.keys(pathMap).length === 0) {
+    return content;
+  }
+
+  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;
+}
+
+// ============================================================
+// transformForPlatform - 主转换函数
+// ============================================================
+function transformForPlatform(ir, platform, options = {}) {
+  let body = ir.body;
+
+  // 默认关闭内联，保持引用（仅替换为路径）
+  const inlineOptions = { inline: options.inline === true };
+  const pathMap = options.pathMap || {};
+
+  // 1. 展开 {SCRIPT:alias} - 第一轮
+  body = expandScriptPlaceholders(body, ir.frontmatter.scripts);
+
+  // 2. 展开 {TEMPLATE:alias} - 内联模板内容
+  body = expandTemplatePlaceholders(body, ir.frontmatter.templates, inlineOptions);
+
+  // 3. 展开 {GUIDE:alias} - 内联指南内容
+  body = expandGuidePlaceholders(body, ir.frontmatter.guides, inlineOptions);
+
+  // 4. 递归展开内联内容中的 {SCRIPT:alias}
+  // 模板/指南中可能也包含 {SCRIPT:xxx}，需要用原始 frontmatter 的 scripts 展开
+  body = expandScriptPlaceholders(body, ir.frontmatter.scripts);
+
+  // 5. 展开 {AGENT_SCRIPT}
+  body = expandAgentScript(body, ir.frontmatter.agent_scripts, platform);
+
+  // 6. 映射 $ARGUMENTS
+  body = mapArguments(body, platform);
+
+  // 7. 重写 .claude/ 路径为平台路径
+  body = rewritePaths(body, pathMap);
+
+  return {
+    body,
+    frontmatter: ir.frontmatter
+  };
+}
+
+module.exports = {
+  transformForPlatform,
+  expandScriptPlaceholders,
+  expandTemplatePlaceholders,
+  expandGuidePlaceholders,
+  expandAgentScript,
+  mapArguments,
+  rewritePaths,
+  readFileContent,
+  clearFileCache,
+  ARGUMENT_MAPPING
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "cc-devflow",
+    "version": "1.0.1",
+    "description": "DevFlow CLI tool",
+    "main": "bin/cc-devflow.js",
+    "bin": {
+        "cc-devflow": "bin/cc-devflow-cli.js"
+    },
+    "files": [
+        "bin/",
+        "lib/",
+        "config/",
+        ".claude/",
+        "docs/",
+        "README.md",
+        "README.zh-CN.md",
+        "CHANGELOG.md",
+        "LICENSE",
+        "package.json"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "license": "MIT",
+    "scripts": {
+        "prepublishOnly": "node scripts/validate-publish.js",
+        "test": "jest",
+        "start": "node bin/cc-devflow.js",
+        "adapt": "node bin/adapt.js",
+        "adapt:check": "node bin/adapt.js --check",
+        "adapt:skills": "node bin/adapt.js --skills",
+        "adapt:rules": "node bin/adapt.js --rules",
+        "adapt:codex": "node bin/adapt.js --platform codex",
+        "adapt:cursor": "node bin/adapt.js --platform cursor",
+        "adapt:qwen": "node bin/adapt.js --platform qwen",
+        "adapt:antigravity": "node bin/adapt.js --platform antigravity"
+    },
+    "dependencies": {
+        "gray-matter": "^4.0.3",
+        "@iarna/toml": "^2.2.5",
+        "js-yaml": "^4.1.0",
+        "zod": "^3.22.4"
+    },
+    "devDependencies": {
+        "jest": "^29.7.0"
+    },
+    "engines": {
+        "node": ">=18"
+    }
+}