bi-superpowers 1.0.0

package/bin/commands/validate-projects.js

@@ -0,0 +1,426 @@
+/**
+ * Project Validation Command
+ * ==========================
+ *
+ * Validates public fixtures and private project references without copying
+ * customer repositories into this repo. Versioned descriptors live under
+ * validation/projects/*.json; private paths live in validation.local.json,
+ * which is intentionally ignored by git.
+ *
+ * Usage:
+ *   super validate-projects
+ *   super validate-projects --project base-template
+ *   super validate-projects --root C:\path\to\bi-superpowers
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_VALIDATION_DIR = 'validation';
+const DEFAULT_LOCAL_CONFIG = 'validation.local.json';
+
+function parseArgs(args) {
+  const options = {
+    rootDir: process.cwd(),
+    localConfigPath: null,
+    projectIds: [],
+    json: false,
+    list: false,
+    strict: false,
+  };
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+
+    if (arg === '--root') {
+      options.rootDir = readValue(args, ++index, arg);
+    } else if (arg === '--local') {
+      options.localConfigPath = readValue(args, ++index, arg);
+    } else if (arg === '--project' || arg === '-p') {
+      options.projectIds.push(readValue(args, ++index, arg));
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--list') {
+      options.list = true;
+    } else if (arg === '--strict') {
+      options.strict = true;
+    }
+  }
+
+  options.rootDir = path.resolve(options.rootDir);
+  if (options.localConfigPath) {
+    options.localConfigPath = path.resolve(options.localConfigPath);
+  }
+  return options;
+}
+
+function readValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function readJsonStrict(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Cannot read JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+function getValidationProjectsDir(rootDir) {
+  return path.join(rootDir, DEFAULT_VALIDATION_DIR, 'projects');
+}
+
+function getLocalConfigPath(rootDir, overridePath) {
+  return overridePath || path.join(rootDir, DEFAULT_LOCAL_CONFIG);
+}
+
+function loadProjectDescriptors(rootDir) {
+  const projectsDir = getValidationProjectsDir(rootDir);
+  if (!fs.existsSync(projectsDir)) {
+    throw new Error(
+      `Validation project descriptors not found at ${projectsDir}. ` +
+        'Run this command from the bi-superpowers source checkout or pass --root <repo>.'
+    );
+  }
+
+  const descriptorFiles = fs.readdirSync(projectsDir).filter(isDescriptorFile).sort();
+
+  if (descriptorFiles.length === 0) {
+    throw new Error(`No validation project descriptors found in ${projectsDir}.`);
+  }
+
+  return descriptorFiles.map((file) => {
+    const filePath = path.join(projectsDir, file);
+    const descriptor = readJsonStrict(filePath);
+    validateDescriptor(descriptor, filePath);
+    return { ...descriptor, descriptorPath: filePath };
+  });
+}
+
+function isDescriptorFile(file) {
+  return file.endsWith('.json') && !file.endsWith('.example.json');
+}
+
+function validateDescriptor(descriptor, filePath) {
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+    throw new Error(`Project descriptor must be an object: ${filePath}`);
+  }
+  if (!isValidProjectId(descriptor.id)) {
+    throw new Error(`Project descriptor has invalid id at ${filePath}`);
+  }
+  if (!descriptor.name || typeof descriptor.name !== 'string') {
+    throw new Error(`Project descriptor ${descriptor.id} must include a name`);
+  }
+  if (descriptor.path != null && typeof descriptor.path !== 'string') {
+    throw new Error(`Project descriptor ${descriptor.id} path must be a string`);
+  }
+  if (descriptor.path != null && path.isAbsolute(descriptor.path)) {
+    throw new Error(
+      `Project descriptor ${descriptor.id} path must be relative. Put private absolute paths in validation.local.json.`
+    );
+  }
+  if (descriptor.skills != null && !isStringArray(descriptor.skills)) {
+    throw new Error(`Project descriptor ${descriptor.id} skills must be an array of strings`);
+  }
+  if (descriptor.checks != null && !Array.isArray(descriptor.checks)) {
+    throw new Error(`Project descriptor ${descriptor.id} checks must be an array`);
+  }
+  for (const check of descriptor.checks || []) {
+    if (!check || typeof check !== 'object' || Array.isArray(check)) {
+      throw new Error(`Project descriptor ${descriptor.id} has an invalid check`);
+    }
+    if (!check.name || typeof check.name !== 'string') {
+      throw new Error(`Project descriptor ${descriptor.id} has a check without a name`);
+    }
+    if (!check.path || typeof check.path !== 'string') {
+      throw new Error(`Project descriptor ${descriptor.id} check ${check.name} needs a path`);
+    }
+    if (path.isAbsolute(check.path)) {
+      throw new Error(`Project descriptor ${descriptor.id} check ${check.name} must be relative`);
+    }
+  }
+}
+
+function isValidProjectId(value) {
+  return typeof value === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+function loadLocalConfig(rootDir, overridePath) {
+  const localPath = getLocalConfigPath(rootDir, overridePath);
+  if (!fs.existsSync(localPath)) {
+    return { path: localPath, projects: {} };
+  }
+
+  const config = readJsonStrict(localPath);
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`Local validation config must be an object: ${localPath}`);
+  }
+  if (config.projects == null) {
+    return { path: localPath, projects: {} };
+  }
+  if (typeof config.projects !== 'object' || Array.isArray(config.projects)) {
+    throw new Error(`Local validation config projects must be an object: ${localPath}`);
+  }
+
+  for (const [projectId, project] of Object.entries(config.projects)) {
+    if (!isValidProjectId(projectId)) {
+      throw new Error(`Local validation config has invalid project id: ${projectId}`);
+    }
+    if (!project || typeof project !== 'object' || Array.isArray(project)) {
+      throw new Error(`Local validation project ${projectId} must be an object`);
+    }
+    if (!project.path || typeof project.path !== 'string') {
+      throw new Error(`Local validation project ${projectId} must include a path`);
+    }
+  }
+
+  return { path: localPath, projects: config.projects };
+}
+
+function mergeProjects(descriptors, localProjects) {
+  const merged = new Map();
+
+  for (const descriptor of descriptors) {
+    const local = localProjects[descriptor.id] || {};
+    merged.set(descriptor.id, {
+      ...descriptor,
+      path: local.path || descriptor.path,
+      localOnly: false,
+      localNotes: local.notes,
+    });
+  }
+
+  for (const [id, local] of Object.entries(localProjects)) {
+    if (merged.has(id)) {
+      continue;
+    }
+    merged.set(id, {
+      id,
+      name: local.name || id,
+      privacy: 'private-local',
+      path: local.path,
+      skills: local.skills || [],
+      checks: local.checks || [],
+      localOnly: true,
+      localNotes: local.notes,
+    });
+  }
+
+  return Array.from(merged.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function resolveProjectPath(rootDir, projectPath) {
+  if (!projectPath) {
+    return null;
+  }
+  return path.isAbsolute(projectPath)
+    ? path.normalize(projectPath)
+    : path.resolve(rootDir, projectPath);
+}
+
+function validateProject(project, rootDir) {
+  const resolvedPath = resolveProjectPath(rootDir, project.path);
+  const result = {
+    id: project.id,
+    name: project.name,
+    privacy: project.privacy || 'unspecified',
+    path: resolvedPath,
+    status: 'passed',
+    reason: null,
+    checks: [],
+  };
+
+  if (!resolvedPath) {
+    result.status = 'skipped';
+    result.reason = 'No path configured. Add this project to validation.local.json.';
+    return result;
+  }
+
+  if (!fs.existsSync(resolvedPath)) {
+    result.status = 'failed';
+    result.reason = `Project path does not exist: ${resolvedPath}`;
+    return result;
+  }
+
+  for (const check of project.checks || []) {
+    const checkPath = path.resolve(resolvedPath, check.path);
+    if (!isPathInside(resolvedPath, checkPath)) {
+      result.checks.push({
+        name: check.name,
+        path: checkPath,
+        passed: false,
+        reason: 'Check path escapes the project root.',
+      });
+      continue;
+    }
+    const passed = fs.existsSync(checkPath);
+    result.checks.push({
+      name: check.name,
+      path: checkPath,
+      passed,
+    });
+  }
+
+  if (result.checks.some((check) => !check.passed)) {
+    result.status = 'failed';
+    result.reason = 'One or more required project files are missing.';
+  }
+
+  return result;
+}
+
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function runValidation(options) {
+  const descriptors = loadProjectDescriptors(options.rootDir);
+  const localConfig = loadLocalConfig(options.rootDir, options.localConfigPath);
+  const projects = mergeProjects(descriptors, localConfig.projects);
+  const selected = filterProjects(projects, options.projectIds);
+  const results = selected.projects.map((project) => validateProject(project, options.rootDir));
+
+  if (options.strict) {
+    for (const result of results) {
+      if (result.status === 'skipped') {
+        result.status = 'failed';
+        result.reason = `${result.reason} Strict mode treats skipped projects as failures.`;
+      }
+    }
+  }
+
+  return {
+    rootDir: options.rootDir,
+    localConfigPath: localConfig.path,
+    missingProjectIds: selected.missingProjectIds,
+    results,
+    summary: summarizeResults(results, selected.missingProjectIds),
+  };
+}
+
+function filterProjects(projects, ids) {
+  if (ids.length === 0) {
+    return { projects, missingProjectIds: [] };
+  }
+
+  const byId = new Map(projects.map((project) => [project.id, project]));
+  const selected = [];
+  const missingProjectIds = [];
+
+  for (const id of ids) {
+    if (byId.has(id)) {
+      selected.push(byId.get(id));
+    } else {
+      missingProjectIds.push(id);
+    }
+  }
+
+  return { projects: selected, missingProjectIds };
+}
+
+function summarizeResults(results, missingProjectIds = []) {
+  return {
+    total: results.length,
+    passed: results.filter((result) => result.status === 'passed').length,
+    failed:
+      results.filter((result) => result.status === 'failed').length + missingProjectIds.length,
+    skipped: results.filter((result) => result.status === 'skipped').length,
+  };
+}
+
+function printList(report) {
+  console.log('BI Agent Superpowers — Validation Projects');
+  console.log('==========================================\n');
+
+  if (report.results.length === 0) {
+    console.log('No project descriptors found.');
+    return;
+  }
+
+  for (const result of report.results) {
+    console.log(`- ${result.id}: ${result.name} (${result.privacy})`);
+  }
+}
+
+function printReport(report) {
+  console.log('BI Agent Superpowers — Project Validation');
+  console.log('=========================================\n');
+  console.log(`Root: ${report.rootDir}`);
+  console.log(`Local config: ${report.localConfigPath}`);
+  console.log('');
+
+  for (const missingId of report.missingProjectIds) {
+    console.log(`FAIL ${missingId}`);
+    console.log('  Project id was requested but no descriptor or local config exists.\n');
+  }
+
+  for (const result of report.results) {
+    const label = result.status.toUpperCase();
+    console.log(`${label} ${result.id} — ${result.name}`);
+    if (result.path) {
+      console.log(`  Path: ${result.path}`);
+    }
+    if (result.reason) {
+      console.log(`  ${result.reason}`);
+    }
+    for (const check of result.checks) {
+      const checkLabel = check.passed ? 'OK' : 'MISS';
+      console.log(`  ${checkLabel} ${check.name}: ${check.path}`);
+    }
+    console.log('');
+  }
+
+  const summary = report.summary;
+  console.log(
+    `Summary: ${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped (${summary.total} checked)`
+  );
+}
+
+function validateProjectsCommand(args) {
+  let options;
+  try {
+    options = parseArgs(args || []);
+    const report = runValidation(options);
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else if (options.list) {
+      printList(report);
+    } else {
+      printReport(report);
+    }
+
+    if (report.summary.failed > 0) {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    if (options && options.json) {
+      console.log(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+module.exports = Object.assign(validateProjectsCommand, {
+  parseArgs,
+  readJsonStrict,
+  loadProjectDescriptors,
+  loadLocalConfig,
+  mergeProjects,
+  resolveProjectPath,
+  validateProject,
+  isPathInside,
+  runValidation,
+  summarizeResults,
+});

package/bin/commands/watch.js

@@ -0,0 +1,251 @@
+/**
+ * Watch Command (sentinel)
+ * ========================
+ * Watches for changes in skills and auto-regenerates the Claude Code plugin
+ * plus any configured legacy adapters.
+ *
+ * Usage:
+ *   super sentinel                      Watch all configured outputs
+ *   super sentinel --tool claude-plugin Watch a specific output only
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tui = require('../utils/tui');
+
+// Try to require chokidar, but handle if not available
+let chokidar;
+try {
+  chokidar = require('chokidar');
+} catch (e) {
+  chokidar = null;
+}
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - CLI arguments
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args) {
+  const options = {
+    tool: null, // null means all configured outputs
+    targetDir: process.cwd(),
+    debounce: 500, // ms
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--tool' || arg === '-t') {
+      options.tool = args[++i];
+    } else if (arg === '--debounce') {
+      options.debounce = parseInt(args[++i], 10) || 500;
+    } else if (!arg.startsWith('-')) {
+      options.targetDir = arg;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Chokidar v4 no longer supports glob paths. Watch the skill root and filter
+ * relevant runtime/source files in-process so folder-based skills are covered.
+ *
+ * @param {string} skillsDir - Directory containing skill sources
+ * @returns {string[]} Watch roots
+ */
+function getWatchRoots(skillsDir) {
+  return [skillsDir];
+}
+
+/**
+ * @param {string} changedPath - Changed file path
+ * @param {string} skillsDir - Watched skill root
+ * @returns {boolean} Whether the changed file should trigger regeneration
+ */
+function isRelevantSkillPath(changedPath, skillsDir) {
+  const relative = path.relative(skillsDir, changedPath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return false;
+  }
+
+  const base = path.basename(changedPath);
+  if (
+    base.endsWith('.test.js') ||
+    base.endsWith('.spec.js') ||
+    base.endsWith('.bak') ||
+    base.endsWith('.tmp') ||
+    base.startsWith('.')
+  ) {
+    return false;
+  }
+
+  return ['.md', '.js', '.json', '.sh'].includes(path.extname(changedPath));
+}
+
+/**
+ * Main watch command handler
+ * @param {string[]} args - Command arguments
+ * @param {Object} config - CLI configuration with paths
+ * @param {Object} cliModule - Reference to main CLI module for regeneration
+ */
+function watchCommand(args, config, cliModule) {
+  if (!chokidar) {
+    tui.error('Watch mode requires the chokidar package.');
+    tui.info('Install dependencies with: npm install');
+    process.exit(1);
+  }
+
+  const options = parseArgs(args);
+  const skillsDir = config.skillsDir;
+  const targetDir = options.targetDir;
+
+  if (!fs.existsSync(skillsDir)) {
+    tui.error('Skills directory not found. Try reinstalling: npm install -g bi-superpowers');
+    process.exit(1);
+  }
+
+  tui.header('BI Agent Superpowers', 'Watch Mode');
+
+  tui.info(`Watching: ${skillsDir}`);
+  tui.info(`Target: ${targetDir}`);
+  if (options.tool) {
+    tui.info(`Tool: ${options.tool}`);
+  } else {
+    tui.info('Tool: All configured tools');
+  }
+
+  console.log('');
+  tui.muted('Press Ctrl+C to stop watching');
+  console.log('');
+
+  // Debounce timer
+  let debounceTimer = null;
+  const pendingChanges = new Set();
+
+  // Create watcher
+  const watcher = chokidar.watch(getWatchRoots(skillsDir), {
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 200,
+      pollInterval: 100,
+    },
+  });
+
+  /**
+   * Handle file change
+   * @param {string} changedPath - Path to changed file
+   * @param {string} eventType - Type of event (add, change, unlink)
+   */
+  function handleChange(changedPath, _eventType) {
+    if (!isRelevantSkillPath(changedPath, skillsDir)) {
+      return;
+    }
+
+    const filename = path.relative(skillsDir, changedPath);
+    pendingChanges.add(filename);
+
+    // Clear existing timer
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    // Set new timer
+    debounceTimer = setTimeout(() => {
+      const changes = Array.from(pendingChanges);
+      pendingChanges.clear();
+
+      const timestamp = new Date().toLocaleTimeString();
+      console.log(`\n${tui.colors.muted(`[${timestamp}]`)} ${tui.icons.watch} Changes detected:`);
+      changes.forEach((file) => {
+        console.log(`  ${tui.icons.bullet} ${tui.colors.info(file)}`);
+      });
+
+      // Trigger regeneration
+      regenerateConfigs(targetDir, options.tool, cliModule);
+    }, options.debounce);
+  }
+
+  // Watch events
+  watcher
+    .on('add', (path) => handleChange(path, 'add'))
+    .on('change', (path) => handleChange(path, 'change'))
+    .on('unlink', (path) => handleChange(path, 'unlink'))
+    .on('error', (error) => {
+      tui.error(`Watcher error: ${error.message}`);
+    })
+    .on('ready', () => {
+      tui.success('Watching for changes...');
+    });
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n');
+    tui.info('Stopping watch mode...');
+    watcher.close();
+    process.exit(0);
+  });
+}
+
+/**
+ * Regenerate configs after changes detected
+ * @param {string} targetDir - Target directory
+ * @param {string|null} specificTool - Specific tool or null for all
+ * @param {Object} cliModule - CLI module reference
+ */
+async function regenerateConfigs(targetDir, specificTool, cliModule) {
+  const ora = require('ora');
+  const spinner = ora('Regenerating configs...').start();
+
+  try {
+    // Load the saved tool config
+    const configPath = path.join(targetDir, '.bi-superpowers.json');
+    let tools = ['claude-plugin'];
+
+    if (fs.existsSync(configPath)) {
+      try {
+        const savedConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (savedConfig.tools) {
+          tools = savedConfig.tools;
+        }
+      } catch (e) {
+        // Ignore parse errors, use defaults
+      }
+    }
+
+    if (!tools.includes('claude-plugin')) {
+      tools = ['claude-plugin', ...tools];
+    }
+
+    // Filter to specific tool if requested
+    if (specificTool) {
+      tools = tools.filter((t) => t === specificTool);
+    }
+
+    if (tools.length === 0) {
+      spinner.warn('No tools configured');
+      return;
+    }
+
+    // Call the sync logic from CLI module
+    if (cliModule && typeof cliModule.syncProjectInternal === 'function') {
+      await cliModule.syncProjectInternal(targetDir, tools);
+      spinner.succeed(`Regenerated configs for: ${tools.join(', ')}`);
+    } else {
+      // Fallback: just report what would be done
+      spinner.succeed(`Would regenerate configs for: ${tools.join(', ')}`);
+      tui.muted('Note: Run "super recharge" manually to apply changes');
+    }
+  } catch (error) {
+    spinner.fail(`Regeneration failed: ${error.message}`);
+  }
+}
+
+module.exports = Object.assign(watchCommand, {
+  parseArgs,
+  getWatchRoots,
+  isRelevantSkillPath,
+  regenerateConfigs,
+});