# `error-codes` — AudioCliError and EXIT_CODES

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module is the structured error and exit-code boundary for
`@suaveplan/audio-cli`. It defines the six `AUDIO_CLI.*` codes the package
throws, the `AudioCliError` class extending `SuaveplanError` carrying `code`,
`cause`, and `context`, the `AUDIO_CLI_ERROR_METADATA` table with descriptions
and severity, and the `EXIT_CODES` table that maps every code onto a stable
non-zero Unix exit integer.

It also exports `exitCodeFor`, which the CLI entry point calls in its global
catch to convert any thrown value into a `process.exit` argument. The mapping
is part of the public contract: CI pipelines and shell scripts depend on it,
so changing a code-to-integer mapping is a breaking change.

## Features

- Six-code registry (`INVALID_ARGS`, `UNKNOWN_OP`, `INPUT_NOT_FOUND`,
  `BAD_OUTPUT`, `PIPELINE_FAILED`, `ABORTED`) via `defineCodes`.
- `AudioCliError extends SuaveplanError` with strongly-typed `code`.
- `EXIT_CODES` immutable table (`0`-reserved, `2/3/4/5/130`).
- `exitCodeFor(err)` unknown-shape fallback to `1`.
- Idempotent `registerAudioCliErrorCodes()` for cross-package code-table fans.

## Usage: Basic

```ts
import { AudioCliError, AUDIO_CLI_CODES, exitCodeFor } from "@suaveplan/audio-cli/error-codes";

try {
    throw new AudioCliError(AUDIO_CLI_CODES.INPUT_NOT_FOUND, "audio-cli.input-not-found", {
        context: { path: "missing.wav" },
    });
} catch (err) {
    process.exit(exitCodeFor(err));
}
```

## Usage: Advanced

```ts
import {
    AUDIO_CLI_CODES,
    AUDIO_CLI_ERROR_METADATA,
    EXIT_CODES,
    type AudioCliErrorCode,
} from "@suaveplan/audio-cli/error-codes";

// Render a help table of every code, its severity, and the exit it produces.
for (const [code, meta] of Object.entries(AUDIO_CLI_ERROR_METADATA)) {
    const c = code as AudioCliErrorCode;
    console.log(`${c}\t${meta.severity}\texit=${EXIT_CODES[c]}\t${meta.description}`);
}
```

## API Reference

- `AUDIO_CLI_CODES` — frozen string-literal record of the six codes.
- `AudioCliErrorCode` — union of those code values.
- `AudioCliError(code, messageKey, options?)` — `SuaveplanError` subclass.
- `AUDIO_CLI_ERROR_METADATA` — per-code `{ description, severity }`.
- `EXIT_CODES` — per-code non-zero integer.
- `registerAudioCliErrorCodes()` — idempotent registry hook.
- `exitCodeFor(err)` — map a thrown value to an exit code (`0`/`1`/EXIT_CODES).

## Implementation Notes

The error class follows the same pattern as `AudioEngineServerError` and
`AudioCodecsError` in sibling packages. `defineCodes` ensures the literal
record is frozen at the type level so a typo in `AUDIO_CLI_CODES.foo` fails to
compile. `exitCodeFor` walks two shapes: an `AudioCliError` instance (cheap
typeof check) and a duck-typed `{ code: string }` so foreign errors carrying a
known `AUDIO_CLI.*` code still map correctly. Anything else falls through to
`1`, the canonical "uncaught error" Unix convention.