@zenithbuild/compiler 1.3.2 → 1.3.9

package/dist/core/plugins/bridge.js

@@ -0,0 +1,121 @@
+/**
+ * Zenith CLI Bridge
+ *
+ * The ONLY interface between CLI and plugins.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * CLI BRIDGE RULES (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * 1. No runtime emitters - plugins return data, CLI serializes blindly
+ * 2. No plugin typing - all data is unknown
+ * 3. No semantic helpers - CLI is blind to what data means
+ *
+ * The CLI dispatches hooks and collects returns. It never inspects payloads.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+const hookRegistry = new Map();
+/**
+ * Register a hook handler
+ *
+ * @internal Called by CLIBridgeAPI.on()
+ */
+export function registerHook(hook, handler) {
+    if (!hookRegistry.has(hook)) {
+        hookRegistry.set(hook, []);
+    }
+    hookRegistry.get(hook).push(handler);
+}
+/**
+ * Clear all registered hooks
+ *
+ * @internal Used for testing and cleanup
+ */
+export function clearHooks() {
+    hookRegistry.clear();
+}
+// ============================================
+// Hook Execution (CLI-facing)
+// ============================================
+/**
+ * Run all handlers for a hook (fire-and-forget)
+ *
+ * CLI calls this for lifecycle events.
+ * No return values are collected.
+ *
+ * @param hook - Hook name to dispatch
+ * @param ctx - Hook context
+ */
+export async function runPluginHooks(hook, ctx) {
+    const handlers = hookRegistry.get(hook) || [];
+    for (const handler of handlers) {
+        try {
+            await handler(ctx);
+        }
+        catch (error) {
+            console.error(`[Zenith] Hook "${hook}" error:`, error);
+        }
+    }
+}
+/**
+ * Collect return values from all handlers for a hook
+ *
+ * CLI calls this for 'cli:runtime:collect' to gather plugin payloads.
+ * Only RuntimePayload-shaped returns are collected.
+ *
+ * @param hook - Hook name to dispatch
+ * @param ctx - Hook context
+ * @returns Array of runtime payloads from plugins
+ */
+export async function collectHookReturns(hook, ctx) {
+    const handlers = hookRegistry.get(hook) || [];
+    const results = [];
+    for (const handler of handlers) {
+        try {
+            const result = await handler(ctx);
+            // Only collect properly shaped payloads
+            if (result &&
+                typeof result === 'object' &&
+                'namespace' in result &&
+                'payload' in result &&
+                typeof result.namespace === 'string') {
+                results.push(result);
+            }
+        }
+        catch (error) {
+            console.error(`[Zenith] Hook "${hook}" collection error:`, error);
+        }
+    }
+    return results;
+}
+/**
+ * Build runtime envelope from collected payloads
+ *
+ * CLI calls this to serialize plugin data for injection.
+ * CLI never inspects the envelope contents.
+ *
+ * @param payloads - Array of runtime payloads from collectHookReturns
+ * @returns Envelope object: { [namespace]: payload }
+ */
+export function buildRuntimeEnvelope(payloads) {
+    const envelope = {};
+    for (const { namespace, payload } of payloads) {
+        envelope[namespace] = payload;
+    }
+    return envelope;
+}
+// ============================================
+// Bridge API Factory
+// ============================================
+/**
+ * Create a CLI Bridge API for plugin registration
+ *
+ * CLI calls this once and passes to each plugin's registerCLI method.
+ *
+ * @returns CLIBridgeAPI instance
+ */
+export function createBridgeAPI() {
+    return {
+        on: registerHook
+    };
+}

package/dist/core/plugins/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Zenith Plugins
+ *
+ * Public exports for plugin system
+ */
+export { PluginRegistry, createPluginContext } from './registry';

package/dist/core/plugins/index.js

@@ -0,0 +1,6 @@
+/**
+ * Zenith Plugins
+ *
+ * Public exports for plugin system
+ */
+export { PluginRegistry, createPluginContext } from './registry';

package/dist/core/plugins/registry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Zenith Plugin Registry
+ *
+ * Manages plugin registration and initialization
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOOK OWNERSHIP RULE (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * The plugin registry is part of core infrastructure.
+ * It MUST remain plugin-agnostic:
+ *   - No plugin-specific types
+ *   - No plugin-specific logic
+ *   - Generic data handling only
+ *
+ * Plugins own their data structures; core provides the storage mechanism.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import type { ZenithPlugin, PluginContext } from '../config/types';
+/**
+ * Get all plugin data (for runtime access)
+ */
+export declare function getPluginData(): Record<string, unknown[]>;
+/**
+ * Get plugin data by namespace
+ */
+export declare function getPluginDataByNamespace(namespace: string): unknown[];
+/**
+ * Plugin registry for managing Zenith plugins
+ */
+export declare class PluginRegistry {
+    private plugins;
+    /**
+     * Register a plugin
+     */
+    register(plugin: ZenithPlugin): void;
+    /**
+     * Get a plugin by name
+     */
+    get(name: string): ZenithPlugin | undefined;
+    /**
+     * Check if a plugin is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered plugins
+     */
+    all(): ZenithPlugin[];
+    /**
+     * Initialize all plugins with the provided context
+     */
+    initAll(ctx: PluginContext): Promise<void>;
+    /**
+     * Clear all registered plugins
+     */
+    clear(): void;
+}
+/**
+ * Create a plugin context for initialization
+ *
+ * Uses a generic data setter that stores data by namespace.
+ * Plugins define their own data structures internally.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns A PluginContext for plugin initialization
+ */
+export declare function createPluginContext(projectRoot: string): PluginContext;

package/dist/core/plugins/registry.js

@@ -0,0 +1,112 @@
+/**
+ * Zenith Plugin Registry
+ *
+ * Manages plugin registration and initialization
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOOK OWNERSHIP RULE (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * The plugin registry is part of core infrastructure.
+ * It MUST remain plugin-agnostic:
+ *   - No plugin-specific types
+ *   - No plugin-specific logic
+ *   - Generic data handling only
+ *
+ * Plugins own their data structures; core provides the storage mechanism.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * Global plugin data store
+ *
+ * Plugins store their data here using namespaced keys.
+ * Core does not interpret this data - it just stores and serves it.
+ */
+const pluginDataStore = {};
+/**
+ * Get all plugin data (for runtime access)
+ */
+export function getPluginData() {
+    return { ...pluginDataStore };
+}
+/**
+ * Get plugin data by namespace
+ */
+export function getPluginDataByNamespace(namespace) {
+    return pluginDataStore[namespace] || [];
+}
+/**
+ * Plugin registry for managing Zenith plugins
+ */
+export class PluginRegistry {
+    plugins = new Map();
+    /**
+     * Register a plugin
+     */
+    register(plugin) {
+        if (this.plugins.has(plugin.name)) {
+            console.warn(`[Zenith] Plugin "${plugin.name}" is already registered. Overwriting.`);
+        }
+        this.plugins.set(plugin.name, plugin);
+    }
+    /**
+     * Get a plugin by name
+     */
+    get(name) {
+        return this.plugins.get(name);
+    }
+    /**
+     * Check if a plugin is registered
+     */
+    has(name) {
+        return this.plugins.has(name);
+    }
+    /**
+     * Get all registered plugins
+     */
+    all() {
+        return Array.from(this.plugins.values());
+    }
+    /**
+     * Initialize all plugins with the provided context
+     */
+    async initAll(ctx) {
+        for (const plugin of this.plugins.values()) {
+            try {
+                await plugin.setup(ctx);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`[Zenith] Failed to initialize plugin "${plugin.name}":`, message);
+            }
+        }
+    }
+    /**
+     * Clear all registered plugins
+     */
+    clear() {
+        this.plugins.clear();
+        // Also clear plugin data
+        for (const key of Object.keys(pluginDataStore)) {
+            delete pluginDataStore[key];
+        }
+    }
+}
+/**
+ * Create a plugin context for initialization
+ *
+ * Uses a generic data setter that stores data by namespace.
+ * Plugins define their own data structures internally.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns A PluginContext for plugin initialization
+ */
+export function createPluginContext(projectRoot) {
+    return {
+        projectRoot,
+        setPluginData: (namespace, data) => {
+            pluginDataStore[namespace] = data;
+        },
+        options: {}
+    };
+}

package/dist/css/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Zenith CSS Compiler Module
+ *
+ * Compiler-owned CSS processing that integrates Tailwind CSS v4 JIT
+ * at compile time. This module ensures:
+ *
+ * 1. All CSS is processed at build time (no runtime generation)
+ * 2. Tailwind sees all .zen templates for class scanning
+ * 3. HMR support for instant CSS updates in dev mode
+ * 4. Deterministic, cacheable output for production
+ *
+ * Per Zenith CSS Directive: The compiler owns styles.
+ */
+export interface CSSCompileOptions {
+    /** Input CSS file path (e.g., src/styles/globals.css) */
+    input: string;
+    /** Output CSS file path, or ':memory:' for in-memory result */
+    output: string;
+    /** Enable minification for production */
+    minify?: boolean;
+    /** Watch mode for HMR */
+    watch?: boolean;
+}
+export interface CSSCompileResult {
+    /** Compiled CSS content */
+    css: string;
+    /** Compilation time in milliseconds */
+    duration: number;
+    /** Whether compilation succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Compile CSS using Tailwind CSS v4 CLI
+ *
+ * This function synchronously compiles CSS for use in:
+ * - Dev server startup
+ * - SSG build
+ * - On-demand recompilation
+ *
+ * @param options Compilation options
+ * @returns Compiled CSS result
+ */
+export declare function compileCss(options: CSSCompileOptions): CSSCompileResult;
+/**
+ * Compile CSS asynchronously (non-blocking)
+ *
+ * Used for HMR updates where we don't want to block the main thread.
+ */
+export declare function compileCssAsync(options: CSSCompileOptions): Promise<CSSCompileResult>;
+export interface CSSWatchOptions extends CSSCompileOptions {
+    /** Callback when CSS changes */
+    onChange: (result: CSSCompileResult) => void;
+    /** Debounce delay in ms */
+    debounce?: number;
+}
+/**
+ * Watch CSS and source files for changes, recompile on change
+ *
+ * This is used by the dev server for HMR support.
+ * It watches both the CSS entry point AND all .zen files
+ * that Tailwind scans for class names.
+ */
+export declare function watchCss(options: CSSWatchOptions): () => void;
+/**
+ * Resolve the canonical globals.css path for a Zenith project
+ */
+export declare function resolveGlobalsCss(projectRoot: string): string | null;
+/**
+ * Get the output path for compiled CSS
+ */
+export declare function getCompiledCssPath(projectRoot: string, mode: 'dev' | 'build'): string;

package/dist/css/index.js

@@ -0,0 +1,246 @@
+/**
+ * Zenith CSS Compiler Module
+ *
+ * Compiler-owned CSS processing that integrates Tailwind CSS v4 JIT
+ * at compile time. This module ensures:
+ *
+ * 1. All CSS is processed at build time (no runtime generation)
+ * 2. Tailwind sees all .zen templates for class scanning
+ * 3. HMR support for instant CSS updates in dev mode
+ * 4. Deterministic, cacheable output for production
+ *
+ * Per Zenith CSS Directive: The compiler owns styles.
+ */
+import { spawn, spawnSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+// ============================================
+// CSS Compilation
+// ============================================
+/**
+ * Compile CSS using Tailwind CSS v4 CLI
+ *
+ * This function synchronously compiles CSS for use in:
+ * - Dev server startup
+ * - SSG build
+ * - On-demand recompilation
+ *
+ * @param options Compilation options
+ * @returns Compiled CSS result
+ */
+export function compileCss(options) {
+    const startTime = performance.now();
+    const { input, output, minify = false } = options;
+    // Validate input exists
+    if (!fs.existsSync(input)) {
+        return {
+            css: '',
+            duration: 0,
+            success: false,
+            error: `CSS input file not found: ${input}`
+        };
+    }
+    try {
+        // Build Tailwind CLI arguments
+        const args = [
+            '@tailwindcss/cli',
+            '-i', input
+        ];
+        // For in-memory compilation, use stdout
+        const useStdout = output === ':memory:';
+        if (!useStdout) {
+            args.push('-o', output);
+        }
+        if (minify) {
+            args.push('--minify');
+        }
+        // Execute Tailwind CLI synchronously
+        const result = spawnSync('bunx', args, {
+            cwd: path.dirname(input),
+            encoding: 'utf-8',
+            stdio: useStdout ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'pipe'],
+            env: { ...process.env }
+        });
+        const duration = Math.round(performance.now() - startTime);
+        if (result.status !== 0) {
+            const errorMsg = result.stderr?.toString() || 'Unknown compilation error';
+            return {
+                css: '',
+                duration,
+                success: false,
+                error: `Tailwind compilation failed: ${errorMsg}`
+            };
+        }
+        // Get CSS content
+        let css = '';
+        if (useStdout) {
+            css = result.stdout?.toString() || '';
+        }
+        else if (fs.existsSync(output)) {
+            css = fs.readFileSync(output, 'utf-8');
+        }
+        return {
+            css,
+            duration,
+            success: true
+        };
+    }
+    catch (error) {
+        return {
+            css: '',
+            duration: Math.round(performance.now() - startTime),
+            success: false,
+            error: error.message
+        };
+    }
+}
+/**
+ * Compile CSS asynchronously (non-blocking)
+ *
+ * Used for HMR updates where we don't want to block the main thread.
+ */
+export async function compileCssAsync(options) {
+    return new Promise((resolve) => {
+        const startTime = performance.now();
+        const { input, output, minify = false } = options;
+        if (!fs.existsSync(input)) {
+            resolve({
+                css: '',
+                duration: 0,
+                success: false,
+                error: `CSS input file not found: ${input}`
+            });
+            return;
+        }
+        const args = ['@tailwindcss/cli', '-i', input];
+        const useStdout = output === ':memory:';
+        if (!useStdout) {
+            args.push('-o', output);
+        }
+        if (minify) {
+            args.push('--minify');
+        }
+        const child = spawn('bunx', args, {
+            cwd: path.dirname(input),
+            stdio: useStdout ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'pipe'],
+            env: { ...process.env }
+        });
+        let stdout = '';
+        let stderr = '';
+        if (useStdout && child.stdout) {
+            child.stdout.on('data', (data) => { stdout += data.toString(); });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => { stderr += data.toString(); });
+        }
+        child.on('close', (code) => {
+            const duration = Math.round(performance.now() - startTime);
+            if (code !== 0) {
+                resolve({
+                    css: '',
+                    duration,
+                    success: false,
+                    error: `Tailwind compilation failed: ${stderr}`
+                });
+                return;
+            }
+            let css = '';
+            if (useStdout) {
+                css = stdout;
+            }
+            else if (fs.existsSync(output)) {
+                css = fs.readFileSync(output, 'utf-8');
+            }
+            resolve({
+                css,
+                duration,
+                success: true
+            });
+        });
+        child.on('error', (err) => {
+            resolve({
+                css: '',
+                duration: Math.round(performance.now() - startTime),
+                success: false,
+                error: err.message
+            });
+        });
+    });
+}
+/**
+ * Watch CSS and source files for changes, recompile on change
+ *
+ * This is used by the dev server for HMR support.
+ * It watches both the CSS entry point AND all .zen files
+ * that Tailwind scans for class names.
+ */
+export function watchCss(options) {
+    const { input, output, minify, onChange, debounce = 100 } = options;
+    let timeout = null;
+    let isCompiling = false;
+    const recompile = async () => {
+        if (isCompiling)
+            return;
+        isCompiling = true;
+        const result = await compileCssAsync({ input, output, minify });
+        onChange(result);
+        isCompiling = false;
+    };
+    const debouncedRecompile = () => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(recompile, debounce);
+    };
+    // Watch the styles directory
+    const stylesDir = path.dirname(input);
+    const stylesWatcher = fs.watch(stylesDir, { recursive: true }, (event, filename) => {
+        if (filename?.endsWith('.css')) {
+            debouncedRecompile();
+        }
+    });
+    // Watch source files that Tailwind scans (for class changes)
+    // This assumes standard Zenith structure: src/pages, src/components, src/layouts
+    const srcDir = path.resolve(stylesDir, '..');
+    let srcWatcher = null;
+    if (fs.existsSync(srcDir)) {
+        srcWatcher = fs.watch(srcDir, { recursive: true }, (event, filename) => {
+            if (filename?.endsWith('.zen') || filename?.endsWith('.tsx') || filename?.endsWith('.jsx')) {
+                debouncedRecompile();
+            }
+        });
+    }
+    // Return cleanup function
+    return () => {
+        if (timeout)
+            clearTimeout(timeout);
+        stylesWatcher.close();
+        srcWatcher?.close();
+    };
+}
+// ============================================
+// Path Utilities
+// ============================================
+/**
+ * Resolve the canonical globals.css path for a Zenith project
+ */
+export function resolveGlobalsCss(projectRoot) {
+    // Check for globals.css (canonical)
+    const globalsPath = path.join(projectRoot, 'src', 'styles', 'globals.css');
+    if (fs.existsSync(globalsPath))
+        return globalsPath;
+    // Check for global.css (legacy)
+    const globalPath = path.join(projectRoot, 'src', 'styles', 'global.css');
+    if (fs.existsSync(globalPath))
+        return globalPath;
+    return null;
+}
+/**
+ * Get the output path for compiled CSS
+ */
+export function getCompiledCssPath(projectRoot, mode) {
+    if (mode === 'build') {
+        return path.join(projectRoot, 'dist', 'assets', 'styles.css');
+    }
+    // In dev mode, we use in-memory compilation
+    return ':memory:';
+}

package/dist/discovery/componentDiscovery.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Component Discovery
+ *
+ * Discovers and catalogs components in a Zenith project using standard
+ * file system walking and the unified native "syscall" for metadata.
+ */
+import type { TemplateNode, ExpressionIR } from '../ir/types';
+export interface SlotDefinition {
+    name: string | null;
+    location: {
+        line: number;
+        column: number;
+    };
+}
+export interface ComponentMetadata {
+    name: string;
+    path: string;
+    template: string;
+    nodes: TemplateNode[];
+    expressions: ExpressionIR[];
+    slots: SlotDefinition[];
+    props: string[];
+    states: Record<string, string>;
+    styles: string[];
+    script: string | null;
+    scriptAttributes: Record<string, string> | null;
+    hasScript: boolean;
+    hasStyles: boolean;
+}
+/**
+ * Discover all components in a directory recursively
+ */
+export declare function discoverComponents(baseDir: string): Map<string, ComponentMetadata>;
+/**
+ * Universal Zenith Component Tag Rule: PascalCase
+ */
+export declare function isComponentTag(tagName: string): boolean;
+/**
+ * Get component metadata by name
+ */
+export declare function getComponent(components: Map<string, ComponentMetadata>, name: string): ComponentMetadata | undefined;