Jarvy Architecture Guidelines

This skill provides comprehensive architecture guidance for the Jarvy CLI project.

Project Overview

Jarvy is a cross-platform CLI tool that provisions development environments from a jarvy.toml config file using native package managers (Homebrew, apt/dnf, winget).

Directory Structure

jarvy/
├── src/
│   ├── main.rs              # CLI entry point (clap derive macros)
│   ├── lib.rs               # Public re-exports for integration tests
│   ├── config.rs            # jarvy.toml parsing with serde
│   ├── error_codes.rs       # Standardized exit codes
│   ├── analytics.rs         # OpenTelemetry/tracing setup
│   ├── posthog.rs           # PostHog analytics client
│   ├── setup.rs             # Setup command implementation
│   ├── bootstrap.rs         # Bootstrap command implementation
│   ├── init.rs              # Global initialization logic
│   ├── report.rs            # Tool status reporting
│   ├── provisioner.rs       # Core provisioning orchestration
│   ├── tools/
│   │   ├── mod.rs           # Tool module registry and re-exports
│   │   ├── registry.rs      # Global OnceLock<RwLock<HashMap>> registry
│   │   ├── common.rs        # Shared utilities
│   │   ├── _template.rs     # Scaffold template for new tools
│   │   └── {tool}/          # Tool implementations
│   │       ├── mod.rs       # Re-exports the handler
│   │       └── {tool}.rs    # Implementation
│   └── tests/               # Unit test modules
├── tests/                   # Integration tests
├── crates/
│   └── cargo-jarvy/         # Cargo subcommand for scaffolding
└── Cargo.toml

Core Patterns

1. Tool Implementation Pattern

Every tool follows a three-layer architecture:

rust
1// src/tools/{name}/{name}.rs
2
3use crate::tools::common::{InstallError, cmd_satisfies, has, run};
4#[cfg(target_os = "linux")]
5use crate::tools::common::{detect_linux_pm, PkgOps, default_use_sudo};
6
7/// Registry adapter: allows tools::add("{name}", version) to dispatch here
8pub fn add_handler(min_hint: &str) -> Result<(), InstallError> {
9    ensure(min_hint)
10}
11
12/// Main entry: probe first; install if needed
13pub fn ensure(min_hint: &str) -> Result<(), InstallError> {
14    if cmd_satisfies("{binary}", min_hint) {
15        return Ok(());
16    }
17    install()
18}
19
20fn install() -> Result<(), InstallError> {
21    #[cfg(target_os = "macos")]
22    { return install_macos(); }
23    #[cfg(target_os = "linux")]
24    { return install_linux(); }
25    #[cfg(target_os = "windows")]
26    { return install_windows(); }
27    #[allow(unreachable_code)]
28    Err(InstallError::Unsupported)
29}
30
31#[cfg(target_os = "macos")]
32fn install_macos() -> Result<(), InstallError> {
33    if !has("brew") {
34        return Err(InstallError::Prereq("Homebrew not found. Install https://brew.sh"));
35    }
36    run("brew", &["install", "{formula}"])?;
37    Ok(())
38}
39
40#[cfg(target_os = "linux")]
41fn install_linux() -> Result<(), InstallError> {
42    let pm = detect_linux_pm().ok_or(InstallError::Prereq(
43        "No supported package manager (apt/dnf/yum/zypper/pacman/apk)"
44    ))?;
45    let _ = PkgOps::update(pm, default_use_sudo());
46    PkgOps::install(pm, "{package}", default_use_sudo())
47}
48
49#[cfg(target_os = "windows")]
50fn install_windows() -> Result<(), InstallError> {
51    if !has("winget") {
52        return Err(InstallError::Prereq("winget not found"));
53    }
54    run("winget", &["install", "-e", "--id", "{WingetId}"])?;
55    Ok(())
56}

2. Registry Pattern

Tools are registered in a global thread-safe registry:

rust
1// src/tools/registry.rs
2use std::sync::{OnceLock, RwLock};
3use std::collections::HashMap;
4
5pub type ToolAdder = fn(version: &str) -> Result<(), InstallError>;
6
7static REGISTRY: OnceLock<RwLock<HashMap<String, ToolAdder>>> = OnceLock::new();
8
9fn registry() -> &'static RwLock<HashMap<String, ToolAdder>> {
10    REGISTRY.get_or_init(|| RwLock::new(HashMap::new()))
11}
12
13pub fn register_tool(name: &str, handler: ToolAdder) -> bool {
14    let key = name.to_ascii_lowercase();
15    let mut map = registry().write().expect("registry rwlock poisoned");
16    map.insert(key, handler).is_none()
17}
18
19pub fn get_tool(name: &str) -> Option<ToolAdder> {
20    let key = name.to_ascii_lowercase();
21    let map = registry().read().expect("registry rwlock poisoned");
22    map.get(&key).copied()
23}
24
25pub fn add(name: &str, version: &str) -> Result<(), InstallError> {
26    let key = name.to_ascii_lowercase();
27    let map = registry().read().expect("registry rwlock poisoned");
28    if let Some(handler) = map.get(&key) {
29        let f = *handler;
30        drop(map);
31        f(version)
32    } else {
33        Err(InstallError::Parse("unknown tool"))
34    }
35}

3. Error Handling Pattern

Use thiserror for structured errors:

rust
1// src/tools/common.rs
2#[derive(thiserror::Error, Debug)]
3pub enum InstallError {
4    #[error("unsupported platform")]
5    Unsupported,
6    #[error("prerequisite missing: {0}")]
7    Prereq(&'static str),
8    #[error("invalid permissions: {0}")]
9    InvalidPermissions(&'static str),
10    #[error("command failed: {cmd} (code: {code:?})\n{stderr}")]
11    CommandFailed { cmd: String, code: Option<i32>, stderr: String },
12    #[error("io error: {0}")]
13    Io(#[from] std::io::Error),
14    #[error("parse error: {0}")]
15    Parse(&'static str),
16}

4. Platform Detection Pattern

rust
1#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Deserialize, serde::Serialize)]
2#[serde(rename_all = "lowercase")]
3pub enum Os {
4    Linux,
5    Macos,
6    Windows,
7}
8
9pub fn current_os() -> Os {
10    #[cfg(target_os = "linux")]   { Os::Linux }
11    #[cfg(target_os = "macos")]   { Os::Macos }
12    #[cfg(target_os = "windows")] { Os::Windows }
13}
14
15#[cfg(target_os = "linux")]
16pub fn detect_linux_pm() -> Option<PackageManager> {
17    // Returns Apt, Dnf, Yum, Zypper, Pacman, or Apk
18}

5. Configuration Pattern

Support both simple and detailed formats in jarvy.toml:

toml
1[privileges]
2use_sudo = true
3
4[privileges.per_os]
5linux = true
6macos = false
7
8[provisioner]
9# Simple format
10git = "2.40"
11
12# Detailed format
13docker = { version = "24.0", version_manager = true, use_sudo = false }

Parsed with serde untagged enums:

rust
1#[derive(Deserialize)]
2#[serde(untagged)]
3pub enum ToolConfig {
4    Detailed { version: String, version_manager: Option<bool>, use_sudo: Option<bool> },
5    Simple(String),
6}

Adding a New Tool

Step 1: Create the tool directory

bash
1cargo run -p cargo-jarvy -- new-tool {toolname}
2# Or manually:
3mkdir -p src/tools/{toolname}

Step 2: Create mod.rs

rust
1// src/tools/{toolname}/mod.rs
2#![allow(clippy::module_inception)]
3pub mod {toolname};

Step 3: Create the implementation

Use the template in src/tools/_template.rs as a starting point.

Step 4: Register in src/tools/mod.rs

rust
1// Add module declaration
2pub mod {toolname};
3
4// In register_all():
5let _ = register_tool("{toolname}", crate::tools::{toolname}::{toolname}::add_handler);

Common Utilities Reference

Command Execution

rust
1// Run a command and capture output
2run(cmd: &str, args: &[&str]) -> Result<Output, InstallError>
3
4// Run with optional sudo (non-Windows)
5run_maybe_sudo(use_sudo: bool, cmd: &str, args: &[&str]) -> Result<Output, InstallError>
6
7// Check if command exists on PATH
8has(cmd: &str) -> bool
9
10// Check if command output contains version prefix
11cmd_satisfies(cmd: &str, min_prefix: &str) -> bool
12
13// Require command or return error
14require(cmd: &str, remediation: &'static str) -> Result<(), InstallError>
15
16// Require one of multiple commands
17require_any<'a>(candidates: &[&'a str], remediation: &'static str) -> Result<&'a str, InstallError>

Package Manager Operations

rust
1// Update package lists
2PkgOps::update(pm: PackageManager, use_sudo: Option<bool>) -> Result<(), InstallError>
3
4// Install a package
5PkgOps::install(pm: PackageManager, pkg: &str, use_sudo: Option<bool>) -> Result<(), InstallError>

Exit Codes

CLI Structure

Commands defined with clap derive:

rust
1#[derive(Parser)]
2#[clap(name = "jarvy", version, author, about)]
3struct Cli {
4    #[clap(subcommand)]
5    command: Option<Commands>,
6}
7
8#[derive(Subcommand)]
9enum Commands {
10    Setup { #[clap(short, long)] file: String },
11    Bootstrap {},
12    Configure {},
13    Get { file: String, output_format: OutputFormat, output: Option<String> },
14    #[clap(external_subcommand)]
15    External(Vec<String>),
16}

Telemetry Architecture

• PostHog: Product analytics for usage events and errors
• OpenTelemetry: Structured logging via OTLP (HTTP/protobuf)
• Configuration: ~/.jarvy/config.toml with telemetry = true/false
• Environment: JARVY_OTLP_ENDPOINT for custom collectors

Key Dependencies

Conventions

1. Rust Edition: 2024
2. Commit Messages: Conventional Commits (feat:, fix:, docs:, chore:, refactor:, test:)
3. Formatting: Always run cargo fmt --all
4. Linting: cargo clippy --all-features -- -D warnings must pass
5. Dependencies: Prefer stdlib and existing deps over new crates
6. Platform Code: Use #[cfg(target_os = "...")] attributes