cvx-kit 0.1.14 → 0.1.16

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.

package/docs/approvals.md

@@ -1,201 +0,0 @@
-# `cvx-kit/components/approvals` — declarative approval workflows
-
-A self-contained Convex component for human-in-the-loop approval flows:
-declarative step lists (decision / branch / mutation / action / notify) with
-count quorum, maker-checker, expiry, compatibility keys, durable execution via
-a **nested** `@convex-dev/workflow`, and its own audit trail via a **nested**
-`convex-audit-log`. The component never imports host code: tenancy is an
-opaque `scopeRef`, resources are opaque `resourceType`/`resourceRef` strings,
-and callbacks cross the boundary as **function handles**.
-
-## Mounting
-
-```ts
-// convex/convex.config.ts
-import approvals from 'cvx-kit/components/approvals/convex.config'
-app.use(approvals)
-```
-
-After installation or upgrade, deploy once and run the component health query
-from a host wrapper:
-
-```ts
-return ctx.runQuery(components.approvals.health.check, {})
-```
-
-It returns the installed approvals schema version and required index names. It
-also executes reads through
-`approvalDecisions.by_runId_and_decidedAt` and
-`approvalDecisions.by_runId_and_stepKey_and_actor_actorRef`, failing with an
-installation-specific diagnostic if the packaged component schema was not
-deployed.
-
-The component mounts its own private `workflow` and `auditLog` children. Do
-**not** re-register those children at the app root under the same identity,
-and never reach into `components.approvals.workflow` / `.auditLog` from host
-code — the `Approvals` client class is the only contract.
-
-```ts
-// convex/approvals.ts — host facade, declared once
-import { Approvals } from 'cvx-kit/components/approvals'
-import { components } from './_generated/api'
-
-export const approvals = new Approvals(components.approvals)
-```
-
-## Defining a workflow — in the owning domain
-
-Workflow _definitions_ are business logic and live in the domain that owns the
-resource, not in the root facade:
-
-```ts
-// convex/domain/documents/approval.ts
-import { approvals } from '../../approvals'
-import { internal } from '../../_generated/api'
-
-export const publishApproval = approvals.define({
-	name: 'documentPublish',
-	steps: [
-		approvals.decision('managerDecision', {
-			decisions: ['approved', 'rejected'],
-			quorum: { kind: 'count', approvals: 1 },
-			makerChecker: true, // requester cannot decide
-			expiresAfterMs: 7 * 24 * 60 * 60 * 1000,
-		}),
-		approvals.branch('applyDecision', {
-			approvedStepKey: 'publishDocument',
-			rejectedStepKey: 'notifyRejected',
-		}),
-		approvals.mutation('publishDocument', {
-			handler: internal.domain.documents.approval_functions.applyDecision,
-		}),
-		approvals.notify('notifyRejected', {
-			handler: internal.domain.documents.approval_functions.notifyRejected,
-			retry: true,
-		}),
-	],
-})
-```
-
-### Step kinds
-
-| Step                                                                   | Runs                     | Notes                                                                             |
-| ---------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
-| `decision(key, { decisions, quorum, makerChecker?, expiresAfterMs? })` | waits for humans         | quorum is `{ kind: 'count', approvals: n }`; expiry resolves the run as `expired` |
-| `branch(key, { approvedStepKey, rejectedStepKey })`                    | routing                  | jumps by the preceding decision's outcome                                         |
-| `mutation(key, { handler, retry? })`                                   | internal mutation handle | transactional apply step                                                          |
-| `action(key, { handler, retry? })`                                     | internal action handle   | side effects (third parties)                                                      |
-| `notify(key, { handler, retry? })`                                     | internal action handle   | semantically a notification; same contract as action                              |
-
-Limits (enforced by the component's validators): ≤ 32 steps per workflow,
-≤ 8 decisions per decision step, names ≤ 96 chars, references ≤ 256 chars,
-metadata ≤ 32 entries (keys ≤ 64, values ≤ 512 chars).
-
-### Compatibility keys
-
-`compatibilityKey` (defaults to `name`) versions the workflow shape. Every
-`decide`/`cancel`/`status`/`restart` call sends it, so a run started under an
-old definition cannot be driven by an incompatible new one. When you change a
-workflow's steps in a breaking way, change the key.
-
-## Driving a run
-
-```ts
-// start — from an authMutation, with ctx.actor as the requester
-const { runId } = await publishApproval.start(ctx, {
-	scopeRef: ctx.org.organizationId, // opaque tenancy
-	resourceType: 'document',
-	resourceRef: documentId, // opaque to the component
-	requester: ctx.actor,
-	metadata: { title }, // bounded string map
-})
-
-// decide — a manager approves or rejects
-await publishApproval.decide(ctx, { runId, decision: 'approved', reason }, ctx.actor)
-
-// observe from a host query
-await publishApproval.status(ctx, runId) // pending | approved | rejected | expired | canceled
-await publishApproval.evidence(ctx, runId) // per-step decision evidence
-await publishApproval.list(ctx, {
-	scopeRef,
-	state: 'pending',
-	paginationOpts: { cursor: null, numItems: 20 },
-})
-
-// manage
-await publishApproval.cancel(ctx, runId, ctx.actor)
-await publishApproval.restart(ctx, runId)
-await approvals.cleanupAudit(ctx, { olderThanDays: 365, batchSize: 100 })
-```
-
-## Callback handlers — validate everything coming back
-
-Step handlers are **internal** functions (build them with `systemMutation` /
-`systemAction`). They receive `ApprovalCallbackInput`: `{ runId, scopeRef,
-resourceType, resourceRef, metadata?, decision? }` — all opaque strings.
-Because the component cannot know your tables, the handler must re-establish
-trust:
-
-```ts
-import { approvalCallbackArgs } from 'cvx-kit/components/approvals'
-
-export const applyDecision = systemMutation({
-	args: approvalCallbackArgs,
-	handler: async (ctx, input) => {
-		if (input.resourceType !== 'document') throw new Error('WRONG_RESOURCE')
-		const id = ctx.db.normalizeId('documents', input.resourceRef)
-		if (!id) throw new Error('BAD_REF')
-		const document = await ctx.db.get(id)
-		// guard against stale runs: the doc must still point at this run
-		if (document?.approvalRunId !== input.runId) return
-		await ctx.db.patch(id, { reviewState: 'published' })
-	},
-})
-```
-
-That `approvalRunId` check is the idempotency/staleness guard from the origin
-app — copy it.
-
-For branch callbacks, `decision.evidence` contains
-`{ stepKey, actorRef, decision, reason?, decidedAt }` items. Use the exported
-`approvalCallbackArgs` validator instead of duplicating that protocol boundary.
-
-### Paginated inboxes
-
-Expose the configured workflow through a host query; component pagination uses
-`convex-helpers` internally because Convex's built-in `.paginate()` is not
-available inside components:
-
-```ts
-export const approvalInbox = authQuery({
-	args: {
-		state: z.enum(['pending', 'approved', 'rejected', 'expired', 'canceled']).optional(),
-		paginationOpts: convexToZod(paginationOptsValidator),
-	},
-	handler: (ctx, args) =>
-		publishApproval.list(ctx, {
-			scopeRef: ctx.org.organizationId,
-			...args,
-		}),
-})
-```
-
-The result keeps Convex's standard pagination shape, so React consumers can
-call `usePaginatedQuery(api.approvals.approvalInbox, { state: 'pending' },
-{ initialNumItems: 20 })`. Pass each returned cursor only back to the same
-scope/state query.
-
-## Rules and footguns
-
-1. Root facade (`convex/approvals.ts`) instantiates the client; workflow
-   _definitions_ live in the owning domain.
-2. Handlers get opaque strings — always `normalizeId`, re-check
-   `resourceType`, and verify the resource still references the run.
-3. `makerChecker: true` means the requester's decisions are rejected — design
-   your UI accordingly.
-4. The component keeps its own audit trail (retention category
-   `approval-protocol`, cleanup via `cleanupAudit`, retention 1–3650 days,
-   batch ≤ 100). Host-side business audit still goes through your command
-   protocol — they are different trails.
-5. Changing steps without changing `compatibilityKey` lets old runs be driven
-   by a new incompatible shape; bump the key on breaking changes.

package/docs/architecture.md

@@ -1,124 +0,0 @@
-# Architecture — the shape of a cvx-kit application
-
-cvx-kit was extracted from a production Convex application (~12k LOC backend).
-This document describes the architecture that application follows and that the
-kit is designed to reproduce: strict ownership boundaries, injected policy,
-portable components, and conventions that are _executable_ (enforced by tests)
-rather than aspirational.
-
-## The layers
-
-```
-convex/
-  convex.config.ts        # component mounting — each app.use(x) exactly once
-  schema.ts               # defineSchema(domainTables) — nothing else
-  functions.ts            # createAuthFunctions(...) — the ONLY place raw builders appear
-  foundation.ts           # const { Command, Query, observability } = createEffectFoundation(...)
-  approvals.ts            # const approvals = new Approvals(components.approvals)
-  audit.ts                # writeAuditEntry over convex-audit-log + admin readers
-  triggers.ts             # the single Triggers registry + helper registrations
-  auth.ts / auth.config.ts / http.ts   # identity provider wiring (e.g. WorkOS AuthKit)
-  api/                    # PUBLIC surface — thin adapters only
-    <documents>.ts          #   authQuery/authMutation wrapping domain executors
-  domain/
-    table.ts              # merges per-domain table maps into domainTables
-    shared/               # genuinely cross-entity helpers only
-    <entity>/            # one directory per entity/aggregate
-      schema.ts           #   zodTable declaration (shapes only)
-      table.ts            #   indexes attached to <zodTable>.table
-      constants.ts        #   finite vocabularies (UPPER_SNAKE readonly tuples)
-      commands.ts         #   Command({ context, operations }) with handlers inside command({...})
-      queries.ts          #   domain read logic
-      approval.ts         #   approvals.define(...) workflow definitions
-      *_functions.ts      #   internal callbacks (systemMutation/systemAction)
-```
-
-### Layer rules
-
-1. **`api/` is the only public surface.** It contains no bare `query(` or
-   `mutation(` — only `auth*`/`role*`/`admin*` constructors delegating to
-   domain `execute*` functions. Public functions are adapters: parse, pass
-   `ctx.actor`, project DTOs.
-2. **`domain/<entity>/` owns everything about the entity** — its zod shape,
-   indexes, vocabularies, commands, queries, workflows. Cross-domain reuse
-   goes through `domain/shared/`, never sibling imports of another domain's
-   internals.
-3. **Root files are facades over mounted components.** `foundation.ts`,
-   `approvals.ts`, `audit.ts` configure infrastructure; business definitions
-   stay in the owning domain.
-4. **Internal functions use `systemMutation`/`systemAction`** — never raw
-   `internalMutation(`/`internalAction(` — so triggers and `include` apply to
-   scheduled/callback work too.
-
-## Injection, not import
-
-The kit's central design rule: **library code never imports app singletons**.
-Every kit surface takes its policy as a parameter:
-
-- `createAuthFunctions` receives the generated builders, `getAuthUser`,
-  `mapRole`, `verifyMembership`, `triggers`, `errors`.
-- `createEffectFoundation` receives `classifyError`, `writeAudit`, the `enabled` flag.
-- `Approvals` receives only its component reference; host data crosses as
-  opaque validated strings.
-
-The reverse rule holds for components: a portable component must not import
-host domains, generated host APIs, environment configuration, or vendor SDKs
-(WorkOS, Drizzle, Redis…). Host values cross its public API only as
-**validated, bounded, opaque data** — `scopeRef`, `resourceRef`, function
-handles. Component schemas contain only their own records and never mirror a
-private child component's tables.
-
-## Boundaries as schemas
-
-Data crossing any boundary is a zod schema derived from one `zodTable`
-declaration per entity (see `zod-table.md`):
-
-- storage → `defineTable` via `zodToConvex`
-- writes → `insertSchema`/`updateSchema` (server fields and timestamps
-  excluded)
-- commands → `commandInput` (explicit allowlist)
-- clients → `publicDto` + `toPublicDto` (runtime redaction)
-- LLM tools → `tools.*` and `jsonSafeZid`
-
-Everything is `.strict()`. There is exactly one source of truth per entity and
-no boundary that "just trusts" its input.
-
-## Writes as commands
-
-State changes flow through the audited command protocol (see `commands.md`):
-parse input → observe → run handler → parse output → write audit — one
-transaction, rollback-consistent. Classifications and audit derivation are
-type-required per operation. Human-gated changes use the approvals component;
-its apply steps are commands too.
-
-## Conventions worth enforcing with tests
-
-The origin app enforces its architecture with a test suite that raw-globs the
-source and asserts violations — each rule proved against a synthetic fixture
-first so the checker can't silently pass. Highly recommended for consumers:
-
-- **No inline tables/schemas** — `defineTable`/`defineSchema` only in
-  `table.ts`/`schema.ts`.
-- **No inline enums** — `z.enum([...])` with an inline array literal is
-  banned; vocabularies are named `UPPER_SNAKE` tuples in `constants.ts`.
-- **No deep server imports** — components consumed only through their
-  `client.ts` facade; explicit allowlist for exceptions.
-- **No handwritten references** — `makeFunctionReference` banned; use
-  generated `internal`/`api`.
-- **No sibling-domain imports** — a domain reaches another only via
-  `domain/shared/` or the public API.
-- **Facades mount once** — every `app.use(x)` appears exactly once; facades
-  never reach a component's private children.
-- **Component boundary tests** — no host imports, no
-  `process.env`/vendor-SDK references inside `components/*`.
-- **Copyability** — copy the component to a tmpdir with only its package
-  deps, run `tsc`: proves portability continuously.
-
-## Component mounting order
-
-In `convex.config.ts`, mount infrastructure before consumers: auth kit →
-foundation → audit log → approvals → named workflow/workpool instances. Use
-`app.use(x, { name })` when mounting the same component twice; `components.
-<name>` keys off that name. Required env vars can be declared on
-`defineApp({ env: { ... } })` so deploys fail fast — remember to stub them in
-test setup.