first commit

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

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