feat: replace arf r-home with arf r resolve

[eitsupi]

arf r-home printed a single path. Editors and agent extensions need more: the binary to spawn, the version, why that version was picked, and any warnings raised along the way. arf r resolve replaces it, always emitting a JSON descriptor.

It groups under a new arf r noun, matching arf config, arf history, and arf ipc. Output is pretty-printed on a terminal and compact when piped, so --json is gone.

{
  "schema_version": 1,
  "resolved": true,
  "cwd": "/project",
  "target": {
    "r_home": "/opt/R/4.5.2/lib/R",
    "r_binary": "/opt/R/4.5.2/lib/R/bin/R",
    "resolved_version": "4.5.2"
  },
  "resolver": { "name": "arf", "version": "0.4.4" },
  "selected_by": {
    "kind": "version_request",
    "requested_r_home": null,
    "requested_version": "4.4",
    "source": {
      "kind": "project_file",
      "name": null,
      "path": "/project/rproject.toml",
      "format": "toml",
      "key": "project.r_version"
    }
  },
  "provider": "rig",
  "diagnostics": []
}

resolver says which tool produced the descriptor, so the resolution could later move behind a separate command without breaking readers. provider says where the install was found. The version is named resolved_version, not r_version, because it is a prediction made before R starts — unlike the versions the IPC layer reports from a running session. target is null exactly when resolved is false, and every key is always present, null when it does not apply.

selected_by separates what was matched on from where that condition came from. kind is r_home, version_request, or default; source says whether it arrived from a command-line argument, an environment variable, a project file, a configuration file, or a built-in default, and carries the specific name — --r-home, ARF_R_VERSION, the file path and key — so a caller can point the user at the exact thing to change. Deliberately absent are arf's own configuration layer names, which would have made renaming a config key a breaking API change, and the evaluation trace of candidates that failed on the way, which is already reported as diagnostics.

Resolution mirrors normal startup rather than being stricter: a config file that fails to load still falls back to defaults and exits zero with a diagnostic, and so does a version merely suggested by a project file. A version requested explicitly on the command line is an error, because startup refuses to continue in that case too — reporting a different R than arf would actually use would defeat the purpose of the command.

Diagnostics carry a stable code, severity, message, and path, assigned where the warning is raised rather than recovered from its text. Codes are an open enum: clients must not reject unknown codes, and message is for display only.

Exit codes follow arf ipc: 0 for success (including a query that finds no R at all), 2 for invalid invocation, 4 for internal failure. Errors are JSON on stderr in the shape the IPC client already uses.

Probing for rig now reports why it failed, so a rig that exists but cannot run is no longer diagnosed as missing — in :switch and override resolution as well as here.

arf r-home was never released, so there is nothing to migrate. Docs and changelog follow separately.

Test plan

• cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test (1079 passed, 0 failed)
• Every kind × source.kind combination checked against real command output
• Project-file fallback and explicit-request failure covered end to end, including ARF_R_VERSION
• Broken config falls back with a diagnostic and exits zero
• Operational failures (malformed rig output, R binary failure, unrunnable rig) report their cause and exit 4
• A relative --r-home appears as one absolute path throughout the descriptor

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR replaces the unreleased arf r-home command with a new machine-facing arf r resolve subcommand that always emits a JSON “resolve descriptor” (pretty on TTY, compact when piped), including selection metadata and structured diagnostics.

Changes:

• Introduces arf r resolve under a new r noun, removes r-home, and updates CLI parsing, help, and shell completions accordingly.
• Adds a new resolve descriptor format (schema v1) with resolver, selected_by, provider, and structured diagnostics; updates config-load warnings and R-source override warnings to carry stable codes and paths.
• Replaces/extends integration tests to cover resolve behavior, exit codes, and fallback/error scenarios.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
crates/arf-console/tests/resolve_tests.rs	New end-to-end tests for arf r resolve JSON descriptor, diagnostics, and exit codes.
crates/arf-console/tests/r_home_tests.rs	Removes r-home tests now that the command is retired.
crates/arf-console/tests/cli_tests.rs	Renames a CLI-scope test to reflect updated flag semantics.
crates/arf-console/src/snapshots/arf__cli__tests__help_long.snap	Updates long help snapshot to show new r command group.
crates/arf-console/src/snapshots/arf__cli__tests__completions_zsh.snap	Updates zsh completion snapshot for arf r resolve and nested help.
crates/arf-console/src/snapshots/arf__cli__tests__completions_powershell.snap	Updates PowerShell completion snapshot for arf r resolve.
crates/arf-console/src/snapshots/arf__cli__tests__completions_fish.snap	Updates fish completion snapshot for arf r resolve.
crates/arf-console/src/snapshots/arf__cli__tests__completions_bash.snap	Updates bash completion snapshot for arf r resolve and nested help.
crates/arf-console/src/main.rs	Wires arf r resolve, adds structured JSON error printing and exit-code mapping for resolve failures.
crates/arf-console/src/cli/resolve.rs	Adds new r noun and resolve subcommand definitions.
crates/arf-console/src/cli/r_home.rs	Removes r-home CLI args type (and --json).
crates/arf-console/src/cli/mod.rs	Swaps RHome for R(resolve::RArgs) and updates CLI parsing tests.
crates/arf-console/src/cli/completions.rs	Ensures r_version completions are applied to headless and r resolve.
crates/arf-console/src/app/setup/rig.rs	Improves rig resolution error wrapping with anyhow::Context.
crates/arf-console/src/app/setup/r_source.rs	Introduces RSourceDiagnostic and switches resolution reports to structured diagnostics.
crates/arf-console/src/app/setup/overrides.rs	Converts override warnings into structured diagnostics with stable codes and optional paths.
crates/arf-console/src/app/setup/mod.rs	Re-exports RSourceDiagnostic alongside existing setup utilities.
crates/arf-console/src/app/resolve.rs	Implements arf r resolve descriptor generation, diagnostics mapping, and resolve-specific JSON errors.
crates/arf-console/src/app/r_home.rs	Removes old r-home implementation.
crates/arf-console/src/app/mod.rs	Replaces r_home module with resolve.
crates/arf-console/src/app/headless.rs	Adapts headless JSON warnings collection to the new diagnostic struct.
crates/arf-console/src/app/config_load.rs	Adds ConfigLoadWarning and a diagnostic-preserving config-load path for resolve output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated no new comments.

Suppressed comments (2)

crates/arf-console/src/app/resolve.rs:283

• With provider always computed from resolution.status, unresolved descriptors (target: null) still get a non-null provider value. If provider is meant to describe the found install, it should be null when resolved is false (and only set when target is present).

            version: env!("CARGO_PKG_VERSION"),
        },
        selected_by,
        provider: provider(&resolution.status),
        diagnostics,

crates/arf-console/src/app/resolve.rs:86

• provider is documented (in the PR description) as “where the install was found”, but the descriptor currently always emits a non-null string even when resolved is false (target is null). That makes provider misleading for unresolved queries and violates the “null when it does not apply” rule used elsewhere in the schema.

Make provider nullable (still always present as a key) so it can be null when unresolved.

This issue also appears on line 279 of the same file.

    resolver: Resolver,
    selected_by: SelectedBy,
    provider: String,
    diagnostics: Vec<Diagnostic>,