Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
perf(cli): a repeat check starts with the CLI and Chrome already up (#5943)
Miguel Ángel434ad8c41c6f
diff --git a/.fallowrc.jsonc b/.fallowrc.jsoncindex fefab37443..c40522d656 100644--- a/.fallowrc.jsonc+++ b/.fallowrc.jsonc@@ -59,6 +59,9 @@"packages/cli/src/backgroundChecksWorker.ts",// Parakeet decode worker, spawned by path from whisper/sherpa.ts."packages/cli/src/whisper/sherpaWorker.ts",+ // Warm-check client, spawned by path from warmCheck.process.test.ts.+ "packages/cli/src/warmCheckClient.fixture.ts",+ "packages/cli/src/browser/chromeOrphans.fixture.ts",// Test fixture worker, spawned by path via the pools' workerEntryPath// option from the crash-recovery tests; has no import-graph referrer."packages/producer/src/services/__fixtures__/crashOnMessageWorker.mjs",diff --git a/package.json b/package.jsonindex 93d429d446..40514cb2b9 100644--- a/package.json+++ b/package.json@@ -54,7 +54,7 @@"player:perf": "bun run --filter @hyperframes/player perf","format:check": "oxfmt --check .","knip": "knip",- "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/comments-workflow.test.mjs scripts/comment-ratchet.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-cli-lazy-deps.test.mjs scripts/check-studio-copy-dashes.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/clawhub-sync.test.mjs scripts/publish-workflow.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/merge-queue-workflows.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/check-edit-accuracy-filter.test.mjs scripts/edit-accuracy-retry.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/backfill-block-previews.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/rewrite-relative-import-extensions.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/ci/base-file.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs registry/components/filmed-screen/filmed-screen.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts",+ "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/comments-workflow.test.mjs scripts/comment-ratchet.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-cli-lazy-deps.test.mjs scripts/file-url-paths.test.mjs scripts/check-studio-copy-dashes.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/clawhub-sync.test.mjs scripts/publish-workflow.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/merge-queue-workflows.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/check-edit-accuracy-filter.test.mjs scripts/edit-accuracy-retry.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/backfill-block-previews.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/rewrite-relative-import-extensions.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/ci/base-file.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs registry/components/filmed-screen/filmed-screen.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts","typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json","test:skills": "HYPERFRAMES_MEDIA_HOME_REQUIRED=1 node --import ./packages/cli/scripts/test-home.mjs --test 'skills/**/*.test.mjs' 'packages/cli/src/media-use/**/*.test.mjs'","generate:previews": "tsx scripts/generate-template-previews.ts",diff --git a/packages/cli/bin/hyperframes.mjs b/packages/cli/bin/hyperframes.mjsindex 95d72345dc..127537a926 100644--- a/packages/cli/bin/hyperframes.mjs+++ b/packages/cli/bin/hyperframes.mjs@@ -10,5 +10,7 @@ if (error) {} else {// Reuses V8 bytecode across runs (os.tmpdir()/node-compile-cache); Node 22.0 has no such API.module.enableCompileCache?.();- await import("../dist/cli.js");+ const warm = process.argv[2] === "check" ? await import("../dist/warmCheckClient.js") : undefined;+ if (warm?.warmCheckEligible()) process.once("exit", () => warm.startNextWarmCheck());+ if (!(warm?.warmCheckEligible() && (await warm.runWarmCheck()))) await import("../dist/cli.js");}diff --git a/packages/cli/src/browser/chromeOrphans.fixture.ts b/packages/cli/src/browser/chromeOrphans.fixture.tsnew file mode 100644index 0000000000..16917c438d--- /dev/null+++ b/packages/cli/src/browser/chromeOrphans.fixture.ts@@ -0,0 +1,26 @@+import { writeFileSync } from "node:fs";+import puppeteer from "puppeteer-core";+import { testProcessDescendants } from "../utils/processTestUtils.js";++const processFile = process.env.HF_TEST_PROCESS_FILE;+if (!processFile) throw new Error("Missing process file");+const launch = puppeteer.launch.bind(puppeteer);+puppeteer.launch = async (options) => {+ const browser = await launch(options);+ const pid = browser.process()?.pid;+ if (!pid) throw new Error("Browser did not expose its process");+ const newPage = browser.newPage.bind(browser);+ browser.newPage = async () => {+ const page = await newPage();+ writeFileSync(+ processFile,+ JSON.stringify({+ chrome: [pid, ...testProcessDescendants(pid)],+ watchdog: testProcessDescendants(process.pid, /^node/i),+ }),+ );+ return page;+ };+ return browser;+};+await import("../cli.js");diff --git a/packages/cli/src/browser/chromeOrphans.process.test.ts b/packages/cli/src/browser/chromeOrphans.process.test.tsnew file mode 100644index 0000000000..0205346af7--- /dev/null+++ b/packages/cli/src/browser/chromeOrphans.process.test.ts@@ -0,0 +1,92 @@+import { spawn } from "node:child_process";+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";+import { rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";+import { expect, it, onTestFinished } from "vitest";+import {+ stopTestProcesses,+ testProcessDescendants,+ testProcessIsAlive,+ waitForTestCondition,+} from "../utils/processTestUtils.js";++const here = dirname(fileURLToPath(import.meta.url));+const cli = join(here, "..", "cli.ts");++function project(busy: boolean): string {+ const dir = mkdtempSync(join(tmpdir(), "hf-chrome-orphans-"));+ onTestFinished(() => rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));+ mkdirSync(join(dir, "compositions"));+ writeFileSync(+ join(dir, "index.html"),+ `<!doctype html><html><body><div data-composition-id="main" data-width="320" data-height="180" data-duration="1">+<div data-composition-id="scene" data-composition-src="compositions/scene.html" data-start="0" data-duration="1"></div></div>+<script>window.__timelines={main:{duration:()=>1,seek:()=>{},pause:()=>{}}};</script></body></html>`,+ );+ const script = busy+ ? `const el=document.getElementById("box");while(el.offsetWidth<2){el.style.height="1px";}`+ : "";+ writeFileSync(+ join(dir, "compositions/scene.html"),+ `<template id="scene"><div data-composition-id="scene"><div id="box" style="width:1px;height:1px"></div><script>${script}</script></div></template>`,+ );+ return dir;+}++function check(dir: string, entry = cli, env: Record<string, string> = {}) {+ const child = spawn(+ process.execPath,+ ["--import", "tsx", entry, "check", dir, "--json", "--no-browser-gpu", "--samples=1"],+ {+ env: { ...process.env, CI: "1", HYPERFRAMES_NO_TELEMETRY: "1", ...env },+ stdio: ["ignore", "ignore", "ignore"],+ },+ );+ const seen = { chrome: new Set<number>(), watchdog: new Set<number>() };+ const record = () => {+ for (const pid of testProcessDescendants(child.pid!, /chrom/i)) seen.chrome.add(pid);+ for (const pid of testProcessDescendants(child.pid!, /^node/i)) seen.watchdog.add(pid);+ };+ const done = new Promise<void>((resolve) => child.once("close", () => resolve()));+ onTestFinished(() => stopTestProcesses(child, [...seen.chrome, ...seen.watchdog]));+ return { child, seen, record, done };+}++const alive = (pids: Iterable<number>) => [...pids].filter(testProcessIsAlive);++it("leaves no Chrome process behind when the CLI is killed mid busy-loop", async () => {+ const run = check(project(true));+ await waitForTestCondition(() => {+ run.record();+ return run.seen.chrome.size >= 3;+ }, 30_000);+ await new Promise((resolve) => setTimeout(resolve, 3_000));+ run.record();+ run.child.kill("SIGKILL");+ await new Promise((resolve) => setTimeout(resolve, 5_000));+ expect(alive(run.seen.chrome)).toEqual([]);+ await waitForTestCondition(() => alive(run.seen.watchdog).length === 0, 30_000);+}, 90_000);++it("leaves no Chrome process or watchdog behind after a check that finishes", async () => {+ const dir = project(false);+ const processFile = join(dir, "processes.json");+ const run = check(dir, join(here, "chromeOrphans.fixture.ts"), {+ HF_TEST_PROCESS_FILE: processFile,+ });+ await run.done;+ const seen = JSON.parse(readFileSync(processFile, "utf8")) as {+ chrome: number[];+ watchdog: number[];+ };+ seen.chrome.forEach((pid) => run.seen.chrome.add(pid));+ seen.watchdog.forEach((pid) => run.seen.watchdog.add(pid));+ expect(seen.chrome.length).toBeGreaterThan(0);+ if (process.platform === "win32") expect(seen.watchdog.length).toBeGreaterThan(0);+ await waitForTestCondition(+ () => alive(seen.chrome).length + alive(seen.watchdog).length === 0,+ 10_000,+ );+}, 90_000);diff --git a/packages/cli/src/browser/launch.noListen.test.ts b/packages/cli/src/browser/launch.noListen.test.tsindex f40dd4f2fa..2a9e4f2218 100644--- a/packages/cli/src/browser/launch.noListen.test.ts+++ b/packages/cli/src/browser/launch.noListen.test.ts@@ -32,7 +32,7 @@ describe("the GPU probe where nothing may listen", () => {pipe: true,args: ["--headless", "--single-process", "--disable-gpu-compositing"],});- expect(probe.options[1]!.pipe).toBeUndefined();+ expect(probe.options[1]!.pipe).toBe(true);expect(probe.options[1]!.args).toEqual(["--headless"]);});});diff --git a/packages/cli/src/browser/launch.ts b/packages/cli/src/browser/launch.tsindex 73d527ca23..97da91edd0 100644--- a/packages/cli/src/browser/launch.ts+++ b/packages/cli/src/browser/launch.ts@@ -7,6 +7,7 @@ import {import { normalizeErrorMessage } from "../utils/errorMessage.js";import { requestCliExit } from "../utils/commandResult.js";import { processIsAlive } from "../utils/processTree.js";+import { watchChromeTree, type ChromeWatchdog } from "./windowsChromeWatchdog.js";import {inAgentSandbox,isOneProcessOverPipe,@@ -19,6 +20,7 @@ export class BrowserCleanupError extends AggregateError {}const browsers = new Set<Browser>();const closing = new WeakMap<Browser, Promise<void>>();+const watchdogs = new WeakMap<Browser, ChromeWatchdog>();const pending = new Map<Promise<Browser>, AbortController>();const sessionCleanups = new Set<() => Promise<void>>();const CLOSE_GRACE_MS = 1_000;@@ -110,8 +112,9 @@ async function launchOwnedBrowser(ownSignals();const abort = new AbortController();const signal = options.signal ? AbortSignal.any([options.signal, abort.signal]) : abort.signal;+ const launchedAt = Date.now();const launch = untilLaunchOrAbort(- puppeteer.launch({ ...options, signal, handleSIGINT: false, handleSIGTERM: false }),+ puppeteer.launch({ ...options, pipe: true, signal, handleSIGINT: false, handleSIGTERM: false }),signal,);const limit = options.timeout ?? LAUNCH_TIMEOUT_MS;@@ -128,6 +131,8 @@ async function launchOwnedBrowser(const child = browser.process();if (!child) throw new Error("A launched browser has no owned process.");browsers.add(browser);+ const watchdog = watchChromeTree(child, launchedAt);+ if (watchdog) watchdogs.set(browser, watchdog);child.once("exit", () => browsers.delete(browser));return browser;} finally {@@ -191,9 +196,18 @@ export async function rethrowAfterBrowserCleanup(}async function closeBrowser(browser: Browser): Promise<void> {+ let clean = false;+ try {+ clean = await closedWithoutKill(browser);+ } finally {+ watchdogs.get(browser)?.release(clean);+ }+}++async function closedWithoutKill(browser: Browser): Promise<boolean> {const child = browser.process();if (!child) throw new Error("A managed browser lost its owned process.");- if (child.exitCode !== null || child.signalCode !== null) return;+ if (child.exitCode !== null || child.signalCode !== null) return false;const exited = new Promise<void>((resolve) => child.once("exit", () => resolve()));let timer: NodeJS.Timeout | undefined;let poll: NodeJS.Timeout | undefined;@@ -205,7 +219,8 @@ async function closeBrowser(browser: Browser): Promise<void> {browser.close().catch((error: unknown) => console.warn("Browser close failed:", error)),grace,]);- if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");+ const clean = child.exitCode !== null || child.signalCode !== null;+ if (!clean) child.kill("SIGKILL");clearTimeout(timer);const exitLimit = new Promise<never>((_, reject) => {timer = setTimeout(@@ -219,6 +234,7 @@ async function closeBrowser(browser: Browser): Promise<void> {}, EXIT_POLL_MS);});await Promise.race([exited, goneBeforeExitEvent, exitLimit]);+ return clean;} finally {clearTimeout(timer);clearInterval(poll);diff --git a/packages/cli/src/browser/sandboxDenied.test.ts b/packages/cli/src/browser/sandboxDenied.test.tsindex bf3f22bb1f..a6a1c4848a 100644--- a/packages/cli/src/browser/sandboxDenied.test.ts+++ b/packages/cli/src/browser/sandboxDenied.test.ts@@ -68,7 +68,8 @@ describe("a browser inside an agent's macOS seatbelt", () => {vi.stubEnv("CODEX_SANDBOX", "");const { puppeteer, launches } = recordingPuppeteer([SEATBELT_LAUNCH_FAILURE]);await expect(launchManagedBrowser(puppeteer, { args: ["--headless"] })).resolves.toBeDefined();- expect(launches.map((options) => options.pipe ?? false)).toEqual([false, true]);+ expect(launches.map((options) => options.pipe ?? false)).toEqual([true, true]);+ expect(launches[0]!.args).toEqual(["--headless"]);expect(launches[1]!.args).toEqual(["--headless","--single-process",diff --git a/packages/cli/src/browser/windowsChromeWatchdog.ts b/packages/cli/src/browser/windowsChromeWatchdog.tsnew file mode 100644index 0000000000..7838e9b7ba--- /dev/null+++ b/packages/cli/src/browser/windowsChromeWatchdog.ts@@ -0,0 +1,57 @@+import { spawn, type ChildProcess } from "node:child_process";+import { realpathSync } from "node:fs";++const SWEEP = `$b=[int]$env:HF_CHROME_PID; $x=$env:HF_CHROME_EXE; $t=[DateTimeOffset]::FromUnixTimeMilliseconds([int64]$env:HF_CHROME_SINCE).UtcDateTime; Get-CimInstance Win32_Process | Where-Object { ($_.ProcessId -eq $b -or $_.ParentProcessId -eq $b) -and $_.ExecutablePath -eq $x -and $_.CreationDate.ToUniversalTime() -ge $t } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`;++const WATCHDOG = `let clean = false;+const done = () => {+ if (!clean) require("node:child_process").spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ${JSON.stringify(SWEEP)}], { windowsHide: true, timeout: 20000 });+ process.exit(0);+};+process.stdin.on("data", (data) => { clean ||= String(data).includes("clean"); });+process.stdin.on("end", done);+process.stdin.on("error", done);`;++export interface ChromeWatchdog {+ release(clean: boolean): void;+}++function executableOf(chrome: ChildProcess): string | undefined {+ try {+ return realpathSync.native(chrome.spawnfile);+ } catch {+ return undefined;+ }+}++/** Windows does not end a process's children with it, so Chrome's children outlive a killed CLI without this. */+export function watchChromeTree(+ chrome: ChildProcess,+ launchedAt: number,+): ChromeWatchdog | undefined {+ const executable = process.platform === "win32" ? executableOf(chrome) : undefined;+ if (!executable || chrome.pid === undefined) return undefined;+ const watchdog = spawn(process.execPath, ["-e", WATCHDOG], {+ detached: true,+ env: {+ ...process.env,+ HF_CHROME_PID: String(chrome.pid),+ HF_CHROME_EXE: executable,+ HF_CHROME_SINCE: String(launchedAt),+ },+ stdio: ["pipe", "ignore", "ignore"],+ windowsHide: true,+ });+ watchdog.on("error", () => {});+ watchdog.stdin?.on("error", () => {});+ watchdog.unref();+ (watchdog.stdin as unknown as { unref?: () => void } | null)?.unref?.();+ let released = false;+ return {+ release(clean) {+ if (released) return;+ released = true;+ watchdog.stdin?.end(clean ? "clean" : "");+ },+ };+}diff --git a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.tsindex 8cb6428550..f896f605d7 100644--- a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts+++ b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts@@ -260,7 +260,7 @@ describe("openSettledCompositionPage when nothing may listen", () => {const opened = fakeBrowser();mocks.launch.mockResolvedValue(opened.browser);await openSettledCompositionPage(HTML, "http://127.0.0.1:3000", OPTIONS);- expect(launched().pipe).toBeUndefined();+ expect(launched().pipe).toBe(true);expect(launched().args).toEqual(["--headless"]);expect(opened.page.setRequestInterception).not.toHaveBeenCalled();});diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.tsindex e981a77800..c672d4fa1c 100644--- a/packages/cli/src/commands/check.ts+++ b/packages/cli/src/commands/check.ts@@ -26,6 +26,7 @@ import { withMeta } from "../utils/updateCheck.js";import {DEFAULT_CHECK_OPTIONS,checkExitCode,+ prelaunchBrowserForNextCheck,runCheckPipeline,selectFindingCropRequests,type CheckFinding,@@ -317,6 +318,11 @@ function parseCheckOptions(args: Record<string, unknown>): CheckOptions {};}+export function prelaunchBrowserForCheck(rawArgs: string[]) {+ const args = parseArgs(rawArgs, CHECK_COMMAND_ARGS);+ return prelaunchBrowserForNextCheck(resolveProject(args.dir), parseCheckOptions(args));+}+export function parseCheckRange(value: unknown): [number, number] | undefined {if (value === undefined) return undefined;const parts = String(value).split(/[,:]/);diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.tsindex 0de30ca91d..4002f36af3 100644--- a/packages/cli/src/utils/checkPipeline.ts+++ b/packages/cli/src/utils/checkPipeline.ts@@ -2043,10 +2043,23 @@ async function runBrowserCheck(}// Chrome boots while lint, hdr and bundling run; the source index guesses the bundle's launch arguments.+let adoptedBrowser: PrelaunchedBrowser | undefined;++export async function prelaunchBrowserForNextCheck(+ project: ProjectDir,+ options: CheckOptions,+): Promise<PrelaunchedBrowser | undefined> {+ adoptedBrowser = await prelaunchBrowser(project, options);+ return adoptedBrowser;+}+async function prelaunchBrowser(project: ProjectDir,options: CheckOptions,): Promise<PrelaunchedBrowser | undefined> {+ const adopted = adoptedBrowser;+ adoptedBrowser = undefined;+ if (adopted) return adopted;const html = await readFile(project.indexPath, "utf8").catch(() => undefined);if (html === undefined) return undefined;const { prelaunchCompositionBrowser } = await import("../capture/captureCompositionFrame.js");diff --git a/packages/cli/src/utils/processTestUtils.ts b/packages/cli/src/utils/processTestUtils.tsindex 19c5998ab0..8cb1a275b9 100644--- a/packages/cli/src/utils/processTestUtils.ts+++ b/packages/cli/src/utils/processTestUtils.ts@@ -1,4 +1,4 @@-import type { ChildProcess } from "node:child_process";+import { execFileSync, type ChildProcess } from "node:child_process";import { readFileSync, readdirSync } from "node:fs";export function testProcessIsAlive(pid: number): boolean {@@ -27,20 +27,49 @@ export async function waitForTestCondition(check: () => boolean, timeoutMs: numb}}-export function testProcessDescendants(parentPid: number): number[] {- const parents = new Map<number, number>();- for (const name of readdirSync("/proc")) {- if (!/^\d+$/.test(name)) continue;- try {- const stat = readFileSync(`/proc/${name}/stat`, "utf8");- parents.set(Number(name), Number(stat.slice(stat.lastIndexOf(") ") + 2).split(" ")[1]));- } catch {}+function processTable(): Map<number, { parent: number; name: string }> {+ const table = new Map<number, { parent: number; name: string }>();+ if (process.platform === "linux") {+ for (const name of readdirSync("/proc")) {+ if (!/^\d+$/.test(name)) continue;+ try {+ const stat = readFileSync(`/proc/${name}/stat`, "utf8");+ table.set(Number(name), {+ parent: Number(stat.slice(stat.lastIndexOf(") ") + 2).split(" ")[1]),+ name: stat.slice(stat.indexOf("(") + 1, stat.lastIndexOf(")")),+ });+ } catch {}+ }+ return table;}+ const listing =+ process.platform === "win32"+ ? execFileSync(+ "powershell.exe",+ [+ "-NoProfile",+ "-Command",+ 'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId) $($_.ParentProcessId) $($_.Name)" }',+ ],+ { encoding: "utf8" },+ )+ : execFileSync("ps", ["-A", "-o", "pid=,ppid=,comm="], { encoding: "utf8" });+ for (const line of listing.split("\n")) {+ const [pid, parent, ...name] = line.trim().split(/\s+/);+ if (Number(pid) > 0) table.set(Number(pid), { parent: Number(parent), name: name.join(" ") });+ }+ return table;+}++export function testProcessDescendants(parentPid: number, named?: RegExp): number[] {+ const table = processTable();const owned = new Set([parentPid]);for (const pid of owned) {- for (const [child, parent] of parents) if (parent === pid) owned.add(child);+ for (const [child, entry] of table) if (entry.parent === pid) owned.add(child);}- return [...owned].filter((pid) => pid !== parentPid);+ return [...owned].filter(+ (pid) => pid !== parentPid && (!named || named.test(table.get(pid)?.name ?? "")),+ );}export async function stopTestProcesses(diff --git a/packages/cli/src/warmCheck.process.test.ts b/packages/cli/src/warmCheck.process.test.tsnew file mode 100644index 0000000000..023bac8449--- /dev/null+++ b/packages/cli/src/warmCheck.process.test.ts@@ -0,0 +1,236 @@+import { spawn } from "node:child_process";+import { existsSync, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";+import { rm } from "node:fs/promises";+import { connect, createServer } from "node:net";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";+import { expect, it, onTestFinished } from "vitest";+import {+ stopTestProcesses,+ testProcessDescendants,+ testProcessIsAlive,+ waitForTestCondition,+} from "./utils/processTestUtils.js";+import { Frame, encodeFrame, frameReader, warmCheckEndpoint } from "./warmCheckProtocol.js";++const here = dirname(fileURLToPath(import.meta.url));+const CHECK_ARGS = ["--json", "--no-browser-gpu", "--samples=1"];+const CHROME = /chrom/i;++function temporary(prefix: string, base = tmpdir()): string {+ const dir = mkdtempSync(join(base, prefix));+ onTestFinished(() => rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));+ return dir;+}++function privateEnv(): Record<string, string> {+ const base = temporary("hfw-", process.platform === "win32" ? tmpdir() : "/tmp");+ return {+ ...(process.env as Record<string, string>),+ HYPERFRAMES_NO_TELEMETRY: "1",+ DO_NOT_TRACK: "1",+ ...(process.platform === "win32" ? { LOCALAPPDATA: base } : { XDG_RUNTIME_DIR: base }),+ };+}++function project(hang = false): string {+ const dir = temporary("hf-warm-check-");+ mkdirSync(join(dir, "compositions"));+ const scene = hang+ ? `<div data-composition-id="hang" data-composition-src="compositions/hang.html" data-start="0" data-duration="1"></div>`+ : `<p style="color:#fff;background:#000">Warm</p>`;+ writeFileSync(+ join(dir, "index.html"),+ `<!doctype html><html><body>+<div data-composition-id="main" data-width="320" data-height="180" data-duration="1">${scene}</div>+<script>window.__timelines.main={duration:()=>1,seek:()=>{},pause:()=>{}};</script></body></html>`,+ );+ writeFileSync(+ join(dir, "compositions/hang.html"),+ `<template id="hang"><div data-composition-id="hang"><div id="box" style="width:1px;height:1px"></div>+<script>const el=document.getElementById("box");while(el.offsetWidth<2){el.style.height="1px";}</script>+</div></template>`,+ );+ return dir;+}++function run(args: string[], env: Record<string, string>) {+ const child = spawn(process.execPath, ["--import", "tsx", ...args], {+ env,+ stdio: ["ignore", "pipe", "pipe"],+ });+ let stdout = "";+ child.stdout.on("data", (data: Buffer) => (stdout += data.toString()));+ child.stderr.on("data", () => {});+ const done = new Promise<number | null>((resolve) => child.once("close", resolve));+ onTestFinished(() => stopTestProcesses(child, []));+ return { child, done, stdout: () => stdout };+}++async function warmProcess(dir: string, env: Record<string, string>, idleMs = 60_000) {+ const warm = run([join(here, "warmCheck.ts"), String(idleMs), dir, ...CHECK_ARGS], env);+ const pid = warm.child.pid!;+ let chrome: number[] = [];+ onTestFinished(() => stopTestProcesses(warm.child, testProcessDescendants(pid)));+ await waitForTestCondition(() => {+ chrome = testProcessDescendants(pid, CHROME);+ return chrome.length > 0;+ }, 30_000);+ const serving = () =>+ existsSync(join(dir, ".hyperframes")) && readdirSync(join(dir, ".hyperframes")).length > 0;+ return { ...warm, pid, chrome: () => chrome, serving };+}++function client(dir: string, env: Record<string, string>) {+ return run([join(here, "warmCheckClient.fixture.ts"), "check", dir, ...CHECK_ARGS], env);+}++function gone(pids: number[]): boolean {+ return pids.every((pid) => !testProcessIsAlive(pid));+}++function findings(json: string) {+ const report = JSON.parse(json.slice(json.indexOf("{"))) as { saved?: unknown };+ delete report.saved;+ return report;+}++function forgedRequest(env: Record<string, string>, dir: string): Promise<Frame[]> {+ return new Promise((resolve, reject) => {+ const seen: Frame[] = [];+ const socket = connect(warmCheckEndpoint(env)!.address, () => {+ socket.write(encodeFrame(Frame.Hello, "nonce"));+ const request = { argv: ["check", dir], script: "x", cwd: dir, envDigest: "x", proof: "x" };+ socket.write(encodeFrame(Frame.Request, JSON.stringify(request)));+ });+ socket.on(+ "data",+ frameReader((type) => seen.push(type)),+ );+ socket.on("error", reject);+ socket.on("close", () => resolve(seen));+ });+}++function impostor(address: string, reply?: Buffer) {+ const frames: Frame[] = [];+ const server = createServer((socket) => {+ socket.on(+ "data",+ frameReader((type) => {+ frames.push(type);+ if (reply) socket.write(reply);+ }),+ );+ socket.on("error", () => {});+ });+ onTestFinished(() => new Promise<void>((resolve) => server.close(() => resolve())));+ return new Promise<{ frames: Frame[] }>((resolve) =>+ server.listen(address, () => resolve({ frames })),+ );+}++it("serves a check that prints what a cold check prints, then exits with its Chrome", async () => {+ const env = privateEnv();+ const dir = project();+ const warm = await warmProcess(dir, env);+ const chrome = warm.chrome();+ const served = client(dir, env);+ expect(await served.done).toBe(0);+ await waitForTestCondition(() => !testProcessIsAlive(warm.pid) && gone(chrome), 10_000);++ const cold = run([join(here, "cli.ts"), "check", dir, ...CHECK_ARGS], env);+ expect(await cold.done).toBe(0);+ expect(findings(served.stdout())).toEqual(findings(cold.stdout()));+}, 120_000);++it("keeps waiting after a connection that sends no request, then serves", async () => {+ const env = privateEnv();+ const dir = project();+ const warm = await warmProcess(dir, env);+ await new Promise<void>((resolve) => {+ const probe = connect(warmCheckEndpoint(env)!.address, () => probe.destroy());+ probe.once("close", () => resolve());+ });+ const served = client(dir, env);+ expect(await served.done).toBe(0);+ expect(served.stdout()).not.toContain("NOT SERVED");+ await waitForTestCondition(() => !testProcessIsAlive(warm.pid), 10_000);+}, 120_000);++it("takes its Chrome with it when the warm process is killed", async () => {+ const warm = await warmProcess(project(), privateEnv());+ const chrome = warm.chrome();+ warm.child.kill("SIGKILL");+ await waitForTestCondition(() => gone(chrome), 10_000);+}, 60_000);++it("stops with its Chrome when the client is killed mid-check", async () => {+ const env = privateEnv();+ const dir = project(true);+ const warm = await warmProcess(dir, env);+ const chrome = warm.chrome();+ const served = client(dir, env);+ await waitForTestCondition(warm.serving, 30_000);+ served.child.kill("SIGKILL");+ await waitForTestCondition(() => !testProcessIsAlive(warm.pid) && gone(chrome), 10_000);+}, 60_000);++it("exits with its Chrome after its idle window", async () => {+ const warm = await warmProcess(project(), privateEnv(), 10_000);+ const chrome = warm.chrome();+ await waitForTestCondition(() => !testProcessIsAlive(warm.pid) && gone(chrome), 30_000);+}, 60_000);++it("declines a client whose environment differs, and exits for the new one", async () => {+ const env = privateEnv();+ const dir = project();+ const warm = await warmProcess(dir, env);+ const declined = client(dir, { ...env, HF_WARM_TEST_EXTRA: "1" });+ expect(await declined.done).toBe(0);+ expect(declined.stdout()).toBe("NOT SERVED\n");+ await waitForTestCondition(() => !testProcessIsAlive(warm.pid), 10_000);+}, 60_000);++it("leaves a second client to run cold while it serves the first", async () => {+ const env = privateEnv();+ const dir = project(true);+ const warm = await warmProcess(dir, env);+ client(dir, env);+ await waitForTestCondition(warm.serving, 30_000);+ expect(await forgedRequest(env, dir)).toEqual([Frame.Proof, Frame.Declined]);+ const second = client(dir, env);+ expect(await second.done).toBe(0);+ expect(second.stdout()).toBe("NOT SERVED\n");+}, 60_000);++it("declines a request whose proof is wrong, then still serves a genuine client", async () => {+ const env = privateEnv();+ const dir = project();+ const warm = await warmProcess(dir, env);+ expect(await forgedRequest(env, dir)).toEqual([Frame.Proof, Frame.Declined]);+ expect(testProcessIsAlive(warm.pid)).toBe(true);+ const served = client(dir, env);+ expect(await served.done).toBe(0);+ expect(served.stdout()).not.toContain("NOT SERVED");+}, 120_000);++it("sends an impostor that cannot prove the token nothing but its nonce, and runs cold", async () => {+ const env = privateEnv();+ const forged = encodeFrame(Frame.Proof, JSON.stringify({ proof: "0".repeat(64), nonce: "n" }));+ const seen = await impostor(warmCheckEndpoint(env)!.address, forged);+ const cold = client(project(), env);+ expect(await cold.done).toBe(0);+ expect(cold.stdout()).toContain("NOT SERVED");+ expect(seen.frames).toEqual([Frame.Hello]);+}, 120_000);++it("gives up on a silent impostor and runs cold, having sent only its nonce", async () => {+ const env = privateEnv();+ const seen = await impostor(warmCheckEndpoint(env)!.address);+ const cold = client(project(), env);+ expect(await cold.done).toBe(0);+ expect(cold.stdout()).toContain("NOT SERVED");+ expect(seen.frames).toEqual([Frame.Hello]);+}, 120_000);diff --git a/packages/cli/src/warmCheck.ts b/packages/cli/src/warmCheck.tsnew file mode 100644index 0000000000..cde3c0f1b4--- /dev/null+++ b/packages/cli/src/warmCheck.ts@@ -0,0 +1,135 @@+import { randomBytes } from "node:crypto";+import { unlinkSync } from "node:fs";+import { connect, createServer, type Socket } from "node:net";+import { prelaunchBrowserForCheck } from "./commands/check.js";+import "./utils/checkBrowser.js";+import { registerRootExitRequester } from "./utils/commandResult.js";+import {+ Frame,+ encodeFrame,+ envDigest,+ frameForwarder,+ frameReader,+ keyed,+ sameProof,+ warmCheckEndpoint,+ type WarmRequest,+} from "./warmCheckProtocol.js";++const [idleMs = "0", ...checkArgs] = process.argv.slice(2);+const endpoint = warmCheckEndpoint();+if (!endpoint) process.exit(0);+const { address, token } = endpoint;+const startDigest = envDigest(token, process.env);+const exit = process.exit.bind(process);+const idle = setTimeout(() => exit(0), Number(idleMs));+registerRootExitRequester(exit);+let listening = false;+let served: Socket | undefined;++process.on("exit", () => {+ if (listening && process.platform !== "win32") {+ try {+ unlinkSync(address);+ } catch {}+ }+});++const RELAYED_SIGNALS = new Set(["SIGINT", "SIGTERM", "SIGHUP"]);++async function serve(socket: Socket, request: WarmRequest): Promise<void> {+ let finished = false;+ const finish = (code: number) => {+ if (finished) return;+ finished = true;+ server.close();+ listening = false;+ socket.end(encodeFrame(Frame.Exit, String(code)), () => exit(code));+ };+ socket.on("close", () => {+ if (!finished) process.kill(process.pid, "SIGKILL");+ });+ process.stdout.write = frameForwarder(socket, Frame.Stdout);+ process.stderr.write = frameForwarder(socket, Frame.Stderr);+ process.exit = ((code?: number | string | null) =>+ finish(Number(code ?? process.exitCode ?? 0))) as typeof process.exit;+ process.chdir(request.cwd);+ process.argv = [process.execPath, request.script, ...request.argv];+ await import(new URL("./cli.js", import.meta.url).href);+ setImmediate(() => finish(Number(process.exitCode ?? 0)));+}++function decline(socket: Socket, yieldToNewEnvironment: boolean): void {+ socket.end(encodeFrame(Frame.Declined, "declined"), () => {+ if (yieldToNewEnvironment) exit(0);+ });+}++function accept(socket: Socket, request: WarmRequest, nonce: string): void {+ const fresh = !served && sameProof(keyed(token, "client", nonce), request.proof);+ if (!fresh || !sameProof(startDigest, request.envDigest)) return decline(socket, fresh);+ served = socket;+ clearTimeout(idle);+ void serve(socket, request);+}++function parsedRequest(body: Buffer): WarmRequest | undefined {+ try {+ return JSON.parse(body.toString()) as WarmRequest;+ } catch {+ return undefined;+ }+}++function relaySignal(socket: Socket, signal: string): void {+ if (socket === served && RELAYED_SIGNALS.has(signal)) {+ process.kill(process.pid, signal as NodeJS.Signals);+ }+}++function handshake(socket: Socket, nonce: string, type: Frame, body: Buffer): boolean {+ if (type === Frame.Hello) {+ const proof = keyed(token, "server", body.toString());+ socket.write(encodeFrame(Frame.Proof, JSON.stringify({ proof, nonce })));+ return false;+ }+ const request = type === Frame.Request ? parsedRequest(body) : undefined;+ if (request) accept(socket, request, nonce);+ return request !== undefined;+}++const server = createServer((socket) => {+ const nonce = randomBytes(16).toString("hex");+ let accepted = false;+ socket.on("error", () => {});+ const read = frameReader((type, body) => {+ if (type === Frame.Signal) relaySignal(socket, body.toString());+ else if (!accepted) accepted = handshake(socket, nonce, type, body);+ });+ socket.on("data", (chunk: Buffer) => {+ if (!read(chunk)) socket.destroy();+ });+});++function listen(): void {+ server.listen(address, () => {+ listening = true;+ });+}++server.on("error", (error: NodeJS.ErrnoException) => {+ if (error.code !== "EADDRINUSE" || process.platform === "win32") exit(0);+ const probe = connect(address, () => {+ probe.destroy();+ exit(0);+ });+ probe.on("error", () => {+ try {+ unlinkSync(address);+ } catch {}+ listen();+ });+});++listen();+void prelaunchBrowserForCheck(checkArgs).catch(() => undefined);diff --git a/packages/cli/src/warmCheckClient.fixture.ts b/packages/cli/src/warmCheckClient.fixture.tsnew file mode 100644index 0000000000..f01b200bdf--- /dev/null+++ b/packages/cli/src/warmCheckClient.fixture.ts@@ -0,0 +1,3 @@+import { runWarmCheck } from "./warmCheckClient.js";++if (!(await runWarmCheck())) process.stdout.write("NOT SERVED\n");diff --git a/packages/cli/src/warmCheckClient.test.ts b/packages/cli/src/warmCheckClient.test.tsnew file mode 100644index 0000000000..0bd9bee3c6--- /dev/null+++ b/packages/cli/src/warmCheckClient.test.ts@@ -0,0 +1,86 @@+import { mkdtempSync, rmSync } from "node:fs";+import { createServer } from "node:net";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { describe, expect, it, onTestFinished, vi } from "vitest";+import { Frame, encodeFrame, frameReader, keyed } from "./warmCheckProtocol.js";+import { runWarmCheck, warmCheckEligible, warmCheckOutcome } from "./warmCheckClient.js";++describe("warmCheckEligible", () => {+ const argv = ["node", "hyperframes", "check", "."];++ it("hands an agent's check to a warm process", () => {+ expect(warmCheckEligible(argv, {}, false, false)).toBe(true);+ });++ it("keeps terminals, CI, help and other commands cold", () => {+ expect(warmCheckEligible(argv, {}, true, false)).toBe(false);+ expect(warmCheckEligible(argv, {}, false, true)).toBe(false);+ expect(warmCheckEligible(argv, { CI: "true" }, false, false)).toBe(false);+ expect(warmCheckEligible([...argv, "--help"], {}, false, false)).toBe(false);+ expect(warmCheckEligible(["node", "hyperframes", "lint", "."], {}, false, false)).toBe(false);+ });+});++describe("warmCheckOutcome", () => {+ it("takes the warm process's exit code", () => {+ expect(warmCheckOutcome(3, true, undefined)).toEqual({ served: true, exitCode: 3 });+ });++ it("lets the check run cold when the warm process declined before any output", () => {+ expect(warmCheckOutcome(undefined, false, undefined)).toEqual({ served: false });+ });++ it("reports a warm process that stopped mid-output instead of running the check twice", () => {+ expect(warmCheckOutcome(undefined, true, undefined)).toEqual({+ served: true,+ exitCode: 1,+ message: "The warm check process stopped before finishing.\n",+ });+ });++ it("exits like a signalled process when the user interrupted the check", () => {+ expect(warmCheckOutcome(undefined, false, "SIGINT")).toEqual({ served: true, exitCode: 130 });+ });+});++describe("runWarmCheck", () => {+ it("runs cold without connecting anywhere when there is no private endpoint", async () => {+ await expect(runWarmCheck(undefined)).resolves.toBe(false);+ });++ it("delivers every frame the server sends, stdout after stderr included", async () => {+ const dir = mkdtempSync(join(tmpdir(), "hfw-client-"));+ const address =+ process.platform === "win32" ? `\\\\.\\pipe\\${dir.replace(/\W/g, "")}` : join(dir, "s.sock");+ const endpoint = { address, token: "a".repeat(64) };+ const server = createServer((socket) => {+ socket.on(+ "data",+ frameReader((type, body) => {+ if (type !== Frame.Hello) return;+ const proof = keyed(endpoint.token, "server", body.toString());+ socket.write(encodeFrame(Frame.Proof, JSON.stringify({ proof, nonce: "n" })));+ socket.write(encodeFrame(Frame.Stderr, "notice\n"));+ socket.end(+ Buffer.concat([encodeFrame(Frame.Stdout, "{}\n"), encodeFrame(Frame.Exit, "0")]),+ );+ }),+ );+ });+ await new Promise<void>((resolve) => server.listen(endpoint.address, resolve));+ onTestFinished(() => {+ server.close();+ rmSync(dir, { recursive: true, force: true });+ });+ const stdout = vi.spyOn(process.stdout, "write").mockImplementation(() => true);+ const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);+ onTestFinished(() => {+ stdout.mockRestore();+ stderr.mockRestore();+ });+ await expect(runWarmCheck(endpoint)).resolves.toBe(true);+ expect(String(stderr.mock.calls[0]?.[0])).toBe("notice\n");+ expect(String(stdout.mock.calls[0]?.[0])).toBe("{}\n");+ });+});diff --git a/packages/cli/src/warmCheckClient.ts b/packages/cli/src/warmCheckClient.tsnew file mode 100644index 0000000000..28d7efc722--- /dev/null+++ b/packages/cli/src/warmCheckClient.ts@@ -0,0 +1,145 @@+import { spawn } from "node:child_process";+import { randomBytes } from "node:crypto";+import { dirname, join } from "node:path";+import { connect, type Socket } from "node:net";+import { constants } from "node:os";+import { fileURLToPath } from "node:url";+import {+ Frame,+ HANDSHAKE_TIMEOUT_MS,+ WARM_IDLE_MS,+ encodeFrame,+ envDigest,+ frameReader,+ keyed,+ sameProof,+ warmCheckEndpoint,+ type WarmRequest,+} from "./warmCheckProtocol.js";++const distDir = dirname(fileURLToPath(import.meta.url));+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;+const launchEnv = { ...process.env };++export function warmCheckEligible(+ argv = process.argv,+ env = process.env,+ stdoutTTY = process.stdout.isTTY,+ stderrTTY = process.stderr.isTTY,+): boolean {+ return argv[2] === "check" && !stdoutTTY && !stderrTTY && !env.CI && !argv.includes("--help");+}++export function warmCheckOutcome(+ exitCode: number | undefined,+ wrote: boolean,+ signalled: NodeJS.Signals | undefined,+): { served: boolean; exitCode?: number; message?: string } {+ if (exitCode !== undefined) return { served: true, exitCode };+ if (signalled) return { served: true, exitCode: 128 + (constants.signals[signalled] ?? 0) };+ if (!wrote) return { served: false };+ return {+ served: true,+ exitCode: 1,+ message: "The warm check process stopped before finishing.\n",+ };+}++function connected(address: string): Promise<Socket | undefined> {+ return new Promise((resolveSocket) => {+ const socket = connect(address);+ socket.once("connect", () => resolveSocket(socket));+ socket.once("error", () => resolveSocket(undefined));+ });+}++interface ServerProof {+ proof?: unknown;+ nonce?: unknown;+}++function parsedProof(type: Frame, body: Buffer): ServerProof | undefined {+ if (type !== Frame.Proof) return undefined;+ try {+ return JSON.parse(body.toString()) as ServerProof;+ } catch {+ return undefined;+ }+}++export async function runWarmCheck(endpoint = warmCheckEndpoint(launchEnv)): Promise<boolean> {+ if (!endpoint) return false;+ const socket = await connected(endpoint.address);+ if (!socket) return false;+ const nonce = randomBytes(16).toString("hex");+ let trusted = false;+ let wrote = false;+ let signalled: (typeof FORWARDED_SIGNALS)[number] | undefined;+ const relay = (signal: (typeof FORWARDED_SIGNALS)[number]) => {+ signalled = signal;+ if (trusted) socket.write(encodeFrame(Frame.Signal, signal));+ else socket.destroy();+ };+ for (const signal of FORWARDED_SIGNALS) process.on(signal, relay);+ try {+ return await new Promise<boolean>((resolveRun) => {+ let exitCode: number | undefined;+ const sinks = new Map<Frame, NodeJS.WritableStream>([+ [Frame.Stdout, process.stdout],+ [Frame.Stderr, process.stderr],+ ]);+ const handshake = setTimeout(() => socket.destroy(), HANDSHAKE_TIMEOUT_MS);+ const trust = (type: Frame, body: Buffer) => {+ const server = parsedProof(type, body);+ if (!server || !sameProof(keyed(endpoint.token, "server", nonce), server.proof)) {+ socket.destroy();+ return;+ }+ trusted = true;+ clearTimeout(handshake);+ const request: WarmRequest = {+ argv: process.argv.slice(2),+ script: process.argv[1] ?? "",+ cwd: process.cwd(),+ envDigest: envDigest(endpoint.token, launchEnv),+ proof: keyed(endpoint.token, "client", String(server.nonce)),+ };+ socket.write(encodeFrame(Frame.Request, JSON.stringify(request)));+ };+ const read = frameReader((type, body) => {+ if (!trusted) return trust(type, body);+ if (type === Frame.Exit) exitCode = Number(body.toString());+ const sink = sinks.get(type);+ if (!sink) return;+ sink.write(body);+ wrote = true;+ });+ socket.on("data", (chunk: Buffer) => {+ if (!read(chunk)) socket.destroy();+ });+ socket.on("error", () => {});+ socket.on("close", () => {+ clearTimeout(handshake);+ const outcome = warmCheckOutcome(exitCode, wrote, signalled);+ if (outcome.message) process.stderr.write(outcome.message);+ if (outcome.served) process.exitCode = outcome.exitCode;+ resolveRun(outcome.served);+ });+ socket.write(encodeFrame(Frame.Hello, nonce));+ });+ } finally {+ for (const signal of FORWARDED_SIGNALS) process.off(signal, relay);+ }+}++export function startNextWarmCheck(endpoint = warmCheckEndpoint(launchEnv)): void {+ if (!endpoint) return;+ const args = [String(WARM_IDLE_MS), ...process.argv.slice(3)];+ spawn(process.execPath, [join(distDir, "warmCheck.js"), ...args], {+ cwd: process.cwd(),+ env: launchEnv,+ detached: true,+ stdio: "ignore",+ windowsHide: true,+ }).unref();+}diff --git a/packages/cli/src/warmCheckProtocol.test.ts b/packages/cli/src/warmCheckProtocol.test.tsnew file mode 100644index 0000000000..71335b5a1f--- /dev/null+++ b/packages/cli/src/warmCheckProtocol.test.ts@@ -0,0 +1,114 @@+import { chmodSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";+import { join } from "node:path";+import { describe, expect, it, onTestFinished } from "vitest";+import {+ Frame,+ encodeFrame,+ envDigest,+ frameForwarder,+ frameReader,+ warmCheckDirectory,+ warmCheckEndpoint,+} from "./warmCheckProtocol.js";++const TOKEN = "a".repeat(64);++function base(): string {+ const dir = mkdtempSync("/tmp/hfw-proto-");+ onTestFinished(() => rmSync(dir, { recursive: true, force: true }));+ return dir;+}++describe.skipIf(process.platform === "win32")("the warm check endpoint", () => {+ it("lives in a private directory it creates, with a private token", () => {+ const runtime = base();+ const endpoint = warmCheckEndpoint({ XDG_RUNTIME_DIR: runtime });+ expect(endpoint?.address.startsWith(join(runtime, "hyperframes-warm"))).toBe(true);+ expect(endpoint?.token).toMatch(/^[0-9a-f]{64}$/);+ expect(warmCheckEndpoint({ XDG_RUNTIME_DIR: runtime })).toEqual(endpoint);+ });++ it("refuses a directory others can write to, or one that is a symlink", () => {+ const open = base();+ mkdirSync(join(open, "hyperframes-warm"));+ chmodSync(join(open, "hyperframes-warm"), 0o777);+ expect(warmCheckDirectory({ XDG_RUNTIME_DIR: open })).toBeUndefined();+ expect(warmCheckEndpoint({ XDG_RUNTIME_DIR: open })).toBeUndefined();++ const linked = base();+ symlinkSync(base(), join(linked, "hyperframes-warm"));+ expect(warmCheckEndpoint({ XDG_RUNTIME_DIR: linked })).toBeUndefined();+ });++ it("refuses a token file others can read, or one that is a symlink", () => {+ const readable = base();+ mkdirSync(join(readable, "hyperframes-warm"), { mode: 0o700 });+ writeFileSync(join(readable, "hyperframes-warm", "token"), TOKEN, { mode: 0o644 });+ expect(warmCheckEndpoint({ XDG_RUNTIME_DIR: readable })).toBeUndefined();++ const linked = base();+ mkdirSync(join(linked, "hyperframes-warm"), { mode: 0o700 });+ const elsewhere = join(base(), "token");+ writeFileSync(elsewhere, TOKEN, { mode: 0o600 });+ symlinkSync(elsewhere, join(linked, "hyperframes-warm", "token"));+ expect(warmCheckEndpoint({ XDG_RUNTIME_DIR: linked })).toBeUndefined();+ });+});++describe("envDigest", () => {+ it("ignores the shell's per-command variables and unset values", () => {+ expect(envDigest(TOKEN, { A: "1", _: "/x", PWD: "/a", B: undefined })).toBe(+ envDigest(TOKEN, { A: "1", _: "/y", OLDPWD: "/b" }),+ );+ });++ it("tells apart any added, removed or changed variable, and other tokens", () => {+ const digest = envDigest(TOKEN, { A: "1" });+ expect(envDigest(TOKEN, { A: "2" })).not.toBe(digest);+ expect(envDigest(TOKEN, { A: "1", B: "1" })).not.toBe(digest);+ expect(envDigest(TOKEN, {})).not.toBe(digest);+ expect(envDigest("b".repeat(64), { A: "1" })).not.toBe(digest);+ });+});++describe("frames", () => {+ it("decodes frames however the bytes are split", () => {+ const bytes = Buffer.concat([+ encodeFrame(Frame.Stdout, "héllo"),+ encodeFrame(Frame.Exit, "0"),+ encodeFrame(Frame.Stderr, Buffer.alloc(0)),+ ]);+ const seen: [number, string][] = [];+ const read = frameReader((type, body) => seen.push([type, body.toString()]));+ for (const byte of bytes) expect(read(Buffer.from([byte]))).toBe(true);+ expect(seen).toEqual([+ [Frame.Stdout, "héllo"],+ [Frame.Exit, "0"],+ [Frame.Stderr, ""],+ ]);+ });++ it("stops reading at a frame that claims more than the cap", () => {+ const head = Buffer.alloc(5);+ head.writeUInt8(Frame.Stdout, 0);+ head.writeUInt32BE(0xffffffff, 1);+ const read = frameReader(() => {+ throw new Error("no frame expected");+ });+ expect(read(head)).toBe(false);+ expect(read(encodeFrame(Frame.Exit, "0"))).toBe(false);+ });+});++describe("frameForwarder", () => {+ it("hands every write to the socket before returning, so ending the socket loses none", () => {+ const sent: Buffer[] = [];+ const write = frameForwarder({ write: (chunk: Buffer) => sent.push(chunk) > 0 }, Frame.Stdout);+ write("one ");+ write(Buffer.from("two "));+ write("thrée", "utf8");+ const seen: string[] = [];+ frameReader((_type, body) => seen.push(body.toString()))(Buffer.concat(sent));+ expect(seen).toEqual(["one ", "two ", "thrée"]);+ });+});diff --git a/packages/cli/src/warmCheckProtocol.ts b/packages/cli/src/warmCheckProtocol.tsnew file mode 100644index 0000000000..1c46924a59--- /dev/null+++ b/packages/cli/src/warmCheckProtocol.ts@@ -0,0 +1,146 @@+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";+import { lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";+import { homedir } from "node:os";+import { join } from "node:path";+import { Writable } from "node:stream";+import { fileURLToPath } from "node:url";++export const WARM_IDLE_MS = 5 * 60_000;+export const HANDSHAKE_TIMEOUT_MS = 2_000;+const MAX_FRAME_BYTES = 64 * 1024 * 1024;++export const Frame = {+ Stdout: 1,+ Stderr: 2,+ Exit: 3,+ Declined: 4,+ Signal: 5,+ Request: 6,+ Hello: 7,+ Proof: 8,+} as const;+export type Frame = (typeof Frame)[keyof typeof Frame];++export interface WarmRequest {+ argv: string[];+ script: string;+ cwd: string;+ envDigest: string;+ proof: string;+}++export interface WarmEndpoint {+ address: string;+ token: string;+}++const VOLATILE_ENV = new Set(["_", "PWD", "OLDPWD"]);++function privateToMe(path: string, kind: "dir" | "file"): boolean {+ const stat = lstatSync(path, { throwIfNoEntry: false });+ if (!stat || stat.isSymbolicLink()) return false;+ if (kind === "dir" ? !stat.isDirectory() : !stat.isFile()) return false;+ if (process.platform === "win32") return true;+ return stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0;+}++export function warmCheckDirectory(env = process.env): string | undefined {+ const dir =+ process.platform === "win32"+ ? join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "hyperframes", "warm")+ : env.XDG_RUNTIME_DIR+ ? join(env.XDG_RUNTIME_DIR, "hyperframes-warm")+ : join(homedir(), ".cache", "hyperframes", "warm");+ try {+ mkdirSync(dir, { recursive: true, mode: 0o700 });+ } catch {+ return undefined;+ }+ return privateToMe(dir, "dir") ? dir : undefined;+}++function readToken(dir: string): string | undefined {+ const path = join(dir, "token");+ try {+ writeFileSync(path, randomBytes(32).toString("hex"), { flag: "wx", mode: 0o600 });+ } catch {}+ if (!privateToMe(path, "file")) return undefined;+ const token = readFileSync(path, "utf8");+ return /^[0-9a-f]{64}$/.test(token) ? token : undefined;+}++export function keyed(token: string, ...parts: string[]): string {+ return createHmac("sha256", token).update(parts.join("\0")).digest("hex");+}++export function sameProof(expected: string, received: unknown): boolean {+ const a = Buffer.from(expected);+ const b = Buffer.from(typeof received === "string" ? received : "");+ return a.length === b.length && timingSafeEqual(a, b);+}++export function envDigest(token: string, env: Record<string, string | undefined>): string {+ const entries = Object.keys(env)+ .filter((key) => !VOLATILE_ENV.has(key) && env[key] !== undefined)+ .sort()+ .map((key) => `${key}=${env[key]}`);+ return keyed(token, "env", ...entries);+}++export function warmCheckEndpoint(env = process.env): WarmEndpoint | undefined {+ const dir = warmCheckDirectory(env);+ const token = dir && readToken(dir);+ if (!dir || !token) return undefined;+ const self = statSync(fileURLToPath(import.meta.url));+ const build = createHash("sha256")+ .update(+ [import.meta.url, self.size, self.mtimeMs, process.execPath, process.version].join("\0"),+ )+ .digest("hex")+ .slice(0, 12);+ const address =+ process.platform === "win32"+ ? `\\\\.\\pipe\\hyperframes-warm-${keyed(token, "pipe", build).slice(0, 32)}`+ : join(dir, `${build}.sock`);+ return { address, token };+}++export function encodeFrame(type: Frame, data: string | Uint8Array): Buffer {+ const body = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);+ const head = Buffer.alloc(5);+ head.writeUInt8(type, 0);+ head.writeUInt32BE(body.length, 1);+ return Buffer.concat([head, body]);+}++export function frameReader(+ onFrame: (type: Frame, body: Buffer) => void,+): (chunk: Buffer) => boolean {+ let pending = Buffer.alloc(0);+ let refused = false;+ return (chunk) => {+ if (refused) return false;+ pending = Buffer.concat([pending, chunk]);+ while (pending.length >= 5) {+ const length = pending.readUInt32BE(1);+ if (length > MAX_FRAME_BYTES) return !(refused = true);+ if (pending.length < 5 + length) return true;+ onFrame(pending.readUInt8(0) as Frame, pending.subarray(5, 5 + length));+ pending = pending.subarray(5 + length);+ }+ return true;+ };+}++export function frameForwarder(+ socket: { write(frame: Buffer): unknown },+ type: Frame,+): typeof process.stdout.write {+ const sink = new Writable({+ write(chunk: Buffer, _encoding, next) {+ socket.write(encodeFrame(type, chunk));+ next();+ },+ });+ return sink.write.bind(sink) as typeof process.stdout.write;+}diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.tsindex f59bf0e967..eee43faf4c 100644--- a/packages/cli/tsup.config.ts+++ b/packages/cli/tsup.config.ts@@ -15,6 +15,8 @@ export default defineConfig({cli: "src/cli.ts",fontLocalizeCli: "src/fontLocalizeCli.ts",runtimeVersion: "src/runtimeVersion.ts",+ warmCheck: "src/warmCheck.ts",+ warmCheckClient: "src/warmCheckClient.ts",renderSetupWorker: "src/renderSetupWorker.ts",backgroundChecksWorker: "src/backgroundChecksWorker.ts",sherpaWorker: "src/whisper/sherpaWorker.ts",diff --git a/packages/inspector/build.mjs b/packages/inspector/build.mjsindex c38e9037c8..1b5796a22f 100644--- a/packages/inspector/build.mjs+++ b/packages/inspector/build.mjs@@ -2,10 +2,11 @@import { execFileSync } from "node:child_process";import { copyFileSync, readFileSync, rmSync } from "node:fs";import { createRequire } from "node:module";+import { fileURLToPath } from "node:url";import { build } from "esbuild";import { rewriteRelativeImportExtensions } from "../../scripts/rewrite-relative-import-extensions.mjs";-const at = (path) => new URL(path, import.meta.url).pathname;+const at = (path) => fileURLToPath(new URL(path, import.meta.url));const { dependencies } = JSON.parse(readFileSync(at("./package.json"), "utf8"));// Declared dependencies stay imports; the workspace's own sources (core, parsers) are bundled in.const external = Object.keys(dependencies).filter((name) => !name.startsWith("@hyperframes/"));diff --git a/packages/producer/src/plan-parity-harness.ts b/packages/producer/src/plan-parity-harness.tsindex 16f4c40fd5..c73ad5f8db 100644--- a/packages/producer/src/plan-parity-harness.ts+++ b/packages/producer/src/plan-parity-harness.ts@@ -1,5 +1,6 @@import { existsSync, mkdirSync, writeFileSync } from "node:fs";import { resolve } from "node:path";+import { fileURLToPath } from "node:url";import process from "node:process";import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";import { analyzePlanParityDriverResult } from "./plan-parity-analysis.js";@@ -446,8 +447,7 @@ async function main(): Promise<void> {}const isDirectRun =- process.argv[1] !== undefined &&- resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);+ process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);if (isDirectRun) {await main();}diff --git a/scripts/check-cli-process-ownership.mjs b/scripts/check-cli-process-ownership.mjsindex 7bcf948073..1f6a6ffb25 100644--- a/scripts/check-cli-process-ownership.mjs+++ b/scripts/check-cli-process-ownership.mjs@@ -31,12 +31,15 @@ export function listDirectProcessTermination(source, filename = "source.ts") {return issues;}-function listTypeScriptFiles(directory, rootCliPath) {+// Each is the root of its own process: the CLI, the warm check process, and the check client in bin.+const PROCESS_ROOTS = ["cli.ts", "warmCheck.ts", "warmCheckClient.ts"];++function listTypeScriptFiles(directory, roots) {// fallow-ignore-next-line complexityreturn readdirSync(directory).flatMap((name) => {const path = join(directory, name);- if (statSync(path).isDirectory()) return listTypeScriptFiles(path, rootCliPath);- if (!path.endsWith(".ts") || path.endsWith(".test.ts") || path === rootCliPath) return [];+ if (statSync(path).isDirectory()) return listTypeScriptFiles(path, roots);+ if (!path.endsWith(".ts") || path.endsWith(".test.ts") || roots.includes(path)) return [];return [path];});}@@ -44,7 +47,8 @@ function listTypeScriptFiles(directory, rootCliPath) {export function checkCliProcessOwnership(root = ROOT) {const sourceRoot = join(root, "packages/cli/src");if (!existsSync(sourceRoot)) return [];- return listTypeScriptFiles(sourceRoot, join(sourceRoot, "cli.ts")).flatMap((path) =>+ const roots = PROCESS_ROOTS.map((name) => join(sourceRoot, name));+ return listTypeScriptFiles(sourceRoot, roots).flatMap((path) =>listDirectProcessTermination(readFileSync(path, "utf8"), relative(root, path)),);}@@ -57,7 +61,7 @@ function main() {process.exitCode = 1;return;}- console.log("CLI process ownership verified: only cli.ts terminates the process.");+ console.log("CLI process ownership verified: only process roots terminate the process.");}if (process.argv[1] === fileURLToPath(import.meta.url)) main();diff --git a/scripts/file-url-paths.test.mjs b/scripts/file-url-paths.test.mjsnew file mode 100644index 0000000000..1e74f02367--- /dev/null+++ b/scripts/file-url-paths.test.mjs@@ -0,0 +1,21 @@+import assert from "node:assert/strict";+import { execFileSync } from "node:child_process";+import { readFileSync } from "node:fs";+import { join } from "node:path";+import { it } from "node:test";++const ROOT = join(import.meta.dirname, "..");++// A file URL's pathname is "/D:/a/x" on Windows, which opens "D:\D:\a\x".+it("package code turns file URLs into paths with fileURLToPath, not .pathname", () => {+ const files = execFileSync("git", ["ls-files", "packages/*.mjs", "packages/*.ts"], {+ cwd: ROOT,+ encoding: "utf8",+ })+ .split("\n")+ .filter((file) => file && !/\.test\.|\/tests?\//.test(file));+ const offenders = files.filter((file) =>+ /import\.meta\.url\)\.pathname/.test(readFileSync(join(ROOT, file), "utf8")),+ );+ assert.deepEqual(offenders, []);+});