@o3co/create-auth-provider 0.15.0 → 0.17.0-rc.1

package/README.ja.md

@@ -1,11 +1,49 @@
 # @o3co/create-auth-provider
 
-auth.provider 用の CLI スキャフォルダーです。standalone テンプレートから新しいプロジェクトを生成します。
+最終更新: 2026-10-03
+
+auth.provider 用の CLI スキャフォルダーです。内包するテンプレートの 1 つから新しいサーバープロジェクトを生成します。
+
+## 責務と役割
+
+**役割。** リポジトリ内の [`templates/`](../templates) にあるテンプレート
+（それぞれがデプロイ可能なコンポジションルート）の 1 つを、独立した新しい
+プロジェクトに変換する `npx` の入口です。運用者のマシン上で一度だけ実行されます。生成された
+プロジェクトはこのパッケージを import せず、このパッケージも `packages/*` の
+ライブラリを一切 import しません。
+
+**担うもの。** プロジェクト名・ディレクトリ名・テンプレート名の検証、選んだテンプレートのコピー、生成された
+`package.json` の書き換え（名前、`workspace:*` → 公開バージョン）、プロジェクトの
+`pnpm-workspace.yaml` の書き出し、そして一度きりの `pnpm-lock.yaml` の解決。
+
+**担わないもの。** 生成されるプロジェクトの中身 — ソース、設定、Dockerfile、
+テスト — はテンプレートのものです（このパッケージではなく `templates/<name>` を
+編集してください）。どのテンプレートがあり、それぞれ何のためにあるかは
+[コンポジションテンプレートの ADR](../packages/core/docs/adr/2026-09-29-composition-templates.md)
+のものです。実行時の振る舞いは `@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> [--template <name>] [--dir <dir-name>] [--no-lockfile] [--no-mfa]
+```
+
+`--template` はコピーするテンプレートを指定します（デフォルトは `standalone`）。
+テンプレートは [`templates/`](../templates) 配下で `package.json` を持つディレクトリ
+（シンボリックリンクでも、ドットで始まる名前でもないもの）で、それ以外の名前は、
+使えるテンプレートの一覧を示して拒否されます。各テンプレートが
+何のためにあるかはそれぞれの README に、テンプレートの分け方 — 機能ごとではなく
+コンポジションの形ごとに 1 つ — は
+[コンポジションテンプレートの ADR](../packages/core/docs/adr/2026-09-29-composition-templates.md) にあります。
+
+```bash
+npx @o3co/create-auth-provider my-auth-server --template standalone
 ```
 
 `<project-name>` はスコープ付き npm 名 (`@scope/pkg`) とスコープなしの名前 (`pkg`) のどちらでも指定できます。
@@ -15,8 +53,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 +61,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 +71,84 @@ npx @o3co/create-auth-provider @my-org/auth.provider --dir provider
 cd provider
 ```
 
+`--no-lockfile` を付けると lockfile の生成（下記の手順 7）を省略します。
+
+スキャフォールドは、すべてのパスワードログインに第二要素を求めます: テンプレートの
+MFA スイッチ `mfaMode`（`MFA_MODE`）のデフォルトは `required` です。development では
+ほかに何も要りません。それ以外では、MFA に要るもの（2 つのストアを Redis に、鍵、
+SMTP リレー）を設定するか、`MFA_MODE=off` で MFA を無効にするまで、
+プロジェクトの起動は拒否されます。MFA ページのデフォルトは `/mfa` で、プロジェクトが
+そこでページを用意しなければ、すべてのパスワードログインはそこで止まります。
+スイッチが何をインストールし、何を要するかはテンプレートの README にあります。
+
+`--no-mfa` を付けると、代わりにスイッチをスキャフォールド上で off と書きます。
+`config/application.conf` の末尾に `mfaMode = "off"` と
+`mfaMode = ${?MFA_MODE}` をこの順に追記するので、後のテンプレートがデフォルトを
+変えてもプロジェクトは off のままで、`MFA_MODE` を設定すれば作り直さずに MFA を
+有効にできます。MFA パッケージは依存に残り、ほかには何も削除・変更しません。
+
+生成されるプロジェクトは pnpm のプロジェクトです。`Dockerfile` は
+`pnpm install --frozen-lockfile` でインストールし、ビルドの許可リストは
+`pnpm-workspace.yaml` にあります。
+
+CLI は最後のメッセージで次に `pnpm run debug` を実行するよう案内します。
+スキャフォールドのデフォルトのままでは、これは起動しません: `.env` ファイルは
+読まず（読むのは compose ファイルだけ）、シェルの環境変数から issuer
+（`OAUTH_JWT_ISSUER`）、署名鍵のペア、セッションシークレット、ユーザーサービスの
+2 つの URL（`REPOSITORIES_USER_HTTP_AUTHENTICATE_URL`、`REPOSITORIES_USER_HTTP_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. `--template`（デフォルト `standalone`）が内包するテンプレートの名前であることを確かめ、生成先ディレクトリを `<cwd>/<dir-name>` として解決し、すでに存在する場合はエラーで終了する。
+4. 指定したテンプレートを生成先ディレクトリにコピーし（`node_modules/` と `dist/` は除外）、`.gitignore` を復元する（npm は公開パッケージから `.gitignore` という名前のファイルを落とすため、tarball には `gitignore` として入っている）。`--no-mfa` のときは、その `config/application.conf` に MFA スイッチの行を追記する。
+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) を実行し、
+すべてのテンプレートを `create-app/templates/<name>` にコピーし（git 管理外。
+`node_modules/` と `dist/` は除外。コピー先は丸ごと作り直すので、リポジトリから
+消したテンプレートは残らない）、`create-app/templates/versions.json` —
+公開される `@o3co/auth-provider-*` 全パッケージの現在のバージョン — を書き出します。
+tarball には両方が入り（`files: ["dist", "templates"]`）、`scaffold()` はそこから
+読みます。したがってスキャフォールドされるのは、このパッケージをビルドした時点の
+テンプレートで、同じビルド時点のライブラリバージョンに固定されます。
+テンプレートとは何か — `templates/` 配下のディレクトリで、シンボリックリンクでも
+ドットで始まる名前でもなく、`package.json` を持ち、小文字のケバブケースで名付けられた
+もの — は [`scripts/templates.mjs`](scripts/templates.mjs) の 1 か所で定義され、
+コピーと CI の全テンプレートのビルドの両方がそれを使います。スキャフォルダーの
+`availableTemplates()` は同じ規則でコピーを読みます。
+[`published-package.test.mts`](src/__tests__/published-package.test.mts) は
+パッケージを pack し、tarball がリポジトリのテンプレートをすべて含み、それぞれが
+そこからスキャフォールドできることを確かめます。
+
+CI は [`scripts/check-versions-json.mjs`](scripts/check-versions-json.mjs) を
+実行します。`packages/` 配下の公開パッケージが `copy-templates.mjs` のバージョン
+一覧に欠けているとき、または一覧がもう存在しないパッケージを挙げているときに
+失敗します — そうでなければスキャフォールドがそのパッケージの `workspace:*` の
+バージョンを解決できずに失敗するためです。
 
 ## バリデーションルール
 
@@ -59,49 +161,38 @@ cd provider
 
 `--dir <value>` はスコープなしのパターンと同じ制約です。
 
+`--template <name>` は内包するテンプレートの名前と完全に一致する必要があります。パスは
+テンプレート名になりません。テンプレート名は小文字のケバブケース
+`^[a-z0-9]+(?:-[a-z0-9]+)*$`（英小文字と数字の並びを 1 つのハイフンでつなぐ）で、
+それ以外の名前のテンプレートはビルドが拒否します。
+
 ## 既知の制約
 
-内包されているテンプレートの `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, template?, options?)` — 手順 4〜6。`template`（デフォルトは `DEFAULT_TEMPLATE` = `"standalone"`）からコピーする。`options.noMfa` は `--no-mfa` にあたる。コピーできないときは何も書かずに `templateRefusal` のメッセージで例外を投げる。`workspace:*` 依存が `versions.json` に見つからない場合も例外を投げる。
+- `availableTemplates(templatesRoot?)` — 内包するテンプレートの名前（ソート済み）。
+- `templateRefusal(template, templates)` — `template` からスキャフォールドできない理由（1 つも内包されていない、またはそのどれでもない）。できるときは `undefined`。
+- `generateLockfile(targetDir)` — 手順 7。例外を投げず、`{ ok: true, command }` か `{ ok: false, reason }` を返す。
+- `main()` — CLI 本体。`process.argv` を読み、不正な引数、未知のテンプレート、既存のディレクトリに対しては非ゼロで終了する。
+- `isValidProjectName(name)` / `isValidDirName(name)` — [バリデーションルール](#バリデーションルール)。
 
 ## 関連
 
-- [`@o3co/auth-provider-standalone`](../templates/standalone) — このツールが生成元とするテンプレート
+- [`templates/`](../templates) — このツールが生成元とするテンプレート。[`@o3co/auth-provider-standalone`](../templates/standalone) がデフォルト
+- [コンポジションテンプレートの ADR](../packages/core/docs/adr/2026-09-29-composition-templates.md) — テンプレートをこう分ける理由
 - [`@o3co/auth-provider-core`](../packages/core) — コアアプリケーションファクトリ

package/README.md

@@ -1,11 +1,49 @@
 # @o3co/create-auth-provider
 
-CLI scaffolder for auth.provider. Generates a new project from the standalone template.
+Last updated: 2026-10-03
+
+CLI scaffolder for auth.provider. Generates a new server project from one of the built-in templates.
+
+## Responsibility
+
+**Role.** The `npx` entry point that turns one of the in-repo templates under
+[`templates/`](../templates) — each a deployable composition root — 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, directory and template validation, copying the
+chosen 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/<name>`, not
+this package); and which templates there are, and what each is for — the
+[composition templates ADR](../packages/core/docs/adr/2026-09-29-composition-templates.md).
+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 every template and
+of the library versions they pin ([How the templates are bundled](#how-the-templates-are-bundled)).
 
 ## Usage
 
 ```bash
-npx @o3co/create-auth-provider <project-name> [--dir <dir-name>]
+npx @o3co/create-auth-provider <project-name> [--template <name>] [--dir <dir-name>] [--no-lockfile] [--no-mfa]
+```
+
+`--template` names the template to copy, `standalone` by default. The
+templates are the directories under [`templates/`](../templates) that hold a
+`package.json` (not a symbolic link, not dot-named), and the CLI refuses any
+other name, listing the ones it has.
+What each template is for is in its own README; how the set is drawn — a
+template per composition shape, not per feature — is in the
+[composition templates ADR](../packages/core/docs/adr/2026-09-29-composition-templates.md).
+
+```bash
+npx @o3co/create-auth-provider my-auth-server --template standalone
 ```
 
 `<project-name>` may be either a scoped npm name (`@scope/pkg`) or an unscoped name (`pkg`).
@@ -15,8 +53,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 +61,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 +71,84 @@ npx @o3co/create-auth-provider @my-org/auth.provider --dir provider
 cd provider
 ```
 
+`--no-lockfile` skips the lockfile step (step 7 below).
+
+The scaffold requires a second factor at every password login: the
+template's MFA switch, `mfaMode` (`MFA_MODE`), defaults to `required`. In
+development that needs nothing more; outside it, the project's boot is
+refused until it sets what MFA needs (its two stores on Redis, a key, an SMTP
+relay) or turns MFA off with `MFA_MODE=off`. The MFA page defaults to `/mfa`,
+which the project must serve, or every password login stops there. What the
+switch installs and needs is in the template's README.
+
+`--no-mfa` writes the switch off in the scaffold instead:
+it appends `mfaMode = "off"` and then `mfaMode = ${?MFA_MODE}` to
+`config/application.conf`, so the project stays off whatever default a later
+template ships, and `MFA_MODE` still turns MFA on without re-scaffolding. The
+MFA package stays a dependency; nothing else is removed or changed.
+
+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 (`REPOSITORIES_USER_HTTP_AUTHENTICATE_URL`,
+`REPOSITORIES_USER_HTTP_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. Checks that `--template` (default `standalone`) names a bundled template, and resolves the target directory as `<cwd>/<dir-name>`, erroring if it already exists.
+4. Copies the named 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). With `--no-mfa`, appends the MFA switch lines to its `config/application.conf`.
+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 templates are bundled
+
+The package's `prebuild` and `prepack` scripts run
+[`scripts/copy-templates.mjs`](scripts/copy-templates.mjs), which copies
+every template into `create-app/templates/<name>` (git-ignored; `node_modules/`
+and `dist/` excluded; the destination is rebuilt whole, so a template removed
+from the repository does not linger) 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.
+What a template is — a directory under `templates/`, not a symbolic link and
+not dot-named, holding a `package.json`, named in lowercase kebab-case — is
+defined once, in [`scripts/templates.mjs`](scripts/templates.mjs), which the
+copy and CI's build of every template both use; the scaffolder's
+`availableTemplates()` reads the copy by the same rule.
+[`published-package.test.mts`](src/__tests__/published-package.test.mts)
+packs the package and holds the tarball to the repository: it must ship every
+template, and each must scaffold from it.
+
+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
 
@@ -59,49 +161,38 @@ Both forms must be non-empty, not `.` or `..`, and ≤ 214 characters.
 
 `--dir <value>` must match the unscoped pattern above (same constraints).
 
+`--template <name>` must be the name of a bundled template, exactly; a path is
+never one. A template's name is lowercase kebab-case,
+`^[a-z0-9]+(?:-[a-z0-9]+)*$` (lowercase letters and digits, in parts joined by
+single hyphens); the build refuses a template named otherwise.
+
 ## 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.
+- Each bundled template's `README.md` / `README.ja.md` carry its upstream title, such as `@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 the chosen template, such as
+[`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, template?, options?)` — steps 4–6, from `template` (default `DEFAULT_TEMPLATE`, `"standalone"`); `options.noMfa` is `--no-mfa`. Throws, before writing anything, with `templateRefusal`'s message; and throws if a `workspace:*` dependency has no entry in `versions.json`.
+- `availableTemplates(templatesRoot?)` — the bundled templates' names, sorted.
+- `templateRefusal(template, templates)` — why `template` cannot be scaffolded (none bundled, or not one of them), or `undefined`.
+- `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, an unknown template or an existing directory.
+- `isValidProjectName(name)` / `isValidDirName(name)` — the [Validation Rules](#validation-rules).
 
 ## See Also
 
-- [`@o3co/auth-provider-standalone`](../templates/standalone) — The template this tool generates from
+- [`templates/`](../templates) — The templates this tool generates from; [`@o3co/auth-provider-standalone`](../templates/standalone) is the default
+- [Composition templates ADR](../packages/core/docs/adr/2026-09-29-composition-templates.md) — Why the templates are split as they are
 - [`@o3co/auth-provider-core`](../packages/core) — Core application factory

package/dist/index.d.mts

@@ -1,6 +1,32 @@
+/** The template a scaffold is made from when none is named. */
+export declare const DEFAULT_TEMPLATE = "standalone";
+/**
+ * The templates under `templatesRoot`: every directory — not a symbolic link,
+ * not dot-named — holding a `package.json`, sorted; none when the directory is
+ * missing. This is the rule `scripts/templates.mjs` copies templates by, read
+ * here from the copy, where `versions.json` sits beside them. A name is only
+ * ever looked up in this list, so nothing outside the templates directory can
+ * be named as a template.
+ */
+export declare const availableTemplates: (templatesRoot?: string) => string[];
+/**
+ * Why `template` cannot be scaffolded from `templates`, or `undefined` when it
+ * can: none is bundled (a checkout that never ran the prebuild script), or it
+ * is not one of them.
+ */
+export declare const templateRefusal: (template: string, templates: readonly string[]) => string | undefined;
 export declare const isValidProjectName: (name: string) => boolean;
 export declare const isValidDirName: (name: string) => boolean;
-export declare const scaffold: (targetDir: string, projectName: string) => void;
+/** What `scaffold()` changes in the copy beyond the name and the versions. */
+export interface ScaffoldOptions {
+    /**
+     * Write the template's MFA switch off (`MFA_OFF_LINES`), so the scaffold
+     * stays off whatever default a later template ships; `MFA_MODE` still
+     * turns MFA on.
+     */
+    readonly noMfa?: boolean;
+}
+export declare const scaffold: (targetDir: string, projectName: string, template?: string, options?: ScaffoldOptions) => void;
 /** Outcome of the scaffold-time lockfile generation. */
 export type LockfileResult = {
     readonly ok: true;
@@ -10,15 +36,12 @@ export type LockfileResult = {
     readonly reason: string;
 };
 /**
- * Resolve the scaffolded project's dependency graph into `pnpm-lock.yaml`.
- *
- * This is what makes the template's `pnpm install --frozen-lockfile` build
- * possible: the lockfile cannot be shipped with the template, because the
- * dependency set it would pin does not exist until `scaffold` has replaced
- * every `workspace:*` with a published version (#289). It is therefore
- * resolved once, here, against the rewritten `package.json`. Best-effort by
- * design — it needs a package manager and a reachable registry — so failure
- * is a result, not a throw.
+ * Resolve the scaffolded project's dependency graph into `pnpm-lock.yaml`,
+ * which the template's `pnpm install --frozen-lockfile` build needs. The
+ * lockfile cannot ship with the template: the dependency set it pins exists
+ * only after `scaffold` has replaced every `workspace:*`. Best-effort (it needs
+ * a package manager and a reachable registry), so failure is a result, not a
+ * throw.
  */
 export declare const generateLockfile: (targetDir: string) => LockfileResult;
 export declare const main: () => void;

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,KAAG,IAyEjE,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqBnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AA0DF,eAAO,MAAM,IAAI,QAAO,IAmEvB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAgCA,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAe,MAAuB,KAAG,MAAM,EAWjF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC3B,UAAU,MAAM,EAChB,WAAW,SAAS,MAAM,EAAE,KAC1B,MAAM,GAAG,SAQX,CAAC;AAcF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,OAIjD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAI7C,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CACzB;AAeD,eAAO,MAAM,QAAQ,GACpB,WAAW,MAAM,EACjB,aAAa,MAAM,EACnB,WAAU,MAAyB,EACnC,UAAS,eAAoB,KAC3B,IAwEF,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,cAAc,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAkBnD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,WAAW,MAAM,KAAG,cA6BpD,CAAC;AA4EF,eAAO,MAAM,IAAI,QAAO,IA6EvB,CAAC"}