feat(core): ctx.raw.argv, render helpers, dynamic fullscreen

[zrosenbauer]

Summary

• ctx.raw.argv — Normalized argv on the command context where argv[0] is always the CLI name (via yargs $0). Middleware can inspect the full invocation without guessing preamble offsets.
• render() / renderToString() — Kidd-wrapped Ink render helpers that auto-inject KiddProvider with screen context. Enables full lifecycle control from normal command() handlers (e.g., post-exit child process spawning).
• Dynamic fullscreen — screen({ fullscreen }) now accepts (ctx: ScreenContext) => boolean | Promise<boolean> for runtime decisions based on args, config, or terminal capabilities.

Test plan

• pnpm typecheck passes
• pnpm test — 1066 tests passing (81 test files)
• New tests for ctx.raw.argv (frozen, normalized, independent from input)
• New tests for render() and renderToString() (KiddProvider injection, options passthrough)
• New tests for dynamic fullscreen (sync fn, async fn, false resolver, ctx passthrough)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
oss-kidd	Ignored	Preview	Apr 2, 2026 10:58pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 56a6c44

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

This PR includes changesets to release 2 packages

Name	Type
@kidd-cli/core	Minor
@kidd-cli/cli	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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 70fd7ae8-ebf4-4dde-a8cb-84c17f2357f7

📥 Commits

Reviewing files that changed from the base of the PR and between 1bdc2aa and 56a6c44.

📒 Files selected for processing (1)

• packages/core/src/screen/render.test.tsx

---

📝 Walkthrough

Walkthrough

This PR threads a normalized, immutable CLI argv through the system: cli() now derives tokens via hideBin(process.argv) and passes argv into createRuntime; RuntimeOptions requires argv; createRuntime forwards argv to createContext; CreateContextOptions and CommandContext gain a frozen raw.argv. The screen subsystem adds render and renderToString, exports toScreenContext, and extends ScreenDef.fullscreen to accept boolean or (possibly async) resolver invoked with the computed ScreenContext. Tests and test helpers updated to supply and assert argv/raw and fullscreen resolver behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• feat: support dynamic/async resolution for screen().fullscreen #148: Implements dynamic/async fullscreen resolution — this PR adds ScreenDef.fullscreen as boolean | (ctx => boolean | Promise) and awaits the resolver.

Possibly related PRs

• refactor(core): rename Context to CommandContext #104: Both modify CommandContext shape and typing; this PR adds a frozen raw.argv field to the context.
• fix(core): clear alt screen buffer before leaving fullscreen #102: Both change fullscreen/teardown behavior in the screen implementation, including handling of leave/enter sequences.
• refactor(packages/core,packages/cli): fix coding standards violations #41: Both touch CLI argv normalization/propagation (cli → runtime → context) and related types.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 64.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the three main features: ctx.raw.argv, render helpers, and dynamic fullscreen. It is concise and specific to the core changes.
Description check	✅ Passed	The description clearly relates to the changeset, detailing the three major features (ctx.raw.argv, render/renderToString helpers, and dynamic fullscreen) with concrete use cases and testing confirmation.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ctx-raw-argv-render-helpers-dynamic-fullscreen

---

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 2 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing feat/ctx-raw-argv-render-helpers-dynamic-fullscreen (56a6c44) with main (c93cbfc)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/core/src/screen/render.test.tsx`:
- Around line 7-16: The mock functions for the ink module are missing type
parameters on vi.fn(), causing ESLint failures; update each vi.fn() call in the
mock (the top-level render and renderToString entries and the nested cleanup,
clear, rerender, unmount, waitUntilExit) to include the correct generic types
matching the real ink API (e.g., the render function's return shape and
waitUntilExit's Promise<void> signature) so the mocked signatures align with the
real types and satisfy eslint-plugin-vitest's require-mock-type-parameters rule.
- Line 120: The test uses a non-null assertion on
mockedInkRenderToString.mock.calls[0] when assigning rendered; replace the '!'
with a safe check or assertion helper: read the first call with optional
chaining (mockedInkRenderToString.mock.calls[0]?.[0]) or assert the call exists
with an explicit expect/assert before casting, then cast to ReactElement (or
narrow the type to ReactElement | undefined) so you avoid the non-null
assertion; update the assignment for rendered and add a preceding
expect(mockedInkRenderToString.mock.calls.length).toBeGreaterThan(0) or similar
to guarantee the value is present.
- Line 83: The test uses a forbidden non-null assertion on
mockedInkRender.mock.calls[0] when assigning rendered; replace the `!` with a
safe access and fallback or an assertion helper: retrieve the first call using
optional chaining (or Array.prototype.at(0)) and check/assert that it exists
before casting to ReactElement (or call an assertDefined/assertIsNotNull helper
to fail the test early), then assign that value to rendered; update the
reference to mockedInkRender and rendered to ensure the code no longer uses `!`.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f86d2e7b-3b0a-48cd-ac26-e5c17bcc7638

📥 Commits

Reviewing files that changed from the base of the PR and between c93cbfc and e5cb3d3.

⛔ Files ignored due to path filters (3)

• .changeset/ctx-raw-argv.md is excluded by !.changeset/**
• .changeset/dynamic-fullscreen.md is excluded by !.changeset/**
• .changeset/render-helpers.md is excluded by !.changeset/**

📒 Files selected for processing (17)

• packages/core/src/cli.ts
• packages/core/src/context/create-context.test.ts
• packages/core/src/context/create-context.ts
• packages/core/src/context/decorate.test.ts
• packages/core/src/context/types.ts
• packages/core/src/index.ts
• packages/core/src/middleware/auth/auth-http-chain.test.ts
• packages/core/src/middleware/typed-middleware.test.ts
• packages/core/src/runtime/runtime.ts
• packages/core/src/runtime/types.ts
• packages/core/src/screen/index.ts
• packages/core/src/screen/render.test.tsx
• packages/core/src/screen/render.tsx
• packages/core/src/screen/screen.test.ts
• packages/core/src/screen/screen.tsx
• packages/core/src/test/context.ts
• packages/core/src/ui/index.ts