[sorccu]

Linear: RED-1240

Problem

Unable to create a construct '<X>' outside a Checkly CLI project. also happens when the project's files import a different checkly install than the one running the command. Constructs then register with a Session the running CLI never reads. #1563 hands commands to the project's install to prevent this, but that doesn't help in four cases:

• a global CLI from before the hand-off;
• CHECKLY_NO_DELEGATION=1;
• a project install that can't be read or started;
• Deno.

In those cases the bare message gives no hint of the real cause.

Change

In that case the error keeps its first line and adds an explanation. It names both installs (version and path), says constructs only register with the install that runs the command, and suggests what to do:

Unable to create a construct 'ApiCheck' outside a Checkly CLI project.

The project's files import checkly 9.5.0 from node_modules/checkly, but checkly 10.0.0 from /usr/local/lib/node_modules/checkly runs this command. Constructs only register with the checkly install that runs the command. Run the project's own CLI with `npx checkly` (or your package manager's equivalent, such as `pnpm exec checkly` or `yarn checkly`). CHECKLY_NO_DELEGATION=1 is set, which stops checkly from running the project's install; unset it to let checkly do that.

The advice depends on the case:

• The running CLI predates the hand-off (older than 10.0.0-rc.4): also suggest updating it to 10.0.0 or later.
• CHECKLY_NO_DELEGATION=1 is set on a CLI that can hand off: say so.
• On Deno: say that the hand-off doesn't run there.
• Otherwise: suggest reinstalling the project's dependencies if npx checkly fails too.
• The file imports a different install than the project's directory resolves (for example, a workspace package with its own version): ask for a single checkly install instead of suggesting npx.

Either install can be the older one, so both sides detect it (src/services/two-installs.ts):

• The construct's copy (Session.validateCreateConstruct) explains it when process.argv[1] belongs to another checkly package. This covers an old global CLI running a new project install, because all older CLIs embed the thrown message.
• The running CLI (Session.loadFile) explains it when a file fails with that message from another install. That means an error that isn't its own OutsideProjectError, where the file resolves a different node_modules/checkly. This covers a new CLI running an old project install. The project's install is looked up from the config directory, as the hand-off does.

The explanation appears once. When the running CLI reports it, it throws without the other install's stack or a cause, because oclif prints the cause chain. Diagnosis runs only on the error path, is synchronous, and never throws: anything unexpected keeps today's message.

Also: isSameDirectory in project-cli.ts is now synchronous and shared, and the dev-build version check (isDevelopmentBuild) is shared with baseCommand.ts.

Testing

• src/services/__tests__/two-installs.spec.ts:
  • the advice text per case;
  • the install lookups, including the first-candidate stop rule;
  • both detection sides through Session;
  • the workspace case, where the lookup uses the config directory rather than the workspace root;
  • a launcher run against a fake older install.
• The existing sandbox test (real installs on both sides, opt-out) now expects the explanation exactly once.
• With session.ts reverted, the Session tests fail.
• Manually:
  • published checkly@9.5.0 running a project with this build: explained, including the update advice;
  • this build with CHECKLY_NO_DELEGATION=1 running a project with checkly@9.5.0: explained once, including the opt-out sentence.
• Full unit suite passes.
• Not verified: the running-CLI path (process.argv[1]) under deno run npm:checkly.

🤖 Generated with Claude Code

[github-actions]

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