@o3co/create-auth-provider 0.16.0 → 0.17.0-rc.2

package/README.ja.md

@@ -1,35 +1,49 @@
 # @o3co/create-auth-provider
 
-最終更新: 2026-09-24
+最終更新: 2026-10-03
 
-auth.provider 用の CLI スキャフォルダーです。内包する standalone テンプレートから新しいサーバープロジェクトを生成します。
+auth.provider 用の CLI スキャフォルダーです。内包するテンプレートの 1 つから新しいサーバープロジェクトを生成します。
 
 ## 責務と役割
 
-**役割。** リポジトリ内のテンプレート
-[`templates/standalone`](../templates/standalone) を、独立した新しいプロジェクトに
-変換する `npx` の入口です。運用者のマシン上で一度だけ実行されます。生成された
+**役割。** リポジトリ内の [`templates/`](../templates) にあるテンプレート
+（それぞれがデプロイ可能なコンポジションルート）の 1 つを、独立した新しい
+プロジェクトに変換する `npx` の入口です。運用者のマシン上で一度だけ実行されます。生成された
 プロジェクトはこのパッケージを import せず、このパッケージも `packages/*` の
 ライブラリを一切 import しません。
 
-**担うもの。** プロジェクト名とディレクトリ名の検証、テンプレートのコピー、生成された
+**担うもの。** プロジェクト名・ディレクトリ名・テンプレート名の検証、選んだテンプレートのコピー、生成された
 `package.json` の書き換え（名前、`workspace:*` → 公開バージョン）、プロジェクトの
 `pnpm-workspace.yaml` の書き出し、そして一度きりの `pnpm-lock.yaml` の解決。
 
 **担わないもの。** 生成されるプロジェクトの中身 — ソース、設定、Dockerfile、
-テスト — はテンプレートのものです（このパッケージではなく `templates/standalone` を
-編集してください）。実行時の振る舞いは `@o3co/auth-provider-core` と、テンプレートが
+テスト — はテンプレートのものです（このパッケージではなく `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>] [--no-lockfile]
+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`) のどちらでも指定できます。
@@ -59,6 +73,20 @@ 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` にあります。
@@ -67,7 +95,7 @@ CLI は最後のメッセージで次に `pnpm run debug` を実行するよう
 スキャフォールドのデフォルトのままでは、これは起動しません: `.env` ファイルは
 読まず（読むのは compose ファイルだけ）、シェルの環境変数から issuer
 （`OAUTH_JWT_ISSUER`）、署名鍵のペア、セッションシークレット、ユーザーサービスの
-2 つの URL（`CLIENT_USER_AUTHENTICATE_URL`、`CLIENT_USER_AUTHENTICATE_BY_TOKEN_URL`）、
+2 つの URL（`REPOSITORIES_USER_HTTP_AUTHENTICATE_URL`、`REPOSITORIES_USER_HTTP_AUTHENTICATE_BY_TOKEN_URL`）、
 そして `localhost:6379` の Redis を必要とします。コマンドは、プロジェクトに含まれる
 テンプレートの README の[使い方](../templates/standalone/README.ja.md#使い方)にあります。
 
@@ -75,8 +103,8 @@ CLI は最後のメッセージで次に `pnpm run debug` を実行するよう
 
 1. `<project-name>` を検証する（[バリデーションルール](#バリデーションルール) 参照）。
 2. 生成先ディレクトリ名を決定する: `--dir <value>` が指定されていればその値、そうでなければスコープ付き名のパッケージ部分、最終的には入力値そのもの。
-3. 生成先ディレクトリを `<cwd>/<dir-name>` として解決し、すでに存在する場合はエラーで終了する。
-4. 内包するテンプレートを生成先ディレクトリにコピーし（`node_modules/` と `dist/` は除外）、`.gitignore` を復元する（npm は公開パッケージから `.gitignore` という名前のファイルを落とすため、tarball には `gitignore` として入っている）。
+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 プロバイダーが誤って公開できてはならないため。本当に公開するつもりなら自分でこのフィールドを削除する。
@@ -100,12 +128,21 @@ lockfile をテンプレートに同梱することはできません: 手順 5
 
 パッケージの `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` —
+すべてのテンプレートを `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` のバージョン
@@ -124,15 +161,20 @@ CI は [`scripts/check-versions-json.mjs`](scripts/check-versions-json.mjs) を
 
 `--dir <value>` はスコープなしのパターンと同じ制約です。
 
+`--template <name>` は内包するテンプレートの名前と完全に一致する必要があります。パスは
+テンプレート名になりません。テンプレート名は小文字のケバブケース
+`^[a-z0-9]+(?:-[a-z0-9]+)*$`（英小文字と数字の並びを 1 つのハイフンでつなぐ）で、
+それ以外の名前のテンプレートはビルドが拒否します。
+
 ## 既知の制約
 
-- 内包されているテンプレートの `README.md` / `README.ja.md` の見出しは上流の `@o3co/auth-provider-standalone` のままです。スコープ付きでプロジェクトを生成した場合、この見出しは `package.json` の名前と一致しません。必要に応じて手動で修正してください。
+- 内包されている各テンプレートの `README.md` / `README.ja.md` の見出しは上流の名前（たとえば `@o3co/auth-provider-standalone`）のままです。スコープ付きでプロジェクトを生成した場合、この見出しは `package.json` の名前と一致しません。必要に応じて手動で修正してください。
 - テンプレートの README は、このリポジトリ内を相対パス（`../../docs/…`、`../../packages/…`）でリンクしています。これはモノレポ内では解決しますが、横に `docs/` も `packages/` もないスキャフォールド先のプロジェクトでは解決しません。GitHub 上で参照してください。
 
 ## 生成される構造
 
-生成されるプロジェクトは [`templates/standalone`](../templates/standalone) の
-完全なコピー（`node_modules/` と `dist/` を除く）に、`pnpm-workspace.yaml`（手順 6）と、
+生成されるプロジェクトは、選んだテンプレート（たとえば
+[`templates/standalone`](../templates/standalone)）の完全なコピー（`node_modules/` と `dist/` を除く）に、`pnpm-workspace.yaml`（手順 6）と、
 `--no-lockfile` を指定せず lockfile の手順が失敗しなかった場合は `pnpm-lock.yaml`（手順 7）を加えたものです。どの
 ファイルがモジュール構成で、どれがホストプロセスで、スキャフォールドが何を
 持つかは、テンプレートの README に記述されています。
@@ -142,12 +184,15 @@ CI は [`scripts/check-versions-json.mjs`](scripts/check-versions-json.mjs) を
 モジュールは CLI を構成する関数を export しています。シグネチャは
 [`src/index.mts`](src/index.mts) にあります。
 
-- `scaffold(targetDir, projectName)` — 手順 4〜6。内包するテンプレートがない場合、または `workspace:*` 依存が `versions.json` に見つからない場合は例外を投げる。
+- `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` を読み、不正な引数や既存のディレクトリに対しては非ゼロで終了する。
+- `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,35 +1,49 @@
 # @o3co/create-auth-provider
 
-Last updated: 2026-09-24
+Last updated: 2026-10-03
 
-CLI scaffolder for auth.provider. Generates a new standalone server project from the built-in template.
+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 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
+**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 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.
+**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/standalone`, not
-this package). Runtime behaviour belongs to `@o3co/auth-provider-core` and the
-libraries the template depends on.
+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 the template and of
-the library versions it pins ([How the template is bundled](#how-the-template-is-bundled)).
+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>] [--no-lockfile]
+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`).
@@ -59,6 +73,20 @@ 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`.
@@ -67,8 +95,8 @@ 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
+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).
 
@@ -76,8 +104,8 @@ template's README, which the project carries, gives the commands under
 
 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>`, 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).
+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).
    - 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.
@@ -96,16 +124,25 @@ 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
+## How the templates are 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.
+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
@@ -124,14 +161,19 @@ 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` 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
 
-The generated project is a complete copy of
+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
@@ -142,12 +184,15 @@ the composition, which is the host process, and what the scaffold owns.
 The module exports the functions the CLI is built from; their signatures are
 in [`src/index.mts`](src/index.mts).
 
-- `scaffold(targetDir, projectName)` — steps 4–6. Throws if the bundled template is missing or a `workspace:*` dependency has no entry 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 or an existing directory.
+- `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"}