swatchkit 0.0.1 → 0.0.2

package/README.md

@@ -1,57 +1,93 @@
 # SwatchKit
 
-**SwatchKit** is a lightweight, zero-configuration tool for creating HTML pattern libraries. It follows the "Magic Folder" principle: you drop files in, and a documentation site comes out.
+**SwatchKit** is a lightweight tool for generating HTML pattern libraries. It acts as a **Pattern Discovery Engine**: it scans your folders for HTML components and stitches them into a documentation site using a layout you control.
 
-## How it works
+It follows the "Magic Folder" principle: drop files in, and a library comes out.
 
-1.  **Drop Patterns:** Add `.html` files (or folders) to `src/patterns/`.
-2.  **Add Styles:** Add standard CSS to `src/css/styles.css`.
-3.  **Build:** Run `node build.js`.
+## Quick Start
 
-## Features
+Try it instantly in any project:
 
-### 1. The Magic Folder
-*   **Single File:** Drop `button.html` into `src/patterns/`. It automatically appears in the library.
-*   **Component Folder:** Drop a folder like `src/patterns/carousel/` containing `index.html`. It works exactly the same way.
+```bash
+# 1. Initialize the layout
+npx swatchkit init
 
-### 2. Automatic JS Bundling
-If your component needs client-side JavaScript, just add a `.js` file to its folder.
-*   Example: `src/patterns/carousel/script.js`
-*   **SwatchKit** will automatically find it, wrap it in an IIFE (to protect scope), and bundle it into the final site. You can have multiple JS files per pattern.
+# 2. Build the library
+npx swatchkit
+```
 
-### 3. Zero Config
-No config files. No build pipelines. No complex templating engines. Just HTML, CSS, and JS.
+This will create a `swatches/` folder and build your site to `public/swatchkit/`.
 
-## Usage
+---
 
-### Using npx (Recommended)
+## Project Setup (Recommended)
 
-Run directly without installing:
-```bash
-npx swatchkit
-```
-
-### Installing locally
+For real projects, install SwatchKit as a development dependency to lock the version.
 
-Install as a dev dependency:
 ```bash
 npm install -D swatchkit
 ```
 
-Then add to your `package.json` scripts:
+Then add it to your `package.json` scripts:
+
 ```json
 "scripts": {
-  "build:patterns": "swatchkit"
+  "patterns": "swatchkit"
 }
 ```
 
-And run:
+## How It Works
+
+### 1. The Magic Folder
+By default, SwatchKit looks for a `swatches/` folder in your project root.
+*   **Single File:** Drop `card.html` into `swatches/`. It appears in the library.
+*   **Component Folder:** Drop a folder like `swatches/carousel/` containing `index.html`. It works the same way.
+
+### 2. Custom Layouts
+When you run `swatchkit init`, we create `swatches/_layout.html`.
+**You own this file.**
+*   Add your own `<link rel="stylesheet" href="/css/app.css">`.
+*   Add custom fonts, scripts, or meta tags.
+*   Change the HTML structure, logo, or classes.
+
+SwatchKit simply injects the content into the `<!-- PATTERNS -->` and `<!-- SIDEBAR_LINKS -->` placeholders.
+
+### 3. JavaScript Bundling
+If your component needs client-side JS:
+1.  Create a folder: `swatches/carousel/`.
+2.  Add `index.html` (Markup).
+3.  Add `script.js` (Logic).
+
+SwatchKit automatically bundles your JS files, wraps them in a safety scope (IIFE), and injects them into the final build.
+
+## CLI Reference
+
 ```bash
-npm run build:patterns
+swatchkit [command] [options]
 ```
 
-### View the library
-After building, open the generated file:
-```bash
-open dist/index.html
+### Commands
+*   `swatchkit` (Default): Builds the library.
+*   `swatchkit init`: Scaffolds the `_layout.html` file.
+
+### Flags
+| Flag | Short | Description |
+| :--- | :--- | :--- |
+| `--watch` | `-w` | Watch mode (coming soon). |
+| `--config` | `-c` | Path to config file. |
+| `--input` | `-i` | Pattern directory (Default: `swatches/`). |
+| `--outDir` | `-o` | Output directory (Default: `public/swatchkit`). |
+| `--force` | `-f` | Overwrite layout file during init. |
+
+## Configuration
+Optional. Create `swatchkit.config.js` in your root for persistent settings.
+
+```javascript
+module.exports = {
+  // Override default pattern directory
+  input: './src/patterns',
+
+  // Override default output directory
+  outDir: './dist/docs'
+};
 ```

package/build.js

@@ -2,38 +2,170 @@
 const fs = require('fs');
 const path = require('path');
 
-const config = {
-  srcDir: path.join(process.cwd(), 'src'),
-  cssDir: path.join(process.cwd(), 'src/css'),
-  patternsDir: path.join(process.cwd(), 'src/patterns'),
-  layoutFile: path.join(__dirname, 'src/layout.html'),
-  distDir: path.join(process.cwd(), 'dist'),
-  distCssDir: path.join(process.cwd(), 'dist/css'),
-  distJsDir: path.join(process.cwd(), 'dist/js'),
-  outputFile: path.join(process.cwd(), 'dist/index.html'),
-  outputJsFile: path.join(process.cwd(), 'dist/js/patterns.js')
-};
-
-function build() {
-  console.log('[SwatchKit] Starting build...');
+/**
+ * SwatchKit Build Script
+ * Refactored for Phase 1 Expansion
+ */
+
+// --- 1. CLI Argument Parsing ---
+function parseArgs(args) {
+  const options = {
+    command: null,
+    watch: false,
+    config: null,
+    input: null,
+    outDir: null,
+    force: false
+  };
+
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === 'init') {
+      options.command = 'init';
+    } else if (arg === '-w' || arg === '--watch') {
+      options.watch = true;
+    } else if (arg === '-f' || arg === '--force') {
+      options.force = true;
+    } else if (arg === '-c' || arg === '--config') {
+      // Handle case where flag is last arg
+      if (i + 1 < args.length) {
+        options.config = args[++i];
+      }
+    } else if (arg === '-i' || arg === '--input') {
+      if (i + 1 < args.length) {
+        options.input = args[++i];
+      }
+    } else if (arg === '-o' || arg === '--outDir') {
+      if (i + 1 < args.length) {
+        options.outDir = args[++i];
+      }
+    }
+  }
+  return options;
+}
+
+// --- 2. Config Loading ---
+function loadConfig(configPath) {
+  let finalPath;
+  if (configPath) {
+    finalPath = path.resolve(process.cwd(), configPath);
+  } else {
+    finalPath = path.join(process.cwd(), 'swatchkit.config.js');
+  }
+
+  if (fs.existsSync(finalPath)) {
+    try {
+      console.log(`[SwatchKit] Loading config from ${finalPath}`);
+      return require(finalPath);
+    } catch (e) {
+      console.error('[SwatchKit] Error loading config file:', e.message);
+      return {};
+    }
+  }
+  return {};
+}
+
+// --- 3. Smart Defaults & Path Resolution ---
+function resolveSettings(cliOptions, fileConfig) {
+  const cwd = process.cwd();
+
+  // Helper to find patterns dir
+  function findPatternsDir() {
+    // 1. Explicit input
+    if (cliOptions.input) return path.resolve(cwd, cliOptions.input);
+    if (fileConfig.input) return path.resolve(cwd, fileConfig.input);
+
+    // 2. Search candidates
+    const candidates = ['swatches', 'src/swatches', 'src/patterns'];
+    for (const cand of candidates) {
+      const absPath = path.join(cwd, cand);
+      if (fs.existsSync(absPath)) return absPath;
+    }
+
+    // 3. Fallback default (swatches)
+    return path.join(cwd, 'swatches');
+  }
+
+  const patternsDir = findPatternsDir();
+
+  // Output Dir
+  // Default: public/swatchkit
+  const outDir = cliOptions.outDir 
+    ? path.resolve(cwd, cliOptions.outDir)
+    : (fileConfig.outDir ? path.resolve(cwd, fileConfig.outDir) : path.join(cwd, 'public/swatchkit'));
+
+  // CSS Dir (Legacy support: src/css)
+  const cssDir = path.join(cwd, 'src/css');
+
+  return {
+    patternsDir,
+    outDir,
+    cssDir,
+    // Internal layout template (relative to this script)
+    internalLayout: path.join(__dirname, 'src/layout.html'),
+    // Project specific layout override
+    projectLayout: path.join(patternsDir, '_layout.html'),
+    
+    // Derived paths
+    distCssDir: path.join(outDir, 'css'),
+    distJsDir: path.join(outDir, 'js'),
+    outputFile: path.join(outDir, 'index.html'),
+    outputJsFile: path.join(outDir, 'js/patterns.js')
+  };
+}
+
+// --- 4. Init Command Logic ---
+function runInit(settings, options) {
+  console.log('[SwatchKit] Initializing...');
+
+  // Ensure patterns directory exists
+  if (!fs.existsSync(settings.patternsDir)) {
+    console.log(`Creating patterns directory: ${settings.patternsDir}`);
+    fs.mkdirSync(settings.patternsDir, { recursive: true });
+  }
+
+  const targetLayout = settings.projectLayout;
+  
+  if (fs.existsSync(targetLayout) && !options.force) {
+    console.warn(`Warning: Layout file already exists at ${targetLayout}`);
+    console.warn('Use --force to overwrite.');
+    return;
+  }
+
+  if (fs.existsSync(settings.internalLayout)) {
+    const layoutContent = fs.readFileSync(settings.internalLayout, 'utf-8');
+    fs.writeFileSync(targetLayout, layoutContent);
+    console.log(`Created layout file at ${targetLayout}`);
+  } else {
+    console.error(`Error: Internal layout file not found at ${settings.internalLayout}`);
+    process.exit(1);
+  }
+}
+
+// --- 5. Build Logic ---
+function build(settings) {
+  console.log(`[SwatchKit] Starting build...`);
+  console.log(`  Patterns: ${settings.patternsDir}`);
+  console.log(`  Output:   ${settings.outDir}`);
 
   // 1. Check if patterns directory exists
-  if (!fs.existsSync(config.patternsDir)) {
-    console.error('Error: No patterns found. Create src/patterns to get started.');
+  if (!fs.existsSync(settings.patternsDir)) {
+    console.error(`Error: Patterns directory not found at ${settings.patternsDir}`);
+    console.error('Run "swatchkit init" to get started.');
     process.exit(1);
   }
 
   // 2. Ensure dist directories exist
-  [config.distDir, config.distCssDir, config.distJsDir].forEach(dir => {
+  [settings.outDir, settings.distCssDir, settings.distJsDir].forEach(dir => {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   });
 
   // 3. Copy CSS files
-  console.log('Copying CSS...');
-  if (fs.existsSync(config.cssDir)) {
-      const cssFiles = fs.readdirSync(config.cssDir).filter(file => file.endsWith('.css'));
+  if (fs.existsSync(settings.cssDir)) {
+      console.log('Copying CSS...');
+      const cssFiles = fs.readdirSync(settings.cssDir).filter(file => file.endsWith('.css'));
       cssFiles.forEach(file => {
-          fs.copyFileSync(path.join(config.cssDir, file), path.join(config.distCssDir, file));
+          fs.copyFileSync(path.join(settings.cssDir, file), path.join(settings.distCssDir, file));
       });
   }
 
@@ -42,15 +174,18 @@ function build() {
   const patterns = [];
   const scripts = [];
 
-  const items = fs.readdirSync(config.patternsDir);
+  const items = fs.readdirSync(settings.patternsDir);
 
   items.forEach(item => {
-      const itemPath = path.join(config.patternsDir, item);
+      // Skip _layout.html or hidden files
+      if (item.startsWith('_') || item.startsWith('.')) return;
+
+      const itemPath = path.join(settings.patternsDir, item);
       const stat = fs.statSync(itemPath);
       
       let name, content, id;
 
-      // Handle Directory Pattern (Folder with index.html + optional JS files)
+      // Handle Directory Pattern
       if (stat.isDirectory()) {
         const indexFile = path.join(itemPath, 'index.html');
         
@@ -59,7 +194,7 @@ function build() {
           id = item;
           content = fs.readFileSync(indexFile, 'utf-8');
 
-          // Find all .js files in this directory
+          // Find all .js files
           const jsFiles = fs.readdirSync(itemPath).filter(file => file.endsWith('.js'));
           
           jsFiles.forEach(jsFile => {
@@ -73,7 +208,7 @@ ${scriptContent}
           });
         }
       } 
-      // Handle Single File Pattern (.html)
+      // Handle Single File Pattern
       else if (item.endsWith('.html')) {
         name = path.basename(item, '.html');
         id = name;
@@ -109,24 +244,47 @@ ${scriptContent}
 
   // 6. Write JS Bundle
   if (scripts.length > 0) {
-    fs.writeFileSync(config.outputJsFile, scripts.join('\n'));
-    console.log(`Bundled ${scripts.length} scripts to ${config.outputJsFile}`);
+    fs.writeFileSync(settings.outputJsFile, scripts.join('\n'));
+    console.log(`Bundled ${scripts.length} scripts to ${settings.outputJsFile}`);
   } else {
-    // Write empty file if no scripts so browser doesn't 404
-    fs.writeFileSync(config.outputJsFile, '// No pattern scripts found');
+    fs.writeFileSync(settings.outputJsFile, '// No pattern scripts found');
   }
 
-  // 7. Read layout and replace placeholders
-  let layout = fs.readFileSync(config.layoutFile, 'utf-8');
+  // 7. Load Layout
+  let layoutContent;
+  if (fs.existsSync(settings.projectLayout)) {
+    console.log(`Using custom layout: ${settings.projectLayout}`);
+    layoutContent = fs.readFileSync(settings.projectLayout, 'utf-8');
+  } else {
+    // console.log(`Using internal layout`);
+    layoutContent = fs.readFileSync(settings.internalLayout, 'utf-8');
+  }
   
-  const finalHtml = layout
+  const finalHtml = layoutContent
     .replace('<!-- SIDEBAR_LINKS -->', sidebarLinks)
     .replace('<!-- PATTERNS -->', patternBlocks);
 
   // 8. Write output
-  fs.writeFileSync(config.outputFile, finalHtml);
+  fs.writeFileSync(settings.outputFile, finalHtml);
   
-  console.log(`Build complete! Generated ${config.outputFile}`);
+  console.log(`Build complete! Generated ${settings.outputFile}`);
 }
 
-build();
+// --- Main Execution ---
+try {
+  const cliOptions = parseArgs(process.argv);
+  const fileConfig = loadConfig(cliOptions.config);
+  const settings = resolveSettings(cliOptions, fileConfig);
+
+  if (cliOptions.command === 'init') {
+    runInit(settings, cliOptions);
+  } else {
+    build(settings);
+    if (cliOptions.watch) {
+      console.log('[SwatchKit] Watch mode is not yet fully implemented.');
+    }
+  }
+} catch (error) {
+  console.error('[SwatchKit] Error:', error.message);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swatchkit",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A lightweight tool for creating HTML pattern libraries.",
   "main": "build.js",
   "bin": {