cvx-kit 0.1.2 → 0.1.4

package/docs/zod-table.md

@@ -2,7 +2,7 @@
 
 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
+DTO, LLM tool input — is a _derived mask_ of that single declaration. There is
 no second source of truth to drift.
 
 ```ts
@@ -10,36 +10,58 @@ 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
-  },
+	'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
 
-| 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 |
-| `toPublicDto(row)` | projects **and re-parses** a row into the DTO | query handlers |
-| `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 |
+### Shared ID validation (0.1.3)
+
+Install one compatible `convex-helpers` peer (`>=0.1.123 <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        |
+| `toPublicDto(row)`                           | projects **and re-parses** a row into the DTO        | query handlers                 |
+| `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
 
@@ -50,13 +72,13 @@ 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
-  },
+	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
+	},
 })
 ```
 
@@ -69,7 +91,7 @@ Every `zodTable` bakes in three optional, **server-owned** fields:
 - `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
+`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']`).
 
@@ -83,11 +105,11 @@ vocabulary is yours; `_creationTime` remains available for index ordering.
 
 Think of the options as three independent allowlists over the same shape:
 
-- `serverFields` — *the server assigns these.* Excluded from `insertSchema`
+- `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
+- `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;
+- `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
@@ -124,10 +146,13 @@ 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() }),
-]))
+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
 ```
 
@@ -143,7 +168,7 @@ the type level:
 
 ```ts
 const assignInput = z.object({
-  documentId: jsonSafeZid('documents'), // LLM sees: string, "Convex document id for table \"documents\""
+	documentId: jsonSafeZid('documents'), // LLM sees: string, "Convex document id for table \"documents\""
 })
 ```
 
@@ -155,9 +180,9 @@ 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']),
+	documents: documents.table
+		.index('by_owner', ['ownerId'])
+		.index('by_owner_archived', ['ownerId', 'archivedAt']),
 })
 ```
 

package/package.json

@@ -1,9 +1,24 @@
 {
 	"name": "cvx-kit",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
-	"type": "module",
+	"keywords": [
+		"component",
+		"convex",
+		"workos",
+		"zod"
+	],
+	"homepage": "https://github.com/ImRLopezAG/cvx-kit#readme",
+	"bugs": {
+		"url": "https://github.com/ImRLopezAG/cvx-kit/issues"
+	},
 	"license": "MIT",
+	"author": "Angel Lopez",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ImRLopezAG/cvx-kit.git"
+	},
+	"type": "module",
 	"sideEffects": false,
 	"exports": {
 		"./package.json": "./package.json",
@@ -85,13 +100,22 @@
 		},
 		"./components/approvals/_generated/component": {
 			"types": "./dist/components/approvals/_generated/component.d.mts"
+		},
+		"./oxlint": {
+			"types": "./dist/oxlint.d.mts",
+			"import": "./dist/oxlint.mjs"
 		}
 	},
 	"scripts": {
+		"lint": "vp lint",
+		"check": "vp check",
+		"test:lint": "vp test run tools/oxlint/cvx/index.test.mjs",
 		"build": "vp pack && node scripts/convex-config-bridge.mjs && publint",
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run --exclude test/package-contents.test.mjs",
 		"test:package": "bun run build && vp test run test/package-contents.test.mjs",
+		"test:package:ids": "bun run build && node scripts/test-packed-ids.mjs",
+		"test:package:oxlint": "bun run build && node scripts/test-packed-oxlint.mjs",
 		"test:package:smoke:bun": "bun scripts/smoke-packed-components.mjs bun",
 		"test:package:smoke:npm": "node scripts/smoke-packed-components.mjs npm",
 		"docs:sync": "rm -f docs/*.md && cp src/docs/*.md docs/",
@@ -101,36 +125,25 @@
 		"release:minor": "npm version minor && git push --follow-tags"
 	},
 	"dependencies": {
-		"@convex-dev/workflow": "0.4.4",
-		"convex-audit-log": "^0.2.0",
-		"convex-helpers": "0.1.122"
-	},
-	"peerDependencies": {
-		"convex": "^1.43.0",
-		"zod": "^4.0.0"
+		"@convex-dev/workflow": "0.4.6",
+		"@oxlint/plugins": "1.79.0",
+		"convex-audit-log": "^0.2.0"
 	},
 	"devDependencies": {
 		"@edge-runtime/vm": "^5.0.0",
-		"convex": "1.43.0",
-		"convex-test": "^0.0.55",
-		"publint": "^0.3.23",
+		"@types/node": "^26.6.1",
+		"convex": "1.45.0",
+		"convex-helpers": "0.1.124",
+		"convex-test": "^0.0.56",
+		"oxlint": "1.79.0",
+		"publint": "^0.3.24",
 		"typescript": "7.0.2",
-		"vite-plus": "0.2.8",
-		"zod": "4.4.3"
+		"vite-plus": "0.3.0",
+		"zod": "4.5.4"
 	},
-	"keywords": [
-		"convex",
-		"component",
-		"workos",
-		"zod"
-	],
-	"author": "Angel Lopez",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/ImRLopezAG/cvx-kit.git"
-	},
-	"homepage": "https://github.com/ImRLopezAG/cvx-kit#readme",
-	"bugs": {
-		"url": "https://github.com/ImRLopezAG/cvx-kit/issues"
+	"peerDependencies": {
+		"convex": "^1.45.0",
+		"convex-helpers": ">=0.1.123 <0.2.0",
+		"zod": "^4.5.4"
 	}
 }

package/scripts/convex-config-bridge.mjs

@@ -2,13 +2,7 @@
 // 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 { readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -16,8 +10,10 @@ 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?/, '')
+	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.
@@ -36,17 +32,10 @@ for (const component of ['foundation', 'approvals']) {
 		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',
-	)
+	const dataModelDeclaration = join(directory, '_generated', 'dataModel.d.mts')
 	writeFileSync(
 		dataModelDeclaration,
-		readFileSync(dataModelDeclaration, 'utf8').replace(
-			'../schema.mjs',
-			'../schema.js',
-		),
+		readFileSync(dataModelDeclaration, 'utf8').replace('../schema.mjs', '../schema.js'),
 	)
 	rmSync(join(directory, 'schema.mjs'))
 	rmSync(join(directory, 'schema.mjs.map'))

package/scripts/extract-changelog.mjs

@@ -11,7 +11,7 @@ if (!version) {
 }
 const changelog = readFileSync(new URL('../CHANGELOG.md', import.meta.url), 'utf8')
 const pattern = new RegExp(
-	String.raw`^## \[${version.replace(/\./g, String.raw`\.`)}\][^\n]*\n([\s\S]*?)(?=^## \[|\Z)`,
+	String.raw`^## \[${version.replace(/\./g, String.raw`\.`)}\][^\n]*\n([\s\S]*?)(?=^## \[|(?![\s\S]))`,
 	'm',
 )
 const match = changelog.match(pattern)

package/scripts/smoke-packed-components.mjs

@@ -1,12 +1,5 @@
 import { execFileSync } from 'node:child_process'
-import {
-	copyFileSync,
-	mkdirSync,
-	mkdtempSync,
-	readFileSync,
-	rmSync,
-	writeFileSync,
-} from 'node:fs'
+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -18,9 +11,8 @@ if (installer !== 'bun' && installer !== 'npm') {
 const root = join(import.meta.dirname, '..')
 const temporaryRoot = mkdtempSync(join(tmpdir(), 'cvx-kit-smoke-'))
 const fixture = join(temporaryRoot, 'fixture')
-const packageVersion = JSON.parse(
-	readFileSync(join(root, 'package.json'), 'utf8'),
-).version
+const packageManifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const packageVersion = packageManifest.version
 const tarball = join(temporaryRoot, `cvx-kit-${packageVersion}.tgz`)
 
 function run(command, args, cwd = fixture) {
@@ -41,10 +33,7 @@ function runStreaming(command, args, cwd = fixture) {
 }
 
 function runConvex(...args) {
-	return run('node', [
-		join(fixture, 'node_modules', 'convex', 'bin', 'main.js'),
-		...args,
-	])
+	return run('node', [join(fixture, 'node_modules', 'convex', 'bin', 'main.js'), ...args])
 }
 
 function write(relativePath, contents) {
@@ -58,11 +47,7 @@ function step(label, callback) {
 }
 
 try {
-	run(
-		'bun',
-		['pm', 'pack', '--destination', temporaryRoot, '--ignore-scripts'],
-		root,
-	)
+	run('bun', ['pm', 'pack', '--destination', temporaryRoot, '--ignore-scripts'], root)
 	mkdirSync(join(fixture, 'convex'), { recursive: true })
 	write(
 		'package.json',
@@ -72,11 +57,12 @@ try {
 				type: 'module',
 				dependencies: {
 					'cvx-kit': `file:${tarball}`,
-					convex: '1.43.0',
-					zod: '4.4.3',
+					convex: packageManifest.devDependencies.convex,
+					zod: packageManifest.devDependencies.zod,
+					'convex-helpers': packageManifest.devDependencies['convex-helpers'],
 				},
 				devDependencies: {
-					'vite-plus': '0.2.8',
+					'vite-plus': packageManifest.devDependencies['vite-plus'],
 				},
 			},
 			null,
@@ -250,13 +236,8 @@ export const status = query({
 		copyFileSync(join(root, 'bun.lock'), join(fixture, 'bun.lock'))
 	}
 	if (installer === 'bun')
-		step('install with bun', () =>
-			runStreaming('bun', ['install', '--ignore-scripts']),
-		)
-	else
-		step('install with npm', () =>
-			runStreaming('npm', ['install', '--ignore-scripts']),
-		)
+		step('install with bun', () => runStreaming('bun', ['install', '--ignore-scripts']))
+	else step('install with npm', () => runStreaming('npm', ['install', '--ignore-scripts']))
 	if (installer === 'bun')
 		step('test helper with bun', () =>
 			runStreaming('bunx', ['vp', 'test', 'run', 'packed-test-helper.test.ts']),
@@ -266,30 +247,18 @@ export const status = query({
 			runStreaming('npx', ['vp', 'test', 'run', 'packed-test-helper.test.ts']),
 		)
 
-	step('deploy Convex fixture', () =>
-		runConvex('dev', '--once', '--typecheck=disable'),
-	)
+	step('deploy Convex fixture', () => runConvex('dev', '--once', '--typecheck=disable'))
 	const health = JSON.parse(runConvex('run', 'smoke:health'))
 	if (health.status !== 'ready' || health.schemaVersion !== 1) {
-		throw new Error(
-			`Unexpected approvals health response: ${JSON.stringify(health)}`,
-		)
+		throw new Error(`Unexpected approvals health response: ${JSON.stringify(health)}`)
 	}
-	const foundationHealth = JSON.parse(
-		runConvex('run', 'smoke:foundationHealth'),
-	)
+	const foundationHealth = JSON.parse(runConvex('run', 'smoke:foundationHealth'))
 	if (foundationHealth !== 'ready') {
-		throw new Error(
-			`Unexpected foundation health response: ${JSON.stringify(foundationHealth)}`,
-		)
+		throw new Error(`Unexpected foundation health response: ${JSON.stringify(foundationHealth)}`)
 	}
 	const { runId } = JSON.parse(runConvex('run', 'smoke:start'))
 	const { runId: secondRunId } = JSON.parse(
-		runConvex(
-			'run',
-			'smoke:start',
-			JSON.stringify({ resourceRef: 'packed-component-2' }),
-		),
+		runConvex('run', 'smoke:start', JSON.stringify({ resourceRef: 'packed-component-2' })),
 	)
 	const firstPage = JSON.parse(
 		runConvex(
@@ -322,46 +291,37 @@ export const status = query({
 		secondPage.page[0]._id !== runId ||
 		secondPage.page[0]._id === firstPage.page[0]._id
 	) {
-		throw new Error(
-			`Unexpected continuation approval page: ${JSON.stringify(secondPage)}`,
-		)
+		throw new Error(`Unexpected continuation approval page: ${JSON.stringify(secondPage)}`)
 	}
 
-	let decision
-	let lastError
-	for (let attempt = 0; attempt < 10; attempt += 1) {
-		try {
-			decision = JSON.parse(
-				runConvex('run', 'smoke:decide', JSON.stringify({ runId })),
-			)
-			break
-		} catch (error) {
-			lastError = error
-			const currentStatus = JSON.parse(
-				runConvex('run', 'smoke:status', JSON.stringify({ runId })),
-			)
-			if (currentStatus.state === 'approved') {
-				decision = currentStatus
-				break
-			}
-			await new Promise((resolve) => setTimeout(resolve, 500))
+	// start schedules the workflow; a successful start is not decision readiness.
+	let readyStatus
+	const readyDeadline = Date.now() + 60_000
+	while (Date.now() < readyDeadline) {
+		readyStatus = JSON.parse(runConvex('run', 'smoke:status', JSON.stringify({ runId })))
+		if (
+			readyStatus?.run.state !== 'pending' ||
+			['failed', 'canceled', 'completed'].includes(readyStatus?.execution?.type)
+		) {
+			throw new Error(`Approval ended before decision readiness: ${JSON.stringify(readyStatus)}`)
 		}
+		if (readyStatus.run.currentStepKey === 'releaseDecision') break
+		await new Promise((resolve) => setTimeout(resolve, 500))
+	}
+	if (readyStatus?.run.currentStepKey !== 'releaseDecision') {
+		throw new Error(`Approval did not become decision-ready: ${JSON.stringify(readyStatus)}`)
 	}
-	if (!decision) throw lastError
+	const decision = JSON.parse(runConvex('run', 'smoke:decide', JSON.stringify({ runId })))
 	if (decision.state !== 'approved') {
 		throw new Error(`Unexpected decision response: ${JSON.stringify(decision)}`)
 	}
-	const history = JSON.parse(
-		runConvex('run', 'smoke:history', JSON.stringify({ runId })),
-	)
+	const history = JSON.parse(runConvex('run', 'smoke:history', JSON.stringify({ runId })))
 	if (history.length !== 1 || history[0].decision !== 'approved') {
 		throw new Error(`Unexpected approval history: ${JSON.stringify(history)}`)
 	}
 	let status
 	for (let attempt = 0; attempt < 20; attempt += 1) {
-		status = JSON.parse(
-			runConvex('run', 'smoke:status', JSON.stringify({ runId })),
-		)
+		status = JSON.parse(runConvex('run', 'smoke:status', JSON.stringify({ runId })))
 		if (status.execution?.type === 'completed') break
 		await new Promise((resolve) => setTimeout(resolve, 500))
 	}