juxscript 1.0.0 → 1.0.2

package/README.md

@@ -21,7 +21,19 @@ Have you ever considered the energy requirements to ship chunks of HTML markup l
 
 ## GETTING STARTED
 
-
+```bash
+# New project
+mkdir my-project
+cd my-project
+npm init -y
+npm install juxscript
+
+# Initialize (creates jux/ directory)
+npx jux init
+
+# Builds jux-dist and serves index.jux
+npx jux serve
+```
 > install
 `npm i juxscript`
 

package/bin/cli.js

@@ -10,11 +10,42 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// CLEAR PATH CONTRACT - CONVENTIONS
+const PATHS = {
+  // Where jux package is installed (in node_modules/juxscript or local dev)
+  packageRoot: path.resolve(__dirname, '..'),
+  
+  // Where the user's project root is (where they run `npx jux`)
+  projectRoot: process.cwd(),
+  
+  // Where user's .jux source files live (CONVENTION: ./jux/)
+  get juxSource() {
+    return path.join(this.projectRoot, 'jux');
+  },
+  
+  // Where jux lib files are (components, layouts, etc.)
+  get juxLib() {
+    return path.join(this.packageRoot, 'lib');
+  },
+  
+  // Where frontend build output goes (CONVENTION: ./jux-dist/)
+  get frontendDist() {
+    return path.join(this.projectRoot, 'jux-dist');
+  }
+};
+
+console.log('📍 JUX Paths:');
+console.log(`   Package:  ${PATHS.packageRoot}`);
+console.log(`   Project:  ${PATHS.projectRoot}`);
+console.log(`   Source:   ${PATHS.juxSource}`);
+console.log(`   Output:   ${PATHS.frontendDist}`);
+console.log(`   Lib:      ${PATHS.juxLib}\n`);
+
 const command = process.argv[2];
-const projectRoot = process.cwd();
-const distDir = path.join(projectRoot, 'dist');
 
 function findJuxFiles(dir, fileList = []) {
+  if (!fs.existsSync(dir)) return fileList;
+  
   const files = fs.readdirSync(dir);
   
   files.forEach(file => {
@@ -22,7 +53,7 @@ function findJuxFiles(dir, fileList = []) {
     const stat = fs.statSync(filePath);
     
     if (stat.isDirectory()) {
-      if (file !== 'node_modules' && file !== 'dist' && file !== '.git') {
+      if (file !== 'node_modules' && file !== 'jux-dist' && file !== '.git' && file !== 'server') {
         findJuxFiles(filePath, fileList);
       }
     } else if (file.endsWith('.jux')) {
@@ -34,7 +65,7 @@ function findJuxFiles(dir, fileList = []) {
 }
 
 async function loadConfig() {
-  const configPath = path.join(projectRoot, 'jux.config.js');
+  const configPath = path.join(PATHS.projectRoot, 'jux.config.js');
   
   if (fs.existsSync(configPath)) {
     try {
@@ -50,44 +81,55 @@ async function loadConfig() {
 }
 
 async function buildProject(isServe = false) {
-  console.log('🔨 Building JUX project...\n');
+  console.log('🔨 Building JUX frontend...\n');
   
   try {
-    if (fs.existsSync(distDir)) {
-      fs.rmSync(distDir, { recursive: true, force: true });
+    // Verify jux source directory exists
+    if (!fs.existsSync(PATHS.juxSource)) {
+      console.error(`❌ Source directory not found: ${PATHS.juxSource}`);
+      console.error(`   Please create a 'jux/' directory with your .jux files`);
+      process.exit(1);
     }
-    fs.mkdirSync(distDir, { recursive: true });
 
-    // Step 1: Generate documentation FIRST
+    // Clean and create frontend dist
+    if (fs.existsSync(PATHS.frontendDist)) {
+      fs.rmSync(PATHS.frontendDist, { recursive: true, force: true });
+    }
+    fs.mkdirSync(PATHS.frontendDist, { recursive: true });
+
+    // Step 1: Generate documentation from jux lib
     console.log('📚 Generating documentation...');
     try {
-      await generateDocs(projectRoot);
+      await generateDocs(PATHS.juxLib);
       console.log('✅ Documentation generated\n');
     } catch (error) {
       console.warn('⚠️  Failed to generate docs:', error.message);
     }
 
-    // Step 2: Copy lib/ to dist/lib/ (includes docs-data.json)
-    await copyLibToOutput(projectRoot, distDir);
+    // Step 2: Copy jux lib to frontend dist
+    await copyLibToOutput(PATHS.juxLib, PATHS.frontendDist);
     
-    // Step 3: Copy project assets (CSS, JS) from project root
-    await copyProjectAssets(projectRoot, distDir);
+    // Step 3: Copy project assets from jux/ (CSS, JS, images)
+    await copyProjectAssets(PATHS.juxSource, PATHS.frontendDist);
 
-    // Step 4: Find and compile project .jux files
-    const projectJuxFiles = findJuxFiles(projectRoot);
-    console.log(`Found ${projectJuxFiles.length} project .jux file(s)\n`);
+    // Step 4: Compile .jux files from jux/ directory ONLY
+    const projectJuxFiles = findJuxFiles(PATHS.juxSource);
+    console.log(`Found ${projectJuxFiles.length} .jux file(s) in /jux\n`);
 
     for (const file of projectJuxFiles) {
       try {
-        await compileJuxFile(file, { distDir, projectRoot, isServe });
+        await compileJuxFile(file, {
+          distDir: PATHS.frontendDist,
+          projectRoot: PATHS.juxSource,
+          isServe
+        });
       } catch (err) {
         console.error(`Error compiling ${file}:`, err.message);
       }
     }
 
-    // Step 5: Find and compile vendor layout .jux files
-    const libRoot = path.resolve(projectRoot, '../lib');
-    const layoutsDir = path.join(libRoot, 'layouts');
+    // Step 5: Compile vendor layouts
+    const layoutsDir = path.join(PATHS.juxLib, 'layouts');
     
     if (fs.existsSync(layoutsDir)) {
       console.log('\n📐 Compiling vendor layouts...');
@@ -96,11 +138,11 @@ async function buildProject(isServe = false) {
       
       for (const file of vendorJuxFiles) {
         try {
-          const relPath = path.relative(libRoot, file);
+          const relPath = path.relative(PATHS.juxLib, file);
           
           await compileJuxFile(file, { 
-            distDir: path.join(distDir, 'lib'),
-            projectRoot: libRoot, 
+            distDir: path.join(PATHS.frontendDist, 'lib'),
+            projectRoot: PATHS.juxLib,
             isServe 
           });
           
@@ -111,38 +153,123 @@ async function buildProject(isServe = false) {
       }
     }
 
-    console.log(`\n✅ Built ${projectJuxFiles.length} project file(s) + layouts\n`);
+    console.log(`\n✅ Built ${projectJuxFiles.length} file(s) → ${PATHS.frontendDist}\n`);
+    
+    // Show backend integration examples
+    console.log('📦 Serve from your backend:');
+    console.log(`   Express:  app.use(express.static('jux-dist'))`);
+    console.log(`   Flask:    app = Flask(__name__, static_folder='jux-dist')`);
+    console.log(`   FastAPI:  app.mount("/", StaticFiles(directory="jux-dist"), name="static")`);
+    console.log(`   Laravel:  Route::view('/', 'jux-dist/index.html')`);
+    console.log('');
+    
   } catch (err) {
     console.error('❌ Build error:', err.message);
+    console.error(err.stack);
     process.exit(1);
   }
 }
 
 (async () => {
-  if (command === 'build') {
+  if (command === 'init') {
+    console.log('🎨 Initializing JUX project...\n');
+    
+    const juxDir = PATHS.juxSource;
+    
+    if (fs.existsSync(juxDir)) {
+      console.error('❌ jux/ directory already exists');
+      process.exit(1);
+    }
+    
+    // Create structure
+    fs.mkdirSync(juxDir, { recursive: true });
+    
+    // Copy template file from lib/templates/index.juxt
+    const templatePath = path.join(PATHS.packageRoot, 'lib', 'templates', 'index.juxt');
+    const targetPath = path.join(juxDir, 'index.jux');
+    
+    if (fs.existsSync(templatePath)) {
+      fs.copyFileSync(templatePath, targetPath);
+      console.log('✅ Created jux/index.jux from template');
+    } else {
+      // Fallback if template doesn't exist
+      console.warn('⚠️  Template not found, creating basic index.jux');
+      const fallbackContent = `// Welcome to JUX!
+import { jux } from '/lib/jux.js';
+
+jux.style('/lib/layouts/default.css');
+jux.theme('light');
+
+const header = jux.header('header').render("#app");
+const main = jux.main('main').render("#app");
+const footer = jux.footer('footer').render("#app");
+
+jux.hero('hero1', {
+  title: 'Welcome to JUX',
+  subtitle: 'A JavaScript UX authorship platform'
+}).render('#main');
+`;
+      fs.writeFileSync(targetPath, fallbackContent);
+      console.log('✅ Created jux/index.jux');
+    }
+    
+    // Create .gitignore
+    const gitignorePath = path.join(PATHS.projectRoot, '.gitignore');
+    const gitignoreContent = `jux-dist/
+node_modules/
+.DS_Store
+`;
+    
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, gitignoreContent);
+      console.log('✅ Created .gitignore');
+    }
+    
+    console.log('✅ Created jux/ directory\n');
+    console.log('Next steps:');
+    console.log('  1. Edit jux/index.jux');
+    console.log('  2. Run: npx jux build');
+    console.log('  3. Serve jux-dist/ from your backend\n');
+    
+  } else if (command === 'build') {
     await buildProject(false);
-    console.log(`✅ Build complete: ${distDir}`);
+    console.log(`✅ Build complete: ${PATHS.frontendDist}`);
     
   } else if (command === 'serve') {
-    // Build first
-    await buildProject(true); // isServe = true
+    await buildProject(true);
     
-    // Start server with watcher
     const config = await loadConfig();
-    await start(3000, config);
+    config.distDir = PATHS.frontendDist;  // Pass the correct dist directory
+    
+    const port = parseInt(process.argv[3]) || 3000;
+    await start(port, config);
     
   } else {
     console.log(`
 JUX CLI - A JavaScript UX authorship platform
 
 Usage:
-  npx jux build              Compile all .jux files to HTML/CSS/JS
+  npx jux init               Initialize a new JUX project
+  npx jux build              Compile .jux files from ./jux/ to ./jux-dist/
   npx jux serve [port]       Start dev server with hot reload (default: 3000)
-                             Builds automatically if dist/ doesn't exist
+
+Project Structure (Convention):
+  my-project/
+  ├── jux/                   # Your .jux source files (REQUIRED)
+  │   ├── index.jux
+  │   └── pages/
+  ├── jux-dist/             # Build output (generated, git-ignore this)
+  ├── server/               # Your backend (untouched by jux)
+  └── package.json
+
+Getting Started:
+  1. npx jux init           # Create jux/ directory
+  2. npx jux build          # Build to jux-dist/
+  3. Serve jux-dist/ from your backend
 
 Examples:
   npx jux build              Build for production
-  npx jux serve              Start dev server (builds if needed)
+  npx jux serve              Start dev server
   npx jux serve 8080         Start on port 8080
     `);
   }

package/lib/components/docs-data.json

@@ -1207,5 +1207,5 @@
     }
   ],
   "version": "1.0.0",
-  "lastUpdated": "2026-01-16T19:58:49.958Z"
+  "lastUpdated": "2026-01-16T23:06:56.674Z"
 }

package/lib/templates/index.juxt

@@ -0,0 +1,33 @@
+// Welcome to JUX!
+import { code } from '/lib/components/code.js';
+import { jux } from '/lib/jux.js';
+
+jux.style('/lib/layouts/notion.css');
+jux.theme('light');
+
+const appheader = jux.header('appheader', {}).render("#app");
+const appsubheader = jux.header('appsubheader', {}).render("#app");
+const appsidebar = jux.sidebar('appsidebar', {}).render("#app");
+const appmain = jux.main('appmain', {}).render("#app");
+const appaside = jux.sidebar('appaside', {}).render("#app");
+const appfooter = jux.footer('appfooter', {}).render("#app");
+const appmodal = jux.modal('appmodal', {}).render("#app");
+
+
+await jux.hero('hero1', {
+  title: 'Welcome to JUX',
+  subtitle: 'A JavaScript UX authorship platform'
+}).render();
+
+const code1 = code('code1').code(`Serve from your backend:
+   Express:  app.use(express.static('jux-dist'))
+   Flask:    app = Flask(__name__, static_folder='jux-dist')
+   FastAPI:  app.mount("/", StaticFiles(directory="jux-dist"), name="static")
+   Laravel:  Route::view('/', 'jux-dist/index.html')`)
+   .language('bash');
+
+   code1.render();
+
+  // note
+  // render()
+  // renderTo()

package/machinery/doc-generator.js

@@ -4,10 +4,15 @@ import { glob } from 'glob';
 
 /**
  * Generate documentation from TypeScript component files
+ * 
+ * @param {string} juxLibPath - Absolute path to jux/lib directory
  */
-export async function generateDocs(projectRoot) {
-  const libRoot = path.resolve(projectRoot, '../lib');
-  const componentsDir = path.join(libRoot, 'components');
+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}`);
   
@@ -15,7 +20,7 @@ export async function generateDocs(projectRoot) {
   const componentFiles = glob.sync('*.ts', {
     cwd: componentsDir,
     absolute: true,
-    ignore: ['reactivity.js', 'error-handler.ts', 'docs.ts']
+    ignore: ['reactivity.ts', 'error-handler.ts']
   });
 
   console.log(`  Found ${componentFiles.length} component files`);
@@ -62,23 +67,14 @@ function parseComponentFile(content, filePath) {
   const fileName = path.basename(filePath, '.ts');
   const className = fileName.charAt(0).toUpperCase() + fileName.slice(1);
   
-  // Extract category from file content or infer
   const category = inferCategory(className, content);
-  
-  // Extract description from class JSDoc
   const descMatch = content.match(/\/\*\*\s*\n\s*\*\s*([^\n*]+)/);
   const description = descMatch ? descMatch[1].trim() : `${className} component`;
-  
-  // Extract constructor/factory pattern
   const factoryMatch = content.match(/export function\s+\w+\(([^)]*)\)/);
   const constructorSig = factoryMatch 
     ? `jux.${fileName}(${factoryMatch[1]})`
     : `new ${className}()`;
-  
-  // Extract fluent methods
   const fluentMethods = extractFluentMethods(content, className);
-  
-  // Extract usage example from JSDoc
   const exampleMatch = content.match(/\*\s+Usage:\s*\n\s*\*\s+(.+?)(?:\n|$)/);
   let example = exampleMatch 
     ? exampleMatch[1].trim()
@@ -99,28 +95,14 @@ function parseComponentFile(content, filePath) {
  */
 function extractFluentMethods(content, className) {
   const methods = [];
-  
-  // Match method patterns: methodName(params): this
   const methodRegex = /^\s*(\w+)\(([^)]*)\):\s*this\s*\{/gm;
   let match;
   
   while ((match = methodRegex.exec(content)) !== null) {
     const methodName = match[1];
     const params = match[2];
-    
-    // Skip private methods and constructor
     if (methodName.startsWith('_') || methodName === 'constructor') continue;
-    
-    // Clean up params
-    const cleanParams = params
-      .split(',')
-      .map(p => {
-        const parts = p.trim().split(':');
-        return parts[0].trim();
-      })
-      .filter(p => p)
-      .join(', ');
-    
+    const cleanParams = params.split(',').map(p => p.trim().split(':')[0].trim()).filter(p => p).join(', ');
     methods.push({
       name: methodName,
       params: cleanParams ? `(${cleanParams})` : '()',
@@ -129,7 +111,6 @@ function extractFluentMethods(content, className) {
     });
   }
   
-  // Also look for render methods
   const renderMatch = content.match(/^\s*render\(([^)]*)\):\s*(\w+)/m);
   if (renderMatch && !methods.find(m => m.name === 'render')) {
     methods.push({
@@ -149,12 +130,7 @@ function extractFluentMethods(content, className) {
 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';
-  }
+  if (dataComponents.some(dc => name.includes(dc))) return 'Data Components';
+  if (coreComponents.includes(name)) return 'Core';
   return 'UI Components';
 }

package/machinery/server.js

@@ -12,7 +12,7 @@ const __dirname = path.dirname(__filename);
 
 let db = null;
 
-async function serve(port = 3000, distDir = './dist') {
+async function serve(port = 3000, distDir = './jux-dist') {  // Changed default
   const app = express();
   const absoluteDistDir = path.resolve(distDir);
   const projectRoot = path.resolve('.');
@@ -20,8 +20,8 @@ async function serve(port = 3000, distDir = './dist') {
   app.use(express.json());
 
   if (!fs.existsSync(absoluteDistDir)) {
-    console.error(`Error: dist directory not found at ${absoluteDistDir}`);
-    console.log('Building project first...\n');
+    console.error(`❌ Error: ${path.basename(distDir)}/ directory not found at ${absoluteDistDir}`);
+    console.error('   Run: npx jux build\n');
     process.exit(1);
   }
 
@@ -146,16 +146,23 @@ async function serve(port = 3000, distDir = './dist') {
   // Start HTTP server
   server.listen(port, () => {
     console.log(`🚀 JUX dev server running at http://localhost:${port}`);
+    console.log(`   Serving: ${absoluteDistDir}`);
+    console.log(`   Press Ctrl+C to stop\n`);
   });
 
   // Start file watcher
-  startWatcher(projectRoot, absoluteDistDir, clients);
+  const juxSource = path.join(projectRoot, 'jux');
+  if (fs.existsSync(juxSource)) {
+    console.log(`👀 Watching: ${juxSource}\n`);
+    startWatcher(juxSource, absoluteDistDir, clients);
+  }
 
   // Graceful shutdown
   const shutdown = async () => {
     console.log('\n\n👋 Shutting down server...');
     wss.close();
     server.close();
+    if (db) db = null;
     process.exit(0);
   };
 
@@ -181,5 +188,5 @@ async function initDatabase() {
 
 export async function start(port = 3000, config = {}) {
   await initDatabase();
-  return serve(port, config.distDir || './dist');
+  return serve(port, config.distDir || './jux-dist');  // Changed default
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juxscript",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "A JavaScript UX authorship platform",
   "main": "lib/jux.js",