keycloakify 10.0.0-rc.3 → 10.0.0-rc.31

package/src/bin/main.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import { termost } from "termost";
+import { readThisNpmPackageVersion } from "./tools/readThisNpmPackageVersion";
+import * as child_process from "child_process";
+
+export type CliCommandOptions = {
+    reactAppRootDirPath: string | undefined;
+};
+
+const program = termost<CliCommandOptions>(
+    {
+        name: "keycloakify",
+        description: "Keycloakify CLI",
+        version: readThisNpmPackageVersion()
+    },
+    {
+        onException: error => {
+            console.error(error);
+            process.exit(1);
+        }
+    }
+);
+
+const optionsKeys: string[] = [];
+
+program.option({
+    key: "reactAppRootDirPath",
+    name: (() => {
+        const long = "project";
+        const short = "p";
+
+        optionsKeys.push(long, short);
+
+        return { long, short };
+    })(),
+    description: [
+        `For monorepos, path to the keycloakify project.`,
+        "Example: `npx keycloakify build --project packages/keycloak-theme`",
+        "https://docs.keycloakify.dev/build-options#project-or-p-cli-option"
+    ].join(" "),
+    defaultValue: undefined
+});
+
+function skip(_context: any, argv: { options: Record<string, unknown> }) {
+    const unrecognizedOptionKey = Object.keys(argv.options).find(
+        key => !optionsKeys.includes(key)
+    );
+
+    if (unrecognizedOptionKey !== undefined) {
+        console.error(
+            `keycloakify: Unrecognized option: ${
+                unrecognizedOptionKey.length === 1 ? "-" : "--"
+            }${unrecognizedOptionKey}`
+        );
+        process.exit(1);
+    }
+
+    return false;
+}
+
+program
+    .command({
+        name: "build",
+        description: "Build the theme (default subcommand)."
+    })
+    .task({
+        skip,
+        handler: async cliCommandOptions => {
+            const { command } = await import("./keycloakify");
+
+            await command({ cliCommandOptions });
+        }
+    });
+
+program
+    .command<{
+        port: number;
+        keycloakVersion: string | undefined;
+        realmJsonFilePath: string | undefined;
+    }>({
+        name: "start-keycloak",
+        description:
+            "Spin up a pre configured Docker image of Keycloak to test your theme."
+    })
+    .option({
+        key: "port",
+        name: (() => {
+            const name = "port";
+
+            optionsKeys.push(name);
+
+            return name;
+        })(),
+        description: ["Keycloak server port.", "Example `--port 8085`"].join(" "),
+        defaultValue: 8080
+    })
+    .option({
+        key: "keycloakVersion",
+        name: (() => {
+            const name = "keycloak-version";
+
+            optionsKeys.push(name);
+
+            return name;
+        })(),
+        description: [
+            "Use a specific version of Keycloak.",
+            "Example `--keycloak-version 21.1.1`"
+        ].join(" "),
+        defaultValue: undefined
+    })
+    .option({
+        key: "realmJsonFilePath",
+        name: (() => {
+            const name = "import";
+
+            optionsKeys.push(name);
+
+            return name;
+        })(),
+        defaultValue: undefined,
+        description: [
+            "Import your own realm configuration file",
+            "Example `--import path/to/myrealm-realm.json`"
+        ].join(" ")
+    })
+    .task({
+        skip,
+        handler: async cliCommandOptions => {
+            const { command } = await import("./start-keycloak");
+
+            await command({ cliCommandOptions });
+        }
+    });
+
+program
+    .command({
+        name: "download-keycloak-default-theme",
+        description: "Download the built-in Keycloak theme."
+    })
+    .task({
+        skip,
+        handler: async cliCommandOptions => {
+            const { command } = await import("./download-keycloak-default-theme");
+
+            await command({ cliCommandOptions });
+        }
+    });
+
+program
+    .command({
+        name: "eject-page",
+        description: "Eject a Keycloak page."
+    })
+    .task({
+        skip,
+        handler: async cliCommandOptions => {
+            const { command } = await import("./eject-page");
+
+            await command({ cliCommandOptions });
+        }
+    });
+
+program
+    .command({
+        name: "initialize-email-theme",
+        description: "Initialize an email theme."
+    })
+    .task({
+        skip,
+        handler: async cliCommandOptions => {
+            const { command } = await import("./initialize-email-theme");
+
+            await command({ cliCommandOptions });
+        }
+    });
+
+program
+    .command({
+        name: "copy-keycloak-resources-to-public",
+        description:
+            "(Webpack/Create-React-App only) Copy Keycloak default theme resources to the public directory."
+    })
+    .task({
+        skip,
+        handler: async cliCommandOptions => {
+            const { command } = await import("./copy-keycloak-resources-to-public");
+
+            await command({ cliCommandOptions });
+        }
+    });
+
+// Fallback to build command if no command is provided
+{
+    const [, , ...rest] = process.argv;
+
+    if (
+        rest.length === 0 ||
+        (rest[0].startsWith("-") && rest[0] !== "--help" && rest[0] !== "-h")
+    ) {
+        const { status } = child_process.spawnSync(
+            "npx",
+            ["keycloakify", "build", ...rest],
+            {
+                stdio: "inherit"
+            }
+        );
+
+        process.exit(status ?? 1);
+    }
+}

package/src/bin/shared/KeycloakVersionRange.ts

@@ -0,0 +1,9 @@
+export type KeycloakVersionRange =
+    | KeycloakVersionRange.WithAccountTheme
+    | KeycloakVersionRange.WithoutAccountTheme;
+
+export namespace KeycloakVersionRange {
+    export type WithoutAccountTheme = "21-and-below" | "22-and-above";
+
+    export type WithAccountTheme = "21-and-below" | "23" | "24-and-above";
+}

package/src/bin/shared/buildOptions.ts

@@ -0,0 +1,310 @@
+import { parse as urlParse } from "url";
+import { join as pathJoin } from "path";
+import { getAbsoluteAndInOsFormatPath } from "../tools/getAbsoluteAndInOsFormatPath";
+import { getNpmWorkspaceRootDirPath } from "../tools/getNpmWorkspaceRootDirPath";
+import type { CliCommandOptions } from "../main";
+import { z } from "zod";
+import * as fs from "fs";
+import { assert } from "tsafe";
+import * as child_process from "child_process";
+import { vitePluginSubScriptEnvNames } from "./constants";
+
+/** Consolidated build option gathered form CLI arguments and config in package.json */
+export type BuildOptions = {
+    bundler: "vite" | "webpack";
+    themeVersion: string;
+    themeNames: string[];
+    extraThemeProperties: string[] | undefined;
+    groupId: string;
+    artifactId: string;
+    loginThemeResourcesFromKeycloakVersion: string;
+    reactAppRootDirPath: string;
+    // TODO: Remove from vite type
+    reactAppBuildDirPath: string;
+    /** Directory that keycloakify outputs to. Defaults to {cwd}/build_keycloak */
+    keycloakifyBuildDirPath: string;
+    publicDirPath: string;
+    cacheDirPath: string;
+    /** If your app is hosted under a subpath, it's the case in CRA if you have "homepage": "https://example.com/my-app" in your package.json
+     * In this case the urlPathname will be "/my-app/" */
+    urlPathname: string | undefined;
+    assetsDirPath: string;
+    npmWorkspaceRootDirPath: string;
+    kcContextExclusionsFtlCode: string | undefined;
+};
+
+export type UserProvidedBuildOptions = {
+    extraThemeProperties?: string[];
+    artifactId?: string;
+    groupId?: string;
+    loginThemeResourcesFromKeycloakVersion?: string;
+    keycloakifyBuildDirPath?: string;
+    themeName?: string | string[];
+    kcContextExclusionsFtlCode?: string;
+};
+
+export type ResolvedViteConfig = {
+    buildDir: string;
+    publicDir: string;
+    assetsDir: string;
+    urlPathname: string | undefined;
+    userProvidedBuildOptions: UserProvidedBuildOptions;
+};
+
+export function readBuildOptions(params: {
+    cliCommandOptions: CliCommandOptions;
+}): BuildOptions {
+    const { cliCommandOptions } = params;
+
+    const reactAppRootDirPath = (() => {
+        if (cliCommandOptions.reactAppRootDirPath === undefined) {
+            return process.cwd();
+        }
+
+        return getAbsoluteAndInOsFormatPath({
+            pathIsh: cliCommandOptions.reactAppRootDirPath,
+            cwd: process.cwd()
+        });
+    })();
+
+    const { resolvedViteConfig } = (() => {
+        if (
+            fs
+                .readdirSync(reactAppRootDirPath)
+                .find(fileBasename => fileBasename.startsWith("vite.config")) ===
+            undefined
+        ) {
+            return { resolvedViteConfig: undefined };
+        }
+
+        const output = child_process
+            .execSync("npx vite", {
+                cwd: reactAppRootDirPath,
+                env: {
+                    ...process.env,
+                    [vitePluginSubScriptEnvNames.resolveViteConfig]: "true"
+                }
+            })
+            .toString("utf8");
+
+        assert(
+            output.includes(vitePluginSubScriptEnvNames.resolveViteConfig),
+            "Seems like the Keycloakify's Vite plugin is not installed."
+        );
+
+        const resolvedViteConfigStr = output
+            .split(vitePluginSubScriptEnvNames.resolveViteConfig)
+            .reverse()[0];
+
+        const resolvedViteConfig: ResolvedViteConfig = JSON.parse(resolvedViteConfigStr);
+
+        return { resolvedViteConfig };
+    })();
+
+    const parsedPackageJson = (() => {
+        type ParsedPackageJson = {
+            name: string;
+            version?: string;
+            homepage?: string;
+            keycloakify?: UserProvidedBuildOptions & {
+                reactAppBuildDirPath?: string;
+            };
+        };
+
+        const zParsedPackageJson = z.object({
+            name: z.string(),
+            version: z.string().optional(),
+            homepage: z.string().optional(),
+            keycloakify: z
+                .object({
+                    extraThemeProperties: z.array(z.string()).optional(),
+                    artifactId: z.string().optional(),
+                    groupId: z.string().optional(),
+                    loginThemeResourcesFromKeycloakVersion: z.string().optional(),
+                    reactAppBuildDirPath: z.string().optional(),
+                    keycloakifyBuildDirPath: z.string().optional(),
+                    themeName: z.union([z.string(), z.array(z.string())]).optional()
+                })
+                .optional()
+        });
+
+        {
+            type Got = ReturnType<(typeof zParsedPackageJson)["parse"]>;
+            type Expected = ParsedPackageJson;
+            assert<Got extends Expected ? true : false>();
+            assert<Expected extends Got ? true : false>();
+        }
+
+        return zParsedPackageJson.parse(
+            JSON.parse(
+                fs
+                    .readFileSync(pathJoin(reactAppRootDirPath, "package.json"))
+                    .toString("utf8")
+            )
+        );
+    })();
+
+    const userProvidedBuildOptions: UserProvidedBuildOptions = {
+        ...parsedPackageJson.keycloakify,
+        ...resolvedViteConfig?.userProvidedBuildOptions
+    };
+
+    const themeNames = (() => {
+        if (userProvidedBuildOptions.themeName === undefined) {
+            return [
+                parsedPackageJson.name
+                    .replace(/^@(.*)/, "$1")
+                    .split("/")
+                    .join("-")
+            ];
+        }
+
+        if (typeof userProvidedBuildOptions.themeName === "string") {
+            return [userProvidedBuildOptions.themeName];
+        }
+
+        return userProvidedBuildOptions.themeName;
+    })();
+
+    const reactAppBuildDirPath = (() => {
+        webpack: {
+            if (resolvedViteConfig !== undefined) {
+                break webpack;
+            }
+
+            if (parsedPackageJson.keycloakify?.reactAppBuildDirPath !== undefined) {
+                return getAbsoluteAndInOsFormatPath({
+                    pathIsh: parsedPackageJson.keycloakify.reactAppBuildDirPath,
+                    cwd: reactAppRootDirPath
+                });
+            }
+
+            return pathJoin(reactAppRootDirPath, "build");
+        }
+
+        return pathJoin(reactAppRootDirPath, resolvedViteConfig.buildDir);
+    })();
+
+    const { npmWorkspaceRootDirPath } = getNpmWorkspaceRootDirPath({
+        reactAppRootDirPath,
+        dependencyExpected: "keycloakify"
+    });
+
+    return {
+        bundler: resolvedViteConfig !== undefined ? "vite" : "webpack",
+        themeVersion:
+            process.env.KEYCLOAKIFY_THEME_VERSION ?? parsedPackageJson.version ?? "0.0.0",
+        themeNames,
+        extraThemeProperties: userProvidedBuildOptions.extraThemeProperties,
+        groupId: (() => {
+            const fallbackGroupId = `${themeNames[0]}.keycloak`;
+
+            return (
+                process.env.KEYCLOAKIFY_GROUP_ID ??
+                userProvidedBuildOptions.groupId ??
+                (parsedPackageJson.homepage === undefined
+                    ? fallbackGroupId
+                    : urlParse(parsedPackageJson.homepage)
+                          .host?.replace(/:[0-9]+$/, "")
+                          ?.split(".")
+                          .reverse()
+                          .join(".") ?? fallbackGroupId) + ".keycloak"
+            );
+        })(),
+        artifactId:
+            process.env.KEYCLOAKIFY_ARTIFACT_ID ??
+            userProvidedBuildOptions.artifactId ??
+            `${themeNames[0]}-keycloak-theme`,
+        loginThemeResourcesFromKeycloakVersion:
+            userProvidedBuildOptions.loginThemeResourcesFromKeycloakVersion ?? "24.0.4",
+        reactAppRootDirPath,
+        reactAppBuildDirPath,
+        keycloakifyBuildDirPath: (() => {
+            if (userProvidedBuildOptions.keycloakifyBuildDirPath !== undefined) {
+                return getAbsoluteAndInOsFormatPath({
+                    pathIsh: userProvidedBuildOptions.keycloakifyBuildDirPath,
+                    cwd: reactAppRootDirPath
+                });
+            }
+
+            return pathJoin(
+                reactAppRootDirPath,
+                resolvedViteConfig?.buildDir === undefined
+                    ? "build_keycloak"
+                    : `${resolvedViteConfig.buildDir}_keycloak`
+            );
+        })(),
+        publicDirPath: (() => {
+            webpack: {
+                if (resolvedViteConfig !== undefined) {
+                    break webpack;
+                }
+
+                if (process.env.PUBLIC_DIR_PATH !== undefined) {
+                    return getAbsoluteAndInOsFormatPath({
+                        pathIsh: process.env.PUBLIC_DIR_PATH,
+                        cwd: reactAppRootDirPath
+                    });
+                }
+
+                return pathJoin(reactAppRootDirPath, "public");
+            }
+
+            return pathJoin(reactAppRootDirPath, resolvedViteConfig.publicDir);
+        })(),
+        cacheDirPath: (() => {
+            const cacheDirPath = pathJoin(
+                (() => {
+                    if (process.env.XDG_CACHE_HOME !== undefined) {
+                        return getAbsoluteAndInOsFormatPath({
+                            pathIsh: process.env.XDG_CACHE_HOME,
+                            cwd: process.cwd()
+                        });
+                    }
+
+                    return pathJoin(npmWorkspaceRootDirPath, "node_modules", ".cache");
+                })(),
+                "keycloakify"
+            );
+
+            return cacheDirPath;
+        })(),
+        urlPathname: (() => {
+            webpack: {
+                if (resolvedViteConfig !== undefined) {
+                    break webpack;
+                }
+
+                const { homepage } = parsedPackageJson;
+
+                let url: URL | undefined = undefined;
+
+                if (homepage !== undefined) {
+                    url = new URL(homepage);
+                }
+
+                if (url === undefined) {
+                    return undefined;
+                }
+
+                const out = url.pathname.replace(/([^/])$/, "$1/");
+                return out === "/" ? undefined : out;
+            }
+
+            return resolvedViteConfig.urlPathname;
+        })(),
+        assetsDirPath: (() => {
+            webpack: {
+                if (resolvedViteConfig !== undefined) {
+                    break webpack;
+                }
+
+                return pathJoin(reactAppBuildDirPath, "static");
+            }
+
+            return pathJoin(reactAppBuildDirPath, resolvedViteConfig.assetsDir);
+        })(),
+        npmWorkspaceRootDirPath,
+        kcContextExclusionsFtlCode: userProvidedBuildOptions.kcContextExclusionsFtlCode
+    };
+}

package/src/bin/{keycloakify/generateFtl/pageId.ts → shared/constants.ts}

@@ -1,3 +1,23 @@
+export const nameOfTheGlobal = "kcContext";
+export const nameOfTheLocalizationRealmOverridesUserProfileProperty =
+    "__localizationRealmOverridesUserProfile";
+export const keycloak_resources = "keycloak-resources";
+export const resources_common = "resources-common";
+export const lastKeycloakVersionWithAccountV1 = "21.1.2";
+export const basenameOfTheKeycloakifyResourcesDir = "build";
+
+export const themeTypes = ["login", "account"] as const;
+export const accountV1ThemeName = "account-v1";
+
+export type ThemeType = (typeof themeTypes)[number];
+
+export const vitePluginSubScriptEnvNames = {
+    runPostBuildScript: "KEYCLOAKIFY_RUN_POST_BUILD_SCRIPT",
+    resolveViteConfig: "KEYCLOAKIFY_RESOLVE_VITE_CONFIG"
+} as const;
+
+export const skipBuildJarsEnvName = "KEYCLOAKIFY_SKIP_BUILD_JAR";
+
 export const loginThemePageIds = [
     "login.ftl",
     "login-username.ftl",
@@ -35,7 +55,17 @@ export const loginThemePageIds = [
     "webauthn-error.ftl"
 ] as const;
 
-export const accountThemePageIds = ["password.ftl", "account.ftl", "sessions.ftl", "totp.ftl", "applications.ftl", "log.ftl"] as const;
+export const accountThemePageIds = [
+    "password.ftl",
+    "account.ftl",
+    "sessions.ftl",
+    "totp.ftl",
+    "applications.ftl",
+    "log.ftl",
+    "federatedIdentity.ftl"
+] as const;
 
 export type LoginThemePageId = (typeof loginThemePageIds)[number];
 export type AccountThemePageId = (typeof accountThemePageIds)[number];
+
+export const containerName = "keycloak-keycloakify";

package/src/bin/shared/copyKeycloakResourcesToPublic.ts

@@ -0,0 +1,104 @@
+import {
+    downloadKeycloakStaticResources,
+    type BuildOptionsLike as BuildOptionsLike_downloadKeycloakStaticResources
+} from "./downloadKeycloakStaticResources";
+import { join as pathJoin, relative as pathRelative } from "path";
+import {
+    themeTypes,
+    keycloak_resources,
+    lastKeycloakVersionWithAccountV1
+} from "../shared/constants";
+import { readThisNpmPackageVersion } from "../tools/readThisNpmPackageVersion";
+import { assert } from "tsafe/assert";
+import * as fs from "fs";
+import { rmSync } from "../tools/fs.rmSync";
+import type { BuildOptions } from "./buildOptions";
+
+export type BuildOptionsLike = BuildOptionsLike_downloadKeycloakStaticResources & {
+    loginThemeResourcesFromKeycloakVersion: string;
+    publicDirPath: string;
+};
+
+assert<BuildOptions extends BuildOptionsLike ? true : false>();
+
+export async function copyKeycloakResourcesToPublic(params: {
+    buildOptions: BuildOptionsLike;
+}) {
+    const { buildOptions } = params;
+
+    const destDirPath = pathJoin(buildOptions.publicDirPath, keycloak_resources);
+
+    const keycloakifyBuildinfoFilePath = pathJoin(destDirPath, "keycloakify.buildinfo");
+
+    const keycloakifyBuildinfoRaw = JSON.stringify(
+        {
+            destDirPath,
+            keycloakifyVersion: readThisNpmPackageVersion(),
+            buildOptions: {
+                loginThemeResourcesFromKeycloakVersion: readThisNpmPackageVersion(),
+                cacheDirPath: pathRelative(destDirPath, buildOptions.cacheDirPath),
+                npmWorkspaceRootDirPath: pathRelative(
+                    destDirPath,
+                    buildOptions.npmWorkspaceRootDirPath
+                )
+            }
+        },
+        null,
+        2
+    );
+
+    skip_if_already_done: {
+        if (!fs.existsSync(keycloakifyBuildinfoFilePath)) {
+            break skip_if_already_done;
+        }
+
+        const keycloakifyBuildinfoRaw_previousRun = fs
+            .readFileSync(keycloakifyBuildinfoFilePath)
+            .toString("utf8");
+
+        if (keycloakifyBuildinfoRaw_previousRun !== keycloakifyBuildinfoRaw) {
+            break skip_if_already_done;
+        }
+
+        return;
+    }
+
+    rmSync(destDirPath, { force: true, recursive: true });
+
+    fs.mkdirSync(destDirPath, { recursive: true });
+
+    fs.writeFileSync(pathJoin(destDirPath, ".gitignore"), Buffer.from("*", "utf8"));
+
+    for (const themeType of themeTypes) {
+        await downloadKeycloakStaticResources({
+            keycloakVersion: (() => {
+                switch (themeType) {
+                    case "login":
+                        return buildOptions.loginThemeResourcesFromKeycloakVersion;
+                    case "account":
+                        return lastKeycloakVersionWithAccountV1;
+                }
+            })(),
+            themeType,
+            themeDirPath: destDirPath,
+            buildOptions
+        });
+    }
+
+    fs.writeFileSync(
+        pathJoin(destDirPath, "README.txt"),
+        Buffer.from(
+            // prettier-ignore
+            [
+                "This is just a test folder that helps develop",
+                "the login and register page without having to run a Keycloak container\n",
+                "This directory will be automatically excluded from the final build."
+            ].join(" ")
+        )
+    );
+
+    fs.writeFileSync(
+        keycloakifyBuildinfoFilePath,
+        Buffer.from(keycloakifyBuildinfoRaw, "utf8")
+    );
+}