@otto-assistant/otto 0.1.0

package/src/config.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest"
+import {
+  mergePlugins,
+  readOttoConfig,
+  writeOttoConfig,
+  OTTO_DEFAULTS,
+  buildSubagentThreadPolicy,
+  mergeAgentPrompts,
+  ensureSubagentThreadSkill,
+  readOpenCodeConfigState,
+  type OpenCodeConfig,
+  type OttoConfig,
+} from "./config.js"
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+
+describe("config", () => {
+  it("adds plugin to empty config", () => {
+    const config: OpenCodeConfig = {}
+    const result = mergePlugins(config, "opencode-agent-memory")
+    expect(result.plugin).toEqual(["opencode-agent-memory"])
+  })
+
+  it("appends plugin to existing array", () => {
+    const config: OpenCodeConfig = { plugin: ["existing-plugin"] }
+    const result = mergePlugins(config, "opencode-agent-memory")
+    expect(result.plugin).toEqual(["existing-plugin", "opencode-agent-memory"])
+  })
+
+  it("does not duplicate existing plugin", () => {
+    const config: OpenCodeConfig = { plugin: ["opencode-agent-memory"] }
+    const result = mergePlugins(config, "opencode-agent-memory")
+    expect(result.plugin).toEqual(["opencode-agent-memory"])
+  })
+
+  it("preserves other config fields", () => {
+    const config: OpenCodeConfig = {
+      model: "gpt-4",
+      plugin: ["existing"],
+      provider: { cursor: { name: "Cursor" } },
+    }
+    const result = mergePlugins(config, "opencode-agent-memory")
+    expect(result.model).toBe("gpt-4")
+    expect(result.provider).toEqual({ cursor: { name: "Cursor" } })
+    expect(result.plugin).toEqual(["existing", "opencode-agent-memory"])
+  })
+
+  it("readOttoConfig returns defaults when otto.json missing", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      const result = readOttoConfig(tmpDir)
+      expect(result.subagentThreads).toEqual({
+        enabled: true,
+        askBeforeDelete: true,
+        autoDeleteOnComplete: false,
+      })
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it("writeOttoConfig + readOttoConfig round-trip", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      const config: OttoConfig = {
+        subagentThreads: {
+          enabled: false,
+          askBeforeDelete: false,
+          autoDeleteOnComplete: true,
+        },
+      }
+      const written = writeOttoConfig(config, tmpDir)
+      expect(written).toBe(true)
+
+      const read = readOttoConfig(tmpDir)
+      expect(read.subagentThreads).toEqual({
+        enabled: false,
+        askBeforeDelete: false,
+        autoDeleteOnComplete: true,
+      })
+
+      // Idempotent
+      const writtenAgain = writeOttoConfig(config, tmpDir)
+      expect(writtenAgain).toBe(false)
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it("readOttoConfig fills defaults for partial config", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      fs.mkdirSync(tmpDir, { recursive: true })
+      fs.writeFileSync(
+        path.join(tmpDir, "otto.json"),
+        JSON.stringify({ subagentThreads: { enabled: false } }, null, 2) + "\n",
+        "utf-8",
+      )
+      const result = readOttoConfig(tmpDir)
+      expect(result.subagentThreads.enabled).toBe(false)
+      expect(result.subagentThreads.askBeforeDelete).toBe(true) // default
+      expect(result.subagentThreads.autoDeleteOnComplete).toBe(false) // default
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it("policy includes kimaki send commands when enabled", () => {
+    const ottoConfig: OttoConfig = {
+      subagentThreads: { enabled: true, askBeforeDelete: true, autoDeleteOnComplete: false },
+    }
+    const policy = buildSubagentThreadPolicy(ottoConfig)
+
+    expect(policy).toContain("Otto subagent policy (must follow):")
+    expect(policy).toContain("subagent_threads_enabled: true")
+    expect(policy).toContain("kimaki send")
+    expect(policy).toContain("--channel")
+    expect(policy).toContain("--wait")
+    expect(policy).toContain("ask the user")
+  })
+
+  it("policy is short when threads disabled", () => {
+    const ottoConfig: OttoConfig = {
+      subagentThreads: { enabled: false, askBeforeDelete: true, autoDeleteOnComplete: false },
+    }
+    const policy = buildSubagentThreadPolicy(ottoConfig)
+
+    expect(policy).toContain("subagent_threads_enabled: false")
+    expect(policy).toContain("without creating Discord threads")
+    expect(policy).not.toContain("kimaki send")
+  })
+
+  it("policy includes auto-archive when autoDeleteOnComplete is true", () => {
+    const ottoConfig: OttoConfig = {
+      subagentThreads: { enabled: true, askBeforeDelete: false, autoDeleteOnComplete: true },
+    }
+    const policy = buildSubagentThreadPolicy(ottoConfig)
+
+    expect(policy).toContain("auto_delete_on_complete: true")
+    expect(policy).toContain("kimaki session archive")
+    expect(policy).not.toContain("ask the user")
+  })
+
+  it("injects policy into existing agent prompt", () => {
+    const config: OpenCodeConfig = {
+      agent: { build: { prompt: "existing rule" } },
+    }
+
+    const ottoConfig: OttoConfig = OTTO_DEFAULTS
+    const policy = buildSubagentThreadPolicy(ottoConfig)
+    const result = mergeAgentPrompts(config, policy)
+    const prompt = (result.agent as Record<string, { prompt?: string }>).build.prompt
+
+    expect(prompt).toContain("existing rule")
+    expect(prompt).toContain("Otto subagent policy (must follow):")
+    expect(prompt).toContain("subagent_threads_enabled: true")
+  })
+
+  it("does not duplicate policy when already present", () => {
+    const ottoConfig: OttoConfig = OTTO_DEFAULTS
+    const policy = buildSubagentThreadPolicy(ottoConfig)
+    const config: OpenCodeConfig = {
+      agent: { build: { prompt: policy } },
+    }
+
+    const result = mergeAgentPrompts(config, policy)
+    const prompt = (result.agent as Record<string, { prompt?: string }>).build.prompt ?? ""
+    expect(prompt.match(/Otto subagent policy \(must follow\):/g)?.length).toBe(1)
+  })
+
+  it("creates build agent with policy when agent section is empty", () => {
+    const ottoConfig: OttoConfig = OTTO_DEFAULTS
+    const policy = buildSubagentThreadPolicy(ottoConfig)
+    const result = mergeAgentPrompts({}, policy)
+    const agents = result.agent as Record<string, { prompt?: string }>
+
+    expect(agents.build?.prompt).toContain("Otto subagent policy (must follow):")
+  })
+
+  it("readOpenCodeConfigState returns missing when file absent", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      const result = readOpenCodeConfigState(tmpDir)
+      expect(result.status).toBe("missing")
+      expect(result.config).toEqual({})
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it("readOpenCodeConfigState returns ok for valid JSON", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      fs.mkdirSync(tmpDir, { recursive: true })
+      fs.writeFileSync(path.join(tmpDir, "opencode.json"), "{\"model\":\"x\"}\n", "utf-8")
+      const result = readOpenCodeConfigState(tmpDir)
+      expect(result.status).toBe("ok")
+      expect(result.config).toEqual({ model: "x" })
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it("readOpenCodeConfigState returns invalid for broken JSON", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      fs.mkdirSync(tmpDir, { recursive: true })
+      fs.writeFileSync(path.join(tmpDir, "opencode.json"), "{not json", "utf-8")
+      const result = readOpenCodeConfigState(tmpDir)
+      expect(result.status).toBe("invalid")
+      expect(result.config).toEqual({})
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it("ensureSubagentThreadSkill creates skill file", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "otto-test-"))
+    try {
+      const created = ensureSubagentThreadSkill(tmpDir)
+      expect(created).toBe(true)
+
+      const skillPath = path.join(tmpDir, "skills", "otto-subagent-threads", "SKILL.md")
+      const content = fs.readFileSync(skillPath, "utf-8")
+      expect(content).toContain("name: otto-subagent-threads")
+      expect(content).toContain("kimaki send")
+      expect(content).toContain("kimaki session archive")
+
+      // Idempotent — second call returns false
+      const second = ensureSubagentThreadSkill(tmpDir)
+      expect(second).toBe(false)
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/config.ts

@@ -0,0 +1,362 @@
+import fs from "node:fs"
+import path from "node:path"
+import { OPENCODE_CONFIG_DIR } from "./manifest.js"
+
+export interface OttoSubagentThreads {
+  enabled?: boolean
+  askBeforeDelete?: boolean
+  autoDeleteOnComplete?: boolean
+}
+
+export interface OttoConfig {
+  subagentThreads: {
+    enabled: boolean
+    askBeforeDelete: boolean
+    autoDeleteOnComplete: boolean
+  }
+}
+
+/** Defaults used when otto.json is missing or partial. */
+export const OTTO_DEFAULTS: OttoConfig = {
+  subagentThreads: {
+    enabled: true,
+    askBeforeDelete: true,
+    autoDeleteOnComplete: false,
+  },
+}
+
+export interface OpenCodeConfig {
+  $schema?: string
+  model?: string
+  plugin?: string[]
+  provider?: Record<string, unknown>
+  agent?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export function mergePlugins(config: OpenCodeConfig, pluginToAdd: string): OpenCodeConfig {
+  const plugins = config.plugin ?? []
+  if (plugins.includes(pluginToAdd)) {
+    return config
+  }
+  return { ...config, plugin: [...plugins, pluginToAdd] }
+}
+
+// ---------------------------------------------------------------------------
+// Otto's own config (stored in ~/.config/opencode/otto.json, NOT opencode.json)
+// opencode rejects unknown keys in its config — Otto must not pollute it.
+// ---------------------------------------------------------------------------
+
+export type OttoConfigReadStatus = "missing" | "ok" | "invalid"
+
+export function readOttoConfig(dir?: string): OttoConfig {
+  const configDir = dir ?? OPENCODE_CONFIG_DIR()
+  const configPath = path.join(configDir, "otto.json")
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8")
+    const parsed = JSON.parse(raw) as Partial<OttoConfig>
+    return {
+      subagentThreads: {
+        enabled: parsed.subagentThreads?.enabled ?? OTTO_DEFAULTS.subagentThreads.enabled,
+        askBeforeDelete: parsed.subagentThreads?.askBeforeDelete ?? OTTO_DEFAULTS.subagentThreads.askBeforeDelete,
+        autoDeleteOnComplete: parsed.subagentThreads?.autoDeleteOnComplete ?? OTTO_DEFAULTS.subagentThreads.autoDeleteOnComplete,
+      },
+    }
+  } catch {
+    return { ...OTTO_DEFAULTS }
+  }
+}
+
+export function writeOttoConfig(config: OttoConfig, dir?: string): boolean {
+  const configDir = dir ?? OPENCODE_CONFIG_DIR()
+  const configPath = path.join(configDir, "otto.json")
+
+  let existing: string | null = null
+  try {
+    existing = fs.readFileSync(configPath, "utf-8")
+  } catch {
+    // file doesn't exist
+  }
+
+  const newContent = JSON.stringify(config, null, 2) + "\n"
+  if (existing === newContent) {
+    return false
+  }
+
+  fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, newContent, "utf-8")
+  return true
+}
+
+export function buildSubagentThreadPolicy(ottoConfig: OttoConfig): string {
+  const policy = ottoConfig.subagentThreads
+  const enabled = policy.enabled
+  const askBeforeDelete = policy.askBeforeDelete
+  const autoDeleteOnComplete = policy.autoDeleteOnComplete
+
+  const lines = [
+    "Otto subagent policy (must follow):",
+    `- subagent_threads_enabled: ${enabled}`,
+    `- subagent_threads_ask_before_delete: ${askBeforeDelete}`,
+    `- subagent_threads_auto_delete_on_complete: ${autoDeleteOnComplete}`,
+  ]
+
+  if (!enabled) {
+    lines.push(
+      "- subagent_threads_enabled is false — you may spawn subagents normally (Task tool or otherwise) without creating Discord threads.",
+    )
+    return lines.join("\n")
+  }
+
+  lines.push(
+    "",
+    "## Spawning subagents with Discord threads",
+    "",
+    "When you need to spawn a subagent (parallel task, background investigation, etc.), do NOT use the Task tool directly.",
+    "Instead, create a visible Discord thread using `kimaki send` via Bash:",
+    "",
+    "```bash",
+    'kimaki send --channel <channel_id> --prompt "detailed task description" --user "<username>"',
+    "```",
+    "",
+    "The channel_id and username are in your system prompt (\"Your current Discord channel ID\" / \"Discord\" user field).",
+    "",
+    "For sequential tasks where you need the result before continuing, use --wait (set Bash timeout to 1_500_000+):",
+    "```bash",
+    'kimaki send --channel <channel_id> --prompt "task" --user "<username>" --wait',
+    "```",
+    "",
+    "## After subagent completes",
+    "",
+  )
+
+  if (autoDeleteOnComplete) {
+    lines.push(
+      "- subagent_threads_auto_delete_on_complete is true → automatically archive the thread after the subagent finishes:",
+      "  ```bash",
+      '  kimaki session archive --session <session_id>',
+      "  ```",
+    )
+  } else if (askBeforeDelete) {
+    lines.push(
+      "- subagent_threads_ask_before_delete is true → after the subagent finishes, ask the user:",
+      '  "Subagent thread created. Should I archive it or keep it open?"',
+      "  If user says archive → `kimaki session archive --session <session_id>`",
+    )
+  } else {
+    lines.push(
+      "- Keep the subagent thread open after completion (no auto-archive, no prompt).",
+    )
+  }
+
+  lines.push(
+    "",
+    "## Required: load skills before subagent execution",
+    "",
+    "Before dispatching any subagent, load the skill: `otto-subagent-threads`.",
+    "This ensures the subagent follows the same thread creation rules if it spawns further subagents.",
+  )
+
+  return lines.join("\n")
+}
+
+export function mergeAgentPrompts(config: OpenCodeConfig, policyText: string): OpenCodeConfig {
+  const marker = "Otto subagent policy (must follow):"
+  const agent = (config.agent ?? {}) as Record<string, unknown>
+  const entries = Object.entries(agent)
+
+  if (entries.length === 0) {
+    return {
+      ...config,
+      agent: {
+        build: { prompt: policyText },
+      },
+    }
+  }
+
+  const nextAgent: Record<string, unknown> = {}
+  for (const [name, value] of entries) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const typed = value as Record<string, unknown>
+      const existingPrompt = typeof typed.prompt === "string" ? typed.prompt : ""
+      const hasPolicy = existingPrompt.includes(marker)
+      nextAgent[name] = {
+        ...typed,
+        prompt: hasPolicy
+          ? existingPrompt
+          : (existingPrompt.length > 0 ? `${existingPrompt}\n\n${policyText}` : policyText),
+      }
+    } else {
+      nextAgent[name] = value
+    }
+  }
+
+  return { ...config, agent: nextAgent }
+}
+
+export type OpenCodeConfigReadStatus = "missing" | "ok" | "invalid"
+
+/** Distinguishes a missing file from invalid JSON (both previously surfaced as `{}`). */
+export function readOpenCodeConfigState(dir?: string): {
+  config: OpenCodeConfig
+  status: OpenCodeConfigReadStatus
+} {
+  const configDir = dir ?? OPENCODE_CONFIG_DIR()
+  const configPath = path.join(configDir, "opencode.json")
+  if (!fs.existsSync(configPath)) {
+    return { config: {}, status: "missing" }
+  }
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8")
+    return { config: JSON.parse(raw) as OpenCodeConfig, status: "ok" }
+  } catch {
+    return { config: {}, status: "invalid" }
+  }
+}
+
+export function readOpenCodeConfig(dir?: string): OpenCodeConfig {
+  return readOpenCodeConfigState(dir).config
+}
+
+export function writeOpenCodeConfig(config: OpenCodeConfig, dir?: string): boolean {
+  const configDir = dir ?? OPENCODE_CONFIG_DIR()
+  const configPath = path.join(configDir, "opencode.json")
+
+  let existing: string | null = null
+  try {
+    existing = fs.readFileSync(configPath, "utf-8")
+  } catch {
+    // file doesn't exist
+  }
+
+  const newContent = JSON.stringify(config, null, 2) + "\n"
+  if (existing === newContent) {
+    return false
+  }
+
+  fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, newContent, "utf-8")
+  return true
+}
+
+export function ensureAgentMemoryConfig(dir?: string): boolean {
+  const configDir = dir ?? OPENCODE_CONFIG_DIR()
+  const configPath = path.join(configDir, "agent-memory.json")
+
+  try {
+    fs.readFileSync(configPath, "utf-8")
+    return false
+  } catch {
+    // create with defaults
+  }
+
+  const defaults = {
+    journal: {
+      enabled: true,
+      tags: [
+        { name: "infra", description: "Infrastructure changes, host/service topology, runtime environment" },
+        { name: "debugging", description: "Bug investigations, root-cause analysis, and troubleshooting" },
+        { name: "decision", description: "Architecture and implementation decisions with rationale" },
+        { name: "incident", description: "Service failures, outages, and recovery actions" },
+        { name: "automation", description: "Agent workflows, scripts, and repeatable operational routines" },
+      ],
+    },
+  }
+
+  fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(configPath, JSON.stringify(defaults, null, 2) + "\n", "utf-8")
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Skill file: otto-subagent-threads
+// ---------------------------------------------------------------------------
+
+const SKILL_NAME = "otto-subagent-threads"
+
+const SKILL_MD = `---
+name: otto-subagent-threads
+description: Enforce visible Discord threads for every subagent spawn. Use before dispatching any subagent via kimaki send.
+---
+
+# Otto Subagent Threads
+
+## When to Use
+
+Use this skill EVERY TIME you are about to spawn a subagent (parallel task, background investigation, code review, etc.).
+
+## Rules
+
+### 1. NEVER use Task tool directly for subagents
+
+The Task tool spawns a subagent in "shadow mode" — invisible to the user in Discord.
+Instead, create a visible Discord thread.
+
+### 2. Create a Discord thread with kimaki send
+
+\`\`\`bash
+kimaki send --channel <channel_id> --prompt "detailed task description" --user "<username>"
+\`\`\`
+
+Get channel_id and username from your system prompt:
+- "Your current Discord channel ID is: ..."
+- Discord user info section
+
+### 3. Wait for result if needed
+
+If you need the subagent's output before continuing, add \`--wait\` and set Bash timeout to 1_500_000+:
+
+\`\`\`bash
+kimaki send --channel <channel_id> --prompt "task" --user "<username>" --wait
+\`\`\`
+
+### 4. After subagent completes
+
+Check the otto.subagentThreads config:
+- **autoDeleteOnComplete = true** → archive the thread:
+  \`\`\`bash
+  kimaki session archive --session <session_id>
+  \`\`\`
+- **askBeforeDelete = true** → ask the user:
+  "Subagent finished. Should I archive the thread or keep it open?"
+- **both false** → keep the thread open.
+
+### 5. Nested subagents
+
+If your subagent itself needs to spawn further subagents, include these same rules in its prompt so it also creates visible threads.
+
+## Quick Reference
+
+| Scenario | Command |
+|----------|---------|
+| Parallel task (fire & forget) | \`kimaki send -c <ch> -p "task" -u <user>\` |
+| Sequential task (need result) | \`kimaki send -c <ch> -p "task" -u <user> --wait\` |
+| Archive thread | \`kimaki session archive -s <session_id>\` |
+| List sessions | \`kimaki session list\` |
+| Read session output | \`kimaki session read <session_id> > ./tmp/session.md 2>/dev/null\` |
+
+## Anti-patterns
+
+- **DO NOT** use the Task tool to spawn subagents (creates invisible shadow sessions).
+- **DO NOT** create worktrees (\`--worktree\`) unless the user explicitly asks.
+- **DO NOT** forget to include your channel_id in the kimaki send command.
+`
+
+export function ensureSubagentThreadSkill(dir?: string): boolean {
+  const configDir = dir ?? OPENCODE_CONFIG_DIR()
+  const skillDir = path.join(configDir, "skills", SKILL_NAME)
+  const skillPath = path.join(skillDir, "SKILL.md")
+
+  try {
+    const existing = fs.readFileSync(skillPath, "utf-8")
+    if (existing === SKILL_MD) {
+      return false // already up to date
+    }
+  } catch {
+    // file doesn't exist — will create
+  }
+
+  fs.mkdirSync(skillDir, { recursive: true })
+  fs.writeFileSync(skillPath, SKILL_MD, "utf-8")
+  return true
+}

package/src/detect.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest"
+import { getInstalledVersion, detectPackage, type InstalledPackage } from "./detect.js"
+
+describe("detect", () => {
+  it("returns null for non-existent package", () => {
+    const result = getInstalledVersion("nonexistent-package-xyz-123")
+    expect(result).toBeNull()
+  })
+
+  // These tests require kimaki to be globally installed (skipped on CI)
+  const describeIfInstalled = process.env.CI ? describe.skip : describe
+
+  describeIfInstalled("with kimaki installed", () => {
+    it("detects an existing global package", () => {
+      const result = getInstalledVersion("kimaki")
+      expect(result).not.toBeNull()
+      expect(result).toMatch(/^\d+\.\d+\.\d+/)
+    })
+
+    it("detectPackage returns full info", async () => {
+      const result = await detectPackage("kimaki")
+      expect(result).toEqual({
+        name: "kimaki",
+        installed: expect.any(String),
+      })
+    })
+  })
+})

package/src/detect.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from "node:child_process"
+
+export interface InstalledPackage {
+  name: string
+  installed: string | null
+}
+
+let globalVersionCache: Map<string, string> | null = null
+
+function loadGlobalPackageVersions(): Map<string, string> {
+  if (globalVersionCache) {
+    return globalVersionCache
+  }
+  const map = new Map<string, string>()
+  try {
+    const output = execFileSync(
+      process.platform === "win32" ? "npm.cmd" : "npm",
+      ["list", "-g", "--json", "--depth=0"],
+      {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    )
+    const parsed = JSON.parse(output) as { dependencies?: Record<string, { version?: string }> }
+    const deps = parsed.dependencies ?? {}
+    for (const [name, info] of Object.entries(deps)) {
+      if (info?.version) {
+        map.set(name, info.version)
+      }
+    }
+  } catch {
+    // leave map empty — callers treat missing entries as not installed
+  }
+  globalVersionCache = map
+  return map
+}
+
+/** For tests: reset cached `npm list -g` result between cases. */
+export function clearGlobalNpmListCache(): void {
+  globalVersionCache = null
+}
+
+export function getInstalledVersion(packageName: string): string | null {
+  return loadGlobalPackageVersions().get(packageName) ?? null
+}
+
+export async function detectPackage(name: string): Promise<InstalledPackage> {
+  return {
+    name,
+    installed: getInstalledVersion(name),
+  }
+}