centoui-cli 1.0.0-alpha.36 → 1.0.0-alpha.38

package/dist/index.d.mts

@@ -16,7 +16,12 @@ type GlobalsRegistry = {
  */
 type ComponentRegistry = {
   /** Unique identifier for the component. Matches its registry filename (e.g. `"button"`). */name: string; /** Short human-readable description shown in CLI output. */
-  description?: string;
+  description: string;
+  /**
+   * Whether this component requires the global utils file (e.g., isSlotEmpty).
+   * If true, the utils file will be written when this component is installed.
+   */
+  needsUtils?: boolean;
   /**
    * Source file paths relative to `packages/core/src/`.
    * All paths start with `components/` by convention (e.g. `"components/button/button.vue"`).
@@ -27,13 +32,13 @@ type ComponentRegistry = {
    * Names of other CentoUI components that must be installed alongside this one.
    * The CLI resolves the full dependency tree automatically.
    */
-  componentDeps: string[];
+  componentDeps?: string[];
   /**
    * NPM packages required specifically by this component,
    * in addition to the global dependencies defined in `GlobalsRegistry`.
    * Keys are package names; values are semver version ranges.
    */
-  packageDeps: Record<string, string>;
+  packageDeps?: Record<string, string>;
 };
 /**
  * The complete CentoUI registry — the `index.json` file fetched from GitHub.

package/dist/index.mjs

@@ -8,7 +8,7 @@ import { loadConfig } from "c12";
 //#endregion
 //#region src/constants.ts
 /** CentoUI current package version, sourced directly from package.json. */
-const VERSION = "1.0.0-alpha.36";
+const VERSION = "1.0.0-alpha.38";
 /** File name for the user-side CentoUI config (created by `centoui init`). */
 const CONFIG_FILE_NAME = "centoui.config.ts";
 /**
@@ -68,7 +68,7 @@ async function installMissingPackages(requiredPackages, cwd, onProgress) {
 		...packageJson.dependencies,
 		...packageJson.devDependencies
 	};
-	const packagesToInstall = Object.entries(requiredPackages).filter(([name, version]) => alreadyInstalled[name] !== version).map(([name, version]) => `${name}@${version}`);
+	const packagesToInstall = Object.entries(requiredPackages).filter(([name]) => !(name in alreadyInstalled)).map(([name, version]) => `${name}@${version}`);
 	if (packagesToInstall.length === 0) return "All packages already up to date";
 	try {
 		for (const [index, pkg] of packagesToInstall.entries()) {
@@ -128,16 +128,16 @@ function validateNonEmptyPath(value) {
 //#endregion
 //#region src/utils/file-system-utils.ts
 /**
-* Converts a registry-relative file path into the absolute destination path
+* Converts a registry-relative component file path into the absolute destination path
 * inside the user's project.
 *
-* Registry file paths always begin with `components/` (e.g.
+* Registry component file paths always begin with `components/` (e.g.
 * `"components/button/button.vue"`). This function strips that leading segment
 * and joins the remainder with the user's configured components directory so
 * that `"components/button/button.vue"` becomes, for example,
 * `"/home/user/my-app/src/components/centoui/button/button.vue"`.
 *
-* @param registryFilePath - Path as it appears in the component's registry entry
+* @param registryComponentFilePath - Path as it appears in the component's registry entry
 *                           (always starts with `"components/"`).
 * @param config - The loaded CentoUI project configuration.
 * @param cwd - Absolute path to the project root.
@@ -145,11 +145,11 @@ function validateNonEmptyPath(value) {
 *
 * @example
 * // config.componentsDir = 'src/components/centoui', cwd = '/home/user/my-app'
-* mapRegistryPathToProjectDest('components/button/button.vue', config, cwd)
+* mapComponentsRegistryPathToProjectDest('components/button/button.vue', config, cwd)
 * // → '/home/user/my-app/src/components/centoui/button/button.vue'
 */
-function mapRegistryPathToProjectDest(registryFilePath, config, cwd) {
-	const pathWithoutRegistryPrefix = registryFilePath.replace(/^components\//, "");
+function mapComponentsRegistryPathToProjectDest(registryComponentFilePath, config, cwd) {
+	const pathWithoutRegistryPrefix = registryComponentFilePath.replace(/^components\//, "");
 	return join(cwd, config.componentsDir, pathWithoutRegistryPrefix);
 }
 /**
@@ -185,7 +185,10 @@ async function writeFileWithDirs(filePath, content) {
 */
 async function confirmOverwriteIfExists(label, path) {
 	if (!await fsExtra.pathExists(path)) return true;
-	const answer = await confirm({ message: `"${label}" already exists. Overwrite?` });
+	const answer = await confirm({
+		message: `"${label}" already exists. Overwrite?`,
+		initialValue: false
+	});
 	if (isCancel(answer)) {
 		cancel("Operation cancelled.");
 		process.exit(0);
@@ -337,7 +340,7 @@ function resolveComponentWithDependencies(componentName, registry, visited = /*
 	const entry = registry.components.find((component) => component.name === componentName);
 	if (!entry) throw new Error(`[resolveComponentWithDependencies] Component "${componentName}" not found in registry.`);
 	result.set(componentName, entry);
-	for (const dep of entry.componentDeps) for (const [depName, depEntry] of resolveComponentWithDependencies(dep, registry, visited)) result.set(depName, depEntry);
+	for (const dep of entry?.componentDeps || []) for (const [depName, depEntry] of resolveComponentWithDependencies(dep, registry, visited)) result.set(depName, depEntry);
 	return result;
 }
 /**
@@ -410,9 +413,8 @@ async function fetchUtilsFileContent() {
 * Bootstraps a new CentoUI project in the current working directory.
 *
 * Flow:
-*  1. Prompt the user for the components directory and theme CSS file path.
-*  2. Ask upfront whether to overwrite any of the three output paths
-*     (config file, theme CSS, components directory) if they already exist.
+*  1. Prompt the user for the components directory, theme CSS file path, and utils file path.
+*  2. Ask upfront whether to overwrite the config file, theme CSS, components directory paths if they already exist.
 *  3. Write the config file, fetch and write the theme CSS, prepare the
 *     components directory, and install global npm dependencies.
 */
@@ -438,7 +440,7 @@ function init() {
 						validate: validateNonEmptyPath
 					}),
 					utilsFilePath: () => text({
-						message: "Path for the utils file",
+						message: "Path for the utils file (written on demand)",
 						initialValue: "src/utils/centoui-utils.ts",
 						validate: validateNonEmptyPath
 					})
@@ -449,19 +451,16 @@ function init() {
 				const configPath = join(cwd, CONFIG_FILE_NAME);
 				const themePath = join(cwd, directories.themeFilePath);
 				const componentsPath = join(cwd, directories.componentDir);
-				const utilsPath = join(cwd, directories.utilsFilePath);
 				const shouldWriteConfig = await confirmOverwriteIfExists(CONFIG_FILE_NAME, configPath);
 				const shouldWriteTheme = await confirmOverwriteIfExists(directories.themeFilePath, themePath);
 				const shouldWriteComponentsDir = await confirmOverwriteIfExists(directories.componentDir, componentsPath);
-				const shouldWriteUtils = await confirmOverwriteIfExists(directories.utilsFilePath, utilsPath);
 				let registry;
 				await tasks([
 					{
 						title: "Fetching config defaults",
 						task: async () => {
 							if (!shouldWriteConfig) return `Skipped — "${CONFIG_FILE_NAME}" already exists`;
-							const userConfigContent = await buildUserDefaultConfigFileContent(directories.themeFilePath, directories.componentDir, directories.utilsFilePath);
-							await fsExtra.outputFile(configPath, userConfigContent, "utf-8");
+							await writeFileWithDirs(configPath, await buildUserDefaultConfigFileContent(directories.themeFilePath, directories.componentDir, directories.utilsFilePath));
 							return `${CONFIG_FILE_NAME} written`;
 						}
 					},
@@ -469,20 +468,10 @@ function init() {
 						title: "Fetching theme CSS",
 						task: async () => {
 							if (!shouldWriteTheme) return `Skipped — "${directories.themeFilePath}" already exists`;
-							const themeContent = await fetchThemeCSSContent();
-							await fsExtra.outputFile(themePath, themeContent, "utf-8");
+							await writeFileWithDirs(themePath, await fetchThemeCSSContent());
 							return `${directories.themeFilePath} written`;
 						}
 					},
-					{
-						title: "Writing utils file",
-						task: async () => {
-							if (!shouldWriteUtils) return `Skipped — "${directories.utilsFilePath}" already exists`;
-							const utilsContent = await fetchUtilsFileContent();
-							await fsExtra.outputFile(utilsPath, utilsContent, "utf-8");
-							return `${directories.utilsFilePath} written`;
-						}
-					},
 					{
 						title: "Preparing components directory",
 						task: async () => {
@@ -585,7 +574,8 @@ async function checkIsComponentInstalled(componentName, config, cwd) {
 *  1. Resolve the full dependency tree for every requested component.
 *  2. Ask the user upfront whether to overwrite any that already exist.
 *  3. Fetch and write the source files for components the user approved.
-*  4. Install any npm packages required by the components being written.
+*  4. Fetch and write the utils file if it doesn't exist but is required by the components.
+*  5. Install any npm packages required by the components being written.
 */
 function add() {
 	return defineCommand({
@@ -617,19 +607,32 @@ function add() {
 				const packageDepsToInstall = {};
 				for (const [name, entry] of allComponents) if (writeDecisions.get(name)) Object.assign(packageDepsToInstall, entry.packageDeps);
 				const approvedComponents = Array.from(allComponents.entries()).filter(([name]) => writeDecisions.get(name));
-				await tasks([...approvedComponents.map(([name, entry]) => ({
-					title: `Installing ${name}`,
-					task: async () => {
-						for (const registryFilePath of entry.files) {
-							const content = await fetchRegistryFileContent(registryFilePath);
-							await writeFileWithDirs(mapRegistryPathToProjectDest(registryFilePath, config, cwd), content);
+				const needsUtils = Array.from(approvedComponents).some(([, entry]) => entry.needsUtils === true);
+				const utilsPath = join(cwd, config.utilsFilePath);
+				const utilsFileExists = await fsExtra.pathExists(utilsPath);
+				await tasks([
+					...approvedComponents.map(([name, entry]) => ({
+						title: `Installing ${name}`,
+						task: async () => {
+							for (const registryFilePath of entry.files) {
+								const content = await fetchRegistryFileContent(registryFilePath);
+								await writeFileWithDirs(mapComponentsRegistryPathToProjectDest(registryFilePath, config, cwd), content);
+							}
+							return `${name} installed (${entry.files.length} file(s))`;
 						}
-						return `${name} installed (${entry.files.length} file(s))`;
-					}
-				})), {
-					title: "Installing packages",
-					task: async (message) => installMissingPackages(packageDepsToInstall, cwd, message)
-				}]);
+					})),
+					{
+						title: "Installing packages",
+						task: async (message) => installMissingPackages(packageDepsToInstall, cwd, message)
+					},
+					...needsUtils && !utilsFileExists ? [{
+						title: "Writing utils file",
+						task: async () => {
+							await writeFileWithDirs(utilsPath, await fetchUtilsFileContent());
+							return `${config.utilsFilePath} written`;
+						}
+					}] : []
+				]);
 				const skippedNames = Array.from(writeDecisions.entries()).filter(([, shouldWrite]) => !shouldWrite).map(([name]) => name);
 				note([
 					`Installed  > ${approvedComponents.map(([name]) => name).join(", ") || "none"}`,
@@ -660,6 +663,7 @@ function add() {
 *     know which of this component's packages become orphaned.
 *  4. Ask for confirmation, then delete the component directory and remove
 *     any newly orphaned npm packages.
+*  5. Check if any utils file is no longer needed and remove it if so(with confirmation from the user).
 */
 function remove() {
 	return defineCommand({
@@ -689,14 +693,17 @@ function remove() {
 				for (const name of remainingNames) {
 					const entry = registry.components.find((component) => component.name === name);
 					if (!entry) continue;
-					if (entry.componentDeps.includes(componentName)) dependents.add(name);
-					Object.assign(packagesStillNeeded, entry.packageDeps);
+					if (entry.componentDeps?.includes(componentName)) dependents.add(name);
+					Object.assign(packagesStillNeeded, entry.packageDeps || {});
 				}
 				if (dependents.size > 0) {
 					const list = Array.from(dependents).map((dependent) => `  · ${dependent}`).join("\n");
 					throw new Error(`Cannot remove "${componentName}" — the following installed components depend on it:\n${list}`);
 				}
-				const confirmed = await confirm({ message: `Remove "${componentName}"?` });
+				const confirmed = await confirm({
+					message: `Remove "${componentName}"?`,
+					initialValue: false
+				});
 				if (isCancel(confirmed) || !confirmed) {
 					cancel("Removal cancelled.");
 					process.exit(0);
@@ -709,10 +716,25 @@ function remove() {
 					}
 				}, {
 					title: "Removing orphaned packages",
-					task: async (message) => removeOrphanedPackages(targetEntry.packageDeps, packagesStillNeeded, cwd, message)
+					task: async (message) => removeOrphanedPackages(targetEntry.packageDeps || {}, packagesStillNeeded, cwd, message)
 				}]);
-				const removedPackages = Object.keys(targetEntry.packageDeps).filter((pkg) => !(pkg in packagesStillNeeded));
+				const removedPackages = Object.keys(targetEntry.packageDeps || {}).filter((pkg) => !(pkg in packagesStillNeeded));
 				if (removedPackages.length > 0) note(removedPackages.map((pkg) => `  · ${pkg}`).join("\n"), "Packages removed");
+				if (!remainingNames.some((name) => {
+					return registry.components.find((c) => c.name === name)?.needsUtils === true;
+				})) {
+					const utilsPath = join(cwd, config.utilsFilePath);
+					if (await fsExtra.pathExists(utilsPath)) {
+						const shouldDeleteUtils = await confirm({
+							message: "Delete utils file? (no components require it anymore)",
+							initialValue: false
+						});
+						if (!isCancel(shouldDeleteUtils) && shouldDeleteUtils) {
+							await fsExtra.remove(utilsPath);
+							note(`${config.utilsFilePath} deleted`, "Utils file removed");
+						}
+					}
+				}
 				outro("All set!");
 			} catch (error) {
 				log.error(`Failed to remove component: ${error}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "centoui-cli",
   "type": "module",
-  "version": "1.0.0-alpha.36",
+  "version": "1.0.0-alpha.38",
   "private": false,
   "description": "Official CLI for CentoUI.",
   "keywords": [