@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/normalize-sdk-response.ts

@@ -0,0 +1,40 @@
+export interface NormalizeSDKResponseOptions {
+    preferResponseOnMissingData?: boolean;
+}
+
+// Audit note: `as TData` casts are intentional at this boundary. The OpenCode plugin SDK types
+// external responses as `unknown`. Adding Zod validation here would require schema definitions
+// for every SDK response shape, which changes with each OpenCode release. The fallback parameter
+// provides safe degradation when shapes mismatch.
+export function normalizeSDKResponse<TData>(
+    response: unknown,
+    fallback: TData,
+    options?: NormalizeSDKResponseOptions,
+): TData {
+    if (response === null || response === undefined) {
+        return fallback;
+    }
+
+    if (Array.isArray(response)) {
+        return response as TData;
+    }
+
+    if (typeof response === "object" && "data" in response) {
+        const data = (response as { data?: unknown }).data;
+        if (data !== null && data !== undefined) {
+            return data as TData;
+        }
+
+        if (options?.preferResponseOnMissingData === true) {
+            return response as TData;
+        }
+
+        return fallback;
+    }
+
+    if (options?.preferResponseOnMissingData === true) {
+        return response as TData;
+    }
+
+    return fallback;
+}

package/src/shared/opencode-config-dir-types.ts

@@ -0,0 +1,15 @@
+export type OpenCodeBinaryType = "opencode" | "opencode-desktop";
+
+export type OpenCodeConfigDirOptions = {
+    binary: OpenCodeBinaryType;
+    version?: string | null;
+    checkExisting?: boolean;
+};
+
+export type OpenCodeConfigPaths = {
+    configDir: string;
+    configJson: string;
+    configJsonc: string;
+    packageJson: string;
+    omoConfig: string;
+};

package/src/shared/opencode-config-dir.ts

@@ -0,0 +1,111 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+import type { OpenCodeConfigDirOptions, OpenCodeConfigPaths } from "./opencode-config-dir-types";
+
+export type {
+    OpenCodeBinaryType,
+    OpenCodeConfigDirOptions,
+    OpenCodeConfigPaths,
+} from "./opencode-config-dir-types";
+
+/**
+ * The user's home directory, preferring `$HOME` over the cached value.
+ *
+ * `os.homedir()` reads `$HOME` once when the process starts and never again,
+ * so a test (or a wrapper) that sets `HOME` afterwards would otherwise be
+ * silently ignored and we would read the developer's real config. `$HOME` is
+ * normally unset on Windows, where the cached value is the right answer.
+ */
+function resolveHomeDir(): string {
+    return process.env.HOME?.trim() || homedir();
+}
+
+/**
+ * OpenCode's GLOBAL config directory: `$XDG_CONFIG_HOME/opencode`, falling
+ * back to `~/.config/opencode` (on every platform, Windows included — OpenCode
+ * does not use %APPDATA%).
+ *
+ * This helper names the loader's XDG layer, not every OpenCode surface called
+ * "config". In 1.18.30, `Global.Path.config` is the pure-XDG path
+ * (`packages/core/src/global.ts:13`) and the loader merges it once at
+ * `packages/opencode/src/config/config.ts:412-413`. Its later directories loop
+ * accepts only `.opencode` paths or the exact `OPENCODE_CONFIG_DIR` value
+ * (`config.ts:437-441`), so the XDG layer is skipped there and the env path is
+ * merged last. The detector mirrors that loader order via
+ * {@link getOpenCodeConfigDirs}.
+ *
+ * Service consumers see a different value: `Global.make()` injects
+ * `Flag.OPENCODE_CONFIG_DIR ?? Path.config` as `config`
+ * (`packages/core/src/global.ts:64`), so setting the env var replaces the
+ * service's value even though the loader still merges the XDG layer.
+ */
+export function getOpenCodeGlobalConfigDir(): string {
+    if (process.platform === "win32") {
+        return join(resolveHomeDir(), ".config", "opencode");
+    }
+
+    return join(process.env.XDG_CONFIG_HOME || join(resolveHomeDir(), ".config"), "opencode");
+}
+
+function getEnvConfigDir(): string | undefined {
+    const envConfigDir = process.env.OPENCODE_CONFIG_DIR?.trim();
+    return envConfigDir ? resolve(envConfigDir) : undefined;
+}
+
+function getCliConfigDir(): string {
+    return getEnvConfigDir() ?? getOpenCodeGlobalConfigDir();
+}
+
+/**
+ * The single directory Magic Context WRITES its OpenCode-side config into.
+ *
+ * `OPENCODE_CONFIG_DIR` wins here on purpose: among the directories OpenCode
+ * reads it has the highest precedence, so a setting written there is the one
+ * that takes effect. Do NOT use this to decide what OpenCode RESOLVED — for
+ * that you must read every directory in {@link getOpenCodeConfigDirs}, because
+ * a value the user set in the global directory is still live when
+ * `OPENCODE_CONFIG_DIR` points somewhere that does not override it.
+ */
+export function getOpenCodeConfigDir(_options: OpenCodeConfigDirOptions): string {
+    return getCliConfigDir();
+}
+
+export function getOpenCodeConfigPaths(options: OpenCodeConfigDirOptions): OpenCodeConfigPaths {
+    const configDir = getOpenCodeConfigDir(options);
+    return {
+        configDir,
+        configJson: join(configDir, "opencode.json"),
+        configJsonc: join(configDir, "opencode.jsonc"),
+        packageJson: join(configDir, "package.json"),
+        omoConfig: join(configDir, "magic-context.jsonc"),
+    };
+}
+
+/**
+ * Every user-tier directory OpenCode reads config from, ordered from LOWEST to
+ * HIGHEST precedence — later entries override earlier ones, which is the order
+ * OpenCode merges them in.
+ *
+ * Verified against the opencode 1.18.30 binary (`ConfigPaths.directories` plus
+ * the global loader in `Config.loadInstanceState`) and confirmed on a live host
+ * with `opencode debug config`:
+ *
+ *   1. `$XDG_CONFIG_HOME/opencode` — always read, whatever the environment says
+ *   2. `~/.opencode`               — always scanned, even outside a project
+ *   3. `$OPENCODE_CONFIG_DIR`      — appended last, so it wins ties
+ *
+ * The important part is that entry 3 is an ADDITION, not a replacement. A
+ * launcher that exports `OPENCODE_CONFIG_DIR` to a directory holding only
+ * plugin scaffolding does not stop OpenCode from reading the user's real
+ * config in entry 1 — so neither may we.
+ *
+ * Project-level directories are deliberately not included: they depend on the
+ * working directory and are resolved by the caller that knows it.
+ */
+export function getOpenCodeConfigDirs(): string[] {
+    const dirs = [getOpenCodeGlobalConfigDir(), join(resolveHomeDir(), ".opencode")];
+    const envDir = getEnvConfigDir();
+    if (envDir) dirs.push(envDir);
+    return [...new Set(dirs)];
+}

package/src/shared/opencode-db-path.test.ts

@@ -0,0 +1,389 @@
+/// <reference types="bun-types" />
+
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    assertOpenCodeStoreGeneration,
+    detectOpenCodeStoreGeneration,
+    formatOpenCodeDbDoctorLine,
+    formatOpenCodeDbMissingBanner,
+    formatOpenCodeDbMissingStatusLine,
+    hasV1MessageTables,
+    openCodeDbPathExists,
+    resetOpenCodeDbPathStateForTesting,
+    resolveOpenCodeDbPath,
+    sourceOpenCodeDatabaseFilename,
+} from "./opencode-db-path";
+import { Database } from "./sqlite";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+const ORIGINAL_ENV = {
+    XDG_DATA_HOME: process.env.XDG_DATA_HOME,
+    OPENCODE_DB: process.env.OPENCODE_DB,
+    OPENCODE_DISABLE_CHANNEL_DB: process.env.OPENCODE_DISABLE_CHANNEL_DB,
+    OPENCODE_CHANNEL: process.env.OPENCODE_CHANNEL,
+};
+const tempDirs: string[] = [];
+
+function restore(name: keyof typeof ORIGINAL_ENV): void {
+    const value = ORIGINAL_ENV[name];
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+}
+
+afterEach(() => {
+    restore("XDG_DATA_HOME");
+    restore("OPENCODE_DB");
+    restore("OPENCODE_DISABLE_CHANNEL_DB");
+    restore("OPENCODE_CHANNEL");
+    resetOpenCodeDbPathStateForTesting();
+    for (const directory of tempDirs.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+function useDataHome(): { dataHome: string; openCodeDir: string } {
+    const dataHome = createTestTempDirFromPath(join(tmpdir(), "opencode-db-path-"));
+    const openCodeDir = join(dataHome, "opencode");
+    mkdirSync(openCodeDir, { recursive: true });
+    tempDirs.push(dataHome);
+    process.env.XDG_DATA_HOME = dataHome;
+    delete process.env.OPENCODE_DB;
+    delete process.env.OPENCODE_DISABLE_CHANNEL_DB;
+    delete process.env.OPENCODE_CHANNEL;
+    resetOpenCodeDbPathStateForTesting();
+    return { dataHome, openCodeDir };
+}
+
+function createCandidate(openCodeDir: string, name: string, mtimeMs: number): string {
+    const path = join(openCodeDir, name);
+    writeFileSync(path, "sqlite fixture");
+    const time = new Date(mtimeMs);
+    utimesSync(path, time, time);
+    return path;
+}
+
+describe("resolveOpenCodeDbPath", () => {
+    it("honors absolute and relative OPENCODE_DB overrides before every other source", () => {
+        const { openCodeDir } = useDataHome();
+        const absolute = join(openCodeDir, "elsewhere.db");
+        process.env.OPENCODE_DB = absolute;
+        process.env.OPENCODE_DISABLE_CHANNEL_DB = "true";
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: absolute,
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+
+        process.env.OPENCODE_DB = "relative.db";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "relative.db"),
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+    });
+
+    it("treats OPENCODE_DB=:memory: as an explicit but absent store", () => {
+        useDataHome();
+        process.env.OPENCODE_DB = ":memory:";
+        const resolution = resolveOpenCodeDbPath();
+        expect(resolution).toEqual({ path: ":memory:", source: "OPENCODE_DB", channel: null });
+        expect(openCodeDbPathExists(resolution)).toBe(false);
+    });
+
+    it("uses the default DB when channel databases are disabled", () => {
+        const { openCodeDir } = useDataHome();
+        process.env.OPENCODE_DISABLE_CHANNEL_DB = "1";
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "default",
+            channel: null,
+        });
+    });
+
+    it("honors an OPENCODE_CHANNEL visible to the plugin", () => {
+        const { openCodeDir } = useDataHome();
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode-dev.db"),
+            source: "channel",
+            channel: "dev",
+        });
+    });
+
+    for (const selectedName of [
+        "opencode.db",
+        "opencode-local.db",
+        "opencode-dev.db",
+        "opencode-nightly.db",
+    ]) {
+        it(`discovers ${selectedName} when it is the newest existing candidate`, () => {
+            const { openCodeDir } = useDataHome();
+            const names = [
+                "opencode.db",
+                "opencode-local.db",
+                "opencode-dev.db",
+                "opencode-nightly.db",
+            ];
+            for (const [index, name] of names.entries()) {
+                createCandidate(openCodeDir, name, name === selectedName ? 10_000 : 1_000 + index);
+            }
+
+            expect(resolveOpenCodeDbPath()).toEqual({
+                path: join(openCodeDir, selectedName),
+                source: "discovered",
+                channel:
+                    selectedName === "opencode.db"
+                        ? null
+                        : selectedName.slice("opencode-".length, -".db".length),
+            });
+        });
+    }
+
+    it("uses candidate order as the deterministic tie-breaker for equal mtimes", () => {
+        const { openCodeDir } = useDataHome();
+        for (const name of ["opencode-local.db", "opencode-dev.db", "opencode.db"]) {
+            createCandidate(openCodeDir, name, 5_000);
+        }
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "discovered",
+            channel: null,
+        });
+    });
+
+    it("returns the default path by value when no candidate exists", () => {
+        const { openCodeDir } = useDataHome();
+        const resolution = resolveOpenCodeDbPath();
+        expect(resolution).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "default",
+            channel: null,
+        });
+        expect(openCodeDbPathExists(resolution)).toBe(false);
+    });
+
+    it("re-probes discovery when the memoized chosen file disappears", () => {
+        const { openCodeDir } = useDataHome();
+        const primary = createCandidate(openCodeDir, "opencode-local.db", 2_000);
+        const fallback = createCandidate(openCodeDir, "opencode.db", 1_000);
+        expect(resolveOpenCodeDbPath().path).toBe(primary);
+
+        unlinkSync(primary);
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: fallback,
+            source: "discovered",
+            channel: null,
+        });
+    });
+
+    it("uses the verbatim v2 channel filename table without changing v1 defaults", () => {
+        const { dataHome, openCodeDir } = useDataHome();
+        for (const channel of ["latest", "dev", "beta", "next", "prod"]) {
+            expect(sourceOpenCodeDatabaseFilename("v2", channel, {})).toBe("opencode.db");
+        }
+        expect(sourceOpenCodeDatabaseFilename("v2", "a/b c!._-", {})).toBe("opencode-abc._-.db");
+        expect(
+            resolveOpenCodeDbPath("v2", {
+                dataHome,
+                channel: "local",
+                env: { OPENCODE_DB: "opencode2.db" },
+            }),
+        ).toEqual({
+            path: join(openCodeDir, "opencode2.db"),
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+    });
+
+    it("takes an absolute v2 OPENCODE_DB as is and resolves a relative one against the data dir", () => {
+        // OpenCode 2 resolves the database with `path.resolve(data, OPENCODE_DB)`;
+        // verified against the 2.0.15 binary's `opencode debug paths db`.
+        const { dataHome, openCodeDir } = useDataHome();
+        const absolute = join(dataHome, "elsewhere", "custom.db");
+        expect(resolveOpenCodeDbPath("v2", { dataHome, env: { OPENCODE_DB: absolute } })).toEqual({
+            path: absolute,
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+        expect(
+            resolveOpenCodeDbPath("v2", { dataHome, env: { OPENCODE_DB: "nested/../rel.db" } }),
+        ).toEqual({ path: join(openCodeDir, "rel.db"), source: "OPENCODE_DB", channel: null });
+        expect(resolveOpenCodeDbPath("v2", { dataHome, env: { OPENCODE_DB: ":memory:" } })).toEqual(
+            { path: ":memory:", source: "OPENCODE_DB", channel: null },
+        );
+    });
+
+    it("detects store generations and refuses a mismatched schema before reading", () => {
+        const { openCodeDir } = useDataHome();
+        const v1Path = join(openCodeDir, "v1.db");
+        const v2Path = join(openCodeDir, "v2.db");
+        const v1 = new Database(v1Path);
+        const v2 = new Database(v2Path);
+        try {
+            v1.exec("CREATE TABLE message(id TEXT); CREATE TABLE part(id TEXT)");
+            v2.exec("CREATE TABLE session_message(id TEXT)");
+            expect(detectOpenCodeStoreGeneration(v1)).toBe("v1");
+            expect(detectOpenCodeStoreGeneration(v2)).toBe("v2");
+            expect(() => assertOpenCodeStoreGeneration(v2, "v1", v2Path)).toThrow(
+                "expected v1, found v2",
+            );
+            expect(() => assertOpenCodeStoreGeneration(v1, "v2", v1Path)).toThrow(
+                "expected v2, found v1",
+            );
+        } finally {
+            v1.close();
+            v2.close();
+        }
+    });
+
+    it("reads a live OpenCode 1.18.x store as v1 even though it ships session_message", () => {
+        const { openCodeDir } = useDataHome();
+        const livePath = join(openCodeDir, "live-v1.db");
+        const live = new Database(livePath);
+        try {
+            // Captured from a running OpenCode 1.18.30 store. session_message exists in v1,
+            // so a detector keyed on its presence calls a v1 host v2 and every v1 reader
+            // (historian chunk, marker discovery, message index, tool-owner backfill) then
+            // refuses. Keep this table list as observed, not as remembered.
+            for (const table of [
+                "account",
+                "event",
+                "message",
+                "part",
+                "permission",
+                "project",
+                "session",
+                "session_message",
+                "session_run_lease",
+                "todo",
+                "workspace",
+            ]) {
+                live.exec(`CREATE TABLE ${table}(id TEXT)`);
+            }
+            expect(detectOpenCodeStoreGeneration(live)).toBe("v1");
+            expect(() => assertOpenCodeStoreGeneration(live, "v1", livePath)).not.toThrow();
+            expect(() => assertOpenCodeStoreGeneration(live, "v2", livePath)).toThrow(
+                "expected v2, found v1",
+            );
+        } finally {
+            live.close();
+        }
+    });
+
+    it("reports v1 message capability on a migrated store accepted by both readers", () => {
+        const { openCodeDir } = useDataHome();
+        const migratedPath = join(openCodeDir, "migrated-v2.db");
+        const migrated = new Database(migratedPath);
+        try {
+            // Captured from an OpenCode 2.0.7 store that the v2 host migrated from a 1.18.x
+            // store: it keeps the v1 `message`/`part` tables beside its own schema, so it
+            // carries BOTH generations. `session_v2` is written only by an OpenCode 2 host
+            // (the 1.18.31 binary never references it). Keep this table list as observed.
+            for (const table of [
+                "account",
+                "account_state",
+                "control_account",
+                "credential",
+                "event",
+                "event_sequence",
+                "instruction_blob",
+                "instruction_entry",
+                "instruction_state",
+                "kv",
+                "message",
+                "migration",
+                "part",
+                "permission",
+                "project",
+                "project_directory",
+                "session",
+                "session_inbox",
+                "session_message",
+                "session_pending",
+                "session_share",
+                "session_v2",
+                "todo",
+                "workspace",
+                "worktree",
+            ]) {
+                migrated.exec(`CREATE TABLE ${table}(id TEXT)`);
+            }
+            expect(hasV1MessageTables(migrated)).toBe(true);
+            expect(() => assertOpenCodeStoreGeneration(migrated, "v2", migratedPath)).not.toThrow();
+            expect(() => assertOpenCodeStoreGeneration(migrated, "v1", migratedPath)).not.toThrow();
+        } finally {
+            migrated.close();
+        }
+    });
+
+    it("reads a fresh OpenCode 2 store as v2 only", () => {
+        const { openCodeDir } = useDataHome();
+        const freshV2Path = join(openCodeDir, "fresh-v2.db");
+        const freshV2 = new Database(freshV2Path);
+        try {
+            // Captured from a new OpenCode 2.0.7 data directory: no v1 message tables.
+            for (const table of [
+                "account",
+                "event",
+                "migration",
+                "permission",
+                "project",
+                "session_inbox",
+                "session_message",
+                "session_pending",
+                "session_v2",
+                "workspace",
+            ]) {
+                freshV2.exec(`CREATE TABLE ${table}(id TEXT)`);
+            }
+            expect(hasV1MessageTables(freshV2)).toBe(false);
+            expect(detectOpenCodeStoreGeneration(freshV2)).toBe("v2");
+            expect(() => assertOpenCodeStoreGeneration(freshV2, "v2", freshV2Path)).not.toThrow();
+            expect(() => assertOpenCodeStoreGeneration(freshV2, "v1", freshV2Path)).toThrow(
+                "expected v1, found v2",
+            );
+        } finally {
+            freshV2.close();
+        }
+    });
+
+    it("treats a store with no schema yet as empty rather than as a conflicting host", () => {
+        const { openCodeDir } = useDataHome();
+        const freshPath = join(openCodeDir, "fresh.db");
+        const fresh = new Database(freshPath);
+        try {
+            // A host that has not written its first row looks like this. Readers have always
+            // seen it as empty; refusing here throws inside the historian, marker and index
+            // readers on every fresh data directory.
+            expect(detectOpenCodeStoreGeneration(fresh)).toBe("unknown");
+            expect(() => assertOpenCodeStoreGeneration(fresh, "v1", freshPath)).not.toThrow();
+            expect(() => assertOpenCodeStoreGeneration(fresh, "v2", freshPath)).not.toThrow();
+        } finally {
+            fresh.close();
+        }
+    });
+
+    it("formats the missing banner, status, and doctor lines by value", () => {
+        const { openCodeDir } = useDataHome();
+        const lookedFor = [
+            join(openCodeDir, "opencode.db"),
+            join(openCodeDir, "opencode-local.db"),
+            join(openCodeDir, "opencode-dev.db"),
+            join(openCodeDir, "opencode-<channel>.db"),
+        ].join(", ");
+        const resolution = resolveOpenCodeDbPath();
+
+        expect(formatOpenCodeDbMissingBanner(resolution)).toBe(
+            `Magic Context cannot find OpenCode's session database (looked for ${lookedFor}). History compaction (historian) and the mid-turn valve are disabled until it is found; set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+        expect(formatOpenCodeDbMissingStatusLine(resolution)).toBe(
+            `OpenCode DB: MISSING (looked for ${lookedFor}). History compaction (historian) and the mid-turn valve are disabled; set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+        expect(formatOpenCodeDbDoctorLine(resolution)).toBe(
+            `FAIL OpenCode session database: not found (looked for ${lookedFor}); set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+    });
+});