Cli: Handle nested array schema for AI help

[huang-julien]

Closes #

What I did

Support showing array schema details instead of just
--collections (array, required)

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

run the storybook ai --help command and check if the array sche!ma shows details for the array items

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• New Features

  • Enhanced CLI help output to show richer, schema-based argument details for AI tools.
  • Nested objects, array items, and selectable variants are now displayed more clearly in help text.

• Bug Fixes

  • Help output now handles complex argument schemas more gracefully, including unsupported shapes, by falling back to a simpler description instead of failing.
  • Improved handling of required arguments so they are labeled more clearly in generated help.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a recursive JsonSchemaNode type and JsonSchemaNodeSchema valibot schema in types.ts, then uses them in run-tool.ts to render nested, schema-driven argument help text (objects, array items, anyOf/oneOf variants) with bounded depth, replacing the prior flat property listing. New tests cover nested expansion, union variants, and fallback rendering.

Changes

Recursive JSON Schema Help Rendering

Layer / File(s)	Summary
Schema type and validation contract code/core/src/cli/ai/mcp/types.ts	Adds recursive JsonSchemaNode interface and JsonSchemaNodeSchema valibot schema (using v.lazy and looseObject) supporting properties, items, and anyOf/oneOf.
Nested schema rendering in help output code/core/src/cli/ai/mcp/run-tool.ts	Adds MAX_SCHEMA_DEPTH, schemaLines, and traversal helpers to render nested object/array/union schema details; formatToolHelp now safeParses each argument against JsonSchemaNodeSchema and falls back to a minimal type/description node on parse failure, replacing the previous flat argument listing.
Tests for nested, union, and fallback rendering code/core/src/cli/ai/mcp/run-tool.test.ts	Adds runAiToolHelp tests validating recursive expansion of nested object properties, anyOf/oneOf option rendering, and graceful fallback to top-level type/description when a schema cannot be modeled.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• storybookjs/storybook#35212: Both PRs modify the storybook ai <command> --help / runAiToolHelp path in run-tool.ts, with this PR extending it with recursive schema-based argument rendering.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

code/core/src/cli/ai/mcp/run-tool.test.ts (1)

802-857: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding a oneOf test case or clarifying the test name.

The test is named "describes anyOf/oneOf union variants in help" but only exercises anyOf. While both use the same code path (schema.anyOf ?? schema.oneOf), a dedicated oneOf assertion would guard against future divergence.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@code/core/src/cli/ai/mcp/run-tool.test.ts` around lines 802 - 857, The test
name suggests coverage for both anyOf and oneOf, but the current case only
exercises anyOf in runAiToolHelp. Update the test in run-tool.test.ts by either
renaming it to reflect anyOf-only behavior or, preferably, add a separate oneOf
assertion that also validates the same union-variant help output path through
runAiToolHelp and loadStorybookAiMetadata. Keep the existing snapshot-style
expectations aligned with the union variant labels so future changes to
schema.anyOf ?? schema.oneOf are covered.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@code/core/src/cli/ai/mcp/run-tool.test.ts`:
- Around line 802-857: The test name suggests coverage for both anyOf and oneOf,
but the current case only exercises anyOf in runAiToolHelp. Update the test in
run-tool.test.ts by either renaming it to reflect anyOf-only behavior or,
preferably, add a separate oneOf assertion that also validates the same
union-variant help output path through runAiToolHelp and
loadStorybookAiMetadata. Keep the existing snapshot-style expectations aligned
with the union variant labels so future changes to schema.anyOf ?? schema.oneOf
are covered.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1a9c79b2-a6e6-4136-8c72-db349f841226

📥 Commits

Reviewing files that changed from the base of the PR and between 4cf1f20 and 9a33c03.

📒 Files selected for processing (3)

• code/core/src/cli/ai/mcp/run-tool.test.ts
• code/core/src/cli/ai/mcp/run-tool.ts
• code/core/src/cli/ai/mcp/types.ts

[github-actions]

	Fails
🚫	node failed.

Log

Details

Error:  Error: Could not find the Dangerfile at scripts/dangerfile.ts - if it is local, perhaps you have a typo? If it's using a remote file, it doesn't have a repo reference.
    at /usr/src/danger/dist/platforms/GitHub.js:161:27
    at step (/usr/src/danger/dist/platforms/GitHub.js:44:23)
    at Object.next (/usr/src/danger/dist/platforms/GitHub.js:25:53)
    at /usr/src/danger/dist/platforms/GitHub.js:19:71
    at new Promise (<anonymous>)
    at __awaiter (/usr/src/danger/dist/platforms/GitHub.js:15:12)
    at Object.executeRuntimeEnvironment (/usr/src/danger/dist/platforms/GitHub.js:144:88)
    at /usr/src/danger/dist/commands/danger-runner.js:101:47
    at step (/usr/src/danger/dist/commands/danger-runner.js:34:23)
    at Object.next (/usr/src/danger/dist/commands/danger-runner.js:15:53)
danger-results://tmp/danger-results-0ec124c2.json

Generated by 🚫 dangerJS against 6cf1848