[Bug]: webcmd doctor reports generic "fetch failed" when CloakBrowser binary download is blocked

[adot-7]

Description

Summary

webcmd doctor reports a generic fetch failed error when the CloakBrowser Chromium binary is missing and its automatic download cannot reach the download servers.

The daemon and Cloak runtime appear healthy, which makes the error look like a browser-profile or daemon problem rather than a missing browser binary.

Environment

• OS: Fedora Linux 42
• Node.js: v20.20.2
• Webcmd: v0.5.3
• CloakBrowser: v0.4.5
• Installation: global npm package

Workaround

Using an existing local Chrome installation resolves the problem:

export CLOAKBROWSER_BINARY_PATH=/opt/google/chrome/chrome
webcmd daemon restart
webcmd doctor -v

After applying the workaround:

[OK] Daemon: running on port 9777 (v0.5.3)
[OK] Runtime: cloak connected (v0.4.5)

Profiles:
  • default: connected v0.4.5
[OK] Connectivity: connected in 0.1s

Everything looks good!

External browser navigation and the Reddit adapter also worked afterward.

Suggested improvement

1. Check for the CloakBrowser executable during webcmd doctor.
2. Preserve the original binary download error and attempted URL.
3. Return a specific installation/download error code instead of fetch failed or UNKNOWN.
4. Suggest CLOAKBROWSER_BINARY_PATH as an actionable fallback.
5. Clarify that "runtime connected" does not mean the browser binary is installed and launchable.

Additional observation

Invoking the installed CloakBrowser CLI through its npm symlink produced no output:

node_modules/.bin/cloakbrowser doctor

Invoking its actual script directly worked:

node node_modules/cloakbrowser/dist/cli.js info --quick --json

This appears related to the CLI entry-point check comparing import.meta.url with the unresolved symlink path. It may be a separate CloakBrowser issue, but it made diagnosis harder.

Steps to Reproduce

Start with no CloakBrowser binary installed:

ls ~/.cloakbrowser

The directory is empty.

Use a network where the CloakBrowser and GitHub download endpoints cannot be reached, then run:

webcmd daemon restart
webcmd profile list
webcmd doctor -v

A browser-backed adapter also reproduces it:

webcmd reddit login

Expected Behavior

Expected behavior

Webcmd should preserve and display the underlying CloakBrowser error, for example:

CloakBrowser Chromium is not installed and could not be downloaded.

Download failed from cloakbrowser.dev and GitHub.
Check network access or set CLOAKBROWSER_BINARY_PATH to a compatible local Chromium executable.

The error code should ideally distinguish browser installation/download failures from page fetch failures, such as:

BROWSER_BINARY_MISSING
BROWSER_BINARY_DOWNLOAD_FAILED

webcmd doctor could also check whether the expected CloakBrowser binary exists before attempting the browser connectivity probe.

Actual behavior

webcmd profile list reports:

No Cloak runtime profiles are active.
Run a browser-backed command or webcmd <site> login to create one.

webcmd doctor -v reports:

webcmd v0.5.3 doctor (node v20.20.2)

[OK] Daemon: running on port 9777 (v0.5.3)
[OK] Runtime: cloak connected (v0.4.5)
[FAIL] Connectivity: failed (fetch failed)

Issues:
  • Browser connectivity test failed: fetch failed

webcmd reddit login reports:

ok: false
error:
  code: UNKNOWN
  message: fetch failed
  exitCode: 1

The browser binary expected by CloakBrowser was not installed:

{
  "binary": {
    "path": "~/.cloakbrowser/chromium-146.0.7680.177.5/chrome",
    "installed": false
  }
}

webcmd Version

v0.5.3

Node.js Version

20.x

Operating System

Linux

Logs / Screenshots