cvx-kit 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -1,337 +0,0 @@
-# Changelog
-
-All notable changes to cvx-kit are documented here. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-
-**Semver contract (from 0.1.0):** while on 0.x, breaking changes land only on
-minor bumps; patches are additive or fixes. The breaking window formally
-closes at the follow-up consolidation release (package-name decision + full
-export-name API audit) — until then, the six 0.1.0 helper surfaces may still
-be renamed in a minor. Every release tag gets a GitHub Release whose notes
-are this file's matching section.
-
-## [Unreleased]
-
-## [0.1.15] - 2026-10-11
-
-### Added
-
-- Declare a global query engine with only `createQueryEngine({ schema, relations })`.
-- Load cursor secrets internally from server environment configuration on first pagination.
-- Configure optional engine overrides in a separate second argument, while preserving existing declarations.
-
-### Changed
-
-- Document global engine setup, server cursor secrets, and the purpose of advanced options.
-- Publish releases after successful CI for the exact main commit, without repeating tests in the release workflow.
-
-## [0.1.14] - 2026-10-11
-
-### Added
-
-- Typed relational queries with scalar and relationship filters, conditional indexes, global ascending or descending order, and bounded stream pagination.
-- Explicit relationship declarations for direct, self, and junction relationships, with paginated child continuations.
-- Managed query authorization, shared read budgets, and encrypted cursors bound to the query, principal, tenant, and parent relationship.
-- Table DTO options for validated IDs and extensions, including `toPublicDto(row, true)`, plus native-derived `paginationOpts` and page DTO helpers.
-- Oxlint enforcement for manual ID projections, copied pagination contracts, and unsafe relational query boundaries.
-- Dedicated querying documentation and updated table and rule documentation in `src/docs`.
-
-### Fixed
-
-- Preserve shared validator graphs during native auth registration to avoid repeated validator expansion.
-
-### Verified
-
-- Source, type, rule, and packed-consumer checks; 308 independently audited relational stress sequences across installed and minimum peer versions.
-- 33 HTTP responses exercised encrypted cursor pagination and rejection paths on a local Convex backend. Hosted production performance remains unmeasured.
-
-## [0.1.13] - 2026-10-10
-
-### Added
-
-- Implement contracted operations with `command.handler(handler, options?)` and
-  `query.handler(handler, options?)` in both Promise and Effect registries.
-- Infer each handler's input and result from its operation object key, without
-  repeating the operation name; preserve existing named helpers.
-
-### Verified
-
-- Cover contract binding, validation, audits, and handler inference with 684
-  runtime tests and strict type fixtures.
-- Compile the documentation examples and test packed npm/Bun consumers with
-  and without Effect.
-
-## [0.1.12] - 2026-10-10
-
-### Added
-
-- Declare optional domain contracts with root errors, command classification,
-  and exact command/query implementation keys in both Effect and Promise registries (#26).
-- Share a registry-level command audit default with per-operation overrides,
-  preserving replay bypass, schema inference, and transactional rollback.
-- Use `createFoundation` for typed Promise registries without installing Effect.
-- Enforce reserved domain file declarations through the packaged Oxlint plugin,
-  including constructor provenance and declarative contract ownership.
-- Document both contract APIs with packed-compiled examples and audit guidance.
-
-### Verified
-
-- Cover native validation, error projection, rollback, audit selection, agent tools,
-  workflow integration, and npm/Bun consumers with and without Effect.
-- Pass 680 runtime tests, 340 lint-rule tests, and both packed-component CI smoke tests.
-
-## [0.1.11] - 2026-10-09
-
-### Added
-
-- Configure shared post-auth Effect services and command/query handles once across
-  all auth, role, admin, and system constructors with `createEffectAuthFunctions` (#24).
-- Keep query, mutation, action, and internal system capabilities separately typed
-  and configured; preserve secured database wrapping and live action membership.
-- Document the shared application factory with packed-compiled examples and
-  constructor capability guidance for coding agents.
-
-### Verified
-
-- Cover denied authentication, roles and membership, request-local scopes, context
-  collisions, nested command auditing, and registered mutation rollback.
-- Preserve packed native auth context compatibility on Convex 1.45 and 1.46.
-
-## [0.1.10] - 2026-10-09
-
-### Fixed
-
-- Preserve native Convex context types in auth, role, admin, and system function
-  constructors so secured handlers bind directly to Effect registries (#22).
-- Install Standard Schema types explicitly so native contract input and output
-  inference works in clean installations.
-
-### Changed
-
-- Update package dependencies and migrate the development toolchain to Vite+ 1.1.
-- Require Convex 1.46 or newer and convex-helpers 0.1.127 or newer (below 0.2.0),
-  matching workflow 0.4.10.
-
-## [0.1.7] - 2026-10-07
-
-### Added
-
-- Add optional Effect 4 command and query registries with cohesive ordinary,
-  Promise, generator, and function handlers, injected services, and scoped API
-  execution through native and custom Convex builders.
-- Add asynchronous operation contracts, explicit schema adapters, and checked
-  transport for declared safe errors.
-- Add injectable audited Effect CRUD, host-owned transactional idempotency
-  receipts, native durable workflow bindings, and selected domain operation tools.
-- Document server-side declaration, composition, API consumption, receipts,
-  workflows, and tools with compile-checked public-package examples.
-
-### Fixed
-
-- Preserve native validators, trusted authorization, RLS, triggers, audit, and
-  rollback across API, workflow, and tool integrations.
-- Reconcile late workflow outcomes without allowing stale generations or late
-  completion to overwrite canceled runs.
-- Validate retained receipt versions before fingerprints and replay, and require
-  current authorization before disclosing replayed results.
-
-## [0.1.6] - 2026-09-19
-
-### Added
-
-- Add five opt-in consumer Oxlint rules for project structure, root wiring,
-  application orchestration, internal function ownership, and domain file
-  responsibilities. The packaged plugin now includes 20 rules.
-- Check colocated test presence, runtime import cycles, and shared-code ownership.
-  Export `checkArchitecture` for standalone checks without copying architecture
-  test suites into applications. These static checks do not replace behavior tests.
-
-### Fixed
-
-- Resolve tsconfig aliases when checking consumer import boundaries and reject
-  migration dependencies from application code.
-- Enforce documented ownership of domain implementations, table aggregation,
-  query side effects, and component boundaries.
-
-## [0.1.5] - 2026-09-18
-
-### Fixed
-
-- Correct `cvx-kit/oxlint` to enforce the documented consumer `convex/` layout
-  rather than this repository's `src/` layout. Keep the six library-authoring
-  rules in repository tooling and publish 15 consumer rules, with coverage for
-  domain boundaries, auth builders, thin adapters, facade ownership, table
-  placement, vocabularies, bounded read syntax, and trigger-owned timestamps.
-- Replace consumer `entryPoints`/`packageName` options with `convexDir`; document
-  migration, allowed exceptions, and the checks that still need runtime tests.
-  Validate the packaged plugin against consumer fixtures installed by npm and Bun.
-
-## [0.1.4] - 2026-09-18
-
-### Added
-
-- Publish the TypeScript Oxlint plugin as `cvx-kit/oxlint`, with six rules for
-  component isolation, environment access, schema placement, public facades,
-  API ordering, and named private helpers. Consumer entry points and package
-  self-import boundaries are configurable.
-- Enforce all 15 generic anti-slop rules in the repository and verify the
-  published plugin through fresh npm and Bun installations in CI.
-
-### Changed
-
-- Replace cast-heavy command, CRUD, tenancy, auth, webhook, and tool boundaries
-  with schema-derived types and validation. Preserve distinct agent-tool result
-  types and validate the emitted declarations in packed consumers.
-- Tighten TypeScript contracts for query middleware, include transforms, audit
-  metadata, and webhook targets. See `docs/upgrading.md` for migration details.
-- Format owned source, tests, scripts, and documentation consistently.
-
-## [0.1.3] - 2026-09-06
-
-### Fixed
-
-- Fix Convex ID validation across package boundaries by sharing `convex-helpers`
-  as a peer dependency. Export `zid`, `zodToConvex`, and `convexToZod` from
-  `cvx-kit/zod-table`; verify differing compatible host versions under npm and Bun (#10).
-- Add `Command.withContext<Context, Extension>()` for schema-inferred guards,
-  audit callbacks, operation middleware, and correlated registry middleware (#11).
-- Add invocation-local `prepare` hooks with authorized, validated replay and
-  completion after audit, inside observation. Durable storage remains host-owned (#12).
-- Accept concrete and generic `convex-test` backends directly in registration helpers (#13).
-- Parse command results once after middleware; handler and middleware result types
-  describe schema inputs, while audit, completion, and executor results describe outputs.
-- Accept raw command schema inputs at executor call sites while inferring parsed
-  outputs for callbacks; reject incompatible typed host contexts and registry middleware.
-- See `docs/upgrading.md` for helper peer installation and transformed-result migration.
-
-## [0.1.2] - 2026-08-21
-
-### Added
-
-- `resolveOrganization` hook on `createAuthFunctions`: identity providers
-  whose tokens carry no org claims (custom credentials, magic codes,
-  memberships in app tables) can resolve organization and role from the
-  database. When configured, the hook overrides claim-based resolution and
-  fails closed — `null` or an error rejects with `FORBIDDEN`; its `roleSlug`
-  still passes `mapRole`, tenancy derives from the hook's organization, and
-  `verifyMembership` for actions is unchanged. Hook-less configurations are
-  unaffected. ([#8](https://github.com/ImRLopezAG/cvx-kit/issues/8))
-
-## [0.1.1] - 2026-08-17
-
-### Fixed
-
-- Package Convex component schemas exclusively as discoverable `schema.js` and
-  `schema.d.ts` files. This restores the approvals tables and the
-  `approvalDecisions.by_runId_and_decidedAt` and
-  `approvalDecisions.by_runId_and_stepKey_and_actor_actorRef` indexes without
-  consumer `patchedDependencies` workarounds or canonicalization conflicts.
-- Keep compiled component imports aligned with the discoverable `schema.js`
-  filename when runtime functions use the schema directly.
-- Include `stepKey` in the public approval callback evidence contract and
-  export canonical Zod and Convex callback validators for strict consumers.
-- Use component-safe cursor pagination for approval request lists instead of
-  Convex's app-only built-in `.paginate()` implementation.
-
-### Added
-
-- Packed-tarball content checks and clean anonymous-deployment smoke tests for
-  every bundled component under both Bun and npm installation.
-- `components.approvals.health.check`, which verifies the approvals schema
-  version and required decision indexes with an actionable failure diagnostic.
-- Supported Convex, Zod, Bun, Node.js, and npm versions plus an approvals
-  packaging migration note.
-- Packed callback and paginated-list smoke coverage through real host wrappers.
-
-## [0.1.0] - 2026-08-14
-
-The big one: the full helper surface, in one release.
-
-### Added
-
-- **Pagination bridge** — `paginated(dto)` boundary schemas
-  (`cvx-kit/zod-table`) and an `include(...).paginate(opts, transform?)`
-  terminal (`cvx-kit/auth`): cursor pagination bounded by the same maxRows
-  policy as `execute`. Under row-level security, pages may be shorter than
-  `numItems` (filtered rows); cursors remain correct.
-- **CRUD command factory** — `createCrudCommands` (`cvx-kit/crud`):
-  create/update/archive operations generated from a zodTable, fully inside
-  the audited command pipeline; soft-delete only; `enrich` is required for
-  tenantTables (fails fast with `CRUD_ENRICH_REQUIRED`).
-- **State-machine helper** — `createStateMachine` (`cvx-kit/state-machine`):
-  typed transition legality from constants tuples; `assert` throws
-  `INVALID_TRANSITION` via the injected ErrorFactory, dropping straight into
-  command guards.
-- **Rate-limit middleware** — `rateLimit` (`cvx-kit/middleware`): the first
-  packaged middleware, over an injected `@convex-dev/rate-limiter` instance
-  (structural typing — zero new kit dependencies). Keyed by `ctx.tenant` by
-  default; a missing key is a configuration error
-  (`RATE_LIMIT_KEY_MISSING`), never a silent shared bucket.
-- **Webhook boundary** — `createWebhookBoundary`, `recordWebhookEvent`,
-  `webhookEventsTable` (`cvx-kit/webhooks`): raw-body signature verification
-  (fail closed), natural-key dedup transactional inside the target internal
-  mutation, host-owned dedup table.
-- **Agent tool generator** — `createAgentTools` (`cvx-kit/agent-tools`):
-  tool records from the table tool masks, shape-compatible with
-  `@convex-dev/agent`'s `createTool` without depending on it; mutation
-  handlers route through command executors so agents get audited commands.
-- **Typed middleware context** — `Command.middleware<Ctx, Extension>` /
-  `Query.middleware<Ctx, Extension>`: `next({ context })` is typed against
-  the declared extension; registries and operations accept typed middleware
-  without casts (`AnyCommandMiddleware`/`AnyQueryMiddleware` variance seam).
-- **Upgrade guide** — `docs/upgrading.md` ships in the package: old way →
-  new way per feature for consumers on 0.0.x.
-
-### Changed
-
-- `tools.update` / `tools.id` masks now use `jsonSafeZid` instead of `zid`,
-  so ids present as plain strings in generated JSON schemas (compile-time
-  `Id<...>` types preserved).
-- Release workflow now creates a GitHub Release with this file's section as
-  notes, and action pins are updated past the Node 20 deprecation.
-
-## [0.0.8] - 2026-08-14
-
-- Composable next()-based middleware for Command and Query kernels, inside
-  pipeline invariants (registry-wide + per-operation, context enrichment,
-  result re-parse).
-
-## [0.0.7] - 2026-08-14
-
-- `systemQuery` constructor: internal, include-equipped, RLS-unwrapped.
-  BREAKING: `createAuthFunctions` config requires the `internalQuery` builder.
-
-## [0.0.6] - 2026-08-14
-
-- Materialized `convex.config.js` bridges (Convex CLI discovers components by
-  that literal filename). BREAKING: mount via
-  `cvx-kit/components/<name>/convex.config`; client facades no longer
-  default-export the component config.
-
-## [0.0.5] - 2026-08-14
-
-- BREAKING: the Foundation facade is the only runtime surface — kernel
-  classes and execution utilities destructure from the instance.
-
-## [0.0.4] - 2026-08-14
-
-- Tarball ships only `dist`, `docs`, and the source test helper
-  (`.npmignore`); `cvx-kit/test` registers compiled dist modules.
-
-## [0.0.3] - 2026-08-14
-
-- Opt-in tenancy and security controls: `tenantTable`, `createModule`,
-  `security` config on `createAuthFunctions` (role rules + tenant RLS),
-  `ctx.tenant`, `cvx-kit/tenancy`, `tenantOwnership` trigger. Command
-  guards, permission checks, and the aggregate allowlist.
-
-## [0.0.2] - 2026-08-13
-
-- Shipped package documentation (architecture, conventions, migration,
-  llms) at `docs/`; opinionated timestamps on every table; single-path
-  component mounts.
-
-## [0.0.1] - 2026-08-13
-
-- Initial release: foundation + approvals components, zod-table boundaries,
-  auth constructors, triggers, audited command protocol.

package/ROADMAP.md

@@ -1,126 +0,0 @@
-# Roadmap to 1.0.0
-
-Where cvx-kit is going and what "stable" will mean. Tracked with checkboxes;
-each milestone ships as one minor version. From `0.1.0` on, **breaking
-changes only land on minor bumps** (0.x semver: minor = breaking, patch =
-fix/additive) and every release gets a CHANGELOG entry.
-
-## 0.1.0 — the big one: API consolidation + the feature set
-
-Goal: one release that both closes the breaking window AND ships the full
-helper surface, so consumers adopt a complete kit once instead of chasing
-minors. Everything here may still rename freely — that's why the features
-belong in this milestone: they land already conforming to the frozen names.
-
-### Consolidation (the last breaking pass)
-
-- [ ] Decide the published name (`cvx-kit` is a working title) and, if it
-      changes, publish under the final name with `cvx-kit` deprecated.
-- [ ] API audit: review every exported name, option key, and error code
-      against `conventions.md`'s own naming grammar; freeze the error-code
-      taxonomy (`KitError` codes) as a documented tuple.
-- [x] Typed middleware context accumulation: `next({ context })` currently
-      merges loosely; tighten so enrichment widens the downstream ctx type
-      (TanStack-style), without breaking the loose form.
-- [x] Introduce `CHANGELOG.md` + release notes on the GitHub tag; adopt the
-      0.x semver contract above. (GitHub Releases automated in release.yml.)
-- [ ] CI hardening: add `--dry-run` pack + `attw` (Are The Types Wrong) next
-      to publint; bump the deprecated actions pins.
-
-### Features
-
-- [x] **Pagination bridge** — `paginated(table.publicDto)` arg/return
-      helpers over Convex's pagination validators, and an
-      `include(...).paginate(opts)` terminal next to `.execute(limit)`:
-      cursors, not just bounded `take`.
-- [x] **CRUD command factory** — `createCrudCommands(table, policy)`
-      generating the standard create/update/archive operations from a
-      zodTable's masks: command input from `commandFields`, audit derivation
-      from the aggregate, timestamps/tenant already structural. The single
-      biggest remaining per-entity boilerplate.
-- [x] **State-machine helper** — `createStateMachine(STATES, transitions)`
-      typed against the constants tuple, returning `isTransitionLegal` /
-      `assertTransition` that drop straight into a command `guard`.
-- [x] **Rate-limit middleware factory** — the first official middleware:
-      `rateLimit({ key: (ctx) => ctx.tenant, ... })` over
-      `@convex-dev/rate-limiter`, packaged as `Command.middleware` /
-      `Query.middleware` and the template for future middleware.
-- [x] **Webhook boundary helper** — signature verification + event dedup by
-      natural key (`${event}:${id}:${updatedAt}`) + delegation to a
-      `system*` function: the one boundary that genuinely needs dedup, as a
-      first-class helper.
-- [x] **Agent tool generator** — `createAgentTools(table, executors)`
-      emitting `@convex-dev/agent` tool definitions from the existing
-      `tools.*` masks + `jsonSafeZid`, with handlers routed through the
-      command protocol — agents get audited commands, never raw db access.
-
-Each feature ships with its own doc page (or section), tests on the real
-Convex runtime where applicable, and an `llms.md` entry.
-
-## 0.2.0 — guardrails as a product
-
-Goal: the conventions the docs prescribe become importable tests, so a
-consumer gets the origin app's discipline on day one — enforced against the
-by-then-frozen 0.1.0 names.
-
-- [ ] `createArchitectureTest(rules)` — glob-based rule runner with the
-      standard rules built in (no raw builders outside functions.ts, no
-      inline tables/enums, no sibling-domain imports, no deep component
-      imports, facades mount once), each rule fixture-proved, extensible
-      with app-specific rules.
-- [ ] Tenancy exhaustiveness helper: assert every `tenantTable` is in the
-      registry and vice versa; assert internal builders accept no tenant arg.
-- [ ] `llms.md` conformance check: an automated test that every export in
-      its tables exists with that signature (also an rc gate — build it here).
-- [ ] Port the approvals copyability test (cp -r + tsc) into this repo's
-      suite as the permanent portability guarantee for both components.
-
-## 0.3.0 — scaffolding
-
-Goal: the first hour of a new app is generated, not hand-written.
-
-- [ ] WorkOS scaffold generator: `auth.ts`, `auth.config.ts`, `http.ts`,
-      `functions.ts`, `foundation.ts`, `triggers.ts` from one command.
-- [ ] Audit facade helpers over any `convex-audit-log` instance:
-      fingerprinted cursors, bounded windows, admin readers.
-- [ ] Decide on the optional idempotency/replay component (deferred from
-      0.0.x — only if a consumer demonstrates the need beyond Convex's
-      exactly-once mutation delivery).
-
-## 1.0.0-rc — proving it
-
-Entry gates, not work items. The rc ships when all are true:
-
-- [ ] Two real applications run the latest kit in production-like use for
-      several weeks (the multi-tenant integration and one more).
-- [ ] One full minor cycle with zero breaking changes needed.
-- [ ] Docs complete and verified: the `llms.md` conformance check (built in
-      0.2.0) green in CI.
-- [ ] CI matrix: bun + node LTS, convex peer-range min and latest.
-- [ ] Public-API test coverage: every exported runtime symbol exercised by
-      at least one test.
-
-## 1.0.0
-
-- [ ] Freeze the export surface; document the semver contract (what counts
-      as breaking, deprecation policy of one minor with warnings).
-- [ ] `MIGRATING.md` from 0.x.
-- [ ] Provenance, README badges, and a docs site or expanded README landing.
-
-## Candidates (recorded, not committed)
-
-- Observability sink adapters: OTel/Axiom-shaped formatters for the
-  injectable `emit`, so `command.execution` events land in real telemetry
-  without per-consumer mapping.
-- Migration companion: a thin `@convex-dev/migrations` wrapper aligned with
-  zodTable epochs ("make optional field required after backfill" as a
-  declared step), closing the loop with `migration.md`.
-
-## Explicitly out of scope for 1.0
-
-- General idempotency store (platform already covers single-call
-  exactly-once; boundary dedup is the webhook helper's job).
-- Frontend helpers/React bindings.
-- Multi-provider auth abstractions beyond the injected-policy seam
-  (`createAuthFunctions` already accepts any provider via `getAuthUser`/
-  `mapRole`/`verifyMembership`).

package/docs/agent-tools.md

@@ -1,41 +0,0 @@
-# `cvx-kit/agent-tools` — agents get audited commands
-
-`createAgentTools` turns a table's tool masks into framework-agnostic tool
-records `{ name, description, args, handler }` — directly spreadable into
-`@convex-dev/agent`'s `createTool`, adaptable to ai-sdk `tool()`, and the
-kit depends on neither (shape checked against `@convex-dev/agent@0.6.x`;
-re-verify at install).
-
-The point is the routing, not the shape: **mutation handlers go through
-command executors**, so every agent action is validated, guarded, audited,
-and observed. An agent never gets raw db access.
-
-```ts
-import { createAgentTools } from 'cvx-kit/agent-tools'
-
-const tools = createAgentTools(<entities>, {
-  // mutations — audited commands (createCrudCommands executors fit exactly):
-  create: (ctx, input) => crud.executeCreate(ctx, input),
-  update: (ctx, input) => crud.executeUpdate(ctx, input),
-  archive: (ctx, input) => crud.executeArchive(ctx, input),
-  // reads — caller-supplied query handlers (reads don't route through commands):
-  get: (ctx, { id }) => loadDto(ctx, id),
-  list: (ctx, { paginationOpts }) => listPage(ctx, paginationOpts),
-})
-
-// host-side, with @convex-dev/agent:
-// const agentTools = Object.fromEntries(Object.values(tools).map((t) =>
-//   [t.name, createTool({ description: t.description, args: t.args, handler: t.handler })]))
-```
-
-## Contracts
-
-- **Args are the table masks, no drift**: `create` = `tools.insert`
-  (`commandFields`), `update` = `tools.update`, `archive`/`get` = `tools.id`,
-  `list` = the pagination opts boundary. Ids present as plain strings in
-  generated JSON schemas (`jsonSafeZid`) while keeping `Id<...>` types.
-- **Only the kinds you supply handlers for are emitted**; names are
-  `<tableName>_<verb>`; descriptions are derived and overridable via
-  `options.descriptions`.
-- DTO discipline applies to reads: `get`/`list` handlers should return
-  `toPublicDto`-projected data, same as any public query.