first commit

docs/media/audio/audio-cli/src/bin/bin.md

@@ -0,0 +1,59 @@
+# `bin` — `suaveplan-audio` entry point
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module is the `bin` shebang entry for the `suaveplan-audio` command. It
+is the only file in the package with side effects: when executed as a script
+it installs a `SIGINT` handler, constructs an `AudioCLI`, dispatches
+`process.argv`, and calls `process.exit` with the returned exit code. The
+function `main` is also exported so tests and programmatic callers can drive
+the exact dispatch path without spawning a subprocess.
+
+The root barrel deliberately does NOT re-export this module — importing
+`@suaveplan/audio-cli` should never read `process.argv` or attach signal
+listeners.
+
+## Features
+
+- `#!/usr/bin/env bun` shebang so the installed `bin` runs through Bun.
+- Single `AbortController` per invocation, threaded into every long-running
+  command via `cli.dispatch`.
+- Two-tick `SIGINT` handling: first signal aborts cooperatively, second
+  signal calls `process.exit(130)` for force-exit.
+- `import.meta.url` self-test guard so importing the file as a module is a
+  pure type/export operation.
+
+## Usage: Basic
+
+```sh
+$ suaveplan-audio --version
+0.1.0
+$ suaveplan-audio convert input.wav output.flac
+```
+
+## Usage: Advanced
+
+```ts
+import { main } from "@suaveplan/audio-cli/bin";
+
+const exitCode = await main(["analyze", "track.wav", "--lufs"]);
+console.log("exit:", exitCode);
+```
+
+## API Reference
+
+- `main(argv: readonly string[]): Promise<number>` — dispatch and return
+  exit code without calling `process.exit` (caller's responsibility).
+
+## Implementation Notes
+
+The `import.meta.url === \`file://\${process.argv[1]}\`` check is the
+canonical Node ESM way to ask "am I running as the entry script?" It avoids
+the historical `require.main === module` CJS idiom and keeps the file safe
+to import from tests. The single `AbortController` is threaded via the
+dispatch's per-command argument extraction so the same signal reaches the
+engine adapters as the spec mandates.