@cregis-dev/cckit 0.4.0 → 0.4.1

package/src/core/upstream.js

@@ -1,357 +1,357 @@
-/**
- * Upstream source fetching, path mapping, and file copying for sync.
- *
- * Handles pulling content from BMAD (npm), ECC (git), plugins (git),
- * and external skills (git) upstreams, then copying files to the local
- * templates/ directory via configurable path mappings with optional
- * filters, excludes, and post-processing.
- */
-
-import path from 'node:path'
-import fse from 'fs-extra'
-import os from 'node:os'
-import { execFile as execFileCb } from 'node:child_process'
-import { promisify } from 'node:util'
-import { mkdtemp } from 'node:fs/promises'
-import { listFiles, TEXT_EXTENSIONS } from '../utils/fs.js'
-
-const execFile = promisify(execFileCb)
-
-// ─── Path Mappings ──────────────────────────────────────────────────────────
-
-export const BMAD_PATH_MAPPINGS = [
-  { src: '_bmad/core', dest: 'bmad/core' },
-  { src: '_bmad/bmm', dest: 'bmad/bmm' },
-  { src: '_bmad/tea', dest: 'bmad/tea' },
-  { src: '_bmad/_config', dest: 'bmad/_config', exclude: ['manifest.yaml'] },
-  { src: '.claude/commands', dest: 'bmad/commands', filter: /^bmad-/ },
-  { src: '.trae/rules', dest: 'trae-bmad/rules', filter: /^bmad-/ },
-]
-
-export const ECC_REPO_URL = 'https://github.com/affaan-m/everything-claude-code'
-
-export const ECC_PATH_MAPPINGS = [
-  { src: 'rules', dest: 'ecc/rules' },
-  { src: 'agents', dest: 'ecc/agents' },
-  { src: 'skills', dest: 'ecc/skills' },
-  { src: 'commands', dest: 'ecc/commands' },
-]
-
-// ─── Fetch Functions ────────────────────────────────────────────────────────
-
-/**
- * Fetch BMAD content by running `npx bmad-method install` in a temp directory.
- * BMAD v6+ uses a CLI with `install` subcommand and module selection.
- *
- * @param {{ tmpDir: string, logger: object }} opts
- * @returns {Promise<{ version: string, dir: string }>} Extracted npm package version and install dir
- */
-export async function fetchBmad({ tmpDir, logger }) {
-  logger.debug('Fetching BMAD via npx bmad-method install...')
-
-  const bmadDir = path.join(tmpDir, 'bmad')
-  await fse.ensureDir(bmadDir)
-
-  // BMAD v6 CLI: install --yes --modules bmm,tea --tools claude-code,trae
-  await execFile('npx', [
-    '-y', 'bmad-method@latest', 'install',
-    '--yes',
-    '--directory', bmadDir,
-    '--modules', 'bmm,tea',
-    '--tools', 'claude-code,trae',
-    '--user-name', 'User',
-    '--communication-language', 'English',
-    '--document-output-language', 'English',
-  ], {
-    cwd: bmadDir,
-    timeout: 120_000,
-    shell: process.platform === 'win32',
-  })
-
-  // Extract version from the installed manifest
-  let version = 'unknown'
-  try {
-    const manifestPath = path.join(bmadDir, '_bmad', '_config', 'manifest.yaml')
-    if (await fse.pathExists(manifestPath)) {
-      const content = await fse.readFile(manifestPath, 'utf8')
-      const match = content.match(/version:\s*['"]?([^\s'"]+)/)
-      if (match) version = match[1]
-    }
-  } catch {
-    // Fallback: try package.json in npm cache
-  }
-
-  if (version === 'unknown') {
-    try {
-      const { stdout } = await execFile('npx', ['-y', 'bmad-method@latest', '--version'], {
-        timeout: 30_000,
-        shell: process.platform === 'win32',
-      })
-      version = stdout.trim() || 'unknown'
-    } catch {
-      logger.warn('Could not determine BMAD package version')
-    }
-  }
-
-  logger.debug(`BMAD fetched, version: ${version}`)
-  return { version, dir: bmadDir }
-}
-
-/**
- * Fetch ECC content by cloning the git repository.
- *
- * @param {{ tmpDir: string, logger: object }} opts
- * @returns {Promise<{ sha: string }>} HEAD commit SHA
- */
-export async function fetchEcc({ tmpDir, logger }) {
-  const repo = `${ECC_REPO_URL}.git`
-  const eccDir = path.join(tmpDir, 'ecc')
-
-  logger.debug(`Cloning ECC from ${repo}...`)
-
-  await execFile('git', ['clone', '--depth', '1', repo, eccDir], {
-    timeout: 120_000,
-    shell: process.platform === 'win32',
-  })
-
-  // Get HEAD SHA
-  let sha = 'unknown'
-  try {
-    const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
-      cwd: eccDir,
-      shell: process.platform === 'win32',
-    })
-    sha = stdout.trim()
-  } catch {
-    logger.warn('Could not determine ECC commit SHA')
-  }
-
-  logger.debug(`ECC cloned, SHA: ${sha}`)
-  return { sha, dir: eccDir }
-}
-
-// ─── Mapping & Copy ─────────────────────────────────────────────────────────
-
-/**
- * Apply path mappings to copy files from source to destination.
- *
- * @param {{
- *   srcBase: string,
- *   destBase: string,
- *   mappings: Array<{ src: string, dest: string, exclude?: string[], filter?: RegExp }>,
- *   postProcess?: (content: string, relPath: string) => string,
- *   logger: object
- * }} opts
- * @returns {Promise<number>} Total number of files copied
- */
-export async function applyMappings({ srcBase, destBase, mappings, postProcess, logger }) {
-  let totalFiles = 0
-
-  for (const mapping of mappings) {
-    const srcDir = path.join(srcBase, mapping.src)
-    const destDir = path.join(destBase, mapping.dest)
-
-    if (!await fse.pathExists(srcDir)) {
-      logger.warn(`Source directory not found, skipping: ${mapping.src}`)
-      continue
-    }
-
-    const files = await listFiles(srcDir)
-
-    for (const relPath of files) {
-      const fileName = path.basename(relPath)
-
-      // Apply exclude list
-      if (mapping.exclude && mapping.exclude.includes(fileName)) {
-        logger.debug(`  Excluded: ${mapping.src}/${relPath}`)
-        continue
-      }
-
-      // Apply filename filter (regex must match basename)
-      if (mapping.filter && !mapping.filter.test(fileName)) {
-        continue
-      }
-
-      const srcFile = path.join(srcDir, relPath)
-      const destFile = path.join(destDir, relPath)
-
-      await fse.ensureDir(path.dirname(destFile))
-
-      // Read, optionally post-process, then write
-      const ext = path.extname(relPath).toLowerCase()
-      const isText = TEXT_EXTENSIONS.has(ext)
-
-      if (isText && postProcess) {
-        let content = await fse.readFile(srcFile, 'utf8')
-        const destRelPath = path.join(mapping.dest, relPath).replace(/\\/g, '/')
-        content = postProcess(content, destRelPath)
-        await fse.writeFile(destFile, content, 'utf8')
-      } else {
-        await fse.copy(srcFile, destFile)
-      }
-
-      totalFiles++
-    }
-
-    logger.debug(`  Mapped ${mapping.src} → ${mapping.dest}`)
-  }
-
-  return totalFiles
-}
-
-// ─── Plugin Fetch ───────────────────────────────────────────────────────────
-
-/**
- * Fetch plugin content by cloning a marketplace GitHub repository.
- *
- * @param {{ tmpDir: string, logger: object, registry: object }} opts
- * @returns {Promise<{ sha: string, dir: string }>} HEAD commit SHA and clone directory
- */
-export async function fetchPlugins({ tmpDir, logger, registry }) {
-  const upstream = registry.upstream?.plugins
-  if (!upstream?.repo) {
-    throw new Error('No plugins upstream configured in registry.json')
-  }
-
-  const repo = upstream.repo.endsWith('.git') ? upstream.repo : `${upstream.repo}.git`
-  const pluginsDir = path.join(tmpDir, 'plugins')
-
-  logger.debug(`Cloning plugins from ${repo}...`)
-
-  await execFile('git', ['clone', '--depth', '1', repo, pluginsDir], {
-    timeout: 120_000,
-    shell: process.platform === 'win32',
-  })
-
-  // Get HEAD SHA
-  let sha = 'unknown'
-  try {
-    const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
-      cwd: pluginsDir,
-      shell: process.platform === 'win32',
-    })
-    sha = stdout.trim()
-  } catch {
-    logger.warn('Could not determine plugins commit SHA')
-  }
-
-  logger.debug(`Plugins cloned, SHA: ${sha}`)
-  return { sha, dir: pluginsDir }
-}
-
-/**
- * Build path mappings for plugins based on registry.plugins entries.
- * Each plugin maps from its source directory in the marketplace repo
- * to its destination in templates/plugins/.
- *
- * @param {object} registry - Registry object with plugins section
- * @returns {Array<{ src: string, dest: string }>} Path mappings
- */
-export function buildPluginMappings(registry) {
-  const pluginsPath = registry.upstream?.plugins?.pluginsPath || 'plugins'
-  const plugins = registry.plugins || {}
-
-  return Object.keys(plugins).map(id => ({
-    src: `${pluginsPath}/${id}`,
-    dest: `plugins/${id}`,
-  }))
-}
-
-// ─── External Skills Fetch ─────────────────────────────────────────────────
-
-/**
- * Fetch external skills by cloning each registered repo and extracting
- * the configured skillPath into a unified output directory.
- *
- * Each skill entry in `registry.upstream['ext-skills']` is cloned
- * independently, allowing skills from different repos to coexist.
- *
- * @param {{ tmpDir: string, logger: object, registry: object }} opts
- * @returns {Promise<{ skills: Record<string, { sha: string }>, dir: string }>}
- */
-export async function fetchExtSkills({ tmpDir, logger, registry }) {
-  const entries = registry.upstream?.['ext-skills'] || {}
-  const ids = Object.keys(entries)
-
-  if (ids.length === 0) {
-    throw new Error('No ext-skills upstream configured in registry.json')
-  }
-
-  const outputDir = path.join(tmpDir, 'ext-skills')
-  await fse.ensureDir(outputDir)
-
-  const skills = {}
-
-  for (const id of ids) {
-    const entry = entries[id]
-    if (entry.type !== 'git' || !entry.repo) {
-      logger.warn(`ext-skill "${id}" has invalid config, skipping`)
-      continue
-    }
-
-    const repo = entry.repo.endsWith('.git') ? entry.repo : `${entry.repo}.git`
-    const cloneDir = path.join(tmpDir, `ext-skill-${id}`)
-
-    logger.debug(`Cloning ext-skill "${id}" from ${repo}...`)
-
-    await execFile('git', ['clone', '--depth', '1', repo, cloneDir], {
-      timeout: 120_000,
-      shell: process.platform === 'win32',
-    })
-
-    // Get HEAD SHA
-    let sha = 'unknown'
-    try {
-      const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
-        cwd: cloneDir,
-        shell: process.platform === 'win32',
-      })
-      sha = stdout.trim()
-    } catch {
-      logger.warn(`Could not determine commit SHA for ext-skill "${id}"`)
-    }
-
-    // Copy skillPath contents to output/<id>/
-    const skillSrc = path.join(cloneDir, entry.skillPath || id)
-    const skillDest = path.join(outputDir, id)
-
-    if (await fse.pathExists(skillSrc)) {
-      await fse.copy(skillSrc, skillDest)
-      logger.debug(`ext-skill "${id}": copied ${entry.skillPath} → ${id}/, SHA: ${sha}`)
-    } else {
-      logger.warn(`ext-skill "${id}": skillPath "${entry.skillPath}" not found in repo`)
-    }
-
-    skills[id] = { sha }
-  }
-
-  return { skills, dir: outputDir }
-}
-
-/**
- * Build path mappings for external skills based on registry.upstream['ext-skills'].
- * Each skill maps from its ID subdirectory to templates/ext-skills/<id>.
- *
- * @param {object} registry - Registry object
- * @returns {Array<{ src: string, dest: string }>} Path mappings
- */
-export function buildExtSkillMappings(registry) {
-  const entries = registry.upstream?.['ext-skills'] || {}
-
-  return Object.keys(entries).map(id => ({
-    src: id,
-    dest: `ext-skills/${id}`,
-  }))
-}
-
-// ─── Temp Directory Helper ──────────────────────────────────────────────────
-
-/**
- * Create a uniquely-named temporary directory.
- *
- * @param {string} prefix - Prefix for the temp directory name
- * @returns {Promise<string>} Absolute path to the created directory
- */
-export async function createTempDir(prefix = 'cckit-sync') {
-  return mkdtemp(path.join(os.tmpdir(), `${prefix}-`))
-}
+/**
+ * Upstream source fetching, path mapping, and file copying for sync.
+ *
+ * Handles pulling content from BMAD (npm), ECC (git), plugins (git),
+ * and external skills (git) upstreams, then copying files to the local
+ * templates/ directory via configurable path mappings with optional
+ * filters, excludes, and post-processing.
+ */
+
+import path from 'node:path'
+import fse from 'fs-extra'
+import os from 'node:os'
+import { execFile as execFileCb } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp } from 'node:fs/promises'
+import { listFiles, TEXT_EXTENSIONS } from '../utils/fs.js'
+
+const execFile = promisify(execFileCb)
+
+// ─── Path Mappings ──────────────────────────────────────────────────────────
+
+export const BMAD_PATH_MAPPINGS = [
+  { src: '_bmad/core', dest: 'bmad/core' },
+  { src: '_bmad/bmm', dest: 'bmad/bmm' },
+  { src: '_bmad/tea', dest: 'bmad/tea' },
+  { src: '_bmad/_config', dest: 'bmad/_config', exclude: ['manifest.yaml'] },
+  { src: '.claude/commands', dest: 'bmad/commands', filter: /^bmad-/ },
+  { src: '.trae/rules', dest: 'trae-bmad/rules', filter: /^bmad-/ },
+]
+
+export const ECC_REPO_URL = 'https://github.com/affaan-m/everything-claude-code'
+
+export const ECC_PATH_MAPPINGS = [
+  { src: 'rules', dest: 'ecc/rules' },
+  { src: 'agents', dest: 'ecc/agents' },
+  { src: 'skills', dest: 'ecc/skills' },
+  { src: 'commands', dest: 'ecc/commands' },
+]
+
+// ─── Fetch Functions ────────────────────────────────────────────────────────
+
+/**
+ * Fetch BMAD content by running `npx bmad-method install` in a temp directory.
+ * BMAD v6+ uses a CLI with `install` subcommand and module selection.
+ *
+ * @param {{ tmpDir: string, logger: object }} opts
+ * @returns {Promise<{ version: string, dir: string }>} Extracted npm package version and install dir
+ */
+export async function fetchBmad({ tmpDir, logger }) {
+  logger.debug('Fetching BMAD via npx bmad-method install...')
+
+  const bmadDir = path.join(tmpDir, 'bmad')
+  await fse.ensureDir(bmadDir)
+
+  // BMAD v6 CLI: install --yes --modules bmm,tea --tools claude-code,trae
+  await execFile('npx', [
+    '-y', 'bmad-method@latest', 'install',
+    '--yes',
+    '--directory', bmadDir,
+    '--modules', 'bmm,tea',
+    '--tools', 'claude-code,trae',
+    '--user-name', 'User',
+    '--communication-language', 'English',
+    '--document-output-language', 'English',
+  ], {
+    cwd: bmadDir,
+    timeout: 120_000,
+    shell: process.platform === 'win32',
+  })
+
+  // Extract version from the installed manifest
+  let version = 'unknown'
+  try {
+    const manifestPath = path.join(bmadDir, '_bmad', '_config', 'manifest.yaml')
+    if (await fse.pathExists(manifestPath)) {
+      const content = await fse.readFile(manifestPath, 'utf8')
+      const match = content.match(/version:\s*['"]?([^\s'"]+)/)
+      if (match) version = match[1]
+    }
+  } catch {
+    // Fallback: try package.json in npm cache
+  }
+
+  if (version === 'unknown') {
+    try {
+      const { stdout } = await execFile('npx', ['-y', 'bmad-method@latest', '--version'], {
+        timeout: 30_000,
+        shell: process.platform === 'win32',
+      })
+      version = stdout.trim() || 'unknown'
+    } catch {
+      logger.warn('Could not determine BMAD package version')
+    }
+  }
+
+  logger.debug(`BMAD fetched, version: ${version}`)
+  return { version, dir: bmadDir }
+}
+
+/**
+ * Fetch ECC content by cloning the git repository.
+ *
+ * @param {{ tmpDir: string, logger: object }} opts
+ * @returns {Promise<{ sha: string }>} HEAD commit SHA
+ */
+export async function fetchEcc({ tmpDir, logger }) {
+  const repo = `${ECC_REPO_URL}.git`
+  const eccDir = path.join(tmpDir, 'ecc')
+
+  logger.debug(`Cloning ECC from ${repo}...`)
+
+  await execFile('git', ['clone', '--depth', '1', repo, eccDir], {
+    timeout: 120_000,
+    shell: process.platform === 'win32',
+  })
+
+  // Get HEAD SHA
+  let sha = 'unknown'
+  try {
+    const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
+      cwd: eccDir,
+      shell: process.platform === 'win32',
+    })
+    sha = stdout.trim()
+  } catch {
+    logger.warn('Could not determine ECC commit SHA')
+  }
+
+  logger.debug(`ECC cloned, SHA: ${sha}`)
+  return { sha, dir: eccDir }
+}
+
+// ─── Mapping & Copy ─────────────────────────────────────────────────────────
+
+/**
+ * Apply path mappings to copy files from source to destination.
+ *
+ * @param {{
+ *   srcBase: string,
+ *   destBase: string,
+ *   mappings: Array<{ src: string, dest: string, exclude?: string[], filter?: RegExp }>,
+ *   postProcess?: (content: string, relPath: string) => string,
+ *   logger: object
+ * }} opts
+ * @returns {Promise<number>} Total number of files copied
+ */
+export async function applyMappings({ srcBase, destBase, mappings, postProcess, logger }) {
+  let totalFiles = 0
+
+  for (const mapping of mappings) {
+    const srcDir = path.join(srcBase, mapping.src)
+    const destDir = path.join(destBase, mapping.dest)
+
+    if (!await fse.pathExists(srcDir)) {
+      logger.warn(`Source directory not found, skipping: ${mapping.src}`)
+      continue
+    }
+
+    const files = await listFiles(srcDir)
+
+    for (const relPath of files) {
+      const fileName = path.basename(relPath)
+
+      // Apply exclude list
+      if (mapping.exclude && mapping.exclude.includes(fileName)) {
+        logger.debug(`  Excluded: ${mapping.src}/${relPath}`)
+        continue
+      }
+
+      // Apply filename filter (regex must match basename)
+      if (mapping.filter && !mapping.filter.test(fileName)) {
+        continue
+      }
+
+      const srcFile = path.join(srcDir, relPath)
+      const destFile = path.join(destDir, relPath)
+
+      await fse.ensureDir(path.dirname(destFile))
+
+      // Read, optionally post-process, then write
+      const ext = path.extname(relPath).toLowerCase()
+      const isText = TEXT_EXTENSIONS.has(ext)
+
+      if (isText && postProcess) {
+        let content = await fse.readFile(srcFile, 'utf8')
+        const destRelPath = path.join(mapping.dest, relPath).replace(/\\/g, '/')
+        content = postProcess(content, destRelPath)
+        await fse.writeFile(destFile, content, 'utf8')
+      } else {
+        await fse.copy(srcFile, destFile)
+      }
+
+      totalFiles++
+    }
+
+    logger.debug(`  Mapped ${mapping.src} → ${mapping.dest}`)
+  }
+
+  return totalFiles
+}
+
+// ─── Plugin Fetch ───────────────────────────────────────────────────────────
+
+/**
+ * Fetch plugin content by cloning a marketplace GitHub repository.
+ *
+ * @param {{ tmpDir: string, logger: object, registry: object }} opts
+ * @returns {Promise<{ sha: string, dir: string }>} HEAD commit SHA and clone directory
+ */
+export async function fetchPlugins({ tmpDir, logger, registry }) {
+  const upstream = registry.upstream?.plugins
+  if (!upstream?.repo) {
+    throw new Error('No plugins upstream configured in registry.json')
+  }
+
+  const repo = upstream.repo.endsWith('.git') ? upstream.repo : `${upstream.repo}.git`
+  const pluginsDir = path.join(tmpDir, 'plugins')
+
+  logger.debug(`Cloning plugins from ${repo}...`)
+
+  await execFile('git', ['clone', '--depth', '1', repo, pluginsDir], {
+    timeout: 120_000,
+    shell: process.platform === 'win32',
+  })
+
+  // Get HEAD SHA
+  let sha = 'unknown'
+  try {
+    const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
+      cwd: pluginsDir,
+      shell: process.platform === 'win32',
+    })
+    sha = stdout.trim()
+  } catch {
+    logger.warn('Could not determine plugins commit SHA')
+  }
+
+  logger.debug(`Plugins cloned, SHA: ${sha}`)
+  return { sha, dir: pluginsDir }
+}
+
+/**
+ * Build path mappings for plugins based on registry.plugins entries.
+ * Each plugin maps from its source directory in the marketplace repo
+ * to its destination in templates/plugins/.
+ *
+ * @param {object} registry - Registry object with plugins section
+ * @returns {Array<{ src: string, dest: string }>} Path mappings
+ */
+export function buildPluginMappings(registry) {
+  const pluginsPath = registry.upstream?.plugins?.pluginsPath || 'plugins'
+  const plugins = registry.plugins || {}
+
+  return Object.keys(plugins).map(id => ({
+    src: `${pluginsPath}/${id}`,
+    dest: `plugins/${id}`,
+  }))
+}
+
+// ─── External Skills Fetch ─────────────────────────────────────────────────
+
+/**
+ * Fetch external skills by cloning each registered repo and extracting
+ * the configured skillPath into a unified output directory.
+ *
+ * Each skill entry in `registry.upstream['ext-skills']` is cloned
+ * independently, allowing skills from different repos to coexist.
+ *
+ * @param {{ tmpDir: string, logger: object, registry: object }} opts
+ * @returns {Promise<{ skills: Record<string, { sha: string }>, dir: string }>}
+ */
+export async function fetchExtSkills({ tmpDir, logger, registry }) {
+  const entries = registry.upstream?.['ext-skills'] || {}
+  const ids = Object.keys(entries)
+
+  if (ids.length === 0) {
+    throw new Error('No ext-skills upstream configured in registry.json')
+  }
+
+  const outputDir = path.join(tmpDir, 'ext-skills')
+  await fse.ensureDir(outputDir)
+
+  const skills = {}
+
+  for (const id of ids) {
+    const entry = entries[id]
+    if (entry.type !== 'git' || !entry.repo) {
+      logger.warn(`ext-skill "${id}" has invalid config, skipping`)
+      continue
+    }
+
+    const repo = entry.repo.endsWith('.git') ? entry.repo : `${entry.repo}.git`
+    const cloneDir = path.join(tmpDir, `ext-skill-${id}`)
+
+    logger.debug(`Cloning ext-skill "${id}" from ${repo}...`)
+
+    await execFile('git', ['clone', '--depth', '1', repo, cloneDir], {
+      timeout: 120_000,
+      shell: process.platform === 'win32',
+    })
+
+    // Get HEAD SHA
+    let sha = 'unknown'
+    try {
+      const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
+        cwd: cloneDir,
+        shell: process.platform === 'win32',
+      })
+      sha = stdout.trim()
+    } catch {
+      logger.warn(`Could not determine commit SHA for ext-skill "${id}"`)
+    }
+
+    // Copy skillPath contents to output/<id>/
+    const skillSrc = path.join(cloneDir, entry.skillPath || id)
+    const skillDest = path.join(outputDir, id)
+
+    if (await fse.pathExists(skillSrc)) {
+      await fse.copy(skillSrc, skillDest)
+      logger.debug(`ext-skill "${id}": copied ${entry.skillPath} → ${id}/, SHA: ${sha}`)
+    } else {
+      logger.warn(`ext-skill "${id}": skillPath "${entry.skillPath}" not found in repo`)
+    }
+
+    skills[id] = { sha }
+  }
+
+  return { skills, dir: outputDir }
+}
+
+/**
+ * Build path mappings for external skills based on registry.upstream['ext-skills'].
+ * Each skill maps from its ID subdirectory to templates/ext-skills/<id>.
+ *
+ * @param {object} registry - Registry object
+ * @returns {Array<{ src: string, dest: string }>} Path mappings
+ */
+export function buildExtSkillMappings(registry) {
+  const entries = registry.upstream?.['ext-skills'] || {}
+
+  return Object.keys(entries).map(id => ({
+    src: id,
+    dest: `ext-skills/${id}`,
+  }))
+}
+
+// ─── Temp Directory Helper ──────────────────────────────────────────────────
+
+/**
+ * Create a uniquely-named temporary directory.
+ *
+ * @param {string} prefix - Prefix for the temp directory name
+ * @returns {Promise<string>} Absolute path to the created directory
+ */
+export async function createTempDir(prefix = 'cckit-sync') {
+  return mkdtemp(path.join(os.tmpdir(), `${prefix}-`))
+}