first commit

docs/security-stack/security/server-keys/src/bin/validate-file.md

@@ -0,0 +1,57 @@
+# `bin/validate-file`
+
+## Purpose
+
+Commander entry point for the `validate-file` operator command. Parses CLI
+flags, prompts for any required passwords via `@suaveplan/server-keys/prompt`,
+and dispatches to the matching function in
+`@suaveplan/server-keys/commands/`. The body runs inside
+`runFunction("validate-file", ...)` so OTel emission, structured stderr
+banners, and `exit(1)` on failure are all handled by the shared
+wrapper instead of being re-implemented per bin.
+
+This file is a thin wrapper — operator-facing behaviour lives in the
+`commands/` module the bin imports. The bin's only responsibilities
+are flag parsing, password prompting, and exit-code threading; the
+spec compliance, error handling, and OTel emission all come from the
+shared wrapper layer.
+
+## Features
+
+- `commander` flag parsing with `-h/--help` for every sub-command.
+- Password prompts via `@inquirer/prompts` (echo-disabled).
+- OTel command-total + duration histogram per invocation.
+- Structured `SERVER_KEYS_*` error banners on failure.
+- `process.exit(1)` on any thrown failure, after the banner.
+
+## Usage: Basic
+
+```bash
+validate-file --help
+```
+
+## Usage: Advanced
+
+Run the bin from a shell with a non-TTY `stdin` (e.g. via process
+substitution) to script multiple operations:
+
+```bash
+echo "mypassword" | validate-file [flags...]
+```
+
+When invoked under a `SIGINT`-trapping shell, the bin honours the
+shared `AbortController` plumbed through `runFunction`.
+
+## API Reference
+
+This bin exposes its surface via `commander` flags only. Run
+`validate-file --help` for the authoritative list. The library-level surface
+the bin wraps is documented under the matching `commands/` module.
+
+## Implementation Notes
+
+The bin imports its target command lazily where possible to keep `bun
+link` cold-start time short. Every prompt accepts `{ inputStream,
+outputStream, signal }` via `PromptOptions` so tests can drive the
+bin without a real TTY; in production the defaults resolve to
+`process.stdin` / `process.stdout`.