Fix stale OpenCode plugin cache doctor check (#199)

Compare the cached @cortexkit/opencode-magic-context against its OWN npm latest version instead of the CLI's self-version, so doctor clears a stale plugin cache even when invoked via a stale cached CLI. Extract the duplicated plugin-cache path literals into a shared opencode-plugin-cache module, clear the versionless cache root as well as the @latest root, and preserve the cache when the npm latest check is unavailable (offline) rather than blindly clearing it.

Authored by @coleleavitt.

Author: coleleavitt

packages/cli/src/adapters/opencode.ts

@@ -3,6 +3,11 @@ import { dirname } from "node:path";
 import { parse as parseJsonc, stringify as stringifyJsonc } from "comment-json";
 import { writeFileAtomic } from "../lib/atomic-write";
 import { isOpenCodeInstalledOnSystem } from "../lib/opencode-install";
+import {
+    getOpenCodePluginPackageJsonPaths,
+    OPENCODE_PLUGIN_ENTRY_WITH_VERSION as PLUGIN_ENTRY,
+    OPENCODE_PLUGIN_NAME as PLUGIN_NAME,
+} from "../lib/opencode-plugin-cache";
 import {
     detectConfigPaths,
     dirSizeBytes,
@@ -16,9 +21,6 @@ import type {
     PluginEntryResult,
 } from "./types";
 
-const PLUGIN_NAME = "@cortexkit/opencode-magic-context";
-const PLUGIN_ENTRY = `${PLUGIN_NAME}@latest`;
-
 export class OpenCodeAdapter implements HarnessAdapter {
     readonly kind = "opencode" as const;
     readonly displayName = "OpenCode";
@@ -214,12 +216,7 @@ export class OpenCodeAdapter implements HarnessAdapter {
 
     getInstalledPluginVersion(): string | null {
         // Look in OpenCode's plugin cache for the installed package version.
-        const cacheDir = getOpenCodePluginCacheDir();
-        const candidates = [
-            `${cacheDir}/${PLUGIN_NAME}@latest/node_modules/${PLUGIN_NAME}/package.json`,
-            `${cacheDir}/${PLUGIN_NAME}/node_modules/${PLUGIN_NAME}/package.json`,
-        ];
-        for (const candidate of candidates) {
+        for (const candidate of getOpenCodePluginPackageJsonPaths()) {
             if (!existsSync(candidate)) continue;
             try {
                 const raw = readFileSync(candidate, "utf-8");

packages/cli/src/commands/doctor-opencode-cache.ts

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import {
+    getOpenCodePluginCacheRoots,
+    getOpenCodePluginPackageJsonPath,
+} from "../lib/opencode-plugin-cache";
+
+export interface PluginCacheResult {
+    action: "cleared" | "up_to_date" | "not_found" | "check_unavailable" | "error";
+    path: string;
+    paths?: string[];
+    cached?: string;
+    latest?: string;
+    error?: string;
+}
+
+function readCachedPluginVersion(pluginCacheDir: string): string | undefined {
+    try {
+        const installedPkgPath = getOpenCodePluginPackageJsonPath(pluginCacheDir);
+        if (!existsSync(installedPkgPath)) return undefined;
+        const pkg = JSON.parse(readFileSync(installedPkgPath, "utf-8")) as { version?: unknown };
+        return typeof pkg.version === "string" ? pkg.version : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+export async function clearPluginCache(
+    options: { force?: boolean; latestVersion?: string | null } = {},
+): Promise<PluginCacheResult> {
+    const pluginCacheRoots = getOpenCodePluginCacheRoots();
+    const existingRoots = pluginCacheRoots.filter((root) => existsSync(root));
+
+    if (existingRoots.length === 0) {
+        return { action: "not_found", path: pluginCacheRoots[0] ?? "" };
+    }
+
+    const latestVersion = options.latestVersion ?? undefined;
+    const cacheEntries = existingRoots.map((path) => ({
+        path,
+        cached: readCachedPluginVersion(path),
+    }));
+
+    if (options.force !== true && latestVersion === undefined) {
+        const firstEntry = cacheEntries[0];
+        return {
+            action: "check_unavailable",
+            path: firstEntry?.path ?? pluginCacheRoots[0] ?? "",
+            paths: cacheEntries.map((entry) => entry.path),
+            cached: firstEntry?.cached,
+        };
+    }
+
+    const clearTargets = cacheEntries.filter(
+        (entry) =>
+            options.force === true || entry.cached === undefined || entry.cached !== latestVersion,
+    );
+
+    if (clearTargets.length === 0) {
+        const firstEntry = cacheEntries[0];
+        return {
+            action: "up_to_date",
+            path: firstEntry?.path ?? pluginCacheRoots[0] ?? "",
+            paths: cacheEntries.map((entry) => entry.path),
+            cached: firstEntry?.cached,
+            latest: latestVersion,
+        };
+    }
+
+    try {
+        for (const entry of clearTargets) {
+            rmSync(entry.path, { recursive: true, force: true });
+        }
+        const firstTarget = clearTargets[0];
+        return {
+            action: "cleared",
+            path: firstTarget?.path ?? pluginCacheRoots[0] ?? "",
+            paths: clearTargets.map((entry) => entry.path),
+            cached: firstTarget?.cached,
+            latest: latestVersion,
+        };
+    } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            action: "error",
+            path: clearTargets[0]?.path ?? existingRoots[0] ?? "",
+            error: message,
+        };
+    }
+}

packages/cli/src/commands/doctor-opencode.test.ts

@@ -1,16 +1,21 @@
 import { afterEach, describe, expect, it } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import {
     initializeDatabase,
     runMigrations,
 } from "@magic-context/core/features/magic-context/storage";
 import { computeLegacyRustDirIdentity } from "@magic-context/core/features/magic-context/v22-deferred-backfill";
 import { Database } from "@magic-context/core/shared/sqlite";
 import { parse as parseJsonc, stringify as stringifyJsonc } from "comment-json";
+import {
+    OPENCODE_PLUGIN_ENTRY_WITH_VERSION,
+    OPENCODE_PLUGIN_NAME,
+} from "../lib/opencode-plugin-cache";
 import { runV22BackfillCommands } from "../lib/v22-backfill-commands";
 import { migrateLegacyAgentEnabledConfigForDoctor } from "./doctor-opencode";
+import { clearPluginCache } from "./doctor-opencode-cache";
 
 function migrate(input: Record<string, unknown>) {
     const logs: Array<{ level: "success" | "warn"; message: string }> = [];
@@ -71,6 +76,7 @@ describe("doctor OpenCode legacy agent enabled migration", () => {
 
 const tempDirs: string[] = [];
 const dbs: Database[] = [];
+let originalXdgCacheHome: string | undefined;
 
 function makeTempDir(prefix = "mc-v22-doctor-"): string {
     const dir = mkdtempSync(join(tmpdir(), prefix));
@@ -121,6 +127,12 @@ function makeHarness(database: Database, messages: string[]) {
 }
 
 afterEach(() => {
+    if (originalXdgCacheHome === undefined) {
+        delete process.env.XDG_CACHE_HOME;
+    } else {
+        process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    }
+    originalXdgCacheHome = undefined;
     for (const db of dbs.splice(0)) {
         db.close();
     }
@@ -129,6 +141,120 @@ afterEach(() => {
     }
 });
 
+function createCachedOpenCodePlugin(
+    root: string,
+    version: string,
+    entry = OPENCODE_PLUGIN_ENTRY_WITH_VERSION,
+): string {
+    const pluginCachePath = join(root, "opencode", "packages", entry);
+    const installedPackagePath = join(
+        pluginCachePath,
+        "node_modules",
+        "@cortexkit",
+        "opencode-magic-context",
+        "package.json",
+    );
+    mkdirSync(dirname(installedPackagePath), { recursive: true });
+    writeFileSync(installedPackagePath, `${JSON.stringify({ version })}\n`);
+    return pluginCachePath;
+}
+
+describe("doctor OpenCode plugin cache", () => {
+    it("clears stale @latest cache when cached plugin is older than npm latest", async () => {
+        const cacheRoot = makeTempDir("mc-opencode-cache-");
+        originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+        process.env.XDG_CACHE_HOME = cacheRoot;
+        const pluginCachePath = createCachedOpenCodePlugin(cacheRoot, "0.26.0");
+
+        const result = await clearPluginCache({ latestVersion: "0.29.1" });
+
+        expect(result).toMatchObject({
+            action: "cleared",
+            cached: "0.26.0",
+            latest: "0.29.1",
+            path: pluginCachePath,
+        });
+        expect(existsSync(pluginCachePath)).toBe(false);
+    });
+
+    it("keeps @latest cache when cached plugin matches npm latest", async () => {
+        const cacheRoot = makeTempDir("mc-opencode-cache-");
+        originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+        process.env.XDG_CACHE_HOME = cacheRoot;
+        const pluginCachePath = createCachedOpenCodePlugin(cacheRoot, "0.29.1");
+
+        const result = await clearPluginCache({ latestVersion: "0.29.1" });
+
+        expect(result).toMatchObject({
+            action: "up_to_date",
+            cached: "0.29.1",
+            latest: "0.29.1",
+            path: pluginCachePath,
+        });
+        expect(existsSync(pluginCachePath)).toBe(true);
+    });
+
+    it("clears stale versionless cache even when @latest cache is current", async () => {
+        const cacheRoot = makeTempDir("mc-opencode-cache-");
+        originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+        process.env.XDG_CACHE_HOME = cacheRoot;
+        const latestCachePath = createCachedOpenCodePlugin(cacheRoot, "0.29.1");
+        const versionlessCachePath = createCachedOpenCodePlugin(
+            cacheRoot,
+            "0.26.0",
+            OPENCODE_PLUGIN_NAME,
+        );
+
+        const result = await clearPluginCache({ latestVersion: "0.29.1" });
+
+        expect(result).toMatchObject({
+            action: "cleared",
+            cached: "0.26.0",
+            latest: "0.29.1",
+            path: versionlessCachePath,
+            paths: [versionlessCachePath],
+        });
+        expect(existsSync(latestCachePath)).toBe(true);
+        expect(existsSync(versionlessCachePath)).toBe(false);
+    });
+
+    it("preserves existing cache when plugin npm latest is unavailable", async () => {
+        const cacheRoot = makeTempDir("mc-opencode-cache-");
+        originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+        process.env.XDG_CACHE_HOME = cacheRoot;
+        const pluginCachePath = createCachedOpenCodePlugin(cacheRoot, "0.29.1");
+
+        const result = await clearPluginCache({ latestVersion: null });
+
+        expect(result).toMatchObject({
+            action: "check_unavailable",
+            cached: "0.29.1",
+            path: pluginCachePath,
+            paths: [pluginCachePath],
+        });
+        expect(result.latest).toBeUndefined();
+        expect(existsSync(pluginCachePath)).toBe(true);
+    });
+
+    it("force-clears existing cache even when plugin npm latest is unavailable", async () => {
+        const cacheRoot = makeTempDir("mc-opencode-cache-");
+        originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+        process.env.XDG_CACHE_HOME = cacheRoot;
+        const pluginCachePath = createCachedOpenCodePlugin(cacheRoot, "0.29.1");
+
+        const result = await clearPluginCache({ force: true, latestVersion: null });
+
+        expect(result).toMatchObject({
+            action: "cleared",
+            cached: "0.29.1",
+            path: pluginCachePath,
+            paths: [pluginCachePath],
+        });
+        expect(result.latest).toBeUndefined();
+        expect(existsSync(pluginCachePath)).toBe(false);
+    });
+});
+
 describe("doctor v22 backfill commands", () => {
     it("--check-v22-backfill reports status", async () => {
         const database = makeDb();