Skip to content

G1: Add a comprehensive headless doctor command #194

Description

@SarthakWade

Problem

Runtime checks are spread across startup, the Linux installer, Docker helpers, settings, and error messages. Users and agents cannot run one bounded command to explain why Headless cannot start or which dependency or permission is wrong.

Split from #54 G1. The host-log checks depend on G2.

Contract

  • Add an architecture decision defining checks, output schema, exit status, redaction, and offline behavior.
  • Implement headless doctor as a local CLI command that never launches a browser, changes configuration, repairs files, or contacts the network.
  • Report product and protocol versions, platform, executable resolution, runtime directory safety, socket state, artifact-store safety, default host-log health, FFmpeg availability, browser availability, settings validity, and relevant sandbox constraints.
  • Use structured, bounded JSON with stable check identifiers, severity, status, safe details, and actionable suggestions.
  • Distinguish healthy, warning, unsupported, and failed checks. Exit nonzero only for failures that prevent supported operation.
  • Never expose environment values, credentials, cookies, storage, page data, usernames embedded in URLs, or arbitrary file contents.
  • Handle a running host without disrupting it and detect stale or unsafe socket state without deleting anything.

Acceptance criteria

  • Healthy macOS and Linux installations return a deterministic successful report.
  • Missing browser, missing FFmpeg, unsafe runtime permissions, stale socket, corrupt settings, and unavailable host logs produce the correct bounded findings.
  • The command is read-only and works offline with no browser process launch.
  • Unknown arguments fail closed.
  • Output stays below the protocol framing budget even though the command is local.
  • CLI help, command docs, shell tests, and unit tests cover happy and failure paths.
  • Existing startup behavior remains unchanged.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:cliCLI parser, help, capabilitiespriority:mediumScheduled, not blockingtype:featureNew capability or command

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions