@decohere/scaffold 0.0.1-dev.18 → 0.0.1-dev.20261105.54

package/es6/src/models/project.model.js

@@ -0,0 +1,117 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+/**
+ * A sub-unit of the monorepo (e.g. `projects/api`).
+ *
+ * Models and files registered here produce paths relative to `dir`. The parent
+ * `MonoRepoScaffold` calls `files()` and prepends `dir/` to every path, so
+ * models remain unaware of where they live in the repo.
+ */ export class ProjectScaffold {
+    dir;
+    _models = new Map();
+    _files = [];
+    constructor(dir){
+        this.dir = dir;
+    }
+    addModel(model) {
+        this._models.set(model.key, model);
+        return model;
+    }
+    addFile(provider) {
+        this._files.push(...provider.files());
+        return this;
+    }
+    getModel(key) {
+        return this._models.get(key);
+    }
+    getModels(ctor) {
+        return [
+            ...this._models.values()
+        ].filter((m)=>m instanceof ctor);
+    }
+    /** Returns all files with `dir/` prepended to each path. */ files() {
+        const all = [
+            ...this._files,
+            ...[
+                ...this._models.values()
+            ].flatMap((m)=>m.files())
+        ];
+        return all.map((f)=>({
+                filePath: `${this.dir}/${f.filePath}`,
+                content: f.content
+            }));
+    }
+}
+export class WorkspaceScaffold {
+    files = [];
+    targetDir = process.cwd();
+    _name;
+    /** Project name — host directory basename, not the in-container mount path. */ get name() {
+        return this._name ?? basename(this.targetDir);
+    }
+    setName(name) {
+        this._name = name;
+        return this;
+    }
+    /** Add an ad-hoc file provider whose output is included at render time. */ addFile(provider) {
+        this.files.push(...provider.files());
+        return this;
+    }
+}
+export class MonoRepoScaffold extends WorkspaceScaffold {
+    _models = new Map();
+    _projects = [];
+    /** Register a named project. */ addProject(project) {
+        this._projects.push(project);
+        return project;
+    }
+    /** Retrieve a previously-registered project by its directory path. */ getProject(dir) {
+        return this._projects.find((p)=>p.dir === dir);
+    }
+    /** All registered projects, in registration order. */ getProjects() {
+        return this._projects;
+    }
+    /** Register a named model at workspace level. */ addModel(model) {
+        this._models.set(model.key, model);
+        return model;
+    }
+    /**
+	 * Retrieve a model by key. Searches workspace models first, then all
+	 * registered projects in order.
+	 */ getModel(key) {
+        const m = this._models.get(key);
+        if (m !== undefined) return m;
+        for (const project of this._projects){
+            const pm = project.getModel(key);
+            if (pm !== undefined) return pm;
+        }
+        return undefined;
+    }
+    /**
+	 * Retrieve all models of a given type. Searches workspace models and all
+	 * projects, so features can discover controllers across multiple projects.
+	 */ getModels(ctor) {
+        return [
+            ...[
+                ...this._models.values()
+            ].filter((m)=>m instanceof ctor),
+            ...this._projects.flatMap((p)=>p.getModels(ctor))
+        ];
+    }
+    /** Render all models and projects into files, then write everything to disk. */ async scaffold() {
+        const allFiles = [
+            ...this.files,
+            ...[
+                ...this._models.values()
+            ].flatMap((m)=>m.files()),
+            ...this._projects.flatMap((p)=>p.files())
+        ];
+        await Promise.all(allFiles.map(async (file)=>{
+            const fullPath = join(this.targetDir, file.filePath);
+            await mkdir(dirname(fullPath), {
+                recursive: true
+            });
+            await writeFile(fullPath, file.content);
+        }));
+    }
+}

package/es6/src/models/source-file.js

@@ -0,0 +1 @@
+export { };

package/es6/src/models/tsconfig.model.js

@@ -0,0 +1,22 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+export class TsConfig {
+    key = WELL_KNOWN_FILES.TSCONFIG;
+    files() {
+        return [
+            {
+                filePath: "tsconfig.json",
+                content: JSON.stringify({
+                    compilerOptions: {
+                        target: "ES2022",
+                        module: "NodeNext",
+                        moduleResolution: "NodeNext",
+                        strict: true,
+                        skipLibCheck: true,
+                        experimentalDecorators: true,
+                        emitDecoratorMetadata: true
+                    }
+                }, null, 2)
+            }
+        ];
+    }
+}

package/es6/src/models/vitest-config.model.js

@@ -0,0 +1,23 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+export class VitestConfig {
+    key = WELL_KNOWN_FILES.VITEST_CONFIG;
+    files() {
+        return [
+            {
+                filePath: "vitest.config.ts",
+                content: [
+                    'import { forgeBuild } from "@decohere/forge/vitest";',
+                    'import { defineConfig } from "vitest/config";',
+                    "",
+                    "export default defineConfig({",
+                    '\tplugins: [forgeBuild({ logLevel: "silent" })],',
+                    "\ttest: {",
+                    '\t\tinclude: ["projects/**/*.{test,spec}.?(c|m)[jt]s?(x)"],',
+                    "\t},",
+                    "});",
+                    ""
+                ].join("\n")
+            }
+        ];
+    }
+}

package/es6/src/models/vscode-settings.model.js

@@ -0,0 +1,19 @@
+import { WELL_KNOWN_FILES } from "./const.js";
+export class VSCodeSettings {
+    title;
+    key = WELL_KNOWN_FILES.VSCODE_SETTINGS;
+    constructor(title){
+        this.title = title;
+    }
+    files() {
+        return [
+            {
+                filePath: ".vscode/settings.json",
+                content: JSON.stringify({
+                    "window.title": `${this.title}\${separator}\${activeEditorShort}`,
+                    "window.titleSeparator": " | "
+                }, null, 2)
+            }
+        ];
+    }
+}

package/es6/src/program.js

@@ -0,0 +1,50 @@
+import { Command, CommanderError } from "commander";
+import { CreateCliError } from "./webapi/api-name.js";
+import { runAuth0Configure, runAuth0Login } from "./webapi/auth0-commands.js";
+import { addWebapiFeatureOptions, collectName, runScaffoldApi, toApiOptions } from "./webapi/cli-options.js";
+export function createProgram() {
+    const program = new Command();
+    program.exitOverride();
+    program.name("decohere").description("Decohere CLI").option("-d <directory>", "Target directory (default: current directory)", ".");
+    const create = program.command("create").description("Create a new Decohere workspace");
+    addWebapiFeatureOptions(create.command("webapi").argument("[directory]", "Target directory (default: -d or current directory)").option("--name <slug>", "API name under projects/ (repeatable; default: api)", collectName, [])).action(async (directory, _opts, cmd)=>{
+        await runScaffoldApi(toApiOptions(directory, cmd.optsWithGlobals()));
+    });
+    addWebapiFeatureOptions(program.command("add").description("Add to an existing Decohere workspace").command("api").argument("<name>", "API name under projects/")).action(async (name, _opts, cmd)=>{
+        await runScaffoldApi(toApiOptions(undefined, cmd.optsWithGlobals(), {
+            names: [
+                name
+            ],
+            add: true
+        }));
+    });
+    const auth0 = program.command("auth0").description("Log in to Auth0 and update a scaffolded client");
+    auth0.command("login").description("Authenticate the Auth0 CLI (device URL; tokens persist on the host)").action(()=>{
+        runAuth0Login();
+    });
+    auth0.command("configure").description("Update Auth0 API permissions and Postman SPA from @Authorize in this workspace").action((_opts, cmd)=>{
+        const d = cmd.optsWithGlobals().d;
+        runAuth0Configure(typeof d === "string" ? d : ".");
+    });
+    return program;
+}
+/**
+ * Runs the CLI and returns its exit code; the bin (`cli.ts`) exits with it. Returning instead
+ * of calling `process.exit` here lets tests run it in process: a run that finished after its
+ * test had timed out used to call `process.exit` in whichever test came next.
+ */ export async function runCli(argv = process.argv) {
+    try {
+        await createProgram().parseAsync(argv);
+    } catch (err) {
+        if (err instanceof CommanderError) {
+            return err.exitCode;
+        }
+        if (err instanceof CreateCliError) {
+            console.error(`\n  ${err.message}\n`);
+            return 1;
+        }
+        console.error(err);
+        return 1;
+    }
+    return typeof process.exitCode === "number" ? process.exitCode : 0;
+}

package/es6/src/resolve-target-dir.js

@@ -0,0 +1,7 @@
+/**
+ * Resolve scaffold destination: positional `webapi my-app` wins over `-d`.
+ * `npm create … webapi -d my-app` drops `-d` (npm loglevel) and forwards `my-app`.
+ */ export function resolveTargetDir(positional, flag) {
+    const dir = positional?.trim() || flag?.trim() || ".";
+    return dir;
+}

package/es6/src/services/scaffold.service.js

@@ -0,0 +1,50 @@
+async function scaffold(workspace, cliOptions, features) {
+    const options = await getAllOptions(workspace, cliOptions, features);
+    // Features mutate workspace models first, then workspace renders to disk.
+    await scaffoldFeatures(workspace, options, features);
+    await scaffoldWorkspace(workspace, options);
+    // Post-write phase: install deps, print final messages, etc.
+    await finalizeFeatures(workspace, options, features);
+}
+async function scaffoldWorkspace(workspace, _options) {
+    await workspace.scaffold();
+}
+/**
+ * Iterate features in order, calling `getOptions` on each.
+ * Each feature receives the running merged options so later features can
+ * branch on decisions made by earlier ones (e.g. database choice affects auth).
+ * Results are shallow-merged, so features only need to return what they own.
+ */ async function getAllOptions(workspace, cliOptions, features) {
+    let options = {
+        ...cliOptions
+    };
+    for (const feature of features){
+        const featureOptions = await feature.getOptions(workspace, options);
+        options = {
+            ...options,
+            ...featureOptions
+        };
+    }
+    return options;
+}
+/**
+ * Iterate features in order, calling `scaffold` with the fully-resolved options.
+ * All option-gathering is complete before any scaffolding begins.
+ */ async function scaffoldFeatures(workspace, options, features) {
+    for (const feature of features){
+        await feature.scaffold(workspace, options);
+    }
+}
+/**
+ * Iterate features in order, calling `finalize` on each (if defined).
+ * All files are on disk by this point.
+ */ async function finalizeFeatures(workspace, options, features) {
+    for (const feature of features){
+        if (feature.finalize) {
+            await feature.finalize(workspace, options);
+        }
+    }
+}
+export const ScaffoldService = {
+    scaffold
+};

package/es6/src/version.js

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const _require = createRequire(import.meta.url);
+const DEFAULT_CREATE_VERSION = "0.0.1-dev";
+const DEFAULT_CREATE_IMAGE_REPOSITORY = "ghcr.io/typesmiths/decohere/create";
+const DEFAULT_DEVCONTAINER_IMAGE_REPOSITORY = "ghcr.io/typesmiths/decohere/devcontainer";
+function resolveCreateMetadata() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for(let i = 0; i < 5; i++){
+        try {
+            const pkg = _require(join(dir, "package.json"));
+            if (pkg.name === "@decohere/scaffold") {
+                return {
+                    version: pkg.version ?? DEFAULT_CREATE_VERSION,
+                    imageRepository: pkg.decohere?.dockerImageRepository ?? DEFAULT_CREATE_IMAGE_REPOSITORY,
+                    devcontainerImageRepository: pkg.decohere?.devcontainerImageRepository ?? DEFAULT_DEVCONTAINER_IMAGE_REPOSITORY
+                };
+            }
+        } catch  {}
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return {
+        version: DEFAULT_CREATE_VERSION,
+        imageRepository: DEFAULT_CREATE_IMAGE_REPOSITORY,
+        devcontainerImageRepository: DEFAULT_DEVCONTAINER_IMAGE_REPOSITORY
+    };
+}
+const createMetadata = resolveCreateMetadata();
+/** Version of @decohere/create, used to pin scaffolded @decohere/* dependencies. */ export const CREATE_VERSION = createMetadata.version;
+/** Canonical published Docker repository for the @decohere/create builder image. */ export const CREATE_IMAGE_REPOSITORY = createMetadata.imageRepository;
+/** Published app Dev Container base (`docker pull` updates shared layers). */ export const DEVCONTAINER_IMAGE_REPOSITORY = createMetadata.devcontainerImageRepository;

package/es6/src/webapi/api-name.js

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_WEBAPI_NAME } from "./const.js";
+/** Lowercase npm-safe directory slug: `billing`, `admin-api`. */ export const API_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+export class CreateCliError extends Error {
+    constructor(message){
+        super(message);
+        this.name = "CreateCliError";
+    }
+}
+export function assertValidApiName(name) {
+    if (!API_NAME_PATTERN.test(name)) {
+        throw new CreateCliError(`Invalid API name "${name}". Use a lowercase slug starting with a letter, then letters, digits, or hyphens (e.g. billing).`);
+    }
+}
+/** Default `["api"]` when the caller omitted `--name`. Rejects duplicates and invalid slugs. */ export function parseApiNames(raw) {
+    const names = raw != null && raw.length > 0 ? [
+        ...raw
+    ] : [
+        DEFAULT_WEBAPI_NAME
+    ];
+    const seen = new Set();
+    for (const name of names){
+        assertValidApiName(name);
+        if (seen.has(name)) {
+            throw new CreateCliError(`Duplicate API name "${name}".`);
+        }
+        seen.add(name);
+    }
+    return names;
+}
+export function isDecohereWorkspace(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        const build = pkg.scripts?.build;
+        return typeof build === "string" && build.includes("forge");
+    } catch  {
+        return false;
+    }
+}
+/** Directory names under `projects/` that already have a `package.json`. */ export function listExistingApiNames(dir) {
+    const projectsDir = join(dir, "projects");
+    try {
+        return readdirSync(projectsDir, {
+            withFileTypes: true
+        }).filter((entry)=>entry.isDirectory() && existsSync(join(projectsDir, entry.name, "package.json"))).map((entry)=>entry.name).sort();
+    } catch  {
+        return [];
+    }
+}
+/** `billing` → `BILLING`, `admin-api` → `ADMIN_API` — prefix for `{PREFIX}_DB_HOST`. */ export function apiEnvPrefix(apiName) {
+    return apiName.replace(/-/g, "_").toUpperCase();
+}
+export function apiNameFromProjectDir(dir) {
+    const slash = dir.lastIndexOf("/");
+    return slash >= 0 ? dir.slice(slash + 1) : dir;
+}

package/es6/src/webapi/auth0-commands.js

@@ -0,0 +1,185 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { CreateCliError, isDecohereWorkspace } from "./api-name.js";
+import { discoverAuthorizeScopes, mergeApiScopes, postmanRequestedScopes } from "./authorize-scopes.js";
+import * as auth0Cli from "./features/auth0-cli.js";
+/** Same Postman OAuth callbacks as `PostmanFeature`. */ const POSTMAN_CALLBACKS = [
+    "https://oauth.pstmn.io/v1/callback",
+    "https://oauth.pstmn.io/v1/browser-callback"
+];
+const SPA_SUFFIX = " Postman";
+export const AUTH0_CLI_INSTALL_MESSAGE = "The Auth0 CLI is required.\n" + "  It is bundled in the Decohere create image (`npx @decohere/create auth0 login`).\n" + "  Host install: brew install auth0/auth0-cli/auth0\n" + "  Or visit: https://github.com/auth0/auth0-cli";
+function fail(message) {
+    throw new CreateCliError(message);
+}
+/** Throw if the `auth0` binary is missing. */ export function requireInstalled() {
+    if (auth0Cli.isInstalled()) return;
+    fail(AUTH0_CLI_INSTALL_MESSAGE);
+}
+/**
+ * Log in when there is no tenant session or the Management API token is expired.
+ * Returns the active tenant.
+ */ export function ensureLoggedIn() {
+    requireInstalled();
+    process.stdout.write("\n  Checking Auth0 credentials...");
+    let tenants = auth0Cli.listTenants();
+    if (tenants.length === 0) {
+        process.stdout.write(" not logged in.\n");
+        console.log("  Logging in to Auth0 (open the URL in your browser)...");
+        if (!auth0Cli.login()) fail("Auth0 login failed.");
+        tenants = auth0Cli.listTenants();
+    }
+    try {
+        auth0Cli.listApis();
+        process.stdout.write(" ok.\n");
+    } catch (err) {
+        if (err instanceof auth0Cli.Auth0AuthError) {
+            process.stdout.write(" token expired.\n");
+            console.log("  Re-authenticating (open the URL in your browser)...");
+            if (!auth0Cli.login()) fail("Auth0 login failed.");
+            tenants = auth0Cli.listTenants();
+        }
+    }
+    const active = tenants.find((t)=>t.active) ?? tenants[0];
+    if (active == null) fail("No Auth0 tenant after login.");
+    return active;
+}
+export function runAuth0Login() {
+    requireInstalled();
+    console.log("  Logging in to Auth0 (open the URL in your browser)...");
+    if (!auth0Cli.login()) fail("Auth0 login failed.");
+    const tenants = auth0Cli.listTenants();
+    const active = tenants.find((t)=>t.active) ?? tenants[0];
+    if (active == null) fail("No Auth0 tenant after login.");
+    console.log(`\n  ✓ Auth0 tenant: https://${active.name}`);
+    console.log("    Tokens are stored in ~/.config/auth0 (mounted into the create image).");
+    console.log("    Next: npx @decohere/create auth0 configure");
+}
+export function runAuth0Configure(directory = ".") {
+    const targetDir = resolve(directory);
+    if (!isDecohereWorkspace(targetDir)) {
+        throw new CreateCliError(`Not a Decohere workspace: ${targetDir}. Scaffold one first with \`npx @decohere/create webapi\`.`);
+    }
+    const active = ensureLoggedIn();
+    const issuerBaseUrl = `https://${active.name}`;
+    const projectName = process.env.DECOHERE_PROJECT_NAME?.trim() || basename(targetDir);
+    const envPath = join(targetDir, ".env");
+    const existing = readEnvFile(envPath);
+    const existingAudience = existing.AUTH0_AUDIENCE?.trim();
+    const discovered = discoverAuthorizeScopes(targetDir);
+    let existingScopes = [];
+    if (existingAudience) {
+        try {
+            existingScopes = auth0Cli.listApiScopes(existingAudience);
+        } catch (err) {
+            if (err instanceof auth0Cli.Auth0AuthError) throw err;
+        }
+    }
+    const apiScopes = resolveApiScopes(discovered, existingScopes);
+    console.log(discovered.length > 0 ? `  ✓ Scanned @Authorize — ${discovered.length} scope(s) from controllers` : "  ✓ No @Authorize in projects/*/src — keeping existing / Hello scopes");
+    let audience = existingAudience;
+    if (audience) {
+        try {
+            auth0Cli.updateApiScopes(audience, apiScopes);
+            console.log(`  ✓ API scopes ensured (${apiScopes.join(", ")})`);
+        } catch (err) {
+            console.error(`  ✗ Failed to update API scopes: ${err instanceof Error ? err.message : err}`);
+        }
+    } else {
+        const identifier = `https://api.${projectName}`;
+        console.log(`\n  Creating Auth0 API ${identifier}...`);
+        audience = auth0Cli.createApi(`${projectName} API`, identifier, apiScopes).identifier;
+        console.log(`  ✓ API created: ${audience}`);
+    }
+    const appName = `${projectName}${SPA_SUFFIX}`;
+    const app = auth0Cli.ensureSpaApp(appName, [
+        ...POSTMAN_CALLBACKS
+    ]);
+    console.log(app.reused ? `  ✓ Reusing Auth0 SPA app (${app.client_id})` : `  ✓ Auth0 SPA app created (${app.client_id})`);
+    try {
+        auth0Cli.enableConnectionForClient(auth0Cli.DB_CONNECTION_NAME, app.client_id);
+        console.log(`  ✓ Enabled ${auth0Cli.DB_CONNECTION_NAME} on SPA`);
+    } catch (err) {
+        console.error(`  ✗ Failed to enable DB connection on SPA: ${err instanceof Error ? err.message : err}`);
+    }
+    upsertEnv(envPath, {
+        AUTH0_ISSUER_BASE_URL: issuerBaseUrl,
+        AUTH0_AUDIENCE: audience
+    });
+    console.log(`  ✓ Wrote AUTH0_ISSUER_BASE_URL and AUTH0_AUDIENCE to .env`);
+    const adminSub = existing.AUTH0_ADMIN_USER_SUB?.trim();
+    if (adminSub) {
+        try {
+            auth0Cli.assignUserPermissions(adminSub, audience, apiScopes);
+            console.log(`  ✓ Assigned ${apiScopes.length} API permission(s) to admin user`);
+        } catch (err) {
+            console.error(`  ✗ Failed to assign admin permissions: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    const domain = issuerBaseUrl.replace(/^https?:\/\//, "");
+    patchPostmanAuth(targetDir, projectName, {
+        domain,
+        audience,
+        clientId: app.client_id,
+        scopes: postmanRequestedScopes(apiScopes)
+    });
+}
+function readEnvFile(path) {
+    if (!existsSync(path)) return {};
+    const out = {};
+    for (const line of readFileSync(path, "utf8").split("\n")){
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0) continue;
+        out[line.slice(0, eq).trim()] = line.slice(eq + 1);
+    }
+    return out;
+}
+function resolveApiScopes(discovered, existing) {
+    const merged = mergeApiScopes(discovered, existing);
+    return merged.length > 0 ? merged : [
+        ...auth0Cli.HELLO_API_SCOPES
+    ].sort();
+}
+function upsertEnv(path, entries) {
+    let text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    for (const [key, value] of Object.entries(entries)){
+        const re = new RegExp(`^${key}=.*$`, "m");
+        if (re.test(text)) {
+            text = text.replace(re, `${key}=${value}`);
+        } else {
+            text = `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${key}=${value}\n`;
+        }
+    }
+    if (text !== "" && !text.endsWith("\n")) text = `${text}\n`;
+    writeFileSync(path, text);
+}
+function patchPostmanAuth(targetDir, projectName, auth) {
+    const envYaml = join(targetDir, "postman/environments", `${projectName}-Local.environment.yaml`);
+    if (existsSync(envYaml)) {
+        let yaml = readFileSync(envYaml, "utf8");
+        yaml = replaceYamlKeyedValue(yaml, "auth0Domain", auth.domain);
+        yaml = replaceYamlKeyedValue(yaml, "auth0Audience", auth.audience);
+        yaml = replaceYamlKeyedValue(yaml, "auth0ClientId", auth.clientId);
+        yaml = replaceYamlKeyedValue(yaml, "authUrl", `https://${auth.domain}/authorize?audience=${auth.audience}`);
+        yaml = replaceYamlKeyedValue(yaml, "accessTokenUrl", `https://${auth.domain}/oauth/token`);
+        yaml = replaceYamlKeyedValue(yaml, "scope", auth.scopes);
+        writeFileSync(envYaml, yaml);
+        console.log(`  ✓ Updated Postman environment auth0ClientId (${auth.clientId})`);
+        console.log(`  ✓ Updated Postman token scopes`);
+    }
+    const collectionDef = join(targetDir, "postman/collections", `${projectName} WebAPI`, ".resources/definition.yaml");
+    if (existsSync(collectionDef)) {
+        let yaml = readFileSync(collectionDef, "utf8");
+        yaml = yaml.replace(/^(\s*clientId:\s*).+$/m, `$1${JSON.stringify(auth.clientId)}`);
+        yaml = yaml.replace(/^(\s*scope:\s*).+$/m, `$1${JSON.stringify(auth.scopes)}`);
+        writeFileSync(collectionDef, yaml);
+    }
+}
+/** Replace `key: <name>` / `value: …` pairs in Postman Local View environment YAML. */ function replaceYamlKeyedValue(yaml, key, value) {
+    const quoted = JSON.stringify(value);
+    const re = new RegExp(`(key:\\s*${key}\\s*\\n\\s*value:\\s*)[^\\n]+`, "m");
+    if (!re.test(yaml)) return yaml;
+    return yaml.replace(re, `$1${quoted}`);
+}

package/es6/src/webapi/authorize-scopes.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listExistingApiNames } from "./api-name.js";
+/** OIDC scopes requested on the Postman SPA token (not Auth0 API permissions). */ export const OIDC_SCOPES = [
+    "openid",
+    "profile",
+    "email"
+];
+const AUTHORIZE_RE = /@Authorize\(\s*(["'])([^"']+)\1(?:\s*,\s*(["'])([^"']+)\3)?\s*\)/g;
+function isAppSource(fileName) {
+    return fileName.endsWith(".ts") && !fileName.endsWith(".spec.ts") && !fileName.endsWith(".test.ts") && !fileName.endsWith(".d.ts");
+}
+/** Collect action:Subject scopes from Authorize decorators in each API src tree. */ export function discoverAuthorizeScopes(rootDir) {
+    const scopes = new Set();
+    for (const apiName of listExistingApiNames(rootDir)){
+        collectFromDir(join(rootDir, "projects", apiName, "src"), scopes);
+    }
+    return [
+        ...scopes
+    ].sort();
+}
+function collectFromDir(dir, scopes) {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, {
+        withFileTypes: true
+    })){
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectFromDir(path, scopes);
+            continue;
+        }
+        if (!entry.isFile() || !isAppSource(entry.name)) continue;
+        const text = readFileSync(path, "utf8");
+        for (const match of text.matchAll(AUTHORIZE_RE)){
+            const action = match[2];
+            if (action == null || action === "") continue;
+            const subject = match[4] ?? "all";
+            scopes.add(`${action}:${subject}`);
+        }
+    }
+}
+/** Additive union so Auth0 CLI scope replace does not drop permissions already on the API. */ export function mergeApiScopes(discovered, existing) {
+    return [
+        ...new Set([
+            ...existing,
+            ...discovered
+        ])
+    ].sort();
+}
+export function postmanRequestedScopes(apiScopes) {
+    return [
+        ...OIDC_SCOPES,
+        ...apiScopes
+    ].join(" ");
+}

package/es6/src/webapi/cli-options.js

@@ -0,0 +1,34 @@
+import { resolveTargetDir } from "../resolve-target-dir.js";
+import { parseApiNames } from "./api-name.js";
+import { scaffoldApi } from "./create-api.js";
+export function collectName(value, previous) {
+    previous.push(value);
+    return previous;
+}
+export function addWebapiFeatureOptions(cmd) {
+    return cmd.option("--database <provider>", "Database provider: none | postgres/typeorm").option("--auth <provider>", "Auth provider: none | auth0").option("--postman <provider>", "Postman provider: none | local | api").option("-y, --yes", "Install dependencies without prompting").option("--install <mode>", "Dependency install mode: ask | yes | no", "ask");
+}
+export function toApiOptions(directory, opts, extra = {}) {
+    const installMode = String(opts.install ?? "ask").toLowerCase();
+    const names = Array.isArray(opts.name) ? opts.name : typeof opts.name === "string" ? [
+        opts.name
+    ] : extra.names;
+    return {
+        d: resolveTargetDir(directory, typeof opts.d === "string" ? opts.d : undefined),
+        databaseProvider: opts.database,
+        authProvider: opts.auth,
+        postmanProvider: opts.postman,
+        installDependencies: opts.yes === true ? "yes" : installMode === "yes" || installMode === "no" ? installMode : undefined,
+        names,
+        ...extra
+    };
+}
+export async function runScaffoldApi(normalized) {
+    parseApiNames(normalized.names);
+    const { closePrompt } = await import("../domain/prompt.js");
+    try {
+        await scaffoldApi(normalized);
+    } finally{
+        closePrompt();
+    }
+}