@seyuna/cli 1.0.0-canary.17 → 1.0.0-canary.19

package/esm/deno.d.ts

@@ -13,6 +13,7 @@ declare namespace _default {
         "@std/cli": string;
         "@std/fs": string;
         "@std/path": string;
+        "@std/streams": string;
         "@std/assert": string;
         "@std/async": string;
         "@std/fmt": string;

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "@seyuna/cli",
-    "version": "1.0.0-canary.17",
+    "version": "1.0.0-canary.19",
     "exports": "./src/main.ts",
     "publish": {
         "include": [
@@ -18,6 +18,7 @@ export default {
         "@std/cli": "jsr:@std/cli@^1.0.25",
         "@std/fs": "jsr:@std/fs@^1.0.0",
         "@std/path": "jsr:@std/path@^1.0.0",
+        "@std/streams": "jsr:@std/streams@^1.0.8",
         "@std/assert": "jsr:@std/assert@^1.0.0",
         "@std/async": "jsr:@std/async@^1.0.0",
         "@std/fmt": "jsr:@std/fmt@^1.0.0",

package/esm/src/config/init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Initializes a new Seyuna project by creating a 'seyuna.json' configuration file.
+ * This function performs safety checks to avoid overwriting existing configurations.
+ *
+ * @returns A promise that resolves when initialization is complete.
+ */
+export declare function initConfig(): Promise<void>;

package/esm/src/config/init.js

@@ -0,0 +1,68 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { UI_CONFIGURATION } from "../ui/default.js";
+import { SeyunaSpinner } from "../helpers/cli.js";
+import { Brand } from "../helpers/styles.js";
+import { Input, Select } from "@cliffy/prompt";
+/**
+ * Initializes a new Seyuna project by creating a 'seyuna.json' configuration file.
+ * This function performs safety checks to avoid overwriting existing configurations.
+ *
+ * @returns A promise that resolves when initialization is complete.
+ */
+export async function initConfig() {
+    const licenseKey = await Input.prompt({
+        message: `${Brand.muted("›")} Enter your Seyuna license key (optional)`,
+    });
+    const outputDir = await Input.prompt({
+        message: `${Brand.muted("›")} Output directory for generated CSS`,
+        default: "src/styles",
+    }) || "src/styles";
+    const mode = await Select.prompt({
+        message: `${Brand.muted("›")} Default color appearance mode`,
+        default: "system",
+        options: [
+            { name: "System", value: "system" },
+            { name: "Light", value: "light" },
+            { name: "Dark", value: "dark" },
+        ],
+    });
+    const spinner = new SeyunaSpinner("Setting up your Seyuna project").start();
+    try {
+        /** @type {Config} Template for the initial project configuration */
+        const config = {
+            license: licenseKey || undefined,
+            ui: {
+                ...UI_CONFIGURATION,
+                mode,
+                output_dir: outputDir,
+            },
+        };
+        spinner.progress("Building configuration manifest");
+        const json = JSON.stringify(config, null, 2);
+        spinner.progress("Writing manifest to disk");
+        const fileName = "seyuna.json";
+        // Safety check: Avoid accidental overwrites of existing configurations
+        try {
+            const stats = await dntShim.Deno.stat(fileName);
+            if (stats.isFile) {
+                spinner.error(`Existing '${fileName}' found. Initialization aborted to prevent data loss.`);
+                return;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof dntShim.Deno.errors.NotFound)) {
+                throw error;
+            }
+            // File doesn't exist, proceed with initialization
+        }
+        await dntShim.Deno.writeTextFile(fileName, json);
+        spinner.done("Success! Your project is now powered by Seyuna.");
+        // Display helpful onboarding steps
+        console.log(`\n${Brand.muted("Next steps:")}`);
+        console.log(`${Brand.secondary("seyuna ui --compile")}   ${Brand.muted("Build your initial styles")}`);
+        console.log(`${Brand.secondary("seyuna ui --watch")}     ${Brand.muted("Start the development server")}`);
+    }
+    catch (error) {
+        spinner.error(`Failed to initialize: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+}

package/esm/src/config/types.d.ts

@@ -0,0 +1,24 @@
+import type { UI } from "../ui/types.js";
+/**
+ * Root configuration structure for a Seyuna project.
+ * This interface represents the schema of the 'seyuna.json' file.
+ */
+export interface Config {
+    /**
+     * Optional license key for premium features.
+     */
+    license?: string;
+    /**
+     * UI and styling engine configuration.
+     */
+    ui?: UI;
+}
+/**
+ * Deeply merges two project configurations.
+ * Currently handles nested merging for the 'ui' property.
+ *
+ * @param base - The default or base configuration
+ * @param override - The user-provided or overriding configuration
+ * @returns A new configuration object with combined properties
+ */
+export declare function mergeConfig(base: Config, override: Config): Config;

package/esm/src/config/types.js

@@ -0,0 +1,18 @@
+import { mergeUI } from "../ui/types.js";
+/**
+ * Deeply merges two project configurations.
+ * Currently handles nested merging for the 'ui' property.
+ *
+ * @param base - The default or base configuration
+ * @param override - The user-provided or overriding configuration
+ * @returns A new configuration object with combined properties
+ */
+export function mergeConfig(base, override) {
+    return {
+        ...base,
+        ...override,
+        ui: base.ui && override.ui
+            ? mergeUI(base.ui, override.ui)
+            : (override.ui ?? base.ui),
+    };
+}

package/esm/src/helpers/cli.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A branded spinner class that provides visual feedback for long-running CLI operations.
+ * It uses the Seyuna color palette and gradients for a premium experience.
+ */
+export declare class SeyunaSpinner {
+    private spinner;
+    /**
+     * Creates a new branded spinner.
+     * @param message - The initial message to display next to the spinner.
+     */
+    constructor(message: string);
+    /**
+     * Starts the spinner animation.
+     * @returns The spinner instance for chaining.
+     */
+    start(): this;
+    /**
+     * Updates the message displayed next to the active spinner.
+     * @param message - The new progress message.
+     */
+    progress(message: string): void;
+    /**
+     * Stops the spinner and displays a branded success message.
+     * @param message - The message to display upon completion.
+     */
+    done(message: string): void;
+    /**
+     * Stops the spinner and displays a branded error message.
+     * @param message - The error message to display.
+     */
+    error(message: string): void;
+    /**
+     * Stops the spinner and displays a branded warning message.
+     * @param message - The warning message to display.
+     */
+    warning(message: string): void;
+}
+/**
+ * Convenience function to create and start a branded spinner in one call.
+ *
+ * @param message - The message to display.
+ * @returns An active SeyunaSpinner instance.
+ */
+export declare function startSpinner(message: string): SeyunaSpinner;

package/esm/src/helpers/cli.js

@@ -0,0 +1,72 @@
+import { Spinner } from "@std/cli/unstable-spinner";
+import { Brand, seyunaGradient, Symbols } from "./styles.js";
+/**
+ * A branded spinner class that provides visual feedback for long-running CLI operations.
+ * It uses the Seyuna color palette and gradients for a premium experience.
+ */
+export class SeyunaSpinner {
+    /**
+     * Creates a new branded spinner.
+     * @param message - The initial message to display next to the spinner.
+     */
+    constructor(message) {
+        Object.defineProperty(this, "spinner", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.spinner = new Spinner({
+            message: seyunaGradient(message),
+            color: "cyan",
+        });
+    }
+    /**
+     * Starts the spinner animation.
+     * @returns The spinner instance for chaining.
+     */
+    start() {
+        this.spinner.start();
+        return this;
+    }
+    /**
+     * Updates the message displayed next to the active spinner.
+     * @param message - The new progress message.
+     */
+    progress(message) {
+        this.spinner.message = seyunaGradient(message);
+    }
+    /**
+     * Stops the spinner and displays a branded success message.
+     * @param message - The message to display upon completion.
+     */
+    done(message) {
+        this.spinner.stop();
+        console.log(`${Symbols.success} ${Brand.success(message)}`);
+    }
+    /**
+     * Stops the spinner and displays a branded error message.
+     * @param message - The error message to display.
+     */
+    error(message) {
+        this.spinner.stop();
+        console.log(`${Symbols.error} ${Brand.error(message)}`);
+    }
+    /**
+     * Stops the spinner and displays a branded warning message.
+     * @param message - The warning message to display.
+     */
+    warning(message) {
+        this.spinner.stop();
+        console.log(`${Symbols.warning} ${Brand.warning(message)}`);
+    }
+}
+/**
+ * Convenience function to create and start a branded spinner in one call.
+ *
+ * @param message - The message to display.
+ * @returns An active SeyunaSpinner instance.
+ */
+export function startSpinner(message) {
+    return new SeyunaSpinner(message).start();
+}

package/esm/src/helpers/fs.d.ts

@@ -0,0 +1,34 @@
+import type { Config } from "../config/types.js";
+/**
+ * Constructs an absolute or relative path from a filename and an output directory.
+ *
+ * @param fileName - The name of the file (e.g., "styles.css")
+ * @param outputDir - The target directory (e.g., "dist")
+ * @throws Error if fileName or outputDir are empty strings
+ * @returns The joined path string
+ */
+export declare function createPathFromFileName(fileName: string, outputDir: string): string;
+/**
+ * Reads the text content of a file at the specified path.
+ *
+ * @param path - Path to the file to be read
+ * @throws Error with a descriptive message if the file is not found or cannot be read
+ * @returns The file content as a string
+ */
+export declare function readFile(path: string): Promise<string>;
+/**
+ * Saves content to a file, ensuring the parent directory exists.
+ *
+ * @param path - The target file path
+ * @param content - The content to write (string or Uint8Array)
+ * @returns A promise that resolves when the file is written
+ */
+export declare function saveFile(path: string, content: string | Uint8Array): Promise<void>;
+/**
+ * Loads and parses the 'seyuna.json' configuration file from the current directory.
+ * Merges the user configuration with the default UI settings.
+ *
+ * @throws Error if 'seyuna.json' is missing or contains invalid JSON
+ * @returns The merged configuration object
+ */
+export declare function loadSeyunaUserConfig(): Promise<Config>;

package/esm/src/helpers/fs.js

@@ -0,0 +1,83 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { dirname, join } from "@std/path";
+import { ensureDir } from "@std/fs";
+import { mergeConfig } from "../config/types.js";
+import { UI_CONFIGURATION } from "../ui/default.js";
+/**
+ * Constructs an absolute or relative path from a filename and an output directory.
+ *
+ * @param fileName - The name of the file (e.g., "styles.css")
+ * @param outputDir - The target directory (e.g., "dist")
+ * @throws Error if fileName or outputDir are empty strings
+ * @returns The joined path string
+ */
+export function createPathFromFileName(fileName, outputDir) {
+    if (!fileName.trim()) {
+        throw new Error("File name cannot be empty");
+    }
+    if (!outputDir.trim()) {
+        throw new Error("Output directory cannot be empty");
+    }
+    return join(outputDir, fileName);
+}
+/**
+ * Reads the text content of a file at the specified path.
+ *
+ * @param path - Path to the file to be read
+ * @throws Error with a descriptive message if the file is not found or cannot be read
+ * @returns The file content as a string
+ */
+export async function readFile(path) {
+    try {
+        return await dntShim.Deno.readTextFile(path);
+    }
+    catch (error) {
+        if (error instanceof dntShim.Deno.errors.NotFound) {
+            throw new Error(`File not found at path: ${path}`);
+        }
+        throw new Error(`Failed to read file at ${path}: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+}
+/**
+ * Saves content to a file, ensuring the parent directory exists.
+ *
+ * @param path - The target file path
+ * @param content - The content to write (string or Uint8Array)
+ * @returns A promise that resolves when the file is written
+ */
+export async function saveFile(path, content) {
+    const dir = dirname(path);
+    await ensureDir(dir);
+    const data = typeof content === "string"
+        ? new TextEncoder().encode(content)
+        : content;
+    await dntShim.Deno.writeFile(path, data);
+}
+/**
+ * Loads and parses the 'seyuna.json' configuration file from the current directory.
+ * Merges the user configuration with the default UI settings.
+ *
+ * @throws Error if 'seyuna.json' is missing or contains invalid JSON
+ * @returns The merged configuration object
+ */
+export async function loadSeyunaUserConfig() {
+    try {
+        const content = await readFile("seyuna.json");
+        const userConfig = JSON.parse(content);
+        /** @type {Config} Default fallback configuration */
+        const defaultConfig = {
+            license: undefined,
+            ui: UI_CONFIGURATION,
+        };
+        return mergeConfig(defaultConfig, userConfig);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("File not found")) {
+            throw new Error("Could not find 'seyuna.json' in the current directory. Please run 'seyuna ui config --init' to generate it.");
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error(`Failed to parse 'seyuna.json': ${error.message}`);
+        }
+        throw error;
+    }
+}

package/esm/src/helpers/styles.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A function that applies a color or style to a string.
+ */
+export type ColorFunction = (text: string) => string;
+/**
+ * Standard brand colors and styles for the Seyuna CLI.
+ * Provides a consistent visual identity across all command outputs.
+ */
+export declare const Brand: {
+    /** Vibrant Spring Green - Primary brand color */
+    readonly primary: (text: string) => any;
+    /** Cyan - Secondary brand color */
+    readonly secondary: (text: string) => any;
+    /** Magenta - Accent color for highlights */
+    readonly accent: (text: string) => any;
+    /** Bold Green - Indicates successful operations */
+    readonly success: (text: string) => any;
+    /** Bold Red - Indicates errors or critical failures */
+    readonly error: (text: string) => any;
+    /** Bold Yellow - Indicates warnings or non-critical issues */
+    readonly warning: (text: string) => any;
+    /** Gray - For less important or decorative text */
+    readonly muted: (text: string) => any;
+};
+/**
+ * Interpolates between two hex colors to create a gradient effect on text.
+ *
+ * @param text - The string to apply the gradient to
+ * @param startRgb - Start color in hex format (e.g., 0x00FF87)
+ * @param endRgb - End color in hex format (e.g., 0x60EFFF)
+ * @returns The text with ANSI color codes applied per character
+ */
+export declare function gradient(text: string, startRgb: number, endRgb: number): string;
+/**
+ * Standard Seyuna gradient (Spring Green to Cyan).
+ * Used for logos and primary brand headings.
+ */
+export declare const seyunaGradient: ColorFunction;
+/**
+ * Branded Unicode symbols for consistent status reporting.
+ */
+export declare const Symbols: {
+    /** Info icon (Cyan) */
+    readonly info: any;
+    /** Success icon (Green) */
+    readonly success: any;
+    /** Warning icon (Yellow) */
+    readonly warning: any;
+    /** Error icon (Red) */
+    readonly error: any;
+    /** Decorative arrow (Muted) */
+    readonly arrow: any;
+};

package/esm/src/helpers/styles.js

@@ -0,0 +1,71 @@
+import * as colors from "@std/fmt/colors";
+/**
+ * Standard brand colors and styles for the Seyuna CLI.
+ * Provides a consistent visual identity across all command outputs.
+ */
+export const Brand = {
+    /** Vibrant Spring Green - Primary brand color */
+    primary: (text) => colors.rgb24(text, 0x00FF87),
+    /** Cyan - Secondary brand color */
+    secondary: (text) => colors.rgb24(text, 0x60EFFF),
+    /** Magenta - Accent color for highlights */
+    accent: (text) => colors.rgb24(text, 0xFF00E5),
+    /** Bold Green - Indicates successful operations */
+    success: (text) => colors.bold(colors.green(text)),
+    /** Bold Red - Indicates errors or critical failures */
+    error: (text) => colors.bold(colors.red(text)),
+    /** Bold Yellow - Indicates warnings or non-critical issues */
+    warning: (text) => colors.bold(colors.yellow(text)),
+    /** Gray - For less important or decorative text */
+    muted: (text) => colors.gray(text),
+};
+/**
+ * Interpolates between two hex colors to create a gradient effect on text.
+ *
+ * @param text - The string to apply the gradient to
+ * @param startRgb - Start color in hex format (e.g., 0x00FF87)
+ * @param endRgb - End color in hex format (e.g., 0x60EFFF)
+ * @returns The text with ANSI color codes applied per character
+ */
+export function gradient(text, startRgb, endRgb) {
+    const start = {
+        r: (startRgb >> 16) & 0xFF,
+        g: (startRgb >> 8) & 0xFF,
+        b: startRgb & 0xFF,
+    };
+    const end = {
+        r: (endRgb >> 16) & 0xFF,
+        g: (endRgb >> 8) & 0xFF,
+        b: endRgb & 0xFF,
+    };
+    const characters = Array.from(text);
+    const length = characters.length;
+    return characters.map((char, i) => {
+        // If text is 1 char long, use start color
+        const factor = length > 1 ? i / (length - 1) : 0;
+        const r = Math.round(start.r + factor * (end.r - start.r));
+        const g = Math.round(start.g + factor * (end.g - start.g));
+        const b = Math.round(start.b + factor * (end.b - start.b));
+        return colors.rgb24(char, (r << 16) | (g << 8) | b);
+    }).join("");
+}
+/**
+ * Standard Seyuna gradient (Spring Green to Cyan).
+ * Used for logos and primary brand headings.
+ */
+export const seyunaGradient = (text) => gradient(text, 0x00FF87, 0x60EFFF);
+/**
+ * Branded Unicode symbols for consistent status reporting.
+ */
+export const Symbols = {
+    /** Info icon (Cyan) */
+    info: Brand.secondary("ℹ"),
+    /** Success icon (Green) */
+    success: Brand.success("✔"),
+    /** Warning icon (Yellow) */
+    warning: Brand.warning("⚠"),
+    /** Error icon (Red) */
+    error: Brand.error("✖"),
+    /** Decorative arrow (Muted) */
+    arrow: Brand.muted("›"),
+};

package/esm/src/main.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Seyuna CLI - Entrypoint
+ *
+ * This is the main orchestrator for the Seyuna Command Line Interface.
+ * It defines the command hierarchy and provides the branded "Premium"
+ * help screens.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";

package/esm/src/main.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Seyuna CLI - Entrypoint
+ *
+ * This is the main orchestrator for the Seyuna Command Line Interface.
+ * It defines the command hierarchy and provides the branded "Premium"
+ * help screens.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import * as dntShim from "../_dnt.shims.js";
+import { Command } from "@cliffy/command";
+import * as colors from "@std/fmt/colors";
+import { initConfig } from "./config/init.js";
+import { compile } from "./ui/compile.js";
+import { Brand, seyunaGradient } from "./helpers/styles.js";
+// Import project name and version from deno.json for single-source-of-truth.
+import denoConfig from "../deno.js";
+const VERSION = denoConfig.version;
+/**
+ * High-fidelity ASCII logo for the CLI.
+ * Rendered using the primary brand gradient.
+ */
+const seyunaLogo = seyunaGradient(`
+                                     
+ _____ _____ __ __ _____ _____ _____ 
+|   __|   __|  |  |  |  |   | |  _  |
+|__   |   __|_   _|  |  | | | |     |
+|_____|_____| |_| |_____|_|___|__|__|
+                                             
+`);
+/**
+ * 'ui' Command Definition.
+ * Handles style compilation, real-time watching, and configuration.
+ */
+const uiCmd = new Command()
+    .option("-c, --compile", "Run a one-time compilation of your styles.")
+    .option("-w, --watch", "Watch for changes and re-compile automatically.")
+    .action(async (options) => {
+    if (options.compile || options.watch) {
+        await compile({ watch: options.watch });
+    }
+    else {
+        console.log(Brand.warning("Please provide an option or subcommand. See --help for more info."));
+    }
+})
+    /**
+     * 'ui config' Subcommand.
+     * Handles project initialization.
+     */
+    .command("config")
+    .option("-i, --init", "Initialize a new 'seyuna.json' configuration.")
+    .action(async (options) => {
+    if (options.init) {
+        await initConfig();
+    }
+    else {
+        console.log(Brand.warning("Please provide an option. See --help for more info."));
+    }
+});
+/**
+ * Root 'seyuna' Command.
+ */
+const cmd = new Command()
+    .name("seyuna")
+    .version(VERSION)
+    .action(() => {
+    // Show help by default if no subcommand is provided.
+    cmd.showHelp();
+})
+    .command("ui", uiCmd)
+    .command("generate-json-schema")
+    .hidden() // Hidden command for future expansion
+    .action(() => {
+    console.log(Brand.muted("JSON schema generation is planned for a future release."));
+});
+/**
+ * Traverses the command tree and prepends the branded logo to every
+ * generated help screen. This ensures a consistent premium brand experience.
+ *
+ * @param command - The Cliffy Command instance to apply the logo to.
+ */
+// deno-lint-ignore no-explicit-any
+const applyBrandedHelp = (command) => {
+    const originalGetHelp = command.getHelp;
+    command.getHelp = function () {
+        return seyunaLogo + originalGetHelp.call(this);
+    };
+    // Recursively apply to all sub-commands
+    command.getCommands().forEach((c) => applyBrandedHelp(c));
+};
+// Initialize branding
+// @ts-ignore: Cliffy Command types are highly generic and conflict after adding subcommands
+applyBrandedHelp(cmd);
+/**
+ * CLI Execution Loop.
+ * Handles argument parsing and top-level error reporting.
+ */
+if ((import.meta.url === ("file:///" + process.argv[1].replace(/\\/g, "/")).replace(/\/{3,}/, "///"))) {
+    try {
+        await cmd.parse(dntShim.Deno.args);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`${colors.bold(colors.red("Error:"))} ${error.message}`);
+        }
+        dntShim.Deno.exit(1);
+    }
+}

package/esm/src/ui/compile.d.ts

@@ -0,0 +1,20 @@
+import type { Config } from "../config/types.js";
+/**
+ * Main entrypoint for the UI compilation process.
+ * Orchestrates loading configuration, generating CSS, and optionally
+ * starting a file watcher for real-time development.
+ *
+ * @param options - Compilation options, including 'watch' mode
+ * @returns The loaded project configuration
+ */
+export declare function compile(options: {
+    watch?: boolean;
+}): Promise<Config>;
+/**
+ * The core engine that translates project tokens into functional CSS files.
+ * Generates both 'seyuna-global.css' (reset + variables) and
+ * 'postcss-variables.css' (design token manifest for PostCSS).
+ *
+ * @param config - The project configuration object
+ */
+export declare function compileCss(config: Config): Promise<void>;

package/esm/src/ui/compile.js

@@ -0,0 +1,193 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { GLOBAL_CSS } from "./global.css.js";
+import { createPathFromFileName, loadSeyunaUserConfig, saveFile, } from "../helpers/fs.js";
+import { SeyunaSpinner } from "../helpers/cli.js";
+import { delay } from "@std/async";
+import { Brand } from "../helpers/styles.js";
+/**
+ * Main entrypoint for the UI compilation process.
+ * Orchestrates loading configuration, generating CSS, and optionally
+ * starting a file watcher for real-time development.
+ *
+ * @param options - Compilation options, including 'watch' mode
+ * @returns The loaded project configuration
+ */
+export async function compile(options) {
+    try {
+        const config = await loadSeyunaUserConfig();
+        await compileCss(config);
+        if (options.watch) {
+            console.log(`\n${Brand.secondary("Watching for changes...")}`);
+            await watchConfigAndRecompile("seyuna.json");
+        }
+        return config;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+/**
+ * Starts an optimized file watcher on the configuration manifest.
+ * Provides debounced recompilation to handle rapid file system events.
+ *
+ * @param file - The path to the configuration file to watch
+ */
+async function watchConfigAndRecompile(file) {
+    const watcher = dntShim.Deno.watchFs(file);
+    let debounceTimer;
+    for await (const event of watcher) {
+        // Only trigger on actual content modifications
+        if (event.kind === "modify") {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(async () => {
+                // Short delay to ensure the OS has finished writing the file
+                await delay(300);
+                try {
+                    const config = await loadSeyunaUserConfig();
+                    await compileCss(config);
+                    const time = new Date().toLocaleTimeString();
+                    console.log(`${Brand.muted(time)} ${Brand.success("Recompiled successfully")}`);
+                }
+                catch (e) {
+                    console.error(`${Brand.error("Watch Error:")} ${e instanceof Error ? e.message : "Unknown error"}`);
+                }
+            }, 50);
+        }
+    }
+}
+/**
+ * The core engine that translates project tokens into functional CSS files.
+ * Generates both 'seyuna-global.css' (reset + variables) and
+ * 'postcss-variables.css' (design token manifest for PostCSS).
+ *
+ * @param config - The project configuration object
+ */
+export async function compileCss(config) {
+    const spinner = new SeyunaSpinner("Compiling your UI styles").start();
+    try {
+        const ui = getUiConfig(config);
+        if (!ui.output_dir) {
+            throw new Error("Output directory ('output_dir') must be specified in the UI configuration.");
+        }
+        spinner.progress("Building token manifest");
+        const globalCss = buildGlobalCss(config);
+        const postcssVariables = buildPostcssVariables(config);
+        const globalPath = createPathFromFileName("seyuna-global.css", ui.output_dir);
+        const varsPath = createPathFromFileName("postcss-variables.css", ui.output_dir);
+        spinner.progress(`Persisting styles to ${ui.output_dir}`);
+        await saveFile(globalPath, globalCss);
+        await saveFile(varsPath, postcssVariables);
+        spinner.done("Styles compiled successfully!");
+    }
+    catch (error) {
+        spinner.error(`Compilation failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+        throw error;
+    }
+}
+/**
+ * Safely extracts the UI block from the root configuration.
+ */
+function getUiConfig(config) {
+    if (!config.ui) {
+        throw new Error("Missing 'ui' configuration block in 'seyuna.json'.");
+    }
+    return config.ui;
+}
+/**
+ * Combines dynamic token variables with the global reset template.
+ */
+function buildGlobalCss(config) {
+    return [buildCssVariables(config), GLOBAL_CSS].join("\n");
+}
+/**
+ * Generates a full CSS variable sheet including base tokens,
+ * theme modes, and system scheme adaptivity.
+ */
+function buildCssVariables(config) {
+    const ui = getUiConfig(config);
+    const out = [":root {"];
+    // Hue Tokens (e.g., --alpha-hue)
+    for (const [name, val] of Object.entries(ui.theme.hues)) {
+        out.push(`  --${name}-hue: ${val};`);
+    }
+    // Global Semantic Colors
+    for (const [name, color] of Object.entries(ui.theme.colors)) {
+        out.push(`  --${name}-lightness: ${color.lightness};`);
+        out.push(`  --${name}-chroma: ${color.chroma};`);
+        out.push(`  --${name}-hue: ${color.hue};`);
+    }
+    out.push("}\n");
+    const modes = ["light", "dark"];
+    // Explicit Theme Mode Overrides ([data-mode="light"])
+    for (const mode of modes) {
+        out.push(`[data-mode="${mode}"] {`);
+        out.push(buildModeBlock(ui, mode));
+        // Mode-specific semantic color overrides
+        for (const [name, color] of Object.entries(ui.theme[mode].colors)) {
+            out.push(`  --${name}-lightness: ${color.lightness};`);
+            out.push(`  --${name}-chroma: ${color.chroma};`);
+            out.push(`  --${name}-hue: ${color.hue};`);
+        }
+        out.push("}\n");
+    }
+    // System Adatpivity (Auto switching via @media)
+    for (const mode of modes) {
+        out.push(`@media (prefers-color-scheme: ${mode}) {`);
+        out.push('  [data-mode="system"] {');
+        out.push(indent(buildModeBlock(ui, mode), 2));
+        for (const [name, color] of Object.entries(ui.theme[mode].colors)) {
+            out.push(`    --${name}-lightness: ${color.lightness};`);
+            out.push(`    --${name}-chroma: ${color.chroma};`);
+            out.push(`    --${name}-hue: ${color.hue};`);
+        }
+        out.push("  }");
+        out.push("}\n");
+    }
+    return out.join("\n");
+}
+/**
+ * Generates a SASS/PostCSS compatible SCSS manifest.
+ * Used for deep integration with traditional build tools.
+ */
+function buildPostcssVariables(config) {
+    const ui = getUiConfig(config);
+    const fixed = Object.keys(ui.theme.colors).map((c) => `'${c}'`).join(", ");
+    const hues = Object.keys(ui.theme.hues).map((n) => `'${n}'`).join(", ");
+    return [
+        `$fixed_colors: (${fixed});`,
+        `$standard_colors: (${hues});`,
+        "$xs: 20rem;",
+        "$sm: 40rem;",
+        "$md: 48rem;",
+        "$lg: 64rem;",
+        "$xl: 80rem;",
+        "\n",
+    ].join("\n");
+}
+/**
+ * Builds a block of core CSS variables (background, text) for a specific mode.
+ */
+function buildModeBlock(ui, mode) {
+    const p = ui.theme[mode];
+    return [
+        `  --background: oklch(${p.background.lightness} ${p.background.chroma} ${p.background.hue});`,
+        `  --text: oklch(${p.text.lightness} ${p.text.chroma} ${p.text.hue});`,
+        `  --chroma: ${p.chroma};`,
+        `  --lightness: ${p.lightness};`,
+    ].join("\n");
+}
+/**
+ * Helper to indent string lines for pretty-printed CSS output.
+ *
+ * @param s - The string to indent
+ * @param level - Number of double-space indents to apply
+ * @returns The formatted and indented string
+ */
+function indent(s, level) {
+    const pad = "  ".repeat(level);
+    return s.split(/\r?\n/)
+        .filter((line) => line.trim().length > 0)
+        .map((line) => `${pad}${line.trim()}\n`)
+        .join("");
+}

package/esm/src/ui/default.d.ts

@@ -0,0 +1,7 @@
+import type { UI } from "./types.js";
+/**
+ * The default out-of-the-box UI configuration for Seyuna projects.
+ * This provides a robust set of design tokens including a full
+ * Greek-lettered hue scale and foundational semantic colors.
+ */
+export declare const UI_CONFIGURATION: UI;

package/esm/src/ui/default.js

@@ -0,0 +1,65 @@
+/**
+ * The default out-of-the-box UI configuration for Seyuna projects.
+ * This provides a robust set of design tokens including a full
+ * Greek-lettered hue scale and foundational semantic colors.
+ */
+export const UI_CONFIGURATION = {
+    theme: {
+        /**
+         * Global hue scale. Uses Greek letters to provide semantically neutral
+         * references for the 360-degree color wheel.
+         */
+        hues: {
+            "alpha": 0,
+            "beta": 15,
+            "gamma": 30,
+            "delta": 45,
+            "epsilon": 60,
+            "zeta": 75,
+            "eta": 90,
+            "theta": 105,
+            "iota": 120,
+            "kappa": 135,
+            "lambda": 150,
+            "mu": 165,
+            "nu": 180,
+            "xi": 195,
+            "omicron": 210,
+            "pi": 225,
+            "rho": 240,
+            "sigma": 255,
+            "tau": 270,
+            "upsilon": 285,
+            "phi": 300,
+            "chi": 315,
+            "psi": 330,
+            "omega": 345,
+        },
+        /** Base semantic colors shared across modes */
+        colors: {
+            "white": { lightness: 1.0, chroma: 0.0, hue: 0 },
+            "black": { lightness: 0.0, chroma: 0.0, hue: 0 },
+            "primary": { lightness: 0.66, chroma: 0.26, hue: 240 },
+        },
+        /** Default light mode palette */
+        light: {
+            chroma: 0.26,
+            lightness: 0.66,
+            background: { hue: 0, chroma: 0.0, lightness: 1.0 },
+            text: { hue: 0, chroma: 0.0, lightness: 0.0 },
+            colors: {},
+        },
+        /** Default dark mode palette */
+        dark: {
+            chroma: 0.26,
+            lightness: 0.66,
+            background: { hue: 0, chroma: 0.0, lightness: 0.0 },
+            text: { hue: 0, chroma: 0.0, lightness: 1.0 },
+            colors: {},
+        },
+    },
+    /** Default to following the system's preferred color scheme */
+    mode: "system",
+    /** Standard output directory for generated CSS assets */
+    output_dir: "src/styles",
+};

package/esm/src/ui/global.css.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core global CSS template for the Seyuna framework.
+ *
+ * Provides a modern baseline including:
+ * - CSS Cascade Layers (@layer reset, base, etc.)
+ * - Sophisticated CSS Reset with focus on accessibility and modern typography
+ * - Responsive typography foundations
+ * - Standardized element baselines (links, images, headings)
+ */
+export declare const GLOBAL_CSS = "@layer reset, base, components, utilities;\n\n@layer reset {\n/* \n  Reset all elements to a zeroed baseline to ensure consistency in all browsers.\n*/\n  *,\n  *::before,\n  *::after {\n    box-sizing: border-box;\n    margin: 0;\n    padding: 0;\n    line-height: 2;\n    font-family: inherit;\n  }\n\n/* \n  Prevent automatic font size adjustments on mobile devices to keep text rendering consistent across platforms.\n*/\n  html {\n    -moz-text-size-adjust: none; /* Firefox */\n    -webkit-text-size-adjust: none; /* Safari / older WebKit browsers */\n    text-size-adjust: none; /* Modern spec-compliant browsers */\n    color: var(--text);\n    background-color: var(--background);\n    font-size: max(1rem, 0.833vw);\n  }\n\n/* \n  Remove default list styling from unordered and ordered lists that \n  explicitly use role=\"list\".\n*/\n  ul[role=\"list\"],\n  ol[role=\"list\"] {\n    list-style: none;\n  }\n\n/* \n  Ensure the body element always fills at least the full height of the viewport\n  so short pages don't collapse. Improve text rendering across browsers by\n  enabling smoother grayscale antialiasing. Set the body as a container\n  (queryable by its inline size) for use with CSS container queries, and\n  enable smooth scrolling for anchor links and programmatic scroll actions.\n*/\n  body {\n    min-height: 100vh;\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n    container-type: inline-size;\n    scroll-behavior: smooth;\n  }\n\n/* \n  Improve heading readability by evenly distributing words across lines.\n  This prevents awkward line breaks and creates more balanced, aesthetic headings.\n*/\n  h1,\n  h2,\n  h3,\n  h4,\n  h5,\n  h6 {\n    text-wrap: balance;\n  }\n\n/* \n  Reset all link styles to inherit from parent elements.\n  This removes default colors, underlines, and visited/hover states.\n*/\n  a {\n    all: unset;\n    color: inherit;\n    text-decoration: none;\n    cursor: pointer;\n  }\n\n/* \n  Ensure images and <picture> elements scale within their container,\n  preventing overflow and maintaining layout integrity on any screen size.\n*/\n  img,\n  picture {\n    max-width: 100%;\n    display: block;\n  }\n\n/* \n  Add extra scroll margin above and below elements targeted via anchors.\n  This prevents the element from hugging the top edge of the viewport when navigated to.\n*/\n  :target {\n    scroll-margin-block: 1rem;\n  }\n}\n";

package/esm/src/ui/global.css.js

@@ -0,0 +1,104 @@
+/**
+ * Core global CSS template for the Seyuna framework.
+ *
+ * Provides a modern baseline including:
+ * - CSS Cascade Layers (@layer reset, base, etc.)
+ * - Sophisticated CSS Reset with focus on accessibility and modern typography
+ * - Responsive typography foundations
+ * - Standardized element baselines (links, images, headings)
+ */
+export const GLOBAL_CSS = `@layer reset, base, components, utilities;
+
+@layer reset {
+/* 
+  Reset all elements to a zeroed baseline to ensure consistency in all browsers.
+*/
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    line-height: 2;
+    font-family: inherit;
+  }
+
+/* 
+  Prevent automatic font size adjustments on mobile devices to keep text rendering consistent across platforms.
+*/
+  html {
+    -moz-text-size-adjust: none; /* Firefox */
+    -webkit-text-size-adjust: none; /* Safari / older WebKit browsers */
+    text-size-adjust: none; /* Modern spec-compliant browsers */
+    color: var(--text);
+    background-color: var(--background);
+    font-size: max(1rem, 0.833vw);
+  }
+
+/* 
+  Remove default list styling from unordered and ordered lists that 
+  explicitly use role="list".
+*/
+  ul[role="list"],
+  ol[role="list"] {
+    list-style: none;
+  }
+
+/* 
+  Ensure the body element always fills at least the full height of the viewport
+  so short pages don't collapse. Improve text rendering across browsers by
+  enabling smoother grayscale antialiasing. Set the body as a container
+  (queryable by its inline size) for use with CSS container queries, and
+  enable smooth scrolling for anchor links and programmatic scroll actions.
+*/
+  body {
+    min-height: 100vh;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    container-type: inline-size;
+    scroll-behavior: smooth;
+  }
+
+/* 
+  Improve heading readability by evenly distributing words across lines.
+  This prevents awkward line breaks and creates more balanced, aesthetic headings.
+*/
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    text-wrap: balance;
+  }
+
+/* 
+  Reset all link styles to inherit from parent elements.
+  This removes default colors, underlines, and visited/hover states.
+*/
+  a {
+    all: unset;
+    color: inherit;
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+/* 
+  Ensure images and <picture> elements scale within their container,
+  preventing overflow and maintaining layout integrity on any screen size.
+*/
+  img,
+  picture {
+    max-width: 100%;
+    display: block;
+  }
+
+/* 
+  Add extra scroll margin above and below elements targeted via anchors.
+  This prevents the element from hugging the top edge of the viewport when navigated to.
+*/
+  :target {
+    scroll-margin-block: 1rem;
+  }
+}
+`;

package/esm/src/ui/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Supported color appearance modes.
+ * - 'system': Automatically follows OS preference.
+ * - 'light': Forces light theme.
+ * - 'dark': Forces dark theme.
+ */
+export type Mode = "system" | "light" | "dark";
+/**
+ * Represents a color in the Oklch color space.
+ * Oklch provides a perceptually uniform way to define colors,
+ * making it ideal for accessibility-conscious design systems.
+ */
+export interface Color {
+    /** Lightness (0-100%) */
+    lightness: number;
+    /** Chroma (color intensity, 0-0.4) */
+    chroma: number;
+    /** Hue (angle on the color wheel, 0-360) */
+    hue: number;
+}
+/**
+ * A cohesive set of colors used within a specific theme mode (Light or Dark).
+ */
+export interface Palette {
+    /** Base chroma for primary elements */
+    chroma: number;
+    /** Base lightness for background/text contrast */
+    lightness: number;
+    /** Prime background color definition */
+    background: Color;
+    /** Prime text color definition */
+    text: Color;
+    /** Named semantic colors (e.g., 'primary', 'secondary') */
+    colors: Record<string, Color>;
+}
+/**
+ * The complete theme specification containing both light and dark mode mappings.
+ */
+export interface Theme {
+    /** Global hue definitions for consistent branding */
+    hues: Record<string, number>;
+    /** Global color definitions inherited by palettes */
+    colors: Record<string, Color>;
+    /** Light mode palette configuration */
+    light: Palette;
+    /** Dark mode palette configuration */
+    dark: Palette;
+}
+/**
+ * UI Engine Configuration.
+ * Controls how the CSS is generated and where it's saved.
+ */
+export interface UI {
+    /** Theme specification */
+    theme: Theme;
+    /** Default theme mode */
+    mode: Mode;
+    /** Relative path to save generated CSS files */
+    output_dir?: string;
+}
+/**
+ * Merges two color objects. Currently prioritizes the override.
+ */
+export declare function mergeColor(_base: Color, override: Color): Color;
+/**
+ * Recursively merges two palettes.
+ */
+export declare function mergePalette(base: Palette, override: Palette): Palette;
+/**
+ * Recursively merges two theme specifications.
+ */
+export declare function mergeTheme(base: Theme, override: Theme): Theme;
+/**
+ * Recursively merges two UI engine configurations.
+ */
+export declare function mergeUI(base: UI, override: UI): UI;

package/esm/src/ui/types.js

@@ -0,0 +1,41 @@
+/**
+ * Merges two color objects. Currently prioritizes the override.
+ */
+export function mergeColor(_base, override) {
+    return { ...override };
+}
+/**
+ * Recursively merges two palettes.
+ */
+export function mergePalette(base, override) {
+    return {
+        ...base,
+        ...override,
+        background: mergeColor(base.background, override.background),
+        text: mergeColor(base.text, override.text),
+        colors: { ...base.colors, ...override.colors },
+    };
+}
+/**
+ * Recursively merges two theme specifications.
+ */
+export function mergeTheme(base, override) {
+    return {
+        ...base,
+        ...override,
+        hues: { ...base.hues, ...override.hues },
+        colors: { ...base.colors, ...override.colors },
+        light: mergePalette(base.light, override.light),
+        dark: mergePalette(base.dark, override.dark),
+    };
+}
+/**
+ * Recursively merges two UI engine configurations.
+ */
+export function mergeUI(base, override) {
+    return {
+        ...base,
+        ...override,
+        theme: mergeTheme(base.theme, override.theme),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seyuna/cli",
-  "version": "1.0.0-canary.17",
+  "version": "1.0.0-canary.19",
   "description": "Seyuna CLI",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     "node": ">=18"
   },
   "bin": {
-    "seyuna": "./esm/main.js"
+    "seyuna": "./esm/src/main.js"
   },
   "dependencies": {
     "@deno/shim-deno": "~0.18.0"