@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/verifiers/agents.js

@@ -0,0 +1,245 @@
+/**
+ * Agents Verifier - Dynamic agent validation using versions.json as source of truth
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createCheck, createResult, SEVERITY } = require('../lib/verify-formatter');
+const { getPluginRoot } = require('./plugin');
+
+const NAME = 'Agents';
+
+/**
+ * Load versions.json registry
+ */
+function loadRegistry() {
+  const pluginRoot = getPluginRoot();
+  const versionsPath = path.join(pluginRoot, 'config', 'versions.json');
+
+  try {
+    const content = fs.readFileSync(versionsPath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get active agents from registry
+ */
+function getRegisteredAgents(versions) {
+  if (!versions || !versions.agents) return [];
+
+  return Object.entries(versions.agents)
+    .filter(([, info]) => info.status === 'active')
+    .map(([name]) => name);
+}
+
+/**
+ * Get agents directory path
+ */
+function getAgentsDir() {
+  const pluginRoot = getPluginRoot();
+
+  // Check multiple possible locations
+  const locations = [
+    path.join(pluginRoot, 'agents'),
+    path.join(pluginRoot, '..', 'agents'),
+    path.join(process.cwd(), 'agents'),
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc)) {
+      return loc;
+    }
+  }
+
+  return path.join(pluginRoot, 'agents');
+}
+
+/**
+ * Get existing agent files
+ */
+function getExistingAgents() {
+  const agentsDir = getAgentsDir();
+
+  if (!fs.existsSync(agentsDir)) return [];
+
+  return fs
+    .readdirSync(agentsDir)
+    .filter((f) => f.endsWith('.md') && f !== 'INDEX.md')
+    .map((f) => f.replace('.md', ''));
+}
+
+/**
+ * Check registry vs disk bidirectionally
+ */
+function checkRegistrySync() {
+  const versions = loadRegistry();
+  const checks = [];
+
+  if (!versions) {
+    return [
+      createCheck('Agents registry', false, {
+        severity: SEVERITY.WARNING,
+        message: 'cannot load versions.json',
+        remediation: 'Fix or create config/versions.json',
+      }),
+    ];
+  }
+
+  const registered = getRegisteredAgents(versions);
+  const existing = getExistingAgents();
+
+  // Check: All registered agents exist on disk
+  const missing = registered.filter((a) => !existing.includes(a));
+  if (missing.length > 0) {
+    checks.push(
+      createCheck('Registered agents exist', false, {
+        severity: SEVERITY.WARNING,
+        message: `missing: ${missing.slice(0, 3).join(', ')}${missing.length > 3 ? '...' : ''}`,
+        remediation: `Create missing agent files or update versions.json`,
+      })
+    );
+  } else {
+    checks.push(
+      createCheck('Registered agents exist', true, {
+        message: `${registered.length} verified`,
+      })
+    );
+  }
+
+  // Check: All existing agents are registered
+  const unregistered = existing.filter((a) => !registered.includes(a));
+  if (unregistered.length > 0) {
+    checks.push(
+      createCheck('Agents are registered', false, {
+        severity: SEVERITY.WARNING,
+        message: `unregistered: ${unregistered.slice(0, 3).join(', ')}${unregistered.length > 3 ? '...' : ''}`,
+        remediation: `Add agents to versions.json or remove files`,
+      })
+    );
+  } else {
+    checks.push(
+      createCheck('Agents are registered', true, {
+        message: `${existing.length} on disk`,
+      })
+    );
+  }
+
+  return checks;
+}
+
+/**
+ * Parse YAML frontmatter from markdown
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      const value = line.slice(colonIndex + 1).trim();
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Check agents have valid frontmatter
+ */
+function checkAgentFrontmatter() {
+  const agentsDir = getAgentsDir();
+  const checks = [];
+
+  if (!fs.existsSync(agentsDir)) {
+    return [
+      createCheck('Agent frontmatter', false, {
+        severity: SEVERITY.WARNING,
+        message: 'agents/ directory not found',
+      }),
+    ];
+  }
+
+  const agentFiles = fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md') && f !== 'INDEX.md');
+
+  let validCount = 0;
+  let invalidAgents = [];
+
+  for (const file of agentFiles) {
+    const filePath = path.join(agentsDir, file);
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const frontmatter = parseFrontmatter(content);
+
+      if (!frontmatter) {
+        invalidAgents.push({ file, reason: 'no frontmatter' });
+      } else if (!frontmatter.name) {
+        invalidAgents.push({ file, reason: 'missing name' });
+      } else if (!frontmatter.model) {
+        invalidAgents.push({ file, reason: 'missing model' });
+      } else {
+        validCount++;
+      }
+    } catch {
+      invalidAgents.push({ file, reason: 'read error' });
+    }
+  }
+
+  if (invalidAgents.length > 0) {
+    const examples = invalidAgents.slice(0, 2).map((a) => `${a.file} (${a.reason})`);
+    checks.push(
+      createCheck('Agent frontmatter', false, {
+        severity: SEVERITY.WARNING,
+        message: `${invalidAgents.length} invalid`,
+        remediation: `Fix: ${examples.join(', ')}${invalidAgents.length > 2 ? '...' : ''}`,
+      })
+    );
+  } else {
+    checks.push(
+      createCheck('Agent frontmatter', true, {
+        message: `${validCount} valid`,
+      })
+    );
+  }
+
+  return checks;
+}
+
+/**
+ * Check INDEX.md exists
+ */
+function checkIndexFile() {
+  const agentsDir = getAgentsDir();
+  const indexPath = path.join(agentsDir, 'INDEX.md');
+
+  if (fs.existsSync(indexPath)) {
+    return createCheck('INDEX.md', true, {
+      message: 'found',
+    });
+  }
+
+  return createCheck('INDEX.md', false, {
+    severity: SEVERITY.WARNING,
+    message: 'not found',
+    remediation: 'Create agents/INDEX.md listing all agents',
+  });
+}
+
+/**
+ * Run all agents checks
+ */
+function verify() {
+  const checks = [...checkRegistrySync(), ...checkAgentFrontmatter(), checkIndexFile()];
+
+  return createResult(NAME, checks);
+}
+
+module.exports = { verify, NAME };

package/scripts/verifiers/config.js

@@ -0,0 +1,186 @@
+/**
+ * Config Verifier - JSON configuration file validation
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createCheck, createResult, SEVERITY } = require('../lib/verify-formatter');
+const { getPluginRoot } = require('./plugin');
+
+const NAME = 'Config';
+
+/**
+ * Check a JSON config file
+ */
+function checkConfigFile(name, filePath, requiredFields = []) {
+  if (!fs.existsSync(filePath)) {
+    return createCheck(name, false, {
+      severity: SEVERITY.WARNING,
+      message: 'not found',
+      remediation: `Create ${name} configuration file`,
+    });
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const config = JSON.parse(content);
+
+    // Check required fields
+    const missingFields = requiredFields.filter((field) => !config[field]);
+    if (missingFields.length > 0) {
+      return createCheck(name, false, {
+        severity: SEVERITY.WARNING,
+        message: `missing: ${missingFields.join(', ')}`,
+        remediation: `Add missing fields to ${name}`,
+      });
+    }
+
+    return createCheck(name, true, {
+      message: 'valid',
+    });
+  } catch (err) {
+    return createCheck(name, false, {
+      severity: SEVERITY.CRITICAL,
+      message: 'JSON parse error',
+      remediation: `Fix JSON syntax in ${name}`,
+    });
+  }
+}
+
+/**
+ * Check versions.json (critical - source of truth)
+ */
+function checkVersionsJson() {
+  const pluginRoot = getPluginRoot();
+  const configPath = path.join(pluginRoot, 'config', 'versions.json');
+
+  const check = checkConfigFile('versions.json', configPath, ['skills', 'agents']);
+
+  if (check.passed) {
+    try {
+      const content = fs.readFileSync(configPath, 'utf8');
+      const config = JSON.parse(content);
+      const skillCount = Object.keys(config.skills || {}).length;
+      const agentCount = Object.keys(config.agents || {}).length;
+      check.message = `${skillCount} skills, ${agentCount} agents`;
+    } catch {
+      // Already handled
+    }
+  } else {
+    check.severity = SEVERITY.CRITICAL;
+  }
+
+  return check;
+}
+
+/**
+ * Check quality-gates.json
+ */
+function checkQualityGatesJson() {
+  const pluginRoot = getPluginRoot();
+  const configPath = path.join(pluginRoot, 'config', 'quality-gates.json');
+
+  const check = checkConfigFile('quality-gates.json', configPath, ['gates']);
+
+  if (check.passed) {
+    try {
+      const content = fs.readFileSync(configPath, 'utf8');
+      const config = JSON.parse(content);
+      const gateCount = Object.keys(config.gates || {}).length;
+      check.message = `${gateCount} gates defined`;
+    } catch {
+      // Already handled
+    }
+  }
+
+  return check;
+}
+
+/**
+ * Check for .env in repo root (should not exist)
+ */
+function checkNoEnvInRepo() {
+  const pluginRoot = getPluginRoot();
+  // Check both plugin root and parent
+  const envLocations = [
+    path.join(pluginRoot, '.env'),
+    path.join(pluginRoot, '..', '.env'),
+    path.join(pluginRoot, '.env.local'),
+    path.join(pluginRoot, '..', '.env.local'),
+  ];
+
+  for (const envPath of envLocations) {
+    if (fs.existsSync(envPath)) {
+      return createCheck('No .env in repo', false, {
+        severity: SEVERITY.CRITICAL,
+        message: 'found .env file',
+        remediation: 'Remove .env from repo and add to .gitignore',
+      });
+    }
+  }
+
+  return createCheck('No .env in repo', true, {
+    message: 'clean',
+  });
+}
+
+/**
+ * Check other config files
+ */
+function checkOtherConfigs() {
+  const pluginRoot = getPluginRoot();
+  const configDir = path.join(pluginRoot, 'config');
+  const checks = [];
+
+  const optionalConfigs = [
+    'aggregation.json',
+    'asset-value.json',
+    'onboarding-milestones.json',
+    'prompt-router.json',
+    'shared-knowledge.json',
+  ];
+
+  if (!fs.existsSync(configDir)) {
+    return [
+      createCheck('config/ directory', false, {
+        severity: SEVERITY.WARNING,
+        message: 'not found',
+      }),
+    ];
+  }
+
+  for (const configName of optionalConfigs) {
+    const configPath = path.join(configDir, configName);
+    if (fs.existsSync(configPath)) {
+      const check = checkConfigFile(configName, configPath);
+      checks.push(check);
+    }
+  }
+
+  // Summary if no optional configs checked
+  if (checks.length === 0) {
+    checks.push(
+      createCheck('Optional configs', true, {
+        message: 'none present (ok)',
+      })
+    );
+  }
+
+  return checks;
+}
+
+/**
+ * Run all config checks
+ */
+function verify() {
+  const checks = [
+    checkVersionsJson(),
+    checkQualityGatesJson(),
+    checkNoEnvInRepo(),
+    ...checkOtherConfigs(),
+  ];
+
+  return createResult(NAME, checks);
+}
+
+module.exports = { verify, NAME };

package/scripts/verifiers/environment.js

@@ -0,0 +1,123 @@
+/**
+ * Environment Verifier - System prerequisites check
+ */
+
+const { execSync } = require('child_process');
+const { createCheck, createResult, SEVERITY } = require('../lib/verify-formatter');
+const { commandExists } = require('../lib/utils');
+
+const NAME = 'Environment';
+
+/**
+ * Check Node.js version (requires >= 18)
+ */
+function checkNodeVersion() {
+  const version = process.versions.node;
+  const major = parseInt(version.split('.')[0], 10);
+  const passed = major >= 18;
+
+  return createCheck('Node.js', passed, {
+    message: `v${version}`,
+    severity: passed ? SEVERITY.INFO : SEVERITY.CRITICAL,
+    remediation: 'Install Node.js 18+ from https://nodejs.org',
+  });
+}
+
+/**
+ * Check Git is installed
+ */
+function checkGit() {
+  try {
+    const version = execSync('git --version', { encoding: 'utf8' }).trim();
+    const match = version.match(/(\d+\.\d+\.\d+)/);
+    return createCheck('Git', true, {
+      message: match ? `v${match[1]}` : 'installed',
+    });
+  } catch {
+    return createCheck('Git', false, {
+      severity: SEVERITY.CRITICAL,
+      remediation: 'Install Git from https://git-scm.com',
+    });
+  }
+}
+
+/**
+ * Check package manager availability
+ */
+function checkPackageManager() {
+  const managers = ['npm', 'yarn', 'pnpm', 'bun'];
+  let found = null;
+
+  for (const manager of managers) {
+    if (commandExists(manager)) {
+      found = manager;
+      break;
+    }
+  }
+
+  if (found) {
+    return createCheck('Package Manager', true, {
+      message: found,
+    });
+  }
+
+  return createCheck('Package Manager', false, {
+    severity: SEVERITY.CRITICAL,
+    remediation: 'Install Node.js (includes npm) from https://nodejs.org',
+  });
+}
+
+/**
+ * Check Git user.email is configured
+ */
+function checkGitEmail() {
+  try {
+    const email = execSync('git config user.email', { encoding: 'utf8' }).trim();
+    return createCheck('Git user.email', !!email, {
+      message: email ? 'configured' : 'not set',
+      severity: email ? SEVERITY.INFO : SEVERITY.WARNING,
+      remediation: 'git config --global user.email "you@example.com"',
+    });
+  } catch {
+    return createCheck('Git user.email', false, {
+      severity: SEVERITY.WARNING,
+      remediation: 'git config --global user.email "you@example.com"',
+    });
+  }
+}
+
+/**
+ * Check Git user.name is configured
+ */
+function checkGitName() {
+  try {
+    const name = execSync('git config user.name', { encoding: 'utf8' }).trim();
+    return createCheck('Git user.name', !!name, {
+      message: name ? 'configured' : 'not set',
+      severity: name ? SEVERITY.INFO : SEVERITY.WARNING,
+      remediation: 'git config --global user.name "Your Name"',
+    });
+  } catch {
+    return createCheck('Git user.name', false, {
+      severity: SEVERITY.WARNING,
+      remediation: 'git config --global user.name "Your Name"',
+    });
+  }
+}
+
+/**
+ * Run all environment checks
+ */
+function verify() {
+  const checks = [
+    checkNodeVersion(),
+    checkGit(),
+    checkPackageManager(),
+    checkGitEmail(),
+    checkGitName(),
+  ];
+
+  return createResult(NAME, checks);
+}
+
+module.exports = { verify, NAME };