create-template-project 1.5.23 → 1.6.0

package/dist/index.js

@@ -12,6 +12,7 @@ import { existsSync } from "node:fs";
 var TemplateTypeSchema = z.enum([
 	"cli",
 	"web-vanilla",
+	"web-widget",
 	"web-app",
 	"web-fullstack"
 ]);
@@ -46,6 +47,9 @@ var genericProcessor = (content, { opts }) => {
 		case "web-vanilla":
 			description = "A standalone web page/application for modern browsers.";
 			break;
+		case "web-widget":
+			description = "A publishable native TypeScript web widget with a Vite demo and npm-ready package build.";
+			break;
 		case "web-fullstack":
 			description = "A full-stack monorepo with an Express server and a React/MUI client.";
 			break;
@@ -68,7 +72,7 @@ var WORKFLOW_PNPM_SETUP = `      - name: Setup pnpm
 var WORKFLOW_PLAYWRIGHT_SETUP = `      - name: Install Playwright Browsers & Deps
         run: npx playwright install --with-deps chromium`;
 var githubWorkflowProcessor = (content, { filePath, opts }) => {
-	if (!filePath.includes(".github/workflows/node.js.yml")) return content;
+	if (!filePath.includes(".github/workflows/") || !filePath.endsWith(".yml")) return content;
 	const { template, packageManager: pm } = opts;
 	let installCommand = "npm ci";
 	let pmSetup = "";
@@ -77,7 +81,7 @@ var githubWorkflowProcessor = (content, { filePath, opts }) => {
 		pmSetup = WORKFLOW_PNPM_SETUP;
 	} else if (pm === "yarn") installCommand = "yarn install --frozen-lockfile";
 	let playwrightSetup = "";
-	if (template === "web-fullstack" || template === "web-app" || template === "web-vanilla") playwrightSetup = WORKFLOW_PLAYWRIGHT_SETUP;
+	if ((filePath.includes("ci.yml") || filePath.includes("node.js.yml")) && (template === "web-fullstack" || template === "web-app" || template === "web-vanilla" || template === "web-widget")) playwrightSetup = WORKFLOW_PLAYWRIGHT_SETUP;
 	let processed = content.replaceAll("{{installCommand}}", installCommand).replaceAll("# [PM_SETUP]", pmSetup).replaceAll("# [PLAYWRIGHT_SETUP]", playwrightSetup);
 	processed = processed.replace(/^\s*# \[PM_SETUP\]\s*\n/mu, "");
 	processed = processed.replace(/^\s*# \[PLAYWRIGHT_SETUP\]\s*\n/mu, "");
@@ -99,7 +103,11 @@ var tsconfigProcessor = (content, { filePath, opts }) => {
 	if (filePath !== "tsconfig.json") return content;
 	const { template } = opts;
 	let processed = content;
-	if (template === "web-fullstack" || template === "web-vanilla" || template === "web-app") processed = processed.replace(/\/\* Language and Environment \*\/[\s\S]*?\/\* Strict Type-Checking Options \*\//u, `${WEB_ENV}\n\n\t\t/* Strict Type-Checking Options */`);
+	if (template === "web-fullstack" || template === "web-vanilla" || template === "web-widget" || template === "web-app") processed = processed.replace(/\/\* Language and Environment \*\/[\s\S]*?\/\* Strict Type-Checking Options \*\//u, `${WEB_ENV}\n\n\t\t/* Strict Type-Checking Options */`);
+	if (template === "web-widget") processed = processed.replace("\"moduleResolution\": \"bundler\" /* Specify how TypeScript looks up a file from a given module specifier. */,", `"moduleResolution": "bundler" /* Specify how TypeScript looks up a file from a given module specifier. */,
+		"paths": {
+			"${opts.projectName}": ["./src/lib/index.ts"]
+		},`);
 	if (template === "web-fullstack") processed = processed.replace(/"include":\s*\[\s*"src\/\*\*\/\*"\s*\]/u, "\"include\": [\"client/src/**/*\", \"server/src/**/*\"]");
 	return processed;
 };
@@ -124,7 +132,7 @@ var webVanillaHtmlProcessor = (content, { filePath, opts }) => {
 var oxcConfigProcessor = (content, { filePath, opts }) => {
 	if (filePath !== "oxc.config.ts") return content;
 	const shouldAddNodeEnv = opts.template === "cli" || opts.template === "web-fullstack";
-	const shouldAddBrowserEnv = opts.template === "web-vanilla" || opts.template === "web-app" || opts.template === "web-fullstack";
+	const shouldAddBrowserEnv = opts.template === "web-vanilla" || opts.template === "web-widget" || opts.template === "web-app" || opts.template === "web-fullstack";
 	const linesToAdd = [];
 	if (shouldAddNodeEnv && !content.includes("node: true")) linesToAdd.push("		node: true,");
 	if (shouldAddBrowserEnv && !content.includes("browser: true")) linesToAdd.push("		browser: true,");
@@ -155,6 +163,34 @@ var processContent$1 = (filePath, content, opts, addedDeps) => {
 //#endregion
 //#region src/shared/file.ts
 var debug$3 = debugLib("create-template-project:utils:file");
+var parseExactVersion$1 = (version) => {
+	const match = /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:[-+].*)?$/u.exec(version);
+	if (match?.groups === void 0) return;
+	return [
+		Number(match.groups.major),
+		Number(match.groups.minor),
+		Number(match.groups.patch)
+	];
+};
+var isGreaterOrEqualVersion$1 = (current, next) => {
+	const currentParts = parseExactVersion$1(current);
+	const nextParts = parseExactVersion$1(next);
+	if (currentParts === void 0 || nextParts === void 0) return false;
+	for (const [index, currentPart] of currentParts.entries()) {
+		const nextPart = nextParts[index];
+		if (currentPart > nextPart) return true;
+		if (currentPart < nextPart) return false;
+	}
+	return true;
+};
+var mergeStringRecord = (target, source, preserveExistingVersions) => {
+	const merged = { ...target };
+	for (const [name, version] of Object.entries(source)) {
+		if (preserveExistingVersions && Object.hasOwn(merged, name) && isGreaterOrEqualVersion$1(merged[name], version)) continue;
+		merged[name] = version;
+	}
+	return merged;
+};
 var toErrorDetail$1 = (error) => {
 	if (error instanceof Error) {
 		const value = error;
@@ -191,21 +227,27 @@ var getAllFiles = async (dirPath, arrayOfFiles = []) => {
 	];
 };
 var processContent = (filePath, content, opts, addedDeps) => processContent$1(filePath, content, opts, addedDeps);
-var mergePackageJson = (target, source) => {
+var mergePackageJson = (target, source, options = {}) => {
+	const preservePackageFields = options.preserveExistingPackageFields === true;
+	const preserveDependencyVersions = options.preserveExistingDependencyVersions === true;
+	if (source.private !== void 0) target.private = source.private;
+	if (source.files !== void 0 && (!preservePackageFields || target.files === void 0)) target.files = source.files;
+	if (source.main !== void 0 && (!preservePackageFields || target.main === void 0)) target.main = source.main;
+	if (source.module !== void 0 && (!preservePackageFields || target.module === void 0)) target.module = source.module;
+	if (source.types !== void 0 && (!preservePackageFields || target.types === void 0)) target.types = source.types;
+	if (source.exports !== void 0 && (!preservePackageFields || target.exports === void 0)) target.exports = source.exports;
 	if (source.scripts !== void 0) target.scripts = {
 		...target.scripts,
 		...source.scripts
 	};
-	if (source.dependencies !== void 0) target.dependencies = {
-		...target.dependencies,
-		...source.dependencies
+	if (source.dependencies !== void 0) target.dependencies = mergeStringRecord(target.dependencies, source.dependencies, preserveDependencyVersions);
+	if (source.devDependencies !== void 0) target.devDependencies = mergeStringRecord(target.devDependencies, source.devDependencies, preserveDependencyVersions);
+	if (source.peerDependencies !== void 0) target.peerDependencies = {
+		...target.peerDependencies,
+		...source.peerDependencies
 	};
-	if (source.devDependencies !== void 0) target.devDependencies = {
-		...target.devDependencies,
-		...source.devDependencies
-	};
-	if (source.workspaces !== void 0) target.workspaces = source.workspaces;
-	if (source.bin !== void 0) target.bin = source.bin;
+	if (source.workspaces !== void 0 && (!preservePackageFields || target.workspaces === void 0)) target.workspaces = source.workspaces;
+	if (source.bin !== void 0 && (!preservePackageFields || target.bin === void 0)) target.bin = source.bin;
 };
 var isSeedFile = (filePath) => {
 	return [
@@ -377,6 +419,72 @@ var getWebVanillaTemplate = (_opts) => ({
 	templateDir: getTemplateDir(import.meta.dirname, "web-vanilla")
 });
 //#endregion
+//#region src/templates/web-widget/index.ts
+var getWebWidgetTemplate = (_opts) => ({
+	name: "web-widget",
+	description: "A publishable native TypeScript web widget with a Vite demo, package build, API docs, and screenshots.",
+	components: [
+		{
+			name: "Native TypeScript Widget",
+			description: "Dependency-free DOM component published as an ESM package."
+		},
+		{
+			name: "tsdown",
+			description: "Builds ESM library artifacts and declaration files for npm publishing."
+		},
+		{
+			name: "Vite",
+			description: "Runs and builds the documentation/demo site."
+		},
+		{
+			name: "TypeDoc",
+			description: "Generates API documentation for the public package surface."
+		},
+		{
+			name: "Stylelint",
+			description: "Lints the widget and demo stylesheets."
+		},
+		{
+			name: "Playwright",
+			description: "Runs e2e checks and captures demo screenshots."
+		}
+	],
+	dependencies: {},
+	devDependencies: {
+		vite: "vite",
+		vitest: "vitest",
+		"@vitest/browser": "@vitest/browser",
+		"@vitest/browser-playwright": "@vitest/browser-playwright",
+		playwright: "playwright",
+		"@playwright/test": "@playwright/test",
+		tsdown: "tsdown",
+		typedoc: "typedoc",
+		stylelint: "stylelint",
+		"stylelint-config-standard": "stylelint-config-standard",
+		react: "react",
+		"react-dom": "react-dom",
+		"@types/react": "@types/react",
+		"@types/react-dom": "@types/react-dom"
+	},
+	scripts: {
+		dev: "vite",
+		build: "vite build",
+		"build:lib": "tsdown",
+		"build:demo": "vite build",
+		"docs:api": "typedoc",
+		preview: "vite preview",
+		start: "vite preview --port 4173 --strictPort",
+		test: "vitest run",
+		"test:ui": "vitest",
+		"integration-test": "playwright test",
+		"lint:css": "stylelint 'src/{demo,styles}/**/*.css'",
+		"lint:css:fix": "stylelint --fix 'src/{demo,styles}/**/*.css'",
+		screenshot: "node scripts/screenshot.mjs"
+	},
+	files: [],
+	templateDir: getTemplateDir(import.meta.dirname, "web-widget")
+});
+//#endregion
 //#region src/templates/web-app/index.ts
 var getWebAppTemplate = (_opts) => ({
 	name: "web-app",
@@ -518,6 +626,7 @@ var getWebFullstackTemplate = (opts) => ({
 var templateFactories = {
 	cli: getCliTemplate,
 	"web-vanilla": getWebVanillaTemplate,
+	"web-widget": getWebWidgetTemplate,
 	"web-app": getWebAppTemplate,
 	"web-fullstack": getWebFullstackTemplate
 };
@@ -526,6 +635,7 @@ var getProjectTemplates = (opts) => [getBaseTemplate(opts), getTemplateByType(op
 var getTemplateTypes = () => [
 	"cli",
 	"web-vanilla",
+	"web-widget",
 	"web-app",
 	"web-fullstack"
 ];
@@ -558,6 +668,208 @@ var getTemplateInfo = (type) => {
 };
 var getAllTemplatesInfo = () => getTemplateTypes().map((type) => getTemplateInfo(type));
 //#endregion
+//#region src/generators/project-compatibility.ts
+var PASS_THRESHOLD = 75;
+var isRecord$3 = (value) => typeof value === "object" && value !== null;
+var pathExists$2 = async (filePath) => {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+};
+var listFiles = async (directory) => {
+	try {
+		const entries = await fs.readdir(directory, { withFileTypes: true });
+		return (await Promise.all(entries.map(async (entry) => {
+			const entryPath = path.join(directory, entry.name);
+			if (entry.isDirectory()) return await listFiles(entryPath);
+			return entry.isFile() ? [entryPath] : [];
+		}))).flat();
+	} catch {
+		return [];
+	}
+};
+var parseStringRecord$1 = (value) => {
+	if (!isRecord$3(value)) return;
+	const parsed = {};
+	for (const [key, entry] of Object.entries(value)) if (typeof entry === "string") parsed[key] = entry;
+	return parsed;
+};
+var parsePackageJson = async (pkgPath) => {
+	try {
+		const parsed = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+		if (!isRecord$3(parsed)) return;
+		return {
+			name: typeof parsed.name === "string" ? parsed.name : void 0,
+			type: typeof parsed.type === "string" ? parsed.type : void 0,
+			scripts: parseStringRecord$1(parsed.scripts),
+			dependencies: parseStringRecord$1(parsed.dependencies),
+			devDependencies: parseStringRecord$1(parsed.devDependencies),
+			workspaces: Array.isArray(parsed.workspaces) ? parsed.workspaces.filter((workspace) => typeof workspace === "string") : void 0
+		};
+	} catch {
+		return;
+	}
+};
+var hasAnyDependency = (pkg, dependency) => pkg?.dependencies?.[dependency] !== void 0 || pkg?.devDependencies?.[dependency] !== void 0;
+var requiredFilesByTemplate = {
+	cli: [
+		"src/index.ts",
+		"src/index.test.ts",
+		"vite.config.ts"
+	],
+	"web-vanilla": [
+		"index.html",
+		"src/index.ts",
+		"vite.config.ts",
+		"playwright.config.ts"
+	],
+	"web-widget": [
+		"index.html",
+		"src/lib/index.ts",
+		"tsdown.config.ts",
+		"typedoc.json",
+		"vite.config.ts",
+		"playwright.config.ts"
+	],
+	"web-app": [
+		"index.html",
+		"src/index.tsx",
+		"src/App.tsx",
+		"vite.config.ts",
+		"playwright.config.ts"
+	],
+	"web-fullstack": [
+		"client/package.json",
+		"server/package.json",
+		"client/src/main.tsx",
+		"server/src/index.ts"
+	]
+};
+var requiredDependenciesByTemplate = {
+	cli: ["vite"],
+	"web-vanilla": [
+		"vite",
+		"vitest",
+		"playwright"
+	],
+	"web-widget": [
+		"vite",
+		"vitest",
+		"playwright",
+		"tsdown",
+		"typedoc",
+		"stylelint"
+	],
+	"web-app": [
+		"react",
+		"react-dom",
+		"@mui/material",
+		"vite"
+	],
+	"web-fullstack": [
+		"express",
+		"@trpc/server",
+		"react",
+		"react-dom"
+	]
+};
+var validateProjectCompatibility = async (directory, template) => {
+	const pkg = await parsePackageJson(path.join(directory, "package.json"));
+	const checks = [];
+	const addCheck = (id, label, passed, required = false) => {
+		checks.push({
+			id,
+			label,
+			passed,
+			required
+		});
+	};
+	addCheck("package-json", "package.json exists and is valid JSON", pkg !== void 0, true);
+	addCheck("package-name", "package.json has a name", typeof pkg?.name === "string" && pkg.name.length > 0, true);
+	addCheck("esm", "package.json uses ESM type module", pkg?.type === "module");
+	const canonicalWorkflowPath = ".github/workflows/ci.yml";
+	const legacyWorkflowPath = ".github/workflows/node.js.yml";
+	const canonicalWorkflowExists = await pathExists$2(path.join(directory, canonicalWorkflowPath));
+	const legacyWorkflowExists = await pathExists$2(path.join(directory, legacyWorkflowPath));
+	const commonFileResults = await Promise.all([
+		"tsconfig.json",
+		"vitest.config.ts",
+		"commitlint.config.js",
+		".husky/pre-commit"
+	].map(async (filePath) => ({
+		filePath,
+		exists: await pathExists$2(path.join(directory, filePath))
+	})));
+	for (const { filePath, exists } of commonFileResults) addCheck(`file:${filePath}`, `${filePath} exists`, exists);
+	addCheck(`file:${canonicalWorkflowPath}`, canonicalWorkflowExists ? `${canonicalWorkflowPath} exists` : `${canonicalWorkflowPath} exists (canonical; legacy ${legacyWorkflowPath} is accepted for adoption)`, canonicalWorkflowExists || legacyWorkflowExists);
+	const configFileResults = await Promise.all([
+		"oxc.config.ts",
+		"oxlint.config.ts",
+		"oxfmt.config.ts"
+	].map(async (filePath) => ({
+		filePath,
+		exists: await pathExists$2(path.join(directory, filePath))
+	})));
+	for (const { filePath, exists } of configFileResults) addCheck(`file:${filePath}`, `${filePath} exists`, exists);
+	for (const script of [
+		"typecheck",
+		"lint",
+		"format:check",
+		"ci",
+		"test"
+	]) addCheck(`script:${script}`, `package.json has ${script} script`, pkg?.scripts?.[script] !== void 0);
+	for (const dependency of [
+		"typescript",
+		"vitest",
+		"oxlint",
+		"oxfmt",
+		"husky",
+		"@commitlint/cli"
+	]) addCheck(`dependency:${dependency}`, `${dependency} dependency is declared`, hasAnyDependency(pkg, dependency));
+	const templateFileResults = await Promise.all(requiredFilesByTemplate[template].map(async (filePath) => ({
+		filePath,
+		exists: await pathExists$2(path.join(directory, filePath))
+	})));
+	for (const { filePath, exists } of templateFileResults) addCheck(`template-file:${filePath}`, `${template} file ${filePath} exists`, exists);
+	if (template === "web-widget") {
+		const sourceFiles = await listFiles(path.join(directory, "src/lib"));
+		const styleFiles = await listFiles(path.join(directory, "src/styles"));
+		const implementationFiles = sourceFiles.map((filePath) => path.relative(directory, filePath).split(path.sep).join("/")).filter((filePath) => /\.tsx?$/u.test(filePath) && !filePath.endsWith("/index.ts") && !filePath.endsWith("/react.tsx") && !filePath.includes(".test."));
+		const widgetStyles = styleFiles.map((filePath) => path.relative(directory, filePath).split(path.sep).join("/")).filter((filePath) => filePath.endsWith(".css"));
+		addCheck("web-widget:implementation", implementationFiles.length > 0 ? `web-widget implementation found (${implementationFiles.join(", ")})` : "web-widget implementation exists in src/lib", implementationFiles.length > 0);
+		addCheck("web-widget:stylesheet", widgetStyles.length > 0 ? `web-widget stylesheet found (${widgetStyles.join(", ")})` : "web-widget stylesheet exists in src/styles", widgetStyles.length > 0);
+	}
+	for (const dependency of requiredDependenciesByTemplate[template]) addCheck(`template-dependency:${dependency}`, `${template} dependency ${dependency} is declared`, hasAnyDependency(pkg, dependency));
+	if (template === "web-fullstack") addCheck("workspaces", "package.json has workspaces", Array.isArray(pkg?.workspaces) && pkg.workspaces.length > 0);
+	const requiredPassed = checks.filter((check) => check.required).every((check) => check.passed);
+	const passedCount = checks.filter((check) => check.passed).length;
+	const score = Math.round(passedCount / checks.length * 100);
+	return {
+		directory,
+		template,
+		score,
+		passed: requiredPassed && score >= PASS_THRESHOLD,
+		checks
+	};
+};
+var formatCompatibilityReport = (report) => {
+	const failed = report.checks.filter((check) => !check.passed);
+	const lines = [
+		`Directory: ${report.directory}`,
+		`Template: ${report.template}`,
+		`Score: ${report.score}%`,
+		`Status: ${report.passed ? "PASS" : "FAIL"}`
+	];
+	if (failed.length > 0) {
+		lines.push("", "Missing or incompatible checks:");
+		for (const check of failed) lines.push(`- ${check.label}${check.required ? " (required)" : ""}`);
+	}
+	return lines.join("\n");
+};
+//#endregion
 //#region src/cli.ts
 var isRecord$2 = (value) => typeof value === "object" && value !== null;
 var isPackageManager = (value) => value === "npm" || value === "pnpm" || value === "yarn";
@@ -620,6 +932,35 @@ var getDefaultGithubUsername = async () => {
 		return "";
 	}
 };
+var getMissingProjectConfigMessage$1 = (pkgPath) => [
+	`No "create-template-project" configuration found in ${pkgPath}.`,
+	"The update command only runs after a project has been adopted by this tool.",
+	"If this project matches a template, run \"create-template-project doctor --template <type> --directory <dir>\" to validate it, then \"create-template-project adopt --template <type> --directory <dir>\" to add the marker."
+].join(" ");
+var parseTemplateOption = (template) => {
+	const templateInput = stripQuotes(template);
+	const templateResult = TemplateTypeSchema.safeParse(templateInput);
+	if (!templateResult.success) {
+		p.log.error(`Invalid template type: ${template}. Must be one of: cli, web-vanilla, web-widget, web-app, web-fullstack`);
+		process.exit(1);
+	}
+	return templateResult.data;
+};
+var adoptProject = async (directory, template) => {
+	const pkgPath = path.join(directory, "package.json");
+	const parsed = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+	if (!isRecord$2(parsed)) {
+		p.log.error(`Failed to adopt project: ${pkgPath} does not contain a JSON object.`);
+		process.exit(1);
+	}
+	await fs.writeFile(pkgPath, `${JSON.stringify({
+		...parsed,
+		"create-template-project": {
+			...isRecord$2(parsed["create-template-project"]) ? parsed["create-template-project"] : {},
+			template
+		}
+	}, null, "	")}\n`);
+};
 var debug$2 = debugLib("create-template-project:cli");
 var parseArgs = async () => {
 	debug$2("Parsing CLI arguments: %O", process.argv);
@@ -632,27 +973,22 @@ var parseArgs = async () => {
 		process.env.DEBUG = "create-template-project:*";
 		debugLib.enable("create-template-project:*");
 	}).addHelpText("after", `
-Commands:
-  create      - Create a new project from a template.
-  update      - Update an existing project from its template.
-  interactive - Start interactive project configuration.
-  info        - Show detailed information about available templates and components.
-
 Templates:
   cli            - Node.js CLI application with commander and cli-progress.
   web-vanilla    - Standalone web page (modern HTML/JS).
+  web-widget     - Publishable native TypeScript widget with demo, docs, and npm build.
   web-app        - React application with MUI and TanStack Query.
   web-fullstack  - Full-stack monorepo with Express server and React/MUI client.
 `);
 	let commandResult;
-	program.command("info").description("Show detailed information about available templates and their components").option("-t, --template <type>", "Template type (cli, web-vanilla, web-app, web-fullstack)").action((opts) => {
+	program.command("info").description("Show detailed information about available templates and their components").option("-t, --template <type>", "Template type (cli, web-vanilla, web-widget, web-app, web-fullstack)").action((opts) => {
 		debug$2("Executing \"info\" command with options: %O", opts);
 		p.intro("Template Information");
 		if (opts.template !== void 0 && opts.template.length > 0) {
 			const template = stripQuotes(opts.template);
 			const typeResult = TemplateTypeSchema.safeParse(template);
 			if (!typeResult.success) {
-				p.log.error(`Invalid template type: ${opts.template}. Must be one of: cli, web-vanilla, web-app, web-fullstack`);
+				p.log.error(`Invalid template type: ${opts.template}. Must be one of: cli, web-vanilla, web-widget, web-app, web-fullstack`);
 				process.exit(1);
 			}
 			const info = getTemplateInfo(typeResult.data);
@@ -674,12 +1010,49 @@ 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("--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 repository and push initial commit").requiredOption("--path <path>", "Output directory").option("--build", "Run the CI script (lint, build, test) after scaffolding", false).option("--no-progress", "Do not show progress indicators").action(async (opts) => {
+	program.command("doctor").description("Check whether an existing project can be adopted for template updates").requiredOption("-t, --template <type>", "Template type (cli, web-vanilla, web-widget, web-app, web-fullstack)").option("-d, --directory <path>", "Project directory", ".").action(async (opts) => {
+		debug$2("Executing \"doctor\" command with options: %O", opts);
+		const template = parseTemplateOption(opts.template);
+		const directory = path.resolve(opts.directory);
+		const report = await validateProjectCompatibility(directory, template);
+		p.note(formatCompatibilityReport(report), "Compatibility Check");
+		if (!report.passed) {
+			p.log.error("Project is not compatible enough to adopt safely. Fix the failed checks and run doctor again.");
+			process.exit(1);
+		}
+		p.log.success(`Project is compatible. Run "create-template-project adopt --template ${template} --directory ${directory}" to add the create-template-project marker.`);
+		process.exit(0);
+	});
+	program.command("adopt").description("Validate an existing project and add the create-template-project update marker").requiredOption("-t, --template <type>", "Template type (cli, web-vanilla, web-widget, web-app, web-fullstack)").option("-d, --directory <path>", "Project directory", ".").option("--yes", "Adopt without confirmation", false).action(async (opts) => {
+		debug$2("Executing \"adopt\" command with options: %O", opts);
+		const template = parseTemplateOption(opts.template);
+		const directory = path.resolve(opts.directory);
+		const report = await validateProjectCompatibility(directory, template);
+		p.note(formatCompatibilityReport(report), "Compatibility Check");
+		if (!report.passed) {
+			p.log.error("Project is not compatible enough to adopt safely. Fix the failed checks and run doctor again.");
+			process.exit(1);
+		}
+		if (opts.yes !== true) {
+			const confirmed = await p.confirm({
+				message: `Add create-template-project marker for template "${template}" to ${path.join(directory, "package.json")}?`,
+				initialValue: false
+			});
+			if (p.isCancel(confirmed) || !confirmed) {
+				p.cancel("Adoption cancelled.");
+				process.exit(0);
+			}
+		}
+		await adoptProject(directory, template);
+		p.log.success(`Project adopted as ${template}. You can now run "create-template-project update --directory ${directory}".`);
+		process.exit(0);
+	});
+	program.command("create").description("Create a new project from a template").option("-t, --template <type>", "Template type (cli, web-vanilla, web-widget, 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 repository and push initial commit").requiredOption("--path <path>", "Output directory").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);
 		const templateInput = stripQuotes(opts.template);
 		const templateResult = TemplateTypeSchema.safeParse(templateInput);
 		if (!templateResult.success) {
-			p.log.error(`Invalid template type: ${opts.template}. Must be one of: cli, web-vanilla, web-app, web-fullstack`);
+			p.log.error(`Invalid template type: ${opts.template}. Must be one of: cli, web-vanilla, web-widget, web-app, web-fullstack`);
 			process.exit(1);
 		}
 		commandResult = {
@@ -708,7 +1081,7 @@ Restrictions & Behavior:
   - 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 show a summary of proposed changes and lets you preview diffs before applying.
- `).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 repository and push initial commit").option("-d, --directory <path>", "Output directory", ".").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) => {
+ `).option("-t, --template <type>", "Template type (cli, web-vanilla, web-widget, 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 repository and push initial commit").option("-d, --directory <path>", "Output directory", ".").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");
@@ -730,19 +1103,11 @@ Restrictions & Behavior:
 		}
 		const projectConfig = pkg["create-template-project"];
 		if (projectConfig === void 0 || projectConfig.template === void 0) {
-			p.log.error(`No "create-template-project" configuration found in ${pkgPath}. The update command can only be used on projects created with this tool.`);
+			p.log.error(getMissingProjectConfigMessage$1(pkgPath));
 			process.exit(1);
 		}
 		let template = projectConfig.template;
-		if (opts.template !== void 0) {
-			const templateInput = stripQuotes(opts.template);
-			const templateResult = TemplateTypeSchema.safeParse(templateInput);
-			if (!templateResult.success) {
-				p.log.error(`Invalid template type: ${opts.template}. Must be one of: cli, web-vanilla, web-app, web-fullstack`);
-				process.exit(1);
-			}
-			template = templateResult.data;
-		}
+		if (opts.template !== void 0) template = parseTemplateOption(opts.template);
 		commandResult = {
 			...opts,
 			update: true,
@@ -859,7 +1224,7 @@ Restrictions & Behavior:
 				process.exit(0);
 			}
 			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.`);
+				p.log.error(getMissingProjectConfigMessage$1(pkgPath));
 				process.exit(1);
 			}
 			update = true;
@@ -879,6 +1244,10 @@ Restrictions & Behavior:
 						label: "Web-Vanilla (Standalone)",
 						value: "web-vanilla"
 					},
+					{
+						label: "Web-Widget (Publishable)",
+						value: "web-widget"
+					},
 					{
 						label: "Web-App (React + MUI)",
 						value: "web-app"
@@ -1070,12 +1439,62 @@ var isFileRequired = (relativePath, type) => {
 	if (relativePath === "vitest.config.ts") return ![
 		"cli",
 		"web-vanilla",
+		"web-widget",
 		"web-app",
 		"web-fullstack"
 	].includes(type);
 	return true;
 };
-var isCustomConfigFile = (relativePath) => relativePath === "oxlint.config.ts" || relativePath === "oxfmt.config.ts";
+var isCustomConfigFile = (relativePath) => relativePath === "oxlint.config.ts" || relativePath === "oxfmt.config.ts" || relativePath === "stylelint.config.js";
+var toPosixPath = (filePath) => filePath.split(path.sep).join("/");
+var isOptionalCapabilityFile = (filePath) => {
+	const normalizedPath = toPosixPath(filePath);
+	return normalizedPath.startsWith(".github/workflows/") && normalizedPath !== ".github/workflows/ci.yml" && normalizedPath !== ".github/workflows/node.js.yml";
+};
+var isStarterFile = (filePath) => {
+	const normalizedPath = toPosixPath(filePath);
+	return isSeedFile(normalizedPath) || normalizedPath.startsWith("tests/e2e/") || normalizedPath.startsWith("src/demo/") || normalizedPath.endsWith(".test.ts") || normalizedPath.endsWith(".test.tsx") || normalizedPath.endsWith(".spec.ts") || normalizedPath.endsWith(".spec.tsx");
+};
+var getAddReason = (filePath) => {
+	const normalizedPath = toPosixPath(filePath);
+	if (normalizedPath === "package.json") return "Initial project metadata, dependencies, and scripts";
+	if (normalizedPath === ".npmrc") return "Package manager configuration required by the template";
+	if (normalizedPath === "pnpm-workspace.yaml") return "Workspace configuration required by pnpm";
+	if (normalizedPath === ".github/workflows/ci.yml") return "Continuous integration workflow required by the base template";
+	if (normalizedPath.startsWith(".github/workflows/")) return "GitHub workflow provided by the template";
+	if (normalizedPath.includes("lint") || normalizedPath.includes("oxc") || normalizedPath.includes("oxfmt") || normalizedPath.includes("stylelint")) return "Linting and formatting configuration required by the template";
+	if (normalizedPath.includes("tsconfig") || normalizedPath.includes("vite") || normalizedPath.includes("tsdown") || normalizedPath.includes("playwright") || normalizedPath.includes("typedoc")) return "Build, test, or documentation tooling configuration required by the template";
+	return "Template tooling file required for this project type";
+};
+var getModifyReason = (filePath) => {
+	const normalizedPath = toPosixPath(filePath);
+	if (normalizedPath === "package.json") return "Update dependencies, scripts, and template metadata";
+	if (normalizedPath === "pnpm-workspace.yaml") return "Update workspace configuration for pnpm";
+	if (normalizedPath === ".github/workflows/ci.yml" || normalizedPath === ".github/workflows/node.js.yml") return "Update continuous integration workflow to match the base template";
+	if (normalizedPath.startsWith(".github/workflows/")) return "Update GitHub workflow to match the template";
+	if (normalizedPath.includes("lint") || normalizedPath.includes("oxc") || normalizedPath.includes("oxfmt") || normalizedPath.includes("stylelint")) return "Update linting and formatting configuration";
+	if (normalizedPath.includes("tsconfig") || normalizedPath.includes("vite") || normalizedPath.includes("tsdown") || normalizedPath.includes("playwright") || normalizedPath.includes("typedoc")) return "Update build, test, or documentation tooling configuration";
+	return "Update template-managed tooling or configuration";
+};
+var getDeleteReason = (filePath) => {
+	if (toPosixPath(filePath) === "vitest.config.ts") return "File no longer required because this template uses Vite/Vitest configuration";
+	return "File no longer required for this template type";
+};
+var getUpdateFilePolicy = (filePath) => {
+	if (isOptionalCapabilityFile(filePath)) return {
+		shouldAddDuringUpdate: false,
+		reason: "Optional capability file - available but skipped during update"
+	};
+	if (isStarterFile(filePath)) return {
+		shouldAddDuringUpdate: false,
+		reason: "Starter/example project file - available but skipped during update"
+	};
+	return {
+		shouldAddDuringUpdate: true,
+		reason: getAddReason(filePath)
+	};
+};
+var formatActionSummary = (actions) => actions.map((a) => `  ${a.type.padEnd(8)} ${a.path}${a.reason === void 0 ? "" : ` - ${a.reason}`}`).join("\n");
 var buildSimpleUnifiedDiff = (filePath, before, after) => {
 	const beforeLines = before.split("\n");
 	const afterLines = after.split("\n");
@@ -1099,7 +1518,12 @@ var buildSimpleUnifiedDiff = (filePath, before, after) => {
 };
 var getTemplateArchitectureSection;
 var generateGeneratedMd;
-var isTemplateType = (value) => value === "cli" || value === "web-vanilla" || value === "web-app" || value === "web-fullstack";
+var isTemplateType = (value) => value === "cli" || value === "web-vanilla" || value === "web-widget" || value === "web-app" || value === "web-fullstack";
+var getMissingProjectConfigMessage = (pkgPath) => [
+	`No "create-template-project" configuration found in ${pkgPath}.`,
+	"The update command only runs after a project has been adopted by this tool.",
+	"Run \"create-template-project doctor --template <type> --directory <dir>\" to validate the structure, then \"create-template-project adopt --template <type> --directory <dir>\" to add the marker."
+].join(" ");
 var isRecord$1 = (value) => typeof value === "object" && value !== null;
 var parseStringRecord = (value) => {
 	if (!isRecord$1(value)) return {};
@@ -1131,9 +1555,38 @@ var parseExistingProjectPackage = (raw) => {
 		scripts: parseStringRecord(parsed.scripts),
 		dependencies: parseStringRecord(parsed.dependencies),
 		devDependencies: parseStringRecord(parsed.devDependencies),
+		peerDependencies: parseStringRecord(parsed.peerDependencies),
 		"create-template-project": typeof template === "string" && isTemplateType(template) ? { template } : void 0
 	};
 };
+var parseExactVersion = (version) => {
+	const match = /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:[-+].*)?$/u.exec(version);
+	if (match?.groups === void 0) return;
+	return [
+		Number(match.groups.major),
+		Number(match.groups.minor),
+		Number(match.groups.patch)
+	];
+};
+var isGreaterOrEqualVersion = (current, next) => {
+	const currentParts = parseExactVersion(current);
+	const nextParts = parseExactVersion(next);
+	if (currentParts === void 0 || nextParts === void 0) return false;
+	for (const [index, currentPart] of currentParts.entries()) {
+		const nextPart = nextParts[index];
+		if (currentPart > nextPart) return true;
+		if (currentPart < nextPart) return false;
+	}
+	return true;
+};
+var mergePackageRecord = (target, source, preserveExistingVersions) => {
+	const merged = { ...target };
+	for (const [name, version] of Object.entries(source)) {
+		if (preserveExistingVersions && Object.hasOwn(merged, name) && isGreaterOrEqualVersion(merged[name], version)) continue;
+		merged[name] = version;
+	}
+	return merged;
+};
 var parseTemplatePackageJson = (raw) => {
 	const parsed = JSON.parse(raw);
 	if (!isRecord$1(parsed)) return {};
@@ -1180,16 +1633,19 @@ var generateProject = async (opts) => {
 	const depConfig = parseDependencyConfig(await fs.readFile(depConfigPath, "utf8"));
 	const addedDeps = [];
 	const resolveDeps = (deps = {}) => {
-		for (const dep of Object.keys(deps)) if (Object.hasOwn(depConfig.dependencies, dep)) {
-			const config = depConfig.dependencies[dep];
-			deps[dep] = config.version;
-			addedDeps.push({
-				name: dep,
-				description: config.description
-			});
-		} else {
-			log.warn(`Dependency "${dep}" not found in central configuration. Using empty version.`);
-			debug$1(`Dependency "${dep}" missing in config`);
+		for (const [dep, version] of Object.entries(deps)) {
+			if (version.length > 0 && version !== dep) continue;
+			if (Object.hasOwn(depConfig.dependencies, dep)) {
+				const config = depConfig.dependencies[dep];
+				deps[dep] = config.version;
+				addedDeps.push({
+					name: dep,
+					description: config.description
+				});
+			} else {
+				log.warn(`Dependency "${dep}" not found in central configuration. Using empty version.`);
+				debug$1(`Dependency "${dep}" missing in config`);
+			}
 		}
 	};
 	let finalPkg = {
@@ -1215,18 +1671,30 @@ var generateProject = async (opts) => {
 	const pkgPath = path.join(projectDir, "package.json");
 	if (isUpdate && await pathExists(pkgPath)) {
 		debug$1("Loading existing package.json for update");
+		const defaultPkg = finalPkg;
 		const existingPkg = parseExistingProjectPackage(await fs.readFile(pkgPath, "utf8"));
-		if (!existingPkg["create-template-project"]) throw new Error(`No "create-template-project" configuration found in ${pkgPath}. The update command can only be used on projects created with this tool.`);
+		if (!existingPkg["create-template-project"]) throw new Error(getMissingProjectConfigMessage(pkgPath));
 		finalPkg = {
-			...finalPkg,
 			...existingPkg,
+			name: existingPkg.name ?? defaultPkg.name,
+			version: existingPkg.version ?? defaultPkg.version,
+			private: existingPkg.private,
+			description: existingPkg.description ?? defaultPkg.description,
+			keywords: existingPkg.keywords ?? defaultPkg.keywords,
+			homepage: existingPkg.homepage ?? defaultPkg.homepage,
+			bugs: existingPkg.bugs ?? defaultPkg.bugs,
+			license: existingPkg.license ?? defaultPkg.license,
+			author: existingPkg.author ?? defaultPkg.author,
+			repository: existingPkg.repository ?? defaultPkg.repository,
+			type: existingPkg.type ?? defaultPkg.type,
 			"create-template-project": {
 				...existingPkg["create-template-project"],
 				template: type
 			},
 			scripts: { ...existingPkg.scripts },
 			dependencies: { ...existingPkg.dependencies },
-			devDependencies: { ...existingPkg.devDependencies }
+			devDependencies: { ...existingPkg.devDependencies },
+			peerDependencies: { ...existingPkg.peerDependencies }
 		};
 		debug$1("Loaded existing package.json: %O", finalPkg);
 	}
@@ -1243,14 +1711,17 @@ var generateProject = async (opts) => {
 		resolveDeps(templateDeps);
 		resolveDeps(templateDevDeps);
 		Object.assign(finalPkg.scripts, t.scripts);
-		Object.assign(finalPkg.dependencies, templateDeps);
-		Object.assign(finalPkg.devDependencies, templateDevDeps);
+		finalPkg.dependencies = mergePackageRecord(finalPkg.dependencies, templateDeps, isUpdate);
+		finalPkg.devDependencies = mergePackageRecord(finalPkg.devDependencies, templateDevDeps, isUpdate);
 		if (t.workspaces !== void 0) finalPkg.workspaces = t.workspaces;
 		const pkgPart = templatePackageParts[index];
 		if (pkgPart !== void 0) {
 			resolveDeps(pkgPart.dependencies);
 			resolveDeps(pkgPart.devDependencies);
-			mergePackageJson(finalPkg, pkgPart);
+			mergePackageJson(finalPkg, pkgPart, {
+				preserveExistingPackageFields: isUpdate,
+				preserveExistingDependencyVersions: isUpdate
+			});
 		}
 	}
 	const actions = [];
@@ -1274,13 +1745,22 @@ var generateProject = async (opts) => {
 				}
 				if (!isFileRequired(relativePath, type)) {
 					if (isUpdate && await pathExists(targetPath)) {
+						const existingContent = await fs.readFile(targetPath, "utf8");
+						plannedDiffs.push({
+							path: relativePath,
+							before: existingContent,
+							after: ""
+						});
 						actions.push({
 							type: "DELETE",
 							path: relativePath,
-							reason: "File no longer required for this template type"
+							reason: getDeleteReason(relativePath)
 						});
-						pendingOperations.push(async () => {
-							await fs.rm(targetPath, { force: true });
+						pendingOperations.push({
+							path: relativePath,
+							run: async () => {
+								await fs.rm(targetPath, { force: true });
+							}
 						});
 					}
 					continue;
@@ -1289,7 +1769,7 @@ var generateProject = async (opts) => {
 					relativePath = relativePath.slice(1);
 					targetPath = path.join(projectDir, relativePath);
 				}
-				if (isUpdate && (relativePath === "oxlint.config.ts" || relativePath === "oxfmt.config.ts")) {
+				if (isUpdate && isCustomConfigFile(relativePath)) {
 					actions.push({
 						type: "SKIP",
 						path: relativePath,
@@ -1313,36 +1793,50 @@ var generateProject = async (opts) => {
 						const action = {
 							type: "MODIFY",
 							path: finalRelativePath,
-							reason: "Template tooling or configuration update"
+							reason: getModifyReason(finalRelativePath)
 						};
 						actions.push(action);
-						pendingOperations.push(async () => {
-							if (finalRelativePath === "oxc.config.ts") {
-								await fs.writeFile(finalTargetPath, content);
-								action.type = "UPDATED";
-								action.reason = "Default config was updated to the latest template version";
-								log.info(`✔ Updated: ${finalRelativePath}`);
-							} else {
-								const result = await mergeFile(finalTargetPath, existingContent, content, log);
-								if (result === "merged") {
-									action.type = "MERGE";
-									action.reason = "Merged template updates with your manual changes";
-									action.recommendedAction = "Review changes for correct integration";
-									log.info(`ℹ Merged: ${finalRelativePath}`);
-								} else if (result === "conflict") {
-									action.type = "CONFLICT";
-									action.reason = "Conflicting changes between template and your code";
-									action.recommendedAction = "Resolve git conflict markers in this file";
-									log.warn(`⚠ Conflict: ${finalRelativePath}`);
-								} else if (result === "updated") {
+						pendingOperations.push({
+							path: finalRelativePath,
+							run: async () => {
+								if (finalRelativePath === "oxc.config.ts") {
+									await fs.writeFile(finalTargetPath, content);
 									action.type = "UPDATED";
-									action.reason = "File was updated to the latest template version";
+									action.reason = "Default config was updated to the latest template version";
 									log.info(`✔ Updated: ${finalRelativePath}`);
+								} else {
+									const result = await mergeFile(finalTargetPath, existingContent, content, log);
+									if (result === "merged") {
+										action.type = "MERGE";
+										action.reason = "Merged template updates with your manual changes";
+										action.recommendedAction = "Review changes for correct integration";
+										log.info(`ℹ Merged: ${finalRelativePath}`);
+									} else if (result === "conflict") {
+										action.type = "CONFLICT";
+										action.reason = "Conflicting changes between template and your code";
+										action.recommendedAction = "Resolve git conflict markers in this file";
+										log.warn(`⚠ Conflict: ${finalRelativePath}`);
+									} else if (result === "updated") {
+										action.type = "UPDATED";
+										action.reason = "File was updated to the latest template version";
+										log.info(`✔ Updated: ${finalRelativePath}`);
+									}
 								}
 							}
 						});
 					}
 				} else if (!exists) {
+					if (isUpdate) {
+						const policy = getUpdateFilePolicy(finalRelativePath);
+						if (!policy.shouldAddDuringUpdate) {
+							actions.push({
+								type: "SKIP",
+								path: finalRelativePath,
+								reason: policy.reason
+							});
+							continue;
+						}
+					}
 					plannedDiffs.push({
 						path: finalRelativePath,
 						before: "",
@@ -1351,13 +1845,16 @@ var generateProject = async (opts) => {
 					actions.push({
 						type: "ADD",
 						path: finalRelativePath,
-						reason: "New template file added"
+						reason: getAddReason(finalRelativePath)
 					});
-					pendingOperations.push(async () => {
-						await fs.mkdir(path.dirname(finalTargetPath), { recursive: true });
-						await fs.writeFile(finalTargetPath, content);
-						const normalizedPath = finalRelativePath.split(path.sep).join("/");
-						if (normalizedPath.startsWith(".husky/") && !normalizedPath.endsWith("/")) await fs.chmod(finalTargetPath, 493);
+					pendingOperations.push({
+						path: finalRelativePath,
+						run: async () => {
+							await fs.mkdir(path.dirname(finalTargetPath), { recursive: true });
+							await fs.writeFile(finalTargetPath, content);
+							const normalizedPath = finalRelativePath.split(path.sep).join("/");
+							if (normalizedPath.startsWith(".husky/") && !normalizedPath.endsWith("/")) await fs.chmod(finalTargetPath, 493);
+						}
 					});
 				}
 			}
@@ -1382,13 +1879,22 @@ var generateProject = async (opts) => {
 			}
 			if (!isFileRequired(file.path, type)) {
 				if (isUpdate && await pathExists(targetPath)) {
+					const existingContent = await fs.readFile(targetPath, "utf8");
+					plannedDiffs.push({
+						path: file.path,
+						before: existingContent,
+						after: ""
+					});
 					actions.push({
 						type: "DELETE",
 						path: file.path,
-						reason: "File no longer required for this template type"
+						reason: getDeleteReason(file.path)
 					});
-					pendingOperations.push(async () => {
-						await fs.rm(targetPath, { force: true });
+					pendingOperations.push({
+						path: file.path,
+						run: async () => {
+							await fs.rm(targetPath, { force: true });
+						}
 					});
 				}
 				continue;
@@ -1407,36 +1913,50 @@ var generateProject = async (opts) => {
 					const action = {
 						type: "MODIFY",
 						path: file.path,
-						reason: "Template configuration update"
+						reason: getModifyReason(file.path)
 					};
 					actions.push(action);
-					pendingOperations.push(async () => {
-						if (file.path === "oxc.config.ts") {
-							await fs.writeFile(targetPath, content);
-							action.type = "UPDATED";
-							action.reason = "Default config was updated to the latest template version";
-							log.info(`✔ Updated: ${file.path}`);
-						} else {
-							const result = await mergeFile(targetPath, existingContent, content, log);
-							if (result === "merged") {
-								action.type = "MERGE";
-								action.reason = "Merged template updates with your manual changes";
-								action.recommendedAction = "Review changes for correct integration";
-								log.info(`ℹ Merged: ${file.path}`);
-							} else if (result === "conflict") {
-								action.type = "CONFLICT";
-								action.reason = "Conflicting changes between template and your code";
-								action.recommendedAction = "Resolve git conflict markers in this file";
-								log.warn(`⚠ Conflict: ${file.path}`);
-							} else if (result === "updated") {
+					pendingOperations.push({
+						path: file.path,
+						run: async () => {
+							if (file.path === "oxc.config.ts") {
+								await fs.writeFile(targetPath, content);
 								action.type = "UPDATED";
-								action.reason = "File was updated to the latest template version";
+								action.reason = "Default config was updated to the latest template version";
 								log.info(`✔ Updated: ${file.path}`);
+							} else {
+								const result = await mergeFile(targetPath, existingContent, content, log);
+								if (result === "merged") {
+									action.type = "MERGE";
+									action.reason = "Merged template updates with your manual changes";
+									action.recommendedAction = "Review changes for correct integration";
+									log.info(`ℹ Merged: ${file.path}`);
+								} else if (result === "conflict") {
+									action.type = "CONFLICT";
+									action.reason = "Conflicting changes between template and your code";
+									action.recommendedAction = "Resolve git conflict markers in this file";
+									log.warn(`⚠ Conflict: ${file.path}`);
+								} else if (result === "updated") {
+									action.type = "UPDATED";
+									action.reason = "File was updated to the latest template version";
+									log.info(`✔ Updated: ${file.path}`);
+								}
 							}
 						}
 					});
 				}
 			} else if (!exists) {
+				if (isUpdate) {
+					const policy = getUpdateFilePolicy(file.path);
+					if (!policy.shouldAddDuringUpdate) {
+						actions.push({
+							type: "SKIP",
+							path: file.path,
+							reason: policy.reason
+						});
+						continue;
+					}
+				}
 				plannedDiffs.push({
 					path: file.path,
 					before: "",
@@ -1445,11 +1965,14 @@ var generateProject = async (opts) => {
 				actions.push({
 					type: "ADD",
 					path: file.path,
-					reason: "New template file added"
+					reason: getAddReason(file.path)
 				});
-				pendingOperations.push(async () => {
-					await fs.mkdir(path.dirname(targetPath), { recursive: true });
-					await fs.writeFile(targetPath, content);
+				pendingOperations.push({
+					path: file.path,
+					run: async () => {
+						await fs.mkdir(path.dirname(targetPath), { recursive: true });
+						await fs.writeFile(targetPath, content);
+					}
 				});
 			}
 		}
@@ -1473,10 +1996,13 @@ var generateProject = async (opts) => {
 		actions.push({
 			type: "ADD",
 			path: ".npmrc",
-			reason: "Initial package manager configuration"
+			reason: getAddReason(".npmrc")
 		});
-		pendingOperations.push(async () => {
-			await fs.writeFile(npmrcPath, npmrcContent);
+		pendingOperations.push({
+			path: ".npmrc",
+			run: async () => {
+				await fs.writeFile(npmrcPath, npmrcContent);
+			}
 		});
 	}
 	if (pm === "pnpm" && finalPkg.workspaces) {
@@ -1496,10 +2022,13 @@ var generateProject = async (opts) => {
 			actions.push({
 				type: workspaceExists ? "MODIFY" : "ADD",
 				path: "pnpm-workspace.yaml",
-				reason: "Updated workspace configuration for pnpm"
+				reason: workspaceExists ? getModifyReason("pnpm-workspace.yaml") : getAddReason("pnpm-workspace.yaml")
 			});
-			pendingOperations.push(async () => {
-				await fs.writeFile(workspacePath, workspaceYaml);
+			pendingOperations.push({
+				path: "pnpm-workspace.yaml",
+				run: async () => {
+					await fs.writeFile(workspacePath, workspaceYaml);
+				}
 			});
 		}
 		delete finalPkg.workspaces;
@@ -1521,35 +2050,50 @@ var generateProject = async (opts) => {
 		if (isUpdate) actions.push({
 			type: "MODIFY",
 			path: "package.json",
-			reason: "Updated dependencies and scripts to match latest template"
+			reason: getModifyReason("package.json")
 		});
 		else actions.push({
 			type: "ADD",
 			path: "package.json",
-			reason: "Initial project configuration"
+			reason: getAddReason("package.json")
 		});
-		pendingOperations.push(async () => {
-			debug$1("Writing final consolidated package.json to: %s", pkgPath);
-			await fs.writeFile(pkgPath, newPkgContent);
+		pendingOperations.push({
+			path: "package.json",
+			run: async () => {
+				debug$1("Writing final consolidated package.json to: %s", pkgPath);
+				await fs.writeFile(pkgPath, newPkgContent);
+			}
 		});
 	}
 	if (isUpdate && actions.length > 0 && process.env.NODE_ENV !== "test") {
-		const summary = actions.filter((a) => a.type !== "SKIP").map((a) => `  ${a.type.padEnd(8)} ${a.path}`).join("\n");
+		const summary = formatActionSummary(actions);
 		if (summary) {
 			const relativeProjectDir = path.relative(process.cwd(), projectDir) || ".";
 			p.note(summary, `Planned changes in ${relativeProjectDir}:`);
+			const syncedPaths = /* @__PURE__ */ new Set();
+			const syncFile = async (filePath) => {
+				const operation = pendingOperations.find((candidate) => candidate.path === filePath && !syncedPaths.has(candidate.path));
+				if (operation === void 0) {
+					p.note("This file has no pending sync operation.", `Sync: ${filePath}`);
+					return;
+				}
+				await operation.run();
+				syncedPaths.add(filePath);
+				p.log.success(`Synced ${filePath}`);
+			};
 			let confirmed = false;
 			while (!confirmed) {
-				const action = await p.select({
-					message: "Choose next step:",
+				const selectedFile = await p.select({
+					message: "Choose file to inspect or sync:",
 					options: [
+						...plannedDiffs.map((entry) => ({
+							label: entry.path,
+							value: entry.path,
+							hint: `${syncedPaths.has(entry.path) ? "synced; " : ""}${actions.find((candidate) => candidate.path === entry.path)?.reason ?? "Planned file change"}`
+						})),
 						{
-							label: "Show diff",
-							value: "show-diff"
-						},
-						{
-							label: "Apply changes",
-							value: "apply"
+							label: "Continue update",
+							value: "continue-update"
 						},
 						{
 							label: "Cancel update",
@@ -1557,24 +2101,57 @@ var generateProject = async (opts) => {
 						}
 					]
 				});
-				if (p.isCancel(action) || action === "cancel") {
+				if (p.isCancel(selectedFile) || selectedFile === "cancel") {
 					p.cancel("Update cancelled.");
 					process.exit(0);
 				}
-				if (action === "show-diff") {
-					for (const entry of plannedDiffs) {
-						const diff = buildSimpleUnifiedDiff(entry.path, entry.before, entry.after);
-						p.note(diff, `Diff preview: ${entry.path}`);
+				if (selectedFile === "continue-update") {
+					confirmed = true;
+					continue;
+				}
+				const fileActionOptions = syncedPaths.has(selectedFile) ? [{
+					label: "Show diff",
+					value: "show-diff"
+				}, {
+					label: "Back",
+					value: "back"
+				}] : [
+					{
+						label: "Show diff",
+						value: "show-diff"
+					},
+					{
+						label: "Sync file",
+						value: "sync-file"
+					},
+					{
+						label: "Back",
+						value: "back"
+					}
+				];
+				const fileAction = await p.select({
+					message: `Choose action for ${selectedFile}:`,
+					options: fileActionOptions
+				});
+				if (p.isCancel(fileAction) || fileAction === "back") continue;
+				if (fileAction === "show-diff") {
+					const selectedDiff = plannedDiffs.find((entry) => entry.path === selectedFile);
+					if (selectedDiff !== void 0) {
+						const diff = buildSimpleUnifiedDiff(selectedDiff.path, selectedDiff.before, selectedDiff.after);
+						p.note(diff, `Diff preview: ${selectedDiff.path}`);
 					}
 					continue;
 				}
-				confirmed = true;
+				if (fileAction === "sync-file") await syncFile(selectedFile);
 			}
+			await pendingOperations.filter((operation) => !syncedPaths.has(operation.path)).reduce(async (previous, operation) => {
+				await previous;
+				await operation.run();
+			}, Promise.resolve());
 		} else log.info("No changes detected.");
-	}
-	await pendingOperations.reduce(async (previous, operation) => {
+	} else await pendingOperations.reduce(async (previous, operation) => {
 		await previous;
-		await operation();
+		await operation.run();
 	}, Promise.resolve());
 	const states = {
 		gitInitialized: false,
@@ -1911,6 +2488,20 @@ getTemplateArchitectureSection = (template) => {
 			"- 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-widget": return [
+			"## 🏗️ Web Widget Architecture",
+			"A publishable native TypeScript widget package with a Vite-powered demo site.",
+			"",
+			"### Source Files Generated",
+			"- **`src/lib/`**: The public widget implementation, exports, and optional React adapter subpath.",
+			"- **`src/styles/index.css`**: The exported widget stylesheet available through the package `./styles.css` subpath.",
+			"- **`src/demo/`**: The demo application used by Vite, Playwright, and screenshot generation.",
+			"",
+			"### How to Enhance",
+			"- Keep reusable package logic in `src/lib/` and demo-only behavior in `src/demo/`.",
+			"- Update `tsdown.config.ts` and `package.json` exports together when adding public entry points.",
+			"- Run `pnpm run docs:api` and `pnpm run screenshot` before publishing visible API or demo changes."
+		];
 		case "web-app": return [
 			"## 🏗️ Web App Architecture",
 			"A robust React SPA configured with MUI components and TanStack Query.",