effect 4.0.0-beta.3 → 4.0.0-beta.30

package/dist/unstable/cli/GlobalFlag.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @since 4.0.0
+ */
+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 type * as Command from "./Command.ts";
+import * as Flag from "./Flag.ts";
+/**
+ * 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
+     */
+    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>;
+/**
+ * Creates an Action flag that performs a side effect and exits.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export declare const action: <A>(options: {
+    readonly flag: Flag.Flag<A>;
+    readonly run: (value: A, context: HandlerContext) => Effect.Effect<void>;
+}) => Action<A>;
+/**
+ * Creates a Setting flag that configures the command handler's environment.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export declare const setting: <const Id extends string>(id: Id) => <A>(options: {
+    readonly flag: Flag.Flag<A>;
+}) => Setting<Id, A>;
+/**
+ * The `--help` / `-h` global flag.
+ * Shows help documentation for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export declare const Help: Action<boolean>;
+/**
+ * The `--version` global flag.
+ * Shows version information for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export declare const Version: Action<boolean>;
+/**
+ * The `--completions` global flag.
+ * Prints shell completion script for the given shell.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export declare const Completions: Action<Option.Option<"bash" | "zsh" | "fish">>;
+/**
+ * The `--log-level` global flag.
+ * Sets the minimum log level for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export declare const LogLevel: Setting<"log-level", Option.Option<LogLevelType>>;
+/**
+ * Built-in global flags in default precedence order.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export declare const BuiltIns: ReadonlyArray<GlobalFlag<any>>;
+/**
+ * Built-in setting context identifiers.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export type BuiltInSettingContext = Setting.Identifier<"log-level">;
+//# sourceMappingURL=GlobalFlag.d.ts.map

package/dist/unstable/cli/GlobalFlag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalFlag.d.ts","sourceRoot":"","sources":["../../../src/unstable/cli/GlobalFlag.ts"],"names":[],"mappings":"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"}

package/dist/unstable/cli/GlobalFlag.js

@@ -0,0 +1,118 @@
+/**
+ * @since 4.0.0
+ */
+import * as Console from "../../Console.js";
+import * as Effect from "../../Effect.js";
+import * as Option from "../../Option.js";
+import * as ServiceMap from "../../ServiceMap.js";
+import * as CliOutput from "./CliOutput.js";
+import * as Flag from "./Flag.js";
+/* ========================================================================== */
+/* Constructors                                                               */
+/* ========================================================================== */
+/**
+ * Creates an Action flag that performs a side effect and exits.
+ *
+ * @since 4.0.0
+ * @category constructors
+ */
+export const action = options => ({
+  _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 = id => options => {
+  settingIdCounter += 1;
+  const ref = ServiceMap.Service(`effect/unstable/cli/GlobalFlag/${id}/${settingIdCounter}`);
+  return Object.assign(ref, {
+    _tag: "Setting",
+    id,
+    flag: options.flag
+  });
+};
+let settingIdCounter = 0;
+/* ========================================================================== */
+/* Built-in Flag References                                                   */
+/* ========================================================================== */
+import * as CommandDescriptor from "./internal/completions/CommandDescriptor.js";
+import * as CompletionsInternal from "./internal/completions/Completions.js";
+import * as HelpInternal from "./internal/help.js";
+/**
+ * The `--help` / `-h` global flag.
+ * Shows help documentation for the command.
+ *
+ * @since 4.0.0
+ * @category references
+ */
+export const Help = /*#__PURE__*/action({
+  flag: /*#__PURE__*/Flag.boolean("help").pipe(/*#__PURE__*/Flag.withAlias("h"), /*#__PURE__*/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 = /*#__PURE__*/action({
+  flag: /*#__PURE__*/Flag.boolean("version").pipe(/*#__PURE__*/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 = /*#__PURE__*/action({
+  flag: /*#__PURE__*/Flag.choice("completions", ["bash", "zsh", "fish", "sh"]).pipe(Flag.optional, /*#__PURE__*/Flag.map(v => Option.map(v, s => s === "sh" ? "bash" : s)), /*#__PURE__*/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 = /*#__PURE__*/setting("log-level")({
+  flag: /*#__PURE__*/Flag.choiceWithValue("log-level", [["all", "All"], ["trace", "Trace"], ["debug", "Debug"], ["info", "Info"], ["warn", "Warn"], ["warning", "Warn"], ["error", "Error"], ["fatal", "Fatal"], ["none", "None"]]).pipe(Flag.optional, /*#__PURE__*/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 = [Help, Version, Completions, LogLevel];
+//# sourceMappingURL=GlobalFlag.js.map

package/dist/unstable/cli/GlobalFlag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlobalFlag.js","names":["Console","Effect","Option","ServiceMap","CliOutput","Flag","action","options","_tag","flag","run","setting","id","settingIdCounter","ref","Service","Object","assign","CommandDescriptor","CompletionsInternal","HelpInternal","Help","boolean","pipe","withAlias","withDescription","_","command","commandPath","gen","formatter","Formatter","helpDoc","getHelpForCommandPath","BuiltIns","log","formatHelpDoc","Version","version","formatVersion","name","Completions","choice","optional","map","v","s","shell","isNone","descriptor","fromCommand","generate","value","LogLevel","choiceWithValue"],"sources":["../../../src/unstable/cli/GlobalFlag.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/unstable/cli/HelpDoc.d.ts

@@ -1,6 +1,8 @@
 /**
  * @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
@@ -8,11 +10,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",
@@ -58,6 +62,14 @@ export interface HelpDoc {
      * List of available flags/options for this command
      */
     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
      */
@@ -65,7 +77,27 @@ 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;
 }
 /**
  * Documentation for a single command-line flag/option
@@ -121,15 +153,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"
  * }
  *
@@ -137,8 +174,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]
+ *   }]
  * }
  * ```
  *
@@ -150,16 +191,42 @@ export interface SubcommandDoc {
      * Name of the subcommand
      */
     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 = {
@@ -182,6 +249,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/dist/unstable/cli/HelpDoc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HelpDoc.d.ts","sourceRoot":"","sources":["../../../src/unstable/cli/HelpDoc.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAEtC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAErC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B"}
+{"version":3,"file":"HelpDoc.d.ts","sourceRoot":"","sources":["../../../src/unstable/cli/HelpDoc.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,KAAK,KAAK,UAAU,MAAM,qBAAqB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAEtC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAE7C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IAElD;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAErC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;IAExD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;IAE7C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAA;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAExC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAE1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B"}

package/dist/unstable/cli/Primitive.d.ts

@@ -407,7 +407,7 @@ export declare const keyValuePair: Primitive<Record<string, string>>;
  *
  * 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/dist/unstable/cli/Primitive.js

@@ -446,7 +446,7 @@ export const keyValuePair = /*#__PURE__*/makePrimitive("KeyValuePair", /*#__PURE
  *
  * 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/dist/unstable/cli/Prompt.js

@@ -1647,6 +1647,14 @@ const processNumberBackspace = state => {
     }
   }));
 };
+const processNumberClear = state => Effect.succeed(Action.NextFrame({
+  state: {
+    ...state,
+    cursor: 0,
+    value: "",
+    error: undefined
+  }
+}));
 const defaultIntProcessor = (input, state) => {
   if (state.value.length === 0 && input === "-") {
     return Effect.succeed(Action.NextFrame({
@@ -1709,6 +1717,9 @@ const handleRenderInteger = options => {
 };
 const handleProcessInteger = options => {
   return (input, state) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processNumberClear(state);
+    }
     switch (input.key.name) {
       case "backspace":
         {
@@ -1781,6 +1792,9 @@ const handleRenderFloat = options => {
 };
 const handleProcessFloat = options => {
   return (input, state) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processNumberClear(state);
+    }
     switch (input.key.name) {
       case "backspace":
         {
@@ -2053,6 +2067,9 @@ const processAutoCompleteBackspace = (state, options) => {
     state: updateAutoCompleteState(state, options, query)
   }));
 };
+const processAutoCompleteClear = (state, options) => Effect.succeed(Action.NextFrame({
+  state: updateAutoCompleteState(state, options, "")
+}));
 const processAutoCompleteInput = (input, state, options) => {
   if (input.length === 0) {
     return Effect.succeed(Action.Beep());
@@ -2149,6 +2166,9 @@ const handleSelectProcess = options => {
 };
 const handleAutoCompleteProcess = options => {
   return (input, state) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processAutoCompleteClear(state, options);
+    }
     switch (input.key.name) {
       case "k":
       case "up":
@@ -2189,9 +2209,6 @@ const handleAutoCompleteProcess = options => {
     }
   };
 };
-const getValue = (state, options) => {
-  return state.value.length > 0 ? state.value : options.default;
-};
 const renderClearScreen = /*#__PURE__*/Effect.fnUntraced(function* (state, options) {
   const terminal = yield* Terminal.Terminal;
   const columns = yield* terminal.columns;
@@ -2206,7 +2223,7 @@ const renderClearScreen = /*#__PURE__*/Effect.fnUntraced(function* (state, optio
   return clearOutput + resetCurrentLine;
 });
 const renderTextInput = (nextState, options, submitted, renderOptions) => {
-  const text = getValue(nextState, options);
+  const text = nextState.value;
   if (renderOptions?.plain === true) {
     switch (options.type) {
       case "hidden":
@@ -2292,6 +2309,14 @@ const processTextBackspace = state => {
     }
   }));
 };
+const processTextClear = state => Effect.succeed(Action.NextFrame({
+  state: {
+    ...state,
+    cursor: 0,
+    value: "",
+    error: undefined
+  }
+}));
 const processTextCursorLeft = state => {
   if (state.cursor <= 0) {
     return Effect.succeed(Action.Beep());
@@ -2322,13 +2347,12 @@ const processTab = (state, options) => {
   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,
+      cursor: value.length,
       error: undefined
     }
   }));
@@ -2360,6 +2384,9 @@ const handleTextRender = options => {
 };
 const handleTextProcess = options => {
   return (input, state) => {
+    if (input.key.ctrl && input.key.name === "u") {
+      return processTextClear(state);
+    }
     switch (input.key.name) {
       case "backspace":
         {
@@ -2376,7 +2403,7 @@ const handleTextProcess = options => {
       case "enter":
       case "return":
         {
-          const value = getValue(state, options);
+          const value = state.value;
           return Effect.match(options.validate(value), {
             onFailure: error => Action.NextFrame({
               state: {