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

package/es6/src/webapi/features/auth0-cli.js

@@ -0,0 +1,406 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+/** Management API scopes needed for API, SPA, connections, and admin users. */ const REQUIRED_SCOPES = [
+    "create:clients",
+    "read:clients",
+    "update:clients",
+    "create:resource_servers",
+    "read:resource_servers",
+    "update:resource_servers",
+    "read:connections",
+    "update:connections",
+    "create:users",
+    "read:users",
+    "update:users"
+].join(",");
+/** Hard timeout for any Management API call. Prevents indefinite hangs on token re-auth. */ const API_TIMEOUT_MS = 8_000;
+/** Default API scopes matching Hello CASL Authorize decorators. */ export const HELLO_API_SCOPES = [
+    "read:Hello",
+    "create:Hello",
+    "update:Hello",
+    "delete:Hello"
+];
+export const DB_CONNECTION_NAME = "Username-Password-Authentication";
+export class Auth0AuthError extends Error {
+    constructor(message){
+        super(message);
+        this.name = "Auth0AuthError";
+    }
+}
+/** Returns true if an error or stderr output looks like an expired/missing token. */ function isAuthError(text) {
+    return text.includes("renew access token") || text.includes("log in") || text.includes("Unauthorized");
+}
+/** Strip Auth0 CLI banner lines before JSON. */ function parseJsonOutput(stdout) {
+    const start = stdout.indexOf("{");
+    const arrayStart = stdout.indexOf("[");
+    let idx = -1;
+    if (start === -1) idx = arrayStart;
+    else if (arrayStart === -1) idx = start;
+    else idx = Math.min(start, arrayStart);
+    if (idx < 0) throw new Error(`Expected JSON from auth0 CLI, got: ${stdout.slice(0, 200)}`);
+    return JSON.parse(stdout.slice(idx));
+}
+/** Run an auth0 CLI command with a hard timeout. Returns stdout on success, throws on failure. */ function runAuth0(args) {
+    const result = spawnSync("auth0", args, {
+        encoding: "utf8",
+        timeout: API_TIMEOUT_MS,
+        input: "",
+        stdio: "pipe"
+    });
+    if (result.error) {
+        const msg = result.error.message;
+        if (isAuthError(msg) || result.error.code === "ETIMEDOUT") {
+            throw new Auth0AuthError(msg);
+        }
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const stderr = result.stderr ?? "";
+        if (isAuthError(stderr)) throw new Auth0AuthError(stderr);
+        throw new Error(stderr || `auth0 exited with code ${result.status}`);
+    }
+    return result.stdout;
+}
+export function isInstalled() {
+    try {
+        execFileSync("auth0", [
+            "--version"
+        ], {
+            stdio: "pipe"
+        });
+        return true;
+    } catch  {
+        return false;
+    }
+}
+export function listTenants() {
+    try {
+        const out = execFileSync("auth0", [
+            "tenants",
+            "list",
+            "--json"
+        ], {
+            encoding: "utf8",
+            stdio: "pipe"
+        });
+        return JSON.parse(out);
+    } catch  {
+        return [];
+    }
+}
+/** Device/URL login (`--no-input`) so Docker can print a host-browser URL. */ export function login() {
+    const result = spawnSync("auth0", [
+        "login",
+        "--scopes",
+        REQUIRED_SCOPES,
+        "--no-input"
+    ], {
+        stdio: "inherit"
+    });
+    return result.status === 0;
+}
+export function listApis() {
+    try {
+        const out = runAuth0([
+            "apis",
+            "list",
+            "--json",
+            "--no-input"
+        ]);
+        return parseJsonOutput(out);
+    } catch (err) {
+        if (err instanceof Auth0AuthError) throw err;
+        return [];
+    }
+}
+export function createApi(name, identifier, scopes = HELLO_API_SCOPES) {
+    const out = runAuth0([
+        "apis",
+        "create",
+        "--name",
+        name,
+        "--identifier",
+        identifier,
+        "--scopes",
+        scopes.join(","),
+        // RBAC: only permissions assigned to the user/role appear on the token.
+        "--enforce-policies",
+        // Include Auth0 `permissions[]` claim (consumed by sample principalMapper).
+        "--token-dialect",
+        "access_token_authz",
+        "--json",
+        "--no-input"
+    ]);
+    return parseJsonOutput(out);
+}
+export function listApiScopes(identifier) {
+    try {
+        const out = runAuth0([
+            "apis",
+            "show",
+            identifier,
+            "--json",
+            "--no-input"
+        ]);
+        const api = parseJsonOutput(out);
+        return (api.scopes ?? []).map((scope)=>typeof scope === "string" ? scope : scope.value ?? scope.name ?? "").filter((scope)=>scope.length > 0);
+    } catch (err) {
+        if (err instanceof Auth0AuthError) throw err;
+        return [];
+    }
+}
+/** Assign API permissions to a user (Authorization Core). Idempotent when already granted. */ export function assignUserPermissions(userId, audience, permissions) {
+    if (permissions.length === 0) return;
+    runAuth0([
+        "api",
+        "post",
+        `users/${encodeURIComponent(userId)}/permissions`,
+        "--data",
+        JSON.stringify({
+            permissions: permissions.map((permission_name)=>({
+                    resource_server_identifier: audience,
+                    permission_name
+                }))
+        }),
+        "--no-input"
+    ]);
+}
+/**
+ * Replace an API's scopes and enable RBAC policy enforcement.
+ * Auth0 CLI `--scopes` replaces the full set.
+ */ export function updateApiScopes(identifier, scopes = HELLO_API_SCOPES) {
+    runAuth0([
+        "apis",
+        "update",
+        identifier,
+        "--scopes",
+        scopes.join(","),
+        "--enforce-policies",
+        "--token-dialect",
+        "access_token_authz",
+        "--no-input"
+    ]);
+}
+/** True when Auth0 refuses create because the tenant hit its Applications quota. */ export function isAuth0EntityLimitError(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    return /limit of entities|reached the limit|tenant application limit reached/i.test(text);
+}
+/**
+ * Actionable message when Auth0 will not create another application.
+ * Does not suggest reusing unrelated apps — free tenants must delete unused ones.
+ */ export function formatSpaEntityLimitError(appName, apps) {
+    const listed = apps.length === 0 ? "Could not list existing applications." : `This tenant already has ${apps.length} application(s):\n${apps.map((a)=>`  - ${a.name} (${a.client_id})`).join("\n")}`;
+    return [
+        `Auth0 refused to create SPA "${appName}": tenant application limit reached.`,
+        listed,
+        "",
+        "Fix: Auth0 Dashboard → Applications → Applications → delete unused apps,",
+        `then re-run the scaffold (or choose Postman "none" to skip SPA creation).`,
+        "Re-scaffold of the same project name reuses an exact-name match when it still exists."
+    ].join("\n");
+}
+export function createSpaApp(name, callbackUrls) {
+    const callbacks = typeof callbackUrls === "string" ? callbackUrls : callbackUrls.join(",");
+    const out = runAuth0([
+        "apps",
+        "create",
+        "--name",
+        name,
+        "--type",
+        "spa",
+        "--callbacks",
+        callbacks,
+        "--json",
+        "--no-input"
+    ]);
+    const app = parseJsonOutput(out);
+    const clientId = app.client_id ?? app.clientId;
+    if (!clientId) {
+        throw new Error(`Auth0 create SPA response missing client_id. stdout: ${out.slice(0, 300)}`);
+    }
+    return {
+        client_id: clientId
+    };
+}
+export function listApps() {
+    try {
+        const out = runAuth0([
+            "apps",
+            "list",
+            "--json",
+            "--no-input"
+        ]);
+        const apps = parseJsonOutput(out);
+        return apps.map((a)=>({
+                client_id: a.client_id ?? a.clientId ?? "",
+                name: a.name ?? ""
+            })).filter((a)=>a.client_id && a.name);
+    } catch (err) {
+        if (err instanceof Auth0AuthError) throw err;
+        return [];
+    }
+}
+export function updateSpaCallbacks(clientId, callbackUrls) {
+    const callbacks = typeof callbackUrls === "string" ? callbackUrls : callbackUrls.join(",");
+    runAuth0([
+        "apps",
+        "update",
+        clientId,
+        "--callbacks",
+        callbacks,
+        "--no-input"
+    ]);
+}
+/**
+ * Create a Postman SPA, or reuse an existing app with the same name (re-scaffold).
+ * Always returns a client_id suitable for Postman auth0ClientId.
+ * On Auth0 application-quota errors, throws a clear delete-apps message (no cross-app reuse).
+ */ export function ensureSpaApp(name, callbackUrls) {
+    const apps = listApps();
+    const existing = apps.find((a)=>a.name === name);
+    if (existing) {
+        try {
+            updateSpaCallbacks(existing.client_id, callbackUrls);
+        } catch  {
+        // Callbacks may already match; still usable for Postman.
+        }
+        return {
+            client_id: existing.client_id,
+            reused: true
+        };
+    }
+    try {
+        return {
+            ...createSpaApp(name, callbackUrls),
+            reused: false
+        };
+    } catch (err) {
+        if (isAuth0EntityLimitError(err)) {
+            throw new Error(formatSpaEntityLimitError(name, apps));
+        }
+        throw err;
+    }
+}
+/** Enable a database connection for an application (required for username/password login). */ export function enableConnectionForClient(connectionName, clientId) {
+    const listOut = runAuth0([
+        "api",
+        "get",
+        "connections",
+        "--no-input"
+    ]);
+    const connections = parseJsonOutput(listOut);
+    const connection = connections.find((c)=>c.name === connectionName);
+    if (!connection) {
+        throw new Error(`Auth0 connection not found: ${connectionName}`);
+    }
+    const clientsOut = runAuth0([
+        "api",
+        "get",
+        `connections/${connection.id}/clients`,
+        "--no-input"
+    ]);
+    const { clients } = parseJsonOutput(clientsOut);
+    if (clients.some((c)=>c.client_id === clientId)) return;
+    // Dedicated enabled-clients endpoint (enabled_clients on connection PATCH is deprecated).
+    runAuth0([
+        "api",
+        "patch",
+        `connections/${connection.id}/clients`,
+        "--data",
+        JSON.stringify([
+            {
+                client_id: clientId,
+                status: true
+            }
+        ]),
+        "--no-input"
+    ]);
+}
+/** Strong default password when the scaffolder caller leaves password blank. */ export function generateAdminPassword() {
+    return `${randomBytes(12).toString("base64url")}aA1!`;
+}
+function isUserAlreadyExistsError(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    return /already exists|user exists|Conflict|409/i.test(text);
+}
+/** Look up a user by email (Management API users-by-email). */ export function findUserByEmail(email) {
+    const out = runAuth0([
+        "api",
+        "get",
+        `users-by-email?email=${encodeURIComponent(email)}`,
+        "--no-input"
+    ]);
+    const users = parseJsonOutput(out);
+    const user = users.find((u)=>u.user_id && u.email);
+    if (!user?.user_id || !user.email) return null;
+    return {
+        user_id: user.user_id,
+        email: user.email
+    };
+}
+/** Reset password so a re-scaffold can write a known password to .env. */ export function updateUserPassword(userId, password) {
+    runAuth0([
+        "api",
+        "patch",
+        `users/${encodeURIComponent(userId)}`,
+        "--data",
+        JSON.stringify({
+            password,
+            connection: DB_CONNECTION_NAME
+        }),
+        "--no-input"
+    ]);
+}
+/**
+ * Create a DB connection root-admin user for local / Postman login.
+ * If the user already exists, look them up, reset password to `input.password`,
+ * and return that identity so callers can still write .env credentials.
+ */ export function createAdminDatabaseUser(input) {
+    const body = {
+        email: input.email,
+        connection: DB_CONNECTION_NAME,
+        password: input.password,
+        name: input.username,
+        email_verified: true,
+        verify_email: false,
+        app_metadata: {
+            roles: [
+                "admin"
+            ]
+        }
+    };
+    try {
+        const out = runAuth0([
+            "api",
+            "post",
+            "users",
+            "--data",
+            JSON.stringify(body),
+            "--no-input"
+        ]);
+        const user = parseJsonOutput(out);
+        if (!user.user_id || !user.email) {
+            throw new Error(`Auth0 create user response missing user_id/email. stdout: ${out.slice(0, 300)}`);
+        }
+        return {
+            user_id: user.user_id,
+            email: user.email,
+            password: input.password,
+            username: input.username
+        };
+    } catch (err) {
+        if (!isUserAlreadyExistsError(err)) throw err;
+        const existing = findUserByEmail(input.email);
+        if (!existing) {
+            throw new Error(`Auth0 user already exists for ${input.email}, but lookup by email returned no user.`);
+        }
+        updateUserPassword(existing.user_id, input.password);
+        return {
+            user_id: existing.user_id,
+            email: existing.email,
+            password: input.password,
+            username: input.username
+        };
+    }
+}
+export { REQUIRED_SCOPES };

package/es6/src/webapi/features/biome-format.js

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Format/lint-fix all files in the scaffolded workspace with Biome.
+ * Prefer a global `biome` binary (builder image); fall back to `npx`.
+ */ export function formatScaffoldedFiles(targetDir, paths = [
+    "."
+]) {
+    process.stdout.write("\n  Formatting scaffolded files with Biome...");
+    let result = spawnSync("biome", [
+        "check",
+        "--write",
+        ...paths
+    ], {
+        cwd: targetDir,
+        encoding: "utf8",
+        stdio: "pipe"
+    });
+    if (result.error && result.error.code === "ENOENT") {
+        result = spawnSync("npx", [
+            "--yes",
+            "@biomejs/biome",
+            "check",
+            "--write",
+            ...paths
+        ], {
+            cwd: targetDir,
+            encoding: "utf8",
+            stdio: "pipe"
+        });
+    }
+    if (result.status === 0) {
+        process.stdout.write(" done.\n");
+        return;
+    }
+    const detail = (result.stderr || result.stdout || result.error?.message || "").trim();
+    process.stdout.write(" failed.\n");
+    if (detail) {
+        console.error(`  ✗ Biome: ${detail.slice(0, 400)}`);
+    }
+}