[hlenke]

⚠️ EXPERIMENTAL PROTOTYPE — this is a draft on purpose, and it is completely fine to throw this away. If the gains below are not meaningful enough to justify the added build complexity, close this PR without merging. Nothing depends on it.

Sequencing note: remaining dependencies on #1530 and #1532

#1543 has landed and this branch is rebased on top of it — runtime deps are now 2 (jiti, oxc-parser) and installs no longer pull the ~24 MB typescript peer. Two open PRs still change what this branch should look like when it grows up:

• perf(cli): lazy-load modules most commands don't need at startup #1530 (lazy-load startup imports) pursues the same startup goal at the source level. It composes with this PR: its lazy imports make each command's bundled chunk graph leaner. Almost no file overlap.
• perf(cli): replace warn-if-update-available with a lightweight hook #1532 (lightweight update-check hook) supersedes this branch's folded src/hooks/check-update.ts. If it lands first, this branch should drop that hook and take theirs.

Affected Components

• CLI
• Create CLI
• Test
• Docs
• Examples
• Other

What this does, in plain language

Today, installing the CLI downloads 39 npm packages plus everything those packages depend on — roughly 224 packages, 7,800 files, 95 MB — before the CLI can run. Almost all of that code is ours or is used in exactly one way.

This branch has esbuild (the same bundler the Shopify CLI uses) combine everything into a small number of pre-built files that ship inside the checkly package itself. After that:

• Installing the CLI downloads 3 packages instead of 39 (95 MB → 42 MB of node_modules, most of which is typescript that npm auto-installs as a peer, same as on main).
• Every JS dependency is pinned at build time. A transitive dependency can no longer break or surprise us after release; but it also means security patches in bundled dependencies now require a CLI release. That is a posture change, made deliberately — it is the same conservatism as our 2-day new-version holdback, taken to its conclusion.
• Startup got faster, not slower: the CLI now starts from a small pre-compiled chunk graph instead of resolving hundreds of module files, and bin/run.cjs now enables Node's V8 compile cache so warm runs skip re-parsing the bundle entirely.

One deliberate deviation from the Shopify pattern, with measurements: Shopify uses oclif's "explicit" command strategy — one file importing all commands, which oclif loads eagerly. I built that first; it made every invocation import all 60 command classes, and warm --version regressed 96 ms → 225 ms. So this branch instead gives each command its own bundle entry, with shared code split into chunks by esbuild — running checkly env ls never even parses the mqtt or archiver code. oclif keeps its default lazy command discovery, just pointed at the bundled files. Shopify's bundling without Shopify's startup tax.

Performance numbers

Measured on the same idle macOS machine, from real npm installs of the packed tarballs — both columns on current main (after #1543 landed), p50 of 30 runs:

Metric	main	This branch
npm install, cold cache	5.3 s	1.1 s
node_modules	71 MB / 7,550 files / 220 pkgs	12 MB / 675 files / 5 pkgs
checkly --version warm	74.2 ms	51.8 ms
checkly --help warm	82.7 ms	60.6 ms
Tarball	1.23 MB gz / 1,374 files	1.32 MB gz / 614 files

The tarball is within 8% of main. The bundles are minified (halving them from 7.4 MB to 3.5 MB) with esbuild's keepNames, so class and function names stay readable in stack traces — only local identifiers are mangled. Sourcemaps are not shipped: the split-bundle maps weigh ~13 MB, and Node only applies sourceMappingURL with --enable-source-maps anyway.

Runtime dependencies: 39 → 2. The two that remain each genuinely cannot be bundled:

• oxc-parser — native Rust bindings, resolved per platform
• jiti — lazy-requires its own package files at runtime

(@typescript-eslint/typescript-estree was the third until #1543 landed; it is now a devDependency used only by the parser-parity test, and nothing imports it at runtime.)

@oclif/core, @oclif/plugin-help and @oclif/plugin-warn-if-update-available become devDependencies (bundled in). plugin-help turned out to be fully shadowed: help output is byte-identical without it.

How the build works now

• prepare:dist = tsc --build (still the source of truth for types and .d.ts files) → scripts/bundle.mjs (esbuild).
• oclif's command discovery, hooks and help class keep their original configuration shape, just pointing at dist/bundle/... paths.
• A few files computed paths relative to their own depth in dist/; those now use a small packageRoot() walker (src/services/package-root.ts) so they resolve identically from the bundle, from tsc output, and from source.
• A new CI step (pnpm --filter checkly run startup:check in the lint job) fails the build if --version p50 exceeds a generous 400 ms budget (currently ~50 ms) — so startup regressions from new dependencies fail a check instead of going unnoticed.

Testing done

• Full unit + type suite: 223 files, 4,298 tests, green — including the fixture-sandbox tests that install the packed tarball into real pnpm/yarn/bun projects and drive the bundled CLI.
• 18-case smoke battery byte-identical to the main build: --help/help/topics/-h/-v, unknown-command hook (exit 127), parse-error hook, skills, runtimes, live authenticated API commands (env add/rm, including agent mode), plus ESM and CJS imports of the public API from the installed copy.
• Clean-slate reproducibility: pnpm run prepare (clean → tsc → bundle → AI-context generation) runs end-to-end; the AI-context step itself executes the bundled CLI.
• Local validation is macOS-only. The riskiest remaining unknowns — Windows path handling in packageRoot() and the fixture installs — are exactly what CI on this draft would validate for free (unit + fixture suites run on Windows in CI). That is a big part of why this draft exists.

Known trade-offs / open questions

• Tarball is 8% larger than main (1.32 vs 1.22 MB gz); minified with keepNames, no shipped sourcemaps (see above).
• Bundled-dependency security-patch posture (above).
• e2e suite passed in CI on both platforms (the draft's first run caught a real bundling lesson: esbuild renamed construct classes, breaking the deploy preview — fixed with keepNames).
• src/hooks/check-update.ts (the folded update-check plugin) should be replaced by perf(cli): replace warn-if-update-available with a lightweight hook #1532 when it lands.