hyperframes/packages/cli/src/cli.ts

#!/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 process.exit(0). 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 { 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";

const 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);
}

// Capture treats CWD as project data too: its early loader must use the same
// allowlist/opt-out as output ancestors, before browser selection can observe it.
const { applyDotEnv, CAPTURE_ENV_KEYS } = await import("./utils/dotEnv.js");
// The root has no value-taking options: Citty skips flags up to the first
// positional command, and stops subcommand selection at the -- separator.
const separator = argv.indexOf("--");
const commandArgs = separator < 0 ? argv : argv.slice(0, separator);
const captureEnv = commandArgs.find((arg) => !arg.startsWith("-")) === "capture";
if (!captureEnv || process.env.HYPERFRAMES_NO_CAPTURE_DOTENV !== "1") {
  try {
    const { readFileSync } = await import("node:fs");
    const envPath = resolve(process.cwd(), ".env");
    applyDotEnv(
      readFileSync(envPath, "utf-8"),
      process.env,
      captureEnv ? CAPTURE_ENV_KEYS : undefined,
    );
  } catch {
    /* .env not present — fine, env vars may be set another way */
  }
}

// ── Lazy imports ────────────────────────────────────────────────────────────
// Telemetry, update checks, and heavy modules are imported only when needed.
// For --help we skip telemetry entirely.

import { defineCommand, runCommand } from "citty";
import type { ArgsDef, CommandDef } from "citty";
import { getRunId } from "./telemetry/runId.js";
import { reportCommandFailure, trackCommandFailures } from "./utils/command-failure-tracking.js";
import { isRenderSucceeded } from "./utils/render-success-state.js";
import { resolveCommandUsage } from "./utils/commandUsageResolution.js";
import { isDevMode } from "./utils/env.js";
import {
  CliResultSignal,
  CliRuntimeError,
  CliUsageError,
  consumeCommandResult,
  outputWritten,
  registerRootExitCodeSanitizer,
  registerRootExitRequester,
  type CommandResult,
} from "./utils/commandResult.js";
import { registerRunningCli } from "./utils/runningCli.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<void> {
  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),
  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),
  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),
};

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");

// 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<void> = 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 &&
  !hasJsonFlag &&
  command !== "upgrade" &&
  command !== "events" &&
  command !== "telemetry" &&
  command !== "skills" &&
  command !== "usage"
) {
  // 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 — same gating as the CLI self-update notice.
  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<void> {
  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;
  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 (!hasJsonFlag) {
    _printUpdateNotice?.();
    _printStalePinNotice?.();
    _printSkillsUpdateNotice?.();
  }
  if (_appHistoryNotice) process.stderr.write(`◇  ${_appHistoryNotice}\n`);
  process.exitCode = exitCode;
}

registerRootExitRequester((exitCode) => {
  void finalizeCli({
    exitCode,
    kind: exitCode === 0 ? "success" : "runtime_error",
    presented: true,
  }).finally(async () => {
    await outputWritten();
    process.exit(exitCode);
  });
});

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] Post-render ${label} (render already succeeded): ${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 when the CLI runs under a
// piped agent (Claude Code, Codex, …) — the reader may stop consuming as
// soon as it has what it needs. Exit cleanly, but only score the run as a
// failure when the pipe died BEFORE the render artifact was validated:
// unconditionally setting `commandFailed = true` here marked every piped
// successful render as success:false (0.7.65–0.7.90). Delivery of anything
// still queued (render_complete's eager flush() dies with the process) is
// owned by the unconditional flushSync() in the `exit` handler below.
function handleStreamEpipe(): never {
  if (!isRenderSucceeded()) commandFailed = true;
  process.exit(0);
}

// 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 (isRenderSucceeded()) {
    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 (isRenderSucceeded()) {
    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<T extends ArgsDef>(
  cmd: CommandDef<T>,
  parent?: CommandDef<T>,
): Promise<void> {
  const { showUsage: impl } = await import("./help.js");
  return impl(cmd as CommandDef, parent as CommandDef | undefined);
}

async function showRequestedUsage(): Promise<void> {
  const requested = await resolveCommandUsage(main as CommandDef, argv);
  return showUsage(requested.command, requested.parent);
}

function commandResultForError(error: unknown): CommandResult {
  if (error instanceof CliResultSignal) return error.result;
  if (error instanceof CliUsageError || error instanceof CliRuntimeError) return error.result;
  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<void> {
  let result: CommandResult = { exitCode: 0, kind: "success" };
  try {
    if (isHelp) await showRequestedUsage();
    else await runCommand(main, { rawArgs: argv });
  } catch (error) {
    result = commandResultForError(error);
    if (!(error instanceof CliResultSignal)) {
      commandFailed = true;
      await reportCommandFailure(command, error);
      const typed = error instanceof CliUsageError || error instanceof CliRuntimeError;
      if (error instanceof CliUsageError && !error.result.presented) await showRequestedUsage();
      if (!typed || !error.result.presented) {
        console.error(error instanceof Error ? error.message : String(error));
      }
    }
  } finally {
    const pending = consumeCommandResult();
    if (pending.exitCode !== 0 || result.exitCode === 0) result = pending;
    await finalizeCli(result);
  }
}

await executeCli();