devloom 1.0.0 → 1.1.0

package/scripts/model-capabilities.mjs

@@ -0,0 +1,169 @@
+// Provider-agnostic model identity, candidate resolution, and capability hints
+// for DevLoom profiles. Pure module: no fs, no child_process, no secrets.
+//
+// Design rules:
+// - Model IDs are conceptually `provider/model` (the model segment may itself
+//   contain slashes, e.g. `lmstudio/google/gemma-4-26b`). Any provider is valid;
+//   availability always comes from `opencode models` at the call site.
+// - MODEL_FAMILIES is the authoritative capability source for known families.
+//   `capabilitiesFor()` falls back to conservative name heuristics for unknown
+//   models — hints only, never a substitute for availability validation.
+// - Nothing here is MiMo-specific; MiMo is simply the first family registered.
+
+/** Conceptual model families with candidate chains + capability declarations. */
+export const MODEL_FAMILIES = {
+  mimoV26Flash: {
+    id: "mimoV26Flash",
+    label: "MiMo V2.6 Flash",
+    // Provider prefix is NOT assumed — resolution picks the first available.
+    candidates: [
+      "mimo/mimo-v2.6-flash",
+      "xiaomi/mimo-v2.6-flash",
+      "opencode-go/mimo-v2.6-flash",
+    ],
+    familyPattern: /(^|\/)mimo-v2\.6/i,
+    capabilities: {
+      vision: true,
+      multimodal: true,
+      coding: "high",
+      reasoning: "high",
+      toolUse: true,
+      longContext: true,
+      speed: "fast",
+      costClass: "low",
+      orchestration: true,
+      verification: "high",
+    },
+  },
+}
+
+/** MiMo V2.6 Flash candidate chain (re-exported for profile manager + tests). */
+export const MIMO_V26_FLASH_CANDIDATES = MODEL_FAMILIES.mimoV26Flash.candidates
+
+/**
+ * Vision-capable fallbacks used when a vision-required role (vision,
+ * visual-critic) resolves to a text-only model. Ordered by existing DevLoom
+ * convention: Go multimodal models first, free-tier vision model last.
+ */
+export const VISION_FALLBACK_CANDIDATES = [
+  "opencode-go/qwen3.6-plus",
+  "opencode-go/glm-5.3-flash",
+  "opencode-go/deepseek-v4-flash-vision-exp",
+  "opencode-go/minimax-m3",
+  "opencode/mimo-v2.5-free",
+]
+
+/** Roles whose assigned model must accept image input. */
+const VISION_REQUIRED_ROLES = new Set(["vision", "visual-critic"])
+
+const PROVIDER_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._+/-]*$/
+
+/**
+ * True for any well-formed OpenCode model identifier of the form
+ * `provider/model` (the model segment may contain further slashes).
+ * Availability is a separate concern — see findAvailableCandidate().
+ */
+export function isValidModelId(id) {
+  if (typeof id !== "string") return false
+  if (!id || id.length > 256 || /\s/.test(id)) return false
+  const slash = id.indexOf("/")
+  if (slash <= 0 || slash === id.length - 1) return false
+  const provider = id.slice(0, slash)
+  const model = id.slice(slash + 1)
+  if (!PROVIDER_RE.test(provider)) return false
+  if (!MODEL_RE.test(model)) return false
+  if (model.startsWith("/") || model.endsWith("/")) return false
+  return true
+}
+
+/** First candidate present in the available list, or null. */
+export function findAvailableCandidate(candidates, available) {
+  if (!Array.isArray(candidates) || !Array.isArray(available)) return null
+  for (const candidate of candidates) {
+    if (available.includes(candidate)) return candidate
+  }
+  return null
+}
+
+/**
+ * Resolve a candidate chain against the available model list.
+ *
+ * Returns { model, attempted, exact, fallback }:
+ * - exact hit on any declared candidate → exact: true
+ * - optional opts.familyPattern permits a same-family fallback (e.g.
+ *   mimo-v2.6-flash → mimo-v2.6-pro) reported with exact: false so callers
+ *   can surface "requested vs resolved" transparently
+ * - otherwise model: null — callers must fail loudly, never pretend
+ */
+export function resolveModelCandidate(candidates, available, opts = {}) {
+  const attempted = Array.isArray(candidates) ? [...candidates] : []
+  const list = Array.isArray(available) ? available : []
+  const exact = findAvailableCandidate(attempted, list)
+  if (exact) return { model: exact, attempted, exact: true, fallback: null }
+  if (opts.familyPattern instanceof RegExp) {
+    const family = list.find((m) => isValidModelId(m) && opts.familyPattern.test(m))
+    if (family) return { model: family, attempted, exact: false, fallback: family }
+  }
+  return { model: null, attempted, exact: false, fallback: null }
+}
+
+function familyCapabilities(modelId) {
+  for (const family of Object.values(MODEL_FAMILIES)) {
+    if (family.candidates.includes(modelId)) return { ...family.capabilities }
+    if (family.familyPattern instanceof RegExp && family.familyPattern.test(modelId)) {
+      return { ...family.capabilities }
+    }
+  }
+  return null
+}
+
+/**
+ * Capability hints for a model id. Authoritative for registered families;
+ * conservative heuristics otherwise. Callers must not treat `vision: false`
+ * from the heuristic path as proof a model cannot see images — it only means
+ * DevLoom has no evidence, which is the safe direction for routing decisions.
+ */
+export function capabilitiesFor(modelId) {
+  const id = typeof modelId === "string" ? modelId : ""
+  const known = familyCapabilities(id)
+  if (known) return known
+  const caps = {
+    vision: false,
+    multimodal: false,
+    coding: "medium",
+    reasoning: "medium",
+    toolUse: true,
+    longContext: false,
+    speed: "medium",
+    costClass: "unknown",
+    orchestration: false,
+    verification: "medium",
+  }
+  // Known multimodal markers observed in OpenCode catalogs.
+  if (/vision|minimax-m3|qwen3\.6|mimo-v2\.[56]|glm-5\.3/i.test(id)) {
+    caps.vision = true
+    caps.multimodal = true
+  }
+  if (/-free$|big-pickle/.test(id)) caps.costClass = "free"
+  if (/flash/i.test(id)) caps.speed = "fast"
+  if (/pro|max|kimi-k3|glm-5\.2$/.test(id)) {
+    caps.reasoning = "high"
+    caps.coding = "high"
+  }
+  if (/kimi-k2\.7-code|kimi-k3|qwen3\.7|longcat|glm-5\.3$/.test(id)) caps.longContext = true
+  return caps
+}
+
+export function roleRequiresVision(role) {
+  return VISION_REQUIRED_ROLES.has(role)
+}
+
+/** Whether a model satisfies a role's capability requirements. */
+export function modelMeetsRole(modelId, role) {
+  if (!roleRequiresVision(role)) return { ok: true, missing: [] }
+  const caps = capabilitiesFor(modelId)
+  const missing = []
+  if (!caps.vision) missing.push("vision")
+  return { ok: missing.length === 0, missing }
+}

package/scripts/plugin-cache.mjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+// Shared helpers for keeping the OpenCode plugin cache in sync with the
+// installed DevLoom package.
+//
+// OpenCode installs npm plugins into `~/.cache/opencode/packages/<spec>` with
+// `ignoreScripts: true`, so the package `postinstall` never runs there and the
+// cached copy can silently go stale. These helpers refresh the cached package
+// files (dist, agents, commands, ...) directly from a package source directory.
+import {
+  existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync,
+  copyFileSync, rmSync, statSync,
+} from "fs"
+import { resolve, dirname, join } from "path"
+import { fileURLToPath } from "url"
+import { homedir, platform } from "os"
+import { execFileSync } from "node:child_process"
+
+export function getOpenCodeCacheDir(_platform = platform(), _homedir = homedir(), _env = process.env) {
+  if (_platform === "win32") {
+    return resolve(_env.LOCALAPPDATA ?? _homedir, "cache", "opencode")
+  }
+  if (_platform === "darwin") {
+    const lib = resolve(_homedir, "Library", "Caches", "opencode")
+    const legacy = resolve(_env.XDG_CACHE_HOME ?? join(_homedir, ".cache"), "opencode")
+    // Some opencode builds keep using ~/.cache/opencode on macOS; prefer the
+    // platform path unless only the legacy one exists on disk.
+    if (!existsSync(lib) && existsSync(legacy)) return legacy
+    return lib
+  }
+  return resolve(_env.XDG_CACHE_HOME ?? join(_homedir, ".cache"), "opencode")
+}
+
+// Names of OpenCode plugin cache entries that contain a `devloom` package.
+// Both `devloom` (legacy) and `devloom@latest` (current config spec) exist in
+// the wild; refreshing both is harmless and covers every loader path.
+export function openCodePluginEntries(cacheDir) {
+  const packagesDir = join(cacheDir, "packages")
+  if (!existsSync(packagesDir)) return []
+  let entries = []
+  try {
+    entries = readdirSync(packagesDir)
+  } catch {
+    return []
+  }
+  return entries.filter((entry) => {
+    try {
+      return existsSync(join(packagesDir, entry, "node_modules", "devloom"))
+    } catch {
+      return false
+    }
+  })
+}
+
+function copyDir(src, dest) {
+  if (existsSync(dest) && !statSync(src).isDirectory()) {
+    rmSync(dest, { recursive: true, force: true })
+  }
+  const stat = statSync(src)
+  if (stat.isDirectory()) {
+    mkdirSync(dest, { recursive: true })
+    for (const name of readdirSync(src)) {
+      copyDir(join(src, name), join(dest, name))
+    }
+  } else {
+    mkdirSync(dirname(dest), { recursive: true })
+    copyFileSync(src, dest)
+  }
+}
+
+// Rebuild dist/ from source before it is copied into the OpenCode plugin cache,
+// so a refresh never deploys stale compiled code. Runs the package's declared
+// `build` script (npm run build) when present. Best-effort: never throws —
+// failures are reported in the returned summary and the caller proceeds with
+// whatever dist already exists.
+export function buildPackageDist(sourceDir, exec = execFileSync) {
+  const summary = { built: false, skipped: "", errors: [] }
+  try {
+    const pkg = JSON.parse(readFileSync(join(sourceDir, "package.json"), "utf8"))
+    const build = pkg.scripts && typeof pkg.scripts.build === "string" ? pkg.scripts.build : ""
+    if (!build) {
+      summary.skipped = "no build script in package.json"
+      return summary
+    }
+    exec("npm", ["run", "build"], { cwd: sourceDir, stdio: "ignore", timeout: 120_000 })
+    summary.built = true
+  } catch (err) {
+    summary.errors.push(`build failed: ${err && typeof err.message === "string" ? err.message : String(err)}`)
+  }
+  return summary
+}
+
+// Copy the current package (dist, agents, commands, ... per package.json
+// `files` plus package.json itself) into every existing OpenCode plugin cache
+// entry. Best-effort: never throws, reports per-entry results.
+export function refreshOpenCodePluginCache(sourceDir, cacheDir = getOpenCodeCacheDir(), exec = execFileSync) {
+  const summary = { refreshed: [], skipped: [], errors: [], build: null }
+  // Root-cause guard against the "status ok but stale" class of bugs: the
+  // refresh pipeline must ship freshly built code, not whatever dist happens
+  // to sit in the source tree. Rebuild before copying.
+  const build = buildPackageDist(sourceDir, exec)
+  summary.build = build
+  if (build.errors.length > 0) summary.errors.push(...build.errors)
+  let roots = []
+  try {
+    const pkg = JSON.parse(readFileSync(join(sourceDir, "package.json"), "utf8"))
+    roots = Array.isArray(pkg.files) ? pkg.files : []
+  } catch (err) {
+    summary.errors.push(`cannot read package.json at ${sourceDir}: ${err.message}`)
+    return summary
+  }
+
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) {
+    summary.skipped.push(cacheDir)
+    return summary
+  }
+
+  const toCopy = [...roots, "package.json"]
+  for (const entry of entries) {
+    const destPkg = join(cacheDir, "packages", entry, "node_modules", "devloom")
+    let copied = 0
+    for (const root of toCopy) {
+      const src = join(sourceDir, root)
+      if (!existsSync(src)) continue
+      try {
+        copyDir(src, join(destPkg, root))
+        copied++
+      } catch (err) {
+        summary.errors.push(`${entry}/${root}: ${err.message}`)
+      }
+    }
+    if (copied > 0) summary.refreshed.push(entry)
+  }
+  return summary
+}
+
+// Sync the installed agent files into the cached plugin package so a profile
+// change is reflected even in the cache copy. Best-effort, never throws.
+export function refreshOpenCodePluginAgentFiles(agentsDir, cacheDir = getOpenCodeCacheDir()) {
+  const summary = { refreshed: [], skipped: [], errors: [] }
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) {
+    summary.skipped.push(cacheDir)
+    return summary
+  }
+  for (const entry of entries) {
+    const destAgents = join(cacheDir, "packages", entry, "node_modules", "devloom", "agents")
+    try {
+      mkdirSync(destAgents, { recursive: true })
+      const files = readdirSync(agentsDir).filter((f) => f.startsWith("devloom-") && f.endsWith(".md"))
+      for (const file of files) {
+        copyFileSync(join(agentsDir, file), join(destAgents, file))
+      }
+      summary.refreshed.push(entry)
+    } catch (err) {
+      summary.errors.push(`${entry}: ${err.message}`)
+    }
+  }
+  return summary
+}
+
+// Sync the runtime dependencies of the installed package into every existing
+// cache entry. The TUI plugin (dist/tui.js) imports `@opentui/solid` +
+// `solid-js`, and OpenCode installs plugins with `ignoreScripts` so those deps
+// are not guaranteed to exist in the cache. Running `npm install` inside the
+// cached plugin directory mirrors what a normal package install would do,
+// without touching the cache entry root (no pruning of existing packages).
+// Best-effort: never throws, reports per-entry results.
+export function syncOpenCodePluginDependencies(sourceDir, cacheDir = getOpenCodeCacheDir(), exec = execFileSync) {
+  const summary = { synced: [], skipped: [], errors: [] }
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) {
+    summary.skipped.push(cacheDir)
+    return summary
+  }
+  for (const entry of entries) {
+    const pluginDir = join(cacheDir, "packages", entry, "node_modules", "devloom")
+    try {
+      exec(
+        "npm",
+        [
+          "install", "--prefix", pluginDir,
+          "--no-save", "--ignore-scripts", "--no-audit", "--no-fund",
+          "--no-package-lock", "--omit=dev", "--loglevel=error",
+        ],
+        { stdio: "ignore", timeout: 120_000 }
+      )
+      summary.synced.push(entry)
+    } catch (err) {
+      summary.errors.push(`${entry}: ${err && typeof err.message === "string" ? err.message : String(err)}`)
+    }
+  }
+  return summary
+}
+
+// Per-entry cache health breakdown.
+// "ok"   – every existing cache entry has the config hook that injects DevLoom
+//          agents AND the current feature code (the profile-filter wiring in
+//          dist/agents.js, detected via `agentVariantVisible`). Conservative:
+//          one stale entry makes the whole cache stale.
+// "stale"– at least one cache entry lacks the config hook or the feature code.
+// "missing" – DevLoom was never installed as an OpenCode plugin.
+export function pluginCacheStatusDetail(cacheDir = getOpenCodeCacheDir()) {
+  const entries = openCodePluginEntries(cacheDir)
+  if (entries.length === 0) return { status: "missing", entries: [] }
+  const details = entries.map((entry) => {
+    const base = join(cacheDir, "packages", entry, "node_modules", "devloom")
+    let hook = false
+    let featureCode = false
+    let orchestratorLabel = false
+    try {
+      const pluginJs = join(base, "dist", "plugin.js")
+      if (existsSync(pluginJs)) {
+        hook = readFileSync(pluginJs, "utf8").includes("injectDevloomAgents")
+      }
+    } catch { /* entry treated as stale */ }
+    try {
+      // The profile-filter feature marker: present only in freshly built dist.
+      const agentsJs = join(base, "dist", "agents.js")
+      if (existsSync(agentsJs)) {
+        featureCode = readFileSync(agentsJs, "utf8").includes("agentVariantVisible")
+      }
+    } catch { /* entry treated as stale */ }
+    try {
+      const orchestratorMd = join(base, "agents", "devloom-orchestrator.md")
+      if (existsSync(orchestratorMd)) {
+        orchestratorLabel = /\(profile: [^)]+\)/.test(readFileSync(orchestratorMd, "utf8"))
+      }
+    } catch { /* label unknown -> false */ }
+    return { entry, hook, featureCode, orchestratorLabel }
+  })
+  const status = details.every((detail) => detail.hook && detail.featureCode) ? "ok" : "stale"
+  return { status, entries: details }
+}
+
+export function pluginCacheStatus(cacheDir = getOpenCodeCacheDir()) {
+  return pluginCacheStatusDetail(cacheDir).status
+}
+
+export function runCli(args, cacheDir = getOpenCodeCacheDir()) {
+  const command = args[0] || ""
+  if (command === "status") {
+    const detail = pluginCacheStatusDetail(cacheDir)
+    console.log(`DevLoom plugin cache: ${detail.status}`)
+    if (detail.entries.length === 0) {
+      console.log("  No DevLoom plugin cache entry found.")
+      console.log("  Install the plugin once with: opencode plugin devloom --global")
+      console.log("  then refresh the cache with: npm install -g devloom && node $(npm root -g)/devloom/postinstall.mjs")
+      return detail.status
+    }
+    for (const entry of detail.entries) {
+      const hook = entry.hook ? "yes" : "NO"
+      const feature = entry.featureCode ? "yes" : "NO"
+      const label = entry.orchestratorLabel ? "yes" : "no"
+      console.log(`  ${entry.entry}: config-hook=${hook} feature-code=${feature} orchestrator-profile-label=${label}`)
+    }
+    if (detail.status !== "ok") {
+      console.log("  Fix: run /devloom-refresh, then restart opencode (or: opencode --continue).")
+    }
+    return detail.status
+  }
+  console.log("DevLoom plugin cache helpers")
+  console.log("Commands:")
+  console.log("  devloom plugin-cache status  — print cache health (ok/stale/missing) + per-entry info")
+  return null
+}
+
+const isMain = process.argv[1] ? fileURLToPath(import.meta.url) === resolve(process.argv[1]) : false
+if (isMain) runCli(process.argv.slice(2))