opencode-autoresearch 3.1.0-beta.2 → 3.3.0

package/dist/cli.js

@@ -1,12 +1,21 @@
 #!/usr/bin/env node
-import { printJson } from "./helpers.js";
-function usage() {
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { resolve } from "path";
+import { printJson, resolveRepo } from "./helpers.js";
+const VERSION_FLAGS = ["--version", "-v"];
+const HELP_FLAGS = ["--help", "-h", "help"];
+const usage = () => {
     console.error("Usage: autoresearch <command> [options]");
     console.error("");
     console.error("Commands:");
     console.error("  init       Initialize a run");
     console.error("  wizard     Generate a setup summary");
     console.error("  status     Print run status");
+    console.error("  explain    Human-readable run state");
+    console.error("  history    Show recent iteration log");
+    console.error("  config     Show runtime configuration");
+    console.error("  summary    Aggregate stats across runs");
+    console.error("  suggest    Suggest next goal from memory");
     console.error("  launch     Launch a background run");
     console.error("  complete   Mark a run complete");
     console.error("  stop       Request a background run stop");
@@ -21,25 +30,49 @@ function usage() {
     console.error("  --metric        Metric name to track");
     console.error("  --direction     lower or higher");
     console.error("  --verify        Mechanical verification command");
+    console.error("  --guard         Guard command for regression catch");
     console.error("  --mode          foreground or background");
     console.error("  --scope         In-scope files or subsystem");
     console.error("  --iterations    Iteration cap");
     console.error("  --duration      Wall-clock cap (e.g., 5h or 300m)");
+    console.error("  --json          Output raw JSON (default: human-readable)");
     console.error("  --results-path  Custom results TSV path");
     console.error("  --state-path    Custom state JSON path");
     console.error("  --fresh-start   Archive previous artifacts before starting");
     console.error("");
+    console.error("Flags:");
+    console.error("  -h, --help      Show this help");
+    console.error("  -v, --version   Show version");
+    console.error("  --verbose       Enable verbose output");
+    console.error("  --dry-run       Preview changes without executing");
+    console.error("");
     console.error("Examples:");
     console.error("  autoresearch wizard --goal \"optimize response time\"");
     console.error("  autoresearch init --goal \"reduce errors\" --metric errors --direction lower --verify \"npm test\"");
     console.error("  autoresearch status");
-}
-function parseArgs(args) {
+    console.error("  autoresearch explain");
+    console.error("  autoresearch history");
+};
+const parseArgs = (args) => {
     const result = {};
     for (let i = 0; i < args.length; i++) {
         if (args[i].startsWith("--")) {
             const key = args[i].slice(2);
-            if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+            if (i + 1 < args.length && !args[i + 1].startsWith("--") && !args[i + 1].startsWith("-")) {
+                result[key] = args[++i];
+            }
+            else {
+                result[key] = "true";
+            }
+        }
+        else if (args[i].startsWith("-") && args[i].length === 2 && args[i] !== "--") {
+            const shortToLong = {
+                r: "repo", g: "goal", m: "metric", d: "direction",
+                v: "verify", n: "guard", o: "mode", s: "scope",
+                i: "iterations", t: "duration",
+            };
+            const key = shortToLong[args[i][1]] ?? args[i].slice(1);
+            if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
                 result[key] = args[++i];
             }
             else {
@@ -48,16 +81,44 @@ function parseArgs(args) {
         }
     }
     return result;
-}
-async function main() {
+};
+const formatMetricValue = (val) => {
+    if (val === undefined || val === null)
+        return "—";
+    return String(val);
+};
+const formatTimestamp = (ts) => {
+    try {
+        const d = new Date(ts);
+        return d.toLocaleString();
+    }
+    catch {
+        return ts;
+    }
+};
+const main = async () => {
     const args = process.argv.slice(2);
-    if (args.length === 0 || args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    // Handle standalone flags
+    if (args.length === 0) {
+        usage();
+        return 0;
+    }
+    const first = args[0];
+    if (VERSION_FLAGS.includes(first)) {
+        const { VERSION, PACKAGE_NAME, SKILL_NAME } = await import("./constants.js");
+        console.log(`${SKILL_NAME} ${VERSION} (${PACKAGE_NAME})`);
+        console.log("Runtime: Node.js " + process.version);
+        return 0;
+    }
+    if (HELP_FLAGS.includes(first)) {
         usage();
         return 0;
     }
     const [cmd, ...cmdArgs] = args;
     const pargs = parseArgs(cmdArgs);
-    // Group args by collecting multi-word options (like required-keep-labels)
+    const useJson = pargs.json === "true";
+    const verbose = pargs.verbose === "true";
+    const dryRun = pargs["dry-run"] === "true";
     const grouped = {};
     for (const [k, v] of Object.entries(pargs)) {
         if (k === "required-keep-labels" || k === "required-stop-labels" || k === "labels") {
@@ -91,6 +152,18 @@ async function main() {
                 break;
             }
             case "init": {
+                if (verbose)
+                    console.error(`[verbose] Initializing run with goal: ${grouped.goal}`);
+                if (dryRun) {
+                    console.log("[dry-run] Would initialize run with config:");
+                    console.log(JSON.stringify({
+                        goal: grouped.goal,
+                        metric: grouped.metric,
+                        direction: grouped.direction || "lower",
+                        mode: grouped.mode || "foreground",
+                    }, null, 2));
+                    return 0;
+                }
                 const { initializeRun } = await import("./run-manager.js");
                 const config = {
                     goal: grouped.goal,
@@ -116,7 +189,402 @@ async function main() {
             case "status": {
                 const { buildSupervisorSnapshot } = await import("./run-manager.js");
                 const snapshot = await buildSupervisorSnapshot(grouped.repo, grouped["results-path"], grouped["state-path"]);
-                printJson(snapshot);
+                if (useJson) {
+                    printJson(snapshot);
+                }
+                else {
+                    const s = snapshot;
+                    const stats = s.stats;
+                    console.log(`Run:     ${s.run_id}`);
+                    console.log(`Status:  ${s.status}`);
+                    console.log(`Mode:    ${s.mode}`);
+                    console.log(`Goal:    ${s.goal}`);
+                    if (s.metric) {
+                        const m = s.metric;
+                        console.log(`Metric:  ${m.name} (${m.direction})`);
+                        console.log(`  best:  ${formatMetricValue(m.best)}`);
+                        console.log(`  latest: ${formatMetricValue(m.latest)}`);
+                    }
+                    if (stats) {
+                        console.log(`Stats:   ${stats.total_iterations} iterations, ${stats.kept} kept, ${stats.discarded} discarded`);
+                    }
+                    console.log(`Results: ${s.results_rows} rows`);
+                    const lastIter = s.last_iteration;
+                    if (lastIter && lastIter.iteration) {
+                        console.log(`Last:    iter ${lastIter.iteration} — ${lastIter.decision} (${lastIter.metric_value})`);
+                    }
+                    const flags = s.flags;
+                    if (flags?.needs_human)
+                        console.log("⚠  Needs human input");
+                    if (flags?.stop_requested)
+                        console.log("⏹  Stop requested");
+                }
+                break;
+            }
+            case "explain": {
+                const { buildSupervisorSnapshot } = await import("./run-manager.js");
+                const snapshot = await buildSupervisorSnapshot(grouped.repo, grouped["results-path"], grouped["state-path"]);
+                const s = snapshot;
+                const stats = s.stats;
+                const lastIter = s.last_iteration;
+                const flags = s.flags;
+                if (useJson) {
+                    printJson(snapshot);
+                    break;
+                }
+                const statusEmoji = {
+                    running: "🔄", completed: "✅", initialized: "📋", stopping: "⏹", stopped: "⏸",
+                };
+                console.log(`${statusEmoji[s.status] ?? "⚪"} Auto Research Run: ${s.run_id}`);
+                console.log(`   Goal:      ${s.goal ?? "—"}`);
+                console.log(`   Status:    ${s.status}`);
+                console.log(`   Mode:      ${s.mode}`);
+                if (s.metric) {
+                    const m = s.metric;
+                    console.log(`   Metric:    ${m.name} → ${formatMetricValue(m.latest)} (best: ${formatMetricValue(m.best)}, dir: ${m.direction})`);
+                }
+                if (stats) {
+                    console.log(`   Progress:  ${stats.total_iterations} iterations | ${stats.kept} kept | ${stats.discarded} discarded`);
+                }
+                if (lastIter && lastIter.iteration) {
+                    console.log(`   Last iter: #${lastIter.iteration} — ${lastIter.decision}`);
+                    if (lastIter.change_summary)
+                        console.log(`   Change:    ${lastIter.change_summary}`);
+                }
+                if (flags?.needs_human)
+                    console.log("   ⚠  Needs human review");
+                if (flags?.stop_requested)
+                    console.log("   ⏹  Stop was requested");
+                if (flags?.background_active)
+                    console.log("   📡  Background active — `autoresearch status` to check");
+                break;
+            }
+            case "history": {
+                const { resolvePath } = await import("./helpers.js");
+                const { RESULTS_DEFAULT } = await import("./constants.js");
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                if (!existsSync(resultsPath)) {
+                    console.log("No results file found.");
+                    break;
+                }
+                const content = readFileSync(resultsPath, "utf-8");
+                const lines = content.trim().split("\n");
+                if (lines.length <= 1) {
+                    console.log("No iteration records yet.");
+                    break;
+                }
+                const limit = grouped.limit ? parseInt(grouped.limit) : 10;
+                const records = lines.slice(1).reverse().slice(0, limit);
+                if (useJson) {
+                    const headers = lines[0].split("\t");
+                    const parsed = records.map((r) => {
+                        const cols = r.split("\t");
+                        const obj = {};
+                        for (let i = 0; i < headers.length; i++) {
+                            obj[headers[i]] = cols[i] ?? "";
+                        }
+                        return obj;
+                    });
+                    printJson({ count: records.length, records: parsed });
+                    break;
+                }
+                for (const r of records) {
+                    const cols = r.split("\t");
+                    if (cols.length >= 8) {
+                        const emoji = cols[2] === "keep" ? "✓" : cols[2] === "discard" ? "✗" : "⚠";
+                        console.log(`${emoji}  #${cols[1]}  ${cols[2]}  (${formatMetricValue(cols[3])})  ${cols[7].substring(0, 60)}`);
+                    }
+                }
+                console.log(`\nShowing ${Math.min(limit, records.length)} of ${lines.length - 1} records.`);
+                break;
+            }
+            case "config": {
+                const { resolvePath, readJsonFile } = await import("./helpers.js");
+                const { STATE_DEFAULT } = await import("./constants.js");
+                const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                if (!existsSync(statePath)) {
+                    console.log("No run state found. Run 'autoresearch init' first.");
+                    break;
+                }
+                const state = readJsonFile(statePath);
+                if (useJson) {
+                    printJson({
+                        goal: state.goal,
+                        mode: state.mode,
+                        metric: state.metric,
+                        scope: state.scope,
+                        iterations_cap: state.iterations_cap,
+                        deadline_at: state.deadline_at,
+                        verify: state.verify,
+                        guard: state.guard,
+                        subagent_pool: state.subagent_pool ? "configured" : "none",
+                        label_requirements: state.label_requirements,
+                    });
+                    break;
+                }
+                console.log("Run Configuration:");
+                console.log(`  Goal:     ${state.goal ?? "—"}`);
+                console.log(`  Mode:     ${state.mode ?? "—"}`);
+                if (state.metric) {
+                    const m = state.metric;
+                    console.log(`  Metric:   ${m.name} (${m.direction})`);
+                }
+                console.log(`  Scope:    ${state.scope ?? "—"}`);
+                console.log(`  Iter cap: ${state.iterations_cap ?? "—"}`);
+                console.log(`  Deadline: ${state.deadline_at ? formatTimestamp(state.deadline_at) : "—"}`);
+                console.log(`  Verify:   ${state.verify ?? "—"}`);
+                console.log(`  Guard:    ${state.guard ?? "—"}`);
+                console.log(`  Pool:     ${state.subagent_pool ? "configured" : "none"}`);
+                break;
+            }
+            case "summary": {
+                const { resolvePath } = await import("./helpers.js");
+                const { RESULTS_DEFAULT } = await import("./constants.js");
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                if (!existsSync(resultsPath)) {
+                    console.log("No results file found. No runs completed yet.");
+                    break;
+                }
+                const content = readFileSync(resultsPath, "utf-8");
+                const lines = content.trim().split("\n");
+                const records = lines.slice(1).filter(Boolean);
+                let totalKept = 0, totalDiscarded = 0, totalNeedsHuman = 0;
+                const runIds = new Set();
+                for (const r of records) {
+                    const cols = r.split("\t");
+                    const dec = cols[2];
+                    if (dec === "keep")
+                        totalKept++;
+                    else if (dec === "discard")
+                        totalDiscarded++;
+                    else if (dec === "needs_human")
+                        totalNeedsHuman++;
+                    const iterTags = cols[1].split(":");
+                    if (iterTags.length >= 2)
+                        runIds.add(iterTags[0]);
+                }
+                if (useJson) {
+                    printJson({
+                        total_records: records.length,
+                        total_kept: totalKept,
+                        total_discarded: totalDiscarded,
+                        total_needs_human: totalNeedsHuman,
+                        keep_rate: records.length > 0 ? (totalKept / records.length * 100).toFixed(1) + "%" : "0%",
+                        distinct_run_ids: Array.from(runIds),
+                    });
+                    break;
+                }
+                console.log("Auto Research Summary");
+                console.log(`  Total iterations:   ${records.length}`);
+                console.log(`  Kept:               ${totalKept}`);
+                console.log(`  Discarded:          ${totalDiscarded}`);
+                console.log(`  Needs human:        ${totalNeedsHuman}`);
+                console.log(`  Keep rate:          ${records.length > 0 ? (totalKept / records.length * 100).toFixed(1) : 0}%`);
+                console.log(`  Distinct runs:      ${runIds.size}`);
+                break;
+            }
+            case "validate": {
+                const { normalizeDirection, normalizeMode, inferVerifyCommand } = await import("./helpers.js");
+                const errors = [];
+                if (!grouped.goal)
+                    errors.push("Missing required: --goal");
+                if (!grouped.metric)
+                    errors.push("Missing required: --metric");
+                try {
+                    if (grouped.direction)
+                        normalizeDirection(grouped.direction);
+                }
+                catch (e) {
+                    errors.push(`Invalid direction: ${e.message}`);
+                }
+                try {
+                    if (grouped.mode)
+                        normalizeMode(grouped.mode);
+                }
+                catch (e) {
+                    errors.push(`Invalid mode: ${e.message}`);
+                }
+                const verify = grouped.verify || inferVerifyCommand(grouped.repo);
+                if (verify === "<set verify command>") {
+                    errors.push("Cannot infer verify command. Provide --verify explicitly.");
+                }
+                if (useJson) {
+                    printJson({ valid: errors.length === 0, errors });
+                    return errors.length > 0 ? 1 : 0;
+                }
+                if (errors.length === 0) {
+                    console.log("✓ Configuration is valid");
+                    console.log(`  Goal: ${grouped.goal}`);
+                    console.log(`  Metric: ${grouped.metric} (${grouped.direction || "lower"})`);
+                    console.log(`  Verify: ${verify}`);
+                    console.log(`  Mode: ${grouped.mode || "foreground"}`);
+                }
+                else {
+                    console.error("✗ Configuration errors:");
+                    for (const err of errors) {
+                        console.error(`  - ${err}`);
+                    }
+                    return 1;
+                }
+                break;
+            }
+            case "report": {
+                const { resolvePath, readJsonFile } = await import("./helpers.js");
+                const { STATE_DEFAULT, RESULTS_DEFAULT } = await import("./constants.js");
+                const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                if (!existsSync(statePath)) {
+                    console.log("No run state found. Run 'autoresearch init' first.");
+                    break;
+                }
+                const state = readJsonFile(statePath);
+                let results = [];
+                if (existsSync(resultsPath)) {
+                    const content = readFileSync(resultsPath, "utf-8");
+                    results = content.trim().split("\n").slice(1).filter(Boolean);
+                }
+                if (useJson) {
+                    printJson({ state, results_count: results.length });
+                    break;
+                }
+                console.log(`# Auto Research Report`);
+                console.log(`\n**Run:** ${state.run_id}`);
+                console.log(`**Goal:** ${state.goal}`);
+                console.log(`**Status:** ${state.status}`);
+                console.log(`**Mode:** ${state.mode}`);
+                if (state.metric) {
+                    const m = state.metric;
+                    console.log(`**Metric:** ${m.name} (${m.direction})`);
+                    console.log(`**Best:** ${m.best} | **Latest:** ${m.latest}`);
+                }
+                if (state.stats) {
+                    const s = state.stats;
+                    console.log(`\n## Stats`);
+                    console.log(`- Iterations: ${s.total_iterations}`);
+                    console.log(`- Kept: ${s.kept}`);
+                    console.log(`- Discarded: ${s.discarded}`);
+                    console.log(`- Needs human: ${s.needs_human}`);
+                }
+                if (results.length > 0) {
+                    console.log(`\n## Iterations`);
+                    for (const r of results) {
+                        const cols = r.split("\t");
+                        if (cols.length >= 8) {
+                            console.log(`- ${cols[1]}: ${cols[2]} (${cols[3]}) — ${cols[7].substring(0, 60)}`);
+                        }
+                    }
+                }
+                break;
+            }
+            case "suggest": {
+                const { resolvePath } = await import("./helpers.js");
+                const { MEMORY_DEFAULT } = await import("./constants.js");
+                const memoryPath = resolvePath(grouped.repo, grouped["memory-path"], MEMORY_DEFAULT);
+                if (!existsSync(memoryPath)) {
+                    console.log("No memory file found. Run a self-improvement cycle first.");
+                    break;
+                }
+                const memory = readFileSync(memoryPath, "utf-8");
+                const patterns = memory.match(/### Pattern: [^\n]+/g) ?? [];
+                if (useJson) {
+                    printJson({ patterns_found: patterns.length, suggestions: patterns.map((p) => p.replace("### Pattern: ", "")) });
+                    break;
+                }
+                console.log("Memory Patterns — candidate next goals:");
+                for (const p of patterns) {
+                    console.log(`  → ${p.replace("### Pattern: ", "")}`);
+                }
+                console.log(`\n${patterns.length} patterns available. Use 'autoresearch init --goal "..."' to start a new run.`);
+                break;
+            }
+            case "export": {
+                const { resolvePath } = await import("./helpers.js");
+                const { RESULTS_DEFAULT, STATE_DEFAULT } = await import("./constants.js");
+                const resultsPath = resolvePath(grouped.repo, grouped["results-path"], RESULTS_DEFAULT);
+                const statePath = resolvePath(grouped.repo, grouped["state-path"], STATE_DEFAULT);
+                const format = grouped.format || "json";
+                if (!existsSync(resultsPath) || !existsSync(statePath)) {
+                    console.error("No run data found. Run 'autoresearch init' first.");
+                    return 1;
+                }
+                const results = readFileSync(resultsPath, "utf-8");
+                const state = readFileSync(statePath, "utf-8");
+                const lines = results.trim().split("\n");
+                const headers = lines[0].split("\t");
+                const records = lines.slice(1).filter(Boolean).map((r) => {
+                    const cols = r.split("\t");
+                    const obj = {};
+                    for (let i = 0; i < headers.length; i++) {
+                        obj[headers[i]] = cols[i] ?? "";
+                    }
+                    return obj;
+                });
+                const exportData = {
+                    exported_at: new Date().toISOString(),
+                    state: JSON.parse(state),
+                    iterations: records,
+                    summary: {
+                        total: records.length,
+                        kept: records.filter((r) => r.decision === "keep").length,
+                        discarded: records.filter((r) => r.decision === "discard").length,
+                    },
+                };
+                if (format === "json") {
+                    console.log(JSON.stringify(exportData, null, 2));
+                }
+                else if (format === "md" || format === "markdown") {
+                    console.log(`# Auto Research Export`);
+                    console.log(`\n**Run:** ${exportData.state.run_id}`);
+                    console.log(`**Goal:** ${exportData.state.goal}`);
+                    console.log(`**Exported:** ${exportData.exported_at}`);
+                    console.log(`\n## Summary`);
+                    console.log(`- Total iterations: ${exportData.summary.total}`);
+                    console.log(`- Kept: ${exportData.summary.kept}`);
+                    console.log(`- Discarded: ${exportData.summary.discarded}`);
+                    console.log(`\n## Iterations`);
+                    console.log(`| # | Decision | Metric | Summary |`);
+                    console.log(`|---|----------|--------|---------|`);
+                    for (const r of records) {
+                        console.log(`| ${r.iteration} | ${r.decision} | ${r.metric_value || "—"} | ${r.change_summary?.substring(0, 50) || "—"} |`);
+                    }
+                }
+                else {
+                    console.error(`Unknown format: ${format}. Supported: json, md`);
+                    return 1;
+                }
+                break;
+            }
+            case "completion": {
+                const shell = grouped.shell || "bash";
+                const commands = ["init", "wizard", "status", "explain", "history", "config", "summary", "suggest", "launch", "complete", "stop", "resume", "record", "doctor", "export", "completion", "help"];
+                const options = ["--repo", "--goal", "--metric", "--direction", "--verify", "--guard", "--mode", "--scope", "--iterations", "--duration", "--json", "--results-path", "--state-path", "--fresh-start", "--memory-path", "--format", "--shell"];
+                if (shell === "bash" || shell === "zsh") {
+                    console.log(`# Auto Research CLI completion for ${shell}`);
+                    console.log(`_autoresearch() {`);
+                    console.log(`  local cur="\${COMP_WORDS[COMP_CWORD]}"`);
+                    console.log(`  local cmds="${commands.join(" ")}"`);
+                    console.log(`  local opts="${options.join(" ")}"`);
+                    console.log(`  if [ $COMP_CWORD -eq 1 ]; then`);
+                    console.log(`    COMPREPLY=($(compgen -W "$cmds" -- "$cur"))`);
+                    console.log(`  else`);
+                    console.log(`    COMPREPLY=($(compgen -W "$opts" -- "$cur"))`);
+                    console.log(`  fi`);
+                    console.log(`}`);
+                    console.log(`complete -F _autoresearch autoresearch`);
+                }
+                else if (shell === "fish") {
+                    console.log(`# Auto Research CLI completion for fish`);
+                    for (const cmd of commands) {
+                        console.log(`complete -c autoresearch -n '__fish_use_subcommand' -a '${cmd}'`);
+                    }
+                    for (const opt of options) {
+                        console.log(`complete -c autoresearch -n '__fish_seen_subcommand_from ${commands.join(" ")}' -l ${opt.slice(2)}`);
+                    }
+                }
+                else {
+                    console.error(`Unknown shell: ${shell}. Supported: bash, zsh, fish`);
+                    return 1;
+                }
                 break;
             }
             case "launch": {
@@ -178,15 +646,40 @@ async function main() {
                 const { VERSION, PACKAGE_NAME, SKILL_NAME } = await import("./constants.js");
                 console.log(`${SKILL_NAME} ${VERSION} (${PACKAGE_NAME})`);
                 console.log("Runtime: Node.js " + process.version);
-                console.log("Commands: OK");
-                console.log("Skills: OK");
-                console.log("Hooks: OK");
+                const base = resolveRepo(grouped.repo);
+                const checks = [];
+                const cmdDir = resolve(base, "commands");
+                const skillsDir = resolve(base, "skills/autoresearch");
+                const hooksDir = resolve(base, "hooks");
+                const cmdFiles = existsSync(cmdDir) ? readdirSync(cmdDir).filter((f) => f.endsWith(".md")) : [];
+                const skillFiles = existsSync(skillsDir) ? readdirSync(skillsDir) : [];
+                const hookFiles = existsSync(hooksDir) ? readdirSync(hooksDir).filter((f) => f.endsWith(".sh")) : [];
+                checks.push({ name: "commands", ok: cmdFiles.length > 0, detail: `${cmdFiles.length} command files` });
+                checks.push({ name: "skills", ok: skillFiles.length > 0, detail: `${skillFiles.length} skill files` });
+                checks.push({ name: "hooks", ok: hookFiles.length > 0, detail: `${hookFiles.length} hook scripts` });
+                checks.push({ name: "dist", ok: existsSync(resolve(base, "dist/cli.js")), detail: "dist/cli.js" });
+                checks.push({ name: "plugin", ok: existsSync(resolve(base, ".opencode-plugin/plugin.json")), detail: "plugin manifest" });
+                checks.push({ name: "VERSION", ok: existsSync(resolve(base, "VERSION")), detail: "version marker" });
+                let maxNameLen = 0;
+                for (const c of checks)
+                    maxNameLen = Math.max(maxNameLen, c.name.length);
+                for (const c of checks) {
+                    const padded = c.name.padEnd(maxNameLen + 2);
+                    console.log(`  ${c.ok ? "✓" : "✗"} ${padded}${c.detail ?? (c.ok ? "present" : "missing")}`);
+                }
+                const failed = checks.filter((c) => !c.ok).length;
+                if (failed > 0) {
+                    console.error(`\n${failed} check(s) failed. Reinstall with 'npm install -g opencode-autoresearch'.`);
+                    return 1;
+                }
+                console.log(`\nAll ${checks.length} checks passed.`);
                 break;
             }
-            default:
+            default: {
                 console.error(`Unknown command: ${cmd}`);
                 console.error("Run 'autoresearch --help' for usage.");
                 return 1;
+            }
         }
     }
     catch (exc) {
@@ -194,7 +687,7 @@ async function main() {
         return 2;
     }
     return 0;
-}
+};
 main().then((code) => process.exit(code)).catch((err) => {
     console.error(err);
     process.exit(1);