#!/usr/bin/env node // ── EPIPE suppression (must run before ANY stdout/stderr write) ──────────── // When the CLI runs inside a piped agent environment (Claude Code, Codex, // Cursor, etc.), the reader may close the pipe before we finish writing. // Node treats EPIPE on stdout/stderr as an uncaughtException, which crashes // the process. This is a normal lifecycle event — suppress it. // // commandFailed must be declared here (before the handlers) so the EPIPE // stream-error path can set it before it exits. The telemetry exit // handler reads this flag to determine success/failure — an EPIPE that // interrupts a command should NOT score as success:true, but one that // arrives after the render artifact was validated is the normal agent-pipe // teardown and must stay success:true (see handleStreamEpipe). let commandFailed = false; for (const stream of [process.stdout, process.stderr]) { stream.on("error", (err) => { if ((err as NodeJS.ErrnoException).code === "EPIPE") { handleStreamEpipe(); } }); } // ── Worker entry path bootstrap (must run before any producer/engine load) ── // The shaderTransitionWorkerPool lives in the producer package and resolves // its worker entry by probing for a sibling `.js` file next to // `import.meta.url`. When this CLI is bundled by tsup, the producer code is // bundled into chunks beside cli.js, but `import.meta.url` resolves to the producer's // own dist path (NOT cli.js) on some module-graph layouts — so the sibling // probe lands in a directory that does not contain the bundled worker. // We emit the worker entry next to cli.js (see tsup.config.ts) and tell // the pool where to find it via the published env-var override. import "./utils/hideChildConsoles.js"; import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { existsSync } from "node:fs"; (() => { const here = dirname(fileURLToPath(import.meta.url)); const shader = join(here, "shaderTransitionWorker.js"); if (!process.env.HF_SHADER_WORKER_ENTRY && existsSync(shader)) { process.env.HF_SHADER_WORKER_ENTRY = shader; } })(); // ── Fast-path exits ───────────────────────────────────────────────────────── // Check --version before importing anything heavy. This makes // `hyperframes --version` near-instant (~10ms vs ~80ms). import { VERSION } from "./version.js"; let argv = process.argv.slice(2); if (argv[0] === "help") { process.argv = [...process.argv.slice(0, 2), ...argv.slice(1), "--help"]; argv = process.argv.slice(2); } const commandArg = argv[0]; const rootVersionRequested = commandArg === "--version" || commandArg === "-V" || (commandArg === undefined && (argv.includes("--version") || argv.includes("-V"))); if (rootVersionRequested) { console.log(VERSION); process.exit(0); } // The working directory is project data: load only the settings a project `.env` may supply, // before browser selection can observe the environment. const { loadProjectDotEnv } = await import("./utils/dotEnv.js"); const captureEnv = argv[commandWordIndex(argv)] === "capture"; if (!captureEnv || process.env.HYPERFRAMES_NO_CAPTURE_DOTENV !== "1") { loadProjectDotEnv(process.cwd(), process.env, (line) => console.error(line)); } // ── Lazy imports ──────────────────────────────────────────────────────────── // Telemetry, update checks, and heavy modules are imported only when needed. // For --help we skip telemetry entirely. import { runCommand } from "citty"; import { defineCommand } from "./utils/defineCommand.js"; import type { ArgsDef, CommandDef } from "citty"; import { getRunId } from "./telemetry/runId.js"; import { reportCommandFailure, trackCommandFailures } from "./utils/command-failure-tracking.js"; import { isRenderSucceeded, isRunDelivered, markCommandDelivered, } from "./utils/render-success-state.js"; import { resolveCommandUsage, type ResolvedCommandUsage } from "./utils/commandUsageResolution.js"; import { closestMatch, fileHint, synonymMatch } from "./utils/didYouMean.js"; import { jsonErrorBody, watchOutput, writeJsonFailure } from "./utils/jsonError.js"; import { isDevMode } from "./utils/env.js"; import { CliResultSignal, CliRuntimeError, CliUsageError, USAGE_EXIT_CODE, consumeCommandResult, endProcess, outputWritten, registerRootExitCodeSanitizer, registerRootExitRequester, type CommandResult, } from "./utils/commandResult.js"; import { registerRunningCli } from "./utils/runningCli.js"; import { commandWordIndex, openShortcutArgv } from "./utils/projectShortcut.js"; registerRunningCli(); const isHelp = process.argv.includes("--help") || process.argv.includes("-h"); // Runs before commands/preview.js is imported, so a missing or stale // package is named here instead of crashing deep inside that import. async function assertStudioWorkspaceBuilt(): Promise { if (!isDevMode()) return; const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."); const { checkStudioWorkspaceBuild, formatWorkspaceBuildProblems } = await import("./utils/workspaceBuildCheck.js"); const problems = checkStudioWorkspaceBuild(repoRoot); if (problems.length === 0) return; console.error(formatWorkspaceBuildProblems(problems)); throw new CliRuntimeError("Studio workspace build check failed", { exitCode: 1, presented: true, }); } // --------------------------------------------------------------------------- // CLI definition — all commands are lazy-loaded via dynamic import() // --------------------------------------------------------------------------- const commandLoaders = { init: () => import("./commands/init.js").then((m) => m.default), add: () => import("./commands/add.js").then((m) => m.default), catalog: () => import("./commands/catalog.js").then((m) => m.default), "media-use": () => import("./commands/media-use.js").then((m) => m.default), play: () => import("./commands/play.js").then((m) => m.default), present: () => import("./commands/present.js").then((m) => m.default), preview: () => assertStudioWorkspaceBuilt().then(() => import("./commands/preview.js").then((m) => m.default)), publish: () => import("./commands/publish.js").then((m) => m.default), open: () => import("./commands/open.js").then((m) => m.default), "catch-up": () => import("./commands/catch-up.js").then((m) => m.default), render: () => import("./commands/render.js").then((m) => m.default), lint: () => import("./commands/lint.js").then((m) => m.default), check: () => import("./commands/check.js").then((m) => m.default), beats: () => import("./commands/beats.js").then((m) => m.default), audio: () => import("./commands/audio.js").then((m) => m.default), "normalize-audio": () => import("./commands/normalize-audio.js").then((m) => m.default), inspect: () => import("./commands/inspect.js").then((m) => m.default), keyframes: () => import("./commands/keyframes.js").then((m) => m.default), layout: () => import("./commands/layout.js").then((m) => m.default), info: () => import("./commands/info.js").then((m) => m.default), compositions: () => import("./commands/compositions.js").then((m) => m.default), timeline: () => import("./commands/timeline.js").then((m) => m.default), history: () => import("./commands/history.js").then((m) => m.default), benchmark: () => import("./commands/benchmark.js").then((m) => m.default), browser: () => import("./commands/browser.js").then((m) => m.default), "remove-background": () => import("./commands/remove-background.js").then((m) => m.default), transcribe: () => import("./commands/transcribe.js").then((m) => m.default), usage: () => import("./commands/usage.js").then((m) => m.default), models: () => import("./commands/models.js").then((m) => m.default), tts: () => import("./commands/tts.js").then((m) => m.default), docs: () => import("./commands/docs.js").then((m) => m.default), doctor: () => import("./commands/doctor.js").then((m) => m.default), clean: () => import("./commands/clean.js").then((m) => m.default), upgrade: () => import("./commands/upgrade.js").then((m) => m.default), update: () => import("./commands/update.js").then((m) => m.default), skills: () => import("./commands/skills.js").then((m) => m.default), feedback: () => import("./commands/feedback.js").then((m) => m.default), telemetry: () => import("./commands/telemetry.js").then((m) => m.default), events: () => import("./commands/events.js").then((m) => m.default), validate: () => import("./commands/validate.js").then((m) => m.default), snapshot: () => import("./commands/snapshot.js").then((m) => m.default), "media-treatment": () => import("./commands/media-treatment.js").then((m) => m.mediaTreatmentCommand), "grade-compare": () => import("./commands/grade-compare.js").then((m) => m.default), compare: () => import("./commands/compare.js").then((m) => m.default), diff: () => import("./commands/diff.js").then((m) => m.default), measure: () => import("./commands/measure.js").then((m) => m.default), reverse: () => import("./commands/reverse.js").then((m) => m.default), billing: () => import("./commands/billing.js").then((m) => m.default), templates: () => import("./commands/templates.js").then((m) => m.default), capture: () => import("./commands/capture.js").then((m) => m.default), lambda: () => import("./commands/lambda.js").then((m) => m.default), cloudrun: () => import("./commands/cloudrun.js").then((m) => m.default), cloud: () => import("./commands/cloud.js").then((m) => m.default), auth: () => import("./commands/auth.js").then((m) => m.default), figma: () => import("./commands/figma.js").then((m) => m.default), }; // `hyperframes ` is `hyperframes open `; every later read of the command sees `open`. process.argv = [ ...process.argv.slice(0, 2), ...openShortcutArgv(argv, new Set(Object.keys(commandLoaders))), ]; argv = process.argv.slice(2); const subCommands = Object.fromEntries( Object.entries(commandLoaders).map(([name, load]) => [name, trackCommandFailures(load)]), ); const main = defineCommand({ meta: { name: "hyperframes", version: VERSION, description: "Create and render HTML video compositions", }, subCommands, }); // --------------------------------------------------------------------------- // Telemetry — lazy-loaded, captured references for exit handlers // --------------------------------------------------------------------------- const cliCommandArg = process.argv[2]; // Explicit annotation breaks a type cycle: `subCommands` references `command` // (in the failure reporter) and `command` references `subCommands` (the `in` // check), so its type can't be inferred from its own initializer. const command: string = cliCommandArg && cliCommandArg in subCommands ? cliCommandArg : "unknown"; const hasJsonFlag = process.argv.includes("--json"); // Under --json a failure always answers on stdout with the shared envelope (see executeCli). const jsonOutput = hasJsonFlag ? watchOutput() : undefined; // Captured references — populated when the lazy imports resolve. // Used in exit handlers where dynamic import() is unsafe (beforeExit loops, // exit handler is synchronous-only). let _flushSync: (() => void) | undefined; let _trackCliError: | ((props: { error_name: string; error_message: string; stack_trace?: string; command?: string; kind: "uncaught_exception" | "unhandled_rejection" | "command_error"; }) => void) | undefined; let _trackCommandResult: | ((props: { command: string; success: boolean; exitCode: number; durationMs: number; runId?: string; }) => void) | undefined; let _printUpdateNotice: (() => void) | undefined; let _printStalePinNotice: (() => void) | undefined; let _printSkillsUpdateNotice: (() => void) | undefined; let telemetryReady: Promise = Promise.resolve(); // `events` is a telemetry-internal beacon: it self-tracks + self-flushes, so it // skips the per-command wrapper (no duplicate cli_command, no first-run notice // printed into a skill's captured output). if ( !isHelp && command !== "telemetry" && command !== "events" && command !== "usage" && command !== "unknown" ) { telemetryReady = import("./telemetry/index.js").then((mod) => { _flushSync = mod.flushSync; _trackCliError = mod.trackCliError; _trackCommandResult = mod.trackCommandResult; mod.showTelemetryNotice(); mod.trackCommand(command, runId); if (mod.shouldTrack()) mod.incrementCommandCount(); }); } // `events` skips the update check too — a skill-usage beacon must not add // network latency or trigger a background self-upgrade on the calling skill. // `telemetry` skips it because update metadata must never race the command // that changes the user's telemetry preference. // `skills` is excluded from the SKILLS nudge for the same reason `upgrade` is // excluded from the self-update notice: a command that is itself actively // checking/reconciling skills (`skills check`, `skills update`) must not also // tell the user to go run `skills update` — that's either redundant (it just // did) or, worse, misleading (it printed a stale nudge count from the last // cached check while reporting fresh results of its own). if ( !isHelp && command !== "upgrade" && command !== "update" && command !== "events" && command !== "telemetry" && command !== "skills" && command !== "usage" ) { if (!hasJsonFlag) { // Report any completed auto-install from the previous run first, before // kicking off the next check — so the user sees "updated to vX" once and // we don't over-print. import("./utils/autoUpdate.js").then((mod) => mod.reportCompletedUpdate()).catch(() => {}); import("./utils/updateCheck.js") .then(async (mod) => { _printUpdateNotice = mod.printUpdateNotice; _printStalePinNotice = mod.printStalePinNotice; const result = mod.cachedUpdateCheck(); if (result.updateAvailable) { const auto = await import("./utils/autoUpdate.js").catch(() => null); auto?.scheduleBackgroundInstall(result.latest, result.current); } }) .catch(() => {}); } // Skills freshness nudge: stderr only, so it also runs under --json, which agents pass. import("./utils/skillsUpdateCheck.js") .then((mod) => { _printSkillsUpdateNotice = mod.printSkillsUpdateNotice; }) .catch(() => {}); // The notices read the caches; a detached child refreshes them for the next run. import("./utils/backgroundChecks.js").then((mod) => mod.launchBackgroundChecks()).catch(() => {}); } // A command run on a project the desktop app chatted about since it was last caught up on ends by saying so. let _appHistoryNotice: string | null = null; if (!isHelp && !["unknown", "catch-up", "events", "telemetry"].includes(command)) { import("./utils/appHistory.js") .then((mod) => { _appHistoryNotice = mod.appHistoryNotice(process.cwd(), process.argv.slice(3)); }) .catch(() => {}); } const commandStart = Date.now(); const runId = getRunId(); let finalized = false; // Root-only lifecycle fan-in: telemetry, notices, flushing, then exit code. // fallow-ignore-next-line complexity async function finalizeCli(result: CommandResult): Promise { if (finalized) return; finalized = true; // Once the artifact has validated and been committed to disk, the run // delivered — anything recorded as a failure after that is teardown noise. // The uncaughtException / unhandledRejection handlers already consult // isRenderSucceeded(), but a post-render throw that the command wrapper // CATCHES never reaches them: it becomes an ordinary non-zero // CommandResult, and a valid render is reported as a failure. Sanitizing // here, once, is what those handlers cannot cover, and it keeps the exit // code and the telemetry record from disagreeing about the same run. const exitCode = isRenderSucceeded() ? 0 : result.exitCode; if (exitCode === 0) markCommandDelivered(); commandFailed ||= exitCode !== 0; await telemetryReady.catch(() => {}); _trackCommandResult?.({ command, success: exitCode === 0 && commandSucceededForTelemetry(), exitCode, durationMs: Date.now() - commandStart, runId, }); // No network wait: the exit handler's flushSync() delivers what is still queued. if (result.kind !== "usage_error") printNotices(); process.exitCode = exitCode; } function printNotices(): void { if (!hasJsonFlag) { _printUpdateNotice?.(); _printStalePinNotice?.(); } _printSkillsUpdateNotice?.(); if (_appHistoryNotice) process.stderr.write(`◇ ${_appHistoryNotice}\n`); } registerRootExitRequester((exitCode) => { void finalizeCli({ exitCode, kind: exitCode === 0 ? "success" : "runtime_error", presented: true, }).finally(async () => { await outputWritten(); endProcess(exitCode, { exit: (code) => process.exit(code), setExitCode: (code) => { process.exitCode = code; }, later: setTimeout, }); }); }); registerRootExitCodeSanitizer(() => { if (process.exitCode !== undefined && process.exitCode !== 0) { process.exitCode = 0; } }); // Sync-only: exit handlers cannot await promises or drain microtasks. // _trackCommandResult / _trackCliError are captured references resolved // at init time, so they're callable synchronously here. process.on( "exit", // fallow-ignore-next-line complexity (code) => { if (!finalized) { _trackCommandResult?.({ command, success: code === 0 && commandSucceededForTelemetry(), exitCode: code, durationMs: Date.now() - commandStart, runId, }); } // Unconditional: this is the exit-time delivery for every command (gating it on `finalized` // was the 0.7.65 render_complete loss). Empty queue is a no-op; uuids make re-sends idempotent. _flushSync?.(); }, ); // Report a CLI error event to telemetry. Extracted from the process-error // handlers so their bodies stay simple linear branches (see fallow CRAP // scoring — arrow handlers with inline telemetry calls tip past threshold). function emitCliErrorEvent(kind: "uncaught_exception" | "unhandled_rejection", error: Error): void { _trackCliError?.({ error_name: error.name, error_message: error.message, stack_trace: error.stack, command, kind, }); } // Handle a post-artifact-validated throw: record the diagnostic, emit the // telemetry event, but do NOT mark the run as failed. Field signals: // ts=1784169760, ts=1784171150, ts=1784172467 (all win32/x64, CLI 0.7.58, // ffmpeg=no, 1080x1920, valid MP4s on disk). // The render is valid — a worker teardown / browser shutdown / stray // subprocess stream error after `renderSucceeded` was set must not flip // exit code or telemetry success to failure. function reportPostRenderTerminationEvent( label: "uncaughtException" | "unhandledRejection", kind: "uncaught_exception" | "unhandled_rejection", error: Error, ): void { process.stderr.write( ` [hyperframes] Late ${label} (the command already delivered its result): ${error.message}\n`, ); emitCliErrorEvent(kind, error); } // Terminate the process after a post-artifact-validated throw. Wraps // report + flush + exit(0) so the caller arrow handler doesn't accumulate // optional-chain branches (fallow CRAP scoring on the arrow tips past // threshold otherwise). function exitAfterPostRenderTermination( label: "uncaughtException" | "unhandledRejection", kind: "uncaught_exception" | "unhandled_rejection", error: Error, ): never { reportPostRenderTerminationEvent(label, kind, error); _flushSync?.(); process.exit(0); } // A closed pipe (EPIPE) is the normal teardown under a piped agent: exit without a crash. A run that had not delivered // (a refused or interrupted render) still exits 1, so `| head` cannot turn a failure into success. // The `exit` handler's flushSync() delivers anything still queued. function handleStreamEpipe(): never { const delivered = isRunDelivered(); if (!delivered) commandFailed = true; process.exit(delivered ? 0 : 1); } // Success gate for the cli_command_result telemetry field. `commandFailed` // can be set by pre-artifact noise — a stray unhandledRejection mid-render, // or an EPIPE that fires before validation on a run that still completes. // Once the render artifact has been validated (`isRenderSucceeded()`), that // earlier noise must not score the run as a failure: the run delivered. // Genuine failures keep a non-zero exit code and are caught by the // `exitCode === 0 &&` half of the expression at both call sites. function commandSucceededForTelemetry(): boolean { return !commandFailed || isRenderSucceeded(); } // Terminate the process after a genuine CLI failure — mark commandFailed, // emit telemetry, flush, exit(1). Same rationale as above: keeps the arrow // handler linear so fallow CRAP stays under threshold. function exitAfterCliFailure( kind: "uncaught_exception" | "unhandled_rejection", error: Error, ): never { commandFailed = true; emitCliErrorEvent(kind, error); _flushSync?.(); process.exit(1); } process.on("uncaughtException", (error) => { if ((error as NodeJS.ErrnoException).code === "EPIPE") { handleStreamEpipe(); } // Post-artifact-validated shutdown throws must not turn a valid render // into an exit-1 "no final error message" failure. The render command // sets `renderSucceeded` right after the producer resolves and the // artifact is committed. if (isRunDelivered()) { exitAfterPostRenderTermination("uncaughtException", "uncaught_exception", error); } exitAfterCliFailure("uncaught_exception", error); }); // unhandledRejection does not call process.exit() — Node may continue // running if the rejection is non-fatal (e.g. a fire-and-forget promise). // The exit handler above will still fire with the real exit code. process.on("unhandledRejection", (reason) => { const error = reason instanceof Error ? reason : new Error(String(reason)); // Same rationale as the uncaughtException branch above: a stray promise // rejection during post-artifact-validated cleanup must not mark a valid // render as failed. `commandFailed` gates the success:true telemetry // field — keep it false when the render actually succeeded. if (isRunDelivered()) { reportPostRenderTerminationEvent("unhandledRejection", "unhandled_rejection", error); return; } commandFailed = true; process.exitCode = 1; emitCliErrorEvent("unhandled_rejection", error); }); // Lazy-load help renderer — avoids allocating help data on non-help invocations async function showUsage( cmd: CommandDef, parent: CommandDef | undefined, print: (text: string) => void, ): Promise { const { showUsage: impl } = await import("./help.js"); return impl(cmd as CommandDef, parent as CommandDef | undefined, print); } // Prints the suggestion and the group's usage on stderr; the caller throws the returned error. async function unknownCommandError(requested: ResolvedCommandUsage): Promise { const word = requested.unknownSubcommand ?? ""; const group = ["hyperframes", ...requested.path].join(" "); const declared = requested.command.subCommands; const subCommands = typeof declared === "function" ? await declared() : await declared; const names = Object.keys(subCommands ?? {}); const match = (requested.path.length === 0 ? synonymMatch(word, names) : undefined) ?? closestMatch(word, names); const hint = match ? `Did you mean '${group} ${match}'?` : fileHint(word, requested.path, names); console.error(`Unknown command: ${word}`); if (hint) console.error(hint); console.error(""); await showUsage(requested.command, requested.parent, console.error); return new CliUsageError(`Unknown command: ${word}`, { presented: true, code: "unknown_command", hint, }); } // A group like `timeline` also takes a project directory, so a word it does not know may be one. function takesPositionals(command: CommandDef): boolean { const args = command.args; return ( typeof args === "object" && args !== null && Object.values(args).some((arg) => arg.type === "positional") ); } async function showRequestedUsage(print: (text: string) => void): Promise { const requested = await resolveCommandUsage(main as CommandDef, argv); if (requested.unknownSubcommand && !takesPositionals(requested.command)) { throw await unknownCommandError(requested); } return showUsage(requested.command, requested.parent, print); } // citty would load every command looking for an alias before it gives up on an unknown name. async function rejectUnknownTopLevelCommand(): Promise { const word = argv[0]; if (!word || word.startsWith("-") || Object.hasOwn(subCommands, word)) return; throw await unknownCommandError({ command: main as CommandDef, path: [], unknownSubcommand: word, }); } function isCittyError(error: unknown, code: string): boolean { return ( error instanceof Error && error.name === "CLIError" && (error as { code?: unknown }).code === code ); } // citty's own parse errors (missing argument, bad enum value, unknown or missing subcommand). const CITTY_USAGE_CODES = new Set(["EARG", "E_UNKNOWN_COMMAND", "E_NO_COMMAND"]); function isCittyUsageError(error: unknown): boolean { return [...CITTY_USAGE_CODES].some((code) => isCittyError(error, code)); } function commandResultForError(error: unknown): CommandResult { if (error instanceof CliResultSignal) return error.result; if (error instanceof CliUsageError || error instanceof CliRuntimeError) return error.result; if (isCittyUsageError(error)) return { exitCode: USAGE_EXIT_CODE, kind: "usage_error" }; return { exitCode: 1, kind: "runtime_error" }; } // Root-only command boundary; keeping every result path here prevents modules // from bypassing output, telemetry, or finalizers. // fallow-ignore-next-line complexity async function executeCli(): Promise { let result: CommandResult = { exitCode: 0, kind: "success" }; let failure: unknown; try { if (isHelp) await showRequestedUsage(console.log); else { await rejectUnknownTopLevelCommand(); await runCommand(main, { rawArgs: argv }); } } catch (caught) { const error = isCittyError(caught, "E_UNKNOWN_COMMAND") ? await unknownCommandError(await resolveCommandUsage(main as CommandDef, argv)) : caught; failure = error; result = commandResultForError(error); if (!(error instanceof CliResultSignal)) { commandFailed = true; await reportCommandFailure(command, error); const typed = error instanceof CliUsageError || error instanceof CliRuntimeError; const usage = error instanceof CliUsageError && !error.result.presented; if (usage && !error.hint) await showRequestedUsage(console.error); if (!typed || !error.result.presented) { console.error(error instanceof Error ? error.message : String(error)); } if (usage && error.hint) console.error(error.hint); } } finally { const pending = consumeCommandResult(); if (pending.exitCode !== 0 || result.exitCode === 0) result = pending; if (jsonOutput && result.exitCode !== 0 && !jsonOutput.wroteStdout()) { writeJsonFailure(jsonErrorBody(failure, result, jsonOutput.stderrText())); } await finalizeCli(result); } } await executeCli();