diff --git a/src/cli.ts b/src/cli.ts index b9e512e3d8..b802d3e7e5 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -57,7 +57,7 @@ import { } from "./cli/remove-plan.js"; import { portFlagSuffix } from "./cli/ready-hint.js"; import { embeddingStatusLabel } from "./cli/embedding-status.js"; -import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive } from "./cli/engine-install.js"; +import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive, installIiiZip } from "./cli/engine-install.js"; import { runtimeConfigPath, redactCredentialUrls, @@ -959,12 +959,30 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null } if (IS_WINDOWS || isZipAsset) { - p.log.info( - `Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n` + + const binDir = agentmemoryBinDir(); + const binPath = privateIiiPath(); + const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`; + const spinner = p.spinner(); + spinner.start(label); + const outcome = await installIiiZip({ + releaseUrl, + version: IIPINNED_VERSION, + asset: asset ?? "", + binDir, + binPath, + }); + if (outcome.ok) { + spinner.stop(`${label} ${pc.green("✓")}`); + iiiProbeScan?.delete(binPath); + return { ok: true, binPath }; + } + spinner.stop(`${label} ${pc.red("✗")}`); + p.log.warn( + `iii-engine auto-install failed: ${outcome.detail.slice(0, 300)}\n` + + `Install it manually, then re-run agentmemory:\n` + ` 1. Download ${releaseUrl}\n` + ` Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n` + - ` 2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` + - `Install the pinned iii binary from ${releaseUrl}`, + ` 2. Extract iii.exe into ${binDir}`, ); return { ok: false, binPath: null }; } @@ -1483,7 +1501,7 @@ function installInstructions(): string[] { ` 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}`, ` 2. Download iii-x86_64-pc-windows-msvc.zip (or iii-aarch64-pc-windows-msvc.zip on ARM)`, verify, - " 3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)", + " 3. Extract iii.exe to %USERPROFILE%\\.agentmemory\\bin\\iii.exe (or add to PATH)", " 4. Re-run: npx @agentmemory/agentmemory", "", "Or skip the engine entirely (standalone MCP): npx @agentmemory/agentmemory mcp", diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts index a9979a5ee6..83ee9ff434 100644 --- a/src/cli/engine-install.ts +++ b/src/cli/engine-install.ts @@ -1,7 +1,7 @@ -import { spawnSync } from "node:child_process"; -import { createHash } from "node:crypto"; -import { readFileSync, rmSync } from "node:fs"; -import { join } from "node:path"; +import { spawn, spawnSync } from "node:child_process"; +import { createHash, randomBytes } from "node:crypto"; +import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"; +import { basename, join } from "node:path"; export const III_INSTALL_CONNECT_TIMEOUT_S = 15; export const III_INSTALL_MAX_TIME_S = 300; @@ -140,3 +140,240 @@ export function installIiiArchive(opts: { } return { ok: true }; } + +export type ZipRunResult = { + status: number | null; + stdout?: string | null; + stderr?: string | null; + error?: Error & { code?: string }; + signal?: NodeJS.Signals | null; +}; + +export type ZipCommandRunner = (command: string, args: string[]) => ZipRunResult | Promise; + +export type ZipDownloader = (url: string, dest: string) => Promise; + +export function iiiZipArchivePath(binDir: string): string { + return join(binDir, `.iii-download-${process.pid}-${randomBytes(4).toString("hex")}.zip`); +} + +function removeQuietly(path: string): void { + try { + rmSync(path, { force: true, recursive: true }); + } catch {} +} + +export const STALE_INSTALL_FILE_MS = 15 * 60 * 1000; + +export function removeStaleInstallFiles(binDir: string, now: number = Date.now()): string[] { + const removed: string[] = []; + let entries: string[]; + try { + entries = readdirSync(binDir); + } catch { + return removed; + } + for (const name of entries) { + if (!name.startsWith(".iii-download-") && !name.startsWith(".iii-staging-")) continue; + const path = join(binDir, name); + try { + if (now - statSync(path).mtimeMs < STALE_INSTALL_FILE_MS) continue; + } catch { + continue; + } + removeQuietly(path); + if (!existsSync(path)) removed.push(name); + } + return removed; +} + +const PROXY_ENV_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"]; + +export function proxyConfigured(env: NodeJS.ProcessEnv): boolean { + return PROXY_ENV_KEYS.some((key) => Boolean(env[key]?.trim())); +} + +export function windowsCurlDownloadCommand( + url: string, + dest: string, + env: NodeJS.ProcessEnv = process.env, +): { command: string; args: string[] } { + const systemRoot = env["SystemRoot"] || env["SYSTEMROOT"] || "C:\\Windows"; + return { + command: join(systemRoot, "System32", "curl.exe"), + args: [ + "-fsSL", + "--connect-timeout", + String(III_INSTALL_CONNECT_TIMEOUT_S), + "--max-time", + String(III_INSTALL_MAX_TIME_S), + "-o", + dest, + url, + ], + }; +} + +export function powershellLiteral(value: string): string { + return `'${value.replace(/'/g, "''")}'`; +} + +export function windowsZipExtractCommands( + archive: string, + binDir: string, + env: NodeJS.ProcessEnv = process.env, +): { command: string; args: string[] }[] { + const systemRoot = env["SystemRoot"] || env["SYSTEMROOT"] || "C:\\Windows"; + const system32 = join(systemRoot, "System32"); + return [ + { command: join(system32, "tar.exe"), args: ["-xf", archive, "-C", binDir] }, + { + command: join(system32, "WindowsPowerShell", "v1.0", "powershell.exe"), + args: [ + "-NoProfile", + "-NonInteractive", + "-Command", + `Expand-Archive -LiteralPath ${powershellLiteral(archive)} -DestinationPath ${powershellLiteral(binDir)} -Force`, + ], + }, + ]; +} + +export async function downloadToFile( + url: string, + dest: string, + env: NodeJS.ProcessEnv = process.env, + run: ZipCommandRunner = runInstallCommand, +): Promise { + if (proxyConfigured(env)) { + const step = windowsCurlDownloadCommand(url, dest, env); + const result = await run(step.command, step.args); + if (result.status !== 0) throw new Error(describeInstallFailure(result)); + return; + } + const res = await fetch(url, { + redirect: "follow", + signal: AbortSignal.timeout(III_INSTALL_MAX_TIME_S * 1000), + }); + if (!res.ok) throw new Error(`download failed with HTTP ${res.status} ${res.statusText}`.trim()); + writeFileSync(dest, Buffer.from(await res.arrayBuffer())); +} + +export function runInstallCommand(command: string, args: string[]): Promise { + return new Promise((done) => { + let stdout = ""; + let stderr = ""; + let timedOut = false; + const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true, shell: false }); + const killOnExit = () => { + try { + child.kill(); + } catch {} + }; + process.once("exit", killOnExit); + const timer = setTimeout(() => { + timedOut = true; + child.kill(); + }, III_INSTALL_SPAWN_TIMEOUT_MS); + child.stdout?.on("data", (chunk) => { stdout += chunk; }); + child.stderr?.on("data", (chunk) => { stderr += chunk; }); + let spawnError: (Error & { code?: string }) | undefined; + child.on("error", (error: Error & { code?: string }) => { + spawnError = error; + if (child.pid !== undefined) return; + clearTimeout(timer); + process.off("exit", killOnExit); + done({ status: null, stdout, stderr, error }); + }); + child.on("close", (status, signal) => { + clearTimeout(timer); + process.off("exit", killOnExit); + if (spawnError && status === null && !timedOut) { + done({ status: null, stdout, stderr, signal, error: spawnError }); + return; + } + if (timedOut) { + done({ status: null, stdout, stderr, signal, error: Object.assign(new Error("timed out"), { code: "ETIMEDOUT" }) }); + return; + } + done({ status, stdout, stderr, signal }); + }); + }); +} + +export async function installIiiZip(opts: { + releaseUrl: string; + version: string; + asset: string; + binDir: string; + binPath: string; + env?: NodeJS.ProcessEnv; + checksums?: ChecksumTable; + download?: ZipDownloader; + run?: ZipCommandRunner; +}): Promise { + const expected = expectedIiiSha256(opts.version, opts.asset, opts.checksums); + if (!expected) { + return { + ok: false, + reason: "no-checksum", + detail: `no pinned SHA-256 for ${opts.asset} in iii v${opts.version}, so the download cannot be verified`, + }; + } + const run = opts.run ?? runInstallCommand; + const download = opts.download ?? ((url: string, dest: string) => downloadToFile(url, dest, opts.env ?? process.env, run)); + const archive = iiiZipArchivePath(opts.binDir); + + try { + mkdirSync(opts.binDir, { recursive: true }); + removeStaleInstallFiles(opts.binDir); + await download(opts.releaseUrl, archive); + } catch (err) { + removeQuietly(archive); + return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) }; + } + + let actual: string; + try { + actual = sha256File(archive); + } catch (err) { + removeQuietly(archive); + return { ok: false, reason: "download", detail: err instanceof Error ? err.message : String(err) }; + } + if (actual !== expected) { + removeQuietly(archive); + return { + ok: false, + reason: "checksum", + detail: `SHA-256 mismatch for ${opts.asset}: expected ${expected}, got ${actual}. The download was deleted and nothing was installed`, + }; + } + + const staging = join(opts.binDir, `.iii-staging-${process.pid}-${randomBytes(4).toString("hex")}`); + const staged = join(staging, basename(opts.binPath)); + const failures: string[] = []; + try { + for (const step of windowsZipExtractCommands(archive, staging, opts.env)) { + removeQuietly(staging); + mkdirSync(staging, { recursive: true }); + const result = await run(step.command, step.args); + if (result.status === 0 && existsSync(staged)) { + try { + renameSync(staged, opts.binPath); + return { ok: true }; + } catch (err) { + failures.push(`could not move ${staged} to ${opts.binPath}: ${err instanceof Error ? err.message : String(err)}`); + break; + } + } + failures.push(`${step.command}: ${result.status === 0 ? `finished but ${basename(opts.binPath)} is missing from the archive` : describeInstallFailure(result)}`); + } + return { ok: false, reason: "extract", detail: failures.join("; ") }; + } catch (err) { + failures.push(err instanceof Error ? err.message : String(err)); + return { ok: false, reason: "extract", detail: failures.join("; ") }; + } finally { + removeQuietly(staging); + removeQuietly(archive); + } +} diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts index 0186a288cc..d7a065f5a2 100644 --- a/test/engine-install.test.ts +++ b/test/engine-install.test.ts @@ -13,6 +13,15 @@ import { iiiManualInstallCommand, installIiiArchive, sha256File, + downloadToFile, + iiiZipArchivePath, + installIiiZip, + powershellLiteral, + proxyConfigured, + removeStaleInstallFiles, + runInstallCommand, + STALE_INSTALL_FILE_MS, + windowsZipExtractCommands, } from "../src/cli/engine-install.js"; import { III_PINNED_VERSION } from "../src/version.js"; @@ -214,3 +223,236 @@ describe("iii engine auto-installer", () => { expect(existsSync(binPath)).toBe(true); }); }); + +describe("iii engine Windows zip installer", () => { + const ZIP_ASSET = "iii-x86_64-pc-windows-msvc.zip"; + const ZIP_BYTES = Buffer.from("fake windows iii zip"); + + function leftoverArchives(binDir: string): string[] { + return existsSync(binDir) ? readdirSync(binDir).filter((name) => name.startsWith(".iii-download") || name.startsWith(".iii-staging")) : []; + } + + function extractDest(args: string[]): string { + if (args[0] === "-xf") return args[3]; + const match = /-DestinationPath '((?:[^']|'')*)'/.exec(args[3] ?? ""); + return (match?.[1] ?? "").replace(/''/g, "'"); + } + + function zipChecksums(bytes: Buffer = ZIP_BYTES) { + const dir = sandbox(); + const file = join(dir, "probe.zip"); + writeFileSync(file, bytes); + return { "9.9.9": { [ZIP_ASSET]: sha256File(file) } }; + } + + function zipOpts(binDir: string, extra: Record = {}) { + return { + releaseUrl: "https://example.invalid/iii.zip", + version: "9.9.9", + asset: ZIP_ASSET, + binDir, + binPath: join(binDir, "iii.exe"), + env: { SystemRoot: "C:\\Windows" }, + checksums: zipChecksums(), + download: async (_url: string, dest: string) => writeFileSync(dest, ZIP_BYTES), + ...extra, + }; + } + + it("extracts with System32 tar.exe first and PowerShell Expand-Archive second, without a shell", () => { + const steps = windowsZipExtractCommands("C:\\a\\.iii-download.zip", "C:\\a", { SystemRoot: "C:\\Windows" }); + expect(steps).toHaveLength(2); + expect(steps[0].command).toMatch(/System32[\\/]tar\.exe$/); + expect(steps[0].args).toEqual(["-xf", "C:\\a\\.iii-download.zip", "-C", "C:\\a"]); + expect(steps[1].command).toMatch(/WindowsPowerShell[\\/]v1\.0[\\/]powershell\.exe$/); + expect(steps[1].args.slice(0, 3)).toEqual(["-NoProfile", "-NonInteractive", "-Command"]); + expect(steps[1].args[3]).toContain("Expand-Archive -LiteralPath 'C:\\a\\.iii-download.zip'"); + }); + + it("quotes PowerShell paths so a quote in the profile path cannot end the string", () => { + expect(powershellLiteral("C:\\Users\\o'brien")).toBe("'C:\\Users\\o''brien'"); + }); + + it("installs when the download matches the pinned SHA-256 and tar.exe extracts iii.exe", async () => { + const binDir = join(sandbox(), "bin"); + const calls: string[] = []; + const outcome = await installIiiZip(zipOpts(binDir, { + run: (command: string, args: string[]) => { + calls.push(command); + writeFileSync(join(extractDest(args), "iii.exe"), "bin"); + return { status: 0 }; + }, + })); + expect(outcome).toEqual({ ok: true }); + expect(calls).toHaveLength(1); + expect(calls[0]).toMatch(/tar\.exe$/); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("falls back to Expand-Archive when tar.exe fails", async () => { + const binDir = join(sandbox(), "bin"); + const calls: string[] = []; + const outcome = await installIiiZip(zipOpts(binDir, { + run: (command: string, args: string[]) => { + calls.push(command); + if (command.endsWith("tar.exe")) return { status: 1, stderr: "tar: unsupported" }; + writeFileSync(join(extractDest(args), "iii.exe"), "bin"); + return { status: 0 }; + }, + })); + expect(outcome).toEqual({ ok: true }); + expect(calls.map((c) => c.split(/[\\/]/).pop())).toEqual(["tar.exe", "powershell.exe"]); + }); + + it("never extracts a download whose SHA-256 does not match", async () => { + const binDir = join(sandbox(), "bin"); + let ran = false; + const outcome = await installIiiZip(zipOpts(binDir, { + download: async (_url: string, dest: string) => writeFileSync(dest, Buffer.from("tampered")), + run: () => { + ran = true; + return { status: 0 }; + }, + })); + expect(outcome.ok).toBe(false); + expect(outcome.ok === false && outcome.reason).toBe("checksum"); + expect(ran).toBe(false); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("downloads nothing for an asset without a pinned SHA-256", async () => { + const binDir = join(sandbox(), "bin"); + let downloaded = false; + const outcome = await installIiiZip(zipOpts(binDir, { + checksums: { "9.9.9": {} }, + download: async () => { + downloaded = true; + }, + })); + expect(outcome.ok === false && outcome.reason).toBe("no-checksum"); + expect(downloaded).toBe(false); + }); + + it("reports an extract failure when neither extractor produces iii.exe", async () => { + const binDir = join(sandbox(), "bin"); + const outcome = await installIiiZip(zipOpts(binDir, { run: () => ({ status: 0 }) })); + expect(outcome.ok === false && outcome.reason).toBe("extract"); + expect(outcome.ok === false && outcome.detail).toContain("iii.exe is missing"); + }); + + it("extracts into a staging directory and keeps a working iii.exe when extraction fails", async () => { + const binDir = join(sandbox(), "bin"); + mkdirSync(binDir, { recursive: true }); + writeFileSync(join(binDir, "iii.exe"), "working"); + const dests: string[] = []; + const outcome = await installIiiZip(zipOpts(binDir, { + run: (_command: string, args: string[]) => { + dests.push(extractDest(args)); + writeFileSync(join(extractDest(args), "iii.exe"), "partial"); + return { status: 1, stderr: "disk full" }; + }, + })); + expect(outcome.ok === false && outcome.reason).toBe("extract"); + expect(dests.every((dest) => dest !== binDir && dest.includes(".iii-staging-"))).toBe(true); + expect(readFileSync(join(binDir, "iii.exe"), "utf-8")).toBe("working"); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("replaces iii.exe only after the staged copy exists", async () => { + const binDir = join(sandbox(), "bin"); + mkdirSync(binDir, { recursive: true }); + writeFileSync(join(binDir, "iii.exe"), "old"); + const outcome = await installIiiZip(zipOpts(binDir, { + run: (_command: string, args: string[]) => { + writeFileSync(join(extractDest(args), "iii.exe"), "new"); + return { status: 0 }; + }, + })); + expect(outcome).toEqual({ ok: true }); + expect(readFileSync(join(binDir, "iii.exe"), "utf-8")).toBe("new"); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("runs install commands without blocking the event loop, so Ctrl+C handlers can still run", async () => { + let timerFired = false; + setTimeout(() => { timerFired = true; }, 20); + const pending = runInstallCommand(process.execPath, ["-e", "setTimeout(() => process.stdout.write('done'), 300)"]); + await new Promise((resolve) => setTimeout(resolve, 100)); + expect(timerFired).toBe(true); + const result = await pending; + expect(result.status).toBe(0); + expect(result.stdout).toBe("done"); + }); + + it("returns an extract failure instead of throwing when an extractor throws", async () => { + const binDir = join(sandbox(), "bin"); + const outcome = await installIiiZip(zipOpts(binDir, { + run: () => { + throw new Error("EPERM: staging denied"); + }, + })); + expect(outcome.ok === false && outcome.reason).toBe("extract"); + expect(outcome.ok === false && outcome.detail).toContain("EPERM: staging denied"); + expect(leftoverArchives(binDir)).toEqual([]); + }); + + it("reports a missing executable without waiting for a close event", async () => { + const result = await runInstallCommand(join(sandbox(), "no-such-tool.exe"), []); + expect(result.status).toBeNull(); + expect(result.error?.code).toBe("ENOENT"); + }); + + it("kills a running install command when the CLI exits", async () => { + const before = process.listenerCount("exit"); + const pending = runInstallCommand(process.execPath, ["-e", "setTimeout(() => {}, 5000)"]); + expect(process.listenerCount("exit")).toBe(before + 1); + process.listeners("exit").at(-1)?.call(process, 0); + const result = await pending; + expect(result.status === 0).toBe(false); + expect(process.listenerCount("exit")).toBe(before); + }); + + it("removes stale archives and staging folders from earlier failed installs", () => { + const binDir = join(sandbox(), "bin"); + mkdirSync(join(binDir, ".iii-staging-1-old"), { recursive: true }); + writeFileSync(join(binDir, ".iii-download-1-old.zip"), "x"); + writeFileSync(join(binDir, ".iii-download-2-fresh.zip"), "x"); + writeFileSync(join(binDir, "iii.exe"), "keep"); + const later = Date.now() + STALE_INSTALL_FILE_MS + 1000; + const freshNow = Date.now(); + const removedLater = removeStaleInstallFiles(binDir, later); + expect(removedLater.sort()).toEqual([".iii-download-1-old.zip", ".iii-download-2-fresh.zip", ".iii-staging-1-old"]); + expect(existsSync(join(binDir, "iii.exe"))).toBe(true); + writeFileSync(join(binDir, ".iii-download-3-new.zip"), "x"); + expect(removeStaleInstallFiles(binDir, freshNow)).toEqual([]); + expect(existsSync(join(binDir, ".iii-download-3-new.zip"))).toBe(true); + }); + + it("gives every install its own archive file so concurrent starts cannot clobber each other", () => { + const a = iiiZipArchivePath("C:\\bin"); + const b = iiiZipArchivePath("C:\\bin"); + expect(a).not.toBe(b); + expect(a).toContain(`.iii-download-${process.pid}-`); + expect(a.endsWith(".zip")).toBe(true); + }); + + it("downloads through System32 curl.exe when a proxy is configured", async () => { + expect(proxyConfigured({})).toBe(false); + expect(proxyConfigured({ HTTPS_PROXY: "http://proxy:3128" })).toBe(true); + expect(proxyConfigured({ http_proxy: " " })).toBe(false); + const calls: { command: string; args: string[] }[] = []; + await downloadToFile("https://example.invalid/iii.zip", "C:\\bin\\a.zip", { SystemRoot: "C:\\Windows", HTTPS_PROXY: "http://proxy:3128" }, (command, args) => { + calls.push({ command, args }); + return { status: 0 }; + }); + expect(calls).toHaveLength(1); + expect(calls[0].command).toMatch(/System32[\\/]curl\.exe$/); + expect(calls[0].args).toEqual(expect.arrayContaining(["-o", "C:\\bin\\a.zip", "https://example.invalid/iii.zip", "--max-time"])); + await expect(downloadToFile("https://example.invalid/iii.zip", "C:\\bin\\a.zip", { HTTPS_PROXY: "http://proxy:3128" }, () => ({ status: 22, stderr: "curl: (22) 407" }))).rejects.toThrow("407"); + }); + + it("pins a SHA-256 for both Windows assets of the pinned release", () => { + expect(expectedIiiSha256(III_PINNED_VERSION, "iii-x86_64-pc-windows-msvc.zip")).toMatch(/^[0-9a-f]{64}$/); + expect(expectedIiiSha256(III_PINNED_VERSION, "iii-aarch64-pc-windows-msvc.zip")).toMatch(/^[0-9a-f]{64}$/); + }); +});