@cregis-dev/cckit 0.4.0 → 0.5.0

package/src/steps/install-mcp.js

@@ -0,0 +1,70 @@
+/**
+ * Step: Install MCP configuration.
+ *
+ * Copies the bundled `.mcp.json` template to the project root.
+ * Uses `overwrite: false` to preserve user modifications.
+ */
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import fse from 'fs-extra'
+import { computeFileHash } from '../utils/fs.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const CCKIT_ROOT = path.resolve(__dirname, '../..')
+
+/**
+ * @param {object} opts
+ * @param {string} opts.targetDir - Project root
+ * @param {object} opts.mcpConfig - { template, target } from registry
+ * @param {boolean} opts.skip - Skip this step
+ * @param {boolean} [opts.forceOverwrite] - Overwrite existing file
+ * @param {object} logger
+ * @returns {Promise<import('../core/orchestrator.js').StepResult>}
+ */
+export async function installMcp(opts, logger) {
+  if (opts.skip) {
+    return { stepId: 'install-mcp', name: 'Install MCP Config', success: true, skipped: true, details: {} }
+  }
+
+  const srcPath = path.resolve(CCKIT_ROOT, opts.mcpConfig.template)
+  const destPath = path.join(opts.targetDir, opts.mcpConfig.target)
+
+  if (!await fse.pathExists(srcPath)) {
+    return {
+      stepId: 'install-mcp',
+      name: 'Install MCP Config',
+      success: false,
+      skipped: false,
+      details: {},
+      error: `MCP template not found at ${opts.mcpConfig.template}`,
+    }
+  }
+
+  // Don't overwrite user-modified file unless forced
+  if (!opts.forceOverwrite && await fse.pathExists(destPath)) {
+    const hash = await computeFileHash(destPath)
+    logger.info(`  ${opts.mcpConfig.target} already exists, skipping (use --force to overwrite)`)
+    return {
+      stepId: 'install-mcp',
+      name: 'Install MCP Config',
+      success: true,
+      skipped: false,
+      details: { target: opts.mcpConfig.target, hash, preserved: true },
+    }
+  }
+
+  await fse.ensureDir(path.dirname(destPath))
+  await fse.copy(srcPath, destPath)
+
+  const hash = await computeFileHash(destPath)
+  logger.debug(`Installed MCP config to ${opts.mcpConfig.target}`)
+
+  return {
+    stepId: 'install-mcp',
+    name: 'Install MCP Config',
+    success: true,
+    skipped: false,
+    details: { target: opts.mcpConfig.target, hash },
+  }
+}

package/src/steps/install-rules.js

@@ -0,0 +1,110 @@
+/**
+ * Step: Install ECC rules via git clone + copy.
+ *
+ * Clones the ECC repository to a user-level cache directory,
+ * then copies the `rules/` subtree to `.claude/rules/`.
+ * Cache is reused within 24 hours.
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import os from 'node:os'
+import path from 'node:path'
+import fse from 'fs-extra'
+import { listFiles } from '../utils/fs.js'
+
+const execFileAsync = promisify(execFile)
+
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+/**
+ * Clone a git repo to cache, reusing if fresh.
+ *
+ * @param {string} cacheKey - Cache directory name
+ * @param {string} repo - Git repository URL
+ * @param {boolean} forceRefresh - Force re-clone even if cache exists
+ * @param {object} [_deps] - Injectable dependencies
+ * @returns {Promise<string>} Absolute path to cached clone
+ */
+async function getCachedClone(cacheKey, repo, forceRefresh = false, _deps = {}) {
+  const { execFileFn = execFileAsync } = _deps
+  const cacheBase = path.join(os.homedir(), '.cckit', 'cache')
+  const cacheDir = path.join(cacheBase, cacheKey)
+
+  if (!forceRefresh && await fse.pathExists(cacheDir)) {
+    const stat = await fse.stat(cacheDir)
+    const ageMs = Date.now() - stat.mtimeMs
+    if (ageMs < CACHE_MAX_AGE_MS) {
+      return cacheDir
+    }
+  }
+
+  // Remove stale cache if exists
+  if (await fse.pathExists(cacheDir)) {
+    await fse.remove(cacheDir)
+  }
+
+  await fse.ensureDir(cacheBase)
+  await execFileFn('git', ['clone', '--depth', '1', repo, cacheDir])
+  return cacheDir
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.targetDir - Project root
+ * @param {object} opts.rulesConfig - { repo, rulesPath, target, cacheKey }
+ * @param {boolean} opts.skip - Skip this step
+ * @param {boolean} [opts.forceRefresh] - Force re-clone
+ * @param {object} logger
+ * @param {object} [_deps] - Injectable dependencies
+ * @returns {Promise<import('../core/orchestrator.js').StepResult>}
+ */
+export async function installRules(opts, logger, _deps = {}) {
+  if (opts.skip) {
+    return { stepId: 'install-rules', name: 'Install ECC Rules', success: true, skipped: true, details: {} }
+  }
+
+  const { repo, rulesPath, target, cacheKey } = opts.rulesConfig
+
+  try {
+    logger.info('  Cloning ECC rules repository...')
+    const cloneDir = await getCachedClone(cacheKey, repo, opts.forceRefresh, _deps)
+
+    const srcDir = path.join(cloneDir, rulesPath)
+    const destDir = path.join(opts.targetDir, target)
+
+    if (!await fse.pathExists(srcDir)) {
+      return {
+        stepId: 'install-rules',
+        name: 'Install ECC Rules',
+        success: false,
+        skipped: false,
+        details: {},
+        error: `Rules path "${rulesPath}" not found in cloned repository`,
+      }
+    }
+
+    await fse.ensureDir(destDir)
+    await fse.copy(srcDir, destDir, { overwrite: true })
+
+    const files = await listFiles(destDir)
+    logger.debug(`Copied ${files.length} rule files to ${target}`)
+
+    return {
+      stepId: 'install-rules',
+      name: 'Install ECC Rules',
+      success: true,
+      skipped: false,
+      details: { files: files.length, target },
+    }
+  } catch (err) {
+    return {
+      stepId: 'install-rules',
+      name: 'Install ECC Rules',
+      success: false,
+      skipped: false,
+      details: {},
+      error: err.message,
+    }
+  }
+}

package/src/steps/install-skills.js

@@ -0,0 +1,54 @@
+/**
+ * Step: Install skills via `npx skills add`.
+ *
+ * Iterates over skill entries from the registry and runs
+ * `npx skills add <repo> --skill <id>` for each.
+ * Individual failures do not abort the overall step.
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * @param {object} opts
+ * @param {string} opts.targetDir - Project root
+ * @param {Array<{id: string, repo: string, skill: string}>} opts.skills - Skill definitions
+ * @param {boolean} opts.skip - Skip this step
+ * @param {object} logger
+ * @param {object} [_deps] - Injectable dependencies
+ * @returns {Promise<import('../core/orchestrator.js').StepResult>}
+ */
+export async function installSkills(opts, logger, _deps = {}) {
+  if (opts.skip) {
+    return { stepId: 'install-skills', name: 'Install Skills', success: true, skipped: true, details: {} }
+  }
+
+  const { execFileFn = execFileAsync } = _deps
+  const results = []
+
+  for (const skillDef of opts.skills) {
+    logger.info(`  Installing skill: ${skillDef.id}`)
+    try {
+      await execFileFn('npx', ['skills', 'add', skillDef.repo, '--skill', skillDef.skill], {
+        cwd: opts.targetDir,
+        shell: true,
+      })
+      results.push({ id: skillDef.id, success: true })
+      logger.debug(`  Skill "${skillDef.id}" installed successfully`)
+    } catch (err) {
+      results.push({ id: skillDef.id, success: false, error: err.message })
+      logger.warn(`Skill "${skillDef.id}" failed: ${err.message}`)
+    }
+  }
+
+  const allSuccess = results.every(r => r.success)
+  return {
+    stepId: 'install-skills',
+    name: 'Install Skills',
+    success: allSuccess,
+    skipped: false,
+    details: { results },
+  }
+}

package/src/utils/fs.js

@@ -1,55 +1,33 @@
-import fse from 'fs-extra'
-import path from 'node:path'
-import crypto from 'node:crypto'
-import { glob } from 'glob'
-
-const INTERPOLATE_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.json', '.csv', '.txt'])
-
-export { INTERPOLATE_EXTENSIONS as TEXT_EXTENSIONS }
-
-export async function copyWithInterpolation(srcDir, destDir, variables) {
-  const files = await listFiles(srcDir)
-  let count = 0
-
-  for (const relPath of files) {
-    const srcFile = path.join(srcDir, relPath)
-    const destFile = path.join(destDir, relPath)
-    const ext = path.extname(relPath).toLowerCase()
-
-    await fse.ensureDir(path.dirname(destFile))
-
-    if (INTERPOLATE_EXTENSIONS.has(ext)) {
-      let content = await fse.readFile(srcFile, 'utf8')
-      content = interpolate(content, variables)
-      await fse.writeFile(destFile, content, 'utf8')
-    } else {
-      await fse.copy(srcFile, destFile)
-    }
-    count++
-  }
-
-  return count
-}
-
-export function interpolate(content, variables) {
-  return content.replace(/\{(\w+)\}/g, (match, key) => {
-    return key in variables ? variables[key] : match
-  })
-}
-
-export async function computeFileHash(filePath) {
-  const content = await fse.readFile(filePath)
-  const hash = crypto.createHash('sha256').update(content).digest('hex')
-  return `sha256:${hash}`
-}
-
-export async function listFiles(dir) {
-  const pattern = '**/*'
-  const files = await glob(pattern, {
-    cwd: dir,
-    nodir: true,
-    dot: true,
-    ignore: ['**/.git/**'],
-  })
-  return files
-}
+import fse from 'fs-extra'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { glob } from 'glob'
+
+/**
+ * Compute SHA256 hash of a file.
+ *
+ * @param {string} filePath - Absolute path to file
+ * @returns {Promise<string>} Hash in format "sha256:<hex>"
+ */
+export async function computeFileHash(filePath) {
+  const content = await fse.readFile(filePath)
+  const hash = crypto.createHash('sha256').update(content).digest('hex')
+  return `sha256:${hash}`
+}
+
+/**
+ * List all files in a directory recursively.
+ *
+ * @param {string} dir - Directory to scan
+ * @returns {Promise<string[]>} Relative file paths
+ */
+export async function listFiles(dir) {
+  const pattern = '**/*'
+  const files = await glob(pattern, {
+    cwd: dir,
+    nodir: true,
+    dot: true,
+    ignore: ['**/.git/**'],
+  })
+  return files
+}

package/src/utils/logger.js

@@ -1,16 +1,16 @@
-import chalk from 'chalk'
-
-export function createLogger(options = {}) {
-  const { write = (msg) => console.log(msg), debug: debugEnabled = false } = options
-
-  return {
-    info: (msg) => write(msg),
-    success: (msg) => write(chalk.green(`  \u2713 ${msg}`)),
-    error: (msg) => write(chalk.red(`  \u2717 ${msg}`)),
-    warn: (msg) => write(chalk.yellow(`  \u26A0 ${msg}`)),
-    debug: (msg) => { if (debugEnabled) write(chalk.gray(`  [debug] ${msg}`)) },
-    step: (current, total, msg) => write(chalk.blue(`  [${current}/${total}] ${msg}`)),
-    banner: (msg) => write(chalk.bold.green(`\n${msg}\n`)),
-    newline: () => write('')
-  }
-}
+import chalk from 'chalk'
+
+export function createLogger(options = {}) {
+  const { write = (msg) => console.log(msg), debug: debugEnabled = false } = options
+
+  return {
+    info: (msg) => write(msg),
+    success: (msg) => write(chalk.green(`  \u2713 ${msg}`)),
+    error: (msg) => write(chalk.red(`  \u2717 ${msg}`)),
+    warn: (msg) => write(chalk.yellow(`  \u26A0 ${msg}`)),
+    debug: (msg) => { if (debugEnabled) write(chalk.gray(`  [debug] ${msg}`)) },
+    step: (current, total, msg) => write(chalk.blue(`  [${current}/${total}] ${msg}`)),
+    banner: (msg) => write(chalk.bold.green(`\n${msg}\n`)),
+    newline: () => write('')
+  }
+}

package/src/utils/manifest.js

@@ -0,0 +1,99 @@
+/**
+ * Manifest utilities — read/write the cckit installation manifest.
+ *
+ * Manifest lives at `_bmad/_config/manifest.yaml` and tracks:
+ * - Installation config (user preferences)
+ * - Step execution results
+ * - File registry (SHA256 hashes for tracked files)
+ */
+
+import path from 'node:path'
+import fse from 'fs-extra'
+import YAML from 'yaml'
+
+export const MANIFEST_REL = path.join('_bmad', '_config', 'manifest.yaml')
+
+/**
+ * Read and parse the manifest from a project directory.
+ *
+ * @param {string} dir - Project root directory
+ * @returns {Promise<object>} Parsed manifest object
+ * @throws {Error} If manifest does not exist
+ */
+export async function readManifest(dir) {
+  const manifestPath = path.join(path.resolve(dir), MANIFEST_REL)
+  try {
+    const content = await fse.readFile(manifestPath, 'utf8')
+    return YAML.parse(content)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error('cckit is not installed. Run `cckit init` first.')
+    }
+    throw err
+  }
+}
+
+/**
+ * Write manifest to a project directory.
+ *
+ * @param {string} dir - Project root directory
+ * @param {object} manifest - Manifest data to write
+ * @returns {Promise<void>}
+ */
+export async function writeManifest(dir, manifest) {
+  const manifestPath = path.join(path.resolve(dir), MANIFEST_REL)
+  await fse.ensureDir(path.dirname(manifestPath))
+  await fse.writeFile(manifestPath, YAML.stringify(manifest), 'utf8')
+}
+
+/**
+ * Serialize step results for manifest storage.
+ *
+ * @param {Array<import('../core/orchestrator.js').StepResult>} steps
+ * @returns {Array<object>}
+ */
+export function serializeSteps(steps) {
+  return steps.map(s => ({
+    stepId: s.stepId,
+    success: s.success,
+    skipped: s.skipped || false,
+    ...(s.details ? { details: s.details } : {}),
+    ...(s.error ? { error: s.error } : {}),
+  }))
+}
+
+/**
+ * Build a new manifest from orchestration results.
+ *
+ * @param {object} params
+ * @param {object} params.config - Merged config
+ * @param {import('../core/orchestrator.js').RunReport} params.report - Orchestration report
+ * @param {string} params.version - cckit version
+ * @returns {object} Manifest object
+ */
+export function buildManifest({ config, report, version }) {
+  return {
+    cckit: {
+      version,
+      installedAt: new Date().toISOString(),
+      config: {
+        user_name: config.user_name,
+        communication_language: config.communication_language,
+        document_output_language: config.document_output_language,
+        languages: config.languages,
+      },
+      steps: serializeSteps(report.steps),
+      fileRegistry: report.fileRegistry,
+    }
+  }
+}
+
+/**
+ * Check if a manifest uses the legacy v1 format (modules-based).
+ *
+ * @param {object} manifest - Parsed manifest
+ * @returns {boolean}
+ */
+export function isLegacyManifest(manifest) {
+  return !!(manifest.cckit?.modules) && !manifest.cckit?.steps
+}

package/src/utils/prompt.js

@@ -0,0 +1,41 @@
+/**
+ * Readline utility for interactive prompts.
+ */
+
+import { createInterface } from 'node:readline'
+
+/**
+ * Prompt user for input via readline.
+ * Returns empty string if user presses Enter without typing.
+ *
+ * @param {string} question - Prompt text
+ * @param {object} [_deps] - Injectable dependencies for testing
+ * @param {object} [_deps.rl] - Mock readline interface
+ * @returns {Promise<string>} User input (trimmed)
+ */
+export function askQuestion(question, _deps = {}) {
+  const { rl: mockRl } = _deps
+
+  // If mock is provided, use it directly
+  if (mockRl) {
+    return new Promise((resolve) => {
+      mockRl.question(question, (answer) => {
+        mockRl.close()
+        resolve((answer == null ? '' : String(answer)).trim())
+      })
+    })
+  }
+
+  // Default: use real readline
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve((answer == null ? '' : String(answer)).trim())
+    })
+  })
+}

package/templates/mcp/claude-code/.mcp.json

@@ -1,35 +1,40 @@
-{
-  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/.mcp.schema.json",
-  "mcpServers": {
-    "cf-bindings": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://bindings.mcp.cloudflare.com/mcp"],
-      "description": "Workers Bindings: D1, R2, KV, Queues 资源管理"
-    },
-    "cf-observability": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://observability.mcp.cloudflare.com/mcp"],
-      "description": "Workers 日志分析与调试"
-    },
-    "cf-builds": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://builds.mcp.cloudflare.com/mcp"],
-      "description": "Workers 构建状态监控"
-    },
-    "cf-docs": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://docs.mcp.cloudflare.com/sse"],
-      "description": "Cloudflare 官方文档查询"
-    },
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp@latest"],
-      "description": "库文档实时查询（Hono, Zod, React Query, Zustand, Radix UI 等）"
-    },
-    "playwright": {
-      "command": "npx",
-      "args": ["-y", "@anthropic-ai/mcp-playwright@latest"],
-      "description": "Playwright 浏览器自动化，用于 E2E 测试和 UI 验证"
-    }
-  }
-}
+{
+  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/.mcp.schema.json",
+  "mcpServers": {
+    "cf-bindings": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://bindings.mcp.cloudflare.com/mcp"],
+      "description": "Workers Bindings: D1, R2, KV, Queues 资源管理",
+      "disabled": true
+    },
+    "cf-observability": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://observability.mcp.cloudflare.com/mcp"],
+      "description": "Workers 日志分析与调试",
+      "disabled": true
+    },
+    "cf-builds": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://builds.mcp.cloudflare.com/mcp"],
+      "description": "Workers 构建状态监控",
+      "disabled": true
+    },
+    "cf-docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://docs.mcp.cloudflare.com/sse"],
+      "description": "Cloudflare 官方文档查询",
+      "disabled": true
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "description": "库文档实时查询（Hono, Zod, React Query, Zustand, Radix UI 等）"
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-playwright@latest"],
+      "description": "Playwright 浏览器自动化，用于 E2E 测试和 UI 验证",
+      "disabled": true
+    }
+  }
+}

package/src/adapters/trae-adapter.js

@@ -1,90 +0,0 @@
-import path from 'node:path'
-
-/**
- * Detects whether markdown content already has YAML frontmatter.
- * Frontmatter starts with '---' (optionally preceded by whitespace).
- */
-export function hasFrontmatter(content) {
-  return content.trimStart().startsWith('---')
-}
-
-/**
- * Converts a rule file for Trae by prepending alwaysApply frontmatter.
- * Skips injection if frontmatter already exists.
- */
-export function convertRuleForTrae(content, filename) {
-  if (hasFrontmatter(content)) return content
-
-  const frontmatter = [
-    '---',
-    'alwaysApply: true',
-    '---',
-    ''
-  ].join('\n')
-
-  return frontmatter + content
-}
-
-/**
- * Extracts the text of the first markdown heading (# ...) from content.
- * Returns null if no heading is found.
- */
-function extractFirstHeading(content) {
-  const match = content.match(/^#\s+(.+)/m)
-  return match ? match[1].trim() : null
-}
-
-/**
- * Derives a short name from a filename by stripping the extension.
- */
-function deriveNameFromFilename(filename) {
-  return path.basename(filename, path.extname(filename))
-}
-
-/**
- * Converts an agent file for Trae by prepending name/description/disable-model-invocation frontmatter.
- */
-export function convertAgentForTrae(content, filename) {
-  const name = deriveNameFromFilename(filename)
-  const description = extractFirstHeading(content) || name
-
-  const frontmatter = [
-    '---',
-    `name: '${name}'`,
-    `description: '${description}'`,
-    'disable-model-invocation: true',
-    '---',
-    ''
-  ].join('\n')
-
-  return frontmatter + content
-}
-
-/**
- * Converts a command file for Trae by prepending name/description/disable-model-invocation frontmatter.
- */
-export function convertCommandForTrae(content, filename) {
-  const name = deriveNameFromFilename(filename)
-  const description = extractFirstHeading(content) || name
-
-  const frontmatter = [
-    '---',
-    `name: '${name}'`,
-    `description: '${description}'`,
-    'disable-model-invocation: true',
-    '---',
-    ''
-  ].join('\n')
-
-  return frontmatter + content
-}
-
-/**
- * Adapter lookup map used by the Installer.
- * Keys correspond to the `adapter` field in module definitions.
- */
-export const ADAPTERS = {
-  'trae-rules': convertRuleForTrae,
-  'trae-agents': convertAgentForTrae,
-  'trae-commands': convertCommandForTrae
-}