Initial Commit

openspec/archive/2026-05-16-add-storage-uri/tasks.md

@@ -0,0 +1,83 @@
+# Tasks — add-storage-uri
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 1. Spec authoring
+
+- [ ] 1.1 Read `openspec/specs/types/spec.md` and confirm `StorageLike` is the right structural target
+- [ ] 1.2 Read `openspec/AGENTS.md` §0c, §13, §14
+- [ ] 1.3 Read `openspec/archive/2026-05-16-add-storage-http/` end-to-end as the closest precedent
+- [ ] 1.4 Read `packages/core/types/src/storage-like.ts` to confirm the structural surface available
+- [ ] 1.5 Draft `proposal.md` from `openspec/templates/proposal.md`
+- [ ] 1.6 Draft `design.md` covering tier, file layout, dispatch, stream/write fallback, per-scheme parse contract, OTel surface
+- [ ] 1.7 Draft `specs/storage-uri/spec.md` — every requirement carries a `**Verified by:**` line at authoring time
+- [ ] 1.8 Build the numbered Requirement/Scenario implementation checklist (per §0c step 6)
+
+## 2. Scaffolding
+
+- [ ] 2.1 Create `packages/storage/storage-uri/` mirroring `packages/storage/storage-http/` conventions
+- [ ] 2.2 Write `package.json` v0.0.0, `"sideEffects": false`, subpath exports for every feature module
+- [ ] 2.3 Wire deps: `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`, `tslib` (all `workspace:^` / `catalog:`)
+- [ ] 2.4 Wire devDeps: `@suaveplan/testing`, `@suaveplan/storage-file`, `@suaveplan/storage-http`, `@vitest/coverage-istanbul`, `fast-check`, `typescript`, `vite`, `vite-plugin-dts`, `vitest`
+- [ ] 2.5 Write `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts` (via `createTestConfig`)
+- [ ] 2.6 Write `tests/setup/polyfills.ts` and `README.md` skeleton
+
+## 3. Core implementation
+
+- [ ] 3.1 `src/error-codes/error-codes.ts` — `defineCodes("STORAGE_URI", [...])` with 8 codes, `StorageUriError` class, `uri`/`scheme` discriminants
+- [ ] 3.2 `src/types/plugin.types.ts` — `UriPlugin`, `ParsedUri` interfaces
+- [ ] 3.3 `src/types/resolver.types.ts` — `StorageUriResolver` shape, `StatResult`, `ListResult`
+- [ ] 3.4 `src/parse-uri/parse-uri.ts` — RFC 3986 scheme+authority+path split, `INVALID_URI` mapping, 4096-char cap, null-byte rejection
+- [ ] 3.5 `src/otel/otel.ts` — meter+tracer wiring, `recordOp(op, scheme, outcome, ms)`, URI redaction (drop query string)
+- [ ] 3.6 `src/resolver/resolver.ts` — registry construction, frozen map, scheme dispatch (case-insensitive), AbortSignal short-circuit, ADAPTER_ERROR wrap, exists/remove/stat delegates
+- [ ] 3.7 `src/resolver/resolver.streams.ts` — `open()` with `createReadStream` forwarding + one-chunk fallback + counter
+- [ ] 3.8 `src/resolver/resolver.writes.ts` — `write()` accepting `Uint8Array | ReadableStream`, `createWriteStream` forwarding + drain fallback + counter
+- [ ] 3.9 `src/resolver/resolver.list.ts` — prefix list, `plugin.build` re-serialise, `LIST_UNSUPPORTED` for plugins without `build`
+- [ ] 3.10 `src/conformance/conformance.ts` — `runUriPluginConformance(plugin, fixtures)` harness
+- [ ] 3.11 `src/index.ts` — explicit named re-exports per §6a (no `export *` in non-root barrels)
+
+## 4. Tests (every `it(...)` carries `{ timeout: 5000 }`)
+
+- [ ] 4.1 `src/parse-uri/parse-uri.test.ts` — valid scheme set, malformed inputs → `INVALID_URI`, null-byte rejection, 4096-char cap, case-insensitive scheme
+- [ ] 4.2 `src/error-codes/error-codes.test.ts` — every code reachable, discriminants populated, `cause` preserved
+- [ ] 4.3 `src/resolver/resolver.test.ts` — scheme dispatch, `UNKNOWN_SCHEME`, case-insensitive scheme match, `SCHEME_CONFLICT`, idempotent re-registration, `AbortSignal` pre/forward, `ADAPTER_ERROR` wrap, exists/remove/stat delegation
+- [ ] 4.4 `src/resolver/resolver.streams.test.ts` — native forwarding, one-chunk fallback + counter, `NOT_FOUND` on undefined
+- [ ] 4.5 `src/resolver/resolver.writes.test.ts` — `Uint8Array` forwarding, stream drain + counter, `WRITE_UNSUPPORTED` re-wrap
+- [ ] 4.6 `src/resolver/resolver.list.test.ts` — re-serialisation via `build`, `LIST_UNSUPPORTED` when `build` absent, continuation token round-trip
+- [ ] 4.7 `src/resolver/resolver.spec-conformance.test.ts` — type conformance against `StorageLike`, every `STORAGE_URI` code reachable, capability probing
+- [ ] 4.8 `src/otel/otel.test.ts` — duration histogram on success, `errors_total` on failure, query-string redaction in span attributes (via in-memory `MeterProvider` + `SpanExporter`)
+- [ ] 4.9 `src/conformance/conformance.test.ts` — harness passes for a good plugin, fails for broken round-trip
+- [ ] 4.10 `tests/integration/cross-scheme.test.ts` — real `storage-file` + real `storage-http` composition, read both via the same resolver
+- [ ] 4.11 No imports from `vitest` or `bun:test` in test files — all via `@suaveplan/testing/runner` (§7)
+
+## 5. Sibling adapter plugins (additive — each in its own package)
+
+- [ ] 5.1 `storage-file`: add `src/uri-plugin/uri-plugin.ts` exporting `fileUriPlugin(options)`, sibling `.md`, conformance test using `runUriPluginConformance`
+- [ ] 5.2 `storage-http`: add `httpUriPlugin(adapter)` and `httpsUriPlugin(adapter)` exports + conformance test
+- [ ] 5.3 `storage-cdn-rackspace`: add `rackspaceUriPlugin(adapter, container)` export + conformance test
+- [ ] 5.4 `storage-cdn-bunnycdn`: add `bunnyUriPlugin(adapter, zone)` export + conformance test
+- [ ] 5.5 (deferred) `storage-s3`: `s3UriPlugin(adapter, bucket)` — gated on s3 package landing
+
+## 6. Documentation
+
+- [ ] 6.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
+- [ ] 6.2 `README.md` links every module under `## Modules`
+- [ ] 6.3 README documents the cross-scheme media-pipeline composition recipe
+- [ ] 6.4 README documents how to author a third-party `UriPlugin`
+
+## 7. Gates
+
+- [ ] 7.1 `bun run check`
+- [ ] 7.2 `bunx turbo lint typecheck test --filter=@suaveplan/storage-uri`
+- [ ] 7.3 `bunx turbo test:coverage --filter=@suaveplan/storage-uri` (100/100/100/100 Istanbul)
+- [ ] 7.4 `bun scripts/lint/check-test-runner-imports.ts` (rule 11)
+- [ ] 7.5 Tier-purity grep — `grep -rnE "from ['\"](node:|bun:)" packages/storage/storage-uri/src/` returns empty
+- [ ] 7.6 `bun scripts/openspec-conformance.ts @suaveplan/storage-uri`
+- [ ] 7.7 Every sibling adapter package still green under its own pre-publish gate after adding its `uriPlugin`
+
+## 8. Manifest & archival
+
+- [ ] 8.1 Add package to `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`
+- [ ] 8.2 Update `STATUS.md` (genesis-original — add to "Completed" once shipped)
+- [ ] 8.3 Fold `specs/storage-uri/spec.md` into `openspec/specs/storage-uri/spec.md`
+- [ ] 8.4 Move `openspec/changes/add-storage-uri/` → `openspec/archive/<yyyy-mm-dd>-add-storage-uri/`