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

package/src/unstable/ai/index.ts

@@ -280,7 +280,7 @@ export * as McpServer from "./McpServer.ts"
  *
  * declare const myAnthropicLayer: Layer.Layer<LanguageModel.LanguageModel>
  *
- * const anthropicModel = Model.make("anthropic", myAnthropicLayer)
+ * const anthropicModel = Model.make("anthropic", "claude-3-5-haiku", myAnthropicLayer)
  *
  * const program = Effect.gen(function*() {
  *   const response = yield* LanguageModel.generateText({

package/src/unstable/ai/internal/codec-transformer.ts

@@ -1,5 +1,4 @@
 import * as Schema from "../../../Schema.ts"
-import * as ServiceMap from "../../../ServiceMap.ts"
 import type { CodecTransformer } from "../LanguageModel.ts"
 
 /** @internal */
@@ -11,9 +10,3 @@ export const defaultCodecTransformer: CodecTransformer = (codec) => {
   }
   return { codec, jsonSchema }
 }
-
-/** @internal */
-export const CurrentCodecTransformer = ServiceMap.Reference(
-  "effect/unstable/ai/CodecTransformer",
-  { defaultValue: (): CodecTransformer => defaultCodecTransformer }
-)

package/src/unstable/cli/CliError.ts

@@ -2,6 +2,7 @@
  * @since 4.0.0
  */
 import * as Predicate from "../../Predicate.ts"
+import * as Runtime from "../../Runtime.ts"
 import * as Schema from "../../Schema.ts"
 
 /**
@@ -107,7 +108,7 @@ export type CliError =
  * // In CLI parsing context
  * const parseCommand = Effect.gen(function*() {
  *   // If parsing encounters unknown flag
- *   return yield* Effect.fail(unrecognizedError)
+ *   return yield* unrecognizedError
  * })
  * ```
  *
@@ -200,7 +201,7 @@ export class DuplicateOption extends Schema.ErrorClass(`${TypeId}/DuplicateOptio
  *   Effect.gen(function*() {
  *     const apiKey = options["api-key"]
  *     if (!apiKey) {
- *       return yield* Effect.fail(missingOptionError)
+ *       return yield* missingOptionError
  *     }
  *     return apiKey
  *   })
@@ -245,7 +246,7 @@ export class MissingOption extends Schema.ErrorClass(`${TypeId}/MissingOption`)(
  * const parseArguments = (args: Array<string>) =>
  *   Effect.gen(function*() {
  *     if (args.length === 0) {
- *       return yield* Effect.fail(missingArgError)
+ *       return yield* missingArgError
  *     }
  *     return args[0]
  *   })
@@ -353,7 +354,7 @@ export class InvalidValue extends Schema.ErrorClass(`${TypeId}/InvalidValue`)({
  *   Effect.gen(function*() {
  *     const validCommands = ["deploy", "destroy", "status"]
  *     if (!validCommands.includes(subcommand)) {
- *       return yield* Effect.fail(unknownSubcommandError)
+ *       return yield* unknownSubcommandError
  *     }
  *     return subcommand
  *   })
@@ -386,61 +387,6 @@ export class UnknownSubcommand extends Schema.ErrorClass(`${TypeId}/UnknownSubco
   }
 }
 
-/**
- * Control flow indicator when help is requested via --help flag.
- * This is not an error but uses the error channel for control flow.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import { CliError } from "effect/unstable/cli"
- *
- * const showHelpIndicator = new CliError.ShowHelp({
- *   commandPath: ["myapp", "deploy", "production"]
- * })
- *
- * console.log(showHelpIndicator.message)
- * // "Help requested"
- *
- * // In help flag handling
- * const handleHelpFlag = (hasHelpFlag: boolean) =>
- *   Effect.gen(function*() {
- *     if (hasHelpFlag) {
- *       return yield* Effect.fail(showHelpIndicator)
- *     }
- *     return "continuing with command"
- *   })
- *
- * // In error handling
- * const handleCliErrors = (error: CliError.CliError): void => {
- *   if (error._tag === "ShowHelp") {
- *     // Display help for the command path
- *     console.log(`Displaying help for: ${error.commandPath.join(" ")}`)
- *   }
- *   // Handle other errors...
- * }
- * ```
- *
- * @since 4.0.0
- * @category models
- */
-export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
-  _tag: Schema.tag("ShowHelp"),
-  commandPath: Schema.Array(Schema.String)
-}) {
-  /**
-   * @since 4.0.0
-   */
-  readonly [TypeId] = TypeId
-
-  /**
-   * @since 4.0.0
-   */
-  override get message() {
-    return "Help requested"
-  }
-}
-
 /**
  * Wrapper for user (handler) errors to unify under CLI error channel when desired.
  *
@@ -485,3 +431,45 @@ export class UserError extends Schema.ErrorClass(`${TypeId}/UserError`)({
    */
   readonly [TypeId] = TypeId
 }
+
+const NonShowHelpErrors: Schema.Union<
+  readonly [
+    typeof UnrecognizedOption,
+    typeof DuplicateOption,
+    typeof MissingOption,
+    typeof MissingArgument,
+    typeof InvalidValue,
+    typeof UnknownSubcommand,
+    typeof UserError
+  ]
+> = Schema.Union([
+  UnrecognizedOption,
+  DuplicateOption,
+  MissingOption,
+  MissingArgument,
+  InvalidValue,
+  UnknownSubcommand,
+  UserError
+])
+
+/**
+ * Control flow indicator when help is requested via --help flag.
+ * This is not an error but uses the error channel for control flow.
+ *
+ * @since 4.0.0
+ * @category models
+ */
+export class ShowHelp extends Schema.ErrorClass(`${TypeId}/ShowHelp`)({
+  _tag: Schema.tag("ShowHelp"),
+  commandPath: Schema.Array(Schema.String),
+  errors: Schema.Array(NonShowHelpErrors)
+}) {
+  readonly [TypeId] = TypeId
+
+  override readonly [Runtime.errorExitCode] = this.errors.length ? 1 : 0
+  override readonly [Runtime.errorReported] = false
+
+  override get message() {
+    return "Help requested"
+  }
+}

package/src/unstable/cli/CliOutput.ts

@@ -409,6 +409,8 @@ const renderTable = (rows: ReadonlyArray<Row>, widthCap: number) => {
   return rows.map(({ left, right }) => `  ${pad(left, col)}${right}`).join("\n")
 }
 
+const formatSubcommandName = (name: string, alias: string | undefined): string => alias ? `${name}, ${alias}` : name
+
 /**
  * Color functions interface for help formatting.
  * @internal
@@ -497,16 +499,83 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
     sections.push("")
   }
 
+  // Global Flags section
+  if (doc.globalFlags && doc.globalFlags.length > 0) {
+    sections.push(colors.bold("GLOBAL FLAGS"))
+
+    const globalFlagRows: Array<Row> = doc.globalFlags.map((flag) => {
+      const names: Array<string> = []
+
+      // Add main name with -- prefix first
+      names.push(colors.green(`--${flag.name}`))
+
+      // Add aliases after (like -f) to match expected ordering
+      for (const alias of flag.aliases) {
+        names.push(colors.green(alias))
+      }
+
+      const namesPart = names.join(", ")
+      const typePart = flag.type !== "boolean" ? ` ${colors.dim(flag.type)}` : ""
+
+      return {
+        left: namesPart + typePart,
+        right: flag.description ?? ""
+      }
+    })
+
+    sections.push(renderTable(globalFlagRows, 30))
+    sections.push("")
+  }
+
   // Subcommands section
   if (doc.subcommands && doc.subcommands.length > 0) {
-    sections.push(colors.bold("SUBCOMMANDS"))
+    const ungrouped = doc.subcommands.find((group) => group.group === undefined)
+
+    if (ungrouped) {
+      sections.push(colors.bold("SUBCOMMANDS"))
+      sections.push(renderTable(
+        ungrouped.commands.map((sub) => ({
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      if (doc.subcommands.length > 1) {
+        sections.push("")
+      }
+    }
 
-    const subcommandRows: Array<Row> = doc.subcommands.map((sub) => ({
-      left: colors.cyan(sub.name),
-      right: sub.description
-    }))
+    for (const group of doc.subcommands) {
+      if (group.group === undefined) continue
+      sections.push(colors.bold(`${group.group}:`))
+      sections.push(renderTable(
+        group.commands.map((sub) => ({
+          left: colors.cyan(formatSubcommandName(sub.name, sub.alias)),
+          right: sub.shortDescription ?? sub.description
+        })),
+        20
+      ))
+      sections.push("")
+    }
+  }
 
-    sections.push(renderTable(subcommandRows, 20))
+  // Examples section
+  if (doc.examples && doc.examples.length > 0) {
+    sections.push(colors.bold("EXAMPLES"))
+
+    let first = true
+    let previousHadDescription = false
+    for (const example of doc.examples) {
+      if (example.description) {
+        if (!first) sections.push("")
+        sections.push(`  ${colors.dim(`# ${example.description}`)}`)
+      } else if (previousHadDescription) {
+        sections.push("")
+      }
+      sections.push(`  ${colors.cyan(example.command)}`)
+      first = false
+      previousHadDescription = !!example.description
+    }
     sections.push("")
   }