@zenithbuild/compiler 1.0.2

package/dist/core/lifecycle/zen-mount.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Zenith OnMount - Post-Mount Lifecycle Hook
+ *
+ * Registers a callback to run after a component's DOM is inserted.
+ * This is an effect wrapper that defers execution until the mount phase.
+ *
+ * Features:
+ * - Runs after DOM is available
+ * - Only runs once per mount
+ * - Supports cleanup function return
+ * - Works with component lifecycle system
+ *
+ * @example
+ * ```ts
+ * zenOnMount(() => {
+ *   console.log('Component mounted!')
+ *   const el = document.querySelector('.my-element')
+ *
+ *   // Optional cleanup - runs on unmount
+ *   return () => {
+ *     console.log('Component will unmount')
+ *   }
+ * })
+ * ```
+ *
+ * Note: This hook registers callbacks that will be executed by the
+ * component lifecycle system. If no mount scheduler is active,
+ * callbacks are queued for later execution.
+ */
+/**
+ * Mount callback type - can optionally return a cleanup function
+ */
+export type MountCallback = () => void | (() => void);
+/**
+ * Register a callback to run after component mount
+ *
+ * @param callback - Function to run after mount (can return cleanup function)
+ * @returns Dispose function to cancel the mount callback
+ */
+export declare function zenOnMount(callback: MountCallback): () => void;
+/**
+ * Trigger mount phase - called by component lifecycle system
+ * Executes all pending mount callbacks
+ *
+ * @internal
+ */
+export declare function triggerMount(): void;
+/**
+ * Trigger unmount phase - called by component lifecycle system
+ * Runs cleanup functions for all active mount hooks
+ *
+ * @internal
+ */
+export declare function triggerUnmount(): void;
+/**
+ * Check if currently in mounted state
+ *
+ * @internal
+ */
+export declare function getIsMounted(): boolean;
+/**
+ * Reset mount state - for testing purposes
+ *
+ * @internal
+ */
+export declare function resetMountState(): void;

package/dist/core/lifecycle/zen-mount.js

@@ -0,0 +1,151 @@
+/**
+ * Zenith OnMount - Post-Mount Lifecycle Hook
+ *
+ * Registers a callback to run after a component's DOM is inserted.
+ * This is an effect wrapper that defers execution until the mount phase.
+ *
+ * Features:
+ * - Runs after DOM is available
+ * - Only runs once per mount
+ * - Supports cleanup function return
+ * - Works with component lifecycle system
+ *
+ * @example
+ * ```ts
+ * zenOnMount(() => {
+ *   console.log('Component mounted!')
+ *   const el = document.querySelector('.my-element')
+ *
+ *   // Optional cleanup - runs on unmount
+ *   return () => {
+ *     console.log('Component will unmount')
+ *   }
+ * })
+ * ```
+ *
+ * Note: This hook registers callbacks that will be executed by the
+ * component lifecycle system. If no mount scheduler is active,
+ * callbacks are queued for later execution.
+ */
+/**
+ * Queue of pending mount callbacks
+ * These are registered but not yet executed because mount hasn't occurred
+ */
+const pendingMountCallbacks = [];
+/**
+ * Currently active mount hooks (for cleanup on unmount)
+ */
+const activeMountHooks = new Set();
+/**
+ * Flag indicating whether we're in a mounted state
+ * This is controlled by the component lifecycle system
+ */
+let isMounted = false;
+/**
+ * Register a callback to run after component mount
+ *
+ * @param callback - Function to run after mount (can return cleanup function)
+ * @returns Dispose function to cancel the mount callback
+ */
+export function zenOnMount(callback) {
+    const state = {
+        callback,
+        cleanup: null,
+        mounted: false
+    };
+    if (isMounted) {
+        // Already mounted - run immediately
+        executeMountCallback(state);
+    }
+    else {
+        // Queue for later execution
+        pendingMountCallbacks.push(state);
+    }
+    activeMountHooks.add(state);
+    // Return dispose function
+    return () => {
+        // Remove from pending if not yet executed
+        const pendingIndex = pendingMountCallbacks.indexOf(state);
+        if (pendingIndex !== -1) {
+            pendingMountCallbacks.splice(pendingIndex, 1);
+        }
+        // Run cleanup if already mounted
+        if (state.mounted && state.cleanup) {
+            state.cleanup();
+            state.cleanup = null;
+        }
+        activeMountHooks.delete(state);
+    };
+}
+/**
+ * Execute a mount callback
+ */
+function executeMountCallback(state) {
+    if (state.mounted)
+        return;
+    state.mounted = true;
+    try {
+        const result = state.callback();
+        if (typeof result === 'function') {
+            state.cleanup = result;
+        }
+    }
+    catch (error) {
+        console.error('[Zenith] Error in onMount callback:', error);
+    }
+}
+/**
+ * Trigger mount phase - called by component lifecycle system
+ * Executes all pending mount callbacks
+ *
+ * @internal
+ */
+export function triggerMount() {
+    isMounted = true;
+    // Execute all pending callbacks
+    const callbacks = [...pendingMountCallbacks];
+    pendingMountCallbacks.length = 0;
+    for (const state of callbacks) {
+        executeMountCallback(state);
+    }
+}
+/**
+ * Trigger unmount phase - called by component lifecycle system
+ * Runs cleanup functions for all active mount hooks
+ *
+ * @internal
+ */
+export function triggerUnmount() {
+    isMounted = false;
+    // Run all cleanup functions
+    for (const state of activeMountHooks) {
+        if (state.cleanup) {
+            try {
+                state.cleanup();
+            }
+            catch (error) {
+                console.error('[Zenith] Error in onMount cleanup:', error);
+            }
+            state.cleanup = null;
+        }
+        state.mounted = false;
+    }
+}
+/**
+ * Check if currently in mounted state
+ *
+ * @internal
+ */
+export function getIsMounted() {
+    return isMounted;
+}
+/**
+ * Reset mount state - for testing purposes
+ *
+ * @internal
+ */
+export function resetMountState() {
+    isMounted = false;
+    pendingMountCallbacks.length = 0;
+    activeMountHooks.clear();
+}

package/dist/core/lifecycle/zen-unmount.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Zenith OnUnmount - Pre-Unmount Lifecycle Hook
+ *
+ * Registers a cleanup callback to run before a component is disposed.
+ * Useful for cleaning up subscriptions, timers, event listeners, etc.
+ *
+ * Features:
+ * - Runs before component is removed from DOM
+ * - Can register multiple callbacks
+ * - Callbacks run in registration order
+ *
+ * @example
+ * ```ts
+ * zenOnUnmount(() => {
+ *   console.log('Cleaning up...')
+ *   subscription.unsubscribe()
+ *   clearInterval(timerId)
+ * })
+ * ```
+ *
+ * Note: This hook registers callbacks that will be executed by the
+ * component lifecycle system when the component is disposed.
+ */
+/**
+ * Unmount callback type
+ */
+export type UnmountCallback = () => void;
+/**
+ * Register a callback to run before component unmount
+ *
+ * @param callback - Function to run before unmount
+ * @returns Dispose function to cancel the unmount callback
+ */
+export declare function zenOnUnmount(callback: UnmountCallback): () => void;
+/**
+ * Execute all unmount callbacks
+ * Called by the component lifecycle system before disposal
+ *
+ * @internal
+ */
+export declare function executeUnmountCallbacks(): void;
+/**
+ * Get count of registered unmount callbacks
+ * Useful for testing
+ *
+ * @internal
+ */
+export declare function getUnmountCallbackCount(): number;
+/**
+ * Reset unmount state - for testing purposes
+ *
+ * @internal
+ */
+export declare function resetUnmountState(): void;

package/dist/core/lifecycle/zen-unmount.js

@@ -0,0 +1,76 @@
+/**
+ * Zenith OnUnmount - Pre-Unmount Lifecycle Hook
+ *
+ * Registers a cleanup callback to run before a component is disposed.
+ * Useful for cleaning up subscriptions, timers, event listeners, etc.
+ *
+ * Features:
+ * - Runs before component is removed from DOM
+ * - Can register multiple callbacks
+ * - Callbacks run in registration order
+ *
+ * @example
+ * ```ts
+ * zenOnUnmount(() => {
+ *   console.log('Cleaning up...')
+ *   subscription.unsubscribe()
+ *   clearInterval(timerId)
+ * })
+ * ```
+ *
+ * Note: This hook registers callbacks that will be executed by the
+ * component lifecycle system when the component is disposed.
+ */
+/**
+ * Queue of registered unmount callbacks
+ */
+const unmountCallbacks = new Set();
+/**
+ * Register a callback to run before component unmount
+ *
+ * @param callback - Function to run before unmount
+ * @returns Dispose function to cancel the unmount callback
+ */
+export function zenOnUnmount(callback) {
+    unmountCallbacks.add(callback);
+    // Return dispose function
+    return () => {
+        unmountCallbacks.delete(callback);
+    };
+}
+/**
+ * Execute all unmount callbacks
+ * Called by the component lifecycle system before disposal
+ *
+ * @internal
+ */
+export function executeUnmountCallbacks() {
+    // Execute in registration order
+    for (const callback of unmountCallbacks) {
+        try {
+            callback();
+        }
+        catch (error) {
+            console.error('[Zenith] Error in onUnmount callback:', error);
+        }
+    }
+    // Clear all callbacks after execution
+    unmountCallbacks.clear();
+}
+/**
+ * Get count of registered unmount callbacks
+ * Useful for testing
+ *
+ * @internal
+ */
+export function getUnmountCallbackCount() {
+    return unmountCallbacks.size;
+}
+/**
+ * Reset unmount state - for testing purposes
+ *
+ * @internal
+ */
+export function resetUnmountState() {
+    unmountCallbacks.clear();
+}

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

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * CLI Bridge API - passed to plugins during CLI registration
+ *
+ * Plugins use this to register namespaced hooks.
+ * CLI lifecycle hooks: 'cli:*'
+ * Plugin hooks: '<namespace>:*'
+ */
+export interface CLIBridgeAPI {
+    /**
+     * Register a hook handler
+     *
+     * @param hook - Namespaced hook name (e.g., 'cli:runtime:collect', 'content:dev:watch')
+     * @param handler - Handler function that receives context and optionally returns data
+     */
+    on(hook: string, handler: (ctx: HookContext) => unknown | void | Promise<unknown | void>): void;
+}
+/**
+ * Context passed to hook handlers
+ *
+ * CLI provides this but never uses getPluginData itself.
+ * Only plugins call getPluginData with their own namespace.
+ */
+export interface HookContext {
+    /** Absolute path to project root */
+    projectRoot: string;
+    /**
+     * Opaque data accessor
+     *
+     * CLI passes this function but NEVER calls it.
+     * Only plugins use it to access their own namespaced data.
+     */
+    getPluginData: (namespace: string) => unknown;
+    /** Additional context data (e.g., filename for file-change hooks) */
+    [key: string]: unknown;
+}
+/**
+ * Runtime payload returned by plugins
+ *
+ * CLI collects these and serializes without inspection.
+ * The envelope structure is: { [namespace]: payload }
+ */
+export interface RuntimePayload {
+    /** Plugin namespace (e.g., 'content', 'router') */
+    namespace: string;
+    /** Opaque payload - CLI never inspects this */
+    payload: unknown;
+}
+type HookHandler = (ctx: HookContext) => unknown | void | Promise<unknown | void>;
+/**
+ * Register a hook handler
+ *
+ * @internal Called by CLIBridgeAPI.on()
+ */
+export declare function registerHook(hook: string, handler: HookHandler): void;
+/**
+ * Clear all registered hooks
+ *
+ * @internal Used for testing and cleanup
+ */
+export declare function clearHooks(): void;
+/**
+ * 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 declare function runPluginHooks(hook: string, ctx: HookContext): Promise<void>;
+/**
+ * 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 declare function collectHookReturns(hook: string, ctx: HookContext): Promise<RuntimePayload[]>;
+/**
+ * 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 declare function buildRuntimeEnvelope(payloads: RuntimePayload[]): Record<string, unknown>;
+/**
+ * Create a CLI Bridge API for plugin registration
+ *
+ * CLI calls this once and passes to each plugin's registerCLI method.
+ *
+ * @returns CLIBridgeAPI instance
+ */
+export declare function createBridgeAPI(): CLIBridgeAPI;
+export {};

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;