[sorccu]

Linear: RED-757

Problem

checkly test, deploy and every other command that loads a project failed with Unable to create a construct '…' outside a Checkly CLI project whenever the running checkly was a different install from the project's own node_modules/checkly. That happens with a global npm i -g checkly, pnpm dlx/pnpx checkly, and npx checkly@<other version>. The project's constructs register with the Session of the checkly the project imports, not the one that is running, and the error says nothing about the real cause.

Change

Any checkly install now behaves like npx checkly in the project's directory. bin/launch.cjs loads .env, then looks for node_modules/checkly upwards from the project's directory, the same search a bare checkly import does. The project's directory is that of the --config/-c file when one is given, as the commands themselves resolve it, and the working directory otherwise. When that is a different install by real path, the launcher runs every command with it, before @oclif/core is even imported. The logic is in src/services/project-cli.ts.

• No per-command metadata: all commands are handed off, including --version and --help, so the project's version decides what is available. The only argument the launcher reads is the config file. It accepts every form oclif does (--config v, --config=v, -c v, -c=v, -cv, and c after boolean short flags in one group, like -pc v) and stops at --. Tests assert that -c means --config on every command, and that the scan's set of boolean short letters matches the commands that take -c, so the scan can ignore which command runs. pnpm symlinks and the project's own npx checkly resolve to the same install and stay in-process.
• Cheap: the outer process skips oclif entirely. A handed-off --version takes about 30 ms longer than running the project's CLI directly.
• How it runs: the project install's bin runs with the same argv and inherited stdio. It gets the .env-merged environment, because installs before 8.0.0 don't load .env themselves. It also gets this process's Node flags, minus inspector flags in execArgv and NODE_OPTIONS. SIGINT, SIGTERM and SIGHUP are forwarded; on Windows the console already delivers Ctrl+C to the child. The outer process exits with the child's exit code, or is killed by the same signal.
• Notice: one line on stderr, only when the versions differ: Using checkly 9.5.0 from this project (node_modules/checkly) instead of checkly 10.0.0. When the invoked CLI is newer, it adds To use 10.0.0, install it in this project.
• Fallbacks:
  • CHECKLY_NO_DELEGATION=1 keeps the command with the invoked CLI.
  • Deno is skipped, because the child would lose the deno run permissions.
  • When the project's install can't be read or started, the command runs in-process with a stderr line.
  • An internal CHECKLY_HANDED_OFF_TO guard stops an install from handing off to itself again, while a nested checkly in another project can still hand off.

localCliNote (the init footer) still recommends npx checkly, but no longer claims a global install cannot load the project. Global installs from before this release still can't.

Testing

• src/services/__tests__/project-cli.spec.ts:
  • unit tests for the install lookup, the hand-off decision and the --config/-c scan, which is checked against oclif's own parser;
  • launcher tests that run the real bin/run.cjs against a fake project install. They cover argv, exit code, the .env env, notice wording, handing off every invocation including from subdirectories, the search starting from a -c file in another package, the opt-out, signal forwarding and signal exits;
  • a regression test that runs debug parse-project from this package in a FixtureSandbox project with its own checkly. It succeeds with the hand-off and fails with the original error under CHECKLY_NO_DELEGATION=1.
• src/services/__tests__/project-cli-spawn-error.spec.ts: fallback when the install can't be started or read.
• Manually, in a project with published checkly@9.5.0: --version and validate from this checkout were handed off, including from a subdirectory.
• Full unit suite passes.

Docs: checkly/docs#593.

🤖 Generated with Claude Code

[github-actions]

Auto-approved: ship/show PR from a same-repo branch.