hono-webhooks 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -88,7 +88,7 @@
     "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@types/bun": "^1.4.2",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "hanzio": "^3.1.0",
+    "hanzio": "^3.3.0",
     "hono": "^4.13.10",
     "husky": "^9.1.7",
     "typescript": "^7.0.2",

package/src/cli-commands.ts

@@ -2,7 +2,13 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { CliError, type CliWriter, defineCli, defineCommand } from 'hanzio/cli'
+import {
+	CliError,
+	CliUsageError,
+	type CommandContext,
+	defineCli,
+	defineCommand
+} from 'hanzio/cli'
 import { z } from 'zod'
 import {
 	createWebhooks,
@@ -78,193 +84,201 @@ const BUN_ONLY_ERRORS = new Set([
 /**
  * Under Node, a Bun project's TypeScript (extensionless imports, for one)
  * fails to load. Rerun the same command under Bun when it is installed and
- * return its exit code.
+ * exit with its code.
  */
-function rerunUnderBun(error: unknown, stderr: CliWriter): number {
+function rerunUnderBun(error: unknown): never {
 	const code = (error as { code?: string }).code
 	if (process.versions.bun || !code || !BUN_ONLY_ERRORS.has(code)) throw error
-	stderr.write(`Node can't load the module (${code}), trying Bun\n`)
+	process.stderr.write(`Node can't load the module (${code}), trying Bun\n`)
 	const run = spawnSync('bun', process.argv.slice(1), { stdio: 'inherit' })
 	if (run.error) {
 		throw new CliError(
 			'Bun is not installed either. Run the CLI with a runtime that can load your code, e.g. bunx --bun hono-webhooks ...'
 		)
 	}
-	return run.status ?? 1
+	process.exit(run.status ?? 1)
 }
 
-// One command with <module> <command> positionals: hanzio/cli reads command
-// names first, so it can't put the module before them.
-export const cli = defineCli({
-	name: 'hono-webhooks',
-	commands: defineCommand({
-		description: `<module> exports a createWebhooks() app or an array of webhooks, as default
-or named export.
+type Ctx = CommandContext<WebhooksApp>
 
-Commands:
-  list                  List the webhooks
-  schema <path>         Print the JSON Schemas of the webhooks at <path>
-  test <method> <path>  Send a request through the webhooks app
+const print = (ctx: Ctx, line: string) => ctx.stdout.write(`${line}\n`)
 
-Examples:
-  hono-webhooks ./src/webhooks.ts list
-  hono-webhooks ./src/webhooks.ts schema /orders/:id
-  hono-webhooks ./src/webhooks.ts test POST /orders/42 -b '{"total":10}'
-  hono-webhooks ./src/webhooks.ts test POST /shopify -b '{"id":1}' \\
-    -r ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET`,
-		input: z.object({
-			module: z
-				.string()
-				.optional()
-				.meta({ positional: true, description: 'Module with the webhooks' }),
-			command: z
-				.enum(['list', 'schema', 'test'])
-				.optional()
-				.meta({ positional: true, description: 'list, schema or test' }),
-			args: z.array(z.string()).meta({
-				positional: true,
-				description: 'schema: <path>, test: <method> <path>'
-			}),
-			preload: z.array(z.string()).meta({
-				alias: 'r',
-				description: 'Import a module first (e.g. to load secrets), repeatable'
-			}),
-			body: z.string().optional().meta({
-				alias: 'b',
-				description:
-					'test: request body (JSON sets content-type: application/json)'
-			}),
-			query: z.string().optional().meta({
-				alias: 'q',
-				description: 'test: query string, e.g. "a=1&b=2"'
-			}),
-			header: z.array(z.string()).meta({
-				alias: 'H',
-				description: 'test: request header "name: value", repeatable'
-			}),
-			sign: z
-				.string()
-				.optional()
-				.meta({
-					alias: 's',
-					description: `test: sign the body with ${Object.keys(schemes).join(', ')}`
-				}),
-			secretEnv: z.string().optional().meta({
-				alias: 'e',
-				description: 'test: environment variable holding the signing secret'
-			})
-		}),
-		async run(input, ctx) {
-			const print = (line: string) => ctx.stdout.write(`${line}\n`)
-			if (!input.module || !input.command) {
-				ctx.exitCode = await cli.run(['--help'], ctx)
-				return
-			}
-			let app: WebhooksApp
-			try {
-				for (const preload of input.preload) await importModule(preload)
-				app = await loadApp(input.module)
-			} catch (error) {
-				ctx.exitCode = rerunUnderBun(error, ctx.stderr)
-				return
-			}
+const list = defineCommand({
+	description: 'List the webhooks',
+	examples: ['hono-webhooks ./src/webhooks.ts list'],
+	run(_, ctx: Ctx) {
+		for (const { config } of ctx.context.webhooks) {
+			const validates = [
+				...(['params', 'query', 'headers', 'body'] as const).filter(
+					(key) => config[key]
+				),
+				...(config.verify ? ['signature'] : [])
+			].join(', ')
+			print(
+				ctx,
+				`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
+			)
+			if (validates) print(ctx, `        validates ${validates}`)
+		}
+	}
+})
 
-			if (input.command === 'list') {
-				for (const { config } of app.webhooks) {
-					const validates = [
-						...(['params', 'query', 'headers', 'body'] as const).filter(
-							(key) => config[key]
-						),
-						...(config.verify ? ['signature'] : [])
-					].join(', ')
-					print(
-						`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
-					)
-					if (validates) print(`        validates ${validates}`)
-				}
-				return
+const schema = defineCommand({
+	description: 'Print the JSON Schemas of the webhooks at <path>',
+	examples: ['hono-webhooks ./src/webhooks.ts schema /orders/:id'],
+	input: z.object({
+		path: z.string().meta({ positional: true, description: 'Webhook path' })
+	}),
+	run({ path }, ctx: Ctx) {
+		const app = ctx.context
+		const descriptions = describeWebhooks(app)
+		const indexes = app.webhooks.flatMap((w, i) =>
+			w.config.path === path ? [i] : []
+		)
+		if (!indexes.length) throw new CliError(`No webhook at ${path}`)
+		for (const i of indexes) {
+			const { config } = app.webhooks[i]!
+			print(ctx, `${config.method} ${config.path}`)
+			for (const part of [
+				'params',
+				'query',
+				'headers',
+				'body',
+				'response'
+			] as const) {
+				if (!config[part]) continue
+				const schema = descriptions[i]!.jsonSchema[part]
+				print(
+					ctx,
+					`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
+				)
 			}
+		}
+	}
+})
 
-			if (input.command === 'schema') {
-				const [path] = input.args
-				const descriptions = describeWebhooks(app)
-				const indexes = app.webhooks.flatMap((w, i) =>
-					w.config.path === path ? [i] : []
+const testCommand = defineCommand({
+	description: 'Send a request through the webhooks app',
+	examples: [
+		`hono-webhooks ./src/webhooks.ts test POST /orders/42 -b '{"total":10}'`,
+		`hono-webhooks ./src/webhooks.ts test POST /shopify -b '{"id":1}' \\
+    -r ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET`
+	],
+	input: z.object({
+		method: z
+			.string()
+			.meta({ positional: true, description: 'HTTP method, e.g. POST' }),
+		path: z.string().meta({ positional: true, description: 'Request path' }),
+		body: z.string().optional().meta({
+			alias: 'b',
+			description: 'Request body (JSON sets content-type: application/json)'
+		}),
+		query: z.string().optional().meta({
+			alias: 'q',
+			description: 'Query string, e.g. "a=1&b=2"'
+		}),
+		header: z.array(z.string()).meta({
+			alias: 'H',
+			description: 'Request header "name: value", repeatable'
+		}),
+		sign: z
+			.string()
+			.optional()
+			.meta({
+				alias: 's',
+				description: `Sign the body: ${Object.keys(schemes).join(', ')}`
+			}),
+		secretEnv: z.string().optional().meta({
+			alias: 'e',
+			description: 'Environment variable holding the signing secret'
+		})
+	}),
+	async run(input, ctx: Ctx) {
+		const { method, path } = input
+		const headers = new Headers()
+		for (const header of input.header) {
+			const at = header.indexOf(':')
+			if (at < 1) {
+				throw new CliError(
+					`Header must look like "name: value", got "${header}"`
 				)
-				if (!indexes.length) throw new CliError(`No webhook at ${path}`)
-				for (const i of indexes) {
-					const { config } = app.webhooks[i]!
-					print(`${config.method} ${config.path}`)
-					for (const part of [
-						'params',
-						'query',
-						'headers',
-						'body',
-						'response'
-					] as const) {
-						if (!config[part]) continue
-						const schema = descriptions[i]!.jsonSchema[part]
-						print(
-							`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
-						)
-					}
-				}
-				return
 			}
-
-			const [method, path] = input.args
-			if (!method || !path) throw new CliError('Usage: test <method> <path>')
-			const headers = new Headers()
-			for (const header of input.header) {
-				const at = header.indexOf(':')
-				if (at < 1) {
-					throw new CliError(
-						`Header must look like "name: value", got "${header}"`
-					)
-				}
-				headers.set(header.slice(0, at).trim(), header.slice(at + 1).trim())
+			headers.set(header.slice(0, at).trim(), header.slice(at + 1).trim())
+		}
+		if (input.body && !headers.has('content-type')) {
+			try {
+				JSON.parse(input.body)
+				headers.set('content-type', 'application/json')
+			} catch {
+				headers.set('content-type', 'text/plain')
 			}
-			if (input.body && !headers.has('content-type')) {
-				try {
-					JSON.parse(input.body)
-					headers.set('content-type', 'application/json')
-				} catch {
-					headers.set('content-type', 'text/plain')
-				}
+		}
+		if (input.sign) {
+			const scheme = schemes[input.sign]
+			if (!scheme) {
+				throw new CliError(
+					`Unknown scheme "${input.sign}", use one of: ${Object.keys(schemes).join(', ')}`
+				)
 			}
-			if (input.sign) {
-				const scheme = schemes[input.sign]
-				if (!scheme) {
-					throw new CliError(
-						`Unknown scheme "${input.sign}", use one of: ${Object.keys(schemes).join(', ')}`
-					)
-				}
-				const name = input.secretEnv
-				if (!name) throw new CliError('--sign needs --secret-env <name>')
-				const secret = ctx.env[name]
-				if (secret === undefined) throw new CliError(`${name} is not set`)
-				for (const [key, value] of Object.entries(
-					await scheme.sign(input.body ?? '', secret)
-				)) {
-					headers.set(key, value)
-				}
+			const name = input.secretEnv
+			if (!name) throw new CliError('--sign needs --secret-env <name>')
+			const secret = ctx.env[name]
+			if (secret === undefined) throw new CliError(`${name} is not set`)
+			for (const [key, value] of Object.entries(
+				await scheme.sign(input.body ?? '', secret)
+			)) {
+				headers.set(key, value)
 			}
+		}
 
-			const url = `${path.startsWith('/') ? path : `/${path}`}${input.query ? `?${input.query}` : ''}`
-			const start = performance.now()
-			const res = await app.request(url, {
-				method: method.toUpperCase(),
-				headers,
-				body: input.body
-			})
-			const text = await res.text()
-			let body = text
-			try {
-				body = JSON.stringify(JSON.parse(text), null, 2)
-			} catch {}
-			print(`${res.status} (${(performance.now() - start).toFixed(1)}ms)`)
-			if (body) print(body)
-			if (!res.ok) ctx.exitCode = 1
+		const url = `${path.startsWith('/') ? path : `/${path}`}${input.query ? `?${input.query}` : ''}`
+		const start = performance.now()
+		const res = await ctx.context.request(url, {
+			method: method.toUpperCase(),
+			headers,
+			body: input.body
+		})
+		const text = await res.text()
+		let body = text
+		try {
+			body = JSON.stringify(JSON.parse(text), null, 2)
+		} catch {}
+		print(ctx, `${res.status} (${(performance.now() - start).toFixed(1)}ms)`)
+		if (body) print(ctx, body)
+		if (!res.ok) ctx.exitCode = 1
+	}
+})
+
+export const cli = defineCli({
+	name: 'hono-webhooks',
+	description: `<module> exports a createWebhooks() app or an array of webhooks, as default
+or named export.`,
+	globals: z.object({
+		module: z
+			.string()
+			.meta({ positional: true, description: 'Module with the webhooks' }),
+		preload: z.array(z.string()).meta({
+			alias: 'r',
+			description: 'Import a module first (e.g. to load secrets), repeatable'
+		})
+	}),
+	async context({ module, preload }) {
+		try {
+			for (const specifier of preload) await importModule(specifier)
+			return await loadApp(module)
+		} catch (error) {
+			return rerunUnderBun(error)
 		}
-	})
+	},
+	commands: { list, schema, test: testCommand },
+	onError(error, io) {
+		// No module or command: print help and succeed, as `--help` does.
+		if (error instanceof CliUsageError && error.kind === 'missing-command') {
+			io.stdout.write(error.help)
+			return 0
+		}
+		// Bad arguments exit 1 like every other failure.
+		const code = io.print()
+		return code === 2 ? 1 : code
+	}
 })

package/src/cli.ts

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
 import { cli } from './cli-commands'
 
-// hanzio/cli exits 2 on bad arguments; this CLI has always exited 1.
-const code = await cli.run()
-process.exitCode = code === 2 ? 1 : code
+process.exitCode = await cli.run()