support arktype (generalise json-schemable validation libraries) (#59)

Be less zod-biased, so that arktype (or in theory another validation
library implementing `.toJsonSchema()`) can be used instead of zod.

Mostly out of my own curiosity, and zod will remain the recommended way
to use this, but feels sensible to not be too coupled to zod.

Notes:
- arktype's `.toJsonSchema()` doesn't always produce a usable json
schema, see arktypeio/arktype#1379 and
arktype.test.ts
- removes some overly-clever logic that attempts to smart-parse
positional arguments based on zod tuple elements etc. Still support
distinction between number and integer and string (so that `mycli foo
2.2` will parse as `"2.2"` for an input of type `z.union([z.string(),
z.number().int()])`. But even this is arguably too smart. Maybe an
argument of type `z.union([z.string(), z.number()])` should just always
parse as a number

Future:

- valibot
- typebox
- effect
- more??
- maybe a proposal to add `.toJsonSchema()` to the standard-schema spec?
I doubt it would be accpeted, but maybe, if there were some official
caveats like it being optional, and it being able to rely on external
libs or something
- maybe even more logic around how to pick a winner in a union
- probably an env var to allow doing something like
`TRPC_CLI_JSON_INPUTS=true mycli foo --input '{"xx": 1, "yy" 2}'` - idea
being that if you don't like the way this library has transformed the
input type into CLI arguments, you can opt out as an escape hatch

---------

Co-authored-by: Misha Kaletsky <[email protected]>

Author: mmkal

README.md

@@ -13,6 +13,7 @@ Turn a [tRPC](https://trpc.io) router into a type-safe, fully-functional, docume
    - [Ignored procedures](#ignored-procedures)
    - [API docs](#api-docs)
    - [Calculator example](#calculator-example)
+- [arktype](#arktype)
 - [tRPC v10 vs v11](#trpc-v10-vs-v11)
 - [Output and lifecycle](#output-and-lifecycle)
 - [Testing your CLI](#testing-your-cli)
@@ -308,7 +309,7 @@ Note: by design, `createCli` simply collects these procedures rather than throwi
 ### API docs
 
 <!-- codegen:start {preset: markdownFromJsdoc, source: src/index.ts, export: createCli} -->
-#### [createCli](./src/index.ts#L64)
+#### [createCli](./src/index.ts#L65)
 
 Run a trpc router as a CLI.
 
@@ -443,6 +444,7 @@ Arguments:
 
 Options:
   -h, --help   display help for command
+
 ```
 <!-- codegen:end -->
 
@@ -504,6 +506,30 @@ const appRouter = trpc.router({
 })
 ```
 
+## arktype
+
+You can also use arktype to validate your inputs.
+
+```ts
+import {type} from 'arktype'
+import {type TrpcCliMeta} from 'trpc-cli'
+
+const t = initTRPC.meta<TrpcCliMeta>().create()
+
+const router = t.router({
+  add: t.procedure
+    .input(type({left: 'number', right: 'number'}))
+    .query(({input}) => input.left + input.right),
+})
+
+const cli = createCli({router})
+
+cli.run() // e.g. `mycli add --left 1 --right 2`
+```
+
+Note: you will need to install `arktype` as a dependency separately
+Note: some arktype features result in types that can't be converted cleanly to CLI args/options, so for some procedures you may need to use the `--input` flag to pass in a JSON string. Check your CLI help text to see if this is the case.
+
 ## tRPC v10 vs v11
 
 Both versions 10 and 11 of `@trpc/server` are both supported, but if using tRPC v11 you must pass in your `@trpc/server` module to `createCli`:
@@ -958,11 +984,15 @@ You can then use tab-completion to autocomplete commands and flags.
 
 ### Implementation and dependencies
 
+All dependencies have zero dependencies of their own, so the dependency tree is very shallow.
+
+- [@trpc/server](https://npmjs.com/package/@trpc/server) for the trpc router
 - [commander](https://npmjs.com/package/commander) for parsing arguments before passing to trpc
+- [zod](https://npmjs.com/package/zod) for input validation, included for convenience
 - [zod-to-json-schema](https://npmjs.com/package/zod-to-json-schema) to convert zod schemas to make them easier to recurse and format help text from
 - [zod-validation-error](https://npmjs.com/package/zod-validation-error) to make bad inputs have readable error messages
 
-`zod` and `@tprc/server` are peer dependencies - right now only zod 3+ and @trpc/server 10+ have been tested, but it may work with most versions of zod.
+`zod` and `@tprc/server` are included as dependencies for convenience, but you can use your own separate installations if you prefer. Zod 3+ and @trpc/server 10 and 11, have been tested. It should work with most versions of zod.
 
 ### Testing
 

eslint.config.js

@@ -1 +1,4 @@
-module.exports = require('eslint-plugin-mmkal').recommendedFlatConfigs
+module.exports = [
+  ...require('eslint-plugin-mmkal').recommendedFlatConfigs,
+  {ignores: ['**/*ignoreme*']}, //
+]

package.json

@@ -34,9 +34,8 @@
   },
   "homepage": "https://github.com/mmkal/trpc-cli#readme",
   "peerDependencies": {
-    "omelette": ">=0.4.17",
     "@trpc/server": ">=10",
-    "zod": ">=3"
+    "omelette": ">=0.4.17"
   },
   "peerDependenciesMeta": {
     "omelette": {
@@ -54,12 +53,14 @@
     "@types/omelette": "^0.4.4",
     "commander": "^13.1.0",
     "picocolors": "^1.0.1",
-    "zod": "^3.23.8",
+    "zod": "^3.24.2",
     "zod-to-json-schema": "^3.23.0",
     "zod-validation-error": "^3.3.0"
   },
   "devDependencies": {
+    "@types/json-schema": "7.0.15",
     "@types/node": "20.16.11",
+    "arktype": "2.1.9",
     "eslint": "8",
     "eslint-plugin-mmkal": "https://pkg.pr.new/mmkal/eslint-plugin-mmkal@899fddb",
     "execa": "9.3.1",

pnpm-lock.yaml

@@ -2,15 +2,26 @@ import {createHash} from 'crypto'
 import {execaCommandSync} from 'execa'
 import stripAnsi from 'strip-ansi'
 
-export const command: import('eslint-plugin-mmkal').CodegenPreset<{command: string; reject?: false}> = ({options}) => {
+export const command: import('eslint-plugin-mmkal').CodegenPreset<{command: string; reject?: false}> = ({
+  options,
+  meta,
+}) => {
   const result = execaCommandSync(options.command, {all: true, reject: options.reject})
-  return [
+  const output = [
     `\`${options.command.replace(/.* test\/fixtures\//, 'node path/to/')}\` output:`,
     '',
     '```',
     stripAnsi(result.all), // includes stderr
     '```',
   ].join('\n')
+
+  const noWhitespace = (s: string) => s.replaceAll(/\s+/g, '')
+
+  if (noWhitespace(output) === noWhitespace(meta.existingContent)) {
+    return meta.existingContent
+  }
+
+  return output
 }
 
 export const dump: import('eslint-plugin-mmkal').CodegenPreset<{file: string}> = ({dependencies, options, meta}) => {

readme-codegen.ts

@@ -9,10 +9,10 @@ import {addCompletions} from './completions'
 import {FailedToExitError, CliValidationError} from './errors'
 import {flattenedProperties, incompatiblePropertyPairs, getDescription, getSchemaTypes} from './json-schema'
 import {lineByLineConsoleLogger} from './logging'
+import {parseProcedureInputs} from './parse-procedure'
 import {AnyProcedure, AnyRouter, CreateCallerFactoryLike, isTrpc11Procedure} from './trpc-compat'
 import {Logger, OmeletteInstanceLike, TrpcCliMeta, TrpcCliParams} from './types'
 import {looksLikeInstanceof} from './util'
-import {parseProcedureInputs} from './zod-procedure'
 
 export * from './types'
 
@@ -47,6 +47,7 @@ type TrpcCliRunParams = {
 
 type CommanderProgramLike = {
   parseAsync: (args: string[], options?: {from: 'user' | 'node' | 'electron'}) => Promise<unknown>
+  helpInformation: () => string
 }
 
 export interface TrpcCli {
@@ -87,13 +88,12 @@ export function createCli<R extends AnyRouter>({router, ...params}: TrpcCliParam
           procedure,
           procedureInputs: {
             positionalParameters: [],
-            parameters: [],
             optionsJsonSchema: {
               type: 'object',
               properties: {
                 input: {
                   type: 'json' as string as 'string',
-                  description: 'Input formatted as JSON',
+                  description: `Input formatted as JSON${procedureInputsResult.success ? '' : ` (procedure's schema couldn't be converted to CLI arguments: ${procedureInputsResult.error})`}`,
                 },
               },
             },
@@ -149,6 +149,9 @@ export function createCli<R extends AnyRouter>({router, ...params}: TrpcCliParam
         throw new FailedToExitError(`Command ${command.name()} exitOverride`, {exitCode: ec.exitCode, cause: ec})
       })
       command.configureOutput({
+        writeOut: str => {
+          logger.info?.(str)
+        },
         writeErr: str => {
           logger.error?.(str)
         },
@@ -167,7 +170,12 @@ export function createCli<R extends AnyRouter>({router, ...params}: TrpcCliParam
       command.description(meta?.description || '')
 
       procedureInputs.positionalParameters.forEach(param => {
-        const argument = new Argument(param.name, param.description + (param.required ? ` (required)` : ''))
+        const descriptionParts = [
+          // param.type, //
+          param.description,
+          param.required ? '(required)' : '',
+        ]
+        const argument = new Argument(param.name, descriptionParts.join(' '))
         argument.required = param.required
         argument.variadic = param.array
         command.addArgument(argument)
@@ -272,6 +280,16 @@ export function createCli<R extends AnyRouter>({router, ...params}: TrpcCliParam
           command.addOption(option)
           return
         }
+        if (rootTypes.length === 2 && rootTypes[0] === 'number' && rootTypes[1] === 'string') {
+          const option = new Option(`${flags} ${bracketise('value')}`, description)
+          option.argParser(value => {
+            const number = numberParser(value, {fallback: null})
+            return number ?? value
+          })
+          if (defaultValue.exists) option.default(defaultValue.value)
+          command.addOption(option)
+          return
+        }
 
         if (rootTypes.length !== 1) {
           const option = new Option(`${flags} ${bracketise('json')}`, `${description} (value will be parsed as JSON)`)
@@ -307,7 +325,8 @@ export function createCli<R extends AnyRouter>({router, ...params}: TrpcCliParam
           option.argParser(value => numberParser(value))
         } else if (propertyType === 'array') {
           option = new Option(`${flags} [values...]`, description)
-          option.default(defaultValue.exists ? defaultValue.value : [])
+          if (defaultValue.exists) option.default(defaultValue.value)
+          else if (isValueRequired) option.default([])
           const itemTypes =
             'items' in propertyValue && propertyValue.items
               ? getSchemaTypes(propertyValue.items as JsonSchema7Type)
@@ -545,6 +564,9 @@ function transformError(err: unknown, command: Command) {
         cause.issues = originalIssues
       }
     }
+    if (err.code === 'BAD_REQUEST' && err.cause?.constructor?.name === 'TraversalError') {
+      return new CliValidationError(err.cause.message + '\n\n' + command.helpInformation())
+    }
     if (err.code === 'INTERNAL_SERVER_ERROR') {
       return cause
     }

src/index.ts

@@ -88,6 +88,7 @@ export const getDescription = (v: JsonSchema7Type, depth = 0): string => {
         if (k === 'type' && Array.isArray(vv)) return `type: ${vv.join(' or ')}`
         if (k === 'description' && i === 0) return String(vv)
         if (k === 'properties') return `Object (json formatted)`
+        if (typeof vv === 'object') return `${capitaliseFromCamelCase(k)}: ${JSON.stringify(vv)}`
         return `${capitaliseFromCamelCase(k)}: ${vv}`
       })
       .join('; ') || ''
@@ -97,15 +98,24 @@ export const getDescription = (v: JsonSchema7Type, depth = 0): string => {
 export const getSchemaTypes = (
   propertyValue: JsonSchema7Type,
 ): Array<'string' | 'boolean' | 'number' | (string & {})> => {
+  const array: string[] = []
   if ('type' in propertyValue) {
-    return [propertyValue.type].flat()
+    array.push(...[propertyValue.type].flat())
+  }
+  if ('enum' in propertyValue && Array.isArray(propertyValue.enum)) {
+    array.push(...propertyValue.enum.flatMap(s => typeof s))
+  }
+  if ('const' in propertyValue && propertyValue.const === null) {
+    array.push('null')
+  } else if ('const' in propertyValue) {
+    array.push(typeof propertyValue.const)
   }
   if ('oneOf' in propertyValue) {
-    return (propertyValue.oneOf as JsonSchema7Type[]).flatMap(getSchemaTypes)
+    array.push(...(propertyValue.oneOf as JsonSchema7Type[]).flatMap(getSchemaTypes))
   }
   if ('anyOf' in propertyValue) {
-    return (propertyValue.anyOf as JsonSchema7Type[]).flatMap(getSchemaTypes)
+    array.push(...(propertyValue.anyOf as JsonSchema7Type[]).flatMap(getSchemaTypes))
   }
 
-  return []
+  return [...new Set(array)]
 }