@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/conflict-fixer.ts

@@ -0,0 +1,295 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse } from "comment-json";
+
+import {
+    type ConflictResult,
+    DCP_PACKAGE_NAMES,
+    extractPluginName,
+    matchesPackageName,
+} from "./conflict-detector";
+import { appendJsoncArrayValues, removeJsoncArrayEntries, setJsoncValue } from "./jsonc-edit";
+import { getOpenCodeConfigPaths } from "./opencode-config-dir";
+
+type JsonObject = Record<string, unknown>;
+
+const CONFLICTING_OMO_HOOKS = [
+    "context-window-monitor",
+    "preemptive-compaction",
+    "anthropic-context-window-limit-recovery",
+] as const;
+
+const OMO_CONFIG_NAMES = [
+    "oh-my-openagent.jsonc",
+    "oh-my-openagent.json",
+    "oh-my-opencode.jsonc",
+    "oh-my-opencode.json",
+] as const;
+
+/** Unified OMO config names (oh-my-openagent >= 4.19.0) */
+const OMO_UNIFIED_NAMES = ["omo.jsonc", "omo.json"] as const;
+
+function isRecord(value: unknown): value is JsonObject {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asStringArray(value: unknown): string[] {
+    return Array.isArray(value)
+        ? value.filter((item): item is string => typeof item === "string")
+        : [];
+}
+
+interface JsonConfigDocument {
+    config: JsonObject;
+    text: string;
+}
+
+function readConfig(filePath: string): JsonConfigDocument | null {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+
+    try {
+        const text = readFileSync(filePath, "utf-8");
+        const parsed = parse(text);
+        return isRecord(parsed) ? { config: parsed, text } : null;
+    } catch {
+        return null;
+    }
+}
+
+function writeConfig(filePath: string, text: string): void {
+    writeFileSync(filePath, text);
+}
+
+function resolveUserOpenCodeConfigPath(): string {
+    const paths = getOpenCodeConfigPaths({ binary: "opencode" });
+    if (existsSync(paths.configJsonc)) return paths.configJsonc;
+    return paths.configJson;
+}
+
+function collectOpenCodeConfigPaths(directory: string): string[] {
+    const paths = new Set<string>();
+    const userConfig = resolveUserOpenCodeConfigPath();
+
+    if (existsSync(userConfig)) {
+        paths.add(userConfig);
+    }
+
+    for (const filePath of [
+        join(directory, ".opencode", "opencode.jsonc"),
+        join(directory, ".opencode", "opencode.json"),
+        join(directory, "opencode.jsonc"),
+        join(directory, "opencode.json"),
+    ]) {
+        if (existsSync(filePath)) {
+            paths.add(filePath);
+        }
+    }
+
+    return [...paths];
+}
+
+function collectOmoConfigPaths(directory: string): string[] {
+    const paths = new Set<string>();
+    const configDir = getOpenCodeConfigPaths({ binary: "opencode" }).configDir;
+
+    // Legacy OMO config names in the OpenCode config dir and project dir
+    for (const fileName of OMO_CONFIG_NAMES) {
+        const userPath = join(configDir, fileName);
+        const projectPath = join(directory, fileName);
+
+        if (existsSync(userPath)) {
+            paths.add(userPath);
+        }
+
+        if (existsSync(projectPath)) {
+            paths.add(projectPath);
+        }
+    }
+
+    // New unified omo.jsonc (oh-my-openagent >= 4.19.0)
+    // User-level: ~/.omo/omo.jsonc (fallback ~/.omo/omo.json)
+    const homeDir = process.env.HOME || homedir();
+    const omoHomeDir = join(homeDir, ".omo");
+    for (const name of OMO_UNIFIED_NAMES) {
+        const userPath = join(omoHomeDir, name);
+        if (existsSync(userPath)) {
+            paths.add(userPath);
+        }
+    }
+
+    // Project-level: .omo/omo.jsonc (fallback .omo/omo.json)
+    for (const name of OMO_UNIFIED_NAMES) {
+        const projectPath = join(directory, ".omo", name);
+        if (existsSync(projectPath)) {
+            paths.add(projectPath);
+        }
+    }
+
+    return [...paths];
+}
+
+/** Check if a config path is a unified omo.json(c) path (not legacy). */
+function isUnifiedOmoPath(configPath: string): boolean {
+    const basename = configPath.split("/").pop() ?? "";
+    return basename === "omo.jsonc" || basename === "omo.json";
+}
+
+function disableCompactionFlags(
+    text: string,
+    config: JsonObject,
+): { text: string; changed: boolean } {
+    if (!isRecord(config.compaction)) {
+        return {
+            text: setJsoncValue(text, ["compaction"], { auto: false, prune: false }),
+            changed: true,
+        };
+    }
+
+    let updated = text;
+    let changed = false;
+    if (config.compaction.auto !== false) {
+        updated = setJsoncValue(updated, ["compaction", "auto"], false);
+        changed = true;
+    }
+    if (config.compaction.prune !== false) {
+        updated = setJsoncValue(updated, ["compaction", "prune"], false);
+        changed = true;
+    }
+    return { text: updated, changed };
+}
+
+/**
+ * Options for {@link fixConflicts}.
+ *
+ * `compactionEnabled` is the boot-resolved MC compaction mode (the result of
+ * {@link isCompactionEnabled} on the resolved user-tier config). When `false`
+ * (compaction-off mode), the fixer MUST NOT flip `compaction.auto`/`prune` to
+ * `false` — native compaction fields are left byte-for-byte as found, because
+ * native compaction (or nothing) is the user's chosen window manager. DCP and
+ * OMO hook fixes keep their existing policy in BOTH modes.
+ *
+ * Default `true` (mode-on) preserves today's fix behavior for call sites that
+ * cannot supply the resolved mode; they fail toward mode-on, never silently
+ * skipping the fix.
+ */
+export interface FixConflictsOptions {
+    compactionEnabled?: boolean;
+}
+
+export function fixConflicts(
+    directory: string,
+    conflicts: ConflictResult["conflicts"],
+    options?: FixConflictsOptions,
+): string[] {
+    const compactionEnabled = options?.compactionEnabled ?? true;
+    const actions: string[] = [];
+    let updatedCompaction = false;
+    let removedDcpPlugin = false;
+    let disabledOmoHooks = false;
+
+    // Native compaction fields are repaired ONLY when MC compaction is ON. In
+    // compaction-off mode the fixer must not rewrite compaction.auto/prune —
+    // native compaction is the intended manager and pre-existing values are
+    // left byte-for-byte as found.
+    const repairCompaction =
+        compactionEnabled && (conflicts.compactionAuto || conflicts.compactionPrune);
+
+    if (repairCompaction || conflicts.dcpPlugin) {
+        for (const configPath of collectOpenCodeConfigPaths(directory)) {
+            const document = readConfig(configPath);
+            if (!document) {
+                continue;
+            }
+
+            let text = document.text;
+            let changed = false;
+
+            if (repairCompaction) {
+                const result = disableCompactionFlags(text, document.config);
+                if (result.changed) {
+                    text = result.text;
+                    changed = true;
+                    updatedCompaction = true;
+                }
+            }
+
+            if (conflicts.dcpPlugin) {
+                const result = removeJsoncArrayEntries(text, ["plugin"], (entry) => {
+                    const name = extractPluginName(entry);
+                    return name ? matchesPackageName(name, DCP_PACKAGE_NAMES) : false;
+                });
+                if (result.removed) {
+                    text = result.text;
+                    changed = true;
+                    removedDcpPlugin = true;
+                }
+            }
+
+            if (changed) {
+                writeConfig(configPath, text);
+            }
+        }
+    }
+
+    if (
+        conflicts.omoContextWindowMonitor ||
+        conflicts.omoPreemptiveCompaction ||
+        conflicts.omoAnthropicRecovery
+    ) {
+        const hooksToDisable = new Set<string>();
+        if (conflicts.omoContextWindowMonitor) {
+            hooksToDisable.add("context-window-monitor");
+        }
+        if (conflicts.omoPreemptiveCompaction) {
+            hooksToDisable.add("preemptive-compaction");
+        }
+        if (conflicts.omoAnthropicRecovery) {
+            hooksToDisable.add("anthropic-context-window-limit-recovery");
+        }
+
+        for (const configPath of collectOmoConfigPaths(directory)) {
+            const document = readConfig(configPath);
+            if (!document) {
+                continue;
+            }
+
+            const unifiedPath = isUnifiedOmoPath(configPath);
+            const target =
+                unifiedPath && isRecord(document.config["[opencode]"])
+                    ? document.config["[opencode]"]
+                    : unifiedPath
+                      ? {}
+                      : document.config;
+            const disabledHooks = new Set(asStringArray(target.disabled_hooks));
+            const hooksToAdd = CONFLICTING_OMO_HOOKS.filter(
+                (hook) => hooksToDisable.has(hook) && !disabledHooks.has(hook),
+            );
+
+            if (hooksToAdd.length > 0) {
+                const path = unifiedPath ? ["[opencode]", "disabled_hooks"] : ["disabled_hooks"];
+                const text = Array.isArray(target.disabled_hooks)
+                    ? appendJsoncArrayValues(document.text, path, hooksToAdd)
+                    : setJsoncValue(document.text, path, hooksToAdd);
+                writeConfig(configPath, text);
+                disabledOmoHooks = true;
+            }
+        }
+    }
+
+    if (updatedCompaction) {
+        actions.push("Disabled auto-compaction");
+    }
+
+    if (removedDcpPlugin) {
+        actions.push("Removed opencode-dcp plugin");
+    }
+
+    if (disabledOmoHooks) {
+        actions.push("Disabled conflicting oh-my-opencode hooks");
+    }
+
+    return actions;
+}

package/src/shared/context-limit-provenance.ts

@@ -0,0 +1,6 @@
+export type ContextLimitProvenance = "prompt_only" | "combined" | "unknown";
+
+export function normalizeContextLimitProvenance(value: unknown): ContextLimitProvenance {
+    if (value === "prompt_only" || value === "combined") return value;
+    return "unknown";
+}

package/src/shared/data-path.test.ts

@@ -0,0 +1,352 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+    ensureMmcArtifactGitignore,
+    getCacheDir,
+    getDataDir,
+    getLegacyOpenCodeMagicContextStorageDir,
+    getMagicContextLogPath,
+    getMagicContextStorageDir,
+    getMagicContextStorageResolution,
+    getOpenCodeCacheDir,
+    getOpenCodeStorageDir,
+    getProjectMagicContextDir,
+    getProjectMagicContextHistorianDir,
+} from "./data-path";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+const savedEnv = {
+    XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+    XDG_DATA_HOME: process.env.XDG_DATA_HOME,
+    MMC_STORAGE_DIR: process.env.MMC_STORAGE_DIR,
+    LOCALAPPDATA: process.env.LOCALAPPDATA,
+    MMC_LOG_PATH: process.env.MMC_LOG_PATH,
+    MMC_TEST_DATA_DIR: process.env.MMC_TEST_DATA_DIR,
+    NODE_ENV: process.env.NODE_ENV,
+};
+
+describe("data-path", () => {
+    beforeEach(() => {
+        process.env.XDG_CACHE_HOME = undefined;
+        process.env.XDG_DATA_HOME = process.env.MMC_TEST_DATA_DIR;
+        delete process.env.MMC_TEST_DATA_DIR;
+        delete process.env.NODE_ENV;
+        process.env.LOCALAPPDATA = undefined;
+        process.env.MMC_LOG_PATH = undefined;
+        // Bun's env handling: explicit delete for unset. XDG_DATA_HOME is
+        // deliberately NOT deleted: it keeps the preload's isolated root
+        // captured above, so a fallback after any mid-test deletion lands on
+        // isolation instead of the real home. Tests asserting unset-XDG
+        // fallback behavior delete it themselves.
+        delete process.env.XDG_CACHE_HOME;
+        delete process.env.MMC_STORAGE_DIR;
+        delete process.env.LOCALAPPDATA;
+        delete process.env.MMC_LOG_PATH;
+    });
+
+    afterEach(() => {
+        // Restore-or-delete every var this suite touches. Several tests lift a
+        // guard (NODE_ENV, MMC_TEST_DATA_DIR) to assert production
+        // shape, so a restore that skips the unset case would leak state into
+        // the next test and make results order-dependent.
+        for (const [key, value] of Object.entries(savedEnv)) {
+            if (value !== undefined) process.env[key] = value;
+            else delete process.env[key];
+        }
+    });
+
+    test("getCacheDir falls back to <homedir>/.cache when XDG_CACHE_HOME is unset (all platforms)", () => {
+        // Matches OpenCode's xdg-basedir behavior on every platform, including
+        // Windows. A previous bug mapped Windows to %LOCALAPPDATA% and caused
+        // doctor --force to target a non-existent cache directory.
+        expect(getCacheDir()).toBe(path.join(os.homedir(), ".cache"));
+    });
+
+    test("getCacheDir honors XDG_CACHE_HOME when set", () => {
+        process.env.XDG_CACHE_HOME = "/tmp/custom-cache";
+        expect(getCacheDir()).toBe("/tmp/custom-cache");
+    });
+
+    test("getCacheDir ignores LOCALAPPDATA on Windows (must match OpenCode's xdg-basedir)", () => {
+        // Even with LOCALAPPDATA set, cache must go to ~/.cache to match
+        // OpenCode's own resolution. Otherwise doctor --force clears the
+        // wrong directory on Windows.
+        process.env.LOCALAPPDATA = "C:\\Users\\Test\\AppData\\Local";
+        expect(getCacheDir()).toBe(path.join(os.homedir(), ".cache"));
+    });
+
+    test("getOpenCodeCacheDir appends 'opencode' to the cache base", () => {
+        expect(getOpenCodeCacheDir()).toBe(path.join(os.homedir(), ".cache", "opencode"));
+    });
+
+    test("getOpenCodeCacheDir with XDG_CACHE_HOME set", () => {
+        process.env.XDG_CACHE_HOME = "/tmp/custom-cache";
+        expect(getOpenCodeCacheDir()).toBe(path.join("/tmp/custom-cache", "opencode"));
+    });
+
+    test("getDataDir falls back to <homedir>/.local/share when XDG_DATA_HOME is unset", () => {
+        // beforeEach seeds XDG_DATA_HOME with the preload's isolated root; this
+        // assertion is about the unset fallback, so create that state for real.
+        delete process.env.XDG_DATA_HOME;
+        expect(getDataDir()).toBe(path.join(os.homedir(), ".local", "share"));
+    });
+
+    test("getOpenCodeStorageDir composes correctly", () => {
+        delete process.env.XDG_DATA_HOME;
+        expect(getOpenCodeStorageDir()).toBe(
+            path.join(os.homedir(), ".local", "share", "opencode", "storage"),
+        );
+    });
+
+    test("getMagicContextStorageDir uses mmc layout", () => {
+        // Cross-harness shared path: both OpenCode and Pi plugins read/write here,
+        // unlike the legacy opencode/storage/plugin/magic-context location which
+        // was OpenCode-specific. See ARCHITECTURE_DECISIONS memory for rationale.
+        // Production shape, so all three test-isolation guards (the preload's
+        // data dir, the seeded XDG_DATA_HOME, and the NODE_ENV backstop bun
+        // sets for every `bun test`) are lifted for the duration of this
+        // assertion.
+        const savedTestDir = process.env.MMC_TEST_DATA_DIR;
+        const savedNodeEnv = process.env.NODE_ENV;
+        delete process.env.MMC_TEST_DATA_DIR;
+        delete process.env.NODE_ENV;
+        delete process.env.XDG_DATA_HOME;
+        try {
+            expect(getMagicContextStorageDir()).toBe(
+                path.join(os.homedir(), ".local", "share", "mmc"),
+            );
+        } finally {
+            if (savedTestDir !== undefined) process.env.MMC_TEST_DATA_DIR = savedTestDir;
+            if (savedNodeEnv !== undefined) process.env.NODE_ENV = savedNodeEnv;
+        }
+    });
+
+    test("getMagicContextStorageDir backstops to a temp dir under NODE_ENV=test with no guard set", () => {
+        // CWD-independent backstop: a `bun test` from a dir whose bunfig has no
+        // `[test] preload` runs every suite with neither guard env var set. The
+        // DB resolver used to own this branch, so direct callers of this helper
+        // (the CLI doctors' own PRAGMA integrity_check) still reached the real
+        // shared DB. Memoized, so repeated calls must agree — openDatabase()
+        // caches by path.
+        const savedTestDir = process.env.MMC_TEST_DATA_DIR;
+        delete process.env.MMC_TEST_DATA_DIR;
+        process.env.NODE_ENV = "test";
+        try {
+            const resolved = getMagicContextStorageDir();
+            expect(resolved).not.toContain(path.join(os.homedir(), ".local", "share"));
+            expect(resolved.endsWith(path.join("mmc"))).toBe(true);
+            expect(getMagicContextStorageDir()).toBe(resolved);
+        } finally {
+            if (savedTestDir !== undefined) process.env.MMC_TEST_DATA_DIR = savedTestDir;
+        }
+    });
+
+    test("getMagicContextStorageDir honors MMC_TEST_DATA_DIR when XDG_DATA_HOME is unset", () => {
+        // The hole this closes: a test that deletes XDG_DATA_HOME to exercise
+        // path fallbacks used to resolve to the user's REAL shared storage,
+        // because bun caches os.homedir() and a mutated process.env.HOME cannot
+        // move getDataDir(). Callers that build their own context.db path (the
+        // CLI doctors) then ran integrity checks against production data.
+        delete process.env.XDG_DATA_HOME;
+        process.env.MMC_TEST_DATA_DIR = "/tmp/mc-test-isolation";
+        expect(getMagicContextStorageDir()).toBe(path.join("/tmp/mc-test-isolation", "mmc"));
+    });
+
+    test("test storage isolation takes precedence over MMC_STORAGE_DIR", () => {
+        delete process.env.XDG_DATA_HOME;
+        process.env.MMC_TEST_DATA_DIR = "/tmp/mc-test-isolation";
+        process.env.MMC_STORAGE_DIR = "/tmp/production-shared-data";
+        expect(getMagicContextStorageDir()).toBe(path.join("/tmp/mc-test-isolation", "mmc"));
+    });
+
+    test("a per-test XDG_DATA_HOME overrides the preload root without escaping test isolation", () => {
+        process.env.MMC_TEST_DATA_DIR = "/tmp/mc-test-isolation";
+        process.env.XDG_DATA_HOME = "/tmp/custom-test-data";
+        process.env.MMC_STORAGE_DIR = "/tmp/production-shared-data";
+        expect(getMagicContextStorageResolution()).toEqual({
+            path: path.join("/tmp/custom-test-data", "mmc"),
+            source: "test isolation",
+        });
+    });
+
+    test("getMagicContextStorageDir honors XDG_DATA_HOME", () => {
+        process.env.XDG_DATA_HOME = "/tmp/custom-data";
+        expect(getMagicContextStorageDir()).toBe(path.join("/tmp/custom-data", "mmc"));
+    });
+
+    test("getMagicContextStorageDir honors MMC_STORAGE_DIR", () => {
+        process.env.XDG_DATA_HOME = "/tmp/private-agent-data";
+        process.env.MMC_STORAGE_DIR = "/tmp/shared-magic-context";
+        expect(getMagicContextStorageDir()).toBe("/tmp/shared-magic-context");
+    });
+
+    test("MMC_STORAGE_DIR takes precedence over XDG_DATA_HOME", () => {
+        process.env.XDG_DATA_HOME = "/tmp/private-agent-data";
+        process.env.MMC_STORAGE_DIR = "/tmp/shared-magic-context";
+        expect(getMagicContextStorageDir()).toBe("/tmp/shared-magic-context");
+    });
+
+    test("relative MMC_STORAGE_DIR is rejected", () => {
+        process.env.MMC_STORAGE_DIR = "./shared-magic-context";
+        expect(() => getMagicContextStorageDir()).toThrow(
+            "MMC_STORAGE_DIR must be an absolute path",
+        );
+    });
+
+    test("blank MMC_STORAGE_DIR falls back to XDG_DATA_HOME", () => {
+        process.env.MMC_STORAGE_DIR = "   ";
+        process.env.XDG_DATA_HOME = "/tmp/custom-data";
+        expect(getMagicContextStorageDir()).toBe(path.join("/tmp/custom-data", "mmc"));
+    });
+
+    test("getLegacyOpenCodeMagicContextStorageDir points at the pre-mmc OpenCode path", () => {
+        // Used only for one-time migration of pre-shared-storage data into the new
+        // location. Must remain stable so users with legacy installs can still
+        // have their data migrated forward across multiple plugin upgrades.
+        delete process.env.XDG_DATA_HOME;
+        expect(getLegacyOpenCodeMagicContextStorageDir()).toBe(
+            path.join(
+                os.homedir(),
+                ".local",
+                "share",
+                "opencode",
+                "storage",
+                "plugin",
+                "magic-context",
+            ),
+        );
+    });
+
+    test("legacy storage dir distinct from new shared dir even with same XDG override", () => {
+        // Sanity check: even when XDG_DATA_HOME points the same place, the two
+        // resolvers must return different paths so the migration copy doesn't
+        // self-overwrite.
+        process.env.XDG_DATA_HOME = "/tmp/test-xdg";
+        const legacy = getLegacyOpenCodeMagicContextStorageDir();
+        const shared = getMagicContextStorageDir();
+        expect(legacy).not.toBe(shared);
+        expect(legacy).toContain("opencode");
+        expect(shared).toContain("mmc");
+    });
+
+    test("getProjectMagicContextDir composes <project>/.mmc/magic-context", () => {
+        // Project-local artifacts (historian state file, failure dumps) live
+        // inside the project so OpenCode's external_directory permission system
+        // treats them as project-internal. Without this, historian's Read tool
+        // would trigger a permission prompt on every run when artifacts lived
+        // under os.tmpdir(). Moved from .opencode/ to the shared .mmc/.
+        expect(getProjectMagicContextDir("/Users/me/Work/proj")).toBe(
+            path.join("/Users/me/Work/proj", ".mmc", "magic-context"),
+        );
+    });
+
+    test("getProjectMagicContextHistorianDir appends historian/", () => {
+        expect(getProjectMagicContextHistorianDir("/Users/me/Work/proj")).toBe(
+            path.join("/Users/me/Work/proj", ".mmc", "magic-context", "historian"),
+        );
+    });
+
+    test("getProjectMagicContextDir is unaffected by XDG_DATA_HOME", () => {
+        // Project-local paths anchor to the project directory the caller
+        // passes in, NOT to any user-config env var. Setting XDG_DATA_HOME
+        // (which changes the shared storage dir) must not change the
+        // project-local historian dir.
+        process.env.XDG_DATA_HOME = "/tmp/custom-data";
+        expect(getProjectMagicContextDir("/some/project")).toBe(
+            path.join("/some/project", ".mmc", "magic-context"),
+        );
+    });
+
+    test("getProjectMagicContextDir handles trailing slashes via path.join", () => {
+        // path.join normalizes redundant separators so callers don't need to
+        // worry about how the project directory was constructed.
+        expect(getProjectMagicContextDir("/some/project/")).toBe(
+            path.join("/some/project/", ".mmc", "magic-context"),
+        );
+    });
+
+    test("getMagicContextLogPath falls back to the harness temp dir when the env override is unset", () => {
+        expect(getMagicContextLogPath("opencode")).toBe(
+            path.join(os.tmpdir(), "opencode", "magic-context", "magic-context.log"),
+        );
+        expect(getMagicContextLogPath("pi")).toBe(
+            path.join(os.tmpdir(), "pi", "magic-context", "magic-context.log"),
+        );
+    });
+
+    test("getMagicContextLogPath honors MMC_LOG_PATH", () => {
+        process.env.MMC_LOG_PATH = "/tmp/custom/magic-context.log";
+        expect(getMagicContextLogPath("pi")).toBe("/tmp/custom/magic-context.log");
+    });
+
+    test("getMagicContextLogPath ignores a blank MMC_LOG_PATH", () => {
+        process.env.MMC_LOG_PATH = "   ";
+        expect(getMagicContextLogPath("pi")).toBe(
+            path.join(os.tmpdir(), "pi", "magic-context", "magic-context.log"),
+        );
+    });
+});
+
+describe("ensureMmcArtifactGitignore", () => {
+    test("creates .mmc/.gitignore with a fenced magic-context block", () => {
+        const dir = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            ensureMmcArtifactGitignore(dir);
+            const gi = readFileSync(path.join(dir, ".mmc", ".gitignore"), "utf8");
+            expect(gi).toContain("# >>> mmc:magic-context");
+            expect(gi).toContain("magic-context/");
+            expect(gi).toContain("# <<< mmc:magic-context");
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    test("is idempotent — a second call does not duplicate the block", () => {
+        const dir = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            ensureMmcArtifactGitignore(dir);
+            ensureMmcArtifactGitignore(dir);
+            const gi = readFileSync(path.join(dir, ".mmc", ".gitignore"), "utf8");
+            const occurrences = gi.split("# >>> mmc:magic-context").length - 1;
+            expect(occurrences).toBe(1);
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    test("preserves a sibling module's existing entries (appends, never clobbers)", () => {
+        const dir = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            const ckDir = path.join(dir, ".mmc");
+            mkdirSync(ckDir, { recursive: true });
+            // Simulate a sibling (e.g. AFT) already owning a fenced block.
+            writeFileSync(
+                path.join(ckDir, ".gitignore"),
+                "# >>> aft:aft\naft/scratch/\n# <<< aft:aft\n",
+            );
+            ensureMmcArtifactGitignore(dir);
+            const gi = readFileSync(path.join(ckDir, ".gitignore"), "utf8");
+            expect(gi).toContain("# >>> aft:aft");
+            expect(gi).toContain("aft/scratch/");
+            expect(gi).toContain("# >>> mmc:magic-context");
+            expect(gi).toContain("magic-context/");
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    test("does not ignore the project config — only the artifact dir", () => {
+        const dir = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-gi-"));
+        try {
+            ensureMmcArtifactGitignore(dir);
+            const gi = readFileSync(path.join(dir, ".mmc", ".gitignore"), "utf8");
+            // The config file stays tracked: it must NOT appear as an ignore.
+            expect(gi).not.toContain("mmc.jsonc");
+            expect(gi).not.toContain("*.jsonc");
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});