Merge branch 'claudedo/852c2328ec8b4fc1bf143df203e1dc6c'
This commit is contained in:
mika kuns
@@ -19,7 +19,7 @@ These sit **between** the CLAUDE.md files and the code:
|
||||
| [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 |
|
||||
| [installer-preflight](installer-preflight.md) | CLI version/login/auto-mode research, the `ExecutableResolver`/shim root cause, and the Installer's `Checks/`+`SystemCheckPage` implementation status |
|
||||
|
||||
## Rules
|
||||
|
||||
|
||||
@@ -2,9 +2,43 @@
|
||||
|
||||
> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
|
||||
> Last verified against commit `bdee731` (2026-08-05).
|
||||
> Drift check: `git log --oneline bdee731..HEAD -- src/ClaudeDo.Worker/Lifecycle/ClaudeCliPreflight.cs src/ClaudeDo.Worker/ClaudeDo.Worker.csproj src/ClaudeDo.App/ClaudeDo.App.csproj .gitea/workflows/release.yml`
|
||||
> Drift check: `git log --oneline bdee731..HEAD -- src/ClaudeDo.Worker/Lifecycle/ClaudeCliPreflight.cs src/ClaudeDo.Worker/ClaudeDo.Worker.csproj src/ClaudeDo.App/ClaudeDo.App.csproj .gitea/workflows/release.yml src/ClaudeDo.Installer/Checks src/ClaudeDo.Data/Environment/ExecutableResolver.cs`
|
||||
> Stable structure only (no line numbers). See docs/explore-notes/README.md.
|
||||
|
||||
## Implementation status (as of 2026-08-05)
|
||||
|
||||
The research below (§1–5) led to an implementation, but it is **not on `main` yet** — it exists
|
||||
on two unmerged task branches:
|
||||
|
||||
- `claudedo/06aca9b3afec4b939f59b627bfe21737` — `src/ClaudeDo.Installer/Checks/*`
|
||||
(`GitCheck`, `GitIdentityCheck`, `WriteAccessCheck`, `PortCheck`, `ClaudeCliCheck`,
|
||||
`ClaudeVersionCheck`, `ClaudeAuthCheck`, `PermissionModeAutoCheck`, `EnvironmentCheckService`,
|
||||
`ClaudeCliLookup`) plus `SystemCheckPage` (the Fresh-Install wizard page hosting them) and its
|
||||
own copy of `src/ClaudeDo.Data/Environment/ExecutableResolver.cs`.
|
||||
- `claudedo/40272c0bb3b14562b59c022d09c382b6` — the original `ExecutableResolver.cs`, plus wiring
|
||||
it into `ClaudeDo.Worker`'s `ClaudeCliPreflight` and `ClaudeProcess` (the actual root-cause fix:
|
||||
both used to spawn `claude` with `UseShellExecute = false` and no `.cmd`/`.bat` shim resolution,
|
||||
so an npm-installed `claude.cmd` was invisible to the Worker even though it worked in a shell).
|
||||
|
||||
The two branches were authored independently and each vendored its own copy of
|
||||
`ExecutableResolver.cs` (identical except `06aca9b3` adds a `FallbackDirectories()` diagnostic
|
||||
helper); merging both cleanly requires picking one copy, not literally running `git merge` twice.
|
||||
Two planned follow-up tasks — a "Claude Help Me" button and a Config-mode Diagnose section —
|
||||
never got past a blocked first step, precisely because this prerequisite work wasn't on `main`
|
||||
when they ran. See `Environment Checks` in `src/ClaudeDo.Installer/CLAUDE.md` and `docs/open.md`
|
||||
for the current gap and the manual verification checklist.
|
||||
|
||||
What's confirmed as **matching the research below**: `ClaudeVersionCheck.MinimumVersion` is
|
||||
`2.1.220`, exactly the "verified-floor, not a proven minimum" constant from §3. `ClaudeAuthCheck`
|
||||
uses `claude auth status --json` exactly as recommended in §4, parsing only the `loggedIn` field.
|
||||
`PermissionModeAutoCheck` is the static "is `auto` listed in `--help`" check recommended in §2 —
|
||||
real org/model/plan eligibility is deliberately **not** checked, matching the recommendation not
|
||||
to build that (a real task run surfaces a startup rejection fast enough on its own). No .NET
|
||||
Desktop Runtime check was implemented as an `IEnvironmentCheck` (§5's registry-key detection
|
||||
remains a documented-but-unbuilt option, not currently gating anything).
|
||||
|
||||
---
|
||||
|
||||
Pure research, no code changed. Answers the five questions from the "Root Cause
|
||||
`--permission-mode auto`" task. Sources: the locally installed CLI (`claude --version` /
|
||||
`--help`), the official docs at `code.claude.com` (fetched 2026-08-05), and this repo's own
|
||||
@@ -89,6 +123,7 @@ and still requires a working prompt/response round trip on the happy path. **Rec
|
||||
don't build this into an automated preflight; a static version+flag check plus `auth status`
|
||||
covers the reliably-detectable ground, and a real first task run will surface an auto-mode
|
||||
rejection immediately and cheaply (fails at startup, not mid-task) if it's actually unavailable.
|
||||
**Implemented as:** `PermissionModeAutoCheck` (Warning) — the static flag-listed check only.
|
||||
|
||||
## 3. Minimum CLI version for the flags ClaudeDo uses
|
||||
|
||||
@@ -123,6 +158,7 @@ What **is** sourced, from the docs fetched 2026-08-05:
|
||||
**Decided constant** (see below) is therefore **the newest version we can positively confirm
|
||||
works end-to-end on this machine** (`2.1.220`), not a proven theoretical minimum — because no
|
||||
lower true minimum is derivable from available sources without guessing.
|
||||
**Implemented as:** `ClaudeVersionCheck.MinimumVersion = new Version(2, 1, 220)` (Error).
|
||||
|
||||
## 4. Detecting "CLI is logged in" without sending a prompt
|
||||
|
||||
@@ -137,6 +173,8 @@ for this task's own tooling; the docs page confirms it lives at
|
||||
`%USERPROFILE%\.claude\.credentials.json` on Windows but say nothing about its schema being a
|
||||
stable public contract). `claude auth status --text` is available for a human-readable variant;
|
||||
`--json` is the default and the right one for a preflight to parse.
|
||||
**Implemented as:** `ClaudeAuthCheck` (Error) — parses only the `loggedIn` boolean; any other
|
||||
field, or a non-zero exit code, or unparseable JSON, becomes `Unknown` rather than `Failed`.
|
||||
|
||||
## 5. .NET runtimes required by the published `app\` / `worker\` artifacts
|
||||
|
||||
@@ -171,6 +209,9 @@ csproj files:
|
||||
live (would require reading `HKLM\SOFTWARE\dotnet\...` on this machine, which is standard
|
||||
.NET installer-detection convention, but out of scope to screenshot/dump here since the task
|
||||
is docs-only and this is a well-documented, non-project-specific Windows convention).
|
||||
**Not implemented** as an `IEnvironmentCheck` — none of the shipped checks verify the Desktop
|
||||
Runtime; if the Installer itself is running at all, .NET 8 Desktop Runtime is implicitly
|
||||
present (framework-dependent publish would otherwise fail to launch).
|
||||
|
||||
## Beschlossene Konstanten
|
||||
|
||||
@@ -184,14 +225,18 @@ csproj files:
|
||||
|
||||
## Erkennungsstrategie pro Check
|
||||
|
||||
| Check | Type | Command | Expected pass output |
|
||||
|---|---|---|---|
|
||||
| CLI present + version | static | `claude --version` | `X.Y.Z (Claude Code)`; parse and compare `X.Y.Z >= 2.1.220` |
|
||||
| `auto` recognized as a flag value | static | `claude --help` (or trigger the parse error path) | `--permission-mode <mode>` help text lists `auto` among the choices |
|
||||
| CLI logged in | static/cheap | `claude auth status --json` | exit 0, `loggedIn: true` |
|
||||
| Auto mode actually eligible (org/model/plan) | **not statically detectable** | none exists | N/A — see §2; don't build this, let a real task run surface a fast startup rejection instead |
|
||||
| .NET Desktop Runtime present (installer only) | static | `dotnet --list-runtimes` (if `dotnet` on PATH) or registry `HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x64\sharedfx\Microsoft.WindowsDesktop.App` | a `Microsoft.WindowsDesktop.App 8.0.x` entry exists |
|
||||
| App/Worker runtime present | **not needed** | — | self-contained, nothing to check |
|
||||
| Check | Type | Command | Expected pass output | Implemented as |
|
||||
|---|---|---|---|---|
|
||||
| git present + version | static | `git --version` (via `ExecutableResolver`) | resolves, exit 0 | `GitCheck` (Error) |
|
||||
| git identity set | static | `git config --get user.name` / `user.email` | both non-empty | `GitIdentityCheck` (Warning) |
|
||||
| install dir + data dir writable | static | probe-file write/delete | succeeds | `WriteAccessCheck` (Error) |
|
||||
| SignalR/ExternalMcp ports free | static | `TcpListener` bind probe + owning-process lookup | free, or owned by running `ClaudeDo.Worker` | `PortCheck` (Warning) |
|
||||
| CLI present + version | static | `claude --version` | `X.Y.Z (Claude Code)`; parse and compare `X.Y.Z >= 2.1.220` | `ClaudeCliCheck` (Error) / `ClaudeVersionCheck` (Error) |
|
||||
| `auto` recognized as a flag value | static | `claude --help` (or trigger the parse error path) | `--permission-mode <mode>` help text lists `auto` among the choices | `PermissionModeAutoCheck` (Warning) |
|
||||
| CLI logged in | static/cheap | `claude auth status --json` | exit 0, `loggedIn: true` | `ClaudeAuthCheck` (Error) |
|
||||
| Auto mode actually eligible (org/model/plan) | **not statically detectable** | none exists | N/A — see §2; don't build this, let a real task run surface a fast startup rejection instead | not implemented (by design) |
|
||||
| .NET Desktop Runtime present (installer only) | static | `dotnet --list-runtimes` (if `dotnet` on PATH) or registry `HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x64\sharedfx\Microsoft.WindowsDesktop.App` | a `Microsoft.WindowsDesktop.App 8.0.x` entry exists | not implemented (see §5) |
|
||||
| App/Worker runtime present | **not needed** | — | self-contained, nothing to check | not implemented (not needed) |
|
||||
|
||||
## Not verifiable (explicit)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user