juxscript 1.0.1 → 1.0.3

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,30 +10,36 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// CLEAR PATH CONTRACT
+// 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 is (where they run `npx jux`)
+  // 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 user's dist output goes
-  get projectDist() {
-    return path.join(this.projectRoot, 'dist');
+  // 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(`   Lib: ${PATHS.juxLib}`);
-console.log(`   Dist: ${PATHS.projectDist}\n`);
+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];
 
@@ -47,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')) {
@@ -75,14 +81,21 @@ async function loadConfig() {
 }
 
 async function buildProject(isServe = false) {
-  console.log('🔨 Building JUX project...\n');
+  console.log('🔨 Building JUX frontend...\n');
   
   try {
-    // Clean and create dist
-    if (fs.existsSync(PATHS.projectDist)) {
-      fs.rmSync(PATHS.projectDist, { 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);
+    }
+
+    // Clean and create frontend dist
+    if (fs.existsSync(PATHS.frontendDist)) {
+      fs.rmSync(PATHS.frontendDist, { recursive: true, force: true });
     }
-    fs.mkdirSync(PATHS.projectDist, { recursive: true });
+    fs.mkdirSync(PATHS.frontendDist, { recursive: true });
 
     // Step 1: Generate documentation from jux lib
     console.log('📚 Generating documentation...');
@@ -93,21 +106,21 @@ async function buildProject(isServe = false) {
       console.warn('⚠️  Failed to generate docs:', error.message);
     }
 
-    // Step 2: Copy jux lib to project dist
-    await copyLibToOutput(PATHS.juxLib, PATHS.projectDist);
+    // Step 2: Copy jux lib to frontend dist
+    await copyLibToOutput(PATHS.juxLib, PATHS.frontendDist);
     
-    // Step 3: Copy project assets (CSS, JS)
-    await copyProjectAssets(PATHS.projectRoot, PATHS.projectDist);
+    // Step 3: Copy project assets from jux/ (CSS, JS, images)
+    await copyProjectAssets(PATHS.juxSource, PATHS.frontendDist);
 
-    // Step 4: Compile project .jux files
-    const projectJuxFiles = findJuxFiles(PATHS.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: PATHS.projectDist,
-          projectRoot: PATHS.projectRoot,
+          distDir: PATHS.frontendDist,
+          projectRoot: PATHS.juxSource,
           isServe
         });
       } catch (err) {
@@ -128,7 +141,7 @@ async function buildProject(isServe = false) {
           const relPath = path.relative(PATHS.juxLib, file);
           
           await compileJuxFile(file, { 
-            distDir: path.join(PATHS.projectDist, 'lib'),
+            distDir: path.join(PATHS.frontendDist, 'lib'),
             projectRoot: PATHS.juxLib,
             isServe 
           });
@@ -140,7 +153,16 @@ 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);
@@ -149,26 +171,105 @@ async function buildProject(isServe = false) {
 }
 
 (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: ${PATHS.projectDist}`);
+    console.log(`✅ Build complete: ${PATHS.frontendDist}`);
     
   } else if (command === 'serve') {
     await buildProject(true);
+    
     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)
 
+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-16T22:00:11.522Z"
+  "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/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.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "A JavaScript UX authorship platform",
   "main": "lib/jux.js",