mikel-cli 0.25.0

package/README.md

@@ -0,0 +1,130 @@
+# mikel-cli
+
+![npm version](https://badgen.net/npm/v/mikel-cli?labelColor=1d2734&color=21bf81)
+![license](https://badgen.net/github/license/jmjuanes/mikel?labelColor=1d2734&color=21bf81)
+
+A command-line interface for the [Mikel](https://github.com/jmjuanes/mikel) templating engine. This CLI tool allows you to render Mikel templates from the command line with support for data files, partials, helpers, and functions.
+
+## Installation
+
+Install the tool using **npm** or **yarn**:
+
+```bash
+# Using npm
+$ npm install mikel-cli mikel
+
+# Using yarn
+$ yarn add mikel-cli mikel
+```
+
+**Note:** You need to install both `mikel-cli` and `mikel` packages. The `mikel` package is a peer dependency that provides the core templating functionality.
+
+## Usage
+
+### Basic Usage
+
+```bash
+$ mikel <template> [options]
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Display help information |
+| `--data <file>` | `-D` | Path to JSON data file |
+| `--output <file>` | `-o` | Output file path |
+| `--partial <file>` | `-P` | Register a partial template (supports glob patterns, can be used multiple times) |
+| `--helper <file>` | `-H` | Register helper functions from a JavaScript module (supports glob patterns, can be used multiple times) |
+| `--function <file>` | `-F` | Register functions from a JavaScript module (supports glob patterns, can be used multiple times) |
+
+### Examples
+
+#### Simple Template Rendering
+
+Render a template and output to console:
+
+```bash
+mikel template.html
+```
+
+#### Using Data File
+
+Render a template with data from a JSON file:
+
+```bash
+mikel template.html --data data.json
+```
+
+#### Output to File
+
+Render template and save to an output file:
+
+```bash
+mikel template.html --data data.json --output dist/index.html
+```
+
+#### Using Partials
+
+Register partial templates for reusable components:
+
+```bash
+mikel template.html --data data.json --partial header.html --partial footer.html --output dist/index.html
+```
+
+#### Using Helpers and Functions
+
+Register custom helpers and functions from JavaScript modules:
+
+```bash
+mikel template.html --data data.json --helper helpers.js --function utils.js --output dist/index.html
+```
+
+#### Using Glob Patterns
+
+Load multiple files using glob patterns:
+
+```bash
+# Load all HTML partials from a directory
+mikel template.html --partial 'partials/*.html' --output dist/index.html
+
+# Load all JavaScript helpers from a directory
+mikel template.html --helper 'helpers/*.js' --output dist/index.html
+
+# Load partials from subdirectories (recursive)
+mikel template.html --partial 'components/**/*.html' --output dist/index.html
+
+# Mix exact files and glob patterns
+mikel template.html --partial header.html --partial 'components/*.html' --output dist/index.html
+```
+
+#### Complex Example
+
+A complete example combining all features:
+
+```bash
+mikel src/template.html \
+  --data src/data.json \
+  --partial 'src/partials/*.html' \
+  --partial 'src/components/**/*.html' \
+  --helper 'src/helpers/*.js' \
+  --function 'src/utils/*.js' \
+  --output dist/index.html
+```
+
+### Glob Pattern Support
+
+The `--partial`, `--helper`, and `--function` options support glob patterns for loading multiple files at once:
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `*.ext` | All files with extension in current directory | `*.html`, `*.js` |
+| `dir/*.ext` | All files with extension in specific directory | `partials/*.html` |
+| `dir/**/*.ext` | All files with extension in directory and subdirectories | `components/**/*.html` |
+| `?` | Single character wildcard | `file?.html` |
+
+**Note:** Glob patterns should be quoted to prevent shell expansion.
+
+## License
+
+Licensed under the [MIT License](../../LICENSE).

package/index.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import mikel from "mikel";
+
+// @description get the files that matches the provided patterns
+// this is a utility function to expand glob patterns to actual file paths.
+// it uses Node.js 24+ built-in fs.glob to handle glob patterns.
+const expandGlobPatterns = async (patterns = []) => {
+    const files = [];
+    for (let i = 0; i < patterns.length; i++) {
+        const pattern = patterns[i];
+        if (pattern.includes("*") || pattern.includes("?") || pattern.includes("[")) {
+            try {
+                // use Node.js 24+ built-in fs.glob
+                // https://nodejs.org/api/fs.html#fspromisesglobpattern-options
+                for await (const file of fs.glob(pattern, { cwd: process.cwd() })) {
+                    files.push(file);
+                }
+            } catch (error) {
+                files.push(pattern);
+            }
+        } else {
+            files.push(pattern);
+        }
+    }
+    // remove duplicates and resolve to absolute paths
+    return Array.from(new Set(files)).map(file => {
+        return path.resolve(process.cwd(), file);
+    });
+};
+
+// @description load JSON data from the provided path
+const loadData = async (file = null) => {
+    if (!file) {
+        return {};
+    }
+    // build the full data file path and check if exists
+    const dataPath = path.resolve(process.cwd(), file);
+    if (!existsSync(dataPath)) {
+        throw new Error(`Data file '${dataPath}' was not found.`);
+    }
+    // read the file and parse it as JSON
+    try {
+        const content = await fs.readFile(dataPath, "utf8");
+        return JSON.parse(content);
+    } catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in data file '${dataPath}': ${error.message}`);
+        }
+        throw new Error(`Failed to read data file '${dataPath}': ${error.message}`);
+    }
+};
+
+// @description load partials
+const loadPartials = async (patterns = []) => {
+    const partials = {}; // output partials object
+    const files = await expandGlobPatterns(patterns);
+    
+    // load all files
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i]; // path.resolve(process.cwd(), uniqueFiles[i]);
+        if (!existsSync(file)) {
+            throw new Error(`Partial file '${file}' was not found.`);
+        }
+        
+        // check if it's a file (not a directory)
+        const stats = await fs.stat(file);
+        if (!stats.isFile()) {
+            continue; // skip directories
+        }
+        
+        // load the file and save it as a partial
+        try {
+            partials[path.basename(file)] = await fs.readFile(file, "utf8");
+        } catch (error) {
+            throw new Error(`Failed to read partial file '${file}': ${error.message}`);
+        }
+    }
+    
+    return partials;
+};
+
+// @description load javascript modules
+const loadModules = async (patterns = []) => {
+    const result = {};
+    const files = await expandGlobPatterns(patterns);
+    
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i]; // path.resolve(process.cwd(), uniqueFiles[i]);
+        if (!existsSync(file)) {
+            throw new Error(`Module '${file}' was not found.`);
+        }
+        
+        // Check if it's a file (not a directory)
+        const stats = await fs.stat(file);
+        if (!stats.isFile()) {
+            continue; // Skip directories
+        }
+        
+        const extension = path.extname(file);
+        if (extension !== ".js" && extension !== ".mjs") {
+            throw new Error(`Module '${file}' is not supported. Only ESM JavaScript (.js or .mjs) files are supported.`);
+        }
+        // import the module
+        try {
+            const content = (await import(file)) || {};
+            if (typeof content === "object" && !!content) {
+                Object.assign(result, content);
+            }
+        } catch (error) {
+            throw new Error(`Failed to import module '${file}': ${error.message}`);
+        }
+    }
+    return result;
+};
+
+// print the help of the tool
+const printHelp = () => {
+    console.log("Usage: ");
+    console.log("  mikel --help");
+    console.log("  mikel <template> [...options]");
+    console.log("");
+    console.log("Options:");
+    console.log("  -h, --help              Prints the usage information");
+    console.log("  -P, --partial <file>    Register a partial (supports glob patterns, can be used multiple times)");
+    console.log("  -H, --helper <file>     Register a helper (supports glob patterns, can be used multiple times)");
+    console.log("  -F, --function <file>   Register a function (supports glob patterns, can be used multiple times)");
+    console.log("  -D, --data <file>       Path to the data file to use (JSON)");
+    console.log("  -o, --output <file>     Output file");
+    console.log("");
+    console.log("Examples:");
+    console.log("  mikel template.html --data data.json --output www/index.html");
+    console.log("  mikel template.html --data data.json --partial header.html --partial footer.html --output www/index.html");
+    console.log("  mikel template.html --helper helpers.js --function utils.js --output dist/index.html");
+    console.log("  mikel template.html --partial 'partials/*.html' --helper 'helpers/*.js' --output dist/index.html");
+    console.log("  mikel template.html --partial 'components/**/*.html' --output dist/index.html");
+    console.log("");
+    process.exit(0);
+};
+
+// @description main function
+const main = async (input = "", options = {}) => {
+    // check to print help
+    if (options.help) {
+        return printHelp();
+    }
+
+    // make sure that input file exists
+    if (!input) {
+        throw new Error(`No input template file provided.`);
+    }
+    const inputPath = path.resolve(process.cwd(), input);
+    if (!existsSync(inputPath)) {
+        throw new Error(`Template file '${inputPath}' was not found.`);
+    }
+    
+    let template;
+    try {
+        template = await fs.readFile(inputPath, "utf8");
+    } catch (error) {
+        throw new Error(`Failed to read template file '${inputPath}': ${error.message}`);
+    }
+
+    // load additional data
+    const data = await loadData(options.data);
+    const partials = await loadPartials(options.partial);
+    const helpers = await loadModules(options.helper);
+    const functions = await loadModules(options.function);
+
+    // compile the template
+    let result;
+    try {
+        result = mikel(template, data || {}, { helpers, functions, partials });
+    } catch (error) {
+        throw new Error(`Template compilation failed: ${error.message}`);
+    }
+
+    // check if output argument has been provided to write the result to a file
+    // this will also create any intermediary directory that does not exist
+    if (options.output) {
+        const outputPath = path.resolve(process.cwd(), options.output);
+        const outputDirectory = path.dirname(outputPath);
+        // make sure that any directory containing the output file exists
+        if (!existsSync(outputDirectory)) {
+            try {
+                await fs.mkdir(outputDirectory, { recursive: true });
+            } catch (error) {
+                throw new Error(`Failed to create output directory '${outputDirectory}': ${error.message}`);
+            }
+        }
+        try {
+            await fs.writeFile(outputPath, result, "utf8");
+            console.error(`✓ Template rendered successfully to '${outputPath}'`);
+        } catch (error) {
+            throw new Error(`Failed to write output file '${outputPath}': ${error.message}`);
+        }
+        process.exit(0);
+    }
+    // if no output file has been provided, print the result to console
+    else {
+        process.stdout.write(result);
+        process.exit(0);
+    }
+};
+
+// process arguments
+const { positionals, values } = parseArgs({
+    options: {
+        data: {
+            type: "string",
+            short: "D",
+        },
+        output: {
+            type: "string",
+            short: "o",
+        },
+        helper: {
+            type: "string",
+            short: "H",
+            multiple: true,
+        },
+        function: {
+            type: "string",
+            short: "F",
+            multiple: true,
+        },
+        partial: {
+            type: "string",
+            short: "P",
+            multiple: true,
+        },
+        help: {
+            type: "boolean",
+            short: "h",
+        },
+    },
+    allowPositionals: true,
+});
+
+// run main script
+main(positionals[0], values).catch(error => {
+    console.error(`\n❌ Error: ${error.message}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "mikel-cli",
+    "description": "The cli tool for mikel templating.",
+    "version": "0.25.0",
+    "type": "module",
+    "license": "MIT",
+    "author": {
+        "name": "Josemi Juanes",
+        "email": "hello@josemi.xyz"
+    },
+    "repository": "https://github.com/jmjuanes/mikel",
+    "bugs": "https://github.com/jmjuanes/mikel/issues",
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "exports": {
+        ".": "./index.js",
+        "./index.js": "./index.js",
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "mikel": "index.js"
+    },
+    "peerDependencies": {
+        "mikel": "^0.25.0"
+    },
+    "files": [
+        "README.md",
+        "index.js"
+    ],
+    "keywords": [
+        "mikel",
+        "cli",
+        "templating"
+    ]
+}