Skip to content

feat(cli): add read-only doctor diagnostics - #198

Merged
SarthakWade merged 1 commit into
feat/193-private-host-logsfrom
feat/194-headless-doctor
Sep 19, 2026
Merged

SarthakWade merged 1 commit into
feat/193-private-host-logsfrom
feat/194-headless-doctor

Conversation

@SarthakWade

Copy link
Copy Markdown
Collaborator

Summary

  • add headless doctor with a deterministic, bounded JSON report and stable check identifiers
  • inspect executable, browser runtime, FFmpeg, private runtime/socket, artifacts, settings, host logs, and Linux sandbox readiness without repairing or deleting state
  • distinguish healthy, warning, unsupported, and blocking failures with actionable guidance and strict exit status
  • document the contract in ADR 30, CLI help, command reference, and the roadmap backlog

Security

  • remains local and offline and never launches a browser
  • performs read-only filesystem inspection plus the existing non-disruptive host ping
  • reports controlled messages without environment values, paths, credentials, page data, or file contents
  • detects unsafe ownership, modes, links, stale sockets, corrupt settings, and unsafe log companion files

Verification

  • pnpm test
  • pnpm test:runtime
  • pnpm --filter @headless/web lint
  • pnpm --filter @headless/app build
  • Linux release protocol suite in Docker: 69/69 passed
  • Linux Chromium E2E on the provisioned test image: passed

The standard Docker rebuild reached and passed the Linux protocol suite, then Docker Desktop could not reach deb.debian.org while rebuilding the test-dependency layer. The identical E2E script passed after layering the current binaries over the existing provisioned image.

Closes #194

@SarthakWade
SarthakWade added this pull request to stack #202 September 19, 2026 09:58

@yashranaway yashranaway left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doctor is a local CLI command, not on the socket. MCP already drops invocations without a protocol request, so agents cannot run it that way.

Checks are read-only: lstat of owned 0700/0600 paths, Chromium/ffmpeg discovery, settings parse, and a 0.5s ping only if the socket is inside the runtime directory with a safe mode. It does not start a host, repair files, or dump file contents. Details and suggestions are capped at 512 bytes. Missing optional tools are warnings; unsafe storage and root on Linux are failures.

CI is green. Stacks on #197.

@SarthakWade
SarthakWade merged commit 49f1b91 into main Sep 19, 2026
16 checks passed
@SarthakWade
SarthakWade deleted the feat/194-headless-doctor branch September 19, 2026 11:20
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.

G1: Add a comprehensive headless doctor command

2 participants