@mison/ling 1.0.0

package/tests/clean-script.test.js

@@ -0,0 +1,77 @@
+const { test, describe, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { parseArgs, runClean } = require("../scripts/clean");
+
+describe("Clean Script", () => {
+    let tempRoot;
+
+    beforeEach(() => {
+        tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-clean-test-"));
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    });
+
+    test("parseArgs should parse dry-run and quiet options", () => {
+        const options = parseArgs(["--dry-run", "--quiet"]);
+        assert.strictEqual(options.dryRun, true);
+        assert.strictEqual(options.quiet, true);
+    });
+
+    test("runClean should remove existing generated directories", () => {
+        const targetA = path.join(tempRoot, "web", ".next");
+        const targetB = path.join(tempRoot, "web", "node_modules");
+        fs.mkdirSync(targetA, { recursive: true });
+        fs.mkdirSync(targetB, { recursive: true });
+        fs.writeFileSync(path.join(targetA, "cache.txt"), "x");
+        fs.writeFileSync(path.join(targetB, "dep.txt"), "x");
+
+        const result = runClean({
+            rootDir: tempRoot,
+            quiet: true,
+            targets: ["web/.next", "web/node_modules"],
+        });
+
+        assert.strictEqual(result.removedCount, 2);
+        assert.ok(!fs.existsSync(targetA));
+        assert.ok(!fs.existsSync(targetB));
+    });
+
+    test("runClean dry-run should not remove directories", () => {
+        const target = path.join(tempRoot, "web", ".next");
+        fs.mkdirSync(target, { recursive: true });
+
+        const result = runClean({
+            rootDir: tempRoot,
+            dryRun: true,
+            quiet: true,
+            targets: ["web/.next"],
+        });
+
+        assert.strictEqual(result.wouldRemoveCount, 1);
+        assert.ok(fs.existsSync(target));
+    });
+
+    test("runClean should skip missing paths", () => {
+        const result = runClean({
+            rootDir: tempRoot,
+            quiet: true,
+            targets: ["web/.next"],
+        });
+
+        assert.strictEqual(result.skippedCount, 1);
+        assert.strictEqual(result.results[0].reason, "not_found");
+    });
+
+    test("package scripts should keep scoped test and clean commands", () => {
+        const packageJsonPath = path.resolve(__dirname, "..", "package.json");
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+
+        assert.strictEqual(packageJson.scripts.test, "node scripts/run-tests.js");
+        assert.strictEqual(packageJson.scripts.clean, "node scripts/clean.js");
+    });
+});

package/tests/cli-smoke.test.js

@@ -0,0 +1,479 @@
+const { test, describe, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const REPO_ROOT = path.resolve(__dirname, "..");
+const CLI_PATH = path.join(REPO_ROOT, "bin", "ling.js");
+
+function runCli(args, options = {}) {
+    const env = {
+        ...process.env,
+        LING_SKIP_UPSTREAM_CHECK: "1",
+        ...options.env,
+    };
+
+    return spawnSync(process.execPath, [CLI_PATH, ...args], {
+        cwd: options.cwd || REPO_ROOT,
+        env,
+        encoding: "utf8",
+    });
+}
+
+describe("CLI Smoke", () => {
+    let tempDir;
+    let workspaceDir;
+    let indexPath;
+
+    beforeEach(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "ling-cli-test-"));
+        workspaceDir = path.join(tempDir, "workspace");
+        indexPath = path.join(tempDir, "workspaces.json");
+        fs.mkdirSync(workspaceDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    test("doctor should work after codex init", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        const doctorResult = runCli(
+            ["doctor", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(doctorResult.status, 0, doctorResult.stderr || doctorResult.stdout);
+    });
+
+    test("doctor --quiet should not print diagnostic details", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        const doctorResult = runCli(
+            ["doctor", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(doctorResult.status, 0, doctorResult.stderr || doctorResult.stdout);
+        assert.strictEqual((doctorResult.stdout || "").trim(), "");
+    });
+
+    test("doctor --fix should remove stale .codex directory", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        fs.mkdirSync(path.join(workspaceDir, ".codex"), { recursive: true });
+        fs.writeFileSync(path.join(workspaceDir, ".codex", "legacy.txt"), "legacy");
+        assert.ok(fs.existsSync(path.join(workspaceDir, ".codex")));
+
+        const doctorFixResult = runCli(
+            ["doctor", "--target", "codex", "--path", workspaceDir, "--fix", "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(doctorFixResult.status, 0, doctorFixResult.stderr || doctorFixResult.stdout);
+        assert.ok(!fs.existsSync(path.join(workspaceDir, ".codex")));
+    });
+
+    test("init should not index temporary workspace by default", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        if (!fs.existsSync(indexPath)) {
+            return;
+        }
+
+        const indexData = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+        const hasWorkspace = (indexData.workspaces || []).some((item) => item.path === workspaceDir);
+        assert.ok(!hasWorkspace, "temp workspace should not be persisted into global index");
+    });
+
+    test("codex init should create .agents managed directory", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+        assert.ok(fs.existsSync(path.join(workspaceDir, ".agents")));
+        assert.ok(!fs.existsSync(path.join(workspaceDir, ".codex")));
+    });
+
+    test("codex update should remove pre-existing legacy .codex directory", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+        assert.ok(fs.existsSync(path.join(workspaceDir, ".agents")));
+        fs.mkdirSync(path.join(workspaceDir, ".codex"), { recursive: true });
+        fs.writeFileSync(path.join(workspaceDir, ".codex", "legacy.txt"), "legacy");
+        assert.ok(fs.existsSync(path.join(workspaceDir, ".codex")));
+
+        const updateResult = runCli(
+            ["update", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(updateResult.status, 0, updateResult.stderr || updateResult.stdout);
+        assert.ok(!fs.existsSync(path.join(workspaceDir, ".codex")));
+        assert.ok(fs.existsSync(path.join(workspaceDir, ".agents")));
+    });
+
+    test("update-all should auto-clean temp workspace records from index", () => {
+        const now = new Date().toISOString();
+        const tempWorkspacePath = path.join(os.tmpdir(), "ling-indexed-temp", "workspace");
+        const seedIndex = {
+            version: 2,
+            updatedAt: now,
+            workspaces: [
+                {
+                    path: tempWorkspacePath,
+                    targets: {
+                        gemini: {
+                            version: "2.0.1",
+                            installedAt: now,
+                            updatedAt: now,
+                        },
+                    },
+                },
+            ],
+            excludedPaths: [],
+        };
+        fs.writeFileSync(indexPath, `${JSON.stringify(seedIndex, null, 2)}\n`, "utf8");
+
+        const result = runCli(["update-all", "--quiet"], {
+            env: { LING_INDEX_PATH: indexPath },
+        });
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+        const indexData = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+        const hasTempWorkspace = (indexData.workspaces || []).some((item) => item.path === tempWorkspacePath);
+        assert.ok(!hasTempWorkspace, "temp workspace record should be removed during update-all");
+    });
+
+    test("update-all should normalize legacy full target records in v2 index", () => {
+        const now = new Date().toISOString();
+        const persistentRoot = fs.mkdtempSync(path.join(REPO_ROOT, ".temp-ling-legacy-index-"));
+        const persistentWorkspace = path.join(persistentRoot, "workspace");
+        fs.mkdirSync(persistentWorkspace, { recursive: true });
+
+        try {
+            const initResult = runCli(
+                ["init", "--target", "codex", "--path", persistentWorkspace, "--quiet"],
+                { env: { LING_INDEX_PATH: indexPath } },
+            );
+            assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+            const seedIndex = {
+                version: 2,
+                updatedAt: now,
+                workspaces: [
+                    {
+                        path: persistentWorkspace,
+                        targets: {
+                            full: {
+                                version: "1.9.0",
+                                installedAt: now,
+                                updatedAt: now,
+                            },
+                        },
+                    },
+                ],
+                excludedPaths: [],
+            };
+            fs.writeFileSync(indexPath, `${JSON.stringify(seedIndex, null, 2)}\n`, "utf8");
+
+            const result = runCli(["update-all", "--quiet"], {
+                env: { LING_INDEX_PATH: indexPath },
+            });
+            assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+            const normalized = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+            assert.ok(!("full" in normalized.workspaces[0].targets), "legacy full target should be removed from rewritten index");
+            assert.ok("codex" in normalized.workspaces[0].targets, "codex target should be preserved after update-all");
+        } finally {
+            fs.rmSync(persistentRoot, { recursive: true, force: true });
+        }
+    });
+
+    test("update-all should auto-clean macOS /private/var temp alias records", () => {
+        if (process.platform !== "darwin") {
+            return;
+        }
+
+        const tmpRoot = os.tmpdir();
+        let aliasTempPath = "";
+        if (tmpRoot.startsWith("/var/")) {
+            aliasTempPath = `/private${tmpRoot}/ling-indexed-temp/workspace`;
+        } else if (tmpRoot.startsWith("/private/var/")) {
+            aliasTempPath = `${tmpRoot.replace(/^\/private/, "")}/ling-indexed-temp/workspace`;
+        } else {
+            return;
+        }
+
+        const now = new Date().toISOString();
+        const seedIndex = {
+            version: 2,
+            updatedAt: now,
+            workspaces: [
+                {
+                    path: aliasTempPath,
+                    targets: {
+                        gemini: {
+                            version: "2.0.1",
+                            installedAt: now,
+                            updatedAt: now,
+                        },
+                    },
+                },
+            ],
+            excludedPaths: [],
+        };
+        fs.writeFileSync(indexPath, `${JSON.stringify(seedIndex, null, 2)}\n`, "utf8");
+
+        const result = runCli(["update-all", "--quiet"], {
+            env: { LING_INDEX_PATH: indexPath },
+        });
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+        const indexData = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+        const hasAliasTempWorkspace = (indexData.workspaces || []).some((item) => item.path === aliasTempPath);
+        assert.ok(!hasAliasTempWorkspace, "macOS alias temp path should be removed during update-all");
+    });
+
+    test("init in non-interactive mode should require explicit target", () => {
+        const result = runCli(
+            ["init", "--non-interactive", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.notStrictEqual(result.status, 0);
+        assert.match(result.stderr || result.stdout, /非交互模式下必须通过 --target 或 --targets 指定目标/);
+    });
+
+    test("update should run in gemini dry-run mode", () => {
+        fs.mkdirSync(path.join(workspaceDir, ".agent"), { recursive: true });
+
+        const result = runCli(
+            ["update", "--target", "gemini", "--path", workspaceDir, "--dry-run", "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+    });
+
+    test("status --quiet should report missing with exit code 2 when nothing is installed", () => {
+        const result = runCli(
+            ["status", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 2);
+        assert.strictEqual((result.stdout || "").trim(), "missing");
+    });
+
+    test("status --quiet should report broken when installation is incomplete", () => {
+        fs.mkdirSync(path.join(workspaceDir, ".agent"), { recursive: true });
+
+        const result = runCli(
+            ["status", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 1);
+        assert.strictEqual((result.stdout || "").trim(), "broken");
+    });
+
+    test("status --quiet should report broken for codex drift", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        fs.writeFileSync(path.join(workspaceDir, ".agents", "AGENTS.md"), "drifted", "utf8");
+
+        const result = runCli(
+            ["status", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 1);
+        assert.strictEqual((result.stdout || "").trim(), "broken");
+    });
+
+    test("status --quiet should report installed when installation is healthy", () => {
+        const initResult = runCli(
+            ["init", "--target", "codex", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+        const result = runCli(
+            ["status", "--path", workspaceDir, "--quiet"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+        assert.strictEqual((result.stdout || "").trim(), "installed");
+    });
+
+    test("status should reject unsupported --no-index option", () => {
+        fs.mkdirSync(path.join(workspaceDir, ".agent"), { recursive: true });
+
+        const result = runCli(
+            ["status", "--path", workspaceDir, "--no-index"],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.notStrictEqual(result.status, 0);
+        assert.match(result.stderr || result.stdout, /命令 status 不支持参数: --no-index/);
+    });
+
+    test("exclude list should reject unsupported --path option", () => {
+        const result = runCli(
+            ["exclude", "list", "--path", workspaceDir],
+            { env: { LING_INDEX_PATH: indexPath } },
+        );
+        assert.notStrictEqual(result.status, 0);
+        assert.match(result.stderr || result.stdout, /命令 exclude list 不支持参数: --path/);
+    });
+
+    test("update-all should run in dry-run mode with indexed workspace", () => {
+        fs.mkdirSync(path.join(workspaceDir, ".agent"), { recursive: true });
+        const now = new Date().toISOString();
+        const seedIndex = {
+            version: 2,
+            updatedAt: now,
+            workspaces: [
+                {
+                    path: workspaceDir,
+                    targets: {
+                        gemini: {
+                            version: "2.0.1",
+                            installedAt: now,
+                            updatedAt: now,
+                        },
+                    },
+                },
+            ],
+            excludedPaths: [],
+        };
+        fs.writeFileSync(indexPath, `${JSON.stringify(seedIndex, null, 2)}\n`, "utf8");
+
+        const result = runCli(["update-all", "--dry-run", "--quiet"], {
+            env: { LING_INDEX_PATH: indexPath },
+        });
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+    });
+
+    test("update-all should update installed target even when index target list is stale", () => {
+        const localWorkspace = fs.mkdtempSync(path.join(REPO_ROOT, ".tmp-ling-update-all-stale-target-"));
+        try {
+            fs.mkdirSync(path.join(localWorkspace, ".codex"), { recursive: true });
+            fs.writeFileSync(
+                path.join(localWorkspace, ".codex", "manifest.json"),
+                JSON.stringify({ version: 2, target: "codex", files: {} }),
+                "utf8",
+            );
+
+            const now = new Date().toISOString();
+            const seedIndex = {
+                version: 2,
+                updatedAt: now,
+                workspaces: [
+                    {
+                        path: localWorkspace,
+                        targets: {
+                            gemini: {
+                                version: "2.0.1",
+                                installedAt: now,
+                                updatedAt: now,
+                            },
+                        },
+                    },
+                ],
+                excludedPaths: [],
+            };
+            fs.writeFileSync(indexPath, `${JSON.stringify(seedIndex, null, 2)}\n`, "utf8");
+
+            const result = runCli(["update-all", "--targets", "codex", "--quiet"], {
+                env: { LING_INDEX_PATH: indexPath },
+            });
+            assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+            const indexData = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+            const record = (indexData.workspaces || []).find((item) => item.path === localWorkspace);
+            assert.ok(record, "workspace should remain in index");
+            assert.ok(record.targets && record.targets.codex, "codex target should be refreshed into index");
+        } finally {
+            fs.rmSync(localWorkspace, { recursive: true, force: true });
+        }
+    });
+
+    test("init should respect --no-index on non-temp workspace", () => {
+        const localWorkspace = fs.mkdtempSync(path.join(REPO_ROOT, ".tmp-ling-no-index-"));
+        try {
+            const initResult = runCli(
+                ["init", "--target", "codex", "--path", localWorkspace, "--no-index", "--quiet"],
+                { env: { LING_INDEX_PATH: indexPath } },
+            );
+            assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+            if (!fs.existsSync(indexPath)) {
+                return;
+            }
+
+            const indexData = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+            const hasWorkspace = (indexData.workspaces || []).some((item) => item.path === localWorkspace);
+            assert.ok(!hasWorkspace, "--no-index should skip workspace registration");
+
+            const updateResult = runCli(
+                ["update", "--quiet"],
+                { cwd: localWorkspace, env: { LING_INDEX_PATH: indexPath } },
+            );
+            assert.strictEqual(updateResult.status, 0, updateResult.stderr || updateResult.stdout);
+
+            const indexAfterUpdate = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+            const hasWorkspaceAfterUpdate = (indexAfterUpdate.workspaces || []).some((item) => item.path === localWorkspace);
+            assert.ok(hasWorkspaceAfterUpdate, "local update without --no-index should re-register workspace");
+        } finally {
+            fs.rmSync(localWorkspace, { recursive: true, force: true });
+        }
+    });
+
+    test("init should skip indexing toolkit source-like workspace by package name", () => {
+        const toolkitWorkspace = fs.mkdtempSync(path.join(REPO_ROOT, ".tmp-ling-toolkit-source-"));
+        try {
+            fs.mkdirSync(path.join(toolkitWorkspace, "bin"), { recursive: true });
+            fs.writeFileSync(
+                path.join(toolkitWorkspace, "package.json"),
+                JSON.stringify({ name: "@mison/ling", version: "2.0.1" }, null, 2),
+                "utf8",
+            );
+            fs.writeFileSync(path.join(toolkitWorkspace, "bin", "ling.js"), "#!/usr/bin/env node\n", "utf8");
+
+            const initResult = runCli(
+                ["init", "--target", "gemini", "--path", toolkitWorkspace, "--quiet"],
+                { env: { LING_INDEX_PATH: indexPath } },
+            );
+            assert.strictEqual(initResult.status, 0, initResult.stderr || initResult.stdout);
+
+            if (!fs.existsSync(indexPath)) {
+                return;
+            }
+
+            const indexData = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+            const hasWorkspace = (indexData.workspaces || []).some((item) => item.path === toolkitWorkspace);
+            assert.ok(!hasWorkspace, "toolkit source-like workspace should be excluded from index");
+        } finally {
+            fs.rmSync(toolkitWorkspace, { recursive: true, force: true });
+        }
+    });
+});

package/tests/codex-adapter.test.js

@@ -0,0 +1,132 @@
+const { test, describe, beforeEach, afterEach } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const CodexAdapter = require("../bin/adapters/codex");
+
+describe("CodexAdapter", () => {
+    let workDir;
+    let installSource;
+
+    beforeEach(() => {
+        workDir = fs.mkdtempSync(path.join(os.tmpdir(), "adapter-test-"));
+        installSource = path.join(workDir, "source");
+        fs.mkdirSync(installSource);
+        fs.writeFileSync(path.join(installSource, "file.txt"), "content");
+    });
+
+    afterEach(() => {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    });
+
+    test("install should create .agents as managed codex directory", () => {
+        const adapter = new CodexAdapter(workDir, { quiet: true });
+        adapter.install(installSource);
+
+        const agentsDir = path.join(workDir, ".agents");
+        const legacyDir = path.join(workDir, ".codex");
+        const manifest = path.join(agentsDir, "manifest.json");
+
+        assert.ok(fs.existsSync(agentsDir));
+        assert.ok(!fs.existsSync(legacyDir));
+        assert.ok(fs.existsSync(manifest));
+
+        const manifestJson = JSON.parse(fs.readFileSync(manifest, "utf8"));
+        assert.strictEqual(manifestJson.target, "codex");
+        assert.ok(manifestJson.files["file.txt"]);
+        assert.strictEqual(typeof manifestJson.files["file.txt"].hash, "string");
+        assert.strictEqual(typeof manifestJson.files["file.txt"].source, "string");
+    });
+
+    test("update should migrate legacy .codex directory to .agents", () => {
+        const legacyDir = path.join(workDir, ".codex");
+        fs.mkdirSync(legacyDir, { recursive: true });
+        fs.writeFileSync(path.join(legacyDir, "manifest.json"), JSON.stringify({ version: 2, target: "codex", files: {} }));
+        fs.writeFileSync(path.join(legacyDir, "legacy.txt"), "legacy");
+
+        const updateSource = path.join(workDir, "update-src");
+        fs.mkdirSync(updateSource);
+        fs.writeFileSync(path.join(updateSource, "new.txt"), "new");
+
+        const adapter = new CodexAdapter(workDir, { quiet: true, force: true });
+        adapter.update(updateSource);
+
+        assert.ok(fs.existsSync(path.join(workDir, ".agents")));
+        assert.ok(!fs.existsSync(path.join(workDir, ".codex")));
+        assert.ok(fs.existsSync(path.join(workDir, ".agents", "new.txt")));
+    });
+
+    test("update should detect drift and backup", () => {
+        const options = { quiet: true, force: true };
+        const adapter = new CodexAdapter(workDir, options);
+
+        adapter.install(installSource);
+
+        const managedFile = path.join(workDir, ".agents", "file.txt");
+        fs.writeFileSync(managedFile, "modified content");
+
+        const updateSource = path.join(workDir, "update_src");
+        fs.mkdirSync(updateSource);
+        fs.writeFileSync(path.join(updateSource, "file.txt"), "v2 content");
+        fs.writeFileSync(path.join(updateSource, "new.txt"), "new file");
+
+        adapter.update(updateSource);
+
+        const agentsDir = path.join(workDir, ".agents");
+        const backupBase = path.join(workDir, ".agents-backup");
+
+        assert.strictEqual(fs.readFileSync(path.join(agentsDir, "file.txt"), "utf8"), "v2 content");
+        assert.ok(fs.existsSync(path.join(agentsDir, "new.txt")));
+
+        assert.ok(fs.existsSync(backupBase));
+        const backups = fs.readdirSync(backupBase);
+        assert.strictEqual(backups.length, 1);
+        const latestBackup = path.join(backupBase, backups[0]);
+        assert.ok(fs.existsSync(path.join(latestBackup, "file.txt")));
+        assert.strictEqual(fs.readFileSync(path.join(latestBackup, "file.txt"), "utf8"), "modified content");
+    });
+
+    test("smart overwrite should skip backup when local content already equals incoming content", () => {
+        const options = { quiet: true, force: true };
+        const adapter = new CodexAdapter(workDir, options);
+
+        adapter.install(installSource);
+
+        const managedFile = path.join(workDir, ".agents", "file.txt");
+        fs.writeFileSync(managedFile, "v2 content");
+
+        const updateSource = path.join(workDir, "update_src_same");
+        fs.mkdirSync(updateSource);
+        fs.writeFileSync(path.join(updateSource, "file.txt"), "v2 content");
+
+        adapter.update(updateSource);
+
+        const backupBase = path.join(workDir, ".agents-backup");
+        assert.ok(!fs.existsSync(backupBase), "No backup should be created when file already equals incoming hash");
+    });
+
+    test("update should create full snapshot backup when manifest is invalid", () => {
+        const options = { quiet: true, force: true };
+        const adapter = new CodexAdapter(workDir, options);
+        adapter.install(installSource);
+
+        const managedFile = path.join(workDir, ".agents", "file.txt");
+        fs.writeFileSync(managedFile, "user-modified");
+        fs.writeFileSync(path.join(workDir, ".agents", "manifest.json"), "{invalid-json");
+
+        const updateSource = path.join(workDir, "update_src_invalid_manifest");
+        fs.mkdirSync(updateSource);
+        fs.writeFileSync(path.join(updateSource, "file.txt"), "next-version");
+
+        adapter.update(updateSource);
+
+        const backupBase = path.join(workDir, ".agents-backup");
+        assert.ok(fs.existsSync(backupBase));
+        const backups = fs.readdirSync(backupBase);
+        assert.strictEqual(backups.length, 1);
+        const snapshotFile = path.join(backupBase, backups[0], "full-snapshot", "file.txt");
+        assert.ok(fs.existsSync(snapshotFile));
+        assert.strictEqual(fs.readFileSync(snapshotFile, "utf8"), "user-modified");
+    });
+});