@cregis-dev/cckit 0.4.0 → 0.5.0

package/src/commands/add.js

@@ -1,192 +0,0 @@
-/**
- * add command — install a third-party plugin from a GitHub URL.
- *
- * Flow:
- * 1. Validate cckit is installed (manifest exists)
- * 2. Validate URL is GitHub
- * 3. Clone repo to temp dir (depth 1)
- * 4. Read and validate cckit-plugin.json
- * 5. Install plugin content per IDE config
- * 6. Update manifest with new plugin entry
- * 7. Cleanup temp dir
- */
-
-import path from 'node:path'
-import fse from 'fs-extra'
-import os from 'node:os'
-import YAML from 'yaml'
-import { execFile as execFileCb } from 'node:child_process'
-import { promisify } from 'node:util'
-import { mkdtemp } from 'node:fs/promises'
-import { createLogger } from '../utils/logger.js'
-import { installForTrae } from '../core/plugin-installer.js'
-
-const execFile = promisify(execFileCb)
-
-const GITHUB_URL_RE = /^https?:\/\/github\.com\/[\w.-]+\/[\w.-]+/
-
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-/**
- * Extract repository name from a GitHub URL.
- * @param {string} url - GitHub URL
- * @returns {string} Repo name (last path segment, without .git)
- */
-function extractRepoName(url) {
-  const cleaned = url.replace(/\.git$/, '').replace(/\/+$/, '')
-  const segments = cleaned.split('/')
-  return segments[segments.length - 1]
-}
-
-/**
- * Validate cckit-plugin.json manifest fields.
- * @param {object} manifest - Parsed plugin manifest
- * @throws {Error} if required fields are missing
- */
-function validatePluginManifest(manifest) {
-  if (!manifest || typeof manifest !== 'object') {
-    throw new Error('cckit-plugin.json must be a valid JSON object')
-  }
-  if (!manifest.name || typeof manifest.name !== 'string') {
-    throw new Error('cckit-plugin.json must have a "name" field (string)')
-  }
-  if (!manifest.version || typeof manifest.version !== 'string') {
-    throw new Error('cckit-plugin.json must have a "version" field (string)')
-  }
-  if (!manifest.contents || typeof manifest.contents !== 'object') {
-    throw new Error('cckit-plugin.json must have a "contents" field (object)')
-  }
-}
-
-/**
- * Default git clone implementation (depth 1).
- * @param {string} url - Repository URL
- * @param {string} dest - Destination directory
- */
-async function defaultCloneRepo(url, dest) {
-  await execFile('git', ['clone', '--depth', '1', url, dest])
-}
-
-/**
- * Install a plugin for Trae IDE.
- * Reuses the installForTrae function from plugin-installer, but wraps
- * the cloned repo data into the format it expects.
- * @param {string} pluginDir - Clone directory root
- * @param {object} pluginManifest - Parsed cckit-plugin.json
- * @param {string} pluginId - Plugin identifier
- * @param {string} targetDir - Project root
- * @param {object} variables - Interpolation variables
- * @param {object} logger - Logger instance
- */
-async function installPluginForTrae(pluginDir, pluginManifest, pluginId, targetDir, variables, logger) {
-  // Build a plugin entry compatible with installForTrae's expected format
-  const pluginEntry = {
-    id: pluginId,
-    def: pluginManifest,
-    templateDir: pluginDir,
-  }
-
-  return installForTrae([pluginEntry], targetDir, variables, logger)
-}
-
-// ─── Main Command ────────────────────────────────────────────────────────────
-
-/**
- * Run the `add` command — install a third-party plugin from GitHub.
- *
- * @param {object} opts
- * @param {string} opts.url - GitHub repository URL
- * @param {string} [opts.dir] - Target project directory
- * @param {boolean} [opts.debug] - Enable debug output
- * @param {object} [opts._deps] - Dependency injection for testing
- * @returns {Promise<{ pluginId: string, installed: boolean }>}
- */
-export async function runAdd(opts = {}) {
-  const { url, dir = process.cwd(), debug = false, _deps = {} } = opts
-  const logger = _deps.logger || createLogger({ debug })
-  const cloneRepo = _deps.cloneRepo || defaultCloneRepo
-
-  // 1. Validate cckit is installed (manifest exists)
-  const manifestPath = path.join(dir, '_bmad', '_config', 'manifest.yaml')
-  if (!(await fse.pathExists(manifestPath))) {
-    throw new Error('cckit is not installed in this directory. Run "cckit init" first.')
-  }
-
-  // 2. Validate URL is GitHub
-  if (!GITHUB_URL_RE.test(url)) {
-    throw new Error('Only GitHub URLs are supported. Please provide a valid GitHub repository URL.')
-  }
-
-  // 3. Clone repo to temp dir
-  const tmpBase = await mkdtemp(path.join(os.tmpdir(), 'cckit-add-'))
-  const repoName = extractRepoName(url)
-  const cloneDir = path.join(tmpBase, repoName)
-
-  try {
-    logger.step(1, 4, 'Cloning repository...')
-    await cloneRepo(url, cloneDir)
-
-    // 4. Read and validate cckit-plugin.json
-    const pluginJsonPath = path.join(cloneDir, 'cckit-plugin.json')
-    if (!(await fse.pathExists(pluginJsonPath))) {
-      throw new Error(
-        `Repository does not contain a cckit-plugin.json file. ` +
-        `This is required for cckit plugins.`
-      )
-    }
-
-    const pluginManifest = await fse.readJson(pluginJsonPath)
-    validatePluginManifest(pluginManifest)
-
-    const pluginId = pluginManifest.name
-
-    // Read project manifest to get IDE config
-    const manifest = YAML.parse(await fse.readFile(manifestPath, 'utf8'))
-    const config = manifest.cckit?.config || {}
-    const ides = config.ides || ['claude-code']
-
-    // Build interpolation variables
-    const variables = {
-      user_name: config.user_name || '',
-      communication_language: config.communication_language || 'English',
-      document_output_language: config.document_output_language || 'English',
-      languages: (config.languages || []).join(', '),
-      'project-root': '.',
-    }
-
-    // 5. Install plugin content for Trae
-    logger.step(2, 4, `Installing plugin "${pluginId}"...`)
-
-    if (ides.includes('trae')) {
-      logger.debug('Installing for Trae...')
-      await installPluginForTrae(cloneDir, pluginManifest, pluginId, dir, variables, logger)
-    }
-
-    // 6. Update manifest with new plugin entry
-    logger.step(3, 4, 'Updating manifest...')
-    const pluginEntry = {
-      id: pluginId,
-      version: pluginManifest.version,
-      source: url,
-    }
-
-    const existingPlugins = manifest.cckit.plugins || []
-    const updatedManifest = {
-      ...manifest,
-      cckit: {
-        ...manifest.cckit,
-        plugins: [...existingPlugins, pluginEntry],
-      },
-    }
-
-    await fse.writeFile(manifestPath, YAML.stringify(updatedManifest), 'utf8')
-
-    logger.step(4, 4, 'Done!')
-    logger.success(`Plugin "${pluginId}" (v${pluginManifest.version}) installed successfully.`)
-
-    return { pluginId, installed: true }
-  } finally {
-    // 7. Cleanup temp dir
-    await fse.remove(tmpBase).catch(() => {})
-  }
-}

package/src/commands/sync.js

@@ -1,325 +0,0 @@
-/**
- * `cckit sync` command — pull upstream BMAD/ECC/ext-skills content into templates/.
- *
- * Workflow:
- *   1. Validate --source parameter
- *   2. Snapshot current templates/ directory
- *   3. If --dry-run: report intended operations and exit
- *   4. Fetch upstream sources (BMAD via npx, ECC via git clone, ext-skills via git clone)
- *   5. Apply path mappings to copy files into templates/
- *   6. Post-snapshot and compute diff
- *   7. Update registry.json upstream metadata
- *   8. Print diff report
- */
-
-import path from 'node:path'
-import fse from 'fs-extra'
-import { fileURLToPath } from 'node:url'
-import { createLogger } from '../utils/logger.js'
-import { loadRegistry } from '../core/registry.js'
-import { snapshotDir, computeDiff } from '../core/differ.js'
-import { shouldTemplatize, templatizeConfigYaml } from '../core/templatize.js'
-import {
-  fetchBmad,
-  fetchEcc,
-  fetchPlugins,
-  fetchExtSkills,
-  buildPluginMappings,
-  buildExtSkillMappings,
-  applyMappings,
-  createTempDir,
-  BMAD_PATH_MAPPINGS,
-  ECC_PATH_MAPPINGS,
-  ECC_REPO_URL,
-} from '../core/upstream.js'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const TEMPLATES_DIR = path.resolve(__dirname, '../../templates')
-const REGISTRY_PATH = path.resolve(__dirname, '../../registry.json')
-
-const VALID_SOURCES = ['bmad', 'ecc', 'plugins', 'ext-skills', 'all']
-
-/**
- * Run the sync command.
- *
- * @param {object} opts - Command options
- * @param {string} [opts.source='all'] - Source to sync: bmad, ecc, plugins, ext-skills, or all
- * @param {boolean} [opts.dryRun=false] - Preview mode
- * @param {boolean} [opts.debug=false] - Debug output
- * @param {object} [opts._deps] - Injectable dependencies for testing
- */
-export async function runSync(opts = {}) {
-  const {
-    source = 'all',
-    dryRun = false,
-    debug = false,
-    _deps = {},
-  } = opts
-
-  const logger = _deps.logger || createLogger({ debug })
-  const templatesDir = _deps.templatesDir || TEMPLATES_DIR
-  const registryPath = _deps.registryPath || REGISTRY_PATH
-  const fetchBmadFn = _deps.fetchBmad || fetchBmad
-  const fetchEccFn = _deps.fetchEcc || fetchEcc
-  const fetchPluginsFn = _deps.fetchPlugins || fetchPlugins
-  const fetchExtSkillsFn = _deps.fetchExtSkills || fetchExtSkills
-
-  // Step 1: Validate source
-  if (!VALID_SOURCES.includes(source)) {
-    throw new Error(`Invalid source "${source}". Must be one of: ${VALID_SOURCES.join(', ')}`)
-  }
-
-  const syncBmad = source === 'bmad' || source === 'all'
-  const syncEcc = source === 'ecc' || source === 'all'
-  const syncPlugins = source === 'plugins' || source === 'all'
-  const syncExtSkills = source === 'ext-skills' || source === 'all'
-
-  logger.banner('cckit sync')
-  logger.info(`  Source: ${source}`)
-
-  // Step 2: Snapshot before
-  logger.debug('Snapshotting templates directory...')
-  const beforeSnapshot = await snapshotDir(templatesDir)
-  logger.debug(`  Before snapshot: ${beforeSnapshot.size} files`)
-
-  // Step 3: Dry-run check
-  if (dryRun) {
-    logger.info('')
-    logger.info('  Dry-run mode — no changes will be applied.')
-    logger.info('')
-    if (syncBmad) {
-      logger.info('  Would sync BMAD:')
-      for (const m of BMAD_PATH_MAPPINGS) {
-        logger.info(`    ${m.src} → templates/${m.dest}`)
-      }
-    }
-    if (syncEcc) {
-      logger.info('  Would sync ECC:')
-      for (const m of ECC_PATH_MAPPINGS) {
-        logger.info(`    ${m.src} → templates/${m.dest}`)
-      }
-    }
-    if (syncPlugins) {
-      const registry = await loadRegistry(registryPath)
-      const pluginMappings = buildPluginMappings(registry)
-      logger.info('  Would sync Plugins:')
-      for (const m of pluginMappings) {
-        logger.info(`    ${m.src} → templates/${m.dest}`)
-      }
-    }
-    if (syncExtSkills) {
-      const registry = await loadRegistry(registryPath)
-      const extSkillMappings = buildExtSkillMappings(registry)
-      logger.info('  Would sync Ext-skills:')
-      for (const m of extSkillMappings) {
-        logger.info(`    ${m.src} → templates/${m.dest}`)
-      }
-    }
-    return { dryRun: true }
-  }
-
-  // Step 4 & 5: Fetch and apply
-  let tmpDir
-  const upstreamMeta = {}
-
-  try {
-    tmpDir = await createTempDir('cckit-sync')
-    logger.debug(`Temp directory: ${tmpDir}`)
-
-    // Pre-check plugins and ext-skills upstream availability to compute accurate step count
-    let pluginsAvailable = false
-    if (syncPlugins) {
-      const reg = await loadRegistry(registryPath)
-      pluginsAvailable = Boolean(reg.upstream?.plugins?.repo)
-      if (!pluginsAvailable) {
-        logger.warn('No plugins upstream configured in registry.json, skipping plugins sync')
-      }
-    }
-
-    let extSkillsAvailable = false
-    if (syncExtSkills) {
-      const reg = await loadRegistry(registryPath)
-      const extEntries = reg.upstream?.['ext-skills'] || {}
-      extSkillsAvailable = Object.keys(extEntries).length > 0
-      if (!extSkillsAvailable) {
-        logger.warn('No ext-skills upstream configured in registry.json, skipping ext-skills sync')
-      }
-    }
-
-    const totalSteps = [syncBmad, syncEcc, pluginsAvailable, extSkillsAvailable].filter(Boolean).length
-    let currentStep = 0
-
-    if (syncBmad) {
-      currentStep++
-      logger.step(currentStep, totalSteps, 'Fetching BMAD...')
-      const bmad = await fetchBmadFn({ tmpDir, logger })
-      upstreamMeta.bmad = { version: bmad.version }
-
-      const postProcess = (content, relPath) => {
-        if (shouldTemplatize(relPath)) {
-          return templatizeConfigYaml(content)
-        }
-        return content
-      }
-
-      const fileCount = await applyMappings({
-        srcBase: bmad.dir,
-        destBase: templatesDir,
-        mappings: BMAD_PATH_MAPPINGS,
-        postProcess,
-        logger,
-      })
-      logger.success(`BMAD: ${fileCount} files synced`)
-    }
-
-    if (syncEcc) {
-      currentStep++
-      logger.step(currentStep, totalSteps, 'Fetching ECC...')
-      const ecc = await fetchEccFn({ tmpDir, logger })
-      upstreamMeta.ecc = { sha: ecc.sha }
-
-      const fileCount = await applyMappings({
-        srcBase: ecc.dir,
-        destBase: templatesDir,
-        mappings: ECC_PATH_MAPPINGS,
-        logger,
-      })
-      logger.success(`ECC: ${fileCount} files synced`)
-    }
-
-    if (pluginsAvailable) {
-      currentStep++
-      logger.step(currentStep, totalSteps, 'Fetching Plugins...')
-
-      const registry = await loadRegistry(registryPath)
-      const plugins = await fetchPluginsFn({ tmpDir, logger, registry })
-      upstreamMeta.plugins = { sha: plugins.sha }
-
-      const pluginMappings = buildPluginMappings(registry)
-      const fileCount = await applyMappings({
-        srcBase: plugins.dir,
-        destBase: templatesDir,
-        mappings: pluginMappings,
-        logger,
-      })
-      logger.success(`Plugins: ${fileCount} files synced`)
-    }
-
-    if (extSkillsAvailable) {
-      currentStep++
-      logger.step(currentStep, totalSteps, 'Fetching Ext-skills...')
-
-      const registry = await loadRegistry(registryPath)
-      const extSkills = await fetchExtSkillsFn({ tmpDir, logger, registry })
-      upstreamMeta.extSkills = extSkills.skills
-
-      const extSkillMappings = buildExtSkillMappings(registry)
-      const fileCount = await applyMappings({
-        srcBase: extSkills.dir,
-        destBase: templatesDir,
-        mappings: extSkillMappings,
-        logger,
-      })
-      logger.success(`Ext-skills: ${fileCount} files synced`)
-    }
-  } finally {
-    // Cleanup temp directory
-    if (tmpDir) {
-      logger.debug('Cleaning up temp directory...')
-      await fse.remove(tmpDir)
-    }
-  }
-
-  // Step 6-8: Post-sync processing (snapshot, registry update, diff report)
-  let diff
-  let updatedUpstream
-  try {
-    // Step 6: Snapshot after and compute diff
-    const afterSnapshot = await snapshotDir(templatesDir)
-    diff = computeDiff(beforeSnapshot, afterSnapshot)
-
-    // Step 7: Update registry.json upstream metadata (immutable)
-    const registry = await loadRegistry(registryPath)
-    const now = new Date().toISOString()
-
-    updatedUpstream = {
-      ...(registry.upstream || {}),
-      ...(upstreamMeta.bmad ? {
-        bmad: {
-          type: 'npm',
-          package: 'bmad-method',
-          lastSyncVersion: upstreamMeta.bmad.version,
-          lastSyncDate: now,
-        },
-      } : {}),
-      ...(upstreamMeta.ecc ? {
-        ecc: {
-          type: 'git',
-          repo: ECC_REPO_URL,
-          lastSyncSha: upstreamMeta.ecc.sha,
-          lastSyncDate: now,
-        },
-      } : {}),
-      ...(upstreamMeta.plugins ? {
-        plugins: {
-          ...(registry.upstream?.plugins || {}),
-          lastSyncSha: upstreamMeta.plugins.sha,
-          lastSyncDate: now,
-        },
-      } : {}),
-      ...(upstreamMeta.extSkills ? {
-        'ext-skills': Object.fromEntries(
-          Object.entries(registry.upstream?.['ext-skills'] || {}).map(([id, entry]) => [
-            id,
-            upstreamMeta.extSkills[id]
-              ? { ...entry, lastSyncSha: upstreamMeta.extSkills[id].sha, lastSyncDate: now }
-              : entry,
-          ])
-        ),
-      } : {}),
-    }
-
-    const updatedRegistry = { ...registry, upstream: updatedUpstream }
-    await fse.writeFile(registryPath, JSON.stringify(updatedRegistry, null, 2) + '\n', 'utf8')
-    logger.debug('Registry updated with upstream metadata')
-  } catch (err) {
-    throw new Error(`Sync completed but post-processing failed: ${err.message}`)
-  }
-
-  // Step 8: Print diff report
-  logger.newline()
-  const totalChanges = diff.added.length + diff.modified.length + diff.deleted.length
-
-  if (totalChanges === 0) {
-    logger.info('  No changes detected — templates are up to date.')
-  } else {
-    logger.info(`  Changes: +${diff.added.length} added, ~${diff.modified.length} modified, -${diff.deleted.length} deleted`)
-    logger.newline()
-
-    if (diff.added.length > 0) {
-      logger.info('  Added:')
-      for (const f of diff.added) {
-        logger.success(f)
-      }
-    }
-
-    if (diff.modified.length > 0) {
-      logger.info('  Modified:')
-      for (const f of diff.modified) {
-        logger.warn(f)
-      }
-    }
-
-    if (diff.deleted.length > 0) {
-      logger.info('  Deleted:')
-      for (const f of diff.deleted) {
-        logger.error(f)
-      }
-    }
-  }
-
-  logger.newline()
-  logger.success('Sync complete.')
-
-  return { diff, upstream: updatedUpstream }
-}

package/src/core/differ.js

@@ -1,57 +0,0 @@
-/**
- * Directory snapshotting and diff computation for sync reporting.
- *
- * Captures file hashes before and after sync, then computes the set
- * of added, modified, and deleted files.
- */
-
-import path from 'node:path'
-import { listFiles, computeFileHash } from '../utils/fs.js'
-
-/**
- * Create a snapshot of all files in a directory as a Map of relPath → hash.
- *
- * @param {string} baseDir - Directory to snapshot
- * @returns {Promise<Map<string, string>>} Map of relative paths to sha256 hashes
- */
-export async function snapshotDir(baseDir) {
-  const files = await listFiles(baseDir)
-  const entries = await Promise.all(
-    files.map(async (relPath) => {
-      const absPath = path.join(baseDir, relPath)
-      const hash = await computeFileHash(absPath)
-      const normalized = relPath.replace(/\\/g, '/')
-      return [normalized, hash]
-    })
-  )
-  return new Map(entries)
-}
-
-/**
- * Compute the diff between two directory snapshots.
- *
- * @param {Map<string, string>} before - Snapshot before changes
- * @param {Map<string, string>} after  - Snapshot after changes
- * @returns {{ added: string[], modified: string[], deleted: string[] }}
- */
-export function computeDiff(before, after) {
-  const added = []
-  const modified = []
-  const deleted = []
-
-  for (const [filePath, hash] of after) {
-    if (!before.has(filePath)) {
-      added.push(filePath)
-    } else if (before.get(filePath) !== hash) {
-      modified.push(filePath)
-    }
-  }
-
-  for (const filePath of before.keys()) {
-    if (!after.has(filePath)) {
-      deleted.push(filePath)
-    }
-  }
-
-  return { added: added.sort(), modified: modified.sort(), deleted: deleted.sort() }
-}

package/src/core/installer.js

@@ -1,97 +0,0 @@
-import fse from 'fs-extra'
-import path from 'node:path'
-import { copyWithInterpolation, computeFileHash, listFiles, interpolate } from '../utils/fs.js'
-
-export class Installer {
-  constructor({ targetDir, logger }) {
-    this.targetDir = targetDir
-    this.logger = logger
-    this.createdPaths = []
-  }
-
-  async install(modules, variables) {
-    const result = { installed: [], fileRegistry: {} }
-
-    try {
-      for (let i = 0; i < modules.length; i++) {
-        const mod = modules[i]
-        this.logger.step(i + 1, modules.length, `Installing ${mod.name}...`)
-
-        const srcExists = await fse.pathExists(mod.templateDir)
-        if (!srcExists) {
-          throw new Error(`Template directory not found: ${mod.templateDir}`)
-        }
-
-        const destDir = path.join(this.targetDir, mod.targetDir)
-        this.createdPaths.push(destDir)
-
-        if (mod.adapter || mod.prefix) {
-          await this.installWithTransform(mod, destDir, variables)
-        } else {
-          await copyWithInterpolation(mod.templateDir, destDir, variables)
-        }
-
-        const files = await listFiles(destDir)
-        for (const file of files) {
-          const fullPath = path.join(destDir, file)
-          const hash = await computeFileHash(fullPath)
-          const relKey = path.join(mod.targetDir, file).replace(/\\/g, '/')
-          result.fileRegistry[relKey] = hash
-        }
-
-        result.installed.push({
-          id: mod.id,
-          name: mod.name,
-          files: files.length
-        })
-
-        this.logger.success(`${mod.name} (${files.length} files)`)
-      }
-    } catch (err) {
-      this.logger.error(`Installation failed: ${err.message}`)
-      await this.rollback()
-      throw err
-    }
-
-    return result
-  }
-
-  async installWithTransform(mod, destDir, variables) {
-    const srcFiles = await listFiles(mod.templateDir)
-
-    for (const relPath of srcFiles) {
-      const srcFile = path.join(mod.templateDir, relPath)
-      let content = await fse.readFile(srcFile, 'utf8')
-
-      // Interpolate variables
-      content = interpolate(content, variables)
-
-      // Apply adapter transformation
-      if (mod.adapter) {
-        content = mod.adapter(content, path.basename(relPath))
-      }
-
-      // Apply prefix to filename
-      let destRelPath = relPath
-      if (mod.prefix) {
-        const dir = path.dirname(relPath)
-        const base = path.basename(relPath)
-        destRelPath = dir === '.' ? `${mod.prefix}${base}` : path.join(dir, `${mod.prefix}${base}`)
-      }
-
-      const destFile = path.join(destDir, destRelPath)
-      await fse.ensureDir(path.dirname(destFile))
-      await fse.writeFile(destFile, content, 'utf8')
-    }
-  }
-
-  async rollback() {
-    this.logger.warn('Rolling back...')
-    for (const p of this.createdPaths.reverse()) {
-      if (await fse.pathExists(p)) {
-        await fse.remove(p)
-        this.logger.debug(`Removed: ${p}`)
-      }
-    }
-  }
-}