# AGENTS.md

Notes for whoever (human or agent) works on this codebase next.

## Layout

```

src/

├── main.rs            # clap CLI: import / list / open (default) / info / edit / rename / delete / path

├── lib.rs             # re-exports the modules below for the binary + tests

├── app.rs             # App state, vim mode machine, ratatui run loop

├── input.rs           # keymap: Normal / Insert / Command modes, popups

├── ui.rs               # rendering: sidebar, url bar, editor tabs, response, popups

├── highlight.rs         # JSON/XML tokenizer -> styled ratatui Lines

├── model.rs            # Collection / SavedRequest / KeyValueRow / FieldDoc / OAuthConfig+AuthKind (serde)

├── store.rs            # ~/.config/cielago persistence, AppConfig

├── openapi/

│   ├── loader.rs        # load spec from file path or http(s) URL, JSON/YAML

│   ├── swagger2.rs       # Swagger 2.0 -> OpenAPI 3.0 rewrite, applied while parsing

│   ├── resolve.rs        # local `#/...` $ref resolution (cycle-safe)

│   ├── examples.rs        # schema -> example JSON value generation

│   ├── docs.rs             # schema -> FieldDoc (types, enums) for the Docs tab

│   └── import.rs            # Spec -> Collection conversion

└── http/

    ├── client.rs           # reqwest request building + response capture

    ├── oauth.rs              # client-credentials token exchange

    ├── secret.rs              # $(cmd) secret resolution via `sh -c`

    ├── send.rs                # send_with_auth: pick scheme; oauth cache/refresh + 401 retry

    ├── url_input.rs            # pasted URL -> origin / path / query (inverse of build_url)

    └── vars.rs                 # {{name}} + dynamic ({{uuid}}, {{randomInt}}…) substitution

```

`tests/` has fixture-driven integration tests: `import_tests.rs` (spec →

collection), `http_tests.rs`/`app_send_tests.rs` (wiremock-backed HTTP +

OAuth), `input_tests.rs` (full keymap flows over an in-memory `App`),

`ui_tests.rs` (draws into a ratatui `TestBackend` and asserts on cell colours

— the only place rendering is covered).

## Design decisions worth knowing

- **The project was renamed `getman` → `stableman` → `manpost` → `cielago`.**

  `store::config_dir` moves a leftover `~/.config/{manpost,stableman,getman}`

  onto `~/.config/cielago` on first use (see `LEGACY_DIR_NAMES`), so existing

  collections survive. Drop those migrations once they've had time to run

  everywhere.

- **Swagger 2.0 is normalised, not supported twice.** `openapi::swagger2`

  rewrites a 2.0 document into the 3.0 shape inside `loader::parse_spec`, so

  `import`/`examples`/`docs` only ever see 3.x — adding a dialect to those

  would have meant a second branch in every schema walk. The rewrite moves

  `definitions`/`parameters`/`responses`/`securityDefinitions` under

  `components` (rewriting every local `$ref` to match), folds

  `schemes`+`host`+`basePath` into `servers`, lifts a parameter's inline

  `type`/`format`/… into a `schema`, and turns `in: body` / `in: formData`

  parameters into a `requestBody` keyed by the operation's `consumes`.

  Unrecognised keys are carried across untouched, so `x-` extensions survive.

  Deliberately lossy: `collectionFormat` and operation-level `schemes` are

  dropped (3.0 has no per-operation server, and cielago comma-joins array

  params either way), and `https` is ordered ahead of `http` so a spec offering

  both opens on the secure one.

- **No remote `$ref`s.** `openapi::resolve` only follows local

  `#/components/...` JSON pointers. Specs that split across files aren't

  supported — bundle them first if you hit this.

- **Auth is one struct, three schemes.** `OAuthConfig` (aliased `AuthConfig`)

  carries every scheme's fields, discriminated by `AuthKind` (`bearer` /

  `apikey` / `oauth2`). It stays a single flat JSON object so collections

  written before bearer/api-key support — whose `auth` has no `kind` — still

  deserialize (missing `kind` defaults to `oauth2`, which is what they were).

  The popup (`A`) builds its rows from `App::auth_fields` per kind; the first

  row is always the kind toggle. `send::send_with_auth` branches on the kind:

  bearer/apikey resolve their secret and send (no token cache, no 401 retry),

  oauth2 keeps the cache-and-retry path.

- **Secrets are plaintext, but can be indirected.** Secret fields

  (`token`, `client_secret`) are saved as-is in the collection JSON (explicit

  user choice). To avoid that, a field may hold a single `$(…)` command

  substitution — `http::resolve_secret` runs it through `sh -c` at send time

  and uses the trimmed stdout. Only a value that is *entirely* `$(…)` is

  executed, never one embedded in a longer string. The in-memory `OAuthToken`

  is never persisted.

- **Tags become sidebar groups**, first tag only; untagged requests land in

  a `default` group. This wasn't asked for explicitly but was cheap and

  matches how most specs are organized.

- **`Method::parse`, not `FromStr`** — deliberately not the trait, to dodge

  a clippy lint; nothing else depends on `FromStr`.

- **Vim modes are `Normal` / `Insert` / `Command` / `Search`** — no Visual

  mode. Insert mode is only single-line field edits (`LineEdit`), tracked by

  `app.editing`; there is no in-app multi-line editor. `Search` is the

  `/` sidebar filter: it re-applies on every keystroke, and `app.filter` (the

  committed query) is deliberately separate from `app.search` (the live

  prompt buffer) so `Esc` can drop the prompt without touching the filter.

- **Sidebar labels are a view concern.** `SavedRequest` keeps `name` (user

  editable), `summary` and `operation_id` (verbatim from the spec);

  `Collection.label_mode` picks which one renders. `:rename-all` is the only

  thing that overwrites `name`. Import prefers `summary` over `operationId`

  for the initial name — most real specs put a generated controller method

  name in `operationId`.

- **Switching collections reassigns the whole `App`** (`switch_collection` does

  `*self = App::new(...)`). Everything view-related is derived from the

  collection, so there's nothing to migrate by hand — and dropping the mpsc

  channel and cached `OAuthToken` is a feature, not collateral: a response still

  in flight for the previous collection can no longer land in the new one, and

  the token belonged to the old `auth` config. It deliberately does *not* go

  through a `pending_*` field like `run_external_edit` does; that indirection

  only exists because the editor needs the `&mut Terminal` to suspend raw mode,

  and routing a switch through the run loop would put it out of reach of

  `input_tests.rs`.

- **Pasting a URL rewrites collection state.** `App::apply_url_input` +

  `http::url_input` split an absolute URL into origin / path / query: the origin

  is added to `servers` (deduped on `trim_end_matches('/')`, since `E`-added

  servers may carry a trailing slash) **and made active**, because the URL bar

  renders `base_url() + path` and would otherwise show something other than what

  was just pasted. Query rows are replaced only when the input actually contained

  a `?` — otherwise fixing a typo'd path would silently wipe the disabled

  optional params an import set up. Two traps the module exists to handle:

  `Url::parse("localhost:8080/x")` *succeeds* with scheme `localhost` (hence the

  http/https + host check), and `{`/`}` are in the crate's path encode set, so

  `/pets/{id}` comes back as `/pets/%7Bid%7D` and needs `restore_braces`.

- **`path_params` follows the path.** `SavedRequest::sync_path_params` derives

  the rows from `{placeholders}` in `path`, pruning ones that no longer appear —

  `build_url` ignores those anyway, so a stale row only makes the Params tab

  lie. `{{variables}}` are skipped by the scanner. Import does *not* call it:

  spec-declared rows are authoritative there.

- **`$EDITOR` integration** shells out synchronously, suspending raw mode

  around it (`app::run_external_edit`). It writes/reads a temp file rather

  than piping, so it works with any editor.

- **Highlighting is hand-rolled** (`highlight.rs`), line-oriented, and never

  drops input: every character comes back out in some span (there's a test).

  A `syntect`-class dependency would be larger than the rest of the binary,

  and JSON/XML/plain is all a request client shows.

- **The body is read-only in the TUI.** It renders as a highlighted

  `Paragraph`; edits go through `$EDITOR` (`e`). `app.body_text` is the source

  of truth and `app.body_scroll` is a plain offset clamped at render, which is

  why `j`/`k` on the Body tab just move that offset. There is deliberately no

  in-app text editor — that's what dropped the `tui-textarea` dependency.

- **Dynamic variables live in the `{{…}}` namespace**, not a second syntax:

  `{{uuid}}`, `{{randomInt(1,10)}}`, `{{isoTimestamp}}`. A collection variable

  shadows a dynamic one of the same name (`{{$name}}` forces the dynamic one),

  so a fixed `uuid` can be pinned for debugging. Randomness comes from UUID v4

  bytes and the RFC 3339 formatter is hand-written — both to avoid adding

  `rand`/`chrono` for a handful of values.

- **Collections carry a saved view.** `last_request` (request id),

  `last_focus` (pane `1`/`2`/`3`) and `last_tab` are written by

  `App::record_view` when `:w` runs, and replayed by `App::new` — it reopens

  the request (expanding its group if `groups_collapsed` would hide it), then

  restores the pane and tab. Two deliberate wrinkles: the view is recorded

  *during* `save` rather than by `select_request`, because marking the

  collection dirty just for moving the sidebar cursor would make `:q` nag

  after a read-only browse (the trade: navigate away, quit clean, and the old

  position stays); and a saved `Response` focus falls back to the editor,

  since responses aren't persisted and pane 3 is empty on open.

  `Focus`/`EditorTab` stay in `app.rs` and gained serde derives, so `model.rs`

  reaches back into `app` for those two types.

- **CLI names resolve by slug** (`store::match_name`): the file is named after

  `slugify(name)` anyway, so `delete "some api"` and `delete some-api` both hit

  `Some API`. Exact name wins first. `store::resolve_collection` is the entry

  point and produces the "Available: …" error every name-taking command shares.

- **`cielago edit` edits a temp copy, not the file.** It only writes back after

  the edited text parses as a `Collection`; on a parse error the temp file is

  left in place and its path printed, so a botched edit is recoverable. A `name`

  changed in the editor is a rename (file moves, `config.last_collection`

  follows), and it bails rather than overwriting a different collection whose

  name slugifies the same.

- **`FieldDoc`s are stored on the request**, not read from the spec on demand:

  a collection's `spec_source` is often a URL that has moved or needs auth by

  the time the collection is opened. Cost is a re-import to refresh them, and

  older collections having none.

## Before committing

```sh

cargo fmt

cargo clippy --all-targets   # keep this clean, no warnings

cargo test

```

## Known gaps (intentionally out of scope for v1)

Interactive OAuth flows (auth-code / device / implicit — only

client-credentials is automated; bearer and API-key are static),

collection folders beyond tag grouping, request history/response diffing.

A form body (2.0 `formData`, or any `x-www-form-urlencoded`/`multipart`

`requestBody`) is imported as the JSON object that describes it, with the

matching `Content-Type` — the fields are all there and documented, but the

body isn't encoded as a form at send time.

The Docs tab covers request inputs only — response schemas and status codes

aren't imported.