@nikala-ui/cli 0.11.0 → 0.12.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Giorgi Magradze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO QUALITY AND FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,48 +1,194 @@
 # @nikala-ui/cli
 
-Command Line Interface (CLI) for **Nikala UI** — a copy-paste component system for **SolidJS** built natively for **Tailwind CSS v4**.
+The Nikala UI CLI initializes SolidJS projects and copies Nikala UI components, application blocks, and reactive hooks directly into the consuming project. It is designed for Tailwind CSS v4 and a local source ownership workflow.
 
-Honoring the iconic Georgian painter **Niko Pirosmani (Nikala)**.
+Nikala UI honors the work of Georgian painter Niko Pirosmani (Nikala).
 
-Official Documentation & Interactive Demos: [nikala.dev](https://nikala.dev)
+Documentation and interactive examples: [nikala.dev](https://nikala.dev)
 
----
+## Installation
 
-## Installation & Usage
+Run the CLI without installing it globally:
 
-Execute directly using your preferred package manager:
+```bash
+bunx @nikala-ui/cli <command>
+```
+
+The package also exposes the `nikala` binary when installed as a project dependency.
+
+## Initialize a project
+
+Run `init` from the root of a SolidJS project:
+
+```bash
+bunx @nikala-ui/cli init
+```
+
+Initialization creates or updates the Nikala project configuration, path aliases, Tailwind CSS v4 theme tokens, and the local `cn` helper. It installs the runtime and styling dependencies required by the generated setup.
+
+Options:
+
+```bash
+# Skip interactive prompts and use defaults
+bunx @nikala-ui/cli init --defaults
+
+# Skip dependency installation
+bunx @nikala-ui/cli init --skip-dependencies
+
+# Generate AI assistant rules
+bunx @nikala-ui/cli init --ai
+```
+
+AI rules can also be generated or updated independently:
+
+```bash
+bunx @nikala-ui/cli rules
+bunx @nikala-ui/cli ai
+```
+
+## Add components, blocks, and hooks
+
+Add one or more UI components:
 
 ```bash
-# Add components
 bunx @nikala-ui/cli add button dialog
+```
+
+Add reactive hooks with `--hook` or `-h`:
+
+```bash
+bunx @nikala-ui/cli add --hook create-clipboard create-debounce
+bunx @nikala-ui/cli add -h create-scroll-into-view
+```
+
+Add marketing or application blocks with `--block` or `-b`:
+
+```bash
+bunx @nikala-ui/cli add --block hero-01
+```
+
+If no item names are provided, the CLI opens an interactive searchable selector. Dependencies declared by the selected registry items are installed automatically.
+
+Options:
+
+```bash
+# Add every available item in the selected category
+bunx @nikala-ui/cli add --all
+
+# Overwrite existing local files
+bunx @nikala-ui/cli add button --overwrite
+```
+
+The CLI copies source files into the configured local directories. The project owns those files and can modify them without importing a runtime Nikala UI component package.
+
+## Upgrade installed items
+
+Upgrade selected locally installed components or hooks to the latest registry versions:
+
+```bash
+bunx @nikala-ui/cli upgrade button
+bunx @nikala-ui/cli update button
+bunx @nikala-ui/cli upgrade --all
+```
+
+`update` is an alias for `upgrade`. Without item names, the CLI opens a selector containing installed items.
 
-# Upgrade / update installed components & hooks to latest registry versions
-bunx @nikala-ui/cli upgrade
-bunx @nikala-ui/cli update button --all
+## Remove installed items
 
-# Remove / uninstall installed components or hooks
+Remove local components or hooks:
+
+```bash
 bunx @nikala-ui/cli remove button
-bunx @nikala-ui/cli uninstall -h create-clipboard
+bunx @nikala-ui/cli uninstall button
+bunx @nikala-ui/cli clean --hook create-clipboard
+```
 
-# Initialize project
-bunx @nikala-ui/cli init
+Options:
+
+```bash
+# Remove hooks instead of UI components
+bunx @nikala-ui/cli remove -h create-clipboard
+
+# Remove all items in the selected category
+bunx @nikala-ui/cli remove --all
 ```
 
----
+The CLI asks for confirmation before deleting local source files. `uninstall` and `clean` are aliases for `remove`.
 
-## Available Commands
+## List registry items
 
-- `nikala init` — Initializes configuration, `@` path aliases, and Tailwind CSS v4 variables.
-- `nikala add` — Interactive searchable multiselect menu for component installation.
-- `nikala validate` (or `nikala doctor`) — Runs health diagnostics on workspace configuration, packages, and CSS design tokens.
-- `nikala diff` — Inspects line-by-line code differences between local components and upstream registry manifests.
-- `nikala theme set [primary] [base]` — Customizes primary brand accent colors and base gray palettes directly from the terminal.
+List available registry items and show which ones are installed locally:
 
----
+```bash
+bunx @nikala-ui/cli list
+bunx @nikala-ui/cli ls
+```
+
+Filters and output options:
+
+```bash
+bunx @nikala-ui/cli list --installed
+bunx @nikala-ui/cli list --component
+bunx @nikala-ui/cli list --block
+bunx @nikala-ui/cli list --hook
+bunx @nikala-ui/cli list --json
+```
+
+## Customize the theme
+
+Open the interactive theme selector:
+
+```bash
+bunx @nikala-ui/cli theme
+```
 
-## Documentation
+Set the primary accent and base palette directly:
+
+```bash
+bunx @nikala-ui/cli theme set amber zinc
+```
+
+The command updates the local Tailwind CSS v4 design tokens defined by the project setup.
+
+## Validate a project
+
+Run diagnostics for the Nikala configuration, required dependencies, and CSS design tokens:
+
+```bash
+bunx @nikala-ui/cli validate
+bunx @nikala-ui/cli doctor
+```
+
+`doctor` is an alias for `validate`.
+
+## Inspect local differences
+
+Compare a locally installed component with its current registry source:
+
+```bash
+bunx @nikala-ui/cli diff button
+bunx @nikala-ui/cli diff
+```
+
+The command prints line-by-line differences between local source files and the latest registry manifest.
+
+## Local project structure
+
+After initialization and component installation, a typical project contains:
+
+```text
+src/
+├── components/
+│   ├── blocks/
+│   └── ui/
+├── hooks/
+├── index.css
+└── lib/
+    └── cn.ts
+nikala.config.json
+```
 
-For full documentation, component lists, and theming guides, visit the official repository at [github.com/nikala-ui/ui](https://github.com/nikala-ui/ui).
+The exact directories are controlled by `nikala.config.json`. Components, blocks, and hooks remain local source files that can be customized by the project owner.
 
 ## License
 

package/dist/commands/add.js

@@ -61,9 +61,6 @@ export async function add(components = [], options = {}) {
     const componentsDir = path.resolve(cwd, config.alias.components);
     console.log(pc.cyan(`\n🎨 Adding items to project...\n`));
     const requiredNpmDeps = new Set();
-    if (isHookMode) {
-        requiredNpmDeps.add("@nikala-ui/hooks");
-    }
     for (const target of resolvedTargets) {
         const item = await getRegistryItem(target, config.registries);
         if (!item) {

package/dist/commands/init.d.ts

@@ -1,6 +1,7 @@
 interface InitOptions {
     defaults?: boolean;
     ai?: boolean;
+    skipDependencies?: boolean;
 }
 /**
  * Initializes Nikala UI workspace configuration and sets up design tokens.

package/dist/commands/init.js

@@ -101,8 +101,10 @@ export async function init(options) {
     else {
         requiredDeps.push("tailwindcss", "@tailwindcss/vite");
     }
-    console.log(pc.yellow("\n📦 Installing required runtime & Tailwind CSS dependencies..."));
-    await installDependencies(requiredDeps, cwd);
+    if (!options.skipDependencies) {
+        console.log(pc.yellow("\n📦 Installing required runtime & Tailwind CSS dependencies..."));
+        await installDependencies(requiredDeps, cwd);
+    }
     // 2. Configure path aliases
     await configureAliases(cwd);
     // 3. Generate cn.ts helper

package/dist/index.js

@@ -10,18 +10,19 @@ import { upgradeCommand } from "./commands/upgrade.js";
 import { removeCommand } from "./commands/remove.js";
 import { listCommand } from "./commands/list.js";
 import { setupAiRules } from "./utils/init/setup-ai-rules.js";
-console.log(`\n🎨 ${pc.bold(pc.red("Nikala UI"))} ${pc.dim("v0.11.0")} — SolidJS + Tailwind v4 components`);
+console.log(`\n🎨 ${pc.bold(pc.red("Nikala UI"))} ${pc.dim("v0.12.1")} — SolidJS + Tailwind v4 components`);
 console.log(`   ${pc.italic(pc.dim("Honoring Niko Pirosmani (Nikala)"))}\n`);
 console.log(`   ${pc.dim("Docs:")} ${pc.underline(pc.cyan("https://nikala.dev"))}\n`);
 const program = new Command();
 program
     .name("nikala")
     .description("Nikala UI — SolidJS + Tailwind v4 components")
-    .version("0.11.0");
+    .version("0.12.1");
 program
     .command("init")
     .description("Initialize Nikala UI in your project")
     .option("-d, --defaults", "Skip prompts and use defaults")
+    .option("--skip-dependencies", "Skip dependency installation (used by higher-level tooling)")
     .option("--ai", "Generate AI assistant rules (.cursor/rules/nikala.mdc, .cursorrules, AGENTS.md)")
     .action(init);
 program

package/dist/utils/init/configure-alias.js

@@ -12,36 +12,43 @@ export async function configureAliases(cwd) {
     if (await fs.pathExists(targetConfigPath)) {
         let configContent = await fs.readFile(targetConfigPath, "utf-8");
         let modified = false;
+        // 1. Inject Tailwind CSS v4 Vite plugin if missing
         if (!configContent.includes("@tailwindcss/vite")) {
             configContent = `import tailwindcss from "@tailwindcss/vite";\n${configContent}`;
             if (configContent.includes("plugins: [")) {
                 configContent = configContent.replace("plugins: [", "plugins: [\n    tailwindcss(), ");
+                modified = true;
             }
-            else if (configContent.includes("defineConfig({")) {
-                configContent = configContent.replace("defineConfig({", "defineConfig({\n  plugins: [tailwindcss()],");
+            else {
+                const defineConfigRegex = /(defineConfig\s*\(\s*(?:async\s*)?(?:\([^)]*\)\s*=>\s*)?\{)/;
+                if (defineConfigRegex.test(configContent)) {
+                    configContent = configContent.replace(defineConfigRegex, "$1\n  plugins: [tailwindcss()],");
+                    modified = true;
+                }
             }
-            modified = true;
         }
+        // 2. Inject path alias (@ -> ./src)
         if (!configContent.includes('"@"') && !configContent.includes("'@'")) {
             if (!configContent.includes('import path from "node:path"') && !configContent.includes('import path from "path"')) {
                 configContent = `import path from "node:path";\n${configContent}`;
             }
-            if (configContent.includes("defineConfig({")) {
-                configContent = configContent.replace("defineConfig({", `defineConfig({\n  resolve: {\n    alias: {\n      "@": path.resolve(__dirname, "./src"),\n    },\n  },`);
+            const defineConfigRegex = /(defineConfig\s*\(\s*(?:async\s*)?(?:\([^)]*\)\s*=>\s*)?\{)/;
+            if (defineConfigRegex.test(configContent)) {
+                configContent = configContent.replace(defineConfigRegex, `$1\n  resolve: {\n    alias: {\n      "@": path.resolve(process.cwd(), "./src"),\n    },\n  },`);
+                modified = true;
             }
-            modified = true;
         }
         if (modified) {
             await fs.writeFile(targetConfigPath, configContent, "utf-8");
             console.log(pc.green(`✓ Configured Tailwind CSS v4 plugin and path alias in ${path.basename(targetConfigPath)}`));
         }
     }
+    // 3. Configure tsconfig.json path mappings (@/* -> ./src/*)
     const tsconfigPath = path.join(cwd, "tsconfig.json");
     if (await fs.pathExists(tsconfigPath)) {
         const tsconfig = await readTsConfig(cwd);
         if (tsconfig) {
             tsconfig.compilerOptions = tsconfig.compilerOptions || {};
-            tsconfig.compilerOptions.baseUrl = ".";
             tsconfig.compilerOptions.paths = tsconfig.compilerOptions.paths || {};
             // Correct path mapping with leading relative dot ./src/*
             tsconfig.compilerOptions.paths["@/*"] = ["./src/*"];

package/dist/utils/pkg.js

@@ -1,8 +1,10 @@
 import fs from "fs-extra";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import pc from "picocolors";
 import stripJsonComments from "strip-json-comments";
+// Standard npm package name regex validator (supports scoped packages and version specifiers)
+const NPM_PACKAGE_REGEX = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@[a-zA-Z0-9^~.*><=-]+)?$/;
 /**
  * Detects the package manager used in the target project workspace by checking lockfiles.
  *
@@ -47,27 +49,16 @@ export async function installDependencies(dependencies, cwd = process.cwd()) {
             // Failed to parse original package.json
         }
     }
-    const depsString = dependencies.join(" ");
-    let command = "";
-    switch (pkgManager) {
-        case "bun":
-            command = `bun add ${depsString}`;
-            break;
-        case "pnpm":
-            command = `pnpm add ${depsString}`;
-            break;
-        case "yarn":
-            command = `yarn add ${depsString}`;
-            break;
-        case "npm":
-        default:
-            command = `npm install ${depsString}`;
-            break;
-    }
+    // Validate and sanitize dependency names to prevent any shell metacharacter injection
+    const validDeps = dependencies.filter((dep) => NPM_PACKAGE_REGEX.test(dep));
+    if (validDeps.length === 0)
+        return;
+    const subCommand = pkgManager === "npm" ? "install" : "add";
+    const args = [subCommand, ...validDeps];
     console.log(pc.yellow(`\n📦 Installing required component dependencies (${pkgManager})...`));
-    console.log(pc.white(`   ${command}\n`));
+    console.log(pc.white(`   ${pkgManager} ${args.join(" ")}\n`));
     try {
-        execSync(command, { cwd, stdio: "inherit" });
+        execFileSync(pkgManager, args, { cwd, stdio: "inherit" });
         // 2. Validate package.json integrity after installation and restore stripped fields if necessary
         if (originalPkgJson && (await fs.pathExists(pkgPath))) {
             try {
@@ -97,6 +88,6 @@ export async function installDependencies(dependencies, cwd = process.cwd()) {
     }
     catch (error) {
         console.log(pc.red(`❌ Failed to install dependencies automatically.`));
-        console.log(pc.yellow(`   Please run manually: ${command}`));
+        console.log(pc.yellow(`   Please run manually: ${pkgManager} ${args.join(" ")}`));
     }
 }

package/dist/utils/theme.js

@@ -171,16 +171,16 @@ export const PRIMARY_COLORS = {
         },
     },
     yellow: {
-        light: "oklch(0.75 0.18 90)",
-        dark: "oklch(0.82 0.16 90)",
+        light: "oklch(0.795 0.184 86.047)",
+        dark: "oklch(0.852 0.199 91.936)",
         lightFg: "oklch(0.1450 0 0)",
         darkFg: "oklch(0.1450 0 0)",
         charts: {
-            chart1: "oklch(0.82 0.18 90)",
-            chart2: "oklch(0.72 0.16 80)",
-            chart3: "oklch(0.62 0.14 100)",
-            chart4: "oklch(0.88 0.12 95)",
-            chart5: "oklch(0.52 0.15 85)",
+            chart1: "oklch(0.795 0.184 86.047)",
+            chart2: "oklch(0.65 0.16 50)",
+            chart3: "oklch(0.55 0.15 85)",
+            chart4: "oklch(0.85 0.12 60)",
+            chart5: "oklch(0.45 0.14 75)",
         },
     },
     lime: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nikala-ui/cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Command line interface for Nikala UI",
   "type": "module",
   "main": "./dist/index.js",