effect 4.0.0-beta.3 → 4.0.0-beta.31

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/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,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/Primitive.ts

@@ -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"

package/src/unstable/cli/Prompt.ts

@@ -2489,6 +2489,11 @@ const processNumberBackspace = (state: NumberState) => {
   }))
 }
 
+const processNumberClear = (state: NumberState) =>
+  Effect.succeed(Action.NextFrame({
+    state: { ...state, cursor: 0, value: "", error: undefined }
+  }))
+
 const defaultIntProcessor = (input: string, state: NumberState) => {
   if (state.value.length === 0 && input === "-") {
     return Effect.succeed(Action.NextFrame({
@@ -2542,6 +2547,9 @@ const handleRenderInteger = (options: IntegerOptionsReq) => {
 
 const handleProcessInteger = (options: IntegerOptionsReq) => {
   return (input: Terminal.UserInput, state: NumberState) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processNumberClear(state)
+    }
     switch (input.key.name) {
       case "backspace": {
         return processNumberBackspace(state)
@@ -2612,6 +2620,9 @@ const handleRenderFloat = (options: FloatOptionsReq) => {
 
 const handleProcessFloat = (options: FloatOptionsReq) => {
   return (input: Terminal.UserInput, state: NumberState) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processNumberClear(state)
+    }
     switch (input.key.name) {
       case "backspace": {
         return processNumberBackspace(state)
@@ -2962,6 +2973,9 @@ const processAutoCompleteBackspace = <A>(state: AutoCompleteState, options: Auto
   return Effect.succeed(Action.NextFrame({ state: updateAutoCompleteState(state, options, query) }))
 }
 
+const processAutoCompleteClear = <A>(state: AutoCompleteState, options: AutoCompleteOptionsReq<A>) =>
+  Effect.succeed(Action.NextFrame({ state: updateAutoCompleteState(state, options, "") }))
+
 const processAutoCompleteInput = <A>(input: string, state: AutoCompleteState, options: AutoCompleteOptionsReq<A>) => {
   if (input.length === 0) {
     return Effect.succeed(Action.Beep())
@@ -3045,6 +3059,9 @@ const handleSelectProcess = <A>(options: SelectOptionsReq<A>) => {
 
 const handleAutoCompleteProcess = <A>(options: AutoCompleteOptionsReq<A>) => {
   return (input: Terminal.UserInput, state: AutoCompleteState) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processAutoCompleteClear(state, options)
+    }
     switch (input.key.name) {
       case "k":
       case "up": {
@@ -3091,10 +3108,6 @@ interface TextState {
   readonly error: string | undefined
 }
 
-const getValue = (state: TextState, options: TextOptionsReq): string => {
-  return state.value.length > 0 ? state.value : options.default
-}
-
 const renderClearScreen = Effect.fnUntraced(function*(state: TextState, options: TextOptionsReq) {
   const terminal = yield* Terminal.Terminal
   const columns = yield* terminal.columns
@@ -3115,7 +3128,7 @@ const renderTextInput = (
   submitted: boolean,
   renderOptions?: RenderOptions | undefined
 ) => {
-  const text = getValue(nextState, options)
+  const text = nextState.value
   if (renderOptions?.plain === true) {
     switch (options.type) {
       case "hidden": {
@@ -3217,6 +3230,13 @@ const processTextBackspace = (state: TextState) => {
   )
 }
 
+const processTextClear = (state: TextState) =>
+  Effect.succeed(
+    Action.NextFrame({
+      state: { ...state, cursor: 0, value: "", error: undefined }
+    })
+  )
+
 const processTextCursorLeft = (state: TextState) => {
   if (state.cursor <= 0) {
     return Effect.succeed(Action.Beep())
@@ -3245,11 +3265,10 @@ const processTab = (state: TextState, options: TextOptionsReq) => {
   if (state.value === options.default) {
     return Effect.succeed(Action.Beep())
   }
-  const value = getValue(state, options)
-  const cursor = value.length
+  const value = state.value.length === 0 ? options.default : state.value
   return Effect.succeed(
     Action.NextFrame({
-      state: { ...state, value, cursor, error: undefined }
+      state: { ...state, value, cursor: value.length, error: undefined }
     })
   )
 }
@@ -3278,6 +3297,9 @@ const handleTextRender = (options: TextOptionsReq) => {
 
 const handleTextProcess = (options: TextOptionsReq) => {
   return (input: Terminal.UserInput, state: TextState) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processTextClear(state)
+    }
     switch (input.key.name) {
       case "backspace": {
         return processTextBackspace(state)
@@ -3290,7 +3312,7 @@ const handleTextProcess = (options: TextOptionsReq) => {
       }
       case "enter":
       case "return": {
-        const value = getValue(state, options)
+        const value = state.value
         return Effect.match(options.validate(value), {
           onFailure: (error) =>
             Action.NextFrame({

package/src/unstable/cli/index.ts

@@ -24,11 +24,21 @@ export * as CliOutput from "./CliOutput.ts"
  */
 export * as Command from "./Command.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as Completions from "./Completions.ts"
+
 /**
  * @since 4.0.0
  */
 export * as Flag from "./Flag.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as GlobalFlag from "./GlobalFlag.ts"
+
 /**
  * @since 4.0.0
  */