clovie 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Adrian Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,441 @@
+# 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.
+
+## 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
+```
+
+## 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
+
+## Usage
+
+### Installation
+
+#### Option 1: Local Installation (Recommended)
+```bash
+# Install as dev dependency in your project
+npm install --save-dev clovie
+
+# Use via npm scripts
+npm run build
+npm run dev
+```
+
+#### Option 2: Global Installation
+```bash
+# Install globally
+npm install -g clovie
+```
+
+### Creating New Projects
+
+#### Using Clovie CLI (Recommended)
+```bash
+# Create a new project
+npx clovie create my-site
+
+# Or with global install
+clovie create my-site
+```
+
+
+
+### Building and Development
+
+```bash
+# Build the site
+clovie build
+# or
+npm run build
+
+# Start development server with file watching
+clovie watch
+# or
+npm run dev
+```
+
+## Configuration
+
+### Minimal Configuration (Recommended)
+
+Clovie uses smart defaults and auto-detection, so you can start with just:
+
+```javascript
+export default {
+  data: {
+    title: 'My Site'
+  }
+};
+```
+
+Clovie will automatically detect:
+- `views/` directory for HTML templates
+- `scripts/main.js` for JavaScript entry point
+- `styles/main.scss` for SCSS entry point
+- `assets/` directory for static files
+
+### Full Configuration
+
+If you need custom paths or behavior:
+
+```javascript
+export default {
+  // Custom paths (optional - Clovie will auto-detect if not specified)
+  scripts: './src/js/app.js',
+  styles: './src/css/main.scss',
+  views: './templates',
+  assets: './public',
+  outputDir: './build',
+  
+  // Your data
+  data: {
+    title: 'My Site'
+  },
+  
+  // Custom compiler (optional - Clovie has a good default)
+  compiler: (template, data) => {
+    return yourTemplateEngine(template, data);
+  }
+};
+```
+
+## Advanced Features
+
+### Async Data Loading
+
+Clovie supports asynchronous data loading for dynamic content:
+
+```javascript
+// app.config.js
+export default {
+  // ... other config
+  data: async () => {
+    // Fetch data from API
+    const response = await fetch('https://api.example.com/posts');
+    const posts = await response.json();
+    
+    return {
+      title: 'My Blog',
+      posts: posts,
+      timestamp: new Date().toISOString()
+    };
+  }
+};
+```
+
+### Data Models & Dynamic Pages
+
+Create multiple pages from data arrays using the models system:
+
+```javascript
+// app.config.js
+export default {
+  // ... other config
+  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' }
+    ]
+  },
+  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()
+        };
+      }
+    }
+  }
+};
+```
+
+**Template (`_post.html`):**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>{{local.title}} - {{title}}</title>
+</head>
+<body>
+  <article>
+    <h1>{{local.title}}</h1>
+    <p>{{local.excerpt}}</p>
+    <div>{{local.content}}</div>
+  </article>
+</body>
+</html>
+```
+
+**Output:**
+- `post-1.html` - First post page
+- `post-2.html` - Second post page  
+- `post-3.html` - Third post page
+
+### Custom Template Engines
+
+Clovie is template-engine agnostic. Here are examples for popular engines:
+
+#### Handlebars
+```javascript
+import Handlebars from 'handlebars';
+
+export default {
+  // ... other config
+  compiler: (template, data) => {
+    const compiled = Handlebars.compile(template);
+    return compiled(data);
+  }
+};
+```
+
+#### Nunjucks
+```javascript
+import nunjucks from 'nunjucks';
+
+export default {
+  // ... other config
+  compiler: (template, data) => {
+    return nunjucks.renderString(template, data);
+  }
+};
+```
+
+#### Pug
+```javascript
+import pug from 'pug';
+
+export default {
+  // ... other config
+  compiler: (template, data) => {
+    return pug.render(template, { ...data, pretty: true });
+  }
+};
+```
+
+#### Custom Engine
+```javascript
+export default {
+  // ... other config
+  compiler: (template, data) => {
+    // Simple variable replacement
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+      return data[key] || match;
+    });
+  }
+};
+```
+
+### Pagination
+
+The models system includes built-in pagination:
+
+```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`;
+      }
+    }
+  }
+};
+```
+
+**Output:**
+- `blog.html` - First 5 posts
+- `blog-2.html` - Next 5 posts
+- `blog-3.html` - Remaining posts
+
+### Data Transformation
+
+Transform data before rendering with custom functions:
+
+```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
+        };
+      }
+    }
+  }
+};
+```
+
+## Error Handling & Best Practices
+
+### Error Handling
+
+Clovie includes robust error handling for common issues:
+
+- **Missing directories**: Gracefully handles missing views, scripts, or assets folders
+- **File read errors**: Continues processing even if individual files fail
+- **Template errors**: Provides clear error messages for compilation failures
+- **Data validation**: Warns about invalid data structures
+
+### Progress Indicators
+
+Clovie provides clear feedback during builds:
+
+```
+🚀 Starting build...
+🧹 Cleaning output directory...
+📊 Loading data...
+   Loaded 2 data sources
+📝 Processing views...
+   Processed 5 views
+🎨 Rendering templates...
+   Rendered 5 templates
+⚡ Bundling scripts...
+   Bundled 1 script files
+🎨 Compiling styles...
+   Compiled 1 style files
+📦 Processing assets...
+   Processed 3 asset files
+💾 Writing files...
+✅ Build completed in 45ms
+```
+
+### Auto-Discovery
+
+Clovie automatically detects common project structures:
+
+```
+🔍 Auto-detected views directory: views
+🔍 Auto-detected scripts entry: scripts/main.js
+🔍 Auto-detected styles entry: styles/main.scss
+🔍 Auto-detected assets directory: assets
+```
+
+### 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
+
+### Project Structure
+
+When you create a new project with `clovie create`, you get this structure:
+
+```
+my-site/
+├── app.config.js          # Configuration
+├── package.json           # Dependencies and scripts
+├── README.md              # Project documentation
+├── views/                 # HTML templates
+│   └── index.html        # Home page template
+├── scripts/              # JavaScript
+│   └── main.js          # Main script file
+├── styles/               # SCSS
+│   └── main.scss        # Main stylesheet
+└── assets/               # Static files (images, etc.)
+```
+
+#### Custom Project Structure
+You can also create your own structure:
+
+```
+my-site/
+├── app.config.js          # Configuration
+├── views/                 # Templates
+│   ├── _base.html        # Base template (partial)
+│   ├── _header.html      # Header partial
+│   ├── index.html        # Home page
+│   └── _post.html        # Post template (partial)
+├── scripts/              # JavaScript
+│   └── main.js
+├── styles/               # SCSS
+│   └── main.scss
+├── assets/               # Static files
+│   └── images/
+└── data/                 # Data files (optional)
+    └── posts.json
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"Views directory does not exist"**
+- 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
+
+**"Maximum directory depth exceeded"**
+- Check for circular symlinks or extremely deep directory structures
+- The limit is 50 levels deep (configurable in code)
+
+**Build failures**
+- Check console output for specific error messages
+- Verify all referenced files exist
+- Ensure template syntax matches your compiler
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import path from "path";
+import commandLineArgs from "command-line-args";
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Local
+import Clovie from "../lib/main.js";
+
+// Check for create command first (before any argument parsing)
+if (process.argv.includes('create') && process.argv.length > 2) {
+  const projectName = process.argv[3]; // The name after 'create'
+  
+  if (!projectName) {
+    console.error('Error: Please provide a project name');
+    console.error('Usage: clovie create <project-name>');
+    process.exit(1);
+  }
+  
+  const fs = await import('fs');
+  const projectPath = path.resolve(process.cwd(), projectName);
+  
+  if (fs.existsSync(projectPath)) {
+    console.error(`Error: Directory '${projectName}' already exists`);
+    process.exit(1);
+  }
+  
+  // Copy template files
+  const templateDir = path.join(__dirname, '../templates/default');
+  
+  // Create project directory first
+  fs.mkdirSync(projectPath, { recursive: true });
+  
+  const copyDir = async (src, dest) => {
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      
+      if (entry.isDirectory()) {
+        fs.mkdirSync(destPath, { recursive: true });
+        await copyDir(srcPath, destPath);
+      } else {
+        let content = fs.readFileSync(srcPath, 'utf8');
+        // Replace template variables
+        content = content.replace(/\{\{projectName\}\}/g, projectName);
+        fs.writeFileSync(destPath, content);
+      }
+    }
+  };
+  
+  try {
+    await copyDir(templateDir, projectPath);
+    console.log(`✅ Clovie project created successfully at ${projectPath}`);
+    console.log('\nNext steps:');
+    console.log(`  cd ${projectName}`);
+    console.log('  npm install');
+    console.log('  npm run dev');
+    process.exit(0);
+  } catch (err) {
+    console.error('Error creating project:', err);
+    process.exit(1);
+  }
+}
+
+// Commandline options for other commands
+const mainDefinitions = [
+  { name: 'command', defaultOption: true },
+  { name: 'watch', alias: 'w', type: Boolean }
+];
+const mainOptions = commandLineArgs(mainDefinitions, { stopAtFirstUnknown: true });
+const argv = mainOptions._unknown || [];
+
+// Command-specific options
+const optionDefinitions = [
+  { name: 'config', alias: 'c', type: String, defaultValue: 'app.config.js' },
+  { name: 'watch', alias: 'w', type: Boolean },
+  { name: 'template', alias: 't', type: String, defaultValue: 'default' }
+];
+
+const options = commandLineArgs(optionDefinitions, { argv });
+
+
+
+// Handle watch command
+if (mainOptions.command === 'watch') {
+  options.watch = true;
+}
+
+// Config path
+const configPath = path.resolve(process.cwd(), options.config);
+
+// Main function
+async function main() {
+  try {
+    // Config file
+    const configModule = await import(configPath);
+    const config = configModule.default || configModule;
+
+    // New Clovie instance
+    const site = new Clovie(config);
+
+    site.error(err => {
+      console.error(err);
+      process.exit(1);
+    });
+
+    if (options.watch) {
+      await site.startWatch();
+    } else {
+      await site.build();
+      console.log('Build complete');
+      process.exit(0);
+    }
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+// Run main function
+main();

package/config/default.config.js

@@ -0,0 +1,31 @@
+import Handlebars from 'handlebars';
+import path from 'path';
+
+export default {
+  // Smart defaults - these paths are automatically detected
+  scripts: null,        // Will auto-detect if not specified
+  styles: null,         // Will auto-detect if not specified
+  views: null,          // Will auto-detect if not specified
+  assets: null,         // Will auto-detect if not specified
+  outputDir: path.resolve('./dist/'),
+  
+  // Data and models
+  data: {},
+  models: {},
+  
+  // Default compiler - Handlebars for powerful templating
+  compiler: (template, data) => {
+    try {
+      const compiled = Handlebars.compile(template);
+      return compiled(data);
+    } catch (err) {
+      console.warn(`⚠️  Template compilation error: ${err.message}`);
+      return template; // Fallback to raw template
+    }
+  },
+  
+  // Development options
+  watch: false,
+  port: 3000,
+  open: false
+}

package/lib/core/bundler.js

@@ -0,0 +1,31 @@
+import path from 'path';
+import esbuild from 'esbuild';
+
+export default function(file) {
+  const pathObj = path.parse(file);
+  
+  return new Promise(async (resolve, reject) => {
+    try {
+      const result = await esbuild.build({
+        entryPoints: [file],
+        bundle: true,
+        write: false,
+        format: 'iife',
+        globalName: 'app',
+        platform: 'browser',
+        target: ['es2015'],
+        minify: false,
+        sourcemap: false,
+        // Performance optimizations
+        treeShaking: true,
+        metafile: false,
+        logLevel: 'silent'
+      });
+
+      const { text } = result.outputFiles[0];
+      resolve({[`${pathObj.name}.js`]: text});
+    } catch (err) {
+      reject(err);
+    }
+  });
+};

package/lib/core/cache.js

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+export class BuildCache {
+  constructor(cacheDir) {
+    this.cacheDir = cacheDir;
+    this.cacheFile = path.join(cacheDir, '.clovie-cache.json');
+    this.cache = this.loadCache();
+  }
+  
+  loadCache() {
+    try {
+      if (fs.existsSync(this.cacheFile)) {
+        return JSON.parse(fs.readFileSync(this.cacheFile, 'utf8'));
+      }
+    } catch (err) {
+      console.warn('⚠️  Could not load cache, starting fresh');
+    }
+    return { files: {}, lastBuild: null };
+  }
+  
+  saveCache() {
+    try {
+      if (!fs.existsSync(this.cacheDir)) {
+        fs.mkdirSync(this.cacheDir, { recursive: true });
+      }
+      fs.writeFileSync(this.cacheFile, JSON.stringify(this.cache, null, 2));
+    } catch (err) {
+      console.warn('⚠️  Could not save cache');
+    }
+  }
+  
+  getFileHash(filePath) {
+    try {
+      if (!fs.existsSync(filePath)) return null;
+      const content = fs.readFileSync(filePath);
+      return crypto.createHash('md5').update(content).digest('hex');
+    } catch (err) {
+      return null;
+    }
+  }
+  
+  hasChanged(filePath) {
+    const currentHash = this.getFileHash(filePath);
+    const cachedHash = this.cache.files[filePath];
+    
+    if (currentHash !== cachedHash) {
+      this.cache.files[filePath] = currentHash;
+      return true;
+    }
+    return false;
+  }
+  
+  getChangedFiles(files) {
+    return files.filter(file => this.hasChanged(file));
+  }
+  
+  markBuilt() {
+    this.cache.lastBuild = Date.now();
+    this.saveCache();
+  }
+  
+  getBuildStats() {
+    const totalFiles = Object.keys(this.cache.files).length;
+    const changedFiles = Object.values(this.cache.files).filter(hash => hash !== null).length;
+    return { totalFiles, changedFiles };
+  }
+}