Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): an update never replaces the CLI's files while a hyperframes command is running (#4637)
Miguel Ángelf39b179030f8
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.tsindex 0635ec1366..9d2541cd70 100644--- a/packages/cli/src/cli.ts+++ b/packages/cli/src/cli.ts@@ -116,6 +116,9 @@ import {registerRootExitRequester,type CommandResult,} from "./utils/commandResult.js";+import { registerRunningCli } from "./utils/runningCli.js";++registerRunningCli();const isHelp = process.argv.includes("--help") || process.argv.includes("-h");diff --git a/packages/cli/src/utils/autoUpdate.installer.test.ts b/packages/cli/src/utils/autoUpdate.installer.test.tsnew file mode 100644index 0000000000..fe1802e880--- /dev/null+++ b/packages/cli/src/utils/autoUpdate.installer.test.ts@@ -0,0 +1,152 @@+import { spawn, type ChildProcess } from "node:child_process";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ utimesSync,+ writeFileSync,+} from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, it } from "vitest";+import { installerScript } from "./autoUpdate.js";++// Runs the real detached-installer script; the "install" only writes a marker file.+const dirs: string[] = [];+const children: ChildProcess[] = [];++afterEach(() => {+ for (const child of children.splice(0)) child.kill();+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });+});++function setup(staleMs = 60_000) {+ const dir = mkdtempSync(join(tmpdir(), "hf-installer-"));+ dirs.push(dir);+ const runningDir = join(dir, "running");+ mkdirSync(runningDir);+ const marker = join(dir, "installed");+ const script = installerScript({+ configFile: join(dir, "config.json"),+ version: "9.9.9",+ bin: process.execPath,+ args: ["-e", `require("node:fs").writeFileSync(${JSON.stringify(marker)}, "")`],+ runningDir,+ pollMs: 50,+ maxWaitMs: 60_000,+ staleMs,+ });+ return { dir, runningDir, marker, script };+}++function start(args: string[]): ChildProcess {+ const child = spawn(process.execPath, args, { stdio: "ignore" });+ children.push(child);+ return child;+}++const exited = (child: ChildProcess) =>+ child.exitCode !== null || child.signalCode !== null+ ? Promise.resolve()+ : new Promise<void>((resolve) => child.once("exit", () => resolve()));+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));++async function until(check: () => boolean): Promise<void> {+ while (!check()) await sleep(25);+}++function backdate(file: string): void {+ const tenMinutesAgo = new Date(Date.now() - 10 * 60_000);+ utimesSync(file, tenMinutesAgo, tenMinutesAgo);+}++async function expectInstalledAndRemoved(script: string, marker: string, file: string) {+ await exited(start(["-e", script]));+ expect(existsSync(marker)).toBe(true);+ expect(existsSync(file)).toBe(false);+}++function registerCli(runningDir: string): ChildProcess {+ const cli = start(["-e", "setInterval(() => {}, 1000)"]);+ writeFileSync(join(runningDir, String(cli.pid)), "");+ return cli;+}++it("never replaces package files while a CLI process is running, then installs once it exits", async () => {+ const { dir, runningDir, marker, script } = setup();+ const cli = registerCli(runningDir);+ const installer = start(["-e", script]);++ await sleep(1000);+ expect(existsSync(marker)).toBe(false);++ cli.kill();+ await exited(installer);+ expect(existsSync(marker)).toBe(true);+ expect(JSON.parse(readFileSync(join(dir, "config.json"), "utf-8")).completedUpdate).toMatchObject(+ { version: "9.9.9", ok: true },+ );+});++it("does not wait on a CLI process that died without cleaning up", async () => {+ const { runningDir, marker, script } = setup();+ const dead = start(["-e", ""]);+ await exited(dead);+ const staleFile = join(runningDir, String(dead.pid));+ writeFileSync(staleFile, "");++ await expectInstalledAndRemoved(script, marker, staleFile);+});++it("keeps waiting on a live command whose file looks old after the machine slept", async () => {+ const { runningDir, marker, script } = setup();+ const cli = registerCli(runningDir);+ const file = join(runningDir, String(cli.pid));+ backdate(file);+ const installer = start(["-e", script]);++ await sleep(1000);+ expect(existsSync(marker)).toBe(false);+ expect(existsSync(file)).toBe(true);++ cli.kill();+ await exited(installer);+ expect(existsSync(marker)).toBe(true);+});++it("drops a pid file whose pid belongs to another process once it stops changing", async () => {+ const { runningDir, marker, script } = setup(300);+ const other = start(["-e", "setInterval(() => {}, 1000)"]);+ const staleFile = join(runningDir, String(other.pid));+ writeFileSync(staleFile, "");+ backdate(staleFile);++ await expectInstalledAndRemoved(script, marker, staleFile);+});++it("lets only one installer wait: a later launch exits and installs nothing", async () => {+ const { dir, runningDir, marker, script } = setup();+ const cli = registerCli(runningDir);+ const first = start(["-e", script]);+ await until(() => existsSync(join(dir, "config.json.install-lock")));++ await exited(start(["-e", script]));+ expect(existsSync(marker)).toBe(false);++ cli.kill();+ await exited(first);+ expect(existsSync(marker)).toBe(true);+});++it("takes over an install lock whose pid belongs to another process once it stops changing", async () => {+ const { dir, marker, script } = setup(300);+ const other = start(["-e", "setInterval(() => {}, 1000)"]);+ const lock = join(dir, "config.json.install-lock");+ writeFileSync(lock, String(other.pid));+ backdate(lock);++ await exited(start(["-e", script]));+ expect(existsSync(marker)).toBe(true);+});diff --git a/packages/cli/src/utils/autoUpdate.ts b/packages/cli/src/utils/autoUpdate.tsindex 3b034f11b4..bb5350851c 100644--- a/packages/cli/src/utils/autoUpdate.ts+++ b/packages/cli/src/utils/autoUpdate.ts@@ -31,6 +31,7 @@ import { compareVersions } from "compare-versions";import { withFileLock } from "../media-use/lib/config-lock.mjs";import { readConfig, writeConfig } from "../telemetry/config.js";import { updateCheckDisabled } from "./updateCheck.js";+import { RUNNING_DIR, RUNNING_STALE_MS } from "./runningCli.js";import {detectInstaller,installInvocation,@@ -41,6 +42,9 @@ const CONFIG_DIR = join(homedir(), ".hyperframes");const LOG_FILE = join(CONFIG_DIR, "auto-update.log");/** An install that hasn't finished after this many ms is considered stuck. */const PENDING_TIMEOUT_MS = 10 * 60 * 1000;+/** A waiting installer gives up after this long; the next run schedules it again. */+const INSTALL_MAX_WAIT_MS = 60 * 60 * 1000;+const INSTALL_POLL_MS = 2_000;function isAutoInstallDisabled(): boolean {return updateCheckDisabled() || process.env["HYPERFRAMES_NO_AUTO_INSTALL"] === "1";@@ -65,6 +69,125 @@ function log(line: string): void {}}+export interface InstallerScriptOptions {+ configFile: string;+ version: string;+ bin: string;+ args: readonly string[];+ runningDir: string;+ pollMs: number;+ maxWaitMs: number;+ /** A pid or install-lock file not touched for this long belongs to a dead process. */+ staleMs: number;+}++/** The detached installer, run via `node -e`: waits until no CLI in `runningDir` is alive, then+ * installs with execFile (no shell) and records completedUpdate under the settings lock. */+export function installerScript(o: InstallerScriptOptions): string {+ return `+ const { execFile } = require("node:child_process");+ const fs = require("node:fs");+ const { join } = require("node:path");+ const { readFileSync, renameSync, writeFileSync } = fs;+ const CFG = ${JSON.stringify(o.configFile)};+ const TMP = \`\${CFG}.tmp\`;+ const INSTALL_LOCK = \`\${CFG}.install-lock\`;+ const RUNNING = ${JSON.stringify(o.runningDir)};+ const VERSION = ${JSON.stringify(o.version)};+ const BIN = ${JSON.stringify(o.bin)};+ const ARGS = ${JSON.stringify(o.args)};+ const withFileLock = ${withFileLock.toString()};+ const withLock = (task) => { try { withFileLock(\`\${CFG}.lock\`, fs, task); } catch (e) {} };+ const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };+ // Stale = no heartbeat for staleMs on this process's own clock, which stops while the machine sleeps.+ const seen = new Map();+ const mono = () => Number(process.hrtime.bigint() / 1000000n);+ const observe = (file) => {+ let mtime;+ try { mtime = fs.statSync(file).mtimeMs; } catch (e) { return "stale"; }+ const prev = seen.get(file);+ if (prev && prev.mtime === mtime) return mono() - prev.at >= ${o.staleMs} ? "stale" : "quiet";+ seen.set(file, { mtime, at: mono() });+ return prev ? "beating" : "quiet";+ };+ const touch = (file) => { try { const now = new Date(); fs.utimesSync(file, now, now); } catch (e) {} };+ const running = () => {+ let names = [];+ try { names = fs.readdirSync(RUNNING); } catch (e) {}+ return names.filter((name) => {+ const pid = Number(name);+ const file = join(RUNNING, name);+ if (Number.isInteger(pid) && pid > 0 && alive(pid) && observe(file) !== "stale") return true;+ try { fs.unlinkSync(file); } catch (e) {}+ return false;+ });+ };+ let lockBeat;+ const ownsLock = () => { try { return Number(readFileSync(INSTALL_LOCK, "utf-8")) === process.pid; } catch (e) { return false; } };+ // Under the settings lock, so two installers launched together cannot both take it over.+ const tryLock = () => {+ let result = "stuck";+ withLock(() => {+ let owner = NaN;+ try { owner = Number(readFileSync(INSTALL_LOCK, "utf-8")); } catch (e) {}+ const state = Number.isInteger(owner) && owner > 0 && alive(owner) ? observe(INSTALL_LOCK) : "stale";+ if (state !== "stale") { result = state; return; }+ writeFileSync(INSTALL_LOCK, String(process.pid));+ result = "taken";+ });+ return result;+ };+ const releaseInstallLock = () => {+ clearInterval(lockBeat);+ if (ownsLock()) { try { fs.unlinkSync(INSTALL_LOCK); } catch (e) {} }+ };+ const install = () => execFile(BIN, ARGS, { windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (err, _stdout, stderr) => {+ withLock(() => {+ let cfg = {};+ try { cfg = JSON.parse(readFileSync(CFG, "utf-8")); } catch (e) { if (e.code !== "ENOENT") return; }+ cfg.completedUpdate = {+ version: VERSION,+ ok: !err,+ finishedAt: new Date().toISOString(),+ ...(err ? { error: String(stderr || err.message || "install failed").slice(-400) } : {}),+ };+ delete cfg.pendingUpdate;+ try {+ writeFileSync(TMP, JSON.stringify(cfg, null, 2) + "\\n", { mode: 0o600 });+ renameSync(TMP, CFG);+ } catch (e) {}+ });+ releaseInstallLock();+ });+ const started = Date.now();+ let lastPoll = Date.now();+ const waitThenInstall = () => {+ if (!ownsLock()) return releaseInstallLock();+ // A long gap between polls means the machine slept: watch every file afresh.+ if (Date.now() - lastPoll > ${o.pollMs} * 5) seen.clear();+ lastPoll = Date.now();+ if (running().length === 0) return install();+ if (Date.now() - started > ${o.maxWaitMs}) {+ console.log(\`[wait] gave up on \${VERSION}: a hyperframes process is still running\`);+ return releaseInstallLock();+ }+ setTimeout(waitThenInstall, ${o.pollMs});+ };+ const acquire = () => {+ const result = tryLock();+ if (result === "taken") {+ lockBeat = setInterval(() => ownsLock() && touch(INSTALL_LOCK), ${o.pollMs});+ return waitThenInstall();+ }+ if (result === "quiet") return setTimeout(acquire, ${o.pollMs});+ console.log(result === "beating"+ ? \`[wait] another installer is already waiting; leaving \${VERSION} to it\`+ : \`[wait] settings lock busy; \${VERSION} left for the next run\`);+ };+ acquire();+ `;+}+/*** Spawn a detached child to run the install command. Stdout/stderr land in* the log file; the child is `unref()`d so the parent exits immediately@@ -83,41 +206,16 @@ function launchDetachedInstall(mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });const configFile = join(CONFIG_DIR, "config.json");- // The child script:- // 1. Runs the install via execFile (bin + argv, NO shell) so a version- // string can never be re-interpreted as shell syntax — structural- // symmetry with the interactive `runDetectedInstall` path.- // 2. Under the shared settings lock (withFileLock, embedded as source), rewrites the config with- // completedUpdate and clears pendingUpdate; skips on lock timeout or an unreadable file.- // We run it through `node -e` so we don't need to ship a separate file. Bin- // and args are embedded as JSON literals (data, not code).- const nodeScript = `- const { execFile } = require("node:child_process");- const fs = require("node:fs");- const { readFileSync, renameSync, writeFileSync } = fs;- const CFG = ${JSON.stringify(configFile)};- const TMP = \`\${CFG}.tmp\`;- const VERSION = ${JSON.stringify(version)};- const BIN = ${JSON.stringify(invocation.bin)};- const ARGS = ${JSON.stringify(invocation.args)};- const withFileLock = ${withFileLock.toString()};- const withLock = (task) => { try { withFileLock(\`\${CFG}.lock\`, fs, task); } catch (e) {} };- execFile(BIN, ARGS, { windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (err, _stdout, stderr) => withLock(() => {- let cfg = {};- try { cfg = JSON.parse(readFileSync(CFG, "utf-8")); } catch (e) { if (e.code !== "ENOENT") return; }- cfg.completedUpdate = {- version: VERSION,- ok: !err,- finishedAt: new Date().toISOString(),- ...(err ? { error: String(stderr || err.message || "install failed").slice(-400) } : {}),- };- delete cfg.pendingUpdate;- try {- writeFileSync(TMP, JSON.stringify(cfg, null, 2) + "\\n", { mode: 0o600 });- renameSync(TMP, CFG);- } catch (e) {}- }));- `;+ const nodeScript = installerScript({+ configFile,+ version,+ bin: invocation.bin,+ args: invocation.args,+ runningDir: RUNNING_DIR,+ pollMs: INSTALL_POLL_MS,+ maxWaitMs: INSTALL_MAX_WAIT_MS,+ staleMs: RUNNING_STALE_MS,+ });const out = openSync(LOG_FILE, "a", 0o600);const child = spawn(process.execPath, ["-e", nodeScript], {@@ -130,12 +228,7 @@ function launchDetachedInstall(log(`[launch] pid=${child.pid ?? "?"} cmd=${displayCommand} version=${version}`);}-/**- * If a new version is available and policy allows, kick off a detached- * installer. Returns whether an install was spawned (for tests).- */-export function scheduleBackgroundInstall(latestVersion: string, currentVersion: string): boolean {- if (isAutoInstallDisabled()) return false;+function isSilentUpgrade(latestVersion: string, currentVersion: string): boolean {if (!latestVersion || !currentVersion) return false;let cmp: number;@@ -155,6 +248,16 @@ export function scheduleBackgroundInstall(latestVersion: string, currentVersion:log(`[skip] major-bump ${currentVersion} -> ${latestVersion}`);return false;}+ return true;+}++/**+ * If a new version is available and policy allows, kick off a detached+ * installer. Returns whether an install was spawned (for tests).+ */+export function scheduleBackgroundInstall(latestVersion: string, currentVersion: string): boolean {+ if (isAutoInstallDisabled()) return false;+ if (!isSilentUpgrade(latestVersion, currentVersion)) return false;const installer = detectInstaller();if (installer.kind === "skip") {diff --git a/packages/cli/src/utils/runningCli.test.ts b/packages/cli/src/utils/runningCli.test.tsnew file mode 100644index 0000000000..f977069e1b--- /dev/null+++ b/packages/cli/src/utils/runningCli.test.ts@@ -0,0 +1,38 @@+import { existsSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, it } from "vitest";+import { registerRunningCli } from "./runningCli.js";++let dir = "";+afterEach(() => rmSync(dir, { recursive: true, force: true }));++it("marks this process as running until it exits", () => {+ dir = mkdtempSync(join(tmpdir(), "hf-running-"));+ const before = process.listeners("exit");+ registerRunningCli(join(dir, "running"));+ const file = join(dir, "running", String(process.pid));+ expect(existsSync(file)).toBe(true);++ const added = process.listeners("exit").filter((listener) => !before.includes(listener));+ for (const listener of added) {+ listener(0);+ process.off("exit", listener);+ }+ expect(existsSync(file)).toBe(false);+});++it("rewrites the file on each heartbeat, so a removed file comes back", async () => {+ dir = mkdtempSync(join(tmpdir(), "hf-running-"));+ const before = process.listeners("exit");+ registerRunningCli(join(dir, "running"), 20);+ const file = join(dir, "running", String(process.pid));+ unlinkSync(file);+ await new Promise((resolve) => setTimeout(resolve, 200));+ expect(existsSync(file)).toBe(true);++ for (const listener of process.listeners("exit").filter((l) => !before.includes(l))) {+ listener(0);+ process.off("exit", listener);+ }+});diff --git a/packages/cli/src/utils/runningCli.ts b/packages/cli/src/utils/runningCli.tsnew file mode 100644index 0000000000..538c955381--- /dev/null+++ b/packages/cli/src/utils/runningCli.ts@@ -0,0 +1,39 @@+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";+import { homedir } from "node:os";+import { join } from "node:path";++/** One empty file per live CLI process, named by pid; the background installer waits until none is alive. */+export const RUNNING_DIR = join(homedir(), ".hyperframes", "running");+const RUNNING_HEARTBEAT_MS = 30_000;+export const RUNNING_STALE_MS = 10 * 60_000;++/** Mark this process as running until it exits. Never throws: a failed write only lets an update land sooner. */+export function registerRunningCli(+ dir: string = RUNNING_DIR,+ heartbeatMs: number = RUNNING_HEARTBEAT_MS,+): void {+ try {+ mkdirSync(dir, { recursive: true, mode: 0o700 });+ const file = join(dir, String(process.pid));+ writeFileSync(file, "", { mode: 0o600 });+ const heartbeat = setInterval(() => {+ try {+ mkdirSync(dir, { recursive: true, mode: 0o700 });+ writeFileSync(file, String(Date.now()), { mode: 0o600 });+ } catch {+ /* best-effort */+ }+ }, heartbeatMs);+ heartbeat.unref();+ process.on("exit", () => {+ clearInterval(heartbeat);+ try {+ unlinkSync(file);+ } catch {+ /* already gone */+ }+ });+ } catch {+ /* best-effort */+ }+}