effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/unstable/cli/GlobalFlag.ts

@@ -0,0 +1,243 @@
+/**
+ * @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 Flag from "./Flag.ts"
+
+/* ========================================================================== */
+/* Types                                                                      */
+/* ========================================================================== */
+
+/**
+ * Context passed to action handlers.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export interface HandlerContext {
+  readonly command: Command.Command<any, unknown, 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                                                   */
+/* ========================================================================== */
+
+import * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
+import * as CompletionsInternal from "./internal/completions/Completions.ts"
+import * as HelpInternal from "./internal/help.ts"
+
+/**
+ * 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(
+        CompletionsInternal.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,9 @@
  * @since 4.0.0
  */
 
+import type { NonEmptyReadonlyArray } from "../../Array.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,11 +12,13 @@
  *
  * @example
  * ```ts
+ * import { 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",
@@ -62,6 +67,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 +85,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
 }
 
 /**
@@ -132,15 +170,20 @@ export interface FlagDoc {
  *
  * @example
  * ```ts
+ * import { 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 +191,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,17 +209,47 @@ 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 { ServiceMap } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const sourceArg: HelpDoc.ArgDoc = {
@@ -195,6 +272,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]
  * }

package/src/unstable/cli/index.ts

@@ -29,6 +29,11 @@ export * as Command from "./Command.ts"
  */
 export * as Flag from "./Flag.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as GlobalFlag from "./GlobalFlag.ts"
+
 /**
  * @since 4.0.0
  */

package/src/unstable/cli/internal/command.ts

@@ -5,13 +5,15 @@
  * Internal implementation details for CLI commands.
  * Public API is in ../Command.ts
  */
+import * as Arr from "../../../Array.ts"
 import * as Effect from "../../../Effect.ts"
 import { YieldableProto } from "../../../internal/core.ts"
 import { pipeArguments } from "../../../Pipeable.ts"
 import * as Predicate from "../../../Predicate.ts"
 import * as ServiceMap from "../../../ServiceMap.ts"
 import * as CliError from "../CliError.ts"
-import type { ArgDoc, FlagDoc, HelpDoc, SubcommandDoc } from "../HelpDoc.ts"
+import type * as GlobalFlag from "../GlobalFlag.ts"
+import type { ArgDoc, ExampleDoc, FlagDoc, HelpDoc, SubcommandGroupDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
 import { type ConfigInternal, reconstructTree } from "./config.ts"
@@ -22,13 +24,20 @@ import { type ConfigInternal, reconstructTree } from "./config.ts"
 
 import type { Command, CommandContext, Environment, ParsedTokens } from "../Command.ts"
 
+interface SubcommandGroup {
+  readonly group: string | undefined
+  readonly commands: Arr.NonEmptyReadonlyArray<Command<any, unknown, unknown, unknown>>
+}
+
 /**
  * Internal implementation interface with all the machinery.
  * Use toImpl() to access from internal code.
  */
 export interface CommandInternal<Name extends string, Input, E, R> extends Command<Name, Input, E, R> {
   readonly config: ConfigInternal
-  readonly service: ServiceMap.Service<CommandContext<Name>, Input>
+  readonly service: ServiceMap.Key<CommandContext<Name>, Input>
+  readonly annotations: ServiceMap.ServiceMap<never>
+  readonly globalFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
   readonly parse: (input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>
   readonly handle: (
     input: Input,
@@ -79,9 +88,14 @@ export const Proto = {
 export const makeCommand = <const Name extends string, Input, E, R>(options: {
   readonly name: Name
   readonly config: ConfigInternal
-  readonly service?: ServiceMap.Service<CommandContext<Name>, Input> | undefined
+  readonly service?: ServiceMap.Key<CommandContext<Name>, Input> | undefined
+  readonly annotations?: ServiceMap.ServiceMap<never> | undefined
+  readonly globalFlags?: ReadonlyArray<GlobalFlag.GlobalFlag<any>> | undefined
   readonly description?: string | undefined
-  readonly subcommands?: ReadonlyArray<Command<any, unknown, unknown, unknown>> | undefined
+  readonly shortDescription?: string | undefined
+  readonly alias?: string | undefined
+  readonly examples?: ReadonlyArray<Command.Example> | undefined
+  readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
   readonly handle?:
     | ((input: Input, commandPath: ReadonlyArray<string>) => Effect.Effect<void, E, R | Environment>)
@@ -89,6 +103,9 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
 }): Command<Name, Input, E, R> => {
   const service = options.service ?? ServiceMap.Service<CommandContext<Name>, Input>(`${TypeId}/${options.name}`)
   const config = options.config
+  const annotations = options.annotations ?? ServiceMap.empty()
+  const globalFlags = options.globalFlags ?? []
+  const subcommands = options.subcommands ?? []
 
   const handle = (
     input: Input,
@@ -123,8 +140,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     }
 
     let usage = commandPath.length > 0 ? commandPath.join(" ") : options.name
-    const subcommands = options.subcommands ?? []
-    if (subcommands.length > 0) {
+    if (subcommands.some((group) => group.commands.length > 0)) {
       usage += " <subcommand>"
     }
     usage += " [flags]"
@@ -147,24 +163,40 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
       }
     }
 
-    const subcommandDocs: Array<SubcommandDoc> = subcommands.map((sub) => ({
-      name: sub.name,
-      description: sub.description ?? ""
-    }))
+    const subcommandDocs: Array<SubcommandGroupDoc> = []
+
+    for (const group of subcommands) {
+      subcommandDocs.push({
+        group: group.group,
+        commands: Arr.map(group.commands, (subcommand) => ({
+          name: subcommand.name,
+          alias: subcommand.alias,
+          shortDescription: subcommand.shortDescription,
+          description: subcommand.description ?? ""
+        }))
+      })
+    }
+
+    const examples: ReadonlyArray<ExampleDoc> = options.examples ?? []
 
     return {
       description: options.description ?? "",
       usage,
       flags,
+      annotations,
       ...(args.length > 0 && { args }),
-      ...(subcommandDocs.length > 0 && { subcommands: subcommandDocs })
+      ...(subcommandDocs.length > 0 && { subcommands: subcommandDocs }),
+      ...(examples.length > 0 && { examples })
     }
   }
 
   return Object.assign(Object.create(Proto), {
     [TypeId]: TypeId,
     name: options.name,
-    subcommands: options.subcommands ?? [],
+    examples: options.examples ?? [],
+    annotations,
+    globalFlags,
+    subcommands,
     config,
     service,
     parse,
@@ -172,6 +204,12 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     buildHelpDoc,
     ...(Predicate.isNotUndefined(options.description)
       ? { description: options.description }
+      : {}),
+    ...(Predicate.isNotUndefined(options.shortDescription)
+      ? { shortDescription: options.shortDescription }
+      : {}),
+    ...(Predicate.isNotUndefined(options.alias)
+      ? { alias: options.alias }
       : {})
   })
 }
@@ -241,25 +279,3 @@ export const checkForDuplicateFlags = <Name extends string, Input>(
     }
   }
 }
-
-/**
- * Helper function to get help documentation for a specific command path.
- * Navigates through the command hierarchy to find the right command.
- */
-export const getHelpForCommandPath = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
-  commandPath: ReadonlyArray<string>
-): HelpDoc => {
-  let currentCommand: Command.Any = command
-
-  // Navigate through the command path to find the target command
-  for (let i = 1; i < commandPath.length; i++) {
-    const subcommandName = commandPath[i]
-    const subcommand = currentCommand.subcommands.find((sub) => sub.name === subcommandName)
-    if (subcommand) {
-      currentCommand = subcommand
-    }
-  }
-
-  return toImpl(currentCommand).buildHelpDoc(commandPath)
-}

package/src/unstable/cli/internal/completions/CommandDescriptor.ts

@@ -157,11 +157,16 @@ export const fromCommand = (cmd: Command.Any): CommandDescriptor => {
     }
   }
 
-  const subcommands: Array<CommandDescriptor> = cmd.subcommands.map(fromCommand)
+  const subcommands: Array<CommandDescriptor> = []
+  for (const group of cmd.subcommands) {
+    for (const subcommand of group.commands) {
+      subcommands.push(fromCommand(subcommand))
+    }
+  }
 
   return {
     name: cmd.name,
-    description: cmd.description,
+    description: cmd.shortDescription ?? cmd.description,
     flags,
     arguments: args,
     subcommands