first commit

docs/media/audio/audio-cli/src/error-codes/error-codes.md

@@ -0,0 +1,79 @@
+# `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.