cc-devflow 1.0.1

package/lib/adapters/registry.js

@@ -0,0 +1,153 @@
+const logger = require('./logger');
+
+class AdapterRegistry {
+    constructor() {
+        if (AdapterRegistry.instance) {
+            return AdapterRegistry.instance;
+        }
+        this._adapters = new Map();
+        this._config = { policies: { allow_shell: false, allow_network: false } };
+        this._cachedSelection = null;
+        AdapterRegistry.instance = this;
+    }
+
+    static getInstance() {
+        if (!AdapterRegistry.instance) {
+            AdapterRegistry.instance = new AdapterRegistry();
+        }
+        return AdapterRegistry.instance;
+    }
+
+    /**
+     * Reset singleton for testing.
+     */
+    reset() {
+        this._adapters.clear();
+        this._config = { policies: { allow_shell: false, allow_network: false } };
+        this._cachedSelection = null;
+    }
+
+    setConfig(config) {
+        const next = config && typeof config === 'object' ? config : {};
+        const policies = next.policies && typeof next.policies === 'object' ? next.policies : {};
+        this._config = {
+            ...next,
+            policies: {
+                allow_shell: false,
+                allow_network: false,
+                ...policies
+            }
+        };
+        this._cachedSelection = null;
+    }
+
+    getAdapter(name) {
+        return this._adapters.get(name);
+    }
+
+    register(adapter) {
+        // If it's a class, instantiate it? Or assume instance?
+        // Tech design says register(adapter). Let's support instances.
+        if (!adapter.name) throw new Error("Adapter must have a name");
+        this._adapters.set(adapter.name, adapter);
+        this._cachedSelection = null;
+    }
+
+    async detectEnvironment() {
+        // 1. Check override
+        if (this._config.preferred) {
+            const preferred = this._adapters.get(this._config.preferred);
+            if (preferred) {
+                this._cachedSelection = preferred;
+                return preferred;
+            }
+            logger.warn('Preferred adapter not found', { preferred: this._config.preferred });
+        }
+
+        // 2. Detection loop
+        // Sort adapters? For now iteration order.
+        // Spec-kit pattern: could iterate AGENT_CONFIG keys, but we need registered instances to detect?
+        // Or does registry instantiate them?
+        // Current task T007 implies "Implement Singleton, register(), and detectEnvironment()".
+        // We will iterate registered adapters.
+
+        if (this._cachedSelection) return this._cachedSelection;
+
+        const detected = [];
+        for (const adapter of this._adapters.values()) {
+            const isDetected = await adapter.detect();
+            if (isDetected) detected.push(adapter);
+        }
+
+        if (detected.length === 0) return null;
+
+        detected.sort((a, b) => {
+            const aPriority = typeof a.priority === 'number' ? a.priority : 0;
+            const bPriority = typeof b.priority === 'number' ? b.priority : 0;
+            if (aPriority !== bPriority) return bPriority - aPriority;
+            return String(a.name).localeCompare(String(b.name));
+        });
+
+        if (detected.length > 1) {
+            logger.warn('Multiple adapters detected', {
+                candidates: detected.map((a) => a.name),
+                selected: detected[0].name,
+                reason: 'priority/order'
+            });
+        }
+
+        this._cachedSelection = detected[0];
+        return detected[0];
+    }
+
+    /**
+     * Execute command via selected/specific adapter, strictly enforcing security policies.
+     */
+    async executeCommand(command, args = [], options = {}) {
+        // Mock selection for now, or use detected
+        let adapter = options.adapter ? this.getAdapter(options.adapter) : await this.detectEnvironment();
+        if (!adapter) throw new Error("No adapter selected/detected");
+
+        // Security Check
+        const policies = this._config.policies || {};
+        const adapterCapabilities = adapter.capabilities || [];
+        const requiredCapabilities = Array.isArray(options.requiredCapabilities)
+            ? options.requiredCapabilities
+            : [];
+
+        if (requiredCapabilities.includes('shell') && !policies.allow_shell) {
+            throw new Error('Capability denied: shell');
+        }
+
+        if (requiredCapabilities.includes('network') && !policies.allow_network) {
+            throw new Error('Capability denied: network');
+        }
+
+        for (const capability of requiredCapabilities) {
+            if (!adapterCapabilities.includes(capability)) {
+                throw new Error(`Adapter missing capability: ${capability}`);
+            }
+        }
+
+        return adapter.execute(command, args, options);
+    }
+}
+
+// spec-kit pattern: Metadata-driven configuration for supported agents
+// This can be used to auto-register or suggest adapters.
+AdapterRegistry.AGENT_CONFIG = {
+    "claude": {
+        "name": "Claude Code",
+        "folder": ".claude",
+        "install_url": "https://docs.anthropic.com/en/docs/claude-code/setup",
+        "requires_cli": true
+    },
+    "codex": {
+        "name": "Codex CLI",
+        "folder": ".codex",
+        "install_url": "https://github.com/openai/codex",
+        "requires_cli": true
+    }
+};
+
+module.exports = AdapterRegistry;

package/lib/compiler/CLAUDE.md

@@ -0,0 +1,92 @@
+# Command Emitter - Compiler Module Architecture
+
+## Purpose
+Multi-platform command compiler that transforms `.claude/commands/*.md` (SSOT) into native formats for Codex, Cursor, Qwen, and Antigravity platforms.
+
+## Architecture
+
+```
+lib/compiler/
+├── parser.js           # Parse .md files, extract frontmatter + detect placeholders
+├── transformer.js      # Expand {SCRIPT:*}, {AGENT_SCRIPT}, map $ARGUMENTS
+├── manifest.js         # Incremental compilation, drift detection
+├── schemas.js          # Zod validation schemas (CommandIR, Manifest)
+├── errors.js           # Custom error types (MissingFrontmatter, UnknownAlias, etc.)
+├── skills-registry.js  # Generate skills registry from .claude/skills/
+├── index.js            # Compiler entry point, orchestrates pipeline
+└── emitters/
+    ├── base-emitter.js       # Abstract base class
+    ├── codex-emitter.js      # .codex/prompts/*.md (YAML frontmatter)
+    ├── cursor-emitter.js     # .cursor/commands/*.md (pure Markdown)
+    ├── qwen-emitter.js       # .qwen/commands/*.toml (TOML format)
+    ├── antigravity-emitter.js # .agent/workflows/*.md (12K limit, auto-split)
+    └── index.js              # Emitter factory
+```
+
+## Data Flow
+
+```
+.claude/commands/*.md
+        │
+        ▼
+┌─────────────────┐
+│     Parser      │ gray-matter → CommandIR
+│  (parser.js)    │ - Extract frontmatter
+│                 │ - Detect placeholders
+│                 │ - Compute SHA-256 hash
+└────────┬────────┘
+         │ CommandIR[]
+         ▼
+┌─────────────────┐
+│   Transformer   │ Platform-specific transforms
+│(transformer.js) │ - {SCRIPT:alias} → "bash <path>"
+│                 │ - $ARGUMENTS → {{args}} / [arguments]
+│                 │ - {AGENT_SCRIPT} + __AGENT__ substitution
+└────────┬────────┘
+         │ TransformedContent
+         ▼
+┌─────────────────┐
+│    Emitters     │ Platform format + file write
+│ (emitters/*.js) │ - Codex: MD + YAML frontmatter
+│                 │ - Cursor: pure MD
+│                 │ - Qwen: TOML
+│                 │ - Antigravity: MD + YAML (12K limit)
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│    Manifest     │ devflow/.generated/manifest.json
+│ (manifest.js)   │ - Track source/target hashes
+│                 │ - Enable incremental compilation
+│                 │ - Detect drift
+└─────────────────┘
+```
+
+## CLI Usage
+
+```bash
+npm run adapt                       # Compile all platforms
+npm run adapt -- --platform codex   # Compile single platform
+npm run adapt -- --check            # Drift detection only
+npm run adapt -- --skills           # Generate skills-registry.json
+npm run adapt -- --verbose          # Detailed output
+```
+
+## Key Schemas
+
+- **CommandIR**: Intermediate representation after parsing
+- **ManifestEntry**: Single compilation record (source, target, hash, platform)
+- **Manifest**: Complete compilation history
+
+## Dependencies
+
+- `gray-matter`: Frontmatter parsing
+- `@iarna/toml`: TOML serialization (Qwen)
+- `js-yaml`: YAML serialization (Codex, Antigravity)
+- `zod`: Schema validation
+
+---
+
+**Created**: 2025-12-18
+**REQ**: REQ-005 (RM-007)
+**Version**: 1.0.0

package/lib/compiler/__tests__/drift.test.js

@@ -0,0 +1,215 @@
+/**
+ * T011: Drift Detection Tests
+ *
+ * 测试漂移检测:
+ * 1. 无漂移时返回 exit code 0
+ * 2. 手动修改时返回 exit code 2 并输出 diff
+ * 3. 目标文件缺失时返回 exit code 2
+ * 4. 规则入口文件包含在漂移检测中
+ *
+ * Reference: contracts/cli-spec.yaml#check_output
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+describe('Drift Detection', () => {
+  let tempDir;
+
+  beforeEach(async () => {
+    // 创建临时目录用于测试
+    tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'drift-test-'));
+  });
+
+  afterEach(async () => {
+    // 清理临时目录
+    if (tempDir) {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('checkDrift()', () => {
+    test('should return empty array when no drift', async () => {
+      const { checkDrift, hashContent } = require('../manifest');
+
+      // 创建测试文件
+      const targetPath = path.join(tempDir, 'test.md');
+      const content = 'test content';
+      await fs.promises.writeFile(targetPath, content);
+
+      // 创建 manifest 记录
+      const manifest = {
+        entries: [
+          {
+            source: 'source.md',
+            target: targetPath,
+            hash: hashContent(content), // 使用相同 hash
+            platform: 'codex'
+          }
+        ]
+      };
+
+      const drift = await checkDrift(manifest);
+
+      expect(drift).toEqual([]);
+    });
+
+    test('should detect drift when target file modified', async () => {
+      const { checkDrift, hashContent } = require('../manifest');
+
+      // 创建测试文件
+      const targetPath = path.join(tempDir, 'test.md');
+      const originalContent = 'original content';
+      const modifiedContent = 'modified content';
+
+      await fs.promises.writeFile(targetPath, modifiedContent);
+
+      // manifest 记录原始内容的 hash
+      const manifest = {
+        entries: [
+          {
+            source: 'source.md',
+            target: targetPath,
+            hash: hashContent(originalContent),
+            platform: 'codex'
+          }
+        ]
+      };
+
+      const drift = await checkDrift(manifest);
+
+      expect(drift.length).toBe(1);
+      expect(drift[0].issue).toBe('target file modified since last compile');
+    });
+
+    test('should detect drift when target file missing', async () => {
+      const { checkDrift, hashContent } = require('../manifest');
+
+      const missingPath = path.join(tempDir, 'nonexistent.md');
+
+      const manifest = {
+        entries: [
+          {
+            source: 'source.md',
+            target: missingPath,
+            hash: hashContent('some content'),
+            platform: 'codex'
+          }
+        ]
+      };
+
+      const drift = await checkDrift(manifest);
+
+      expect(drift.length).toBe(1);
+      expect(drift[0].issue).toBe('target file missing');
+    });
+
+    test('should return empty array for null manifest', async () => {
+      const { checkDrift } = require('../manifest');
+
+      const drift = await checkDrift(null);
+
+      expect(drift).toEqual([]);
+    });
+
+    test('should return empty array for manifest without entries', async () => {
+      const { checkDrift } = require('../manifest');
+
+      const drift = await checkDrift({ entries: null });
+
+      expect(drift).toEqual([]);
+    });
+  });
+
+  describe('Rules Entry Drift Detection', () => {
+    test('should include rules entry files in drift check', async () => {
+      // 规则入口文件应该和普通命令文件一样被检测
+      // 这需要在 Phase 4 扩展 checkDrift 函数
+
+      const { checkDrift, hashContent, addRulesEntry, createManifest } = require('../manifest');
+
+      const manifest = createManifest();
+
+      // 添加规则入口记录
+      const rulesPath = path.join(tempDir, 'devflow.mdc');
+      const originalContent = 'original rules';
+
+      addRulesEntry(manifest, 'cursor', {
+        path: rulesPath,
+        hash: hashContent(originalContent),
+        timestamp: new Date().toISOString()
+      });
+
+      // 创建被修改的文件
+      await fs.promises.writeFile(rulesPath, 'modified rules');
+
+      // 注意：当前 checkDrift 只检查 entries，不检查 rulesEntry
+      // 这个测试会在 Phase 4 (T025) 实现后通过
+
+      // 占位断言
+      expect(manifest.rulesEntry.cursor).toBeDefined();
+    });
+  });
+
+  describe('Exit Codes', () => {
+    test('should indicate exit code 0 for no drift', async () => {
+      const { checkDrift } = require('../manifest');
+
+      const drift = await checkDrift({ entries: [] });
+
+      // exit code 由调用方根据 drift 数组长度决定
+      const exitCode = drift.length > 0 ? 2 : 0;
+      expect(exitCode).toBe(0);
+    });
+
+    test('should indicate exit code 2 for drift detected', async () => {
+      const { checkDrift, hashContent } = require('../manifest');
+
+      const targetPath = path.join(tempDir, 'drifted.md');
+      await fs.promises.writeFile(targetPath, 'modified');
+
+      const manifest = {
+        entries: [
+          {
+            source: 'source.md',
+            target: targetPath,
+            hash: hashContent('original'),
+            platform: 'codex'
+          }
+        ]
+      };
+
+      const drift = await checkDrift(manifest);
+
+      const exitCode = drift.length > 0 ? 2 : 0;
+      expect(exitCode).toBe(2);
+    });
+  });
+
+  describe('Drift Report Format', () => {
+    test('should include source and target in drift report', async () => {
+      const { checkDrift, hashContent } = require('../manifest');
+
+      const targetPath = path.join(tempDir, 'report-test.md');
+      await fs.promises.writeFile(targetPath, 'modified');
+
+      const manifest = {
+        entries: [
+          {
+            source: 'original-source.md',
+            target: targetPath,
+            hash: hashContent('original content'),
+            platform: 'codex'
+          }
+        ]
+      };
+
+      const drift = await checkDrift(manifest);
+
+      expect(drift[0]).toHaveProperty('source', 'original-source.md');
+      expect(drift[0]).toHaveProperty('target', targetPath);
+      expect(drift[0]).toHaveProperty('issue');
+    });
+  });
+});

package/lib/compiler/__tests__/errors.test.js

@@ -0,0 +1,184 @@
+/**
+ * T010: Error Types Tests
+ * Tests for compiler error classes
+ * Expected: All tests FAIL (errors not implemented)
+ */
+
+// ============================================================
+// Error imports - will fail until lib/compiler/errors.js exists
+// ============================================================
+let errors;
+try {
+  errors = require('../errors.js');
+} catch (e) {
+  errors = null;
+}
+
+describe('Compiler Errors', () => {
+  beforeEach(() => {
+    if (!errors) {
+      throw new Error('errors.js not implemented');
+    }
+  });
+
+  // ----------------------------------------------------------
+  // CompilerError (Base Class) Tests
+  // ----------------------------------------------------------
+  describe('CompilerError', () => {
+    it('should be an instance of Error', () => {
+      const err = new errors.CompilerError('test message');
+      expect(err).toBeInstanceOf(Error);
+    });
+
+    it('should set name to CompilerError', () => {
+      const err = new errors.CompilerError('test');
+      expect(err.name).toBe('CompilerError');
+    });
+
+    it('should preserve message', () => {
+      const err = new errors.CompilerError('custom message');
+      expect(err.message).toBe('custom message');
+    });
+
+    it('should have proper stack trace', () => {
+      const err = new errors.CompilerError('test');
+      expect(err.stack).toBeDefined();
+      expect(err.stack).toContain('CompilerError');
+    });
+  });
+
+  // ----------------------------------------------------------
+  // MissingFrontmatterError Tests
+  // ----------------------------------------------------------
+  describe('MissingFrontmatterError', () => {
+    it('should extend CompilerError', () => {
+      const err = new errors.MissingFrontmatterError('test.md');
+      expect(err).toBeInstanceOf(errors.CompilerError);
+    });
+
+    it('should set name to MissingFrontmatterError', () => {
+      const err = new errors.MissingFrontmatterError('test.md');
+      expect(err.name).toBe('MissingFrontmatterError');
+    });
+
+    it('should include file path in message', () => {
+      const err = new errors.MissingFrontmatterError('/path/to/file.md');
+      expect(err.message).toContain('/path/to/file.md');
+    });
+
+    it('should store filePath property', () => {
+      const err = new errors.MissingFrontmatterError('/path/to/file.md');
+      expect(err.filePath).toBe('/path/to/file.md');
+    });
+  });
+
+  // ----------------------------------------------------------
+  // InvalidFrontmatterError Tests
+  // ----------------------------------------------------------
+  describe('InvalidFrontmatterError', () => {
+    it('should extend CompilerError', () => {
+      const err = new errors.InvalidFrontmatterError('test.md', 'missing name');
+      expect(err).toBeInstanceOf(errors.CompilerError);
+    });
+
+    it('should set name to InvalidFrontmatterError', () => {
+      const err = new errors.InvalidFrontmatterError('test.md', 'reason');
+      expect(err.name).toBe('InvalidFrontmatterError');
+    });
+
+    it('should include file path and reason in message', () => {
+      const err = new errors.InvalidFrontmatterError('/path/file.md', 'missing required field: name');
+      expect(err.message).toContain('/path/file.md');
+      expect(err.message).toContain('missing required field: name');
+    });
+
+    it('should store filePath and reason properties', () => {
+      const err = new errors.InvalidFrontmatterError('/path/file.md', 'bad format');
+      expect(err.filePath).toBe('/path/file.md');
+      expect(err.reason).toBe('bad format');
+    });
+  });
+
+  // ----------------------------------------------------------
+  // UnknownAliasError Tests
+  // ----------------------------------------------------------
+  describe('UnknownAliasError', () => {
+    it('should extend CompilerError', () => {
+      const err = new errors.UnknownAliasError('test.md', 'unknown_alias');
+      expect(err).toBeInstanceOf(errors.CompilerError);
+    });
+
+    it('should set name to UnknownAliasError', () => {
+      const err = new errors.UnknownAliasError('test.md', 'alias');
+      expect(err.name).toBe('UnknownAliasError');
+    });
+
+    it('should include file path and alias in message', () => {
+      const err = new errors.UnknownAliasError('/path/file.md', 'prereq');
+      expect(err.message).toContain('/path/file.md');
+      expect(err.message).toContain('prereq');
+    });
+
+    it('should store filePath and alias properties', () => {
+      const err = new errors.UnknownAliasError('/path/file.md', 'my_alias');
+      expect(err.filePath).toBe('/path/file.md');
+      expect(err.alias).toBe('my_alias');
+    });
+  });
+
+  // ----------------------------------------------------------
+  // WriteError Tests
+  // ----------------------------------------------------------
+  describe('WriteError', () => {
+    it('should extend CompilerError', () => {
+      const err = new errors.WriteError('test.md', 'permission denied');
+      expect(err).toBeInstanceOf(errors.CompilerError);
+    });
+
+    it('should set name to WriteError', () => {
+      const err = new errors.WriteError('test.md', 'error');
+      expect(err.name).toBe('WriteError');
+    });
+
+    it('should include file path and cause in message', () => {
+      const err = new errors.WriteError('/output/file.md', 'EACCES: permission denied');
+      expect(err.message).toContain('/output/file.md');
+      expect(err.message).toContain('EACCES');
+    });
+
+    it('should store filePath and cause properties', () => {
+      const err = new errors.WriteError('/output/file.md', 'disk full');
+      expect(err.filePath).toBe('/output/file.md');
+      expect(err.cause).toBe('disk full');
+    });
+  });
+
+  // ----------------------------------------------------------
+  // ContentTooLargeError Tests
+  // ----------------------------------------------------------
+  describe('ContentTooLargeError', () => {
+    it('should extend CompilerError', () => {
+      const err = new errors.ContentTooLargeError('test.md', 15000, 12000);
+      expect(err).toBeInstanceOf(errors.CompilerError);
+    });
+
+    it('should set name to ContentTooLargeError', () => {
+      const err = new errors.ContentTooLargeError('test.md', 15000, 12000);
+      expect(err.name).toBe('ContentTooLargeError');
+    });
+
+    it('should include file path, actual and limit in message', () => {
+      const err = new errors.ContentTooLargeError('/path/file.md', 15000, 12000);
+      expect(err.message).toContain('/path/file.md');
+      expect(err.message).toContain('15000');
+      expect(err.message).toContain('12000');
+    });
+
+    it('should store filePath, actualSize and limit properties', () => {
+      const err = new errors.ContentTooLargeError('/path/file.md', 15000, 12000);
+      expect(err.filePath).toBe('/path/file.md');
+      expect(err.actualSize).toBe(15000);
+      expect(err.limit).toBe(12000);
+    });
+  });
+});