cvx-kit 0.0.1 → 0.0.3

package/docs/llms.md

@@ -0,0 +1,206 @@
+# cvx-kit — condensed reference for LLMs and coding agents
+
+> Paste this file (installed at `node_modules/cvx-kit/docs/`) into an agent's
+> context when it works on a cvx-kit application. Detailed docs:
+> `architecture.md`, `conventions.md`, `zod-table.md`, `auth.md`,
+> `commands.md`, `triggers.md`, `approvals.md`, `maintainability.md`,
+> `migration.md` (same directory).
+> Structure, file anatomy, and naming rules → `conventions.md` is
+> authoritative. Restructuring an existing raw project → `migration.md`.
+
+> **Placeholders.** Names like `documents`, `users`, `history`, `title`,
+> `ownerId`, and `documentPublish` in the examples below are illustrative
+> only — replace them with the application's own entities and fields. No
+> specific table, entity, field, or workflow is required by the kit. Names in
+> `<angle brackets>` are always placeholders.
+
+cvx-kit is a reusable Convex application kit: zod table boundaries, auth-aware
+function constructors, a trigger registry, an audited command protocol
+(Foundation component), and a declarative approvals component. Peer deps:
+`convex ^1.43`, `zod ^4`.
+
+## Non-negotiable rules
+
+1. **One `zodTable` per entity**, in `domain/<entity>/schema.ts`. Never write
+   `defineTable` inline or a second zod object for the same entity.
+2. **Raw `query`/`mutation`/`action`/`internal*` builders appear only in
+   `convex/functions.ts`** (the `createAuthFunctions` call). All other
+   functions use `authQuery/authMutation/authAction`, `roleQuery/...`,
+   `adminQuery/...` (public) or `systemMutation/systemAction` (internal).
+   This is what guarantees auth, triggers, and bounded reads.
+3. **Every public query returns DTOs** via `<table>.toPublicDto(row)` —
+   runtime redaction, not just types.
+4. **Every read is bounded**: `ctx.include(ctx.db.query('t')).matching(...)
+   .execute(limit)` with `1 ≤ limit ≤ 100`. `.resolve()` falls back to a full
+   table scan — avoid it.
+5. **State changes are commands**: an operations registry with mandatory
+   `classification` and `audit()` per operation, executed via
+   `commands.exec({ operation, handler })`. Audit writes happen in the same
+   transaction. Optional per-operation `permission` (checked via the
+   Foundation's injected `checkPermission`) and `guard(ctx, command)`
+   preconditions run BEFORE the handler, plus a registry-wide default guard
+   (`new Command(operations, { guard })`). Order: permission → default guard
+   → operation guard → handler → audit.
+6. **Never write timestamps by hand.** `createdAt`/`updatedAt` are maintained
+   by the `timestamps` trigger; `archivedAt` is the app-controlled soft-delete
+   marker.
+7. **Vocabularies are named readonly tuples in `constants.ts`** —
+   `z.enum([...])` with an inline literal is banned in kit-style codebases.
+8. **Components are consumed only through their client facades**
+   (`Foundation`, `Approvals`) — no deep imports, no touching component
+   tables, no reaching private children (`components.approvals.workflow`).
+9. **Operation names are `domain.verb` lowercase-dotted; error codes are
+   UPPER_SNAKE** — otherwise observability silently drops the events.
+10. **Row-level security is configured, not hand-rolled**: the optional
+   `security` config on `createAuthFunctions` takes role-level `rules`
+   (works standalone) and/or `tenancy` (a table registry; adds
+   `ctx.tenant`, deny-default isolation, and pairs with `tenantTable` +
+   `tenantOwnership`). Multi-tenant apps stamp inserts with
+   `tenant: ctx.tenant` and re-verify client ids with
+   `requireTenantReference`. See `tenancy.md`.
+
+## Exports map
+
+| Import | Provides |
+|---|---|
+| `cvx-kit` | everything below re-exported (except components' defaults) |
+| `cvx-kit/zod-table` | `zodTable`, `tenantTable`, `createModule`, `zodVariantTable`, `jsonSafeZid`, `TIMESTAMP_FIELDS` |
+| `cvx-kit/auth` | `createAuthFunctions` (incl. optional `security` RLS config), `createInclude`, `defaultRoleMap` |
+| `cvx-kit/tenancy` | `createTenantRules`, `composeRules`, `requireTenantReference`, `assertTenantOwned`, `TENANT_FIELD` |
+| `cvx-kit/triggers` | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `tenantOwnership`, `Triggers` |
+| `cvx-kit/errors` | `KitError`, `defaultErrors`, `ErrorFactory` |
+| `cvx-kit/components/foundation` | `Foundation`, `executeResultBoundary`, `projectResult`, `Observability`; default export = component config for `app.use` |
+| `cvx-kit/components/approvals` | `Approvals` client; default export = component config for `app.use` |
+| `cvx-kit/test` | `registerFoundation(t)`, `registerApprovals(t)` for convex-test |
+
+## Minimal app wiring (the five root files)
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from 'convex/server'
+import foundation from 'cvx-kit/components/foundation'
+import approvals from 'cvx-kit/components/approvals'
+const app = defineApp()
+app.use(foundation)
+app.use(approvals)
+export default app
+
+// convex/triggers.ts
+import { createTriggers, timestamps, appendOnly } from 'cvx-kit/triggers'
+export const triggers = createTriggers<DataModel>()
+timestamps(triggers, 'documents')
+appendOnly(triggers, 'history')
+
+// convex/functions.ts
+export const { authQuery, authMutation, authAction, adminQuery, adminMutation,
+  adminAction, roleQuery, roleMutation, roleAction, systemMutation,
+  systemAction, include } = createAuthFunctions<DataModel>({
+  query, mutation, action, internalMutation, internalAction,   // from ./_generated/server
+  getAuthUser: (ctx) => authKit.getAuthUser(ctx),
+  mapRole: defaultRoleMap,          // 'member'→'writer'; reader|writer|admin pass
+  adminRoles: ['admin'],
+  triggers,
+  verifyMembership: async ({ userId, organizationId }) => { /* live check; actions only */ },
+})
+
+// convex/foundation.ts
+export const { Command, Query, observability } = new Foundation(
+  components.foundation,
+  { observability: {
+      enabled: () => process.env.OBS === 'true',
+      classifyError,                                  // → { outcome: 'denied'|'failed', errorCode }
+      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
+  } },
+)
+
+// convex/approvals.ts
+export const approvals = new Approvals(components.approvals)
+```
+
+## Entity pattern
+
+```ts
+// domain/documents/schema.ts
+export const documents = zodTable('documents', (id) => ({
+  title: z.string(), ownerId: id('users'), secretNote: z.string(),
+}), {
+  commandFields: ['title'],            // what a command may say
+  publicFields: ['title', 'ownerId'],  // the DTO allowlist
+})
+
+// convex/schema.ts (via domain/table.ts)
+defineSchema({ documents: documents.table.index('by_owner', ['ownerId']) })
+
+// domain/documents/commands.ts
+const operations = {
+  'documents.rename': Command.operation({
+    command: documents.commandInput.extend({ id: zid('documents'), actorId: z.string() }),
+    result: z.object({ ok: z.literal(true) }).strict(),
+    classification: 'business',
+    audit: ({ command }) => ({ operation: 'documents.rename', actorId: command.actorId,
+      aggregate: { type: 'document', id: command.id } }),
+  }),
+} as const
+const commands = new Command<MutationCtx, typeof operations>(operations)
+export const executeRename = commands.exec({ operation: 'documents.rename',
+  handler: async (ctx, cmd) => { await ctx.db.patch(cmd.id, { title: cmd.title }); return { ok: true } } })
+
+// api/documents.ts — thin public adapter
+export const rename = authMutation({
+  args: documents.commandInput.extend({ id: zid('documents') }),
+  returns: z.object({ ok: z.literal(true) }).strict(),
+  handler: (ctx, args) => executeRename(ctx, { ...args, actorId: ctx.actor.userId }),
+})
+export const list = authQuery({
+  args: { limit: z.number() },
+  returns: z.array(documents.publicDto),
+  handler: (ctx, { limit }) =>
+    ctx.include(ctx.db.query('documents'))
+      .matching('by_owner', (ix) => ix.eq('ownerId', ctx.actor.userId))
+      .execute(limit, (rows) => rows.map(documents.toPublicDto)),
+})
+```
+
+## Auth ctx contents
+
+Authenticated handlers receive frozen `ctx.identity` (JWT), `ctx.user.id`,
+`ctx.org = { organizationId, role }`, `ctx.role`, `ctx.actor = { userId,
+organizationId, role }`, and `ctx.include`. Queries/mutations trust the JWT;
+**actions live-verify membership and fail closed**. Use `ctx.actor` as the
+canonical actor for audits/approvals.
+
+## Approvals in one block
+
+```ts
+export const publishApproval = approvals.define({ name: 'documentPublish', steps: [
+  approvals.decision('managerDecision', { decisions: ['approved','rejected'],
+    quorum: { kind: 'count', approvals: 1 }, makerChecker: true, expiresAfterMs: 604_800_000 }),
+  approvals.branch('applyDecision', { approvedStepKey: 'publish', rejectedStepKey: 'notify' }),
+  approvals.mutation('publish', { handler: internal.domain.documents.approval_functions.applyDecision }),
+  approvals.notify('notify', { handler: internal.domain.documents.approval_functions.notifyRejected }),
+]})
+// start(ctx, { scopeRef, resourceType, resourceRef, requester: ctx.actor, metadata? })
+// decide(ctx, { runId, decision, reason? }, ctx.actor) · status/evidence/list/cancel/restart
+```
+
+Callback handlers are `systemMutation`/`systemAction`, receive opaque strings,
+and must `normalizeId` + re-check `resourceType` + verify the resource still
+points at `runId`.
+
+## Footguns (top 8)
+
+1. `t.run(ctx => ctx.db...)` in convex-test and raw builders bypass ALL
+   triggers — seeding only.
+2. `executeResultBoundary` returns a typed failure **only when the
+   transaction has no effects yet**; after any write/schedule it rethrows for
+   rollback. Handled-vs-thrown is decided by transaction state.
+3. Observability drops events on identifier-regex mismatch — see rule 9.
+4. Mis-declared `serverFields` silently make server-owned fields
+   client-writable; masks are the security boundary.
+5. `include(...).resolve()` silently falls back to `fullTableScan()`.
+6. Audit callback ctx is untyped (`never`) — commands must run in mutations;
+   wiring a query ctx fails at runtime.
+7. Changing approval steps without bumping `compatibilityKey` lets old runs
+   be driven by an incompatible shape.
+8. When composing ctx manually, spread `wrapDB(ctx)` first — later spreads
+   carrying `db` restore the unwrapped database.

package/docs/maintainability.md

@@ -0,0 +1,124 @@
+# Maintaining a Convex application built on cvx-kit
+
+Practices that keep a cvx-kit backend maintainable over years, taken from the
+origin application. The theme throughout: make every rule either *structural*
+(the code can't be written any other way) or *executable* (a test fails when
+it's violated). Conventions that live only in documentation decay.
+
+## Schema and indexes
+
+- `convex/schema.ts` stays at ~4 lines: `defineSchema(domainTables)`.
+  Per-domain `table.ts` files attach indexes to `<zodTable>.table` and
+  `domain/table.ts` merges the maps. Shapes (zod) and topology (indexes) are
+  deliberately separate files.
+- **Index naming**: `by_<field>_and_<field>...`, camelCase field names in
+  declaration order, nested paths flattened with `_`
+  (`by_assignedToUserId_and_state_status` for `['assignedToUserId',
+  'state.status']`). A reader should reconstruct the index definition from its
+  name.
+- Every read goes through `ctx.include(...)` with an explicit limit ≤ 100.
+  If a query can't be served by an index, that's a schema problem, not a
+  reason to `fullTableScan`.
+
+## Schema evolution without downtime
+
+Convex validates the whole table against the schema on push, so evolution is
+additive:
+
+1. **New fields arrive `.optional()`** with a comment explaining the epoch:
+   `// Optional only for documents created before priority was frozen.`
+2. Deploy code that writes the new field on every new write and tolerates its
+   absence on reads.
+3. Backfill if needed (a `systemMutation` batch or `@convex-dev/migrations`),
+   then — and only then — consider tightening the schema.
+4. Never rename in place: add the new field, dual-write, backfill, drop the
+   old one release(s) later.
+
+zod-table makes step 1 cheap: change the shape once and every boundary mask
+updates together, with `tsc` pointing at every consumer that must adapt.
+
+## Function hygiene
+
+- Raw `query`/`mutation`/`action` builders appear **only** in `functions.ts`.
+  Everything public is `auth*`/`role*`/`admin*`; everything
+  internal/scheduled is `system*`. This is what makes triggers, auth, and
+  bounded reads impossible to forget.
+- Public functions in `api/` are thin: parse args (zod-table masks), call the
+  domain executor with `ctx.actor`, project through `toPublicDto`. Business
+  logic that lives in an adapter can't be reused by workflows or callbacks —
+  keep it in the domain.
+- Vocabularies (states, kinds, decisions) are single-owner readonly tuples in
+  `constants.ts`. Grep for the tuple name to find every consumer.
+
+## Audit and observability as maintenance tools
+
+- Every state change is a command with a mandatory classification and audit
+  derivation — so "what happened to this record" is a query over the audit
+  log, not archaeology. Keep operation names stable (`domain.verb`); they are
+  your telemetry and audit vocabulary.
+- Observability is payload-free by construction — you can leave it on in
+  production and grep durable one-line JSON events
+  (`event: 'command.execution'`) without PII review.
+- Set retention deliberately: audit entries carry the classification as their
+  retention category; the approvals component ships `cleanupAudit` for its own
+  trail.
+
+## Testing strategy
+
+Three test layers, all in-memory via `convex-test` on `edge-runtime`:
+
+1. **Behavioral tests** — drive functions through the real constructors
+   (`t.withIdentity(...)`), assert DTO shapes and trigger effects. Remember:
+   `t.run(ctx => ctx.db...)` bypasses triggers — use it for seeding, not for
+   asserting write behavior.
+2. **Architecture tests** — glob the source and assert the conventions
+   (no inline tables/enums, no deep imports, no sibling-domain imports, one
+   `app.use` per component, no raw builders outside `functions.ts`). Prove
+   each rule against a synthetic violating fixture first.
+3. **Boundary/copyability tests** — components contain no host imports and no
+   vendor/env references; optionally `cp -r` the component to a tmpdir and
+   run `tsc` to prove copy-portability.
+
+Consumers register the kit's components on their test instance:
+
+```ts
+import { convexTest } from 'convex-test'
+import { registerApprovals, registerFoundation } from 'cvx-kit/test'
+
+const t = convexTest(schema, modules)
+registerFoundation(t)
+registerApprovals(t)
+```
+
+(`cvx-kit/test` ships as source and needs a vitest-compatible runner —
+`import.meta.glob`.) Nested components used by approvals register their own
+test modules the same way (`@convex-dev/workflow/test`,
+`convex-audit-log/test`). Stub required env vars (declared on
+`defineApp({ env })`) in test setup.
+
+## Operational habits
+
+- **Env flags over redeploys**: observability is toggled by an env var read
+  at call time (`enabled: () => env.OBS === 'true'`).
+- **Fail closed**: membership verification errors reject; unknown roles
+  reject; unreadable transaction metrics rethrow. Preserve this bias in app
+  code.
+- **Soft deletes** (`archivedAt` + `noDelete`) for anything a human might ask
+  about later; `appendOnly` for evidence tables. Hard deletes are a data-loss
+  bug you opt into per table.
+- **Component upgrades**: components own their tables; upgrade them like
+  services — read the component's migration notes, bump, run codegen, run the
+  suite. Never write to a component's tables from the host.
+
+## Checklist for a new entity
+
+1. `domain/<entity>/schema.ts` — `zodTable` with the three masks thought
+   through (`serverFields`, `commandFields`, `publicFields`).
+2. `domain/<entity>/table.ts` — indexes, named `by_...`.
+3. Register in `domain/table.ts`; add `timestamps(triggers, '<table>')` and
+   any `appendOnly`/`noDelete` discipline.
+4. `constants.ts` — vocabularies as readonly tuples.
+5. `commands.ts` — operation registry (`domain.verb`, classification, audit)
+   + executors.
+6. `api/<entity>.ts` — thin `auth*` adapters, DTO projection.
+7. Tests: behavior + add the entity to the architecture globs.