feat(cli): add progress bar to generation pipeline

[shivxmsharma]

Description

Adds a cli-progress progress bar to the generate command that tracks each target generator as it completes.

• New src/utils/progressBar.mjs utility wraps cli-progress and writes to stderr to avoid conflicts with the existing logger (stdout)
• Automatically disabled when stderr is not a TTY (CI environments, piped output)
• New --no-progress flag to explicitly disable it

The bar starts after all generators are scheduled and increments once per target generator as its result collection finishes. The phase label shows the generator name:

  legacy-json [████████████████████████████████████████] 100% | 1/1

Validation

# Bar renders
node bin/cli.mjs generate -i "doc/api/*.md" -t legacy-json -o out -v 18.0.0

# Bar suppressed explicitly
node bin/cli.mjs generate -i "doc/api/*.md" -t legacy-json -o out -v 18.0.0 --no-progress

# Bar auto-suppressed in CI / piped output (stderr is not a TTY)
node bin/cli.mjs generate -i "doc/api/*.md" -t legacy-json -o out -v 18.0.0 2>/dev/null

All 312 existing tests pass.

Related Issues

Closes #58

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run npm run format to ensure the code follows the style guide.
• I have run npm test to check if all tests are passing.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 16, 2026 6:53am

[Copilot]

Pull request overview

Adds an optional CLI progress bar to the generation pipeline so users can see per-target generator completion while running doc-kit generate.

Changes:

• Introduces src/utils/progressBar.mjs, a small wrapper around cli-progress that renders to stderr and auto-disables when stderr isn’t a TTY.
• Hooks the progress bar into src/generators.mjs so it starts after scheduling and increments once each target generator’s result collection finishes.
• Adds --no-progress to the generate command and wires it into runGenerators, plus adds the cli-progress dependency.

Reviewed changes

Copilot reviewed 3 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/utils/progressBar.mjs	New utility to create a TTY-aware progress bar that writes to stderr.
src/generators.mjs	Starts/increments/stops the progress bar around target result collection.
bin/commands/generate.mjs	Adds --no-progress and passes opts.progress into the generator runner.
package.json	Adds cli-progress dependency.
package-lock.json	Locks cli-progress and its transitive dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[avivkeller]

cc @ovflowd given that the tooling is really fast, is a progress bar still needed?

[vercel]

Deployment failed with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[AugustinMauroy]

LGMT ! and IMO it's still a good thing to have progress bar

[codecov]

Codecov Report

❌ Patch coverage is 94.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.63%. Comparing base (3fbb9fb) to head (77a37e7).

Files with missing lines	Patch %	Lines
bin/commands/generate.mjs	0.00%	2 Missing ⚠️
src/utils/progressBar.mjs	96.77%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #680      +/-   ##
==========================================
+ Coverage   84.60%   84.63%   +0.02%     
==========================================
  Files         176      177       +1     
  Lines       15802    15850      +48     
  Branches     1411     1413       +2     
==========================================
+ Hits        13369    13414      +45     
- Misses       2423     2426       +3     
  Partials       10       10              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ovflowd]

cc @ovflowd given that the tooling is really fast, is a progress bar still needed?

I think a progress bar/visual indicator is good regardless. Allows us to see on what it is working. I'd argue it should be behind a feature flag such as --progress if we make it opt-in or --no-progress if we make it opt-out. I'd argue opt-out by default would be ideal, so we can disable it on CI.

It is a cool gimmick, but also genuinely brings "status" to what doc-kit is doing atm... Regardless of it being fast. What if I throw 20K md files on it?

[shivxmsharma]

Hey @ovflowd, the current implementation already does this — --no-progress makes it opt-out (enabled by default), and it also auto-disables in CI via a process.stderr.isTTY check, so no flag is even needed there.

@avivkeller the progress flag is now part of the global Configuration object as well. Let me know if there's anything else to address!

[shivxmsharma]

@avivkeller Committed the suggested changes!

[ovflowd]

This implementation of a ProgrressBar only provides Progress per generator, in the future we'd probably want to expose the Progress Bar as an Progress API to each generator so they can have more granular control.

[shivxmsharma]

This implementation of a ProgrressBar only provides Progress per generator, in the future we'd probably want to expose the Progress Bar as an Progress API to each generator so they can have more granular control.

Agreed, that would be a nice follow-up. Happy to work on that in a separate PR!

[cursor]

PR Summary

Low Risk
UX-only CLI output with no changes to generation logic, auth, or data handling; bar is suppressed in non-TTY environments.

Overview
Adds a CLI progress bar during generate so users can see target generators finish one by one.

A new cli-progress dependency and createProgressBar utility render to stderr (keeping stdout for the logger). The bar is on by default (progress: true in config/types), auto-off when stderr is not a TTY, and can be turned off with --no-progress.

runGenerators starts the bar after scheduling, increments once per target as cache.consume completes (phase label = generator name), then stops after the worker pool is destroyed. Config wiring and a CLI/options test expectation were updated for the new flag.

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