centoui-cli 0.2.2 → 1.0.0-alpha.0

package/dist/index.d.mts

@@ -1,39 +1,61 @@
 //#region src/types.d.ts
 /**
- * Global registry mirroring the JSON schema shapes
- * Defines global configurations required by all CentoUI components
+ * Mirrors the `globals.json` registry schema.
+ * Defines properties that every CentoUI project must have.
  */
 type GlobalsRegistry = {
   /**
-   * NPM packages that must be installed in every CentoUI project.
-   * Keys are package names, values are semver version ranges.
+   * NPM packages that are required in every CentoUI project.
+   * Keys are package names; values are semver version ranges (e.g. `"^4.2.2"`).
    */
   packageDeps: Record<string, string>;
 };
 /**
- * Component registry mirroring the JSON schema shapes
+ * Mirrors the `component.json` registry schema.
  * Describes a single installable CentoUI component.
  */
 type ComponentRegistry = {
-  /** Unique component identifier. */name: string; /** Short human-readable description. */
-  description?: string; /** Paths to all source files that belong to this component, relative to the repository root. */
-  files: string[]; /** Names of other CentoUI components that must be installed alongside this one. */
-  componentDeps: string[]; /** NPM packages required specifically by this component, beyond the global dependencies. */
+  /** Unique identifier for the component. Matches its registry filename (e.g. `"button"`). */name: string; /** Short human-readable description shown in CLI output. */
+  description?: string;
+  /**
+   * Source file paths relative to `packages/core/src/`.
+   * All paths start with `components/` by convention (e.g. `"components/button/button.vue"`).
+   * The CLI fetches each file from GitHub and writes it into the user's components directory.
+   */
+  files: string[];
+  /**
+   * Names of other CentoUI components that must be installed alongside this one.
+   * The CLI resolves the full dependency tree automatically.
+   */
+  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>;
 };
-/** CentoUI registry, representing the complete component library. */
+/**
+ * The complete CentoUI registry — the `index.json` file fetched from GitHub.
+ * Contains global project dependencies and the full list of installable components.
+ */
 type Registry = {
-  /** Global configurations required by all CentoUI components */globals: GlobalsRegistry; /** All installable CentoUI components */
+  /** Global properties that every CentoUI project must have. */globals: GlobalsRegistry; /** All components that can be installed with `centoui add`. */
   components: ComponentRegistry[];
 };
-/** CentoUI configuration */
+/**
+ * The user-side CentoUI configuration, stored in `centoui.config.ts`.
+ * Generated by `centoui init` and consumed by every subsequent CLI command.
+ */
 type CentoUIConfig = {
-  /** CentoUI library version */version: string; /** Directory path where components will be installed */
-  componentsDir: string; /** Path to the CSS file where theme and component styles will be generated */
+  /** The CentoUI version this project was initialised with. */version: string; /** Relative path (from project root) to the directory where components are installed. */
+  componentsDir: string; /** Relative path (from project root) to the CSS file that receives theme and component styles. */
   themeFilePath: string;
   /**
-   * Maps internal icon names to Iconify IDs
-   * @example { menu: 'lucide:menu' }
+   * Maps internal CentoUI icon slot names to Iconify icon IDs.
+   * Components reference icon slots by their internal name so you can swap icon libraries freely.
+   *
+   * @example { menu: 'lucide:menu', close: 'lucide:x' }
    */
   icons: Record<string, string>;
 };

package/dist/index.mjs

@@ -3,109 +3,181 @@ import { defineCommand, runMain } from "citty";
 import { cancel, confirm, group, intro, isCancel, log, note, outro, tasks, text } from "@clack/prompts";
 import { dirname, join } from "pathe";
 import fsExtra from "fs-extra";
-import { addDependency } from "nypm";
+import { addDependency, removeDependency } from "nypm";
 import { pathToFileURL } from "node:url";
 //#endregion
 //#region src/constants.ts
-/** CentoUI current package version */
-const VERSION = "0.2.2";
-/** CentoUI config file name */
+/** CentoUI current package version, sourced directly from package.json. */
+const VERSION = "1.0.0-alpha.0";
+/** File name for the user-side CentoUI config (created by `centoui init`). */
 const CONFIG_FILE_NAME = "centoui.config.ts";
-/** CentoUI registry file name */
-const REGISTRY_FILE_NAME = "index.json";
-/** CentoUI core base API URL */
-const BASE_URL = "https://raw.githubusercontent.com/favorodera/centoui/main/packages/core/src";
-/** CentoUI registry files URL */
-const REGISTRY_URL = `${BASE_URL}/registry`;
-/** CentoUI theme file URL */
-const THEME_URL = `${BASE_URL}/css/centoui.css`;
-/** GitHub API fetch headers */
-const FETCH_HEADERS = {
+/**
+* Base URL for the CentoUI core package source tree on GitHub.
+* Every other URL in this file is derived from this one.
+*
+* The path ends at `src/` so that registry and component paths from the
+* registry (e.g. `components/button/button.vue`) can be appended directly.
+*/
+const CORE_SRC_BASE_URL = `https://raw.githubusercontent.com/favorodera/centoui/refs/tags/v${VERSION}/packages/core/src`;
+/** Full URL to the registry index file that lists every available component. */
+const REGISTRY_INDEX_URL = `${`${CORE_SRC_BASE_URL}/registry`}/index.json`;
+/**
+* Full URL to the CentoUI CSS theme file.
+* This file is written to the user's project during `centoui init`.
+*/
+const THEME_CSS_URL = `${CORE_SRC_BASE_URL}/css/centoui.css`;
+/**
+* HTTP headers required when fetching raw content from the GitHub API.
+* These ensure we get the raw file bytes, not GitHub's HTML wrapper.
+*/
+const GITHUB_RAW_FETCH_HEADERS = {
 	"Accept": "application/vnd.github.raw+json",
 	"X-GitHub-Api-Version": "2026-03-10"
 };
 //#endregion
 //#region src/utils/package-utils.ts
 /**
-* Install packages that are missing or on a different version.
-* Reads the project's `package.json` to diff against what's already installed.
-* nypm auto-detects the package manager from lockfiles (npm / pnpm / yarn / bun).
-*
-* @param packages - Map of package name → required version
-* @param cwd - Root of the project to install into
-* @param onProgress - Optional callback fired with a status string per package
-* @returns A human-readable summary string (used as the task return value in clack)
+* Installs any packages from `requiredPackages` that are missing from — or at
+* a different version than what is listed in — the project's `package.json`.
+*
+* Already-satisfied packages are skipped entirely to avoid unnecessary network
+* traffic and lockfile churn. The package manager is auto-detected from
+* lockfiles by nypm (npm / pnpm / yarn / bun).
+*
+* @param requiredPackages - Map of `packageName → semver version range`.
+* @param cwd - Absolute path to the project root (must contain `package.json`).
+* @param onProgress - Optional callback fired before each `addDependency` call
+*                     with a `"[n/total] package@version"` string.
+* @returns Human-readable summary (e.g. `"Installed 3 package(s)"`).
+* @throws If reading `package.json` or running the package manager fails.
 */
-async function installPackages(packages, cwd, onProgress) {
-	if (Object.keys(packages).length === 0) return "No packages to install";
+async function installMissingPackages(requiredPackages, cwd, onProgress) {
+	if (Object.keys(requiredPackages).length === 0) return "No packages to install";
 	const packageJson = await fsExtra.readJson(join(cwd, "package.json")).catch(() => ({}));
-	const installedPackages = {
+	const alreadyInstalled = {
 		...packageJson.dependencies,
 		...packageJson.devDependencies
 	};
-	const packagesToInstall = Object.entries(packages).filter(([packageName, version]) => installedPackages[packageName] !== version).map(([packageName, version]) => `${packageName}@${version}`);
+	const packagesToInstall = Object.entries(requiredPackages).filter(([name, version]) => alreadyInstalled[name] !== version).map(([name, version]) => `${name}@${version}`);
 	if (packagesToInstall.length === 0) return "All packages already up to date";
-	for (const [index, packageToInstall] of packagesToInstall.entries()) {
-		onProgress?.(`[${index + 1}/${packagesToInstall.length}] ${packageToInstall}`);
-		await addDependency(packageToInstall, {
-			cwd,
-			silent: true
-		});
+	try {
+		for (const [index, pkg] of packagesToInstall.entries()) {
+			onProgress?.(`[${index + 1}/${packagesToInstall.length}] ${pkg}`);
+			await addDependency(pkg, {
+				cwd,
+				silent: true
+			});
+		}
+	} catch (error) {
+		throw new Error(`[installMissingPackages] Failed to install packages: ${error}`);
 	}
 	return `Installed ${packagesToInstall.length} package(s)`;
 }
 /**
-* Validate that the given value is a non-empty string representing a valid directory path.
-* Returns `undefined` if valid, otherwise returns an error message.
+* Removes packages that were used by a component being uninstalled, but only
+* if those packages are not still required by other remaining components.
+*
+* Skips any package that appears in `packagesStillNeeded` so that shared
+* dependencies are never removed prematurely.
+*
+* @param packagesToConsider - Packages belonging to the component being removed.
+* @param packagesStillNeeded - Union of `packageDeps` from all other installed components.
+* @param cwd - Absolute path to the project root.
+* @param onProgress - Optional callback fired before each `removeDependency` call.
+* @returns Human-readable summary (e.g. `"Removed 2 package(s)"`).
+* @throws If the package manager fails to remove a dependency.
+*/
+async function removeOrphanedPackages(packagesToConsider, packagesStillNeeded, cwd, onProgress) {
+	const packagesToRemove = Object.keys(packagesToConsider).filter((name) => !(name in packagesStillNeeded));
+	if (packagesToRemove.length === 0) return "No packages to remove";
+	try {
+		for (const [index, pkg] of packagesToRemove.entries()) {
+			onProgress?.(`[${index + 1}/${packagesToRemove.length}] ${pkg}`);
+			await removeDependency(pkg, {
+				cwd,
+				silent: true
+			});
+		}
+	} catch (error) {
+		throw new Error(`[removeOrphanedPackages] Failed to remove packages: ${error}`);
+	}
+	return `Removed ${packagesToRemove.length} package(s)`;
+}
+/**
+* Validates that a value is a non-empty string usable as a file-system path.
+*
+* Intended as a `validate` callback for `@clack/prompts` text inputs.
+*
+* @param value - The raw value from the prompt.
+* @returns An error message string if invalid, or `undefined` if valid.
 */
-function validatePath(path) {
-	if (typeof path !== "string") return "Invalid input";
-	if (path.trim().length < 1) return "Path is required";
+function validateNonEmptyPath(value) {
+	if (typeof value !== "string") return "Expected a string path";
+	if (value.trim().length === 0) return "Path cannot be empty";
 }
 //#endregion
 //#region src/utils/file-system-utils.ts
 /**
-* Resolve the destination path for a component file inside the user's project.
-* Strips the leading `src/components/` registry prefix.
+* Converts a registry-relative file path into the absolute destination path
+* inside the user's project.
 *
-* e.g. with `componentsDir = './components/ui'`:
-*   src/components/button/button.vue → ./components/ui/button/button.vue
+* Registry 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 path - The path to the component file in the registry.
-* @param config - The CentoUI configuration.
-* @param cwd - The current working directory.
-* @returns The destination path for the component file.
+* @param registryFilePath - 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.
+* @returns Absolute destination path for the file in the user's project.
+*
+* @example
+* // config.componentsDir = 'src/components/centoui', cwd = '/home/user/my-app'
+* mapRegistryPathToProjectDest('components/button/button.vue', config, cwd)
+* // → '/home/user/my-app/src/components/centoui/button/button.vue'
 */
-function resolveComponentsDestinationPath(path, config, cwd) {
-	const normalizedPath = path.replace(/^components\//, "");
-	return join(cwd, config.componentsDir, normalizedPath);
+function mapRegistryPathToProjectDest(registryFilePath, config, cwd) {
+	const pathWithoutRegistryPrefix = registryFilePath.replace(/^components\//, "");
+	return join(cwd, config.componentsDir, pathWithoutRegistryPrefix);
 }
 /**
-* Write content to a destination path, creating parent directories as needed.
+* Writes `content` to `filePath`, creating every missing parent directory first.
+*
+* This is the standard way to write any file in the CLI — it ensures the
+* target directory tree exists so callers don't have to `mkdir` manually.
 *
-* @param path - The path to write the file to.
-* @param content - The content to write to the file.
+* @param filePath - Absolute path where the file should be written.
+* @param content - UTF-8 string content to write.
+* @throws If the directory cannot be created or the file cannot be written.
 */
-async function writeFile(path, content) {
+async function writeFileWithDirs(filePath, content) {
 	try {
-		await fsExtra.mkdir(dirname(path), { recursive: true });
-		await fsExtra.writeFile(path, content, "utf8");
+		await fsExtra.mkdir(dirname(filePath), { recursive: true });
+		await fsExtra.writeFile(filePath, content, "utf8");
 	} catch (error) {
-		throw new Error(`Failed to write file: ${path}: ${error}`);
+		throw new Error(`[writeFileWithDirs] Failed to write "${filePath}": ${error}`);
 	}
 }
 /**
-* Ask the user whether to overwrite a path that already exists.
-* Returns `true` immediately (no prompt) if the file does not exist yet.
+* Prompts the user to confirm before overwriting an existing path.
+*
+* If `path` does not yet exist, returns `true` immediately without showing
+* any prompt — nothing to overwrite, safe to proceed.
 *
-* @param label - Human-readable path shown in the prompt message
-* @param path - The path to the file or directory to overwrite.
+* If the user cancels the prompt (e.g. Ctrl+C), the process exits cleanly
+* with a cancellation message rather than throwing.
+*
+* @param label - Human-readable name shown in the prompt (e.g. `"centoui.config.ts"`).
+* @param path - Absolute path to the file or directory to potentially overwrite.
+* @returns `true` if the caller should write/overwrite, `false` if the user declined.
 */
-async function promptOverwrite(label, path) {
+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?` });
 	if (isCancel(answer)) {
-		cancel(`${label} operation cancelled.`);
+		cancel("Operation cancelled.");
 		process.exit(0);
 	}
 	return answer;
@@ -113,28 +185,37 @@ async function promptOverwrite(label, path) {
 //#endregion
 //#region src/utils/config-utils.ts
 /**
-* Loads the user's CentoUI configuration.
+* Loads and returns the user's CentoUI configuration from `centoui.config.ts`.
+*
+* Uses a dynamic `import()` via a `file://` URL so that TypeScript config files
+* compiled by the user's build tooling are resolved correctly at runtime.
 *
-* @param cwd - The current working directory.
-* @returns The user's CentoUI configuration.
-* @throws If the config file is not found or cannot be loaded.
+* @param cwd - Absolute path to the project root.
+* @returns The default export of `centoui.config.ts` cast as {@link CentoUIConfig}.
+* @throws If `centoui.config.ts` is not found — instructs the user to run `centoui init`.
+* @throws If the file exists but cannot be imported or does not export a default value.
 */
-async function loadUserConfig(cwd) {
+async function loadCentoUIConfig(cwd) {
+	const configFilePath = join(cwd, CONFIG_FILE_NAME);
 	try {
-		const configFilePath = join(cwd, CONFIG_FILE_NAME);
-		if (!await fsExtra.pathExists(configFilePath)) throw `No ${CONFIG_FILE_NAME} found. Run \`centoui init\` first.`;
+		if (!await fsExtra.pathExists(configFilePath)) throw new Error(`[loadCentoUIConfig] "${CONFIG_FILE_NAME}" not found in "${cwd}". Run \`centoui init\` first.`);
 		return (await import(pathToFileURL(configFilePath).href)).default;
 	} catch (error) {
-		throw new Error(`Failed to load user config: ${error}`);
+		throw new Error(`[loadCentoUIConfig] Failed to import "${configFilePath}": ${error}`);
 	}
 }
 /**
-* Generates the default user-defined CentoUI config file template.
-* @param themeFilePath - The relative path to the user's theme CSS file.
-* @param componentsDir - The relative path to the user's components directory.
-* @returns The default user-defined CentoUI config file template as a string.
+* Generates the content of a default `centoui.config.ts` file.
+*
+* The generated file uses `defineConfig` so IDEs can provide type-checking
+* and autocompletion on the config object. It pre-fills common icon mappings
+* for the built-in Lucide icon set.
+*
+* @param themeFilePath - Relative path (from project root) where the CSS theme file lives.
+* @param componentsDir - Relative path (from project root) where components will be installed.
+* @returns A string containing the complete TypeScript source for the config file.
 */
-function generateDefaultUserConfigTemplate(themeFilePath, componentsDir) {
+function buildDefaultConfigFileContent(themeFilePath, componentsDir) {
 	return `import { defineConfig } from 'centoui'
 
 export default defineConfig({
@@ -151,64 +232,111 @@ export default defineConfig({
 }
 //#endregion
 //#region src/utils/registry-utils.ts
-let registryCache = null;
+/** In-process cache so the registry is only fetched once per CLI invocation. */
+let cachedRegistry = null;
 /**
-* Fetches the complete component registry once and caches it in memory.
+* Fetches the complete component registry (`index.json`) from GitHub, caching
+* the result in memory for the lifetime of the process.
+*
+* Every other registry utility calls this internally, so the network round-trip
+* only happens once regardless of how many components are being installed.
 *
-* @returns The complete registry including components and globals.
-* @throws If the network request fails or returns a non-OK status
+* @returns The full registry object including globals and all component entries.
+* @throws If the network request fails or the server returns a non-2xx status.
 */
-async function fetchRegistry() {
-	if (registryCache) return registryCache;
-	const requestUrl = `${REGISTRY_URL}/${REGISTRY_FILE_NAME}`;
-	const response = await fetch(requestUrl, { headers: FETCH_HEADERS });
-	if (!response.ok) throw new Error(`${response.status}: ${response.statusText}`);
-	const registry = await response.json();
-	registryCache = registry;
-	return registry;
+async function fetchFullRegistry() {
+	if (cachedRegistry) return cachedRegistry;
+	let response;
+	try {
+		response = await fetch(REGISTRY_INDEX_URL, { headers: GITHUB_RAW_FETCH_HEADERS });
+	} catch (error) {
+		throw new Error(`[fetchFullRegistry] Network request to registry failed: ${error}`);
+	}
+	if (!response.ok) throw new Error(`[fetchFullRegistry] Registry responded with ${response.status} ${response.statusText} (URL: ${REGISTRY_INDEX_URL})`);
+	cachedRegistry = await response.json();
+	return cachedRegistry;
 }
 /**
-* Recursively resolves a component and all its transitive dependencies.
+* Recursively resolves a component and every one of its transitive
+* `componentDeps` into a flat map of `componentName → registry entry`.
+*
+* The traversal is depth-first and guards against circular dependencies via
+* the `visited` set, so each component appears in the result exactly once.
 *
-* @param name - Root component name to resolve
-* @param registry - The pre-fetched registry index
-* @param seen - Internal set used to prevent infinite loops on circular deps
-* @returns Map of component name → registry entry for the full dependency tree
+* @param componentName - Root component name to start resolving from.
+* @param registry - Pre-fetched registry (pass the result of {@link fetchFullRegistry}).
+* @param visited - Internal visited set used to prevent infinite loops;
+*                  callers should omit this — it defaults to an empty set.
+* @returns A `Map<componentName, ComponentRegistry>` covering the full tree.
+* @throws If any component in the tree is not found in the registry.
 */
-function resolveComponentTree(name, registry, seen = /* @__PURE__ */ new Set()) {
+function resolveComponentWithDependencies(componentName, registry, visited = /* @__PURE__ */ new Set()) {
 	const result = /* @__PURE__ */ new Map();
-	if (seen.has(name)) return result;
-	seen.add(name);
-	const entry = registry.components.find((component) => component.name === name);
-	if (!entry) throw new Error(`Component "${name}" not found in registry.`);
-	result.set(name, entry);
-	for (const dependency of entry.componentDeps) for (const [dependencyName, dependencyEntry] of resolveComponentTree(dependency, registry, seen)) result.set(dependencyName, dependencyEntry);
+	if (visited.has(componentName)) return result;
+	visited.add(componentName);
+	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);
 	return result;
 }
 /**
-* Fetches the raw source code of a component or utility file from the registry.
+* Fetches the raw source content of a file referenced in a component's
+* registry entry.
 *
-* @param path - Path as listed in the component registry (e.g. 'components/button/button.vue')
-* @returns The raw source code of the file
+* Registry file paths (e.g. `"components/button/button.vue"`) are relative
+* to `packages/core/src/`, which is already the base of {@link CORE_SRC_BASE_URL}.
+* This function simply appends the path and downloads the content.
+*
+* @param registryFilePath - Path as it appears in the component's `files` array
+*                           (e.g. `"components/button/button.vue"`).
+* @returns Raw UTF-8 content of the file.
+* @throws If the network request fails or the server returns a non-2xx status.
 */
-async function fetchComponentFile(path) {
-	const requestUrl = `${BASE_URL}/${path}`;
-	const response = await fetch(requestUrl, { headers: FETCH_HEADERS });
-	if (!response.ok) throw new Error(`${response.status}: ${response.statusText}`);
+async function fetchRegistryFileContent(registryFilePath) {
+	const url = `${CORE_SRC_BASE_URL}/${registryFilePath}`;
+	let response;
+	try {
+		response = await fetch(url, { headers: GITHUB_RAW_FETCH_HEADERS });
+	} catch (error) {
+		throw new Error(`[fetchRegistryFileContent] Network request failed for "${registryFilePath}": ${error}`);
+	}
+	if (!response.ok) throw new Error(`[fetchRegistryFileContent] Server returned ${response.status} ${response.statusText} for "${url}"`);
 	return response.text();
 }
 /**
-* Fetches the theme file from the registry.
+* Fetches the raw content of the CentoUI CSS theme file from GitHub.
+*
+* This is the file written to the user's project during `centoui init` and
+* contains all CSS custom properties and base styles for every component.
 *
-* @returns The raw source code of the theme file
+* @returns Raw UTF-8 content of the theme CSS file.
+* @throws If the network request fails or the server returns a non-2xx status.
 */
-async function fetchThemeFile() {
-	const response = await fetch(THEME_URL, { headers: FETCH_HEADERS });
-	if (!response.ok) throw new Error(`${response.status}: ${response.statusText}`);
+async function fetchThemeCSSContent() {
+	let response;
+	try {
+		response = await fetch(THEME_CSS_URL, { headers: GITHUB_RAW_FETCH_HEADERS });
+	} catch (error) {
+		throw new Error(`[fetchThemeCSSContent] Network request for theme CSS failed: ${error}`);
+	}
+	if (!response.ok) throw new Error(`[fetchThemeCSSContent] Server returned ${response.status} ${response.statusText} (URL: ${THEME_CSS_URL})`);
 	return response.text();
 }
 //#endregion
 //#region src/commands/init.ts
+/**
+* Command: `centoui init`
+*
+* 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.
+*  3. Write the config file, fetch and write the theme CSS, prepare the
+*     components directory, and install global npm dependencies.
+*/
 function init() {
 	return defineCommand({
 		meta: {
@@ -223,12 +351,12 @@ function init() {
 					componentDir: () => text({
 						message: "Directory to store components",
 						initialValue: "src/components/centoui",
-						validate: validatePath
+						validate: validateNonEmptyPath
 					}),
 					themeFilePath: () => text({
-						message: "Directory to store theme CSS file",
+						message: "Path for the theme CSS file",
 						initialValue: "src/assets/css/centoui.css",
-						validate: validatePath
+						validate: validateNonEmptyPath
 					})
 				}, { onCancel: () => {
 					cancel("Initialization cancelled.");
@@ -237,32 +365,32 @@ function init() {
 				const configPath = join(cwd, CONFIG_FILE_NAME);
 				const themePath = join(cwd, directories.themeFilePath);
 				const componentsPath = join(cwd, directories.componentDir);
-				const shouldWriteConfig = await promptOverwrite(CONFIG_FILE_NAME, configPath);
-				const shouldWriteTheme = await promptOverwrite(directories.themeFilePath, themePath);
-				const shouldWriteComponents = await promptOverwrite(directories.componentDir, componentsPath);
+				const shouldWriteConfig = await confirmOverwriteIfExists(CONFIG_FILE_NAME, configPath);
+				const shouldWriteTheme = await confirmOverwriteIfExists(directories.themeFilePath, themePath);
+				const shouldWriteComponentsDir = await confirmOverwriteIfExists(directories.componentDir, componentsPath);
 				let registry;
 				await tasks([
 					{
 						title: `Writing ${CONFIG_FILE_NAME}`,
 						task: async () => {
-							if (!shouldWriteConfig) return `Skipped writing ${CONFIG_FILE_NAME}, already exists`;
-							await fsExtra.outputFile(configPath, generateDefaultUserConfigTemplate(directories.themeFilePath, directories.componentDir), "utf-8");
+							if (!shouldWriteConfig) return `Skipped — "${CONFIG_FILE_NAME}" already exists`;
+							await fsExtra.outputFile(configPath, buildDefaultConfigFileContent(directories.themeFilePath, directories.componentDir), "utf-8");
 							return `${CONFIG_FILE_NAME} written`;
 						}
 					},
 					{
 						title: "Fetching theme CSS",
 						task: async () => {
-							if (!shouldWriteTheme) return "Skipped fetching theme CSS, already exists";
-							const themeFile = await fetchThemeFile();
-							await fsExtra.outputFile(themePath, themeFile, "utf-8");
+							if (!shouldWriteTheme) return `Skipped — "${directories.themeFilePath}" already exists`;
+							const themeContent = await fetchThemeCSSContent();
+							await fsExtra.outputFile(themePath, themeContent, "utf-8");
 							return `${directories.themeFilePath} written`;
 						}
 					},
 					{
 						title: "Preparing components directory",
 						task: async () => {
-							if (!shouldWriteComponents) return "Skipped preparing components directory. already exists.";
+							if (!shouldWriteComponentsDir) return `Skipped — "${directories.componentDir}" already exists`;
 							await fsExtra.emptyDir(componentsPath);
 							return `${directories.componentDir} ready`;
 						}
@@ -270,15 +398,13 @@ function init() {
 					{
 						title: "Fetching registry",
 						task: async () => {
-							registry = await fetchRegistry();
-							return "Registry index loaded";
+							registry = await fetchFullRegistry();
+							return "Registry loaded";
 						}
 					},
 					{
 						title: "Installing global dependencies",
-						task: async (message) => {
-							return installPackages(registry.globals.packageDeps, cwd, message);
-						}
+						task: async (message) => installMissingPackages(registry.globals.packageDeps, cwd, message)
 					}
 				]);
 				note([
@@ -286,11 +412,11 @@ function init() {
 					`Theme      > ${themePath}`,
 					`Components > ${componentsPath}`,
 					"",
-					"Run 'centoui add button' to install your first component"
-				].join("\n"), "CentoUI initialized");
-				outro("All Set!");
+					"Run 'centoui add button' to install your first component."
+				].filter(Boolean).join("\n"), "CentoUI initialized");
+				outro("All set!");
 			} catch (error) {
-				log.error(`Failed to build registry: ${error}`);
+				log.error(`Initialization failed: ${error}`);
 				process.exit(1);
 			}
 		}
@@ -299,23 +425,71 @@ function init() {
 //#endregion
 //#region src/utils/components-utils.ts
 /**
-* Resolves the absolute path to a specific component directory.
+* Scans the configured components directory and returns a sorted list of
+* installed component names.
+*
+* Each direct subdirectory of `config.componentsDir` is treated as one
+* installed component. Non-directory entries (loose files) are ignored.
+*
+* @param config - The loaded CentoUI project configuration.
+* @param cwd - Absolute path to the project root.
+* @returns Sorted array of installed component names, or an empty array if
+*          the components directory does not exist yet.
+* @throws If the directory exists but cannot be read.
+*/
+async function listInstalledComponentNames(config, cwd) {
+	const componentsDir = join(cwd, config.componentsDir);
+	try {
+		if (!await fsExtra.pathExists(componentsDir)) return [];
+		return (await fsExtra.readdir(componentsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+	} catch (error) {
+		throw new Error(`[listInstalledComponentNames] Failed to read components directory "${componentsDir}": ${error}`);
+	}
+}
+/**
+* Returns the absolute path to a component's installation directory inside
+* the user's project.
+*
+* The directory may or may not exist yet — this function does not check.
+* Use {@link checkIsComponentInstalled} if you need to verify existence.
 *
-* @param name - The name of the component (kebab-case)
-* @param config - CentoUI configuration
-* @param cwd - Current working directory
-* @returns The absolute path to the component directory
+* @param componentName - The component name in kebab-case (e.g. `"button"`).
+* @param config - The loaded CentoUI project configuration.
+* @param cwd - Absolute path to the project root.
 */
-function getComponentPath(name, config, cwd) {
-	return join(cwd, config.componentsDir, name);
+function resolveComponentInstallDir(componentName, config, cwd) {
+	return join(cwd, config.componentsDir, componentName);
+}
+/**
+* Checks whether a component is currently installed by testing for the
+* existence of its installation directory.
+*
+* @param componentName - The component name in kebab-case (e.g. `"button"`).
+* @param config - The loaded CentoUI project configuration.
+* @param cwd - Absolute path to the project root.
+* @returns `true` if the component directory exists, `false` otherwise.
+*/
+async function checkIsComponentInstalled(componentName, config, cwd) {
+	const componentInstallDir = resolveComponentInstallDir(componentName, config, cwd);
+	try {
+		return fsExtra.pathExists(componentInstallDir);
+	} catch (error) {
+		throw new Error(`[checkIsComponentInstalled] Failed to check if component "${componentName}" is installed: ${error}`);
+	}
 }
 //#endregion
 //#region src/commands/add.ts
 /**
-* Command: add
+* Command: `centoui add <component> [component...]`
+*
+* Installs one or more components — and their full transitive dependency trees
+* — from the registry into the user's project.
 *
-* Installs one or more components (and their transitive dependencies) from
-* the registry into the user's project.
+* Flow:
+*  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.
 */
 function add() {
 	return defineCommand({
@@ -327,50 +501,46 @@ function add() {
 		async run({ args }) {
 			try {
 				const cwd = process.cwd();
-				const componentNames = args._;
+				const requestedNames = args._;
 				intro("CentoUI — Add components");
-				if (componentNames.length === 0) {
-					log.error("No components specified. Usage: centoui add <component> [component...]");
-					process.exit(1);
-				}
-				const config = await loadUserConfig(cwd);
-				const registry = await fetchRegistry();
+				if (requestedNames.length === 0) throw new Error("No components specified. Usage: centoui add <component> [component...]");
+				const config = await loadCentoUIConfig(cwd);
+				const registry = await fetchFullRegistry();
 				const allComponents = /* @__PURE__ */ new Map();
-				for (const name of componentNames) try {
-					const tree = resolveComponentTree(name, registry);
+				for (const name of requestedNames) try {
+					const tree = resolveComponentWithDependencies(name, registry);
 					for (const [depName, depEntry] of tree) allComponents.set(depName, depEntry);
 				} catch (error) {
-					log.error(`Failed to resolve "${name}": ${error}`);
-					process.exit(1);
+					throw new Error(`Failed to resolve "${name}": ${error}`);
 				}
-				const installDecisions = /* @__PURE__ */ new Map();
+				const writeDecisions = /* @__PURE__ */ new Map();
 				for (const [name] of allComponents) {
-					const shouldWrite = await promptOverwrite(name, getComponentPath(name, config, cwd));
-					installDecisions.set(name, shouldWrite);
+					const shouldWrite = await confirmOverwriteIfExists(name, resolveComponentInstallDir(name, config, cwd));
+					writeDecisions.set(name, shouldWrite);
 				}
-				const allPackageDeps = {};
-				for (const [name, entry] of allComponents) if (installDecisions.get(name)) Object.assign(allPackageDeps, entry.packageDeps);
-				const componentsToInstall = Array.from(allComponents.entries()).filter(([name]) => installDecisions.get(name));
-				await tasks([...componentsToInstall.map(([name, entry]) => ({
+				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 path of entry.files) {
-							const content = await fetchComponentFile(path);
-							await writeFile(resolveComponentsDestinationPath(path, config, cwd), content);
+						for (const registryFilePath of entry.files) {
+							const content = await fetchRegistryFileContent(registryFilePath);
+							await writeFileWithDirs(mapRegistryPathToProjectDest(registryFilePath, config, cwd), content);
 						}
-						return `${name} installed (${entry.files.length} file${entry.files.length !== 1 ? "s" : ""})`;
+						return `${name} installed (${entry.files.length} file(s))`;
 					}
 				})), {
 					title: "Installing packages",
-					task: async (message) => installPackages(allPackageDeps, cwd, message)
+					task: async (message) => installMissingPackages(packageDepsToInstall, cwd, message)
 				}]);
-				const skipped = Array.from(installDecisions.entries()).filter(([, shouldWrite]) => !shouldWrite).map(([name]) => name);
+				const skippedNames = Array.from(writeDecisions.entries()).filter(([, shouldWrite]) => !shouldWrite).map(([name]) => name);
 				note([
-					`Installed  > ${componentsToInstall.map(([name]) => name).join(", ") || "none"}`,
-					skipped.length > 0 ? `Skipped    > ${skipped.join(", ")}` : "",
+					`Installed  > ${approvedComponents.map(([name]) => name).join(", ") || "none"}`,
+					skippedNames.length > 0 ? `Skipped    > ${skippedNames.join(", ")}` : "",
 					"",
-					"Import components from your components directory to use them"
-				].filter(Boolean).join("\n"), "Components added");
+					"Import components from your components directory to use them."
+				].filter(Boolean).join("\n"), "Component(s) added");
 				outro("All set!");
 			} catch (error) {
 				log.error(`Failed to add component(s): ${error}`);
@@ -380,6 +550,82 @@ function add() {
 	});
 }
 //#endregion
+//#region src/commands/remove.ts
+/**
+* Command: `centoui remove <component>`
+*
+* Removes a single installed component and its files from the user's project.
+*
+* Flow:
+*  1. Confirm the component is actually installed.
+*  2. Fetch the registry and check whether any other installed components
+*     declare this one as a `componentDep` — block removal if so.
+*  3. Collect the packages still required by remaining components so we
+*     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.
+*/
+function remove() {
+	return defineCommand({
+		meta: {
+			name: "remove",
+			description: "Remove an installed component from your project"
+		},
+		args: { component: {
+			type: "positional",
+			required: true,
+			description: "Name of the component to remove (e.g. \"button\")"
+		} },
+		async run({ args }) {
+			try {
+				const cwd = process.cwd();
+				const componentName = args.component;
+				intro("CentoUI — Remove component");
+				const config = await loadCentoUIConfig(cwd);
+				if (!await checkIsComponentInstalled(componentName, config, cwd)) throw new Error(`Component "${componentName}" is not installed.`);
+				const componentInstallDir = resolveComponentInstallDir(componentName, config, cwd);
+				const registry = await fetchFullRegistry();
+				const targetEntry = registry.components.find((component) => component.name === componentName);
+				if (!targetEntry) throw new Error(`"${componentName}" was not found in the registry. Aborting to avoid a partial removal.`);
+				const remainingNames = (await listInstalledComponentNames(config, cwd)).filter((name) => name !== componentName);
+				const dependents = /* @__PURE__ */ new Set();
+				const packagesStillNeeded = {};
+				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 (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}"?` });
+				if (isCancel(confirmed) || !confirmed) {
+					cancel("Removal cancelled.");
+					process.exit(0);
+				}
+				await tasks([{
+					title: `Removing ${componentName}`,
+					task: async () => {
+						await fsExtra.remove(componentInstallDir);
+						return `${componentName} removed`;
+					}
+				}, {
+					title: "Removing orphaned packages",
+					task: async (message) => removeOrphanedPackages(targetEntry.packageDeps, packagesStillNeeded, cwd, message)
+				}]);
+				const removedPackages = Object.keys(targetEntry.packageDeps).filter((pkg) => !(pkg in packagesStillNeeded));
+				if (removedPackages.length > 0) note(removedPackages.map((pkg) => `  · ${pkg}`).join("\n"), "Packages removed");
+				outro("All set!");
+			} catch (error) {
+				log.error(`Failed to remove component: ${error}`);
+				process.exit(1);
+			}
+		}
+	});
+}
+//#endregion
 //#region src/index.ts
 runMain(defineCommand({
 	meta: {
@@ -388,7 +634,8 @@ runMain(defineCommand({
 	},
 	subCommands: {
 		init,
-		add
+		add,
+		remove
 	}
 }));
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "centoui-cli",
   "type": "module",
-  "version": "0.2.2",
+  "version": "1.0.0-alpha.0",
   "private": false,
   "description": "Official CLI for CentoUI.",
   "author": "Favour Emeka <favorodera@gmail.com>",