mika kuns
d743a9d0e9
Four IEnvironmentCheck implementations in src/ClaudeDo.Installer/Checks/: - ClaudeCliCheck (Error) — resolves ctx.ClaudeBin via ExecutableResolver, runs --version; failure message lists searched PATH entries + fallback dirs, flags shim resolution (.cmd/.ps1) in Detail. - ClaudeVersionCheck (Error) — tolerant version parsing (ignores surrounding text), numeric System.Version comparison against a named floor constant (2.1.220, see docs/explore-notes/installer-preflight.md §3). Unparseable or missing CLI -> Unknown, never Failed. - ClaudeAuthCheck (Error) — `claude auth status --json`, never sends a prompt. - PermissionModeAutoCheck (Warning) — per the note's §2 conclusion, real auto-mode eligibility (org/model/plan) has no cheap static signal, so this only confirms `claude --help` still lists "auto" as a --permission-mode choice. Kept as its own check rather than folded into ClaudeVersionCheck, since the note explicitly separates "flag recognized" from "mode eligible" and only the former is checkable at all. All four share a new ClaudeCliLookup that resolves the CLI and runs --version exactly once per install run (memoized, semaphore-guarded), so none of the three version-dependent checks repeats that call. Foundation prerequisites this task depends on (docs/explore-notes/ installer-preflight.md, ExecutableResolver, the IEnvironmentCheck/CheckResult/ EnvironmentCheckService abstraction, ProcessCommand, IProcessRunner) existed only on an unmerged sibling branch, not on main. Rather than merging that whole unreviewed branch, the specific prerequisite files were copied in as-is (git history shows their origin). GitCheck/GitIdentityCheck/PortCheck/ WriteAccessCheck from that branch were intentionally NOT brought in — out of scope for this task. Deviations/decisions worth flagging: - Added ExecutableResolver.FallbackDirectories() (public) so ClaudeCliCheck can name the checked fallback locations in its failure message; the prior branch kept that list private. - Paths.cs now qualifies System.Environment explicitly. Adding the ClaudeDo.Data.Environment namespace makes bare `Environment.X` inside any ClaudeDo.Data.* namespace resolve to the sibling namespace instead of System.Environment (C# prefers nested/enclosing namespace members over usings) — this broke the build until qualified. Not done (explicitly out of scope): no DI wiring into the wizard UI, no XAML — matches how the prerequisite Git/Port/WriteAccess checks were also left unwired.
50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# Explore-notes
|
|
|
|
Distilled, reusable maps of complex subsystems, produced by deep code exploration.
|
|
The goal: stop re-exploring the same subsystem from scratch in every new session.
|
|
|
|
These sit **between** the CLAUDE.md files and the code:
|
|
|
|
- **CLAUDE.md** — high-level orientation, hand-maintained, always-loaded.
|
|
- **explore-notes** — deeper subsystem detail (flows, who-calls-whom, invariants) that is
|
|
too fine-grained for a CLAUDE.md but stable enough to be worth caching. Read on demand.
|
|
- **code** — the only source of truth.
|
|
|
|
## Index
|
|
|
|
| Note | Covers |
|
|
|---|---|
|
|
| [worker-task-pipeline](worker-task-pipeline.md) | `TaskRunner` end-to-end: config resolution, worktree, CLI invocation, streaming, commit |
|
|
| [usage-monitoring](usage-monitoring.md) | OAuth usage endpoint, gate, throttle, per-run token accounting, usage pill/modal |
|
|
| [external-mcp](external-mcp.md) | The `claudedo` MCP tool surface + its two test-enforced conventions |
|
|
| [review-merge](review-merge.md) | Approve=merge-unit, verify gate, `MergeCommit`/revert, diff stack, conflict resolver |
|
|
| [conpty-sessions](conpty-sessions.md) | Interactive/planning/list-handler launch specs + the arg-flattening gotcha |
|
|
| [installer-preflight](installer-preflight.md) | `--permission-mode auto` eligibility, CLI version floor, login check, .NET runtime requirements |
|
|
|
|
## Rules
|
|
|
|
- **Only stable structure.** Flows, responsibilities, entry points, invariants, relative
|
|
file paths. **No line numbers**, no exhaustive symbol dumps — those rot fastest.
|
|
- **Verify before trusting.** A note is a starting map, not authority. Always confirm
|
|
against current code before acting on it. Each note records the commit it was verified
|
|
against so you can diff for drift.
|
|
- **Not a substitute for CLAUDE.md.** If a fact belongs in orientation, put it there.
|
|
|
|
## Header every note must carry
|
|
|
|
```
|
|
> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
|
|
> Last verified against commit `<short-hash>` (<date>).
|
|
> Drift check: `git log --oneline <short-hash>..HEAD -- <paths this note covers>`
|
|
> Stable structure only (no line numbers). See docs/explore-notes/README.md.
|
|
```
|
|
|
|
## Workflow
|
|
|
|
1. **Before** deep-exploring a subsystem, check for a matching note here and read it first;
|
|
explore only to fill gaps or confirm.
|
|
2. **After** a deep explore, distill the durable findings into a new/updated note and bump
|
|
its "verified against" commit line.
|
|
3. If the drift check shows the covered paths changed a lot since the verified commit, treat
|
|
the note as suspect and re-verify the parts you rely on.
|