feat: add generate-spec command

[sobanieca-redocly]

What/Why/How?

Added new generate-spec command which will infer OAD basing on traffic data. To improve accuracy, there is option to use AI agents to improve results.

Reference

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
Large new surface area and --with-ai exfiltrates traffic samples to external CLIs; deterministic path is lower risk but output quality depends on capture coverage.

Overview
Adds an experimental generate-spec CLI command that builds an OpenAPI 3.1 description from recorded HTTP traffic (HAR, Kong, Nginx/Apache JSON, NDJSON), reusing the same traffic parsing as drift.

The pipeline is deterministic first: path templating for ID-like segments, schema merge with oneOf for alternate bodies and nullable unions, repeated shapes lifted to components/schemas, and conservative format/enum inference from observed strings. Optional --with-ai refines one operation at a time via local claude, codex, or cursor CLIs; accepted output must keep path/method, all observed status codes, and pass lint with the pinned spec ruleset, otherwise that operation keeps the baseline. Traffic samples (URLs, bodies) are sent to the provider when AI is enabled.

Wiring includes yargs registration, CODEOWNERS, changeset, command README, unit tests, and e2e tests with stub AI CLIs.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 45980fa

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

This PR includes changesets to release 3 packages

Name	Type
@redocly/cli	Minor
@redocly/openapi-core	Minor
@redocly/respect-core	Minor

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]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	70.29% (🎯 69%)	8364 / 11898
🔵	Statements	70.03% (🎯 69%)	8707 / 12433
🔵	Functions	74.95% (🎯 73%)	1661 / 2216
🔵	Branches	62.02% (🎯 61%)	5624 / 9068

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/commands/generate-spec/components.ts	85.14%	61.18%	78.57%	86.77%	45, 234-251, 258-278, 363
packages/cli/src/commands/generate-spec/generator.ts	56.43%	49.61%	63.41%	54.82%	108, 202, 209, 240, 252-262, 265, 285, 347-351, 364, 366, 430, 437, 453-755
packages/cli/src/commands/generate-spec/index.ts	0%	0%	0%	0%	31-113
packages/cli/src/commands/generate-spec/samples.ts	85.13%	72.58%	100%	84.93%	43, 52, 71, 74, 83, 113, 123-127, 171
packages/cli/src/commands/generate-spec/value-inference.ts	93.33%	90%	100%	94.73%	49, 127, 133, 146
packages/cli/src/commands/generate-spec/ai/prompt.ts	42.85%	27.77%	66.66%	42.85%	34-55
packages/cli/src/commands/generate-spec/ai/providers.ts	1.4%	0%	0%	1.4%	24-167
packages/cli/src/commands/generate-spec/ai/refine.ts	97.01%	83.87%	100%	96.96%	103, 134, 138, 236

Generated in workflow #10689 for commit 45980fa by the Vitest Coverage Report Action

[github-actions]

Performance Benchmark (Lower is Faster)

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

[sobanieca-redocly]

@cursor review

[sobanieca-redocly]

@cursor review

[sobanieca-redocly]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

2 issues from previous reviews remain unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 956bf00. Configure here.}

[sobanieca-redocly]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 3a11b20. Configure here.}

[sobanieca-redocly]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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

[sobanieca-redocly]

@cursor review

[sobanieca-redocly]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 90a2052. Configure here.}