jan-cli 0.16.0

# Architecture

```mermaid
flowchart TD
  cli[jan CLI / clap] --> use{first token}
  use -->|use| cfg[XDG config.json]
  use -->|other builtins| builtins[bundle alias list search show validate audit cron packages test]
  use -->|YAML command| match[match_commands]
  match --> help[format_help]
  match --> run[run_matched]
  cfg --> load[load_spec]
  load --> yaml[spec_load + include closure]
  yaml --> remote[HTTPS fetch + sha256 cache]
  run --> deps[env / PATH / requires / inputs]
  run --> pkgs[packages uv pnpm gradle]
  run --> spawn[Command::new]
  spawn --> sqlite[audit.db]
```

## Modules (`src/`)

| Module | Responsibility |
|--------|----------------|
| `runner.rs` | Clap globals, dispatch to builtins vs matched leaves |
| `config.rs` | `jan use` preference (`jan_dir`, `spec_root`, remote source) |
| `spec_load.rs` | YAML load, platform filter, include graft, path confinement |
| `yaml_closure.rs` | Reachable local files for `jan bundle` |
| `lib.rs` | `RootSpec` / `CommandNode` / `ExecSpec` types, help, match, spawn, audit schema |
| `deps.rs` | Chain env, `pass`, PATH prefixes, `requires`, argv[0] resolution |
| `inputs.rs` | Typed flags and `${{ inputs.* }}` |
| `packages.rs` | Ensure / inspect / prune uv, pnpm, gradle envs; language argv helpers |
| `remote.rs` | HTTPS fetch, TTL cache, bundle unpack |
| `cron.rs` | Five-field expression matching |
| `cmdtest.rs` | `jan test` harness |
| `inspect.rs` | list / search / show / validate / audit / cron CLI |
| `builtins.rs` | use / bundle / alias |

The binary entry is `src/bin/jan.rs` → `jan_cli::run_jan()`.

## Trust and spawn

- Preferred tree path is sticky and unsigned ([Security](../security.md)).
- `argv[0]` resolves on inherited PATH before spec directories apply.
- Restricted child env when `env` is non-empty (essential allowlist + declared vars).
- Remote objects are hash-verified; cache root is `0700` on Unix.

## Data locations

| Data | Location |
|------|----------|
| Preference | `$JAN_CONFIG_DIR` or `~/.config/jan-cli/config.json` |
| Audit DB | `$JAN_DB` or XDG data local `jan-cli/audit.db` |
| Remote objects / trees / packages | `$JAN_CACHE_DIR` or `~/.cache/jan/` |

## Known debt

- YAML stack is unmaintained `serde_yaml` 0.9 / `unsafe-libyaml` (see `SECURITY.md` H1).
- No tree content digest in `config.json` (H3).
- No YAML depth/size caps (M4).