217 lines
15 KiB
Markdown
217 lines
15 KiB
Markdown
<!-- markdownlint-disable MD024 -->
|
|
|
|
# Capability Spec Delta: audio-cli (audio-cli)
|
|
|
|
**Package**: `@suaveplan/audio-cli`
|
|
**Status**: PROPOSED
|
|
|
|
> Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions.
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Server-tier purity
|
|
|
|
The `@suaveplan/audio-cli` package SHALL be a server-tier application package: it MAY import Node APIs (`node:fs`, `node:path`, `node:process`, `node:stream`, `Buffer`) and MUST NOT import browser-only APIs (`window`, `document`, `navigator`, `AudioContext`, `AudioBuffer`). All audio processing SHALL be delegated to the universal `@suaveplan/audio-core`, `@suaveplan/audio-codecs`, and `@suaveplan/audio-engine-server` packages — the CLI itself SHALL contain no DSP, codec, or page-management logic. Its `dependencies` SHALL be limited to `@suaveplan/audio-core`, `@suaveplan/audio-codecs`, `@suaveplan/audio-engine-server`, `@suaveplan/audio-fx-plugin-base`, `@suaveplan/audio-analysis-*`, `@suaveplan/cli`, `@suaveplan/queue`, `@suaveplan/streams`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry`, `tslib`, and `zod`.
|
|
|
|
#### Scenario: Built dist references no browser globals
|
|
|
|
- **WHEN** the built `dist/` is grep'd
|
|
- **THEN** it MUST NOT reference `window`, `document`, `navigator`, `AudioContext`, or `AudioBuffer`
|
|
|
|
#### Scenario: No DSP logic lives in the CLI package
|
|
|
|
- **WHEN** the package source is audited
|
|
- **THEN** every audio transform is reached through an imported `@suaveplan/audio-*` symbol, and no `Float32Array` block-processing loop is implemented in `audio-cli`
|
|
|
|
**Verified by:** `tests/purity.test.ts::"dist references no browser globals"` AND `tests/purity.test.ts::"dependency set is limited to the declared workspace packages and zod"`
|
|
|
|
---
|
|
|
|
### Requirement: The `audio` CLI entry point and `bin` declaration
|
|
|
|
The package SHALL ship an executable entry module that registers the `audio` command-line tool. `package.json` SHALL declare `"bin": { "audio": "./dist/index.js" }` and the entry module SHALL begin with a `#!/usr/bin/env bun` shebang. The entry point SHALL construct an `AudioCLI` instance, register every subcommand, parse `process.argv`, dispatch the matched command, and call `process.exit` with the resolved exit code. The package SHALL also export the `AudioCLI` class from its root barrel for programmatic use without spawning a subprocess.
|
|
|
|
#### Scenario: Installed `bin` resolves and runs
|
|
|
|
- **WHEN** the package is installed and `audio --version` is invoked through the `bin` shim
|
|
- **THEN** the process prints the package version to stdout and exits `0`
|
|
|
|
#### Scenario: Programmatic AudioCLI mirrors the CLI
|
|
|
|
- **WHEN** a caller imports `AudioCLI` and calls `cli.process(input, output, opts)` directly
|
|
- **THEN** the produced output file is byte-identical to running the equivalent `audio <input> ... save <output>` invocation
|
|
|
|
**Verified by:** `tests/integration.test.ts::"audio --version runs through the bin shim and exits 0"` AND `src/cli.test.ts::"programmatic AudioCLI.process matches the CLI invocation"`
|
|
|
|
---
|
|
|
|
### Requirement: Argument and pipeline parsing
|
|
|
|
The package SHALL export a `parsePipeline(spec: string)` function that converts a Unix-pipe-style operation chain (e.g. `"trim 30s | normalize -16lufs | fade 0.5s 1s"`) and the positional bare-op form (`audio input.wav trim 30s normalize -16lufs save output.flac`) into an ordered `Array<[opName: string, params: Record<string, unknown>]>`. The parser SHALL support quoted arguments, backslash escaping, numeric literals, and unit suffixes (`s` seconds, `ms` milliseconds, `lufs`, `db`, `hz`). The resolved op chain SHALL map one-to-one onto `AudioEdit` records passed to `AudioDocument.run`. A chain referencing an op name not present in the composed `OpRegistry` SHALL throw `AudioCliError` with code `AUDIO_CLI.UNKNOWN_OP` naming the offending op.
|
|
|
|
#### Scenario: Pipe-string and bare-op forms produce the same edit chain
|
|
|
|
- **WHEN** `parsePipeline("trim 30s | normalize")` and the positional form `["trim", "30s", "normalize"]` are both parsed
|
|
- **THEN** both yield the same `[["trim", { start: 30 }], ["normalize", {}]]` edit chain
|
|
|
|
#### Scenario: Unknown op name is rejected
|
|
|
|
- **WHEN** a pipeline string names an op absent from the registry
|
|
- **THEN** parsing throws `AudioCliError` whose `code === "AUDIO_CLI.UNKNOWN_OP"` with the offending op name in `context`
|
|
|
|
**Verified by:** `src/pipeline/parser.test.ts::"pipe-string and bare-op forms parse to the same edit chain"` AND `src/pipeline/parser.test.ts::"rejects an unknown op name with AUDIO_CLI.UNKNOWN_OP"`
|
|
|
|
---
|
|
|
|
### Requirement: Input → ops chain → output processing flow
|
|
|
|
The `process` and bare-op commands SHALL execute the pipeline `input → ops chain → output`: load the input via `@suaveplan/audio-engine-server`'s `FileSourceAdapter` (or stdin), append the parsed ops as `AudioEdit` records to an `AudioDocument`, stream the compiled plan through `@suaveplan/audio-core`'s `PlanEngine` + `ProcessPipeline`, and encode the result to the output path via `@suaveplan/audio-codecs` and `FileSinkAdapter` (or stdout). The output codec SHALL be inferred from the output file extension; an unrecognised extension SHALL throw `AudioCliError` with code `AUDIO_CLI.BAD_OUTPUT`. Processing SHALL be streaming end-to-end — the CLI MUST NOT materialise the whole decoded file in memory when the codec supports progressive decode.
|
|
|
|
#### Scenario: Trim then normalize round-trips to a new format
|
|
|
|
- **WHEN** `audio input.wav trim 30s normalize -16lufs save output.flac` runs against a real temp WAV file
|
|
- **THEN** `output.flac` exists, decodes to a 30-second FLAC stream, and the process exits `0`
|
|
|
|
#### Scenario: Unrecognised output extension is rejected
|
|
|
|
- **WHEN** the output path carries an extension no registered codec claims
|
|
- **THEN** the command throws `AudioCliError` whose `code === "AUDIO_CLI.BAD_OUTPUT"` and exits non-zero
|
|
|
|
**Verified by:** `src/commands/process.test.ts::"trim then normalize writes a 30s FLAC and exits 0"` AND `src/commands/process.test.ts::"rejects an unrecognised output extension with AUDIO_CLI.BAD_OUTPUT"`
|
|
|
|
---
|
|
|
|
### Requirement: Streaming through audio-core, audio-codecs, and audio-engine-server
|
|
|
|
Every command that reads or writes audio SHALL compose the three lower packages without re-implementing their behaviour: `@suaveplan/audio-engine-server` for file/stdin/stdout adapters, `@suaveplan/audio-codecs` for decode/encode, and `@suaveplan/audio-core` for the `AudioDocument` + `PlanEngine` + `ProcessPipeline` render path. The `analyze` command SHALL additionally compose the `@suaveplan/audio-analysis-*` ops, and pipeline FX SHALL be resolved from `@suaveplan/audio-fx-plugin-base`. The CLI SHALL pass decoded `Float32Array[]` blocks through `@suaveplan/streams` so backpressure is honoured between decode, process, and encode stages.
|
|
|
|
#### Scenario: Decode, process, and encode stages are backpressure-linked
|
|
|
|
- **WHEN** a large input is processed and the sink stage is artificially slowed
|
|
- **THEN** the decode stage pauses rather than buffering the whole file, and peak memory stays bounded
|
|
|
|
#### Scenario: Analyze composes analysis ops without re-implementing them
|
|
|
|
- **WHEN** `audio analyze input.mp3 --bpm --key --lufs` runs
|
|
- **THEN** the report values are produced by the imported `@suaveplan/audio-analysis-*` ops, not by logic local to `audio-cli`
|
|
|
|
**Verified by:** `tests/integration.test.ts::"decode/process/encode stages honour backpressure"` AND `src/commands/analyze.test.ts::"analyze delegates to the audio-analysis ops"`
|
|
|
|
---
|
|
|
|
### Requirement: `--help` and `--version` flags
|
|
|
|
The CLI SHALL handle `--help` / `-h` and `--version` / `-V` at both the top level and per subcommand. `--version` SHALL print the `@suaveplan/audio-cli` package version to stdout and exit `0`. `--help` SHALL print usage, the command table, and per-command option descriptions to stdout and exit `0`. An unknown top-level command or an unknown flag SHALL print a short usage hint to stderr and exit with a non-zero code.
|
|
|
|
#### Scenario: Top-level help lists every command
|
|
|
|
- **WHEN** `audio --help` runs
|
|
- **THEN** stdout contains a usage line and an entry for each of `process`, `batch`, `analyze`, `convert`, `info`, `play`, and `record`, and the process exits `0`
|
|
|
|
#### Scenario: Unknown command prints usage and exits non-zero
|
|
|
|
- **WHEN** `audio frobnicate` runs
|
|
- **THEN** stderr carries a usage hint, stdout is empty, and the exit code is non-zero
|
|
|
|
**Verified by:** `src/cli.test.ts::"--help lists every registered command and exits 0"` AND `src/cli.test.ts::"unknown command prints usage to stderr and exits non-zero"`
|
|
|
|
---
|
|
|
|
### Requirement: Exit codes mapped from error codes
|
|
|
|
The CLI SHALL exit `0` on success and a documented non-zero code on failure. Every `AUDIO_CLI_*` error code SHALL map to a stable, non-zero exit code via an exported `EXIT_CODES` table: usage/argument errors → `2`, input-not-found / unreadable → `3`, bad-output / encode failure → `4`, pipeline / processing failure → `5`, aborted (SIGINT) → `130`. An uncaught error of unknown shape SHALL exit `1`. A failed command SHALL write a single human-readable diagnostic line to stderr carrying the error `code` and `message` before exiting.
|
|
|
|
#### Scenario: Missing input file exits with the input-error code
|
|
|
|
- **WHEN** `audio missing.wav normalize save out.wav` runs against a path that does not exist
|
|
- **THEN** the process exits `3`, stderr carries an `AUDIO_CLI.INPUT_NOT_FOUND` diagnostic, and no output file is created
|
|
|
|
#### Scenario: Every error code has a distinct non-zero exit mapping
|
|
|
|
- **WHEN** the `EXIT_CODES` table is enumerated
|
|
- **THEN** every `AUDIO_CLI_*` code maps to a non-zero integer and `0` is reserved for success
|
|
|
|
**Verified by:** `src/commands/process.test.ts::"missing input exits 3 with an AUDIO_CLI.INPUT_NOT_FOUND diagnostic"` AND `src/error-codes.test.ts::"every AUDIO_CLI code maps to a distinct non-zero exit code"`
|
|
|
|
---
|
|
|
|
### Requirement: Zod boundary validation of parsed arguments
|
|
|
|
Every command's resolved option object — `ProcessOptions`, `BatchOptions`, `AnalyzeOptions`, `ConvertOptions`, `InfoOptions`, `PlayOptions`, `RecordOptions` — SHALL have a Zod schema exported from a sibling `*.schemas.ts`, and each command SHALL validate its parsed arguments against the schema before doing any I/O. A validation failure SHALL throw `AudioCliError` with code `AUDIO_CLI.INVALID_ARGS` carrying the Zod issue list in `context`, and the CLI SHALL surface it as exit code `2`.
|
|
|
|
#### Scenario: Invalid argument is rejected at the boundary
|
|
|
|
- **WHEN** `audio batch --workers -1 ...` is invoked with a negative worker count
|
|
- **THEN** the command throws `AudioCliError` whose `code === "AUDIO_CLI.INVALID_ARGS"` with the Zod issues in `context`, and the process exits `2`
|
|
|
|
**Verified by:** `src/commands/batch.test.ts::"rejects a negative --workers value with AUDIO_CLI.INVALID_ARGS and exit 2"`
|
|
|
|
---
|
|
|
|
### Requirement: Structured error codes
|
|
|
|
The package SHALL export `AudioCliErrorCode`, `AUDIO_CLI_ERROR_METADATA`, and `registerAudioCliErrorCodes()`, registering the codes `AUDIO_CLI.INVALID_ARGS`, `AUDIO_CLI.UNKNOWN_OP`, `AUDIO_CLI.INPUT_NOT_FOUND`, `AUDIO_CLI.BAD_OUTPUT`, `AUDIO_CLI.PIPELINE_FAILED`, and `AUDIO_CLI.ABORTED` with `@suaveplan/error`. Every error thrown by the package SHALL be an `AudioCliError` extending `SuaveplanError` carrying one of these codes, `cause`, and `context`. Every registered code SHALL be reachable from a real call site exercised by tests running the real CLI against real temp files.
|
|
|
|
#### Scenario: Every registered code is thrown by a call site
|
|
|
|
- **WHEN** the test suite runs
|
|
- **THEN** each code in `AUDIO_CLI_ERROR_METADATA` is asserted thrown by at least one test invoking the real CLI
|
|
|
|
**Verified by:** `src/error-codes.test.ts::"every AUDIO_CLI code is reachable from a call site"`
|
|
|
|
---
|
|
|
|
### Requirement: OpenTelemetry instrumentation
|
|
|
|
The package SHALL instrument its commands via `@suaveplan/opentelemetry`: a span per command named `audio_cli.<command>`, a counter `audio_cli_files_processed_total{command,outcome}`, a counter `audio_cli_commands_total{command,outcome}`, and a histogram `audio_cli_command_duration_ms{command,outcome}`. The `outcome` attribute SHALL be one of `success`/`error`/`aborted`. Instrumentation SHALL be a no-op when no exporter is registered and SHALL NOT run as an import-time side effect.
|
|
|
|
#### Scenario: A successful command records its span and counters
|
|
|
|
- **WHEN** `audio convert in.wav out.flac` runs against a real in-memory OTel provider
|
|
- **THEN** a span `audio_cli.convert` is recorded, `audio_cli_commands_total{command="convert",outcome="success"}` increments by 1, and `audio_cli_command_duration_ms` records one observation
|
|
|
|
#### Scenario: Instrumentation is inert without an exporter
|
|
|
|
- **WHEN** the package is imported and a command runs with no OTel exporter registered
|
|
- **THEN** no error is thrown and no global state is mutated at import time
|
|
|
|
**Verified by:** `src/commands/convert.test.ts::"convert records a span and counters with an exporter registered"` AND `tests/purity.test.ts::"importing the package mutates no global state"`
|
|
|
|
---
|
|
|
|
### Requirement: AbortSignal and SIGINT handling
|
|
|
|
The CLI SHALL install a `SIGINT` handler that aborts an `AbortController` whose signal is threaded into every long-running command (`process`, `batch`, `analyze`, `convert`, `record`) and into the underlying `audio-core` stream and `audio-engine-server` adapter calls. On abort the command SHALL stop at the next block boundary, clean up any partially written output file, throw `AudioCliError` with code `AUDIO_CLI.ABORTED`, and exit `130`. A second `SIGINT` SHALL force-exit immediately. The programmatic `AudioCLI` methods SHALL accept an `AbortSignal` via their options object so the same path is exercisable without a real signal.
|
|
|
|
#### Scenario: SIGINT aborts and removes the partial output
|
|
|
|
- **WHEN** a long `process` run receives `SIGINT` mid-stream
|
|
- **THEN** the command throws `AUDIO_CLI.ABORTED`, the partially written output file is removed, and the process exits `130`
|
|
|
|
#### Scenario: Pre-aborted signal short-circuits a programmatic call
|
|
|
|
- **WHEN** `AudioCLI.process` is called with an already-aborted signal
|
|
- **THEN** it throws `AudioCliError` whose `code === "AUDIO_CLI.ABORTED"` before opening the input file
|
|
|
|
**Verified by:** `tests/integration.test.ts::"SIGINT aborts a process run, removes partial output, exits 130"` AND `src/cli.test.ts::"AudioCLI.process short-circuits a pre-aborted signal"`
|
|
|
|
---
|
|
|
|
### Requirement: Subpath exports for reusable modules
|
|
|
|
`package.json` SHALL declare subpath `exports` for the reusable non-`bin` modules — `./cli` (the `AudioCLI` class), `./pipeline/parser` (`parsePipeline`), and `./commands/<command>` for each command's programmatic entry — in addition to the root `.` barrel and the `bin` entry. `sideEffects` SHALL be `false`. The shebang entry module SHALL NOT be re-exported from the root barrel so importing the package never triggers `process.argv` parsing.
|
|
|
|
#### Scenario: The pipeline parser is independently importable
|
|
|
|
- **WHEN** a consumer imports `@suaveplan/audio-cli/pipeline/parser`
|
|
- **THEN** the import resolves to `parsePipeline` without pulling the command registry or the `bin` entry
|
|
|
|
#### Scenario: Importing the root barrel does not parse argv
|
|
|
|
- **WHEN** a consumer imports `@suaveplan/audio-cli`
|
|
- **THEN** no command dispatch runs and `process.argv` is not read at import time
|
|
|
|
**Verified by:** `tests/exports.test.ts::"every reusable module has a subpath export entry"` AND `tests/exports.test.ts::"importing the root barrel does not parse process.argv"`
|
|
|
|
<!-- markdownlint-enable MD024 -->
|