Initial Commit

openspec/changes/complete-storage-uri-adapters/tasks.md

@@ -0,0 +1,199 @@
+# Tasks — complete-storage-uri-adapters
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 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.
+
+## 0. Pre-flight
+
+- [ ] 0.1 Read `openspec/AGENTS.md` §0c, §13, §14
+- [ ] 0.2 Read `openspec/archive/2026-05-16-add-storage-uri/proposal.md`,
+      `tasks.md`, and `specs/storage-uri/spec.md` — confirm the
+      `UriPlugin` contract and the `runUriPluginConformance` harness
+      requirements
+- [ ] 0.3 Read `packages/storage/storage-uri/src/types/plugin.types.ts`
+      (`UriPlugin`, `ParsedUri`, `StreamingStorageExtensions`,
+      `StatResult`) and
+      `packages/storage/storage-uri/src/conformance/conformance.ts`
+      (`runUriPluginConformance`, `UriPluginFixtures`) verbatim
+- [ ] 0.4 Read each of the four adapter packages' `index.ts` to map the
+      exported surface the plugin must wrap
+- [ ] 0.5 Confirm no adapter already ships a `uri-plugin` (verified by
+      `find packages/storage/storage-{file,http,cdn-bunnycdn,cdn-rackspace} -name 'uri-plugin*'`
+      returning empty)
+- [ ] 0.6 Build the numbered Requirement/Scenario implementation
+      checklist (per §0c step 6) — one per adapter, plus shared
+      scaffolding row
+
+## 1. Shared scaffolding
+
+- [ ] 1.1 Confirm `@suaveplan/storage-uri` is on
+      `workspace:^` in each of the four adapter packages' `devDependencies`
+      (for the conformance test only — no runtime dep)
+- [ ] 1.2 Add a co-located `redact-signed-url/redact-signed-url.ts`
+      helper to `@suaveplan/storage-http` (used by URI redaction policy)
+      and re-use the same module from `bunnycdn` and `rackspace` via
+      adapter-local mirrors (do NOT cross-import — each package keeps its
+      own redaction list per scheme)
+
+## 2. `@suaveplan/storage-file` — `fileUriPlugin`
+
+- [ ] 2.1 `src/uri-plugin/uri-plugin.ts` — `fileUriPlugin(options)`
+      factory; scheme `"file"`; `parse(uri)` with RFC 8089 authority
+      handling, Windows drive-letter detection
+      (`/^[A-Za-z]:/` after stripping leading `/`), and `..` traversal
+      rejection against `rootDir`
+- [ ] 2.2 `src/uri-plugin/uri-plugin.ts` — `build(key)` inverse with
+      RFC 3986 segment-percent-encoding and Windows drive-letter
+      preservation
+- [ ] 2.3 `src/uri-plugin/error-codes.ts` —
+      `defineCodes("STORAGE_FILE_URI", [...])` with the 6 codes;
+      `StorageFileUriError extends SuaveplanError`
+- [ ] 2.4 `src/uri-plugin/uri-plugin.md` (≥200 words, basic + advanced)
+- [ ] 2.5 `src/uri-plugin/error-codes.md`
+- [ ] 2.6 `src/uri-plugin/uri-plugin.test.ts` — POSIX paths,
+      Windows drive-letter, relative-vs-absolute, `..` escape,
+      permission-denied wrap, conformance via `runUriPluginConformance`
+      with `validUris` (POSIX + Windows + `file://localhost/...`),
+      `invalidUris` (`file:`, `file://host/x`, `file:///../../etc/passwd`),
+      and `buildRoundTrip` pairs
+- [ ] 2.7 Add `"./uri-plugin/uri-plugin"` subpath export +
+      `"./uri-plugin/error-codes"` to `package.json`
+- [ ] 2.8 Add named re-exports in `src/index.ts` (explicit — no
+      `export *`, per CLAUDE.md rule 10)
+- [ ] 2.9 Update `README.md` `## Modules` with the new entries
+
+## 3. `@suaveplan/storage-http` — `httpUriPlugin` + `httpsUriPlugin`
+
+- [ ] 3.1 `src/uri-plugin/uri-plugin.ts` — internal `buildHttpUriPlugin`
+      builder; `httpUriPlugin(options)` and `httpsUriPlugin(options)`
+      factories differing only in `scheme`
+- [ ] 3.2 `src/uri-plugin/uri-plugin.ts` — full RFC 3986 parse via
+      `parseUri`, key = `path + (query ? "?" + query : "")` so presigned
+      query strings survive
+- [ ] 3.3 `src/uri-plugin/uri-plugin.ts` — range parsing via
+      `?range=bytes=<offset>-<end>` query parameter; on parse failure
+      raise `STORAGE_HTTP_URI.RANGE_INVALID`; on success route to
+      `adapter.getPartial(key, { offset, length })`
+- [ ] 3.4 `src/uri-plugin/uri-plugin.ts` — redirect-loop classification
+      (re-wrap `STORAGE_HTTP.REDIRECT_LOOP` if/when adapter raises;
+      fallback maps any `Response.status === 310` or fetch loop signal)
+- [ ] 3.5 `src/uri-plugin/uri-plugin.ts` — `build(key, meta?)` inverse
+      via `new URL(key, adapter.options.baseUrl)` with `scheme`
+      substitution for the `http`/`https` factory split
+- [ ] 3.6 `src/uri-plugin/redact-signed-url.ts` — case-insensitive
+      deny-list strip; exported for reuse and unit-tested
+- [ ] 3.7 `src/uri-plugin/error-codes.ts` —
+      `defineCodes("STORAGE_HTTP_URI", [...])` with 6 codes;
+      `StorageHttpUriError`
+- [ ] 3.8 `src/uri-plugin/uri-plugin.md`, `redact-signed-url.md`,
+      `error-codes.md`
+- [ ] 3.9 `src/uri-plugin/uri-plugin.test.ts` — happy `http://` +
+      `https://` round-trips, query-string preservation, range parsing
+      success + failure, redirect loop wrap, redaction unit tests, full
+      `runUriPluginConformance` per factory
+- [ ] 3.10 Subpath exports in `package.json` for the three new files
+- [ ] 3.11 Named re-exports in `src/index.ts`
+- [ ] 3.12 README modules update
+
+## 4. `@suaveplan/storage-cdn-bunnycdn` — `bunnyUriPlugin`
+
+- [ ] 4.1 `src/uri-plugin/uri-plugin.ts` — `bunnyUriPlugin(options)`
+      factory; ONE plugin registered against TWO schemes
+      (`bunnycdn` and `bunnycdn+pull`) via the same factory returning
+      one of two `UriPlugin` instances (the resolver registers each
+      explicitly)
+- [ ] 4.2 `src/uri-plugin/uri-plugin.ts` — storage-zone parse:
+      `bunnycdn://<zone>/<path>`, zone mismatch raises
+      `STORAGE_CDN_BUNNY_URI.ZONE_MISMATCH`
+- [ ] 4.3 `src/uri-plugin/uri-plugin.ts` — pull-zone parse:
+      `bunnycdn+pull://<pull-zone>/<path>`; `set`/`delete` reject with
+      `UNSUPPORTED_OPERATION`
+- [ ] 4.4 `src/uri-plugin/uri-plugin.ts` — signed-URL handling: parse
+      `?token=...&expires=...`, forward to existing
+      `buildTokenAuthQuery` helper. Token bytes NEVER persisted on
+      `meta`
+- [ ] 4.5 `src/uri-plugin/uri-plugin.ts` — `build(key, meta?)` per
+      surface (`storage` vs `pull` based on `meta.surface`)
+- [ ] 4.6 `src/uri-plugin/redact-signed-url.ts` — strips
+      `token`, `signature`, `expires`
+- [ ] 4.7 `src/uri-plugin/error-codes.ts` —
+      `defineCodes("STORAGE_CDN_BUNNY_URI", [...])` with 6 codes
+- [ ] 4.8 Co-located `.md`s for every implementation file
+- [ ] 4.9 `src/uri-plugin/uri-plugin.test.ts` — zone match/mismatch,
+      pull-zone read-only enforcement, signed-URL passthrough,
+      redaction, full conformance harness
+- [ ] 4.10 Subpath exports + named re-exports + README
+
+## 5. `@suaveplan/storage-cdn-rackspace` — `rackspaceUriPlugin`
+
+- [ ] 5.1 `src/uri-plugin/uri-plugin.ts` — `rackspaceUriPlugin(options)`
+      factory; scheme `"rackspace"`; authority = container,
+      path = object key
+- [ ] 5.2 `src/uri-plugin/uri-plugin.ts` — authority `_` or empty
+      rebinds to configured container; mismatched container raises
+      `CONTAINER_MISMATCH`
+- [ ] 5.3 `src/uri-plugin/uri-plugin.ts` — temp-URL signed-URL
+      verification via existing `buildTempUrlSignature`, on mismatch
+      raise `TEMP_URL_INVALID`
+- [ ] 5.4 `src/uri-plugin/uri-plugin.ts` — `build(key, meta?)` with
+      optional `?region=<region>` echo
+- [ ] 5.5 `src/uri-plugin/redact-signed-url.ts` — strips
+      `temp_url_sig`, `temp_url_expires`, `X-Auth-Token`
+- [ ] 5.6 `src/uri-plugin/error-codes.ts` —
+      `defineCodes("STORAGE_CDN_RACKSPACE_URI", [...])` with 6 codes
+- [ ] 5.7 Co-located `.md`s
+- [ ] 5.8 `src/uri-plugin/uri-plugin.test.ts` — container match/mismatch,
+      auth-token threading, temp-URL valid/invalid, region echo,
+      redaction, conformance
+- [ ] 5.9 Subpath exports + named re-exports + README
+
+## 6. Cross-package conformance
+
+- [ ] 6.1 Each adapter's `uri-plugin.test.ts` MUST import
+      `runUriPluginConformance` from `@suaveplan/storage-uri/conformance/conformance`
+      and call it with a fixture set covering valid/invalid/round-trip
+- [ ] 6.2 Add a cross-scheme integration test in
+      `packages/storage/storage-uri/tests/integration/all-four-schemes.test.ts`
+      composing all four plugins behind one resolver and asserting
+      end-to-end dispatch
+- [ ] 6.3 Tier purity:
+      `grep -rnE "from ['\"](node:|bun:)" packages/storage/storage-cdn-*/src/uri-plugin/`
+      returns empty (CDN plugins are universal-tier);
+      `storage-file/src/uri-plugin/` MAY use `node:` (server-tier
+      adapter); `storage-http/src/uri-plugin/` MUST be universal
+- [ ] 6.4 Test-runner imports — every new `.test.ts` imports from
+      `@suaveplan/testing/runner` only (rule 11)
+
+## 7. Gates (per adapter package)
+
+For each of `storage-file`, `storage-http`, `storage-cdn-bunnycdn`,
+`storage-cdn-rackspace`:
+
+- [ ] 7.1 `bun run check`
+- [ ] 7.2 `bunx turbo lint typecheck test --filter=@suaveplan/<pkg>`
+- [ ] 7.3 `bunx turbo test:coverage --filter=@suaveplan/<pkg>`
+      (100/100/100/100 istanbul)
+- [ ] 7.4 Banned-pattern scan returns zero
+- [ ] 7.5 Missing-`.md` scan returns zero
+- [ ] 7.6 Subpath export count matches feature module count
+- [ ] 7.7 `bun scripts/openspec-conformance.ts @suaveplan/<pkg>`
+- [ ] 7.8 Dependent sweep —
+      `bunx turbo test --filter=...@suaveplan/<pkg>` green
+- [ ] 7.9 Cross-package: full
+      `bunx turbo test --filter=@suaveplan/storage-uri` green after the
+      four plugins land
+
+## 8. Manifest & archival
+
+- [ ] 8.1 `bun scripts/folder-reorg/generate-manifest.ts` to refresh
+      `MANIFEST.md` (export-graph change)
+- [ ] 8.2 `bunx markdownlint-cli2 --fix` on touched files
+- [ ] 8.3 Fold each `specs/<adapter>/spec.md` into
+      `openspec/specs/<adapter>/spec.md` (one per adapter)
+- [ ] 8.4 Move `openspec/changes/complete-storage-uri-adapters/` →
+      `openspec/archive/<yyyy-mm-dd>-complete-storage-uri-adapters/`