feat: add the experimental --with-ai options for generate-arazzo command

[DmitryAnansky]

What/Why/How?

Added --with-ai and --ai-provider options for generate-arazzo command .

Notes:

• Use x-security when possible.
• Provide hint with placeholders how to execute generated workflow.
• Complex security flows are not supported due to lack of initial information to reconstruct it.

Reference

https://github.com/Redocly/redocly/issues/25890

Testing

Screenshots (optional)

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Medium Risk
--with-ai sends the resolved OpenAPI spec to external/local AI CLIs, and generator security/auth output changed in ways that affect generated Respect workflows.

Overview
generate-arazzo gains optional --with-ai (with --ai-provider and --max-workflows) to turn the one-workflow-per-operation skeleton into multi-step scenarios via a local AI CLI (claude, codex, cursor). Responses are validated (operation refs, workflow count, spec lint) and failures fall back to the mechanical baseline; successful AI output is prefixed with a verification comment.

After generation, the command prints a ready-to-run respect line with --input placeholders (including resolved component input refs).

The handler moves under commands/generate-arazzo/; AI helpers are shared with generate-spec via utils/ai/ (providers, stripCodeFences, lintDocumentSource). respect-core now returns a TestDescription from generate(), bumps generated Arazzo to 1.1.0, and wires auth through per-step x-security (replacing workflow Authorization parameters), with expanded security input shapes (e.g. basic username/password, OAuth2).

^{Reviewed by Cursor Bugbot for commit 454eee1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 454eee1

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

This PR includes changesets to release 4 packages

Name	Type
@redocly/cli	Minor
@redocly/openapi-core	Minor
@redocly/respect-core	Minor
@redocly/client-generator	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

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x ± 0.01	▓ 1.00x (Fastest)	▓ 1.01x ± 0.01
cli-next	▓ 1.00x (Fastest)	▓ 1.02x ± 0.01	▓ 1.00x (Fastest)

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	78.61% (🎯 77%)	14043 / 17863
🔵	Statements	78.38% (🎯 77%)	15133 / 19306
🔵	Functions	82.28% (🎯 81%)	2885 / 3506
🔵	Branches	71.65% (🎯 71%)	10429 / 14554

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/types.ts	100%	100%	100%	100%
packages/cli/src/commands/generate-arazzo/index.ts	93.33%	89.28%	80%	93.33%	46, 89-90
packages/cli/src/commands/generate-arazzo/ai/generate-workflows.ts	87.32%	80%	87.5%	88.57%	37, 71, 75, 81, 85, 91, 106-110, 193
packages/cli/src/commands/generate-arazzo/ai/prompt.ts	100%	100%	100%	100%
packages/cli/src/commands/generate-spec/index.ts	0%	0%	0%	0%	31-113
packages/cli/src/commands/generate-spec/ai/refine.ts	97.1%	86.11%	100%	97.05%	106, 137, 141, 240
packages/cli/src/utils/ai/output.ts	100%	100%	100%	100%
packages/respect-core/src/generate.ts	0%	100%	0%	0%	17
packages/respect-core/src/modules/arazzo-description-generator/generate-arazzo-description.ts	100%	85.71%	100%	100%
packages/respect-core/src/modules/arazzo-description-generator/generate-inputs-arazzo-components.ts	100%	100%	100%	100%
packages/respect-core/src/modules/arazzo-description-generator/generate-step-security.ts	94.73%	90.9%	100%	94.73%	32
packages/respect-core/src/modules/arazzo-description-generator/generate-workflows-from-description.ts	100%	76.66%	100%	100%

Generated in workflow #11524 for commit 454eee1 by the Vitest Coverage Report Action

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 454eee1. Configure here.}

[cursor]

Oversized-spec log claims a send

Low Severity

When the prompt still exceeds MAX_PROMPT_CHARS after stripProse, the command logs that it is sending the description without description and example fields, then throws and never calls the provider. Users with large specs see a “sending” message followed by a failure that the description was too large to send.

 

^{Reviewed by Cursor Bugbot for commit 454eee1. Configure here.}