@cregis-dev/cckit 0.4.1 → 0.6.1

package/src/core/orchestrator.js

@@ -0,0 +1,79 @@
+/**
+ * Orchestrator — executes installation steps in sequence
+ * and collects results into a unified RunReport.
+ *
+ * Each step is independently retriable; the orchestrator
+ * never throws — it captures failures in step results.
+ */
+
+/**
+ * @typedef {object} StepResult
+ * @property {string} stepId - Stable identifier
+ * @property {string} name - Human-readable label
+ * @property {boolean} success
+ * @property {boolean} skipped
+ * @property {object} details - Step-specific metadata
+ * @property {string} [error] - Error message if !success
+ */
+
+/**
+ * @typedef {object} StepSpec
+ * @property {string} id
+ * @property {Function} fn - async (opts, logger, _deps?) => StepResult
+ * @property {object} opts - Step-specific options
+ */
+
+/**
+ * @typedef {object} RunReport
+ * @property {StepResult[]} steps
+ * @property {boolean} success - True if all non-skipped steps succeeded
+ * @property {object} fileRegistry - Hash registry (currently MCP only)
+ */
+
+/**
+ * Execute steps sequentially, collecting results.
+ *
+ * @param {StepSpec[]} steps - Ordered step specifications
+ * @param {object} logger - Logger instance
+ * @returns {Promise<RunReport>}
+ */
+export async function orchestrate(steps, logger) {
+  const results = []
+  const fileRegistry = {}
+
+  for (let i = 0; i < steps.length; i++) {
+    const { id, fn, opts } = steps[i]
+    logger.step(i + 1, steps.length, id)
+
+    try {
+      const result = await fn(opts, logger)
+      results.push(result)
+
+      // Collect file hashes from steps that produce them
+      if (result.details?.hash && result.details?.target) {
+        fileRegistry[result.details.target] = result.details.hash
+      }
+
+      if (result.skipped) {
+        logger.debug(`  Skipped: ${id}`)
+      } else if (result.success) {
+        logger.success(result.name || id)
+      } else {
+        logger.warn(`${result.name || id}: ${result.error || 'completed with errors'}`)
+      }
+    } catch (err) {
+      logger.error(`${id} threw unexpectedly: ${err.message}`)
+      results.push({
+        stepId: id,
+        name: id,
+        success: false,
+        skipped: false,
+        details: {},
+        error: err.message,
+      })
+    }
+  }
+
+  const success = results.every(r => r.skipped || r.success)
+  return { steps: results, success, fileRegistry }
+}

package/src/core/registry.js

@@ -6,6 +6,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 /**
  * Load and parse registry.json from disk.
+ *
  * @param {string} [customPath] - Override path to registry.json
  * @returns {Promise<object>} Parsed registry object
  */
@@ -16,60 +17,44 @@ export async function loadRegistry(customPath) {
 }
 
 /**
- * Get IDs of all modules that are default or required.
+ * Get IDs of all plugins marked as default.
+ *
  * @param {object} registry - Loaded registry object
- * @returns {string[]} Array of module IDs
+ * @returns {string[]} Array of plugin IDs
  */
-export function getDefaultModules(registry) {
-  return Object.entries(registry.modules)
-    .filter(([_, mod]) => mod.required || mod.default)
+export function getDefaultPlugins(registry) {
+  return Object.entries(registry.plugins || {})
+    .filter(([, def]) => def.default)
     .map(([id]) => id)
 }
 
 /**
- * Resolve a list of selected module IDs into an ordered array of module objects,
- * automatically including required modules and all transitive dependencies.
- * Dependencies appear before dependents in the result.
+ * Resolve requested plugin IDs to plugin definitions.
  *
- * @param {object} registry - Loaded registry object
- * @param {string[]} selectedIds - User-selected module IDs
- * @returns {Array<{id: string, [key: string]: any}>} Ordered module objects
- * @throws {Error} If any selected ID is not found in the registry
+ * @param {object} registry - Registry object
+ * @param {object} config - Merged config (uses config.plugins)
+ * @returns {Array<{id: string, def: object}>} Resolved plugin entries
  */
-export function resolveModules(registry, selectedIds) {
-  for (const id of selectedIds) {
-    if (!registry.modules[id]) {
-      throw new Error(`Unknown module: "${id}"`)
-    }
-  }
-
-  const requiredIds = Object.entries(registry.modules)
-    .filter(([_, mod]) => mod.required)
-    .map(([id]) => id)
-
-  const allIds = [...new Set([...requiredIds, ...selectedIds])]
-
-  const resolved = new Set()
-  const ordered = []
-
-  function visit(id) {
-    if (resolved.has(id)) return
-    const mod = registry.modules[id]
-    if (!mod) throw new Error(`Unknown module: "${id}"`)
-
-    if (mod.dependsOn) {
-      for (const depId of mod.dependsOn) {
-        visit(depId)
-      }
-    }
-
-    resolved.add(id)
-    ordered.push({ id, ...mod })
-  }
-
-  for (const id of allIds) {
-    visit(id)
-  }
+export function resolvePlugins(registry, config) {
+  const pluginIds = config.plugins === 'default'
+    ? getDefaultPlugins(registry)
+    : config.plugins === 'none'
+      ? []
+      : Array.isArray(config.plugins) ? config.plugins : []
+
+  return pluginIds
+    .map(id => ({ id, def: registry.plugins?.[id] }))
+    .filter(p => p.def)
+}
 
-  return ordered
+/**
+ * Resolve a model alias to a model ID using the registry's model map.
+ *
+ * @param {object} userSettings - registry.userSettings
+ * @param {string} [preferredAlias] - User-specified model alias (e.g. 'kimi')
+ * @returns {string} Resolved model ID (e.g. 'Kimi-K2.5')
+ */
+export function resolveModelId(userSettings = {}, preferredAlias) {
+  const alias = preferredAlias || userSettings.defaultModel || 'minimax'
+  return (userSettings.models || {})[alias] || alias
 }

package/src/steps/configure-user.js

@@ -0,0 +1,130 @@
+/**
+ * Step: Configure user-level settings in ~/.claude/settings.json.
+ *
+ * Writes API URL, API key (ANTHROPIC_AUTH_TOKEN), and model env vars.
+ * User-level settings are separate from project-level .claude/settings.json.
+ */
+
+import path from 'node:path'
+import os from 'node:os'
+import fse from 'fs-extra'
+import { askQuestion } from '../utils/prompt.js'
+
+/**
+ * @param {object} opts
+ * @param {string} opts.apiUrl - API base URL (default from registry)
+ * @param {string} [opts.apiKey] - API key from CLI flag
+ * @param {boolean} [opts.forceApiKey] - Force overwrite existing key
+ * @param {string} opts.modelId - Resolved model ID (e.g. "MiniMax-M2.5")
+ * @param {string[]} opts.modelEnvKeys - Env keys to set for model
+ * @param {boolean} [opts.yes] - Non-interactive mode
+ * @param {boolean} opts.skip - Skip this step
+ * @param {object} logger
+ * @param {object} [_deps] - Injectable dependencies for testing
+ * @returns {Promise<import('../core/orchestrator.js').StepResult>}
+ */
+export async function configureUser(opts, logger, _deps = {}) {
+  if (opts.skip) {
+    return { stepId: 'configure-user', name: 'Configure User Settings', success: true, skipped: true, details: {} }
+  }
+
+  const { askFn = askQuestion } = _deps
+  const settingsPath = _deps.settingsPath || path.join(os.homedir(), '.claude', 'settings.json')
+
+  // Read existing user settings
+  let existing = {}
+  try {
+    const raw = await fse.readFile(settingsPath, 'utf8')
+    existing = JSON.parse(raw)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // File doesn't exist — start fresh
+    } else {
+      // Other error (permission, corrupt, etc.) — log and start fresh
+      logger.warn(`Failed to read ${settingsPath}: ${err.message}, using defaults`)
+    }
+  }
+
+  const existingEnv = existing.env || {}
+
+  // 1. API URL — prompt for confirmation if not provided via CLI
+  let apiUrl = opts.apiUrl
+  if (!opts.yes && !opts.apiUrl) {
+    const input = await askFn('  Enter API URL (default: ' + opts.apiUrl + '): ')
+    if (input && input.trim()) {
+      apiUrl = input.trim()
+    }
+  }
+
+  // 2. API Key — resolve from CLI flag, readline, or existing
+  let apiKey = existingEnv.ANTHROPIC_AUTH_TOKEN || ''
+  const hasExistingKey = Boolean(apiKey)
+
+  if (opts.apiKey) {
+    // CLI flag provided — use it (force or new)
+    apiKey = opts.apiKey
+  } else if (!hasExistingKey || opts.forceApiKey) {
+    // No existing key, or force update — prompt via readline
+    if (!opts.yes) {
+      const prompt = hasExistingKey
+        ? '  API Key already exists. Enter new key to replace (empty to keep): '
+        : '  Enter your API Key (empty to skip): '
+      const input = await askFn(prompt)
+      if (input) {
+        apiKey = input
+      } else if (!hasExistingKey) {
+        logger.warn('No API Key provided. You can set it later with `cckit install --api-key <key>`')
+      }
+    }
+    // --yes mode without --api-key: skip prompt, keep existing
+  }
+
+  // 3. Model — prompt for confirmation
+  let modelId = opts.modelId
+  if (!opts.yes && !opts.model) {
+    const input = await askFn('  Enter model (default: ' + opts.modelId + '): ')
+    if (input && input.trim()) {
+      modelId = input.trim()
+    }
+  }
+
+  // 4. Model env vars
+  const modelEnvEntries = {}
+  for (const key of opts.modelEnvKeys) {
+    modelEnvEntries[key] = modelId
+  }
+
+  // 5. Merge and write
+  const merged = {
+    ...existing,
+    env: {
+      ...existingEnv,
+      ANTHROPIC_BASE_URL: apiUrl,
+      ...(apiKey ? { ANTHROPIC_AUTH_TOKEN: apiKey } : {}),
+      ...modelEnvEntries,
+    },
+  }
+
+  await fse.ensureDir(path.dirname(settingsPath))
+  await fse.writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8')
+
+  const maskedKey = apiKey ? `${apiKey.slice(0, 4)}...${apiKey.slice(-4)}` : '(not set)'
+
+  logger.info(`  API URL:   ${apiUrl}`)
+  logger.info(`  API Key:   ${maskedKey}`)
+  logger.info(`  Model:     ${modelId}`)
+  logger.info(`  Settings:  ${settingsPath}`)
+
+  return {
+    stepId: 'configure-user',
+    name: 'Configure User Settings',
+    success: true,
+    skipped: false,
+    details: {
+      apiUrl,
+      hasApiKey: Boolean(apiKey),
+      modelId,
+      settingsPath,
+    },
+  }
+}

package/src/steps/enable-plugins.js

@@ -0,0 +1,97 @@
+/**
+ * Step: Enable Claude Code plugins in `.claude/settings.json`.
+ *
+ * Writes `enabledPlugins`, `extraKnownMarketplaces`, and environment
+ * defaults via read-merge-write to preserve existing user settings.
+ */
+
+import path from 'node:path'
+import fse from 'fs-extra'
+
+const ENV_DEFAULTS = {
+  DISABLE_BUG_COMMAND: '1',
+  DISABLE_ERROR_REPORTING: '1',
+  DISABLE_TELEMETRY: '1',
+  MCP_TIMEOUT: '60000',
+  MAX_THINKING_TOKENS: '31999',
+  CLAUDE_CODE_MAX_OUTPUT_TOKENS: '64000',
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.targetDir - Project root
+ * @param {Array<{id: string, def: object}>} opts.plugins - Resolved plugins
+ * @param {boolean} opts.skip - Skip this step
+ * @param {object} logger
+ * @returns {Promise<import('../core/orchestrator.js').StepResult>}
+ */
+export async function enablePlugins(opts, logger) {
+  if (opts.skip) {
+    return { stepId: 'enable-plugins', name: 'Enable Plugins', success: true, skipped: true, details: {} }
+  }
+
+  const settingsPath = path.join(opts.targetDir, '.claude', 'settings.json')
+  let existing = {}
+
+  try {
+    const raw = await fse.readFile(settingsPath, 'utf8')
+    existing = JSON.parse(raw)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      // No existing settings — start fresh
+    } else {
+      logger.warn(`settings.json parse error, backing up and recreating: ${err.message}`)
+      const backupPath = `${settingsPath}.bak.${Date.now()}`
+      await fse.copy(settingsPath, backupPath)
+    }
+    existing = {}
+  }
+
+  const newPlugins = {}
+  const newMarketplaces = {}
+
+  for (const { id, def } of opts.plugins) {
+    const key = `${id}@${def.marketplace}`
+    newPlugins[key] = true
+
+    if (def.marketplaceSource && !newMarketplaces[def.marketplace]) {
+      newMarketplaces[def.marketplace] = { source: { ...def.marketplaceSource } }
+    }
+  }
+
+  const merged = {
+    ...existing,
+    env: {
+      ...(existing.env || {}),
+      ...ENV_DEFAULTS,
+    },
+    enabledPlugins: {
+      ...(existing.enabledPlugins || {}),
+      ...newPlugins,
+    },
+  }
+
+  if (Object.keys(newMarketplaces).length > 0) {
+    merged.extraKnownMarketplaces = {
+      ...(existing.extraKnownMarketplaces || {}),
+      ...newMarketplaces,
+    }
+  }
+
+  await fse.ensureDir(path.dirname(settingsPath))
+  await fse.writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf8')
+
+  const enabledKeys = Object.keys(newPlugins)
+  logger.debug(`Enabled ${enabledKeys.length} plugins in settings.json`)
+
+  return {
+    stepId: 'enable-plugins',
+    name: 'Enable Plugins',
+    success: true,
+    skipped: false,
+    details: {
+      enabledKeys,
+      marketplaces: Object.keys(newMarketplaces),
+    },
+  }
+}

package/src/steps/install-bmad.js

@@ -0,0 +1,85 @@
+/**
+ * Step: Install BMAD methodology via `npx bmad-method install`.
+ *
+ * Spawns the BMAD CLI as a child process with stdio inherited
+ * so the user sees real-time output.
+ */
+
+import { spawn } from 'node:child_process'
+
+/**
+ * @param {object} opts
+ * @param {string} opts.targetDir - Project root
+ * @param {object} opts.bmadConfig - { command, args, outputDirs } from registry
+ * @param {object} [opts.config] - User config (communication_language, document_output_language)
+ * @param {boolean} opts.skip - Skip this step
+ * @param {object} logger
+ * @param {object} [_deps] - Injectable dependencies for testing
+ * @returns {Promise<import('../core/orchestrator.js').StepResult>}
+ */
+export async function installBmad(opts, logger, _deps = {}) {
+  if (opts.skip) {
+    return { stepId: 'install-bmad', name: 'Install BMAD', success: true, skipped: true, details: {} }
+  }
+
+  const { spawnFn = spawn } = _deps
+  const { command, args: baseArgs } = opts.bmadConfig
+
+  // Override language args from user config if provided
+  const args = [...baseArgs]
+  if (opts.config) {
+    const langMap = {
+      '--communication-language': opts.config.communication_language,
+      '--document-output-language': opts.config.document_output_language,
+    }
+    for (const [flag, value] of Object.entries(langMap)) {
+      if (!value) continue
+      const idx = args.indexOf(flag)
+      if (idx !== -1) {
+        args[idx + 1] = value
+      }
+    }
+  }
+
+  logger.info(`  Running: ${command} ${args.join(' ')}`)
+
+  return new Promise((resolve) => {
+    const child = spawnFn(command, args, {
+      cwd: opts.targetDir,
+      stdio: 'inherit',
+      shell: true,
+    })
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({
+          stepId: 'install-bmad',
+          name: 'Install BMAD',
+          success: true,
+          skipped: false,
+          details: { outputDirs: opts.bmadConfig.outputDirs },
+        })
+      } else {
+        resolve({
+          stepId: 'install-bmad',
+          name: 'Install BMAD',
+          success: false,
+          skipped: false,
+          details: {},
+          error: `npx bmad-method exited with code ${code}`,
+        })
+      }
+    })
+
+    child.on('error', (err) => {
+      resolve({
+        stepId: 'install-bmad',
+        name: 'Install BMAD',
+        success: false,
+        skipped: false,
+        details: {},
+        error: `Failed to spawn: ${err.message}`,
+      })
+    })
+  })
+}

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,69 @@
+/**
+ * Step: Install ECC rules via template copy.
+ *
+ * Copies the bundled rules template to `.claude/rules/`.
+ */
+
+import path from 'node:path'
+import fse from 'fs-extra'
+import { listFiles } from '../utils/fs.js'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/**
+ * @param {object} opts
+ * @param {string} opts.targetDir - Project root
+ * @param {object} opts.rulesConfig - { template, target }
+ * @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 installRules(opts, logger, _deps = {}) {
+  if (opts.skip) {
+    return { stepId: 'install-rules', name: 'Install ECC Rules', success: true, skipped: true, details: {} }
+  }
+
+  const { template, target } = opts.rulesConfig
+
+  try {
+    // Resolve template path - use absolute path if provided, otherwise relative to cckit package
+    const templatePath = path.resolve(__dirname, '../../', template)
+    const destDir = path.join(opts.targetDir, target)
+
+    if (!await fse.pathExists(templatePath)) {
+      return {
+        stepId: 'install-rules',
+        name: 'Install ECC Rules',
+        success: false,
+        skipped: false,
+        details: {},
+        error: `Rules template not found: ${templatePath}`,
+      }
+    }
+
+    await fse.ensureDir(destDir)
+    await fse.copy(templatePath, 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 },
+  }
+}