chore: crush git history - reborn from consolidation on 2026-03-10

2026-03-10 00:00:00 -07:00
commit d278c4b105
313 changed files with 87549 additions and 0 deletions
@@ -0,0 +1,109 @@
+# NEXT_STEPS_424.md
+
+## Status
+
+v1.1 released 2026-04-24. All planned features complete. 468 tests passing.
+
+### Completed
+
+| Feature | Tests | Files |
+|---------|-------|-------|
+| Core Extension Points | 14 | `src/extension/types.ts`, `src/extension/registry.ts`, `src/formula/parser.ts` |
+| Multipart Uploads | 9 | `src/types.ts`, `src/domain/schema-to-arbitrary.ts`, `src/domain/request-builder.ts`, `src/infrastructure/http-executor.ts`, `src/formula/evaluator.ts` |
+| Streaming / NDJSON | 7 | `src/types.ts`, `src/infrastructure/http-executor.ts`, `src/formula/evaluator.ts` |
+| Extension System Polish | 5 | `src/plugin/index.ts`, `src/domain/contract-validation.ts` |
+| SSE Extension | 7 | `src/extensions/sse/` |
+| Serializers Extension | 4 | `src/extensions/serializers/` |
+| WebSockets Extension | 5 | `src/extensions/websocket/` |
+| Code Cleanup | 5 | `src/formula/evaluator.ts`, `src/domain/error-suggestions.ts`, `src/extension/registry.ts`, `src/test/helpers.ts`, `src/test/runner-utils.ts` |
+
+---
+
+## Architecture
+
+### Core vs Extensions
+
+Core features require changes to the schema-to-arbitrary pipeline or HTTP executor:
+- Multipart uploads
+- Streaming/NDJSON
+- Timeouts, redirects
+
+Extensions are opt-in modules:
+- SSE: specialized parser
+- Serializers: external dependencies (protobuf, msgpack)
+- WebSockets: different protocol
+
+### Extension Registration
+
+```typescript
+await fastify.register(apophis, {
+  extensions: [
+    sseExtension,
+    createSerializerExtension(registry),
+    websocketExtension,
+  ]
+})
+```
+
+Each extension provides:
+- `headers`: APOSTL operations for parser validation
+- `predicates`: custom formula evaluation
+- `onBuildRequest` / `onBeforeRequest` / `onAfterRequest`: lifecycle hooks
+- `onSuiteStart` / `onSuiteEnd`: suite-level hooks
+
+---
+
+## Test Strategy
+
+### First-Class Features
+
+Red-green-refactor cycle:
+1. Add operation to parser
+2. Add parser test
+3. Add operation to evaluator
+4. Add evaluator test
+5. Add HTTP executor support
+6. Add integration test with Fastify
+7. Add schema-to-arbitrary support (for multipart)
+8. Add generation test
+9. Add request builder support
+10. Add end-to-end test
+
+### Extensions
+
+Self-contained modules with own test suites:
+
+```typescript
+// src/extensions/NAME/test.ts
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { extension } from './extension.js'
+
+test('predicate returns correct value', () => {
+  const resolver = extension.predicates!.predicate_name
+  const result = resolver(mockContext)
+  assert.strictEqual(result.value, expected)
+})
+```
+
+---
+
+## Migration
+
+### v1.0 → v1.1
+
+No breaking changes.
+
+To use new features:
+1. **Multipart**: add `x-content-type: multipart/form-data` to schema
+2. **Streaming**: add `x-streaming: true` to response schema
+3. **Extensions**: import and register via `extensions: [...]` option
+
+---
+
+## Reference
+
+- **Architecture**: `docs/extensions/EXTENSION-ARCHITECTURE.md`
+- **Quick Reference**: `docs/extensions/QUICK-REFERENCE.md`
+- **Extension Specs**: `docs/extensions/WEBSOCKETS.md`, `HTTP-EXTENSIONS.md`
+- **API Design**: `docs/API_REDESIGN_V1.md`