@cli-schema/zod 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+# @cli-schema/zod
+
+Derives [CLI Schema](https://github.com/cli-schema/cli-schema) parameter definitions from
+[Zod](https://zod.dev) schemas — types, requiredness, defaults, descriptions, and JSON-Schema
+validation constraints, all read directly off the schema you already wrote for validation.
+
+Part of the [`cli-schema-js`](https://github.com/cli-schema/cli-schema-js) monorepo. Framework-
+agnostic: it doesn't know about Commander, yargs, or any other CLI library — it only knows Zod
+in, structured parameter data out. [`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander)
+builds on top of it.
+
+## Quickstart
+
+```sh
+npm install @cli-schema/zod zod
+```
+
+```ts
+import { z } from 'zod'
+import { extractSchemaArgs } from '@cli-schema/zod'
+
+const SearchInput = z.object({
+  index: z.string().describe('Index to search'),
+  size: z.number().default(10).describe('Number of results'),
+})
+
+extractSchemaArgs(SearchInput)
+// [
+//   { schemaKey: 'index', cliFlag: 'index', type: 'string', required: true,  description: 'Index to search' },
+//   { schemaKey: 'size',  cliFlag: 'size',  type: 'number', required: false, description: 'Number of results', defaultValue: 10 },
+// ]
+```
+
+That's the core of it: one Zod object schema in, one CLI parameter definition per top-level key
+out.
+
+## Purpose
+
+If your CLI already validates its input with Zod, that schema *is* a complete, precise
+description of every flag the command accepts — type, requiredness, default, description,
+enum/range/length constraints. Re-describing all of that by hand for help text, documentation, or
+a CLI Schema document is duplicated, drifting work. `@cli-schema/zod` reads it back out.
+
+It deliberately knows nothing about any particular CLI's own conventions (routing metadata,
+custom parsing hints, reserved flag names) — those vary per project, so they're exposed as
+extension points (`enrich`, a `reserved` list) rather than baked in.
+
+## Features
+
+- **`extractSchemaArgs`** — the main entry point. Walks a `z.object()`'s top-level shape and
+  returns one `SchemaArgDefinition` per key:
+  - **Type inference** across `string`, `number`, `integer` (zod's `z.int()`), `boolean`,
+    `object`, `array`, `enum` — including through `.optional()`, `.default()`, `z.lazy()`,
+    `z.union()` (first member wins), `z.record()`/`z.any()`/`z.unknown()` (→ `object`).
+  - **Kebab-case flag names** derived from the schema key (`toKebabCase`) — handles
+    `snake_case`, `camelCase`, and strips leading underscores (`_source` → `source`).
+  - **Requiredness and defaults** — a field is required only if it's neither optional nor
+    defaulted; `defaultValue` is read straight off `.default(...)`.
+  - **Descriptions** from `.describe()` / `.meta({ description })`.
+  - **`acceptsArrayForm`** detection for the `union(T, array(T))` pattern — a common way to let a
+    field accept either a single value or a collection while keeping the type inference on the
+    scalar branch for CLI ergonomics.
+  - **An `enrich` hook** so your own framework can attach extra fields (routing metadata, parse
+    hints, anything) without this package needing to know what they mean.
+- **`validateSchemaArgs`** — fail-fast collision detection: throws if two schema keys would
+  produce the same CLI flag, or if a flag collides with your CLI's reserved names.
+- **`buildFlagKeyMap`** — a bidirectional `cliFlag` ↔ `schemaKey` map, for merging parsed CLI
+  flags back into the shape your Zod schema expects.
+- **JSON-Schema-derived enrichment** (`zodToJsonSchema`, `extractEnumValues`,
+  `extractElementType`, `extractValidations`) — for the detail `extractSchemaArgs` alone can't
+  carry (enum values, array element types, range/length/regex/email/url constraints), reusing
+  Zod's own `toJSONSchema()` rather than re-implementing schema introspection.
+- **`readMetaField` / `walkWrapperChain`** — the low-level primitives the above are built on,
+  exported for CLIs that need their own custom extraction (e.g. a `found_in` routing tag, or a
+  named-shape check like "is this schema tagged `Sort` anywhere in its wrapper chain").
+
+## Usage
+
+### Basic extraction
+
+```ts
+import { z } from 'zod'
+import { extractSchemaArgs } from '@cli-schema/zod'
+
+const args = extractSchemaArgs(z.object({
+  numShards: z.number().min(1).max(100),
+  level: z.enum(['low', 'medium', 'high']).default('medium'),
+  tags: z.array(z.string()).optional(),
+}))
+
+args.map((a) => a.cliFlag) // ['num-shards', 'level', 'tags']
+```
+
+### Attaching framework-specific extras with `enrich`
+
+Say your CLI routes some fields to an HTTP path/query/body via `.meta({ found_in: '...' })`.
+Rather than this package hardcoding that convention, thread it through `enrich`:
+
+```ts
+import { z } from 'zod'
+import { extractSchemaArgs, type SchemaArgDefinition } from '@cli-schema/zod'
+
+interface MyExtras {
+  foundIn?: 'path' | 'query' | 'body'
+}
+
+const schema = z.object({
+  index: z.string().meta({ found_in: 'path' }),
+  q: z.string().optional().meta({ found_in: 'query' }),
+})
+
+const args: Array<SchemaArgDefinition & MyExtras> = extractSchemaArgs(schema, {
+  enrich: (field, base) => {
+    const foundIn = (field.meta() as Record<string, unknown> | undefined)?.['found_in']
+    return foundIn != null ? { foundIn } : {}
+  },
+})
+```
+
+### Validating for flag collisions
+
+```ts
+import { validateSchemaArgs } from '@cli-schema/zod'
+
+// throws: "help" collides with a name your CLI already uses for --help
+validateSchemaArgs(extractSchemaArgs(z.object({ help: z.string() })), ['help', 'json', 'config-file'])
+```
+
+`reserved` defaults to `['help']` if omitted, since nearly every CLI framework reserves
+`--help`.
+
+### Round-tripping flags back to schema keys
+
+```ts
+import { buildFlagKeyMap } from '@cli-schema/zod'
+
+const map = buildFlagKeyMap(args)
+map.toSchemaKey.get('num-shards') // 'numShards'
+map.toCliFlag.get('numShards')    // 'num-shards'
+```
+
+### Enum values, array element types, and validation constraints
+
+`extractSchemaArgs` alone doesn't carry enum values or range/length constraints — those need the
+full JSON Schema, which is a separate (and more expensive) step best done once per command:
+
+```ts
+import { z } from 'zod'
+import { extractSchemaArgs, zodToJsonSchema, extractEnumValues, extractElementType, extractValidations } from '@cli-schema/zod'
+
+const schema = z.object({
+  level: z.enum(['low', 'medium', 'high']),
+  size: z.number().min(1).max(100),
+})
+
+const root = zodToJsonSchema(schema)
+const properties = root.properties as Record<string, Record<string, unknown>>
+
+for (const arg of extractSchemaArgs(schema)) {
+  const node = properties[arg.schemaKey]
+  console.log(arg.cliFlag, {
+    enumValues: extractEnumValues(node, root),
+    elementType: extractElementType(node, root), // only meaningful when arg.type === 'array'
+    validations: extractValidations(node, root),  // e.g. [{ kind: 'range', min: '1', max: '100' }]
+  })
+}
+```
+
+`extractValidations` covers the constraint kinds directly derivable from JSON Schema keywords —
+`range` (`minimum`/`maximum`), `length` (`minLength`/`maxLength`), `regex` (`pattern`), `email`
+and `url` (`format`). Kinds that need domain knowledge beyond what JSON Schema expresses
+(`timeSpanRange`, `count`, `allowed`, `denied`, `uriScheme`, `fileExtensions`, `existing`,
+`nonExisting`, `rejectSymbolicLinks` — see the [spec](https://github.com/cli-schema/cli-schema/blob/main/spec/v1/README.md#62-constraints))
+aren't inferred automatically; attach them via the `enrich` hook if your schema encodes them.
+
+## Related packages
+
+- [`@cli-schema/spec`](https://www.npmjs.com/package/@cli-schema/spec) — the `Constraint`/`Parameter` types this package's JSON-Schema helpers produce
+- [`@cli-schema/commander`](https://www.npmjs.com/package/@cli-schema/commander) — wires this package's output into a full `CliSchema` document from a live Commander tree
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './schema-args.ts';
+export * from './json-schema.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./schema-args.js";
+export * from "./json-schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA"}

package/dist/json-schema.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { Constraint, ParameterElementType } from '@cli-schema/spec';
+export type JsonSchemaNode = Record<string, unknown>;
+export declare function zodToJsonSchema(schema: z.ZodType): JsonSchemaNode;
+export declare function resolveRef(node: JsonSchemaNode, root: JsonSchemaNode): JsonSchemaNode;
+export declare function unwrapNullable(node: JsonSchemaNode, root: JsonSchemaNode): JsonSchemaNode;
+export declare function resolveNode(node: JsonSchemaNode, root: JsonSchemaNode): JsonSchemaNode;
+export declare function extractEnumValues(node: JsonSchemaNode, root: JsonSchemaNode): string[] | undefined;
+export declare function extractElementType(node: JsonSchemaNode, root: JsonSchemaNode): ParameterElementType | undefined;
+export declare function extractValidations(node: JsonSchemaNode, root: JsonSchemaNode): Constraint[] | undefined;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAExE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAGpD,wBAAgB,eAAe,CAAE,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,cAAc,CAElE;AAED,wBAAgB,UAAU,CAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAUtF;AAED,wBAAgB,cAAc,CAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAS1F;AAED,wBAAgB,WAAW,CAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,cAAc,CAEvF;AAED,wBAAgB,iBAAiB,CAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,EAAE,GAAG,SAAS,CAKnG;AAID,wBAAgB,kBAAkB,CAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,oBAAoB,GAAG,SAAS,CAShH;AAaD,wBAAgB,kBAAkB,CAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,GAAG,UAAU,EAAE,GAAG,SAAS,CAwCxG"}

package/dist/json-schema.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+export function zodToJsonSchema(schema) {
+    return z.toJSONSchema(schema, { reused: 'ref' });
+}
+export function resolveRef(node, root) {
+    const ref = node['$ref'];
+    if (typeof ref !== 'string')
+        return node;
+    const parts = ref.replace(/^#\//, '').split('/');
+    let cur = root;
+    for (const part of parts) {
+        if (cur == null || typeof cur !== 'object')
+            return node;
+        cur = cur[part];
+    }
+    return (cur != null && typeof cur === 'object') ? cur : node;
+}
+export function unwrapNullable(node, root) {
+    const anyOf = node['anyOf'];
+    if (!Array.isArray(anyOf))
+        return node;
+    const nonNull = anyOf.find((b) => {
+        if (b == null || typeof b !== 'object')
+            return false;
+        const branch = b;
+        return branch['type'] !== 'null' && branch['const'] !== null;
+    });
+    return nonNull != null ? resolveRef(nonNull, root) : node;
+}
+export function resolveNode(node, root) {
+    return unwrapNullable(resolveRef(node, root), root);
+}
+export function extractEnumValues(node, root) {
+    const resolved = resolveNode(node, root);
+    const enumVals = resolved['enum'];
+    if (!Array.isArray(enumVals) || enumVals.length === 0)
+        return undefined;
+    return enumVals.filter((v) => v != null).map(String);
+}
+const SCALAR_ELEMENT_TYPES = new Set(['string', 'integer', 'number', 'boolean']);
+export function extractElementType(node, root) {
+    const resolved = resolveNode(node, root);
+    const items = resolved['items'];
+    if (items == null || typeof items !== 'object')
+        return undefined;
+    const resolvedItems = resolveNode(items, root);
+    const t = resolvedItems['type'];
+    if (typeof t !== 'string')
+        return undefined;
+    return SCALAR_ELEMENT_TYPES.has(t) ? t : undefined;
+}
+export function extractValidations(node, root) {
+    const resolved = resolveNode(node, root);
+    const validations = [];
+    const min = resolved['minimum'];
+    const max = resolved['maximum'];
+    if (min !== undefined || max !== undefined) {
+        validations.push({
+            kind: 'range',
+            ...(min !== undefined && { min: String(min) }),
+            ...(max !== undefined && { max: String(max) }),
+        });
+    }
+    const minLength = resolved['minLength'];
+    const maxLength = resolved['maxLength'];
+    if (minLength !== undefined || maxLength !== undefined) {
+        validations.push({
+            kind: 'length',
+            ...(minLength !== undefined && { min: String(minLength) }),
+            ...(maxLength !== undefined && { max: String(maxLength) }),
+        });
+    }
+    const format = resolved['format'];
+    if (format === 'email') {
+        validations.push({ kind: 'email' });
+    }
+    else if (format === 'uri' || format === 'url') {
+        validations.push({ kind: 'url' });
+    }
+    else {
+        const pattern = resolved['pattern'];
+        if (typeof pattern === 'string') {
+            validations.push({ kind: 'regex', pattern });
+        }
+    }
+    return validations.length > 0 ? validations : undefined;
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"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"}

package/dist/schema-args.d.ts

@@ -0,0 +1,24 @@
+import type { z } from 'zod';
+export type SchemaArgType = 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array' | 'enum';
+export interface SchemaArgDefinition {
+    schemaKey: string;
+    cliFlag: string;
+    type: SchemaArgType;
+    required: boolean;
+    defaultValue?: unknown;
+    description: string;
+    acceptsArrayForm?: boolean;
+}
+export interface FlagKeyMap {
+    toSchemaKey: Map<string, string>;
+    toCliFlag: Map<string, string>;
+}
+export declare function toKebabCase(key: string): string;
+export declare function walkWrapperChain(field: z.ZodType, predicate: (node: z.ZodType) => boolean): boolean;
+export declare function readMetaField<T = unknown>(field: z.ZodType, key: string): T | undefined;
+export declare function extractSchemaArgs<E extends object = object>(schema: unknown, opts?: {
+    enrich?: (field: z.ZodType, base: SchemaArgDefinition) => E;
+}): Array<SchemaArgDefinition & E>;
+export declare function buildFlagKeyMap(args: Array<Pick<SchemaArgDefinition, 'schemaKey' | 'cliFlag'>>): FlagKeyMap;
+export declare function validateSchemaArgs(args: Array<Pick<SchemaArgDefinition, 'schemaKey' | 'cliFlag'>>, reserved?: Iterable<string>): void;
+//# sourceMappingURL=schema-args.d.ts.map

package/dist/schema-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-args.d.ts","sourceRoot":"","sources":["../src/schema-args.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAG5B,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;AAQrG,MAAM,WAAW,mBAAmB;IAElC,SAAS,EAAE,MAAM,CAAA;IAGjB,OAAO,EAAE,MAAM,CAAA;IAGf,IAAI,EAAE,aAAa,CAAA;IAGnB,QAAQ,EAAE,OAAO,CAAA;IAGjB,YAAY,CAAC,EAAE,OAAO,CAAA;IAGtB,WAAW,EAAE,MAAM,CAAA;IAOnB,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAKD,MAAM,WAAW,UAAU;IAEzB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAGhC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAaD,wBAAgB,WAAW,CAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMhD;AAiED,wBAAgB,gBAAgB,CAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,KAAK,OAAO,GAAG,OAAO,CAmBpG;AAOD,wBAAgB,aAAa,CAAE,CAAC,GAAG,OAAO,EAAG,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAWzF;AAwBD,wBAAgB,iBAAiB,CAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC1D,MAAM,EAAE,OAAO,EACf,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,mBAAmB,KAAK,CAAC,CAAA;CAAE,GACrE,KAAK,CAAC,mBAAmB,GAAG,CAAC,CAAC,CA4BhC;AAMD,wBAAgB,eAAe,CAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC,GAAG,UAAU,CAQ5G;AAWD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC,EAC/D,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAY,GACpC,IAAI,CAYN"}

package/dist/schema-args.js

@@ -0,0 +1,118 @@
+export function toKebabCase(key) {
+    return key
+        .replace(/^_+/, '')
+        .replace(/_/g, '-')
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}
+function unwrapField(field) {
+    const def = field.def;
+    if (def.type === 'date') {
+        throw new Error('Date cannot be represented in JSON Schema: use z.string() with an ISO-8601 description instead of z.date()');
+    }
+    if (def.type === 'optional') {
+        const inner = unwrapField(def.innerType);
+        return { ...inner, isOptional: true };
+    }
+    if (def.type === 'default') {
+        const inner = unwrapField(def.innerType);
+        return { ...inner, defaultValue: def.defaultValue, isOptional: false };
+    }
+    if (def.type === 'lazy' && typeof def.getter === 'function') {
+        return unwrapField(def.getter());
+    }
+    if (def.type === 'record' || def.type === 'any' || def.type === 'unknown') {
+        return { typeName: 'object', isOptional: false };
+    }
+    if (def.type === 'union' && Array.isArray(def.options) && def.options.length > 0) {
+        return unwrapField(def.options[0]);
+    }
+    if (def.type === 'int' || def.type === 'int32' || def.type === 'int64') {
+        return { typeName: 'integer', isOptional: false };
+    }
+    return { typeName: def.type, isOptional: false };
+}
+const CLI_TYPES = new Set(['string', 'integer', 'number', 'boolean', 'object', 'array', 'enum']);
+export function walkWrapperChain(field, predicate) {
+    const seen = new Set();
+    function walk(node) {
+        if (seen.has(node))
+            return false;
+        seen.add(node);
+        if (predicate(node))
+            return true;
+        const def = node.def;
+        if (def.type === 'optional' || def.type === 'default') {
+            return def.innerType != null && walk(def.innerType);
+        }
+        if (def.type === 'lazy' && typeof def.getter === 'function') {
+            return walk(def.getter());
+        }
+        if (def.type === 'union' && Array.isArray(def.options)) {
+            return def.options.some((o) => walk(o));
+        }
+        return false;
+    }
+    return walk(field);
+}
+export function readMetaField(field, key) {
+    const outerMeta = field.meta();
+    if (outerMeta?.[key] != null)
+        return outerMeta[key];
+    const innerType = field.def.innerType;
+    if (innerType != null) {
+        const innerMeta = innerType.meta();
+        if (innerMeta?.[key] != null)
+            return innerMeta[key];
+    }
+    return undefined;
+}
+function schemaAcceptsArrayForm(field) {
+    return walkWrapperChain(field, (n) => n.def.type === 'array');
+}
+export function extractSchemaArgs(schema, opts) {
+    const shape = schema?.shape;
+    if (shape == null || typeof shape !== 'object')
+        return [];
+    return Object.entries(shape).map(([key, fieldSchema]) => {
+        const field = fieldSchema;
+        const { typeName, isOptional, defaultValue } = unwrapField(field);
+        const type = (CLI_TYPES.has(typeName) ? typeName : 'string');
+        const description = readMetaField(field, 'description') ?? '';
+        const acceptsArrayForm = type !== 'array' && schemaAcceptsArrayForm(field);
+        const base = {
+            schemaKey: key,
+            cliFlag: toKebabCase(key),
+            type,
+            required: !isOptional && defaultValue === undefined,
+            defaultValue,
+            description,
+            ...(acceptsArrayForm ? { acceptsArrayForm: true } : {}),
+        };
+        const extra = opts?.enrich != null ? opts.enrich(field, base) : {};
+        return { ...base, ...extra };
+    });
+}
+export function buildFlagKeyMap(args) {
+    const toSchemaKey = new Map();
+    const toCliFlag = new Map();
+    for (const arg of args) {
+        toSchemaKey.set(arg.cliFlag, arg.schemaKey);
+        toCliFlag.set(arg.schemaKey, arg.cliFlag);
+    }
+    return { toSchemaKey, toCliFlag };
+}
+export function validateSchemaArgs(args, reserved = ['help']) {
+    const reservedSet = new Set(reserved);
+    const seen = new Set();
+    for (const arg of args) {
+        if (reservedSet.has(arg.cliFlag)) {
+            throw new Error(`Schema key "${arg.schemaKey}" collides with reserved flag "--${arg.cliFlag}"`);
+        }
+        if (seen.has(arg.cliFlag)) {
+            throw new Error(`Duplicate CLI flag collision: multiple schema keys map to "--${arg.cliFlag}"`);
+        }
+        seen.add(arg.cliFlag);
+    }
+}
+//# sourceMappingURL=schema-args.js.map

package/dist/schema-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-args.js","sourceRoot":"","sources":["../src/schema-args.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cli-schema/zod",
+  "version": "0.1.0",
+  "description": "Derives CLI Schema parameter definitions from Zod schemas (https://github.com/cli-schema/cli-schema)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --import tsx/esm --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@cli-schema/spec": "^0.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "^4.3.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cli-schema/cli-schema-js.git",
+    "directory": "packages/zod"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './schema-args.ts'
+export * from './json-schema.ts'

package/src/json-schema.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+import { z } from 'zod'
+import type { Constraint, ParameterElementType } from '@cli-schema/spec'
+
+export type JsonSchemaNode = Record<string, unknown>
+
+/** Converts a Zod schema to JSON Schema, resolving repeated refs to `$ref` (matches `z.toJSONSchema` defaults for this package's needs). */
+export function zodToJsonSchema (schema: z.ZodType): JsonSchemaNode {
+  return z.toJSONSchema(schema, { reused: 'ref' }) as JsonSchemaNode
+}
+
+export function resolveRef (node: JsonSchemaNode, root: JsonSchemaNode): JsonSchemaNode {
+  const ref = node['$ref']
+  if (typeof ref !== 'string') return node
+  const parts = ref.replace(/^#\//, '').split('/')
+  let cur: unknown = root
+  for (const part of parts) {
+    if (cur == null || typeof cur !== 'object') return node
+    cur = (cur as JsonSchemaNode)[part]
+  }
+  return (cur != null && typeof cur === 'object') ? cur as JsonSchemaNode : node
+}
+
+export function unwrapNullable (node: JsonSchemaNode, root: JsonSchemaNode): JsonSchemaNode {
+  const anyOf = node['anyOf']
+  if (!Array.isArray(anyOf)) return node
+  const nonNull = anyOf.find((b: unknown) => {
+    if (b == null || typeof b !== 'object') return false
+    const branch = b as JsonSchemaNode
+    return branch['type'] !== 'null' && branch['const'] !== null
+  })
+  return nonNull != null ? resolveRef(nonNull as JsonSchemaNode, root) : node
+}
+
+export function resolveNode (node: JsonSchemaNode, root: JsonSchemaNode): JsonSchemaNode {
+  return unwrapNullable(resolveRef(node, root), root)
+}
+
+export function extractEnumValues (node: JsonSchemaNode, root: JsonSchemaNode): string[] | undefined {
+  const resolved = resolveNode(node, root)
+  const enumVals = resolved['enum']
+  if (!Array.isArray(enumVals) || enumVals.length === 0) return undefined
+  return enumVals.filter((v) => v != null).map(String)
+}
+
+const SCALAR_ELEMENT_TYPES: ReadonlySet<string> = new Set(['string', 'integer', 'number', 'boolean'])
+
+export function extractElementType (node: JsonSchemaNode, root: JsonSchemaNode): ParameterElementType | undefined {
+  const resolved = resolveNode(node, root)
+  const items = resolved['items']
+  if (items == null || typeof items !== 'object') return undefined
+  const resolvedItems = resolveNode(items as JsonSchemaNode, root)
+  const t = resolvedItems['type']
+  if (typeof t !== 'string') return undefined
+  // Spec only allows scalar element types; object/array items are not expressible.
+  return SCALAR_ELEMENT_TYPES.has(t) ? t as ParameterElementType : undefined
+}
+
+/**
+ * Derives {@link Constraint} validation rules from a resolved JSON Schema node.
+ *
+ * Covers the constraint kinds directly derivable from JSON Schema keywords
+ * (`range`, `length`, `regex`, `email`, `url`). Kinds that require domain knowledge beyond
+ * what JSON Schema expresses (`timeSpanRange`, `count`, `allowed`, `denied`, `uriScheme`,
+ * `fileExtensions`, `existing`, `nonExisting`, `rejectSymbolicLinks`) are not inferred here —
+ * attach them via {@link extractSchemaArgs}'s `enrich` hook if your schema encodes them.
+ *
+ * Enum values are surfaced via the dedicated `enumValues` field, not as a constraint.
+ */
+export function extractValidations (node: JsonSchemaNode, root: JsonSchemaNode): Constraint[] | undefined {
+  const resolved = resolveNode(node, root)
+  const validations: Constraint[] = []
+
+  const min = resolved['minimum']
+  const max = resolved['maximum']
+  if (min !== undefined || max !== undefined) {
+    validations.push({
+      kind: 'range',
+      ...(min !== undefined && { min: String(min) }),
+      ...(max !== undefined && { max: String(max) }),
+    })
+  }
+
+  const minLength = resolved['minLength']
+  const maxLength = resolved['maxLength']
+  if (minLength !== undefined || maxLength !== undefined) {
+    validations.push({
+      kind: 'length',
+      ...(minLength !== undefined && { min: String(minLength) }),
+      ...(maxLength !== undefined && { max: String(maxLength) }),
+    })
+  }
+
+  // A named format (email, url) implies its own pattern under the hood (e.g. zod's z.email()
+  // JSON Schema includes both `format: "email"` and a matching `pattern`); surface only the
+  // named constraint in that case rather than a redundant, semantically weaker regex.
+  const format = resolved['format']
+  if (format === 'email') {
+    validations.push({ kind: 'email' })
+  } else if (format === 'uri' || format === 'url') {
+    validations.push({ kind: 'url' })
+  } else {
+    const pattern = resolved['pattern']
+    if (typeof pattern === 'string') {
+      validations.push({ kind: 'regex', pattern })
+    }
+  }
+
+  return validations.length > 0 ? validations : undefined
+}

package/src/schema-args.ts

@@ -0,0 +1,269 @@
+/*
+ * Copyright cli-schema contributors
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { z } from 'zod'
+
+/** Declared type of a schema-derived CLI argument, before mapping to a spec {@link Parameter} type. */
+export type SchemaArgType = 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array' | 'enum'
+
+/**
+ * Represents a single CLI argument derived from a top-level key in a Zod object schema.
+ *
+ * Framework-specific extras (e.g. HTTP-transport routing, custom parsing hints) are not part
+ * of this type — attach them via the `enrich` option on {@link extractSchemaArgs}.
+ */
+export interface SchemaArgDefinition {
+  /** Original key name as defined in the Zod schema (e.g., `num_shards`, `refreshInterval`) */
+  schemaKey: string
+
+  /** Kebab-case flag name derived from `schemaKey` (e.g., `num-shards`, `refresh-interval`) */
+  cliFlag: string
+
+  /** Declared type from schema introspection */
+  type: SchemaArgType
+
+  /** Whether the field is required (no default, not optional) */
+  required: boolean
+
+  /** Default value from the schema, if any */
+  defaultValue?: unknown
+
+  /** Description from the schema's metadata, used in help text */
+  description: string
+
+  /**
+   * True when the schema accepts both a scalar and an array form (e.g. `Fields = union(Field, array(Field))`).
+   * CLI ergonomics typically register a scalar flag; callers that need the array form split
+   * comma-separated values themselves where the destination demands it.
+   */
+  acceptsArrayForm?: boolean
+}
+
+/**
+ * A bidirectional mapping between kebab-case CLI flag names and original schema keys.
+ */
+export interface FlagKeyMap {
+  /** Maps `cliFlag` -> `schemaKey` for reverse lookup during merge */
+  toSchemaKey: Map<string, string>
+
+  /** Maps `schemaKey` -> `cliFlag` for registration and help text */
+  toCliFlag: Map<string, string>
+}
+
+/**
+ * Converts a schema key to its kebab-case CLI flag name.
+ * Handles snake_case, camelCase, and plain lowercase inputs.
+ *
+ * @example
+ * ```ts
+ * toKebabCase('num_shards')      // 'num-shards'
+ * toKebabCase('refreshInterval') // 'refresh-interval'
+ * toKebabCase('index')           // 'index'
+ * ```
+ */
+export function toKebabCase (key: string): string {
+  return key
+    .replace(/^_+/, '') // strip leading underscores (e.g. Elasticsearch's _source, _meta)
+    .replace(/_/g, '-')
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+}
+
+/** Minimal shape of a Zod field def for the properties we need to introspect. */
+interface ZodFieldDef {
+  type: string
+  innerType?: { def: ZodFieldDef }
+  defaultValue?: unknown
+  getter?: () => z.ZodType
+  options?: z.ZodType[]
+}
+
+/**
+ * Unwraps wrapper types from a Zod schema field, resolving lazy thunks,
+ * records, unions, and any/unknown to their CLI-appropriate type names.
+ */
+function unwrapField (field: z.ZodType): { typeName: string, isOptional: boolean, defaultValue?: unknown } {
+  const def = field.def as ZodFieldDef
+  if (def.type === 'date') {
+    throw new Error('Date cannot be represented in JSON Schema: use z.string() with an ISO-8601 description instead of z.date()')
+  }
+
+  if (def.type === 'optional') {
+    const inner = unwrapField(def.innerType as unknown as z.ZodType)
+    return { ...inner, isOptional: true }
+  }
+
+  if (def.type === 'default') {
+    const inner = unwrapField(def.innerType as unknown as z.ZodType)
+    return { ...inner, defaultValue: def.defaultValue, isOptional: false }
+  }
+
+  if (def.type === 'lazy' && typeof def.getter === 'function') {
+    return unwrapField(def.getter())
+  }
+
+  if (def.type === 'record' || def.type === 'any' || def.type === 'unknown') {
+    return { typeName: 'object', isOptional: false }
+  }
+
+  if (def.type === 'union' && Array.isArray(def.options) && def.options.length > 0) {
+    return unwrapField(def.options[0] as z.ZodType)
+  }
+
+  // zod v4 exposes `z.int()` (and `.int()` refinements) as a distinct 'int' def.type
+  // in some code paths; treat it as a first-class integer rather than folding into 'number'.
+  if (def.type === 'int' || def.type === 'int32' || def.type === 'int64') {
+    return { typeName: 'integer', isOptional: false }
+  }
+
+  return { typeName: def.type, isOptional: false }
+}
+
+const CLI_TYPES = new Set<SchemaArgType>(['string', 'integer', 'number', 'boolean', 'object', 'array', 'enum'])
+
+/**
+ * Walks `field` through `optional`, `default`, `lazy`, and `union` wrappers, returning true
+ * if `predicate` matches any visited node. The `seen` set breaks cycles in self-referential
+ * lazy schemas (e.g. `z.lazy(() => Foo)` where `Foo` references itself).
+ *
+ * Exported for consumers that need to detect wrapped conditions this package doesn't model
+ * itself (e.g. a framework-specific `.meta({id: 'Sort'})` tag anywhere in the wrapper chain).
+ *
+ * Note: evaluating `lazy.getter()` forces lazy-schema evaluation; schemas that need predicates
+ * depending on a lazy's inner shape can't avoid this.
+ */
+export function walkWrapperChain (field: z.ZodType, predicate: (node: z.ZodType) => boolean): boolean {
+  const seen = new Set<z.ZodType>()
+  function walk (node: z.ZodType): boolean {
+    if (seen.has(node)) return false
+    seen.add(node)
+    if (predicate(node)) return true
+    const def = node.def as ZodFieldDef
+    if (def.type === 'optional' || def.type === 'default') {
+      return def.innerType != null && walk(def.innerType as unknown as z.ZodType)
+    }
+    if (def.type === 'lazy' && typeof def.getter === 'function') {
+      return walk(def.getter())
+    }
+    if (def.type === 'union' && Array.isArray(def.options)) {
+      return def.options.some((o) => walk(o))
+    }
+    return false
+  }
+  return walk(field)
+}
+
+/**
+ * Reads a `.meta()` field from `field`, checking the outermost type first and falling back to
+ * one wrapper level in (`optional`/`default`) if absent. Zod's `.optional()`/`.default()` wrap
+ * the original schema, so metadata attached before wrapping lives on the inner type.
+ */
+export function readMetaField <T = unknown> (field: z.ZodType, key: string): T | undefined {
+  const outerMeta = field.meta() as Record<string, unknown> | null | undefined
+  if (outerMeta?.[key] != null) return outerMeta[key] as T
+
+  const innerType = (field.def as { innerType?: z.ZodType }).innerType
+  if (innerType != null) {
+    const innerMeta = innerType.meta() as Record<string, unknown> | null | undefined
+    if (innerMeta?.[key] != null) return innerMeta[key] as T
+  }
+
+  return undefined
+}
+
+/**
+ * Returns true when the schema (or any branch of its unions) accepts an array form.
+ *
+ * A common CLI-schema pattern types a field as `union(T, array(T))` (e.g. accept either a
+ * single value or a comma-separated / repeated collection), which {@link unwrapField} collapses
+ * to the scalar branch for CLI ergonomics. `acceptsArrayForm` surfaces that the array form still
+ * exists so callers can register a `repeatable`/`separator` parameter or split values themselves.
+ */
+function schemaAcceptsArrayForm (field: z.ZodType): boolean {
+  return walkWrapperChain(field, (n) => (n.def as ZodFieldDef).type === 'array')
+}
+
+/**
+ * Extracts CLI argument definitions from a Zod object schema.
+ * Each top-level key becomes a `SchemaArgDefinition` with its kebab-case flag name,
+ * type, required status, default value, and description.
+ *
+ * Returns an empty array if `schema` is not a Zod object schema.
+ *
+ * Pass `enrich` to attach framework-specific extras (read off the original, un-unwrapped Zod
+ * field) to each definition — e.g. HTTP-transport routing metadata, custom parse hints.
+ */
+export function extractSchemaArgs <E extends object = object> (
+  schema: unknown,
+  opts?: { enrich?: (field: z.ZodType, base: SchemaArgDefinition) => E },
+): Array<SchemaArgDefinition & E> {
+  const shape = (schema as z.ZodObject<z.ZodRawShape> | null)?.shape
+  if (shape == null || typeof shape !== 'object') return []
+
+  return Object.entries(shape).map(([key, fieldSchema]) => {
+    const field = fieldSchema as z.ZodType
+    const { typeName, isOptional, defaultValue } = unwrapField(field)
+    const type = (CLI_TYPES.has(typeName as SchemaArgType) ? typeName : 'string') as SchemaArgType
+
+    // Read description from the Zod globalRegistry -- much faster than calling
+    // .toJSONSchema() per field, which would force lazy-schema evaluation.
+    const description = readMetaField<string>(field, 'description') ?? ''
+
+    const acceptsArrayForm = type !== 'array' && schemaAcceptsArrayForm(field)
+
+    const base: SchemaArgDefinition = {
+      schemaKey: key,
+      cliFlag: toKebabCase(key),
+      type,
+      required: !isOptional && defaultValue === undefined,
+      defaultValue,
+      description,
+      ...(acceptsArrayForm ? { acceptsArrayForm: true } : {}),
+    }
+
+    const extra = opts?.enrich != null ? opts.enrich(field, base) : ({} as E)
+    return { ...base, ...extra }
+  })
+}
+
+/**
+ * Builds a bidirectional mapping between CLI flag names and schema keys for a command.
+ * Created once at registration time; immutable after creation.
+ */
+export function buildFlagKeyMap (args: Array<Pick<SchemaArgDefinition, 'schemaKey' | 'cliFlag'>>): FlagKeyMap {
+  const toSchemaKey = new Map<string, string>()
+  const toCliFlag = new Map<string, string>()
+  for (const arg of args) {
+    toSchemaKey.set(arg.cliFlag, arg.schemaKey)
+    toCliFlag.set(arg.schemaKey, arg.cliFlag)
+  }
+  return { toSchemaKey, toCliFlag }
+}
+
+/**
+ * Validates schema arguments for naming conflicts.
+ * Throws if any `cliFlag` collides with a `reserved` flag or duplicates another arg's flag.
+ * Called at command registration time for fail-fast detection.
+ *
+ * @param reserved - flag names this CLI already uses for framework-level concerns
+ *   (e.g. `help`, `json`, `config-file`). Defaults to `['help']`, since nearly every CLI
+ *   framework reserves `--help`.
+ */
+export function validateSchemaArgs (
+  args: Array<Pick<SchemaArgDefinition, 'schemaKey' | 'cliFlag'>>,
+  reserved: Iterable<string> = ['help'],
+): void {
+  const reservedSet = new Set(reserved)
+  const seen = new Set<string>()
+  for (const arg of args) {
+    if (reservedSet.has(arg.cliFlag)) {
+      throw new Error(`Schema key "${arg.schemaKey}" collides with reserved flag "--${arg.cliFlag}"`)
+    }
+    if (seen.has(arg.cliFlag)) {
+      throw new Error(`Duplicate CLI flag collision: multiple schema keys map to "--${arg.cliFlag}"`)
+    }
+    seen.add(arg.cliFlag)
+  }
+}