Merge branch 'next' of https://github.com/readmeio/rdme into oleh/ope…

…napi-adding-command-to-solve-circularity-and-recursiveness

.eslintignore

@@ -1,3 +1,6 @@
+# test result artifacts
 coverage/
+
+# release build artifacts
 dist/
-exe/
+dist-gha/

.eslintrc

@@ -33,11 +33,11 @@
     /**
      * This is a small rule to prevent us from using console.log() statements in our commands.
      *
-     * We've had troubles in the past where our test coverage required us to use Jest mocks for
+     * We've had troubles in the past where our test coverage required us to use Vitest mocks for
      * console.log() calls, hurting our ability to write resilient tests and easily debug issues.
      *
      * We should be returning Promise-wrapped values in our main command functions
-     * so we can write robust tests and take advantage of `bin/rdme.js`,
+     * so we can write robust tests and take advantage of `bin/run.js` and `src/baseCommand.ts`,
      * which we use for printing function outputs and returning correct exit codes.
      *
      * Furthermore, we should also be using our custom loggers (see src/lib/logger.js)

.github/workflows/ci.yml

@@ -64,17 +64,14 @@ jobs:
           path: oas-examples-repo
           repository: readmeio/oas-examples
 
-      # For every GitHub Action release, we deploy our Docker images
-      # to the GitHub Container Registry for performance reasons.
-      # Instead of testing against the pre-built image, we can build
-      # an image from the currently checked-out repo contents by doing a
-      # li'l update in the action.yml file to point to the current Dockerfile.
-      - name: Replace Docker image value in action.yml
-        uses: jacobtomlinson/gha-find-replace@v3
-        with:
-          find: 'image:.*'
-          replace: "image: 'Dockerfile'"
-          include: rdme-repo/action.yml
+      # Since this workflow file is in the `rdme` repository itself,
+      # we need to test the GitHub Action using the current commit.
+      # This step builds the `rdme` action code so we can do that.
+      #
+      # This step is not required for syncing your docs to ReadMe!
+      - name: Rebuild GitHub Action for testing purposes
+        run: npm ci && npm run build:gha
+        working-directory: rdme-repo
 
       - name: Run `openapi:validate` command
         uses: ./rdme-repo/

.github/workflows/docs.yml

@@ -40,17 +40,13 @@ jobs:
           regex: false
           include: documentation/*
 
-      # For every GitHub Action release, we deploy our Docker images
-      # to the GitHub Container Registry for performance reasons.
-      # Instead of testing against the pre-built image, we can build
-      # an image from the currently checked-out repo contents by doing a
-      # li'l update in the action.yml file to point to the current Dockerfile.
-      - name: Replace Docker image value in action.yml
-        uses: jacobtomlinson/gha-find-replace@v3
-        with:
-          find: 'image:.*'
-          replace: "image: 'Dockerfile'"
-          include: action.yml
+      # Since this workflow file is in the `rdme` repository itself,
+      # we need to test the GitHub Action using the current commit.
+      # This step builds the `rdme` action code so we can do that.
+      #
+      # This step is not required for syncing your docs to ReadMe!
+      - name: Rebuild GitHub Action for testing purposes
+        run: npm run build:gha
 
       # And finally, with our updated documentation,
       # we run the `rdme` GitHub Action to sync the Markdown file

.github/workflows/release.yml

@@ -24,44 +24,14 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: 'npm'
 
       - name: Install dependencies and build TS
         run: npm ci && npm run build
 
       - name: Install semantic-release and friends
-        run: npm i --no-save semantic-release@21 @semantic-release/changelog@6 @semantic-release/exec@6 @semantic-release/git@10
-
-      # We do a dry run here to analyze the commits and grab the next version
-      # for usage in the Docker metadata action
-      - name: Dry run of semantic-release workflow
-        run: npx semantic-release --dry-run
-        id: release
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Log in to the Container registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          # For every release we add 2-3 tags to the docker build:
-          # 1. A semver tag (e.g., 8.0.0, 8.0.0-next.0)
-          # 2. A branch tag (e.g., next, main)
-          # 3. A `latest` tag (only on the main branch)
-          tags: |
-            type=semver,pattern={{version}},value=${{ steps.release.outputs.nextVersion }}
-            type=ref,event=branch
-            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'main') }}
+        run: npm i --no-save semantic-release@24 @semantic-release/changelog@6 @semantic-release/exec@6 @semantic-release/git@10
 
       - name: Run semantic-release workflow
         env:

.gitignore

@@ -1,5 +1,9 @@
 .env
 coverage/
 dist/
-exe/
 node_modules/
+
+# required for building with TS + oclif + GitHub Actions
+dist-gha/package.json
+oclif.manifest.json
+src/package.json

.prettierignore

@@ -1,5 +1,11 @@
+# invalid files
 __tests__/__fixtures__/invalid-json/yikes.json
-CHANGELOG.md
+
+# test result artifacts
 coverage/
+
+# release build artifacts
+CHANGELOG.md
 dist/
-exe/
+documentation/commands.md
+dist-gha/

.releaserc.yml

@@ -1,3 +1,4 @@
+$schema: https://json.schemastore.org/semantic-release.json
 branches:
   - name: main
   - name: next
@@ -14,11 +15,6 @@ plugins:
   - [
       '@semantic-release/exec',
       {
-        # Runs two commands:
-        # 1. Updates our action.yml file to reflect current Docker image version.
-        #   This needs to happen before `@semantic-release/git` so we can commit this file.
-        # 2. Builds and pushes the Docker image
-        'prepareCmd': './bin/set-action-image.js && ./bin/docker.js',
         # Adds a major version git tag (e.g., v8) as a convenience for GitHub Actions users
         # We need to run this in the publish phase so it can be force-pushed separately from the other tags
         'publishCmd': './bin/set-major-version-tag.js push',
@@ -27,21 +23,23 @@ plugins:
   - [
       '@semantic-release/git',
       {
-        assets: ['action.yml', 'CHANGELOG.md', 'package.json', 'package-lock.json'],
+        assets:
+          [
+            'CHANGELOG.md',
+            'documentation/commands.md',
+            'package.json',
+            'package-lock.json',
+            'dist-gha/commands.js',
+            'dist-gha/run.js',
+          ],
         message: "build(release): 🚀 v${nextRelease.version} 🦉\n\n${nextRelease.notes}\n[skip ci]",
       },
     ]
   - [
       '@semantic-release/exec',
       {
-        # Verify existence of gh and docker CLIs
-        'verifyConditionsCmd': './bin/verify-clis.sh',
-        # Sets the next version as a GitHub Actions output parameter for usage in subsequent workflow steps
-        # https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter
-        'verifyReleaseCmd': 'echo nextVersion=${nextRelease.version} >> $GITHUB_OUTPUT',
         # Adds an additional git tag without the `v` prefix as a convenience for GitHub Actions users
         'prepareCmd': 'git tag ${nextRelease.version}',
-        # Lightweight alternative to `@semantic-release/github` that creates a draft GitHub release
-        'publishCmd': 'gh release create ${nextRelease.version} --draft --generate-notes',
       },
     ]
+  - '@semantic-release/github'

CHANGELOG.md

@@ -1,3 +1,70 @@
+# [9.0.0-next.26](https://github.com/readmeio/rdme/compare/v9.0.0-next.25...v9.0.0-next.26) (2024-11-19)
+
+
+### Bug Fixes
+
+* build `dist-gha/` files with every release ([f42392b](https://github.com/readmeio/rdme/commit/f42392b5141d82df2acfa10df82989fe4832b36f))
+
+# [9.0.0-next.25](https://github.com/readmeio/rdme/compare/v9.0.0-next.24...v9.0.0-next.25) (2024-11-19)
+
+
+### Bug Fixes
+
+* **npm:** tweak npm lifecycle scripts ([#1073](https://github.com/readmeio/rdme/issues/1073)) ([35534db](https://github.com/readmeio/rdme/commit/35534dbe7228a75b49408bf4db3fcfb31091358a))
+
+# [9.0.0-next.24](https://github.com/readmeio/rdme/compare/v9.0.0-next.23...v9.0.0-next.24) (2024-11-19)
+
+
+* feat!: remove `validate`, deprecate/hide `open` ([#1072](https://github.com/readmeio/rdme/issues/1072)) ([f1b46f6](https://github.com/readmeio/rdme/commit/f1b46f6ef1593f81b5bb61b7890aa52e826b58d7))
+
+
+### BREAKING CHANGES
+
+* `rdme validate` has been removed, use `rdme
+openapi:validate` instead.
+* `rdme open` is now deprecated
+
+also updates our docs accordingly
+
+# [9.0.0-next.23](https://github.com/readmeio/rdme/compare/v9.0.0-next.22...v9.0.0-next.23) (2024-11-19)
+
+
+### Features
+
+* add `title` flag to `openapi:convert` ([#1071](https://github.com/readmeio/rdme/issues/1071)) ([1d71f3f](https://github.com/readmeio/rdme/commit/1d71f3ff3db022bf81a5c6ec9d9eceb42d093961)), closes [#1068](https://github.com/readmeio/rdme/issues/1068)
+
+# [9.0.0-next.22](https://github.com/readmeio/rdme/compare/v9.0.0-next.21...v9.0.0-next.22) (2024-11-19)
+
+
+* feat!: oclif (take 2) ([#1068](https://github.com/readmeio/rdme/issues/1068)) ([5e05f93](https://github.com/readmeio/rdme/commit/5e05f9381ff92441b95e49fcf6b369ed74b62a2e)), closes [#962](https://github.com/readmeio/rdme/issues/962) [#1067](https://github.com/readmeio/rdme/issues/1067) [/github.com/readmeio/rdme/blob/d01d76fe3c2e4a98b4f5c415be03e589fbe3b56e/.releaserc.yml#L30](https://github.com//github.com/readmeio/rdme/blob/d01d76fe3c2e4a98b4f5c415be03e589fbe3b56e/.releaserc.yml/issues/L30) [#1067](https://github.com/readmeio/rdme/issues/1067)
+
+
+### BREAKING CHANGES
+
+* the `rdme` GitHub Actions is now a [the `node20` JavaScript action](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions) rather than [a Docker container action](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-docker-container-actions).
+* `rdme` is now powered by [`oclif`](https://oclif.io/). The formatting and content of certain error messages and outputs may have changed. Please continue to only utilize exit codes to determine command successes/failures.
+
+completed tasks:
+
+- [x] a handful of tests are still failing, hoping that
+https://github.com/oclif/test/pull/652 gets merged in)
+- [x] github actions dry runs are failing (but i got them working in
+
+# [9.0.0-next.21](https://github.com/readmeio/rdme/compare/v9.0.0-next.20...v9.0.0-next.21) (2024-11-18)
+
+
+### Bug Fixes
+
+* add GITHUB_TOKEN ([e106e10](https://github.com/readmeio/rdme/commit/e106e1047c9ec0e47b3b3812783d2e44dddbe9bd))
+* attempt to use semantic-release/github instead of `gh` ([331d28b](https://github.com/readmeio/rdme/commit/331d28bc1e9f0f2b57a4d8d39f2ebaf6bf64896a))
+
+# [9.0.0-next.20](https://github.com/readmeio/rdme/compare/v9.0.0-next.19...v9.0.0-next.20) (2024-11-18)
+
+
+### Bug Fixes
+
+* bump semantic-release versions ([21efc66](https://github.com/readmeio/rdme/commit/21efc66eef0ff063366e3ad1394fedf5170b1d94))
+
 # [9.0.0-next.19](https://github.com/readmeio/rdme/compare/v9.0.0-next.18...v9.0.0-next.19) (2024-11-09)
 
 

CONTRIBUTING.md

@@ -2,19 +2,38 @@
 
 ## Running Shell Commands Locally 🐚
 
-To run test commands from within the repository, run the build and then run your commands from the root of the repository and use `./bin/rdme.js` instead of `rdme` so it properly points to the command executable, like so:
+To get started, run the `build` script to create a symlink with `package.json` (required for our `oclif` setup to read our commands properly). You only need to do this the first time you clone the repository.
 
 ```sh
 npm run build
-./bin/rdme.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
-If you need to debug commands quicker and re-building TS everytime is becoming cumbersome, you can use the debug command, like so:
+To run test commands, use `./bin/dev.js` instead of `rdme`. For example, if the command you're testing looks like this...
 
 ```sh
-npm run debug -- openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
+rdme openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
+... your local command will look like this:
+
+```sh
+bin/dev.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
+```
+
+The `bin/dev.js` file has a few features that are useful for local development:
+
+- It reads directly from your TypeScript files (so no need to re-run the TypeScript compiler every time you make a change)
+- It returns error messages with full stack traces
+
+`bin/dev.js` is convenient for useful for rapid development but it's not a 1:1 recreation of what the end-user experience with `rdme` is like. To recreate the production `rdme` experience, use the `bin/run.js` file instead. You'll need to re-run the TypeScript compiler (i.e., `npm run build`) every time you make a change. So for example:
+
+```sh
+npm run build
+bin/run.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
+```
+
+Your changes to the command code may make changes to [the command reference document](./documentation/commands.md) — it is up to you whether you include those changes in your PR or if you let the release process take care of it. More information on that can be found in [MAINTAINERS.md](./MAINTAINERS.md).
+
 ## Running GitHub Actions Locally 🐳
 
 To run GitHub Actions locally, we'll be using [`act`](https://github.com/nektos/act) (make sure to read their [prerequisites list](https://github.com/nektos/act#necessary-prerequisites-for-running-act) and have that ready to go before installing `act`)!
@@ -70,7 +89,7 @@ act -j simple
 
 ### Usage of `console`
 
-As you'll learn in our commands logic (see [`bin/rdme.js`](bin/rdme.js) and the [`src/cmds`](src/cmds) directory), we wrap our command outputs in resolved/rejected [`Promise` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and use [`bin/rdme.js`](bin/rdme.js) file to log the results to the console and return the correct status code. This is so we can write more resilient tests, ensure that the proper exit codes are being returned, and make debugging easier.
+As you'll learn in our commands logic (see [`bin/run.js`](bin/run.js) and the [`src/commands`](src/commands) directory), we wrap our command outputs in resolved/rejected [`Promise` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and use [`bin/run.js`](bin/run.js) file to log the results to the console and return the correct status code. This is so we can write more resilient tests, ensure that the proper exit codes are being returned, and make debugging easier.
 
 When writing command logic, avoid using `console` statements (and correspondingly, avoid mocking `console` statements in tests) when possible.