import fs from "node:fs"; import os from "node:os"; import path from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { writeManagedShim, flipCurrentAtomic, initializeInstallStore, payloadPathFor, readInstallManifest, resolveInstallStorePaths, writeInstallManifestAtomic, type InstallManifest, type InstallRecord } from "../install-store.js"; import type { CommandRunner } from "../commands/install.js"; import { compareVersions, detectInstallMode, resolveUpdateRequest, rollbackManagedInstall, updateCommand } from "../commands/update.js"; let root: string; let previousHome: string | undefined; let previousPaperclipHome: string | undefined; function record(payloadPath: string, version: string, channel: "latest" | "canary" | "pinned" = "latest"): InstallRecord { return { source: "npm", version, channel, payloadPath, installedAt: `2026-07-22T00:00:0${version}.000Z` }; } function createPayload(payloadPath: string, version: string): string { const entrypoint = path.join(payloadPath, "node_modules", "paperclipai", "dist", "index.js"); fs.mkdirSync(path.dirname(entrypoint), { recursive: true }); fs.writeFileSync(entrypoint, version); return entrypoint; } beforeEach(() => { root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-update-")); previousHome = process.env.HOME; previousPaperclipHome = process.env.PAPERCLIP_HOME; process.env.HOME = path.join(root, "home"); process.env.PAPERCLIP_HOME = path.join(root, "paperclip"); }); afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); if (previousHome === undefined) delete process.env.HOME; else process.env.HOME = previousHome; if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME; else process.env.PAPERCLIP_HOME = previousPaperclipHome; fs.rmSync(root, { recursive: true, force: true }); process.exitCode = undefined; }); describe("update command", () => { it.each(["npm", "git", "global-npm"] as const)("rejects %s updates on unsupported Node before any update work", async (source) => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const payload = payloadPathFor(paths, "npm", "1.0.0"); const entrypoint = createPayload(payload, "1.0.0"); flipCurrentAtomic(payload, paths); const manifest: InstallManifest = { schemaVersion: 1, ...record(payload, "1.0.0"), source: source === "git" ? "git" : "npm", previous: [] }; writeInstallManifestAtomic(manifest, paths); const runCommand = vi.fn(); const backup = vi.fn(); const restartActiveService = vi.fn(); const nodeVersion = Object.getOwnPropertyDescriptor(process.versions, "node")!; Object.defineProperty(process.versions, "node", { ...nodeVersion, value: "22.22.2" }); try { await expect(updateCommand({ yes: true }, { paths, executablePath: source === "global-npm" ? path.join(root, "lib", "node_modules", "paperclipai", "dist", "index.js") : entrypoint, runCommand, backup, restartActiveService, })).rejects.toThrow("npx paperclipai@latest install --yes"); expect(runCommand).not.toHaveBeenCalled(); expect(backup).not.toHaveBeenCalled(); expect(restartActiveService).not.toHaveBeenCalled(); expect(readInstallManifest(paths)).toEqual(manifest); expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(payload)); } finally { Object.defineProperty(process.versions, "node", nodeVersion); } }); it("keeps update checks, dry runs, and rollback available on unsupported Node", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldPayload = payloadPathFor(paths, "npm", "1.0.0"); createPayload(oldPayload, "1.0.0"); const payload = payloadPathFor(paths, "npm", "2.0.0"); const executablePath = createPayload(payload, "2.0.0"); flipCurrentAtomic(payload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(payload, "2.0.0"), previous: [record(oldPayload, "1.0.0")] }, paths); const runCommand = vi.fn(async () => ({ stdout: '\"3.0.0\"\n', stderr: "" })); const restartActiveService = vi.fn(async () => false); const nodeVersion = Object.getOwnPropertyDescriptor(process.versions, "node")!; Object.defineProperty(process.versions, "node", { ...nodeVersion, value: "22.22.2" }); try { await updateCommand({ check: true }, { paths, executablePath, runCommand }); await updateCommand({ dryRun: true }, { paths, executablePath, runCommand }); expect(readInstallManifest(paths)?.version).toBe("2.0.0"); await updateCommand({ rollback: true }, { paths, executablePath, restartActiveService }); expect(readInstallManifest(paths)?.version).toBe("1.0.0"); expect(restartActiveService).toHaveBeenCalledWith("1.0.0"); } finally { Object.defineProperty(process.versions, "node", nodeVersion); } }); it("orders SemVer prerelease identifiers numerically", () => { expect(compareVersions("1.0.0-canary.10", "1.0.0-canary.2")).toBeGreaterThan(0); expect(compareVersions("1.0.0-1", "1.0.0-alpha")).toBeLessThan(0); expect(compareVersions("1.0.0-alpha", "1.0.0-alpha.1")).toBeLessThan(0); }); it("detects managed, global npm, npx, and source modes", () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const payload = payloadPathFor(paths, "npm", "1.0.0"); const entrypoint = createPayload(payload, "1.0.0"); flipCurrentAtomic(payload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(payload, "1.0.0"), previous: [] }, paths); expect(detectInstallMode(entrypoint, paths)).toBe("managed"); expect(detectInstallMode(path.join(root, "lib", "node_modules", "paperclipai", "dist", "index.js"), paths)).toBe("global-npm"); expect(detectInstallMode(path.join(root, ".npm", "_npx", "abc", "node_modules", "paperclipai", "dist", "index.js"), paths)).toBe("npx"); const source = path.join(root, "source"); fs.mkdirSync(path.join(source, ".git"), { recursive: true }); expect(detectInstallMode(path.join(source, "cli", "src", "index.ts"), paths)).toBe("source"); }); it("resolves channels and keeps pinned installs pinned by default", () => { const manifest = { channel: "pinned", version: "1.2.3" } as InstallManifest; expect(resolveUpdateRequest(manifest, {})).toEqual({ spec: "1.2.3", channel: "pinned", explicit: false }); expect(resolveUpdateRequest(manifest, { latest: true })).toEqual({ spec: "latest", channel: "latest", explicit: true }); expect(() => resolveUpdateRequest(manifest, { latest: true, canary: true })).toThrow("only one"); }); it("re-resolves a moving git branch and activates the new SHA payload", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldSha = "1".repeat(40); const newSha = "2".repeat(40); const oldPayload = payloadPathFor(paths, "git", oldSha.slice(0, 12)); const executable = createPayload(oldPayload, "0.3.1"); fs.writeFileSync(path.join(oldPayload, "node_modules", "paperclipai", "package.json"), JSON.stringify({ version: "0.3.1" })); const newPayload = payloadPathFor(paths, "git", newSha.slice(0, 12)); createPayload(newPayload, "0.3.1"); fs.writeFileSync(path.join(newPayload, "node_modules", "paperclipai", "package.json"), JSON.stringify({ version: "0.3.1" })); flipCurrentAtomic(oldPayload, paths); writeInstallManifestAtomic({ schemaVersion: 1, source: "git", version: "0.3.1", channel: "pinned", repo: "paperclipai/paperclip", ref: "master", sha: oldSha, payloadPath: oldPayload, installedAt: "2026-07-22T00:00:00.000Z", previous: [] }, paths); writeManagedShim(paths); // Simulate a launcher generated before child-runtime PATH pinning existed. fs.writeFileSync(paths.shimPath, fs.readFileSync(paths.shimPath, "utf8").replace(/^export PATH=.*\n/m, "")); const backup = vi.fn(async () => undefined); const confirm = vi.fn(async () => true); const restartActiveService = vi.fn(async () => true); const runCommand = vi.fn(async (file: string) => file === "curl" ? { stdout: JSON.stringify({ sha: newSha }), stderr: "" } : { stdout: "0.3.1\n", stderr: "" }); await updateCommand({}, { paths, executablePath: executable, runCommand, backup, confirm, restartActiveService, hasInstanceData: () => true, now: () => new Date("2026-07-22T12:00:00Z") }); expect(confirm).toHaveBeenCalledWith(expect.stringContaining(`commit ${newSha.slice(0, 12)}`)); expect(fs.readFileSync(paths.shimPath, "utf8")).toContain(`export PATH='${path.dirname(process.execPath)}'`); expect(backup).toHaveBeenCalledOnce(); expect(restartActiveService).toHaveBeenCalledWith("0.3.1"); expect(readInstallManifest(paths)?.sha).toBe(newSha); expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(newPayload)); }); it("reports SHA git installs as pinned without resolving again", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const sha = "3".repeat(40); const payload = payloadPathFor(paths, "git", sha.slice(0, 12)); const executable = createPayload(payload, "0.3.1"); flipCurrentAtomic(payload, paths); writeInstallManifestAtomic({ schemaVersion: 1, source: "git", version: "0.3.1", channel: "pinned", repo: "paperclipai/paperclip", ref: sha.slice(0, 12), sha, payloadPath: payload, installedAt: "2026-07-22T00:00:00.000Z", previous: [] }, paths); const runCommand = vi.fn(async () => ({ stdout: "", stderr: "" })); await updateCommand({}, { paths, executablePath: executable, runCommand }); expect(runCommand).not.toHaveBeenCalled(); }); it("requires explicit confirmation before downgrading", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const payload = payloadPathFor(paths, "npm", "2.0.0"); const entrypoint = createPayload(payload, "2.0.0"); flipCurrentAtomic(payload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(payload, "2.0.0"), previous: [] }, paths); const runCommand = vi.fn(async () => ({ stdout: '"1.0.0"\n', stderr: "" })); await expect(updateCommand({ version: "1.0.0", dryRun: true }, { paths, executablePath: entrypoint, runCommand, confirm: async () => false })).rejects.toThrow("Downgrade cancelled"); }); it("requires explicit confirmation before a global npm downgrade", async () => { const paths = resolveInstallStorePaths(); const executable = path.join(root, "lib", "node_modules", "paperclipai", "dist", "index.js"); const runCommand = vi.fn(async () => ({ stdout: '"0.2.0"\n', stderr: "" })); await expect(updateCommand({ version: "0.2.0" }, { paths, executablePath: executable, runCommand, confirm: async () => false })).rejects.toThrow("Downgrade cancelled"); expect(runCommand).toHaveBeenCalledTimes(1); }); it("isolates global npm updates from hostile registry configuration", async () => { const paths = resolveInstallStorePaths(); const executable = path.join(root, "lib", "node_modules", "paperclipai", "dist", "index.js"); vi.stubEnv("NPM_CONFIG_REGISTRY", "http://attacker-registry.invalid"); fs.mkdirSync(process.env.HOME!, { recursive: true }); fs.writeFileSync(path.join(process.env.HOME!, ".npmrc"), "registry=http://attacker-registry.invalid\n"); const runCommand = vi.fn(async (_file, args, commandOptions) => { if (args[0] === "view") return { stdout: '"2.0.0"\n', stderr: "" }; expect(args).toContain("--registry=https://registry.npmjs.org"); expect(args).toContain("--@paperclipai:registry=https://registry.npmjs.org"); expect(commandOptions?.env?.NPM_CONFIG_REGISTRY).toBe("https://registry.npmjs.org"); expect(commandOptions?.env?.npm_config_registry).toBe("https://registry.npmjs.org"); expect(commandOptions?.env?.NPM_CONFIG_USERCONFIG).toBe(commandOptions?.env?.npm_config_userconfig); expect(fs.readFileSync(commandOptions!.env!.NPM_CONFIG_USERCONFIG!, "utf8")).toContain("registry=https://registry.npmjs.org"); return { stdout: "", stderr: "" }; }); await updateCommand({}, { paths, executablePath: executable, runCommand }); expect(runCommand).toHaveBeenCalledTimes(2); }); it("backs up, installs side-by-side, flips, and rolls back instantly", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldPayload = payloadPathFor(paths, "npm", "1.0.0"); const executable = createPayload(oldPayload, "1.0.0"); flipCurrentAtomic(oldPayload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(oldPayload, "1.0.0"), previous: [] }, paths); writeManagedShim(paths); // Simulate a launcher generated before child-runtime PATH pinning existed. fs.writeFileSync(paths.shimPath, fs.readFileSync(paths.shimPath, "utf8").replace(/^export PATH=.*\n/m, "")); const backup = vi.fn(async () => undefined); const restartActiveService = vi.fn(async () => true); const runCommand = vi.fn(async (file: string, args: string[]) => { if (args[0] === "view") return { stdout: '"2.0.0"\n', stderr: "" }; if (file === "npm" && args[0] === "install") { const prefix = args[args.indexOf("--prefix") + 1]; createPayload(prefix, "2.0.0"); return { stdout: "", stderr: "" }; } return { stdout: "2.0.0\n", stderr: "" }; }); await updateCommand({}, { paths, executablePath: executable, runCommand, backup, restartActiveService, hasInstanceData: () => true, now: () => new Date("2026-07-22T12:00:00Z") }); expect(fs.readFileSync(paths.shimPath, "utf8")).toContain(`export PATH='${path.dirname(process.execPath)}'`); expect(backup).toHaveBeenCalledOnce(); expect(restartActiveService).toHaveBeenCalledWith("2.0.0"); expect(readInstallManifest(paths)?.version).toBe("2.0.0"); expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(payloadPathFor(paths, "npm", "2.0.0"))); const rolledBack = rollbackManagedInstall(paths); expect(rolledBack.version).toBe("1.0.0"); expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(oldPayload)); }); it("explains how to recover when the pre-update database is unreachable", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldPayload = payloadPathFor(paths, "npm", "1.0.0"); const executable = createPayload(oldPayload, "1.0.0"); flipCurrentAtomic(oldPayload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(oldPayload, "1.0.0"), previous: [] }, paths); const backupError = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:54329"), { code: "ECONNREFUSED" }); const backup = vi.fn(async () => { throw backupError; }); const runCommand = vi.fn(async () => ({ stdout: '"2.0.0"\n', stderr: "" })); await expect(updateCommand({}, { paths, executablePath: executable, runCommand, backup, hasInstanceData: () => true })).rejects.toThrow( "Start the service with `paperclipai service start` and retry, or skip the backup with `paperclipai update --no-backup`.", ); expect(backup).toHaveBeenCalledOnce(); expect(readInstallManifest(paths)?.version).toBe("1.0.0"); }); it("skips the pre-update backup when there is no onboarded instance data", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldPayload = payloadPathFor(paths, "npm", "1.0.0"); const executable = createPayload(oldPayload, "1.0.0"); flipCurrentAtomic(oldPayload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(oldPayload, "1.0.0"), previous: [] }, paths); const backup = vi.fn(async () => undefined); const log = vi.spyOn(console, "log").mockImplementation(() => undefined); const runCommand = vi.fn(async (file: string, args: string[]) => { if (args[0] === "view") return { stdout: '"2.0.0"\n', stderr: "" }; if (file === "npm" && args[0] === "install") { createPayload(args[args.indexOf("--prefix") + 1], "2.0.0"); return { stdout: "", stderr: "" }; } return { stdout: "2.0.0\n", stderr: "" }; }); await updateCommand({}, { paths, executablePath: executable, runCommand, backup, restartActiveService: async () => false, hasInstanceData: () => false }); expect(backup).not.toHaveBeenCalled(); expect(log).toHaveBeenCalledWith(expect.stringContaining("has not been onboarded and has no data to back up")); expect(readInstallManifest(paths)?.version).toBe("2.0.0"); }); it("does not inherit a managed pin for global npm updates", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const managedPayload = payloadPathFor(paths, "npm", "1.2.3"); createPayload(managedPayload, "1.2.3"); writeInstallManifestAtomic({ schemaVersion: 1, ...record(managedPayload, "1.2.3"), channel: "pinned", previous: [] }, paths); const executable = path.join(root, "lib", "node_modules", "paperclipai", "dist", "index.js"); const runCommand = vi.fn(async (_file: string, args: string[]) => args[0] === "view" ? { stdout: '"2.0.0"\n', stderr: "" } : { stdout: "", stderr: "" }); await updateCommand({ dryRun: true }, { paths, executablePath: executable, runCommand }); expect(runCommand).toHaveBeenCalledWith("npm", expect.arrayContaining(["view", "paperclipai@latest"]), expect.anything()); }); it("rolls back the active payload when restart validation fails", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldPayload = payloadPathFor(paths, "npm", "1.0.0"); const executable = createPayload(oldPayload, "1.0.0"); flipCurrentAtomic(oldPayload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(oldPayload, "1.0.0"), previous: [] }, paths); const runCommand = vi.fn(async (file: string, args: string[]) => { if (args[0] === "view") return { stdout: '"2.0.0"\n', stderr: "" }; if (file === "npm" && args[0] === "install") { createPayload(args[args.indexOf("--prefix") + 1], "2.0.0"); return { stdout: "", stderr: "" }; } return { stdout: "2.0.0\n", stderr: "" }; }); const restartActiveService = vi.fn(async (version: string) => { if (version === "2.0.0") throw new Error("health timeout"); return true; }); await expect(updateCommand({}, { paths, executablePath: executable, runCommand, backup: async () => undefined, restartActiveService })).rejects.toThrow("rolled back to 1.0.0"); expect(readInstallManifest(paths)?.version).toBe("1.0.0"); expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(oldPayload)); expect(restartActiveService).toHaveBeenLastCalledWith("1.0.0"); }); it("surfaces a failure to restart the rolled-back payload", async () => { const paths = resolveInstallStorePaths(); initializeInstallStore(paths); const oldPayload = payloadPathFor(paths, "npm", "1.0.0"); const executable = createPayload(oldPayload, "1.0.0"); flipCurrentAtomic(oldPayload, paths); writeInstallManifestAtomic({ schemaVersion: 1, ...record(oldPayload, "1.0.0"), previous: [] }, paths); const runCommand = vi.fn(async (file: string, args: string[]) => { if (args[0] === "view") return { stdout: '"2.0.0"\n', stderr: "" }; if (file === "npm" && args[0] === "install") { createPayload(args[args.indexOf("--prefix") + 1], "2.0.0"); return { stdout: "", stderr: "" }; } return { stdout: "2.0.0\n", stderr: "" }; }); const restartActiveService = vi.fn(async (version: string) => { throw new Error(version === "2.0.0" ? "health timeout" : "rollback restart failed"); }); await expect(updateCommand({}, { paths, executablePath: executable, runCommand, backup: async () => undefined, restartActiveService, })).rejects.toThrow("rolled-back service also failed to restart"); expect(readInstallManifest(paths)?.version).toBe("1.0.0"); expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(oldPayload)); expect(restartActiveService).toHaveBeenNthCalledWith(1, "2.0.0"); expect(restartActiveService).toHaveBeenNthCalledWith(2, "1.0.0"); }); });