feat: basic push-status command implementation and extended push command

[roman-sainchuk]

What/Why/How?

Now push command also applied for BH push.
Syntax for push command:

REDOCLY_AUTHORIZATION=<api key> \ 
npm run cli -- push \ 
    --organization <orgId> \
    --project <projectId> \ 
    --mount-path <blue harvest mount path> \
    --branch <branch where files are pushed from> \
    --author 'Author Name <[email protected]>' \
    --message <message files are committed with> \
    --files <folders or/and files>  \
    --domain 'http://localhost'

or

REDOCLY_AUTHORIZATION=<api key> \ 
REDOCLY_DOMAIN='http://localhost' \
npm run cli -- push  \ 
    --organization <orgId> \
    --project <projectId> \ 
    --mount-path <blue harvest mount path> \
    --branch <branch where files are pushed from> \
    --author 'Author Name <[email protected]>' \
    --files <folders or/and files> \
    --message <message files are committed with> \

Syntax for push-status command:

REDOCLY_AUTHORIZATION=<api key> \ 
npm run cli -- push-status  <pushId> \
    --organization <orgId> \
    --project <projectId> \ 
    --domain 'http://localhost' \
    --wait

or

REDOCLY_AUTHORIZATION=<api key> \ 
REDOCLY_DOMAIN='http://localhost' \
npm run cli -- push-status  <pushId>
    --organization <orgId> \
    --project <projectId> \ 
    --wait

Reference

Testing

Screenshots (optional)

Check yourself

• Code is linted
• Tested with redoc/reference-docs/workflows (internal)
• All new/updated code is covered with tests

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

[changeset-bot]

🦋 Changeset detected

Latest commit: 7a85e28

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

This PR includes changesets to release 2 packages

Name	Type
@redocly/cli	Minor
@redocly/openapi-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

St.❔	Category	Percentage	Covered / Total
🟡	Statements	76.19%	4306/5652
🟡	Branches	65.76%	2236/3400
🟡	Functions	68.81%	695/1010
🟡	Lines	76.4%	4049/5300

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟡	... / miscellaneous.ts	64.88%	51.85%	75.47%	64.29%
🟢	... / fetch-with-timeout.ts	84.62%	100%	66.67%	83.33%
🔴	... / update-version-notifier.ts	34.43%	7.69%	0%	34.55%
🟢	... / push.ts	86.96%	58.33%	100%	86.57%
🟢	... / push-status.ts	80.56%	54.55%	80%	81.69%
🟢	... / spinner.ts	95.65%	75%	100%	95.65%
🟢	... / utils.ts	100%	100%	100%	100%
🟢	... / index.ts	100%	100%	100%	100%
🟡	... / api-client.ts	80%	46.15%	75%	79.17%
🟢	... / domains.ts	100%	100%	100%	100%
🟢	... / api-keys.ts	100%	100%	100%	100%
🟢	... / js-utils.ts	90.91%	83.33%	100%	100%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟡	... / push.ts	73.81% (-1.04% 🔻)	67.46% (-1.65% 🔻)	54.55% (-2.6% 🔻)	76.25% (-1.17% 🔻)

Test suite run success

699 tests passing in 100 suites.

Report generated by 🧪jest coverage report action from 7a85e28

[github-actions]

Command	Mean [s]	Min [s]	Max [s]	Relative
redocly lint packages/core/src/benchmark/benches/rebilly.yaml	1.065 ± 0.040	1.028	1.153	1.00
redocly-next lint packages/core/src/benchmark/benches/rebilly.yaml	1.087 ± 0.028	1.060	1.148	1.02 ± 0.05

[lornajane]

We need to discuss the naming of this command, either to somehow reuse the push command, or to use [product] push, or to pick a different word altogether. Adding the suffix won't be clear to users.

[roman-sainchuk]

We need to discuss the naming of this command, either to somehow reuse the push command, or to use [product] push, or to pick a different word altogether. Adding the suffix won't be clear to users.

Agree, for now it's not clear how to properly distinguish which command to run when you hit push. We discussed [product] push approach yesterday with @tatomyr, but looks like this approach will confuse users even more.

I'm also thinking about docker approach with contexts. Example:

redocly context create bh-eu --domain 'https://auth.beta.eu.redocly.com/' --description 'EU Region'

And then:

redocly context use bh-eu
and
redocly push ...

@lornajane , @RomanHotsiy , @tatomyr what do you think?

[roman-sainchuk]

The default context will be hardcoded as https://app.beta.redocly.com/, but looks like it is breaking change, so maybe the default context should be old workflows

[roman-sainchuk]

I think we can handle it without breaking changes, just need to properly migrate old .redocly-config.json files

[RomanHotsiy]

Yeah, I think the suffix is a temporary solution not to get blocked. I don't have an answer now. Let me think a bit.

[lornajane]

It's fine to work on it with the suffix, but we can't merge until we figure out a better approach. I think we'll end up with other commands that also have the product names in, so maybe adopting that extra piece is the least confusing option.

I'm not in favour of introducing the context as it's quite complex and since the push command is mostly intended to run in CI, it should be a repeatable single command.

[roman-sainchuk]

either to somehow reuse the push command

This is not an option because the syntax and options are totally different, also it will be confusing for user to understand what options should be provided to satisfy required arguments for chosen product (e.g. push --help)

[lornajane]

Perhaps we can pick a different command name, to keep things very clear and use that language consistently. How about upload or commit ? So far we have only decided on options we can't use, so I'm trying to find things that could be ruled in rather than ruled out, if that makes sense.

[adamaltman]

@roman-sainchuk I dislike the context proposal a lot. I like this one a lot:

   REDOCLY_DOMAIN='http://localhost' \

[roman-sainchuk]

@adamaltman me too, but on order to have the same command name and proper distinguishing between contexts (workflows/BH) we need to pass it even when you want to get the hint, e.g.:

REDOCLY_DOMAIN='http://localhost' redocly push --help

otherwise it will print workflows version of the push syntax

[tatomyr]

I suggest moving the redocly/cloud (and possibly all redocly) folder to the CLI package from core (perhaps to the cms folder). The intention is to use this command in CI/CD pipelines, so it looks like we can make the openapi-core bundle smaller if we don't include this things there.

[tatomyr]

Thank you @IgorKarpiuk! Looks much better now. Left one minor comment.

[tatomyr]

Please don't forget to add a changeset (I believe it's needed here).