@siliconoid/agentkit 0.1.0

package/lib/scaffold.mjs

@@ -0,0 +1,385 @@
+import { join, relative } from 'path'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs'
+import {
+  copyDir, ensureDir, writeIfNotExists, writeWithMarker, templateReplace, getTemplatesDir, MARKERS,
+  WORKFLOW_PACKS, SKILL_BUNDLES,
+} from './utils.mjs'
+
+/**
+ * Copy the base .ai/ skeleton into the project.
+ * Only writes files that don't already exist.
+ */
+export function scaffoldBase(projectRoot, vars) {
+  const templatesDir = getTemplatesDir()
+  const baseSrc = join(templatesDir, 'base')
+  const created = []
+
+  function copyRecursive(src, dest) {
+    ensureDir(dest)
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+      const srcPath = join(src, entry.name)
+      const destPath = join(dest, entry.name)
+      if (entry.isDirectory()) {
+        copyRecursive(srcPath, destPath)
+      } else {
+        if (!existsSync(destPath)) {
+          ensureDir(dest)
+          const content = readFileSync(srcPath, 'utf8')
+          writeFileSync(destPath, templateReplace(content, vars))
+          created.push(relative(projectRoot, destPath))
+        }
+      }
+    }
+  }
+
+  copyRecursive(baseSrc, projectRoot)
+  return created
+}
+
+/**
+ * Apply framework-specific rule overrides (overwrite matching files).
+ */
+export function scaffoldFramework(projectRoot, framework, vars) {
+  const templatesDir = getTemplatesDir()
+  const fwDir = join(templatesDir, 'frameworks', framework)
+  if (!existsSync(fwDir)) return []
+
+  const created = []
+  function copyRecursive(src, dest) {
+    ensureDir(dest)
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+      const srcPath = join(src, entry.name)
+      const destPath = join(dest, entry.name)
+      if (entry.isDirectory()) {
+        copyRecursive(srcPath, destPath)
+      } else {
+        ensureDir(dest)
+        const content = readFileSync(srcPath, 'utf8')
+        writeFileSync(destPath, templateReplace(content, vars))
+        created.push(relative(projectRoot, destPath))
+      }
+    }
+  }
+
+  copyRecursive(fwDir, projectRoot)
+  return created
+}
+
+/**
+ * Generate platform-specific root docs and directories.
+ */
+export async function scaffoldPlatforms(projectRoot, platforms, vars) {
+  const created = []
+
+  for (const platformId of platforms) {
+    const adapter = await import(`./adapters/${platformId}.mjs`)
+    const paths = adapter.getOutputPaths(projectRoot)
+
+    // Generate root doc
+    if (paths.rootDoc) {
+      const content = adapter.generateRootDoc(vars)
+      // Windsurf uses writeWithMarker so sync can update the merged file later
+      if (platformId === 'windsurf') {
+        const marker = adapter.marker || MARKERS.md
+        if (writeWithMarker(paths.rootDoc, content, marker)) {
+          created.push(relative(projectRoot, paths.rootDoc))
+        }
+      } else {
+        if (writeIfNotExists(paths.rootDoc, content)) {
+          created.push(relative(projectRoot, paths.rootDoc))
+        }
+      }
+    }
+
+    // Create skills/commands dirs if adapter supports them
+    if (paths.skillsDir) ensureDir(paths.skillsDir)
+    if (paths.commandsDir) ensureDir(paths.commandsDir)
+  }
+
+  return created
+}
+
+// Which platforms support skill packs (skills dir)
+const SKILL_PLATFORMS = {
+  claude:      '.claude/skills',
+  codex:       '.codex/skills',
+  gemini:      '.gemini/skills',
+  antigravity: '.agent/skills',
+}
+
+/**
+ * Install workflow packs (e.g. BMAD) for selected platforms.
+ * @param {string} projectRoot
+ * @param {string[]} platforms - selected platform IDs
+ * @param {string[]} workflowPackIds - selected workflow pack IDs (e.g. ['bmad'])
+ * @returns {string[]} created file paths (relative)
+ */
+export function scaffoldWorkflows(projectRoot, platforms, workflowPackIds, vars = {}) {
+  const templatesDir = getTemplatesDir()
+  const created = []
+
+  for (const packId of workflowPackIds) {
+    const pack = WORKFLOW_PACKS.find(w => w.id === packId)
+    if (!pack) continue
+
+    const packTemplateDir = join(templatesDir, packId)
+    if (!existsSync(packTemplateDir)) continue
+
+    // Install platform-specific command stubs
+    for (const platformId of platforms) {
+      const mapping = pack.platformMapping[platformId]
+      if (!mapping) continue
+
+      const src = join(packTemplateDir, mapping.src)
+      if (!existsSync(src)) continue
+
+      const dest = join(projectRoot, mapping.dest)
+      copyRecursiveIfNotExists(src, dest, projectRoot, created)
+    }
+
+    // Install source files that command stubs depend on (e.g. _bmad/)
+    if (pack.sourceDir) {
+      const srcDir = join(packTemplateDir, pack.sourceDir.src)
+      const destDir = join(projectRoot, pack.sourceDir.dest)
+      if (existsSync(srcDir)) {
+        copyRecursiveIfNotExists(srcDir, destDir, projectRoot, created)
+
+        // Generate runtime config with template vars
+        const configPath = join(destDir, 'core', 'config.yaml')
+        if (existsSync(join(srcDir, 'config.yaml'))) {
+          ensureDir(join(destDir, 'core'))
+          const tmpl = readFileSync(join(srcDir, 'config.yaml'), 'utf8')
+          const content = templateReplace(tmpl, vars)
+          writeFileSync(configPath, content)
+          created.push(relative(projectRoot, configPath))
+        }
+
+        // Generate _config/manifest.yaml with platform info
+        const manifestPath = join(destDir, '_config', 'manifest.yaml')
+        if (existsSync(join(destDir, '_config'))) {
+          const idesList = platforms
+            .map(p => {
+              const idMap = { claude: 'claude-code', cursor: 'cursor', codex: 'codex', gemini: 'gemini', antigravity: 'antigravity', windsurf: 'windsurf' }
+              return idMap[p]
+            })
+            .filter(Boolean)
+          const manifestContent = [
+            'installation:',
+            '  version: 6.0.0',
+            `  installDate: ${new Date().toISOString()}`,
+            `  lastUpdated: ${new Date().toISOString()}`,
+            'modules:',
+            '  - core',
+            '  - bmm',
+            'ides:',
+            ...idesList.map(id => `  - ${id}`),
+            '',
+          ].join('\n')
+          writeFileSync(manifestPath, manifestContent)
+        }
+
+        // Generate _config/ides/ yaml files for each platform
+        const idesDir = join(destDir, '_config', 'ides')
+        if (existsSync(idesDir)) {
+          for (const platformId of platforms) {
+            const idMap = { claude: 'claude-code', cursor: 'cursor', codex: 'codex', gemini: 'gemini', antigravity: 'antigravity', windsurf: 'windsurf' }
+            const ideId = idMap[platformId]
+            if (!ideId) continue
+            const idePath = join(idesDir, `${ideId}.yaml`)
+            if (!existsSync(idePath)) {
+              const ideContent = [
+                `ide: ${ideId}`,
+                `configured_date: ${new Date().toISOString()}`,
+                `last_updated: ${new Date().toISOString()}`,
+                'configuration:',
+                '  subagentChoices: null',
+                '  installLocation: null',
+                '',
+              ].join('\n')
+              writeFileSync(idePath, ideContent)
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return created
+}
+
+/**
+ * Install skill packs for each selected platform.
+ */
+export function scaffoldSkills(projectRoot, platforms, skillPacks) {
+  const templatesDir = getTemplatesDir()
+  const skillsDir = join(templatesDir, 'skills')
+  const created = []
+
+  if (!existsSync(skillsDir) || skillPacks.length === 0) return created
+
+  for (const platformId of platforms) {
+    const destBase = SKILL_PLATFORMS[platformId]
+    if (!destBase) continue
+
+    for (const skillName of skillPacks) {
+      const src = join(skillsDir, skillName)
+      if (!existsSync(src)) continue
+
+      const dest = join(projectRoot, destBase, skillName)
+      copyRecursiveIfNotExists(src, dest, projectRoot, created)
+    }
+  }
+
+  return created
+}
+
+// Which platforms support agents
+const AGENT_PLATFORMS = {
+  claude:      '.claude/agents',
+}
+
+/**
+ * Install skill bundles (e.g. Superpowers) — multi-skill packs installed as a unit.
+ * Each bundle contains multiple skill dirs + optional agents.
+ */
+export function scaffoldSkillBundles(projectRoot, platforms, bundleIds) {
+  const templatesDir = getTemplatesDir()
+  const created = []
+
+  for (const bundleId of bundleIds) {
+    const bundle = SKILL_BUNDLES.find(b => b.id === bundleId)
+    if (!bundle) continue
+
+    const bundleDir = join(templatesDir, bundle.templateDir)
+    if (!existsSync(bundleDir)) continue
+
+    // Install each skill subdirectory to platform skills dirs
+    for (const entry of readdirSync(bundleDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue  // skip LICENSE, etc.
+      if (entry.name === '_agents') continue  // handled below
+
+      const skillSrc = join(bundleDir, entry.name)
+      for (const platformId of platforms) {
+        const destBase = SKILL_PLATFORMS[platformId]
+        if (!destBase) continue
+        const dest = join(projectRoot, destBase, entry.name)
+        copyRecursiveIfNotExists(skillSrc, dest, projectRoot, created)
+      }
+    }
+
+    // Install agents (e.g. code-reviewer.md → .claude/agents/)
+    const agentsDir = join(bundleDir, '_agents')
+    if (existsSync(agentsDir)) {
+      for (const platformId of platforms) {
+        const agentDest = AGENT_PLATFORMS[platformId]
+        if (!agentDest) continue
+        const destDir = join(projectRoot, agentDest)
+        copyRecursiveIfNotExists(agentsDir, destDir, projectRoot, created)
+      }
+    }
+  }
+
+  return created
+}
+
+/** Helper: recursively copy files, skip existing */
+function copyRecursiveIfNotExists(src, dest, projectRoot, created) {
+  ensureDir(dest)
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name)
+    const destPath = join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyRecursiveIfNotExists(srcPath, destPath, projectRoot, created)
+    } else {
+      if (!existsSync(destPath)) {
+        ensureDir(dest)
+        const content = readFileSync(srcPath, 'utf8')
+        writeFileSync(destPath, content)
+        created.push(relative(projectRoot, destPath))
+      }
+    }
+  }
+}
+
+/**
+ * Apply template variable replacement to all .md files in .ai/rules/
+ */
+export function runTemplateReplace(projectRoot, vars) {
+  const rulesDir = join(projectRoot, '.ai', 'rules')
+  if (!existsSync(rulesDir)) return
+
+  for (const file of readdirSync(rulesDir).filter(f => f.endsWith('.md'))) {
+    const filePath = join(rulesDir, file)
+    const content = readFileSync(filePath, 'utf8')
+    const replaced = templateReplace(content, vars)
+    if (replaced !== content) {
+      writeFileSync(filePath, replaced)
+    }
+  }
+}
+
+/**
+ * Generate .ai/QUICK-START.md with project configuration summary.
+ */
+export function generateQuickStart(projectRoot, vars, framework) {
+  const rulesRecommendation = getRecommendedRules(framework)
+
+  const content = `# Quick Start
+
+## Project Configuration
+
+| Setting | Value |
+|---------|-------|
+| Project | ${vars.projectName} |
+| Framework | ${vars.frameworkDisplay} ${vars.frameworkVersion !== '—' ? vars.frameworkVersion : ''} |
+| Language | ${vars.primaryLanguage} |
+| Package Manager | ${vars.packageManager} |
+| Build Tool | ${vars.buildTool} |
+
+## Top Rules to Review First
+
+${rulesRecommendation}
+
+## Next Steps
+
+1. **Review rules** — Check \`.ai/rules/\` and customize for your project
+2. **Run doctor** — \`npx agentkit doctor\` to verify setup
+3. **Sync skills** — \`npx agentkit sync\` after modifying skills
+4. **Add platforms** — \`npx agentkit add-platform <id>\` for more AI tools
+5. **List config** — \`npx agentkit list\` to see current setup
+
+---
+*Generated by AgentKit*
+`
+
+  const filePath = join(projectRoot, '.ai', 'QUICK-START.md')
+  ensureDir(join(projectRoot, '.ai'))
+  writeFileSync(filePath, content)
+}
+
+function getRecommendedRules(framework) {
+  const base = [
+    '1. **01-project-overview.md** — Your tech stack and constraints',
+    '2. **03-coding-conventions.md** — Code style and patterns',
+  ]
+
+  switch (framework) {
+    case 'nextjs-pages':
+    case 'nextjs-app':
+      base.push('3. **07-react.md** — React patterns and Next.js conventions')
+      break
+    case 'react-spa':
+      base.push('3. **07-react.md** — React component patterns')
+      break
+    case 'vue':
+      base.push('3. **07-react.md** — Vue component patterns (rename to 07-vue.md)')
+      break
+    case 'nodejs':
+      base.push('3. **02-architecture.md** — Backend architecture patterns')
+      break
+    default:
+      base.push('3. **02-architecture.md** — System architecture')
+  }
+
+  return base.join('\n')
+}

package/lib/schema.mjs

@@ -0,0 +1,135 @@
+/**
+ * Lightweight config schema validator.
+ * No external dependencies — pure JS validation.
+ */
+
+// ---------------------------------------------------------------------------
+// Schema Definition
+// ---------------------------------------------------------------------------
+
+const KNOWN_PLATFORMS = ['claude', 'cursor', 'codex', 'gemini', 'antigravity', 'windsurf']
+const KNOWN_FRAMEWORKS = ['nextjs-pages', 'nextjs-app', 'react-spa', 'vue', 'nodejs', 'custom']
+const KNOWN_WORKFLOW_PACKS = ['bmad']
+
+/**
+ * Validate a agentkit.json config object.
+ * @param {object} config - The parsed config object
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateConfig(config) {
+  const errors = []
+  const warnings = []
+
+  if (!config || typeof config !== 'object') {
+    return { valid: false, errors: ['Config must be a non-null object'], warnings }
+  }
+
+  // Required fields
+  if (!config.version || typeof config.version !== 'string') {
+    errors.push('Missing or invalid "version" field (expected string)')
+  }
+
+  if (!config.platforms || !Array.isArray(config.platforms)) {
+    errors.push('Missing or invalid "platforms" field (expected array)')
+  } else {
+    if (config.platforms.length === 0) {
+      warnings.push('"platforms" is empty — no platform adapters will be generated')
+    }
+    for (const p of config.platforms) {
+      if (!KNOWN_PLATFORMS.includes(p)) {
+        warnings.push(`Unknown platform "${p}" — known: ${KNOWN_PLATFORMS.join(', ')}`)
+      }
+    }
+  }
+
+  // Optional string fields
+  for (const field of ['projectName', 'projectDescription']) {
+    if (config[field] !== undefined && typeof config[field] !== 'string') {
+      errors.push(`"${field}" must be a string`)
+    }
+  }
+
+  // Framework
+  if (config.framework !== undefined) {
+    if (typeof config.framework !== 'string') {
+      errors.push('"framework" must be a string')
+    } else if (!KNOWN_FRAMEWORKS.includes(config.framework)) {
+      warnings.push(`Unknown framework "${config.framework}" — known: ${KNOWN_FRAMEWORKS.join(', ')}`)
+    }
+  }
+
+  // Array fields
+  for (const field of ['workflowPacks', 'skillPacks', 'skillBundles']) {
+    if (config[field] !== undefined && !Array.isArray(config[field])) {
+      errors.push(`"${field}" must be an array`)
+    }
+  }
+
+  // Workflow packs validation
+  if (Array.isArray(config.workflowPacks)) {
+    for (const w of config.workflowPacks) {
+      if (!KNOWN_WORKFLOW_PACKS.includes(w)) {
+        warnings.push(`Unknown workflow pack "${w}"`)
+      }
+    }
+  }
+
+  // Packages registry (new field)
+  if (config.packages !== undefined) {
+    if (typeof config.packages !== 'object' || Array.isArray(config.packages)) {
+      errors.push('"packages" must be an object')
+    } else {
+      for (const [name, pkg] of Object.entries(config.packages)) {
+        if (!pkg || typeof pkg !== 'object') {
+          errors.push(`packages["${name}"] must be an object`)
+          continue
+        }
+        if (!pkg.source || typeof pkg.source !== 'string') {
+          errors.push(`packages["${name}"].source is required (string)`)
+        }
+        if (!pkg.type || !['rule-pack', 'skill-pack', 'workflow-pack', 'mixed'].includes(pkg.type)) {
+          warnings.push(`packages["${name}"].type should be one of: rule-pack, skill-pack, workflow-pack, mixed`)
+        }
+      }
+    }
+  }
+
+  // Warn on unknown top-level keys
+  const knownKeys = new Set([
+    'version', 'projectName', 'projectDescription', 'framework',
+    'platforms', 'workflowPacks', 'skillPacks', 'skillBundles', 'packages', 'detected',
+  ])
+  for (const key of Object.keys(config)) {
+    if (!knownKeys.has(key)) {
+      warnings.push(`Unknown config key "${key}"`)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+/**
+ * Provide default values for optional config fields.
+ * Mutates and returns the config object.
+ */
+export function normalizeConfig(config) {
+  config.projectName = config.projectName || 'project'
+  config.projectDescription = config.projectDescription || ''
+  config.framework = config.framework || 'custom'
+  config.skillPacks = config.skillPacks || []
+  config.skillBundles = config.skillBundles || []
+  config.packages = config.packages || {}
+
+  // Backward-compat: migrate bmadCommands → workflowPacks
+  if (config.bmadCommands !== undefined && config.workflowPacks === undefined) {
+    config.workflowPacks = config.bmadCommands ? ['bmad'] : []
+    delete config.bmadCommands
+  }
+  config.workflowPacks = config.workflowPacks || []
+
+  return config
+}