@o3co/create-auth-provider 0.15.0 → 0.16.0

package/README.ja.md

@@ -1,11 +1,35 @@
 # @o3co/create-auth-provider
 
-auth.provider 用の CLI スキャフォルダーです。standalone テンプレートから新しいプロジェクトを生成します。
+最終更新: 2026-09-24
+
+auth.provider 用の CLI スキャフォルダーです。内包する standalone テンプレートから新しいサーバープロジェクトを生成します。
+
+## 責務と役割
+
+**役割。** リポジトリ内のテンプレート
+[`templates/standalone`](../templates/standalone) を、独立した新しいプロジェクトに
+変換する `npx` の入口です。運用者のマシン上で一度だけ実行されます。生成された
+プロジェクトはこのパッケージを import せず、このパッケージも `packages/*` の
+ライブラリを一切 import しません。
+
+**担うもの。** プロジェクト名とディレクトリ名の検証、テンプレートのコピー、生成された
+`package.json` の書き換え（名前、`workspace:*` → 公開バージョン）、プロジェクトの
+`pnpm-workspace.yaml` の書き出し、そして一度きりの `pnpm-lock.yaml` の解決。
+
+**担わないもの。** 生成されるプロジェクトの中身 — ソース、設定、Dockerfile、
+テスト — はテンプレートのものです（このパッケージではなく `templates/standalone` を
+編集してください）。実行時の振る舞いは `@o3co/auth-provider-core` と、テンプレートが
+依存するライブラリのものです。
+
+**別パッケージである理由。** `bin` 付きで単独公開されるため、provider をインストール
+せずに `npx` で実行できます。公開 tarball にはモノレポが含まれないので、このパッケージは
+テンプレートのコピーと、固定するライブラリのバージョンを自前で持ちます
+（[テンプレートの同梱方法](#テンプレートの同梱方法)）。
 
 ## 使い方
 
 ```bash
-npx @o3co/create-auth-provider <project-name> [--dir <dir-name>]
+npx @o3co/create-auth-provider <project-name> [--dir <dir-name>] [--no-lockfile]
 ```
 
 `<project-name>` はスコープ付き npm 名 (`@scope/pkg`) とスコープなしの名前 (`pkg`) のどちらでも指定できます。
@@ -15,8 +39,7 @@ npx @o3co/create-auth-provider <project-name> [--dir <dir-name>]
 ```bash
 npx @o3co/create-auth-provider my-auth-server
 cd my-auth-server
-npm install
-npm run debug
+pnpm install
 ```
 
 スコープ付きの例（ディレクトリ名はパッケージ部分 `auth.provider` がデフォルト）:
@@ -24,8 +47,7 @@ npm run debug
 ```bash
 npx @o3co/create-auth-provider @my-org/auth.provider
 cd auth.provider
-npm install
-npm run debug
+pnpm install
 ```
 
 `--dir` でディレクトリ名を明示指定:
@@ -35,18 +57,61 @@ npx @o3co/create-auth-provider @my-org/auth.provider --dir provider
 cd provider
 ```
 
+`--no-lockfile` を付けると lockfile の生成（下記の手順 7）を省略します。
+
+生成されるプロジェクトは pnpm のプロジェクトです。`Dockerfile` は
+`pnpm install --frozen-lockfile` でインストールし、ビルドの許可リストは
+`pnpm-workspace.yaml` にあります。
+
+CLI は最後のメッセージで次に `pnpm run debug` を実行するよう案内します。
+スキャフォールドのデフォルトのままでは、これは起動しません: `.env` ファイルは
+読まず（読むのは compose ファイルだけ）、シェルの環境変数から issuer
+（`OAUTH_JWT_ISSUER`）、署名鍵のペア、セッションシークレット、ユーザーサービスの
+2 つの URL（`CLIENT_USER_AUTHENTICATE_URL`、`CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL`）、
+そして `localhost:6379` の Redis を必要とします。コマンドは、プロジェクトに含まれる
+テンプレートの README の[使い方](../templates/standalone/README.ja.md#使い方)にあります。
+
 ## 動作内容
 
-1. `<project-name>` を検証する（バリデーションルール参照）。
+1. `<project-name>` を検証する（[バリデーションルール](#バリデーションルール) 参照）。
 2. 生成先ディレクトリ名を決定する: `--dir <value>` が指定されていればその値、そうでなければスコープ付き名のパッケージ部分、最終的には入力値そのもの。
-3. 生成先ディレクトリを `<cwd>/<dir-name>` として解決する。
-4. ディレクトリがすでに存在する場合はエラーを出力して終了する。
-5. `templates/standalone/` を生成先ディレクトリにコピーする（`node_modules/` と `dist/` は除外）。
-6. 生成されたディレクトリの `package.json` を書き換える:
-   - `name` を `<project-name>` をそのまま設定する（スコープを保持）。
-   - `private` フィールドを削除する。
-   - すべての `workspace:*` バージョン参照を `versions.json` の公開 semver バージョンに置き換える。
-7. 次のステップを出力する。
+3. 生成先ディレクトリを `<cwd>/<dir-name>` として解決し、すでに存在する場合はエラーで終了する。
+4. 内包するテンプレートを生成先ディレクトリにコピーし（`node_modules/` と `dist/` は除外）、`.gitignore` を復元する（npm は公開パッケージから `.gitignore` という名前のファイルを落とすため、tarball には `gitignore` として入っている）。
+5. 生成されたディレクトリの `package.json` を書き換える:
+   - `name` を `<project-name>` そのままに設定する（スコープを保持）。
+   - `"private": true` は意図的に残す: スキャフォールドされた ID プロバイダーが誤って公開できてはならないため。本当に公開するつもりなら自分でこのフィールドを削除する。
+   - `dependencies`・`devDependencies`・`peerDependencies` の各 `workspace:*` を、内包する `versions.json` の `^<version>` に置き換える。
+6. `bcrypt` 用の `onlyBuiltDependencies` 許可リストを書いた `pnpm-workspace.yaml` を生成する — pnpm 10.29 以降はこの許可リストを、単一パッケージのプロジェクトであってもこのファイルからしか読まない。
+7. `--no-lockfile` が指定されていなければ、依存関係を `pnpm-lock.yaml` に解決する（`pnpm install --lockfile-only --ignore-workspace`。`pnpm` が `PATH` にない場合は `corepack pnpm` 経由）。到達可能なレジストリが必要で、失敗しても警告を出すだけでスキャフォールドは完了する。
+8. 次のステップを出力する。
+
+### 生成される `pnpm-lock.yaml`
+
+テンプレートの `Dockerfile` は `pnpm install --frozen-lockfile` でインストール
+するため、生成されたプロジェクトは lockfile がなければそもそもビルドできません。
+lockfile をテンプレートに同梱することはできません: 手順 5 がすべての
+`workspace:*` を公開バージョンに置き換えるまで、lockfile が固定すべき依存関係の
+集合が存在しないからです。そこで、書き換え後の `package.json` に対してここで
+一度だけ解決します。**コミットしてください** — `docker build` を再現可能にするのは
+この lockfile です。手順 7 が失敗した、または省略した場合は、プロジェクト内で一度
+`pnpm install` を実行して結果をコミットしてください。
+
+## テンプレートの同梱方法
+
+パッケージの `prebuild` と `prepack` スクリプトが
+[`scripts/copy-templates.mjs`](scripts/copy-templates.mjs) を実行し、
+`templates/standalone` を `create-app/templates/standalone` にコピーし（git 管理外。
+`node_modules/` と `dist/` は除外）、`create-app/templates/versions.json` —
+公開される `@o3co/auth-provider-*` 全パッケージの現在のバージョン — を書き出します。
+tarball には両方が入り（`files: ["dist", "templates"]`）、`scaffold()` はそこから
+読みます。したがってスキャフォールドされるのは、このパッケージをビルドした時点の
+テンプレートで、同じビルド時点のライブラリバージョンに固定されます。
+
+CI は [`scripts/check-versions-json.mjs`](scripts/check-versions-json.mjs) を
+実行します。`packages/` 配下の公開パッケージが `copy-templates.mjs` のバージョン
+一覧に欠けているとき、または一覧がもう存在しないパッケージを挙げているときに
+失敗します — そうでなければスキャフォールドがそのパッケージの `workspace:*` の
+バージョンを解決できずに失敗するためです。
 
 ## バリデーションルール
 
@@ -61,45 +126,26 @@ cd provider
 
 ## 既知の制約
 
-内包されているテンプレートの `README.md` / `README.ja.md` の見出しは `@o3co/auth-provider-standalone` のままです。スコープ付きでプロジェクトを生成した場合、この見出しは生成された `package.json` の `name` と一致しません。必要に応じて手動で修正してください。
+- 内包されているテンプレートの `README.md` / `README.ja.md` の見出しは上流の `@o3co/auth-provider-standalone` のままです。スコープ付きでプロジェクトを生成した場合、この見出しは `package.json` の名前と一致しません。必要に応じて手動で修正してください。
+- テンプレートの README は、このリポジトリ内を相対パス（`../../docs/…`、`../../packages/…`）でリンクしています。これはモノレポ内では解決しますが、横に `docs/` も `packages/` もないスキャフォールド先のプロジェクトでは解決しません。GitHub 上で参照してください。
 
 ## 生成される構造
 
-```
-<プロジェクト名>/
-├── config/
-│   ├── application.conf   # HOCON 設定（環境変数で上書き可能）
-│   ├── clients.yaml       # OAuth クライアントレジストリ
-│   └── clients.yaml.example
-├── src/
-│   └── app.mts            # Composition root
-├── tests/
-├── .dockerignore
-├── .env.example
-├── Dockerfile
-├── docker-compose.yml
-├── docker-compose.test.yml
-├── Makefile
-├── package.json
-├── tsconfig.json
-└── vitest.config.mts
-```
-
-生成後、`.env.example` をコピーして `.env` を作成し、必須の環境変数を設定してください。
+生成されるプロジェクトは [`templates/standalone`](../templates/standalone) の
+完全なコピー（`node_modules/` と `dist/` を除く）に、`pnpm-workspace.yaml`（手順 6）と、
+`--no-lockfile` を指定せず lockfile の手順が失敗しなかった場合は `pnpm-lock.yaml`（手順 7）を加えたものです。どの
+ファイルがモジュール構成で、どれがホストプロセスで、スキャフォールドが何を
+持つかは、テンプレートの README に記述されています。
 
 ## プログラマティック API
 
-```typescript
-import { scaffold, main } from "@o3co/create-auth-provider";
-
-// 絶対パスにプロジェクトを生成する
-scaffold(targetDir: string, projectName: string): void;
-
-// CLI エントリーポイント — process.argv を読み取り、エラー時は終了する
-main(): void;
-```
+モジュールは CLI を構成する関数を export しています。シグネチャは
+[`src/index.mts`](src/index.mts) にあります。
 
-テンプレートディレクトリが見つからない場合、または `workspace:*` 依存関係が `versions.json` で解決できない場合、`scaffold` はエラーをスローします。
+- `scaffold(targetDir, projectName)` — 手順 4〜6。内包するテンプレートがない場合、または `workspace:*` 依存が `versions.json` に見つからない場合は例外を投げる。
+- `generateLockfile(targetDir)` — 手順 7。例外を投げず、`{ ok: true, command }` か `{ ok: false, reason }` を返す。
+- `main()` — CLI 本体。`process.argv` を読み、不正な引数や既存のディレクトリに対しては非ゼロで終了する。
+- `isValidProjectName(name)` / `isValidDirName(name)` — [バリデーションルール](#バリデーションルール)。
 
 ## 関連
 

package/README.md

@@ -1,11 +1,35 @@
 # @o3co/create-auth-provider
 
-CLI scaffolder for auth.provider. Generates a new project from the standalone template.
+Last updated: 2026-09-24
+
+CLI scaffolder for auth.provider. Generates a new standalone server project from the built-in template.
+
+## Responsibility
+
+**Role.** The `npx` entry point that turns the in-repo template
+[`templates/standalone`](../templates/standalone) into a new, independent
+project. It runs once, on the operator's machine; nothing in the generated
+project imports it, and it imports none of the `packages/*` libraries.
+
+**Owns.** Project-name and directory validation, copying the template,
+rewriting the generated `package.json` (name, `workspace:*` → published
+versions), writing the project's `pnpm-workspace.yaml`, and the one-time
+`pnpm-lock.yaml` resolution.
+
+**Does not own.** The content of the generated project — source, config,
+Dockerfile, tests — which is the template's (edit `templates/standalone`, not
+this package). Runtime behaviour belongs to `@o3co/auth-provider-core` and the
+libraries the template depends on.
+
+**Why a separate package.** It is published on its own with a `bin`, so it can
+be run with `npx` without installing the provider. The monorepo is not in the
+published tarball, so the package carries its own copy of the template and of
+the library versions it pins ([How the template is bundled](#how-the-template-is-bundled)).
 
 ## Usage
 
 ```bash
-npx @o3co/create-auth-provider <project-name> [--dir <dir-name>]
+npx @o3co/create-auth-provider <project-name> [--dir <dir-name>] [--no-lockfile]
 ```
 
 `<project-name>` may be either a scoped npm name (`@scope/pkg`) or an unscoped name (`pkg`).
@@ -15,8 +39,7 @@ Unscoped example:
 ```bash
 npx @o3co/create-auth-provider my-auth-server
 cd my-auth-server
-npm install
-npm run debug
+pnpm install
 ```
 
 Scoped example (directory defaults to the package portion `auth.provider`):
@@ -24,8 +47,7 @@ Scoped example (directory defaults to the package portion `auth.provider`):
 ```bash
 npx @o3co/create-auth-provider @my-org/auth.provider
 cd auth.provider
-npm install
-npm run debug
+pnpm install
 ```
 
 Override the directory name with `--dir`:
@@ -35,18 +57,61 @@ npx @o3co/create-auth-provider @my-org/auth.provider --dir provider
 cd provider
 ```
 
+`--no-lockfile` skips the lockfile step (step 7 below).
+
+The generated project is a pnpm project: its `Dockerfile` installs with
+`pnpm install --frozen-lockfile`, and its build allowlist lives in
+`pnpm-workspace.yaml`.
+
+The CLI's closing message suggests `pnpm run debug` next. On the scaffold's
+defaults alone that does not boot: it reads no `.env` file (only the compose
+files do), and needs from the shell's environment an issuer
+(`OAUTH_JWT_ISSUER`), a signing key pair, a session secret, the two URLs of
+your user service (`CLIENT_USER_AUTHENTICATE_URL`,
+`CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL`) and a Redis on `localhost:6379`. The
+template's README, which the project carries, gives the commands under
+[Usage](../templates/standalone/README.md#usage).
+
 ## What It Does
 
-1. Validates `<project-name>` (see Validation Rules).
+1. Validates `<project-name>` (see [Validation Rules](#validation-rules)).
 2. Derives the target directory name: `--dir <value>` if given, else the unscoped part of a scoped name, else the name itself.
-3. Resolves the target directory as `<cwd>/<dir-name>`.
-4. Errors if the directory already exists.
-5. Copies `templates/standalone/` to the target directory, excluding `node_modules/` and `dist/`.
-6. Rewrites `package.json` in the generated directory:
+3. Resolves the target directory as `<cwd>/<dir-name>`, and errors if it already exists.
+4. Copies the bundled template to the target directory, excluding `node_modules/` and `dist/`, and restores its `.gitignore` (the tarball carries it as `gitignore`, because npm drops a file named `.gitignore` from a published package).
+5. Rewrites `package.json` in the generated directory:
    - Sets `name` to `<project-name>` verbatim (scope-preserving).
-   - Removes the `private` field.
-   - Replaces all `workspace:*` version references with published semver versions from `versions.json`.
-7. Prints next-step instructions.
+   - Keeps `"private": true` on purpose: a scaffolded identity provider should not be publishable by accident. Remove the field yourself if you really intend to publish.
+   - Replaces each `workspace:*` version in `dependencies`, `devDependencies` and `peerDependencies` with `^<version>` from the bundled `versions.json`.
+6. Writes `pnpm-workspace.yaml` with the `onlyBuiltDependencies` allowlist for `bcrypt` — pnpm 10.29 and later read that allowlist only from this file, in a single-package project too.
+7. Resolves the dependency set into `pnpm-lock.yaml` (`pnpm install --lockfile-only --ignore-workspace`, through `corepack pnpm` when `pnpm` is not on `PATH`), unless `--no-lockfile` was passed. This needs a reachable registry; a failure prints a warning and the scaffold still completes.
+8. Prints next-step instructions.
+
+### The generated `pnpm-lock.yaml`
+
+The template's `Dockerfile` installs with `pnpm install --frozen-lockfile`, so
+the generated project needs a lockfile to build at all. It cannot ship with the
+template: until step 5 has replaced every `workspace:*` with a published
+version, the dependency set the lockfile would have to pin does not exist. So
+it is resolved once, here, against the rewritten `package.json`. **Commit it** —
+it is what makes `docker build` reproducible. If step 7 failed or was skipped,
+run `pnpm install` in the project once and commit the result.
+
+## How the template is bundled
+
+The package's `prebuild` and `prepack` scripts run
+[`scripts/copy-templates.mjs`](scripts/copy-templates.mjs), which copies
+`templates/standalone` into `create-app/templates/standalone` (git-ignored;
+`node_modules/` and `dist/` excluded) and writes `create-app/templates/versions.json`,
+the current version of every published `@o3co/auth-provider-*` package. The
+tarball ships both (`files: ["dist", "templates"]`), and `scaffold()` reads
+them from there. A scaffold is therefore the template as it was when this
+package was built, pinned to the library versions of that same build.
+
+CI runs [`scripts/check-versions-json.mjs`](scripts/check-versions-json.mjs),
+which fails when a published package under `packages/` is missing from
+`copy-templates.mjs`'s version list, or the list names one that no longer
+exists — a scaffold would otherwise fail to resolve that package's
+`workspace:*` version.
 
 ## Validation Rules
 
@@ -61,45 +126,26 @@ Both forms must be non-empty, not `.` or `..`, and ≤ 214 characters.
 
 ## Known Limitations
 
-The bundled template's `README.md` / `README.ja.md` still carry the upstream title `@o3co/auth-provider-standalone`. When generating a scoped project, that title will not match your `package.json` name; edit it manually if it matters for your use case.
+- The bundled template's `README.md` / `README.ja.md` carry the upstream title `@o3co/auth-provider-standalone`. When generating a scoped project, that title will not match your `package.json` name; edit it manually if it matters for your use case.
+- The template's README links into this repository with relative paths (`../../docs/…`, `../../packages/…`). Those resolve in the monorepo and not in a scaffolded project, where there is no `docs/` or `packages/` beside it; read them on GitHub instead.
 
 ## Generated Structure
 
-```
-<project-name>/
-├── config/
-│   ├── application.conf   # HOCON config (overridable via env vars)
-│   ├── clients.yaml       # OAuth client registry
-│   └── clients.yaml.example
-├── src/
-│   └── app.mts            # Composition root
-├── tests/
-├── .dockerignore
-├── .env.example
-├── Dockerfile
-├── docker-compose.yml
-├── docker-compose.test.yml
-├── Makefile
-├── package.json
-├── tsconfig.json
-└── vitest.config.mts
-```
-
-After generation, fill in the required environment variables in `.env` (copy from `.env.example`).
+The generated project is a complete copy of
+[`templates/standalone`](../templates/standalone) (without `node_modules/` and
+`dist/`) plus `pnpm-workspace.yaml` (step 6) and, unless `--no-lockfile` was
+given or the lockfile step failed, `pnpm-lock.yaml` (step 7). The template's README describes its layout — which file is
+the composition, which is the host process, and what the scaffold owns.
 
 ## Programmatic API
 
-```typescript
-import { scaffold, main } from "@o3co/create-auth-provider";
-
-// Generate a project at an absolute path
-scaffold(targetDir: string, projectName: string): void;
-
-// CLI entry point — reads process.argv and exits on error
-main(): void;
-```
+The module exports the functions the CLI is built from; their signatures are
+in [`src/index.mts`](src/index.mts).
 
-`scaffold` throws if the template directory is missing or if a `workspace:*` dependency cannot be resolved in `versions.json`.
+- `scaffold(targetDir, projectName)` — steps 4–6. Throws if the bundled template is missing or a `workspace:*` dependency has no entry in `versions.json`.
+- `generateLockfile(targetDir)` — step 7. Returns `{ ok: true, command }` or `{ ok: false, reason }` rather than throwing.
+- `main()` — the CLI: reads `process.argv`, and exits non-zero on an invalid argument or an existing directory.
+- `isValidProjectName(name)` / `isValidDirName(name)` — the [Validation Rules](#validation-rules).
 
 ## See Also
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/create-auth-provider",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Scaffold a new o3co/auth.provider project from the standalone template",
   "license": "Apache-2.0",
   "type": "module",

package/templates/standalone/.env.example

@@ -37,8 +37,20 @@ SESSION_SECRET=
 # be absolute https URLs. http:// is accepted only for a loopback host
 # (localhost, 127.0.0.0/8, [::1]) — a private-range address or a compose service
 # name such as http://user-service:8080 still needs https. Boot fails otherwise.
+# Each must be the endpoint that answers: no request follows a 3xx, so a URL that
+# redirects fails every call.
 CLIENT_USER_AUTHENTICATE_URL=
 CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL=
+# The credential this server presents to the Store: every Store request carries
+# `Authorization: Bearer <token>`. Without one, anyone who can reach the Store
+# can resolve an identity to its user, so your Store should refuse any request
+# without it, with 401 and `WWW-Authenticate: Bearer error="invalid_token"`
+# (which this server then reports as an outage naming the refused credential).
+# The one token goes to every Store URL above: they must be one trust domain.
+# At least 32 bytes, measured like SESSION_SECRET; boot fails on a weak or
+# malformed value. Left commented out because a blank value is refused too:
+#   openssl rand -hex 32
+# CLIENT_USER_BEARER_TOKEN=
 
 # --- Reverse proxy (required in production) -----------------------------------
 # Express `trust proxy`. Set this to the address or CIDR range of whatever

package/templates/standalone/Dockerfile

@@ -92,7 +92,7 @@ EXPOSE ${HTTP_PORT}
 # per-service, which keeps the restart-driving signal out of it.
 #
 # Use the shell form so ${HTTP_PORT} expands at probe time. The HOCON
-# config reads `${?HTTP_PORT}` for `http.port`, so app.listen() and the
+# config reads `${?HTTP_PORT}` for `http.port`, so the listener and the
 # probe stay in sync regardless of the operator's port choice.
 HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
   CMD wget -q -O /dev/null "http://localhost:${HTTP_PORT}/_healthcheck" || exit 1