Src

---
name: src-skill
description: How to work in `src/`. Read before editing here.
---

# local-search / src

## Purpose
Application code for the CLI, including argument parsing, command dispatch,
typed errors, browser control, and output rendering.

## Mental model & key files
- `src/bin/lsearch.rs` parses Clap arguments and turns typed errors into stable
  stderr JSON.
- `lib.rs` exposes the async `run` entry point.
- `cli.rs` is declarative command/argument structure.
- `commands/mod.rs` is orchestration: attach browser, execute command, print
  result.
- `commands/search.rs` owns search, browser-scoped caching, output, and content
  enrichment. Keep cache hits behind live connection verification, but avoid
  attaching a page unless content or an explicit target needs it.
- `updates.rs` checks published releases independently of browser commands.
  Keep automatic notices terminal-only and startup-only, with daily caching,
  bounded HTTPS requests, and an opt-out. `update-check` is explicit JSON output;
  registry failures are advisory, never an implicit install or browser fallback.
- `error.rs` keeps operator-facing messages and machine-readable error codes in
  one place.

## Patterns to follow / invariants
- Keep command handlers thin enough to read from top to bottom.
- Prefer typed `Error` variants over ad hoc strings.
- Any command that may expose browser credentials should redact by default or
  require an explicit opt-in flag.
- Do not put CDP JSON protocol plumbing in command handlers when it belongs in
  `src/browser/`.

## Common tasks → first action
- New command: add Clap args, add command branch, update README, add CLI test.
- Managed browser cleanup: keep `cleanup` dry-run by default, kill exact managed
  listener PIDs only, and never delete profile cookies/data. Use graceful CDP
  shutdown by default; SIGKILL requires explicit `--force`.
- New output mode: update `output.rs` only if the envelope contract changes.
- New error: add variant in `error.rs` and stable `code()` mapping.

## Gotchas
- `run` owns the parsed `Cli`; avoid async closures borrowing `&mut CdpClient`
  across helper boundaries unless lifetimes are explicit.
- `read --format text|markdown` and `html` without a path intentionally write raw
  body content instead of JSON.