bmad-module-skill-forge 0.2.0

package/tools/cli/lib/installer.js

@@ -0,0 +1,307 @@
+/**
+ * SKF Installer - Core orchestrator
+ * Copies SKF source files, compiles agents, creates folder structure.
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const { spinner } = require('@clack/prompts');
+const yaml = require('js-yaml');
+const { compileAgentFile } = require('./compiler');
+const { generateIdeCommands } = require('./ide-commands');
+const { writeManifest } = require('./manifest');
+
+class Installer {
+  constructor() {
+    // Resolve directories relative to this file (tools/cli/lib/ -> up 3 levels)
+    const repoRoot = path.resolve(__dirname, '..', '..', '..');
+    this.srcDir = path.join(repoRoot, 'src');
+    this.docsDir = path.join(repoRoot, 'docs');
+  }
+
+  async install(config) {
+    const { projectDir, skfFolder } = config;
+    const skfDir = path.join(projectDir, skfFolder);
+    const action = config._action || 'fresh';
+    const s = spinner();
+
+    // Handle update vs fresh for existing installation
+    if (action === 'update' && (await fs.pathExists(skfDir))) {
+      const configPath = path.join(skfDir, 'config.yaml');
+      if (!config._savedConfigYaml && (await fs.pathExists(configPath))) {
+        config._savedConfigYaml = await fs.readFile(configPath, 'utf8');
+      }
+
+      // On update, extract settings from saved config
+      if (config._savedConfigYaml) {
+        try {
+          const savedData = yaml.load(config._savedConfigYaml);
+          if (!config.ides && savedData.ides) config.ides = savedData.ides;
+          if (!config.skills_output_folder && savedData.skills_output_folder) config.skills_output_folder = savedData.skills_output_folder;
+          if (!config.forge_data_folder && savedData.forge_data_folder) config.forge_data_folder = savedData.forge_data_folder;
+        } catch {
+          /* ignore parse errors, defaults will apply */
+        }
+      }
+
+      s.start('Updating SKF files...');
+      await fs.remove(skfDir);
+      s.stop('Old files cleared');
+    } else if (action === 'fresh' && (await fs.pathExists(skfDir))) {
+      s.start('Removing existing SKF installation...');
+      await fs.remove(skfDir);
+      s.stop('Old installation removed');
+    }
+
+    // Ensure parent directory exists (for _bmad/skf/)
+    await fs.ensureDir(path.dirname(skfDir));
+
+    // Step 1: Copy source files
+    s.start('Copying SKF files...');
+    try {
+      await this.copySrcFiles(skfDir);
+      s.stop('SKF files copied');
+    } catch (error) {
+      s.stop('Failed to copy SKF files');
+      throw error;
+    }
+
+    // Step 2: Setup agent sidecar
+    s.start('Setting up agent sidecar...');
+    try {
+      await this.setupSidecar(projectDir);
+      s.stop('Agent sidecar initialized');
+    } catch (error) {
+      s.stop('Failed to setup sidecar');
+      throw error;
+    }
+
+    // Step 2b: Update .gitignore
+    await this.updateGitignore(projectDir);
+
+    // Step 3: Write config.yaml
+    s.start('Writing configuration...');
+    try {
+      await this.writeConfig(skfDir, config);
+      s.stop('Configuration saved');
+    } catch (error) {
+      s.stop('Failed to write configuration');
+      throw error;
+    }
+
+    // Step 4: Compile agents
+    s.start('Compiling agents...');
+    try {
+      const agents = await this.compileAgents(skfDir, skfFolder);
+      s.stop(`Compiled ${agents.length} agent${agents.length === 1 ? '' : 's'}`);
+    } catch (error) {
+      s.stop('Failed to compile agents');
+      throw error;
+    }
+
+    // Step 5: Create output folders
+    s.start('Creating project folders...');
+    try {
+      await this.createOutputFolders(projectDir, config);
+      s.stop('Project folders created');
+    } catch (error) {
+      s.stop('Failed to create project folders');
+      throw error;
+    }
+
+    // Step 6: Copy learning material (optional)
+    if (config.install_learning !== false) {
+      s.start('Copying learning & reference material...');
+      try {
+        await this.copyLearningMaterial(projectDir);
+        s.stop('Learning material added to _skf-learn/');
+      } catch (error) {
+        s.stop('Failed to copy learning material');
+        throw error;
+      }
+    }
+
+    // Step 7: Generate IDE command files
+    let ideFiles = [];
+    const selectedIdes = config.ides || [];
+    if (selectedIdes.length > 0 && !selectedIdes.every((ide) => ide === 'other')) {
+      s.start('Generating IDE commands...');
+      try {
+        const ideResult = await generateIdeCommands(projectDir, skfFolder, selectedIdes);
+        ideFiles = ideResult.files || [];
+        if (ideResult.generated > 0) {
+          s.stop(`IDE commands generated for ${ideResult.ides.join(', ')}`);
+        } else {
+          s.stop('No IDE commands to generate');
+        }
+      } catch (error) {
+        s.stop('Failed to generate IDE commands');
+        throw error;
+      }
+    }
+
+    // Step 8: Write installation manifest
+    s.start('Writing manifest...');
+    try {
+      const packageJson = require('../../../package.json');
+      await writeManifest(projectDir, config, {
+        version: packageJson.version,
+        ideFiles,
+      });
+      s.stop('Installation manifest saved');
+    } catch (error) {
+      s.stop('Failed to write manifest');
+      throw error;
+    }
+
+    return { success: true, skfDir, projectDir };
+  }
+
+  /**
+   * Copy src/ content into the target SKF directory.
+   * Workflows are placed under a skillforge/ subdirectory to match agent path references.
+   */
+  async copySrcFiles(skfDir) {
+    // Copy agents and knowledge directly
+    for (const dir of ['agents', 'knowledge']) {
+      const src = path.join(this.srcDir, dir);
+      const dest = path.join(skfDir, dir);
+      if (await fs.pathExists(src)) {
+        await fs.copy(src, dest);
+      }
+    }
+
+    // Workflows go under workflows/skillforge/ to match agent YAML paths
+    const workflowsSrc = path.join(this.srcDir, 'workflows');
+    const workflowsDest = path.join(skfDir, 'workflows', 'skillforge');
+    if (await fs.pathExists(workflowsSrc)) {
+      await fs.copy(workflowsSrc, workflowsDest);
+    }
+
+    // Copy module.yaml and module-help.csv
+    for (const file of ['module.yaml', 'module-help.csv']) {
+      const src = path.join(this.srcDir, file);
+      if (await fs.pathExists(src)) {
+        await fs.copy(src, path.join(skfDir, file));
+      }
+    }
+  }
+
+  /**
+   * Setup the ferris sidecar directory with template files.
+   * Existing sidecar files are preserved (they contain user state).
+   */
+  async setupSidecar(projectDir) {
+    const sidecarDir = path.join(projectDir, '_bmad', '_memory', 'forger-sidecar');
+    await fs.ensureDir(sidecarDir);
+
+    const forgerSrc = path.join(this.srcDir, 'forger');
+    if (await fs.pathExists(forgerSrc)) {
+      const files = await fs.readdir(forgerSrc);
+      for (const file of files) {
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+          const dest = path.join(sidecarDir, file);
+          // Don't overwrite existing sidecar files (preserves user state)
+          if (!(await fs.pathExists(dest))) {
+            await fs.copy(path.join(forgerSrc, file), dest);
+          }
+        }
+      }
+    }
+  }
+
+  async writeConfig(skfDir, config) {
+    // On update, restore the user's existing config
+    if (config._savedConfigYaml) {
+      await fs.writeFile(path.join(skfDir, 'config.yaml'), config._savedConfigYaml, 'utf8');
+      return;
+    }
+
+    // Get user name from git or system
+    const getUserName = () => {
+      try {
+        const { execSync } = require('node:child_process');
+        return execSync('git config user.name', { encoding: 'utf8' }).trim() || 'Developer';
+      } catch {
+        return 'Developer';
+      }
+    };
+
+    const configData = {
+      user_name: getUserName(),
+      project_name: config.project_name || 'Untitled Project',
+      communication_language: 'en',
+      document_output_language: 'en',
+      skills_output_folder: config.skills_output_folder || 'skills',
+      forge_data_folder: config.forge_data_folder || 'forge-data',
+      skf_folder: config.skfFolder,
+      ides: config.ides || [],
+    };
+
+    const yamlStr = yaml.dump(configData, { lineWidth: -1 });
+    await fs.writeFile(path.join(skfDir, 'config.yaml'), `# SKF Configuration - Generated by installer\n${yamlStr}`, 'utf8');
+  }
+
+  async compileAgents(skfDir, skfFolder) {
+    const agentsDir = path.join(skfDir, 'agents');
+    const files = await fs.readdir(agentsDir);
+    const agentFiles = files.filter((f) => f.endsWith('.agent.yaml'));
+    const results = [];
+
+    for (const file of agentFiles) {
+      const yamlPath = path.join(agentsDir, file);
+      const result = compileAgentFile(yamlPath, { skfFolder });
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  async createOutputFolders(projectDir, config) {
+    const skillsFolder = config.skills_output_folder || 'skills';
+    const forgeDataFolder = config.forge_data_folder || 'forge-data';
+
+    for (const folder of [skillsFolder, forgeDataFolder]) {
+      const folderPath = path.join(projectDir, folder);
+      if (!(await fs.pathExists(folderPath))) {
+        await fs.ensureDir(folderPath);
+        await fs.writeFile(path.join(folderPath, '.gitkeep'), '# This file ensures the directory is tracked by git\n');
+      }
+    }
+  }
+
+  async updateGitignore(projectDir) {
+    const gitignorePath = path.join(projectDir, '.gitignore');
+    const entry = '_bmad/_memory/';
+
+    try {
+      if (await fs.pathExists(gitignorePath)) {
+        const content = await fs.readFile(gitignorePath, 'utf8');
+        // Check if entry already present (exact line match)
+        const lines = content.split('\n');
+        if (lines.some((line) => line.trim() === entry)) return;
+        // Append with preceding newline if file doesn't end with one
+        const prefix = content.endsWith('\n') ? '' : '\n';
+        await fs.appendFile(gitignorePath, `${prefix}${entry}\n`, 'utf8');
+      } else {
+        await fs.writeFile(gitignorePath, `${entry}\n`, 'utf8');
+      }
+    } catch {
+      // Non-critical — don't fail the install over .gitignore
+    }
+  }
+
+  async copyLearningMaterial(projectDir) {
+    const learnDir = path.join(projectDir, '_skf-learn');
+    if (await fs.pathExists(this.docsDir)) {
+      await fs.copy(this.docsDir, learnDir, {
+        filter: (srcPath) => {
+          // Skip website-specific files
+          return !path.basename(srcPath).startsWith('404');
+        },
+      });
+    }
+  }
+}
+
+module.exports = { Installer };

package/tools/cli/lib/manifest.js

@@ -0,0 +1,109 @@
+/**
+ * SKF Manifest - Tracks installed files for uninstall and smart updates.
+ * Writes _bmad/_config/manifest.yaml after each install.
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+
+const MANIFEST_DIR = '_bmad/_config';
+const MANIFEST_FILE = 'skf-manifest.yaml';
+
+/**
+ * Recursively collect all file paths under a directory,
+ * returned as paths relative to projectDir.
+ */
+async function collectFiles(dir, projectDir) {
+  const files = [];
+  if (!(await fs.pathExists(dir))) return files;
+
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const subFiles = await collectFiles(fullPath, projectDir);
+      files.push(...subFiles);
+    } else {
+      files.push(path.relative(projectDir, fullPath));
+    }
+  }
+  return files;
+}
+
+/**
+ * Build and write the manifest after installation.
+ *
+ * @param {string} projectDir - Project root
+ * @param {object} config - Install config (skfFolder, ides, etc.)
+ * @param {object} options - Additional info (version, ideFiles)
+ */
+async function writeManifest(projectDir, config, options = {}) {
+  const skfFolder = config.skfFolder || '_bmad/skf';
+  const skfDir = path.join(projectDir, skfFolder);
+  const sidecarDir = path.join(projectDir, '_bmad', '_memory', 'forger-sidecar');
+
+  // Collect all installed files
+  const skfFiles = await collectFiles(skfDir, projectDir);
+  const sidecarFiles = await collectFiles(sidecarDir, projectDir);
+
+  // Collect IDE command files
+  const ideFiles = options.ideFiles || [];
+
+  // Collect learning material files
+  const learnDir = path.join(projectDir, '_skf-learn');
+  const learnFiles = await collectFiles(learnDir, projectDir);
+
+  // Collect output folder gitkeep files
+  const outputFiles = [];
+  for (const folder of [config.skills_output_folder || 'skills', config.forge_data_folder || 'forge-data']) {
+    const gitkeep = path.join(folder, '.gitkeep');
+    if (await fs.pathExists(path.join(projectDir, gitkeep))) {
+      outputFiles.push(gitkeep);
+    }
+  }
+
+  const manifest = {
+    version: options.version || 'unknown',
+    installed_at: new Date().toISOString(),
+    action: config._action || 'fresh',
+    module: 'skf',
+    skf_folder: skfFolder,
+    ides: config.ides || [],
+    skills_output_folder: config.skills_output_folder || 'skills',
+    forge_data_folder: config.forge_data_folder || 'forge-data',
+    directories: [skfFolder, '_bmad/_memory/forger-sidecar', ...(learnFiles.length > 0 ? ['_skf-learn'] : [])],
+    files: {
+      skf: skfFiles,
+      sidecar: sidecarFiles,
+      ide_commands: ideFiles,
+      learning: learnFiles,
+      output: outputFiles,
+    },
+  };
+
+  const manifestDir = path.join(projectDir, MANIFEST_DIR);
+  await fs.ensureDir(manifestDir);
+
+  const yamlStr = yaml.dump(manifest, { lineWidth: -1, sortKeys: false });
+  await fs.writeFile(
+    path.join(manifestDir, MANIFEST_FILE),
+    `# SKF Installation Manifest - Generated by installer\n# Do not edit manually\n${yamlStr}`,
+    'utf8',
+  );
+}
+
+/**
+ * Read an existing manifest, or return null if none exists.
+ */
+async function readManifest(projectDir) {
+  const manifestPath = path.join(projectDir, MANIFEST_DIR, MANIFEST_FILE);
+  try {
+    const content = await fs.readFile(manifestPath, 'utf8');
+    return yaml.load(content) || null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { writeManifest, readManifest, MANIFEST_DIR, MANIFEST_FILE };

package/tools/cli/lib/ui.js

@@ -0,0 +1,277 @@
+/**
+ * SKF Installer UI - Banner, prompts, and success message.
+ * Uses @clack/prompts for terminal UI.
+ */
+
+const { intro, outro, text, select, multiselect, confirm, note, isCancel, cancel, log } = require('@clack/prompts');
+const chalk = require('chalk');
+const figlet = require('figlet');
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+
+const SKF_FOLDER = '_bmad/skf';
+
+class UI {
+  displayBanner() {
+    let banner;
+    try {
+      banner = figlet.textSync('SKF', { font: 'Standard' });
+    } catch {
+      banner = '\n  S K F';
+    }
+    const packageJson = require('../../../package.json');
+    intro(
+      `${chalk.cyan(banner)}\n${chalk.white.bold('  Skill Forge')} ${chalk.dim(`v${packageJson.version}`)}\n${chalk.dim('  AST-verified, provenance-backed agent skills from code\n  repositories, documentation, and developer discourse')}`,
+    );
+  }
+
+  async detectInstallation(projectDir) {
+    const hasBmadSkf = await fs.pathExists(path.join(projectDir, SKF_FOLDER));
+    const hasBmadDir = await fs.pathExists(path.join(projectDir, '_bmad'));
+
+    if (hasBmadSkf) {
+      return { type: 'existing', folder: SKF_FOLDER };
+    }
+    if (hasBmadDir) {
+      return { type: 'bmad-ready', folder: SKF_FOLDER };
+    }
+    return { type: 'fresh', folder: SKF_FOLDER };
+  }
+
+  async promptInstall() {
+    this.displayBanner();
+
+    const projectDir = process.cwd();
+    const defaultProjectName = path.basename(projectDir);
+    const detection = await this.detectInstallation(projectDir);
+    const skfFolder = detection.folder;
+
+    log.info(`Target: ${chalk.cyan(projectDir)}`);
+
+    let action = 'fresh';
+
+    if (detection.type === 'existing') {
+      log.warn(`Found existing installation at ${chalk.white(SKF_FOLDER + '/')}`);
+
+      const choice = await select({
+        message: 'What would you like to do?',
+        options: [
+          { label: 'Update — Replace SKF files, keep config.yaml', value: 'update' },
+          { label: 'Fresh install — Remove everything and start over', value: 'fresh' },
+          { label: 'Cancel', value: 'cancel' },
+        ],
+      });
+
+      if (isCancel(choice) || choice === 'cancel') {
+        cancel('Installation cancelled.');
+        return { cancelled: true };
+      }
+      action = choice;
+    } else {
+      log.info(`Agents and workflows will be installed in ${chalk.white(skfFolder + '/')}`);
+    }
+
+    if (action === 'update') {
+      log.info('Existing config.yaml will be preserved.');
+      return {
+        projectDir,
+        skfFolder,
+        _detection: detection,
+        _action: action,
+        cancelled: false,
+      };
+    }
+
+    // Load saved config to pre-populate defaults on fresh reinstall
+    const savedConfig = await this.loadSavedConfig(projectDir, skfFolder);
+    if (savedConfig) {
+      log.info('Previous configuration detected — defaults pre-populated.');
+    }
+
+    const ideOptions = [
+      { label: 'Claude Code', value: 'claude-code' },
+      { label: 'Cline', value: 'cline' },
+      { label: 'Codex', value: 'codex' },
+      { label: 'Cursor', value: 'cursor' },
+      { label: 'GitHub Copilot', value: 'github-copilot' },
+      { label: 'Roo Code', value: 'roo' },
+      { label: 'Windsurf', value: 'windsurf' },
+      { label: 'Other', value: 'other' },
+    ];
+
+    // Pre-check IDEs: saved config takes priority, then auto-detect from directories
+    const savedIdes = savedConfig?.ides || [];
+    let initialIdes = [];
+    if (savedIdes.length > 0) {
+      initialIdes = savedIdes;
+    } else {
+      const detectedIdes = await this.detectIdes(projectDir);
+      if (detectedIdes.length > 0) {
+        initialIdes = detectedIdes;
+        log.info(`Auto-detected IDEs: ${detectedIdes.join(', ')}`);
+      }
+    }
+
+    // Mark initially selected IDEs
+    for (const opt of ideOptions) {
+      opt.initialSelected = initialIdes.includes(opt.value);
+    }
+
+    // Project name
+    const project_name = await text({
+      message: 'Project name:',
+      initialValue: savedConfig?.project_name || defaultProjectName,
+    });
+    if (isCancel(project_name)) {
+      cancel('Installation cancelled.');
+      return { cancelled: true };
+    }
+
+    // Skills output folder
+    const skills_output_folder = await text({
+      message: 'Where should generated skills be saved?',
+      initialValue: savedConfig?.skills_output_folder || 'skills',
+    });
+    if (isCancel(skills_output_folder)) {
+      cancel('Installation cancelled.');
+      return { cancelled: true };
+    }
+
+    // Forge data folder
+    const forge_data_folder = await text({
+      message: 'Where should forge workspace artifacts be stored?',
+      initialValue: savedConfig?.forge_data_folder || 'forge-data',
+    });
+    if (isCancel(forge_data_folder)) {
+      cancel('Installation cancelled.');
+      return { cancelled: true };
+    }
+
+    // IDE selection
+    const ides = await multiselect({
+      message: 'Which tools/IDEs are you using?',
+      options: ideOptions,
+      initialValues: initialIdes,
+      required: true,
+    });
+    if (isCancel(ides)) {
+      cancel('Installation cancelled.');
+      return { cancelled: true };
+    }
+
+    // Learning material
+    const install_learning = await confirm({
+      message: 'Install learning & reference material?',
+      initialValue: true,
+    });
+    if (isCancel(install_learning)) {
+      cancel('Installation cancelled.');
+      return { cancelled: true };
+    }
+
+    return {
+      projectDir,
+      project_name,
+      skills_output_folder,
+      forge_data_folder,
+      ides,
+      install_learning,
+      skfFolder,
+      _detection: detection,
+      _action: action,
+      cancelled: false,
+    };
+  }
+
+  async detectIdes(projectDir) {
+    const markers = {
+      'claude-code': ['.claude'],
+      cursor: ['.cursor'],
+      cline: ['.clinerules'],
+      codex: ['.codex'],
+      'github-copilot': ['.github/copilot-instructions.md', '.github/prompts'],
+      roo: ['.roo', '.roomodes'],
+      windsurf: ['.windsurf'],
+    };
+
+    const detected = [];
+    for (const [ide, paths] of Object.entries(markers)) {
+      for (const p of paths) {
+        if (await fs.pathExists(path.join(projectDir, p))) {
+          detected.push(ide);
+          break;
+        }
+      }
+    }
+    return detected;
+  }
+
+  async loadSavedConfig(projectDir, skfFolder) {
+    const configPath = path.join(projectDir, skfFolder, 'config.yaml');
+    try {
+      if (await fs.pathExists(configPath)) {
+        const content = await fs.readFile(configPath, 'utf8');
+        return yaml.load(content) || null;
+      }
+    } catch {
+      // ignore parse errors
+    }
+    return null;
+  }
+
+  displaySuccess(skfFolder, ides = [], action = 'fresh') {
+    const ideNames = {
+      'claude-code': 'Claude Code',
+      cline: 'Cline',
+      codex: 'Codex',
+      cursor: 'Cursor',
+      'github-copilot': 'GitHub Copilot',
+      roo: 'Roo Code',
+      windsurf: 'Windsurf',
+      other: 'your IDE',
+    };
+
+    let ideDisplay;
+    if (!ides || ides.length === 0) {
+      ideDisplay = 'your IDE';
+    } else if (ides.length === 1) {
+      ideDisplay = ideNames[ides[0]] || 'your IDE';
+    } else {
+      ideDisplay = ides.map((ide) => ideNames[ide] || ide).join(' or ');
+    }
+
+    let noteTitle;
+    let noteBody;
+
+    if (action === 'update') {
+      noteTitle = 'Update complete!';
+      noteBody = [
+        `${chalk.white.bold('What Changed')}`,
+        'SKF files and agents have been refreshed.',
+        'Your config.yaml and sidecar state are preserved.',
+        '',
+        `${chalk.white.bold('Next Steps')}`,
+        `1. Reload the agent in ${ideDisplay}:`,
+        `   ${chalk.cyan(`"Read and activate ${skfFolder}/agents/forger.md"`)}`,
+        '2. Run @Ferris SF to re-detect tools if needed',
+      ].join('\n');
+    } else {
+      noteTitle = 'Installation complete!';
+      noteBody = [
+        `${chalk.white.bold('Get Started')}`,
+        `1. Open this folder in ${ideDisplay}`,
+        '2. Locate the chat window and type:',
+        `   ${chalk.cyan(`"Read and activate ${skfFolder}/agents/forger.md"`)}`,
+        '3. Ferris (your Skill Architect) will guide you through',
+        '   setting up and forging your first agent skill',
+      ].join('\n');
+    }
+
+    note(noteBody, noteTitle);
+
+    outro(`Agent: Ferris (Skill Architect & Integrity Guardian)\nDocs: https://github.com/armelhbobdad/bmad-module-skill-forge`);
+  }
+}
+
+module.exports = { UI };