# `cli` — `AudioCLI` class

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

## Purpose

`AudioCLI` is the application-class wrapper for the `audio` command-line tool.
It owns the default codec registry, the default op registry, the
`FileSourceAdapter` / `FileSinkAdapter` pair from `@suaveplan/audio-engine-server`,
the stdout/stderr streams, the OTel instrumentation, and the argv dispatch
logic. Both the `bin` entry and programmatic consumers construct an instance
of this class and call its public methods, so the test surface and the binary
exercise the same code path.

The class deliberately holds only wiring: every audio transform is delegated
to the seven `runX` command modules, the pipeline parser, and the underlying
`@suaveplan/audio-*` packages.

## Features

- Default `CodecRegistry` populated with the 10 built-in codecs.
- Default `OpRegistry.createWithDefaults()` plus user-supplied overrides.
- Injectable `FileSourceAdapter` / `FileSinkAdapter` for tests without
  patching `node:fs`.
- OTel span (`audio_cli.<command>`), command counter, duration histogram,
  files-processed counter, all tagged with `{ command, outcome }`.
- `dispatch(argv)` returns a numeric exit code, never throws — failures are
  formatted onto stderr and mapped through the `EXIT_CODES` table.
- `helpText()` lists every subcommand and global flag for `--help` rendering.
- `detectCodecForOutput(path, registry)` exposed for tests and the convert
  command: extension → codec name, throws `AUDIO_CLI.BAD_OUTPUT` on miss.

## Usage: Basic

```ts
import { AudioCLI } from "@suaveplan/audio-cli/cli";

const cli = new AudioCLI();
await cli.process("input.wav", "output.flac");
```

## Usage: Advanced

```ts
import { AudioCLI } from "@suaveplan/audio-cli/cli";
import { CodecRegistry, WavCodec } from "@suaveplan/audio-codecs";

const wavOnly = new CodecRegistry({ codecs: [WavCodec] });
const cli = new AudioCLI({ registry: wavOnly, version: "1.2.3" });
const exit = await cli.dispatch(["--version"]);   // prints "1.2.3", returns 0
```

## API Reference

- `AudioCLI(options?: AudioCliOptions)` — constructor.
- `AudioCliOptions` — `{ registry, ops, source, sink, stdout, stderr, version }`.
- `cli.process / batch / analyze / convert / info / play / record` — typed
  promises, each delegating to its `runX` module.
- `cli.dispatch(argv)` — exit-code-returning dispatcher.
- `cli.helpText()` — rendered help string.
- `createDefaultCodecRegistry()` — top-level helper used by the default
  constructor path.
- `detectCodecForOutput(path, registry)` — extension → codec-name lookup.

## Implementation Notes

The OTel wrapper records the start time at the top of every command, records
the outcome attribute in `finally`, and lets the `AudioCliError` propagate.
`#reportAndExit` is the single point that converts a thrown value into a
numeric exit code; it writes a single human-readable diagnostic line to
stderr (`code: message`) so the binary composes cleanly inside shell
pipelines. The `dispatch` switch is deliberately flat — every subcommand owns
its argument-parsing helper, validates inputs with a Zod schema, and either
returns `0` or throws an `AudioCliError`.