opencode-auto-agent 1.0.0 → 1.2.0

package/src/lib/constants.js

@@ -1,26 +1,22 @@
 /**
  * Shared constants for ai-starter-kit.
+ *
+ * Defines the agent ecosystem, model defaults, presets, and directory layout.
+ * All values here align with OpenCode's official concepts.
  */
 
-/** Name of the folder scaffolded into target repos. */
-export const SCAFFOLD_DIR = ".ai-starter-kit";
+/** Name of the folder scaffolded into target repos (.opencode is OpenCode's convention). */
+export const SCAFFOLD_DIR = ".opencode";
 
-/** Filename for the kit configuration. */
+/** Filename for the kit configuration inside .opencode/. */
 export const CONFIG_FILE = "config.json";
 
+/** Version written into scaffolded config for upgrade detection. */
+export const SCHEMA_VERSION = "0.2.0";
+
 /** Known presets shipped with the package. */
 export const PRESETS = ["java", "springboot", "nextjs"];
 
-/** Standard agent names (order matters — this is the agent team). */
-export const AGENTS = [
-  "orchestrator",
-  "planner",
-  "developer",
-  "qa",
-  "reviewer",
-  "docs",
-];
-
 /** Folder names inside the scaffold directory. */
 export const DIRS = {
   agents: "agents",
@@ -29,5 +25,85 @@ export const DIRS = {
   rules: "rules",
 };
 
-/** Version written into scaffolded config for upgrade detection. */
-export const SCHEMA_VERSION = "0.1.0";
+// ── Agent definitions ──────────────────────────────────────────────────────
+
+/**
+ * Agent role definitions with OpenCode-aligned metadata.
+ *
+ * Each role maps to an OpenCode agent (mode: primary | subagent).
+ * The `defaultModel` is a sensible default that can be overridden during init.
+ * `tools` and `permission` follow OpenCode's tool/permission schema.
+ */
+export const AGENT_ROLES = {
+  orchestrator: {
+    description: "Primary orchestrator — routes tasks to specialist sub-agents",
+    mode: "primary",
+    defaultModel: "google/gemini-3-pro",
+    temperature: 0.2,
+    tools: { "*": true },
+    permission: {
+      task: { "*": "allow" },
+      edit: "deny",
+      bash: "ask",
+      todoread: "allow",
+      todowrite: "allow",
+    },
+  },
+  planner: {
+    description: "Architect & planner — breaks objectives into steps",
+    mode: "subagent",
+    defaultModel: "google/gemini-3-pro",
+    temperature: 0.2,
+    tools: { write: false, edit: false, bash: false },
+    permission: {},
+  },
+  developer: {
+    description: "Developer — writes and edits production code",
+    mode: "subagent",
+    defaultModel: "openai/gpt-5.1-codex",
+    temperature: 0.3,
+    tools: { "*": true },
+    permission: { bash: "allow" },
+  },
+  qa: {
+    description: "QA / Tester — runs tests, verifies correctness",
+    mode: "subagent",
+    defaultModel: "anthropic/claude-sonnet-4-5",
+    temperature: 0.1,
+    tools: { write: false, edit: false },
+    permission: { bash: "allow" },
+  },
+  reviewer: {
+    description: "Code reviewer — reviews for quality, security, performance",
+    mode: "subagent",
+    defaultModel: "anthropic/claude-sonnet-4-5",
+    temperature: 0.1,
+    tools: { write: false, edit: false, bash: false },
+    permission: {},
+  },
+  docs: {
+    description: "Documentation — keeps docs aligned with code changes",
+    mode: "subagent",
+    defaultModel: "anthropic/claude-sonnet-4-5",
+    temperature: 0.3,
+    tools: { bash: false },
+    permission: {},
+  },
+};
+
+/** Standard agent names in workflow order. */
+export const AGENTS = Object.keys(AGENT_ROLES);
+
+/** Map of role -> sensible default model ID (used when discovered models don't overlap). */
+export const DEFAULT_MODEL_MAP = Object.fromEntries(
+  Object.entries(AGENT_ROLES).map(([role, def]) => [role, def.defaultModel])
+);
+
+// ── OpenCode workflow ──────────────────────────────────────────────────────
+
+/** Standard workflow steps the orchestrator enforces. */
+export const WORKFLOW_STEPS = ["plan", "implement", "test", "verify"];
+
+/** Package name and version for CLI help text. */
+export const PKG_NAME = "opencode-auto-agent";
+export const PKG_ALIAS = "aisk";

package/src/lib/models.js

@@ -0,0 +1,172 @@
+/**
+ * Model discovery — runs `opencode models` and parses the output
+ * to discover available models from the user's configured providers.
+ *
+ * Models are returned in the OpenCode format: provider/model-id
+ */
+
+import { execSync } from "node:child_process";
+import { createSpinner, c } from "./ui.js";
+
+/**
+ * @typedef {Object} DiscoveredModel
+ * @property {string} id        - Full model ID (e.g. "openai/gpt-5.1-codex")
+ * @property {string} provider  - Provider name (e.g. "openai")
+ * @property {string} model     - Model name (e.g. "gpt-5.1-codex")
+ */
+
+/**
+ * Discover available models by running `opencode models`.
+ * Returns a parsed list of model objects.
+ *
+ * @returns {DiscoveredModel[]}
+ */
+export function discoverModels() {
+  let raw;
+  try {
+    raw = execSync("opencode models", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30_000,
+    });
+  } catch (err) {
+    // If opencode is not installed or fails, return empty
+    return [];
+  }
+
+  return parseModelsOutput(raw);
+}
+
+/**
+ * Parse the text output of `opencode models` into structured data.
+ * The output format is typically lines containing provider/model pairs.
+ *
+ * @param {string} raw
+ * @returns {DiscoveredModel[]}
+ */
+export function parseModelsOutput(raw) {
+  const models = [];
+  const seen = new Set();
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Skip header/decorative lines
+    if (trimmed.startsWith("─") || trimmed.startsWith("=") || trimmed.startsWith("-")) continue;
+    if (/^(provider|model|name|id)/i.test(trimmed)) continue;
+    if (trimmed.startsWith("#")) continue;
+
+    // Try to extract provider/model pattern
+    // Common formats:
+    //   provider/model-name
+    //   provider/model-name  (some description)
+    //   provider  model-name  description
+    const slashMatch = trimmed.match(/^([a-zA-Z0-9_-]+\/[a-zA-Z0-9._-]+)/);
+    if (slashMatch) {
+      const id = slashMatch[1];
+      if (!seen.has(id)) {
+        seen.add(id);
+        const [provider, ...modelParts] = id.split("/");
+        models.push({
+          id,
+          provider,
+          model: modelParts.join("/"),
+        });
+      }
+      continue;
+    }
+
+    // Try tab/space separated: provider  model
+    const parts = trimmed.split(/\s{2,}|\t+/).filter(Boolean);
+    if (parts.length >= 2) {
+      const candidate = `${parts[0]}/${parts[1]}`;
+      // Validate it looks like provider/model
+      if (/^[a-zA-Z0-9_-]+\/[a-zA-Z0-9._-]+$/.test(candidate) && !seen.has(candidate)) {
+        seen.add(candidate);
+        models.push({
+          id: candidate,
+          provider: parts[0],
+          model: parts[1],
+        });
+      }
+    }
+  }
+
+  return models;
+}
+
+/**
+ * Discover models with a spinner and status output.
+ * @returns {DiscoveredModel[]}
+ */
+export function discoverModelsInteractive() {
+  const spinner = createSpinner("Discovering available models via opencode...");
+  spinner.start();
+
+  const models = discoverModels();
+
+  if (models.length === 0) {
+    spinner.fail("No models found. Is opencode configured with at least one provider?");
+  } else {
+    spinner.stop(`Found ${c.bold(String(models.length))} models from ${c.bold(String(countProviders(models)))} providers`);
+  }
+
+  return models;
+}
+
+/**
+ * Group models by provider.
+ * @param {DiscoveredModel[]} models
+ * @returns {Map<string, DiscoveredModel[]>}
+ */
+export function groupByProvider(models) {
+  const groups = new Map();
+  for (const m of models) {
+    if (!groups.has(m.provider)) groups.set(m.provider, []);
+    groups.get(m.provider).push(m);
+  }
+  return groups;
+}
+
+/**
+ * Count unique providers.
+ * @param {DiscoveredModel[]} models
+ * @returns {number}
+ */
+function countProviders(models) {
+  return new Set(models.map((m) => m.provider)).size;
+}
+
+/**
+ * Find the best matching model from the available list given a preferred ID.
+ * Falls back to fuzzy matching on the model name portion.
+ *
+ * @param {DiscoveredModel[]} models
+ * @param {string} preferredId - e.g. "openai/gpt-5.1-codex"
+ * @returns {DiscoveredModel|null}
+ */
+export function findModel(models, preferredId) {
+  // Exact match
+  const exact = models.find((m) => m.id === preferredId);
+  if (exact) return exact;
+
+  // Match by model name only (ignoring provider)
+  const modelName = preferredId.includes("/") ? preferredId.split("/").slice(1).join("/") : preferredId;
+  const byName = models.find((m) => m.model === modelName);
+  if (byName) return byName;
+
+  // Fuzzy: model name contains the search term
+  const fuzzy = models.find((m) => m.model.includes(modelName) || m.id.includes(preferredId));
+  return fuzzy || null;
+}
+
+/**
+ * Validate that a model ID exists in the discovered models.
+ * @param {DiscoveredModel[]} models
+ * @param {string} modelId
+ * @returns {boolean}
+ */
+export function isValidModel(models, modelId) {
+  return findModel(models, modelId) !== null;
+}

package/src/lib/prerequisites.js

@@ -0,0 +1,151 @@
+/**
+ * Prerequisite validation — checks that required tools are installed
+ * and accessible before allowing initialization or execution to proceed.
+ *
+ * Rules:
+ *  - Never auto-install anything
+ *  - Abort early with clear messages if required tools are missing
+ *  - Distinguish between hard requirements (abort) and soft requirements (warn)
+ */
+
+import { execSync } from "node:child_process";
+import { status, error, c } from "./ui.js";
+
+/**
+ * @typedef {Object} ToolCheck
+ * @property {string} name     - Tool name
+ * @property {string} command  - Command to check (e.g. "opencode --version")
+ * @property {boolean} ok      - Whether the tool was found
+ * @property {string} version  - Detected version string
+ * @property {string} hint     - Install hint if missing
+ */
+
+/**
+ * Check if a CLI tool is available and return its version.
+ *
+ * @param {string} name - Display name
+ * @param {string} command - Command to run for version check
+ * @param {string} installHint - How to install if missing
+ * @returns {ToolCheck}
+ */
+export function checkTool(name, command, installHint) {
+  try {
+    const output = execSync(command, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 10_000,
+    }).trim();
+
+    // Try to extract version number
+    const vMatch = output.match(/v?([\d]+\.[\d]+[\d.]*)/);
+    const version = vMatch ? vMatch[1] : output.slice(0, 40);
+
+    return { name, command, ok: true, version, hint: installHint };
+  } catch {
+    return { name, command, ok: false, version: "", hint: installHint };
+  }
+}
+
+/**
+ * Check Node.js version meets minimum requirement.
+ * @param {number} minMajor - Minimum major version (default 18)
+ * @returns {ToolCheck}
+ */
+export function checkNodeVersion(minMajor = 18) {
+  const current = process.versions.node;
+  const major = parseInt(current.split(".")[0], 10);
+  return {
+    name: `Node.js (>=${minMajor})`,
+    command: "node --version",
+    ok: major >= minMajor,
+    version: current,
+    hint: `Node.js ${minMajor}+ is required. Current: ${current}`,
+  };
+}
+
+/**
+ * Run all prerequisite checks and return results.
+ *
+ * @param {Object} options
+ * @param {boolean} options.requireRalphy - Whether ralphy is a hard requirement
+ * @returns {{ checks: ToolCheck[], allPassed: boolean, hardFailed: boolean }}
+ */
+export function validatePrerequisites({ requireRalphy = false } = {}) {
+  const checks = [];
+
+  // 1. Node.js version
+  checks.push(checkNodeVersion(18));
+
+  // 2. OpenCode CLI (always required)
+  checks.push(checkTool(
+    "OpenCode CLI",
+    "opencode --version",
+    "Install: npm install -g opencode-ai  |  https://opencode.ai/docs"
+  ));
+
+  // 3. Ralphy CLI (conditional)
+  checks.push(checkTool(
+    "Ralphy CLI",
+    "ralphy --version",
+    "Install: npm install -g ralphy-cli  |  https://github.com/michaelshimeles/ralphy"
+  ));
+
+  // 4. Git (nice to have)
+  checks.push(checkTool(
+    "Git",
+    "git --version",
+    "Install Git: https://git-scm.com"
+  ));
+
+  // Determine hard failures
+  const hardRequired = ["Node.js", "OpenCode CLI"];
+  if (requireRalphy) hardRequired.push("Ralphy CLI");
+
+  const hardFailed = checks.some(
+    (ch) => !ch.ok && hardRequired.some((name) => ch.name.startsWith(name))
+  );
+  const allPassed = checks.every((ch) => ch.ok);
+
+  return { checks, allPassed, hardFailed };
+}
+
+/**
+ * Run prerequisite checks and print results to terminal.
+ * Aborts (process.exit) if hard requirements fail.
+ *
+ * @param {Object} options
+ * @param {boolean} options.requireRalphy
+ * @param {boolean} options.abortOnFail - Whether to exit on hard failure (default true)
+ * @returns {{ checks: ToolCheck[], allPassed: boolean }}
+ */
+export function validateAndReport({ requireRalphy = false, abortOnFail = true } = {}) {
+  const result = validatePrerequisites({ requireRalphy });
+
+  for (const ch of result.checks) {
+    if (ch.ok) {
+      status("pass", `${ch.name}`, `v${ch.version}`);
+    } else {
+      // Is this a hard failure?
+      const isHard = ch.name.startsWith("Node.js") ||
+                     ch.name.startsWith("OpenCode") ||
+                     (requireRalphy && ch.name.startsWith("Ralphy"));
+      if (isHard) {
+        status("fail", `${ch.name}`, "not found");
+        console.log(`          ${c.gray(ch.hint)}`);
+      } else {
+        status("warn", `${ch.name}`, "not found (optional)");
+        console.log(`          ${c.gray(ch.hint)}`);
+      }
+    }
+  }
+
+  if (result.hardFailed && abortOnFail) {
+    error(
+      "Required tools are missing. Cannot proceed.",
+      "Install the missing tools above and try again."
+    );
+    process.exit(1);
+  }
+
+  return result;
+}