Prompt kind/type mismatch: multiselect accepted on enum flag, then fails at runtime

[kjanat]

Summary

flag.enum([...]).prompt({ kind: 'multiselect' }) is currently accepted, but it fails at runtime with a ValidationError.

This is confusing because the prompt config is accepted up front, and the failure only appears later during resolution.

Minimal repro

import { command, flag } from '@kjanat/dreamcli';
import { runCommand } from '@kjanat/dreamcli/testkit';

const story = command('story')
  .flag(
    'mood',
    flag
      .enum(['calm', 'chaos', 'legendary'])
      .prompt({ kind: 'multiselect', message: 'Set the mood!' }),
  )
  .action(({ flags, out }) => {
    out.log(String(flags.mood));
  });

const result = await runCommand(story, [], { answers: [['calm']] });
console.log(result);

Actual behavior

• Exit code: 2
• Error: ValidationError
• Message:

Invalid value 'calm' from prompt for flag --mood. Allowed: calm, chaos, legendary
Suggestion: Select one of: calm, chaos, legendary

Expected behavior

One of these should happen instead:

1. Type-level/config-time rejection for incompatible combinations (e.g. multiselect on scalar flags like enum/string/number/boolean), or
2. Clear runtime config error before prompting (e.g. "multiselect is only supported for array-valued flags").

Context

Docs already describe multiselect as array-oriented, so this looks like a prompt kind vs flag output-type compatibility gap in validation/typing.

[kjanat]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

FINALLY we be fixin' this wretched mess! Arrr, the approach be clean and surgical:

• Add a validation gate in resolvePromptValueWithConfig() that checks prompt kind against flag kind compatibility before any promptin' occurs
• Return a clear ValidationError with actionable suggest guidance when combinations be incompatible
• Define explicit compatibility rules: confirm↔boolean, input↔string/number, select↔enum, multiselect↔array
• Follow existing error patterns with proper code, details, and suggest fields so the error be genuinely helpful instead of that confusin' mess about "Invalid value 'calm'"

Design Choices

Design Choice 1: Runtime validation vs. type-level constraint approach

Options Considered:

1. Add kind to FlagConfig and create conditional types for FlagBuilder.prompt() to only accept compatible prompt configs at compile time
2. Add runtime validation in resolvePromptValueWithConfig() that throws a clear ValidationError before promptin' when kinds be incompatible

Chosen Option: 2

Rationale: Runtime validation be the surgical fix that solves the immediate problem (confusin' error message) without invasive type system changes. The error will be clear and actionable, thrown before any promptin' occurs. Type-level constraints can be a future enhancement if the crew desires it.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Add Prompt-Flag Compatibility Validation

Arrr, this phase adds a validation gate in the resolution pipeline that catches incompatible prompt kind / flag kind combinations before the prompter runs, replacin' the current confusin' coercion error with a clear, actionable message. No more blowin' up at runtime with nonsense errors, ye scurvy dogs!

Task 1: Implement Compatibility Check in Resolution Pipeline

Add validation logic to resolvePromptValueWithConfig() that verifies the prompt kind be compatible with the flag's kind before proceedin' to resolution. Finally, a proper guard so we stop lookin' like fools!

• Add a helper function (e.g., validatePromptFlagCompatibility) in src/core/resolve/flags.ts that maps prompt kinds to their compatible flag kinds:
  • confirm → boolean only
  • input → string or number
  • select → enum
  • multiselect → array
  • custom flag kind → allow any prompt kind (we can't know the underlying type)
• Call this validation at the top of resolvePromptValueWithConfig() before resolvePromptConfig() is invoked
• Return a { ok: false, error: ValidationError } result with:
  • code: 'INVALID_PROMPT_CONFIG' (or similar semantic code)
  • details includin' flag, flagKind, promptKind
  • suggest with actionable guidance (e.g., "Use 'select' prompt for enum flags" or "Change to flag.array() for multiselect prompts")
• Follow the existing pattern where errors flow through PromptResolveResult and get aggregated by resolveFlags()

Task 2: Add Tests for Prompt-Flag Incompatibility Validation

Add test coverage in the resolve test suite verifyin' that incompatible prompt/flag combinations produce clear errors. We test it PROPERLY or we don't test it at all, savvy?!

• Add tests in src/core/resolve/resolve-prompt.test.ts (or a new dedicated section) coverin':
  • multiselect prompt on enum flag → ValidationError with clear message (the exact case from the ticket)
  • multiselect prompt on string flag → ValidationError
  • confirm prompt on string flag → ValidationError
  • select prompt on boolean flag → ValidationError
  • Valid combinations continue to work (regression tests): multiselect + array, select + enum, confirm + boolean, input + string
• Use the existing catchValidationError helper pattern from resolve-errors.test.ts
• Assert on error.code, error.suggest, and error.details to verify the error be properly structured and actionable

🤖 Prompt for AI agents

This phase adds a validation gate in `src/core/resolve/flags.ts` to catch
incompatible prompt kind / flag kind combinations before the prompter is ever
invoked, replacing the confusing runtime `ValidationError` with a clear,
actionable one.

**Task 1: Implement Compatibility Check (`src/core/resolve/flags.ts`)**
- Add a helper function `validatePromptFlagCompatibility` (or similarly named)
that defines the compatibility map:
  - `confirm` → `boolean` only
  - `input` → `string` or `number`
  - `select` → `enum`
  - `multiselect` → `array`
  - `custom` flag kind → allow any prompt kind
- Call this helper at the very top of `resolvePromptValueWithConfig()`, before
`resolvePromptConfig()` is invoked
- On incompatibility, return `{ ok: false, error: ValidationError }` with:
  - `code: 'INVALID_PROMPT_CONFIG'` (or a similarly semantic code)
  - `details` containing `flag`, `flagKind`, and `promptKind`
- `suggest` with actionable guidance (e.g., `"Use 'select' prompt for enum
flags"` or `"Change to flag.array() for multiselect prompts"`)
- Follow the existing error-flow pattern so results propagate through
`PromptResolveResult` and get aggregated by `resolveFlags()`

**Task 2: Add Tests (`src/core/resolve/resolve-prompt.test.ts`)**
- Add a dedicated section for prompt-flag incompatibility validation
- Cover these incompatible combinations (each should produce a
`ValidationError`):
  - `multiselect` on `enum` flag (the exact ticket case)
  - `multiselect` on `string` flag
  - `confirm` on `string` flag
  - `select` on `boolean` flag
- Cover valid combinations as regression tests:
  - `multiselect` + `array`
  - `select` + `enum`
  - `confirm` + `boolean`
  - `input` + `string`
- Use the existing `catchValidationError` helper pattern from
`resolve-errors.test.ts`
- Assert on `error.code`, `error.suggest`, and `error.details` for every
incompatible case

Research

Arrr, here be what we found in the cursed codebase!

This be a well-structured CLI framework with src/core/schema/ holdin' the flag and prompt type definitions, src/core/resolve/ handlin' the resolution pipeline (CLI→env→config→prompt→default), and src/core/prompt/ managin' the actual prompter logic. The key file be src/core/resolve/flags.ts where resolvePromptValueWithConfig() has access to both the FlagSchema (with its .kind) and the PromptConfig (with its .kind)—the perfect spot to intercept this blasted incompatibility before the prompter even gets invoked.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase adds a validation gate in `src/core/resolve/flags.ts` to catch
incompatible prompt kind / flag kind combinations before the prompter is ever
invoked, replacing the confusing runtime `ValidationError` with a clear,
actionable one.

**Task 1: Implement Compatibility Check (`src/core/resolve/flags.ts`)**
- Add a helper function `validatePromptFlagCompatibility` (or similarly named)
that defines the compatibility map:
  - `confirm` → `boolean` only
  - `input` → `string` or `number`
  - `select` → `enum`
  - `multiselect` → `array`
  - `custom` flag kind → allow any prompt kind
- Call this helper at the very top of `resolvePromptValueWithConfig()`, before
`resolvePromptConfig()` is invoked
- On incompatibility, return `{ ok: false, error: ValidationError }` with:
  - `code: 'INVALID_PROMPT_CONFIG'` (or a similarly semantic code)
  - `details` containing `flag`, `flagKind`, and `promptKind`
- `suggest` with actionable guidance (e.g., `"Use 'select' prompt for enum
flags"` or `"Change to flag.array() for multiselect prompts"`)
- Follow the existing error-flow pattern so results propagate through
`PromptResolveResult` and get aggregated by `resolveFlags()`

**Task 2: Add Tests (`src/core/resolve/resolve-prompt.test.ts`)**
- Add a dedicated section for prompt-flag incompatibility validation
- Cover these incompatible combinations (each should produce a
`ValidationError`):
  - `multiselect` on `enum` flag (the exact ticket case)
  - `multiselect` on `string` flag
  - `confirm` on `string` flag
  - `select` on `boolean` flag
- Cover valid combinations as regression tests:
  - `multiselect` + `array`
  - `select` + `enum`
  - `confirm` + `boolean`
  - `input` + `string`
- Use the existing `catchValidationError` helper pattern from
`resolve-errors.test.ts`
- Assert on `error.code`, `error.suggest`, and `error.details` for every
incompatible case

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!