bmad-module-ultracode-goal 0.1.0

package/tools/cli/commands/status.js

@@ -0,0 +1,161 @@
+/**
+ * UCG Status Command
+ * Shows installation state, version, configured IDEs, and skill integrity.
+ */
+
+const chalk = require('chalk');
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const { readManifest } = require('../lib/manifest');
+const { getAvailablePlatforms } = require('../lib/ide-skills');
+
+const UCG_FOLDER = '_bmad/ucg';
+const SKILL_NAME = 'ultracode-goal';
+
+function getIdeNames() {
+  const names = { other: 'Other' };
+  for (const p of getAvailablePlatforms()) {
+    names[p.value] = p.label;
+  }
+  return names;
+}
+
+async function readYaml(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    return yaml.load(content) || {};
+  } catch {
+    return null;
+  }
+}
+
+async function getStatus(projectDir) {
+  const ucgDir = path.join(projectDir, UCG_FOLDER);
+  const skillDir = path.join(ucgDir, SKILL_NAME);
+
+  const installed = await fs.pathExists(ucgDir);
+  if (!installed) {
+    return { installed: false };
+  }
+
+  // Read config
+  const config = await readYaml(path.join(ucgDir, 'config.yaml'));
+
+  // Read installed version
+  let installedVersion = null;
+  try {
+    installedVersion = (await fs.readFile(path.join(ucgDir, 'VERSION'), 'utf8')).trim();
+  } catch {
+    /* keep null */
+  }
+
+  // Skill integrity: SKILL.md, stage references, deterministic scripts, hooks
+  const skillInstalled = await fs.pathExists(path.join(skillDir, 'SKILL.md'));
+
+  let referenceCount = 0;
+  const referencesDir = path.join(skillDir, 'references');
+  if (await fs.pathExists(referencesDir)) {
+    const entries = await fs.readdir(referencesDir);
+    referenceCount = entries.filter((entry) => entry.endsWith('.md')).length;
+  }
+
+  const gateScript = await fs.pathExists(path.join(skillDir, 'scripts', 'gate_eval.py'));
+  const preflightScript = await fs.pathExists(path.join(skillDir, 'scripts', 'preflight_check.py'));
+  const hooksPresent = await fs.pathExists(path.join(skillDir, 'scripts', 'hooks'));
+
+  // Learning material
+  const learnInstalled = await fs.pathExists(path.join(projectDir, '_ucg-learn'));
+
+  // Read manifest
+  const manifest = await readManifest(projectDir);
+
+  return {
+    installed: true,
+    config,
+    installedVersion,
+    skillInstalled,
+    referenceCount,
+    gateScript,
+    preflightScript,
+    hooksPresent,
+    learnInstalled,
+    manifest,
+  };
+}
+
+function displayStatus(status, version) {
+  console.log('');
+  console.log(chalk.hex('#6366F1').bold('  UltraCode Goal — Status'));
+  console.log(chalk.dim(`  v${version}`));
+  console.log('');
+
+  if (!status.installed) {
+    console.log(chalk.yellow('  Not installed.'));
+    console.log(chalk.dim('  Run: npx bmad-module-ultracode-goal install'));
+    console.log('');
+    return;
+  }
+
+  const config = status.config || {};
+
+  // Installation
+  const manifest = status.manifest;
+  console.log(chalk.white.bold('  Installation'));
+  console.log(`    Project:      ${chalk.hex('#818CF8')(config.project_name || '(unknown)')}`);
+  console.log(`    UCG folder:   ${chalk.dim(UCG_FOLDER + '/')}`);
+  console.log(`    Version:      ${status.installedVersion ? chalk.white(status.installedVersion) : chalk.yellow('(unknown)')}`);
+  console.log(`    Skill:        ${status.skillInstalled ? chalk.green('installed') : chalk.yellow('not installed')}`);
+  if (manifest) {
+    console.log(
+      `    Installed:    ${chalk.dim(manifest.installed_at ? new Date(manifest.installed_at).toLocaleDateString() : '(unknown)')}`,
+    );
+    console.log(`    Manifest:     ${chalk.green('present')}`);
+  } else {
+    console.log(`    Manifest:     ${chalk.yellow('missing')} ${chalk.dim('(reinstall to generate)')}`);
+  }
+  console.log('');
+
+  // Skill integrity
+  console.log(chalk.white.bold('  Skill Integrity'));
+  console.log(`    Stages:       ${chalk.white(status.referenceCount)} ${chalk.dim('reference files')}`);
+  console.log(`    gate_eval:    ${status.gateScript ? chalk.green('present') : chalk.red('missing')}`);
+  console.log(`    preflight:    ${status.preflightScript ? chalk.green('present') : chalk.red('missing')}`);
+  console.log(`    hooks:        ${status.hooksPresent ? chalk.green('present') : chalk.red('missing')}`);
+  console.log('');
+
+  // IDEs
+  const ides = config.ides || [];
+  const ideNames = getIdeNames();
+  console.log(chalk.white.bold('  IDEs'));
+  if (ides.length > 0) {
+    for (const ide of ides) {
+      console.log(`    ${chalk.green('●')} ${ideNames[ide] || ide}`);
+    }
+  } else {
+    console.log(chalk.dim('    None configured'));
+  }
+  console.log('');
+
+  // Learning material
+  console.log(chalk.white.bold('  Learning Material'));
+  console.log(`    _ucg-learn/:  ${status.learnInstalled ? chalk.green('installed') : chalk.dim('not installed')}`);
+  console.log('');
+}
+
+module.exports = {
+  command: 'status',
+  description: 'Show UCG installation state, version, and configuration',
+  options: [],
+  action: async () => {
+    try {
+      const projectDir = process.cwd();
+      const packageJson = require('../../../package.json');
+      const status = await getStatus(projectDir);
+      displayStatus(status, packageJson.version);
+    } catch (error) {
+      console.error(chalk.red('\nFailed to read status:'), error.message);
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/commands/uninstall.js

@@ -0,0 +1,175 @@
+/**
+ * UCG Uninstall Command
+ * Clean removal of UCG files, IDE skill directories, and learning material.
+ * Uses the manifest to know exactly what to remove.
+ */
+
+const chalk = require('chalk');
+const path = require('node:path');
+const fs = require('fs-extra');
+const { confirm, isCancel, spinner, log, outro } = require('@clack/prompts');
+const { readManifest, MANIFEST_DIR, MANIFEST_FILE } = require('../lib/manifest');
+const { removeAllUcgSkills } = require('../lib/ide-skills');
+
+/**
+ * Count files that still exist on disk from manifest lists.
+ */
+async function countExistingFiles(projectDir, manifest) {
+  const allFiles = [...(manifest.files.ucg || []), ...(manifest.files.ide_skills || []), ...(manifest.files.learning || [])];
+
+  let existing = 0;
+  for (const file of allFiles) {
+    if (await fs.pathExists(path.join(projectDir, file))) {
+      existing++;
+    }
+  }
+  return { total: allFiles.length, existing };
+}
+
+/**
+ * Display what will be removed, grouped by category.
+ */
+async function displayRemovalPlan(projectDir, manifest) {
+  const categories = [
+    { key: 'ucg', label: 'UCG module files', dir: manifest.ucg_folder },
+    { key: 'ide_skills', label: 'IDE skill directories' },
+    { key: 'learning', label: 'Learning material', dir: '_ucg-learn' },
+  ];
+
+  const lines = [];
+  for (const cat of categories) {
+    const files = manifest.files[cat.key] || [];
+    if (files.length === 0) continue;
+
+    // Count how many still exist
+    let existCount = 0;
+    for (const f of files) {
+      if (await fs.pathExists(path.join(projectDir, f))) existCount++;
+    }
+
+    if (existCount === 0) continue;
+
+    if (cat.dir) {
+      lines.push(`${chalk.red('×')} ${cat.label} ${chalk.dim(`(${cat.dir}/ — ${existCount} files)`)}`);
+    } else {
+      lines.push(`${chalk.red('×')} ${cat.label} ${chalk.dim(`(${existCount} files)`)}`);
+    }
+  }
+
+  // Manifest itself
+  lines.push(`${chalk.red('×')} Installation manifest ${chalk.dim(`(${MANIFEST_DIR}/${MANIFEST_FILE})`)}`);
+
+  log.warn(`The following will be removed:\n${lines.join('\n')}`);
+  log.info(
+    'Note: hooks merged into .claude/settings.local.json are not removed —\ndelete the ultracode-goal entries there manually if you added them.',
+  );
+}
+
+/**
+ * Remove a directory if it exists and is empty.
+ */
+async function removeEmptyDir(dirPath) {
+  if (!(await fs.pathExists(dirPath))) return;
+  try {
+    const entries = await fs.readdir(dirPath);
+    if (entries.length === 0) {
+      await fs.remove(dirPath);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+module.exports = {
+  command: 'uninstall',
+  description: 'Remove the UCG installation from the current project',
+  options: [],
+  action: async () => {
+    try {
+      const projectDir = process.cwd();
+      const manifest = await readManifest(projectDir);
+
+      if (!manifest) {
+        // Check if UCG exists without manifest
+        const ucgExists = await fs.pathExists(path.join(projectDir, '_bmad/ucg'));
+        if (ucgExists) {
+          log.warn(
+            'No manifest found. Reinstall first to generate one,\nthen run uninstall again for clean removal.\nRun: npx bmad-module-ultracode-goal install',
+          );
+        } else {
+          log.warn('UltraCode Goal is not installed in this directory.');
+        }
+        process.exit(0);
+        return;
+      }
+
+      const { existing } = await countExistingFiles(projectDir, manifest);
+      if (existing === 0) {
+        log.warn('No UCG files found to remove.');
+        // Clean up stale manifest
+        await fs.remove(path.join(projectDir, MANIFEST_DIR, MANIFEST_FILE));
+        process.exit(0);
+        return;
+      }
+
+      await displayRemovalPlan(projectDir, manifest);
+
+      const shouldProceed = await confirm({
+        message: 'Proceed with uninstall?',
+        initialValue: false,
+      });
+
+      if (isCancel(shouldProceed) || !shouldProceed) {
+        log.warn('Uninstall cancelled.');
+        process.exit(0);
+        return;
+      }
+
+      const s = spinner();
+
+      // Remove IDE skill directories from all known platforms (skills + legacy command files)
+      s.start('Removing IDE skill directories...');
+      const removedIdeDirs = await removeAllUcgSkills(projectDir);
+      if (removedIdeDirs.length > 0) {
+        s.stop(`Cleaned the skill from ${removedIdeDirs.length} IDE target(s)`);
+      } else {
+        s.stop('No IDE skill directories found');
+      }
+
+      // Remove learning material directory
+      const learnFiles = manifest.files.learning || [];
+      if (learnFiles.length > 0) {
+        s.start('Removing learning material...');
+        const learnDir = path.join(projectDir, '_ucg-learn');
+        if (await fs.pathExists(learnDir)) {
+          await fs.remove(learnDir);
+        }
+        s.stop('Learning material removed');
+      }
+
+      // Remove UCG module directory
+      s.start('Removing UCG module...');
+      const ucgDir = path.join(projectDir, manifest.ucg_folder);
+      if (await fs.pathExists(ucgDir)) {
+        await fs.remove(ucgDir);
+      }
+      s.stop('UCG module removed');
+
+      // Remove manifest
+      const manifestPath = path.join(projectDir, MANIFEST_DIR, MANIFEST_FILE);
+      if (await fs.pathExists(manifestPath)) {
+        await fs.remove(manifestPath);
+      }
+      // Clean empty _bmad/_config/ and _bmad/ if we were the only occupant
+      await removeEmptyDir(path.join(projectDir, MANIFEST_DIR));
+      await removeEmptyDir(path.join(projectDir, '_bmad'));
+
+      outro('UltraCode Goal uninstalled successfully.');
+
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('\nUninstall failed:'), error.message);
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/commands/update.js

@@ -0,0 +1,65 @@
+/**
+ * UCG Quick Update Command
+ * Replaces UCG files and reinstalls the skill without re-prompting.
+ * Preserves config.yaml.
+ */
+
+const chalk = require('chalk');
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const { Installer } = require('../lib/installer');
+const { UI } = require('../lib/ui');
+
+const UCG_FOLDER = '_bmad/ucg';
+
+module.exports = {
+  command: 'update',
+  description: 'Update UCG files and reinstall the skill (preserves config)',
+  options: [],
+  action: async () => {
+    try {
+      const projectDir = process.cwd();
+      const ucgDir = path.join(projectDir, UCG_FOLDER);
+
+      if (!(await fs.pathExists(ucgDir))) {
+        console.log(chalk.yellow('\n  UltraCode Goal is not installed in this directory.'));
+        console.log(chalk.dim('  Run: npx bmad-module-ultracode-goal install\n'));
+        process.exit(0);
+        return;
+      }
+
+      console.log('');
+      console.log(chalk.hex('#6366F1').bold('  UltraCode Goal — Quick Update'));
+      console.log(chalk.dim('  Replacing UCG files, preserving config.\n'));
+
+      const installer = new Installer();
+      const result = await installer.install({
+        projectDir,
+        ucgFolder: UCG_FOLDER,
+        _action: 'update',
+      });
+
+      if (result && result.success) {
+        // Read config to get IDEs for post-update notes
+        let ides = [];
+        try {
+          const configContent = await fs.readFile(path.join(ucgDir, 'config.yaml'), 'utf8');
+          const config = yaml.load(configContent);
+          ides = config?.ides || [];
+        } catch {
+          /* use empty */
+        }
+        const ui = new UI();
+        ui.displaySuccess(UCG_FOLDER, ides, 'update');
+        process.exit(0);
+      } else {
+        console.error(chalk.red('\nUpdate failed.'));
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(chalk.red('\nUpdate failed:'), error.message);
+      process.exit(1);
+    }
+  },
+};

package/tools/cli/lib/ide-skills.js

@@ -0,0 +1,218 @@
+/**
+ * IDE Skill Installer — Verbatim skill directory installation
+ *
+ * Follows the BMAD standard: skill directories (containing SKILL.md +
+ * supporting files) are copied directly to each IDE's skills/ directory.
+ * IDEs read SKILL.md natively.
+ *
+ * Supports 23+ IDEs via platform-codes.yaml (config-driven, no IDE-specific code).
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+
+const PLATFORM_CODES_PATH = path.join(__dirname, 'platform-codes.yaml');
+
+// UCG-owned skill directories inside IDE skills/ targets
+const UCG_SKILLS = new Set(['ultracode-goal']);
+
+// OS/editor artifacts to filter during copy
+const ARTIFACT_FILTER = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini', '._.DS_Store']);
+
+/**
+ * Load platform configuration from platform-codes.yaml.
+ * Returns { platforms: { 'claude-code': { name, preferred, installer: { target_dir, legacy_targets } }, ... } }
+ */
+function loadPlatforms() {
+  const content = fs.readFileSync(PLATFORM_CODES_PATH, 'utf8');
+  return yaml.load(content);
+}
+
+/**
+ * Get available platforms for UI display.
+ * Returns array of { value, label, preferred, skillInvocationPrefix }.
+ * skillInvocationPrefix is null when the IDE only auto-invokes skills.
+ */
+function getAvailablePlatforms() {
+  const config = loadPlatforms();
+  return Object.entries(config.platforms)
+    .filter(([, p]) => !p.suspended)
+    .map(([code, p]) => ({
+      value: code,
+      label: p.name,
+      preferred: p.preferred || false,
+      skillInvocationPrefix: p.skill_invocation_prefix ?? null,
+    }))
+    .sort((a, b) => {
+      // Preferred first, then alphabetical
+      if (a.preferred !== b.preferred) return b.preferred ? 1 : -1;
+      return a.label.localeCompare(b.label);
+    });
+}
+
+/**
+ * Get IDE auto-detection markers.
+ * Returns { 'claude-code': ['.claude'], 'cursor': ['.cursor'], ... }
+ *
+ * Uses explicit detection_marker from platform config when available,
+ * otherwise derives from the top-level directory of target_dir.
+ * The derived marker only works when the IDE's config directory exists
+ * independently of the installer (e.g. .claude/ exists before UCG install).
+ */
+function getDetectionMarkers() {
+  const config = loadPlatforms();
+  const markers = {};
+  for (const [code, p] of Object.entries(config.platforms)) {
+    if (p.suspended) continue;
+    const targetDir = p.installer?.target_dir;
+    if (!targetDir) continue;
+    if (p.installer.detection_marker) {
+      markers[code] = [p.installer.detection_marker];
+    } else {
+      // Derive from target_dir — works when top-level dir is the IDE's own config dir
+      const topDir = '.' + targetDir.split('/')[0].replace(/^\./, '');
+      markers[code] = [topDir];
+    }
+  }
+  return markers;
+}
+
+/**
+ * Install skill directories to all selected IDEs.
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {string} ucgDir - Path to installed UCG module (e.g., {projectDir}/_bmad/ucg)
+ * @param {string[]} ideCodes - Array of IDE codes (e.g., ['claude-code', 'cursor'])
+ * @returns {{ installed: number, ides: string[], directories: string[] }}
+ */
+async function installSkillsToIdes(projectDir, ucgDir, ideCodes) {
+  if (!ideCodes || ideCodes.length === 0) return { installed: 0, ides: [], directories: [] };
+
+  const config = loadPlatforms();
+  let totalInstalled = 0;
+  const processedIdes = [];
+  const allDirectories = [];
+
+  // Copy filter: skip OS artifacts
+  const copyFilter = (src) => !ARTIFACT_FILTER.has(path.basename(src));
+
+  for (const ideCode of ideCodes) {
+    const platform = config.platforms[ideCode];
+    if (!platform || !platform.installer?.target_dir) continue;
+
+    const targetDir = path.join(projectDir, platform.installer.target_dir);
+
+    // Clean legacy targets first (old command files from previous UCG installs)
+    await cleanLegacyTargets(projectDir, platform);
+
+    // Clean existing UCG skills from this IDE (for update/reinstall)
+    await cleanUcgSkills(targetDir);
+
+    // Ensure target directory exists
+    await fs.ensureDir(targetDir);
+
+    // Copy UCG-owned skill directories from the installed module
+    if (await fs.pathExists(ucgDir)) {
+      const entries = await fs.readdir(ucgDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        if (UCG_SKILLS.has(entry.name)) {
+          const src = path.join(ucgDir, entry.name);
+          const dest = path.join(targetDir, entry.name);
+          await fs.copy(src, dest, { filter: copyFilter });
+          totalInstalled++;
+        }
+      }
+    }
+
+    allDirectories.push(platform.installer.target_dir);
+    processedIdes.push(ideCode);
+  }
+
+  return { installed: totalInstalled, ides: processedIdes, directories: allDirectories };
+}
+
+/**
+ * Remove legacy command files from old IDE target directories.
+ * Handles migration from command-file approach to skill-directory approach.
+ */
+async function cleanLegacyTargets(projectDir, platform) {
+  const legacyTargets = platform.installer?.legacy_targets || [];
+
+  for (const legacyDir of legacyTargets) {
+    const fullPath = path.join(projectDir, legacyDir);
+    if (!(await fs.pathExists(fullPath))) continue;
+
+    try {
+      const files = await fs.readdir(fullPath);
+      for (const file of files) {
+        // Remove UCG-specific command files from legacy directories
+        if (file.startsWith('bmad-ultracode-goal-') || file.startsWith('bmad-ucg-')) {
+          await fs.remove(path.join(fullPath, file));
+        }
+      }
+
+      // Remove empty directories
+      const remaining = await fs.readdir(fullPath);
+      if (remaining.length === 0) {
+        await fs.remove(fullPath);
+        // Also try to remove empty parent
+        const parentDir = path.dirname(fullPath);
+        try {
+          const parentRemaining = await fs.readdir(parentDir);
+          if (parentRemaining.length === 0) await fs.remove(parentDir);
+        } catch {
+          /* ignore */
+        }
+      }
+    } catch {
+      /* non-critical, continue */
+    }
+  }
+}
+
+/**
+ * Remove existing UCG skill directories from an IDE target.
+ * Called before reinstalling to ensure clean state.
+ */
+async function cleanUcgSkills(targetDir) {
+  if (!(await fs.pathExists(targetDir))) return;
+
+  try {
+    const entries = await fs.readdir(targetDir);
+    for (const entry of entries) {
+      // Only remove UCG-owned directories
+      if (UCG_SKILLS.has(entry)) {
+        await fs.remove(path.join(targetDir, entry));
+      }
+    }
+  } catch {
+    /* non-critical */
+  }
+}
+
+/**
+ * Remove all UCG skills from all known IDE directories.
+ * Used during uninstall.
+ */
+async function removeAllUcgSkills(projectDir) {
+  const config = loadPlatforms();
+  const removed = [];
+
+  for (const [, platform] of Object.entries(config.platforms)) {
+    if (!platform.installer?.target_dir) continue;
+    const targetDir = path.join(projectDir, platform.installer.target_dir);
+    if (await fs.pathExists(targetDir)) {
+      await cleanUcgSkills(targetDir);
+      // Also clean legacy targets
+      await cleanLegacyTargets(projectDir, platform);
+      removed.push(platform.installer.target_dir);
+    }
+  }
+
+  return removed;
+}
+
+module.exports = { installSkillsToIdes, getAvailablePlatforms, getDetectionMarkers, removeAllUcgSkills, loadPlatforms };