Skip to content

Add autter doctor end-to-end setup validation command - #51

Merged
sagnik11 merged 2 commits into
mainfrom
posthog/autter-doctor-command
Aug 18, 2026
Merged

Add autter doctor end-to-end setup validation command#51
sagnik11 merged 2 commits into
mainfrom
posthog/autter-doctor-command

Conversation

@sagnik11

Copy link
Copy Markdown
Member

What

New autter doctor command: one-command setup validation that answers "is autter actually capturing and attributing right now?" — including validating a real checkpoint event end-to-end (checkpoint → daemon → working log → commit → attribution).

Requested by Alan and Kanka (and implicitly Mayank): a doctor/validation command to identify missing hooks, invalid configuration, and service/connectivity failures. Built as a focused presentation layer over the existing diagnostics.rs + install-hooks installer primitives rather than a new check framework.

Checks

Section Checks
Setup git binary + minimum version (configured and terminal git), config-file parse, repository allow/exclude eligibility
Background service daemon readiness + real trace2 ingestion probe (auto-starts/restarts stale daemons)
Git capture (trace2) trace2 global config for both gits, trace2 file self-check
End-to-end checkpoint real human/mock_known_human/mock_ai checkpoints in a scratch repo, committed, attribution verified via blame — skipped with a pointer when the service check already failed
AI agent hooks per-agent installed/up-to-date status from the install-hooks installers; VS Code ≥ 1.109.3 native-hooks chain (hook file + chat.useHooks + chat.hookFilesLocations) refactored out of debug.rs for reuse; undetected agents collapse to one line
Account & sync auth state — an expired session fails loudly since sync silently no-ops when unauthenticated; API reachability probe (only when authenticated, so it never fires in tests/air-gapped local-only use)

UX / contract

  • One ✓ / ⚠ / ✗ / - line per check; every failure gets a concrete fix: line (failure details + command logs stay available in autter debug).
  • Exit code: 0 when no check fails (warnings allowed), 1 otherwise — unlike autter debug, which stays a full always-exit-0 support dump.
  • --json: stable single-line machine-readable report (checks[], summary, ok) for CI/scripts.
  • --skip-trace2-checks mirrors the debug flag (the file self-check briefly rewrites global git config).
  • Broken-install error paths (suggest_autter_debug) now point users at autter doctor; shared remediation strings updated likewise.

Why the config-file check matters

The runtime load path silently falls back to defaults when ~/.autter/config.json is malformed — a typo disables every setting with zero signal. Doctor is now the place that failure mode becomes visible (it reuses the error-propagating load_file_config_public() path).

Tests

  • Unit tests for status mapping, summary counting, and JSON shape.
  • Integration tests (tests/integration/doctor.rs): full end-to-end pass — the test writes the trace2 global config autter install would write (pointed at the per-test daemon socket) and asserts the checkpoint round-trip check passes, plus JSON/summary/exit-code consistency, unknown-flag rejection, and --skip-trace2-checks. Connectivity is asserted skipped so tests never touch the network.

Manually smoke-tested in a fully isolated env (HOME/gitconfig/daemon dir): misconfigured trace2 renders the expected failures + fixes; correctly configured env passes the full round-trip; --json and --help verified.


Created with PostHog Desktop

`autter debug` is a full support dump: it always exits 0 and buries
failures in ~200 lines of report, so users have no one-command way to
answer "is autter actually working right now?". `autter doctor` closes
that gap with a focused pass/warn/fail report built on the existing
diagnostics primitives:

- Setup: git binary/version, config-file parse (surfacing the silently
  ignored malformed ~/.autter/config.json), repository allow/exclude
  eligibility
- Background service: daemon readiness + real trace2 ingestion probe
- Git capture: trace2 global config for both configured and terminal
  git, plus the trace2 file self-check
- End-to-end checkpoint: a real checkpoint event through checkpoint ->
  daemon -> working log -> commit -> attribution (skipped with a
  pointer when the service check already failed)
- AI agent hooks: per-agent install/up-to-date status via the
  install-hooks installers, including the VS Code >= 1.109.3 native
  hooks chain (refactored out of debug.rs for reuse)
- Account & sync: auth state (expired sessions fail loudly since sync
  silently no-ops) and an API reachability probe when authenticated

Every failure prints a concrete `fix:` line. Exits 0 when nothing
failed (warnings allowed), 1 otherwise; `--json` emits a stable
machine-readable report for CI/scripts. Error paths that previously
suggested `autter debug` now point at `autter doctor`; debug remains
unchanged as the deep support dump.

Generated-By: PostHog Desktop
Task-Id: c84ac9ce-31cc-4e70-8451-62857be00f1c
@sagnik11
sagnik11 merged commit 3e66c82 into main Aug 18, 2026
1 check passed
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.

1 participant