clovie 0.1.4 → 0.1.6

package/README.md

@@ -1,40 +1,105 @@
 # Clovie - Vintage Web Dev Tooling
 
-A Node.js-based static site generator designed to be simple, fast, and highly modular. The "Hollow Knight of Web Dev" - simple but deep, easy to start but room to grow.
+A Node.js-based static site generator and web framework designed to be simple, fast, and highly modular. Built on the **brickworks/engine** pattern for maximum flexibility and maintainability.
+
+## Architecture Overview
+
+Clovie uses a **service-oriented architecture** where all functionality is provided by services that extend `ServiceProvider` from the brickworks/engine framework. The engine orchestrates these services through dependency injection and provides stable state management.
+
+### Core Services
+
+- **File** - File system operations (reading, writing, watching)
+- **Compiler** - Template compilation with live reload injection  
+- **Views** - View discovery and processing
+- **Routes** - Route generation and processing (static & dynamic)
+- **Build** - Static site generation orchestration
+- **Server** - Express server management (conditionally loaded)
+- **Cache** - Build caching and incremental builds
+
+### Two Operating Modes
+
+**Static Mode (`type: 'static'`)**:
+- Generates static HTML files to output directory
+- Uses Express server only for development (live reload, file serving)
+- Traditional static site generator behavior
+
+**Server Mode (`type: 'server'`)**:
+- Builds a real Express application 
+- Serves static files + handles dynamic routes/API endpoints
+- Full web application server with server-side rendering
 
 ## Project Structure
 
 ```
-packages/clovie/
-├── __tests__/           # Test files
-│   └── index.test.js
-├── bin/                 # CLI executable
-│   └── cli.js
-├── config/              # Configuration files
-│   └── default.config.js
-├── lib/                 # Source code
-│   ├── core/           # Core functionality
-│   │   ├── index.js    # Main Clovie class
-│   │   ├── bundler.js  # JavaScript bundling
-│   │   ├── render.js   # Template rendering
-│   │   ├── write.js    # File writing
-│   │   ├── getViews.js # View processing
-│   │   ├── getData.js  # Data loading
-│   │   ├── getStyles.js # SCSS compilation
-│   │   └── getAssets.js # Asset processing
-│   └── utils/          # Utility functions
-│       ├── clean.js    # Directory cleaning
-│       └── create.js   # Project creation
-└── package.json
+clovie/
+├── __tests__/              # Test files
+├── bin/                    # CLI executable
+│   └── cli.js             # Command line interface
+├── config/                # Configuration files  
+│   └── clovie.config.js   # Default configuration
+├── lib/                   # Source code - Service-based architecture
+│   ├── createClovie.js    # Engine factory function
+│   ├── Build.js           # Build service
+│   ├── Cache.js           # Caching service
+│   ├── Compiler.js        # Template compilation service
+│   ├── File.js            # File system service
+│   ├── Routes.js          # Routing service  
+│   ├── Server.js          # Express server service
+│   ├── Views.js           # View processing service
+│   └── utils/             # Utility functions
+│       ├── clean.js       # Directory cleaning
+│       ├── discover.js    # Auto-discovery
+│       └── liveReloadScript.js # Live reload
+├── templates/             # Project templates
+└── examples/              # Configuration examples
+```
+
+## Service Architecture
+
+Each service in Clovie extends `ServiceProvider` and defines:
+
+- **Static manifest**: Name, namespace, version, and dependencies
+- **initialize()**: Setup phase with access to config and context
+- **actions()**: Methods exposed through the engine context
+
+### Service Dependencies
+
+Services declare their dependencies in their manifest:
+
+```javascript
+static manifest = {
+  name: 'Clovie Build',
+  namespace: 'build', 
+  version: '1.0.0',
+  dependencies: [Cache, Routes]  // Initialized first
+};
+```
+
+### State Management
+
+The engine provides two state stores:
+
+- **`state`**: Reactive store for build-time data (from config.data)
+- **`stable`**: Persistent storage (cache, build stats, etc.)
+
+Services access these via `useContext()`:
+
+```javascript
+actions(useContext) {
+  const { state, stable, file, compiler } = useContext();
+  // Service methods can access other services and state
+}
 ```
 
 ## Core Features
 
 - **Template Engine Agnostic**: Support for Handlebars, Nunjucks, Pug, Mustache, or custom engines
-- **Asset Processing**: JavaScript bundling with esbuild, SCSS compilation, static asset copying
-- **Development Server**: Live reload with Browser-Sync and file watching
-- **Data-Driven Pages**: Model system for dynamic page generation
-- **Pagination Support**: Built-in pagination for data-driven content
+- **Asset Processing**: JavaScript bundling with esbuild, SCSS compilation, static asset copying  
+- **Development Server**: Live reload with Express and file watching
+- **Dynamic Routing**: Powerful route system for both static and server-side page generation
+- **Server-Side Rendering**: Full Express applications with dynamic routes and API endpoints
+- **Incremental Builds**: Smart caching for faster rebuilds
+- **Auto-Discovery**: Intelligent project structure detection
 
 ## Usage
 
@@ -71,18 +136,27 @@ clovie create my-site
 
 ### Building and Development
 
+#### Static Mode (Default)
 ```bash
-# Build the site
+# Build static files
 clovie build
 # or
 npm run build
 
-# Start development server with file watching
+# Development server with live reload  
 clovie watch
 # or
 npm run dev
 ```
 
+#### Server Mode
+```bash
+# Run as Express server application
+clovie server
+# or add to package.json:
+# "scripts": { "serve": "clovie server" }
+```
+
 ## Configuration
 
 ### Minimal Configuration (Recommended)
@@ -103,28 +177,87 @@ Clovie will automatically detect:
 - `styles/main.scss` for SCSS entry point
 - `assets/` directory for static files
 
-### Full Configuration
-
-If you need custom paths or behavior:
+### Static Site Configuration
 
 ```javascript
 export default {
-  // Custom paths (optional - Clovie will auto-detect if not specified)
+  type: 'static', // Default - generates static files
+  
+  // Auto-detected paths (override if needed)
+  views: './src/views',
   scripts: './src/js/app.js',
-  styles: './src/css/main.scss',
-  views: './templates',
+  styles: './src/scss/main.scss', 
   assets: './public',
-  outputDir: './build',
+  outputDir: './dist',
   
-  // Your data
-  data: {
-    title: 'My Site'
+  // Template compilation
+  templateCompiler: (template, data) => {
+    return yourTemplateEngine(template, data);
   },
   
-  // Custom compiler (optional - Clovie has a good default)
-  compiler: (template, data) => {
-    return yourTemplateEngine(template, data);
-  }
+  // Routes for dynamic pages from data
+  routes: [{
+    name: 'Blog Posts',
+    path: '/posts/:slug',
+    template: 'post.html',
+    repeat: (state) => state.get(['posts']),
+    data: (state, post) => ({ 
+      ...post, 
+      title: post.title,
+      slug: post.slug 
+    })
+  }]
+};
+```
+
+### Server Application Configuration  
+
+```javascript
+export default {
+  type: 'server', // Express application mode
+  
+  port: 3000,
+  outputDir: './dist', // Serve static files from here
+  
+  // Same view/asset processing as static mode
+  views: './src/views',
+  scripts: './src/js', 
+  styles: './src/scss',
+  
+  // Server-specific routes
+  routes: [{
+    name: 'Posts API',
+    path: '/api/posts',
+    method: 'GET',
+    handler: async (req, res) => {
+      const posts = await getPosts();
+      res.json(posts);
+    }
+  }, {
+    name: 'Post Pages',
+    path: '/posts/:slug',
+    template: 'post.html',
+    data: async (state, params) => {
+      const post = await getPost(params.slug);
+      return { post };
+    }
+  }],
+  
+  // API routes
+  api: [{
+    path: '/api/users',
+    method: 'POST',
+    handler: async (req, res) => {
+      const user = await createUser(req.body);
+      res.json(user);
+    }
+  }],
+  
+  // Express middleware
+  middleware: [
+    express.json(),
+    cors()
+  ]
 };
 ```
 
@@ -152,9 +285,9 @@ export default {
 };
 ```
 
-### Data Models & Dynamic Pages
+### Dynamic Routes & Data-Driven Pages
 
-Create multiple pages from data arrays using the models system:
+Create multiple pages from data arrays using the routes system:
 
 ```javascript
 // clovie.config.js
@@ -163,51 +296,46 @@ export default {
   data: {
     title: 'My Blog',
     posts: [
-      { id: 1, title: 'First Post', content: 'Hello World' },
-      { id: 2, title: 'Second Post', content: 'Another post' },
-      { id: 3, title: 'Third Post', content: 'Yet another' }
+      { id: 1, title: 'First Post', content: 'Hello World', slug: 'first-post' },
+      { id: 2, title: 'Second Post', content: 'Another post', slug: 'second-post' },
+      { id: 3, title: 'Third Post', content: 'Yet another', slug: 'third-post' }
     ]
   },
-  models: {
-    posts: {
-      template: '_post.html',        // Template to use
-      paginate: 2,                   // Posts per page (optional)
-      output: (post, index) => {     // Custom output filename
-        return `post-${post.id}.html`;
-      },
-      transform: (post, index) => {  // Transform data before rendering
-        return {
-          ...post,
-          excerpt: post.content.substring(0, 100) + '...',
-          date: new Date().toISOString()
-        };
-      }
-    }
-  }
+  routes: [{
+    name: 'Blog Posts',
+    path: '/posts/:slug',
+    template: 'post.html',
+    repeat: (state) => state.get(['posts']),
+    data: (state, post) => ({
+      ...post,
+      excerpt: post.content.substring(0, 100) + '...',
+      date: new Date().toISOString()
+    })
+  }]
 };
 ```
 
-**Template (`_post.html`):**
+**Template (`post.html`):**
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-  <title>{{local.title}} - {{title}}</title>
+  <title>{{title}} - {{../title}}</title>
 </head>
 <body>
   <article>
-    <h1>{{local.title}}</h1>
-    <p>{{local.excerpt}}</p>
-    <div>{{local.content}}</div>
+    <h1>{{title}}</h1>
+    <p>{{excerpt}}</p>
+    <div>{{content}}</div>
   </article>
 </body>
 </html>
 ```
 
 **Output:**
-- `post-1.html` - First post page
-- `post-2.html` - Second post page  
-- `post-3.html` - Third post page
+- `posts/first-post.html` - First post page
+- `posts/second-post.html` - Second post page  
+- `posts/third-post.html` - Third post page
 
 ### Custom Template Engines
 
@@ -263,50 +391,55 @@ export default {
 };
 ```
 
-### Pagination
+### Route Pagination
 
-The models system includes built-in pagination:
+Routes support built-in pagination for large datasets:
 
 ```javascript
 export default {
   // ... other config
-  models: {
-    blog: {
-      template: '_blog.html',
-      paginate: 5,  // 5 posts per page
-      output: (posts, pageNum) => {
-        return pageNum === 0 ? 'blog.html' : `blog-${pageNum + 1}.html`;
-      }
-    }
-  }
+  routes: [{
+    name: 'Blog Pagination',
+    path: '/blog/:page?',
+    template: 'blog.html',
+    paginate: 5,  // 5 posts per page
+    repeat: (state) => state.get(['posts']),
+    data: (state, posts, pageInfo) => ({
+      posts,
+      pagination: pageInfo,
+      title: `Blog - Page ${pageInfo.current}`
+    })
+  }]
 };
 ```
 
 **Output:**
-- `blog.html` - First 5 posts
-- `blog-2.html` - Next 5 posts
-- `blog-3.html` - Remaining posts
+- `blog.html` - First 5 posts (page 1)
+- `blog/2.html` - Next 5 posts (page 2)
+- `blog/3.html` - Remaining posts (page 3)
 
-### Data Transformation
+### Data Transformation in Routes
 
-Transform data before rendering with custom functions:
+Transform data before rendering using the `data` function:
 
 ```javascript
 export default {
   // ... other config
-  models: {
-    products: {
-      template: '_product.html',
-      transform: (product, index) => {
-        return {
-          ...product,
-          price: `$${product.price.toFixed(2)}`,
-          slug: product.name.toLowerCase().replace(/\s+/g, '-'),
-          inStock: product.quantity > 0
-        };
-      }
-    }
-  }
+  routes: [{
+    name: 'Products',
+    path: '/products/:slug',
+    template: 'product.html',
+    repeat: (state) => state.get(['products']),
+    data: (state, product) => ({
+      ...product,
+      price: `$${product.price.toFixed(2)}`,
+      slug: product.name.toLowerCase().replace(/\s+/g, '-'),
+      inStock: product.quantity > 0,
+      relatedProducts: state.get(['products']).filter(p => 
+        p.category === product.category && p.id !== product.id
+      )
+    })
+  }]
 };
 ```
 
@@ -358,10 +491,11 @@ Clovie automatically detects common project structures:
 ### Best Practices
 
 1. **Use partial templates** (files starting with `_`) for reusable components
-2. **Validate data structures** before passing to models
-3. **Handle async data** with proper error catching
-4. **Use meaningful output filenames** for SEO and organization
-5. **Transform data** in the model configuration, not in templates
+2. **Validate data structures** before passing to routes
+3. **Handle async data** with proper error catching in route data functions
+4. **Use meaningful route paths** for SEO and organization
+5. **Transform data** in route data functions, not in templates
+6. **Separate static and dynamic routes** for better performance
 
 ### Project Structure
 
@@ -423,9 +557,9 @@ npm run test:watch
 - Ensure the `views` path in your config is correct
 - Create the views directory if it doesn't exist
 
-**"Data for model must be an array"**
-- Check that your data structure matches the model configuration
-- Ensure the referenced data key contains an array
+**"Route repeat function must return an array"**
+- Check that your route's repeat function returns an array
+- Ensure the data structure matches the route configuration
 
 **"Maximum directory depth exceeded"**
 - Check for circular symlinks or extremely deep directory structures

package/bin/cli.js

@@ -8,7 +8,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // Local
-import Clovie from "../lib/main.js";
+import { createClovie } from "../lib/createClovie.js";
 
 // Check for create command first (before any argument parsing)
 if (process.argv.includes('create') && process.argv.length > 2) {
@@ -91,6 +91,11 @@ if (mainOptions.command === 'watch') {
   options.watch = true;
 }
 
+// Handle server command
+if (mainOptions.command === 'server') {
+  options.server = true;
+}
+
 // Config path
 const configPath = path.resolve(process.cwd(), options.config);
 
@@ -113,19 +118,103 @@ async function main() {
       }
     }
 
-    // New Clovie instance
-    const site = new Clovie(config);
+    // Override config type if server command is used
+    if (options.server) {
+      config.type = 'server';
+    }
 
-    site.error(err => {
-      console.error(err);
-      process.exit(1);
-    });
+    // New Clovie instance
+    const clovie = await createClovie(config);
 
-    if (options.watch) {
-      await site.startWatch();
+    if (options.server) {
+      // Server mode - run as Express server
+      console.log('🌐 Starting server mode...');
+      
+      // Load data into state first
+      if (config.data) {
+        console.log('📊 Loading data into state...');
+        let loadedData = {};
+        if (typeof config.data === 'function') {
+          loadedData = await config.data();
+        } else if (typeof config.data === 'object') {
+          loadedData = config.data;
+        }
+        clovie.state.load(loadedData);
+        console.log(`   Loaded ${Object.keys(loadedData).length} data sources into state`);
+      }
+      
+      // Start server
+      clovie.server.start();
+      
+      // Keep the process running
+      process.on('SIGINT', () => {
+        console.log('\n🛑 Stopping server...');
+        clovie.server.stop();
+        process.exit(0);
+      });
+      
+    } else if (options.watch) {
+      // Development mode with file watching
+      console.log('🏗️  Initial build...');
+      await clovie.build.static();
+      console.log('✅ Initial build completed\n');
+      
+      // Start development server
+      clovie.server.start();
+      
+      // Set up file watching
+      console.log('👀 Setting up file watching...');
+      const watchPaths = [
+        config.views,
+        config.partials,
+        config.styles,
+        config.scripts,
+      ].filter(Boolean); // Remove undefined paths
+      
+      const watchers = clovie.file.watch(watchPaths);
+      
+      // Set up event handlers for each watcher
+      watchers.forEach(watcher => {
+        watcher.on('change', async (filePath) => {
+          console.log(`🔄 File changed: ${filePath}`);
+          console.log('🔄 Triggering rebuild...');
+          
+          try {
+            const result = await clovie.build.static();
+            console.log(`✅ Rebuild completed in ${result.buildTime}ms`);
+            
+            // Notify live reload
+            if (clovie.server && clovie.server.notifyReload) {
+              clovie.server.notifyReload();
+            }
+          } catch (error) {
+            console.error('❌ Rebuild failed:', error.message);
+          }
+        });
+        
+        watcher.on('error', (error) => {
+          console.error('❌ File watcher error:', error);
+        });
+      });
+      
+      console.log(`🌐 Development server running at http://localhost:${config.port || 3000}`);
+      console.log('👀 Watching for file changes...');
+      console.log('Press Ctrl+C to stop the server\n');
+      
+      // Keep the process running
+      process.on('SIGINT', () => {
+        console.log('\n🛑 Stopping development server...');
+        if (clovie.file.isWatching()) {
+          clovie.file.stopWatching();
+        }
+        process.exit(0);
+      });
+      
     } else {
-      await site.build();
-      console.log('Build complete');
+      // Build mode
+      const result = await clovie.build.static();
+      console.log(`✅ Build completed in ${result.buildTime}ms`);
+      console.log(`📁 Generated ${result.filesGenerated} files`);
       process.exit(0);
     }
   } catch (err) {

package/config/clovie.config.js

@@ -31,5 +31,22 @@ export default {
   // Development options
   watch: false,
   port: 3000,
-  open: false
+  open: false,
+  routes: [
+    {
+      name: 'Products',
+      path: '/products/:slug',
+      template: 'index.html',
+      repeat: (state) => {
+        return state.get(['products'])
+      },
+      data: (state, item) => {
+        return {
+          ...item,
+          slug: item.name,
+          title: item.name
+        }
+      }
+    }
+  ]
 }