feat!: unify the source model across flags and args with a real stdin contract

[kjanat]

Targets v4. Stacked on #113. L15 of the input-model unification.

One resolution chain for both surfaces: CLI, stdin fallback, env, config, prompt, default. Args gain .config() and .prompt(); flags gain .stdin(); both share StdinBinding ({ when: dash | missing | dash-or-missing, consume: exclusive | broadcast }). An explicit - is a CLI-precedence value whose bytes come from stdin; implicit fallback is its own stage that beats env. One exclusive stdin consumer per command is enforced at build time on both construction paths (DUPLICATE_STDIN_INPUT, naming the input that already consumes); readStdin runs only when resolution will select a stdin source, pinned by adapter call counts. ValueInput gains a first-class stdin input with env strictness: one trailing terminator stripped for every codec except string, so piped booleans, enums, durations, and dates decode while string and path keep bytes exactly (Decision 5). The resolver walks the SourceBinding projection itself, so projection and behavior cannot drift. Resolution records internal per-input provenance in the Decision 8 shape for L18. readFlags and the testkit mirror everything. The arg stdinMode boolean fragment is redesigned to the stdin config shape (schemaVersion stays 1 per Decision 2). Args also render [config:]/[prompt] help annotations.

Review catches included the projection being production-dead while disagreeing with the resolver on defaults (fixed by making the resolver walk the bindings), and the exclusivity error naming the wrong input. A parity probe against the L14 tip is byte-identical for schemas using none of the new capability.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	dreamcli	a8fbc35	Commit Preview URL Branch Preview URL	Aug 04 2026, 11:16 AM

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• cr:review

🚫 Excluded labels (none allowed) (2)

• wip
• cr:skip

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 885480c1-7d00-45a3-800f-4eeeb26bc783

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

feat!: unify flag and argument source resolution

• Unify resolution for flags and arguments: CLI → stdin → env → config → prompt → default.
• Add configurable StdinBinding support with trigger and consumption modes.
• Read stdin only when resolution selects it.
• Enforce exclusive stdin consumption during schema construction.
• Add config and prompt sources to positional arguments.
• Track source provenance for resolved inputs.
• Update runtime adapters, readFlags, testkit support, schemas, JSON serialisation, documentation, and tests.
• Replace stdinMode with structured stdin bindings.
• Rename duplicate-consumer errors to DUPLICATE_STDIN_INPUT.
• Apply codec-specific stdin terminator handling and validation.
• Preserve byte-identical output for schemas without the new capabilities.

Walkthrough

The change introduces a shared CLI → stdin → env → config → prompt → default resolution chain for flags and positional arguments. It adds typed stdin bindings with dash and missing-value modes, exclusive or broadcast consumption, conditional runtime reads, unified coercion, provenance tracking, and structured schema export. Positional arguments gain configuration and prompt sources. Tests and documentation cover schema validation, parsing, resolution, decoding, runtime adapters, help output, and testkit execution.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant RuntimeAdapter
  participant Resolver
  participant Command
  CLI->>Resolver: parse flags and arguments
  Resolver->>RuntimeAdapter: read stdin when invocation selects it
  RuntimeAdapter-->>Resolver: return stdinData
  Resolver->>Resolver: apply env, config, prompt, or default stages
  Resolver-->>Command: return values and provenance

Loading

Possibly related issues

• KAJ-330 — Adds configuration and prompt source parity for positional arguments.
• Tracking: provenance, cross-flag relationships, and help grouping #88 — Adds resolution provenance to ResolveResult.
• KAJ-339 — Introduces source-stage provenance for resolved values.
• KAJ-341 — Implements winning resolution stages for flags and arguments.
• Value provenance: track resolution stage and expose explicitness to handlers #90 — Addresses the resolver provenance requirement.

Possibly related PRs

• kjanat/dreamcli#1 — Extends earlier configuration and resolution-stage work.
• kjanat/dreamcli#3 — Connects to the runtime adapter readStdin() path.
• kjanat/dreamcli#7 — Modifies stdin-backed input resolution and runtime stdin handling.

Suggested labels: kind: feature, kind: breaking, area: schema, area: resolve, area: docs

Poem

stdin joins the source chain, arrr,
Flags and args now share the bar.
Config and prompts fall in line,
Provenance marks each source sign.
Broadcast streams now flow with cheer—
The resolver’s course is clear.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Release Metadata Sync	❌ Error	package.json and deno.json both declare 3.0.1, but CHANGELOG.md has no [3.0.1] link and [Unreleased] still compares v3.0.0-rc.17 to HEAD.	Add the [3.0.1] comparison link and update [Unreleased] to compare from v3.0.1 to HEAD.
Title check	⚠️ Warning	The title describes the main change but is 78 characters long and does not include the required word "add" for a new feature.	Use a concise title under 50 characters that starts with "add:" and clearly describes the unified stdin source model.
Semver Version Bump Validation	⚠️ Warning	Source files changed, but package.json remains at 3.0.1, matching HEAD^; the PR has breaking public API changes and no required MAJOR SemVer bump.	Update package.json from the base version 3.0.1 to a valid v4 MAJOR version, and keep any released version metadata consistent.
Agents.Md Documentation Updated	❓ Inconclusive	Evidence collection is still in progress.	Inspect all affected directories and their AGENTS.md files before deciding.

✅ Passed checks (7 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the unified source model, stdin contract, resolver changes, validation, provenance, and compatibility goals.
Docstring Coverage	✅ Passed	Docstring coverage is 82.69% which is sufficient. The required threshold is 30.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Runtime Support Sync	✅ Passed	The PR changes stdin resolution documentation, not Node.js, Bun, or Deno minimums or runtime support claims; package engines, support.ts, adapter tests, and runtime support tables are unchanged.
No Generated Docs Artifacts	✅ Passed	The PR commit changes no paths under docs/.vitepress/dist/ or docs/.vitepress/cache/, and neither generated-artifact directory exists in the repository tree.
Changelog Update	✅ Passed	Source files changed, and CHANGELOG.md is updated under ## [Unreleased] with entries for the unified source model, stdin support, breaking changes, and decoding behaviour; no version bump is pres...

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

bun add https://pkg.pr.new/@kjanat/dreamcli@114

npm i https://pkg.pr.new/@kjanat/dreamcli@114

commit: 6bbb5b9