chore(cli): bundle with bun target node and publish from staged dir by RomanHotsiy · Pull Request #2637 · Redocly/redocly-cli

RomanHotsiy · 2026-03-04T14:46:51Z

What/Why/How?

Switch CLI build output to Bun bundling for Node (bun build --target node) instead of the previous TypeScript-only compile flow.
Fix bundled-runtime resolution issues by replacing runtime createRequire('../../package.json') patterns with static JSON imports in CLI runtime paths.
Add a built-in build-docs template fallback so bundled artifacts do not depend on template.hbs being present as a filesystem asset.
Replace publish-time package.json mutation/restore with a staged publish directory (packages/cli/.publish) and publishConfig.directory so changeset publish publishes from the staged manifest/artifacts.
Keep the staged directory minimal: bin/cli.js, bundled lib/index.js, README.md, LICENSE, and a stripped package.json (no deps/devDeps/scripts).
Update local pack/smoke/perf/release snapshot flows to use the staged directory.
Update CI jobs that execute e2e/pack/publish flows to ensure Bun is installed.

Reference

N/A

Testing

npm --workspace packages/cli run compile
node packages/cli/lib/index.js --help
npm run typecheck
npm run pack:prepare
npm run release (no unpublished packages in this run; verified publish-dir prepare/cleanup path)

Screenshots (optional)

N/A

Check yourself

Code changed? - Tested with Redoc/Realm/Reunite (internal)
All new/updated code is covered by tests
New package installed? - Tested in different environments (browser/node)
Documentation update considered

Security

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

Note

Medium Risk
Medium risk because it replaces the CLI build and npm publish mechanics (Bun bundling + staged publish directory), which can break installs, releases, and runtime asset resolution if misconfigured.

Overview
Bundles the CLI into a single Node-targeted output using Bun (with an npx bun fallback) to reduce install time and avoid runtime require-style package.json lookups.

Changes publishing/packing to a staged packages/cli/.publish directory via publishConfig.directory and new prepare:publish-dir/cleanup scripts, and updates release/snapshot/local pack flows (plus .gitignore) to publish/pack from that directory.

Hardens bundled runtime behavior by embedding a fallback build-docs Handlebars template when template.hbs isn’t available on disk, and wiring redoc version lookup through a static JSON import. CI workflows are updated to install Bun and e2e now bundles the CLI before running.

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

changeset-bot · 2026-03-04T14:46:59Z

🦋 Changeset detected

Latest commit: 1b232c3

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	Patch
@redocly/openapi-core	Patch
@redocly/respect-core	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 · 2026-03-04T14:49:00Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	79.92% (🎯 79%)	6693 / 8374
🔵	Statements	79.33% (🎯 79%)	6920 / 8722
🔵	Functions	83.06% (🎯 82%)	1354 / 1630
🔵	Branches	71.64% (🎯 71%)	4554 / 6356

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/commands/build-docs/index.ts	93.33%	50%	100%	93.33%	53
packages/cli/src/commands/build-docs/utils.ts	59.45%	33.33%	85.71%	61.11%	51-72, 127, 134, 149
packages/cli/src/utils/package.ts	100%	100%	100%	100%

Generated in workflow #9288 for commit 1b232c3 by the Vitest Coverage Report Action

github-actions · 2026-03-04T14:49:15Z

CLI Version	Mean Time ± Std Dev (s)	Relative Performance (Lower is Faster)
cli-latest	3.426s ± 0.045s	▓ 1.03x
cli-next	3.318s ± 0.009s	▓ 1.00x (Fastest)

github-actions · 2026-03-04T14:49:16Z

📦 A new experimental 🧪 version v0.0.0-snapshot.1772635755 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1772635755
# or
npm install @redocly/openapi-core@0.0.0-snapshot.1772635755
# or
npm install @redocly/respect-core@0.0.0-snapshot.1772635755

⚠️ Note: This is a development build and may contain unstable features.

.changeset/olive-bobcats-happen.md

tatomyr

Had a brief look. Will give it another pass later.

tatomyr · 2026-03-12T07:53:24Z

packages/cli/src/commands/build-docs/index.ts

 import { performance } from 'node:perf_hooks';
 import { default as redoc } from 'redoc';

+import packageJson from '../../../package.json' with { type: 'json' };


It probably makes more sense to import it from utils/package.js.

packages/cli/src/utils/package.ts

tatomyr · 2026-03-12T08:04:07Z

tests/e2e/helpers.ts

 }

+function cleanUpStyledComponentWarnings(str: string): string {
+  return str.replace(/^styled-components: it looks like an unknown prop .*?(?:\r?\n|$)/gm, '');


I don't see the message anywhere. Why do wee need this?

tatomyr · 2026-03-12T08:06:20Z

scripts/release-publish.mjs

+  const result = spawnSync(command, args, {
+    cwd: rootDir,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',


Are we going to publish from Win?

tatomyr · 2026-03-16T14:00:44Z

packages/cli/package.json

-    "prepublishOnly": "npm run copy-assets && cp ../../README.md ."
+    "compile": "bun build src/index.ts --target node --define process.env.NODE_ENV=process.env.NODE_ENV --outfile lib/index.js",
+    "prepare:publish-dir": "node ./scripts/prepare-publish-dir.mjs",
+    "clean:publish-dir": "node ./scripts/clean-publish-dir.mjs"


Why not simply use rm?

tatomyr · 2026-03-16T14:00:51Z

scripts/release-publish.mjs

+
+try {
+  run('npm', ['--workspace', 'packages/cli', 'run', 'prepare:publish-dir']);
+  run('npm', ['exec', 'changeset', 'publish']);


How does it know it should publish from packages/cli/.publish/ and not from packages/cli/?

"publishConfig": { "directory": ".publish" },

in cli/package.json

tatomyr · 2026-03-16T14:19:37Z

packages/cli/scripts/prepare-publish-dir.mjs

+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== undefined);
+  return Object.fromEntries(entries);


Suggested change

if (!value || typeof value !== 'object') {

return value;

}

const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== undefined);

return Object.fromEntries(entries);

if (isPlainObject(value)) {

const entries = Object.entries(value).filter(([, entryValue]) => entryValue !== undefined);

return Object.fromEntries(entries);

}

return value

Anyways, why do we need to clean up the constructed package json programmatically? Let's just construct it the way we want.

package.json

cursor

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

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

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

cursor · 2026-04-06T07:20:19Z

scripts/release-publish.mjs

+    }
+
+    if (result.status !== 0) {
+      process.exit(result.status ?? 1);


process.exit() bypasses finally cleanup in release script

Medium Severity

The run() function calls process.exit() when a command returns a non-zero exit code. In Node.js, process.exit() terminates the process immediately without unwinding the call stack, so the finally block on line 36 that runs clean:publish-dir never executes. Only the throw path (for spawn errors) is catchable. This means if changeset publish fails with a non-zero exit code, the .publish directory is never cleaned up. Changing the non-zero-status path to throw instead of process.exit() would let the try/catch/finally work as intended.

Additional Locations (1)

scripts/release-publish.mjs#L35-L39

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

tatomyr

Left a minor comment. Please also check this comment: #2637 (comment).
Otherwise LGTM.

tatomyr · 2026-04-06T11:32:51Z

packages/cli/scripts/compile-bundle.mjs

+  }
+
+  console.warn('Bun binary not found on PATH; falling back to `npx bun@1.3.10`.');
+  return spawnSync('npx', ['--yes', 'bun@1.3.10', ...bunBuildArgs], {


Why not just use bun as a dev dependency?

I think it's overkill, we need it only for publishing, I would keep it as is.

RomanHotsiy added 2 commits March 4, 2026 22:44

chore(cli): bundle with bun target node and publish from staged dir

84999a0

style: format publish-dir script

d4754ad

RomanHotsiy added the snapshot Create experimental release PR label Mar 4, 2026

RomanHotsiy removed the snapshot Create experimental release PR label Mar 4, 2026

RomanHotsiy added 7 commits March 4, 2026 22:51

fix(docker): install bun before pack preparation

072a87b

fix(cli): fallback to npx bun when bun is unavailable

7dcbf5e

chore(realm): add bun to the docker

008c0e0

fix(docker): include docs files in build context

62b8e8d

fix(docker): remove obsolete build-docs template copy

d35db98

test(smoke): refresh pre-built docs fixture for bundled cli

70fefcf

chore: add changeset

9515d93

RomanHotsiy marked this pull request as ready for review March 12, 2026 03:43

RomanHotsiy requested review from a team as code owners March 12, 2026 03:43

JLekawa reviewed Mar 12, 2026

View reviewed changes

.changeset/olive-bobcats-happen.md Outdated Show resolved Hide resolved

Apply suggestion from @JLekawa

b902fbf

JLekawa approved these changes Mar 12, 2026

View reviewed changes

tatomyr reviewed Mar 12, 2026

View reviewed changes

tatomyr reviewed Mar 16, 2026

View reviewed changes

chore: fixes after review

1b232c3

cursor bot reviewed Apr 6, 2026

View reviewed changes

tatomyr reviewed Apr 6, 2026

View reviewed changes

Conversation

RomanHotsiy commented Mar 4, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

github-actions bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

Uh oh!

tatomyr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Apr 6, 2026

Choose a reason for hiding this comment

process.exit() bypasses finally cleanup in release script

Uh oh!

tatomyr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

RomanHotsiy commented Mar 4, 2026 •

edited by cursor bot

Loading

changeset-bot bot commented Mar 4, 2026 •

edited

Loading

github-actions bot commented Mar 4, 2026 •

edited

Loading

github-actions bot commented Mar 4, 2026 •

edited

Loading

`process.exit()` bypasses `finally` cleanup in release script