Fix default command UX and status exits

[kjanat]

Summary

• add out.setExitCode(code) for normal-output non-zero status exits
• report unknown root tokens as UNKNOWN_COMMAND when a default command has no positional args
• document the exit-code seam in docs, skills, and changelog

Closes #26.
Closes #27.

Tests

• bun test src/core/cli/planner.test.ts src/core/cli/cli-default.test.ts src/core/output/output.test.ts src/core/testkit/executor-contract.test.ts src/core/testkit/testkit-json.test.ts src/runtime/runtime.test.ts
• bun run typecheck
• bun run lint
• bun run format:check
• bun run test
• bun run docs:build

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces two independent changes, savvy? First, a shiny new setExitCode(code: number) method gets wired onto the Out interface and OutputChannel class, backed by a per-Out WeakMap with integer 0–255 validation. The executor reads the requested exit code on the success path and clears it before and after each command run; CLIBuilder.execute() also clears it at startup. Second, the CLI planner's unknown-root dispatch gets tightened proper-like: two new helpers (canDelegateUnknownRootToDefault, findUnknownFlagBeforePositional) ensure unknown tokens are only delegated to a default command when it accepts positionals; otherwise a structured UNKNOWN_COMMAND or UNKNOWN_FLAG error be returned. Both changes be covered by new unit, contract, and integration tests, plus documentation across guides, references, and skill files. The dprint exec plugin be bumped from 0.6.2 to 0.7.2.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• kjanat/dreamcli#30: The planner's new flagExpectsValue argv scanning for unknown flags is directly aligned with this PR's flag value-arity-aware command dispatch improvements.

Suggested labels

kind: bug, kind: feature, area: cli, area: output

Poem

⚓ Arr, the exit codes sail true at last!
No more error storms when status be cast~
setExitCode(7), normal output flows free,
Unknown commands meet their UNKNOWN decree!
Nya~ the WeakMap holds each code with care,
This pirate-girl's changelog: beyond compare! 🏴‍☠️✨

🚥 Pre-merge checks | ✅ 10 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Semver Version Bump Validation	⚠️ Warning	Source code files modified (6 files, new public APIs added), but version in package.json remains 2.3.0; requires bump to 2.4.0 for MINOR feature addition.	Update package.json version from 2.3.0 to 2.4.0 (MINOR bump for backward-compatible API additions).

✅ Passed checks (10 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Fix default command UX and status exits' is concise, follows conventional commit guidelines with 'Fix' prefix, and clearly summarises the main changes: fixing default command behaviour and adding exit code functionality.
Docstring Coverage	✅ Passed	Docstring coverage is 30.00% 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.
Release Metadata Sync	✅ Passed	Release metadata remains properly aligned: package.json and deno.json both declare version 2.3.0, CHANGELOG.md contains [Unreleased] section and matching [2.3.0] latest release heading with correct...
Runtime Support Sync	✅ Passed	This PR changes exit-code handling and unknown-command reporting, not runtime support claims. No modifications to package.json engines, src/runtime/support.ts, README.md, or runtime docs were made.
No Generated Docs Artifacts	✅ Passed	The PR contains no modifications to docs/.vitepress/dist/ or docs/.vitepress/cache/ directories. All 23 modified files are source code, documentation, and test files—nary a generated artifact in si...
Changelog Update	✅ Passed	Source code files modified across 6 files; CHANGELOG.md properly updated under [Unreleased] with two entries (Added: setExitCode; Fixed: unknown-command handling) accurately describing changes, fol...
Agents.Md Documentation Updated	✅ Passed	All affected modules with code changes have corresponding AGENTS.md files that were properly updated: src/core/cli/ documents UNKNOWN_COMMAND dispatch behaviour, src/core/output/ documents setExitC...
Description check	✅ Passed	The PR description directly addresses the changeset, clearly documenting the addition of out.setExitCode(code), unknown command reporting fixes, and comprehensive documentation updates across multiple files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

[pkg-pr-new]

Open in StackBlitz

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

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

commit: 82e5dd3