Skip to content

feat(cli): add ctxguard doctor command - #4

Merged
Ismail-Rhoulam merged 2 commits into
mainfrom
feat/doctor-command
Jul 12, 2026
Merged

feat(cli): add ctxguard doctor command#4
Ismail-Rhoulam merged 2 commits into
mainfrom
feat/doctor-command

Conversation

@Ismail-Rhoulam

Copy link
Copy Markdown
Owner

Summary

  • Adds ctxguard doctor [path] [--json], a follow-up to the ctxguard init flow that verifies the local install actually works end to end:
    • ctxguard resolves on PATH (what the hooks registered by ctxguard init invoke at runtime, as opposed to plugin-mode hooks which call python3 directly)
    • the resolved binary's version matches the one running the check (catches stale/shadowed installs)
    • .claude/settings.json has both PreToolUse and SessionStart hooks registered, with the expected matcher
    • .ctxguard.toml parses cleanly if present
    • a real end-to-end invocation of the PreToolUse hook succeeds (not just static checks)
  • Each check reports ok/warn/fail; only fail affects the exit code, so e.g. a missing .ctxguard.toml (defaults apply) or a narrower-than-expected matcher surface as visible warnings without blocking CI.
  • This was flagged as a stretch goal in the original build (closing the gap where a pip install into an unactivated venv silently leaves the hooks unresolvable, since ctxguard fails open by design and won't say anything).

Test plan

  • pytest: 192 passed (10 new tests: nothing-set-up, fully-healthy end-to-end via the real installed binary, narrow-matcher warning, malformed-TOML failure, missing-dir exit code, rich report rendering)
  • Self-scan (ctxguard scan .) returns findings only under tests/fixtures/
  • ruff check clean on changed files
  • Manually verified all three states (nothing set up, fully healthy, warn-only) with both the rich and --json output

Verifies the local install end to end: ctxguard resolves on PATH (what
the hooks registered by `ctxguard init` actually invoke at runtime),
the resolved binary's version matches what's running the check,
.claude/settings.json has both PreToolUse and SessionStart hooks
registered with the expected matcher, .ctxguard.toml parses if present,
and a real invocation of the PreToolUse hook succeeds end to end.

Each check reports ok/warn/fail; only fail affects the exit code (1),
so e.g. a missing .ctxguard.toml (defaults apply) or a narrower-than-
expected matcher don't block CI while still surfacing as visible
warnings. --json for scripting, matching scan's convention.
@Ismail-Rhoulam
Ismail-Rhoulam merged commit ae04d5f into main Jul 12, 2026
5 checks passed
@Ismail-Rhoulam
Ismail-Rhoulam deleted the feat/doctor-command branch July 12, 2026 17:14
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