refactor(cli): cleanup Command.ts

packages/effect/src/unstable/cli/Argument.ts

@@ -3,8 +3,9 @@
  */
 import type * as Option from "../../data/Option.ts"
 import type * as Redacted from "../../data/Redacted.ts"
+import type * as Result from "../../data/Result.ts"
 import type * as Effect from "../../Effect.ts"
-import { dual } from "../../Function.ts"
+import { dual, type LazyArg } from "../../Function.ts"
 import type * as FileSystem from "../../platform/FileSystem.ts"
 import type * as Path from "../../platform/Path.ts"
 import type * as Schema from "../../schema/Schema.ts"
@@ -13,13 +14,26 @@ import type { Environment } from "./Command.ts"
 import * as Param from "./Param.ts"
 import type * as Primitive from "./Primitive.ts"
 
+// -------------------------------------------------------------------------------------
+// models
+// -------------------------------------------------------------------------------------
+
 /**
  * Represents a positional command-line argument.
  *
+ * Note: `boolean` is intentionally omitted from Argument constructors.
+ * Positional boolean arguments are ambiguous in CLI design since there's
+ * no flag name to negate (e.g., `--no-verbose`). Use Flag.boolean instead,
+ * or use Argument.choice with explicit "true"/"false" strings if needed.
+ *
  * @since 4.0.0
  * @category models
  */
-export interface Argument<A> extends Param.Param<typeof Param.Argument, A> {}
+export interface Argument<A> extends Param.Param<typeof Param.argumentKind, A> {}
+
+// -------------------------------------------------------------------------------------
+// constructors
+// -------------------------------------------------------------------------------------
 
 /**
  * Creates a positional string argument.
@@ -34,7 +48,7 @@ export interface Argument<A> extends Param.Param<typeof Param.Argument, A> {}
  * @since 4.0.0
  * @category constructors
  */
-export const string = (name: string): Argument<string> => Param.string(Param.Argument, name)
+export const string = (name: string): Argument<string> => Param.string(Param.argumentKind, name)
 
 /**
  * Creates a positional integer argument.
@@ -49,7 +63,7 @@ export const string = (name: string): Argument<string> => Param.string(Param.Arg
  * @since 4.0.0
  * @category constructors
  */
-export const integer = (name: string): Argument<number> => Param.integer(Param.Argument, name)
+export const integer = (name: string): Argument<number> => Param.integer(Param.argumentKind, name)
 
 /**
  * Creates a positional file path argument.
@@ -67,7 +81,7 @@ export const integer = (name: string): Argument<number> => Param.integer(Param.A
  */
 export const file = (name: string, options?: {
   readonly mustExist?: boolean | undefined
-}): Argument<string> => Param.file(Param.Argument, name, options)
+}): Argument<string> => Param.file(Param.argumentKind, name, options)
 
 /**
  * Creates a positional directory path argument.
@@ -84,7 +98,7 @@ export const file = (name: string, options?: {
  */
 export const directory = (name: string, options?: {
   readonly mustExist?: boolean | undefined
-}): Argument<string> => Param.directory(Param.Argument, name, options)
+}): Argument<string> => Param.directory(Param.argumentKind, name, options)
 
 /**
  * Creates a positional float argument.
@@ -99,7 +113,7 @@ export const directory = (name: string, options?: {
  * @since 4.0.0
  * @category constructors
  */
-export const float = (name: string): Argument<number> => Param.float(Param.Argument, name)
+export const float = (name: string): Argument<number> => Param.float(Param.argumentKind, name)
 
 /**
  * Creates a positional date argument.
@@ -114,7 +128,7 @@ export const float = (name: string): Argument<number> => Param.float(Param.Argum
  * @since 4.0.0
  * @category constructors
  */
-export const date = (name: string): Argument<Date> => Param.date(Param.Argument, name)
+export const date = (name: string): Argument<Date> => Param.date(Param.argumentKind, name)
 
 /**
  * Creates a positional choice argument.
@@ -132,7 +146,7 @@ export const date = (name: string): Argument<Date> => Param.date(Param.Argument,
 export const choice = <const Choices extends ReadonlyArray<string>>(
   name: string,
   choices: Choices
-): Argument<Choices[number]> => Param.choice(Param.Argument, name, choices)
+): Argument<Choices[number]> => Param.choice(Param.argumentKind, name, choices)
 
 /**
  * Creates a positional path argument.
@@ -150,7 +164,7 @@ export const choice = <const Choices extends ReadonlyArray<string>>(
 export const path = (name: string, options?: {
   pathType?: "file" | "directory" | "either"
   mustExist?: boolean
-}): Argument<string> => Param.path(Param.Argument, name, options)
+}): Argument<string> => Param.path(Param.argumentKind, name, options)
 
 /**
  * Creates a positional redacted argument that obscures its value.
@@ -165,7 +179,7 @@ export const path = (name: string, options?: {
  * @since 4.0.0
  * @category constructors
  */
-export const redacted = (name: string): Argument<Redacted.Redacted<string>> => Param.redacted(Param.Argument, name)
+export const redacted = (name: string): Argument<Redacted.Redacted<string>> => Param.redacted(Param.argumentKind, name)
 
 /**
  * Creates a positional argument that reads file content as a string.
@@ -180,7 +194,7 @@ export const redacted = (name: string): Argument<Redacted.Redacted<string>> => P
  * @since 4.0.0
  * @category constructors
  */
-export const fileText = (name: string): Argument<string> => Param.fileString(Param.Argument, name)
+export const fileText = (name: string): Argument<string> => Param.fileText(Param.argumentKind, name)
 
 /**
  * Creates a positional argument that reads and validates file content using a schema.
@@ -198,7 +212,7 @@ export const fileText = (name: string): Argument<string> => Param.fileString(Par
 export const fileParse = (
   name: string,
   options?: Primitive.FileParseOptions | undefined
-): Argument<unknown> => Param.fileParse(Param.Argument, name, options)
+): Argument<unknown> => Param.fileParse(Param.argumentKind, name, options)
 
 /**
  * Creates a positional argument that reads and validates file content using a schema.
@@ -225,7 +239,7 @@ export const fileSchema = <A>(
   name: string,
   schema: Schema.Codec<A, string>,
   options?: Primitive.FileSchemaOptions | undefined
-): Argument<A> => Param.fileSchema(Param.Argument, name, schema, options)
+): Argument<A> => Param.fileSchema(Param.argumentKind, name, schema, options)
 
 /**
  * Creates an empty sentinel argument that always fails to parse.
@@ -241,7 +255,11 @@ export const fileSchema = <A>(
  * @since 4.0.0
  * @category constructors
  */
-export const none: Argument<never> = Param.none(Param.Argument)
+export const none: Argument<never> = Param.none(Param.argumentKind)
+
+// -------------------------------------------------------------------------------------
+// combinators
+// -------------------------------------------------------------------------------------
 
 /**
  * Makes a positional argument optional.
@@ -409,21 +427,6 @@ export const mapTryCatch: {
   onError: (error: unknown) => string
 ) => Param.mapTryCatch(self, f, onError))
 
-/**
- * Creates a variadic argument that accepts multiple values (same as variadic).
- *
- * @example
- * ```ts
- * import { Argument } from "effect/unstable/cli"
- *
- * const files = Argument.string("files").pipe(Argument.repeated)
- * ```
- *
- * @since 4.0.0
- * @category combinators
- */
-export const repeated = <A>(arg: Argument<A>): Argument<ReadonlyArray<A>> => Param.repeated(arg)
-
 /**
  * Creates a variadic argument that requires at least n values.
  *
@@ -498,3 +501,150 @@ export const withSchema: {
   <A, B>(schema: Schema.Codec<B, A>): (self: Argument<A>) => Argument<B>
   <A, B>(self: Argument<A>, schema: Schema.Codec<B, A>): Argument<B>
 } = dual(2, <A, B>(self: Argument<A>, schema: Schema.Codec<B, A>) => Param.withSchema(self, schema))
+
+/**
+ * Creates a positional choice argument with custom value mapping.
+ *
+ * @example
+ * ```ts
+ * import { Argument } from "effect/unstable/cli"
+ *
+ * const logLevel = Argument.choiceWithValue("level", [
+ *   ["debug", 0],
+ *   ["info", 1],
+ *   ["warn", 2],
+ *   ["error", 3]
+ * ])
+ * ```
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const choiceWithValue = <const Choices extends ReadonlyArray<readonly [string, any]>>(
+  name: string,
+  choices: Choices
+): Argument<Choices[number][1]> => Param.choiceWithValue(Param.argumentKind, name, choices)
+
+// -------------------------------------------------------------------------------------
+// metadata
+// -------------------------------------------------------------------------------------
+
+/**
+ * Sets a custom metavar (placeholder name) for the argument in help documentation.
+ *
+ * The metavar is displayed in usage text to indicate what value the user should provide.
+ * For example, `<FILE>` shows `FILE` as the metavar.
+ *
+ * @example
+ * ```ts
+ * import { Argument } from "effect/unstable/cli"
+ *
+ * const port = Argument.integer("port").pipe(
+ *   Argument.withMetavar("PORT")
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category metadata
+ */
+export const withMetavar: {
+  <A>(metavar: string): (self: Argument<A>) => Argument<A>
+  <A>(self: Argument<A>, metavar: string): Argument<A>
+} = dual(2, <A>(self: Argument<A>, metavar: string) => Param.withMetavar(self, metavar))
+
+/**
+ * Filters parsed values, failing with a custom error message if the predicate returns false.
+ *
+ * @example
+ * ```ts
+ * import { Argument } from "effect/unstable/cli"
+ *
+ * const positiveInt = Argument.integer("count").pipe(
+ *   Argument.filter(
+ *     n => n > 0,
+ *     n => `Expected positive integer, got ${n}`
+ *   )
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const filter: {
+  <A>(predicate: (a: A) => boolean, onFalse: (a: A) => string): (self: Argument<A>) => Argument<A>
+  <A>(self: Argument<A>, predicate: (a: A) => boolean, onFalse: (a: A) => string): Argument<A>
+} = dual(3, <A>(
+  self: Argument<A>,
+  predicate: (a: A) => boolean,
+  onFalse: (a: A) => string
+) => Param.filter(self, predicate, onFalse))
+
+/**
+ * Filters and transforms parsed values, failing with a custom error message
+ * if the filter function returns None.
+ *
+ * @example
+ * ```ts
+ * import { Option } from "effect/data"
+ * import { Argument } from "effect/unstable/cli"
+ *
+ * const positiveInt = Argument.integer("count").pipe(
+ *   Argument.filterMap(
+ *     (n) => n > 0 ? Option.some(n) : Option.none(),
+ *     (n) => `Expected positive integer, got ${n}`
+ *   )
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const filterMap: {
+  <A, B>(f: (a: A) => Option.Option<B>, onNone: (a: A) => string): (self: Argument<A>) => Argument<B>
+  <A, B>(self: Argument<A>, f: (a: A) => Option.Option<B>, onNone: (a: A) => string): Argument<B>
+} = dual(3, <A, B>(
+  self: Argument<A>,
+  f: (a: A) => Option.Option<B>,
+  onNone: (a: A) => string
+) => Param.filterMap(self, f, onNone))
+
+/**
+ * Provides a fallback argument to use if this argument fails to parse.
+ *
+ * @example
+ * ```ts
+ * import { Argument } from "effect/unstable/cli"
+ *
+ * const value = Argument.integer("value").pipe(
+ *   Argument.orElse(() => Argument.string("value"))
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const orElse: {
+  <B>(that: LazyArg<Argument<B>>): <A>(self: Argument<A>) => Argument<A | B>
+  <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>): Argument<A | B>
+} = dual(2, <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>) => Param.orElse(self, that))
+
+/**
+ * Provides a fallback argument, wrapping results in Result to distinguish which succeeded.
+ *
+ * @example
+ * ```ts
+ * import { Argument } from "effect/unstable/cli"
+ *
+ * const source = Argument.file("source").pipe(
+ *   Argument.orElseResult(() => Argument.string("url"))
+ * )
+ * // Returns Result<string, string>
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const orElseResult: {
+  <B>(that: LazyArg<Argument<B>>): <A>(self: Argument<A>) => Argument<Result.Result<A, B>>
+  <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>): Argument<Result.Result<A, B>>
+} = dual(2, <A, B>(self: Argument<A>, that: LazyArg<Argument<B>>) => Param.orElseResult(self, that))