refactor(cli-agents): readonly-domain-types (stack 12/12, re-split #307)

[YosefHayim]

User description

Stack 12/12 of re-split HOLD #307

Domain: cli-agents
Base: refactor/types/readonly-stack-11-services
Full green tip: refactor/foundation/readonly-types-full

Land stack in order. Intermediate PRs may not typecheck alone.

---

Summary by cubic

Refactors CLI agents and related utilities to use readonly types throughout, improving type safety and aligning with the readonly domain model. No runtime behavior changes.

• Refactors
  • CLI commands (completion, testflight) and option collector now accept readonly arrays.
  • Dashboard and docs table renderers accept readonly collections; command option table uses readonly OptionSpec from @core/types/commandDocs.js.
  • Terminal helpers (completion, halfblock, wizardCommand) updated to readonly inputs.
  • MCP tests use readonly config and tool output shapes to match gate/tool contracts.
  • Insights normalization uses MutableDeep when constructing ReviewDatum to satisfy readonly types.

^{Written for commit d0c226d. Summary will update on new commits.}

---

CodeAnt-AI Description

Allow CLI and rendering utilities to use read-only input data

What Changed

• Command completion, TestFlight tester management, environment options, and wizard flows now accept read-only lists without requiring callers to copy them.
• Documentation, dashboard, terminal rendering, MCP, and insights helpers can consume read-only collections while preserving their existing output and behavior.
• Review normalization still adds optional dates correctly while working with the updated read-only domain types.

Impact

✅ Fewer unnecessary data copies in CLI workflows
✅ Safer reuse of configuration and command data
✅ Unchanged command output and user workflows

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d0c226d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[codeant-ai]

🤖 CodeAnt AI — Review Status

Status	Commit	Started (UTC)	Finished (UTC)
✅ Reviewed your PR	d0c226d	Aug 07, 2026 · 11:07	11:09

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[qodo-code-review]

PR Summary by Qodo

Refactor cli-agents consumers for readonly domain types

✨ Enhancement 🧪 Tests 🕐 10-20 Minutes

AI Description

• Update CLI command handlers and helpers to accept readonly argument arrays.
• Align core renderers/docs/terminal flows with readonly domain collection types.
• Adjust insights normalization to construct readonly domain objects via deep-mutable builder type.

Diagram

graph TD
  A["@core/types (readonly)"] --> B["CLI commands"] --> C["core terminal"]
  A --> D["docs renderer"]
  A --> E["dashboard renderer"]
  A --> F["MCP tests"]
  A --> G["insights command"] --> H["MutableDeep helper"]

  subgraph Legend
    direction LR
    _t["Type defs"] ~~~ _m["Module"] ~~~ _te["Tests"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Build ReviewDatum immutably (no MutableDeep)

• ➕ Avoids introducing/depending on a deep-mutable escape hatch in command code
• ➕ Keeps object construction aligned with readonly types at every step
• ➖ More verbose: requires conditional spreads or separate object branches for optional fields
• ➖ Can be harder to read than a single object with a conditional assignment

2. Make ReviewDatum fields mutable (relax domain type)

• ➕ Eliminates need for MutableDeep and simplifies normalization builders
• ➖ Undercuts the readonly-domain-types initiative and allows unintended mutation elsewhere
• ➖ Broadens API surface risk across many consumers

Recommendation: Keep the PR’s approach: accept readonly arrays at boundaries and use MutableDeep only where a readonly domain object needs incremental construction. This preserves the readonly domain contract while keeping the normalization code straightforward; consider the immutable-builder alternative only if MutableDeep usage starts spreading beyond a few localized construction sites.

Files changed (13) +21 / -20

Refactor (10) +17 / -16

completion.tsAccept readonly completion words in Commander action +1/-1

Accept readonly completion words in Commander action

• Updates the hidden completion subcommand action signature to 'readonly string[]' so it matches readonly argv collection types while passing through to the completion program.

src/cli/commands/completion.ts

testflight.tsMake tester email argument arrays readonly +2/-2

Make tester email argument arrays readonly

• Changes the 'add' and 'rm' subcommand action signatures to accept 'readonly string[]' email lists, aligning with readonly domain typing without altering behavior.

src/cli/commands/testflight.ts

options.tsUse readonly accumulator in commander env collector +1/-1

Use readonly accumulator in commander env collector

• Updates the 'collectEnv' reducer to accept a 'readonly string[]' previous accumulator while still returning a new mutable 'string[]' for commander.

src/cli/options.ts

render.tsRender dashboard tables from readonly lists +4/-4

Render dashboard tables from readonly lists

• Updates table rendering helpers (apps/accounts/artifacts/secrets) to take 'readonly' arrays, matching readonly dashboard state shapes.

src/core/dashboard/render.ts

commandReference.tsRender option tables from readonly option specs +1/-1

Render option tables from readonly option specs

• Changes the options table renderer to accept 'readonly OptionSpec[]', matching the command spec’s readonly collections.

src/core/docs/commandDocs/commandReference.ts

common.tsCount test cases from readonly sources list +1/-1

Count test cases from readonly sources list

• Updates 'countTestCases' to accept a 'readonly string[]' input list while keeping counting logic identical.

src/core/docs/commandDocs/common.ts

command.tsUse MutableDeep when constructing readonly ReviewDatum +3/-2

Use MutableDeep when constructing readonly ReviewDatum

• Imports 'MutableDeep' and uses it for 'normalizedReview' objects so optional fields can be assigned during normalization even though 'ReviewDatum' is readonly.

src/core/insights/command.ts

completion.tsAccept readonly words when descending commander tree +1/-1

Accept readonly words when descending commander tree

• Updates 'descendCommandTree' to accept 'readonly string[]' words to align with readonly CLI argument flows.

src/core/terminal/completion.ts

halfblock.tsRender halfblock rows from readonly cell arrays +1/-1

Render halfblock rows from readonly cell arrays

• Changes 'renderRow' to accept 'readonly Cell[]' while keeping rendering logic unchanged.

src/core/terminal/halfblock.ts

wizardCommand.tsAccept readonly configured apps in wizard flows +2/-2

Accept readonly configured apps in wizard flows

• Updates 'selectPlatform' and 'flowInvalidReason' to take 'readonly AppDescriptor[]', aligning wizard logic with readonly collections.

src/core/terminal/wizardCommand.ts

Tests (3) +4 / -4

gate.test.tsAllow readonly capability arrays in test config helper +1/-1

Allow readonly capability arrays in test config helper

• Updates the test 'config' helper to accept 'readonly McpCapability[]', aligning with readonly capability lists.

src/core/mcp/gate.test.ts

tools.test.tsTighten MCP test fixtures to readonly shapes +2/-2

Tighten MCP test fixtures to readonly shapes

• Updates the test 'config' helper to accept 'readonly' capability arrays and tightens 'parseToolOutput'’s 'content' typing to readonly nested structures.

src/core/mcp/tools.test.ts

wizardCommand.test.tsMake wizard test config helper accept readonly profile names +1/-1

Make wizard test config helper accept readonly profile names

• Updates 'configWith' to accept 'readonly string[]' profile name lists, matching readonly domain typing expectations.

src/core/terminal/wizardCommand.test.ts

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2d9d7154-4975-48fb-a588-e028256a549d

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[cubic-dev-ai]

No issues found across 13 files

_{Re-trigger cubic}

[YosefHayim]

Superseded by land of tip stack #386 (same 12 domain commits).