Epic: 4.0 refactor

[gmoon]

Epic: 4.0 refactor

Goal

Eliminate the silent error contract, decompose the god class, replace the internal AWS SDK middleware hack, and prepare the library to host extension packages (compress, cache, signed-URL fallback) — all while keeping the test suite green at every commit.

Why now

• v3 error contract is broken in practice: 404s call res.writeHead() from inside the proxy and substitute an empty stream, so consumer error handlers either get headers-already-sent errors or never fire.
• The AWS SDK middleware-stack hack uses undocumented internals with a load-bearing "not sure why" comment. One SDK upgrade away from breaking.
• The current proxy.get(req, res) shape (writes res and returns the stream) blocks any clean extension model — compression, caching, signed-URL fallback all need an unwritten response to operate on.

Phase A — independent (no API changes; can ship incrementally)

• Replace AWS SDK middleware-stack hack with public API #95 Replace AWS SDK middleware-stack hack with public API
• Share base config across tsconfig and vitest configs; replace shell-pipeline version generation #96 Share base config across tsconfig/vitest; replace shell-pipeline version generation
• Repo hygiene: prune root markdown bloat; revise credentials guidance #97 Repo hygiene: prune root markdown bloat; revise credentials guidance

Phase B — breaking refactor (4.0)

• Fix error contract: typed errors (S3NotFound/S3Forbidden/S3InvalidRange), no silent empty-stream substitution #98 Fix error contract: typed errors, no silent empty-stream substitution
• Make init() probe opt-out via verifyOnInit; unify with healthCheck() #99 Make init() probe opt-out via verifyOnInit; unify with healthCheck()
• Decompose S3Proxy: introduce fetch(), extract RequestParser + S3Gateway, retire get(req,res)/head(req,res) #100 Decompose S3Proxy: introduce fetch(), extract RequestParser + S3Gateway, retire get(req,res)/head(req,res)
• Test rewrite: kill 'as any', add behavioral coverage, smoke-test examples #101 Test rewrite: kill as any, add behavioral coverage, smoke-test examples

Dependencies

• Decompose S3Proxy: introduce fetch(), extract RequestParser + S3Gateway, retire get(req,res)/head(req,res) #100 depends on Fix error contract: typed errors (S3NotFound/S3Forbidden/S3InvalidRange), no silent empty-stream substitution #98 (typed errors) and Make init() probe opt-out via verifyOnInit; unify with healthCheck() #99 (init/health split lands cleaner first)
• Test rewrite: kill 'as any', add behavioral coverage, smoke-test examples #101 depends on Fix error contract: typed errors (S3NotFound/S3Forbidden/S3InvalidRange), no silent empty-stream substitution #98 + Make init() probe opt-out via verifyOnInit; unify with healthCheck() #99 + Decompose S3Proxy: introduce fetch(), extract RequestParser + S3Gateway, retire get(req,res)/head(req,res) #100 (final sweep against the new shape)
• All Phase A items are independent of each other and of Phase B

Out of scope (4.1+)

• @s3proxy/compress — gzip/brotli with Accept-Encoding negotiation, ETag invalidation, Range interaction
• @s3proxy/cache — disk/Redis with ETag-aware revalidation, Range support
• @s3proxy/signed-url-fallback — 302 to presigned URL above a size threshold (egress lever)
• Multi-bucket routing
• OpenTelemetry adapter

Migration

A MIGRATION.md ships in this PR with sed-able before/after for the Express handler, init() removal, and typed error catches.

Discipline

This work is being executed under a one-shot prompt with non-negotiable rules:

1. Every commit leaves the working tree green (unit + integration + lint + type-check + examples smoke).
2. Every commit changing production code includes the matching test update in the same commit.
3. No it.skip, no it.only, no commented-out tests.
4. The simplify skill runs at the end of every issue.

Decision log

<append-only — date, decision, reason>

[gmoon]

All seven sub-issues (#95-#101) shipped via PR #103 (v4.0). Closing the epic — the v4 line is in master and on npm. Subsequent related work (Hono example #104→#106, lattice backfill #107/#108, dep refresh #105) followed up cleanly.