opencode-auto-agent 1.0.0 → 1.2.0

package/src/commands/doctor.js

@@ -1,91 +1,374 @@
 /**
- * doctor command — validate configuration and tool availability.
+ * doctor command — validate configuration, tools, model assignments, and
+ * full alignment with the OpenCode agent/tool/rule ecosystem.
+ *
+ * Checks:
+ *  1. Prerequisites (node, opencode, ralphy, git)
+ *  2. Scaffold directory structure (.opencode/)
+ *  3. config.json schema & version
+ *  4. Model assignments exist and are still available via `opencode models`
+ *  5. opencode.json alignment (agents, model, instructions)
+ *  6. Agent markdown files (frontmatter, model field)
+ *  7. Rules and presets
+ *  8. Ralphy config
+ *  9. Tasks/PRD file
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { execSync } from "node:child_process";
 
-import { SCAFFOLD_DIR, CONFIG_FILE, DIRS, AGENTS, PRESETS } from "../lib/constants.js";
+import {
+  SCAFFOLD_DIR, CONFIG_FILE, DIRS, AGENTS, AGENT_ROLES,
+  PRESETS, SCHEMA_VERSION,
+} from "../lib/constants.js";
 import { readJsonSync } from "../lib/fs-utils.js";
+import { validatePrerequisites } from "../lib/prerequisites.js";
+import { discoverModels, findModel } from "../lib/models.js";
+import {
+  banner, section, status, kv, error, warn, success, c, table, hr,
+  createSpinner,
+} from "../lib/ui.js";
+
+/**
+ * @param {string} targetDir - Project root
+ * @param {Object} opts
+ * @param {boolean} [opts.verbose] - Show extra detail
+ */
+export async function doctor(targetDir, { verbose = false } = {}) {
+  banner("OpenCode Auto-Agent Doctor", "Validating project configuration");
 
-export async function doctor(targetDir) {
-  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
   let errors = 0;
   let warnings = 0;
 
-  console.log("[doctor] Checking opencode-auto-agent configuration...\n");
+  const pass = (label, detail) => { status("pass", label, detail); };
+  const fail = (label, detail) => { status("fail", label, detail); errors++; };
+  const softWarn = (label, detail) => { status("warn", label, detail); warnings++; };
+
+  // ── 1. Prerequisites ──────────────────────────────────────────────────────
+  section("Prerequisites");
+  const prereqs = validatePrerequisites({ requireRalphy: false });
+
+  for (const ch of prereqs.checks) {
+    if (ch.ok) {
+      pass(ch.name, `v${ch.version}`);
+    } else if (ch.name.startsWith("Node") || ch.name.startsWith("OpenCode")) {
+      fail(ch.name, "not found");
+      console.log(`          ${c.gray(ch.hint)}`);
+    } else {
+      softWarn(ch.name, "not found (optional)");
+      console.log(`          ${c.gray(ch.hint)}`);
+    }
+  }
+
+  // ── 2. Scaffold directory ─────────────────────────────────────────────────
+  section("Project Structure");
+  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
+
+  if (!existsSync(scaffoldDir)) {
+    fail(`${SCAFFOLD_DIR}/ directory`, "not found");
+    error(
+      `No ${SCAFFOLD_DIR}/ directory found.`,
+      "Run 'npx opencode-auto-agent init' to scaffold the project."
+    );
+    printSummary(errors, warnings);
+    return;
+  }
+  pass(`${SCAFFOLD_DIR}/ directory`, "exists");
 
-  // 1. Scaffold directory exists
-  check("Scaffold directory", existsSync(scaffoldDir), `${SCAFFOLD_DIR}/ not found. Run 'opencode-auto-agent init'.`);
+  // Check subdirectories
+  for (const [key, sub] of Object.entries(DIRS)) {
+    const subPath = join(scaffoldDir, sub);
+    if (existsSync(subPath)) {
+      const count = safeReaddir(subPath).length;
+      pass(`${SCAFFOLD_DIR}/${sub}/`, `${count} file(s)`);
+    } else {
+      fail(`${SCAFFOLD_DIR}/${sub}/`, "missing");
+    }
+  }
 
-  // 2. Config file
+  // ── 3. config.json ────────────────────────────────────────────────────────
+  section("Configuration");
   const configPath = join(scaffoldDir, CONFIG_FILE);
   const config = readJsonSync(configPath);
-  check("Config file", !!config, `${CONFIG_FILE} missing or invalid JSON.`);
 
-  if (config) {
-    // 3. Preset is valid
-    const presetFile = join(scaffoldDir, DIRS.presets, `${config.preset}.md`);
-    check(`Preset "${config.preset}"`, existsSync(presetFile), `Preset file not found: presets/${config.preset}.md`);
+  if (!config) {
+    fail(CONFIG_FILE, "missing or invalid JSON");
+  } else {
+    pass(CONFIG_FILE, "valid JSON");
 
-    // 4. Task file exists
+    // Schema version
+    if (config.version === SCHEMA_VERSION) {
+      pass("Config version", `v${config.version}`);
+    } else if (config.version) {
+      softWarn("Config version", `v${config.version} (current: ${SCHEMA_VERSION})`);
+    } else {
+      softWarn("Config version", "missing (expected " + SCHEMA_VERSION + ")");
+    }
+
+    // Preset
+    if (config.preset) {
+      const presetFile = join(scaffoldDir, DIRS.presets, `${config.preset}.md`);
+      if (existsSync(presetFile)) {
+        pass(`Preset "${config.preset}"`, "file found");
+      } else {
+        fail(`Preset "${config.preset}"`, `presets/${config.preset}.md not found`);
+      }
+    } else {
+      softWarn("Preset", "not set in config");
+    }
+
+    // Models section
+    if (config.models && typeof config.models === "object") {
+      pass("Models mapping", `${Object.keys(config.models).length} agent(s) configured`);
+    } else {
+      softWarn("Models mapping", "missing from config (legacy v0.1.0 format?)");
+    }
+
+    // Agents section
+    if (config.agents && typeof config.agents === "object") {
+      const enabledCount = Object.values(config.agents).filter((a) => a.enabled).length;
+      pass("Agents config", `${enabledCount}/${Object.keys(config.agents).length} enabled`);
+    } else {
+      softWarn("Agents config", "missing from config");
+    }
+
+    // Paths
     const tasksPath = join(targetDir, config.tasksPath || "PRD.md");
-    warn(`Tasks file (${config.tasksPath || "PRD.md"})`, existsSync(tasksPath), "Create a PRD.md or update tasksPath in config.");
-  }
+    if (existsSync(tasksPath)) {
+      pass("Tasks file", config.tasksPath || "PRD.md");
+    } else {
+      softWarn("Tasks file", `${config.tasksPath || "PRD.md"} not found`);
+    }
 
-  // 5. Agent markdowns
-  for (const agent of AGENTS) {
-    const agentFile = join(scaffoldDir, DIRS.agents, `${agent}.md`);
-    check(`Agent: ${agent}`, existsSync(agentFile), `Missing agent definition: agents/${agent}.md`);
+    const docsPath = join(targetDir, config.docsPath || "Docs");
+    if (existsSync(docsPath)) {
+      pass("Docs directory", config.docsPath || "Docs");
+    } else {
+      softWarn("Docs directory", `${config.docsPath || "Docs"} not found (optional)`);
+    }
   }
 
-  // 6. Rules
-  const rulesDir = join(scaffoldDir, DIRS.rules, "universal.md");
-  check("Universal rules", existsSync(rulesDir), "Missing rules/universal.md");
-
-  // 7. External tools
-  checkTool("ralphy", "npm install -g ralphy-cli");
-  checkTool("opencode", "npm install -g opencode-ai");
+  // ── 4. Model validation against live discovery ────────────────────────────
+  section("Model Validation");
 
-  // 8. OpenCode config
-  const ocConfig = join(targetDir, "opencode.json");
-  warn("opencode.json", existsSync(ocConfig), "Run 'opencode-auto-agent init' to generate it.");
+  if (config && config.models) {
+    const spinner = createSpinner("Checking model availability via opencode...");
+    spinner.start();
+    const availableModels = discoverModels();
+    if (availableModels.length === 0) {
+      spinner.fail("Could not discover models (opencode may not be configured)");
+      softWarn("Model validation", "skipped — no models discovered");
+    } else {
+      spinner.stop(`Discovered ${availableModels.length} models`);
 
-  console.log("\n[doctor] ─────────────────────────────────────────");
-  if (errors === 0 && warnings === 0) {
-    console.log("[doctor] All checks passed.");
+      for (const [role, modelId] of Object.entries(config.models)) {
+        const found = findModel(availableModels, modelId);
+        if (found) {
+          pass(`${padRole(role)} ${c.cyan(modelId)}`, "available");
+        } else {
+          fail(`${padRole(role)} ${c.cyan(modelId)}`, "NOT available from opencode");
+        }
+      }
+    }
   } else {
-    console.log(`[doctor] ${errors} error(s), ${warnings} warning(s).`);
+    softWarn("Model validation", "skipped — no models mapping in config");
   }
 
-  // ── helpers ──────────────────────────────────────────────────────────────
+  // ── 5. opencode.json ──────────────────────────────────────────────────────
+  section("OpenCode Integration");
+  const opencodeConfigPath = join(targetDir, "opencode.json");
+  const opencodeConfig = readJsonSync(opencodeConfigPath);
+
+  if (!opencodeConfig) {
+    fail("opencode.json", "missing or invalid");
+  } else {
+    pass("opencode.json", "valid JSON");
+
+    // $schema field
+    if (opencodeConfig.$schema) {
+      pass("$schema", opencodeConfig.$schema);
+    } else {
+      softWarn("$schema", "missing (recommended: https://opencode.ai/config.json)");
+    }
 
-  function check(label, ok, hint) {
-    if (ok) {
-      console.log(`  [pass] ${label}`);
+    // Root model
+    if (opencodeConfig.model) {
+      pass("Root model", opencodeConfig.model);
     } else {
-      console.log(`  [FAIL] ${label} — ${hint}`);
-      errors++;
+      softWarn("Root model", "not set in opencode.json");
+    }
+
+    // Instructions
+    if (Array.isArray(opencodeConfig.instructions) && opencodeConfig.instructions.length > 0) {
+      pass("Instructions", `${opencodeConfig.instructions.length} file(s)`);
+    } else {
+      softWarn("Instructions", "none configured");
+    }
+
+    // Agent definitions
+    if (opencodeConfig.agent && typeof opencodeConfig.agent === "object") {
+      const agentNames = Object.keys(opencodeConfig.agent);
+      pass("Agent definitions", `${agentNames.length} agent(s)`);
+
+      // Cross-check with AGENTS constant
+      for (const role of AGENTS) {
+        const agentDef = opencodeConfig.agent[role];
+        if (!agentDef) {
+          softWarn(`Agent "${role}"`, "missing from opencode.json");
+          continue;
+        }
+        const issues = [];
+        if (!agentDef.model) issues.push("no model");
+        if (!agentDef.mode) issues.push("no mode");
+        if (!agentDef.description) issues.push("no description");
+        if (issues.length > 0) {
+          softWarn(`Agent "${role}"`, issues.join(", "));
+        } else if (verbose) {
+          pass(`Agent "${role}"`, `${agentDef.mode} / ${agentDef.model}`);
+        }
+      }
+
+      // Check model consistency between config.json and opencode.json
+      if (config && config.models) {
+        let mismatches = 0;
+        for (const role of AGENTS) {
+          const configModel = config.models[role];
+          const ocModel = opencodeConfig.agent[role]?.model;
+          if (configModel && ocModel && configModel !== ocModel) {
+            softWarn(
+              `Model mismatch: ${role}`,
+              `config.json=${configModel} vs opencode.json=${ocModel}`
+            );
+            mismatches++;
+          }
+        }
+        if (mismatches === 0) {
+          pass("Model consistency", "config.json and opencode.json agree");
+        }
+      }
+    } else {
+      fail("Agent definitions", "no 'agent' section in opencode.json");
     }
   }
 
-  function warn(label, ok, hint) {
-    if (ok) {
-      console.log(`  [pass] ${label}`);
+  // ── 6. Agent markdown files ───────────────────────────────────────────────
+  section("Agent Files");
+  const agentsDir = join(scaffoldDir, DIRS.agents);
+
+  for (const role of AGENTS) {
+    const agentFile = join(agentsDir, `${role}.md`);
+    if (!existsSync(agentFile)) {
+      fail(`Agent: ${role}`, `${DIRS.agents}/${role}.md missing`);
+      continue;
+    }
+
+    const content = safeReadFile(agentFile);
+    if (!content) {
+      fail(`Agent: ${role}`, "empty or unreadable");
+      continue;
+    }
+
+    // Check for YAML frontmatter
+    if (!content.startsWith("---")) {
+      softWarn(`Agent: ${role}`, "no YAML frontmatter");
+      continue;
+    }
+
+    // Check for model field in frontmatter
+    const endIdx = content.indexOf("---", 3);
+    if (endIdx > 0) {
+      const frontmatter = content.slice(3, endIdx);
+      if (/^model:/m.test(frontmatter)) {
+        const modelMatch = frontmatter.match(/^model:\s*(.+)$/m);
+        const modelVal = modelMatch ? modelMatch[1].trim() : "?";
+        pass(`Agent: ${role}`, `model: ${modelVal}`);
+      } else {
+        softWarn(`Agent: ${role}`, "no model field in frontmatter");
+      }
     } else {
-      console.log(`  [warn] ${label} — ${hint}`);
-      warnings++;
+      softWarn(`Agent: ${role}`, "malformed frontmatter");
+    }
+  }
+
+  // ── 7. Rules ──────────────────────────────────────────────────────────────
+  section("Rules");
+  const rulesDir = join(scaffoldDir, DIRS.rules);
+  const universalRules = join(rulesDir, "universal.md");
+
+  if (existsSync(universalRules)) {
+    const content = safeReadFile(universalRules);
+    pass("Universal rules", content ? `${content.split("\n").length} lines` : "empty");
+  } else {
+    fail("Universal rules", `${DIRS.rules}/universal.md missing`);
+  }
+
+  // Check for any additional rule files
+  if (existsSync(rulesDir)) {
+    const ruleFiles = safeReaddir(rulesDir).filter((f) => f.endsWith(".md") && f !== "universal.md");
+    if (ruleFiles.length > 0) {
+      pass("Custom rules", `${ruleFiles.length} additional file(s): ${ruleFiles.join(", ")}`);
     }
   }
 
-  function checkTool(name, installHint) {
-    try {
-      execSync(`${name} --version`, { stdio: "pipe" });
-      console.log(`  [pass] CLI: ${name}`);
-    } catch {
-      console.log(`  [warn] CLI: ${name} not found. Install: ${installHint}`);
-      warnings++;
+  // ── 8. Ralphy config ──────────────────────────────────────────────────────
+  section("Ralphy Integration");
+  const ralphyConfig = join(targetDir, ".ralphy", "config.yaml");
+
+  if (existsSync(ralphyConfig)) {
+    const content = safeReadFile(ralphyConfig);
+    pass(".ralphy/config.yaml", content ? `${content.split("\n").length} lines` : "exists");
+
+    // Check for placeholder values
+    if (content && content.includes('name: ""')) {
+      softWarn("Ralphy project name", 'still empty ("") — edit .ralphy/config.yaml');
     }
+  } else {
+    softWarn(".ralphy/config.yaml", "not found (needed for 'run' command)");
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  printSummary(errors, warnings);
+
+  // Return for programmatic use
+  return { errors, warnings };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function printSummary(errors, warnings) {
+  console.log();
+  hr();
+  console.log();
+
+  if (errors === 0 && warnings === 0) {
+    success("All checks passed. Your project is ready.");
+  } else if (errors === 0) {
+    console.log(`  ${c.bgYellow(" RESULT ")} ${c.yellow(`${warnings} warning(s), 0 errors`)}`);
+    console.log(`  ${c.gray("Warnings won't prevent execution but may indicate issues.")}`);
+    console.log();
+  } else {
+    console.log(`  ${c.bgRed(" RESULT ")} ${c.red(`${errors} error(s), ${warnings} warning(s)`)}`);
+    console.log(`  ${c.gray("Fix the errors above before running the agent team.")}`);
+    console.log();
+  }
+}
+
+function padRole(role) {
+  return role.padEnd(14);
+}
+
+function safeReaddir(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function safeReadFile(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return null;
   }
 }