Initial Commit

openspec/archive/2026-05-12-storage-file/tasks.md

@@ -0,0 +1,80 @@
+# Tasks — storage-file
+
+> Every checkbox MUST reflect work actually done in this change.
+
+## 1. Spec authoring
+
+- [x] 1.1 Read `../suaveplan/enterprise/storage-file.md` end-to-end
+- [x] 1.2 Read `openspec/specs/storage/spec.md` and confirm capability boundary
+- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.4 Draft `proposal.md` from `openspec/templates/proposal.md`
+- [x] 1.5 Fill in `## Source mapping` table — every requirement cites a line range OR appears in the "no source line" table with justification
+- [x] 1.6 Draft `specs/storage-file/spec.md` from `openspec/templates/spec-delta.md`
+- [x] 1.7 Every requirement in the spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles
+
+## 2. Scaffolding
+
+- [x] 2.1 Create `packages/storage/storage-file/` mirroring `packages/storage/storage-s3/` conventions
+- [x] 2.2 Write `package.json` v0.0.0, `"sideEffects": false`, subpath exports for every feature module
+- [x] 2.3 Wire deps: `@suaveplan/error`, `@suaveplan/storage`, `@suaveplan/retry`, `@suaveplan/types`, `@opentelemetry/api`, `zod`, `tslib` (all `workspace:^` / `catalog:`)
+- [x] 2.4 Wire devDeps: `@suaveplan/testing`, `@types/node`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`, `typescript`, `vite`, `vite-plugin-dts`, `vitest`
+- [x] 2.5 Write `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`
+- [x] 2.6 Write `tests/setup/polyfills.ts` and `README.md` skeleton
+
+## 3. Implementation
+
+- [x] 3.1 `src/error-codes.ts` — `defineCodes("STORAGE_FILE", [...])` with 8 codes, `StorageFileError` class, `key` discriminant
+- [x] 3.2 `src/types/node-fs-storage.types.ts` + `.schemas` — `NodeFsStorageOptions` interface + Zod schema
+- [x] 3.3 `src/types/fs-adapter.types.ts` — `NodeFsLike` structural interface (mkdir, readFile, writeFile, rename, unlink, readdir, stat, access, open, createReadStream, createWriteStream)
+- [x] 3.4 `src/node-fs/node-fs.ts` — `defaultNodeFs()` factory wrapping `node:fs/promises` + `node:fs` streams
+- [x] 3.5 `src/key-sanitizer/key-sanitizer.ts` — `sanitizeKey(key)` strict boundary
+- [x] 3.6 `src/retry-helper/retry-helper.ts` — `withFsRetry(fn, options)` consuming `@suaveplan/retry.retry` with transient classifier
+- [x] 3.7 `src/otel/otel.ts` — meters/histograms/counters/tracer, `recordOp(op, outcome, durationMs, bytes?)`
+- [x] 3.8 `src/streams/streams.ts` — `createNodeReadStream` and `createNodeWriteStream` mapping `node:fs` streams to Web Streams with AbortSignal
+- [x] 3.9 `src/node-fs-storage/node-fs-storage.ts` — `NodeFsStorage extends AbstractStorage` with all abstract methods, atomic writes, AbortSignal, capabilities matrix
+- [x] 3.10 `src/registry/registry.ts` — `declare module "@suaveplan/storage"` + `registerNodeFsProvider()`
+- [x] 3.11 `src/index.ts` — explicit named re-exports per §6a
+
+## 4. Tests
+
+- [x] 4.1 `src/key-sanitizer/key-sanitizer.test.ts` — valid, traversal, absolute, null bytes, control chars, overlong, separator normalisation
+- [x] 4.2 `src/node-fs/node-fs.test.ts` — adapter forwards to real `fs.mkdtemp`-rooted directory
+- [x] 4.3 `src/retry-helper/retry-helper.test.ts` — classifier, backoff timing, exhaustion
+- [x] 4.4 `src/otel/otel.test.ts` — metrics observed via real in-memory MeterProvider
+- [x] 4.5 `src/streams/streams.test.ts` — round-trip, large payload, AbortSignal mid-stream
+- [x] 4.6 `src/node-fs-storage/node-fs-storage.test.ts` — full CRUD + metadata + list + clear + getSize + getPartial + atomic write rollback + retry path
+- [x] 4.7 `src/node-fs-storage/node-fs-storage.spec-conformance.test.ts` — type conformance, capabilities, OTel instruments emitted, registry idempotency
+- [x] 4.8 `src/registry/registry.test.ts` — registers `file` slot, factory dispatch
+- [x] 4.9 Every `it(...)` carries `{ timeout: 5000 }` (or 30000 for genuinely async)
+
+## 5. Documentation
+
+- [x] 5.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
+- [x] 5.2 `README.md` links every module under `## Modules`
+
+## 6. Gates
+
+- [x] 6.1 `bun run check`
+- [x] 6.2 `bunx turbo lint typecheck test --filter=@suaveplan/storage-file`
+- [x] 6.3 `bunx turbo test:coverage --filter=@suaveplan/storage-file` (100/100/100/100)
+- [x] 6.4 `bun scripts/openspec-conformance.ts @suaveplan/storage-file`
+- [x] 6.5 `bunx turbo build --filter=@suaveplan/storage-file`
+
+## 7. Pre-archive 9-row checklist
+
+- [x] 7.1 Generics threaded; structural injectable seams (`NodeFsLike`, `TimersLike`)
+- [x] 7.2 Zod schemas wired at every declared boundary
+- [x] 7.3 Every error code thrown by at least one production path
+- [x] 7.4 OTel instruments emitted from production paths; asserted via real in-memory `MeterProvider`
+- [x] 7.5 Atomic writes verified (temp-file removed on success, removed on failure)
+- [x] 7.6 No `export *` in feature-module barrels (§6a)
+- [x] 7.7 No direct `vitest` / `bun:test` imports in tests (§7)
+- [x] 7.8 No banned patterns in `src/` (`TODO`/`FIXME`/`ts-ignore`/`.skip`/`.only`)
+- [x] 7.9 README + sibling `.md` files complete
+
+## 8. Archive
+
+- [x] 8.1 Fold spec delta into `openspec/specs/storage-file/spec.md`
+- [x] 8.2 Move `openspec/changes/storage-file/` → `openspec/archive/<yyyy-mm-dd>-storage-file/`
+- [x] 8.3 Refresh `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`
+- [x] 8.4 Update CLAUDE.md package listing under storage family