@mirrowel/opencode-subagent-explorer 0.1.0-dev.1

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@mirrowel/opencode-subagent-explorer",
+  "version": "0.1.0-dev.1",
+  "type": "module",
+  "description": "OpenCode plugin for exploring and cleaning up subagent sessions of the current session",
+  "license": "MIT",
+  "author": "Mirrowel",
+  "homepage": "https://github.com/Mirrowel/opencode-subagent-explorer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mirrowel/opencode-subagent-explorer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mirrowel/opencode-subagent-explorer/issues"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    },
+    "./wizard": {
+      "types": "./dist/wizard.d.ts",
+      "import": "./dist/wizard.js"
+    },
+    "./sessions": {
+      "types": "./dist/sessions.d.ts",
+      "import": "./dist/sessions.js"
+    },
+    "./tui-host": {
+      "types": "./dist/tui-host.d.ts",
+      "import": "./dist/tui-host.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "subagent",
+    "session",
+    "cleanup"
+  ],
+  "oc-plugin": [
+    "server",
+    "tui"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc --outDir dist --declaration && npm run build:tui",
+    "build:tui": "bun scripts/build-tui.mjs",
+    "ci": "npm run release:intent:check && npm run ci:package",
+    "ci:package": "npm run typecheck && npm run build && npm run test:unit && npm run test:tui-reactivity && npm run test:tui-startup && npm run pack:dry-run && npm run test:tui-package",
+    "commit:check": "npm run ci",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "pack:dry-run": "node scripts/pack-dry-run.mjs",
+    "release:intent": "node scripts/set-release-intent.mjs",
+    "release:intent:check": "node scripts/check-release-intent.mjs",
+    "test:unit": "node scripts/unit-tests.mjs",
+    "test:tui-reactivity": "bun --conditions=browser scripts/tui-reactivity-smoke.mjs",
+    "test:tui-package": "node scripts/tui-package-smoke.mjs",
+    "test:tui-startup": "node scripts/tui-startup-smoke.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "@opentui/solid": "^0.4.1",
+    "comment-json": "^4.2.5",
+    "solid-js": "1.9.12"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Subagent Explorer server plugin (v1).
+ *
+ * The explorer is a TUI-driven tool: the server side exists purely so a
+ * single opencode.json registration loads the plugin (and self-wires the
+ * matching tui.json entry - see selfwire.ts). No hooks are registered; the
+ * plugin never intercepts runtime behavior.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { ensureTuiRegistration, isSubagentExplorerSpec } from "./selfwire.js"
+
+export const plugin: Plugin = async (input) => {
+  // File-scan only, wrapped in try/catch: never blocks or breaks startup.
+  try {
+    ensureTuiRegistration({ directory: input.directory, worktree: input.worktree, env: process.env })
+  } catch {
+    /* self-wiring is best-effort */
+  }
+  return {}
+}
+
+export const __testInternals = { ensureTuiRegistration, isSubagentExplorerSpec }

package/src/palette-category.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared palette category for Mirrowel OpenCode plugins loaded in the same
+ * session. Every family plugin declares its own label into a process-wide
+ * registry at TUI activation; a delayed reconciler joins all declared labels
+ * (alphabetical, deterministic) and writes the join into every registered
+ * command object, so the palette shows one combined section. A plugin loaded
+ * alone keeps its own name; third-party plugins never declare and stay out.
+ *
+ * Labels are defined only in each plugin's entry point - this module carries
+ * no per-plugin data. Keep the logic copies in sync across family repos.
+ */
+
+const REGISTRY_KEY = Symbol.for("mirrowel.opencode.paletteCategory")
+
+// v1 command objects group via `category`; v2 keymap commands use `group`.
+// Stamping both keeps one registry meaningful on both hosts.
+type CategorizedCommand = { category?: string; group?: string }
+type RegistryEntry = { label: string; commands: CategorizedCommand[] }
+type Registry = { entries: RegistryEntry[] }
+
+function registry(): Registry {
+  const globals = globalThis as { [key: symbol]: Registry | undefined }
+  if (!globals[REGISTRY_KEY]) globals[REGISTRY_KEY] = { entries: [] }
+  return globals[REGISTRY_KEY]!
+}
+
+function joinLabels(labels: string[]): string {
+  if (labels.length <= 1) return labels[0] ?? ""
+  return `${labels.slice(0, -1).join(", ")} & ${labels[labels.length - 1]!}`
+}
+
+function joinedCategory(): string {
+  const labels = [...new Set(registry().entries.map((entry) => entry.label))].sort((a, b) => a.localeCompare(b))
+  return joinLabels(labels)
+}
+
+/**
+ * Declares this plugin's category label and attaches command objects whose
+ * `category` field is kept in sync. Returns the current join, so the very
+ * first registration already renders correctly even before reconcilers run.
+ */
+export function declarePaletteCategory(label: string, ...commands: CategorizedCommand[]): string {
+  const reg = registry()
+  let entry = reg.entries.find((item) => item.label === label)
+  if (!entry) {
+    entry = { label, commands: [] }
+    reg.entries.push(entry)
+  }
+  for (const command of commands) {
+    if (command && !entry.commands.includes(command)) entry.commands.push(command)
+  }
+  reconcilePaletteCategories()
+  return joinedCategory()
+}
+
+/** Live join for callback-style command registration (reads fresh each call). */
+export function currentPaletteCategory(): string {
+  return joinedCategory()
+}
+
+/** Writes the current join into every declared command (idempotent). */
+export function reconcilePaletteCategories(): void {
+  const category = joinedCategory()
+  for (const entry of registry().entries) {
+    for (const command of entry.commands) {
+      command.category = category
+      command.group = category
+    }
+  }
+}
+
+/** Delayed reconciles so later-activating siblings join before the user opens the palette. */
+export function schedulePaletteReconcile(delaysMs: readonly number[] = [2000, 6000]): void {
+  for (const delay of delaysMs) {
+    const timer = setTimeout(() => reconcilePaletteCategories(), delay)
+    ;(timer as { unref?: () => void }).unref?.()
+  }
+}
+
+/** Tests only: drop all declarations. */
+export function __resetPaletteRegistry(): void {
+  ;(globalThis as { [key: symbol]: Registry | undefined })[REGISTRY_KEY] = undefined
+}

package/src/selfwire.ts

@@ -0,0 +1,311 @@
+/**
+ * Self-wiring for the subagent-explorer TUI (v1 hosts only).
+ *
+ * OpenCode loads server plugins from the `plugin` array in opencode.json
+ * layers but TUI plugins only from tui.json layers. When subagent-explorer
+ * is registered standalone (opencode.json) without a matching tui.json
+ * entry, the explorer command never loads. ensureTuiRegistration() mirrors
+ * the server registration into tui.json AT THE SAME CONFIG LEVEL
+ * (global -> global, project -> project) with the same auto-correct
+ * semantics as Config Studio's selfwire:
+ *
+ * - identity matching: any checkout counts (repo folder named plain
+ *   `subagent-explorer` or `opencode-subagent-explorer`), not just this
+ *   running instance's directory
+ * - the tui entry must MATCH the server registration; local checkouts win
+ *   over npm installs when both are registered
+ * - stale mirrors (tui entries at levels without a server registration) are
+ *   removed; duplicates are deduped
+ *
+ * When Config Studio is registered anywhere (it can embed subagent-explorer
+ * and provides the Tools menu entry), selfwiring is skipped entirely so the
+ * two never fight over the TUI slot. v2 hosts never run this module: they
+ * auto-discover ./tui from server-declared plugins, and the v2 setup does
+ * not import it.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import { parse, stringify } from "comment-json"
+
+const EXPLORER_NPM = "@mirrowel/opencode-subagent-explorer"
+const STUDIO_NPM = "@mirrowel/opencode-config-studio"
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase()
+}
+
+function specPathSegments(spec: string): string | undefined {
+  if (!spec.startsWith("file:")) return undefined
+  try {
+    let url = spec
+    if (!url.startsWith("file:///") && url.startsWith("file://")) url = `file:///${url.slice("file://".length)}`
+    return normalizePath(new URL(url).pathname)
+  } catch {
+    return undefined
+  }
+}
+
+function isLocalSpec(spec: string): boolean {
+  return spec.startsWith("file:") || /^([a-zA-Z]:[\\/]|\/)/.test(spec)
+}
+
+export function isSubagentExplorerSpec(spec: unknown): spec is string {
+  if (typeof spec !== "string" || spec.length === 0) return false
+  if (spec === EXPLORER_NPM || spec.startsWith(`${EXPLORER_NPM}@`)) return true
+  const path = specPathSegments(spec)
+  if (!path) return false
+  if (path.endsWith("/opencode-subagent-explorer") || path.endsWith("/subagent-explorer")) return true
+  // Cache/wrapper layouts: <base>/@mirrowel/opencode-subagent-explorer@<tag>[/node_modules/...]
+  return path.includes("/@mirrowel/opencode-subagent-explorer") || path.includes("/node_modules/@mirrowel/opencode-subagent-explorer")
+}
+
+export function isConfigStudioSpec(spec: unknown): spec is string {
+  if (typeof spec !== "string" || spec.length === 0) return false
+  if (spec === STUDIO_NPM || spec.startsWith(`${STUDIO_NPM}@`)) return true
+  const path = specPathSegments(spec)
+  if (!path) return false
+  return path.endsWith("/opencode-config-studio")
+}
+
+function specStrings(data: Record<string, unknown>): string[] {
+  const result: string[] = []
+  for (const key of ["plugin", "plugins"] as const) {
+    const array = data[key]
+    if (!Array.isArray(array)) continue
+    for (const entry of array) {
+      const spec =
+        typeof entry === "string"
+          ? entry
+          : Array.isArray(entry) && typeof entry[0] === "string"
+            ? (entry[0] as string)
+            : entry && typeof entry === "object" && typeof (entry as { package?: unknown }).package === "string"
+              ? (entry as { package: string }).package
+              : undefined
+      if (spec !== undefined) result.push(spec)
+    }
+  }
+  return result
+}
+
+function readJsonc(path: string): Record<string, unknown> {
+  try {
+    if (!existsSync(path)) return {}
+    return parse(readFileSync(path, "utf8")) as unknown as Record<string, unknown>
+  } catch {
+    return {}
+  }
+}
+
+function sameDir(a: string, b: string): boolean {
+  return normalizePath(a) === normalizePath(b)
+}
+
+function levelDirOf(configPath: string): string {
+  let dir = dirname(configPath)
+  if (basename(dir) === ".opencode") dir = dirname(dir)
+  return dir
+}
+
+function globalConfigDir(env?: NodeJS.ProcessEnv): string {
+  if (env?.["OPENCODE_CONFIG_DIR"]) return env["OPENCODE_CONFIG_DIR"]
+  if (env?.["XDG_CONFIG_HOME"]) return join(env["XDG_CONFIG_HOME"], "opencode")
+  const home = process.env.USERPROFILE ?? process.env.HOME ?? ""
+  return join(home, ".config", "opencode")
+}
+
+function opencodeLayerPaths(input: { directory?: string; worktree?: string; env?: NodeJS.ProcessEnv }): string[] {
+  const paths: string[] = []
+  const pushDir = (dir: string) => {
+    for (const candidate of [join(dir, "opencode.json"), join(dir, "opencode.jsonc"), join(dir, ".opencode", "opencode.json"), join(dir, ".opencode", "opencode.jsonc")]) {
+      if (existsSync(candidate) && !paths.includes(candidate)) paths.push(candidate)
+    }
+  }
+  const globalDir = globalConfigDir(input.env)
+  if (input.env?.["OPENCODE_CONFIG"]) {
+    if (existsSync(input.env["OPENCODE_CONFIG"])) paths.push(input.env["OPENCODE_CONFIG"])
+  } else {
+    pushDir(globalDir)
+  }
+  if (input.directory && input.worktree && input.directory.startsWith(input.worktree)) {
+    let current: string | undefined = input.directory
+    for (let guard = 0; guard < 64 && current; guard++) {
+      pushDir(current)
+      if (current === input.worktree || current === dirname(current)) break
+      current = dirname(current)
+    }
+  }
+  return paths
+}
+
+function tuiLayerPaths(input: { directory?: string; worktree?: string; env?: NodeJS.ProcessEnv }): string[] {
+  const paths: string[] = []
+  const globalDir = globalConfigDir(input.env)
+  const globalTui = join(globalDir, "tui.json")
+  if (existsSync(globalTui)) paths.push(globalTui)
+  const envTui = input.env?.["OPENCODE_TUI_CONFIG"]
+  if (envTui && existsSync(envTui)) paths.push(envTui)
+  if (input.directory && input.worktree && input.directory.startsWith(input.worktree)) {
+    let current: string | undefined = input.directory
+    for (let guard = 0; guard < 64 && current; guard++) {
+      for (const candidate of [join(current, "tui.json"), join(current, ".opencode", "tui.json")]) {
+        if (existsSync(candidate) && !paths.includes(candidate)) paths.push(candidate)
+      }
+      if (current === input.worktree || current === dirname(current)) break
+      current = dirname(current)
+    }
+  }
+  return paths
+}
+
+function ownIndices(tuiPath: string): number[] {
+  const data = readJsonc(tuiPath)
+  const plugin = data["plugin"]
+  if (!Array.isArray(plugin)) return []
+  const indices: number[] = []
+  plugin.forEach((entry, index) => {
+    const spec = typeof entry === "string" ? entry : Array.isArray(entry) && typeof entry[0] === "string" ? (entry[0] as string) : undefined
+    if (spec !== undefined && isSubagentExplorerSpec(spec)) indices.push(index)
+  })
+  return indices
+}
+
+function preferLocal(specs: string[]): string[] {
+  const local = specs.filter(isLocalSpec)
+  const npm = specs.filter((spec) => !local.includes(spec))
+  return [...local, ...npm]
+}
+
+function atomicWrite(path: string, content: string, stateDir: string): boolean {
+  try {
+    const backupDir = join(stateDir, "selfwire-backups")
+    mkdirSync(backupDir, { recursive: true })
+    if (existsSync(path)) {
+      const backup = join(backupDir, `${basename(path)}.${Date.now()}.bak`)
+      writeFileSync(backup, readFileSync(path, "utf8"), "utf8")
+    }
+    const temp = `${path}.se-tmp`
+    writeFileSync(temp, content, "utf8")
+    renameSync(temp, path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export type WireResult =
+  | { status: "skipped-studio" }
+  | { status: "already-wired"; spec: string }
+  | { status: "wired"; spec: string; target: string }
+  | { status: "corrected"; spec: string; target: string }
+  | { status: "not-registered" }
+  | { status: "failed"; error: string }
+
+/**
+ * Mirrors the standalone subagent-explorer server registration into
+ * tui.json (same config level). No-op when Config Studio is registered
+ * anywhere - it embeds subagent-explorer and provides the Tools entry
+ * itself.
+ */
+export function ensureTuiRegistration(input: { directory?: string; worktree?: string; env?: NodeJS.ProcessEnv } = {}): WireResult {
+  try {
+    const opencodeLayers = opencodeLayerPaths(input)
+    const tuiLayers = tuiLayerPaths(input)
+
+    // Config Studio present anywhere (server or tui layers) -> stand down.
+    for (const layer of [...opencodeLayers, ...tuiLayers]) {
+      if (specStrings(readJsonc(layer)).some((spec) => isConfigStudioSpec(spec))) {
+        return { status: "skipped-studio" }
+      }
+    }
+
+    const registrations = opencodeLayers
+      .map((path) => ({
+        path,
+        level: levelDirOf(path),
+        specs: specStrings(readJsonc(path)).filter((spec) => isSubagentExplorerSpec(spec)),
+      }))
+      .filter((layer) => layer.specs.length > 0)
+    if (registrations.length === 0) return { status: "not-registered" }
+
+    const preferAt = (layers: typeof registrations): string | undefined => {
+      const ordered = [...layers].sort((a, b) => {
+        const aLocal = a.specs.some(isLocalSpec)
+        const bLocal = b.specs.some(isLocalSpec)
+        if (aLocal !== bLocal) return aLocal ? -1 : 1
+        return 0
+      })
+      const first = ordered[0]
+      return first ? preferLocal(first.specs)[0] : undefined
+    }
+    const wanted = preferAt(registrations)
+    if (!wanted) return { status: "not-registered" }
+    const wantedLevel = registrations.find((layer) => layer.specs.includes(wanted))?.level ?? globalConfigDir(input.env)
+    const target = sameDir(wantedLevel, globalConfigDir(input.env))
+      ? join(globalConfigDir(input.env), "tui.json")
+      : join(wantedLevel, "tui.json")
+
+    const stateDir = join(globalConfigDir(input.env), "subagent-explorer")
+    let wired = false
+    let corrected = false
+
+    const seen = new Set<string>()
+    const fixTuiFile = (tuiPath: string, level: string) => {
+      if (seen.has(tuiPath)) return
+      seen.add(tuiPath)
+      const indices = ownIndices(tuiPath)
+      if (indices.length === 0) return
+      const levelLayers = registrations.filter((layer) => sameDir(layer.level, level))
+      const data = readJsonc(tuiPath)
+      const plugin = data["plugin"]
+      if (!Array.isArray(plugin)) return
+      if (levelLayers.length === 0) {
+        // Stale mirror: no server registration at this level.
+        for (const index of [...indices].sort((a, b) => b - a)) plugin.splice(index, 1)
+        corrected = true
+      } else {
+        const wantedHere = preferAt(levelLayers) ?? wanted
+        const keepIndex = indices[0]!
+        let changed = false
+        if (indices.length > 1) {
+          for (const index of [...indices].slice(1).sort((a, b) => b - a)) plugin.splice(index, 1)
+          changed = true
+        }
+        const entry = plugin[keepIndex]
+        const spec = typeof entry === "string" ? entry : Array.isArray(entry) && typeof entry[0] === "string" ? (entry[0] as string) : undefined
+        if (spec !== wantedHere) {
+          if (Array.isArray(entry)) entry[0] = wantedHere
+          else plugin[keepIndex] = wantedHere
+          changed = true
+        }
+        if (changed) corrected = true
+        else return
+      }
+      if (!atomicWrite(tuiPath, stringify(data, null, 2) + "\n", stateDir)) {
+        throw new Error(`failed to write ${tuiPath}`)
+      }
+    }
+
+    for (const layer of tuiLayers) fixTuiFile(layer, levelDirOf(layer))
+
+    // Ensure the registration level carries its mirror (independent of the
+    // correction pass above - an empty plugin array still needs the entry).
+    const targetIndices = existsSync(target) ? ownIndices(target) : []
+    if (targetIndices.length === 0) {
+      const data = readJsonc(target)
+      const plugin = Array.isArray(data["plugin"]) ? (data["plugin"] as unknown[]) : []
+      plugin.push(wanted)
+      data["plugin"] = plugin
+      if (!atomicWrite(target, stringify(data, null, 2) + "\n", stateDir)) {
+        return { status: "failed", error: `failed to write ${target}` }
+      }
+      wired = true
+    }
+
+    if (wired) return { status: "wired", spec: wanted, target }
+    if (corrected) return { status: "corrected", spec: wanted, target }
+    return { status: "already-wired", spec: wanted }
+  } catch (error) {
+    return { status: "failed", error: error instanceof Error ? error.message : String(error) }
+  }
+}

package/src/server.ts

@@ -0,0 +1,17 @@
+import { plugin } from "./index.js"
+import { createV2ServerSetup } from "./v2-server.js"
+
+/**
+ * Dual-target server entry.
+ *
+ * - OpenCode v1 resolves `exports["./server"]`, reads `mod.default`, and
+ *   invokes the `server` factory (excess keys are never validated).
+ * - OpenCode v2 imports the same module, validates `mod.default` as
+ *   `{ id, setup }`, and ignores the legacy `server` key - so one default
+ *   export satisfies both loaders.
+ */
+export default {
+  id: "subagent-explorer",
+  server: plugin,
+  setup: createV2ServerSetup(),
+}