AGENTS.md · diff
git:20260920.4118fd6 to git:20260921.6b73d12
10 added, 7 removed. Audit A to A.
# AGENTS.md
Conventions for AI agents contributing to **lade** (a Rust CLI). For *using*
lade with coding agents and CI, see the README — this file is about working on
the codebase itself.
## Build & test
Stay in the Cursor sandbox for `cargo` / `clippy` / tests. Do not
request `all` because of sccache. `enableSharedBuildCache` remaps
Cargo dirs. It does not cover the sccache daemon. Seatbelt denies
AF_UNIX / 127.0.0.1, so `.cargo/sccache-wrapper` skips sccache when
`CURSOR_SANDBOX` is set. `all` is not a compile workaround.
Run these before proposing changes; they must all pass:
```bash
cargo build --workspace --locked
cargo test --workspace --locked
cargo clippy --all-targets -- -D warnings
shellcheck installer.sh
bash tests/installer_test.sh
```
## House rules
- **All user-facing stderr goes through `message_box::MessageBox`** — never
`eprintln!`. The box is always emitted; only interactive parts (prompts,
countdowns, sleeps) are gated on `UiMode` (`Quiet` vs `Interactive`). See
`.cursor/rules/message-box.mdc`.
- Never rely on default values; be explicit. Prefer the simplest solution that
compiles. Comment only non-obvious intent, not what the code does.
- Keep documented exit codes (`src/exit_codes.rs`) stable across minor
versions. `lade status --json` keeps `version`, `global_config`, `hooks`,
`project_config`, and `ok`; the `hooks` object is `preexec` plus `pretool`.
`age_plugin` is extra (`present`, `path`). `mise` and `log` are extra.
Spoken stderr, README, and clap say pre-exec / pre-tool. JSON stays
`preexec` / `pretool`. `--scope user` and JSON `global` stay.
+ - User-facing copy for Cursor/Claude/Codex/OpenCode says **harness**,
+ not agent. CLI: `--harness`. JSON diary field `agent` is hook metadata.
+ Spoken **pre-exec** / **pre-tool** map to JSON `preexec` / `pretool`.
- **`lade status` latest**: a successful daily GitHub check must persist
the tag (`latest_version` in the global config) so status can show it after
shell use. If the fetch failed, print when we last tried (`tried today at
14:25`, `tried yesterday at 09:05`). Do not print `not checked recently`
when a check was attempted. `version` in `--json` includes `latest`,
`last_check`, `update_available`, and `check_error`.
## Project layout
- - `src/` — CLI crate. Key modules: `pretool/` (`lade hook` preToolUse / MCP verb
+ - `src/` — CLI crate. `command/` is the clap verb entry points.
+ Thematic engines: `pretool/` (`lade hook` preToolUse / MCP verb
handler plus `lade hook enable --scope user|project` into
- Cursor/Claude/Codex/OpenCode configs), `audience.rs`
- (`detect()` for Via, Audience, UI), `prompt.rs` (disclaimer flow),
- `inject.rs`/`exec/` (PTY execution + masking), `network/` (acquire and
- process groups), `mise/` (command-scoped pins via mise.lock and
- `$MISE_INSTALLS_DIR`), `status.rs`, `shell/` (preexec integration),
- `config/`, `message_box/`.
+ Cursor/Claude/Codex/OpenCode configs), `preexec/` (shell wrap),
+ `wrap/` (inject + PTY exec + masking), `mcp/`, `mise/` (command-scoped
+ pins via lade.lock / mise.lock and `$MISE_INSTALLS_DIR`), `network/`
+ (acquire and process groups), `event/` (diary, `log`, `usage`, packs),
+ `config/`, `audience.rs`, `prompt.rs`, `message_box/`.
- `crates/lade-sdk` — providers: vault hydrate, network URI parse, tunnel
command builders, CLI version tables. MCP HTTP byte bridge.
- `crates/age-plugin-lade` — C2SP `age-plugin-lade` binary. Execs
`lade eval` for hydrate. Not compiled into the `lade` binary.
- `tests/` — Rust integration tests + `installer_test.sh`.
- `scripts/`, `examples/tape/` — shell-hook fixtures and README demo tapes.
- `installer.sh`, `action.yml`, `Dockerfile`,
`.github/workflows/` — install & CI surface.