effect 4.0.0-beta.6 → 4.0.0-beta.60

package/src/unstable/cli/index.ts

@@ -24,11 +24,23 @@ export * as CliOutput from "./CliOutput.ts"
  */
 export * as Command from "./Command.ts"
 
+/**
+ * Shell completion descriptors and script generation for the unstable CLI API.
+ *
+ * @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
  */

package/src/unstable/cli/internal/command.ts

@@ -5,16 +5,19 @@
  * Internal implementation details for CLI commands.
  * Public API is in ../Command.ts
  */
+import * as Arr from "../../../Array.ts"
+import * as Context from "../../../Context.ts"
 import * as Effect from "../../../Effect.ts"
 import { YieldableProto } from "../../../internal/core.ts"
+import * as Option from "../../../Option.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 * as GlobalFlag from "../GlobalFlag.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"
+import { type ConfigInternal, emptyConfig, reconstructTree } from "./config.ts"
 
 /* ========================================================================== */
 /* Types                                                                      */
@@ -22,14 +25,25 @@ 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, any, unknown, unknown>>
+}
+
 /**
  * Internal implementation interface with all the machinery.
  * Use toImpl() to access from internal code.
  */
-export interface CommandInternal<Name extends string, Input, E, R> extends Command<Name, Input, E, R> {
+export interface CommandInternal<Name extends string, Input, E, R, ContextInput>
+  extends Command<Name, Input, ContextInput, E, R>
+{
   readonly config: ConfigInternal
-  readonly service: ServiceMap.Service<CommandContext<Name>, Input>
+  readonly contextConfig: ConfigInternal
+  readonly service: Context.Key<CommandContext<Name>, ContextInput>
+  readonly annotations: Context.Context<never>
+  readonly globalFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
   readonly parse: (input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>
+  readonly parseContext: (input: ParsedTokens) => Effect.Effect<ContextInput, CliError.CliError, Environment>
   readonly handle: (
     input: Input,
     commandPath: ReadonlyArray<string>
@@ -51,9 +65,9 @@ export const TypeId = "~effect/cli/Command" as const
  * Casts a Command to its internal implementation.
  * For use by internal modules that need access to config, parse, handle, etc.
  */
-export const toImpl = <Name extends string, Input, E, R>(
-  self: Command<Name, Input, E, R>
-): CommandInternal<Name, Input, E, R> => self as CommandInternal<Name, Input, E, R>
+export const toImpl = <Name extends string, Input, E, R, ContextInput = {}>(
+  self: Command<Name, Input, ContextInput, E, R>
+): CommandInternal<Name, Input, E, R, ContextInput> => self as CommandInternal<Name, Input, E, R, ContextInput>
 
 /* ========================================================================== */
 /* Proto                                                                      */
@@ -64,7 +78,7 @@ export const Proto = {
   pipe() {
     return pipeArguments(this, arguments)
   },
-  asEffect(this: Command<any, any, any, any>) {
+  asEffect(this: Command<any, any, any, any, any>) {
     return toImpl(this).service.asEffect()
   }
 }
@@ -76,19 +90,32 @@ export const Proto = {
 /**
  * Internal command constructor. Only accepts already-parsed ConfigInternal.
  */
-export const makeCommand = <const Name extends string, Input, E, R>(options: {
+export const makeCommand = <const Name extends string, Input, E, R, ContextInput = {}>(options: {
   readonly name: Name
   readonly config: ConfigInternal
-  readonly service?: ServiceMap.Service<CommandContext<Name>, Input> | undefined
+  readonly contextConfig?: ConfigInternal | undefined
+  readonly service?: Context.Key<CommandContext<Name>, ContextInput> | undefined
+  readonly annotations?: Context.Context<never> | undefined
+  readonly globalFlags?: ReadonlyArray<GlobalFlag.GlobalFlag<any>> | undefined
   readonly description?: string | undefined
-  readonly subcommands?: ReadonlyArray<Command<any, unknown, unknown, unknown>> | undefined
+  readonly shortDescription?: string | undefined
+  readonly alias?: 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 parseContext?:
+    | ((input: ParsedTokens) => Effect.Effect<ContextInput, CliError.CliError, Environment>)
+    | undefined
   readonly handle?:
     | ((input: Input, commandPath: ReadonlyArray<string>) => Effect.Effect<void, E, R | Environment>)
     | undefined
-}): Command<Name, Input, E, R> => {
-  const service = options.service ?? ServiceMap.Service<CommandContext<Name>, Input>(`${TypeId}/${options.name}`)
+}): Command<Name, Input, ContextInput, E, R> => {
   const config = options.config
+  const contextConfig = options.contextConfig ?? emptyConfig
+  const service = options.service ?? Context.Service<CommandContext<Name>, ContextInput>(`${TypeId}/${options.name}`)
+  const annotations = options.annotations ?? Context.empty()
+  const globalFlags = options.globalFlags ?? []
+  const subcommands = options.subcommands ?? []
 
   const handle = (
     input: Input,
@@ -96,13 +123,10 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   ): Effect.Effect<void, CliError.CliError | E, R | Environment> =>
     Predicate.isNotUndefined(options.handle)
       ? options.handle(input, commandPath)
-      : Effect.fail(new CliError.ShowHelp({ commandPath }))
+      : Effect.fail(new CliError.ShowHelp({ commandPath, errors: [] }))
 
-  const parse = options.parse ?? Effect.fnUntraced(function*(input: ParsedTokens) {
-    const parsedArgs: Param.ParsedArgs = { flags: input.flags, arguments: input.arguments }
-    const values = yield* parseParams(parsedArgs, config.orderedParams)
-    return reconstructTree(config.tree, values) as Input
-  })
+  const parse = options.parse ?? makeParser(config) as any
+  const parseContext = options.parseContext ?? makeParser(contextConfig) as any
 
   const buildHelpDoc = (commandPath: ReadonlyArray<string>): HelpDoc => {
     const args: Array<ArgDoc> = []
@@ -123,8 +147,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]"
@@ -136,42 +159,59 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     for (const option of config.flags) {
       const singles = Param.extractSingleParams(option)
       for (const single of singles) {
-        const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
-        flags.push({
-          name: single.name,
-          aliases: formattedAliases,
-          type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
-          description: single.description,
-          required: single.primitiveType._tag !== "Boolean"
-        })
+        flags.push(toFlagDoc(single))
       }
     }
 
-    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,
+          alias: subcommand.alias,
+          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,
+    globalFlags,
+    subcommands,
     config,
+    contextConfig,
     service,
     parse,
+    parseContext,
     handle,
     buildHelpDoc,
     ...(Predicate.isNotUndefined(options.description)
       ? { description: options.description }
+      : {}),
+    ...(Predicate.isNotUndefined(options.shortDescription)
+      ? { shortDescription: options.shortDescription }
+      : {}),
+    ...(Predicate.isNotUndefined(options.alias)
+      ? { alias: options.alias }
       : {})
   })
 }
@@ -180,6 +220,46 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
 /* Helpers                                                                    */
 /* ========================================================================== */
 
+/**
+ * Converts a single flag param into a FlagDoc for help display.
+ */
+export const toFlagDoc = (single: Param.Single<typeof Param.flagKind, unknown>): FlagDoc => {
+  const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
+  return {
+    name: single.name,
+    aliases: formattedAliases,
+    type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
+    description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
+    required: single.primitiveType._tag !== "Boolean"
+  }
+}
+
+const appendChoiceKeys = (
+  description: Option.Option<string>,
+  choiceKeys: ReadonlyArray<string> | undefined
+): Option.Option<string> => {
+  if (choiceKeys === undefined || choiceKeys.length === 0) {
+    return description
+  }
+  const choiceSuffix = `(choices: ${choiceKeys.join(", ")})`
+  return Option.match(description, {
+    onNone: () => Option.some(choiceSuffix),
+    onSome: (value) => Option.some(`${value} ${choiceSuffix}`)
+  })
+}
+
+/**
+ * Creates a parser for a given config. Used as the default for both `parse`
+ * and `parseContext`, and also by `withSharedFlags` to avoid constructing a
+ * full throwaway command.
+ */
+export const makeParser = (cfg: ConfigInternal) =>
+  Effect.fnUntraced(function*(input: ParsedTokens) {
+    const parsedArgs: Param.ParsedArgs = { flags: input.flags, arguments: input.arguments }
+    const values = yield* parseParams(parsedArgs, cfg.orderedParams)
+    return reconstructTree(cfg.tree, values)
+  })
+
 /**
  * Parses param values from parsed command arguments into their typed
  * representations.
@@ -207,15 +287,18 @@ const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.An
 /**
  * Checks for duplicate flag names between parent and child commands.
  */
-export const checkForDuplicateFlags = <Name extends string, Input>(
-  parent: Command<Name, Input, unknown, unknown>,
-  subcommands: ReadonlyArray<Command<any, unknown, unknown, unknown>>
+export const checkForDuplicateFlags = <Name extends string, Input, ContextInput>(
+  parent: Command<Name, Input, ContextInput, unknown, unknown>,
+  subcommands: ReadonlyArray<Command<any, unknown, any, unknown, unknown>>,
+  options?: {
+    readonly contextConfig?: ConfigInternal | undefined
+  } | undefined
 ): void => {
   const parentImpl = toImpl(parent)
   const parentOptionNames = new Set<string>()
 
-  const extractNames = (options: ReadonlyArray<Param.Any>): void => {
-    for (const option of options) {
+  const extractNames = (flags: ReadonlyArray<Param.Any>): void => {
+    for (const option of flags) {
       const singles = Param.extractSingleParams(option)
       for (const single of singles) {
         parentOptionNames.add(single.name)
@@ -223,7 +306,7 @@ export const checkForDuplicateFlags = <Name extends string, Input>(
     }
   }
 
-  extractNames(parentImpl.config.flags)
+  extractNames((options?.contextConfig ?? parentImpl.contextConfig).flags)
 
   for (const subcommand of subcommands) {
     const subImpl = toImpl(subcommand)
@@ -241,25 +324,3 @@ export const checkForDuplicateFlags = <Name extends string, Input>(
     }
   }
 }
-
-/**
- * Helper function to get help documentation for a specific command path.
- * Navigates through the command hierarchy to find the right command.
- */
-export const getHelpForCommandPath = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
-  commandPath: ReadonlyArray<string>
-): HelpDoc => {
-  let currentCommand: Command.Any = command
-
-  // 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)
-    if (subcommand) {
-      currentCommand = subcommand
-    }
-  }
-
-  return toImpl(currentCommand).buildHelpDoc(commandPath)
-}

package/src/unstable/cli/internal/completions/bash.ts

@@ -6,7 +6,7 @@
  *
  * @internal
  */
-import type { ArgumentType, CommandDescriptor, FlagDescriptor, FlagType } from "./CommandDescriptor.ts"
+import type * as Completions from "../../Completions.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -16,7 +16,7 @@ const escapeForBash = (s: string): string => s.replace(/'/g, "'\\''")
 
 const sanitizeFunctionName = (s: string): string => s.replace(/[^a-zA-Z0-9_]/g, "_")
 
-const flagNamesForWordlist = (flag: FlagDescriptor): Array<string> => {
+const flagNamesForWordlist = (flag: Completions.FlagDescriptor): Array<string> => {
   const names: Array<string> = [`--${flag.name}`]
   for (const alias of flag.aliases) {
     names.push(alias.length === 1 ? `-${alias}` : `--${alias}`)
@@ -33,7 +33,7 @@ const flagNamesForWordlist = (flag: FlagDescriptor): Array<string> => {
  * all forms in that group are removed from the candidate list.
  */
 const buildFlagGroupDeclarations = (
-  flags: ReadonlyArray<FlagDescriptor>,
+  flags: ReadonlyArray<Completions.FlagDescriptor>,
   lines: Array<string>
 ): void => {
   if (flags.length === 0) return
@@ -60,7 +60,7 @@ const buildFlagGroupDeclarations = (
   lines.push(``)
 }
 
-const flagValueCompletion = (type: FlagType): string | undefined => {
+const flagValueCompletion = (type: Completions.FlagType): string | undefined => {
   switch (type._tag) {
     case "Boolean":
       return undefined
@@ -74,7 +74,7 @@ const flagValueCompletion = (type: FlagType): string | undefined => {
   }
 }
 
-const argCompletion = (type: ArgumentType): string | undefined => {
+const argCompletion = (type: Completions.ArgumentType): string | undefined => {
   switch (type._tag) {
     case "Choice":
       return `COMPREPLY=( $(compgen -W '${type.values.join(" ")}' -- "$cur") )`
@@ -91,7 +91,7 @@ const argCompletion = (type: ArgumentType): string | undefined => {
 // ---------------------------------------------------------------------------
 
 const generateFunction = (
-  descriptor: CommandDescriptor,
+  descriptor: Completions.CommandDescriptor,
   parentPath: ReadonlyArray<string>,
   lines: Array<string>
 ): void => {
@@ -184,7 +184,7 @@ const generateFunction = (
 /** @internal */
 export const generate = (
   executableName: string,
-  descriptor: CommandDescriptor
+  descriptor: Completions.CommandDescriptor
 ): string => {
   const lines: Array<string> = []
   const safeName = sanitizeFunctionName(executableName)

package/src/unstable/cli/internal/completions/{CommandDescriptor.ts → descriptor.ts}

@@ -4,65 +4,18 @@
  *
  * @internal
  */
+import * as Option from "../../../../Option.ts"
 import type { Command } from "../../Command.ts"
+import type * as Completions from "../../Completions.ts"
 import * as Param from "../../Param.ts"
 import * as Primitive from "../../Primitive.ts"
 import { toImpl } from "../command.ts"
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** @internal */
-export interface CommandDescriptor {
-  readonly name: string
-  readonly description: string | undefined
-  readonly flags: ReadonlyArray<FlagDescriptor>
-  readonly arguments: ReadonlyArray<ArgumentDescriptor>
-  readonly subcommands: ReadonlyArray<CommandDescriptor>
-}
-
-/** @internal */
-export interface FlagDescriptor {
-  readonly name: string
-  readonly aliases: ReadonlyArray<string>
-  readonly description: string | undefined
-  readonly type: FlagType
-}
-
-/** @internal */
-export type FlagType =
-  | { readonly _tag: "Boolean" }
-  | { readonly _tag: "String" }
-  | { readonly _tag: "Integer" }
-  | { readonly _tag: "Float" }
-  | { readonly _tag: "Date" }
-  | { readonly _tag: "Choice"; readonly values: ReadonlyArray<string> }
-  | { readonly _tag: "Path"; readonly pathType: "file" | "directory" | "either" }
-
-/** @internal */
-export interface ArgumentDescriptor {
-  readonly name: string
-  readonly description: string | undefined
-  readonly required: boolean
-  readonly variadic: boolean
-  readonly type: ArgumentType
-}
-
-/** @internal */
-export type ArgumentType =
-  | { readonly _tag: "String" }
-  | { readonly _tag: "Integer" }
-  | { readonly _tag: "Float" }
-  | { readonly _tag: "Date" }
-  | { readonly _tag: "Choice"; readonly values: ReadonlyArray<string> }
-  | { readonly _tag: "Path"; readonly pathType: "file" | "directory" | "either" }
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-const toFlagType = (single: Param.Single<"flag", unknown>): FlagType => {
+const toFlagType = (single: Param.Single<"flag", unknown>): Completions.FlagType => {
   const tag = single.primitiveType._tag
   switch (tag) {
     case "Boolean":
@@ -91,7 +44,7 @@ const toFlagType = (single: Param.Single<"flag", unknown>): FlagType => {
   }
 }
 
-const toArgumentType = (single: Param.Single<"argument", unknown>): ArgumentType => {
+const toArgumentType = (single: Param.Single<"argument", unknown>): Completions.ArgumentType => {
   const tag = single.primitiveType._tag
   switch (tag) {
     case "Integer":
@@ -123,11 +76,11 @@ const toArgumentType = (single: Param.Single<"argument", unknown>): ArgumentType
 // ---------------------------------------------------------------------------
 
 /** @internal */
-export const fromCommand = (cmd: Command.Any): CommandDescriptor => {
+export const fromCommand = (cmd: Command.Any): Completions.CommandDescriptor => {
   const impl = toImpl(cmd)
   const config = impl.config
 
-  const flags: Array<FlagDescriptor> = []
+  const flags: Array<Completions.FlagDescriptor> = []
   for (const flag of config.flags) {
     const singles = Param.extractSingleParams(flag)
     for (const single of singles) {
@@ -135,13 +88,13 @@ export const fromCommand = (cmd: Command.Any): CommandDescriptor => {
       flags.push({
         name: single.name,
         aliases: single.aliases,
-        description: single.description,
+        description: Option.getOrUndefined(single.description),
         type: toFlagType(single as Param.Single<"flag", unknown>)
       })
     }
   }
 
-  const args: Array<ArgumentDescriptor> = []
+  const args: Array<Completions.ArgumentDescriptor> = []
   for (const arg of config.arguments) {
     const singles = Param.extractSingleParams(arg)
     const metadata = Param.getParamMetadata(arg)
@@ -149,7 +102,7 @@ export const fromCommand = (cmd: Command.Any): CommandDescriptor => {
       if (single.kind !== "argument") continue
       args.push({
         name: single.name,
-        description: single.description,
+        description: Option.getOrUndefined(single.description),
         required: !metadata.isOptional,
         variadic: metadata.isVariadic,
         type: toArgumentType(single as Param.Single<"argument", unknown>)
@@ -157,11 +110,16 @@ export const fromCommand = (cmd: Command.Any): CommandDescriptor => {
     }
   }
 
-  const subcommands: Array<CommandDescriptor> = cmd.subcommands.map(fromCommand)
+  const subcommands: Array<Completions.CommandDescriptor> = []
+  for (const group of cmd.subcommands) {
+    for (const subcommand of group.commands) {
+      subcommands.push(fromCommand(subcommand))
+    }
+  }
 
   return {
     name: cmd.name,
-    description: cmd.description,
+    description: cmd.shortDescription ?? cmd.description,
     flags,
     arguments: args,
     subcommands

package/src/unstable/cli/internal/completions/fish.ts

@@ -6,7 +6,7 @@
  *
  * @internal
  */
-import type { ArgumentType, CommandDescriptor, FlagDescriptor, FlagType } from "./CommandDescriptor.ts"
+import type * as Completions from "../../Completions.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -46,7 +46,7 @@ const subcommandCondition = (
  * flag has already been typed. Returns the condition string without wrapping
  * quotes (the caller adds those).
  */
-const flagContainsOptCondition = (flag: FlagDescriptor): string => {
+const flagContainsOptCondition = (flag: Completions.FlagDescriptor): string => {
   const optArgs: Array<string> = []
   for (const alias of flag.aliases) {
     if (alias.length === 1) {
@@ -66,7 +66,7 @@ const flagContainsOptCondition = (flag: FlagDescriptor): string => {
   return `not __fish_contains_opt ${optArgs.join(" ")}`
 }
 
-const flagCompletionArgs = (flag: FlagDescriptor): Array<string> => {
+const flagCompletionArgs = (flag: Completions.FlagDescriptor): Array<string> => {
   const args: Array<string> = [`-l ${flag.name}`]
   for (const alias of flag.aliases) {
     if (alias.length === 1) {
@@ -85,7 +85,7 @@ const flagCompletionArgs = (flag: FlagDescriptor): Array<string> => {
   return args
 }
 
-const flagValueArgs = (type: FlagType): string | undefined => {
+const flagValueArgs = (type: Completions.FlagType): string | undefined => {
   switch (type._tag) {
     case "Boolean":
       return undefined
@@ -100,7 +100,7 @@ const flagValueArgs = (type: FlagType): string | undefined => {
   }
 }
 
-const argValueArgs = (type: ArgumentType): string | undefined => {
+const argValueArgs = (type: Completions.ArgumentType): string | undefined => {
   switch (type._tag) {
     case "Choice":
       return `-r -f -a '${type.values.join(" ")}'`
@@ -117,7 +117,7 @@ const argValueArgs = (type: ArgumentType): string | undefined => {
 
 const generateCompletions = (
   executableName: string,
-  descriptor: CommandDescriptor,
+  descriptor: Completions.CommandDescriptor,
   parentPath: ReadonlyArray<string>,
   lines: Array<string>
 ): void => {
@@ -231,7 +231,7 @@ const generateCompletions = (
 /** @internal */
 export const generate = (
   executableName: string,
-  descriptor: CommandDescriptor
+  descriptor: Completions.CommandDescriptor
 ): string => {
   const lines: Array<string> = []
 

package/src/unstable/cli/internal/completions/zsh.ts

@@ -6,13 +6,7 @@
  *
  * @internal
  */
-import type {
-  ArgumentDescriptor,
-  ArgumentType,
-  CommandDescriptor,
-  FlagDescriptor,
-  FlagType
-} from "./CommandDescriptor.ts"
+import type * as Completions from "../../Completions.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -25,7 +19,7 @@ const sanitize = (s: string): string => s.replace(/[^a-zA-Z0-9_]/g, "_")
 /**
  * All forms of a flag (--name, -alias, --no-name) for the exclusion group.
  */
-const allForms = (flag: FlagDescriptor): Array<string> => {
+const allForms = (flag: Completions.FlagDescriptor): Array<string> => {
   const forms: Array<string> = [`--${flag.name}`]
   for (const alias of flag.aliases) {
     forms.push(alias.length === 1 ? `-${alias}` : `--${alias}`)
@@ -36,7 +30,7 @@ const allForms = (flag: FlagDescriptor): Array<string> => {
   return forms
 }
 
-const valueAction = (type: FlagType): string => {
+const valueAction = (type: Completions.FlagType): string => {
   switch (type._tag) {
     case "Boolean":
       return ""
@@ -55,7 +49,7 @@ const valueAction = (type: FlagType): string => {
   }
 }
 
-const argAction = (type: ArgumentType): string => {
+const argAction = (type: Completions.ArgumentType): string => {
   switch (type._tag) {
     case "Choice":
       return `(${type.values.join(" ")})`
@@ -70,7 +64,7 @@ const argAction = (type: ArgumentType): string => {
  * Produce _arguments optspecs for a single flag. Each spec is a complete,
  * single-quoted string — no brace expansion, no line continuations.
  */
-const flagSpecs = (flag: FlagDescriptor): Array<string> => {
+const flagSpecs = (flag: Completions.FlagDescriptor): Array<string> => {
   const specs: Array<string> = []
   const desc = flag.description ? `[${escapeZsh(flag.description)}]` : ""
   const action = valueAction(flag.type)
@@ -94,7 +88,7 @@ const flagSpecs = (flag: FlagDescriptor): Array<string> => {
   return specs
 }
 
-const argSpec = (arg: ArgumentDescriptor): string => {
+const argSpec = (arg: Completions.ArgumentDescriptor): string => {
   const desc = arg.description ? escapeZsh(arg.description) : arg.name
   const action = argAction(arg.type)
   const prefix = arg.variadic ? "*" : ""
@@ -106,7 +100,7 @@ const argSpec = (arg: ArgumentDescriptor): string => {
 // ---------------------------------------------------------------------------
 
 const generateFunction = (
-  descriptor: CommandDescriptor,
+  descriptor: Completions.CommandDescriptor,
   parentPath: ReadonlyArray<string>,
   lines: Array<string>
 ): void => {
@@ -196,7 +190,7 @@ const generateFunction = (
 /** @internal */
 export const generate = (
   executableName: string,
-  descriptor: CommandDescriptor
+  descriptor: Completions.CommandDescriptor
 ): string => {
   const lines: Array<string> = []
   const safeName = sanitize(executableName)