cvx-kit 0.1.15 → 0.1.17

package/scripts/convex-smoke-env.mjs

@@ -1,33 +0,0 @@
-import { existsSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-/** A smoke fixture must never inherit a cloud or self-hosted deployment selection. */
-export function localConvexEnvironment(source = process.env) {
-	const env = Object.fromEntries(
-		Object.entries(source).filter(
-			([key]) =>
-				!key.startsWith('CONVEX_') && key !== 'NEXT_PUBLIC_CONVEX_URL' && key !== 'VITE_CONVEX_URL',
-		),
-	)
-	return { ...env, CONVEX_AGENT_MODE: 'anonymous' }
-}
-
-/** Convex 1.45 can fall back to a legacy home deployment with the same agent name. */
-export function assertIsolatedConvexFixture(
-	fixture,
-	legacyState = join(homedir(), '.convex', 'anonymous-convex-backend-state', 'anonymous-agent'),
-) {
-	const localConfig = join(fixture, '.convex', 'local', 'default', 'config.json')
-	if (!existsSync(localConfig) && existsSync(legacyState)) {
-		throw new Error(
-			'Local smoke cannot reuse legacy anonymous-agent state; an isolated fixture is required',
-		)
-	}
-}
-
-export function assertLocalConvexState(fixture) {
-	if (!existsSync(join(fixture, '.convex', 'local', 'default', 'config.json'))) {
-		throw new Error('Local smoke did not create project-local deployment state')
-	}
-}

package/scripts/extract-changelog.mjs

@@ -1,29 +0,0 @@
-// Extracts one version's section from CHANGELOG.md (Keep a Changelog form).
-// Usage: node scripts/extract-changelog.mjs 0.1.0 [outfile]
-// Used by the release workflow for GitHub Release notes, and runnable
-// locally BEFORE tagging to verify extraction (see the release plan).
-import { readFileSync, writeFileSync } from 'node:fs'
-
-const version = process.argv[2]
-if (!version) {
-	console.error('usage: extract-changelog.mjs <version> [outfile]')
-	process.exit(1)
-}
-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]*?)(?=^## \[|(?![\s\S]))`,
-	'm',
-)
-const match = changelog.match(pattern)
-if (!match) {
-	console.error(`CHANGELOG.md has no section for version ${version}`)
-	process.exit(1)
-}
-const notes = match[1].trim()
-if (!notes) {
-	console.error(`CHANGELOG.md section for ${version} is empty`)
-	process.exit(1)
-}
-const outfile = process.argv[3]
-if (outfile) writeFileSync(outfile, `${notes}\n`)
-else process.stdout.write(`${notes}\n`)

package/scripts/owned-process.mjs

@@ -1,140 +0,0 @@
-import { spawn } from 'node:child_process'
-import { setTimeout as delay } from 'node:timers/promises'
-
-export function processGroupAlive(pid) {
-	try {
-		process.kill(-pid, 0)
-		return true
-	} catch (error) {
-		if (error.code === 'ESRCH') return false
-		throw error
-	}
-}
-const owned = new Set()
-export async function cleanupOwnedProcess(pid, graceMs = 1000) {
-	if (!owned.has(pid)) throw new Error('Process group is not owned by this runner')
-	const signals = [],
-		errors = []
-	for (const signal of ['SIGINT', 'SIGTERM', 'SIGKILL']) {
-		if (!processGroupAlive(pid)) break
-		try {
-			process.kill(-pid, signal)
-			signals.push(signal)
-		} catch (error) {
-			if (error.code !== 'ESRCH') errors.push({ signal, code: error.code })
-		}
-		const deadline = performance.now() + graceMs
-		while (processGroupAlive(pid) && performance.now() < deadline) await delay(20)
-	}
-	return { pid, groupId: pid, signals, errors, alive: processGroupAlive(pid) }
-}
-
-export async function runOwnedProcess({
-	command,
-	args,
-	cwd,
-	env,
-	timeoutMs = 180000,
-	graceMs = 1000,
-	onSpawn = () => {},
-}) {
-	const started = performance.now()
-	const child = spawn(command, args, { cwd, env, detached: true, stdio: ['pipe', 'pipe', 'pipe'] })
-	let stdout = '',
-		stderr = '',
-		timedOut = false,
-		spawnError,
-		timeoutCleanup
-	child.stdout.on('data', (bytes) => {
-		stdout += bytes
-	})
-	child.stderr.on('data', (bytes) => {
-		stderr += bytes
-	})
-	const closed = new Promise((resolve) => {
-		child.once('error', (error) => {
-			spawnError = { code: error.code, message: error.message }
-			resolve({ code: null, signal: null })
-		})
-		child.once('close', (code, signal) => resolve({ code, signal }))
-	})
-	if (child.pid) {
-		owned.add(child.pid)
-		onSpawn(child.pid)
-	}
-	child.stdin.end()
-	let finishTimeout
-	const timeoutFinished = new Promise((resolve) => {
-		finishTimeout = resolve
-	})
-	const timer = setTimeout(() => {
-		timedOut = true
-		timeoutCleanup = child.pid
-			? cleanupOwnedProcess(child.pid, graceMs).catch((error) => ({
-					pid: child.pid,
-					alive: true,
-					error: { code: error.code, message: error.message },
-				}))
-			: Promise.resolve(null)
-		timeoutCleanup.then(() => finishTimeout({ code: child.exitCode, signal: child.signalCode }))
-	}, timeoutMs)
-	let exit, cleanup
-	try {
-		exit = await Promise.race([closed, timeoutFinished])
-		if (timeoutCleanup) await timeoutCleanup
-	} finally {
-		clearTimeout(timer)
-		if (child.pid) {
-			try {
-				cleanup = await cleanupOwnedProcess(child.pid, graceMs)
-			} catch (error) {
-				cleanup = {
-					pid: child.pid,
-					alive: true,
-					error: { code: error.code, message: error.message },
-				}
-			}
-		}
-	}
-	if (timedOut) {
-		child.stdout.destroy()
-		child.stderr.destroy()
-		child.unref()
-	}
-	return {
-		...exit,
-		spawnError,
-		stdout,
-		stderr,
-		timedOut,
-		pid: child.pid,
-		milliseconds: performance.now() - started,
-		timeoutCleanup: await timeoutCleanup,
-		cleanup,
-	}
-}
-
-export async function collectOwnedCleanup({ pids, ports, checkPort, failure, graceMs = 1000 }) {
-	const groups = []
-	for (const pid of pids) {
-		try {
-			groups.push(await cleanupOwnedProcess(pid, graceMs))
-		} catch (error) {
-			groups.push({ pid, alive: true, error: { code: error.code, message: error.message } })
-		}
-	}
-	const portResults = []
-	for (const port of ports) {
-		try {
-			portResults.push({ port, closed: (await checkPort(port)) === port })
-		} catch (error) {
-			portResults.push({ port, closed: false, error: { code: error.code, message: error.message } })
-		}
-	}
-	return {
-		pids: groups.map(({ pid, alive }) => ({ pid, alive })),
-		failure: failure ? { name: failure.name, message: failure.message } : null,
-		groups,
-		ports: portResults,
-	}
-}

package/scripts/owned-process.test.mjs

@@ -1,107 +0,0 @@
-// @vitest-environment node
-import assert from 'node:assert/strict'
-import { test } from 'vite-plus/test'
-import { createServer } from 'node:net'
-import { mkdtempSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import {
-	runOwnedProcess,
-	cleanupOwnedProcess,
-	processGroupAlive,
-	collectOwnedCleanup,
-} from './owned-process.mjs'
-
-const proof = mkdtempSync('/tmp/cvx-owned-process-')
-console.log('Owned cleanup evidence: ' + proof)
-
-const descendant = `process.on('SIGINT',()=>{}); process.on('SIGTERM',()=>{}); console.log('ready'); setInterval(()=>{},1000)`
-const parent = `
- const {spawn}=require('node:child_process');
- const child=spawn(process.execPath,['-e',${JSON.stringify(descendant)}],{stdio:['ignore','pipe','ignore']});
- process.on('SIGINT',()=>{}); process.on('SIGTERM',()=>{});
- child.stdout.once('data',()=>{console.log('descendant:'+child.pid); MODE});
- setInterval(()=>{},1000);
-`
-
-test('timeout terminates the entire owned group after ignored graceful signals', async () => {
-	let pid
-	try {
-		const result = await runOwnedProcess({
-			command: process.execPath,
-			args: ['-e', parent.replace('MODE', '')],
-			timeoutMs: 1500,
-			graceMs: 150,
-			onSpawn: (value) => {
-				pid = value
-			},
-		})
-		writeFileSync(join(proof, 'timeout.json'), JSON.stringify(result, null, 2))
-		assert.match(result.stdout, /descendant:\d+/)
-		assert.equal(result.timedOut, true)
-		assert.ok(result.timeoutCleanup.signals.includes('SIGKILL'))
-		assert.equal(result.cleanup.alive, false)
-		assert.equal(processGroupAlive(pid), false)
-	} finally {
-		if (pid) await cleanupOwnedProcess(pid, 150)
-	}
-})
-
-test('failed leader preserves failure output and finally cleans its surviving descendant', async () => {
-	let pid
-	try {
-		const result = await runOwnedProcess({
-			command: process.execPath,
-			args: ['-e', parent.replace('MODE', "console.error('original failure'); process.exit(7)")],
-			timeoutMs: 1500,
-			graceMs: 150,
-			onSpawn: (value) => {
-				pid = value
-			},
-		})
-		writeFileSync(join(proof, 'failed-leader.json'), JSON.stringify(result, null, 2))
-		assert.equal(result.code, 7)
-		assert.equal(result.timedOut, false)
-		assert.match(result.stderr, /original failure/)
-		assert.equal(result.cleanup.alive, false)
-		assert.equal(processGroupAlive(pid), false)
-	} finally {
-		if (pid) await cleanupOwnedProcess(pid, 150)
-	}
-})
-
-test('cleanup rejects a group that was not created by the runner', async () => {
-	await assert.rejects(cleanupOwnedProcess(process.pid, 20), /not owned/)
-})
-
-test('port-check failure is recorded without replacing original proof failure', async () => {
-	const server = createServer()
-	await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
-	const port = server.address().port
-	try {
-		const result = await runOwnedProcess({
-			command: process.execPath,
-			args: ['-e', 'process.exit(7)'],
-			timeoutMs: 1000,
-		})
-		const failure = new Error('original proof failure: exit ' + result.code)
-		const evidence = await collectOwnedCleanup({
-			pids: [result.pid],
-			ports: [port],
-			failure,
-			checkPort: (requested) =>
-				new Promise((resolve, reject) => {
-					const probe = createServer()
-					probe.once('error', reject)
-					probe.listen(requested, '127.0.0.1', () => probe.close(() => resolve(requested)))
-				}),
-		})
-		writeFileSync(join(proof, 'port-failure.json'), JSON.stringify(evidence, null, 2))
-		assert.equal(evidence.failure.message, 'original proof failure: exit 7')
-		assert.equal(evidence.ports[0].closed, false)
-		assert.equal(evidence.ports[0].error.code, 'EADDRINUSE')
-		assert.equal(evidence.groups[0].alive, false)
-		assert.equal(server.listening, true, 'unrelated listener must never be killed')
-	} finally {
-		await new Promise((resolve) => server.close(resolve))
-	}
-})

package/scripts/smoke-packed-components.mjs

@@ -1,341 +0,0 @@
-import { execFileSync } from 'node:child_process'
-import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import {
-	assertIsolatedConvexFixture,
-	assertLocalConvexState,
-	localConvexEnvironment,
-} from './convex-smoke-env.mjs'
-
-const installer = process.argv[2] ?? 'bun'
-if (installer !== 'bun' && installer !== 'npm') {
-	throw new Error('Usage: smoke-packed-components.mjs [bun|npm]')
-}
-
-const root = join(import.meta.dirname, '..')
-const temporaryRoot = mkdtempSync(join(tmpdir(), 'cvx-kit-smoke-'))
-const fixture = join(temporaryRoot, 'fixture')
-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) {
-	return execFileSync(command, args, {
-		cwd,
-		encoding: 'utf8',
-		stdio: ['ignore', 'pipe', 'pipe'],
-		env: localConvexEnvironment(),
-	})
-}
-
-function runStreaming(command, args, cwd = fixture) {
-	execFileSync(command, args, {
-		cwd,
-		stdio: 'inherit',
-		env: localConvexEnvironment(),
-	})
-}
-
-function runConvex(...args) {
-	return run('node', [join(fixture, 'node_modules', 'convex', 'bin', 'main.js'), ...args])
-}
-
-function write(relativePath, contents) {
-	const path = join(fixture, relativePath)
-	writeFileSync(path, contents)
-}
-
-function step(label, callback) {
-	console.log(`smoke step: ${label}`)
-	return callback()
-}
-
-try {
-	run('bun', ['pm', 'pack', '--destination', temporaryRoot, '--ignore-scripts'], root)
-	mkdirSync(join(fixture, 'convex'), { recursive: true })
-	write(
-		'package.json',
-		JSON.stringify(
-			{
-				private: true,
-				type: 'module',
-				dependencies: {
-					'cvx-kit': `file:${tarball}`,
-					convex: packageManifest.devDependencies.convex,
-					zod: packageManifest.devDependencies.zod,
-					'convex-helpers': packageManifest.devDependencies['convex-helpers'],
-				},
-				devDependencies: {
-					'vite-plus': packageManifest.devDependencies['vite-plus'],
-				},
-			},
-			null,
-			2,
-		),
-	)
-	write(
-		'packed-test-helper.test.ts',
-		`import { describe, expect, it } from 'vite-plus/test'
-import { registerApprovals, registerFoundation } from 'cvx-kit/test'
-
-describe('packed cvx-kit test helpers', () => {
-  it('registers both compiled component bundles and their discoverable schemas', () => {
-    const registrations = []
-    const testRuntime = {
-      registerComponent(name, schema, modules) {
-        registrations.push({ name, schema, modules })
-      },
-    }
-
-    registerApprovals(testRuntime)
-    registerFoundation(testRuntime)
-
-    expect(registrations.map(({ name }) => name)).toEqual(['approvals', 'foundation'])
-    expect(Object.keys(registrations[0].schema.tables).sort()).toEqual([
-      'approvalDecisions',
-      'approvalRuns',
-    ])
-    expect(Object.keys(registrations[0].modules)).toContain(
-      '../dist/components/approvals/health.mjs',
-    )
-  })
-})
-`,
-	)
-	write(
-		'convex/convex.config.ts',
-		`import { defineApp } from 'convex/server'
-import approvals from 'cvx-kit/components/approvals/convex.config'
-import foundation from 'cvx-kit/components/foundation/convex.config'
-
-const app = defineApp()
-app.use(approvals)
-app.use(foundation)
-export default app
-`,
-	)
-	write(
-		'convex/smoke.ts',
-		`import { approvalCallbackArgs } from 'cvx-kit/components/approvals'
-import { createFunctionHandle, paginationOptsValidator } from 'convex/server'
-import { v } from 'convex/values'
-import { components, internal } from './_generated/api'
-import { internalMutation, mutation, query } from './_generated/server'
-
-export const applyDecision = internalMutation({
-  args: approvalCallbackArgs,
-  returns: v.null(),
-  handler: (_ctx, input) => {
-    if (input.decision?.evidence[0]?.stepKey !== 'releaseDecision') {
-      throw new Error('Missing callback decision step key')
-    }
-    return null
-  },
-})
-
-export const rejectDecision = internalMutation({
-  args: approvalCallbackArgs,
-  returns: v.null(),
-  handler: () => null,
-})
-
-export const health = query({
-  args: {},
-  returns: v.any(),
-  handler: (ctx) => ctx.runQuery(components.approvals.health.check, {}),
-})
-
-export const foundationHealth = query({
-  args: {},
-  returns: v.literal('ready'),
-  handler: (ctx) => ctx.runQuery(components.foundation.functions.status, {}),
-})
-
-export const start = mutation({
-  args: { resourceRef: v.optional(v.string()) },
-  returns: v.object({ runId: v.string() }),
-  handler: async (ctx, args) => {
-    const approvedHandle = await createFunctionHandle(internal.smoke.applyDecision)
-    const rejectedHandle = await createFunctionHandle(internal.smoke.rejectDecision)
-    return ctx.runMutation(components.approvals.requests.start, {
-      scopeRef: 'smoke',
-      resourceType: 'release',
-      resourceRef: args.resourceRef ?? 'packed-component',
-      requester: { actorRef: 'requester', capabilities: [] },
-      workflow: {
-        schemaVersion: 1,
-        compatibilityKey: 'packedSmoke',
-        name: 'packedSmoke',
-        steps: [
-          {
-            kind: 'decision',
-            key: 'releaseDecision',
-            decisions: ['approved', 'rejected'],
-            quorum: { kind: 'count', approvals: 1 },
-            makerChecker: true,
-          },
-          {
-            kind: 'branch',
-            key: 'routeDecision',
-            approvedStepKey: 'applyDecision',
-            rejectedStepKey: 'rejectDecision',
-          },
-          {
-            kind: 'mutation',
-            key: 'applyDecision',
-            callback: { kind: 'mutation', handle: approvedHandle, retry: false },
-          },
-          {
-            kind: 'mutation',
-            key: 'rejectDecision',
-            callback: { kind: 'mutation', handle: rejectedHandle, retry: false },
-          },
-        ],
-      },
-    })
-  },
-})
-
-export const list = query({
-  args: {
-    paginationOpts: paginationOptsValidator,
-    state: v.optional(v.union(v.literal('pending'), v.literal('approved'))),
-  },
-  returns: v.any(),
-  handler: (ctx, args) => ctx.runQuery(components.approvals.requests.list, {
-    scopeRef: 'smoke',
-    ...args,
-  }),
-})
-
-export const decide = mutation({
-  args: { runId: v.string() },
-  returns: v.any(),
-  handler: (ctx, args) => ctx.runMutation(components.approvals.decisions.decide, {
-    runId: args.runId,
-    decision: 'approved',
-    actor: { actorRef: 'approver', capabilities: [] },
-    compatibilityKey: 'packedSmoke',
-  }),
-})
-
-export const history = query({
-  args: { runId: v.string() },
-  returns: v.any(),
-  handler: (ctx, args) => ctx.runQuery(components.approvals.decisions.list, args),
-})
-
-export const status = query({
-  args: { runId: v.string() },
-  returns: v.any(),
-  handler: (ctx, args) => ctx.runQuery(components.approvals.requests.status, {
-    ...args,
-    compatibilityKey: 'packedSmoke',
-  }),
-})
-`,
-	)
-
-	if (installer === 'bun') {
-		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']))
-	if (installer === 'bun')
-		step('test helper with bun', () =>
-			runStreaming('bunx', ['vp', 'test', 'run', 'packed-test-helper.test.ts']),
-		)
-	else
-		step('test helper with npm', () =>
-			runStreaming('npx', ['vp', 'test', 'run', 'packed-test-helper.test.ts']),
-		)
-
-	assertIsolatedConvexFixture(fixture)
-	step('deploy Convex fixture', () => runConvex('dev', '--once', '--typecheck=disable'))
-	assertLocalConvexState(fixture)
-	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)}`)
-	}
-	const foundationHealth = JSON.parse(runConvex('run', 'smoke:foundationHealth'))
-	if (foundationHealth !== 'ready') {
-		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' })),
-	)
-	const firstPage = JSON.parse(
-		runConvex(
-			'run',
-			'smoke:list',
-			JSON.stringify({
-				state: 'pending',
-				paginationOpts: { cursor: null, numItems: 1 },
-			}),
-		),
-	)
-	if (firstPage.page.length !== 1 || firstPage.page[0]._id !== secondRunId) {
-		throw new Error(`Unexpected first approval page: ${JSON.stringify(firstPage)}`)
-	}
-	const secondPage = JSON.parse(
-		runConvex(
-			'run',
-			'smoke:list',
-			JSON.stringify({
-				state: 'pending',
-				paginationOpts: {
-					cursor: firstPage.continueCursor,
-					numItems: 10,
-				},
-			}),
-		),
-	)
-	if (
-		secondPage.page.length !== 1 ||
-		secondPage.page[0]._id !== runId ||
-		secondPage.page[0]._id === firstPage.page[0]._id
-	) {
-		throw new Error(`Unexpected continuation approval page: ${JSON.stringify(secondPage)}`)
-	}
-
-	// 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)}`)
-	}
-	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 })))
-	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 })))
-		if (status.execution?.type === 'completed') break
-		await new Promise((resolve) => setTimeout(resolve, 500))
-	}
-	if (status?.execution?.type !== 'completed') {
-		throw new Error(`Approval callback did not complete: ${JSON.stringify(status)}`)
-	}
-	console.log(`packed component smoke passed with ${installer}`)
-} finally {
-	rmSync(temporaryRoot, { recursive: true, force: true })
-}