@o3co/create-auth-provider 0.4.1

package/README.ja.md

@@ -0,0 +1,107 @@
+# @o3co/create-auth-provider
+
+auth.provider 用の CLI スキャフォルダーです。standalone テンプレートから新しいプロジェクトを生成します。
+
+## 使い方
+
+```bash
+npx @o3co/create-auth-provider <project-name> [--dir <dir-name>]
+```
+
+`<project-name>` はスコープ付き npm 名 (`@scope/pkg`) とスコープなしの名前 (`pkg`) のどちらでも指定できます。
+
+スコープなしの例:
+
+```bash
+npx @o3co/create-auth-provider my-auth-server
+cd my-auth-server
+npm install
+npm run debug
+```
+
+スコープ付きの例（ディレクトリ名はパッケージ部分 `auth.provider` がデフォルト）:
+
+```bash
+npx @o3co/create-auth-provider @my-org/auth.provider
+cd auth.provider
+npm install
+npm run debug
+```
+
+`--dir` でディレクトリ名を明示指定:
+
+```bash
+npx @o3co/create-auth-provider @my-org/auth.provider --dir provider
+cd provider
+```
+
+## 動作内容
+
+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. 次のステップを出力する。
+
+## バリデーションルール
+
+`<project-name>` は以下のいずれかに一致する必要があります:
+
+- スコープなし: `^[a-z0-9][a-z0-9-._~]*$`
+- スコープ付き: `^@[a-z0-9][a-z0-9-._~]*/[a-z0-9][a-z0-9-._~]*$`
+
+いずれも空文字・`.`・`..` は不可、最大 214 文字。
+
+`--dir <value>` はスコープなしのパターンと同じ制約です。
+
+## 既知の制約
+
+内包されているテンプレートの `README.md` / `README.ja.md` の見出しは `@o3co/auth-provider-standalone` のままです。スコープ付きでプロジェクトを生成した場合、この見出しは生成された `package.json` の `name` と一致しません。必要に応じて手動で修正してください。
+
+## 生成される構造
+
+```
+<プロジェクト名>/
+├── 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` を作成し、必須の環境変数を設定してください。
+
+## プログラマティック API
+
+```typescript
+import { scaffold, main } from "@o3co/create-auth-provider";
+
+// 絶対パスにプロジェクトを生成する
+scaffold(targetDir: string, projectName: string): void;
+
+// CLI エントリーポイント — process.argv を読み取り、エラー時は終了する
+main(): void;
+```
+
+テンプレートディレクトリが見つからない場合、または `workspace:*` 依存関係が `versions.json` で解決できない場合、`scaffold` はエラーをスローします。
+
+## 関連
+
+- [`@o3co/auth-provider-standalone`](../templates/standalone) — このツールが生成元とするテンプレート
+- [`@o3co/auth-provider-core`](../packages/core) — コアアプリケーションファクトリ

package/README.md

@@ -0,0 +1,107 @@
+# @o3co/create-auth-provider
+
+CLI scaffolder for auth.provider. Generates a new project from the standalone template.
+
+## Usage
+
+```bash
+npx @o3co/create-auth-provider <project-name> [--dir <dir-name>]
+```
+
+`<project-name>` may be either a scoped npm name (`@scope/pkg`) or an unscoped name (`pkg`).
+
+Unscoped example:
+
+```bash
+npx @o3co/create-auth-provider my-auth-server
+cd my-auth-server
+npm install
+npm run debug
+```
+
+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
+```
+
+Override the directory name with `--dir`:
+
+```bash
+npx @o3co/create-auth-provider @my-org/auth.provider --dir provider
+cd provider
+```
+
+## What It Does
+
+1. Validates `<project-name>` (see 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:
+   - 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.
+
+## Validation Rules
+
+`<project-name>` must match one of:
+
+- Unscoped: `^[a-z0-9][a-z0-9-._~]*$`
+- Scoped: `^@[a-z0-9][a-z0-9-._~]*/[a-z0-9][a-z0-9-._~]*$`
+
+Both forms must be non-empty, not `.` or `..`, and ≤ 214 characters.
+
+`--dir <value>` must match the unscoped pattern above (same constraints).
+
+## 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.
+
+## 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`).
+
+## 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;
+```
+
+`scaffold` throws if the template directory is missing or if a `workspace:*` dependency cannot be resolved in `versions.json`.
+
+## See Also
+
+- [`@o3co/auth-provider-standalone`](../templates/standalone) — The template this tool generates from
+- [`@o3co/auth-provider-core`](../packages/core) — Core application factory

package/dist/__tests__/index.test.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.mts.map

package/dist/__tests__/index.test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.mts","sourceRoot":"","sources":["../../src/__tests__/index.test.mts"],"names":[],"mappings":""}

package/dist/__tests__/index.test.mjs

@@ -0,0 +1,226 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { isValidDirName, isValidProjectName, main, scaffold } from "../index.mjs";
+describe("scaffold", () => {
+    let tempDir;
+    beforeEach(() => {
+        tempDir = mkdtempSync(join(tmpdir(), "create-auth-provider-test-"));
+    });
+    afterEach(() => {
+        rmSync(tempDir, { recursive: true, force: true });
+    });
+    it("copies template files to target directory", () => {
+        const targetDir = join(tempDir, "my-auth");
+        scaffold(targetDir, "my-auth");
+        expect(existsSync(join(targetDir, "package.json"))).toBe(true);
+        expect(existsSync(join(targetDir, "tsconfig.json"))).toBe(true);
+        expect(existsSync(join(targetDir, "src", "app.mts"))).toBe(true);
+        expect(existsSync(join(targetDir, "config", "application.conf"))).toBe(true);
+        expect(existsSync(join(targetDir, "config", "development.conf"))).toBe(true);
+        expect(existsSync(join(targetDir, "config", "production.conf"))).toBe(true);
+    });
+    it("rewrites package.json name to project name", () => {
+        const targetDir = join(tempDir, "my-auth");
+        scaffold(targetDir, "my-auth");
+        const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf-8"));
+        expect(pkg.name).toBe("my-auth");
+    });
+    it("replaces all workspace:* dependencies with caret versions", () => {
+        const targetDir = join(tempDir, "my-auth");
+        scaffold(targetDir, "my-auth");
+        const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf-8"));
+        // No workspace:* should remain anywhere
+        for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
+            const deps = pkg[section];
+            if (!deps)
+                continue;
+            for (const [name, version] of Object.entries(deps)) {
+                expect(version, `${section}.${name} should not be workspace:*`).not.toBe("workspace:*");
+            }
+        }
+        // Specific checks
+        expect(pkg.dependencies["@o3co/auth-provider-core"]).toMatch(/^\^/);
+        expect(pkg.dependencies["@o3co/auth-provider-federation-google"]).toMatch(/^\^/);
+        expect(pkg.dependencies["@o3co/auth-provider-federation-github"]).toBeUndefined();
+        expect(pkg.dependencies["@o3co/auth-provider-foundation"]).toMatch(/^\^/);
+    });
+    it("removes private field from package.json", () => {
+        const targetDir = join(tempDir, "my-auth");
+        scaffold(targetDir, "my-auth");
+        const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf-8"));
+        expect(pkg.private).toBeUndefined();
+    });
+    it("writes scoped project name verbatim into package.json", () => {
+        const targetDir = join(tempDir, "auth.provider");
+        scaffold(targetDir, "@piratis-blossoms/auth.provider");
+        const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf-8"));
+        expect(pkg.name).toBe("@piratis-blossoms/auth.provider");
+    });
+    it("ships versions for optional federation provider packages", () => {
+        const versions = JSON.parse(readFileSync(join("templates", "versions.json"), "utf-8"));
+        expect(versions["@o3co/auth-provider-federation-google"]).toBe("0.0.0");
+        expect(versions["@o3co/auth-provider-federation-github"]).toBe("0.0.0");
+    });
+});
+describe("isValidProjectName", () => {
+    it.each([
+        ["my-auth"],
+        ["auth.provider"],
+        ["a"],
+        ["foo_bar~baz.1"],
+        ["@piratis-blossoms/auth.provider"],
+        ["@foo-bar/baz_qux~1"],
+    ])("accepts %s", (name) => {
+        expect(isValidProjectName(name)).toBe(true);
+    });
+    it.each([
+        [""],
+        ["."],
+        [".."],
+        ["UPPER"],
+        ["with space"],
+        ["with/slash"],
+        ["with\\back"],
+        ["@"],
+        ["@/"],
+        ["@scope"],
+        ["@/pkg"],
+        ["@scope/"],
+        ["@scope//pkg"],
+        ["@SCOPE/pkg"],
+        ["a".repeat(215)],
+    ])("rejects %s", (name) => {
+        expect(isValidProjectName(name)).toBe(false);
+    });
+});
+describe("isValidDirName", () => {
+    it.each([["my-auth"], ["auth.provider"], ["a"], ["foo_bar~baz.1"]])("accepts %s", (name) => {
+        expect(isValidDirName(name)).toBe(true);
+    });
+    it.each([
+        [""],
+        ["."],
+        [".."],
+        ["@scope/pkg"],
+        ["with/slash"],
+        ["with\\back"],
+        ["@piratis-blossoms"],
+        ["UPPER"],
+        ["a".repeat(215)],
+    ])("rejects %s", (name) => {
+        expect(isValidDirName(name)).toBe(false);
+    });
+});
+describe("main (argv parsing and directory derivation)", () => {
+    let cwdBackup;
+    let workdir;
+    let argvBackup;
+    beforeEach(() => {
+        cwdBackup = process.cwd();
+        workdir = mkdtempSync(join(tmpdir(), "create-auth-provider-main-"));
+        process.chdir(workdir);
+        argvBackup = process.argv;
+    });
+    afterEach(() => {
+        process.chdir(cwdBackup);
+        process.argv = argvBackup;
+        rmSync(workdir, { recursive: true, force: true });
+    });
+    const runMain = (args) => {
+        process.argv = ["node", "cli", ...args];
+        const exitSpy = vi.spyOn(process, "exit").mockImplementation(((code) => {
+            throw new Error(`__exit__:${code ?? 0}`);
+        }));
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+        let exitCode = 0;
+        try {
+            main();
+        }
+        catch (e) {
+            const m = /__exit__:(\d+)/.exec(e.message);
+            exitCode = m ? Number(m[1]) : null;
+        }
+        const stderr = errSpy.mock.calls.map((c) => c.join(" ")).join("\n");
+        exitSpy.mockRestore();
+        errSpy.mockRestore();
+        logSpy.mockRestore();
+        return { exitCode, stderr };
+    };
+    // Positive: unscoped, no --dir
+    it("unscoped name: dir = name, pkg.name = name", () => {
+        const r = runMain(["my-auth"]);
+        expect(r.exitCode).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(workdir, "my-auth", "package.json"), "utf-8"));
+        expect(pkg.name).toBe("my-auth");
+    });
+    // Positive: scoped, no --dir
+    it("scoped name: dir = pkg part, pkg.name = full scoped", () => {
+        const r = runMain(["@piratis-blossoms/auth.provider"]);
+        expect(r.exitCode).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(workdir, "auth.provider", "package.json"), "utf-8"));
+        expect(pkg.name).toBe("@piratis-blossoms/auth.provider");
+    });
+    // Positive: scoped + --dir space
+    it("scoped name with --dir <val>: dir = val, pkg.name = full scoped", () => {
+        const r = runMain(["@piratis-blossoms/auth.provider", "--dir", "provider"]);
+        expect(r.exitCode).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(workdir, "provider", "package.json"), "utf-8"));
+        expect(pkg.name).toBe("@piratis-blossoms/auth.provider");
+    });
+    // Positive: scoped + --dir= equals form
+    it("scoped name with --dir=<val>: dir = val, pkg.name = full scoped", () => {
+        const r = runMain(["@piratis-blossoms/auth.provider", "--dir=provider2"]);
+        expect(r.exitCode).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(workdir, "provider2", "package.json"), "utf-8"));
+        expect(pkg.name).toBe("@piratis-blossoms/auth.provider");
+    });
+    // Positive: unscoped + --dir
+    it("unscoped name with --dir <val>: dir = val, pkg.name = unscoped", () => {
+        const r = runMain(["my-auth", "--dir", "custom"]);
+        expect(r.exitCode).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(workdir, "custom", "package.json"), "utf-8"));
+        expect(pkg.name).toBe("my-auth");
+    });
+    // Positive: flags may come before the positional
+    it("flags before positional: --dir custom my-auth", () => {
+        const r = runMain(["--dir", "custom", "my-auth"]);
+        expect(r.exitCode).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(workdir, "custom", "package.json"), "utf-8"));
+        expect(pkg.name).toBe("my-auth");
+    });
+    // Negative cases
+    it.each([
+        { case: "no args", args: [] },
+        { case: "two positionals", args: ["foo", "bar"] },
+        { case: "dot", args: ["."] },
+        { case: "dotdot", args: [".."] },
+        { case: "backslash in name", args: ["back\\slash"] },
+        { case: "empty scope", args: ["@/pkg"] },
+        { case: "empty pkg", args: ["@scope/"] },
+        { case: "double slash", args: ["@scope//pkg"] },
+        { case: "name too long", args: ["a".repeat(215)] },
+        { case: "--dir invalid (dot)", args: ["foo", "--dir", "."] },
+        { case: "--dir invalid (slash)", args: ["foo", "--dir", "a/b"] },
+        { case: "--dir invalid (at)", args: ["foo", "--dir", "@foo"] },
+        { case: "--dir invalid (back)", args: ["foo", "--dir", "a\\b"] },
+        { case: "--dir empty space form", args: ["foo", "--dir", ""] },
+        { case: "--dir empty equals form", args: ["foo", "--dir="] },
+        { case: "--dir missing value", args: ["foo", "--dir"] },
+        { case: "--dir duplicated", args: ["foo", "--dir", "a", "--dir", "b"] },
+        { case: "unknown flag", args: ["foo", "--unknown"] },
+        { case: "literal double-dash", args: ["foo", "--"] },
+    ])("rejects: $case", ({ args }) => {
+        const r = runMain(args);
+        expect(r.exitCode).toBe(1);
+        expect(r.stderr.length).toBeGreaterThan(0);
+    });
+    it("target directory already exists", () => {
+        mkdirSync(join(workdir, "foo"));
+        const r = runMain(["foo"]);
+        expect(r.exitCode).toBe(1);
+        expect(r.stderr.length).toBeGreaterThan(0);
+    });
+});

package/dist/cli.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","sourceRoot":"","sources":["../src/cli.mts"],"names":[],"mappings":""}

package/dist/cli.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { main } from "./index.mjs";
+main();

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+export declare const isValidProjectName: (name: string) => boolean;
+export declare const isValidDirName: (name: string) => boolean;
+export declare const scaffold: (targetDir: string, projectName: string) => void;
+export declare const main: () => void;
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.mts"],"names":[],"mappings":"AAkCA,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,IA0CjE,CAAC;AAsDF,eAAO,MAAM,IAAI,QAAO,IA+CvB,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,166 @@
+/*
+ * Copyright 2026 1o1 Co. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = resolve(__dirname, "../templates/standalone");
+const getPackageVersions = () => {
+    const versionFile = resolve(__dirname, "../templates/versions.json");
+    if (existsSync(versionFile)) {
+        return JSON.parse(readFileSync(versionFile, "utf-8"));
+    }
+    return {};
+};
+const UNSCOPED_NAME_RE = /^[a-z0-9][a-z0-9-._~]*$/;
+const SCOPED_NAME_RE = /^@[a-z0-9][a-z0-9-._~]*\/[a-z0-9][a-z0-9-._~]*$/;
+const MAX_NAME_LEN = 214;
+export const isValidProjectName = (name) => {
+    if (name.length === 0 || name.length > MAX_NAME_LEN)
+        return false;
+    if (name === "." || name === "..")
+        return false;
+    return UNSCOPED_NAME_RE.test(name) || SCOPED_NAME_RE.test(name);
+};
+export const isValidDirName = (name) => {
+    if (name.length === 0 || name.length > MAX_NAME_LEN)
+        return false;
+    if (name === "." || name === "..")
+        return false;
+    return UNSCOPED_NAME_RE.test(name);
+};
+export const scaffold = (targetDir, projectName) => {
+    if (!existsSync(TEMPLATES_DIR)) {
+        throw new Error(`Template directory not found at ${TEMPLATES_DIR}. If developing locally, run the prebuild script first.`);
+    }
+    // Copy template to target
+    const EXCLUDED_DIRS = new Set(["node_modules", "dist"]);
+    cpSync(TEMPLATES_DIR, targetDir, {
+        recursive: true,
+        filter: (source) => {
+            const segments = source.split(sep);
+            return !segments.some((s) => EXCLUDED_DIRS.has(s));
+        },
+    });
+    // Rewrite package.json
+    const pkgPath = resolve(targetDir, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    pkg.name = projectName;
+    delete pkg.private;
+    // Replace all workspace:* references with per-package published versions
+    const versions = getPackageVersions();
+    for (const section of ["dependencies", "devDependencies", "peerDependencies"]) {
+        const deps = pkg[section];
+        if (!deps)
+            continue;
+        for (const [name, version] of Object.entries(deps)) {
+            if (version === "workspace:*") {
+                const resolved = versions[name];
+                if (!resolved) {
+                    throw new Error(`Cannot resolve version for workspace dependency "${name}". Ensure versions.json includes this package.`);
+                }
+                deps[name] = `^${resolved}`;
+            }
+        }
+    }
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+};
+const parseArgs = (args) => {
+    const positionals = [];
+    let dir;
+    let dirSeen = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--dir") {
+            if (dirSeen)
+                throw new Error("--dir specified more than once");
+            if (i + 1 >= args.length)
+                throw new Error("--dir requires a value");
+            dir = args[i + 1];
+            dirSeen = true;
+            i++;
+        }
+        else if (a.startsWith("--dir=")) {
+            if (dirSeen)
+                throw new Error("--dir specified more than once");
+            dir = a.slice("--dir=".length);
+            dirSeen = true;
+        }
+        else if (a.startsWith("-")) {
+            // Treats `--` and any --unknown as an unknown flag.
+            throw new Error(`unknown flag: ${a}`);
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    if (positionals.length === 0)
+        throw new Error("missing <project-name>");
+    if (positionals.length > 1)
+        throw new Error("too many positional arguments");
+    return { projectName: positionals[0], dir };
+};
+const deriveDirName = (projectName, dir) => {
+    if (dir !== undefined)
+        return dir;
+    if (projectName.startsWith("@")) {
+        const pkgPart = projectName.split("/")[1];
+        if (!pkgPart) {
+            // Unreachable when projectName has passed isValidProjectName (SCOPED_NAME_RE
+            // guarantees a non-empty package segment after the single "/"). Guarded here
+            // so refactors that reorder validation cannot silently produce undefined.
+            throw new Error(`invariant: unvalidated scoped name ${projectName}`);
+        }
+        return pkgPart;
+    }
+    return projectName;
+};
+// CLI entry point
+export const main = () => {
+    const args = process.argv.slice(2);
+    let parsed;
+    try {
+        parsed = parseArgs(args);
+    }
+    catch (e) {
+        console.error(`Error: ${e.message}`);
+        console.error("Usage: @o3co/create-auth-provider <project-name> [--dir <dir-name>]");
+        console.error("<project-name> must be a valid npm package name (scoped like @scope/pkg, or unscoped).");
+        process.exit(1);
+    }
+    const { projectName, dir } = parsed;
+    if (!isValidProjectName(projectName)) {
+        console.error("Error: <project-name> must be a valid npm package name (scoped like @scope/pkg, or unscoped; max 214 chars; no backslashes; no extra '/' beyond the single scope separator).");
+        process.exit(1);
+    }
+    if (dir !== undefined && !isValidDirName(dir)) {
+        console.error("Error: --dir must be a valid unscoped package name (no '/', '\\', '@'; not '.' or '..'; max 214 chars).");
+        process.exit(1);
+    }
+    const dirName = deriveDirName(projectName, dir);
+    const targetDir = resolve(process.cwd(), dirName);
+    if (existsSync(targetDir)) {
+        console.error(`Error: Directory '${dirName}' already exists.`);
+        process.exit(1);
+    }
+    console.log(`Creating ${projectName}...`);
+    scaffold(targetDir, projectName);
+    console.log(`\nDone! Created ${projectName} at ${targetDir}`);
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${dirName}`);
+    console.log("  npm install");
+    console.log("  npm run debug");
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@o3co/create-auth-provider",
+	"version": "0.4.1",
+	"description": "Scaffold a new o3co/auth.provider project from the standalone template",
+	"license": "Apache-2.0",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/o3co/auth.provider.git",
+		"directory": "create-app"
+	},
+	"bin": {
+		"create-auth-provider": "./dist/cli.mjs"
+	},
+	"files": [
+		"dist",
+		"templates"
+	],
+	"scripts": {
+		"build": "tsc",
+		"prebuild": "node scripts/copy-templates.mjs",
+		"test": "vitest run"
+	},
+	"devDependencies": {
+		"@types/node": "^25.1.0",
+		"vitest": "^4.1.2"
+	}
+}