#442)

Per [discussion #441](#441) —
"sounds fine" 👍

## What
Adds a top-level `Fnox` struct in a new `src/library.rs` module so
downstream library consumers can write three lines instead of
replicating `GetCommand::run`'s boilerplate.

```rust
use fnox::Fnox;

let fnox = Fnox::discover()?;             // walks up + merges parent + local + global
let value = fnox.get("MY_KEY").await?;
let names = fnox.list()?;
```

## Final API surface (after v3 fixes)
- `Fnox::discover()` — `Config::load_smart(CONFIG_FILENAME)` (full
upward-search + parent-merge + local-override + global merge chain)
- `Fnox::open(path)` — explicit config path
- `Fnox::with_profile(profile)` — builder for non-default profile
- `Fnox::profile()` / `Fnox::config()` — accessors
- `Fnox::get(key) -> Option<String>` — resolves via
`secret_resolver::resolve_secret`. Errors with
`FnoxError::SecretNotFound { key, profile, config_path, suggestion }`
(suggestion populated via `crate::suggest` → "Did you mean
DATABASE_URL?")
- `Fnox::list() -> Vec<String>` — declared secret names, declaration
order, **sync**

`Config` is held behind `Arc` — `Fnox: Clone` is cheap.

Re-exported as `fnox::Fnox` from `lib.rs`.

## Removed from earlier drafts
- `Fnox::discover_from(start)` — couldn't be implemented safely without
a process-global `set_current_dir` violating AGENTS.md. Removed in v2.

## What's NOT here
`set()` — `SetCommand::run` is ~100 LOC of
provider/encryption/remote-storage branching. Substantial enough to
warrant its own design pass and PR. Happy to follow up if the API shape
here lands cleanly.

## Tests
8 in `library::tests`:
- `open_loads_explicit_path` / `open_errors_when_path_missing`
- `list_returns_declared_secrets_in_declaration_order`
- `get_returns_default_value_when_no_provider`
- `get_errors_with_secret_not_found_when_key_undeclared`
- `get_secret_not_found_carries_did_you_mean_suggestion` (regression for
the suggestion field)
- `with_profile_routes_list_to_named_profile`
- `clone_does_not_deep_copy_config` (asserts Arc sharing, not deep copy)

Full `cargo test --lib`: **143 passed** (135 existing + 8 new), 0
failed.

## Review fixes (v1 → v2 → v3)
v2 (commit 79f1a81) — addressed v1 review:
- HIGH: `discover_from` was bypassing load_smart's merge chain. Removed.
- MED: `list()` made sync; `Fnox` holds `Arc<Config>`; `get()` uses
`Config::get_secret` not full clone; profile via
`Config::get_profile(None)` (honors `FNOX_PROFILE`); error is
`SecretNotFound` not `Config(...)`.

v3 (commit c17f24a) — addressed v2 review:
- P1: doc example used `fnox.list()` without `?` — fixed.
- MED: `get()` docstring tightened to mention both `if_missing = ignore
| warn`.
- MED: `SecretNotFound`'s `suggestion` field now populated via
`crate::suggest::find_similar` + `format_suggestions`. New regression
test.

## Downstream POC

[bglusman/calciforge#45](bglusman/calciforge#45)
is now using this fork branch via git dep, with the wrapper collapsed
from ~150 LOC of replicated orchestration to ~50 LOC of error coercion.

---------

Co-authored-by: admin <[email protected]>

jdx#442)

Per [discussion jdx#441](jdx#441) —
"sounds fine" 👍

## What
Adds a top-level `Fnox` struct in a new `src/library.rs` module so
downstream library consumers can write three lines instead of
replicating `GetCommand::run`'s boilerplate.

```rust
use fnox::Fnox;

let fnox = Fnox::discover()?;             // walks up + merges parent + local + global
let value = fnox.get("MY_KEY").await?;
let names = fnox.list()?;
```

## Final API surface (after v3 fixes)
- `Fnox::discover()` — `Config::load_smart(CONFIG_FILENAME)` (full
upward-search + parent-merge + local-override + global merge chain)
- `Fnox::open(path)` — explicit config path
- `Fnox::with_profile(profile)` — builder for non-default profile
- `Fnox::profile()` / `Fnox::config()` — accessors
- `Fnox::get(key) -> Option<String>` — resolves via
`secret_resolver::resolve_secret`. Errors with
`FnoxError::SecretNotFound { key, profile, config_path, suggestion }`
(suggestion populated via `crate::suggest` → "Did you mean
DATABASE_URL?")
- `Fnox::list() -> Vec<String>` — declared secret names, declaration
order, **sync**

`Config` is held behind `Arc` — `Fnox: Clone` is cheap.

Re-exported as `fnox::Fnox` from `lib.rs`.

## Removed from earlier drafts
- `Fnox::discover_from(start)` — couldn't be implemented safely without
a process-global `set_current_dir` violating AGENTS.md. Removed in v2.

## What's NOT here
`set()` — `SetCommand::run` is ~100 LOC of
provider/encryption/remote-storage branching. Substantial enough to
warrant its own design pass and PR. Happy to follow up if the API shape
here lands cleanly.

## Tests
8 in `library::tests`:
- `open_loads_explicit_path` / `open_errors_when_path_missing`
- `list_returns_declared_secrets_in_declaration_order`
- `get_returns_default_value_when_no_provider`
- `get_errors_with_secret_not_found_when_key_undeclared`
- `get_secret_not_found_carries_did_you_mean_suggestion` (regression for
the suggestion field)
- `with_profile_routes_list_to_named_profile`
- `clone_does_not_deep_copy_config` (asserts Arc sharing, not deep copy)

Full `cargo test --lib`: **143 passed** (135 existing + 8 new), 0
failed.

## Review fixes (v1 → v2 → v3)
v2 (commit 79f1a81) — addressed v1 review:
- HIGH: `discover_from` was bypassing load_smart's merge chain. Removed.
- MED: `list()` made sync; `Fnox` holds `Arc<Config>`; `get()` uses
`Config::get_secret` not full clone; profile via
`Config::get_profile(None)` (honors `FNOX_PROFILE`); error is
`SecretNotFound` not `Config(...)`.

v3 (commit c17f24a) — addressed v2 review:
- P1: doc example used `fnox.list()` without `?` — fixed.
- MED: `get()` docstring tightened to mention both `if_missing = ignore
| warn`.
- MED: `SecretNotFound`'s `suggestion` field now populated via
`crate::suggest::find_similar` + `format_suggestions`. New regression
test.

## Downstream POC

[bglusman/calciforge#45](bglusman/calciforge#45)
is now using this fork branch via git dep, with the wrapper collapsed
from ~150 LOC of replicated orchestration to ~50 LOC of error coercion.

---------

Co-authored-by: admin <[email protected]>