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

Tasks: enterprise-audio-cli

Change ID: enterprise-audio-cli Package: @suaveplan/audio-cli Target path: packages/media/audio/audio-cli Prerequisite packages on Verdaccio: @suaveplan/audio-core, @suaveplan/audio-codecs, @suaveplan/audio-engine-server, @suaveplan/audio-fx-plugin-base, @suaveplan/cli, @suaveplan/queue, @suaveplan/error, @suaveplan/types

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory packages/media/audio/audio-cli/ with src/, tests/, src/__benchmarks__/, src/commands/, src/pipeline/, and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, bin entry for audio CLI, deps: @suaveplan/audio-core workspace:^, @suaveplan/audio-codecs workspace:^, @suaveplan/audio-engine-server workspace:^, @suaveplan/audio-fx-plugin-base workspace:^, @suaveplan/cli workspace:^, @suaveplan/queue workspace:^, @suaveplan/streams workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/opentelemetry workspace:^, zod catalog:forms.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/error-codes.ts — AudioCliErrorCode, AUDIO_CLI.* codes, registerAudioCliErrorCodes().
• Write Zod schemas: ProcessOptionsSchema, BatchOptionsSchema, AnalyzeOptionsSchema.

---

3. Pipeline parser

• Implement parser.ts — parse Unix-pipe-like pipeline strings into [op, params][] arrays.
• Support quoted arguments, escaping, numeric parsing.
• Write parser.test.ts and parser.md (≥200 words).

---

4. Commands

• Implement process command — load, apply pipeline, save.
• Write process.test.ts and process.md (≥200 words).
• Implement batch command — glob input, queue jobs, collect results.
• Write batch.test.ts and batch.md (≥200 words).
• Implement analyze command — run analysis ops, output JSON.
• Write analyze.test.ts and analyze.md (≥200 words).
• Implement convert command — format conversion only.
• Write convert.test.ts and convert.md (≥200 words).
• Implement info command — print metadata and stats.
• Write info.test.ts and info.md (≥200 words).
• Implement play command — play file (browser/speaker required).
• Write play.test.ts and play.md (≥200 words).
• Implement record command — record from mic to file.
• Write record.test.ts and record.md (≥200 words).

---

5. CLI entry point

• Write src/cli.ts — AudioCLI class wrapping all commands.
• Write src/index.ts with #!/usr/bin/env bun shebang for bin entry.
• Wire @suaveplan/cli for argument parsing and help text.
• Wire OTel: spans per command, counters for files processed.

---

6. Benchmarks

• Write src/__benchmarks__/cli.bench.ts — batch process 100 files, analyze 100 files.

---

7. Tests

• Write tests/integration.test.ts — full CLI round-trip (process, analyze, convert).
• Write tests/property.test.ts (fast-check) — random pipeline chains → deterministic output for same seed.

---

8. Docs + verify + publish

• All co-located .md files (≥200 words each).
• Write README.md at package root with usage examples.
• bunx turbo lint typecheck test --filter=@suaveplan/audio-cli — green.
• bunx turbo test:coverage --filter=@suaveplan/audio-cli — 100%.
• bun scripts/publish.ts --package @suaveplan/audio-cli.
• Fold specs/audio-cli/spec.md into openspec/specs/audio-cli/spec.md.
• Archive to openspec/archive/2026-05-14-enterprise-audio-cli/.