Skip to content

Support self-hosted CloudBeat on closed networks in the wizard - #50

Merged
romovs merged 1 commit into
masterfrom
improve/wizard-self-hosted-offline
Oct 21, 2026
Merged

romovs merged 1 commit into
masterfrom
improve/wizard-self-hosted-offline

Conversation

@ndimer

@ndimer ndimer commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

Why

An enterprise customer with a self-hosted CloudBeat on a closed network can only run npm i (from an internal registry). Two problems with the setup wizard there:

  1. An unreachable URL wasn't handled. The wizard asks "cloud or self-hosted?" only on not_logged_in / invalid_api_key. A stored URL that can't be reached (wrong host or port, VPN, proxy, company certificate) returned the generic error, and the wizard had no path for it, so the user was stuck.
  2. The CLI had to be downloaded. The wizard looked for a global cloudbeat-cli, then fell back to npx -y @cloudbeat/cli, which downloads from the npm registry and fails without internet access.

What changes

CLI

  • New error code connection_failed when the API can't be reached at all (no HTTP response): DNS, port, firewall/proxy, TLS certificate. Used by login, whoami and the project commands. The API client keeps only the message of the underlying error, so detection matches the message (isConnectionError / apiErrorCode in src/lib/output.ts).
  • whoami and login failures now include apiBaseUrl, the URL that was used (for not_logged_in, the URL a login would use). The wizard can show it, or offer to keep it, without reading ~/.cloudbeat/config.json, which contains the API key.
  • Clearer message: Could not connect to <url>: <reason> instead of Stored credentials are not valid: ....

Wizard (questions/01-connect.md, reference/cli.md, /cloudbeat-sync)

  • CLI lookup order: the project's own CLI first (npx --no -- cloudbeat-cli, from devDependencies, works offline), then a global install, and npx -y @cloudbeat/cli only as the last resort. The -- is needed: npx --no cloudbeat-cli --version prints npm's own version.
  • On connection_failed: explain the cause (DNS / port / firewall-VPN-proxy via HTTPS_PROXY/NO_PROXY / company certificate authority via NODE_EXTRA_CA_CERTS, never by disabling TLS checks), then ask the instance question again with a third option, "keep <apiBaseUrl>". With a key already stored, no new login is needed once the network is fixed.
  • The login instruction always passes --apiBaseUrl. Without it, login reuses the previously stored URL, so choosing "cloud" after a self-hosted login silently stayed on the self-hosted server.
  • /cloudbeat-sync uses the same connect procedure instead of a bare ! cloudbeat-cli login.

README: per-project installation for closed networks, self-hosted login, certificate and proxy settings, list of error codes.

Compatibility

Additive for login / whoami (new code plus extra field). project create / status / sync used to return error for every API failure. They now return invalid_api_key for HTTP 401 and connection_failed when the server is unreachable. A script that matched code: "error" on those would see the new codes. Suggest releasing as 5.1.0. The version isn't bumped in this PR.

Testing

  • npm test: eslint plus 45 tests, all passing.
    • New test/unit/output.test.js: error classification for 401, network and TLS messages, other HTTP errors.
    • New end-to-end cases in cli.test.js: whoami returns connection_failed with apiBaseUrl; a login to an unreachable URL fails without touching the stored credentials; not_logged_in reports the URL a login would use.
  • Manual end-to-end run:
    • Setup: a scratch project with this branch installed as a devDependency and init --agent claude, plus a stored key pointing at an unreachable URL.
    • Result: /cloudbeat in Claude Code found the project CLI via npx --no -- cloudbeat-cli and explained the ECONNREFUSED failure. It offered cloud / self-hosted / keep URL, noted that no new login is needed for "keep", and didn't read the config file.

Note: .husky/pre-commit isn't executable in the repo, so the hook is skipped on commit (git prints a hint). Lint was run through npm test.

🤖 Generated with Claude Code

- new error code connection_failed when the API URL cannot be reached (DNS,
  port, firewall/proxy, TLS certificate), for login, whoami and project
  commands; 401 from project commands is now reported as invalid_api_key
- whoami and login failures include the apiBaseUrl that was used, so the
  wizard can show it without reading the config file (it holds the API key)
- wizard: on connection_failed, explain the cause and ask the instance
  question again (cloud / self-hosted / keep the current URL); always pass
  --apiBaseUrl to login; /cloudbeat-sync uses the same connect procedure
- wizard: prefer the project's CLI (npx --no -- cloudbeat-cli), then a global
  install, and download with npx -y @cloudbeat/cli only as the last resort
- README: per-project installation for closed networks, self-hosted login,
  certificate and proxy settings, error codes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@romovs
romovs self-requested a review October 21, 2026 16:05
@romovs
romovs merged commit 487695c into master Oct 21, 2026
1 check passed
@romovs
romovs deleted the improve/wizard-self-hosted-offline branch October 21, 2026 16:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants