feat(v0.6): doctor Settings section with source attribution

Adds a new ── Settings ── block at the bottom of `ctask doctor` (after
the existing tmux INFO line, before the summary). The block reports
every user-level default tracked by the resolver — ctask_root,
project_root, seed_dir, default_agent, default_category, session_mode,
editor — together with the source it was drawn from.

Implementation:

- runDoctor calls config.LoadResolver() once and passes the resolver
  into checkSettings; no setting is re-resolved mid-block (the user's
  correction: "new doctor/info code should load the resolver once and
  reuse it").
- checkSettings prints the config-file lifecycle line first
  (`Config file: <path>` / `Config file: not found — using built-in
  defaults` / `[FAIL] unknown key: "..."` per the resolver's
  ConfigErr state), then iterates the resolver's ResolvedSetting
  accessors and feeds each one through printSettingLine.
- printSettingLine renders the key + value pair plus a `source: …`
  child line. When the resolver chains an Override, the source line
  embeds the overridden source + value in parens. For the
  PlatformOverride session_mode case, an additional
  `configured: <value>` line surfaces what the user asked for.
- formatSettingSource centralises the "EnvVar → CTASK_X env var" /
  "PlatformOverride → ... (persistent mode requires tmux; not
  available on native Windows)" / override-chain wording so doctor
  and info can share the same labels in commit 4.
- Only the invalid-config-file branch increments the failed counter.
  Missing file is INFO. The valid-file branch is purely informational.

Tests (cmd/doctor_settings_test.go, 6 cases):

- TestDoctorShowsSettingsSection — header present + all keys appear
- TestDoctorShowsSourceAttribution — every line has source: + at
  least one "built-in default"
- TestDoctorShowsOverrides — env vs config override chain rendered
- TestDoctorConfigNotFound — INFO, no failed bump
- TestDoctorConfigInvalid — FAIL bump + unknown key named
- TestDoctorSessionModePlatformOverrideRendered — direct value +
  "platform override" label + "configured: persistent" row

Smoke-verified end-to-end against the installed binary:
- no config + no env → all "built-in default"
- env CTASK_AGENT=aider + config default_agent=opencode →
  "CTASK_AGENT env var (overrides config file: opencode)"
- config session_mode=persistent on native Windows → "platform
  override (...)" plus "configured: persistent"
- config with typo "default_agnet: foo" → [FAIL] line names the key
  and the "settings not applied" advisory
This commit is contained in:
2026-05-14 21:55:02 -04:00
parent 0b21b8d3da
commit c918e5ceab
2 changed files with 284 additions and 0 deletions
+105
View File
@@ -207,6 +207,12 @@ func runDoctor(cmd *cobra.Command, args []string) error {
// Check 9: tmux availability for persistent session mode (v0.5.3).
checkTmux(&passed, &failed)
// Check 10: v0.6 — global config file + per-setting source attribution.
// Loaded once and reused across the whole settings block so doctor
// stays internally consistent (no re-reading the config file mid-render).
resolver := config.LoadResolver()
checkSettings(resolver, &passed, &failed)
// Summary
fmt.Println()
fmt.Printf("%d checks passed, %d failed\n", passed, failed)
@@ -259,6 +265,105 @@ func checkSeedDir(label, envValue, resolved, envName string, passed, failed *int
*failed++
}
// checkSettings prints the v0.6 ── Settings ── block. The block shows
// the effective value of every user-level default tracked by the
// resolver, along with the source it was drawn from (built-in default,
// config file, env var, or platform override). When an env var
// overrides a config value, the override line displays both values so
// the user can see what they would inherit if they unset the env.
//
// The block also reports the config-file lifecycle state:
// - not found → INFO line only (no counters bumped)
// - found, valid → INFO line listing the path
// - found, invalid → FAIL line naming the offending key (failed++)
//
// Increments failed only for the invalid-config case. Passed is
// reserved for future per-setting checks (e.g., "ctask_root exists
// and is writable" — currently covered by Check 1).
//
// All values must come from the resolver, never re-read from env or
// disk inside this function — the resolver is the single source of
// truth and was already loaded once by runDoctor.
func checkSettings(r *config.Resolver, passed, failed *int) {
_ = passed // reserved (see doc comment)
fmt.Println()
fmt.Println("── Settings ──────────────────────────────────")
// Config-file lifecycle line.
switch {
case r.ConfigErr != nil:
fmt.Printf("Config file: %s\n", r.ConfigPath)
fmt.Printf(" [FAIL] %s\n", r.ConfigErr)
fmt.Println(" Config file settings not applied — using env vars and built-in defaults only.")
*failed++
case r.ConfigPath != "":
if _, err := os.Stat(r.ConfigPath); err == nil {
fmt.Printf("Config file: %s\n", r.ConfigPath)
} else {
fmt.Printf("Config file: not found — using built-in defaults (%s)\n", r.ConfigPath)
}
default:
fmt.Println("Config file: not found — using built-in defaults")
}
// Per-setting lines. Each line: `<key>: <value>` then a `source:`
// child line. When Override is non-nil the source line names the
// overridden source and value, matching the spec example
// `CTASK_AGENT env var (overrides config file: claude)`.
for _, s := range []config.ResolvedSetting{
r.CtaskRoot(),
r.ProjectRoot(),
r.SeedDir(),
r.DefaultAgent(),
r.DefaultCategory(),
r.SessionMode(),
r.Editor(),
} {
fmt.Println()
printSettingLine(s)
}
}
// printSettingLine renders one ResolvedSetting as a key/value/source
// trio, including override-chain context. Extracted so future settings
// (e.g., per-workspace launch session mode in info) can reuse it.
func printSettingLine(s config.ResolvedSetting) {
fmt.Printf("%s: %s\n", s.Key, s.Value)
fmt.Printf(" source: %s\n", formatSettingSource(s))
if s.Source == config.PlatformOverride && s.Override != nil {
// Spec section 1.8 calls for an extra "configured: <value>"
// row so the user sees what they asked for in addition to
// what's in effect.
fmt.Printf(" configured: %s\n", s.Override.Value)
}
}
// formatSettingSource builds the "source: ..." annotation. The base
// label comes from the SettingSource.String(); env-var sources also
// surface the actual env-var name; PlatformOverride spells out why
// it fired; and when an override chain is present, the next-lower
// source's value is appended in parentheses so doctor renders lines
// like "CTASK_AGENT env var (overrides config file: claude)".
func formatSettingSource(s config.ResolvedSetting) string {
var base string
switch s.Source {
case config.EnvVar:
if s.EnvName != "" {
base = s.EnvName + " env var"
} else {
base = "env var"
}
case config.PlatformOverride:
base = "platform override (persistent mode requires tmux; not available on native Windows)"
default:
base = s.Source.String()
}
if s.Override != nil && s.Source != config.PlatformOverride {
base += fmt.Sprintf(" (overrides %s: %s)", s.Override.Source, s.Override.Value)
}
return base
}
// checkTmux reports the three-state tmux check (v0.5.3):
// - CTASK_SESSION_MODE != "persistent" -> INFO (direct mode, tmux optional)
// - persistent + tmux on PATH + version OK -> two INFO lines