Publish a developer package by GitHub Actions (#25)

* feat(gha): build package

Introduces the following workflows:
- `publish-dev-package`: publishes a developer package when commits are
  pushed to the `dev` branch. Invokes the `publish-package` workflow.
- `publish-package`: implements the process to publish a package.
  Designed for the GitHub npm registry for now.

* feat(gha): append short commit hash to version

The `publish-package` workflow appends the short commit hash to the
version for a developer package.

* feat(gha): publish developer package

The `publish-package` workflow publishes the built package to a
specified npm registry. The caller has to specify the following
parameters:
- `npm-registry-url`: URL of the npm registry to publish to.
- `npm-token`: token that is allowed to publish to the npm registry

The `publish-dev-package` workflow configures the above parameters for
the GitHub npm registry.

* fix(gha): unclean working tree error on publish

Works around the problem that the `pnpm publish` command failed due to
an unclean git working copy. As the short commit hash is appended to the
version of a developer package, the working copy is always unclean. Adds
the `--no-git-checks` option to the `pnpm publish` command as a
workaround.

* chore: include README.ja.md in package

* chore(gha): specify the scope of the package

* chore: add repository to package.json

* chore(gha): change trigger branch: dev → main

The `publish-dev-package` workflow changes the trigger branch from `dev`
to `main`. I decided not to duplicate the `main` branch as `dev`.

When it would come to publishing to the official npm registry, we should
consider other triggers: e.g. creation of a release.

* docs: update README

Explains how to install a developer package from the GitHub npm
registry.

Author: kikuomax

.github/workflows/publish-dev-package.yml

@@ -0,0 +1,20 @@
+name: Publish a developer package
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  packages: write
+  contents: read
+
+jobs:
+  publish:
+    uses: ./.github/workflows/publish-package.yml
+
+    with:
+      npm-registry-url: 'https://npm.pkg.github.com'
+
+    secrets:
+      npm-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-package.yml

@@ -0,0 +1,72 @@
+name: Publish a package
+
+on:
+  workflow_call:
+    inputs:
+      npm-registry-url:
+        description: 'URL of the npm registry to publish to; e.g., https://npm.pkg.github.com for GitHub Packages'
+        type: string
+        required: true
+
+    secrets:
+      npm-token:
+        description: 'Token that is allowed to publish to the npm registry; e.g., GITHUB_TOKEN for GitHub Packages'
+        required: true
+
+env:
+  node-version: 22
+  pnpm-version: 10
+
+permissions:
+  packages: write
+  contents: read
+
+jobs:
+  build-dist:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get short commit hash
+        id: commit-hash
+        run: echo "short-commit-hash=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Install pnpm ${{ env.pnpm-version }}
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.pnpm-version }}
+
+      - name: Setup Node.js ${{ env.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.node-version }}
+          cache: 'pnpm'
+          registry-url: ${{ inputs.npm-registry-url }}
+          scope: '@codemonger-io'
+
+      # appends the short commit hash to the version
+      # 1. reads package information
+      # 2. appends the short commit hash to the version and writes it back
+      - name: Extract package information
+        id: package-info
+        # uses the exact commit to prevent harmful updates
+        uses: jaywcjlove/github-action-package@f6a7afaf74f96a166243f05560d5af4bd4eaa570
+        with:
+          path: package.json
+      - name: Append short commit hash to the version
+        # uses the exact commit to prevent harmful updates
+        uses: jaywcjlove/github-action-package@f6a7afaf74f96a166243f05560d5af4bd4eaa570
+        with:
+          path: package.json
+          version: ${{ steps.package-info.outputs.version }}-${{ steps.commit-hash.outputs.short-commit-hash }}
+
+      - name: Install dependencies
+        run: pnpm install
+
+      # the build script is executed by the prepare script
+      - name: Build and publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.npm-token }}
+        run: pnpm publish --no-git-checks

README.ja.md

@@ -30,6 +30,40 @@ npm install https://github.com/codemonger-io/cdk-rest-api-with-spec.git#v0.3.0
 
 CDK v2プロジェクトで使っている限り、これらを別途インストールする必要はないはずです。
 
+### GitHub Packagesからインストールする
+
+`main`ブランチにコミットがプッシュされるたびに、開発者用パッケージがGitHub Packagesの管理するnpmレジストリにパブリッシュされます。
+開発者用パッケージのバージョンは次のリリースバージョンとハイフン(`-`)と短いコミットハッシュををつなげたもので表現されます。例、`0.3.0-abc1234` (`abc1234`はパッケージをビルドするのに使ったコミット(*スナップショット*)のコミットハッシュ)。
+開発者用パッケージは[こちら](https://github.com/codemonger-io/cdk-rest-api-with-spec/pkgs/npm/cdk-rest-api-with-spec)にあります。
+
+#### GitHubパーソナルアクセストークンの設定
+
+開発者用パッケージをインストールするには、最低限`read:packages`スコープの**クラッシック**GitHubパーソナルアクセストークン(PAT)を設定する必要があります。
+以下、簡単にPATの設定方法を説明します。
+より詳しくは[GitHubのドキュメント](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)をご参照ください。
+
+PATが手に入ったら以下の内容の`.npmrc`ファイルをホームディレクトリに作成してください。
+
+```
+//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT
+```
+
+`$YOUR_GITHUB_PAT`はご自身のPATに置き換えてください。
+
+プロジェクトのルートディレクトリに以下の内容の`.npmrc`ファイルを作成してください。
+
+```
+@codemonger-io:registry=https://npm.pkg.github.com
+```
+
+これで以下のコマンドで開発者パッケージをインストールできます。
+
+```sh
+npm install @codemonger-io/[email protected]
+```
+
+`abc1234`はインストールしたい*スナップショット*の短いコミットハッシュに置き換えてください。
+
 ## 始める
 
 [`aws_apigateway.RestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html)の代わりに[`RestApiWithSpec`](./api-docs/markdown/cdk-rest-api-with-spec.restapiwithspec.md)をインスタンス化してください。

README.md

@@ -30,6 +30,40 @@ This library is supposed to be used in a CDK v2 project, so it does not include
 
 As long as you are working on a CDK v2 project, you should not have to separately install them.
 
+### Installing from GitHub Packages
+
+Every time commits are pushed to the `main` branch, a developer package is published to the npm registry managed by GitHub Packages.
+The version of a developer package is represented by the next release version followed by a dash (`-`) plus the short commit hash; e.g., `0.3.0-abc1234` where `abc1234` is the short commit hash of the commit used to build the package (*snapshot*).
+You can find developer packages [here](https://github.com/codemonger-io/cdk-rest-api-with-spec/pkgs/npm/cdk-rest-api-with-spec).
+
+#### Configuring GitHub personal access token
+
+To install a developer package, you need to configure a **classic** GitHub personal access token (PAT) with at least the `read:packages` scope.
+Below briefly explains how to configure a PAT.
+Please refer to the [GitHub documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry) for more details.
+
+Once you have a PAT, please create a `.npmrc` file in your home directory with the following content,
+
+```
+//npm.pkg.github.com/:_authToken=$YOUR_GITHUB_PAT
+```
+
+Please replace `$YOUR_GITHUB_PAT` with your PAT.
+
+In the root directory of your project, please create a `.npmrc` file with the following content,
+
+```
+@codemonger-io:registry=https://npm.pkg.github.com
+```
+
+Then you can install a developer package with the following command,
+
+```sh
+npm install @codemonger-io/[email protected]
+```
+
+Please replace `abc1234` with the short commit hash of the *snapshot* you want to install.
+
 ## Getting started
 
 Please instantiate [`RestApiWithSpec`](./api-docs/markdown/cdk-rest-api-with-spec.restapiwithspec.md) instead of [`aws_apigateway.RestApi`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html).

package.json

@@ -2,12 +2,17 @@
   "name": "@codemonger-io/cdk-rest-api-with-spec",
   "version": "0.3.0",
   "description": "Describe Amazon API Gateway and OpenAPI at once with CDK",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codemonger-io/cdk-rest-api-with-spec.git"
+  },
   "main": "./dist/index.js",
   "typings": "./dist/index.d.ts",
   "files": [
     "dist/index.js",
     "dist/index.d.ts",
-    "dist/index.js.map"
+    "dist/index.js.map",
+    "README.ja.md"
   ],
   "scripts": {
     "build": "rimraf dist && rollup -c && api-extractor run --local",