sapient-ai 0.1.0 → 0.2.0

package/README.md

@@ -7,6 +7,7 @@ Thin wrapper around `shadcn` for Sapient registry usage.
 - `sapient-ai init`
 - `sapient-ai init --preset <handle-or-id> --template next`
 - `sapient-ai add <component>`
+- `sapient-ai add-icons <design-system|lucide|remix>`
 - `sapient-ai shadcn <args...>`
 
 ## Behavior
@@ -16,6 +17,8 @@ Thin wrapper around `shadcn` for Sapient registry usage.
 - The CLI also generates a `sapient-theme.css` file next to the app's `globals.css` file and imports it automatically so the runtime theme matches the exported Sapient preset.
 - The CLI installs a small Sapient foundation pack by default, then adds any additional registry components inferred from the preset.
 - When the preset references supported Sapient registry items, the CLI also runs `shadcn add` for those components automatically.
+- When the preset uses `lucide` or `remix`, the CLI also installs the matching icon package automatically.
+- `add-icons <library>` updates local Sapient config and installs the matching icon package for an existing project.
 - `add button` is rewritten to `add @sapient/button`.
 - Pass fully-qualified names (`@scope/name`) unchanged.
 - Internally, `init` still uses `shadcn` for project wiring, but it now supplies Sapient-owned defaults so the user does not have to answer the underlying `shadcn` prompts.
@@ -24,7 +27,7 @@ Thin wrapper around `shadcn` for Sapient registry usage.
 
 ```bash
 npm pack ./packages/cli
-npx --yes ./sapient-ai-0.0.1.tgz --help
+ npx --yes ./sapient-ai-0.2.0.tgz --help
 ```
 
 ## Registry URL

package/bin/sapient-ai.js

@@ -24,12 +24,14 @@ Usage:
   sapient-ai init [shadcn-init-args...]
   sapient-ai init --preset <handle-or-id> [shadcn-init-args...]
   sapient-ai add <component> [shadcn-add-args...]
+  sapient-ai add-icons <design-system|lucide|remix> [--cwd <path>]
   sapient-ai shadcn [raw-shadcn-args...]
 
 Examples:
   sapient-ai init
   sapient-ai init --preset ferrari --template next
   sapient-ai add button
+  sapient-ai add-icons remix
   sapient-ai add @sapient/button
   sapient-ai shadcn diff
 
@@ -41,17 +43,17 @@ Environment:
 `);
 }
 
-function runShadcn(args) {
+function runShadcn(args, options = {}) {
   const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
   return spawnSync(npxCmd, ["--yes", "shadcn@latest", ...args], {
     stdio: "inherit",
     env: process.env,
-    cwd: process.cwd(),
+    cwd: options.cwd ?? process.cwd(),
   });
 }
 
-function ensureSapientRegistry() {
-  const componentsPath = path.join(process.cwd(), "components.json");
+function ensureSapientRegistry(projectRoot = process.cwd(), registryUrl = DEFAULT_REGISTRY_URL) {
+  const componentsPath = path.join(projectRoot, "components.json");
 
   if (!fs.existsSync(componentsPath)) {
     return;
@@ -79,7 +81,7 @@ function ensureSapientRegistry() {
   }
 
   parsed.registries = registries;
-  parsed.registries["@sapient"] = DEFAULT_REGISTRY_URL;
+  parsed.registries["@sapient"] = registryUrl;
 
   fs.writeFileSync(
     componentsPath,
@@ -87,7 +89,7 @@ function ensureSapientRegistry() {
     "utf8"
   );
   process.stdout.write(
-    `Updated components.json with @sapient registry: ${DEFAULT_REGISTRY_URL}\n`
+    `Updated components.json with @sapient registry: ${registryUrl}\n`
   );
 }
 
@@ -115,6 +117,87 @@ function parseInitArgs(args) {
   return { presetId, passthrough };
 }
 
+function getOptionValue(args, longName, shortName = null) {
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+
+    if (value === longName || (shortName && value === shortName)) {
+      return args[index + 1] ?? null;
+    }
+
+    if (value.startsWith(`${longName}=`)) {
+      return value.slice(longName.length + 1);
+    }
+
+    if (shortName && value.startsWith(`${shortName}=`)) {
+      return value.slice(shortName.length + 1);
+    }
+  }
+
+  return null;
+}
+
+function captureDirectoryEntries(directoryPath) {
+  try {
+    return new Set(fs.readdirSync(directoryPath));
+  } catch {
+    return new Set();
+  }
+}
+
+function hasProjectMarkers(directoryPath) {
+  return fs.existsSync(path.join(directoryPath, "components.json"));
+}
+
+function resolveProjectRoot({
+  invocationCwd,
+  passthrough,
+  entriesBefore,
+}) {
+  const explicitCwd = getOptionValue(passthrough, "--cwd", "-c");
+  const explicitName = getOptionValue(passthrough, "--name", "-n");
+  const baseDirectory = explicitCwd
+    ? path.resolve(invocationCwd, explicitCwd)
+    : invocationCwd;
+
+  if (explicitName) {
+    const namedProjectDirectory = path.resolve(baseDirectory, explicitName);
+    if (hasProjectMarkers(namedProjectDirectory)) {
+      return namedProjectDirectory;
+    }
+  }
+
+  if (hasProjectMarkers(baseDirectory)) {
+    return baseDirectory;
+  }
+
+  const candidateDirectories = [];
+
+  try {
+    const entriesAfter = fs.readdirSync(baseDirectory, { withFileTypes: true });
+
+    for (const entry of entriesAfter) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const candidatePath = path.join(baseDirectory, entry.name);
+
+      if (!entriesBefore.has(entry.name) && hasProjectMarkers(candidatePath)) {
+        return candidatePath;
+      }
+
+      if (hasProjectMarkers(candidatePath)) {
+        candidateDirectories.push(candidatePath);
+      }
+    }
+  } catch {
+    return baseDirectory;
+  }
+
+  return candidateDirectories[0] ?? baseDirectory;
+}
+
 async function fetchPreset(presetId) {
   const baseUrl = DEFAULT_PRESET_BASE_URL.replace(/\/$/, "");
   const response = await fetch(`${baseUrl}/${encodeURIComponent(presetId)}`);
@@ -176,7 +259,7 @@ async function promptForPresetSelection() {
   }
 }
 
-function writePresetFiles(preset) {
+function writePresetFiles(preset, projectRoot = process.cwd()) {
   if (!preset?.files || !Array.isArray(preset.files)) {
     throw new Error("Preset payload does not include files.");
   }
@@ -186,7 +269,7 @@ function writePresetFiles(preset) {
       continue;
     }
 
-    const absolutePath = path.join(process.cwd(), file.path);
+    const absolutePath = path.join(projectRoot, file.path);
     const directory = path.dirname(absolutePath);
     fs.mkdirSync(directory, { recursive: true });
     fs.writeFileSync(absolutePath, file.content ?? "", "utf8");
@@ -206,13 +289,13 @@ function readJsonFileIfExists(filePath) {
   }
 }
 
-function findExistingArtifactPath(relativePath) {
-  const nextPath = path.join(process.cwd(), SAPIENT_ARTIFACT_DIR, relativePath);
+function findExistingArtifactPath(relativePath, projectRoot = process.cwd()) {
+  const nextPath = path.join(projectRoot, SAPIENT_ARTIFACT_DIR, relativePath);
   if (fs.existsSync(nextPath)) {
     return nextPath;
   }
 
-  const legacyPath = path.join(process.cwd(), relativePath);
+  const legacyPath = path.join(projectRoot, relativePath);
   if (fs.existsSync(legacyPath)) {
     return legacyPath;
   }
@@ -233,8 +316,8 @@ function normalizeBaseColor(baseColor) {
   return match ? match[1] : baseColor;
 }
 
-function findCssEntryFromComponents() {
-  const componentsPath = path.join(process.cwd(), "components.json");
+function findCssEntryFromComponents(projectRoot = process.cwd()) {
+  const componentsPath = path.join(projectRoot, "components.json");
   const components = readJsonFileIfExists(componentsPath);
   const configuredCss = components?.tailwind?.css;
 
@@ -243,7 +326,7 @@ function findCssEntryFromComponents() {
   }
 
   const candidates = ["app/globals.css", "src/app/globals.css"];
-  return candidates.find((candidate) => fs.existsSync(path.join(process.cwd(), candidate))) ?? null;
+  return candidates.find((candidate) => fs.existsSync(path.join(projectRoot, candidate))) ?? null;
 }
 
 function toTokenMap(tokens) {
@@ -261,6 +344,73 @@ function getTokenReference(tokenMap, name, fallback) {
   return Object.prototype.hasOwnProperty.call(tokenMap, name) ? `var(${name})` : fallback;
 }
 
+function resolveSapientExportFont(config) {
+  const fontFallback =
+    'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+
+  if (config?.font === "custom-google" && typeof config?.customFontUrl === "string") {
+    try {
+      const parsedUrl = new URL(config.customFontUrl);
+      let family = "";
+      let importUrl = null;
+
+      if (parsedUrl.hostname === "fonts.googleapis.com") {
+        const familyParam = parsedUrl.searchParams.get("family");
+        family = familyParam
+          ? decodeURIComponent(familyParam.split(":")[0].replace(/\+/g, " ")).trim()
+          : "";
+        importUrl = parsedUrl.toString();
+      } else if (parsedUrl.hostname === "fonts.google.com") {
+        const specimenMatch = parsedUrl.pathname.match(/^\/specimen\/([^/]+)$/);
+        family = specimenMatch?.[1]
+          ? decodeURIComponent(specimenMatch[1].replace(/\+/g, " ")).trim()
+          : "";
+        importUrl = family
+          ? `https://fonts.googleapis.com/css2?family=${family.replace(/\s+/g, "+")}&display=swap`
+          : null;
+      }
+
+      if (importUrl && family) {
+        return {
+          importUrl,
+          fontFamily: `"${family}", ${fontFallback}`,
+        };
+      }
+    } catch {
+      // Fall through to non-custom handling.
+    }
+  }
+
+  if (config?.font === "inter") {
+    return {
+      importUrl: "https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap",
+      fontFamily: `"Inter", ${fontFallback}`,
+    };
+  }
+
+  if (config?.font === "helvetica-neue") {
+    return { importUrl: null, fontFamily: '"Helvetica Neue", Helvetica, Arial, sans-serif' };
+  }
+
+  if (config?.font === "georgia") {
+    return { importUrl: null, fontFamily: 'Georgia, "Times New Roman", serif' };
+  }
+
+  if (config?.font === "trebuchet") {
+    return { importUrl: null, fontFamily: '"Trebuchet MS", "Lucida Grande", sans-serif' };
+  }
+
+  if (typeof config?.customFontName === "string" && config.customFontName.trim().length > 0) {
+    return { importUrl: null, fontFamily: `"${config.customFontName.trim()}", ${fontFallback}` };
+  }
+
+  return {
+    importUrl: null,
+    fontFamily:
+      '"Neue Haas Grotesk Display Pro", ui-sans-serif, system-ui, sans-serif',
+  };
+}
+
 function buildSapientThemeCss({ tokens, config }) {
   const tokenMap = toTokenMap(tokens);
   const baseNeutral = getTokenReference(tokenMap, "--neutral-50", "0 0% 98%");
@@ -282,16 +432,13 @@ function buildSapientThemeCss({ tokens, config }) {
   const cardRadius = getTokenReference(tokenMap, "--card-radius", radius);
   const basePadding = typeof config?.padding === "number" ? `${config.padding}px` : "16px";
   const baseGap = typeof config?.gap === "number" ? `${config.gap}px` : "12px";
-  const fontFamily =
-    typeof config?.font === "string" && config.font.length > 0 && config.font !== "default"
-      ? `'${config.font}', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
-      : `ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`;
+  const { importUrl: fontImportUrl, fontFamily } = resolveSapientExportFont(config);
 
   const tokenLines = Object.entries(tokenMap)
     .map(([name, value]) => `  ${name}: ${String(value)};`)
     .join("\n");
 
-  return `:root {
+  return `${fontImportUrl ? `@import url("${fontImportUrl}");\n\n` : ""}:root {
 ${tokenLines}
   --background: ${baseNeutral};
   --foreground: ${foregroundPrimary};
@@ -399,8 +546,8 @@ html {
 `;
 }
 
-function ensureCssImport(cssPath, importPath) {
-  const absoluteCssPath = path.join(process.cwd(), cssPath);
+function ensureCssImport(projectRoot, cssPath, importPath) {
+  const absoluteCssPath = path.join(projectRoot, cssPath);
 
   if (!fs.existsSync(absoluteCssPath)) {
     return;
@@ -423,14 +570,14 @@ function ensureCssImport(cssPath, importPath) {
   fs.writeFileSync(absoluteCssPath, lines.join("\n"), "utf8");
 }
 
-function applySapientPresetTheme() {
-  const configPath = findExistingArtifactPath("sapient-design-system-config.json");
-  const tokensPath = findExistingArtifactPath("tokens.json");
-  const componentsPath = path.join(process.cwd(), "components.json");
+function applySapientPresetTheme(projectRoot = process.cwd()) {
+  const configPath = findExistingArtifactPath("sapient-design-system-config.json", projectRoot);
+  const tokensPath = findExistingArtifactPath("tokens.json", projectRoot);
+  const componentsPath = path.join(projectRoot, "components.json");
   const config = readJsonFileIfExists(configPath);
   const tokens = readJsonFileIfExists(tokensPath);
   const components = readJsonFileIfExists(componentsPath);
-  const cssPath = findCssEntryFromComponents();
+  const cssPath = findCssEntryFromComponents(projectRoot);
 
   if (!config || !tokens) {
     return;
@@ -443,32 +590,6 @@ function applySapientPresetTheme() {
       components.tailwind.baseColor = normalizedBaseColor;
     }
 
-    components.sapient =
-      components.sapient && typeof components.sapient === "object"
-        ? components.sapient
-        : {};
-    components.sapient.artifactsDir = SAPIENT_ARTIFACT_DIR;
-    components.sapient.configPath = `${SAPIENT_ARTIFACT_DIR}/sapient-design-system-config.json`;
-    components.sapient.tokensPath = `${SAPIENT_ARTIFACT_DIR}/tokens.json`;
-    components.sapient.themeCssPath = cssPath
-      ? path.join(path.dirname(cssPath), "sapient-theme.css")
-      : "app/sapient-theme.css";
-    components.sapient.baseColorToken =
-      typeof config.baseColor === "string" ? config.baseColor : null;
-    components.sapient.iconLibrary =
-      typeof config.iconLibrary === "string" ? config.iconLibrary : null;
-    components.sapient.font =
-      typeof config.font === "string" ? config.font : null;
-    components.sapient.radius =
-      typeof config.radius === "string" ? config.radius : null;
-    components.sapient.spacing =
-      typeof config.padding === "number" || typeof config.gap === "number"
-        ? {
-            padding: typeof config.padding === "number" ? config.padding : null,
-            gap: typeof config.gap === "number" ? config.gap : null,
-          }
-        : null;
-
     writeJsonFile(componentsPath, components);
   }
 
@@ -477,21 +598,202 @@ function applySapientPresetTheme() {
   }
 
   const themeFilePath = path.join(path.dirname(cssPath), "sapient-theme.css");
-  const absoluteThemePath = path.join(process.cwd(), themeFilePath);
+  const absoluteThemePath = path.join(projectRoot, themeFilePath);
   const themeCss = buildSapientThemeCss({ tokens, config });
 
   fs.mkdirSync(path.dirname(absoluteThemePath), { recursive: true });
   fs.writeFileSync(absoluteThemePath, themeCss, "utf8");
-  ensureCssImport(cssPath, "./sapient-theme.css");
+  ensureCssImport(projectRoot, cssPath, "./sapient-theme.css");
   process.stdout.write(`Applied Sapient theme to ${cssPath}\n`);
 }
 
-function installRegistryComponents(preset) {
+function normalizeIconLibrary(value) {
+  if (value === "lucide" || value === "remix") {
+    return value;
+  }
+
+  if (value === "sapient" || value === "sapient-icons" || value === "design-system") {
+    return "design-system";
+  }
+
+  return null;
+}
+
+function collectIconLibrariesFromValue(value, foundLibraries = new Set()) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectIconLibrariesFromValue(item, foundLibraries);
+    }
+    return foundLibraries;
+  }
+
+  if (!value || typeof value !== "object") {
+    return foundLibraries;
+  }
+
+  for (const [key, nestedValue] of Object.entries(value)) {
+    if (key === "iconLibrary" && typeof nestedValue === "string") {
+      const normalized = normalizeIconLibrary(nestedValue);
+      if (normalized) {
+        foundLibraries.add(normalized);
+      }
+    }
+
+    collectIconLibrariesFromValue(nestedValue, foundLibraries);
+  }
+
+  return foundLibraries;
+}
+
+function getPresetIconLibraries(projectRoot = process.cwd()) {
+  const configPath = findExistingArtifactPath("sapient-design-system-config.json", projectRoot);
+  const componentCatalogPath = findExistingArtifactPath("sapient-components.json", projectRoot);
+  const componentLibraryPath = findExistingArtifactPath("sapient-component-library.json", projectRoot);
+  const foundLibraries = new Set();
+
+  [configPath, componentCatalogPath, componentLibraryPath]
+    .map((filePath) => readJsonFileIfExists(filePath))
+    .filter(Boolean)
+    .forEach((artifact) => {
+      collectIconLibrariesFromValue(artifact, foundLibraries);
+    });
+
+  return foundLibraries;
+}
+
+function detectPackageManager(projectRoot = process.cwd()) {
+  if (fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) {
+    return { command: "pnpm", args: ["add"] };
+  }
+
+  if (fs.existsSync(path.join(projectRoot, "yarn.lock"))) {
+    return { command: "yarn", args: ["add"] };
+  }
+
+  if (
+    fs.existsSync(path.join(projectRoot, "bun.lockb")) ||
+    fs.existsSync(path.join(projectRoot, "bun.lock"))
+  ) {
+    return { command: "bun", args: ["add"] };
+  }
+
+  return { command: "npm", args: ["install"] };
+}
+
+function hasInstalledDependency(projectRoot, packageName) {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  const packageJson = readJsonFileIfExists(packageJsonPath);
+
+  if (!packageJson || typeof packageJson !== "object") {
+    return false;
+  }
+
+  return Boolean(
+    packageJson.dependencies?.[packageName] ||
+    packageJson.devDependencies?.[packageName] ||
+    packageJson.peerDependencies?.[packageName]
+  );
+}
+
+function installPresetIconDependencies(projectRoot = process.cwd()) {
+  const packageMap = {
+    lucide: "lucide-react",
+    remix: "@remixicon/react",
+  };
+
+  const requiredPackages = Array.from(getPresetIconLibraries(projectRoot))
+    .filter((library) => library !== "design-system")
+    .map((library) => packageMap[library])
+    .filter(Boolean)
+    .filter((packageName) => !hasInstalledDependency(projectRoot, packageName));
+
+  if (requiredPackages.length === 0) {
+    return;
+  }
+
+  const { command, args } = detectPackageManager(projectRoot);
+  const result = spawnSync(command, [...args, ...requiredPackages], {
+    stdio: "inherit",
+    env: process.env,
+    cwd: projectRoot,
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to install icon dependencies: ${result.error.message}`);
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    throw new Error("Icon dependency installation failed.");
+  }
+
+  process.stdout.write(`Installed icon dependencies: ${requiredPackages.join(", ")}\n`);
+}
+
+function installSpecificIconLibrary(projectRoot = process.cwd(), library) {
+  const packageMap = {
+    lucide: "lucide-react",
+    remix: "@remixicon/react",
+  };
+
+  const packageName = packageMap[library];
+  if (!packageName || hasInstalledDependency(projectRoot, packageName)) {
+    return;
+  }
+
+  const { command, args } = detectPackageManager(projectRoot);
+  const result = spawnSync(command, [...args, packageName], {
+    stdio: "inherit",
+    env: process.env,
+    cwd: projectRoot,
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to install ${packageName}: ${result.error.message}`);
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    throw new Error(`Installation failed for ${packageName}.`);
+  }
+
+  process.stdout.write(`Installed icon dependency: ${packageName}\n`);
+}
+
+function updateComponentsIconLibrary(projectRoot = process.cwd(), library) {
+  const componentsPath = path.join(projectRoot, "components.json");
+  const components = readJsonFileIfExists(componentsPath);
+
+  if (!components || typeof components !== "object") {
+    return false;
+  }
+
+  components.iconLibrary = library === "design-system" ? "lucide" : library;
+  writeJsonFile(componentsPath, components);
+  process.stdout.write(`Updated components.json iconLibrary to ${components.iconLibrary}\n`);
+  return true;
+}
+
+function updateSapientConfigIconLibrary(projectRoot = process.cwd(), library) {
+  const configPath = findExistingArtifactPath("sapient-design-system-config.json", projectRoot);
+  const config = readJsonFileIfExists(configPath);
+
+  if (!config || typeof config !== "object") {
+    return false;
+  }
+
+  config.iconLibrary = library;
+  writeJsonFile(configPath, config);
+  process.stdout.write(`Updated .sapient/sapient-design-system-config.json iconLibrary to ${library}\n`);
+  return true;
+}
+
+function installRegistryComponents(preset, projectRoot = process.cwd()) {
   if (!Array.isArray(preset?.registryComponents) || preset.registryComponents.length === 0) {
     return;
   }
 
-  const result = runShadcn(["add", ...preset.registryComponents]);
+  const result = runShadcn(["add", ...preset.registryComponents], {
+    cwd: projectRoot,
+  });
 
   if (result.error) {
     throw new Error(`Failed to install registry components: ${result.error.message}`);
@@ -527,6 +829,12 @@ function buildHiddenShadcnInitArgs(passthrough) {
 async function handleInit(args) {
   const { presetId, passthrough } = parseInitArgs(args);
   let selectedPreset = presetId;
+  const invocationCwd = process.cwd();
+  const explicitCwd = getOptionValue(passthrough, "--cwd", "-c");
+  const baseDirectory = explicitCwd
+    ? path.resolve(invocationCwd, explicitCwd)
+    : invocationCwd;
+  const entriesBefore = captureDirectoryEntries(baseDirectory);
 
   if (!selectedPreset) {
     try {
@@ -537,7 +845,9 @@ async function handleInit(args) {
     }
   }
 
-  const result = runShadcn(buildHiddenShadcnInitArgs(passthrough));
+  const result = runShadcn(buildHiddenShadcnInitArgs(passthrough), {
+    cwd: invocationCwd,
+  });
 
   if (result.error) {
     process.stderr.write(`Failed to run shadcn init: ${result.error.message}\n`);
@@ -548,7 +858,17 @@ async function handleInit(args) {
     process.exit(result.status ?? 1);
   }
 
-  ensureSapientRegistry();
+  const projectRoot = resolveProjectRoot({
+    invocationCwd,
+    passthrough,
+    entriesBefore,
+  });
+
+  if (projectRoot !== invocationCwd) {
+    process.stdout.write(`Detected project root: ${projectRoot}\n`);
+  }
+
+  ensureSapientRegistry(projectRoot);
 
   if (!selectedPreset) {
     process.exit(0);
@@ -556,9 +876,11 @@ async function handleInit(args) {
 
   try {
     const preset = await fetchPreset(selectedPreset);
-    writePresetFiles(preset);
-    applySapientPresetTheme();
-    installRegistryComponents(preset);
+    ensureSapientRegistry(projectRoot, preset?.registryUrl ?? DEFAULT_REGISTRY_URL);
+    writePresetFiles(preset, projectRoot);
+    applySapientPresetTheme(projectRoot);
+    installRegistryComponents(preset, projectRoot);
+    installPresetIconDependencies(projectRoot);
     process.stdout.write(`Applied preset ${preset.presetHandle || selectedPreset}\n`);
     process.exit(0);
   } catch (error) {
@@ -592,6 +914,43 @@ function handleAdd(args) {
   process.exit(result.status ?? 1);
 }
 
+function handleAddIcons(args) {
+  if (args.length === 0) {
+    process.stderr.write("Missing icon library. Example: sapient-ai add-icons lucide\n");
+    process.exit(1);
+  }
+
+  const [rawLibrary] = args;
+  const library = normalizeIconLibrary(rawLibrary);
+
+  if (!library) {
+    process.stderr.write('Unsupported icon library. Use "design-system", "lucide", or "remix".\n');
+    process.exit(1);
+  }
+
+  const explicitCwd = getOptionValue(args, "--cwd", "-c");
+  const projectRoot = explicitCwd
+    ? path.resolve(process.cwd(), explicitCwd)
+    : process.cwd();
+
+  try {
+    updateComponentsIconLibrary(projectRoot, library);
+    updateSapientConfigIconLibrary(projectRoot, library);
+
+    if (library === "design-system") {
+      process.stdout.write("Sapient design-system icons selected. No external icon package is required.\n");
+      process.exit(0);
+    }
+
+    installSpecificIconLibrary(projectRoot, library);
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    process.stderr.write(`Failed to add icons: ${message}\n`);
+    process.exit(1);
+  }
+}
+
 function handleRawShadcn(args) {
   const result = runShadcn(args);
 
@@ -616,6 +975,10 @@ if (command === "add") {
   handleAdd(rest);
 }
 
+if (command === "add-icons") {
+  handleAddIcons(rest);
+}
+
 if (command === "shadcn") {
   handleRawShadcn(rest);
 }