@zenithbuild/core 0.4.2 → 0.4.5

package/cli/commands/dev.ts

@@ -13,6 +13,7 @@ import { loadContent } from '../utils/content'
 import { loadZenithConfig } from '../../core/config/loader'
 import { PluginRegistry, createPluginContext } from '../../core/plugins/registry'
 import type { ContentItem } from '../../core/config/types'
+import { compileCssAsync, resolveGlobalsCss } from '../../compiler/css'
 
 export interface DevOptions {
     port?: number
@@ -67,6 +68,23 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
     console.log('[Zenith] Content collections loaded:', Object.keys(contentData))
 
+    // ============================================
+    // CSS Compilation (Compiler-Owned)
+    // ============================================
+    const globalsCssPath = resolveGlobalsCss(rootDir)
+    let compiledCss = ''
+
+    if (globalsCssPath) {
+        console.log('[Zenith] Compiling CSS:', path.relative(rootDir, globalsCssPath))
+        const cssResult = await compileCssAsync({ input: globalsCssPath, output: ':memory:' })
+        if (cssResult.success) {
+            compiledCss = cssResult.css
+            console.log(`[Zenith] CSS compiled in ${cssResult.duration}ms`)
+        } else {
+            console.error('[Zenith] CSS compilation failed:', cssResult.error)
+        }
+    }
+
     const clients = new Set<ServerWebSocket<unknown>>()
 
     // Branded Startup Panel
@@ -90,6 +108,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     function compilePageInMemory(pagePath: string): CompiledPage | null {
         try {
             const layoutsDir = path.join(pagesDir, '../layouts')
+            const componentsDir = path.join(pagesDir, '../components')
             const layouts = discoverLayouts(layoutsDir)
             const source = fs.readFileSync(pagePath, 'utf-8')
 
@@ -98,7 +117,9 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
             if (layoutToUse) processedSource = processLayout(source, layoutToUse)
 
-            const result = compileZenSource(processedSource, pagePath)
+            const result = compileZenSource(processedSource, pagePath, {
+                componentsDir: fs.existsSync(componentsDir) ? componentsDir : undefined
+            })
             if (!result.finalized) throw new Error('Compilation failed')
 
             const routeDef = generateRouteDefinition(pagePath, pagesDir)
@@ -117,22 +138,37 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     }
 
     // Set up file watching for HMR
-    const watcher = fs.watch(path.join(pagesDir, '..'), { recursive: true }, (event, filename) => {
+    const watcher = fs.watch(path.join(pagesDir, '..'), { recursive: true }, async (event, filename) => {
         if (!filename) return
 
         if (filename.endsWith('.zen')) {
             logger.hmr('Page', filename)
-            // Broadcast reload
+            // Recompile CSS for new Tailwind classes in .zen files
+            if (globalsCssPath) {
+                const cssResult = await compileCssAsync({ input: globalsCssPath, output: ':memory:' })
+                if (cssResult.success) {
+                    compiledCss = cssResult.css
+                    // Notify clients of CSS update
+                    for (const client of clients) {
+                        client.send(JSON.stringify({ type: 'style-update', url: '/assets/styles.css' }))
+                    }
+                }
+            }
+            // Broadcast page reload
             for (const client of clients) {
                 client.send(JSON.stringify({ type: 'reload' }))
             }
         } else if (filename.endsWith('.css')) {
             logger.hmr('CSS', filename)
+            // Recompile CSS
+            if (globalsCssPath) {
+                const cssResult = await compileCssAsync({ input: globalsCssPath, output: ':memory:' })
+                if (cssResult.success) {
+                    compiledCss = cssResult.css
+                }
+            }
             for (const client of clients) {
-                client.send(JSON.stringify({
-                    type: 'style-update',
-                    url: filename.includes('global.css') ? '/styles/global.css' : `/${filename}`
-                }))
+                client.send(JSON.stringify({ type: 'style-update', url: '/assets/styles.css' }))
             }
         } else if (filename.startsWith('content') || filename.includes('zenith-docs')) {
             logger.hmr('Content', filename)
@@ -173,14 +209,22 @@ export async function dev(options: DevOptions = {}): Promise<void> {
                 return response
             }
 
-            if (pathname === '/styles/global.css') {
-                const globalCssPath = path.join(pagesDir, '../styles/global.css')
-                if (fs.existsSync(globalCssPath)) {
-                    const css = fs.readFileSync(globalCssPath, 'utf-8')
-                    const response = new Response(css, { headers: { 'Content-Type': 'text/css' } })
-                    logger.route('GET', pathname, 200, Math.round(performance.now() - startTime), 0, Math.round(performance.now() - startTime))
-                    return response
-                }
+            // Serve compiler-owned CSS (Tailwind compiled)
+            if (pathname === '/assets/styles.css') {
+                const response = new Response(compiledCss, {
+                    headers: { 'Content-Type': 'text/css; charset=utf-8' }
+                })
+                logger.route('GET', pathname, 200, Math.round(performance.now() - startTime), 0, Math.round(performance.now() - startTime))
+                return response
+            }
+
+            // Legacy: also support /styles/globals.css or /styles/global.css for backwards compat
+            if (pathname === '/styles/globals.css' || pathname === '/styles/global.css') {
+                const response = new Response(compiledCss, {
+                    headers: { 'Content-Type': 'text/css; charset=utf-8' }
+                })
+                logger.route('GET', pathname, 200, Math.round(performance.now() - startTime), 0, Math.round(performance.now() - startTime))
+                return response
             }
 
             // Static files

package/compiler/css/index.ts

@@ -0,0 +1,317 @@
+/**
+ * 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'
+
+// ============================================
+// Types
+// ============================================
+
+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
+}
+
+// ============================================
+// 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: CSSCompileOptions): CSSCompileResult {
+    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: any) {
+        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: CSSCompileOptions): Promise<CSSCompileResult> {
+    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
+            })
+        })
+    })
+}
+
+// ============================================
+// CSS Watcher for HMR
+// ============================================
+
+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 function watchCss(options: CSSWatchOptions): () => void {
+    const { input, output, minify, onChange, debounce = 100 } = options
+
+    let timeout: NodeJS.Timeout | null = 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: fs.FSWatcher | null = 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: string): string | null {
+    // 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: string, mode: 'dev' | 'build'): string {
+    if (mode === 'build') {
+        return path.join(projectRoot, 'dist', 'assets', 'styles.css')
+    }
+    // In dev mode, we use in-memory compilation
+    return ':memory:'
+}

package/compiler/discovery/componentDiscovery.ts

@@ -0,0 +1,174 @@
+/**
+ * Component Discovery
+ * 
+ * Discovers and catalogs components in a Zenith project
+ * Similar to layout discovery but for reusable components
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { parseZenFile } from '../parse/parseZenFile'
+import type { TemplateNode } from '../ir/types'
+
+export interface SlotDefinition {
+    name: string | null  // null = default slot, string = named slot
+    location: {
+        line: number
+        column: number
+    }
+}
+
+export interface ComponentMetadata {
+    name: string          // Component name (e.g., "Card", "Button")
+    path: string          // Absolute path to .zen file
+    template: string      // Raw template HTML
+    nodes: TemplateNode[] // Parsed template nodes
+    slots: SlotDefinition[]
+    props: string[]       // Declared props
+    styles: string[]      // Raw CSS from <style> blocks
+    hasScript: boolean
+    hasStyles: boolean
+}
+
+/**
+ * Discover all components in a directory
+ * @param baseDir - Base directory to search (e.g., src/components)
+ * @returns Map of component name to metadata
+ */
+export function discoverComponents(baseDir: string): Map<string, ComponentMetadata> {
+    const components = new Map<string, ComponentMetadata>()
+
+    // Check if components directory exists
+    if (!fs.existsSync(baseDir)) {
+        return components
+    }
+
+    // Recursively find all .zen files
+    const zenFiles = findZenFiles(baseDir)
+
+    for (const filePath of zenFiles) {
+        try {
+            const metadata = parseComponentFile(filePath)
+            if (metadata) {
+                components.set(metadata.name, metadata)
+            }
+        } catch (error: any) {
+            console.warn(`[Zenith] Failed to parse component ${filePath}: ${error.message}`)
+        }
+    }
+
+    return components
+}
+
+/**
+ * Recursively find all .zen files in a directory
+ */
+function findZenFiles(dir: string): string[] {
+    const files: string[] = []
+
+    if (!fs.existsSync(dir)) {
+        return files
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name)
+
+        if (entry.isDirectory()) {
+            files.push(...findZenFiles(fullPath))
+        } else if (entry.isFile() && entry.name.endsWith('.zen')) {
+            files.push(fullPath)
+        }
+    }
+
+    return files
+}
+
+/**
+ * Parse a component file and extract metadata
+ */
+function parseComponentFile(filePath: string): ComponentMetadata | null {
+    const ir = parseZenFile(filePath)
+
+    // Extract component name from filename
+    const basename = path.basename(filePath, '.zen')
+    const componentName = basename
+
+    // Extract slots from template
+    const slots = extractSlots(ir.template.nodes)
+
+    // Extract props from script attributes
+    const props = ir.script?.attributes['props']?.split(',').map(p => p.trim()) || []
+
+    // Extract raw CSS from styles
+    const styles = ir.styles.map(s => s.raw)
+
+    return {
+        name: componentName,
+        path: filePath,
+        template: ir.template.raw,
+        nodes: ir.template.nodes,
+        slots,
+        props,
+        styles,
+        hasScript: ir.script !== null,
+        hasStyles: ir.styles.length > 0
+    }
+}
+
+/**
+ * Extract slot definitions from template nodes
+ */
+function extractSlots(nodes: TemplateNode[]): SlotDefinition[] {
+    const slots: SlotDefinition[] = []
+
+    function traverse(node: TemplateNode) {
+        if (node.type === 'element') {
+            // Check if this is a <slot> tag
+            if (node.tag === 'slot') {
+                // Extract slot name from attributes
+                const nameAttr = node.attributes.find(attr => attr.name === 'name')
+                const slotName = typeof nameAttr?.value === 'string' ? nameAttr.value : null
+
+                slots.push({
+                    name: slotName,
+                    location: node.location
+                })
+            }
+
+            // Traverse children
+            for (const child of node.children) {
+                traverse(child)
+            }
+        } else if (node.type === 'component') {
+            // Also traverse component children
+            for (const child of node.children) {
+                traverse(child)
+            }
+        }
+    }
+
+    for (const node of nodes) {
+        traverse(node)
+    }
+
+    return slots
+}
+
+/**
+ * Check if a tag name represents a component (starts with uppercase)
+ */
+export function isComponentTag(tagName: string): boolean {
+    return tagName.length > 0 && tagName[0] !== undefined && tagName[0] === tagName[0].toUpperCase()
+}
+
+/**
+ * Get component metadata by name
+ */
+export function getComponent(
+    components: Map<string, ComponentMetadata>,
+    name: string
+): ComponentMetadata | undefined {
+    return components.get(name)
+}

package/compiler/errors/compilerError.ts

@@ -22,3 +22,35 @@ export class CompilerError extends Error {
   }
 }
 
+/**
+ * Invariant Error
+ * 
+ * Thrown when a Zenith compiler invariant is violated.
+ * Invariants are non-negotiable rules that guarantee correct behavior.
+ * 
+ * If an invariant fails, the compiler is at fault — not the user.
+ * The user receives a clear explanation of what is forbidden and why.
+ */
+export class InvariantError extends CompilerError {
+  invariantId: string
+  guarantee: string
+
+  constructor(
+    invariantId: string,
+    message: string,
+    guarantee: string,
+    file: string,
+    line: number,
+    column: number
+  ) {
+    super(`[${invariantId}] ${message}\n\n  Zenith Guarantee: ${guarantee}`, file, line, column)
+    this.name = 'InvariantError'
+    this.invariantId = invariantId
+    this.guarantee = guarantee
+  }
+
+  override toString(): string {
+    return `${this.file}:${this.line}:${this.column} [${this.invariantId}] ${this.message}`
+  }
+}
+