Publish a developer package via GitHub Actions workflow (#13)

* feat(gha): publish developer package

Introduces a GitHub Actions workflow `publish-dev-package` which
publishes a developer package to the GitHub npm registry when commits
are pushed to the `main` branch. A developer package bears the target
release version but followed by the short commit hash of the commit used
to build the package. The actual steps are described in
`publish-package.yml`.

* docs: update README

Topics:
- Explains how to install from GitHub Packages
- Explains how to configure a GitHub personal access token to install a
  developer package
- `npm` → `pnpm` for development

---------

Co-authored-by: Copilot <[email protected]>

Author: kikuomax

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

@@ -0,0 +1,20 @@
+name: "Publish a developer package to GitHub npm registry"
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish-dev:
+    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 to a specified npm registry"
+
+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., secrets.GITHUB_TOKEN for GitHub Packages"
+        required: true
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  node-version: 22
+  pnpm-version: 10
+
+jobs:
+  build-and-publish:
+    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
+
+      # appends the short commit hash to the version number
+      # 1. reads the package.json file
+      # 2. replaces the version and saves it in the package.json
+      - name: Read 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 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'
+
+      - 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

@@ -29,6 +29,40 @@ import { makeIntegrationResponsesAllowCors } from '@codemonger-io/cdk-cors-utils
 
 このライブラリはCDK v2.x用に設計されており、CDK v1.xでは使えません。
 
+### GitHub Packagesからインストールする
+
+`main`ブランチにコミットがプッシュされるたびに、*開発者用パッケージ*がGitHub Packagesの管理するnpmレジストリにパブリッシュされます。
+*開発者用パッケージ*のバージョンは次のリリースバージョンにハイフン(`-`)と短いコミットハッシュをつなげたものになります。例、`0.4.0-abc1234` (`abc1234`はパッケージをビルドするのに使ったコミット(*スナップショット*)の短いコミットハッシュ)。
+*開発者用パッケージ*は[こちら](https://github.com/orgs/codemonger-io/packages?repo_name=cdk-cors-utils)にあります。
+
+#### 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`はインストールしたい*スナップショット*の短いコミットハッシュに置き換えてください。
+
 ## API
 
 [`api-docs/markdown/index.md`](./api-docs/markdown/index.md)を参照ください(**英語版のみ**)。
@@ -44,7 +78,7 @@ TBD
 `build`スクリプトは`src`フォルダ内のTypeScriptファイルをトランスパイルします。
 
 ```sh
-npm run build
+pnpm build
 ```
 
 トランスパイルされたJavaScript(`*.js`)ファイルと型宣言(`*.d.ts`)ファイルが`dist`フォルダに作られます。
@@ -54,7 +88,7 @@ npm run build
 `doc`スクリプトはAPIドキュメントを生成します。
 
 ```sh
-npm run doc
+pnpm doc
 ```
 
 `api-docs/markdown`フォルダ内のMarkdownファイルが更新されます。

README.md

@@ -29,6 +29,40 @@ import { makeIntegrationResponsesAllowCors } from '@codemonger-io/cdk-cors-utils
 
 This library is designed for CDK v2.x, and does not work with CDK v1.x.
 
+### 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.
+A *developer package* bears the next release number but followed by a dash (`-`) plus the short commit hash; e.g., `0.4.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/orgs/codemonger-io/packages?repo_name=cdk-cors-utils).
+
+#### Configuring a 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.
+
 ## APIs
 
 Please refer to [`api-docs/markdown/index.md`](./api-docs/markdown/index.md).
@@ -41,10 +75,10 @@ TBD
 
 ### Transpiling TypeScript files
 
-`build` script transplies TypeScript files in the `src` folder.
+`build` script transpiles TypeScript files in the `src` folder.
 
 ```sh
-npm run build
+pnpm build
 ```
 
 You will find transpiled JavaScript (`*.js`) and type declaration (`*.d.ts`) files created in a folder `dist`.
@@ -54,7 +88,7 @@ You will find transpiled JavaScript (`*.js`) and type declaration (`*.d.ts`) fil
 `doc` script generates the API documentation.
 
 ```sh
-npm run doc
+pnpm doc
 ```
 
 You will find markdown files updated in the folder `api-docs/markdown`.