@beignet/core 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # @beignet/core
 
+## 0.0.4
+
+### Patch Changes
+
+- 8bcb31f: Mark package READMEs with Beignet's experimental alpha status and 0.0.x stability expectations.
+- 5d5e303: Add a database test harness that coordinates app-owned database fixtures, factory sequence resets, seed execution, and cleanup.
+- 31c7e66: Deepen DB, outbox, and jobs devtools panels with domain-specific metrics, correlation fields, attempt/retry context, and richer row details. Provider instrumentation now adds provider names to typed provider events so those panels can group provider work consistently.
+- 8297c7c: Add contract, route, location, and status diagnostics to framework validation and response contract errors.
+- 4c1cb16: Formalize provider package manifest metadata with exported core types and
+  validation, and have doctor warn on malformed installed provider metadata before
+  using provider-derived diagnostics.
+- ac78cdf: Make `createAuthHooks` the single route-scoped auth hook API. The factory is
+  now curried — `createAuthHooks<AppContext>()({ resolve })` — so added context
+  fields are inferred from `resolve` instead of passed as a type argument, and a
+  new optional `headers` schema validates the raw lowercase request header
+  record before `resolve` runs, giving `resolve` typed credential headers
+  without contract casts. On `required()` hooks a header schema failure returns
+  a framework-owned 401; `optional()` hooks skip auth resolution; `public()`
+  hooks never parse headers. `defineRouteHook` (and the `RouteHookBuilder`
+  types) are removed — write non-auth route hooks as plain `RouteHook` object
+  literals.
+- 2da5a05: Report installed-but-unregistered optional providers as informational doctor
+  hints. Provider packages can declare `registration.severity: "hint"` in their
+  `beignet.provider` manifest metadata, and `@beignet/devtools` now uses it, so
+  removing `createDevtoolsProvider()` from `server/providers.ts` no longer fails
+  `beignet doctor --strict`.
+- 780955c: Add Drizzle/Turso-backed durable idempotency storage with setup SQL, root and transaction-client ports, and Unit of Work rollback coverage for idempotency and outbox writes.
+- 1a79090: Emit Node-compatible ESM: all relative imports in published packages now carry explicit .js extensions, fixing ERR_MODULE_NOT_FOUND when running the CLI or importing package dist files under plain Node.
+- 7fe855b: Add OpenAPI schema converters and operation overrides for custom schemas, multipart uploads, binary responses, and streaming media.
+- 079bf59: Clarify unsupported catch-all contract path diagnostics and document that catch-all route files belong to runtime adapters, not individual contracts.
+- 82c48dc: Add canonical test port and context fixtures, and update generated tests to use them.
+- 5a51869: Add schedule run attempt metadata and align durable workflow retry, backoff, terminal failure, and dead-letter documentation.
+- 89390fe: Harden `createRateLimitHooks(...)` against client-controlled inputs. The
+  denial response details no longer include the bucket key — clients now see
+  only `scope`, `retryAfterSeconds`, and `resetAt` — and each denial emits a
+  `rateLimit.denied` instrumentation event with the key, scope, limit, and
+  window so operators keep bucket visibility through the devtools `rateLimit`
+  watcher. `ip`-scoped limits now default to the last `x-forwarded-for` entry
+  (the address appended by the platform's trusted proxy) instead of the
+  client-controlled first entry. The new `ipSource` option selects
+  `"x-forwarded-for-last"` (default), `"x-forwarded-for-first"`, or a custom
+  resolver function, replacing the previous `getClientIp` option.
+- 89390fe: Add `installProviderForTest(...)` to `@beignet/core/testing` for running provider setup against test ports with merged provider-contributed ports and start/stop lifecycle runners, and export the `AnyServiceProvider` type from `@beignet/core/providers`.
+- 303ba07: Define the public HTTP adapter contract and expose the Web Fetch adapter implementation.
+- 2da5a05: Reduce per-request work in server dispatch: the fallback 404/405 hook pipeline is now built once at server creation instead of per unmatched request, unmatched requests scan the route registry with a single pattern test per route, and the registry is re-sorted lazily before the next dispatch instead of on every registration.
+- 493d23b: Make the framework own context assembly with a server context blueprint and first-class service contexts.
+
+  - `createServer(...)` (and the Next/Web adapters) replace the `createContext` option with `context`. Gate-less contexts keep the plain request-factory shorthand; contexts that declare a `gate` must use the blueprint form `{ gate: (ports) => ports.gate, request, service }`. Returning `gate` from a context factory or hook addition is now a compile error.
+  - The gate port gains `gate.attach(ctx)`: it attaches a live, non-enumerable `ctx.gate` getter that re-binds against the receiving object on every access, so identity changes (including auth-hook elevation) can never authorize against a stale context, and spread copies drop the gate loudly instead of silently keeping stale identity. `bind(...)` remains the low-level primitive.
+  - Servers expose `createRequestContext(req)` and `createServiceContext(input?)`; the optional `context.service` factory powers schedule, outbox, command, and background contexts. Provider `setup`, `start`, and `stop` receive a late-bound `createServiceContext` so infra providers no longer hand-build background contexts.
+  - `createTestContextFactory(...)` now attaches the gate after all `extra` and override fields merge, fixing a stale-identity bug in tests.
+  - CLI templates, generators, and doctor diagnostics emit and check the new context blueprint and service-context wrappers.
+
+- 493d23b: Fix `.errors()` on contract builders and contract groups to merge with previously declared catalog errors instead of replacing them. Contracts created from a group with shared catalog errors now keep the union of group and route errors at runtime and in inferred client error types, later declarations win when the same catalog key is declared twice, and multiple catalog codes can share one status across calls. Previously, route-level `.errors(...)` silently dropped group-declared errors from contract metadata, losing both server-side code enforcement and client error typing.
+- 44f1192: Move first-party provider diagnostics to package-owned `beignet.provider`
+  manifest metadata and have doctor read installed provider package manifests.
+- 2aa77ca: Add static provider metadata and provider wiring diagnostics for generated apps.
+- eda7b59: Clarify that app-owned error details are public response data and should be
+  mapped explicitly rather than automatically redacted by the framework.
+- 90c2e48: Add typed operational command definitions and a `beignet make command` generator for feature-owned app commands.
+- ac78cdf: Add `createScheduleRoute(...)` to `@beignet/next` for triggering one registered schedule from a serverless cron route, with the same fail-closed bearer auth and JSON envelope conventions as `createOutboxDrainRoute(...)`. Unknown schedule names throw when the route module loads.
+
+  The inline schedule runner in `@beignet/core/schedules` now accepts `instrumentation` and `instrumentationContext` options and records `schedule` devtools events (`started`, `completed`, `failed`) itself. Recording failures are isolated from schedule execution and reported to `onHookError`. `createScheduleRoute(...)`, `beignet schedule run`, and generated cron routes use this instead of hand-rolled lifecycle hooks.
+
+  Security: cron route bearer secrets in `createScheduleRoute(...)` and `createOutboxDrainRoute(...)` are now compared with a timing-safe SHA-256 digest comparison instead of `!==`.
+
+- 89390fe: Decouple devtools from app code with server-owned instrumentation.
+
+  - `@beignet/core/tracing` is a new dependency-free subpath with the W3C trace
+    primitives (`TraceContext`, `createTraceContext`, `createChildTraceContext`,
+    `parseTraceparent`, `createTraceparent`, `createTraceId`, `createSpanId`).
+    App context types now use `Partial<TraceContext>` instead of importing
+    `DevtoolsTraceContext` from `@beignet/devtools`.
+  - `createServer(...)` owns request instrumentation through a new
+    `instrumentation` option (`ServerInstrumentationOptions | false`). The server
+    resolves request IDs and trace context before user hooks and context
+    creation, passes them to context factories as `requestId` and `trace`,
+    writes `x-request-id`/`traceparent` response headers by default, and records
+    request/error events into the instrumentation port resolved from final ports
+    (`ports.instrumentation`, then `ports.devtools`). The ambient request
+    context (`enterActiveRequestContext` and friends) moved into
+    `@beignet/core/server`.
+  - `createUseCase(...)` instruments runs by default, resolving the
+    instrumentation port from `ctx.ports` per run; opt out with
+    `instrumentation: false`. App `onRun` observers run in addition.
+  - `createInstrumentedAuditLog({ audit, instrumentation })` in
+    `@beignet/core/ports` replaces `createDevtoolsAuditLog`.
+  - `createServer(...)` gains `validateResponses` (default `true`) to skip
+    route-owned response validation, mirroring the client option.
+  - Removed from `@beignet/devtools`: `createDevtoolsHooks`,
+    `createDevtoolsUseCaseObserver`, `createDevtoolsAuditLog`, and the
+    trace/request-context modules. Apps now only need `createDevtoolsProvider()`
+    plus the devtools route; deleting both leaves the rest of the app compiling
+    and running unchanged.
+  - `@beignet/next` cron and upload helpers resolve their instrumentation sink
+    with `resolveProviderInstrumentationPort(ctx.ports)` instead of hardcoding
+    `ports.devtools`.
+  - `beignet create` templates generate the decoupled shape.
+
+- 16cc113: Clarify the canonical route registration story and align generated starters on `app-context.ts`.
+- e9c3209: Add reusable actor, tenant, audit assertion, and default-header request helpers for production app tests.
+- ac78cdf: Split the client `validate` config flag into `validateInput` (default false)
+  and `validateResponses` (default true). Client-side input validation failures
+  now throw a client-source `ContractError` with code `INPUT_VALIDATION_ERROR`
+  and no HTTP status instead of a synthetic 422 `VALIDATION_ERROR`. Setting
+  `validateResponses: false` returns success bodies as-is and classifies non-2xx
+  responses structurally while keeping `INVALID_JSON` transport errors.
+- cca08b1: Align generated apps and package docs around the canonical auth, policy, and AppContext model.
+- ac78cdf: Add server registration and dispatch guarantees. `createServer(...)` now fails
+  at startup when a contract's `pathParams` object schema does not match the
+  `:param` keys in its path template (non-introspectable Standard Schemas are
+  skipped), and when two contracts register the same name, since typed clients,
+  OpenAPI operations, and devtools key on contract names. Requests that match a
+  registered path with an unregistered method now receive a framework-owned
+  `405 METHOD_NOT_ALLOWED` response with an `Allow` header listing the registered
+  methods instead of a `404`; `HEAD` is intentionally not mapped to `GET`
+  handlers. The 405 flows through the same hook and error-ownership pipeline as
+  the 404 fallback, so typed clients surface it as an HTTP error rather than
+  contract drift.
+- a67c637: Add Beignet runtime boundary markers and extend `beignet lint` to catch client-safe roots that value-reach server-only code.
+- 7b0f708: Add first-class outbox instrumentation and devtools visibility for delivered, retried, and dead-lettered messages.
+- 246c66c: Add idempotency entry and provider instrumentation testing helpers for app and provider test suites.
+- 242f220: Add provider-focused testing helpers for recording jobs and schedules plus assertions for events, mail, notifications, storage, outbox workflows, and provider intent.
+- 493d23b: Add typed provider-contributed ports. `InferProviderPorts` (replacing
+  `ProvidedPortsOfList`) merges the ports a provider list contributes so apps can
+  type `ctx.ports` as `AppPorts & InferProviderPorts<typeof providers>` without
+  casts. The curried `definePorts<AppPorts>()({ bound, deferred })` form replaces
+  throwing stub boilerplate: deferred keys boot as descriptive placeholders and
+  `createServer(...)` fails startup with the unbound key list (configurable via
+  `onUnboundPorts: "error" | "warn" | "ignore"`). App-local providers can declare
+  required ports, app context, and service-context input through the curried
+  `createProvider<Requires, Context, ServiceInput>()` form, which types
+  `setup({ ports, createServiceContext })` and lifecycle contexts end to end.
+  CLI templates and `beignet make` generate and maintain the new forms.
+- 8063d38: Rename the contract front door to `defineContract`/`defineContractGroup`, rename operational commands to tasks (`@beignet/core/tasks`, `defineTasks`, `runTask`, `beignet task run`, `beignet make task`, `server/tasks.ts`, `features/<feature>/tasks/`, `paths.tasks`), and standardize context binding: context-free declarations stay top-level (`defineEvent`), while context-bound definitions come from per-capability factories (`createListeners`, `createJobs`, `createSchedules`, `createNotifications`, `createTasks`) called once in `lib/`. Top-level context-generic `defineListener`, `defineJob`, `defineSchedule`, and `defineNotification` are removed.
+- 905da0a: Audit ports can be wrapped with `createAmbientAuditLog` to fill actor, tenant,
+  and correlation ids from the ambient request context at record time — including
+  inside per-transaction port rebuilds — and `requireSession`, `requireUser`,
+  `requireUserId`, `requireTenant`, and `requireTenantId` are now exported from
+  `@beignet/core/ports`, throwing framework-owned 401/403 errors.
+- 192c6ad: Typed clients now attach idempotency keys automatically from contract metadata (override with `idempotencyKey`), React Query mutations keep the key stable across retry attempts, and the shared client error helpers `contractErrorMessage` and `rootFormError` are now exported by @beignet/core/client and @beignet/react-hook-form.
+- 192c6ad: Rename `defineFactory` to `createFactory` and `defineEnv` to `createEnvLoader` to match the naming convention: define declares things you register, create returns runtime objects you call.
+- 192c6ad: beforeSend hooks now run for native web Responses with a headers-only view (`native: true`), so CORS, request-id, and trace headers reach streamed responses; idempotency reservations are released for streamed responses instead of compensating in afterSend.
+- 192c6ad: Routes can bind a contract directly to a use case with `{ contract, useCase }` — status is inferred from a sole 2xx response, input defaults to merged path/query/body parts, and validated inputs are not re-parsed when the use case reuses the contract schema by reference. Full `handle` routes remain the escape hatch for headers, streaming, and multi-status responses.
+- 255527d: Add `createTestContext` for testing jobs, listeners, schedules, notifications, and tasks; make `createTestPorts` overrides accept typed partial ports without casts; default the test audit port to ambient enrichment; add `transaction.outbox` to flush buffered domain events on commit; add `defineServerContext` so apps can share one context blueprint between the server and tests.
+- ac78cdf: Enforce contract `meta.idempotency` at the HTTP boundary with the new
+  `createIdempotencyHooks(...)` server hook. The hook reserves the client key
+  after request parsing, replays completed matching responses with an
+  `idempotency-replayed: true` header, and rejects in-progress and conflicting
+  keys. The server now maps uncaught `IdempotencyConflictError` and
+  `IdempotencyInProgressError` primitives to framework-owned `409` responses
+  using the new `httpErrors.IdempotencyConflict` and
+  `httpErrors.IdempotencyInProgress` catalog entries, so apps no longer need to
+  re-map idempotency primitives to app-local catalog errors.
+  `runIdempotently(...)` remains the workflow-level primitive for non-HTTP work.
+  `beignet doctor` recognizes the new `httpErrors` catalog entries.
+
+## 0.0.3
+
+### Patch Changes
+
+- 3160184: Add `beignet db generate|migrate|seed|reset`, scaffold standard seed/reset database entrypoints, and expose a factory reset helper for test data workflows.
+- 254ef6d: Add scoped route hooks for route and route-group policy, update auth hooks to expose public/optional/required route-hook factories, and teach CLI route inspection about curried route groups.
+- 4cb1784: Add first-class upload router primitives, a typed browser upload client, a
+  React upload adapter, Next.js upload route helper, S3-compatible direct upload
+  signing, devtools upload watcher support, an upload generator, and a
+  first-class `beignet make feature` command with optional policy, event, job,
+  and upload artifacts for the standard vertical slice. Add first-class job retry
+  helpers, outbox retry policy integration, and job retry/dead-letter devtools
+  events. Add a Next.js outbox drain route helper and doctor warnings for
+  serverless background-work footguns.
+- 8bd9085: Add `@beignet/web` as a framework-neutral Web Fetch adapter, include a `@beignet/web/testing` route test harness, and have `@beignet/next` reuse the Web adapter for standard Request/Response handling.
+
 ## 0.0.2
 
 ### Patch Changes