effect 4.0.0-beta.10 → 4.0.0-beta.12

package/src/unstable/cli/Command.ts

@@ -1,6 +1,7 @@
 /**
  * @since 4.0.0
  */
+import type { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Console from "../../Console.ts"
 import * as Effect from "../../Effect.ts"
 import type * as FileSystem from "../../FileSystem.ts"
@@ -11,9 +12,9 @@ import type { Pipeable } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as References from "../../References.ts"
 import * as Result from "../../Result.ts"
-import type * as ServiceMap from "../../ServiceMap.ts"
+import * as ServiceMap from "../../ServiceMap.ts"
 import * as Terminal from "../../Terminal.ts"
-import type { Simplify } from "../../Types.ts"
+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"
@@ -94,16 +95,45 @@ export interface Command<Name extends string, Input, E = never, R = never> exten
    */
   readonly description: string | undefined
 
+  /**
+   * An optional short description used when listing subcommands.
+   */
+  readonly shortDescription: string | undefined
+
+  /**
+   * Optional usage examples for the command.
+   */
+  readonly examples: ReadonlyArray<Command.Example>
+
   /**
    * The subcommands available under this command.
    */
-  readonly subcommands: ReadonlyArray<Command.Any>
+  readonly subcommands: ReadonlyArray<{
+    readonly group: string | undefined
+    readonly commands: NonEmptyReadonlyArray<Command.Any>
+  }>
+
+  /**
+   * Custom annotations associated with this command.
+   */
+  readonly annotations: ServiceMap.ServiceMap<never>
 }
 
 /**
  * @since 4.0.0
  */
 export declare namespace Command {
+  /**
+   * Represents a concrete usage example for a command.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface Example {
+    readonly command: string
+    readonly description?: string | undefined
+  }
+
   /**
    * Configuration object for defining command flags, arguments, and nested structures.
    *
@@ -209,6 +239,25 @@ export declare namespace Command {
    * @category models
    */
   export type Any = Command<string, unknown, unknown, unknown>
+
+  /**
+   * A grouped set of subcommands used by `Command.withSubcommands`.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export interface SubcommandGroup<Commands extends ReadonlyArray<Any> = ReadonlyArray<Any>> {
+    readonly group: string
+    readonly commands: Commands
+  }
+
+  /**
+   * Entry type accepted by `Command.withSubcommands`.
+   *
+   * @since 4.0.0
+   * @category models
+   */
+  export type SubcommandEntry = Any | SubcommandGroup<ReadonlyArray<Any>>
 }
 
 /**
@@ -644,6 +693,57 @@ export const withHandler: {
   handler: (value: A) => Effect.Effect<void, E, R>
 ): Command<Name, A, E, R> => makeCommand({ ...toImpl(self), handle: handler }))
 
+interface SubcommandGroupInternal {
+  readonly group: string | undefined
+  readonly commands: NonEmptyReadonlyArray<Command.Any>
+}
+
+const normalizeSubcommandEntries = (
+  entries: ReadonlyArray<Command.SubcommandEntry>
+): {
+  readonly flat: ReadonlyArray<Command.Any>
+  readonly groups: ReadonlyArray<SubcommandGroupInternal>
+} => {
+  const flat: Array<Command.Any> = []
+  const grouped = new Map<string | undefined, NonEmptyArray<Command.Any>>()
+
+  const addToGroup = (group: string | undefined, command: Command.Any): void => {
+    flat.push(command)
+    const existing = grouped.get(group)
+    if (existing) {
+      existing.push(command)
+    } else {
+      grouped.set(group, [command])
+    }
+  }
+
+  for (const entry of entries) {
+    if (isCommand(entry)) {
+      addToGroup(undefined, entry)
+      continue
+    }
+    for (const command of entry.commands) {
+      addToGroup(entry.group, command)
+    }
+  }
+
+  const groups: Array<SubcommandGroupInternal> = []
+  const ungroupedCommands = grouped.get(undefined)
+
+  if (ungroupedCommands && ungroupedCommands.length > 0) {
+    groups.push({ group: undefined, commands: ungroupedCommands })
+  }
+
+  for (const [group, commands] of grouped) {
+    if (group === undefined) {
+      continue
+    }
+    groups.push({ group, commands })
+  }
+
+  return { flat, groups }
+}
+
 /**
  * Adds subcommands to a command, creating a hierarchical command structure.
  *
@@ -717,7 +817,7 @@ export const withSubcommands: {
    * @since 4.0.0
    * @category combinators
    */
-  <const Subcommands extends ReadonlyArray<Command<any, any, any, any>>>(subcommands: Subcommands): <Name extends string, Input, E, R>(
+  <const Subcommands extends ReadonlyArray<Command.SubcommandEntry>>(subcommands: Subcommands): <Name extends string, Input, E, R>(
     self: Command<Name, Input, E, R>
   ) => Command<
     Name,
@@ -766,7 +866,7 @@ export const withSubcommands: {
     Input,
     E,
     R,
-    const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+    const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
   >(self: Command<Name, Input, E, R>, subcommands: Subcommands): Command<
     Name,
     Input,
@@ -778,7 +878,7 @@ export const withSubcommands: {
   Input,
   E,
   R,
-  const Subcommands extends ReadonlyArray<Command<any, any, any, any>>
+  const Subcommands extends ReadonlyArray<Command.SubcommandEntry>
 >(
   self: Command<Name, Input, E, R>,
   subcommands: Subcommands
@@ -788,10 +888,11 @@ export const withSubcommands: {
   E | ExtractSubcommandErrors<Subcommands>,
   R | Exclude<ExtractSubcommandContext<Subcommands>, CommandContext<Name>>
 > => {
-  checkForDuplicateFlags(self, subcommands)
+  const normalized = normalizeSubcommandEntries(subcommands)
+  checkForDuplicateFlags(self, normalized.flat)
 
   const impl = toImpl(self)
-  const byName = new Map(subcommands.map((s) => [s.name, toImpl(s)] as const))
+  const byName = new Map(normalized.flat.map((s) => [s.name, toImpl(s)] as const))
 
   // Internal type for routing - not exposed in public type
   type SubcommandInfo = { readonly name: string; readonly result: unknown }
@@ -832,16 +933,22 @@ export const withSubcommands: {
     name: impl.name,
     config: impl.config,
     description: impl.description,
+    shortDescription: impl.shortDescription,
+    annotations: impl.annotations,
+    examples: impl.examples,
     service: impl.service,
-    subcommands,
+    subcommands: normalized.groups,
     parse,
     handle
   })
 })
 
 // Type extractors for subcommand arrays - T[number] gives union of all elements
-type ExtractSubcommandErrors<T extends ReadonlyArray<Command<any, any, any, any>>> = Error<T[number]>
-type ExtractSubcommandContext<T extends ReadonlyArray<Command<any, any, any, any>>> = T[number] extends
+type ExtractSubcommand<T> = T extends Command<any, any, any, any> ? T
+  : T extends Command.SubcommandGroup<infer Commands> ? Commands[number]
+  : never
+type ExtractSubcommandErrors<T extends ReadonlyArray<Command.SubcommandEntry>> = Error<ExtractSubcommand<T[number]>>
+type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>> = ExtractSubcommand<T[number]> extends
   Command<any, any, any, infer R> ? R : never
 
 /**
@@ -926,6 +1033,186 @@ export const withDescription: {
   description: string
 ) => makeCommand({ ...toImpl(self), description }))
 
+/**
+ * Sets a short description for a command.
+ *
+ * Short descriptions are used when listing subcommands in help output and
+ * shell completions. If no short description is provided, the full
+ * `description` is used as a fallback.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withShortDescription: {
+  /**
+   * Sets a short description for a command.
+   *
+   * Short descriptions are used when listing subcommands in help output and
+   * shell completions. If no short description is provided, the full
+   * `description` is used as a fallback.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (shortDescription: string): <const Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Sets a short description for a command.
+   *
+   * Short descriptions are used when listing subcommands in help output and
+   * shell completions. If no short description is provided, the full
+   * `description` is used as a fallback.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, shortDescription: string): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  shortDescription: string
+) => makeCommand({ ...toImpl(self), shortDescription }))
+
+/**
+ * Adds a custom annotation to a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const annotate: {
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <I, S>(service: ServiceMap.Service<I, S>, value: NoInfer<S>): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Adds a custom annotation to a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, I, S>(
+    self: Command<Name, Input, E, R>,
+    service: ServiceMap.Service<I, S>,
+    value: NoInfer<S>
+  ): Command<Name, Input, E, R>
+} = dual(3, <Name extends string, Input, E, R, I, S>(
+  self: Command<Name, Input, E, R>,
+  service: ServiceMap.Service<I, S>,
+  value: NoInfer<S>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: ServiceMap.add(impl.annotations, service, value) })
+})
+
+/**
+ * Merges a ServiceMap of annotations into a command.
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const annotateMerge: {
+  /**
+   * Merges a ServiceMap of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <I>(annotations: ServiceMap.ServiceMap<I>): <Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Merges a ServiceMap of annotations into a command.
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <Name extends string, Input, E, R, I>(self: Command<Name, Input, E, R>, annotations: ServiceMap.ServiceMap<I>): Command<Name, Input, E, R>
+} = dual(2, <Name extends string, Input, E, R, I>(
+  self: Command<Name, Input, E, R>,
+  annotations: ServiceMap.ServiceMap<I>
+) => {
+  const impl = toImpl(self)
+  return makeCommand({ ...impl, annotations: ServiceMap.merge(impl.annotations, annotations) })
+})
+
+/**
+ * Sets usage examples for a command.
+ *
+ * Examples are exposed in structured `HelpDoc` data and rendered by the
+ * default formatter in an `EXAMPLES` section.
+ *
+ * @example
+ * ```ts
+ * import { Command } from "effect/unstable/cli"
+ *
+ * const login = Command.make("login").pipe(
+ *   Command.withExamples([
+ *     { command: "myapp login", description: "Log in with browser OAuth" },
+ *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+ *   ])
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category combinators
+ */
+export const withExamples: {
+  /**
+   * Sets usage examples for a command.
+   *
+   * Examples are exposed in structured `HelpDoc` data and rendered by the
+   * default formatter in an `EXAMPLES` section.
+   *
+   * @example
+   * ```ts
+   * import { Command } from "effect/unstable/cli"
+   *
+   * const login = Command.make("login").pipe(
+   *   Command.withExamples([
+   *     { command: "myapp login", description: "Log in with browser OAuth" },
+   *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+   *   ])
+   * )
+   * ```
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (examples: ReadonlyArray<Command.Example>): <const Name extends string, Input, E, R>(
+    self: Command<Name, Input, E, R>
+  ) => Command<Name, Input, E, R>
+  /**
+   * Sets usage examples for a command.
+   *
+   * Examples are exposed in structured `HelpDoc` data and rendered by the
+   * default formatter in an `EXAMPLES` section.
+   *
+   * @example
+   * ```ts
+   * import { Command } from "effect/unstable/cli"
+   *
+   * const login = Command.make("login").pipe(
+   *   Command.withExamples([
+   *     { command: "myapp login", description: "Log in with browser OAuth" },
+   *     { command: "myapp login --token sbp_abc123", description: "Log in with a token" }
+   *   ])
+   * )
+   * ```
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <const Name extends string, Input, E, R>(self: Command<Name, Input, E, R>, examples: ReadonlyArray<Command.Example>): Command<Name, Input, E, R>
+} = dual(2, <const Name extends string, Input, E, R>(
+  self: Command<Name, Input, E, R>,
+  examples: ReadonlyArray<Command.Example>
+) => makeCommand({ ...toImpl(self), examples }))
+
 /* ========================================================================== */
 /* Providing Services                                                         */
 /* ========================================================================== */

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,11 @@ export interface HelpDoc {
    */
   readonly flags: ReadonlyArray<FlagDoc>
 
+  /**
+   * Custom command annotations.
+   */
+  readonly annotations: ServiceMap.ServiceMap<never>
+
   /**
    * List of positional arguments for this command
    */
@@ -70,7 +80,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 +165,18 @@ export interface FlagDoc {
  *
  * @example
  * ```ts
+ * import { ServiceMap } from "effect"
  * import type { HelpDoc } from "effect/unstable/cli"
  *
  * const deploySubcommand: HelpDoc.SubcommandDoc = {
  *   name: "deploy",
+ *   shortDescription: "Deploy app",
  *   description: "Deploy the application to the cloud"
  * }
  *
  * const buildSubcommand: HelpDoc.SubcommandDoc = {
  *   name: "build",
+ *   shortDescription: undefined,
  *   description: "Build the application for production"
  * }
  *
@@ -148,8 +184,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 +202,42 @@ export interface SubcommandDoc {
    */
   readonly name: string
 
+  /**
+   * 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 +260,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/internal/command.ts

@@ -5,13 +5,14 @@
  * 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 { 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,6 +23,11 @@ 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.
@@ -29,6 +35,7 @@ import type { Command, CommandContext, Environment, ParsedTokens } from "../Comm
 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 annotations: ServiceMap.ServiceMap<never>
   readonly parse: (input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>
   readonly handle: (
     input: Input,
@@ -80,8 +87,11 @@ 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 annotations?: ServiceMap.ServiceMap<never> | undefined
   readonly description?: string | undefined
-  readonly subcommands?: ReadonlyArray<Command<any, unknown, unknown, unknown>> | undefined
+  readonly shortDescription?: 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 +99,8 @@ 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 subcommands = options.subcommands ?? []
 
   const handle = (
     input: Input,
@@ -123,8 +135,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 +158,38 @@ 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,
+          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,
+    subcommands,
     config,
     service,
     parse,
@@ -172,6 +197,9 @@ 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 }
       : {})
   })
 }
@@ -255,7 +283,15 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R>(
   // 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)
+    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
     }