effect 4.0.0-beta.100 → 4.0.0-beta.102

package/src/unstable/ai/internal/structured-output.ts

@@ -0,0 +1,458 @@
+import * as Arr from "../../../Array.ts"
+import * as InternalRecord from "../../../internal/record.ts"
+import type * as JsonSchema from "../../../JsonSchema.ts"
+import * as Option from "../../../Option.ts"
+import * as Predicate from "../../../Predicate.ts"
+import * as Schema from "../../../Schema.ts"
+import * as SchemaAST from "../../../SchemaAST.ts"
+import * as SchemaTransformation from "../../../SchemaTransformation.ts"
+import * as Tool from "../Tool.ts"
+
+const REST_PROPERTY_NAME = "__rest__"
+const TAIL_PROPERTY_PREFIX = "__tail_"
+
+const RECORD_DESCRIPTION =
+  "Object encoded as array of [key, value] pairs. Apply object constraints to the decoded object"
+
+const TUPLE_DESCRIPTION =
+  "Tuple encoded as an object with numeric string keys ('0', '1', ...). If present, '__rest__' contains remaining elements"
+const TUPLE_TAIL_DESCRIPTION = `${TUPLE_DESCRIPTION}. Post-rest elements use '__tail_0__', '__tail_1__', and so on`
+
+/** @internal */
+export function toCodec<T, E, RD, RE>(
+  schema: Schema.ConstraintCodec<T, E, RD, RE>
+): Schema.ConstraintCodec<T, unknown, RD, RE> {
+  const jsonCodec = Schema.toCodecJson(schema)
+  const encoded = SchemaAST.toEncoded(jsonCodec.ast)
+  const from = transform(encoded)
+  if (from === encoded) {
+    return jsonCodec.ast === schema.ast ? schema : jsonCodec
+  }
+  return Schema.make<typeof schema>(
+    SchemaAST.decodeTo(from, jsonCodec.ast, SchemaTransformation.passthrough())
+  )
+}
+
+function transform(root: SchemaAST.AST): SchemaAST.AST {
+  const cache = new Map<SchemaAST.AST, SchemaAST.AST>()
+
+  function recur(ast: SchemaAST.AST): SchemaAST.AST {
+    const cached = cache.get(ast)
+    if (cached !== undefined) return cached
+
+    switch (ast._tag) {
+      case "Union": {
+        const types = SchemaAST.mapOrSame(ast.types, recur)
+        const checks = prepareChecks(ast.checks)
+        const mode = ast.mode === "oneOf" ? "anyOf" : ast.mode
+        if (types === ast.types && checks === ast.checks && mode === ast.mode) return ast
+        return new SchemaAST.Union(
+          types,
+          mode,
+          ast.annotations,
+          checks,
+          ast.encoding,
+          ast.context,
+          ast.encodingChecks
+        )
+      }
+      case "Arrays": {
+        if (ast.elements.length > 0 || ast.rest.length > 1) {
+          return tupleToObject(ast, recur)
+        }
+        const elements = SchemaAST.mapOrSame(ast.elements, recur)
+        const rest = SchemaAST.mapOrSame(ast.rest, recur)
+        const checks = prepareChecks(ast.checks)
+        if (elements === ast.elements && rest === ast.rest && checks === ast.checks) return ast
+        return new SchemaAST.Arrays(
+          ast.isMutable,
+          elements,
+          rest,
+          ast.annotations,
+          checks,
+          ast.encoding,
+          ast.context,
+          ast.encodingChecks
+        )
+      }
+      case "Objects": {
+        if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
+          const indexSignature = ast.indexSignatures[0]
+          if (Tool.isEmptyParamsRecord(indexSignature)) return ast
+        }
+        if (ast.indexSignatures.length > 0) {
+          return objectToEntries(ast, recur)
+        }
+
+        const propertySignatures = SchemaAST.mapOrSame(ast.propertySignatures, (propertySignature) => {
+          let type = recur(propertySignature.type)
+          if (SchemaAST.isOptional(propertySignature.type)) {
+            type = optionalToNullable(type)
+          }
+          return type === propertySignature.type
+            ? propertySignature
+            : new SchemaAST.PropertySignature(propertySignature.name, type)
+        })
+        const indexSignatures = SchemaAST.mapOrSame(ast.indexSignatures, (indexSignature) => {
+          const parameter = recur(indexSignature.parameter)
+          const type = recur(indexSignature.type)
+          return parameter === indexSignature.parameter && type === indexSignature.type
+            ? indexSignature
+            : new SchemaAST.IndexSignature(parameter, type, indexSignature.merge)
+        })
+        const checks = prepareChecks(ast.checks)
+        if (
+          propertySignatures === ast.propertySignatures &&
+          indexSignatures === ast.indexSignatures &&
+          checks === ast.checks
+        ) {
+          return ast
+        }
+        return new SchemaAST.Objects(
+          propertySignatures,
+          indexSignatures,
+          ast.annotations,
+          checks,
+          ast.encoding,
+          ast.context,
+          ast.encodingChecks
+        )
+      }
+      case "Suspend": {
+        const out = new SchemaAST.Suspend(
+          () => recur(ast.thunk()),
+          ast.annotations,
+          undefined,
+          ast.encoding,
+          ast.context
+        )
+        cache.set(ast, out)
+        return out
+      }
+      default: {
+        const checks = prepareChecks(ast.checks)
+        return checks === ast.checks ? ast : SchemaAST.replaceChecks(ast, checks)
+      }
+    }
+  }
+
+  return recur(root)
+}
+
+function tupleToObject(ast: SchemaAST.Arrays, recur: (ast: SchemaAST.AST) => SchemaAST.AST): SchemaAST.AST {
+  const propertySignatures = ast.elements.map((element, index) =>
+    new SchemaAST.PropertySignature(String(index), element)
+  )
+  if (ast.rest.length === 1) {
+    propertySignatures.push(
+      new SchemaAST.PropertySignature(REST_PROPERTY_NAME, new SchemaAST.Arrays(false, [], ast.rest))
+    )
+  } else if (ast.rest.length > 1) {
+    propertySignatures.push(
+      new SchemaAST.PropertySignature(REST_PROPERTY_NAME, new SchemaAST.Arrays(false, [], [ast.rest[0]]))
+    )
+    for (let index = 1; index < ast.rest.length; index++) {
+      propertySignatures.push(
+        new SchemaAST.PropertySignature(`${TAIL_PROPERTY_PREFIX}${index - 1}__`, ast.rest[index])
+      )
+    }
+  }
+  const from = recur(
+    new SchemaAST.Objects(
+      propertySignatures,
+      [],
+      structuralAnnotations(ast, ast.rest.length > 1 ? TUPLE_TAIL_DESCRIPTION : TUPLE_DESCRIPTION),
+      compilerChecks(ast.checks)
+    )
+  )
+  return SchemaAST.decodeTo(
+    from,
+    ast,
+    SchemaTransformation.transform({
+      decode: (object) => {
+        let tuple: Array<unknown> = []
+        for (let index = 0; index < ast.elements.length; index++) {
+          const key = String(index)
+          if (object[key] !== undefined) tuple.push(object[key])
+        }
+        if (REST_PROPERTY_NAME in object) {
+          tuple = [...tuple, ...object[REST_PROPERTY_NAME]]
+        }
+        for (let index = 1; index < ast.rest.length; index++) {
+          tuple.push(object[`${TAIL_PROPERTY_PREFIX}${index - 1}__`])
+        }
+        return tuple
+      },
+      encode: (tuple) => {
+        const object: Record<string, unknown> = {}
+        for (let index = 0; index < ast.elements.length; index++) {
+          if (index < tuple.length) object[String(index)] = tuple[index]
+        }
+        if (ast.rest.length >= 1) {
+          const tailLength = ast.rest.length - 1
+          const restEnd = Math.max(ast.elements.length, tuple.length - tailLength)
+          object[REST_PROPERTY_NAME] = tuple.slice(ast.elements.length, restEnd)
+          for (let index = 0; index < tailLength; index++) {
+            object[`${TAIL_PROPERTY_PREFIX}${index}__`] = tuple[restEnd + index]
+          }
+        }
+        return object
+      }
+    })
+  )
+}
+
+function objectToEntries(
+  ast: SchemaAST.Objects,
+  recur: (ast: SchemaAST.AST) => SchemaAST.AST
+): SchemaAST.AST {
+  const checks = combineChecks(recordChecks(ast.checks), compilerChecks(ast.checks))
+  const key = unionOrSingle([
+    ...ast.propertySignatures.map((propertySignature) => new SchemaAST.Literal(propertySignature.name as string)),
+    ...ast.indexSignatures.map((indexSignature) => indexSignature.parameter)
+  ])
+  const value = unionOrSingle([
+    ...ast.propertySignatures.map((propertySignature) => propertySignature.type),
+    ...ast.indexSignatures.map((indexSignature) => indexSignature.type)
+  ])
+  const from = recur(
+    new SchemaAST.Arrays(
+      false,
+      [],
+      [new SchemaAST.Arrays(false, [key, value], [])],
+      structuralAnnotations(ast, RECORD_DESCRIPTION),
+      checks
+    )
+  )
+  return SchemaAST.decodeTo(
+    from,
+    ast,
+    SchemaTransformation.transform({
+      decode: Object.fromEntries,
+      encode: Object.entries
+    })
+  )
+}
+
+function unionOrSingle(types: ReadonlyArray<SchemaAST.AST>): SchemaAST.AST {
+  const unique = Array.from(new Set(types))
+  return unique.length === 1 ? unique[0] : new SchemaAST.Union(unique, "anyOf")
+}
+
+function combineChecks(
+  left: SchemaAST.Checks | undefined,
+  right: SchemaAST.Checks | undefined
+): SchemaAST.Checks | undefined {
+  if (left === undefined) return right
+  if (right === undefined) return left
+  return [...left, ...right]
+}
+
+function compilerChecks(checks: SchemaAST.Checks | undefined): SchemaAST.Checks | undefined {
+  if (checks === undefined) return undefined
+  const out = checks.flatMap(compilerCheck)
+  return Arr.isArrayNonEmpty(out) ? out : undefined
+}
+
+function compilerCheck(check: SchemaAST.Check<any>): Array<SchemaAST.Check<any>> {
+  // Structural rewrites change the value seen by provider-side checks. A
+  // no-op proxy lets the generic compiler call `toJsonSchema` with the real
+  // provider type and dependency schemas without running the original filter
+  // against the wrong runtime shape.
+  const annotations = compilerAnnotations(check.annotations)
+  if (check._tag === "Filter") {
+    return annotations === undefined ? [] : [new SchemaAST.Filter(() => undefined, annotations)]
+  }
+  const checks = check.checks.flatMap(compilerCheck)
+  if (Arr.isArrayNonEmpty(checks)) {
+    return [new SchemaAST.FilterGroup(checks, annotations)]
+  }
+  return annotations === undefined ? [] : [new SchemaAST.Filter(() => undefined, annotations)]
+}
+
+function compilerAnnotations(
+  annotations: Schema.Annotations.Filter | undefined
+): Schema.Annotations.Filter | undefined {
+  if (annotations?.toJsonSchema === undefined) return undefined
+  return {
+    representation: annotations.representation,
+    toJsonSchema: annotations.toJsonSchema
+  }
+}
+
+function optionalToNullable(type: SchemaAST.AST): SchemaAST.AST {
+  return SchemaAST.decodeTo(
+    new SchemaAST.Union([type, SchemaAST.null], "anyOf"),
+    SchemaAST.optionalKey(type),
+    SchemaTransformation.transformOptional({
+      decode: Option.filter(Predicate.isNotNull),
+      encode: Option.orElseSome(() => null)
+    })
+  )
+}
+
+function prepareChecks(checks: SchemaAST.Checks | undefined): SchemaAST.Checks | undefined {
+  if (checks === undefined) return undefined
+  const out = SchemaAST.mapOrSame(checks, prepareCheck)
+  return out as SchemaAST.Checks
+}
+
+function prepareCheck(check: SchemaAST.Check<any>): SchemaAST.Check<any> {
+  switch (check._tag) {
+    case "Filter": {
+      const id = check.annotations?.representation?.id
+      return id === "effect/schema/isFinite" || id === "effect/schema/isInt"
+        ? check.annotate({ expected: undefined })
+        : check
+    }
+    case "FilterGroup": {
+      const checks = SchemaAST.mapOrSame(check.checks, prepareCheck)
+      return checks === check.checks
+        ? check
+        : new SchemaAST.FilterGroup(checks, check.annotations)
+    }
+  }
+}
+
+function recordChecks(checks: SchemaAST.Checks | undefined): SchemaAST.Checks | undefined {
+  if (checks === undefined) return undefined
+  const out = checks.flatMap(recordCheck)
+  return Arr.isArrayNonEmpty(out) ? out : undefined
+}
+
+function recordCheck(check: SchemaAST.Check<any>): Array<SchemaAST.Check<any>> {
+  if (check._tag === "FilterGroup") return check.checks.flatMap(recordCheck)
+  const representation = check.annotations?.representation
+  const payload = representation?.payload
+  if (!isJsonObject(payload)) return []
+  // A decoded record with at least N properties necessarily came from at least
+  // N entries. Upper bounds are not transported because duplicate provider
+  // keys can collapse during `Object.fromEntries`, so `maxItems` could reject
+  // an input that the returned codec accepts.
+  switch (representation?.id) {
+    case "effect/schema/isMinProperties":
+      return typeof payload.minProperties === "number"
+        ? [withoutDescription(Schema.isMinLength(payload.minProperties))]
+        : []
+    case "effect/schema/isPropertiesLengthBetween":
+      return typeof payload.minimum === "number"
+        ? [withoutDescription(Schema.isMinLength(payload.minimum))]
+        : []
+    default:
+      return []
+  }
+}
+
+function isJsonObject(input: Schema.Json | undefined): input is Schema.JsonObject {
+  return typeof input === "object" && input !== null && !Array.isArray(input)
+}
+
+function withoutDescription(check: SchemaAST.Filter<any>): SchemaAST.Filter<any> {
+  return check.annotate({
+    description: undefined,
+    expected: undefined,
+    title: undefined
+  })
+}
+
+function structuralAnnotations(
+  ast: SchemaAST.AST,
+  structuralDescription: string
+): Schema.Annotations.Annotations {
+  const descriptions: Array<string> = []
+  appendAnnotationDescription(descriptions, ast.annotations)
+  if (ast.checks !== undefined) {
+    for (const check of ast.checks) appendCheckDescriptions(descriptions, check)
+  }
+  return {
+    description: descriptions.length === 0
+      ? structuralDescription
+      : `${structuralDescription}; ${descriptions.join(" and ")}`
+  }
+}
+
+function appendCheckDescriptions(descriptions: Array<string>, check: SchemaAST.Check<any>): void {
+  appendAnnotationDescription(descriptions, check.annotations)
+  if (check._tag === "FilterGroup") {
+    for (const child of check.checks) appendCheckDescriptions(descriptions, child)
+  }
+}
+
+function appendAnnotationDescription(
+  descriptions: Array<string>,
+  annotations: Schema.Annotations.Annotations | undefined
+): void {
+  const description = annotations?.description ?? annotations?.expected
+  if (typeof description === "string" && !descriptions.includes(description)) {
+    descriptions.push(description)
+  }
+}
+
+type JsonSchemaVisitor = (schema: JsonSchema.JsonSchema) => JsonSchema.JsonSchema
+
+/** @internal */
+export function walkJsonSchema(
+  schema: JsonSchema.JsonSchema,
+  visitor: JsonSchemaVisitor
+): JsonSchema.JsonSchema {
+  const out: JsonSchema.JsonSchema = {}
+  for (const [key, value] of Object.entries(schema)) {
+    switch (key) {
+      case "properties":
+      case "patternProperties": {
+        if (isJsonSchema(value)) {
+          const properties: Record<string, unknown> = {}
+          for (const [name, property] of Object.entries(value)) {
+            InternalRecord.assignProperty(
+              properties,
+              name,
+              isJsonSchema(property) ? walkJsonSchema(property, visitor) : property
+            )
+          }
+          InternalRecord.assignProperty(out, key, properties)
+        } else {
+          InternalRecord.assignProperty(out, key, value)
+        }
+        break
+      }
+      case "additionalProperties":
+      case "items":
+      case "propertyNames": {
+        InternalRecord.assignProperty(out, key, isJsonSchema(value) ? walkJsonSchema(value, visitor) : value)
+        break
+      }
+      case "prefixItems":
+      case "allOf":
+      case "anyOf":
+      case "oneOf": {
+        InternalRecord.assignProperty(
+          out,
+          key,
+          Array.isArray(value)
+            ? value.map((member) => isJsonSchema(member) ? walkJsonSchema(member, visitor) : member)
+            : value
+        )
+        break
+      }
+      default:
+        InternalRecord.assignProperty(out, key, value)
+        break
+    }
+  }
+  return visitor(out)
+}
+
+/** @internal */
+export function appendDescription(schema: JsonSchema.JsonSchema, description: string): void {
+  if (typeof schema.description === "string") {
+    const descriptions = schema.description.split(" and ")
+    if (!descriptions.includes(description)) schema.description += ` and ${description}`
+  } else {
+    schema.description = description
+  }
+}
+
+/** @internal */
+export function isJsonSchema(input: unknown): input is JsonSchema.JsonSchema {
+  return typeof input === "object" && input !== null && !Array.isArray(input)
+}

package/src/unstable/cli/CliError.ts

@@ -2,11 +2,11 @@
  * Defines structured errors for the unstable CLI parser and runner.
  *
  * CLI errors describe problems such as unknown or duplicate flags, missing
- * flags or arguments, invalid values, unknown subcommands, user handler
- * failures, and requests to show command help. This module includes the
- * `CliError` union, the `isCliError` guard, schema-backed error classes with
- * display messages, and the `NonShowHelpErrors` union used when parse or
- * validation errors should be shown with help output.
+ * flags or arguments, unexpected positional arguments, invalid values, unknown
+ * subcommands, user handler failures, and requests to show command help. This
+ * module includes the `CliError` union, the `isCliError` guard, schema-backed
+ * error classes with display messages, and the `NonShowHelpErrors` union used
+ * when parse or validation errors should be shown with help output.
  *
  * @since 4.0.0
  */
@@ -89,6 +89,7 @@ export type CliError =
   | DuplicateOption
   | MissingOption
   | MissingArgument
+  | UnexpectedArgument
   | InvalidValue
   | UnknownSubcommand
   | ShowHelp
@@ -307,6 +308,49 @@ export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
   }
 }
 
+/**
+ * Error thrown when positional arguments remain after a command has parsed all
+ * of its parameters.
+ *
+ * **Example** (Reporting unexpected arguments)
+ *
+ * ```ts
+ * import { CliError } from "effect/unstable/cli"
+ *
+ * const error = new CliError.UnexpectedArgument({
+ *   arguments: ["extra.txt"]
+ * })
+ *
+ * console.log(error.message)
+ * // "Unexpected positional argument: \"extra.txt\""
+ * ```
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgument>(
+  `${TypeId}/UnexpectedArgument`
+)("UnexpectedArgument", {
+  arguments: Schema.Array(Schema.String)
+}) {
+  /**
+   * Marks this value as an unexpected CLI argument error for runtime guards.
+   *
+   * @since 4.0.0
+   */
+  readonly [TypeId] = TypeId
+
+  /**
+   * Formats the unexpected positional arguments for display.
+   *
+   * @since 4.0.0
+   */
+  override get message() {
+    const label = this.arguments.length === 1 ? "argument" : "arguments"
+    return `Unexpected positional ${label}: ${this.arguments.map((value) => JSON.stringify(value)).join(", ")}`
+  }
+}
+
 /**
  * Error thrown when an option or argument value is invalid.
  *
@@ -506,6 +550,7 @@ export const NonShowHelpErrors: Schema.Union<
     typeof DuplicateOption,
     typeof MissingOption,
     typeof MissingArgument,
+    typeof UnexpectedArgument,
     typeof InvalidValue,
     typeof UnknownSubcommand,
     typeof UserError
@@ -515,6 +560,7 @@ export const NonShowHelpErrors: Schema.Union<
   DuplicateOption,
   MissingOption,
   MissingArgument,
+  UnexpectedArgument,
   InvalidValue,
   UnknownSubcommand,
   UserError

package/src/unstable/cli/Command.ts

@@ -1068,7 +1068,7 @@ export const withSubcommands: {
 
     const context = yield* impl.parseContext(raw)
     const result = yield* sub.parse(raw.subcommand.value.parsedInput)
-    return Object.assign({}, context, { [SubcommandStateSymbol]: { name: sub.name, result } }) as NextInput
+    return { ...context, [SubcommandStateSymbol]: { name: sub.name, result } } as NextInput
   })
 
   const handle = Effect.fnUntraced(function*(input: NextInput, path: ReadonlyArray<string>) {
@@ -1184,20 +1184,20 @@ export const withSharedFlags: {
     type NextInput = Simplify<Input & SharedInput>
     type NextContextInput = Simplify<ContextInput & SharedInput>
 
-    const parseShared = makeParser(sharedConfig) as (
+    const parseShared = makeParser(sharedConfig, { allowLeftovers: true }) as (
       input: ParsedTokens
     ) => Effect.Effect<SharedInput, CliError.CliError, Environment>
 
     const parse = Effect.fnUntraced(function*(raw: ParsedTokens) {
       const base = yield* impl.parse(raw)
       const shared = yield* parseShared(raw)
-      return Object.assign({}, base, shared) as NextInput
+      return { ...(base as object), ...(shared as object) } as NextInput
     })
 
     const parseContext = Effect.fnUntraced(function*(raw: ParsedTokens) {
       const base = yield* impl.parseContext(raw)
       const shared = yield* parseShared(raw)
-      return Object.assign({}, base, shared) as NextContextInput
+      return { ...(base as object), ...(shared as object) } as NextContextInput
     })
 
     const handle = (

package/src/unstable/cli/Param.ts

@@ -343,14 +343,14 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
     params.kind === argumentKind
       ? parsePositional(params.name, params.primitiveType, args)
       : parseFlag(params.name, params.primitiveType, args)
-  return Object.assign(Object.create(Proto), {
+  return Object.setPrototypeOf({
     _tag: "Single",
     ...params,
     description: params.description ?? Option.none(),
     aliases: params.aliases ?? [],
     hidden: params.hidden ?? false,
     parse
-  })
+  }, Proto)
 }
 
 /**
@@ -865,7 +865,7 @@ export const keyValuePair = <Kind extends ParamKind>(
       }),
       { min: 1 }
     ),
-    (objects) => Object.assign({}, ...objects)
+    (objects) => Object.fromEntries(objects.flatMap(Object.entries))
   )
 
 /**

package/src/unstable/cli/Primitive.ts

@@ -236,7 +236,7 @@ export const integer: Primitive<number> = makeSchemaPrimitive(
  */
 export const date: Primitive<Date> = makeSchemaPrimitive(
   "Date",
-  Schema.DateValid
+  Schema.Date
 )
 
 /**

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

@@ -125,7 +125,7 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
       : Effect.fail(new CliError.ShowHelp({ commandPath, errors: [] }))
 
   const parse = options.parse ?? makeParser(config) as any
-  const parseContext = options.parseContext ?? makeParser(contextConfig) as any
+  const parseContext = options.parseContext ?? makeParser(contextConfig, { allowLeftovers: true }) as any
 
   const buildHelpDoc = (commandPath: ReadonlyArray<string>): HelpDoc => {
     const args: Array<ArgDoc> = []
@@ -263,10 +263,18 @@ const appendChoiceKeys = (
  * and `parseContext`, and also by `withSharedFlags` to avoid constructing a
  * full throwaway command.
  */
-export const makeParser = (cfg: ConfigInternal) =>
+export const makeParser = (
+  cfg: ConfigInternal,
+  options?: {
+    readonly allowLeftovers?: boolean | undefined
+  } | undefined
+) =>
   Effect.fnUntraced(function*(input: ParsedTokens) {
     const parsedArgs: Param.ParsedArgs = { flags: input.flags, arguments: input.arguments }
-    const values = yield* parseParams(parsedArgs, cfg.orderedParams)
+    const [remainingArguments, values] = yield* parseParams(parsedArgs, cfg.orderedParams)
+    if (options?.allowLeftovers !== true && remainingArguments.length > 0) {
+      return yield* new CliError.UnexpectedArgument({ arguments: remainingArguments })
+    }
     return reconstructTree(cfg.tree, values)
   })
 
@@ -275,7 +283,7 @@ export const makeParser = (cfg: ConfigInternal) =>
  * representations.
  */
 const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.Any>) => Effect.Effect<
-  ReadonlyArray<unknown>,
+  readonly [remainingArguments: ReadonlyArray<string>, values: ReadonlyArray<unknown>],
   CliError.CliError,
   Environment
 > = Effect.fnUntraced(function*(parsedArgs, params) {
@@ -291,7 +299,7 @@ const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.An
     currentArguments = remainingArguments
   }
 
-  return results
+  return [currentArguments, results] as const
 })
 
 /**