@crustjs/validate 0.0.1 → 0.0.2

package/dist/zod/index.d.ts

@@ -1,5 +1,4 @@
-import { AnyCommand as AnyCommand2, ValidateFlagAliases, ValidateVariadicArgs } from "@crustjs/core";
-import { CommandContext, CommandDef } from "@crustjs/core";
+import { ArgDef, ArgsDef, FlagDef, FlagsDef } from "@crustjs/core";
 import * as z from "zod/v4/core";
 import { AnyCommand } from "@crustjs/core";
 /**
@@ -29,162 +28,162 @@ interface ValidatedContext<
 		flags: Record<string, unknown>;
 	};
 }
-/** A Zod schema used by the Zod entrypoint. */
+/**
+* Unique symbol used to attach a Zod schema to a core `ArgDef` or `FlagDef`.
+*
+* Survives `{ ...def }` spread in `defineCommand` and `Object.freeze`,
+* making the schema available at runtime via `def[ZOD_SCHEMA]`.
+*/
+declare const ZOD_SCHEMA: unique symbol;
+type ZOD_SCHEMA = typeof ZOD_SCHEMA;
+/** A Zod schema used by the validate/zod entrypoint. */
 type ZodSchemaLike<
 	Input = unknown,
 	Output = Input
 > = z.$ZodType<Output, Input>;
-/** Infer output type from a Zod schema. */
-type InferSchemaOutput<S> = S extends z.$ZodType ? z.output<S> : never;
-/** Optional metadata for a positional argument declared with `arg()`. */
-interface ArgOptions {
-	/** Collect remaining positionals into this arg as an array. */
-	readonly variadic?: true;
-}
+/** CLI value type literals. */
+type ValueType = "string" | "number" | "boolean";
 /**
-* A single positional argument spec produced by `arg()`.
+* Resolve the CLI `ValueType` from a Zod schema at the type level.
 *
-* The `Variadic` generic parameter preserves the literal `true` from
-* `arg()` calls so `ValidateVariadicArgs` can distinguish variadic args
-* from non-variadic ones at compile time.
+* Unwraps common wrappers (optional, default, nullable, pipe, catch,
+* prefault, nonoptional, readonly) and maps leaf schemas to their
+* primitive type string.
 *
-* - `ArgSpec<N, S, true>` — variadic arg (only valid in last position)
-* - `ArgSpec<N, S, undefined>` — normal positional arg
-* - `ArgSpec<N, S>` (default) — type-erased form used in constraints
+* Falls back to `ValueType` (the union) for unrecognized schemas — the
+* runtime introspection always produces the correct narrow value.
 */
-interface ArgSpec<
+type ResolveZodValueType<S> = S extends z.$ZodString ? "string" : S extends z.$ZodNumber ? "number" : S extends z.$ZodBoolean ? "boolean" : S extends z.$ZodEnum ? "string" : S extends z.$ZodLiteral<infer L> ? L extends string ? "string" : L extends number ? "number" : L extends boolean ? "boolean" : ValueType : S extends z.$ZodOptional<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodDefault<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodNullable<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodCatch<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodPrefault<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodNonOptional<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodReadonly<infer Inner> ? ResolveZodValueType<Inner> : S extends z.$ZodPipe<infer In, infer _Out> ? ResolveZodValueType<In> : ValueType;
+/**
+* An `ArgDef` enriched with a hidden Zod schema.
+*
+* The `Type` parameter is resolved from the schema at the type level via
+* `ResolveZodValueType`, producing a narrow literal (e.g. `"number"`) that
+* matches exactly one variant of core's discriminated `ArgDef` union.
+*
+* The `ZOD_SCHEMA` symbol key carries the schema for runtime validation.
+*/
+interface ZodArgDef<
 	Name extends string = string,
 	Schema extends ZodSchemaLike = ZodSchemaLike,
-	Variadic extends true | undefined = true | undefined
+	Variadic extends true | undefined = true | undefined,
+	Type extends ValueType = ResolveZodValueType<Schema>
 > {
-	readonly kind: "arg";
 	readonly name: Name;
-	readonly schema: Schema;
+	readonly type: Type;
+	readonly description?: string;
+	readonly required?: true;
+	/**
+	* Non-optional so `ValidateVariadicArgs` can match `{ variadic: true }`.
+	* When `Variadic` is `undefined`, the runtime value is `undefined`.
+	*/
 	readonly variadic: Variadic;
-}
-/** Ordered positional argument specs. */
-type ArgSpecs = readonly ArgSpec[];
-/** Output type for one ArgSpec in the validated handler context. */
-type InferArgValue<S extends ArgSpec> = S["variadic"] extends true ? InferSchemaOutput<S["schema"]>[] : InferSchemaOutput<S["schema"]>;
-/** Flattens an intersection of objects for readable inferred types. */
-type Simplify<T> = { [K in keyof T] : T[K] };
-/** Recursively maps ordered ArgSpec entries to a named output object type. */
-type InferArgsFromTuple<A extends readonly ArgSpec[]> = A extends readonly [infer Head extends ArgSpec, ...infer Tail extends readonly ArgSpec[]] ? { [K in Head["name"]] : InferArgValue<Head> } & InferArgsFromTuple<Tail> : {};
-/** Infer validated args object type from ordered ArgSpec entries. */
-type InferArgsFromSpecs<A extends ArgSpecs> = Simplify<InferArgsFromTuple<A>>;
-/** Optional metadata for a flag declared with `flag()`. */
-interface FlagOptions {
-	/** Short alias or array of aliases (e.g. `"v"` or `["v", "V"]`). */
-	readonly alias?: string | readonly string[];
+	readonly [ZOD_SCHEMA]: Schema;
 }
 /**
-* A named flag schema wrapper produced by `flag()`.
+* A `FlagDef` enriched with a hidden Zod schema.
 *
-* The `Alias` generic parameter preserves alias literals (e.g. `"v"` or
-* `readonly ["v", "V"]`) from `flag()` calls so `ValidateFlagAliases` can
-* detect collisions at compile time.
+* The `Type` parameter is resolved from the schema at the type level.
 *
-* - `FlagSpec<S, "v">` — flag with alias `"v"` (collision-detectable)
-* - `FlagSpec<S, undefined>` — flag without an alias
-* - `FlagSpec<S>` (default) — type-erased form used in constraints
+* The `ZOD_SCHEMA` symbol key carries the schema for runtime validation.
 */
-interface FlagSpec<
+interface ZodFlagDef<
 	Schema extends ZodSchemaLike = ZodSchemaLike,
-	Alias extends string | readonly string[] | undefined = string | readonly string[] | undefined
+	Alias extends string | readonly string[] | undefined = string | readonly string[] | undefined,
+	Type extends ValueType = ResolveZodValueType<Schema>
 > {
-	readonly kind: "flag";
-	readonly schema: Schema;
-	readonly alias: Alias;
+	readonly type: Type;
+	readonly description?: string;
+	readonly required?: true;
+	/**
+	* Non-optional so `ValidateFlagAliases` can extract narrow alias literals.
+	* When `Alias` is `undefined`, the runtime value is `undefined` (no alias).
+	*/
+	readonly alias: Alias extends string | readonly string[] ? Alias : undefined;
+	readonly [ZOD_SCHEMA]: Schema;
 }
-/** Allowed value shape for `flags` in `defineZodCommand()`. */
-type FlagShape = Record<string, ZodSchemaLike | FlagSpec>;
-/** Extract the schema from a flag shape value (plain schema or `flag()` wrapper). */
-type ExtractFlagSchema<V> = V extends FlagSpec<infer S> ? S : V extends ZodSchemaLike ? V : never;
-/** Infer validated flags object type from the flags shape. */
-type InferFlagsFromShape<F extends FlagShape> = { [K in keyof F] : InferSchemaOutput<ExtractFlagSchema<F[K]>> };
-/** Handler type for `defineZodCommand()` with validated/transformed context. */
-type ZodCommandRunHandler<
-	ArgsOut,
-	FlagsOut
-> = (context: ValidatedContext<ArgsOut, FlagsOut>) => void | Promise<void>;
-/** Infer args output type from command config args. */
-type InferArgsFromConfig<A> = A extends ArgSpecs ? InferArgsFromSpecs<A> : Record<string, never>;
-/** Infer flags output type from command config flags. */
-type InferFlagsFromConfig<F> = F extends FlagShape ? InferFlagsFromShape<F> : Record<string, never>;
+/** Options for `arg()`. */
+interface ArgOptions {
+	/** Collect remaining positionals into this arg as an array. */
+	readonly variadic?: true;
+}
+/** Options for `flag()`. */
+interface FlagOptions {
+	/** Short alias or array of aliases (e.g. `"v"` or `["v", "V"]`). */
+	readonly alias?: string | readonly string[];
+}
+/** Infer Zod output type from a schema. */
+type InferSchemaOutput<S> = S extends z.$ZodType ? z.output<S> : never;
+/** Output type for a single arg: variadic → `output[]`, scalar → `output`. */
+type InferValidatedArgValue<D> = D extends {
+	readonly [ZOD_SCHEMA]: infer S;
+	readonly variadic: true;
+} ? InferSchemaOutput<S>[] : D extends {
+	readonly [ZOD_SCHEMA]: infer S;
+} ? InferSchemaOutput<S> : never;
+/** Flattens an intersection of objects for readable inferred types. */
+type Simplify<T> = { [K in keyof T] : T[K] };
+/** Recursively maps args tuple to a named output object. */
+type InferValidatedArgsTuple<A extends readonly ArgDef[]> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? Head extends {
+	readonly name: infer N extends string;
+} ? { [K in N] : InferValidatedArgValue<Head> } & InferValidatedArgsTuple<Tail> : InferValidatedArgsTuple<Tail> : {};
 /**
-* Keys from `CommandDef` that `ZodCommandDef` redefines with different types.
-*
-* - `args` / `flags`: Zod schema-based definitions replace core's `ArgsDef`/`FlagsDef`
-* - `run`: receives `ValidatedContext` instead of raw `CommandContext`
-* - `preRun` / `postRun`: use raw `CommandContext` (no `NoInfer` wrapper)
-*
-* All remaining `CommandDef` keys (e.g. `meta`, `subCommands`) are inherited
-* automatically via `Omit`. If a new passthrough field is added to `CommandDef`,
-* it propagates here without changes. The compile-time key exhaustiveness
-* assertion in `command.test.ts` will fail, forcing a review.
+* Infer the validated args output type from an `ArgsDef` tuple
+* where each element carries a `[ZOD_SCHEMA]` brand.
 */
-type ZodOverriddenKeys = "args" | "flags" | "run" | "preRun" | "postRun";
+type InferValidatedArgs<A> = A extends readonly ArgDef[] ? Simplify<InferValidatedArgsTuple<A>> : Record<string, never>;
 /**
-* Config for `defineZodCommand()` using `arg()` + `flag()` schema-first DSL.
-*
-* Extends `CommandDef` (minus overridden keys) so passthrough fields like
-* `meta` and `subCommands` stay in sync automatically. If a new field is
-* added to `CommandDef`, the key exhaustiveness assertion in
-* `command.test.ts` fails at compile time, forcing a review.
+* Infer the validated flags output type from a `FlagsDef` record
+* where each value carries a `[ZOD_SCHEMA]` brand.
 */
-interface ZodCommandDef<
-	A extends ArgSpecs | undefined = undefined,
-	F extends FlagShape | undefined = undefined
-> extends Omit<CommandDef, ZodOverriddenKeys> {
-	/** Ordered positional args as `arg()` specs. */
-	readonly args?: A;
-	/** Named flags as plain schemas or `flag()` wrappers. */
-	readonly flags?: F;
-	/**
-	* Optional setup hook before schema validation runs.
-	*
-	* Receives raw parser output (`CommandContext`), not schema-transformed values.
-	*/
-	readonly preRun?: (context: CommandContext) => void | Promise<void>;
-	/** Main handler with validated/transformed args and flags. */
-	readonly run?: ZodCommandRunHandler<InferArgsFromConfig<A>, InferFlagsFromConfig<F>>;
-	/**
-	* Optional teardown hook after command execution.
-	*
-	* Receives raw parser output (`CommandContext`), not schema-transformed values.
-	*/
-	readonly postRun?: (context: CommandContext) => void | Promise<void>;
-}
+type InferValidatedFlags<F> = F extends Record<string, FlagDef> ? Simplify<{ [K in keyof F] : F[K] extends {
+	readonly [ZOD_SCHEMA]: infer S;
+} ? InferSchemaOutput<S> : never }> : Record<string, never>;
+/** Check that every arg in a tuple carries the `[ZOD_SCHEMA]` brand. */
+type AllArgsHaveSchema<A extends ArgsDef> = A extends readonly [infer Head, ...infer Tail extends readonly ArgDef[]] ? Head extends {
+	readonly [ZOD_SCHEMA]: unknown;
+} ? AllArgsHaveSchema<Tail> : false : true;
+/** Check that every flag in a record carries the `[ZOD_SCHEMA]` brand. */
+type AllFlagsHaveSchema<F extends FlagsDef> = string extends keyof F ? true : { [K in keyof F] : F[K] extends {
+	readonly [ZOD_SCHEMA]: unknown;
+} ? true : false }[keyof F] extends true ? true : false;
 /**
-* Define a Crust command where schemas are the source of truth.
-*
-* Positional args are declared with `arg(name, schema)` in an ordered array,
-* flags are declared as plain schemas or `flag(schema, meta)` wrappers.
-*
-* The factory generates Crust parser/help definitions and runs schema
-* validation after parsing but before user handler execution.
+* Resolves to `true` only when all args and flags carry schema metadata.
+* Used by `withZod` to enforce strict mode at compile time.
+*/
+type HasAllSchemas<
+	A extends ArgsDef,
+	F extends FlagsDef
+> = AllArgsHaveSchema<A> extends true ? AllFlagsHaveSchema<F> extends true ? true : false : false;
+/**
+* The validated handler type for `withZod()`.
 *
-* Compile-time validation (via intersection branding) catches:
-* - Variadic args that aren't in the last position
-* - Flag alias collisions (alias→name or alias→alias)
+* When all args/flags carry schema metadata, resolves to a typed handler
+* receiving `ValidatedContext`. Otherwise resolves to `never`, causing
+* a compile error at the call site.
 */
-declare function defineZodCommand<
-	const A extends readonly ArgSpec[] | undefined,
-	const F extends FlagShape | undefined
->(config: ZodCommandDef<A, F> & {
-	args?: A extends readonly object[] ? ValidateVariadicArgs<A> : A;
-	flags?: F extends Record<string, unknown> ? ValidateFlagAliases<F> : F;
-}): AnyCommand2;
+type WithZodHandler<
+	A extends ArgsDef,
+	F extends FlagsDef
+> = HasAllSchemas<A, F> extends true ? (context: ValidatedContext<InferValidatedArgs<A>, InferValidatedFlags<F>>) => void | Promise<void> : never;
 /**
-* Define a named positional argument schema for `defineZodCommand()`.
+* Define a named positional argument from a Zod schema.
+*
+* Returns a core `ArgDef` (accepted by `defineCommand`) enriched with hidden
+* schema metadata (via `[ZOD_SCHEMA]` symbol) for runtime validation by `withZod`.
 *
-* The `const Variadic` parameter preserves `{ variadic: true }` as a
-* literal in the return type, enabling compile-time variadic position
-* validation in `defineZodCommand()`.
+* CLI metadata (`type`, `required`, `description`, `variadic`) is derived
+* from the schema automatically — single source of truth.
 *
 * @param name - Positional arg name used in parser output and help text
-* @param schema - Zod schema
-* @param options - Optional CLI metadata (description, variadic)
+* @param schema - Zod schema (source of truth for type/optionality/description)
+* @param options - Optional CLI metadata (`variadic`)
+*
+* @example
+* ```ts
+* arg("port", z.number().int().min(1).describe("Port to listen on"))
+* arg("files", z.string(), { variadic: true })
+* ```
 */
 declare function arg<
 	Name extends string,
@@ -192,21 +191,64 @@ declare function arg<
 	const Variadic extends true | undefined = undefined
 >(name: Name, schema: Schema, options?: ArgOptions & {
 	variadic?: Variadic;
-}): ArgSpec<Name, Schema, Variadic>;
+}): ZodArgDef<Name, Schema, Variadic>;
 /**
-* Define a flag schema for `defineZodCommand()` with optional alias/description.
+* Define a flag from a Zod schema with optional alias.
+*
+* Returns a core `FlagDef` (accepted by `defineCommand`) enriched with hidden
+* schema metadata (via `[ZOD_SCHEMA]` symbol) for runtime validation by `withZod`.
+*
+* CLI metadata (`type`, `multiple`, `required`, `description`) is derived
+* from the schema automatically — single source of truth.
 *
-* The `const Alias` parameter preserves alias literals (e.g. `"v"` or
-* `readonly ["v", "V"]`) in the return type, enabling compile-time alias
-* collision detection in `defineZodCommand()`.
+* @param schema - Zod schema (source of truth for type/optionality/description)
+* @param options - Optional flag metadata (`alias`)
 *
-* @param schema - Zod schema
-* @param options - Optional flag metadata
+* @example
+* ```ts
+* flag(z.boolean().default(false).describe("Enable verbose logging"), { alias: "v" })
+* flag(z.enum(["json", "text"]).default("text"))
+* ```
 */
 declare function flag<
 	Schema extends ZodSchemaLike,
 	const Alias extends string | readonly string[] | undefined = undefined
 >(schema: Schema, options?: FlagOptions & {
 	alias?: Alias;
-}): FlagSpec<Schema, Alias>;
-export { flag, defineZodCommand, arg, ZodSchemaLike, ZodCommandRunHandler, ZodCommandDef, InferSchemaOutput, InferFlagsFromShape, InferFlagsFromConfig, InferArgsFromSpecs, InferArgsFromConfig, FlagSpec, FlagShape, FlagOptions, ArgSpecs, ArgSpec, ArgOptions };
+}): ZodFlagDef<Schema, Alias>;
+import { ArgsDef as ArgsDef2, CommandContext, FlagsDef as FlagsDef2 } from "@crustjs/core";
+/**
+* Create a validated `run` handler for `defineCommand`.
+*
+* Reads Zod schemas from the command's `arg()` / `flag()` definitions,
+* validates parsed CLI input against them, and calls `handler` with
+* the transformed, fully-typed result.
+*
+* **Strict mode**: all args and flags in the command must be created with
+* `arg()` / `flag()` from `@crustjs/validate/zod`. Plain core defs cause
+* a compile-time error (handler parameter becomes `never`).
+*
+* @param handler - Receives `ValidatedContext` with typed args/flags after validation
+* @returns A `run` function compatible with `defineCommand`
+*
+* @example
+* ```ts
+* import { defineCommand } from "@crustjs/core";
+* import { z } from "zod";
+* import { arg, flag, withZod } from "@crustjs/validate/zod";
+*
+* const serve = defineCommand({
+*   meta: { name: "serve" },
+*   args: [arg("port", z.number().min(1))],
+*   flags: { verbose: flag(z.boolean().default(false), { alias: "v" }) },
+*   run: withZod(({ args, flags }) => {
+*     // args.port: number, flags.verbose: boolean
+*   }),
+* });
+* ```
+*/
+declare function withZod<
+	A extends ArgsDef2 = ArgsDef2,
+	F extends FlagsDef2 = FlagsDef2
+>(handler: WithZodHandler<A, F>): (context: CommandContext<A, F>) => Promise<void>;
+export { withZod, flag, arg, ZodSchemaLike, ZodFlagDef, ZodArgDef, WithZodHandler, InferValidatedFlags, InferValidatedArgs, InferSchemaOutput, FlagOptions, ArgOptions };

package/dist/zod/index.js

@@ -1,92 +1,19 @@
 // @bun
 import {
-  buildArgDefinitions,
-  buildFlagDefinitions,
-  buildRunHandler,
+  buildValidatedRunner,
   normalizeIssues
-} from "../shared/chunk-zfhm7pmv.js";
+} from "../shared/chunk-p8pzhj6c.js";
 
-// src/zod/command.ts
-import { defineCommand } from "@crustjs/core";
-import { safeParseAsync } from "zod/v4/core";
+// src/zod/schema.ts
+import { CrustError } from "@crustjs/core";
 
-// src/zod/definitions.ts
-import { CrustError as CrustError2 } from "@crustjs/core";
+// src/zod/types.ts
+var ZOD_SCHEMA = Symbol.for("crustjs.validate.zod");
 
 // src/zod/schema.ts
-import { CrustError } from "@crustjs/core";
 function isZodSchema(value) {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  if (!("_zod" in value)) {
-    return false;
-  }
-  return true;
-}
-function arg(name, schema, options) {
-  if (!name.trim()) {
-    throw new CrustError("DEFINITION", "arg(): name is required and must be a non-empty string");
-  }
-  if (!isZodSchema(schema)) {
-    throw new CrustError("DEFINITION", `arg("${name}"): schema must be a Zod schema`);
-  }
-  return {
-    kind: "arg",
-    name,
-    schema,
-    variadic: options?.variadic
-  };
-}
-function flag(schema, options) {
-  if (!isZodSchema(schema)) {
-    throw new CrustError("DEFINITION", "flag(): schema must be a Zod schema");
-  }
-  return {
-    kind: "flag",
-    schema,
-    alias: options?.alias
-  };
-}
-function resolveDescription(schema) {
-  let current = schema;
-  const seen = new Set;
-  for (;; ) {
-    if (current === undefined || current === null || seen.has(current)) {
-      return;
-    }
-    seen.add(current);
-    if (typeof current !== "object") {
-      return;
-    }
-    if ("description" in current && typeof current.description === "string") {
-      return current.description;
-    }
-    const type = "type" in current ? current.type : undefined;
-    if (typeof type !== "string") {
-      return;
-    }
-    if (type === "pipe" || type === "transform") {
-      const input = current.in;
-      if (input !== undefined) {
-        current = input;
-        continue;
-      }
-      return;
-    }
-    if (type === "optional" || type === "nullable" || type === "default" || type === "prefault" || type === "nonoptional" || type === "readonly" || type === "catch") {
-      const unwrap = current.unwrap;
-      if (typeof unwrap === "function") {
-        current = unwrap();
-        continue;
-      }
-      return;
-    }
-    return;
-  }
+  return typeof value === "object" && value !== null && "_zod" in value;
 }
-
-// src/zod/definitions.ts
 function asRuntimeSchema(value) {
   if (typeof value !== "object" || value === null) {
     return;
@@ -102,7 +29,12 @@ function getSchemaType(schema) {
 }
 function unwrapInputSchema(schema) {
   let current = schema;
+  const seen = new Set;
   for (;; ) {
+    if (seen.has(current)) {
+      return current;
+    }
+    seen.add(current);
     const type = getSchemaType(current);
     const runtime = asRuntimeSchema(current);
     if (!type || !runtime) {
@@ -159,24 +91,29 @@ function resolveInputShape(schema, label) {
   if (getSchemaType(inputSchema) === "array") {
     const runtime = asRuntimeSchema(inputSchema);
     if (typeof runtime?.unwrap !== "function") {
-      throw new CrustError2("DEFINITION", `${label}: unable to inspect array element schema`);
+      throw new CrustError("DEFINITION", `${label}: unable to inspect array element schema`);
     }
     const elementSchema = unwrapInputSchema(runtime.unwrap());
     const primitive2 = resolvePrimitiveInputType(elementSchema);
     if (primitive2) {
       return { type: primitive2, multiple: true };
     }
-    throw new CrustError2("DEFINITION", `${label}: array element type must be string, number, or boolean`);
+    throw new CrustError("DEFINITION", `${label}: array element type must be string, number, or boolean`);
   }
   const primitive = resolvePrimitiveInputType(inputSchema);
   if (primitive) {
     return { type: primitive, multiple: false };
   }
-  throw new CrustError2("DEFINITION", `${label}: unsupported schema type for CLI parsing. Use string, number, boolean, enum/literal, or array of these.`);
+  throw new CrustError("DEFINITION", `${label}: unsupported schema type for CLI parsing. Use string, number, boolean, enum/literal, or array of these.`);
 }
 function isOptionalInputSchema(schema) {
   let current = schema;
+  const seen = new Set;
   for (;; ) {
+    if (seen.has(current)) {
+      return false;
+    }
+    seen.add(current);
     const type = getSchemaType(current);
     const runtime = asRuntimeSchema(current);
     if (!type || !runtime) {
@@ -202,21 +139,90 @@ function isOptionalInputSchema(schema) {
     return false;
   }
 }
-var zodAdapter = {
-  resolveInputShape,
-  isOptionalInputSchema,
-  resolveDescription,
-  commandLabel: "defineZodCommand",
-  arrayHint: "z.array(...)"
-};
-function argsToDefinitions(args) {
-  return buildArgDefinitions(args, zodAdapter);
+function resolveDescription(schema) {
+  let current = schema;
+  const seen = new Set;
+  for (;; ) {
+    if (current === undefined || current === null || seen.has(current)) {
+      return;
+    }
+    seen.add(current);
+    if (typeof current !== "object") {
+      return;
+    }
+    if ("description" in current && typeof current.description === "string") {
+      return current.description;
+    }
+    const type = "type" in current ? current.type : undefined;
+    if (typeof type !== "string") {
+      return;
+    }
+    if (type === "pipe" || type === "transform") {
+      const input = current.in;
+      if (input !== undefined) {
+        current = input;
+        continue;
+      }
+      return;
+    }
+    if (type === "optional" || type === "nullable" || type === "default" || type === "prefault" || type === "nonoptional" || type === "readonly" || type === "catch") {
+      const unwrap = current.unwrap;
+      if (typeof unwrap === "function") {
+        current = unwrap();
+        continue;
+      }
+      return;
+    }
+    return;
+  }
 }
-function flagsToDefinitions(flags) {
-  return buildFlagDefinitions(flags, zodAdapter);
+function arg(name, schema, options) {
+  if (!name.trim()) {
+    throw new CrustError("DEFINITION", "arg(): name is required and must be a non-empty string");
+  }
+  if (!isZodSchema(schema)) {
+    throw new CrustError("DEFINITION", `arg("${name}"): schema must be a Zod schema`);
+  }
+  const shape = resolveInputShape(schema, `arg "${name}"`);
+  const variadic = options?.variadic;
+  if (variadic && shape.multiple) {
+    throw new CrustError("DEFINITION", `arg "${name}": variadic args must use a scalar schema; do not wrap the schema in z.array(...)`);
+  }
+  if (!variadic && shape.multiple) {
+    throw new CrustError("DEFINITION", `arg "${name}": array schema requires { variadic: true }`);
+  }
+  const description = resolveDescription(schema);
+  const required = !isOptionalInputSchema(schema);
+  const def = {
+    name,
+    type: shape.type,
+    ...description !== undefined && { description },
+    variadic,
+    ...required && { required: true },
+    [ZOD_SCHEMA]: schema
+  };
+  return def;
 }
-
-// src/zod/command.ts
+function flag(schema, options) {
+  if (!isZodSchema(schema)) {
+    throw new CrustError("DEFINITION", "flag(): schema must be a Zod schema");
+  }
+  const shape = resolveInputShape(schema, "flag");
+  const required = !isOptionalInputSchema(schema);
+  const description = resolveDescription(schema);
+  const alias = options?.alias === undefined ? undefined : typeof options.alias === "string" ? options.alias : [...options.alias];
+  const def = {
+    type: shape.type,
+    ...shape.multiple && { multiple: true },
+    alias,
+    ...description !== undefined && { description },
+    ...required && { required: true },
+    [ZOD_SCHEMA]: schema
+  };
+  return def;
+}
+// src/zod/withZod.ts
+import { safeParseAsync } from "zod/v4/core";
 async function validateValue(schema, value, prefix) {
   const parseResult = await safeParseAsync(schema, value);
   if (parseResult.success) {
@@ -228,28 +234,11 @@ async function validateValue(schema, value, prefix) {
   }));
   return { ok: false, issues: normalizeIssues(prefixed) };
 }
-function defineZodCommand(config) {
-  const {
-    args: zodArgs,
-    flags: zodFlags,
-    run: userRun,
-    ...passthrough
-  } = config;
-  const argSpecs = zodArgs ?? [];
-  const generatedArgs = argsToDefinitions(argSpecs);
-  const generatedFlags = flagsToDefinitions(zodFlags);
-  const command = defineCommand({
-    ...passthrough,
-    ...generatedArgs.length > 0 && { args: generatedArgs },
-    ...Object.keys(generatedFlags).length > 0 && { flags: generatedFlags },
-    ...userRun && {
-      run: buildRunHandler(argSpecs, zodFlags, userRun, validateValue)
-    }
-  });
-  return command;
+function withZod(handler) {
+  return buildValidatedRunner(handler, validateValue, ZOD_SCHEMA, "withZod");
 }
 export {
+  withZod,
   flag,
-  defineZodCommand,
   arg
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/validate",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Validation helpers for the Crust CLI framework",
 	"type": "module",
 	"license": "MIT",