Function resolveFirstValue

packages/effect/src/unstable/cli/internal/parser.ts:781–847

(
  value: string,
  cursor: TokenCursor,
  context: CommandContext,
  state: ParseState
)

 * - Report error if command expects subcommand but got unknown value
 */
const resolveFirstValue = (
  value: string,
  cursor: TokenCursor,
  context: CommandContext,
  state: ParseState
): FirstValueResult => {
  const { command, commandPath, inheritedFlagRegistry, localFlagNames } = context
  const subIndex = buildSubcommandIndex(command.subcommands)
  const sub = subIndex.get(value)

  if (sub) {
    const selectedPath = [...commandPath, sub.name]

    // Local flags are not inherited by subcommands.
    const parentFlags = state.flags.snapshot()
    for (const localFlagName of localFlagNames) {
      const values = parentFlags[localFlagName]
      if (values !== undefined && values.length > 0) {
        state.errors.push(
          new CliError.UnrecognizedOption({
            option: `--${localFlagName}`,
            suggestions: [],
            command: selectedPath
          })
        )
      }
    }

    // npm-style: inherited parent flags can appear after subcommand name
    const tail = consumeKnownFlags(cursor.rest(), inheritedFlagRegistry)
    state.flags.merge(tail.flagMap)
    state.errors.push(...tail.errors)

    return {
      _tag: "Subcommand",
      result: {
        _tag: "Sub",
        flags: state.flags.snapshot(),
        sub,
        childTokens: tail.remainder,
        errors: state.errors
      }
    }
  }

  // Not a subcommand. Check if this looks like a typo.
  const expectsArgs = toImpl(command).config.arguments.length > 0
  if (!expectsArgs && subIndex.size > 0) {
    // Exclude unlisted subcommands so a typo cannot reveal a subcommand name
    // that was intentionally kept out of --help. Unlisted commands still
    // resolve via subIndex when invoked by exact name.
    const visibleKeys: Array<string> = []
    for (const [key, sub] of subIndex) {
      if (!sub.unlisted) visibleKeys.push(key)
    }
    const suggestions = suggest(value, visibleKeys)
    state.errors.push(
      new CliError.UnknownSubcommand({