# `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.