create-template-project 0.4.0 → 0.5.0

package/dist/index.js

@@ -3,12 +3,12 @@ import { Command } from "commander";
 import * as p from "@clack/prompts";
 import { cancel, intro, outro } from "@clack/prompts";
 import { z } from "zod";
+import { execa } from "execa";
 import path from "node:path";
 import fs from "node:fs/promises";
 import debugLib from "debug";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
-import { execa } from "execa";
 //#region src/types.ts
 var TemplateTypeSchema = z.enum([
 	"cli",
@@ -24,15 +24,16 @@ var PackageManagerSchema = z.enum([
 var ProjectOptionsSchema = z.object({
 	template: TemplateTypeSchema,
 	projectName: z.string().min(1, "Project name is required"),
+	description: z.string().optional(),
+	keywords: z.string().optional(),
+	author: z.string().min(1, "Author name is required"),
+	githubUsername: z.string().min(1, "GitHub username is required"),
 	packageManager: PackageManagerSchema.optional().default("npm"),
 	createGithubRepository: z.boolean().optional().default(false),
 	directory: z.string(),
-	overwrite: z.boolean().optional().default(false),
 	update: z.boolean().optional().default(false),
 	installDependencies: z.boolean().optional().default(false),
 	build: z.boolean().optional().default(false),
-	dev: z.boolean().optional().default(false),
-	open: z.boolean().optional().default(false),
 	progress: z.boolean().optional().default(true)
 });
 //#endregion
@@ -53,9 +54,9 @@ async function getAllFiles(dirPath, arrayOfFiles = []) {
 	return arrayOfFiles;
 }
 function processContent(filePath, content, opts, addedDeps) {
-	const { projectName, template } = opts;
-	let description = "";
-	switch (template) {
+	const { projectName, template, author, githubUsername } = opts;
+	let description = opts.description || "";
+	if (!description) switch (template) {
 		case "cli":
 			description = "A modern Node.js CLI application with TypeScript and automated tooling.";
 			break;
@@ -70,7 +71,8 @@ function processContent(filePath, content, opts, addedDeps) {
 			break;
 	}
 	const pm = opts.packageManager || "npm";
-	let processed = content.replaceAll("{{projectName}}", projectName).replaceAll("{{description}}", description).replaceAll("{{packageManager}}", pm);
+	const lockfileRules = pm === "pnpm" ? "package-lock.json\nyarn.lock" : pm === "yarn" ? "package-lock.json\npnpm-lock.yaml" : "yarn.lock\npnpm-lock.yaml";
+	let processed = content.replaceAll("{{projectName}}", projectName).replaceAll("{{description}}", description).replaceAll("{{packageManager}}", pm).replaceAll("{{author}}", author || "").replaceAll("{{githubUsername}}", githubUsername || "").replaceAll("{{year}}", (/* @__PURE__ */ new Date()).getFullYear().toString()).replaceAll("{{lockfileRules}}", lockfileRules);
 	if (filePath.includes(".github/workflows/node.js.yml")) {
 		let installCommand = "npm ci";
 		let pmSetup = "";
@@ -121,8 +123,9 @@ function isSeedFile(filePath) {
 		"index.html",
 		"App.tsx",
 		"main.tsx",
-		"index.tsx"
-	].some((file) => filePath === file);
+		"index.tsx",
+		"LICENSE"
+	].some((file) => filePath === file) || filePath.toLowerCase().endsWith(".md");
 }
 async function mergeFile(filePath, existing, template, log) {
 	debug$3("Merging file: %s", filePath);
@@ -145,7 +148,7 @@ async function mergeFile(filePath, existing, template, log) {
 			});
 			return (await fs.readFile(filePath, "utf8")).trim() !== template.trim() ? "merged" : "updated";
 		} catch (e) {
-			if (e.exitCode === 1) return "conflict";
+			if (e.exitCode >= 1 && e.exitCode < 128) return "conflict";
 			else {
 				debug$3("Git merge-file failed: %O", e);
 				const detail = e.stdout || e.stderr ? `\n\nOutput:\n${e.stdout}\n${e.stderr}` : "";
@@ -175,8 +178,8 @@ var getBaseTemplate = (_opts) => {
 				description: "Ultra-fast Rust-based linter."
 			},
 			{
-				name: "Prettier",
-				description: "Consistent code formatting."
+				name: "oxfmt",
+				description: "High performance code formatting."
 			},
 			{
 				name: "Vitest",
@@ -428,14 +431,13 @@ var getWebFullstackTemplate = (_opts) => {
 var MOCK_OPTS = {
 	template: "cli",
 	projectName: "mock",
+	author: "mock",
+	githubUsername: "mock",
 	directory: ".",
 	packageManager: "npm",
-	overwrite: false,
 	update: false,
 	installDependencies: false,
 	build: false,
-	dev: false,
-	open: false,
 	progress: true,
 	createGithubRepository: false
 };
@@ -477,6 +479,22 @@ var getAllTemplatesInfo = () => {
 //#endregion
 //#region src/cli.ts
 var pathExists$1 = (p) => fs.access(p).then(() => true).catch(() => false);
+var getDefaultAuthor = async () => {
+	try {
+		const { stdout } = await execa("git", ["config", "user.name"]);
+		return stdout.trim();
+	} catch (e) {
+		return "";
+	}
+};
+var getDefaultGithubUsername = async () => {
+	try {
+		const { stdout } = await execa("git", ["config", "github.user"]);
+		return stdout.trim();
+	} catch (e) {
+		return "";
+	}
+};
 var debug$2 = debugLib("create-template-project:cli");
 var parseArgs = async () => {
 	debug$2("Parsing CLI arguments: %O", process.argv);
@@ -530,17 +548,20 @@ Templates:
 		p.outro("Use \"create\" to scaffold a new project.");
 		process.exit(0);
 	});
-	program.command("create").description("Create a new project from a template").option("-t, --template <type>", "Template type (cli, web-vanilla, web-app, web-fullstack)").option("-n, --name <name>", "Project name").option("-p, --package-manager <pm>", "Package manager (npm, pnpm, yarn)", "npm").option("--create-github-repository", "Create GitHub project").option("-d, --directory <path>", "Output directory", ".").option("--overwrite", "Overwrite existing directory by removing it first", false).option("--install-dependencies", "Install dependencies after scaffolding", false).option("--build", "Run the CI script (lint, build, test) after scaffolding", false).option("--dev", "Run the dev server after scaffolding", false).option("--open", "Open the browser after scaffolding", false).option("--no-progress", "Do not show progress indicators").action((opts) => {
+	program.command("create").description("Create a new project from a template").option("-t, --template <type>", "Template type (cli, web-vanilla, web-app, web-fullstack)").option("-n, --name <name>", "Project name").option("--description <description>", "Project description").option("-k, --keywords <keywords>", "Project keywords (comma separated)").option("-a, --author <author>", "Author name (defaults to 'git config user.name')").option("--github-username <username>", "GitHub username (defaults to 'git config github.user')").option("-p, --package-manager <pm>", "Package manager (npm, pnpm, yarn)", "pnpm").option("--create-github-repository", "Create GitHub project").requiredOption("--path <path>", "Output directory").option("--install-dependencies", "Install dependencies after scaffolding", false).option("--build", "Run the CI script (lint, build, test) after scaffolding", false).option("--no-progress", "Do not show progress indicators").action(async (opts) => {
 		debug$2("Executing \"create\" command with options: %O", opts);
 		commandResult = {
 			...opts,
 			update: false,
 			template: opts.template,
 			projectName: opts.name,
+			description: opts.description,
+			keywords: opts.keywords,
+			author: opts.author || await getDefaultAuthor(),
+			githubUsername: opts.githubUsername || await getDefaultGithubUsername(),
 			packageManager: opts.packageManager,
-			directory: path.resolve(opts.directory),
+			directory: path.resolve(opts.path),
 			createGithubRepository: !!opts.createGithubRepository,
-			overwrite: !!opts.overwrite,
 			progress: !!opts.progress
 		};
 		debug$2("Processed \"create\" options: %O", commandResult);
@@ -551,21 +572,45 @@ Details:
   It intelligently merges changes into your existing files using 'git merge-file'.
 
 Restrictions & Behavior:
-  - Seed Files: Files in 'src/', 'client/src/', etc., are considered "seed" files and are NEVER overwritten or modified during an update to protect your application logic.
+  - Seed Files: Files in 'src/', 'client/src/', etc., and ALL markdown files (*.md) are considered "seed" files and are NEVER overwritten or modified during an update to protect your application logic and documentation.
   - package.json: Dependencies and scripts are merged. Existing versions are preserved unless they are missing.
   - Merging: For non-seed files, the tool attempts to merge template changes. If a conflict occurs, it will be marked with standard git conflict markers.
   - Confirmation: The command will always show a summary of proposed changes (ADD, MODIFY) and ask for your confirmation before applying them.
-`).option("-t, --template <type>", "Template type (cli, web-vanilla, web-app, web-fullstack)").option("-n, --name <name>", "Project name").option("-p, --package-manager <pm>", "Package manager (npm, pnpm, yarn)", "npm").option("--create-github-repository", "Create GitHub project").option("-d, --directory <path>", "Output directory", ".").option("--overwrite", "Overwrite existing directory by removing it first", false).option("--install-dependencies", "Install dependencies after scaffolding", false).option("--build", "Run the CI script (lint, build, test) after updating", false).option("--dev", "Run the dev server after scaffolding", false).option("--open", "Open the browser after scaffolding", false).option("--no-progress", "Do not show progress indicators").action((opts) => {
+`).option("-t, --template <type>", "Template type (cli, web-vanilla, web-app, web-fullstack)").option("--description <description>", "Project description").option("-k, --keywords <keywords>", "Project keywords (comma separated)").option("-a, --author <author>", "Author name (defaults to 'git config user.name')").option("--github-username <username>", "GitHub username (defaults to 'git config github.user')").option("-p, --package-manager <pm>", "Package manager (npm, pnpm, yarn)", "pnpm").option("--create-github-repository", "Create GitHub project").option("-d, --directory <path>", "Output directory", ".").option("--install-dependencies", "Install dependencies after scaffolding", false).option("--build", "Run the CI script (lint, build, test) after updating", false).option("--dev", "Run the dev server after scaffolding", false).option("--open", "Open the browser after scaffolding", false).option("--no-progress", "Do not show progress indicators").action(async (opts) => {
 		debug$2("Executing \"update\" command with options: %O", opts);
+		const directory = path.resolve(opts.directory);
+		const pkgPath = path.join(directory, "package.json");
+		if (!await pathExists$1(pkgPath)) {
+			p.log.error(`No package.json found in ${directory}. The update command must be run in a project directory.`);
+			process.exit(1);
+		}
+		let pkg;
+		try {
+			pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+		} catch (e) {
+			p.log.error(`Failed to read or parse package.json at ${pkgPath}: ${e.message}`);
+			process.exit(1);
+		}
+		if (!pkg.name) {
+			p.log.error(`No name property found in ${pkgPath}.`);
+			process.exit(1);
+		}
+		if (!pkg["create-template-project"]?.template) {
+			p.log.error(`No "create-template-project" configuration found in ${pkgPath}. The update command can only be used on projects created with this tool.`);
+			process.exit(1);
+		}
 		commandResult = {
 			...opts,
 			update: true,
-			template: opts.template,
-			projectName: opts.name,
+			template: opts.template || pkg["create-template-project"]?.template,
+			projectName: pkg.name,
+			description: opts.description || pkg.description,
+			keywords: opts.keywords || (pkg.keywords ? pkg.keywords.join(", ") : void 0),
+			author: opts.author || pkg.author || await getDefaultAuthor(),
+			githubUsername: opts.githubUsername || pkg["create-template-project"]?.githubUsername || await getDefaultGithubUsername(),
 			packageManager: opts.packageManager,
-			directory: path.resolve(opts.directory),
+			directory,
 			createGithubRepository: !!opts.createGithubRepository,
-			overwrite: !!opts.overwrite,
 			progress: !!opts.progress
 		};
 		debug$2("Processed \"update\" options: %O", commandResult);
@@ -595,38 +640,84 @@ Restrictions & Behavior:
 		const pkgPath = path.join(projectDir, "package.json");
 		const pkgExists = await pathExists$1(pkgPath);
 		let existingConfig = {};
+		let existingAuthor = "";
+		let existingGithubUsername = "";
+		let existingDescription = "";
+		let existingKeywords = [];
 		if (pkgExists) try {
-			existingConfig = JSON.parse(await fs.readFile(pkgPath, "utf8"))["create-template-project"] || {};
+			const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+			existingConfig = pkg["create-template-project"] || {};
+			existingAuthor = pkg.author;
+			existingGithubUsername = existingConfig.githubUsername;
+			existingDescription = pkg.description;
+			existingKeywords = pkg.keywords || [];
 			debug$2("Found existing project config: %O", existingConfig);
 		} catch (e) {
 			debug$2("Failed to read existing package.json: %O", e);
 		}
+		const projectDescription = await p.text({
+			message: "Project description:",
+			placeholder: "A new project",
+			defaultValue: existingDescription || ""
+		});
+		if (p.isCancel(projectDescription)) {
+			p.cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		const projectKeywords = await p.text({
+			message: "Project keywords (comma separated):",
+			placeholder: "cli, nodejs, typescript",
+			defaultValue: existingKeywords ? existingKeywords.join(", ") : ""
+		});
+		if (p.isCancel(projectKeywords)) {
+			p.cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		const defaultAuthor = await getDefaultAuthor();
+		const author = await p.text({
+			message: "Author name:",
+			placeholder: "Your Name",
+			defaultValue: existingAuthor || existingConfig.author || defaultAuthor,
+			validate: (value) => value && value.length > 0 ? void 0 : "Author name is required"
+		});
+		if (p.isCancel(author)) {
+			p.cancel("Operation cancelled.");
+			process.exit(0);
+		}
+		const defaultGithubUsername = await getDefaultGithubUsername();
+		const githubUsername = await p.text({
+			message: "GitHub username:",
+			placeholder: "your-github-username",
+			defaultValue: existingGithubUsername || defaultGithubUsername,
+			validate: (value) => value && value.length > 0 ? void 0 : "GitHub username is required"
+		});
+		if (p.isCancel(githubUsername)) {
+			p.cancel("Operation cancelled.");
+			process.exit(0);
+		}
 		let update = false;
-		let overwrite = false;
 		if (exists) {
 			const action = await p.select({
 				message: `Directory "${projectDir}" already exists. What would you like to do?`,
-				options: [
-					{
-						label: "Run an update",
-						value: "update"
-					},
-					{
-						label: "Overwrite existing directory by removing it first",
-						value: "overwrite"
-					},
-					{
-						label: "Cancel",
-						value: "cancel"
-					}
-				]
+				options: [{
+					label: "Run an update",
+					value: "update"
+				}, {
+					label: "Cancel",
+					value: "cancel"
+				}]
 			});
 			if (p.isCancel(action) || action === "cancel") {
 				p.cancel("Operation cancelled.");
 				process.exit(0);
 			}
-			if (action === "update") update = true;
-			else if (action === "overwrite") overwrite = true;
+			if (action === "update") {
+				if (!existingConfig.template) {
+					p.log.error(`No "create-template-project" configuration found in ${pkgPath}. The update command can only be used on projects created with this tool.`);
+					process.exit(1);
+				}
+				update = true;
+			}
 		}
 		let template = existingConfig.template;
 		if (!update || !template) {
@@ -657,11 +748,11 @@ Restrictions & Behavior:
 				process.exit(0);
 			}
 		} else p.log.info(`Using existing template type: ${template}`);
-		let packageManager = "npm";
+		let packageManager = "pnpm";
 		if (!update) {
 			packageManager = await p.select({
 				message: "Select package manager:",
-				initialValue: "npm",
+				initialValue: "pnpm",
 				options: [
 					{
 						label: "npm",
@@ -714,15 +805,16 @@ Restrictions & Behavior:
 		commandResult = {
 			template,
 			projectName,
+			description: projectDescription,
+			keywords: projectKeywords,
+			author,
+			githubUsername,
 			packageManager,
 			createGithubRepository: createGithubRepositoryRes,
-			directory: path.resolve(directory),
+			directory: projectDir,
 			update,
-			overwrite,
 			installDependencies,
 			build,
-			dev: false,
-			open: false,
 			progress: true
 		};
 	});
@@ -751,16 +843,12 @@ Restrictions & Behavior:
 		process.exit(1);
 	}
 	commandResult = validationResult.data;
-	const projectDir = path.resolve(commandResult.directory, commandResult.projectName);
-	if (await pathExists$1(projectDir) && !commandResult.update && !commandResult.overwrite) {
-		p.cancel(`Directory "${projectDir}" already exists. Use --overwrite to overwrite or "update" command.`);
+	const projectDir = commandResult.directory;
+	if (await pathExists$1(projectDir) && !commandResult.update) {
+		p.cancel(`Directory "${projectDir}" already exists. Use the "update" command to update.`);
 		process.exit(1);
 	}
-	if (commandResult.open) {
-		commandResult.dev = true;
-		commandResult.installDependencies = true;
-	}
-	if (commandResult.dev || commandResult.build) commandResult.installDependencies = true;
+	if (commandResult.build) commandResult.installDependencies = true;
 	return commandResult;
 };
 //#endregion
@@ -786,11 +874,6 @@ var getSpinner = (progress) => {
 		stop: (msg) => progress ? s.stop(msg) : void 0
 	};
 };
-var showNote = (msg, title, progress) => {
-	if (progress !== void 0 && !progress) return;
-	if (title) p.log.success(title);
-	p.note(msg);
-};
 var isFileRequired = (relativePath, type) => {
 	if (relativePath === "vitest.config.ts") return ![
 		"cli",
@@ -801,23 +884,17 @@ var isFileRequired = (relativePath, type) => {
 	return true;
 };
 var generateProject = async (opts) => {
-	const { template: type, projectName, directory, update, overwrite, progress } = opts;
+	const { template: type, projectName, author, githubUsername, directory, update, progress } = opts;
 	const isProgress = progress !== false;
 	const log = getLog(isProgress);
 	const spinner = () => getSpinner(isProgress);
-	const projectDir = path.join(directory, projectName);
+	const projectDir = directory;
 	debug$1("Project generation started for: %s", projectName);
 	debug$1("Options: %O", opts);
 	debug$1("Project directory: %s", projectDir);
 	let isUpdate = !!update;
 	if (await pathExists(projectDir)) {
-		if (overwrite) {
-			await fs.rm(projectDir, {
-				recursive: true,
-				force: true
-			});
-			isUpdate = false;
-		} else if (!isUpdate) throw new Error(`Directory "${projectDir}" already exists. Use --overwrite to replace it or --update to update.`);
+		if (!isUpdate) throw new Error(`Directory "${projectDir}" already exists. Use the "update" command to update.`);
 	}
 	const templates = [getBaseTemplate(opts)];
 	debug$1("Applying template: base");
@@ -863,6 +940,16 @@ var generateProject = async (opts) => {
 	let finalPkg = {
 		name: projectName,
 		version: "0.1.0",
+		description: opts.description || "TODO: Add project description",
+		keywords: opts.keywords ? opts.keywords.split(",").map((k) => k.trim()) : ["TODO: Add keywords"],
+		homepage: `https://github.com/${githubUsername}/${projectName}#readme`,
+		bugs: { url: `https://github.com/${githubUsername}/${projectName}/issues` },
+		license: "MIT",
+		author: author || "",
+		repository: {
+			type: "git",
+			url: `https://github.com/${githubUsername}/${projectName}.git`
+		},
 		type: "module",
 		"create-template-project": { template: type },
 		scripts: {},
@@ -873,6 +960,7 @@ var generateProject = async (opts) => {
 	if (isUpdate && await pathExists(pkgPath)) {
 		debug$1("Loading existing package.json for update");
 		const existingPkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+		if (!existingPkg["create-template-project"]?.template) throw new Error(`No "create-template-project" configuration found in ${pkgPath}. The update command can only be used on projects created with this tool.`);
 		finalPkg = {
 			...finalPkg,
 			...existingPkg
@@ -935,8 +1023,8 @@ var generateProject = async (opts) => {
 					}
 					continue;
 				}
-				if (relativePath === "_oxlint.config.ts") {
-					relativePath = "oxlint.config.ts";
+				if (relativePath.startsWith("_") && relativePath.endsWith(".config.ts")) {
+					relativePath = relativePath.substring(1);
 					targetPath = path.join(projectDir, relativePath);
 				}
 				if (relativePath === "package.json") continue;
@@ -1081,6 +1169,16 @@ var generateProject = async (opts) => {
 		} else log.info("No changes detected.");
 	}
 	for (const op of pendingOperations) await op();
+	const states = {
+		gitInitialized: false,
+		githubCreated: false,
+		githubSkipped: !opts.createGithubRepository || isUpdate,
+		githubError: "",
+		depsInstalled: false,
+		depsSkipped: !opts.installDependencies,
+		ciRun: false,
+		ciSkipped: !opts.build || !finalPkg.scripts.ci
+	};
 	const stdio = debug$1.enabled ? "inherit" : "pipe";
 	if (!await pathExists(path.join(projectDir, ".git"))) {
 		debug$1("Initializing Git repository");
@@ -1092,12 +1190,13 @@ var generateProject = async (opts) => {
 				preferLocal: true
 			});
 			log.success("Initialized Git repository (git init).");
+			states.gitInitialized = true;
 		} catch (e) {
 			debug$1("Failed to initialize Git: %O", e);
 			const detail = e.stdout || e.stderr ? `\n\nOutput:\n${e.stdout}\n${e.stderr}` : "";
 			log.error(`Failed to initialize Git: ${e.message}${detail}`);
 		}
-	}
+	} else states.gitInitialized = true;
 	if (opts.createGithubRepository && !isUpdate) {
 		debug$1("Creating GitHub repository");
 		try {
@@ -1115,10 +1214,12 @@ var generateProject = async (opts) => {
 				preferLocal: true
 			});
 			log.success("Created GitHub repository (gh repo create).");
+			states.githubCreated = true;
 		} catch (e) {
 			debug$1("Failed to create GitHub repository: %O", e);
 			const detail = e.stdout || e.stderr ? `\n\nOutput:\n${e.stdout}\n${e.stderr}` : "";
 			log.warn(`Failed to create GitHub repository: ${e.message}${detail}\nEnsure "gh" CLI is installed and authenticated.`);
+			states.githubError = e.message;
 		}
 	}
 	if (opts.installDependencies) {
@@ -1133,6 +1234,7 @@ var generateProject = async (opts) => {
 				preferLocal: true
 			});
 			s.stop(`\x1b[1G\x1b[2K\x1b[32m◆\x1b[39m  Dependencies installed (${pm} install).`);
+			states.depsInstalled = true;
 		} catch (e) {
 			debug$1("Failed to install dependencies: %O", e);
 			s.stop("Failed to install dependencies.");
@@ -1144,16 +1246,16 @@ var generateProject = async (opts) => {
 	if (opts.build && finalPkg.scripts.ci) {
 		debug$1("Running CI script");
 		const s = spinner();
-		if (finalPkg.scripts["prettier-write"]) {
-			s.start(`Formatting files with Prettier (${pm} run prettier-write)...`);
+		if (finalPkg.scripts.format) {
+			s.start(`Formatting files with oxfmt (${pm} run format)...`);
 			try {
-				debug$1("Executing: %s run prettier-write", pm);
-				await execa(pm, ["run", "prettier-write"], {
+				debug$1("Executing: %s run format", pm);
+				await execa(pm, ["run", "format"], {
 					cwd: projectDir,
 					stdio,
 					preferLocal: true
 				});
-				s.stop(`\x1b[1G\x1b[2K\x1b[32m◆\x1b[39m  Files formatted (${pm} run prettier-write).`);
+				s.stop(`\x1b[1G\x1b[2K\x1b[32m◆\x1b[39m  Files formatted (${pm} run format).`);
 			} catch (e) {
 				debug$1("Failed to format files: %O", e);
 				s.stop("Failed to format files.");
@@ -1170,6 +1272,7 @@ var generateProject = async (opts) => {
 				preferLocal: true
 			});
 			s.stop(`\x1b[1G\x1b[2K\x1b[32m◆\x1b[39m  CI script completed (${pm} run ci).`);
+			states.ciRun = true;
 		} catch (e) {
 			debug$1("Failed to run CI script: %O", e);
 			s.stop("Failed to run CI script.");
@@ -1178,53 +1281,200 @@ var generateProject = async (opts) => {
 			throw new Error(`Failed to run CI script: ${e.message}${detail}`);
 		}
 	}
-	log.success(`Project "${projectName}" ${isUpdate ? "updated" : "scaffolded"} successfully in ${projectDir}`);
-	showSummary(opts, pm, isProgress);
-	if (opts.dev && finalPkg.scripts.dev) {
-		log.info("Starting dev server...");
-		if (opts.open) try {
-			debug$1("Executing: %s run dev -- --open", pm);
-			await execa(pm, [
-				"run",
-				"dev",
-				"--",
-				"--open"
-			], {
-				cwd: projectDir,
-				stdio: "inherit",
-				preferLocal: true
-			});
-		} catch (e) {
-			log.error("Dev server failed: " + e);
-		}
-		else try {
-			debug$1("Executing: %s run dev", pm);
-			await execa(pm, ["run", "dev"], {
-				cwd: projectDir,
-				stdio: "inherit",
-				preferLocal: true
-			});
-		} catch (e) {
-			log.error("Dev server failed: " + e);
-		}
+	let hasErrors = false;
+	let hasWarnings = false;
+	const errorMessages = [];
+	if (states.githubError) {
+		hasWarnings = true;
+		errorMessages.push(`GitHub repository creation failed: ${states.githubError}`);
 	}
+	await generateGeneratedMd(projectDir, opts, pm, states, isUpdate, {
+		hasErrors,
+		hasWarnings,
+		errorMessages
+	});
+	const successMsg = `Project "${projectName}" ${isUpdate ? "updated" : "scaffolded"} successfully in ${projectDir}. A detailed setup guide has been generated at GENERATED.md`;
+	if (hasWarnings) log.warn(`${successMsg} (completed with warnings)`);
+	else log.success(successMsg);
 };
-function showSummary(opts, pm, isProgress) {
-	debug$1("Showing summary for options: %O", opts);
-	const { projectName, template } = opts;
-	const summary = [
-		`Successfully created a new ${template} project named '${projectName}'.`,
+async function generateGeneratedMd(projectDir, opts, pm, states, isUpdate, status) {
+	const statusBadge = status.hasErrors ? "🔴 **Completed with Errors**" : status.hasWarnings ? "🟡 **Completed with Warnings**" : "🟢 **Successfully Completed**";
+	const md = [
+		`# 🚀 Project Setup Guide: ${opts.projectName}`,
+		"",
+		`Welcome to your newly ${isUpdate ? "updated" : "generated"} **${opts.template}** project! This document outlines what was scaffolded, the automated steps already completed, and the remaining manual adjustments required to finalize your setup.`,
+		"",
+		`**Status:** ${statusBadge}`,
+		"",
+		...status.errorMessages.length > 0 ? [
+			"### ⚠️ Issues Encountered",
+			...status.errorMessages.map((msg) => `- ${msg}`),
+			""
+		] : [],
+		"## 📦 What Was Generated",
+		`* **Project Name:** \`${opts.projectName}\``,
+		`* **Template Used:** \`${opts.template}\``,
+		`* **Package Manager:** \`${pm}\``,
+		"",
+		"---",
+		"",
+		"## 📋 Initialization Checklist",
+		"The following tasks were executed during the generation process:",
+		`- [x] Scaffold project files and directories`,
+		`- [x] Configure \`package.json\` with appropriate dependencies`,
+		`- [${states.depsInstalled ? "x" : " "}] Install dependencies using \`${pm}\`${states.depsSkipped ? " *(Skipped)*" : ""}`,
+		`- [${states.gitInitialized ? "x" : " "}] Initialize Git repository`,
+		`- [${states.githubCreated ? "x" : " "}] Create GitHub repository${states.githubSkipped ? " *(Skipped)*" : states.githubError ? " *(Failed)*" : ""}`,
+		`- [${states.ciRun ? "x" : " "}] Run initial CI pipeline (lint, build, test)${states.ciSkipped ? " *(Skipped)*" : ""}`,
+		"",
+		"---",
 		"",
-		"Available Commands:"
-	];
-	const commands = [
-		`${pm} run dev    - Starts the development server`,
-		`${pm} run build  - Builds the project for production`,
-		`${pm} run test   - Runs the unit test suite (Vitest)`,
-		`${pm} run lint   - Lints and formats the codebase`,
-		`${pm} run ci     - Runs lint, build, and test (used by CI/CD)`
-	];
-	showNote([...summary, ...commands.map((c) => `  ${c}`)].join("\n"), "Project ready", isProgress);
+		"## 💻 Available Commands",
+		`You can run these commands from the project root using \`${pm} run <command>\`:`,
+		"",
+		"| Command | Description |",
+		"| :--- | :--- |",
+		"| `dev` | Starts the development server |",
+		"| `build` | Builds the project for production |",
+		"| `test` | Runs the unit test suite (Vitest) |",
+		"| `lint` | Lints and formats the codebase |",
+		"| `ci` | Runs lint, build, and test (used by CI/CD) |",
+		"",
+		"---",
+		"",
+		...getTemplateArchitectureSection(opts.template),
+		"",
+		"---",
+		"",
+		"## 🧪 Testing Strategy",
+		"",
+		"### Unit Testing (Vitest)",
+		"This project is pre-configured with **Vitest** for blazing-fast unit testing and coverage reporting.",
+		`- **Where to put tests**: Create files with the \`.test.ts\` or \`.spec.ts\` extension next to your source files (e.g., \`src/main.test.ts\`).`,
+		`- **How to run**: \`${pm} run test\``,
+		`- **Watch mode**: \`${pm} exec vitest\` to automatically re-run tests on file changes.`,
+		`- **Coverage**: Coverage is generated automatically during the test run. Aim for high coverage on core logic!`,
+		"",
+		"### End-to-End (E2E) Testing",
+		"Currently, only unit tests are scaffolded by default. To enhance your project's reliability, we highly recommend adding E2E testing:",
+		`- **For Web Apps**: Consider installing [Playwright](https://playwright.dev/) (\`${pm} create playwright\`) to simulate real user interactions in the browser.`,
+		`- **For CLIs**: Consider using \`execa\` within your Vitest suite to invoke your compiled CLI binary and assert its \`stdout\`/\`stderr\` outputs.`,
+		"",
+		"---",
+		"",
+		"## 🐙 Key Git Commands",
+		"Here are the most common Git operations you will use to manage your codebase:",
+		"",
+		"| Command | Description |",
+		"| :--- | :--- |",
+		"| `git status` | Check the current state of your working directory |",
+		"| `git add .` | Stage all your changes for the next commit |",
+		"| `git commit -m \"feat: your feature\"` | Create a new commit (following Conventional Commits) |",
+		"| `git push` | Push your committed changes to the remote repository |",
+		"| `git pull` | Fetch and merge changes from the remote repository |",
+		"| `git checkout -b <branch>` | Create and switch to a new branch |",
+		"",
+		"---",
+		"",
+		"## 🐈 Key GitHub (`gh`) Commands",
+		"The `gh` CLI provides powerful tools to interact with GitHub right from your terminal:",
+		"",
+		"| Command | Description |",
+		"| :--- | :--- |",
+		"| `gh repo view --web` | Open the repository in your default web browser |",
+		"| `gh pr create` | Create a new Pull Request |",
+		"| `gh pr checkout <pr-number>` | Checkout a Pull Request branch locally |",
+		"| `gh issue create` | Create a new Issue |",
+		"| `gh issue list` | List all open Issues |",
+		"| `gh repo delete <owner>/<repo> --confirm` | Dangerously delete a repository completely (use with caution!) |",
+		"",
+		"---",
+		"",
+		"## 🚀 Creating a Release",
+		"This project uses Conventional Commits and automated changelogs. To create a new release:",
+		"1. **Verify build/tests:** `pnpm run ci`",
+		"2. **Bump version:** `pnpm version <patch|minor|major> --no-git-tag-version`",
+		"3. **Update changelog:** `pnpm run create-changelog`",
+		"4. **Commit changes:** `git add . && git commit -m \"chore(release): $(node -p 'require(\"./package.json\").version')\"`",
+		"5. **Tag & Push:** `git tag v$(node -p 'require(\"./package.json\").version') && git push && git push --tags`",
+		"6. **Create GitHub Release:** `gh release create v$(node -p 'require(\"./package.json\").version') --generate-notes`",
+		"7. **Publish (if applicable):** `pnpm publish`",
+		"",
+		"---",
+		"",
+		"## 🛠️ Manual Adjustments Needed",
+		"To complete your project setup, please review and manually update the following:",
+		"- [ ] **`LICENSE`**: Verify the copyright year and author name.",
+		"- [ ] **`package.json`**: Review the description, keywords, author, and repository links.",
+		"- [ ] **`README.md`**: Update with project-specific instructions, architecture details, and contribution guidelines.",
+		"",
+		"---",
+		"",
+		"## 💡 Next Steps",
+		"1. Review the generated codebase to familiarize yourself with the structure.",
+		`2. Start the development server using \`${pm} run dev\`.`,
+		"3. Make your first commit and push to your remote repository.",
+		"",
+		"<br>",
+		"<p align=\"center\"><i>This file was auto-generated by <b>create-template-project</b>.</i></p>"
+	].join("\n");
+	await fs.writeFile(path.join(projectDir, "GENERATED.md"), md);
+}
+function getTemplateArchitectureSection(template) {
+	switch (template) {
+		case "cli": return [
+			"## 🏗️ CLI Architecture",
+			"This project uses `commander` for argument parsing and `@clack/prompts` for interactive CLI interfaces.",
+			"",
+			"### Source Files Generated",
+			"- **`src/index.ts`**: The main execution entry point. Handles top-level errors and bootstraps the CLI application.",
+			"- **`src/cli.ts`**: Parses command-line arguments and orchestrates your user prompts.",
+			"",
+			"### How to Enhance",
+			"- Add new sub-commands directly in `src/cli.ts`.",
+			"- Extract logic into a new `src/commands/` directory as your application scales."
+		];
+		case "web-vanilla": return [
+			"## 🏗️ Web Vanilla Architecture",
+			"A standalone, blazing fast web application scaffolded with Vite.",
+			"",
+			"### Source Files Generated",
+			"- **`index.html`**: The main HTML entry point that loads your application scripts.",
+			"- **`src/main.ts`**: The core TypeScript application logic where you can start adding DOM manipulation.",
+			"",
+			"### How to Enhance",
+			"- Add new UI logic or Web Components inside the `src/` directory.",
+			"- Create styling (`.css` or `.scss`) and import them directly into `main.ts`."
+		];
+		case "web-app": return [
+			"## 🏗️ Web App Architecture",
+			"A robust React SPA configured with MUI components and TanStack Query.",
+			"",
+			"### Source Files Generated",
+			"- **`index.html`**: The HTML entry point hosting the React root element.",
+			"- **`src/main.tsx`**: Bootstraps the React application and mounts all necessary providers (QueryClient, Theme).",
+			"- **`src/App.tsx`**: The root application component. Start building your UI here.",
+			"",
+			"### How to Enhance",
+			"- Add new components to a `src/components/` directory.",
+			"- Set up React Router for client-side routing.",
+			"- Manage complex global state with a store like Zustand if needed."
+		];
+		case "web-fullstack": return [
+			"## 🏗️ Fullstack Monorepo Architecture",
+			"A modern monorepo combining an Express server with a React client, seamlessly integrated using workspaces.",
+			"",
+			"### Source Files Generated",
+			"- **`client/`**: The frontend React application (similar to the `web-app` template).",
+			"- **`server/`**: The backend Express/Node application delivering API endpoints.",
+			"",
+			"### How to Enhance",
+			"- Add new API routes in the `server` package.",
+			"- Consume those routes in the `client` package via TanStack Query.",
+			"- **Tip**: Create a `shared/` workspace package to share types across both frontend and backend for end-to-end type safety."
+		];
+		default: return [];
+	}
 }
 //#endregion
 //#region src/index.ts