cli: add progress bar for doc generation

[InukaWijerathna]

Summary

Adds a cli-progress-based progress bar that tracks how many of the requested generators have completed while generate runs, similar to the approach used in nodejs.dev's getApiDocsData.js referenced in the issue.

• New src/utils/progress-bar.mjs wraps a cli-progress SingleBar. Rendering is skipped entirely when stdout isn't a TTY, so CI logs, piped output, and tests never receive raw escape codes or bar frames.
• runGenerators() now accepts an optional { onGeneratorComplete } callback, invoked once per requested target (not its dependencies) as soon as its result is ready.
• The generate command creates the bar, starts it with the target count, and wires onGeneratorComplete to increment.

Test plan

• New unit tests for progress-bar.mjs (mocks cli-progress to verify correct start/increment/stop calls, and that it's a no-op off-TTY)
• New test in generators.test.mjs asserting onGeneratorComplete fires once per requested target, not per dependency
• Forced process.stdout.isTTY = true manually and drove a real SingleBar instance through the exported API to confirm no runtime errors
• npm test — no new failures (3 pre-existing failures on this checkout are unrelated Windows path-separator issues, reproducible on main)
• npm run lint — clean (pre-existing unrelated warnings only)

Closes #58

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 5, 2026 5:19pm

[cursor]

PR Summary

Low Risk
CLI UX and an optional callback on the generator runner; no auth, data, or core generation logic changes.

Overview
The generate command now shows a CLI progress bar while the generator pipeline runs, so users can see how many of the requested targets have finished.

A new createProgressBar helper (backed by cli-progress) renders a SingleBar only when stdout is a TTY; otherwise it returns no-op start / increment / stop so CI, pipes, and tests avoid escape codes.

runGenerators accepts an optional onGeneratorComplete callback, fired once per requested target (not dependency-only generators) when that target’s result is ready; the command starts the bar with config.target.length and wires increment to that callback.

Tests cover the progress bar behavior (TTY vs non-TTY) and that onGeneratorComplete is not invoked for dependency-only runs.

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

[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 fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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

[cursor]

Progress bar not stopped on failure

Medium Severity

When runGenerators rejects, progressBar.stop() is skipped because it runs only after a successful await. The TTY bar is started with hideCursor: true, so a failed generate can leave the terminal cursor hidden until the user resets the shell.

 

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

[avivkeller]

Duplicate of #680