Redocly / Redocly/redocly-cli

Expose Reunite push and push-status as a public programmatic API with types

Open
#3,087 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

p2 Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Is your feature request related to a problem? Please describe.

Since @redocly/cli 2.34.0 the published package is a minified esbuild bundle: bin/cli.js, lib/index.js, and hashed chunks. It has no exports field, no lib/reunite/commands/* modules, and no .d.ts files. handlePush, handlePushStatus, and the Reunite response types (PushResponse, DeploymentStatus, and so on) are internal to the bundle.

reunite-push-action used to import these directly. Bumping the CLI broke it (Redocly/reunite-push-action#129, #131, #135). As a bridge, Redocly/reunite-push-action#138 now copies the CLI into the action's dist/, spawns redocly push, parses Push ID: from the text output, and re-implements push-status --wait against the Reunite API to keep GitHub commit statuses working. That means the action owns an endpoint contract the CLI is supposed to own, and it will drift.

Describe the solution you'd like

Expose the Reunite commands as a public programmatic entry point again, for example a second esbuild entry published as @redocly/cli/api, with type declarations:

import { handlePush, handlePushStatus } from '@redocly/cli/api';
import type { PushResponse, PushStatusSummary, DeploymentStatus } from '@redocly/cli/api';

Requirements for the action:

  • handlePush returns the push id.
  • handlePushStatus keeps the onRetry callback (or equivalent) that reports the intermediate commit.statuses, because the action mirrors them to GitHub while a deployment runs.
  • The entry is bundleable by esbuild without reading package.json at runtime (the version must stay inlined, as it is in the bin bundle today).

Describe alternatives you've considered

  • --format json for push and push-status. Then the action becomes a thin wrapper around the binary and stops calling the API itself. Also acceptable, and simpler to keep stable, but the action still has to vendor or install the binary.
  • Keep the current bridge in the action. Rejected as the long-term state: duplicated push-status logic and an API contract owned outside the CLI.

Additional context

  • CLI 2.34.0 changelog: "Improved CLI install speed by bundling the CLI into a dependency-free package."
  • Bridge implementation: Redocly/reunite-push-action#138 (src/redocly-cli.ts, src/push-status.ts, src/types.ts). These files should be deleted once the entry point ships.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the published bundle entry points bin/cli.js and lib/index.js, then compare the Reunite command behavior with the bridge files src/redocly-cli.ts, src/push-status.ts, and src/types.ts. The work is done when a bundleable @redocly/cli/api entry exposes the requested handlers and response types, preserves push-status retry reporting, and the action's bridge files can be removed.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.