@fernir2/saas-kit-cli 0.1.39 → 0.1.41-1096

package/cli/bin/create.ts

@@ -1,450 +1,635 @@
-import { execSync } from "child_process";
-import { promises as fsPromises, existsSync, mkdirSync, rmSync, Stats } from "fs";
-import { fileURLToPath } from "node:url";
-import * as path from "path";
-import fs from "node:fs";
-import {
-    toolsFoldersToReplace,
-    additionalFoldersToCreate,
-} from "@packages/base-repo/constants/create-app-constants";
-
-import { logStringError, logInfoRaw } from "@packages/fd-toolbox/logging/loggers";
-
-import { WithIndexer } from "@packages/fd-toolbox-core/types/with-indexer";
-
-import { projectName } from "@packages/fd-toolbox/constants/constants";
-
-import { allFilesToCopy } from "@packages/level2/npm-commands/build-npm/path";
-
-import { createError } from "@packages/fd-toolbox/errors/errors";
-
-import {
-    files,
-    folders,
-    projectPaths,
-    nonRootProjectPaths,
-} from "@packages/base-repo/app-constants/project-paths";
-
-import { npmPackages } from "@packages/base-repo/constants/packages";
-
-import { aliasSymbols } from "@packages/base-repo/app-constants/aliases";
-
-import { isString, isWithIndexer } from "@packages/fd-toolbox/types/ensure-type";
-
-import { cliEslintContent, cliScripts } from "@npm-commands/build-npm/cli-contents";
-
-interface PackageJson {
-    name?: string;
-    dependencies?: WithIndexer<string>;
-    devDependencies?: WithIndexer<string>;
-    [key: string]: unknown;
-}
-
-interface FileEntry {
-    name: string;
-    isDirectory(): boolean;
-}
-
-const requiredNodeVersion = "v20.0.0";
-
-if (process.version < requiredNodeVersion) {
-    logStringError(`Node.js ${requiredNodeVersion}+ is required`);
-    process.exit(1);
-}
-
-const filename = fileURLToPath(import.meta.url);
-const sourceDir = "../../../../";
-const binDir = path.dirname(filename);
-const repoRoot = path.resolve(binDir, sourceDir);
-const envLocalPath: string = path.join(binDir, `${sourceDir + folders.cli}/${files.envExample}`);
-const envTemplate: string = fs.readFileSync(envLocalPath, "utf8");
-
-const foldersToIgnore: string[] = [
-    `${folders.cli}/${folders.constants}`,
-    `${folders.cli}/${files.packageTemplate}`,
-    `${folders.cli}/${files.envExample}`,
-    `${folders.cli}/${folders.bin}`,
-    `${folders.cli}/${folders.configs}`,
-];
-
-function runCommand(command: string, cwd?: string) {
-    logInfoRaw(`Executing: ${command}`);
-
-    try {
-        execSync(command, { stdio: "inherit", cwd: cwd ?? process.cwd() });
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logStringError(`Error executing: ${command}`);
-        logStringError(errorMessage);
-        process.exit(1);
-    }
-}
-
-function checkTargetFolder(targetDir: string) {
-    if (existsSync(targetDir)) {
-        logStringError(`Error: Folder "${path.basename(targetDir)}" already exists.`);
-        process.exit(1);
-    }
-}
-
-function getCreateNextAppVersion() {
-    const packageJsonPath: string = path.resolve(repoRoot, files.packageJson);
-    const packageJson: PackageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-
-    return String(packageJson.devDependencies?.["next"] ?? packageJson.dependencies?.["next"] ?? "latest");
-}
-
-async function createNextProject(projectTitle: string, targetDir: string) {
-    logInfoRaw("Creating Next.js project...");
-
-    const createNextAppVersion = getCreateNextAppVersion();
-    const createCommand: string = [
-        `npx --yes create-next-app@${createNextAppVersion} "${projectTitle}"`,
-        "--typescript",
-        "--tailwind",
-        "--eslint",
-        "--app",
-        "--src-dir",
-        "--turbopack",
-        "--no-import-alias",
-        "--no-git",
-        "--react-compiler",
-    ].join(" ");
-
-    runCommand(createCommand, path.dirname(targetDir));
-    logInfoRaw("Next.js project created!");
-
-    const tsConfigPath = path.join(targetDir, "next.config.ts");
-    const publicDir = path.join(targetDir, folders.public);
-
-    await fsPromises.rm(tsConfigPath, { force: true });
-    logInfoRaw("Removed default next.config.ts");
-
-    await fsPromises.rm(publicDir, { recursive: true, force: true });
-    logInfoRaw("Removed default public folder");
-
-    await fsPromises.mkdir(publicDir);
-}
-
-async function createEnvFile(targetDir: string) {
-    logInfoRaw(`Creating ${files.env} file with default values...`);
-
-    const envPath: string = path.join(targetDir, files.env);
-
-    try {
-        await fsPromises.writeFile(envPath, envTemplate, "utf8");
-        logInfoRaw(`${files.env} file created with values!`);
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logStringError(`Error creating ${files.env} file:`);
-        logStringError(errorMessage);
-        throw error;
-    }
-}
-
-async function overridePackageJson(targetDir: string) {
-    const targetPackageJsonPath: string = path.join(targetDir, files.packageJson);
-    // "name" is omitted in package.json; renamed to package-template.json so NX ignores it as a project.
-    const cliPackageJsonPath: string = path.join(repoRoot, `${folders.cli}/${files.packageTemplate}`);
-
-    try {
-        const targetPackageJson: PackageJson = JSON.parse(
-            await fsPromises.readFile(targetPackageJsonPath, "utf8"),
-        );
-        const name = targetPackageJson.name;
-
-        const cliPackageJson: PackageJson = JSON.parse(await fsPromises.readFile(cliPackageJsonPath, "utf8"));
-
-        const finalPackageJson: PackageJson = {
-            ...cliPackageJson,
-            name: name,
-        };
-
-        await fsPromises.writeFile(
-            targetPackageJsonPath,
-            `${JSON.stringify(finalPackageJson, null, 2)}\n`,
-            "utf8",
-        );
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logStringError(`Error overriding ${files.packageJson}:`);
-        logStringError(errorMessage);
-        throw error;
-    }
-}
-
-function replaceImports(content: string) {
-    const importRegex = /(import\s+)([^'"]+)(\s+from\s+["'])([^"']+)(["'])/g;
-
-    return content.replace(importRegex, (match, p1, importItems, p3, importPath, p5) => {
-        if (!importPath.startsWith(aliasSymbols.atSign) || importPath.startsWith(npmPackages.saasKit)) {
-            return match;
-        }
-
-        let newImportPath;
-
-        if (
-            importPath.startsWith(aliasSymbols.atSign + folders.server) ||
-            importPath.includes(`${nonRootProjectPaths.server}`)
-        ) {
-            newImportPath = npmPackages.saasKitServer;
-        } else {
-            newImportPath = npmPackages.saasKit;
-        }
-
-        let newImportItems = importItems.trim();
-
-        const isTypeImport = /^type\b/.test(newImportItems);
-        const isNamespaceImport = /^\*\s+as\s+/.test(newImportItems);
-
-        if (!isTypeImport && !isNamespaceImport && !newImportItems.startsWith("{")) {
-            newImportItems = `{ ${newImportItems} }`;
-        }
-
-        return `${p1}${newImportItems}${p3}${newImportPath}${p5}`;
-    });
-}
-
-async function copyProjectFiles(targetDir: string) {
-    logInfoRaw(`Copying ${projectName} files...`);
-
-    for (const file of allFilesToCopy) {
-        const cliFile = `${folders.cli}/${file}`;
-        const srcPath: string = path.join(repoRoot, cliFile);
-
-        const processedFile = replaceToolsFolder(file);
-
-        const destPath: string = path.join(targetDir, processedFile);
-
-        if (existsSync(srcPath)) {
-            const stats: Stats = await fsPromises.stat(srcPath);
-
-            if (stats.isDirectory()) {
-                await copyDirectoryContents(srcPath, destPath);
-            } else {
-                await copyAndProcessFile(srcPath, destPath);
-            }
-        } else {
-            logInfoRaw(`Source file not found: ${cliFile}`);
-        }
-    }
-
-    logInfoRaw("Files copied and imports updated!");
-}
-
-function replaceToolsFolder(file: string) {
-    let processedFile = file;
-
-    for (const [folderPrefix, replacements] of Object.entries(toolsFoldersToReplace)) {
-        if (processedFile.startsWith(folderPrefix) && isWithIndexer<string>(replacements)) {
-            const typedReplacements: WithIndexer<string> = replacements;
-
-            for (const key in typedReplacements) {
-                const value = typedReplacements[key];
-
-                if (isString(value)) {
-                    processedFile = processedFile.replace(key, value);
-                }
-            }
-
-            break;
-        }
-    }
-
-    return processedFile;
-}
-
-function shouldIgnorePath(filePath: string, basePath: string, isDirectory = false) {
-    const relativeFromRepo = path.relative(repoRoot, filePath).replace(/\\/g, "/");
-    const normalizedFoldersToIgnore = foldersToIgnore.map((p) => p.replace(/\\/g, "/"));
-
-    if (normalizedFoldersToIgnore.includes(relativeFromRepo)) {
-        return true;
-    }
-
-    if (isDirectory) {
-        const relativePath = path.relative(basePath, filePath).replace(/\\/g, "/");
-        const pathParts = relativePath.split("/");
-        return normalizedFoldersToIgnore.some((ignoreFolder) =>
-            pathParts.some((part) => part === ignoreFolder),
-        );
-    }
-
-    return false;
-}
-
-async function copyDirectoryContents(srcDir: string, destDir: string) {
-    if (!existsSync(destDir)) {
-        mkdirSync(destDir, { recursive: true });
-    }
-
-    try {
-        const entries: FileEntry[] = await fsPromises.readdir(srcDir, { withFileTypes: true });
-
-        for (const entry of entries) {
-            const srcPath: string = path.join(srcDir, entry.name);
-            const destPath: string = path.join(destDir, entry.name);
-
-            if (!shouldIgnorePath(srcPath, srcDir, entry.isDirectory())) {
-                if (entry.isDirectory()) {
-                    await copyDirectoryContents(srcPath, destPath);
-                } else {
-                    await copyAndProcessFile(srcPath, destPath);
-                }
-            }
-        }
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logStringError(`Error reading directory ${srcDir}: ${errorMessage}`);
-        throw error;
-    }
-}
-
-async function copyAndProcessFile(srcPath: string, destPath: string) {
-    const destDir: string = path.dirname(destPath);
-
-    if (!existsSync(destDir)) {
-        mkdirSync(destDir, { recursive: true });
-    }
-
-    const stats: Stats = await fsPromises.stat(srcPath);
-
-    if (stats.isDirectory()) {
-        await copyDirectoryContents(srcPath, destPath);
-    } else {
-        const ext = path.extname(srcPath).toLowerCase();
-
-        const binaryExtensions = [".ico", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".pdf"];
-
-        if (binaryExtensions.includes(ext)) {
-            await fsPromises.copyFile(srcPath, destPath);
-            return;
-        }
-
-        const content = await fsPromises.readFile(srcPath, "utf8");
-        const processedContent = replaceImports(content);
-        await fsPromises.writeFile(destPath, processedContent, "utf8");
-    }
-}
-
-function createAdditionalFolders(targetDir: string) {
-    for (const folder of additionalFoldersToCreate) {
-        const folderPath: string = path.join(targetDir, folder);
-
-        if (!existsSync(folderPath)) {
-            mkdirSync(folderPath, { recursive: true });
-            logInfoRaw(`Created folder: ${folder}`);
-        }
-    }
-
-    logInfoRaw("Additional folders created!");
-}
-
-async function setupPreCommitHooks(targetDir: string) {
-    const huskyDir = path.join(targetDir, folders.husky);
-    const preCommitHook = path.join(huskyDir, files.preCommit);
-    const commitMsgHook = path.join(huskyDir, files.commitMsg);
-
-    mkdirSync(huskyDir, { recursive: true });
-
-    await fsPromises.writeFile(preCommitHook, cliScripts.preCommit, "utf8");
-    await fsPromises.writeFile(commitMsgHook, cliScripts.commitMsg, "utf8");
-
-    runCommand(cliScripts.chmodPreCommit, targetDir);
-    runCommand(cliScripts.chmodCommitMsg, targetDir);
-}
-
-async function setupEslintConfig(targetDir: string) {
-    const eslintConfigMjsPath = path.join(targetDir, files.eslintConfigMjs);
-
-    if (existsSync(eslintConfigMjsPath)) {
-        await fsPromises.rm(eslintConfigMjsPath);
-    }
-
-    const eslintConfigJsPath = path.join(targetDir, files.eslintConfigJs);
-    await fsPromises.writeFile(eslintConfigJsPath, cliEslintContent, "utf8");
-}
-
-async function enableRepoModeExtras(targetDir: string) {
-    logInfoRaw("Enabling recommendation mode (-r)...");
-
-    runCommand(cliScripts.gitInit, targetDir);
-
-    runCommand(cliScripts.installDevHuskyTsx, targetDir);
-
-    runCommand(cliScripts.setLint, targetDir);
-
-    runCommand(cliScripts.installHusky, targetDir);
-
-    await setupPreCommitHooks(targetDir);
-}
-
-async function updateLayoutTitle(targetDir: string, folderName: string) {
-    const layoutPath = path.join(targetDir, `${projectPaths.app}/${files.layout}`);
-
-    if (!existsSync(layoutPath)) {
-        throw createError(`${files.layout} not found at ${layoutPath}, cannot update title.`);
-    }
-
-    let content = await fsPromises.readFile(layoutPath, "utf8");
-    const titleRegex = /"SaaS Kit"/g;
-
-    if (!titleRegex.test(content)) {
-        throw createError(`SaaS Kit not found in ${files.layout}, cannot update title.`);
-    }
-
-    content = content.replace(titleRegex, `"${folderName}"`);
-    await fsPromises.writeFile(layoutPath, content, "utf8");
-}
-
-export async function create(args: string[]) {
-    try {
-        if (args.length < 1) {
-            logStringError("Error: Specify folder name. Example: npx create-saas-kit-app <folder-name>");
-            process.exit(1);
-        }
-
-        const folderName: string = args[0];
-        const enableRepoMode = args.includes("-r");
-        const targetDir: string = path.resolve(process.cwd(), folderName);
-
-        logInfoRaw(`\nCreating ${projectName} project "${folderName}"...\n`);
-
-        try {
-            checkTargetFolder(targetDir);
-            await createNextProject(folderName, targetDir);
-            await copyProjectFiles(targetDir);
-            await overridePackageJson(targetDir);
-            createAdditionalFolders(targetDir);
-            await createEnvFile(targetDir);
-            await updateLayoutTitle(targetDir, folderName);
-            await setupEslintConfig(targetDir);
-
-            if (enableRepoMode) {
-                await enableRepoModeExtras(targetDir);
-            }
-
-            logInfoRaw(`\n${projectName} project "${folderName}" is ready!`);
-            logInfoRaw("Next steps:");
-            logInfoRaw(`  cd ${folderName}`);
-            logInfoRaw("  npm run prod");
-            logInfoRaw("  npm start");
-        } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : "Unknown error";
-            logStringError("Error:");
-            logStringError(errorMessage);
-
-            if (existsSync(targetDir)) {
-                logInfoRaw("Cleaning up...");
-                rmSync(targetDir, { recursive: true, force: true });
-            }
-
-            process.exit(1);
-        }
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        logStringError("Unhandled error:");
-        logStringError(errorMessage);
-        process.exit(1);
-    }
-}
+// Approved temp
+// eslint-disable-next-line custom-eslint-rules/must-limit-lines-without-comments
+import { execFileSync, execSync } from "child_process";
+import { promises as fsPromises, existsSync, mkdirSync, rmSync, Stats } from "fs";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import process from "process";
+import * as path from "path";
+import fs from "node:fs";
+import os from "os";
+import { toolsFoldersToReplace, additionalFoldersToCreate } from "@base-repo/constants/create-app-constants";
+
+import { logStringError, logInfoRaw } from "@fd-toolbox/logging/loggers";
+
+import { WithIndexer } from "@fd-toolbox-core/types/with-indexer";
+
+import { allFilesToCopy } from "@npm-commands/build-npm/paths";
+
+import { createError } from "@fd-toolbox/errors/errors";
+
+import {
+    files,
+    folders,
+    projectPaths,
+    nonRootProjectPaths,
+    projectName,
+} from "@base-repo/app-constants/project-paths";
+
+import { npmPackages } from "@base-repo/constants/packages";
+
+import { aliasSymbols } from "@base-repo/app-constants/aliases";
+
+import {
+    fileExtensions,
+    nodeOsPlatforms,
+    sourceDir,
+} from "@base-repo/app-constants/internal-system-constants";
+
+import { ensureString, isString, isWithIndexer } from "@fd-toolbox/types/ensure-type";
+
+import { cliEslintContent, cliScripts } from "@npm-commands/build-npm/cli-contents";
+
+import { ecmaVersion, stdioStatuses } from "@base-repo/constants/internal-cli-constants";
+import { gitCommandArguments, gitCommandParts } from "@git/constants/git-constants";
+
+import { commandNames, externalPackageNames } from "@base-repo/app-constants/command-names";
+
+import { commonStatuses } from "@base-repo/constants/ci-constants";
+import { basicErrorMessages } from "@base-repo/constants/internal-common-strings";
+
+import { first } from "@fd-toolbox/server/collections/single-funcs";
+
+interface PackageJson {
+    name?: string;
+    dependencies?: WithIndexer<string>;
+    devDependencies?: WithIndexer<string>;
+    [key: string]: unknown;
+}
+
+interface FileEntry {
+    name: string;
+    isDirectory(): boolean;
+}
+
+export const lifecycleStatuses = {
+    created: commonStatuses.created,
+} as const;
+
+const requiredNodeVersion = "v20.0.0";
+
+if (process.version < requiredNodeVersion) {
+    logStringError(`Node.js ${requiredNodeVersion}+ is required`);
+    process.exit(1);
+}
+
+const filename = fileURLToPath(import.meta.url);
+const binDir = path.dirname(filename);
+const repoRoot = path.resolve(binDir, sourceDir);
+const envLocalPath: string = path.join(binDir, `${sourceDir + folders.cli}/${files.envExample}`);
+const envTemplate: string = fs.readFileSync(envLocalPath, "utf8");
+
+const cliPackageTemplate = `${folders.cli}/${files.packageTemplate}`;
+const gitIgnoreTemplate = `${folders.cli}/${folders.templates}/gitignore-template`;
+
+const foldersToIgnore: string[] = [
+    nonRootProjectPaths.cliConstants,
+    cliPackageTemplate,
+    `${folders.cli}/${files.envExample}`,
+    `${folders.cli}/${folders.bin}`,
+    nonRootProjectPaths.cliConfigs,
+    `${folders.cli}/${folders.templates}`,
+];
+
+const unknownError = basicErrorMessages.unknownError;
+const playwright = externalPackageNames.playwright;
+const project = "project";
+
+export async function create(args: string[]) {
+    try {
+        if (args.length < 1) {
+            logStringError("Error: Specify folder name. Example: npx create-saas-kit-app <folder-name>");
+            process.exit(1);
+        }
+
+        const folderName = first(args);
+        const enableRepoMode = args.includes(gitCommandArguments.dashR);
+        const installPlaywright = await shouldInstallPlaywright(enableRepoMode);
+        const usePreCommit = await shouldUsePreCommit();
+        const targetDir: string = path.resolve(process.cwd(), folderName);
+
+        logInfoRaw(`\nCreating ${projectName} ${project} "${folderName}"...\n`);
+
+        try {
+            checkTargetFolder(targetDir);
+            await createNextProject(folderName, targetDir);
+            await copyProjectFiles(targetDir);
+            await overridePackageJson(targetDir, installPlaywright);
+
+            if (!installPlaywright) {
+                await removePlaywrightArtifacts(targetDir);
+            }
+
+            runCommandWithArgs("npm", ["install"], targetDir);
+
+            createAdditionalFolders(targetDir);
+            await createEnvFile(targetDir);
+            await updateLayoutTitle(targetDir, folderName);
+            await setupEslintConfig(targetDir);
+
+            if (enableRepoMode) {
+                await enableRepoModeExtras(targetDir, usePreCommit);
+            }
+
+            await normalizeLineEndings(targetDir);
+
+            const initialCommit = "0-initial-commit";
+            runCommandWithArgs(commandNames.git, [gitCommandParts.add, "."], targetDir);
+            runCommandWithArgs(
+                commandNames.git,
+                [gitCommandParts.commit, gitCommandArguments.message, initialCommit],
+                targetDir,
+            );
+            logInfoRaw(`${initialCommit} ${lifecycleStatuses.created}!`);
+
+            logInfoRaw(`\n${projectName} ${project} "${folderName}" is ready!`);
+            logInfoRaw("Next steps:");
+            logInfoRaw(`  cd ${folderName}`);
+            logInfoRaw("  npm run start");
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : unknownError;
+            logStringError("Error:");
+            logStringError(errorMessage);
+
+            if (existsSync(targetDir)) {
+                logInfoRaw("Cleaning up...");
+                rmSync(targetDir, { recursive: true, force: true });
+            }
+
+            process.exit(1);
+        }
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : unknownError;
+        logStringError("Unhandled error:");
+        logStringError(errorMessage);
+        process.exit(1);
+    }
+}
+
+function runCommand(command: string, cwd?: string) {
+    logInfoRaw(`Executing: ${command}`);
+
+    try {
+        execSync(command, { stdio: stdioStatuses.inherit, cwd: cwd ?? process.cwd() });
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : unknownError;
+        logStringError(`Error executing: ${command}`);
+        logStringError(errorMessage);
+        process.exit(1);
+    }
+}
+
+function runCommandWithArgs(command: string, args: string[], cwd?: string) {
+    const commandText = `${command} ${args.join(" ")}`;
+    const workingDirectory = cwd ?? process.cwd();
+
+    logInfoRaw(`Executing: ${commandText}`);
+
+    try {
+        execFileSync(command, args, { stdio: stdioStatuses.inherit, cwd: workingDirectory, shell: true });
+    } catch (error) {
+        logStringError(`Error executing: ${commandText}`);
+        logStringError(error instanceof Error ? error.message : unknownError);
+        process.exit(1);
+    }
+}
+
+function checkTargetFolder(targetDir: string) {
+    if (existsSync(targetDir)) {
+        logStringError(`Error: Folder "${path.basename(targetDir)}" already exists.`);
+        process.exit(1);
+    }
+}
+
+function getCreateNextAppVersion() {
+    const packageJsonPath: string = path.resolve(repoRoot, files.packageJson);
+    const packageJson: PackageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    const nextVersion =
+        packageJson.devDependencies?.[externalPackageNames.next] ??
+        packageJson.dependencies?.[externalPackageNames.next];
+
+    return ensureString(nextVersion ?? ecmaVersion);
+}
+
+async function createNextProject(projectTitle: string, targetDir: string) {
+    logInfoRaw("Creating Next.js project...");
+
+    const createNextAppVersion = getCreateNextAppVersion();
+    const createCommand: string = [
+        `npx --yes create-next-app@${createNextAppVersion} "${projectTitle}"`,
+        "--typescript",
+        "--tailwind",
+        "--eslint",
+        "--app",
+        "--src-dir",
+        "--turbopack",
+        "--no-import-alias",
+        "--no-git",
+        "--react-compiler",
+        "--agents",
+        "--ts",
+        "--agents-md",
+    ].join(" ");
+
+    runCommand(createCommand, path.dirname(targetDir));
+    logInfoRaw(`Next.js ${project} ${lifecycleStatuses.created}!`);
+
+    const tsConfigPath = path.join(targetDir, "next.config.ts");
+    const publicDir = path.join(targetDir, folders.public);
+
+    await fsPromises.rm(tsConfigPath, { force: true });
+    logInfoRaw("Removed default next.config.ts");
+
+    await fsPromises.rm(publicDir, { recursive: true, force: true });
+    logInfoRaw("Removed default public folder");
+
+    await fsPromises.mkdir(publicDir);
+}
+
+async function createEnvFile(targetDir: string) {
+    logInfoRaw(`Creating ${files.dotEnv} file with default values...`);
+
+    const envPath: string = path.join(targetDir, files.dotEnv);
+
+    try {
+        await fsPromises.writeFile(envPath, envTemplate, "utf8");
+        logInfoRaw(`${files.dotEnv} file created with values!`);
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : unknownError;
+        logStringError(`Error creating ${files.dotEnv} file:`);
+        logStringError(errorMessage);
+        throw error;
+    }
+}
+
+async function overridePackageJson(targetDir: string, installPlaywright: boolean) {
+    const targetPackageJsonPath: string = path.join(targetDir, files.packageJson);
+    // "name" is omitted in package.json; renamed to package-template.json so NX ignores it as a project.
+    const cliPackageJsonPath: string = path.join(repoRoot, cliPackageTemplate);
+
+    try {
+        const targetPackageJson: PackageJson = JSON.parse(
+            await fsPromises.readFile(targetPackageJsonPath, "utf8"),
+        );
+        const name = targetPackageJson.name;
+
+        const cliPackageJson: PackageJson = JSON.parse(await fsPromises.readFile(cliPackageJsonPath, "utf8"));
+
+        const finalPackageJson: PackageJson = {
+            ...cliPackageJson,
+            name: name,
+        };
+
+        if (!installPlaywright && finalPackageJson.devDependencies) {
+            delete finalPackageJson.devDependencies[playwright];
+        }
+
+        await fsPromises.writeFile(
+            targetPackageJsonPath,
+            `${JSON.stringify(finalPackageJson, undefined, 2)}\n`,
+            "utf8",
+        );
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : unknownError;
+        logStringError(`Error overriding ${files.packageJson}:`);
+        logStringError(errorMessage);
+        throw error;
+    }
+}
+
+async function shouldInstallPlaywright(enableRepoMode: boolean) {
+    let shouldInstall = false;
+
+    if (enableRepoMode) {
+        shouldInstall = true;
+    } else if (!process.stdin.isTTY) {
+        logInfoRaw("No interactive terminal detected; skipping Playwright setup.");
+    } else {
+        const prompt = createInterface({ input: process.stdin, output: process.stdout });
+
+        try {
+            const answer = await prompt.question("Install Playwright? (y/N): ");
+            shouldInstall = /^y(es)?$/i.test(answer.trim());
+        } finally {
+            prompt.close();
+        }
+    }
+
+    return shouldInstall;
+}
+
+async function shouldUsePreCommit() {
+    let shouldUse = false;
+
+    if (!process.stdin.isTTY) {
+        logInfoRaw("No interactive terminal detected; skipping pre-commit setup.");
+    } else {
+        const prompt = createInterface({ input: process.stdin, output: process.stdout });
+
+        try {
+            const answer = await prompt.question("Set up pre-commit? (y/N): ");
+            shouldUse = /^y(es)?$/i.test(answer.trim());
+        } finally {
+            prompt.close();
+        }
+    }
+
+    return shouldUse;
+}
+
+async function removePlaywrightArtifacts(targetDir: string) {
+    const playwrightConfigPath = path.join(targetDir, files.playwrightConfig);
+    const playwrightConfigCliPath = path.join(targetDir, folders.configs, `${playwright}-cli-config.ts`);
+    const testDir = path.join(targetDir, folders.test);
+
+    await fsPromises.rm(playwrightConfigPath, { force: true });
+    await fsPromises.rm(playwrightConfigCliPath, { force: true });
+    await fsPromises.rm(testDir, { recursive: true, force: true });
+}
+
+function replaceImports(content: string) {
+    const importRegex = /(import\s+)([^'"]+)(\s+from\s+["'])([^"']+)(["'])/g;
+    const pathsToSkip = [
+        "@generated/schema",
+        "@generated/meta/crud-handler-map",
+        "@/app/init-saas-kit",
+        "@/app/http-wrappers",
+    ];
+
+    return content.replace(importRegex, (match, p1, importItems, p3, importPath, p5) => {
+        if (!importPath.startsWith(aliasSymbols.atSign) || importPath.startsWith(npmPackages.saasKit)) {
+            return match;
+        }
+
+        if (pathsToSkip.includes(importPath)) {
+            return match;
+        }
+
+        let newImportPath;
+
+        if (
+            importPath.startsWith(aliasSymbols.atSign + folders.server) ||
+            importPath.includes(nonRootProjectPaths.server)
+        ) {
+            newImportPath = npmPackages.saasKitServer;
+        } else {
+            newImportPath = npmPackages.saasKit;
+        }
+
+        let newImportItems = importItems.trim();
+
+        const isTypeImport = /^type\b/.test(newImportItems);
+        const isNamespaceImport = /^\*\s+as\s+/.test(newImportItems);
+
+        if (!isTypeImport && !isNamespaceImport && !newImportItems.startsWith("{")) {
+            newImportItems = `{ ${newImportItems} }`;
+        }
+
+        return `${p1}${newImportItems}${p3}${newImportPath}${p5}`;
+    });
+}
+
+async function copyProjectFiles(targetDir: string) {
+    logInfoRaw(`Copying ${projectName} files...`);
+
+    for (const file of allFilesToCopy) {
+        const cliFile = file === files.gitIgnore ? gitIgnoreTemplate : `${folders.cli}/${file}`;
+        const srcPath: string = path.join(repoRoot, cliFile);
+
+        const processedFile = replaceToolsFolder(file);
+
+        const destPath: string = path.join(targetDir, processedFile);
+
+        if (existsSync(srcPath)) {
+            const stats: Stats = await fsPromises.stat(srcPath);
+
+            if (stats.isDirectory()) {
+                await copyDirectoryContents(srcPath, destPath);
+            } else {
+                await copyAndProcessFile(srcPath, destPath);
+            }
+        } else {
+            logInfoRaw(`Source file not found: ${cliFile}`);
+        }
+    }
+
+    logInfoRaw("Files copied and imports updated!");
+}
+
+function replaceToolsFolder(file: string) {
+    let processedFile = file;
+
+    for (const [folderPrefix, replacements] of Object.entries(toolsFoldersToReplace)) {
+        if (processedFile.startsWith(folderPrefix) && isWithIndexer<string>(replacements)) {
+            const typedReplacements: WithIndexer<string> = replacements;
+
+            for (const key in typedReplacements) {
+                const value = typedReplacements[key];
+
+                if (isString(value)) {
+                    processedFile = processedFile.replace(key, value);
+                }
+            }
+
+            break;
+        }
+    }
+
+    return processedFile;
+}
+
+function shouldIgnorePath(filePath: string, basePath: string, isDirectory = false) {
+    const relativeFromRepo = path.relative(repoRoot, filePath).replace(/\\/g, "/");
+    const normalizedFoldersToIgnore = foldersToIgnore.map((p) => p.replace(/\\/g, "/"));
+
+    if (normalizedFoldersToIgnore.includes(relativeFromRepo)) {
+        return true;
+    }
+
+    if (isDirectory) {
+        const relativePath = path.relative(basePath, filePath).replace(/\\/g, "/");
+        const pathParts = relativePath.split("/");
+        return normalizedFoldersToIgnore.some((ignoreFolder) =>
+            pathParts.some((part) => part === ignoreFolder),
+        );
+    }
+
+    return false;
+}
+
+async function copyDirectoryContents(srcDir: string, destDir: string) {
+    if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+    }
+
+    try {
+        const entries: FileEntry[] = await fsPromises.readdir(srcDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const srcPath: string = path.join(srcDir, entry.name);
+            const destPath: string = path.join(destDir, entry.name);
+
+            if (!shouldIgnorePath(srcPath, srcDir, entry.isDirectory())) {
+                if (entry.isDirectory()) {
+                    await copyDirectoryContents(srcPath, destPath);
+                } else {
+                    await copyAndProcessFile(srcPath, destPath);
+                }
+            }
+        }
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : unknownError;
+        logStringError(`Error reading directory ${srcDir}: ${errorMessage}`);
+        throw error;
+    }
+}
+
+async function copyAndProcessFile(srcPath: string, destPath: string) {
+    const destDir: string = path.dirname(destPath);
+
+    if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+    }
+
+    const stats: Stats = await fsPromises.stat(srcPath);
+
+    if (stats.isDirectory()) {
+        await copyDirectoryContents(srcPath, destPath);
+    } else {
+        const ext = path.extname(srcPath).toLowerCase();
+
+        const binaryExtensions = [
+            fileExtensions.ico,
+            fileExtensions.png,
+            fileExtensions.jpg,
+            fileExtensions.jpeg,
+            fileExtensions.webp,
+            fileExtensions.gif,
+            fileExtensions.svg,
+            ".pdf",
+        ];
+
+        if (binaryExtensions.includes(ext)) {
+            await fsPromises.copyFile(srcPath, destPath);
+            return;
+        }
+
+        const content = await fsPromises.readFile(srcPath, "utf8");
+        const processedContent = replaceImports(content);
+        await fsPromises.writeFile(destPath, processedContent, "utf8");
+    }
+}
+
+function createAdditionalFolders(targetDir: string) {
+    for (const folder of additionalFoldersToCreate) {
+        const folderPath: string = path.join(targetDir, folder);
+
+        if (!existsSync(folderPath)) {
+            mkdirSync(folderPath, { recursive: true });
+            logInfoRaw(`Created folder: ${folder}`);
+        }
+    }
+
+    logInfoRaw("Additional folders created!");
+}
+
+async function setupPreCommitHooks(targetDir: string) {
+    const huskyDir = path.join(targetDir, folders.husky);
+    const preCommitHook = path.join(huskyDir, files.preCommit);
+    const commitMsgHook = path.join(huskyDir, files.commitMsg);
+
+    mkdirSync(huskyDir, { recursive: true });
+
+    await fsPromises.writeFile(preCommitHook, cliScripts.preCommit, "utf8");
+    await fsPromises.writeFile(commitMsgHook, cliScripts.commitMsg, "utf8");
+
+    runCommand(cliScripts.chmodPreCommit, targetDir);
+    runCommand(cliScripts.chmodCommitMsg, targetDir);
+}
+
+async function setupEslintConfig(targetDir: string) {
+    const eslintConfigMjsPath = path.join(targetDir, files.eslintConfigMjs);
+
+    if (existsSync(eslintConfigMjsPath)) {
+        await fsPromises.rm(eslintConfigMjsPath);
+    }
+
+    const eslintConfigJsPath = path.join(targetDir, files.eslintConfigJs);
+    await fsPromises.writeFile(eslintConfigJsPath, cliEslintContent, "utf8");
+}
+
+async function enableRepoModeExtras(targetDir: string, usePreCommit: boolean) {
+    logInfoRaw(`Enabling recommendation mode (${gitCommandArguments.dashR})...`);
+
+    runCommand(cliScripts.gitInit, targetDir);
+
+    runCommand(cliScripts.installDevHuskyTsx, targetDir);
+
+    runCommand(cliScripts.setLint, targetDir);
+
+    runCommand(cliScripts.installHusky, targetDir);
+
+    if (usePreCommit) {
+        await setupPreCommitHooks(targetDir);
+    }
+}
+
+async function updateLayoutTitle(targetDir: string, folderName: string) {
+    const layoutPath = path.join(targetDir, `${projectPaths.app}/${files.layout}`);
+    const cannotUpdateTitle = "Cannot update title";
+
+    if (!existsSync(layoutPath)) {
+        throw createError(`${files.layout} not found at ${layoutPath}, ${cannotUpdateTitle}.`);
+    }
+
+    let content = await fsPromises.readFile(layoutPath, "utf8");
+    const titleRegex = /title: projectName,/g;
+
+    if (!titleRegex.test(content)) {
+        throw createError(`projectName not found in ${files.layout}, ${cannotUpdateTitle}.`);
+    }
+
+    content = content.replace(titleRegex, `title: "${folderName}",`);
+
+    content = content.replace(/import\s*{\s*projectName\s*}\s*from\s*["'][^"']+["'];?\s*\n?/g, "");
+
+    await fsPromises.writeFile(layoutPath, content, "utf8");
+}
+
+async function normalizeLineEndings(targetDir: string) {
+    if (os.platform() !== nodeOsPlatforms.win32) return;
+
+    const textExtensions = [
+        fileExtensions.ts,
+        fileExtensions.tsx,
+        fileExtensions.js,
+        fileExtensions.json,
+        fileExtensions.css,
+        files.dotEnv,
+        fileExtensions.md,
+        fileExtensions.mjs,
+    ];
+
+    const directoriesToProcess: string[] = [targetDir];
+
+    while (directoriesToProcess.length > 0) {
+        const currentDir = directoriesToProcess.pop()!;
+        const entries = await fsPromises.readdir(currentDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+
+            if (entry.isDirectory()) {
+                directoriesToProcess.push(fullPath);
+            } else {
+                const ext = path.extname(fullPath).toLowerCase();
+
+                if (textExtensions.includes(ext) && existsSync(fullPath)) {
+                    const content = await fsPromises.readFile(fullPath, "utf8");
+                    const crlfContent = content.replace(/\r?\n/g, "\r\n");
+                    await fsPromises.writeFile(fullPath, crlfContent, "utf8");
+                }
+            }
+        }
+    }
+}