Register alternate flags used by Param.orElse

[fubhy]

Summary

A valid alternate flag supplied through Param.orElse is rejected as unrecognized before fallback parsing can run.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

Param.orElse alternate flags are not registered

Module: cli/Param
Audit ID: unstable-ai-cli-param-orelse-flag-registration
Severity / confidence: high / high

What happens

A valid alternate flag supplied through Param.orElse is rejected as unrecognized before fallback parsing can run.

Why it happens

The fallback is retained only in a transform closure, while parameter extraction traverses only the primary parameter and omits the alternate name from the command registry.

Expected behavior

Param.orElse accepts a fallback parameter, including one with a different flag name.

Relevant implementation

These links and excerpts are pinned to audit base c9b56ab507f224426ee8388dc450da447ec4715f.

• packages/effect/src/unstable/cli/Param.ts:1847-1862
• packages/effect/src/unstable/cli/Param.ts:2143-2152
• packages/effect/src/unstable/cli/internal/parser.ts:59-61

View problematic code at packages/effect/src/unstable/cli/Param.ts:1847-1862

export const orElse: {
  <B, Kind extends ParamKind>(
    orElse: (error: CliError.CliError) => Param<Kind, B>
  ): <A>(self: Param<Kind, A>) => Param<Kind, A | B>
  <Kind extends ParamKind, A, B>(
    self: Param<Kind, A>,
    orElse: (error: CliError.CliError) => Param<Kind, B>
  ): Param<Kind, A | B>
} = dual(2, <Kind extends ParamKind, A, B>(
  self: Param<Kind, A>,
  orElse: (error: CliError.CliError) => Param<Kind, B>
) =>
  transform(
    self,
    (parse: Parse<A>): Parse<A | B> => (args: ParsedArgs) => Effect.catch(parse(args), (err) => orElse(err).parse(args))
  ))

View exact lines on GitHub

View problematic code at packages/effect/src/unstable/cli/Param.ts:2143-2152

export const extractSingleParams = <Kind extends ParamKind, A>(
  param: Param<Kind, A>
): Array<Single<Kind, unknown>> => {
  return matchParam(param, {
    Single: (single) => [single as Single<Kind, unknown>],
    Map: (mapped) => extractSingleParams(mapped.param),
    Transform: (mapped) => extractSingleParams(mapped.param),
    Optional: (optional) => extractSingleParams(optional.param),
    Variadic: (variadic) => extractSingleParams(variadic.param)
  })

View exact lines on GitHub

View problematic code at packages/effect/src/unstable/cli/internal/parser.ts:59-61

    const singles = commandImpl.config.flags.flatMap(Param.extractSingleParams)
    const flagParams = singles.filter(Param.isFlagParam)
    const flagRegistry = createFlagRegistry(flagParams)

View exact lines on GitHub

Reproduction

pnpm test --run packages/effect/test/unstable/cli/ParamOrElseFlag.audit.test.ts

Observed failure: FAIL: --config-url produced UnrecognizedOption.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

1. Start with the pinned implementation excerpts and the Why it happens analysis above.
2. Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
3. Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm test --run packages/effect/test/unstable/cli/ParamOrElseFlag.audit.test.ts

4. Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

• Audit base: c9b56ab507f224426ee8388dc450da447ec4715f
• Reproduction base: c9b56ab507f224426ee8388dc450da447ec4715f
• Findings: unstable-ai-cli-param-orelse-flag-registration
• Initial patch: focused reproduction tests; implementation fix pending

Closes EFF-398

[changeset-bot]

🦋 Changeset detected

Latest commit: 8a4c9f2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages

Name	Type
effect	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-deno	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/vitest	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/docgen	Patch
@effect/doctest	Patch
@effect/openapi-generator	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

Important

This PR title and commit message say alternate flags are now registered, but the diff only adds the failing reproduction test. The actual implementation fix is missing from packages/effect/src/unstable/cli/Param.ts, so CI will stay red. Push the fix to this branch before merging, or convert the PR to draft and adjust the title.

Reviewed changes

• Added a focused reproduction test in packages/effect/test/unstable/cli/Param.test.ts that demonstrates Flag.orElse(...Flag.string("config-url")) is rejected as an unrecognized option.

⚠️ Implementation fix is missing

The reproduction test is accurate and currently fails with UnrecognizedOption: --config-url. The PR does not yet contain the registration change promised by the title.

Technical details

# Missing alternate flag registration

## Affected sites
- `packages/effect/src/unstable/cli/Param.ts:1861` — `orElse` wraps the fallback param in a parse-time closure inside a `Transform` node.
- `packages/effect/src/unstable/cli/Param.ts:1907` — same pattern in `orElseResult`.
- `packages/effect/src/unstable/cli/Param.ts:2149` — `extractSingleParams` for `Transform` only recurses into `mapped.param`, so the alternate name is never surfaced.
- `packages/effect/src/unstable/cli/internal/parser.ts:59` — command-level flag registry is built from `extractSingleParams`.

## Required outcome
- `orElse`/`orElseResult` register all potential fallback `Single` params for lexer/parser validation.
- The existing reproduction assertions remain unchanged and should pass once the fix is added.

## Suggested approach
- Extend the `Transform` representation to retain the fallback constructor, or otherwise make fallback singles discoverable by `extractSingleParams`.
- Apply the same treatment to `orElseResult`.
- Consider adding a `Command.run` test to verify the alternate flag value flows to the original field.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Run failed. View the logs →

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[github-actions]

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name	Current Size	Previous Size	Difference
basic.ts	7.06 KB	7.06 KB	0.00 KB (0.00%)
batching.ts	9.86 KB	9.86 KB	0.00 KB (0.00%)
brand.ts	6.34 KB	6.34 KB	0.00 KB (0.00%)
cache.ts	10.62 KB	10.71 KB	-0.09 KB (-0.81%)
config.ts	20.60 KB	20.60 KB	0.00 KB (0.00%)
differ.ts	20.20 KB	20.20 KB	0.00 KB (0.00%)
http-client.ts	21.49 KB	21.58 KB	-0.09 KB (-0.41%)
logger.ts	10.76 KB	10.84 KB	-0.08 KB (-0.76%)
metric.ts	8.98 KB	8.98 KB	0.00 KB (0.00%)
optic.ts	7.18 KB	7.18 KB	0.00 KB (0.00%)
pubsub.ts	14.90 KB	14.99 KB	-0.09 KB (-0.57%)
queue.ts	11.58 KB	11.66 KB	-0.08 KB (-0.68%)
schedule.ts	10.74 KB	10.83 KB	-0.09 KB (-0.80%)
schema-class.ts	19.14 KB	19.14 KB	0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts	28.96 KB	28.96 KB	0.00 KB (0.00%)
schema-representation-roundtrip.ts	25.29 KB	25.29 KB	0.00 KB (0.00%)
schema-string-transformation.ts	13.30 KB	13.38 KB	-0.09 KB (-0.64%)
schema-string.ts	10.94 KB	10.94 KB	0.00 KB (0.00%)
schema-template-literal.ts	15.17 KB	15.17 KB	0.00 KB (0.00%)
schema-toArbitraryLazy.ts	21.94 KB	21.94 KB	0.00 KB (0.00%)
schema-toCodeDocument.ts	24.34 KB	24.34 KB	0.00 KB (0.00%)
schema-toCodecJson.ts	19.18 KB	19.18 KB	0.00 KB (0.00%)
schema-toEquivalence.ts	19.01 KB	19.01 KB	0.00 KB (0.00%)
schema-toFormatter.ts	18.87 KB	18.87 KB	0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts	22.60 KB	22.60 KB	0.00 KB (0.00%)
schema-toRepresentation.ts	19.52 KB	19.52 KB	0.00 KB (0.00%)
schema.ts	18.41 KB	18.41 KB	0.00 KB (0.00%)
stm.ts	12.54 KB	12.63 KB	-0.09 KB (-0.74%)
stream.ts	9.80 KB	9.80 KB	0.00 KB (0.00%)