@crustjs/validate 0.0.1 → 0.0.2

package/README.md

@@ -4,13 +4,18 @@
 
 Validation support for the [Crust](https://crustjs.com) CLI framework.
 
+Define args and flags once using schema-first `arg()` / `flag()` helpers, then
+use `withZod()` or `withEffect()` as `run` middleware for `defineCommand`. CLI
+metadata (type, required, description, variadic) is derived from the schema
+automatically — single source of truth.
+
 ## Entry points
 
-| Entry | Import | Purpose |
-| --- | --- | --- |
-| Shared contracts | `@crustjs/validate` | Provider-agnostic types (`ValidatedContext`, `ValidationIssue`) |
-| Effect provider | `@crustjs/validate/effect` | Schema-first command API (`defineEffectCommand`, `arg`, `flag`) |
-| Zod provider | `@crustjs/validate/zod` | Schema-first command API (`defineZodCommand`, `arg`, `flag`) |
+| Entry            | Import                       | Purpose                                                        |
+| ---------------- | ---------------------------- | -------------------------------------------------------------- |
+| Shared contracts | `@crustjs/validate`          | Provider-agnostic types (`ValidatedContext`, `ValidationIssue`) |
+| Effect provider  | `@crustjs/validate/effect`   | `arg`, `flag`, `withEffect`                                    |
+| Zod provider     | `@crustjs/validate/zod`      | `arg`, `flag`, `withZod`                                       |
 
 ## Install
 
@@ -22,105 +27,98 @@ bun add zod
 bun add effect
 ```
 
-## Effect schema-first mode (`defineEffectCommand`)
-
-Define schemas once and let Crust `args`/`flags` definitions be generated automatically.
+## Zod provider
 
 ```ts
-import { runMain } from "@crustjs/core";
-import {
-	arg,
-	defineEffectCommand,
-	flag,
-} from "@crustjs/validate/effect";
-import * as Schema from "effect/Schema";
+import { defineCommand, runMain } from "@crustjs/core";
+import { arg, flag, withZod } from "@crustjs/validate/zod";
+import { z } from "zod";
 
-const serve = defineEffectCommand({
+const serve = defineCommand({
 	meta: { name: "serve", description: "Start dev server" },
 	args: [
-		arg("port", Schema.Number.annotations({ description: "Port to listen on" })),
-		arg("host", Schema.UndefinedOr(
-			Schema.String.annotations({ description: "Host to bind" }),
-		)),
+		arg("port", z.number().int().min(1).max(65535).describe("Port to listen on")),
+		arg("host", z.string().default("localhost").describe("Host to bind")),
 	],
 	flags: {
 		verbose: flag(
-			Schema.Boolean.annotations({ description: "Enable verbose logging" }),
+			z.boolean().default(false).describe("Enable verbose logging"),
 			{ alias: "v" },
 		),
 		format: flag(
-			Schema.Literal("json", "text").annotations({ description: "Output format" }),
+			z.enum(["json", "text"]).default("text").describe("Output format"),
 			{ alias: "f" },
 		),
 	},
-	run({ args, flags, input }) {
-		// args: { port: number; host: string | undefined }
+	run: withZod(({ args, flags, input }) => {
+		// args: { port: number; host: string }
 		// flags: { verbose: boolean; format: "json" | "text" }
 		console.log(args.port, args.host, flags.verbose, flags.format);
 		console.log(input.args, input.flags); // original parser output
-	},
+	}),
 });
 
 runMain(serve);
 ```
 
-### Effect schema support
-
-- Primitive schemas: `Schema.String`, `Schema.Number`, `Schema.Boolean`
-- Enums/literals: `Schema.Enums(...)`, `Schema.Literal(...)`
-- Arrays: `Schema.Array(...)` and array-like tuple rest schemas
-- Wrappers: refinement/transformation/suspend wrappers are unwrapped for parser-shape analysis
-- Descriptions: `schema.annotations({ description: "..." })` — auto-extracted through wrappers
-
-For optional args/flags, use schemas whose encoded input allows `undefined` (for example `Schema.UndefinedOr(Schema.String)`).
+### Zod schema support
 
-## Zod schema-first mode (`defineZodCommand`)
+- Primitive schemas: `z.string()`, `z.number()`, `z.boolean()`
+- Enums/literals: `z.enum(...)`, `z.literal(...)`
+- Arrays: `z.array(...)` for variadic args or flags with `multiple: true`
+- Wrappers: `.optional()`, `.default()`, `.nullable()`, `.transform()`, `.pipe()`
+- Descriptions: `.describe("...")` — auto-extracted through wrappers
 
-Define schemas once and let Crust `args`/`flags` definitions be generated automatically.
+## Effect provider
 
 ```ts
-import { runMain } from "@crustjs/core";
-import { arg, defineZodCommand, flag } from "@crustjs/validate/zod";
-import { z } from "zod";
+import { defineCommand, runMain } from "@crustjs/core";
+import { arg, flag, withEffect } from "@crustjs/validate/effect";
+import * as Schema from "effect/Schema";
 
-const serve = defineZodCommand({
+const serve = defineCommand({
 	meta: { name: "serve", description: "Start dev server" },
 	args: [
-		arg("port", z.number().int().min(1).max(65535).describe("Port to listen on")),
-		arg("host", z.string().default("localhost").describe("Host to bind")),
+		arg("port", Schema.Number.annotations({ description: "Port to listen on" })),
+		arg("host", Schema.UndefinedOr(
+			Schema.String.annotations({ description: "Host to bind" }),
+		)),
 	],
 	flags: {
 		verbose: flag(
-			z.boolean().default(false).describe("Enable verbose logging"),
+			Schema.Boolean.annotations({ description: "Enable verbose logging" }),
 			{ alias: "v" },
 		),
 		format: flag(
-			z.enum(["json", "text"]).default("text").describe("Output format"),
+			Schema.Literal("json", "text").annotations({ description: "Output format" }),
 			{ alias: "f" },
 		),
 	},
-	run({ args, flags, input }) {
-		// args: { port: number; host: string }
+	run: withEffect(({ args, flags, input }) => {
+		// args: { port: number; host: string | undefined }
 		// flags: { verbose: boolean; format: "json" | "text" }
 		console.log(args.port, args.host, flags.verbose, flags.format);
 		console.log(input.args, input.flags); // original parser output
-	},
+	}),
 });
 
 runMain(serve);
 ```
 
-### Zod schema support
+### Effect schema support
 
-- Primitive schemas: `z.string()`, `z.number()`, `z.boolean()`
-- Enums/literals: `z.enum(...)`, `z.literal(...)`
-- Arrays: `z.array(...)` for flags with `multiple: true`
-- Wrappers: `.optional()`, `.default()`, `.nullable()`, `.transform()`, `.pipe()`
-- Descriptions: `.describe("...")` — auto-extracted through wrappers
+- Primitive schemas: `Schema.String`, `Schema.Number`, `Schema.Boolean`
+- Enums/literals: `Schema.Enums(...)`, `Schema.Literal(...)`
+- Arrays: `Schema.Array(...)` and array-like tuple rest schemas
+- Wrappers: refinement/transformation/suspend wrappers are unwrapped for parser-shape analysis
+- Descriptions: `schema.annotations({ description: "..." })` — auto-extracted through wrappers
+
+For optional args/flags, use schemas whose encoded input allows `undefined` (for example `Schema.UndefinedOr(Schema.String)`).
 
-### Positional args
+## Positional args
+
+Use ordered `arg(name, schema, options?)` entries.
 
-- Use ordered `arg(name, schema, options?)` entries.
 - Optional/default schemas become optional CLI args (`[name]`).
 - Variadic args use `{ variadic: true }` and must be last.
 
@@ -131,20 +129,30 @@ args: [
 ];
 ```
 
-### Flags
+## Flags
+
+Use `flag(schema, options?)` to define flags.
 
-- Pass plain Zod schemas or `flag(schema, options?)` wrappers.
 - Use `flag(..., { alias })` for short aliases.
-- Use `.describe("...")` on the schema for help text.
+- Use `.describe("...")` (Zod) or `.annotations({ description: "..." })` (Effect) for help text.
 
 ```ts
 flags: {
-	debug: z.boolean().default(false).describe("Enable debug mode"),
+	debug: flag(z.boolean().default(false).describe("Enable debug mode")),
 	outDir: flag(z.string().default("dist").describe("Output directory"), { alias: "o" }),
 };
 ```
 
-### Help plugin compatibility
+## Strict mode
+
+When using `withZod()` or `withEffect()`, **all** args and flags must be created
+with the matching provider's `arg()` / `flag()` helpers. Mixing plain core
+definitions causes a compile-time error (handler parameter becomes `never`).
+
+Plugin-injected flags (e.g. `--help` from `helpPlugin`) are silently skipped at
+runtime — they don't need schema metadata.
+
+## Help plugin compatibility
 
 Generated definitions are compatible with `helpPlugin`.
 
@@ -155,14 +163,6 @@ import { helpPlugin } from "@crustjs/plugins";
 runMain(serve, { plugins: [helpPlugin()] });
 ```
 
-### Lifecycle hooks
-
-`defineZodCommand` supports `preRun` and `postRun` passthrough hooks.
-
-- Both hooks receive the core `CommandContext` (raw parser output).
-- Schema validation/transforms run inside `run`, so validated values are only
-  available in the schema-first `run` handler.
-
 ## Validation errors
 
 Failures throw `CrustError("VALIDATION")`.
@@ -173,6 +173,6 @@ Failures throw `CrustError("VALIDATION")`.
 ## v1 constraints
 
 - Args and flags only (no env/config validation).
-- Effect mode currently supports context-free schemas only (`R = never`).
+- Effect mode supports context-free, synchronous schemas only (`R = never`).
 - Zod mode requires Zod 4+.
 - No automatic schema inheritance across subcommands.

package/dist/effect/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 schema from "effect/Schema";
 import { AnyCommand } from "@crustjs/core";
 /**
@@ -30,104 +29,147 @@ interface ValidatedContext<
 	};
 }
 /**
-* An Effect schema used by the Effect entrypoint.
+* Unique symbol used to attach an Effect schema to a core `ArgDef` or `FlagDef`.
+*
+* Survives `{ ...def }` spread in `defineCommand` and `Object.freeze`,
+* making the schema available at runtime via `def[EFFECT_SCHEMA]`.
+*/
+declare const EFFECT_SCHEMA: unique symbol;
+type EFFECT_SCHEMA = typeof EFFECT_SCHEMA;
+/**
+* An Effect schema used by the validate/effect entrypoint.
 *
 * v1 intentionally supports context-free schemas only (`R = never`).
-* Schemas must also be **synchronous** — async combinators such as
-* `Schema.filterEffect` or async `Schema.transformOrFail` will cause
-* `Effect.runSync` to throw at runtime.
 */
 type EffectSchemaLike = schema.Schema.AnyNoContext;
-/** Infer output type from an Effect schema. */
-type InferSchemaOutput<S> = S extends schema.Schema<infer A, infer _I, infer _R> ? A : never;
-/** Optional metadata for a positional argument declared with `arg()`. */
-interface ArgOptions {
-	/** Collect remaining positionals into this arg as an array. */
-	readonly variadic?: true;
-}
-/** A single positional argument spec produced by `arg()`. */
-interface ArgSpec<
+/** CLI value type literals. */
+type ValueType = "string" | "number" | "boolean";
+/**
+* Resolve CLI ValueType from an Effect schema's encoded (input) type.
+*
+* Uses `Schema.Encoded<S>` to determine the CLI input type. If the encoded
+* type is a primitive (possibly `| undefined`), resolves to the matching
+* ValueType literal. Falls back to `ValueType` (the union) for complex types.
+*/
+type StripUndefined<T> = Exclude<T, undefined>;
+type PrimitiveToValueType<T> = [T] extends [string] ? "string" : [T] extends [number] ? "number" : [T] extends [boolean] ? "boolean" : ValueType;
+type ResolveEffectValueType<S> = S extends schema.Schema<infer _A, infer I, infer _R> ? PrimitiveToValueType<StripUndefined<I>> : ValueType;
+/**
+* An `ArgDef` enriched with a hidden Effect schema.
+*
+* The `Type` parameter is resolved from the schema's encoded type.
+*
+* The `EFFECT_SCHEMA` symbol key carries the schema for runtime validation.
+*/
+interface EffectArgDef<
 	Name extends string = string,
 	SchemaType extends EffectSchemaLike = EffectSchemaLike,
-	Variadic extends true | undefined = true | undefined
+	Variadic extends true | undefined = true | undefined,
+	Type extends ValueType = ResolveEffectValueType<SchemaType>
 > {
-	readonly kind: "arg";
 	readonly name: Name;
-	readonly schema: SchemaType;
+	readonly type: Type;
+	readonly description?: string;
+	readonly required?: true;
+	/** Non-optional so `ValidateVariadicArgs` can match `{ variadic: true }`. */
 	readonly variadic: Variadic;
+	readonly [EFFECT_SCHEMA]: SchemaType;
 }
-/** 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[];
-}
-/** A named flag schema wrapper produced by `flag()`. */
-interface FlagSpec<
+/**
+* A `FlagDef` enriched with a hidden Effect schema.
+*
+* The `EFFECT_SCHEMA` symbol key carries the schema for runtime validation.
+*/
+interface EffectFlagDef<
 	SchemaType extends EffectSchemaLike = EffectSchemaLike,
-	Alias extends string | readonly string[] | undefined = string | readonly string[] | undefined
+	Alias extends string | readonly string[] | undefined = string | readonly string[] | undefined,
+	Type extends ValueType = ResolveEffectValueType<SchemaType>
 > {
-	readonly kind: "flag";
-	readonly schema: SchemaType;
-	readonly alias: Alias;
+	readonly type: Type;
+	readonly description?: string;
+	readonly required?: true;
+	/** Non-optional so `ValidateFlagAliases` can extract narrow alias literals. */
+	readonly alias: Alias extends string | readonly string[] ? Alias : undefined;
+	readonly [EFFECT_SCHEMA]: SchemaType;
 }
-/** Allowed value shape for `flags` in `defineEffectCommand()`. */
-type FlagShape = Record<string, EffectSchemaLike | 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 EffectSchemaLike ? 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 `defineEffectCommand()` with validated/transformed context. */
-type EffectCommandRunHandler<
-	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>;
-type EffectOverriddenKeys = "args" | "flags" | "run" | "preRun" | "postRun";
-/** Config for `defineEffectCommand()` using `arg()` + `flag()` schema-first DSL. */
-interface EffectCommandDef<
-	A extends ArgSpecs | undefined = undefined,
-	F extends FlagShape | undefined = undefined
-> extends Omit<CommandDef, EffectOverriddenKeys> {
-	/** 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. */
-	readonly preRun?: (context: CommandContext) => void | Promise<void>;
-	/** Main handler with validated/transformed args and flags. */
-	readonly run?: EffectCommandRunHandler<InferArgsFromConfig<A>, InferFlagsFromConfig<F>>;
-	/** Optional teardown hook after command execution. */
-	readonly postRun?: (context: CommandContext) => void | Promise<void>;
+/** 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 Effect output type from a schema. */
+type InferSchemaOutput<S> = S extends schema.Schema<infer A, infer _I, infer _R> ? A : never;
+/** Output type for a single arg: variadic → `output[]`, scalar → `output`. */
+type InferValidatedArgValue<D> = D extends {
+	readonly [EFFECT_SCHEMA]: infer S;
+	readonly variadic: true;
+} ? InferSchemaOutput<S>[] : D extends {
+	readonly [EFFECT_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> : {};
 /**
-* Define a Crust command where Effect schemas are the source of truth.
-*
-* Only context-free (`R = never`), synchronous schemas are supported.
-* Async combinators like `Schema.filterEffect` or async `Schema.transformOrFail`
-* will throw at runtime.
+* Infer the validated args output type from an `ArgsDef` tuple
+* where each element carries an `[EFFECT_SCHEMA]` brand.
 */
-declare function defineEffectCommand<
-	const A extends readonly ArgSpec[] | undefined,
-	const F extends FlagShape | undefined
->(config: EffectCommandDef<A, F> & {
-	args?: A extends readonly object[] ? ValidateVariadicArgs<A> : A;
-	flags?: F extends Record<string, unknown> ? ValidateFlagAliases<F> : F;
-}): AnyCommand2;
+type InferValidatedArgs<A> = A extends readonly ArgDef[] ? Simplify<InferValidatedArgsTuple<A>> : Record<string, never>;
 /**
-* Define a named positional argument schema for `defineEffectCommand()`.
+* Infer the validated flags output type from a `FlagsDef` record
+* where each value carries an `[EFFECT_SCHEMA]` brand.
+*/
+type InferValidatedFlags<F> = F extends Record<string, FlagDef> ? Simplify<{ [K in keyof F] : F[K] extends {
+	readonly [EFFECT_SCHEMA]: infer S;
+} ? InferSchemaOutput<S> : never }> : Record<string, never>;
+/** Check that every arg in a tuple carries the `[EFFECT_SCHEMA]` brand. */
+type AllArgsHaveSchema<A extends ArgsDef> = A extends readonly [infer Head, ...infer Tail extends readonly ArgDef[]] ? Head extends {
+	readonly [EFFECT_SCHEMA]: unknown;
+} ? AllArgsHaveSchema<Tail> : false : true;
+/** Check that every flag in a record carries the `[EFFECT_SCHEMA]` brand. */
+type AllFlagsHaveSchema<F extends FlagsDef> = string extends keyof F ? true : { [K in keyof F] : F[K] extends {
+	readonly [EFFECT_SCHEMA]: unknown;
+} ? true : false }[keyof F] extends true ? true : false;
+/**
+* Resolves to `true` only when all args and flags carry schema metadata.
+* Used by `withEffect` 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 `withEffect()`.
+*/
+type WithEffectHandler<
+	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 from an Effect schema.
+*
+* Returns a core `ArgDef` (accepted by `defineCommand`) enriched with hidden
+* schema metadata (via `[EFFECT_SCHEMA]` symbol) for runtime validation by `withEffect`.
+*
+* 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 - Effect schema (source of truth for type/optionality/description)
+* @param options - Optional CLI metadata (`variadic`)
+*
+* @example
+* ```ts
+* arg("port", Schema.Number.annotations({ description: "Port to listen on" }))
+* arg("files", Schema.String, { variadic: true })
+* ```
 */
 declare function arg<
 	Name extends string,
@@ -135,14 +177,68 @@ declare function arg<
 	const Variadic extends true | undefined = undefined
 >(name: Name, schema: SchemaType, options?: ArgOptions & {
 	variadic?: Variadic;
-}): ArgSpec<Name, SchemaType, Variadic>;
+}): EffectArgDef<Name, SchemaType, Variadic>;
 /**
-* Define a flag schema for `defineEffectCommand()` with optional alias metadata.
+* Define a flag from an Effect schema with optional alias.
+*
+* Returns a core `FlagDef` (accepted by `defineCommand`) enriched with hidden
+* schema metadata (via `[EFFECT_SCHEMA]` symbol) for runtime validation by `withEffect`.
+*
+* CLI metadata (`type`, `multiple`, `required`, `description`) is derived
+* from the schema automatically — single source of truth.
+*
+* @param schema - Effect schema (source of truth for type/optionality/description)
+* @param options - Optional flag metadata (`alias`)
+*
+* @example
+* ```ts
+* flag(Schema.Boolean.annotations({ description: "Enable verbose logging" }), { alias: "v" })
+* flag(Schema.UndefinedOr(Schema.Number))
+* ```
 */
 declare function flag<
 	SchemaType extends EffectSchemaLike,
 	const Alias extends string | readonly string[] | undefined = undefined
 >(schema: SchemaType, options?: FlagOptions & {
 	alias?: Alias;
-}): FlagSpec<SchemaType, Alias>;
-export { flag, defineEffectCommand, arg, InferSchemaOutput, InferFlagsFromShape, InferFlagsFromConfig, InferArgsFromSpecs, InferArgsFromConfig, FlagSpec, FlagShape, FlagOptions, EffectSchemaLike, EffectCommandRunHandler, EffectCommandDef, ArgSpecs, ArgSpec, ArgOptions };
+}): EffectFlagDef<SchemaType, Alias>;
+import { ArgsDef as ArgsDef2, CommandContext, FlagsDef as FlagsDef2 } from "@crustjs/core";
+/**
+* Create a validated `run` handler for `defineCommand`.
+*
+* Reads Effect 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/effect`. Plain core defs cause
+* a compile-time error (handler parameter becomes `never`).
+*
+* **Sync only**: only context-free (`R = never`), synchronous schemas are
+* supported. Async combinators like `Schema.filterEffect` or async
+* `Schema.transformOrFail` will throw at runtime.
+*
+* @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 * as Schema from "effect/Schema";
+* import { arg, flag, withEffect } from "@crustjs/validate/effect";
+*
+* const serve = defineCommand({
+*   meta: { name: "serve" },
+*   args: [arg("port", Schema.Number)],
+*   flags: { verbose: flag(Schema.Boolean, { alias: "v" }) },
+*   run: withEffect(({ args, flags }) => {
+*     // args.port: number, flags.verbose: boolean
+*   }),
+* });
+* ```
+*/
+declare function withEffect<
+	A extends ArgsDef2 = ArgsDef2,
+	F extends FlagsDef2 = FlagsDef2
+>(handler: WithEffectHandler<A, F>): (context: CommandContext<A, F>) => Promise<void>;
+export { withEffect, flag, arg, WithEffectHandler, InferValidatedFlags, InferValidatedArgs, InferSchemaOutput, FlagOptions, EffectSchemaLike, EffectFlagDef, EffectArgDef, ArgOptions };