cvx-kit 0.1.14 → 0.1.16

package/docs/upgrading.md

@@ -1,287 +0,0 @@
-# Upgrading to 0.1.0 — the new way of things
-
-## Current dependency requirements
-
-Install Convex 1.46 or newer and convex-helpers 0.1.127 or newer (below 0.2.0).
-These minimums match workflow 0.4.10. Regenerate your lockfile after updating.
-Auth declarations retain native Convex context types across package versions;
-the regression fixture also checks Convex 1.45, which is below the current
-full-package dependency minimum.
-
-## Current command API — Effect declarations
-
-`Foundation.Command` and its separate `exec({ operation, handler })` API are
-deprecated. For new command code, use `createEffectFoundation` from
-`cvx-kit/effect`, declare handlers inside `command({...})`, and return
-`exec(operation, input, host)` through a shared Effect API builder.
-See [commands.md](./commands.md) for migration steps. Existing consumers remain
-compatible; older release sections below describe their historical APIs.
-
-## 0.1.6 — stricter architecture checks
-
-Enable `project-structure`, `root-wiring-only`, `application-orchestration`,
-`internal-function-ownership`, and `domain-file-responsibilities` alongside the
-existing rules. These are opt-in additions; existing enabled boundary rules now
-also resolve tsconfig aliases and reject migration dependencies.
-
-Move root implementation folders into their owning domains. Keep `application/`
-limited to multi-domain coordination. Move centralized domain tests beside their
-owners and add real tests for nested executable directories. Do not create empty
-scaffold files. Replace copied structural architecture suites with the packaged
-checks; retain tests that exercise actual application behavior and wiring.
-
-## 0.1.5 — consumer Oxlint rules
-
-The initial 0.1.4 plugin incorrectly targeted this package's `src/` layout.
-`cvx-kit/oxlint` now targets consuming applications under `convex/`, following
-`conventions.md`. The six existing rule names remain, with consumer semantics;
-nine additional rules cover builders, generated references, domain imports,
-public adapters, facade ownership, vocabularies, reads, and timestamps.
-
-Remove `entryPoints` and `packageName` options from your consumer lint config.
-Applications have no barrel entry points inside `convex/`. Every rule now
-accepts only an optional `convexDir`, relative to the linter's working directory
-(default: `convex`). Enable the new rules explicitly; loading the plugin alone
-does not enable them. See `oxlint.md` for coverage and the root README for a
-complete configuration. Repository authoring checks remain local tooling.
-
-No runtime API or storage migration is part of this correction.
-
-## 0.1.4
-
-This release introduced the optional `cvx-kit/oxlint` export. Its original
-rules targeted library authoring; see the correction above for consumer use.
-
-This patch tightens several TypeScript contracts during the anti-slop cleanup:
-
-- Query middleware preserves the handler's result type. Return `next()` or
-  throw; middleware that fabricates an unrelated result no longer typechecks.
-- `include().execute` and `.paginate` require a transform callback when
-  requesting a different output type through an explicit type argument.
-- Audit metadata values must be serializable Convex `Value` values.
-- Webhook targets must be internal mutation references accepting
-  `{ eventKey: string, payload: string, source: string }`.
-- CRUD enrichment derives from the table storage schema. Agent tools retain
-  each supplied handler's input and result types.
-
-Run your application's typecheck after upgrading and update affected callbacks.
-No storage migration is required.
-
-## 0.1.3
-
-Install `convex-helpers` as a direct peer, using one compatible instance:
-
-```sh
-bun add cvx-kit@0.1.3 convex-helpers@0.1.124
-```
-
-The peer range was `>=0.1.123 <0.2.0`. Remove overrides that force a
-separate helper copy and regenerate the installation without discarding
-unrelated dependency choices. This release is validated with Convex 1.45.0,
-Zod 4.5.4, and convex-test 0.0.56.
-
-Existing `Command.operation` and `Command.middleware` remain available.
-For callback inference, use `Command.withContext<MutationCtx>().operation`;
-see `commands.md` for typed middleware and transactional completion.
-
-Result transforms now run once, after middleware. A handler and middleware
-return the result schema's **input** type; audit, completion, and the executor
-receive its **output**. Middleware reading `await next()` sees the unparsed
-handler result. Remove workarounds that compensate for double transforms.
-When storing transformed outputs for replay, supply an output validator as
-`replayResult`; otherwise replay uses the ordinary result schema.
-Executor callers supply the command schema's input type; guards, prepare,
-middleware, and handlers receive its parsed output. For example, a string
-transformed to a number is passed as a string to the executor and observed
-as a number by its callbacks.
-
-Test registration no longer needs a registrar adapter or assertion:
-
-```ts
-import { convexTest } from 'convex-test'
-import { registerFoundation, registerApprovals } from 'cvx-kit/test'
-import schema from './schema'
-
-const t = convexTest(schema, import.meta.glob('./**/*.ts'))
-registerFoundation(t)
-registerApprovals(t)
-```
-
-Both helpers accept an optional custom component path as their second argument.
-
-## Approvals packaging repair (0.1.x patch)
-
-`cvx-kit@0.1.0` published component schemas as `schema.mjs`, which Convex does
-not discover for packaged components. Upgrade to the patch containing this
-repair, remove any `patchedDependencies` entry that copied or renamed the
-approvals schema, reinstall from a clean lockfile state, and run one normal
-deployment:
-
-```bash
-bun install
-bunx convex dev --once
-```
-
-The repaired package publishes only `schema.js` and `schema.d.ts` for each
-component. Do not retain both `.mjs` and `.js`; Convex canonicalizes them to the
-same module and rejects the deployment with `CanonicalizationConflict`.
-
-This upgrade does not change table fields or index definitions, so a second
-deployment is not required for staged index backfills. Existing deployments
-that never received the component schema will create the tables and indexes on
-the first repaired deployment. Confirm readiness through
-`components.approvals.health.check` before resuming approval traffic.
-
-The migration file for consumers on 0.0.x. Each section: the old way you were
-hand-writing, the 0.1.0 way, and what stays unchanged. Nothing existing
-breaks in this release except one boundary-mask improvement (see the last
-section).
-
-**Semver contract from 0.1.0:** breaking changes land only on minor bumps;
-patches are additive or fixes. One caveat, stated honestly: the breaking
-window formally closes at the follow-up consolidation release (package-name
-decision + full export-name API audit) — until then the six new helper
-surfaces may still be renamed in a minor. Every tag now gets a GitHub
-Release with CHANGELOG notes.
-
-## Pagination — was: `.take()` loops or hand-bridged validators
-
-Old way:
-
-```ts
-// hand-rolled: convexToZod(paginationOptsValidator) in every project,
-// or worse, .execute(100) and client-side slicing.
-```
-
-New way:
-
-```ts
-import { paginated } from 'cvx-kit/zod-table'
-
-const page = paginated(<entities>.publicDto)
-export const list = authQuery({
-  args: { paginationOpts: page.args.paginationOpts },
-  returns: page.result,
-  handler: (ctx, args) =>
-    ctx.include(ctx.db.query('<entities>'))
-      .matching('by_tenant', (ix) => ix.eq('tenant', ctx.tenant))
-      .paginate(args.paginationOpts, (rows) => rows.map(<entities>.toPublicDto)),
-})
-```
-
-Unchanged: `execute(limit)` for non-cursor reads; the maxRows bound applies
-to `numItems` too. Under RLS, pages may be SHORTER than `numItems` when
-rules reject rows mid-page — cursors remain correct, keep paging until
-`isDone`.
-
-## CRUD — was: hand-written create/update/archive per entity
-
-New way:
-
-```ts
-import { createCrudCommands } from 'cvx-kit/crud'
-
-const crud = createCrudCommands({
-  Command,                             // destructured from your Foundation
-  table: <entities>,
-  aggregateType: '<entity>',
-  actor: (ctx) => ctx.actor.userId,
-  enrich: (ctx) => ({ tenant: ctx.tenant }),  // REQUIRED for tenantTables
-})
-// crud.executeCreate / executeUpdate / executeArchive — audited commands
-```
-
-Unchanged: your api/ adapters stay thin; bespoke operations keep using
-`Command.operation` directly. Archive is soft-delete only, by doctrine.
-
-## Transition guards — was: hand-written `if` chains
-
-New way:
-
-```ts
-import { createStateMachine } from 'cvx-kit/state-machine'
-
-const machine = createStateMachine(<ENTITY>_STATES, {
-	draft: ['published', 'archived'],
-	published: ['archived'],
-})
-// in a command guard:
-guard: async (ctx, command) => machine.assert(row.state, command.to)
-```
-
-## Rate limiting — was: hand-rolled counters or none
-
-New way (host mounts `@convex-dev/rate-limiter`; the kit stays
-dependency-free — it receives the instance):
-
-```ts
-import { rateLimit } from 'cvx-kit/middleware'
-
-const commands = new Command(operations, {
-	middleware: [rateLimit({ limiter, name: '<entities>.write' })],
-})
-```
-
-Keyed by `ctx.tenant` by default. No tenant and no `key` fn →
-`RATE_LIMIT_KEY_MISSING` (configuration error, never a shared bucket).
-
-## Webhooks — was: ad-hoc verification and dedup in the action
-
-New way:
-
-```ts
-import { createWebhookBoundary, recordWebhookEvent, webhookEventsTable } from 'cvx-kit/webhooks'
-
-// schema: webhookEvents: webhookEventsTable().table.index('by_eventKey', ['eventKey'])
-const boundary = createWebhookBoundary({
-	verify: async (raw, request) => timingSafeHmacVerify(raw, request), // RAW body, constant-time, secret from env
-	eventKey: (raw) => {
-		const e = JSON.parse(raw)
-		return `${e.event}:${e.id}:${e.updatedAt}`
-	},
-})
-// http.ts routes to boundary.handle(ctx, request, internal.<module>.functions.applyEvent)
-// applyEvent (systemMutation) calls recordWebhookEvent FIRST — transactional dedup.
-```
-
-Dedup rows are host-owned: prune on a retention window longer than the
-provider's redelivery horizon (cleanup cron over `receivedAt`).
-
-## Agent tools — was: hand-written tool definitions with raw db access
-
-New way:
-
-```ts
-import { createAgentTools } from 'cvx-kit/agent-tools'
-
-const tools = createAgentTools(<entities>, {
-  create: (ctx, input) => crud.executeCreate(ctx, input),   // audited command
-  get: (ctx, { id }) => loadDto(ctx, id),                   // reads: query handlers
-  list: (ctx, { paginationOpts }) => listPage(ctx, paginationOpts),
-})
-// host: spread each record into @convex-dev/agent's createTool (or ai-sdk tool())
-```
-
-Shape-compatible, dependency-free; checked against `@convex-dev/agent@0.6.x`
-— re-verify at install.
-
-## Typed middleware context — was: loose `next({ context })`
-
-New way:
-
-```ts
-const withVendor = Command.middleware<Ctx, { vendor: Vendor }>(async ({ context, next }) =>
-	next({ context: { vendor: await load(context) } }),
-)
-// registries/operations accept typed middleware without casts
-```
-
-Unchanged: untyped middleware keeps compiling.
-
-## The one behavior change: tool masks use jsonSafeZid
-
-`<table>.tools.update` and `<table>.tools.id` now type ids with
-`jsonSafeZid` instead of `zid`, so generated JSON schemas present ids as
-plain strings (compile-time `Id<...>` preserved). If you relied on the masks
-producing `zid` runtime metadata, re-check; for LLM tool schemas this is the
-fix you wanted.

package/docs/webhooks.md

@@ -1,58 +0,0 @@
-# `cvx-kit/webhooks` — the sanctioned webhook boundary
-
-Webhooks are the one boundary that genuinely needs deduplication (Convex's
-client gives exactly-once for its own mutations; external providers redeliver).
-The helper encodes the pattern: **verify over the raw body (fail closed) →
-derive the natural key → delegate to an internal mutation whose first act is
-transactional dedup**.
-
-## Wiring
-
-```ts
-// schema — host-owned dedup table (the kit gains no tables):
-webhookEvents: webhookEventsTable().table.index('by_eventKey', ['eventKey'])
-
-// boundary — used inside the host's httpAction:
-const boundary = createWebhookBoundary({
-  // RAW body, BEFORE parsing. Constant-time comparison (crypto.subtle HMAC
-  // verify), secret from a Convex environment variable — never in code.
-  verify: async (raw, request) => verifyVendorSignature(raw, request.headers),
-  // The natural-key pattern:
-  eventKey: (raw) => {
-    const event = JSON.parse(raw)
-    return `${event.type}:${event.id}:${event.updatedAt}`
-  },
-  source: 'vendor',
-})
-
-// http.ts — routing only:
-http.route({ path: '/webhooks/vendor', method: 'POST',
-  handler: httpAction((ctx, request) =>
-    boundary.handle(ctx, request, internal.<module>.functions.applyVendorEvent)) })
-
-// the target — a systemMutation; dedup FIRST, transactionally:
-export const applyVendorEvent = systemMutation({
-  args: { eventKey: z.string(), payload: z.string(), source: z.string() },
-  handler: async (ctx, args) => {
-    const { duplicate } = await recordWebhookEvent(ctx, { key: args.eventKey, source: args.source })
-    if (duplicate) return null
-    const payload = JSON.parse(args.payload)   // parse INSIDE the trusted path
-    // ...apply, via domain executors
-    return null
-  },
-})
-```
-
-## Rules
-
-1. **Dedup lives in the mutation, never the action.** The action can race;
-   the mutation's insert-if-absent is transactional.
-2. **Verification is over raw bytes.** Re-serialized/parsed bodies break or
-   weaken HMACs; the helper hands `verify` the raw `request.text()`.
-3. **Fail closed.** `verify` returning false OR throwing both reject with
-   `WEBHOOK_SIGNATURE_INVALID`, before any delegation.
-4. **Retention is yours.** Dedup rows grow forever unless pruned — run a
-   cleanup cron over `receivedAt` with a window comfortably longer than the
-   provider's redelivery horizon (days, not hours).
-5. Providers with signed timestamps (Stripe-style): also enforce a tolerance
-   window inside `verify`.

package/docs/zod-table.md

@@ -1,278 +0,0 @@
-# `cvx-kit/zod-table` — one zod shape per entity, masked into every boundary
-
-The core idea: an entity's shape is declared **once** as a zod object, and every
-boundary that shape crosses — storage, insert, update, command input, public
-DTO, LLM tool input — is a _derived mask_ of that single declaration. There is
-no second source of truth to drift.
-
-```ts
-import { z } from 'zod'
-import { zodTable } from 'cvx-kit/zod-table'
-
-export const documents = zodTable(
-	'documents',
-	(id) => ({
-		title: z.string(),
-		ownerId: id('users'), // `id` is convex-helpers' zid — typed Id<'users'>
-		secretNote: z.string(),
-		reviewState: z.enum(['draft', 'published']),
-	}),
-	{
-		serverFields: ['reviewState'], // excluded from inserts — server assigns it
-		commandFields: ['title'], // the ONLY fields a command may carry
-		publicFields: ['title', 'ownerId'], // the DTO allowlist — everything else is redacted
-	},
-)
-```
-
-## What you get back
-
-### Shared ID validation (0.1.3)
-
-Install one compatible `convex-helpers` peer (`>=0.1.127 <0.2.0`) alongside
-cvx-kit. ID metadata lives in a helper-instance registry: copying schemas
-between separately installed helper instances can silently turn an ID into
-`v.any()`. An exact nested dependency previously caused that failure even
-when both helper versions were compatible. Fresh npm and Bun consumer tests
-now exercise storage, command, DTO, and nested ID conversion with a different
-compatible host version.
-
-Prefer the matching kit exports when deriving validators from kit schemas:
-
-```ts
-import { zid, zodToConvex, convexToZod } from 'cvx-kit/zod-table'
-```
-
-Do not force conflicting nested helper copies with overrides or reuse schema
-objects across separate bundles. The upstream converter cannot recognize an
-unregistered foreign ID and does not throw; peer installation prevents the
-supported package graph from creating that ambiguity. Verify critical ID
-validators retain `kind === 'id'` and the expected `tableName` after installation.
-
-| Property                                     | What it is                                             | Where you use it               |
-| -------------------------------------------- | ------------------------------------------------------ | ------------------------------ |
-| `table`                                      | `defineTable(...)` from the storage shape              | `convex/schema.ts`             |
-| `storage`                                    | zod object of the raw row (no `_id`/`_creationTime`)   | validating rows                |
-| `schema`                                     | `storage` + `_id` + `_creationTime`                    | full-document validation       |
-| `insertSchema`                               | storage minus timestamps minus `serverFields`          | mutation args                  |
-| `updateSchema`                               | `insertSchema.partial()`                               | patch mutation args            |
-| `commandInput`                               | strict pick of `commandFields`                         | command protocol inputs        |
-| `publicDto`                                  | strict pick of `publicFields`                          | query return validators        |
-| `dto(options?)`                              | public return schema with optional ID and extensions   | query return validators        |
-| `toPublicDto(row)`                           | projects **and re-parses** a row into the DTO          | query handlers                 |
-| `paginationOpts(selection)`                  | native pagination options, selected filters, and order | query input validators         |
-| `insert(omit?)` / `update(omit?)`            | schema with per-callsite field omission                | specialized mutations          |
-| `tools.insert` / `tools.update` / `tools.id` | ready-made LLM tool input schemas                      | agent tool definitions         |
-| `tableName`                                  | the literal table name                                 | indexes, triggers registration |
-
-## Redaction is runtime, not just types
-
-`toPublicDto` does not merely `pick` at the type level — it re-parses the
-projected object through the strict `publicDto` schema. A field that leaks into
-the projection throws instead of shipping to the client. Use it on **every**
-row a public query returns:
-
-```ts
-export const get = authQuery({
-	args: { id: zid('documents') },
-	returns: documents.publicDto,
-	handler: async (ctx, { id }) => {
-		const row = await ctx.db.get(id)
-		if (!row) throw new KitError({ code: 'NOT_FOUND' })
-		return documents.toPublicDto(row) // secretNote can never leak
-	},
-})
-```
-
-## Public DTO parameters
-
-`publicDto` is the strict Zod schema selected by `publicFields`; it takes no
-parameters. Use `dto(...)` to derive a return schema and `toPublicDto(row, ...)`
-to project a row with the same options. These methods are also available on
-`tenantTable` boundaries.
-
-```ts
-documents.toPublicDto(row) // publicFields only
-documents.toPublicDto(row, false) // same default projection
-documents.toPublicDto(row, true) // publicFields plus _id
-documents.toPublicDto(row, { _id: true }) // explicit equivalent
-
-const withoutId = documents.dto() // same boundary as publicDto
-const withId = documents.dto(true) // branded Id<'documents'>
-const explicit = documents.dto({ _id: true })
-```
-
-Including `_id` requires a row containing an ID and validates it through the
-table's ID schema. It does not expose `_creationTime`, tenant metadata, or other
-storage fields. Do not spread an ID onto a parsed DTO manually; use the matching
-`dto(true)` return validator.
-
-Computed fields need both a schema and explicitly supplied values:
-
-```ts
-const extend = { url: z.url() }
-const returnSchema = documents.dto({ _id: true, extend })
-
-const output = documents.toPublicDto(row, {
-	_id: true,
-	extend,
-	values: { url: `https://example.test/documents/${row._id}` },
-})
-returnSchema.parse(output)
-```
-
-`extend` is a map of field names to Zod validators, not an `extendFields` wrapper.
-`values` belongs only to the projector; `dto(...)` describes the result. Extension
-values are parsed as a strict object: missing required fields, unknown values,
-and invalid values fail. Values are never copied implicitly from storage.
-
-Extensions cannot replace public fields or use `_id`, `_creationTime`, `tenant`,
-`createdAt`, `updatedAt`, `archivedAt`, or `__proto__`. Their schemas must validate
-without changing values: transforms, pipes, coercion, preprocess, defaults,
-catches, and overwrites are rejected, including inside nested schemas.
-Refinements must not mutate their input. Existing public-field schemas retain
-their existing parsing behavior.
-
-## Pagination options
-
-Select filterable scalar fields independently of the public DTO mask:
-
-```ts
-const input = documents.paginationOpts({ title: true, ownerId: true })
-const args = input.parse({
-	numItems: 25,
-	cursor: null,
-	order: 'desc',
-	filters: { title: 'Proposal' },
-})
-```
-
-The helper extends Convex's native pagination options with optional `filters`
-and `order: 'asc' | 'desc'`. It returns a Zod object that can be used directly as
-query args or extended with endpoint-specific fields. `numItems` must be a
-positive integer at most 100; engine configuration may lower that ceiling.
-Unknown filter fields fail. Stored scalar fields, including explicitly selected
-server-owned fields and IDs, can be filterable even when absent from the DTO.
-Arrays, objects, and other unsupported non-scalar fields cannot be selected.
-This schema creates no authorization policy by itself.
-
-For relationship filters and paginated public output, use
-`relations.tables.documents.paginationOpts(selection)` and `.pageDto(selection)`.
-See [querying.md](./querying.md) for declarations, conditional indexes, filters,
-authorization, and child-page continuation. Existing native pagination can keep
-using `paginated(dto)`; the querying engine is independent of `include`.
-
-## Opinionated timestamps
-
-Every `zodTable` bakes in three optional, **server-owned** fields:
-
-- `createdAt` — set once on insert
-- `updatedAt` — moved on every update
-- `archivedAt` — soft-delete marker, under application control
-
-They are always excluded from `insertSchema`, `updateSchema`, and
-`commandInput` — a client or command can never write them. They are _not_ in
-`publicFields` by default; list them explicitly when a DTO needs them
-(`publicFields: ['title', 'createdAt']`).
-
-They maintain themselves only if you register the `timestamps` trigger once
-per table (see `triggers.md`). Without the trigger they stay `undefined`.
-
-Prefer `createdAt` over `_creationTime` in DTOs so the whole lifecycle
-vocabulary is yours; `_creationTime` remains available for index ordering.
-
-## Field masks — who sees what
-
-Think of the options as three independent allowlists over the same shape:
-
-- `serverFields` — _the server assigns these._ Excluded from `insertSchema`
-  and `updateSchema`. Example: `reviewState`, denormalized counters.
-- `commandFields` — _a command may say these._ The command protocol's input
-  is exactly this pick, strict. Everything else must be derived by the handler.
-- `publicFields` — _a client may see these._ The DTO is exactly this pick;
-  may include timestamp fields.
-
-All derived objects are `.strict()` — unknown keys are rejected, in both
-directions.
-
-## `tenantTable` — tenant-owned rows
-
-`tenantTable` is `zodTable` plus a server-owned `tenant` string field —
-injected exactly like timestamps: present in storage, excluded from
-`insertSchema`/`updateSchema`/`commandInput`, in `publicDto` only by explicit
-allowlist. Handlers stamp it from `ctx.tenant`; row-level security matches on
-it; the `tenantOwnership` trigger forbids reassigning it. See `tenancy.md`.
-
-```ts
-export const <entities> = tenantTable('<entities>', (id) => ({ ... }), {
-  commandFields: [...], publicFields: [...],
-})
-```
-
-## `createModule` — module table maps
-
-Merges per-module table maps into the application schema, throwing when two
-modules declare the same table — the combinator for `domain/table.ts`:
-
-```ts
-export default defineSchema(createModule(<moduleA>Tables, <moduleB>Tables))
-```
-
-## `zodVariantTable` — discriminated unions
-
-For tables whose rows are a discriminated union (events, polymorphic
-resources), `zodTable`'s object-shape model doesn't apply. `zodVariantTable`
-keeps the same "one owner per table" convention while accepting any zod type
-as storage:
-
-```ts
-const events = zodVariantTable(
-	'events',
-	z.discriminatedUnion('kind', [
-		z.object({ kind: z.literal('created'), by: zid('users') }),
-		z.object({ kind: z.literal('archived'), reason: z.string() }),
-	]),
-)
-// events.table → defineTable, events.insertSchema → the union itself
-```
-
-Note: variant tables do not get the timestamp fields or boundary masks — the
-union is the boundary.
-
-## `jsonSafeZid` — Ids in LLM tool schemas
-
-JSON-schema generators turn `zid('users')` into an opaque custom type that
-confuses LLM tool calling. `jsonSafeZid('users')` presents as a plain
-described string in the generated JSON schema while keeping `Id<'users'>` at
-the type level:
-
-```ts
-const assignInput = z.object({
-	documentId: jsonSafeZid('documents'), // LLM sees: string, "Convex document id for table \"documents\""
-})
-```
-
-## Wiring into `schema.ts`
-
-```ts
-// convex/schema.ts
-import { defineSchema } from 'convex/server'
-import { documents } from './tables/documents'
-
-export default defineSchema({
-	documents: documents.table
-		.index('by_owner', ['ownerId'])
-		.index('by_owner_archived', ['ownerId', 'archivedAt']),
-})
-```
-
-Indexes are chained on `.table` exactly like a hand-written `defineTable`.
-
-## Rules of thumb
-
-1. One `zodTable` per entity, in its own module, exported by name.
-2. Never define an inline `defineTable` or a second zod object for the same
-   entity — masks only.
-3. Every public query returns `publicDto`-shaped data via `toPublicDto`.
-4. Every command input is `commandInput` (or a documented composition of it).
-5. Timestamps are trigger-maintained; handlers never write them.

package/scripts/convex-config-bridge.mjs

@@ -1,44 +0,0 @@
-// Convex's CLI discovers a packaged component only when its definition file
-// is literally named `convex.config.js` (see DEFINITION_FILENAME_JS in the
-// convex CLI). vp pack emits .mjs, so this postbuild step materializes the
-// compiled definition as convex.config.js in each component's dist directory.
-import { readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const root = join(dirname(fileURLToPath(import.meta.url)), '..')
-
-for (const component of ['foundation', 'approvals']) {
-	const directory = join(root, 'dist', 'components', component)
-	const config = readFileSync(join(directory, 'convex.config.mjs'), 'utf8').replace(
-		/\/\/# sourceMappingURL=.*\n?/,
-		'',
-	)
-	writeFileSync(join(directory, 'convex.config.js'), config)
-
-	// Component implementations are discovered from schema.ts/schema.js only.
-	// Keeping schema.mjs beside schema.js is also invalid because Convex
-	// canonicalizes both extensions to the same module path.
-	const schema = readFileSync(join(directory, 'schema.mjs'), 'utf8').replace(
-		/\/\/# sourceMappingURL=.*\n?/,
-		'',
-	)
-	writeFileSync(join(directory, 'schema.js'), schema)
-	for (const filename of readdirSync(directory)) {
-		if (!filename.endsWith('.mjs')) continue
-		const path = join(directory, filename)
-		const source = readFileSync(path, 'utf8')
-		const bridged = source.replaceAll('./schema.mjs', './schema.js')
-		if (bridged !== source) writeFileSync(path, bridged)
-	}
-	renameSync(join(directory, 'schema.d.mts'), join(directory, 'schema.d.ts'))
-	const dataModelDeclaration = join(directory, '_generated', 'dataModel.d.mts')
-	writeFileSync(
-		dataModelDeclaration,
-		readFileSync(dataModelDeclaration, 'utf8').replace('../schema.mjs', '../schema.js'),
-	)
-	rmSync(join(directory, 'schema.mjs'))
-	rmSync(join(directory, 'schema.mjs.map'))
-	console.log(`bridged dist/components/${component}/convex.config.js`)
-	console.log(`bridged dist/components/${component}/schema.js`)
-}