effect 4.0.0-beta.12 → 4.0.0-beta.14

package/src/unstable/cli/Command.ts

@@ -6,7 +6,8 @@ import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
 import { dual } from "../../Function.ts"
-import type * as Layer from "../../Layer.ts"
+import * as Layer from "../../Layer.ts"
+import * as Option from "../../Option.ts"
 import type * as Path from "../../Path.ts"
 import type { Pipeable } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
@@ -18,13 +19,13 @@ import type { NoInfer, Simplify } from "../../Types.ts"
 import type { ChildProcessSpawner } from "../process/ChildProcessSpawner.ts"
 import * as CliError from "./CliError.ts"
 import * as CliOutput from "./CliOutput.ts"
-import { checkForDuplicateFlags, getHelpForCommandPath, makeCommand, toImpl, TypeId } from "./internal/command.ts"
-import * as CommandDescriptor from "./internal/completions/CommandDescriptor.ts"
-import * as Completions from "./internal/completions/Completions.ts"
+import * as GlobalFlag from "./GlobalFlag.ts"
+import { checkForDuplicateFlags, makeCommand, toImpl, TypeId } from "./internal/command.ts"
 import { parseConfig } from "./internal/config.ts"
+import { getHelpForCommandPath } from "./internal/help.ts"
 import * as Lexer from "./internal/lexer.ts"
 import * as Parser from "./internal/parser.ts"
-import type * as Param from "./Param.ts"
+import * as Param from "./Param.ts"
 
 /* ========================================================================== */
 /* Public Types                                                               */
@@ -100,6 +101,11 @@ export interface Command<Name extends string, Input, E = never, R = never> exten
    */
   readonly shortDescription: string | undefined
 
+  /**
+   * An optional alias that can be used as a shorter command name.
+   */
+  readonly alias: string | undefined
+
   /**
    * Optional usage examples for the command.
    */
@@ -934,6 +940,7 @@ export const withSubcommands: {
     config: impl.config,
     description: impl.description,
     shortDescription: impl.shortDescription,
+    alias: impl.alias,
     annotations: impl.annotations,
     examples: impl.examples,
     service: impl.service,
@@ -1073,6 +1080,43 @@ export const withShortDescription: {
   shortDescription: string
 ) => makeCommand({ ...toImpl(self), shortDescription }))
 
+/**
+ * Sets an alias for a command.
+ *
+ * Aliases are accepted as alternate subcommand names during parsing and are
+ * shown in help output as `name, alias`.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withAlias: {
+  /**
+   * Sets an alias for a command.
+   *
+   * Aliases are accepted as alternate subcommand names during parsing and are
+   * shown in help output as `name, alias`.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (alias: string): <const Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Sets an alias for a command.
+   *
+   * Aliases are accepted as alternate subcommand names during parsing and are
+   * shown in help output as `name, alias`.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, alias: string): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  alias: string
+) => makeCommand({ ...toImpl(self), alias }))
+
 /**
  * Adds a custom annotation to a command.
  *
@@ -1497,7 +1541,7 @@ const showHelp = <Name extends string, Input, E, R>(
 ): Effect.Effect<void, never, Environment> =>
   Effect.gen(function*() {
     const formatter = yield* CliOutput.Formatter
-    const helpDoc = getHelpForCommandPath(command, commandPath)
+    const helpDoc = yield* getHelpForCommandPath(command, commandPath, GlobalFlag.Registry)
     yield* Console.log(formatter.formatHelpDoc(helpDoc))
     if (errors && errors.length > 0) {
       yield* Console.error(formatter.formatErrors(errors))
@@ -1553,12 +1597,13 @@ export const run: {
    * @since 4.0.0
    * @category command execution
    */
-  <Name extends string, Input, E, R>(
-    command: Command<Name, Input, E, R>,
+  (
     config: {
       readonly version: string
     }
-  ): Effect.Effect<void, E | CliError.CliError, R | Environment>
+  ): <Name extends string, Input, E, R>(
+    command: Command<Name, Input, E, R>
+  ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
   /**
    * Runs a command with the provided input arguments.
    *
@@ -1583,13 +1628,12 @@ export const run: {
    * @since 4.0.0
    * @category command execution
    */
-  (
+  <Name extends string, Input, E, R>(
+    command: Command<Name, Input, E, R>,
     config: {
       readonly version: string
     }
-  ): <Name extends string, Input, E, R>(
-    command: Command<Name, Input, E, R>
-  ) => Effect.Effect<void, E | CliError.CliError, R | Environment>
+  ): Effect.Effect<void, E | CliError.CliError, R | Environment>
 } = dual(2, <Name extends string, Input, E, R>(
   command: Command<Name, Input, E, R>,
   config: {
@@ -1652,29 +1696,37 @@ export const runWith = <const Name extends string, Input, E, R>(
   const commandImpl = toImpl(command)
   return Effect.fnUntraced(
     function*(args: ReadonlyArray<string>) {
-      // Lex and extract built-in flags
       const { tokens, trailingOperands } = Lexer.lex(args)
-      const { completions, help, logLevel, remainder, version } = yield* Parser.extractBuiltInOptions(tokens)
+
+      // 1. Read global flags from registry
+      const flags = Array.from(yield* GlobalFlag.Registry)
+
+      // 2. Extract global flag tokens
+      const allFlagParams = flags.flatMap((f) => Param.extractSingleParams(f.flag))
+      const globalRegistry = Parser.createFlagRegistry(allFlagParams.filter(Param.isFlagParam))
+      const { flagMap, remainder } = Parser.consumeKnownFlags(tokens, globalRegistry)
+      const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
+
+      // 3. Parse command arguments from remaining tokens
       const parsedArgs = yield* Parser.parseArgs({ tokens: remainder, trailingOperands }, command)
       const commandPath = [command.name, ...Parser.getCommandPath(parsedArgs)] as const
-      const formatter = yield* CliOutput.Formatter
-
-      // Handle built-in flags (early exits)
-      if (help) {
-        yield* Console.log(formatter.formatHelpDoc(getHelpForCommandPath(command, commandPath)))
-        return
-      }
-      if (completions !== undefined) {
-        const descriptor = CommandDescriptor.fromCommand(command)
-        yield* Console.log(Completions.generate(command.name, completions, descriptor))
-        return
-      }
-      if (version) {
-        yield* Console.log(formatter.formatVersion(command.name, config.version))
+      const handlerCtx: GlobalFlag.HandlerContext = { command, commandPath, version: config.version }
+
+      // 4. Process action flags — first present action wins, then exit
+      for (const flag of flags) {
+        if (flag._tag !== "Action") continue
+        const singles = Param.extractSingleParams(flag.flag)
+        const hasEntry = singles.some((s) => {
+          const entries = flagMap[s.name]
+          return entries !== undefined && entries.length > 0
+        })
+        if (!hasEntry) continue
+        const [, value] = yield* flag.flag.parse(emptyArgs)
+        yield* flag.run(value, handlerCtx)
         return
       }
 
-      // Handle parsing errors
+      // 5. Handle parsing errors
       if (parsedArgs.errors && parsedArgs.errors.length > 0) {
         return yield* showHelp(command, commandPath, parsedArgs.errors)
       }
@@ -1682,15 +1734,30 @@ export const runWith = <const Name extends string, Input, E, R>(
       if (parseResult._tag === "Failure") {
         return yield* showHelp(command, commandPath, [parseResult.failure])
       }
-      const parsed = parseResult.success
 
-      // Create and run the execution program
-      const program = commandImpl.handle(parsed, [command.name])
-      const withLogLevel = logLevel !== undefined
-        ? Effect.provideService(program, References.MinimumLogLevel, logLevel)
-        : program
+      // 6. Provide setting values
+      let contextLayer: Layer.Layer<never> = Layer.empty
+      for (const flag of flags) {
+        if (flag._tag !== "Setting") continue
+        const [, value] = yield* flag.flag.parse(emptyArgs)
+        contextLayer = Layer.merge(contextLayer, Layer.succeed(flag, value))
+      }
+
+      // 7. Apply built-in setting behavior
+      if (flags.includes(GlobalFlag.LogLevel)) {
+        const [, logLevel] = yield* GlobalFlag.LogLevel.flag.parse(emptyArgs)
+        contextLayer = Layer.merge(
+          contextLayer,
+          Option.match(logLevel, {
+            onNone: () => Layer.empty,
+            onSome: (level) => Layer.succeed(References.MinimumLogLevel, level)
+          })
+        )
+      }
 
-      yield* withLogLevel
+      // 8. Run command handler with composed context
+      const program = commandImpl.handle(parseResult.success, [command.name])
+      yield* Effect.provide(program, contextLayer)
     },
     Effect.catchIf(
       ((error: any) =>

package/src/unstable/cli/GlobalFlag.ts

@@ -0,0 +1,321 @@
+/**
+ * @since 4.0.0
+ */
+
+import * as Console from "../../Console.ts"
+import * as Effect from "../../Effect.ts"
+import { dual } from "../../Function.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<A> extends ServiceMap.Reference<A> {
+  readonly _tag: "Setting"
+  readonly flag: Flag.Flag<A>
+}
+
+/**
+ * Global flag discriminated union.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export type GlobalFlag<A> = Action<A> | Setting<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 = <A>(options: {
+  readonly flag: Flag.Flag<A>
+  readonly defaultValue: () => A
+}): Setting<A> => {
+  settingIdCounter += 1
+  const ref = ServiceMap.Reference<A>(
+    `effect/cli/GlobalFlag/Setting/${settingIdCounter}`,
+    { defaultValue: options.defaultValue }
+  )
+  return Object.assign(ref, {
+    _tag: "Setting" as const,
+    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, Registry)
+      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<Option.Option<LogLevelType>> = setting({
+  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")
+  ),
+  defaultValue: () => Option.none()
+})
+
+/* ========================================================================== */
+/* Registry                                                                   */
+/* ========================================================================== */
+
+/**
+ * The ordered set of global flag references.
+ * The parser iterates this set to know which flags to extract.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const Registry: ServiceMap.Reference<
+  Set<GlobalFlag<any>>
+> = ServiceMap.Reference("effect/cli/GlobalFlag/Registry", {
+  defaultValue: () =>
+    new Set<GlobalFlag<any>>([
+      Help,
+      Version,
+      Completions,
+      LogLevel
+    ])
+})
+
+/* ========================================================================== */
+/* Public API                                                                 */
+/* ========================================================================== */
+
+/**
+ * Adds a global flag to the registry.
+ *
+ * @since 4.0.0
+ * @category modifiers
+ */
+export const add: {
+  /* ========================================================================== */
+  /* Public API                                                                 */
+  /* ========================================================================== */
+
+  /**
+   * Adds a global flag to the registry.
+   *
+   * @since 4.0.0
+   * @category modifiers
+   */
+  <A>(flag: GlobalFlag<A>): <B, E, R>(
+    self: Effect.Effect<B, E, R>
+  ) => Effect.Effect<B, E, R>
+  /* ========================================================================== */
+  /* Public API                                                                 */
+  /* ========================================================================== */
+
+  /**
+   * Adds a global flag to the registry.
+   *
+   * @since 4.0.0
+   * @category modifiers
+   */
+  <B, E, R, A>(self: Effect.Effect<B, E, R>, flag: GlobalFlag<A>): Effect.Effect<B, E, R>
+} = dual(
+  2,
+  Effect.fnUntraced(function*<B, E, R, A>(
+    self: Effect.Effect<B, E, R>,
+    flag: GlobalFlag<A>
+  ) {
+    const currentRegistry = yield* Registry
+    const nextRegistry = new Set([...currentRegistry, flag])
+    return yield* Effect.provideService(self, Registry, nextRegistry)
+  })
+)
+
+/**
+ * Removes a global flag by its reference.
+ *
+ * @since 4.0.0
+ * @category modifiers
+ */
+export const remove: {
+  /**
+   * Removes a global flag by its reference.
+   *
+   * @since 4.0.0
+   * @category modifiers
+   */
+  <A>(flag: GlobalFlag<A>): <B, E, R>(
+    self: Effect.Effect<B, E, R>
+  ) => Effect.Effect<B, E, R>
+  /**
+   * Removes a global flag by its reference.
+   *
+   * @since 4.0.0
+   * @category modifiers
+   */
+  <B, E, R, A>(self: Effect.Effect<B, E, R>, flag: GlobalFlag<A>): Effect.Effect<B, E, R>
+} = dual(
+  2,
+  Effect.fnUntraced(function*<B, E, R, A>(
+    self: Effect.Effect<B, E, R>,
+    flag: GlobalFlag<A>
+  ) {
+    const currentRegistry = yield* Registry
+    const nextRegistry = new Set(currentRegistry)
+    nextRegistry.delete(flag)
+    return yield* Effect.provideService(self, Registry, nextRegistry)
+  })
+)
+
+/**
+ * Removes all global flags (built-in and user-defined).
+ *
+ * @since 4.0.0
+ * @category modifiers
+ */
+export const clear = <B, E, R>(self: Effect.Effect<B, E, R>): Effect.Effect<B, E, R> =>
+  Effect.provideService(self, Registry, new Set())

package/src/unstable/cli/HelpDoc.ts

@@ -67,6 +67,11 @@ export interface HelpDoc {
    */
   readonly flags: ReadonlyArray<FlagDoc>
 
+  /**
+   * Global flags available to all commands (e.g., --help, --version).
+   */
+  readonly globalFlags?: ReadonlyArray<FlagDoc>
+
   /**
    * Custom command annotations.
    */
@@ -170,12 +175,14 @@ export interface FlagDoc {
  *
  * 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"
  * }
@@ -202,6 +209,11 @@ 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.
    */

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

@@ -90,6 +90,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   readonly annotations?: ServiceMap.ServiceMap<never> | undefined
   readonly description?: string | 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
@@ -165,6 +166,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
         group: group.group,
         commands: Arr.map(group.commands, (subcommand) => ({
           name: subcommand.name,
+          alias: subcommand.alias,
           shortDescription: subcommand.shortDescription,
           description: subcommand.description ?? ""
         }))
@@ -200,6 +202,9 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
       : {}),
     ...(Predicate.isNotUndefined(options.shortDescription)
       ? { shortDescription: options.shortDescription }
+      : {}),
+    ...(Predicate.isNotUndefined(options.alias)
+      ? { alias: options.alias }
       : {})
   })
 }
@@ -269,33 +274,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]
-    let subcommand: Command.Any | undefined = undefined
-
-    for (const group of currentCommand.subcommands) {
-      subcommand = group.commands.find((sub) => sub.name === subcommandName)
-      if (subcommand) {
-        break
-      }
-    }
-
-    if (subcommand) {
-      currentCommand = subcommand
-    }
-  }
-
-  return toImpl(currentCommand).buildHelpDoc(commandPath)
-}