feat(cli): pre-run render context probe (#69)

[kjanat]

Closes #69.

Problem

Inside a handler, out answers every rendering question (jsonMode, isTTY, color, isHyperlinkSupported). Content built before run() has no out, so consumers re-derive the decisions from raw argv — in the naive form the framework's own docstring warns against:

const JSON_MODE = argv.includes('--json'); // wrong: `mycli -- --json` is a literal

The consumer and the framework then disagree about the same fact, using the same argv.

Solution — both options from the issue

Option 2 (the probe): resolveRenderContext(argv, options?) returns { jsonMode, isTTY, color, isHyperlinkSupported }. It is implemented by feeding the same composition .execute()/.run() give createOutput — ---aware --json detection via includesBeforeSeparator, the hyperlink override via resolveHyperlinkOverride, the color auto-gate — and reading the resolved channel back. No duplicated gating logic, so the probe cannot drift from the channel that will actually render.

One deviation from the issue's sketch: color is the gated Colors palette (the same shape as out.color) rather than a bare boolean — consumers want to style, and identity formatters mean they can do so unconditionally. ctx.color.isColorSupported is the boolean form.

options carries the host facts core cannot read (isTTY, env) plus explicit jsonMode/color overrides — same seams as execute(). Core stays process-free.

Option 1 (the primitives): includesBeforeSeparator and stripBeforeSeparator are exported from the package root for consumers who only need correct ---aware flag reads.

Tests

render-context.test.ts — pre/post-separator --json, explicit overrides, TTY-default and JSON-mode color gating, explicit color: true, and the full hyperlink matrix (NO_HYPERLINKS, FORCE_HYPERLINKS, --no-hyperlinks pre/post-separator). Public-export JSDoc coverage passes.

Docs

guide/output.md gains a "Pre-run Render Context" section with a validated twoslash example; built successfully.

Full suite (2893), typecheck, biome, dprint, deno check, docs build all pass.

Bumps to 3.0.0-rc.16.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds the exported resolveRenderContext API for pre-run JSON, TTY, colour, and hyperlink decisions. It also exports separator-aware root-flag helpers from the package root, adds focused tests, documents usage, and updates the package and release versions to 3.0.0-rc.16.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant resolveRenderContext
  participant FlagParser
  participant OutputChannel
  participant HyperlinkResolver
  Caller->>resolveRenderContext: Provide argv and options
  resolveRenderContext->>FlagParser: Detect flags before --
  resolveRenderContext->>OutputChannel: Apply JSON, TTY, and colour gating
  resolveRenderContext->>HyperlinkResolver: Resolve hyperlink support
  resolveRenderContext-->>Caller: Return render context

Loading

Possibly related issues

• KAJ-315 — Directly covers exporting the render-context and separator-aware parsing helpers implemented here.

Possibly related PRs

• kjanat/dreamcli#31 — Introduces the separator-aware flag handling used by this render-context work.
• kjanat/dreamcli#53 — Uses the same root-flag parsing helpers for --json handling.
• kjanat/dreamcli#71 — Shares the hyperlink enablement logic lifted into pre-run context resolution.

Suggested labels: area: resolve

Poem

Arrr, the flags now heed the double-dash tide,
Colours and links know when to hide.
JSON sails clean, with no ANSI foam,
Render context finds its way home.
RC.16 be shipped—hoist the API!

🚥 Pre-merge checks | ✅ 8 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Semver Version Bump Validation	⚠️ Warning	Additive public APIs were added, but the version only moved 3.0.0-rc.15→3.0.0-rc.16, not the required minor bump.	Bump package.json/deno.json to 3.1.0 (or 3.1.0-rc.0 if staying prerelease).
Agents.Md Documentation Updated	⚠️ Warning	AGENTS.md exists in docs/ and src/core/cli/, but the PR changes docs/guide/output.md and src/core/cli/index.ts without touching either AGENTS file.	Update the affected AGENTS.md files (docs/AGENTS.md and src/core/cli/AGENTS.md) to cover the new docs and CLI interface changes.
Title check	⚠️ Warning	The title is relevant, but it uses feat: instead of the required lowercase verb prefix such as add:.	Rename it to something like add(cli): pre-run render context probe (#69).},{

✅ Passed checks (8 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy #69 by adding the pre-run render-context API and the separator-aware parsing helpers.
Out of Scope Changes check	✅ Passed	The diff stays on scope, with only docs, tests, changelog, and version bump around the feature work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Release Metadata Sync	✅ Passed	Aye: package.json and deno.json both say 3.0.0-rc.16, and CHANGELOG.md has the matching rc.16 heading plus correct Unreleased/rc.16 compare links.
Runtime Support Sync	✅ Passed	PR only bumps version and adds render-context APIs/docs; no Node/Bun/Deno minimums or support claims changed, and support-truth files are untouched.
No Generated Docs Artifacts	✅ Passed	No files under docs/.vitepress/dist/ or docs/.vitepress/cache/ were changed; the diff only touches changelog, config, docs, and src files.
Changelog Update	✅ Passed	PASS: code files changed, CHANGELOG.md was updated with a new [3.0.0-rc.16] section dated 2026-07-20, and the entry documents the added APIs.
Description check	✅ Passed	The description clearly matches the render-context API, exported helpers, tests, docs, and version bump.

---

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

[pkg-pr-new]

Open in StackBlitz

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

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

commit: ec856ec

[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	ec856ec	Commit Preview URL Branch Preview URL	Jul 20 2026, 08:21 PM