Skip to content

Write HTML. Render video. Built for agents.

perf(cli): load each command's code only when that command runs (#4656)

Miguel Ángele07ea1fc7033
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 098628b705..23ec23ef9d 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -27,7 +27,8 @@
"build:copy": "node scripts/build-copy.mjs",
"typecheck": "tsc --noEmit",
"gen:skills-manifest": "tsx scripts/gen-skills-manifest.ts",
- "gen:agent-dirs": "tsx scripts/sync-agent-dirs.ts"
+ "gen:agent-dirs": "tsx scripts/sync-agent-dirs.ts",
+ "bench:startup": "node scripts/bench-startup.mjs"
},
"dependencies": {
"@hono/node-server": "^2.0.5",
diff --git a/packages/cli/scripts/bench-startup.mjs b/packages/cli/scripts/bench-startup.mjs
new file mode 100644
index 0000000000..3554ba21ee
--- /dev/null
+++ b/packages/cli/scripts/bench-startup.mjs
@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Times whole CLI runs (spawn to exit) and prints a markdown table of median and p90.
+// Usage: node scripts/bench-startup.mjs <project-dir> [--runs 10] [--cli bin/hyperframes.mjs] [--no-telemetry]
+// Runs with CI=1 (no update check); telemetry stays on unless --no-telemetry, so each run sends real events.
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const { values, positionals } = parseArgs({
+ allowPositionals: true,
+ options: {
+ runs: { type: "string", default: "10" },
+ cli: { type: "string" },
+ "no-telemetry": { type: "boolean", default: false },
+ },
+});
+const project = resolve(positionals[0] ?? ".");
+const runs = Number(values.runs);
+if (!Number.isInteger(runs) || runs < 1) throw new Error("--runs must be a positive integer");
+const cli = resolve(
+ values.cli ?? fileURLToPath(new URL("../bin/hyperframes.mjs", import.meta.url)),
+);
+const env = { ...process.env, CI: "1" };
+if (values["no-telemetry"]) env.HYPERFRAMES_NO_TELEMETRY = "1";
+
+const commands = [["--help"], ["lint", "--help"], ["lint"], ["compositions"], ["info"]];
+// Nearest rank: p90 of 10 runs is the 9th fastest, not the slowest.
+const percentile = (sorted, p) => sorted[Math.ceil(p * sorted.length) - 1];
+
+function timeRun(command) {
+ const start = process.hrtime.bigint();
+ const result = spawnSync(process.execPath, [cli, ...command], {
+ cwd: project,
+ env,
+ stdio: "ignore",
+ });
+ const seconds = Number(process.hrtime.bigint() - start) / 1e9;
+ // A failed run times nothing worth reporting.
+ if (result.status !== 0)
+ throw result.error ?? new Error(`${command.join(" ")} exited ${result.status}`);
+ return seconds;
+}
+
+console.log(`| command | median (s) | p90 (s) |\n|---|---|---|`);
+for (const command of commands) {
+ timeRun(command); // warm-up: fills the OS file cache, not counted
+ const times = Array.from({ length: runs }, () => timeRun(command)).sort((a, b) => a - b);
+ console.log(
+ `| ${command.join(" ")} | ${percentile(times, 0.5).toFixed(2)} | ${percentile(times, 0.9).toFixed(2)} |`,
+ );
+}
diff --git a/packages/cli/scripts/build-copy.mjs b/packages/cli/scripts/build-copy.mjs
index 84c78fd6e1..83e0fbc5c3 100644
--- a/packages/cli/scripts/build-copy.mjs
+++ b/packages/cli/scripts/build-copy.mjs
@@ -102,10 +102,6 @@ async function main() {
join(mediaEngine, "resolve.mjs"),
join(DIST, "skills", "media-use", "scripts", "resolve.mjs"),
);
- mkdirSync(join(DIST, "skills", "registry"), { recursive: true });
- copyDirContents(join(DIST, "registry"), join(DIST, "skills", "registry"));
- mkdirSync(join(DIST, "skills", "media-use", "registry"), { recursive: true });
- copyDirContents(join(DIST, "registry"), join(DIST, "skills", "media-use", "registry"));
const dockerfile = join(CLI_ROOT, "src", "docker", "Dockerfile.render");
if (existsSync(dockerfile)) {
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 9d2541cd70..b2d04f5518 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -26,7 +26,7 @@ for (const stream of [process.stdout, process.stderr]) {
// 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
-// inlined into `cli.js`, but `import.meta.url` resolves to the producer's
+// 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
@@ -279,20 +279,24 @@ if (
// 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);
- }
- });
+ 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;
- });
+ 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(() => {});
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
index e1175ee906..118c34d9c2 100644
--- a/packages/cli/tsup.config.ts
+++ b/packages/cli/tsup.config.ts
@@ -19,14 +19,13 @@ export default defineConfig({
backgroundChecksWorker: "src/backgroundChecksWorker.ts",
sherpaWorker: "src/whisper/sherpaWorker.ts",
shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
- "registry/localSemantic": "src/registry/localSemantic.ts",
},
format: ["esm"],
outDir: "dist",
target: "node22",
platform: "node",
bundle: true,
- splitting: false,
+ splitting: true,
sourcemap: false,
clean: true,
banner: {