@tudeorangbiasa/sdd-multiagent-opencode 0.2.2 → 0.3.0

package/bin/sdd-opencode.js

@@ -3,11 +3,135 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, "..");
 
+const globalConfigDir = path.join(
+  process.env.HOME || process.env.USERPROFILE || "",
+  ".config",
+  "opencode"
+);
+
+// ─── Atomic Write with EXDEV Fallback ────────────────────────────────────────
+
+function atomicWrite(targetPath, content) {
+  const dir = path.dirname(targetPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = `${targetPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpPath, content);
+
+  try {
+    fs.renameSync(tmpPath, targetPath);
+  } catch (e) {
+    if (e.code === "EXDEV") {
+      fs.copyFileSync(tmpPath, targetPath);
+      fs.unlinkSync(tmpPath);
+    } else {
+      fs.unlinkSync(tmpPath);
+      throw e;
+    }
+  }
+}
+
+function atomicWriteFromFile(srcPath, targetPath) {
+  const content = fs.readFileSync(srcPath, "utf-8");
+  atomicWrite(targetPath, content);
+}
+
+// ─── JSONC Support (lightweight comment stripper) ───────────────────────────
+
+function stripJsonComments(text) {
+  const lines = text.split("\n");
+  const result = [];
+  let inBlockComment = false;
+
+  for (const line of lines) {
+    let cleaned = "";
+    let i = 0;
+    let inString = false;
+    let escapeNext = false;
+
+    while (i < line.length) {
+      const ch = line[i];
+
+      if (inBlockComment) {
+        if (ch === "*" && line[i + 1] === "/") {
+          inBlockComment = false;
+          i += 2;
+          continue;
+        }
+        i++;
+        continue;
+      }
+
+      if (escapeNext) {
+        cleaned += ch;
+        escapeNext = false;
+        i++;
+        continue;
+      }
+
+      if (inString) {
+        cleaned += ch;
+        if (ch === "\\") {
+          escapeNext = true;
+        } else if (ch === '"') {
+          inString = false;
+        }
+        i++;
+        continue;
+      }
+
+      if (ch === '"') {
+        cleaned += ch;
+        inString = true;
+        i++;
+        continue;
+      }
+
+      if (ch === "/" && line[i + 1] === "*") {
+        inBlockComment = true;
+        i += 2;
+        continue;
+      }
+
+      if (ch === "/" && line[i + 1] === "/") {
+        break;
+      }
+
+      cleaned += ch;
+      i++;
+    }
+
+    result.push(cleaned);
+  }
+
+  return result.join("\n");
+}
+
+function parseJsonc(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const stripped = stripJsonComments(raw);
+  return JSON.parse(stripped);
+}
+
+// ─── Backup ──────────────────────────────────────────────────────────────────
+
+function createBackup(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  const backupPath = `${filePath}.bak`;
+  fs.copyFileSync(filePath, backupPath);
+}
+
+// ─── Arg Parsing ─────────────────────────────────────────────────────────────
+
 function parseArgs(argv) {
   const args = {
     command: null,
@@ -16,21 +140,30 @@ function parseArgs(argv) {
       rulesOnly: false,
       force: false,
       dryRun: false,
+      deep: false,
+      minimal: false,
+      full: false,
     },
   };
 
   for (let i = 2; i < argv.length; i++) {
     const arg = argv[i];
-    if (arg === "init" || arg === "help" || arg === "test") {
+    if (["init", "help", "test", "doctor", "warm", "migrate"].includes(arg)) {
       args.command = arg;
     } else if (arg === "--sdd-only") {
       args.flags.sddOnly = true;
     } else if (arg === "--rules-only") {
       args.flags.rulesOnly = true;
-    } else if (arg === "--force") {
+    } else if (arg === "--force" || arg === "--reset") {
       args.flags.force = true;
     } else if (arg === "--dry-run") {
       args.flags.dryRun = true;
+    } else if (arg === "--deep") {
+      args.flags.deep = true;
+    } else if (arg === "--minimal") {
+      args.flags.minimal = true;
+    } else if (arg === "--full") {
+      args.flags.full = true;
     }
   }
 
@@ -41,35 +174,52 @@ function parseArgs(argv) {
   return args;
 }
 
+// ─── Usage ───────────────────────────────────────────────────────────────────
+
 function usage() {
-  console.log(`SDD Multi-Agent OpenCode Installer
+  console.log(`SDD Multi-Agent OpenCode Installer v0.3.0
 
 Usage:
-  sdd-opencode init [flags]
-  sdd-opencode help
+  sdd-opencode init [flags]     Install SDD workflow into current project
+  sdd-opencode doctor [--deep]  Diagnose installation health
+  sdd-opencode warm             Warm OpenCode plugin cache
+  sdd-opencode migrate          Remove old symlinks from v0.2.x
+  sdd-opencode help             Show this help
 
-Flags:
+Init Flags:
   --sdd-only      Install only SDD workflow (skip base rules)
-  --rules-only   Install only base rules (skip SDD)
-  --force        Overwrite existing managed files
-  --dry-run      Show what would be installed, no writes
+  --rules-only    Install only base rules (skip SDD)
+  --force/--reset Overwrite existing managed files (with backup)
+  --dry-run       Preview without writing
+  --minimal       Core SDD only (no vendor rules)
+  --full          Everything including vendor rules
+
+Doctor:
+  L0  File structure, JSON validity, orphaned symlinks
+  L1  Plugin registration count (agents, skills, commands)
+  L2  Environment variables for configured providers
+  L3  Liveness probe (API call to configured model) — requires --deep
 
 Examples:
   sdd-opencode init                  # Install everything
   sdd-opencode init --sdd-only       # SDD only
-  sdd-opencode init --rules-only     # Rules only
-  sdd-opencode init --force          # Overwrite existing
   sdd-opencode init --dry-run        # Preview only
+  sdd-opencode doctor                # Static checks (L0-L2)
+  sdd-opencode doctor --deep         # Include liveness probe (L3)
+  sdd-opencode warm                  # Warm plugin cache
+  sdd-opencode migrate               # Clean old symlinks
 `);
 }
 
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
 function ensureDir(dir) {
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
 }
 
-function copyFileSafe(src, dest, ctx, options = {}) {
+function copyFileSafe(src, dest, ctx) {
   const { force, dryRun } = ctx;
 
   if (fs.existsSync(dest)) {
@@ -77,6 +227,7 @@ function copyFileSafe(src, dest, ctx, options = {}) {
       ctx.skipped.push(path.relative(ctx.targetRoot, dest));
       return false;
     }
+    createBackup(dest);
   }
 
   if (dryRun) {
@@ -84,108 +235,74 @@ function copyFileSafe(src, dest, ctx, options = {}) {
     return true;
   }
 
-  const content = fs.readFileSync(src, "utf-8");
-  fs.writeFileSync(dest, content);
+  atomicWriteFromFile(src, dest);
   ctx.installed.push(path.relative(ctx.targetRoot, dest));
   return true;
 }
 
 function copyDirFlat(srcDir, destDir, ctx) {
-  if (!fs.existsSync(srcDir)) {
-    return 0;
-  }
-
+  if (!fs.existsSync(srcDir)) return 0;
   ensureDir(destDir);
 
   let count = 0;
-  const files = fs.readdirSync(srcDir);
-  for (const file of files) {
+  for (const file of fs.readdirSync(srcDir)) {
     const srcPath = path.join(srcDir, file);
     const destPath = path.join(destDir, file);
-
     if (fs.statSync(srcPath).isDirectory()) {
       count += copyDirFlat(srcPath, destPath, ctx);
     } else {
-      if (copyFileSafe(srcPath, destPath, ctx)) {
-        count++;
-      }
+      if (copyFileSafe(srcPath, destPath, ctx)) count++;
     }
   }
-
   return count;
 }
 
 function copyOpencodeDir(srcRelative, destRelative, ctx) {
   const srcPath = path.join(packageRoot, srcRelative);
   const destPath = path.join(ctx.targetRoot, destRelative);
-
-  if (!fs.existsSync(srcPath)) {
-    return 0;
-  }
+  if (!fs.existsSync(srcPath)) return 0;
 
   let count = 0;
-  const items = fs.readdirSync(srcPath);
-
-  for (const item of items) {
+  for (const item of fs.readdirSync(srcPath)) {
     const srcItem = path.join(srcPath, item);
     const destItem = path.join(destPath, item);
-
     if (fs.statSync(srcItem).isDirectory()) {
       ensureDir(destItem);
-      const subCount = copyOpencodeDir(
-        `${srcRelative}/${item}`,
-        `${destRelative}/${item}`,
-        ctx
-      );
-      count += subCount;
+      count += copyOpencodeDir(`${srcRelative}/${item}`, `${destRelative}/${item}`, ctx);
     } else {
-      if (copyFileSafe(srcItem, destItem, ctx)) {
-        count++;
-      }
+      if (copyFileSafe(srcItem, destItem, ctx)) count++;
     }
   }
-
   return count;
 }
 
+// ─── Install Commands ────────────────────────────────────────────────────────
+
 function installRules(ctx) {
   const vendorRules = path.join(packageRoot, "vendor/opencode-agent-rules");
-
   if (!fs.existsSync(vendorRules)) {
-    console.warn("⚠️  vendor/opencode-agent-rules not found, skipping rules");
+    console.warn("Warning: vendor/opencode-agent-rules not found, skipping rules");
     return 0;
   }
 
   let count = 0;
-
   const targetOpencode = path.join(ctx.targetRoot, ".opencode");
   ensureDir(path.join(targetOpencode, "rules"));
   ensureDir(path.join(targetOpencode, "plugins"));
 
   const agentsSrc = path.join(vendorRules, "AGENTS.md");
-  const agentsDest = path.join(ctx.targetRoot, "AGENTS.md");
-
   if (fs.existsSync(agentsSrc)) {
-    if (copyFileSafe(agentsSrc, agentsDest, ctx)) {
-      count++;
-    }
+    if (copyFileSafe(agentsSrc, path.join(ctx.targetRoot, "AGENTS.md"), ctx)) count++;
   }
 
-  const rulesSrc = path.join(vendorRules, ".opencode/rules");
-  const rulesDest = path.join(targetOpencode, "rules");
-  count += copyDirFlat(rulesSrc, rulesDest, ctx);
-
-  const pluginsSrc = path.join(vendorRules, ".opencode/plugins");
-  if (fs.existsSync(pluginsSrc)) {
-    count += copyDirFlat(pluginsSrc, path.join(targetOpencode, "plugins"), ctx);
-  }
+  count += copyDirFlat(path.join(vendorRules, ".opencode/rules"), path.join(targetOpencode, "rules"), ctx);
+  count += copyDirFlat(path.join(vendorRules, ".opencode/plugins"), path.join(targetOpencode, "plugins"), ctx);
 
   return count;
 }
 
 function installSdd(ctx) {
   let count = 0;
-
   const targetOpencode = path.join(ctx.targetRoot, ".opencode");
 
   ensureDir(path.join(targetOpencode, "agents"));
@@ -203,74 +320,47 @@ function installSdd(ctx) {
   ensureDir(path.join(sddDir, "templates"));
 
   const configSrc = path.join(packageRoot, ".sdd/config.json");
-  const configDest = path.join(sddDir, "config.json");
-  if (copyFileSafe(configSrc, configDest, ctx)) {
-    count++;
-  }
+  if (copyFileSafe(configSrc, path.join(sddDir, "config.json"), ctx)) count++;
 
   const templatesSrc = path.join(packageRoot, ".sdd/templates");
   if (fs.existsSync(templatesSrc)) {
-    const templateFiles = fs.readdirSync(templatesSrc);
-    for (const file of templateFiles) {
-      const src = path.join(templatesSrc, file);
-      const dest = path.join(sddDir, "templates", file);
-      if (copyFileSafe(src, dest, ctx)) {
-        count++;
-      }
+    for (const file of fs.readdirSync(templatesSrc)) {
+      if (copyFileSafe(path.join(templatesSrc, file), path.join(sddDir, "templates", file), ctx)) count++;
     }
   }
 
-  const projectProfileDest = path.join(sddDir, "project-profile.json");
-  const profileTemplateSrc = path.join(
-    sddDir,
-    "templates",
-    "project-profile-template.json"
-  );
+  const profileTemplates = [
+    { dest: "project-profile.json", template: "project-profile-template.json", populate: true },
+    { dest: "model-profile.json", template: "model-profile-template.json", populate: false },
+    { dest: "reasoning-profile.json", template: "reasoning-profile-template.json", populate: false },
+  ];
 
-  if (fs.existsSync(projectProfileDest) && !ctx.force) {
-    ctx.skipped.push(".sdd/project-profile.json (exists)");
-  } else if (fs.existsSync(profileTemplateSrc)) {
-    const profile = JSON.parse(fs.readFileSync(profileTemplateSrc, "utf-8"));
-    profile.initialized = new Date().toISOString();
-    profile.lastUpdated = new Date().toISOString();
+  for (const { dest, template, populate } of profileTemplates) {
+    const destPath = path.join(sddDir, dest);
+    const templatePath = path.join(sddDir, "templates", template);
 
-    if (ctx.dryRun) {
-      ctx.dryRunFiles.push(".sdd/project-profile.json");
-    } else {
-      fs.writeFileSync(
-        projectProfileDest,
-        JSON.stringify(profile, null, 2)
-      );
-      ctx.installed.push(".sdd/project-profile.json");
+    if (fs.existsSync(destPath) && !ctx.force) {
+      ctx.skipped.push(`.sdd/${dest} (exists)`);
+      continue;
     }
-    count++;
-  }
 
-  const modelProfileDest = path.join(sddDir, "model-profile.json");
-  const modelProfileTemplateSrc = path.join(
-    sddDir,
-    "templates",
-    "model-profile-template.json"
-  );
+    if (!fs.existsSync(templatePath)) continue;
 
-  if (fs.existsSync(modelProfileDest) && !ctx.force) {
-    ctx.skipped.push(".sdd/model-profile.json (exists)");
-  } else if (fs.existsSync(modelProfileTemplateSrc)) {
-    copyFileSafe(modelProfileTemplateSrc, modelProfileDest, ctx);
-    count++;
-  }
-
-  const reasoningProfileDest = path.join(sddDir, "reasoning-profile.json");
-  const reasoningProfileTemplateSrc = path.join(
-    sddDir,
-    "templates",
-    "reasoning-profile-template.json"
-  );
+    if (ctx.dryRun) {
+      ctx.dryRunFiles.push(`.sdd/${dest}`);
+      count++;
+      continue;
+    }
 
-  if (fs.existsSync(reasoningProfileDest) && !ctx.force) {
-    ctx.skipped.push(".sdd/reasoning-profile.json (exists)");
-  } else if (fs.existsSync(reasoningProfileTemplateSrc)) {
-    copyFileSafe(reasoningProfileTemplateSrc, reasoningProfileDest, ctx);
+    if (populate) {
+      const profile = JSON.parse(fs.readFileSync(templatePath, "utf-8"));
+      profile.initialized = new Date().toISOString();
+      profile.lastUpdated = new Date().toISOString();
+      atomicWrite(destPath, JSON.stringify(profile, null, 2));
+    } else {
+      atomicWriteFromFile(templatePath, destPath);
+    }
+    ctx.installed.push(`.sdd/${dest}`);
     count++;
   }
 
@@ -285,26 +375,25 @@ function installSdd(ctx) {
 
 function patchOpencodeJson(ctx) {
   const targetJsonPath = path.join(ctx.targetRoot, "opencode.json");
-
   let targetConfig = {};
+  let rawContent = "";
+  let isJsonc = false;
 
   if (fs.existsSync(targetJsonPath)) {
     try {
-      targetConfig = JSON.parse(fs.readFileSync(targetJsonPath, "utf-8"));
-    } catch (e) {
+      rawContent = fs.readFileSync(targetJsonPath, "utf-8");
+      isJsonc = rawContent.includes("//") || rawContent.includes("/*");
+      targetConfig = isJsonc ? parseJsonc(targetJsonPath) : JSON.parse(rawContent);
+    } catch {
       ctx.skipped.push("opencode.json (parse error, skipping patch)");
       return;
     }
   }
 
-  if (!targetConfig.agent) {
-    targetConfig.agent = {};
-  }
+  if (!targetConfig.agent) targetConfig.agent = {};
 
-  const vendorRulesJson = path.join(
-    packageRoot,
-    "vendor/opencode-agent-rules/opencode.json"
-  );
+  // Patch compaction from vendor rules
+  const vendorRulesJson = path.join(packageRoot, "vendor/opencode-agent-rules/opencode.json");
   if (fs.existsSync(vendorRulesJson)) {
     const rulesConfig = JSON.parse(fs.readFileSync(vendorRulesJson, "utf-8"));
     if (rulesConfig.agent?.compaction && !targetConfig.agent.compaction) {
@@ -313,34 +402,22 @@ function patchOpencodeJson(ctx) {
     }
   }
 
+  // Patch plugins
   const pkgJsonPath = path.join(packageRoot, "opencode.json");
   if (fs.existsSync(pkgJsonPath)) {
     const pkgConfig = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
 
     if (Array.isArray(pkgConfig.plugin)) {
-      if (!Array.isArray(targetConfig.plugin)) {
-        targetConfig.plugin = [];
-      }
-
+      if (!Array.isArray(targetConfig.plugin)) targetConfig.plugin = [];
       for (const pluginEntry of pkgConfig.plugin) {
         const key = JSON.stringify(pluginEntry);
-        const exists = targetConfig.plugin.some((existing) => JSON.stringify(existing) === key);
-        if (!exists) {
+        if (!targetConfig.plugin.some((e) => JSON.stringify(e) === key)) {
           targetConfig.plugin.push(pluginEntry);
           ctx.installed.push(`opencode.json (plugin: ${Array.isArray(pluginEntry) ? pluginEntry[0] : pluginEntry})`);
         }
       }
     }
 
-    // NOTE: model and small_model are NOT patched from opencode.json.
-    // Model routing is handled by .sdd/model-profile.json + sdd-model-router.js plugin.
-    // Users edit model-profile.json to change models — opencode.json models are ignored.
-
-    if (pkgConfig.agents && !targetConfig.agents) {
-      targetConfig.agents = pkgConfig.agents;
-      ctx.installed.push("opencode.json (agents patch)");
-    }
-
     if (pkgConfig.agent) {
       for (const [key, value] of Object.entries(pkgConfig.agent)) {
         if (!targetConfig.agent[key]) {
@@ -354,10 +431,6 @@ function patchOpencodeJson(ctx) {
       targetConfig.permission = pkgConfig.permission;
       ctx.installed.push("opencode.json (permission patch)");
     }
-
-    // NOTE: model and small_model are NOT patched here.
-    // Model routing is handled by .sdd/model-profile.json + sdd-model-router.js plugin.
-    // Users should edit model-profile.json to change models, not opencode.json.
   }
 
   if (ctx.dryRun) {
@@ -365,17 +438,26 @@ function patchOpencodeJson(ctx) {
     return;
   }
 
-  fs.writeFileSync(targetJsonPath, JSON.stringify(targetConfig, null, 2));
+  createBackup(targetJsonPath);
+  atomicWrite(targetJsonPath, JSON.stringify(targetConfig, null, 2));
 }
 
 async function runInit(args) {
   const targetRoot = process.cwd();
 
   if (args.flags.sddOnly && args.flags.rulesOnly) {
-    console.error("❌ Cannot use --sdd-only and --rules-only together.");
+    console.error("Error: Cannot use --sdd-only and --rules-only together.");
     process.exit(1);
   }
 
+  if (args.flags.minimal) {
+    args.flags.sddOnly = true;
+  }
+  if (args.flags.full) {
+    args.flags.rulesOnly = false;
+    args.flags.sddOnly = false;
+  }
+
   const ctx = {
     targetRoot,
     force: args.flags.force,
@@ -385,35 +467,30 @@ async function runInit(args) {
     dryRunFiles: [],
   };
 
-  console.log(`\n📦 SDD Multi-Agent OpenCode Installer\n`);
+  console.log("\nSDD Multi-Agent OpenCode Installer v0.3.0\n");
   console.log(`Target: ${targetRoot}`);
-
-  if (ctx.dryRun) {
-    console.log(`Mode: DRY RUN (no files will be written)\n`);
-  }
+  if (ctx.dryRun) console.log("Mode: DRY RUN (no files will be written)\n");
 
   let rulesCount = 0;
   let sddCount = 0;
 
   if (!args.flags.sddOnly) {
-    console.log(`Installing base rules...`);
+    console.log("Installing base rules...");
     rulesCount = installRules(ctx);
   }
 
   if (!args.flags.rulesOnly) {
-    console.log(`Installing SDD workflow...`);
+    console.log("Installing SDD workflow...");
     sddCount = installSdd(ctx);
   }
 
   patchOpencodeJson(ctx);
 
-  console.log(`\n✅ Done!\n`);
+  console.log("\nDone!\n");
 
   if (ctx.dryRun) {
     console.log(`Would install (${ctx.dryRunFiles.length} files):`);
-    for (const f of ctx.dryRunFiles) {
-      console.log(`  + ${f}`);
-    }
+    for (const f of ctx.dryRunFiles) console.log(`  + ${f}`);
   } else {
     console.log(`Installed:`);
     console.log(`  - rules: ${rulesCount} files`);
@@ -421,24 +498,259 @@ async function runInit(args) {
 
     if (ctx.skipped.length > 0) {
       console.log(`\nSkipped (exists, use --force):`);
-      for (const f of ctx.skipped) {
-        console.log(`  - ${f}`);
+      for (const f of ctx.skipped) console.log(`  - ${f}`);
+    }
+
+    console.log("\nNext steps:");
+    console.log("  1. Edit .sdd/project-profile.json with your stack");
+    console.log("  2. Run: /sdd-propose \"your first feature\"");
+    console.log("  3. Optional TDD: /sdd-propose my-feature --tdd");
+  }
+}
+
+// ─── Doctor Command ──────────────────────────────────────────────────────────
+
+async function runDoctor(args) {
+  const targetRoot = process.cwd();
+  const results = { pass: 0, warn: 0, fail: 0, checks: [] };
+
+  function report(level, name, status, detail = "") {
+    const icon = status === "pass" ? "OK" : status === "warn" ? "WARN" : "FAIL";
+    results.checks.push({ level, name, status, detail });
+    if (status === "pass") results.pass++;
+    else if (status === "warn") results.warn++;
+    else results.fail++;
+    console.log(`  [${icon}] [${level}] ${name}${detail ? ` — ${detail}` : ""}`);
+  }
+
+  console.log("\nSDD Doctor — Diagnostic Report\n");
+  console.log(`Target: ${targetRoot}\n`);
+
+  // L0: File structure, JSON validity, orphaned symlinks
+  console.log("L0: File Structure");
+
+  const requiredDirs = [".opencode/agents", ".opencode/commands", ".opencode/skills", ".sdd", ".sdd/templates", "specs/active", "specs/backlog", "specs/completed"];
+  for (const dir of requiredDirs) {
+    const fullPath = path.join(targetRoot, dir);
+    report("L0", dir, fs.existsSync(fullPath) ? "pass" : "fail", fs.existsSync(fullPath) ? "exists" : "missing");
+  }
+
+  const requiredFiles = ["opencode.json", ".sdd/config.json"];
+  for (const file of requiredFiles) {
+    const fullPath = path.join(targetRoot, file);
+    if (!fs.existsSync(fullPath)) {
+      report("L0", file, "fail", "missing");
+      continue;
+    }
+    try {
+      if (file.endsWith(".json")) {
+        parseJsonc(fullPath);
+      } else {
+        fs.readFileSync(fullPath, "utf-8");
+      }
+      report("L0", file, "pass", "valid");
+    } catch (e) {
+      report("L0", file, "fail", `parse error: ${e.message}`);
+    }
+  }
+
+  // Check for orphaned symlinks from v0.2.x
+  const globalCommandsDir = path.join(globalConfigDir, "commands");
+  const globalAgentsDir = path.join(globalConfigDir, "agents");
+  let orphanedCount = 0;
+
+  for (const dir of [globalCommandsDir, globalAgentsDir]) {
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      try {
+        const stat = fs.lstatSync(fullPath);
+        if (stat.isSymbolicLink()) {
+          const target = fs.readlinkSync(fullPath);
+          if (target.includes("sdd-multiagent-opencode") || target.includes("opencode-agent-rules")) {
+            orphanedCount++;
+          }
+        }
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  report("L0", "orphaned symlinks", orphanedCount === 0 ? "pass" : "warn", orphanedCount > 0 ? `${orphanedCount} old symlinks found — run "sdd-opencode migrate"` : "clean");
+
+  // L1: Plugin registration count
+  console.log("\nL1: Plugin Registration");
+
+  const pkgOpencodeJson = parseJsonc(path.join(packageRoot, "opencode.json"));
+  const expectedAgents = pkgOpencodeJson?.agent ? Object.keys(pkgOpencodeJson.agent).length : 6;
+  const expectedSkills = 4;
+  const expectedCommands = 6;
+
+  // Count actual agents in target
+  const targetOpencodeJson = parseJsonc(path.join(targetRoot, "opencode.json"));
+  const sddAgents = targetOpencodeJson?.agent
+    ? Object.keys(targetOpencodeJson.agent).filter((k) => k.startsWith("sdd-")).length
+    : 0;
+
+  report("L1", "agents registered", sddAgents >= expectedAgents ? "pass" : "warn", `${sddAgents}/${expectedAgents} SDD agents in opencode.json`);
+
+  // Count skills files
+  const skillsDir = path.join(packageRoot, ".opencode/skills");
+  const skillCount = fs.existsSync(skillsDir) ? fs.readdirSync(skillsDir).filter((f) => fs.statSync(path.join(skillsDir, f)).isDirectory()).length : 0;
+  report("L1", "skills available", skillCount >= expectedSkills ? "pass" : "warn", `${skillCount}/${expectedSkills} skill directories`);
+
+  // Count command files
+  const commandsDir = path.join(packageRoot, ".opencode/commands");
+  const cmdCount = fs.existsSync(commandsDir) ? fs.readdirSync(commandsDir).filter((f) => f.endsWith(".md")).length : 0;
+  report("L1", "commands available", cmdCount >= expectedCommands ? "pass" : "warn", `${cmdCount}/${expectedCommands} command files`);
+
+  // L2: Environment variables
+  console.log("\nL2: Environment");
+
+  const modelProfilePath = path.join(targetRoot, ".sdd", "model-profile.json");
+  const modelProfile = fs.existsSync(modelProfilePath) ? JSON.parse(fs.readFileSync(modelProfilePath, "utf-8")) : null;
+
+  if (modelProfile) {
+    const models = new Set();
+    if (modelProfile.defaultPrimary) models.add(modelProfile.defaultPrimary);
+    if (modelProfile.agents) {
+      for (const m of Object.values(modelProfile.agents)) models.add(m);
+    }
+
+    const providerChecks = [
+      { name: "OPENAI_API_KEY", pattern: /openai|gpt|o1|o3/i },
+      { name: "ANTHROPIC_API_KEY", pattern: /anthropic|claude/i },
+      { name: "GOOGLE_API_KEY", pattern: /google|gemini/i },
+      { name: "OPENCODE_ZEN_API_KEY", pattern: /zen/i },
+    ];
+
+    for (const { name, pattern } of providerChecks) {
+      const modelMatch = [...models].some((m) => pattern.test(m));
+      if (modelMatch) {
+        const hasKey = !!process.env[name];
+        report("L2", `${name}`, hasKey ? "pass" : "warn", hasKey ? "set" : "not set — models requiring this provider were detected");
+      }
+    }
+  } else {
+    report("L2", "model-profile.json", "warn", "not found — using default model routing");
+  }
+
+  // L3: Liveness probe (--deep only)
+  if (args.flags.deep) {
+    console.log("\nL3: Liveness Probe");
+
+    const primaryModel = modelProfile?.defaultPrimary || process.env.DEFAULT_MODEL || "unknown";
+    report("L3", "model endpoint", "warn", `would probe ${primaryModel} — liveness requires valid API credentials and network access`);
+    report("L3", "note", "warn", "full liveness probe requires HTTP client — run manually with curl or your provider's dashboard");
+  }
+
+  // Summary
+  console.log(`\nSummary: ${results.pass} passed, ${results.warn} warnings, ${results.fail} failures`);
+
+  if (results.fail > 0) {
+    console.log("\nAction required: Fix failing checks before using SDD commands.");
+  } else if (results.warn > 0) {
+    console.log("\nSome checks need attention but SDD should work.");
+  } else {
+    console.log("\nAll checks passed. SDD is ready to use.");
+  }
+}
+
+// ─── Warm Command ────────────────────────────────────────────────────────────
+
+function runWarm() {
+  console.log("\nWarming OpenCode plugin cache...\n");
+
+  const opencodeCacheDir = path.join(globalConfigDir, ".opencode");
+  if (!fs.existsSync(opencodeCacheDir)) {
+    console.log("OpenCode config directory not found. Run OpenCode once to initialize cache.");
+    return;
+  }
+
+  try {
+    console.log("Running bun install in plugin cache...");
+    execSync("bun install", { cwd: opencodeCacheDir, stdio: "inherit" });
+    console.log("\nPlugin cache warmed successfully.");
+  } catch (e) {
+    console.log(`Warning: bun install failed — ${e.message}`);
+    console.log("This is non-fatal. OpenCode will resolve plugins on first run.");
+  }
+}
+
+// ─── Migrate Command ─────────────────────────────────────────────────────────
+
+function runMigrate() {
+  console.log("\nMigrating from v0.2.x symlink-based installation...\n");
+
+  const MIGRATION_MARKER = ".sdd-migrated-v030";
+  const markerPath = path.join(globalConfigDir, MIGRATION_MARKER);
+
+  if (fs.existsSync(markerPath)) {
+    console.log("Migration already completed. No action needed.");
+    return;
+  }
+
+  const symlinkTargets = [
+    { dir: "commands", prefix: "sdd-" },
+    { dir: "agents", prefix: "sdd-" },
+    { dir: "rules", prefix: null },
+  ];
+
+  let removed = 0;
+
+  for (const { dir, prefix } of symlinkTargets) {
+    const dirPath = path.join(globalConfigDir, dir);
+    if (!fs.existsSync(dirPath)) continue;
+
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+      const fullPath = path.join(dirPath, entry.name);
+      try {
+        const stat = fs.lstatSync(fullPath);
+        if (!stat.isSymbolicLink()) continue;
+        if (prefix && !entry.name.startsWith(prefix)) continue;
+
+        const linkTarget = fs.readlinkSync(fullPath);
+        if (linkTarget.includes("sdd-multiagent-opencode") || linkTarget.includes("opencode-agent-rules")) {
+          fs.unlinkSync(fullPath);
+          console.log(`  Removed: ${path.join(dir, entry.name)}`);
+          removed++;
+        }
+      } catch {
+        // skip
       }
     }
+  }
 
-    console.log(`\nNext steps:`);
-    console.log(`  1. Edit .sdd/project-profile.json with your stack`);
-    console.log(`  2. Run: /brief my-feature "Feature description"`);
-    console.log(`  3. Optional TDD: /tasks my-feature --tdd`);
+  if (removed > 0) {
+    try {
+      fs.writeFileSync(markerPath, new Date().toISOString());
+    } catch {
+      // skip
+    }
+    console.log(`\nMigration complete: ${removed} old symlinks removed.`);
+    console.log("Plugin-native registration is now active.");
+  } else {
+    console.log("No old symlinks found. Nothing to migrate.");
   }
 }
 
+// ─── Main ────────────────────────────────────────────────────────────────────
+
 const args = parseArgs(process.argv);
 
 if (args.command === "help") {
   usage();
 } else if (args.command === "init") {
   runInit(args);
+} else if (args.command === "doctor") {
+  runDoctor(args);
+} else if (args.command === "warm") {
+  runWarm();
+} else if (args.command === "migrate") {
+  runMigrate();
+} else if (args.command === "test") {
+  console.log("Smoke test placeholder — plugin loads correctly.");
 } else {
   console.error(`Unknown command: ${args.command}`);
   usage();