@nikala-ui/cli 0.6.0

package/dist/utils/diff/compare-lines.js

@@ -0,0 +1,31 @@
+/**
+ * Compares two text contents line-by-line and returns an array of structured diff entries.
+ * Uses a lightweight matching algorithm to identify added, removed, and identical lines.
+ *
+ * @param oldText - Original local component file content
+ * @param newText - Latest registry component file content
+ */
+export function compareLines(oldText, newText) {
+    const oldLines = oldText.split(/\r?\n/);
+    const newLines = newText.split(/\r?\n/);
+    const diffs = [];
+    let i = 0;
+    let j = 0;
+    while (i < oldLines.length || j < newLines.length) {
+        if (i < oldLines.length && j < newLines.length && oldLines[i] === newLines[j]) {
+            diffs.push({ type: "same", value: oldLines[i] });
+            i++;
+            j++;
+        }
+        else if (j < newLines.length &&
+            (i >= oldLines.length || !oldLines.slice(i).includes(newLines[j]))) {
+            diffs.push({ type: "add", value: newLines[j] });
+            j++;
+        }
+        else if (i < oldLines.length) {
+            diffs.push({ type: "delete", value: oldLines[i] });
+            i++;
+        }
+    }
+    return diffs;
+}

package/dist/utils/diff/format-diff.d.ts

@@ -0,0 +1,8 @@
+import type { DiffLine } from "./compare-lines.js";
+/**
+ * Formats and prints color-coded line differences to the terminal using picocolors.
+ *
+ * @param diffs - Array of diff line entries generated by compareLines
+ * @returns Boolean indicating whether any differences were detected
+ */
+export declare function printFormattedDiff(diffs: DiffLine[]): boolean;

package/dist/utils/diff/format-diff.js

@@ -0,0 +1,27 @@
+import pc from "picocolors";
+/**
+ * Formats and prints color-coded line differences to the terminal using picocolors.
+ *
+ * @param diffs - Array of diff line entries generated by compareLines
+ * @returns Boolean indicating whether any differences were detected
+ */
+export function printFormattedDiff(diffs) {
+    const hasChanges = diffs.some((d) => d.type !== "same");
+    if (!hasChanges) {
+        return false;
+    }
+    console.log("");
+    for (const entry of diffs) {
+        if (entry.type === "add") {
+            console.log(pc.green(`+ ${entry.value}`));
+        }
+        else if (entry.type === "delete") {
+            console.log(pc.red(`- ${entry.value}`));
+        }
+        else {
+            console.log(pc.dim(`  ${entry.value}`));
+        }
+    }
+    console.log("");
+    return true;
+}

package/dist/utils/file.d.ts

@@ -0,0 +1,4 @@
+export declare function readConfig(cwd: string): Promise<any>;
+export declare function writeConfig(cwd: string, config: unknown): Promise<void>;
+export declare function readTsConfig(cwd: string): Promise<any>;
+export declare function writeTsConfig(cwd: string, config: unknown): Promise<void>;

package/dist/utils/file.js

@@ -0,0 +1,23 @@
+// src/utils/file.ts
+import fs from "fs-extra";
+import path from "path";
+import stripJsonComments from "strip-json-comments";
+export async function readConfig(cwd) {
+    const configPath = path.join(cwd, "nikala.config.json");
+    if (!(await fs.pathExists(configPath)))
+        return null;
+    return fs.readJson(configPath);
+}
+export async function writeConfig(cwd, config) {
+    await fs.writeFile(path.join(cwd, "nikala.config.json"), JSON.stringify(config, null, 2));
+}
+export async function readTsConfig(cwd) {
+    const tsconfigPath = path.join(cwd, "tsconfig.json");
+    if (!(await fs.pathExists(tsconfigPath)))
+        return null;
+    const content = await fs.readFile(tsconfigPath, "utf-8");
+    return JSON.parse(stripJsonComments(content));
+}
+export async function writeTsConfig(cwd, config) {
+    await fs.writeFile(path.join(cwd, "tsconfig.json"), JSON.stringify(config, null, 2));
+}

package/dist/utils/init/configure-alias.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Configures Vite / SolidStart config aliases (@) and tsconfig.json path mappings (@/*).
+ */
+export declare function configureAliases(cwd: string): Promise<void>;

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

@@ -0,0 +1,51 @@
+import fs from "fs-extra";
+import path from "node:path";
+import pc from "picocolors";
+import { readTsConfig } from "../file.js";
+/**
+ * Configures Vite / SolidStart config aliases (@) and tsconfig.json path mappings (@/*).
+ */
+export async function configureAliases(cwd) {
+    const viteConfigPath = path.join(cwd, "vite.config.ts");
+    const appConfigPath = path.join(cwd, "app.config.ts");
+    const targetConfigPath = (await fs.pathExists(appConfigPath)) ? appConfigPath : viteConfigPath;
+    if (await fs.pathExists(targetConfigPath)) {
+        let configContent = await fs.readFile(targetConfigPath, "utf-8");
+        let modified = false;
+        if (!configContent.includes("@tailwindcss/vite")) {
+            configContent = `import tailwindcss from "@tailwindcss/vite";\n${configContent}`;
+            if (configContent.includes("plugins: [")) {
+                configContent = configContent.replace("plugins: [", "plugins: [\n    tailwindcss(), ");
+            }
+            else if (configContent.includes("defineConfig({")) {
+                configContent = configContent.replace("defineConfig({", "defineConfig({\n  plugins: [tailwindcss()],");
+            }
+            modified = true;
+        }
+        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  },`);
+            }
+            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)}`));
+        }
+    }
+    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 || {};
+            tsconfig.compilerOptions.paths["@/*"] = ["src/*"];
+            await fs.writeFile(tsconfigPath, JSON.stringify(tsconfig, null, 2), "utf-8");
+            console.log(pc.green("✓ Configured path alias (@/*) in tsconfig.json"));
+        }
+    }
+}

package/dist/utils/init/setup-css.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolves target CSS file path (app.css vs index.css), generates theme setup, and injects entry import.
+ */
+export declare function setupCssTheme(cwd: string, baseColor: string, primaryColor: string): Promise<string>;

package/dist/utils/init/setup-css.js

@@ -0,0 +1,57 @@
+import fs from "fs-extra";
+import path from "node:path";
+import pc from "picocolors";
+import { generateThemeCss } from "../theme.js";
+/**
+ * Resolves target CSS file path (app.css vs index.css), generates theme setup, and injects entry import.
+ */
+export async function setupCssTheme(cwd, baseColor, primaryColor) {
+    let cssPathRelative = "src/index.css";
+    if (await fs.pathExists(path.join(cwd, "src", "app.css"))) {
+        cssPathRelative = "src/app.css";
+    }
+    else if (await fs.pathExists(path.join(cwd, "src", "index.css"))) {
+        cssPathRelative = "src/index.css";
+    }
+    else {
+        const isSolidStart = (await fs.pathExists(path.join(cwd, "src", "app.tsx"))) ||
+            (await fs.pathExists(path.join(cwd, "app.config.ts")));
+        if (isSolidStart) {
+            cssPathRelative = "src/app.css";
+        }
+    }
+    const cssPath = path.join(cwd, cssPathRelative);
+    const generatedCss = generateThemeCss(baseColor, primaryColor);
+    await fs.ensureDir(path.dirname(cssPath));
+    await fs.writeFile(cssPath, generatedCss, "utf-8");
+    console.log(pc.green(`✓ Generated Tailwind CSS v4 theme setup in ${cssPathRelative}`));
+    // Inject CSS import statement into project's main entry point
+    const entryCandidates = [
+        path.join(cwd, "src", "app.tsx"),
+        path.join(cwd, "src", "app.jsx"),
+        path.join(cwd, "src", "entry-client.tsx"),
+        path.join(cwd, "src", "index.tsx"),
+        path.join(cwd, "src", "index.jsx"),
+        path.join(cwd, "src", "index.ts"),
+        path.join(cwd, "src", "main.tsx"),
+        path.join(cwd, "src", "main.ts"),
+    ];
+    let targetEntryPath = null;
+    for (const candidate of entryCandidates) {
+        if (await fs.pathExists(candidate)) {
+            targetEntryPath = candidate;
+            break;
+        }
+    }
+    if (targetEntryPath) {
+        let entryContent = await fs.readFile(targetEntryPath, "utf-8");
+        const cssFileName = path.basename(cssPathRelative);
+        const cssImportStatement = `import "./${cssFileName}";`;
+        if (!entryContent.includes(cssFileName)) {
+            entryContent = `${cssImportStatement}\n${entryContent}`;
+            await fs.writeFile(targetEntryPath, entryContent, "utf-8");
+            console.log(pc.green(`✓ Injected ${cssImportStatement} into ${path.relative(cwd, targetEntryPath)}`));
+        }
+    }
+    return cssPathRelative;
+}

package/dist/utils/pkg.d.ts

@@ -0,0 +1,15 @@
+export type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
+/**
+ * Detects the package manager used in the target project workspace by checking lockfiles.
+ *
+ * @param cwd - Working directory path of the target project
+ * @returns The detected package manager name
+ */
+export declare function detectPackageManager(cwd?: string): Promise<PackageManager>;
+/**
+ * Safely installs missing NPM dependencies while protecting the user's existing package.json from being clobbered.
+ *
+ * @param dependencies - Array of NPM package names to install
+ * @param cwd - Target directory path
+ */
+export declare function installDependencies(dependencies: string[], cwd?: string): Promise<void>;

package/dist/utils/pkg.js

@@ -0,0 +1,102 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import pc from "picocolors";
+import stripJsonComments from "strip-json-comments";
+/**
+ * Detects the package manager used in the target project workspace by checking lockfiles.
+ *
+ * @param cwd - Working directory path of the target project
+ * @returns The detected package manager name
+ */
+export async function detectPackageManager(cwd = process.cwd()) {
+    if ((await fs.pathExists(path.join(cwd, "bun.lockb"))) ||
+        (await fs.pathExists(path.join(cwd, "bun.lock")))) {
+        return "bun";
+    }
+    if (await fs.pathExists(path.join(cwd, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (await fs.pathExists(path.join(cwd, "yarn.lock"))) {
+        return "yarn";
+    }
+    if (await fs.pathExists(path.join(cwd, "package-lock.json"))) {
+        return "npm";
+    }
+    return "bun";
+}
+/**
+ * Safely installs missing NPM dependencies while protecting the user's existing package.json from being clobbered.
+ *
+ * @param dependencies - Array of NPM package names to install
+ * @param cwd - Target directory path
+ */
+export async function installDependencies(dependencies, cwd = process.cwd()) {
+    if (!dependencies || dependencies.length === 0)
+        return;
+    const pkgManager = await detectPackageManager(cwd);
+    const pkgPath = path.join(cwd, "package.json");
+    // 1. Backup original package.json contents before running package manager installation
+    let originalPkgJson = null;
+    if (await fs.pathExists(pkgPath)) {
+        try {
+            const rawContent = await fs.readFile(pkgPath, "utf-8");
+            originalPkgJson = JSON.parse(stripJsonComments(rawContent));
+        }
+        catch {
+            // 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;
+    }
+    console.log(pc.yellow(`\n📦 Installing required component dependencies (${pkgManager})...`));
+    console.log(pc.white(`   ${command}\n`));
+    try {
+        execSync(command, { cwd, stdio: "inherit" });
+        // 2. Validate package.json integrity after installation and restore stripped fields if necessary
+        if (originalPkgJson && (await fs.pathExists(pkgPath))) {
+            try {
+                const currentPkg = await fs.readJson(pkgPath);
+                // If package manager wiped out essential fields like name or scripts, merge original back
+                if (!currentPkg.name && originalPkgJson.name) {
+                    const mergedPkg = {
+                        ...originalPkgJson,
+                        dependencies: {
+                            ...originalPkgJson.dependencies,
+                            ...currentPkg.dependencies,
+                        },
+                        devDependencies: {
+                            ...originalPkgJson.devDependencies,
+                            ...currentPkg.devDependencies,
+                        },
+                    };
+                    await fs.writeFile(pkgPath, JSON.stringify(mergedPkg, null, 2), "utf-8");
+                    console.log(pc.green("  ✓ Preserved and merged original package.json structure."));
+                }
+            }
+            catch {
+                // Ignore merge errors
+            }
+        }
+        console.log(pc.green("  ✓ Dependencies installed successfully."));
+    }
+    catch (error) {
+        console.log(pc.red(`❌ Failed to install dependencies automatically.`));
+        console.log(pc.yellow(`   Please run manually: ${command}`));
+    }
+}

package/dist/utils/registry.d.ts

@@ -0,0 +1,25 @@
+import type { RegistryIndex, RegistryItem } from "../types/registry.js";
+/** Official remote registry CDN URL hosted on GitHub main branch */
+export declare const OFFICIAL_REGISTRY_URL = "https://raw.githubusercontent.com/magradze/nikala-ui/main/packages/core/registry";
+/**
+ * Reads and parses the central registry index manifest.
+ * Bypasses GitHub Raw CDN caching using timestamps and fetches fresh index files.
+ *
+ * @returns The list of available registry items or null if not found.
+ */
+export declare function getRegistryIndex(): Promise<RegistryIndex | null>;
+/**
+ * Fetches a component manifest from a remote HTTP(S) URL with cache-busting.
+ */
+export declare function fetchRemoteRegistryItem(url: string): Promise<RegistryItem | null>;
+/**
+ * Fetches the manifest for a component by name or remote URL.
+ * Checks official remote GitHub registry first, then falls back to local package manifest if offline.
+ *
+ * @param nameOrUrl - Component identifier or full HTTP(S) URL
+ */
+export declare function getRegistryItem(nameOrUrl: string): Promise<RegistryItem | null>;
+/**
+ * Recursively resolves all required internal registry dependencies for a set of component names or URLs.
+ */
+export declare function resolveRegistryDependencies(namesOrUrls: string[]): Promise<string[]>;

package/dist/utils/registry.js

@@ -0,0 +1,123 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Official remote registry CDN URL hosted on GitHub main branch */
+export const OFFICIAL_REGISTRY_URL = "https://raw.githubusercontent.com/magradze/nikala-ui/main/packages/core/registry";
+/**
+ * Resolves the absolute path to the local fallback registry directory inside the Nikala UI package.
+ */
+function getLocalRegistryDirectory() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    return path.resolve(__dirname, "../../registry");
+}
+/**
+ * Reads and parses the central registry index manifest.
+ * Bypasses GitHub Raw CDN caching using timestamps and fetches fresh index files.
+ *
+ * @returns The list of available registry items or null if not found.
+ */
+export async function getRegistryIndex() {
+    // 1. Attempt fetching online manifest from GitHub Raw CDN with cache-busting
+    try {
+        const cacheBuster = Date.now();
+        const response = await fetch(`${OFFICIAL_REGISTRY_URL}/index.json?t=${cacheBuster}`, {
+            headers: { "Cache-Control": "no-cache, no-store" },
+        });
+        if (response.ok) {
+            const data = (await response.json());
+            if (Array.isArray(data))
+                return data;
+        }
+    }
+    catch {
+        // Fallback to local files if offline or network error occurs
+    }
+    // 2. Local package fallback
+    const localDir = getLocalRegistryDirectory();
+    const indexPath = path.join(localDir, "index.json");
+    if (await fs.pathExists(indexPath)) {
+        try {
+            const content = await fs.readFile(indexPath, "utf-8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Fetches a component manifest from a remote HTTP(S) URL with cache-busting.
+ */
+export async function fetchRemoteRegistryItem(url) {
+    try {
+        const cacheBuster = Date.now();
+        const fetchUrl = url.includes("?") ? `${url}&t=${cacheBuster}` : `${url}?t=${cacheBuster}`;
+        const response = await fetch(fetchUrl, {
+            headers: { "Cache-Control": "no-cache, no-store" },
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        if (!data.name || !data.files || !Array.isArray(data.files))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetches the manifest for a component by name or remote URL.
+ * Checks official remote GitHub registry first, then falls back to local package manifest if offline.
+ *
+ * @param nameOrUrl - Component identifier or full HTTP(S) URL
+ */
+export async function getRegistryItem(nameOrUrl) {
+    if (nameOrUrl.startsWith("http://") || nameOrUrl.startsWith("https://")) {
+        return fetchRemoteRegistryItem(nameOrUrl);
+    }
+    // 1. Attempt fetching online component manifest from official GitHub CDN
+    const remoteUrl = `${OFFICIAL_REGISTRY_URL}/${nameOrUrl}.json`;
+    const remoteItem = await fetchRemoteRegistryItem(remoteUrl);
+    if (remoteItem)
+        return remoteItem;
+    // 2. Fallback to local package files if offline or unreleased
+    const localDir = getLocalRegistryDirectory();
+    const itemPath = path.join(localDir, `${nameOrUrl}.json`);
+    if (await fs.pathExists(itemPath)) {
+        try {
+            const content = await fs.readFile(itemPath, "utf-8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Recursively resolves all required internal registry dependencies for a set of component names or URLs.
+ */
+export async function resolveRegistryDependencies(namesOrUrls) {
+    const resolved = new Set();
+    const queue = [...namesOrUrls];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current || resolved.has(current))
+            continue;
+        const item = await getRegistryItem(current);
+        if (!item)
+            continue;
+        resolved.add(current);
+        if (item.registryDependencies && item.registryDependencies.length > 0) {
+            for (const dep of item.registryDependencies) {
+                if (!resolved.has(dep)) {
+                    queue.push(dep);
+                }
+            }
+        }
+    }
+    return Array.from(resolved);
+}

package/dist/utils/theme.d.ts

@@ -0,0 +1,26 @@
+export interface BasePalette {
+    lightBg: string;
+    lightFg: string;
+    darkBg: string;
+    darkFg: string;
+    lightMuted: string;
+    lightMutedFg: string;
+    darkMuted: string;
+    darkMutedFg: string;
+    lightBorder: string;
+    darkBorder: string;
+    lightRing: string;
+    darkRing: string;
+}
+export interface PrimaryColor {
+    light: string;
+    dark: string;
+    lightFg: string;
+    darkFg: string;
+}
+export declare const BASE_PALETTES: Record<string, BasePalette>;
+export declare const PRIMARY_COLORS: Record<string, PrimaryColor>;
+/**
+ * Generates Tailwind CSS v4 theme variables based on base palette and primary accent color.
+ */
+export declare function generateThemeCss(baseColor?: string, primaryColor?: string): string;