juxscript 1.1.0 → 1.1.3

package/machinery/config.js

@@ -0,0 +1,155 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Default configuration
+export const defaultConfig = {
+  sourceDir: 'jux',
+  distDir: '.jux-dist',
+  ports: {
+    http: 3000,
+    ws: 3001
+  },
+  build: {
+    minify: false,
+    sourcemap: true
+  },
+  bootstrap: []
+};
+
+// Load user configuration
+export async function loadConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'juxconfig.js');
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const configModule = await import(`file://${configPath}`);
+      const userConfig = configModule.default || configModule;
+
+      return {
+        ...defaultConfig,
+        ...userConfig,
+        ports: { ...defaultConfig.ports, ...(userConfig.ports || {}) },
+        build: { ...defaultConfig.build, ...(userConfig.build || {}) }
+      };
+    } catch (err) {
+      console.warn(`⚠️  Failed to load juxconfig.js: ${err.message}`);
+      console.warn(`   Using default configuration\n`);
+      return defaultConfig;
+    }
+  }
+
+  console.log('ℹ️  No juxconfig.js found, using defaults');
+  return defaultConfig;
+}
+
+// Run bootstrap functions
+export async function runBootstrap(bootstrapFunctions = []) {
+  if (!Array.isArray(bootstrapFunctions) || bootstrapFunctions.length === 0) {
+    return;
+  }
+
+  console.log('🚀 Running bootstrap functions...\n');
+
+  for (const fn of bootstrapFunctions) {
+    if (typeof fn === 'function') {
+      try {
+        await fn();
+      } catch (err) {
+        console.error(`❌ Bootstrap function failed:`, err.message);
+      }
+    }
+  }
+
+  console.log('✅ Bootstrap complete\n');
+}
+
+/**
+ * Type helper for JUX Configuration (Identity function for Autocomplete)
+ * Used in juxconfig.js to provide Intellisense.
+ * @param {Object} config
+ * @returns {Object}
+ */
+export function defineConfig(config) {
+  return config;
+}
+
+/**
+ * Normalizes user configuration into the strict format used by the compiler/server.
+ * Handles "DX Sugar" like:
+ * - Inferring file extensions (.jux, .css)
+ * - Mapping 'dist' -> 'distribution'
+ * - Resolving shortcuts (e.g. layouts)
+ * - Defaulting ports
+ */
+export function resolveConfig(userConfig, projectRoot = process.cwd()) {
+  const root = userConfig.root || projectRoot;
+
+  // 1. Directories (Map 'dist' alias to 'distribution')
+  const dirs = userConfig.directories || {};
+  const directories = {
+    source: dirs.source || 'jux',
+    distribution: dirs.dist || dirs.distribution || '.jux-dist',
+    themes: dirs.themes || 'themes',
+    layouts: dirs.layouts || 'themes/layouts',
+    assets: dirs.assets || 'themes/assets'
+  };
+
+  // 2. Defaults (Infer extensions)
+  const defs = userConfig.defaults || {};
+  const httpPort = defs.port || defs.httpPort || 3000;
+
+  const defaults = {
+    httpPort,
+    wsPort: defs.wsPort || (httpPort + 1),
+    autoRoute: defs.autoRoute !== false, // default true
+    layout: ensureExt(defs.layout, '.jux') || 'base.jux',
+    theme: ensureExt(defs.theme, '.css') || 'base.css'
+  };
+
+  // 3. Pages Normalization (Recursively fix route paths)
+  const pages = normalizePages(userConfig.pages || {});
+
+  // 4. Return Normalized Config
+  return {
+    root,
+    directories,
+    defaults,
+    pages,
+    hooks: userConfig.hooks || {}
+  };
+}
+
+/**
+ * Helper: Appends extension if missing
+ */
+function ensureExt(file, ext) {
+  if (!file) return file;
+  return file.endsWith(ext) ? file : `${file}${ext}`;
+}
+
+/**
+ * Helper: Recursively normalizes page routes
+ */
+function normalizePages(pages) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(pages)) {
+    if (typeof value === 'string') {
+      // Direct route: '/' -> 'experiments/index'
+      // Becomes: '/' -> 'experiments/index.jux'
+      normalized[key] = ensureExt(value, '.jux');
+    } else if (typeof value === 'object') {
+      // Route Group
+      normalized[key] = {
+        ...value,
+        layout: value.layout ? ensureExt(value.layout, '.jux') : undefined,
+        theme: value.theme ? ensureExt(value.theme, '.css') : undefined,
+        routes: normalizePages(value.routes || {})
+      };
+    }
+  }
+  return normalized;
+}

package/machinery/doc-generator.js

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+
+/**
+ * Generate documentation from TypeScript component files
+ * 
+ * @param {string} juxLibPath - Absolute path to jux/lib directory
+ */
+export async function generateDocs(juxLibPath) {
+  const componentsDir = path.join(juxLibPath, 'components');
+  
+  if (!fs.existsSync(componentsDir)) {
+    throw new Error(`Components directory not found: ${componentsDir}`);
+  }
+  
+  console.log(`  Scanning: ${componentsDir}`);
+  
+  // Find all component TypeScript files
+  const componentFiles = glob.sync('*.ts', {
+    cwd: componentsDir,
+    absolute: true,
+    ignore: ['reactivity.ts', 'error-handler.ts']
+  });
+
+  console.log(`  Found ${componentFiles.length} component files`);
+
+  const components = [];
+
+  for (const filePath of componentFiles) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const componentDoc = parseComponentFile(content, filePath);
+    
+    if (componentDoc) {
+      components.push(componentDoc);
+      console.log(`    ✓ ${componentDoc.name}`);
+    }
+  }
+
+  // Sort by category and name
+  components.sort((a, b) => {
+    const categoryCompare = (a.category || 'ZZZ').localeCompare(b.category || 'ZZZ');
+    if (categoryCompare !== 0) return categoryCompare;
+    return a.name.localeCompare(b.name);
+  });
+
+  // Generate the docs data
+  const docsData = {
+    components,
+    version: '1.0.0',
+    lastUpdated: new Date().toISOString()
+  };
+
+  // Write to JSON file
+  const outputPath = path.join(componentsDir, 'docs-data.json');
+  fs.writeFileSync(outputPath, JSON.stringify(docsData, null, 2));
+  
+  console.log(`  Generated: ${outputPath}`);
+  
+  return docsData;
+}
+
+/**
+ * Parse a single component file
+ */
+function parseComponentFile(content, filePath) {
+  const fileName = path.basename(filePath, '.ts');
+  const className = fileName.charAt(0).toUpperCase() + fileName.slice(1);
+  
+  const category = inferCategory(className, content);
+  const descMatch = content.match(/\/\*\*\s*\n\s*\*\s*([^\n*]+)/);
+  const description = descMatch ? descMatch[1].trim() : `${className} component`;
+  const factoryMatch = content.match(/export function\s+\w+\(([^)]*)\)/);
+  const constructorSig = factoryMatch 
+    ? `jux.${fileName}(${factoryMatch[1]})`
+    : `new ${className}()`;
+  const fluentMethods = extractFluentMethods(content, className);
+  const exampleMatch = content.match(/\*\s+Usage:\s*\n\s*\*\s+(.+?)(?:\n|$)/);
+  let example = exampleMatch 
+    ? exampleMatch[1].trim()
+    : `jux.${fileName}('id').render()`;
+  
+  return {
+    name: className,
+    category,
+    description,
+    constructor: constructorSig,
+    fluentMethods,
+    example
+  };
+}
+
+/**
+ * Extract fluent API methods from class
+ */
+function extractFluentMethods(content, className) {
+  const methods = [];
+  const methodRegex = /^\s*(\w+)\(([^)]*)\):\s*this\s*\{/gm;
+  let match;
+  
+  while ((match = methodRegex.exec(content)) !== null) {
+    const methodName = match[1];
+    const params = match[2];
+    if (methodName.startsWith('_') || methodName === 'constructor') continue;
+    const cleanParams = params.split(',').map(p => p.trim().split(':')[0].trim()).filter(p => p).join(', ');
+    methods.push({
+      name: methodName,
+      params: cleanParams ? `(${cleanParams})` : '()',
+      returns: 'this',
+      description: `Set ${methodName}`
+    });
+  }
+  
+  const renderMatch = content.match(/^\s*render\(([^)]*)\):\s*(\w+)/m);
+  if (renderMatch && !methods.find(m => m.name === 'render')) {
+    methods.push({
+      name: 'render',
+      params: renderMatch[1] ? `(${renderMatch[1]})` : '()',
+      returns: renderMatch[2],
+      description: 'Render component to DOM'
+    });
+  }
+  
+  return methods;
+}
+
+/**
+ * Infer category from component name or content
+ */
+function inferCategory(name, content) {
+  const dataComponents = ['Table', 'List', 'Chart', 'Data'];
+  const coreComponents = ['App', 'Layout', 'Theme', 'Style', 'Script', 'Import'];
+  if (dataComponents.some(dc => name.includes(dc))) return 'Data Components';
+  if (coreComponents.includes(name)) return 'Core';
+  return 'UI Components';
+}

package/machinery/imports.js

@@ -0,0 +1,155 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REGISTRY_PATH = path.join(__dirname, '../lib/registry/packages.json');
+
+/**
+ * Load package registry
+ */
+function loadRegistry() {
+  if (!fs.existsSync(REGISTRY_PATH)) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf-8'));
+}
+
+/**
+ * Parse @import directives from Jux code
+ */
+export function parseImports(juxCode) {
+  const imports = [];
+  const lines = juxCode.split('\n');
+  
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    
+    // Stop parsing when we hit actual code (non-directive, non-comment)
+    if (line && !line.startsWith('@') && !line.startsWith('//') && !line.startsWith('/*')) {
+      break;
+    }
+    
+    // Match @import directive
+    const importMatch = line.match(/^@import\s+(.+)$/);
+    if (importMatch) {
+      const importSpec = importMatch[1].trim();
+      imports.push({
+        line: i + 1,
+        raw: importSpec,
+        resolved: resolveImport(importSpec)
+      });
+      
+      if (process.env.JUX_VERBOSE) {
+        console.log(`  [Line ${i + 1}] Found @import: ${importSpec}`);
+      }
+    }
+  }
+  
+  return imports;
+}
+
+/**
+ * Resolve import specification to URL/path
+ */
+export function resolveImport(importSpec) {
+  // Remove quotes if present
+  const cleaned = importSpec.replace(/^['"]|['"]$/g, '');
+  
+  // Direct URL (starts with http:// or https://)
+  if (cleaned.startsWith('http://') || cleaned.startsWith('https://')) {
+    return {
+      type: 'cdn',
+      url: cleaned,
+      source: 'direct'
+    };
+  }
+  
+  // Local file (starts with ./ or ../ or /)
+  if (cleaned.startsWith('./') || cleaned.startsWith('../') || cleaned.startsWith('/')) {
+    return {
+      type: 'local',
+      path: cleaned,
+      source: 'file'
+    };
+  }
+  
+  // Unknown/unsupported
+  return {
+    type: 'unknown',
+    name: cleaned,
+    error: `Import "${cleaned}" must be a URL (https://...) or relative path (./...)`
+  };
+}
+
+/**
+ * Auto-detect component dependencies
+ */
+function detectComponentDependencies(usedComponents) {
+  const componentDeps = {
+    'chart': 'chart.js'
+    // Add more mappings as needed
+  };
+  
+  const deps = new Set();
+  
+  usedComponents.forEach(comp => {
+    if (componentDeps[comp]) {
+      deps.add(componentDeps[comp]);
+    }
+  });
+  
+  return Array.from(deps).map(pkg => ({
+    auto: true,
+    resolved: resolveImport(pkg)
+  }));
+}
+
+/**
+ * Generate HTML script tags from resolved imports
+ */
+export function generateImportTags(imports) {
+  const tags = [];
+  const seen = new Set();
+  
+  for (const imp of imports) {
+    const resolved = imp.resolved;
+    
+    if (resolved.type === 'unknown') {
+      tags.push(`<!-- ERROR: ${resolved.error} -->`);
+      continue;
+    }
+    
+    const key = resolved.url || resolved.path;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    
+    if (resolved.type === 'cdn') {
+      tags.push(`  <script src="${resolved.url}"></script>`);
+    } else if (resolved.type === 'local') {
+      tags.push(`  <script type="module" src="${resolved.path}"></script>`);
+    }
+  }
+  
+  return tags.join('\n');
+}
+
+/**
+ * Validate all imports are resolvable
+ */
+export function validateImports(imports) {
+  const errors = [];
+  
+  imports.forEach(imp => {
+    if (imp.resolved.type === 'unknown') {
+      errors.push({
+        line: imp.line,
+        message: imp.resolved.error,
+        raw: imp.raw
+      });
+    }
+  });
+  
+  return errors;
+}

package/machinery/serve.js

@@ -0,0 +1,255 @@
+import express from 'express';
+import path from 'path';
+import fs from 'fs';
+import http from 'http';
+import { fileURLToPath } from 'url';
+import { WebSocketServer } from 'ws';
+import { createWatcher } from './watcher.js';
+import { JuxCompiler } from './compiler3.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ═══════════════════════════════════════════════════════════════
+// CONFIGURATION
+// ═══════════════════════════════════════════════════════════════
+const args = process.argv.slice(2);
+const HOT_RELOAD = args.includes('--hot') || args.includes('-h') || args.includes('--watch');
+
+// Extract port from args (e.g., --port=3000 or -p 3000)
+function getArgValue(flag, shortFlag, defaultValue) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith(`${flag}=`)) return args[i].split('=')[1];
+    if (args[i].startsWith(`${shortFlag}=`)) return args[i].split('=')[1];
+    if ((args[i] === flag || args[i] === shortFlag) && args[i + 1]) return args[i + 1];
+  }
+  return defaultValue;
+}
+
+const PORT = parseInt(getArgValue('--port', '-p', process.env.PORT || '3000'));
+const WS_PORT = parseInt(getArgValue('--ws-port', '-w', process.env.WS_PORT || String(PORT + 1)));
+
+// Resolve paths relative to CWD (user's project)
+const PROJECT_ROOT = process.cwd();
+const DIST_DIR = path.resolve(PROJECT_ROOT, '.jux-dist');
+const SRC_DIR = path.resolve(PROJECT_ROOT, 'jux');
+
+const app = express();
+let lastBuildResult = { success: true, errors: [] };
+
+// Check if dist directory exists - if not, try to build first
+if (!fs.existsSync(DIST_DIR) || !fs.existsSync(path.join(DIST_DIR, 'index.html'))) {
+  console.log('⚠️  Dist directory not found. Running initial build...');
+
+  const compiler = new JuxCompiler({
+    srcDir: SRC_DIR,
+    distDir: DIST_DIR
+  });
+
+  try {
+    const result = await compiler.build();
+    lastBuildResult = result;
+
+    if (!result.success) {
+      console.log('\n❌ Initial build failed. Starting server to show error overlay.\n');
+    }
+  } catch (err) {
+    console.error('❌ Initial build failed:', err.message);
+    lastBuildResult = { success: false, errors: [{ message: err.message }] };
+  }
+}
+
+if (!fs.existsSync(DIST_DIR)) {
+  fs.mkdirSync(DIST_DIR, { recursive: true });
+}
+
+app.use((req, res, next) => {
+  res.setHeader('Cache-Control', 'no-store');
+  next();
+});
+
+app.use((req, res, next) => {
+  if (req.path.endsWith('.js')) {
+    res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+  }
+  next();
+});
+
+app.get('/favicon.ico', (req, res) => res.status(204).end());
+app.get('/favicon.png', (req, res) => res.status(204).end());
+
+app.get('/__jux_sources.json', (req, res) => {
+  const snapshotPath = path.join(DIST_DIR, '__jux_sources.json');
+  if (fs.existsSync(snapshotPath)) {
+    res.setHeader('Content-Type', 'application/json');
+    res.sendFile(snapshotPath);
+  } else {
+    res.json({});
+  }
+});
+
+const hotReloadScript = `
+<script>
+(function() {
+    var ws = new WebSocket('ws://localhost:${WS_PORT}');
+    ws.onopen = function() { console.log('🔥 Hot reload connected'); };
+    ws.onmessage = function(e) {
+        var data = JSON.parse(e.data);
+        if (data.type === 'reload') location.reload();
+        else if (data.type === 'build-error') console.error('❌ Build error:', data.errors);
+    };
+    ws.onclose = function() { setTimeout(function() { location.reload(); }, 2000); };
+})();
+</script>
+`;
+
+function getErrorPageHtml(errors) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>JUX Build Error</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body { font-family: monospace; background: #1a1a2e; color: #eee; min-height: 100vh; padding: 40px; }
+        .container { max-width: 800px; margin: 0 auto; }
+        h1 { color: #ff6b6b; margin-bottom: 8px; }
+        .subtitle { color: #888; margin-bottom: 30px; }
+        .error-card { background: #16213e; padding: 16px 20px; border-radius: 8px; margin-bottom: 12px; border-left: 4px solid #ff6b6b; }
+        .error-header { color: #ff6b6b; font-weight: bold; margin-bottom: 8px; }
+        .error-code { background: #0f0f23; padding: 12px; border-radius: 4px; font-size: 13px; color: #888; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🛑 Build Failed</h1>
+        <p class="subtitle">Fix the errors below and save to rebuild.</p>
+        ${errors.map(err => `
+            <div class="error-card">
+                <div class="error-header">${err.view ? `[${err.view}] ` : ''}${err.message}</div>
+                ${err.code ? `<pre class="error-code">${err.code}</pre>` : ''}
+            </div>
+        `).join('')}
+    </div>
+    ${HOT_RELOAD ? `<script>
+        var ws = new WebSocket('ws://localhost:${WS_PORT}');
+        ws.onmessage = function(e) { if (JSON.parse(e.data).type === 'reload') location.reload(); };
+    </script>` : ''}
+</body>
+</html>`;
+}
+
+if (HOT_RELOAD) {
+  app.get(['/', '/index.html'], (req, res) => {
+    const indexPath = path.join(DIST_DIR, 'index.html');
+
+    if (!fs.existsSync(indexPath) || !lastBuildResult.success) {
+      return res.send(getErrorPageHtml(lastBuildResult.errors));
+    }
+
+    let html = fs.readFileSync(indexPath, 'utf8');
+    html = html.replace('</body>', hotReloadScript + '</body>');
+    res.setHeader('Content-Type', 'text/html');
+    res.send(html);
+  });
+}
+
+app.use(express.static(DIST_DIR));
+
+app.get('*', (req, res) => {
+  if (path.extname(req.path) && req.path !== '/') {
+    return res.status(404).send('Not found');
+  }
+
+  const indexPath = path.join(DIST_DIR, 'index.html');
+
+  if (!fs.existsSync(indexPath) || !lastBuildResult.success) {
+    return res.send(getErrorPageHtml(lastBuildResult.errors));
+  }
+
+  if (HOT_RELOAD) {
+    let html = fs.readFileSync(indexPath, 'utf8');
+    html = html.replace('</body>', hotReloadScript + '</body>');
+    res.setHeader('Content-Type', 'text/html');
+    res.send(html);
+  } else {
+    res.sendFile(indexPath);
+  }
+});
+
+const server = http.createServer(app);
+let wss = null;
+let watcher = null;
+
+if (HOT_RELOAD) {
+  wss = new WebSocketServer({ port: WS_PORT });
+  const clients = new Set();
+
+  wss.on('connection', (ws) => {
+    clients.add(ws);
+    ws.on('close', () => clients.delete(ws));
+  });
+
+  const broadcast = (message) => {
+    const data = JSON.stringify(message);
+    clients.forEach(client => {
+      if (client.readyState === 1) client.send(data);
+    });
+  };
+
+  const compiler = new JuxCompiler({
+    srcDir: SRC_DIR,
+    distDir: DIST_DIR
+  });
+
+  watcher = createWatcher(SRC_DIR, {
+    onChange: async (changedFiles) => {
+      console.log('🔄 Rebuilding...');
+
+      try {
+        const result = await compiler.build();
+        lastBuildResult = result;
+
+        if (!result.success) {
+          console.error('❌ Rebuild failed');
+          broadcast({ type: 'build-error', errors: result.errors });
+          return;
+        }
+
+        console.log('✅ Rebuild complete');
+        broadcast({ type: 'reload', files: changedFiles });
+      } catch (err) {
+        console.error('❌ Rebuild failed:', err.message);
+        lastBuildResult = { success: false, errors: [{ message: err.message }] };
+        broadcast({ type: 'build-error', errors: [{ message: err.message }] });
+      }
+    },
+    onReady: () => {
+      console.log(`👀 Watching: ${SRC_DIR}`);
+    }
+  });
+}
+
+server.listen(PORT, () => {
+  console.log(`\n🚀 JUX Server running at http://localhost:${PORT}`);
+  if (HOT_RELOAD) {
+    console.log(`🔥 Hot reload: ws://localhost:${WS_PORT}`);
+  }
+  if (!lastBuildResult.success) {
+    console.log(`⚠️  Build has errors - fix them and save\n`);
+  }
+});
+
+const shutdown = () => {
+  console.log('\n👋 Shutting down...');
+  if (watcher) watcher.close();
+  if (wss) {
+    wss.clients.forEach(client => client.terminate());
+    wss.close();
+  }
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 2000);
+};
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);