Initial Commit

openspec/archive/2026-04-19-enterprise-metadata/proposal.md

@@ -0,0 +1,37 @@
+# OpenSpec Change: enterprise-metadata
+
+- **Change ID**: enterprise-metadata
+- **Package**: `@suaveplan/audio-metadata`
+- **Category**: universal
+- **Target path**: `universal/data/metadata`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/metadata.md`
+
+## Summary
+Greenfield rebuild of `@suaveplan/audio-metadata` — a universal audio-and-media metadata extractor that works in both Node and browser. Parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg, WAV, AIFF, and returns a normalised `Track` record (title/artist/album/cover/duration/bitrate). Supplies the data layer used by players and libraries.
+
+## Current-state audit (genesis)
+Package does not exist yet — fresh build.
+
+## Dependencies
+- Workspace: none (leaf)
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+- `MetadataExtractor` (singleton `.getInstance()`) with methods:
+  - `extractFromUrl(url, options?): Promise<Track>`
+  - `extractFromBuffer(buffer, options?): Promise<Track>`
+  - `extractFromFile(file: File|Blob, options?): Promise<Track>` (browser)
+- Types: `Track`, `AudioMetadata`, `MetadataExtractionOptions`
+
+## New genesis additions
+- Codes: `METADATA.UNSUPPORTED_FORMAT`, `METADATA.PARSE_ERROR`, `METADATA.FETCH_FAILED`.
+- Zod schemas for `Track`, `AudioMetadata`.
+- OTel histogram `metadata.extract.duration_ms{format}`; counter `metadata.extract.total{format, outcome}`.
+- Differential tests against `music-metadata` on fixtures (parity without pulling the dependency into production runtime).
+
+## Impact
+- Adds one new package: `universal/data/metadata`
+- Adds one new spec capability: `metadata`

openspec/archive/2026-04-19-enterprise-metadata/specs/metadata/spec.md

@@ -0,0 +1,27 @@
+# Capability Spec: metadata
+
+**Package**: `@suaveplan/audio-metadata`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### META-01 — Normalised Track
+`Track` MUST be `{ title?, artist?, albumArtist?, album?, year?, genre?, trackNumber?, discNumber?, duration: number (seconds), bitrate?, sampleRate?, channels?, codec?, format: AudioFormat, coverArt?: Blob | Uint8Array }`. All parsers MUST produce this shape and pass `TrackSchema.parse`.
+
+### META-02 — Runtime agnostic
+`MetadataExtractor` MUST work in Node and browser. `extractFromUrl` MUST use `fetch` (global in browsers, Node ≥ 18). `extractFromFile` MUST read `File` / `Blob` via `arrayBuffer()`. No direct filesystem access in source code.
+
+### META-03 — Format support
+The extractor MUST parse MP3 (ID3v1 + ID3v2.3/2.4), M4A/MP4 (iTunes `ilst` atoms), FLAC (Vorbis comments + `METADATA_BLOCK_PICTURE`), Ogg (Vorbis), WAV (RIFF LIST INFO), AIFF (ID3). Unknown containers MUST surface as `METADATA.UNSUPPORTED_FORMAT`.
+
+### META-04 — Streaming parse
+`extractFromUrl` MUST use `Range: bytes=…` requests where the server signals `accept-ranges: bytes` to avoid downloading the full audio payload when `options.coverArt === false`.
+
+### META-05 — Observability
+Every extract call MUST record `metadata.extract.duration_ms` histogram and `metadata.extract.total{format, outcome}` counter.
+
+### META-06 — Error reporting
+Parser failures MUST surface as `METADATA.PARSE_ERROR` with `{ format, offset, reason }` context. Network failures MUST surface as `METADATA.FETCH_FAILED`.

openspec/archive/2026-04-19-enterprise-metadata/tasks.md

@@ -0,0 +1,30 @@
+# Tasks: enterprise-metadata
+
+## 1. Scaffold
+- [x] 1.1 `universal/data/metadata/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+- [x] 2.1 `src/errors/metadata-error.ts` — codes.
+- [x] 2.2 Zod schemas for `Track`, `AudioMetadata`.
+
+## 3. Format parsers
+- [x] 3.1 `src/parsers/id3v2/*`.
+- [x] 3.2 `src/parsers/id3v1/*`.
+- [x] 3.3 `src/parsers/mp4-atom/*` (iTunes `ilst`).
+- [x] 3.4 `src/parsers/flac-vorbis/*`.
+- [x] 3.5 `src/parsers/ogg-vorbis/*`.
+- [x] 3.6 `src/parsers/wav-riff/*`.
+- [x] 3.7 `src/parsers/aiff-id3/*`.
+- [x] 3.8 Fixture tests per format with real files.
+
+## 4. Extractor façade
+- [x] 4.1 `src/metadata-extractor.ts` — `MetadataExtractor` singleton; runtime-agnostic fetch adapter (Node: `undici`, browser: `fetch`).
+- [x] 4.2 OTel histogram + counter.
+
+## 5. Docs / barrel / subpath exports / README
+
+## 6. Benchmarks
+- [x] 6.1 `extract.bench.ts` on MP3 / M4A / FLAC 5 MB fixtures.
+
+## 7. Ship gate
+- [x] 7.1 Verification sequence; fold + archive.