Initial Commit

openspec/archive/2026-05-23-enterprise-audio-cli/proposal.md

@@ -0,0 +1,127 @@
+# OpenSpec Change: enterprise-audio-cli
+
+- **Change ID**: enterprise-audio-cli
+- **Package**: `@suaveplan/audio-cli`
+- **Category**: server
+- **Target path**: `packages/media/audio/audio-cli`
+- **Status**: PROPOSED
+- **Date**: 2026-05-14
+- **Design**: `./design.md`
+- **Spec delta**: `./specs/audio-cli/spec.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/audio-cli` on the genesis branch from scratch at enterprise quality. Command-line audio processing tool for the genesis monorepo. Built on `@suaveplan/cli` for argument parsing and `@suaveplan/audio-engine-server` for file I/O. All processing is universal — the CLI is just a shell around the same `AudioDocument` + `PlanEngine` + `ProcessPipeline` that runs in browsers.
+
+Inspired by `audiojs/audio`'s CLI: chainable operations, batch processing, and Unix pipe support.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/audio-core` (`workspace:^`) | `AudioDocument`, `OpRegistry`, `PlanEngine`, `ProcessPipeline` |
+| `@suaveplan/audio-codecs` (`workspace:^`) | `CodecRegistry`, `encodeTo`, `decodeSource` |
+| `@suaveplan/audio-engine-server` (`workspace:^`) | `FileSourceAdapter`, `FileSinkAdapter` |
+| `@suaveplan/audio-fx-plugin-base` (`workspace:^`) | FX plugins for pipeline processing |
+| `@suaveplan/audio-analysis-*` (`workspace:^`) | Analysis ops for `analyze` command |
+| `@suaveplan/cli` (`workspace:^`) | CLI framework, argument parsing, command registry |
+| `@suaveplan/queue` (`workspace:^`) | Batch job distribution |
+| `@suaveplan/streams` (`workspace:^`) | Pipe support |
+| `@suaveplan/error` (`workspace:^`) | `AudioError` base class; `AUDIO_CLI.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
+
+---
+
+## Public API
+
+### CLI commands
+
+```ts
+// process <input> <output> --pipeline "trim 30s | normalize | fade 0.5s 1s"
+// batch --input "./tracks/*.mp3" --pipeline "..." --output "./processed/"
+// analyze input.mp3 --bpm --key --lufs --output report.json
+// convert input.wav output.flac
+// info input.mp3
+// play input.wav
+// record output.wav --duration 60s
+```
+
+### Programmatic API
+
+```ts
+import { AudioCLI } from '@suaveplan/audio-cli'
+
+const cli = new AudioCLI()
+await cli.process('input.wav', 'output.flac', { pipeline: [['trim', { start: 30 }], ['normalize', { lufs: -16 }]] })
+const report = await cli.analyze('input.mp3', ['bpm', 'key', 'lufs'])
+```
+
+---
+
+## New additions for genesis
+
+1. **Chainable pipeline syntax** — Unix-pipe-like string parsing for operation chains.
+2. **Batch with glob + queue** — `batch` command supports glob patterns and `@suaveplan/queue` for distributed processing.
+3. **Pipe support** — read from stdin, write to stdout for Unix pipeline integration.
+4. **Analysis JSON output** — structured reports for CI integration.
+5. **Progress bars** — per-file and overall progress for batch operations.
+6. **OTel instrumentation** — spans per command, counters for files processed.
+7. **Property-based tests** — random pipeline chains → deterministic output for same seed.
+8. **Benchmark suite** — batch process 100 files, analyze 100 files.
+
+---
+
+## File layout
+
+```text
+packages/media/audio/audio-cli/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    cli.ts
+    cli.md
+    commands/
+      process.ts, process.md, process.test.ts
+      batch.ts, batch.md, batch.test.ts
+      analyze.ts, analyze.md, analyze.test.ts
+      convert.ts, convert.md, convert.test.ts
+      info.ts, info.md, info.test.ts
+      play.ts, play.md, play.test.ts
+      record.ts, record.md, record.test.ts
+      index.ts
+    pipeline/
+      parser.ts, parser.md, parser.test.ts
+      index.ts
+    __benchmarks__/
+      cli.bench.ts
+  tests/
+    integration.test.ts
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Breaking changes**: none — fresh build, package does not yet exist on genesis.
+
+**Prerequisites**: `@suaveplan/audio-core`, `@suaveplan/audio-codecs`, `@suaveplan/audio-engine-server`, `@suaveplan/audio-fx-plugin-base`, `@suaveplan/audio-analysis-*`, `@suaveplan/cli`, `@suaveplan/queue`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry` published to Verdaccio.
+
+### Affected dependents
+
+No dependents (verified by `bunx turbo ls --filter=...@suaveplan/audio-cli`) — this is a terminal application package. The `audio` CLI sits at the top of the `@suaveplan/audio-*` dependency graph; nothing imports it. Downstream *consumers* are external (DevOps pipelines, server-side media processing, CI audio validation), not workspace packages, so there is no dependent surface to test or migrate.