effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/ai/Toolkit.ts

@@ -149,6 +149,8 @@ export interface HandlerContext<Tool extends Tool.Any> {
   /**
    * Emit a preliminary result during long-running tool calls.
    *
+   * **Details**
+   *
    * Preliminary results are streamed to the caller before the handler completes,
    * enabling real-time progress updates for lengthy operations.
    */
@@ -190,6 +192,8 @@ export type ToolsByName<Tools> = Tools extends Record<string, Tool.Any> ?
 /**
  * A utility type that maps tool names to their required handler functions.
  *
+ * **Details**
+ *
  * Handlers can return either the tool's custom failure type, an `AiErrorReason`
  * (which will be wrapped in `AiError`), or a full `AiError`.
  *
@@ -222,6 +226,8 @@ export interface WithHandler<in out Tools extends Record<string, Tool.Any>> {
   /**
    * Executes a tool call by name.
    *
+   * **Details**
+   *
    * Validates the input parameters, executes the corresponding handler, and
    * streams back both the typed result and encoded result. Streaming allows
    * handlers to emit preliminary results before completion.
@@ -461,6 +467,8 @@ const resolveInput = <Tools extends ReadonlyArray<Tool.Any>>(
 /**
  * An empty toolkit with no tools.
  *
+ * **When to use**
+ *
  * Useful as a starting point for building toolkits or as a default value. Can
  * be extended using the merge function to add tools.
  *
@@ -472,6 +480,8 @@ export const empty: Toolkit<{}> = makeProto({})
 /**
  * Creates a new toolkit from the specified tools.
  *
+ * **Details**
+ *
  * This is the primary constructor for creating toolkits. It accepts multiple
  * tools and organizes them into a toolkit that can be provided to AI language
  * models.
@@ -541,6 +551,8 @@ export type MergedTools<Toolkits extends ReadonlyArray<Any>> = SimplifyRecord<
 /**
  * Merges multiple toolkits into a single toolkit.
  *
+ * **Details**
+ *
  * Combines all tools from the provided toolkits into one unified toolkit.
  * If there are naming conflicts, tools from later toolkits will override
  * tools from earlier ones.

package/src/unstable/cli/Argument.ts

@@ -41,10 +41,12 @@ import type * as Primitive from "./Primitive.ts"
 /**
  * Represents a positional command-line argument.
  *
- * Note: `boolean` is intentionally omitted from Argument constructors.
- * Positional boolean arguments are ambiguous in CLI design since there's
- * no flag name to negate (e.g., `--no-verbose`). Use Flag.boolean instead,
- * or use Argument.choice with explicit "true"/"false" strings if needed.
+ * **Gotchas**
+ *
+ * `boolean` is intentionally omitted from Argument constructors. Positional
+ * boolean arguments are ambiguous in CLI design since there is no flag name to
+ * negate (for example, `--no-verbose`). Use Flag.boolean instead, or use
+ * Argument.choice with explicit "true" / "false" strings if needed.
  *
  * @category models
  * @since 4.0.0
@@ -229,6 +231,8 @@ export const fileText = (name: string): Argument<string> => Param.fileText(Param
 /**
  * Creates a positional argument that reads a file and parses its content.
  *
+ * **Details**
+ *
  * The parser is chosen from the explicit `format` option or, when omitted, the
  * file extension. The parsed value is `unknown`; use `fileSchema` when the
  * parsed content should also be decoded with a Schema.
@@ -1043,6 +1047,8 @@ export const choiceWithValue = <const Choices extends ReadonlyArray<readonly [st
 /**
  * Sets a custom metavar (placeholder name) for the argument in help documentation.
  *
+ * **Details**
+ *
  * The metavar is displayed in usage text to indicate what value the user should provide.
  * For example, `<FILE>` shows `FILE` as the metavar.
  *
@@ -1067,6 +1073,8 @@ export const withMetavar: {
   /**
    * Sets a custom metavar (placeholder name) for the argument in help documentation.
    *
+   * **Details**
+   *
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `<FILE>` shows `FILE` as the metavar.
    *
@@ -1091,6 +1099,8 @@ export const withMetavar: {
   /**
    * Sets a custom metavar (placeholder name) for the argument in help documentation.
    *
+   * **Details**
+   *
    * The metavar is displayed in usage text to indicate what value the user should provide.
    * For example, `<FILE>` shows `FILE` as the metavar.
    *

package/src/unstable/cli/CliError.ts

@@ -494,6 +494,8 @@ export class UserError extends Schema.ErrorClass<UserError>(`${TypeId}/UserError
 /**
  * Schema for concrete CLI errors that can be reported together with help output.
  *
+ * **Details**
+ *
  * This excludes `ShowHelp` itself, allowing parse and validation errors to be
  * stored in `ShowHelp.errors` without nesting another help-control value.
  *
@@ -523,6 +525,8 @@ export const NonShowHelpErrors: Schema.Union<
 /**
  * Type of CLI errors that are not `ShowHelp`.
  *
+ * **Details**
+ *
  * These errors can be accumulated and attached to `ShowHelp.errors` when the
  * runner should display help along with the underlying parse or validation
  * failures.
@@ -535,6 +539,8 @@ export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
 /**
  * Control-flow value that asks the CLI runner to render help for a command path.
  *
+ * **Details**
+ *
  * It is used for explicit help requests and for parse or validation failures
  * that should be shown with help text. When `errors` is non-empty, the runtime
  * exit code is `1`; otherwise it is `0`.

package/src/unstable/cli/Command.ts

@@ -62,7 +62,10 @@ import * as Param from "./Param.ts"
 /**
  * Represents a CLI command with its configuration, handler, and metadata.
  *
+ * **Details**
+ *
  * Commands are the core building blocks of CLI applications. They define:
+ *
  * - The command name and description
  * - Configuration including flags and arguments
  * - Handler function for execution
@@ -152,6 +155,13 @@ export interface Command<in out Name extends string, in Input, out ContextInput
    * Custom annotations associated with this command.
    */
   readonly annotations: Context.Context<never>
+
+  /**
+   * Whether this command is hidden from parent help output, shell
+   * completions, and unknown-subcommand suggestions. Hidden commands still
+   * parse and execute normally when invoked by exact name.
+   */
+  readonly hidden: boolean
 }
 
 /**
@@ -164,6 +174,8 @@ export declare namespace Command {
   /**
    * Type-level variance marker for `Command`.
    *
+   * **Details**
+   *
    * The parsed input type is contravariant, while the command error and service
    * requirement types are covariant.
    *
@@ -190,10 +202,11 @@ export declare namespace Command {
   /**
    * Configuration object for defining command flags, arguments, and nested structures.
    *
-   * Command.Config allows you to specify:
-   * - Individual flags and arguments using Param types
-   * - Nested configuration objects for organization
-   * - Arrays of parameters for repeated elements
+   * **Details**
+   *
+   * `Command.Config` can contain individual flags and arguments using `Param`
+   * types, nested configuration objects for organization, and arrays of
+   * parameters for repeated elements.
    *
    * **Example** (Configuring command input)
    *
@@ -234,6 +247,8 @@ export declare namespace Command {
   /**
    * Configuration shape accepted by `Command.withSharedFlags`.
    *
+   * **Details**
+   *
    * Only flags are allowed here; arguments are intentionally excluded.
    *
    * @category models
@@ -255,6 +270,8 @@ export declare namespace Command {
     /**
      * Infers the TypeScript type from a Command.Config structure.
      *
+     * **Details**
+     *
      * This type utility extracts the final configuration type that handlers will receive,
      * preserving the nested structure while converting Param types to their values.
      *
@@ -319,6 +336,7 @@ export declare namespace Command {
       readonly commands: NonEmptyReadonlyArray<Command.Any>
     }>
     readonly annotations: Context.Context<never>
+    readonly hidden: boolean
   }
 
   /**
@@ -344,6 +362,8 @@ export declare namespace Command {
 /**
  * Services required by CLI parsing and execution.
  *
+ * **Details**
+ *
  * This includes file-system and path services for arguments, terminal and
  * stdio services for running commands, and child-process spawning for
  * process-related CLI features.
@@ -371,6 +391,8 @@ export type Error<C> = C extends Command<
 /**
  * Service context for a specific command, enabling subcommands to access their parent's parsed configuration.
  *
+ * **Details**
+ *
  * When a subcommand handler needs access to flags or arguments from a parent command,
  * it can yield the parent command directly to retrieve its config. This is powered by
  * Effect's service system - each command automatically creates a service that provides
@@ -444,6 +466,8 @@ export const isCommand = (u: unknown): u is Command.Any => Predicate.hasProperty
  * Creates a `Command` from a name, an optional configuration, and an optional
  * handler.
  *
+ * **Details**
+ *
  * Use `withDescription` and related metadata combinators to add help text. The
  * overloads support simple commands, configured commands, and commands with
  * effectful handlers.
@@ -504,6 +528,8 @@ export const make: {
    * Creates a `Command` from a name, an optional configuration, and an optional
    * handler.
    *
+   * **Details**
+   *
    * Use `withDescription` and related metadata combinators to add help text. The
    * overloads support simple commands, configured commands, and commands with
    * effectful handlers.
@@ -565,6 +591,8 @@ export const make: {
    * Creates a `Command` from a name, an optional configuration, and an optional
    * handler.
    *
+   * **Details**
+   *
    * Use `withDescription` and related metadata combinators to add help text. The
    * overloads support simple commands, configured commands, and commands with
    * effectful handlers.
@@ -626,6 +654,8 @@ export const make: {
    * Creates a `Command` from a name, an optional configuration, and an optional
    * handler.
    *
+   * **Details**
+   *
    * Use `withDescription` and related metadata combinators to add help text. The
    * overloads support simple commands, configured commands, and commands with
    * effectful handlers.
@@ -850,6 +880,8 @@ const normalizeSubcommandEntries = (
 /**
  * Adds subcommands to a command, creating a hierarchical command structure.
  *
+ * **Details**
+ *
  * Subcommands can access their parent's parsed configuration by yielding the parent
  * command within their handler. This enables shared parent flags that affect
  * all subcommands.
@@ -890,6 +922,8 @@ export const withSubcommands: {
   /**
    * Adds subcommands to a command, creating a hierarchical command structure.
    *
+   * **Details**
+   *
    * Subcommands can access their parent's parsed configuration by yielding the parent
    * command within their handler. This enables shared parent flags that affect
    * all subcommands.
@@ -938,6 +972,8 @@ export const withSubcommands: {
   /**
    * Adds subcommands to a command, creating a hierarchical command structure.
    *
+   * **Details**
+   *
    * Subcommands can access their parent's parsed configuration by yielding the parent
    * command within their handler. This enables shared parent flags that affect
    * all subcommands.
@@ -1068,6 +1104,8 @@ export const withSubcommands: {
 /**
  * Adds flags that are inherited by subcommands.
  *
+ * **Details**
+ *
  * Shared flags are available to this command's handler and to descendant
  * handlers via `yield* parentCommand`. Shared flags are accepted both before
  * and after a selected subcommand name (npm-style).
@@ -1079,6 +1117,8 @@ export const withSharedFlags: {
   /**
    * Adds flags that are inherited by subcommands.
    *
+   * **Details**
+   *
    * Shared flags are available to this command's handler and to descendant
    * handlers via `yield* parentCommand`. Shared flags are accepted both before
    * and after a selected subcommand name (npm-style).
@@ -1098,6 +1138,8 @@ export const withSharedFlags: {
   /**
    * Adds flags that are inherited by subcommands.
    *
+   * **Details**
+   *
    * Shared flags are available to this command's handler and to descendant
    * handlers via `yield* parentCommand`. Shared flags are accepted both before
    * and after a selected subcommand name (npm-style).
@@ -1181,6 +1223,8 @@ export const withSharedFlags: {
 /**
  * Declares global flags for a command scope.
  *
+ * **Details**
+ *
  * Declared global flags apply to the command and all of its descendants.
  *
  * @category combinators
@@ -1190,6 +1234,8 @@ export const withGlobalFlags: {
   /**
    * Declares global flags for a command scope.
    *
+   * **Details**
+   *
    * Declared global flags apply to the command and all of its descendants.
    *
    * @category combinators
@@ -1201,6 +1247,8 @@ export const withGlobalFlags: {
   /**
    * Declares global flags for a command scope.
    *
+   * **Details**
+   *
    * Declared global flags apply to the command and all of its descendants.
    *
    * @category combinators
@@ -1248,6 +1296,8 @@ type ExtractSubcommandContext<T extends ReadonlyArray<Command.SubcommandEntry>>
 /**
  * Sets the description for a command.
  *
+ * **Details**
+ *
  * Descriptions provide users with information about what the command does
  * when they view help documentation.
  *
@@ -1274,6 +1324,8 @@ export const withDescription: {
   /**
    * Sets the description for a command.
    *
+   * **Details**
+   *
    * Descriptions provide users with information about what the command does
    * when they view help documentation.
    *
@@ -1302,6 +1354,8 @@ export const withDescription: {
   /**
    * Sets the description for a command.
    *
+   * **Details**
+   *
    * Descriptions provide users with information about what the command does
    * when they view help documentation.
    *
@@ -1333,6 +1387,8 @@ export const withDescription: {
 /**
  * Sets a short description for a command.
  *
+ * **Details**
+ *
  * 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.
@@ -1344,6 +1400,8 @@ export const withShortDescription: {
   /**
    * Sets a short description for a command.
    *
+   * **Details**
+   *
    * 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.
@@ -1357,6 +1415,8 @@ export const withShortDescription: {
   /**
    * Sets a short description for a command.
    *
+   * **Details**
+   *
    * 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.
@@ -1373,6 +1433,8 @@ export const withShortDescription: {
 /**
  * Sets an alias for a command.
  *
+ * **Details**
+ *
  * Aliases are accepted as alternate subcommand names during parsing and are
  * shown in help output as `name, alias`.
  *
@@ -1383,6 +1445,8 @@ export const withAlias: {
   /**
    * Sets an alias for a command.
    *
+   * **Details**
+   *
    * Aliases are accepted as alternate subcommand names during parsing and are
    * shown in help output as `name, alias`.
    *
@@ -1395,6 +1459,8 @@ export const withAlias: {
   /**
    * Sets an alias for a command.
    *
+   * **Details**
+   *
    * Aliases are accepted as alternate subcommand names during parsing and are
    * shown in help output as `name, alias`.
    *
@@ -1407,6 +1473,39 @@ export const withAlias: {
   alias: string
 ) => makeCommand({ ...toImpl(self), alias }))
 
+/**
+ * Hides a subcommand from parent help output, shell completions, and
+ * "did you mean?" suggestions while keeping it fully invocable by exact name.
+ *
+ * **When to use**
+ *
+ * Use this for experimental or internal subcommands that should be accepted but
+ * not advertised on the public CLI surface.
+ *
+ * **Example** (Hiding a subcommand)
+ *
+ * ```ts
+ * import { Command } from "effect/unstable/cli"
+ *
+ * // `experimental` still runs when invoked as `mycli experimental`,
+ * // but it does not appear under SUBCOMMANDS in `mycli --help`.
+ * const experimental = Command.make("experimental").pipe(
+ *   Command.withHidden
+ * )
+ *
+ * const root = Command.make("mycli").pipe(
+ *   Command.withSubcommands([experimental])
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export const withHidden = <const Name extends string, Input, E, R, ContextInput>(
+  self: Command<Name, Input, ContextInput, E, R>
+): Command<Name, Input, ContextInput, E, R> =>
+  makeCommand({ ...toImpl(self), hidden: true }) as Command<Name, Input, ContextInput, E, R>
+
 /**
  * Adds a custom annotation to a command.
  *
@@ -1480,6 +1579,8 @@ export const annotateMerge: {
 /**
  * Sets usage examples for a command.
  *
+ * **Details**
+ *
  * Examples are exposed in structured `HelpDoc` data and rendered by the
  * default formatter in an `EXAMPLES` section.
  *
@@ -1503,6 +1604,8 @@ export const withExamples: {
   /**
    * Sets usage examples for a command.
    *
+   * **Details**
+   *
    * Examples are exposed in structured `HelpDoc` data and rendered by the
    * default formatter in an `EXAMPLES` section.
    *
@@ -1528,6 +1631,8 @@ export const withExamples: {
   /**
    * Sets usage examples for a command.
    *
+   * **Details**
+   *
    * Examples are exposed in structured `HelpDoc` data and rendered by the
    * default formatter in an `EXAMPLES` section.
    *
@@ -1888,8 +1993,11 @@ const showHelp = <Name extends string, Input, E, R, ContextInput>(
 /**
  * Runs a command using the arguments supplied by the `Stdio` service.
  *
- * Use `runWith` when you need to execute a command with an explicit argument
- * array, such as in tests.
+ * **When to use**
+ *
+ * Use `run` at an application entry point when arguments should come from
+ * `Stdio`; use `runWith` when you need an explicit argument array, such as in
+ * tests.
  *
  * **Example** (Running commands with standard input)
  *
@@ -1917,8 +2025,11 @@ export const run: {
   /**
    * Runs a command using the arguments supplied by the `Stdio` service.
    *
-   * Use `runWith` when you need to execute a command with an explicit argument
-   * array, such as in tests.
+   * **When to use**
+   *
+   * Use `run` at an application entry point when arguments should come from
+   * `Stdio`; use `runWith` when you need an explicit argument array, such as in
+   * tests.
    *
    * **Example** (Running commands with standard input)
    *
@@ -1952,8 +2063,11 @@ export const run: {
   /**
    * Runs a command using the arguments supplied by the `Stdio` service.
    *
-   * Use `runWith` when you need to execute a command with an explicit argument
-   * array, such as in tests.
+   * **When to use**
+   *
+   * Use `run` at an application entry point when arguments should come from
+   * `Stdio`; use `runWith` when you need an explicit argument array, such as in
+   * tests.
    *
    * **Example** (Running commands with standard input)
    *
@@ -1997,9 +2111,11 @@ export const run: {
   ))
 
 /**
- * Runs a command with explicitly provided arguments instead of using process.argv.
+ * Runs a command with explicitly provided arguments instead of using arguments from `Stdio`.
+ *
+ * **When to use**
  *
- * This function is useful for testing CLI applications or when you want to
+ * Use this function for testing CLI applications or when you want to
  * programmatically execute commands with specific arguments.
  *
  * **Example** (Running commands with explicit arguments)

package/src/unstable/cli/Flag.ts

@@ -253,8 +253,10 @@ export const directory = (name: string, options?: {
 }): Flag<string> => Param.directory(Param.flagKind, name, options)
 
 /**
- * Creates a string flag whose parsed value is wrapped in `Redacted.Redacted`
- * so stringification and logging redact the value.
+ * Creates a string flag whose parsed value is wrapped in `Redacted.Redacted` so
+ * stringification and logging redact the value.
+ *
+ * **Gotchas**
  *
  * Values supplied on the command line may still be visible to the operating
  * system or shell history.
@@ -302,6 +304,8 @@ export const fileText = (name: string): Flag<string> => Param.fileText(Param.fla
 /**
  * Creates a flag that reads and parses the content of the specified file.
  *
+ * **Details**
+ *
  * The parser that is utilized will depend on the specified `format`, or the
  * extension of the file passed on the command-line if no `format` is specified.
  *
@@ -355,10 +359,15 @@ export const fileSchema = <A>(
 
 /**
  * Creates a flag that parses key=value pairs.
- * Useful for options that accept configuration values.
  *
- * Note: Requires at least one key=value pair. Multiple pairs are merged
- * into a single record.
+ * **When to use**
+ *
+ * Use this for options that accept configuration values.
+ *
+ * **Details**
+ *
+ * Requires at least one key=value pair. Multiple pairs are merged into a single
+ * record.
  *
  * **Example** (Parsing key-value pairs)
  *
@@ -553,8 +562,10 @@ export const withDescription: {
 /**
  * Sets a custom metavar (placeholder name) for the flag in help documentation.
  *
- * The metavar is displayed in usage text to indicate what value the user should provide.
- * For example, `--output FILE` shows `FILE` as the metavar.
+ * **Details**
+ *
+ * The metavar is displayed in usage text to indicate what value the user should
+ * provide. For example, `--output FILE` shows `FILE` as the metavar.
  *
  * **Example** (Setting metavars)
  *
@@ -584,8 +595,10 @@ export const withMetavar: {
   /**
    * Sets a custom metavar (placeholder name) for the flag in help documentation.
    *
-   * The metavar is displayed in usage text to indicate what value the user should provide.
-   * For example, `--output FILE` shows `FILE` as the metavar.
+   * **Details**
+   *
+   * The metavar is displayed in usage text to indicate what value the user should
+   * provide. For example, `--output FILE` shows `FILE` as the metavar.
    *
    * **Example** (Setting metavars)
    *
@@ -615,8 +628,10 @@ export const withMetavar: {
   /**
    * Sets a custom metavar (placeholder name) for the flag in help documentation.
    *
-   * The metavar is displayed in usage text to indicate what value the user should provide.
-   * For example, `--output FILE` shows `FILE` as the metavar.
+   * **Details**
+   *
+   * The metavar is displayed in usage text to indicate what value the user should
+   * provide. For example, `--output FILE` shows `FILE` as the metavar.
    *
    * **Example** (Setting metavars)
    *
@@ -645,9 +660,11 @@ export const withMetavar: {
  * Hides a flag from generated help output and shell completions while keeping
  * it fully parseable on the command line.
  *
- * Useful for experimental or internal flags that should be accepted but not
- * advertised — for example, `--experimental-foo`, debug toggles, or escape
- * hatches that are not yet committed to the public CLI surface.
+ * **When to use**
+ *
+ * Use this for experimental or internal flags that should be accepted but not
+ * advertised, such as `--experimental-foo`, debug toggles, or escape hatches
+ * that are not yet committed to the public CLI surface.
  *
  * **Example** (Hiding a flag from help)
  *