keycloakify 11.6.1 → 11.6.2

package/src/bin/main.ts

@@ -248,13 +248,30 @@ program
 
 program
     .command({
-        name: "postinstall",
-        description: "Initialize all the Keycloakify UI modules installed in the project."
+        name: "sync-extensions",
+        description: [
+            "Synchronizes all installed Keycloakify extension modules with your project.",
+            "",
+            "Example of extension modules: '@keycloakify/keycloak-account-ui', '@keycloakify/keycloak-admin-ui', '@keycloakify/keycloak-ui-shared'",
+            "",
+            "This command ensures that:",
+            "- All required files from installed extensions are copied into your project.",
+            "- The copied files are correctly ignored by Git to help you distinguish between your custom source files",
+            "  and those provided by the extensions.",
+            "- Peer dependencies declared by the extensions are automatically added to your package.json.",
+            "",
+            "You can safely run this command multiple times. It will only update the files and dependencies if needed,",
+            "ensuring your project stays in sync with the installed extensions.",
+            "",
+            "Typical usage:",
+            "- Should be run as a postinstall script of your project.",
+            ""
+        ].join("\n")
     })
     .task({
         skip,
         handler: async ({ projectDirPath }) => {
-            const { command } = await import("./postinstall");
+            const { command } = await import("./sync-extensions");
 
             await command({ buildContext: getBuildContext({ projectDirPath }) });
         }
@@ -262,37 +279,65 @@ program
 
 program
     .command<{
-        file: string;
+        path: string;
+        revert: boolean;
     }>({
-        name: "eject-file",
+        name: "own",
         description: [
-            "WARNING: Not usable yet, will be used for future features",
-            "Take ownership over a given file"
-        ].join(" ")
+            "Manages ownership of auto-generated files provided by Keycloakify extensions.",
+            "",
+            "This command allows you to take ownership of a specific file or directory generated",
+            "by an extension. Once owned, you can freely modify and version-control the file.",
+            "",
+            "You can also use the --revert flag to relinquish ownership and restore the file",
+            "or directory to its original auto-generated state.",
+            "",
+            "For convenience, the exact command to take ownership of any file is included as a comment",
+            "in the header of each extension-generated file.",
+            "",
+            "Examples:",
+            "$ npx keycloakify own --path admin/KcPage.tsx"
+        ].join("\n")
     })
     .option({
-        key: "file",
+        key: "path",
         name: (() => {
-            const long = "file";
-            const short = "f";
+            const long = "path";
+            const short = "p";
 
             optionsKeys.push(long, short);
 
             return { long, short };
         })(),
         description: [
-            "Relative path of the file relative to the directory of your keycloak theme source",
-            "Example `--file src/login/page/Login.tsx`"
+            "Specifies the relative path of the file or directory to take ownership of.",
+            "This path should be relative to your theme directory.",
+            "Example: `--path 'admin/KcPage.tsx'`"
         ].join(" ")
     })
+    .option({
+        key: "revert",
+        name: (() => {
+            const name = "revert";
+
+            optionsKeys.push(name);
+
+            return name;
+        })(),
+        description: [
+            "Restores a file or directory to its original auto-generated state,",
+            "removing your ownership claim and reverting any modifications."
+        ].join(" "),
+        defaultValue: false
+    })
     .task({
         skip,
-        handler: async ({ projectDirPath, file }) => {
-            const { command } = await import("./eject-file");
+        handler: async ({ projectDirPath, path, revert }) => {
+            const { command } = await import("./own");
 
             await command({
                 buildContext: getBuildContext({ projectDirPath }),
-                cliCommandOptions: { file }
+                cliCommandOptions: { path, isRevert: revert }
             });
         }
     });

package/src/bin/own.ts

@@ -0,0 +1,209 @@
+import type { BuildContext } from "./shared/buildContext";
+import { getExtensionModuleFileSourceCodeReadyToBeCopied } from "./sync-extensions/getExtensionModuleFileSourceCodeReadyToBeCopied";
+import type { ExtensionModuleMeta } from "./sync-extensions/extensionModuleMeta";
+import { command as command_syncExtensions } from "./sync-extensions/sync-extension";
+import {
+    readManagedGitignoreFile,
+    writeManagedGitignoreFile
+} from "./sync-extensions/managedGitignoreFile";
+import { getExtensionModuleMetas } from "./sync-extensions/extensionModuleMeta";
+import { getAbsoluteAndInOsFormatPath } from "./tools/getAbsoluteAndInOsFormatPath";
+import { relative as pathRelative, dirname as pathDirname, join as pathJoin } from "path";
+import { getInstalledModuleDirPath } from "./tools/getInstalledModuleDirPath";
+import * as fsPr from "fs/promises";
+import { isInside } from "./tools/isInside";
+import chalk from "chalk";
+
+export async function command(params: {
+    buildContext: BuildContext;
+    cliCommandOptions: {
+        path: string;
+        isRevert: boolean;
+    };
+}) {
+    const { buildContext, cliCommandOptions } = params;
+
+    const extensionModuleMetas = await getExtensionModuleMetas({ buildContext });
+
+    const { targetFileRelativePathsByExtensionModuleMeta } = await (async () => {
+        const fileOrDirectoryRelativePath = pathRelative(
+            buildContext.themeSrcDirPath,
+            getAbsoluteAndInOsFormatPath({
+                cwd: buildContext.themeSrcDirPath,
+                pathIsh: cliCommandOptions.path
+            })
+        );
+
+        const arr = extensionModuleMetas
+            .map(extensionModuleMeta => ({
+                extensionModuleMeta,
+                fileRelativePaths: extensionModuleMeta.files
+                    .map(({ fileRelativePath }) => fileRelativePath)
+                    .filter(
+                        fileRelativePath =>
+                            fileRelativePath === fileOrDirectoryRelativePath ||
+                            isInside({
+                                dirPath: fileOrDirectoryRelativePath,
+                                filePath: fileRelativePath
+                            })
+                    )
+            }))
+            .filter(({ fileRelativePaths }) => fileRelativePaths.length !== 0);
+
+        const targetFileRelativePathsByExtensionModuleMeta = new Map<
+            ExtensionModuleMeta,
+            string[]
+        >();
+
+        for (const { extensionModuleMeta, fileRelativePaths } of arr) {
+            targetFileRelativePathsByExtensionModuleMeta.set(
+                extensionModuleMeta,
+                fileRelativePaths
+            );
+        }
+
+        return { targetFileRelativePathsByExtensionModuleMeta };
+    })();
+
+    if (targetFileRelativePathsByExtensionModuleMeta.size === 0) {
+        console.log(
+            chalk.yellow(
+                "There is no Keycloakify extension modules files matching the provided path."
+            )
+        );
+        process.exit(1);
+    }
+
+    const { ownedFilesRelativePaths: ownedFilesRelativePaths_current } =
+        await readManagedGitignoreFile({
+            buildContext
+        });
+
+    await (cliCommandOptions.isRevert ? command_revert : command_own)({
+        extensionModuleMetas,
+        targetFileRelativePathsByExtensionModuleMeta,
+        ownedFilesRelativePaths_current,
+        buildContext
+    });
+}
+
+type Params_subcommands = {
+    extensionModuleMetas: ExtensionModuleMeta[];
+    targetFileRelativePathsByExtensionModuleMeta: Map<ExtensionModuleMeta, string[]>;
+    ownedFilesRelativePaths_current: string[];
+    buildContext: BuildContext;
+};
+
+async function command_own(params: Params_subcommands) {
+    const {
+        extensionModuleMetas,
+        targetFileRelativePathsByExtensionModuleMeta,
+        ownedFilesRelativePaths_current,
+        buildContext
+    } = params;
+
+    await writeManagedGitignoreFile({
+        buildContext,
+        extensionModuleMetas,
+        ownedFilesRelativePaths: [
+            ...ownedFilesRelativePaths_current,
+            ...Array.from(targetFileRelativePathsByExtensionModuleMeta.values())
+                .flat()
+                .filter(
+                    fileRelativePath =>
+                        !ownedFilesRelativePaths_current.includes(fileRelativePath)
+                )
+        ]
+    });
+
+    const writeActions: (() => Promise<void>)[] = [];
+
+    for (const [
+        extensionModuleMeta,
+        fileRelativePaths
+    ] of targetFileRelativePathsByExtensionModuleMeta.entries()) {
+        const extensionModuleDirPath = await getInstalledModuleDirPath({
+            moduleName: extensionModuleMeta.moduleName,
+            packageJsonDirPath: pathDirname(buildContext.packageJsonFilePath),
+            projectDirPath: buildContext.projectDirPath
+        });
+
+        for (const fileRelativePath of fileRelativePaths) {
+            if (ownedFilesRelativePaths_current.includes(fileRelativePath)) {
+                console.log(
+                    chalk.grey(`You already have ownership over '${fileRelativePath}'.`)
+                );
+                continue;
+            }
+
+            writeActions.push(async () => {
+                const sourceCode = await getExtensionModuleFileSourceCodeReadyToBeCopied({
+                    buildContext,
+                    fileRelativePath,
+                    isOwnershipAction: true,
+                    extensionModuleName: extensionModuleMeta.moduleName,
+                    extensionModuleDirPath,
+                    extensionModuleVersion: extensionModuleMeta.version
+                });
+
+                await fsPr.writeFile(
+                    pathJoin(buildContext.themeSrcDirPath, fileRelativePath),
+                    sourceCode
+                );
+
+                console.log(chalk.green(`Ownership over '${fileRelativePath}' claimed.`));
+            });
+        }
+    }
+
+    if (writeActions.length === 0) {
+        console.log(chalk.yellow("No new file claimed."));
+        return;
+    }
+
+    await Promise.all(writeActions.map(action => action()));
+}
+
+async function command_revert(params: Params_subcommands) {
+    const {
+        extensionModuleMetas,
+        targetFileRelativePathsByExtensionModuleMeta,
+        ownedFilesRelativePaths_current,
+        buildContext
+    } = params;
+
+    const ownedFilesRelativePaths_toRemove = Array.from(
+        targetFileRelativePathsByExtensionModuleMeta.values()
+    )
+        .flat()
+        .filter(fileRelativePath => {
+            if (!ownedFilesRelativePaths_current.includes(fileRelativePath)) {
+                console.log(
+                    chalk.grey(`Ownership over '${fileRelativePath}' wasn't claimed.`)
+                );
+                return false;
+            }
+
+            console.log(
+                chalk.green(`Ownership over '${fileRelativePath}' relinquished.`)
+            );
+
+            return true;
+        });
+
+    if (ownedFilesRelativePaths_toRemove.length === 0) {
+        console.log(chalk.yellow("No file relinquished."));
+        return;
+    }
+
+    await writeManagedGitignoreFile({
+        buildContext,
+        extensionModuleMetas,
+        ownedFilesRelativePaths: ownedFilesRelativePaths_current.filter(
+            fileRelativePath =>
+                !ownedFilesRelativePaths_toRemove.includes(fileRelativePath)
+        )
+    });
+
+    await command_syncExtensions({ buildContext });
+}

package/src/bin/shared/{addPostinstallScriptIfNotPresent.ts → addSyncExtensionsToPostinstallScript.ts}

@@ -9,13 +9,13 @@ export type BuildContextLike = {
 
 assert<BuildContext extends BuildContextLike ? true : false>();
 
-export function addPostinstallScriptIfNotPresent(params: {
+export function addSyncExtensionsToPostinstallScript(params: {
     parsedPackageJson: { scripts?: Record<string, string | undefined> };
     buildContext: BuildContextLike;
 }) {
     const { parsedPackageJson, buildContext } = params;
 
-    const cmd_base = "keycloakify postinstall";
+    const cmd_base = "keycloakify sync-extensions";
 
     const projectCliOptionValue = (() => {
         const packageJsonDirPath = pathDirname(buildContext.packageJsonFilePath);

package/src/bin/{postinstall/uiModuleMeta.ts → sync-extensions/extensionModuleMeta.ts}

@@ -10,15 +10,15 @@ import { crawlAsync } from "../tools/crawlAsync";
 import { getIsPrettierAvailable, getPrettier } from "../tools/runPrettier";
 import { readThisNpmPackageVersion } from "../tools/readThisNpmPackageVersion";
 import {
-    getUiModuleFileSourceCodeReadyToBeCopied,
-    type BuildContextLike as BuildContextLike_getUiModuleFileSourceCodeReadyToBeCopied
-} from "./getUiModuleFileSourceCodeReadyToBeCopied";
+    getExtensionModuleFileSourceCodeReadyToBeCopied,
+    type BuildContextLike as BuildContextLike_getExtensionModuleFileSourceCodeReadyToBeCopied
+} from "./getExtensionModuleFileSourceCodeReadyToBeCopied";
 import * as crypto from "crypto";
 import { KEYCLOAK_THEME } from "../shared/constants";
 import { exclude } from "tsafe/exclude";
 import { isAmong } from "tsafe/isAmong";
 
-export type UiModuleMeta = {
+export type ExtensionModuleMeta = {
     moduleName: string;
     version: string;
     files: {
@@ -29,8 +29,8 @@ export type UiModuleMeta = {
     peerDependencies: Record<string, string>;
 };
 
-const zUiModuleMeta = (() => {
-    type ExpectedType = UiModuleMeta;
+const zExtensionModuleMeta = (() => {
+    type ExpectedType = ExtensionModuleMeta;
 
     const zTargetType = z.object({
         moduleName: z.string(),
@@ -56,7 +56,7 @@ type ParsedCacheFile = {
     keycloakifyVersion: string;
     prettierConfigHash: string | null;
     thisFilePath: string;
-    uiModuleMetas: UiModuleMeta[];
+    extensionModuleMetas: ExtensionModuleMeta[];
 };
 
 const zParsedCacheFile = (() => {
@@ -66,7 +66,7 @@ const zParsedCacheFile = (() => {
         keycloakifyVersion: z.string(),
         prettierConfigHash: z.union([z.string(), z.null()]),
         thisFilePath: z.string(),
-        uiModuleMetas: z.array(zUiModuleMeta)
+        extensionModuleMetas: z.array(zExtensionModuleMeta)
     });
 
     type InferredType = z.infer<typeof zTargetType>;
@@ -76,10 +76,10 @@ const zParsedCacheFile = (() => {
     return id<z.ZodType<ExpectedType>>(zTargetType);
 })();
 
-const CACHE_FILE_RELATIVE_PATH = pathJoin("ui-modules", "cache.json");
+const CACHE_FILE_RELATIVE_PATH = pathJoin("extension-modules", "cache.json");
 
 export type BuildContextLike =
-    BuildContextLike_getUiModuleFileSourceCodeReadyToBeCopied & {
+    BuildContextLike_getExtensionModuleFileSourceCodeReadyToBeCopied & {
         cacheDirPath: string;
         packageJsonFilePath: string;
         projectDirPath: string;
@@ -87,9 +87,9 @@ export type BuildContextLike =
 
 assert<BuildContext extends BuildContextLike ? true : false>();
 
-export async function getUiModuleMetas(params: {
+export async function getExtensionModuleMetas(params: {
     buildContext: BuildContextLike;
-}): Promise<UiModuleMeta[]> {
+}): Promise<ExtensionModuleMeta[]> {
     const { buildContext } = params;
 
     const cacheFilePath = pathJoin(buildContext.cacheDirPath, CACHE_FILE_RELATIVE_PATH);
@@ -106,7 +106,7 @@ export async function getUiModuleMetas(params: {
         return configHash;
     })();
 
-    const installedUiModules = await (async () => {
+    const installedExtensionModules = await (async () => {
         const installedModulesWithKeycloakifyInTheName = await listInstalledModules({
             packageJsonFilePath: buildContext.packageJsonFilePath,
             projectDirPath: buildContext.packageJsonFilePath,
@@ -134,7 +134,7 @@ export async function getUiModuleMetas(params: {
         return await fsPr.readFile(cacheFilePath);
     })();
 
-    const uiModuleMetas_cacheUpToDate: UiModuleMeta[] = await (async () => {
+    const extensionModuleMetas_cacheUpToDate: ExtensionModuleMeta[] = await (async () => {
         const parsedCacheFile: ParsedCacheFile | undefined = await (async () => {
             if (cacheContent === undefined) {
                 return undefined;
@@ -177,45 +177,51 @@ export async function getUiModuleMetas(params: {
             return [];
         }
 
-        const uiModuleMetas_cacheUpToDate = parsedCacheFile.uiModuleMetas.filter(
-            uiModuleMeta => {
-                const correspondingInstalledUiModule = installedUiModules.find(
-                    installedUiModule =>
-                        installedUiModule.moduleName === uiModuleMeta.moduleName
-                );
+        const extensionModuleMetas_cacheUpToDate =
+            parsedCacheFile.extensionModuleMetas.filter(extensionModuleMeta => {
+                const correspondingInstalledExtensionModule =
+                    installedExtensionModules.find(
+                        installedExtensionModule =>
+                            installedExtensionModule.moduleName ===
+                            extensionModuleMeta.moduleName
+                    );
 
-                if (correspondingInstalledUiModule === undefined) {
+                if (correspondingInstalledExtensionModule === undefined) {
                     return false;
                 }
 
-                return correspondingInstalledUiModule.version === uiModuleMeta.version;
-            }
-        );
+                return (
+                    correspondingInstalledExtensionModule.version ===
+                    extensionModuleMeta.version
+                );
+            });
 
-        return uiModuleMetas_cacheUpToDate;
+        return extensionModuleMetas_cacheUpToDate;
     })();
 
-    const uiModuleMetas = await Promise.all(
-        installedUiModules.map(
+    const extensionModuleMetas = await Promise.all(
+        installedExtensionModules.map(
             async ({
                 moduleName,
                 version,
                 peerDependencies,
                 dirPath
-            }): Promise<UiModuleMeta> => {
+            }): Promise<ExtensionModuleMeta> => {
                 use_cache: {
-                    const uiModuleMeta_cache = uiModuleMetas_cacheUpToDate.find(
-                        uiModuleMeta => uiModuleMeta.moduleName === moduleName
-                    );
+                    const extensionModuleMeta_cache =
+                        extensionModuleMetas_cacheUpToDate.find(
+                            extensionModuleMeta =>
+                                extensionModuleMeta.moduleName === moduleName
+                        );
 
-                    if (uiModuleMeta_cache === undefined) {
+                    if (extensionModuleMeta_cache === undefined) {
                         break use_cache;
                     }
 
-                    return uiModuleMeta_cache;
+                    return extensionModuleMeta_cache;
                 }
 
-                const files: UiModuleMeta["files"] = [];
+                const files: ExtensionModuleMeta["files"] = [];
 
                 {
                     const srcDirPath = pathJoin(dirPath, KEYCLOAK_THEME);
@@ -225,13 +231,13 @@ export async function getUiModuleMetas(params: {
                         returnedPathsType: "relative to dirPath",
                         onFileFound: async fileRelativePath => {
                             const sourceCode =
-                                await getUiModuleFileSourceCodeReadyToBeCopied({
+                                await getExtensionModuleFileSourceCodeReadyToBeCopied({
                                     buildContext,
                                     fileRelativePath,
-                                    isForEjection: false,
-                                    uiModuleDirPath: dirPath,
-                                    uiModuleName: moduleName,
-                                    uiModuleVersion: version
+                                    isOwnershipAction: false,
+                                    extensionModuleDirPath: dirPath,
+                                    extensionModuleName: moduleName,
+                                    extensionModuleVersion: version
                                 });
 
                             const hash = computeHash(sourceCode);
@@ -261,7 +267,7 @@ export async function getUiModuleMetas(params: {
                     });
                 }
 
-                return id<UiModuleMeta>({
+                return id<ExtensionModuleMeta>({
                     moduleName,
                     version,
                     files,
@@ -281,7 +287,7 @@ export async function getUiModuleMetas(params: {
             keycloakifyVersion,
             prettierConfigHash,
             thisFilePath: cacheFilePath,
-            uiModuleMetas
+            extensionModuleMetas
         });
 
         const cacheContent_new = Buffer.from(
@@ -306,7 +312,7 @@ export async function getUiModuleMetas(params: {
         await fsPr.writeFile(cacheFilePath, cacheContent_new);
     }
 
-    return uiModuleMetas;
+    return extensionModuleMetas;
 }
 
 export function computeHash(data: Buffer) {

package/src/bin/{postinstall/getUiModuleFileSourceCodeReadyToBeCopied.ts → sync-extensions/getExtensionModuleFileSourceCodeReadyToBeCopied.ts}

@@ -11,40 +11,51 @@ export type BuildContextLike = {
 
 assert<BuildContext extends BuildContextLike ? true : false>();
 
-export async function getUiModuleFileSourceCodeReadyToBeCopied(params: {
+export async function getExtensionModuleFileSourceCodeReadyToBeCopied(params: {
     buildContext: BuildContextLike;
     fileRelativePath: string;
-    isForEjection: boolean;
-    uiModuleDirPath: string;
-    uiModuleName: string;
-    uiModuleVersion: string;
+    isOwnershipAction: boolean;
+    extensionModuleDirPath: string;
+    extensionModuleName: string;
+    extensionModuleVersion: string;
 }): Promise<Buffer> {
     const {
         buildContext,
-        uiModuleDirPath,
+        extensionModuleDirPath,
         fileRelativePath,
-        isForEjection,
-        uiModuleName,
-        uiModuleVersion
+        isOwnershipAction,
+        extensionModuleName,
+        extensionModuleVersion
     } = params;
 
     let sourceCode = (
-        await fsPr.readFile(pathJoin(uiModuleDirPath, KEYCLOAK_THEME, fileRelativePath))
+        await fsPr.readFile(
+            pathJoin(extensionModuleDirPath, KEYCLOAK_THEME, fileRelativePath)
+        )
     ).toString("utf8");
 
     sourceCode = addCommentToSourceCode({
         sourceCode,
         fileRelativePath,
-        commentLines: isForEjection
-            ? [`This file was ejected from ${uiModuleName} version ${uiModuleVersion}.`]
-            : [
-                  `WARNING: Before modifying this file run the following command:`,
-                  ``,
-                  `$ npx keycloakify eject-file --file '${fileRelativePath.split(pathSep).join("/")}'`,
-                  ``,
-                  `This file comes from ${uiModuleName} version ${uiModuleVersion}.`,
-                  `This file has been copied over to your repo by your postinstall script: \`npx keycloakify postinstall\``
-              ]
+        commentLines: (() => {
+            const path = fileRelativePath.split(pathSep).join("/");
+
+            return isOwnershipAction
+                ? [
+                      `This file has been claimed for ownership from ${extensionModuleName} version ${extensionModuleVersion}.`,
+                      `To relinquish ownership and restore this file to its original content, run the following command:`,
+                      ``,
+                      `$ npx keycloakify own --path '${path}' --revert`
+                  ]
+                : [
+                      `WARNING: Before modifying this file, run the following command:`,
+                      ``,
+                      `$ npx keycloakify own --path '${path}'`,
+                      ``,
+                      `This file is provided by ${extensionModuleName} version ${extensionModuleVersion}.`,
+                      `It was copied into your repository by the postinstall script: \`keycloakify sync-extensions\`.`
+                  ];
+        })()
     });
 
     const destFilePath = pathJoin(buildContext.themeSrcDirPath, fileRelativePath);
@@ -93,7 +104,7 @@ function addCommentToSourceCode(params: {
             `<!--`,
             ...commentLines.map(
                 line =>
-                    ` ${line.replace("--file", "-f").replace("Before modifying", "Before modifying or replacing")}`
+                    ` ${line.replace("--path", "-p").replace("Before modifying", "Before modifying or replacing")}`
             ),
             `-->`
         ].join("\n");

package/src/bin/sync-extensions/index.ts

@@ -0,0 +1 @@
+export * from "./sync-extension";