effect 4.0.0-beta.4 → 4.0.0-beta.40

package/src/unstable/cli/Completions.ts

@@ -0,0 +1,36 @@
+/**
+ * @since 4.0.0
+ */
+import * as Bash from "./internal/completions/bash.ts"
+import type * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
+import * as Fish from "./internal/completions/fish.ts"
+import * as Zsh from "./internal/completions/zsh.ts"
+
+/**
+ * Shell type used to generate completion scripts.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export type Shell = "bash" | "zsh" | "fish"
+
+/**
+ * Generates a shell completion script for a command descriptor.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const generate = (
+  executableName: string,
+  shell: Shell,
+  descriptor: CommandDescriptor.CommandDescriptor
+): string => {
+  switch (shell) {
+    case "bash":
+      return Bash.generate(executableName, descriptor)
+    case "zsh":
+      return Zsh.generate(executableName, descriptor)
+    case "fish":
+      return Fish.generate(executableName, descriptor)
+  }
+}

package/src/unstable/cli/Flag.ts

@@ -304,7 +304,7 @@ export const fileParse = (
  * const ConfigSchema = Schema.Struct({
  *   port: Schema.Number,
  *   host: Schema.String
- * }).pipe(Schema.fromJsonString)
+ * })
  *
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
  * ```
@@ -314,7 +314,7 @@ export const fileParse = (
  */
 export const fileSchema = <A>(
   name: string,
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: Primitive.FileSchemaOptions | undefined
 ): Flag<A> => Param.fileSchema(Param.flagKind, name, schema, options)
 

package/src/unstable/cli/GlobalFlag.ts

@@ -0,0 +1,242 @@
+/**
+ * @since 4.0.0
+ */
+
+import * as Console from "../../Console.ts"
+import * as Effect from "../../Effect.ts"
+import type { LogLevel as LogLevelType } from "../../LogLevel.ts"
+import * as Option from "../../Option.ts"
+import * as ServiceMap from "../../ServiceMap.ts"
+import * as CliOutput from "./CliOutput.ts"
+import type * as Command from "./Command.ts"
+import * as Completions_ from "./Completions.ts"
+import * as Flag from "./Flag.ts"
+import * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
+import * as HelpInternal from "./internal/help.ts"
+
+/* ========================================================================== */
+/* Types                                                                      */
+/* ========================================================================== */
+
+/**
+ * Context passed to action handlers.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface HandlerContext {
+  readonly command: Command.Command<any, unknown, any, unknown, unknown>
+  readonly commandPath: ReadonlyArray<string>
+  readonly version: string
+}
+
+/**
+ * Action flag: side effect + exit (--help, --version, --completions).
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface Action<A> {
+  readonly _tag: "Action"
+  readonly flag: Flag.Flag<A>
+  readonly run: (
+    value: A,
+    context: HandlerContext
+  ) => Effect.Effect<void>
+}
+
+/**
+ * Setting flag: configure command handler's environment (--log-level, --config).
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface Setting<Id extends string, A> extends ServiceMap.Service<Setting.Identifier<Id>, A> {
+  readonly _tag: "Setting"
+  readonly id: Id
+  readonly flag: Flag.Flag<A>
+}
+
+/**
+ * @since 4.0.0
+ */
+export declare namespace Setting {
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export type Identifier<Id extends string> = `effect/unstable/cli/GlobalFlag/${Id}`
+}
+
+/**
+ * Global flag discriminated union.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export type GlobalFlag<A> = Action<A> | Setting<any, A>
+
+/* ========================================================================== */
+/* Constructors                                                               */
+/* ========================================================================== */
+
+/**
+ * Creates an Action flag that performs a side effect and exits.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const action = <A>(options: {
+  readonly flag: Flag.Flag<A>
+  readonly run: (
+    value: A,
+    context: HandlerContext
+  ) => Effect.Effect<void>
+}): Action<A> => ({
+  _tag: "Action",
+  flag: options.flag,
+  run: options.run
+})
+
+/**
+ * Creates a Setting flag that configures the command handler's environment.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const setting = <const Id extends string>(
+  id: Id
+) =>
+<A>(options: {
+  readonly flag: Flag.Flag<A>
+}): Setting<Id, A> => {
+  settingIdCounter += 1
+  const ref = ServiceMap.Service<Setting.Identifier<Id>, A>(
+    `effect/unstable/cli/GlobalFlag/${id}/${settingIdCounter}`
+  )
+  return Object.assign(ref, {
+    _tag: "Setting" as const,
+    id,
+    flag: options.flag
+  })
+}
+
+let settingIdCounter = 0
+
+/* ========================================================================== */
+/* Built-in Flag References                                                   */
+/* ========================================================================== */
+
+/**
+ * The `--help` / `-h` global flag.
+ * Shows help documentation for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const Help: Action<boolean> = action({
+  flag: Flag.boolean("help").pipe(
+    Flag.withAlias("h"),
+    Flag.withDescription("Show help information")
+  ),
+  run: (_, { command, commandPath }) =>
+    Effect.gen(function*() {
+      const formatter = yield* CliOutput.Formatter
+      const helpDoc = yield* HelpInternal.getHelpForCommandPath(command, commandPath, BuiltIns)
+      yield* Console.log(formatter.formatHelpDoc(helpDoc))
+    })
+})
+
+/**
+ * The `--version` global flag.
+ * Shows version information for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const Version: Action<boolean> = action({
+  flag: Flag.boolean("version").pipe(
+    Flag.withDescription("Show version information")
+  ),
+  run: (_, { command, version }) =>
+    Effect.gen(function*() {
+      const formatter = yield* CliOutput.Formatter
+      yield* Console.log(formatter.formatVersion(command.name, version))
+    })
+})
+
+/**
+ * The `--completions` global flag.
+ * Prints shell completion script for the given shell.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const Completions: Action<Option.Option<"bash" | "zsh" | "fish">> = action({
+  flag: Flag.choice("completions", ["bash", "zsh", "fish", "sh"] as const)
+    .pipe(
+      Flag.optional,
+      Flag.map((v) => Option.map(v, (s) => s === "sh" ? "bash" : s)),
+      Flag.withDescription("Print shell completion script")
+    ),
+  run: (shell, { command }) =>
+    Effect.gen(function*() {
+      if (Option.isNone(shell)) return
+      const descriptor = CommandDescriptor.fromCommand(command)
+      yield* Console.log(
+        Completions_.generate(command.name, shell.value, descriptor)
+      )
+    })
+})
+
+/**
+ * The `--log-level` global flag.
+ * Sets the minimum log level for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const LogLevel: Setting<"log-level", Option.Option<LogLevelType>> = setting("log-level")({
+  flag: Flag.choiceWithValue(
+    "log-level",
+    [
+      ["all", "All"],
+      ["trace", "Trace"],
+      ["debug", "Debug"],
+      ["info", "Info"],
+      ["warn", "Warn"],
+      ["warning", "Warn"],
+      ["error", "Error"],
+      ["fatal", "Fatal"],
+      ["none", "None"]
+    ] as const
+  ).pipe(
+    Flag.optional,
+    Flag.withDescription("Sets the minimum log level")
+  )
+})
+
+/* ========================================================================== */
+/* References                                                                 */
+/* ========================================================================== */
+
+/**
+ * Built-in global flags in default precedence order.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const BuiltIns: ReadonlyArray<GlobalFlag<any>> = [
+  Help,
+  Version,
+  Completions,
+  LogLevel
+]
+
+/**
+ * Built-in setting context identifiers.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export type BuiltInSettingContext = Setting.Identifier<"log-level">

package/src/unstable/cli/HelpDoc.ts

@@ -2,6 +2,10 @@
  * @since 4.0.0
  */
 
+import type { NonEmptyReadonlyArray } from "../../Array.ts"
+import type * as Option from "../../Option.ts"
+import type * as ServiceMap from "../../ServiceMap.ts"
+
 /**
  * Structured representation of help documentation for a command.
  * This data structure is independent of formatting, allowing for
@@ -9,24 +13,26 @@
  *
  * @example
  * ```ts
+ * import { Option as O, ServiceMap } from "effect"
  * import type * as HelpDoc from "effect/unstable/cli/HelpDoc"
  *
  * const deployCommandHelp: HelpDoc.HelpDoc = {
  *   description: "Deploy your application to the cloud",
  *   usage: "myapp deploy [options] <target>",
+ *   annotations: ServiceMap.empty(),
  *   flags: [
  *     {
  *       name: "verbose",
  *       aliases: ["-v"],
  *       type: "boolean",
- *       description: "Enable verbose logging",
+ *       description: O.some("Enable verbose logging"),
  *       required: false
  *     },
  *     {
  *       name: "env",
  *       aliases: ["-e"],
  *       type: "string",
- *       description: "Target environment",
+ *       description: O.some("Target environment"),
  *       required: true
  *     }
  *   ],
@@ -34,7 +40,7 @@
  *     {
  *       name: "target",
  *       type: "string",
- *       description: "Deployment target (e.g., 'production', 'staging')",
+ *       description: O.some("Deployment target (e.g., 'production', 'staging')"),
  *       required: true,
  *       variadic: false
  *     }
@@ -62,6 +68,16 @@ export interface HelpDoc {
    */
   readonly flags: ReadonlyArray<FlagDoc>
 
+  /**
+   * Global flags available to all commands (e.g., --help, --version).
+   */
+  readonly globalFlags?: ReadonlyArray<FlagDoc>
+
+  /**
+   * Custom command annotations.
+   */
+  readonly annotations: ServiceMap.ServiceMap<never>
+
   /**
    * List of positional arguments for this command
    */
@@ -70,7 +86,30 @@ export interface HelpDoc {
   /**
    * Optional list of subcommands if this is a parent command
    */
-  readonly subcommands?: ReadonlyArray<SubcommandDoc>
+  readonly subcommands?: ReadonlyArray<SubcommandGroupDoc>
+
+  /**
+   * Optional concrete usage examples for the command
+   */
+  readonly examples?: ReadonlyArray<ExampleDoc>
+}
+
+/**
+ * Documentation for a command usage example
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface ExampleDoc {
+  /**
+   * Command line invocation example
+   */
+  readonly command: string
+
+  /**
+   * Optional explanation for the example
+   */
+  readonly description?: string | undefined
 }
 
 /**
@@ -78,13 +117,14 @@ export interface HelpDoc {
  *
  * @example
  * ```ts
+ * import { Option as O } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const verboseFlag: HelpDoc.FlagDoc = {
  *   name: "verbose",
  *   aliases: ["-v", "--verbose"],
  *   type: "boolean",
- *   description: "Enable verbose output",
+ *   description: O.some("Enable verbose output"),
  *   required: false
  * }
  *
@@ -92,7 +132,7 @@ export interface HelpDoc {
  *   name: "port",
  *   aliases: ["-p"],
  *   type: "integer",
- *   description: "Port number to use",
+ *   description: O.some("Port number to use"),
  *   required: true
  * }
  * ```
@@ -119,7 +159,7 @@ export interface FlagDoc {
   /**
    * Description of what the flag does
    */
-  readonly description: string | undefined
+  readonly description: Option.Option<string>
 
   /**
    * Whether this flag is required
@@ -132,15 +172,20 @@ export interface FlagDoc {
  *
  * @example
  * ```ts
+ * import { Option as O, ServiceMap } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const deploySubcommand: HelpDoc.SubcommandDoc = {
  *   name: "deploy",
+ *   alias: "d",
+ *   shortDescription: "Deploy app",
  *   description: "Deploy the application to the cloud"
  * }
  *
  * const buildSubcommand: HelpDoc.SubcommandDoc = {
  *   name: "build",
+ *   alias: undefined,
+ *   shortDescription: undefined,
  *   description: "Build the application for production"
  * }
  *
@@ -148,8 +193,12 @@ export interface FlagDoc {
  * const mainCommandHelp: HelpDoc.HelpDoc = {
  *   description: "Cloud deployment tool",
  *   usage: "myapp <command> [options]",
+ *   annotations: ServiceMap.empty(),
  *   flags: [],
- *   subcommands: [deploySubcommand, buildSubcommand]
+ *   subcommands: [{
+ *     group: undefined,
+ *     commands: [deploySubcommand, buildSubcommand]
+ *   }]
  * }
  * ```
  *
@@ -162,23 +211,53 @@ export interface SubcommandDoc {
    */
   readonly name: string
 
+  /**
+   * Optional short alias for invoking the subcommand.
+   */
+  readonly alias: string | undefined
+
+  /**
+   * Optional short description of what the subcommand does.
+   */
+  readonly shortDescription: string | undefined
+
   /**
    * Brief description of what the subcommand does
    */
   readonly description: string
 }
 
+/**
+ * Documentation for a grouped subcommand listing
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface SubcommandGroupDoc {
+  /**
+   * Group name used in help output.
+   * Undefined means the default ungrouped section.
+   */
+  readonly group: string | undefined
+
+  /**
+   * Subcommands in this group.
+   */
+  readonly commands: NonEmptyReadonlyArray<SubcommandDoc>
+}
+
 /**
  * Documentation for a positional argument
  *
  * @example
  * ```ts
+ * import { Option as O, ServiceMap } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const sourceArg: HelpDoc.ArgDoc = {
  *   name: "source",
  *   type: "file",
- *   description: "Source file to process",
+ *   description: O.some("Source file to process"),
  *   required: true,
  *   variadic: false
  * }
@@ -186,7 +265,7 @@ export interface SubcommandDoc {
  * const filesArg: HelpDoc.ArgDoc = {
  *   name: "files",
  *   type: "file",
- *   description: "Files to process (can specify multiple)",
+ *   description: O.some("Files to process (can specify multiple)"),
  *   required: false,
  *   variadic: true
  * }
@@ -195,6 +274,7 @@ export interface SubcommandDoc {
  * const copyCommandHelp: HelpDoc.HelpDoc = {
  *   description: "Copy files from source to destination",
  *   usage: "copy <source> [files...]",
+ *   annotations: ServiceMap.empty(),
  *   flags: [],
  *   args: [sourceArg, filesArg]
  * }
@@ -217,7 +297,7 @@ export interface ArgDoc {
   /**
    * Description of what the argument is for
    */
-  readonly description: string | undefined
+  readonly description: Option.Option<string>
 
   /**
    * Whether this argument is required or optional

package/src/unstable/cli/Param.ts

@@ -147,7 +147,7 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly _tag: "Single"
   readonly kind: Kind
   readonly name: string
-  readonly description: string | undefined
+  readonly description: Option.Option<string>
   readonly aliases: ReadonlyArray<string>
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
@@ -193,8 +193,8 @@ export interface Variadic<Kind extends ParamKind, A> extends Param<Kind, Readonl
   readonly _tag: "Variadic"
   readonly kind: Kind
   readonly param: Param<Kind, A>
-  readonly min: number | undefined
-  readonly max: number | undefined
+  readonly min: Option.Option<number>
+  readonly max: Option.Option<number>
 }
 
 const Proto = {
@@ -268,7 +268,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly name: string
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
-  readonly description?: string | undefined
+  readonly description?: Option.Option<string> | undefined
   readonly aliases?: ReadonlyArray<string> | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
@@ -278,7 +278,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   return Object.assign(Object.create(Proto), {
     _tag: "Single",
     ...params,
-    description: params.description,
+    description: params.description ?? Option.none(),
     aliases: params.aliases ?? [],
     parse
   })
@@ -734,7 +734,7 @@ export const fileParse = <Kind extends ParamKind>(
  * const configSchema = Schema.Struct({
  *   port: Schema.Number,
  *   host: Schema.String
- * }).pipe(Schema.fromJsonString)
+ * })
  *
  * const config = Param.fileSchema(Param.flagKind, "config", configSchema, {
  *   format: "json"
@@ -754,7 +754,7 @@ export const fileParse = <Kind extends ParamKind>(
 export const fileSchema = <Kind extends ParamKind, A>(
   kind: Kind,
   name: string,
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: Primitive.FileSchemaOptions | undefined
 ): Param<Kind, A> =>
   makeSingle({
@@ -1005,7 +1005,7 @@ export const withDescription: {
   return transformSingle(self, <X>(single: Single<Kind, X>) =>
     makeSingle({
       ...single,
-      description
+      description: Option.some(description)
     }))
 })
 
@@ -1603,8 +1603,8 @@ export const variadic = <Kind extends ParamKind, A>(
     _tag: "Variadic",
     kind: self.kind,
     param: self,
-    min: options?.min,
-    max: options?.max,
+    min: Option.fromUndefinedOr(options?.min),
+    max: Option.fromUndefinedOr(options?.max),
     parse
   })
 }
@@ -2587,7 +2587,11 @@ const transformSingle = <Kind extends ParamKind, A>(
     Map: (mapped) => map(transformSingle(mapped.param, f), mapped.f),
     Transform: (mapped) => transform(transformSingle(mapped.param, f), mapped.f),
     Optional: (p) => optional(transformSingle(p.param, f)) as Param<Kind, A>,
-    Variadic: (p) => variadic(transformSingle(p.param, f), { min: p.min, max: p.max }) as Param<Kind, A>
+    Variadic: (p) =>
+      variadic(transformSingle(p.param, f), {
+        min: Option.getOrUndefined(p.min),
+        max: Option.getOrUndefined(p.max)
+      }) as Param<Kind, A>
   })
 }
 

package/src/unstable/cli/Primitive.ts

@@ -575,7 +575,7 @@ export type FileSchemaOptions = Struct.Simplify<
  * @category constructors
  */
 export const fileSchema = <A>(
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: FileSchemaOptions | undefined
 ): Primitive<A> => {
   const decode = Schema.decodeUnknownEffect(schema)
@@ -645,7 +645,7 @@ export const keyValuePair: Primitive<Record<string, string>> = makePrimitive(
  *
  * const program = Effect.gen(function*() {
  *   // This will always fail - useful for boolean flags
- *   const result = yield* Primitive.none.parse("any-value")
+ *   return yield* Primitive.none.parse("any-value")
  * })
  *
  * // The above effect will fail with "This option does not accept values"