portapack 0.2.1

package/src/cli/options.ts

@@ -0,0 +1,151 @@
+/**
+ * @file src/cli/options.ts
+ * @description Centralized CLI argument parser for PortaPack using Commander.
+ * Returns strongly typed options object including the determined LogLevel.
+ */
+
+import { Command, Option } from 'commander';
+// Import LogLevel enum and names type from the central types file
+// Ensure CLIOptions is imported correctly if defined in types.ts
+import { LogLevel, type LogLevelName, type CLIOptions } from '../types';
+
+
+// Define valid choices for the --log-level option
+const logLevels: LogLevelName[] = ['debug', 'info', 'warn', 'error', 'silent', 'none'];
+
+/**
+ * Custom parser for the --recursive option value.
+ * Treats flag without value, non-numeric value, or negative value as true.
+ *
+ * @param {string | undefined} val - The value passed to the option.
+ * @returns {boolean | number} True if flag only/invalid number, otherwise the parsed depth.
+ */
+function parseRecursiveValue(val: string | undefined): boolean | number {
+    if (val === undefined) return true; // Flag only
+    const parsed = parseInt(val, 10);
+    // Invalid number (NaN) or negative depth treated as simple boolean 'true'
+    return isNaN(parsed) || parsed < 0 ? true : parsed;
+}
+
+/**
+ * Parses CLI arguments using Commander and returns a typed CLIOptions object.
+ * Handles mapping --verbose and --log-level flags to the appropriate LogLevel enum value.
+ * Handles mapping --no-minify to individual minification flags.
+ * Ensures flags like --no-embed-assets correctly override their positive counterparts.
+ *
+ * @param {string[]} [argv=process.argv] - Command-line arguments array (e.g., process.argv).
+ * @returns {CLIOptions} Parsed and structured options object.
+ * @throws {Error} Throws errors if Commander encounters parsing/validation issues.
+ */
+export function parseOptions(argv: string[] = process.argv): CLIOptions {
+    const program = new Command();
+
+    program
+        .name('portapack')
+        .version('0.0.0') // Version updated dynamically by cli.ts
+        .description('📦 Bundle HTML and its dependencies into a portable file')
+        .argument('[input]', 'Input HTML file or URL')
+        .option('-o, --output <file>', 'Output file path')
+        .option('-m, --minify', 'Enable all minification (HTML, CSS, JS)') // Presence enables default true below
+        .option('--no-minify', 'Disable all minification') // Global disable flag
+        .option('--no-minify-html', 'Disable HTML minification')
+        .option('--no-minify-css', 'Disable CSS minification')
+        .option('--no-minify-js', 'Disable JavaScript minification')
+        .option('-e, --embed-assets', 'Embed assets as data URIs') // Presence enables default true below
+        .option('--no-embed-assets', 'Keep asset links relative/absolute') // Disable flag
+        .option('-r, --recursive [depth]', 'Recursively crawl site (optional depth)', parseRecursiveValue)
+        .option('--max-depth <n>', 'Set max depth for recursive crawl (alias for -r <n>)', parseInt)
+        .option('-b, --base-url <url>', 'Base URL for resolving relative links')
+        .option('-d, --dry-run', 'Run without writing output file')
+        .option('-v, --verbose', 'Enable verbose (debug) logging')
+        .addOption(new Option('--log-level <level>', 'Set logging level')
+            .choices(logLevels));
+
+    // Prevent commander from exiting on error during tests (optional)
+    // program.exitOverride();
+
+    program.parse(argv);
+
+    // Raw options object from Commander's parsing
+    const opts = program.opts<CLIOptions>();
+    // Get the positional argument (input) if provided
+    const inputArg = program.args.length > 0 ? program.args[0] : undefined;
+
+    // --- Determine Effective LogLevel ---
+    let finalLogLevel: LogLevel;
+    const cliLogLevel = opts.logLevel as unknown as LogLevelName | undefined; // Commander stores choice string
+    if (cliLogLevel) {
+        // Map string choice to LogLevel enum value
+        switch (cliLogLevel) {
+            case 'debug': finalLogLevel = LogLevel.DEBUG; break;
+            case 'info': finalLogLevel = LogLevel.INFO; break;
+            case 'warn': finalLogLevel = LogLevel.WARN; break;
+            case 'error': finalLogLevel = LogLevel.ERROR; break;
+            case 'silent': case 'none': finalLogLevel = LogLevel.NONE; break;
+            default: finalLogLevel = LogLevel.INFO; // Fallback, though choices() should prevent this
+        }
+    } else if (opts.verbose) {
+        // --verbose is shorthand for debug level if --log-level not set
+        finalLogLevel = LogLevel.DEBUG;
+    } else {
+        // Default log level
+        finalLogLevel = LogLevel.INFO;
+    }
+
+    // --- Handle Embedding ---
+    // Default is true. --no-embed-assets flag sets opts.embedAssets to false.
+    // Check argv directly to ensure --no- wins regardless of order.
+    let embedAssets = true; // Start with default
+    if (argv.includes('--no-embed-assets')) {
+         embedAssets = false; // Explicit negation flag takes precedence
+    } else if (opts.embedAssets === true) {
+         embedAssets = true; // Positive flag enables it if negation wasn't present
+    }
+    // If neither flag is present, it remains the default 'true'.
+
+    // --- Handle Minification ---
+    // Default to true unless specifically disabled by --no-minify-<type>
+    let minifyHtml = opts.minifyHtml !== false;
+    let minifyCss = opts.minifyCss !== false;
+    let minifyJs = opts.minifyJs !== false;
+
+    // Global --no-minify flag overrides all individual settings
+    // Commander sets opts.minify to false if --no-minify is used.
+    if (opts.minify === false) {
+        minifyHtml = false;
+        minifyCss = false;
+        minifyJs = false;
+    }
+    // Note: Positive flags (-m or individual --minify-<type>) don't need extra handling
+    // as the initial state is true, and negations correctly turn them off.
+
+    // --- Handle Recursive/MaxDepth ---
+    // Start with the value parsed from -r/--recursive
+    let recursiveOpt = opts.recursive;
+    // If --max-depth was provided and is a valid non-negative number, it overrides -r
+    if (opts.maxDepth !== undefined && !isNaN(opts.maxDepth) && opts.maxDepth >= 0) {
+        recursiveOpt = opts.maxDepth;
+    }
+
+    // Return the final structured options object
+    return {
+        // Pass through directly parsed options
+        baseUrl: opts.baseUrl,
+        dryRun: opts.dryRun ?? false, // Ensure boolean, default false
+        output: opts.output,
+        verbose: opts.verbose ?? false, // Ensure boolean, default false
+
+        // Set calculated/processed options
+        input: inputArg,
+        logLevel: finalLogLevel,
+        recursive: recursiveOpt, // Final calculated value for recursion
+        embedAssets: embedAssets, // Final calculated value
+        minifyHtml: minifyHtml,   // Final calculated value
+        minifyCss: minifyCss,     // Final calculated value
+        minifyJs: minifyJs,       // Final calculated value
+
+        // Exclude intermediate commander properties like:
+        // minify, logLevel (string version), maxDepth,
+        // minifyHtml, minifyCss, minifyJs (commander's raw boolean flags)
+    };
+}

package/src/core/bundler.ts

@@ -0,0 +1,201 @@
+/**
+ * @file bundler.ts
+ * @description Core bundling functions to handle both single and multi-page HTML documents. This includes asset extraction, optional minification, and full inlining into a self-contained HTML file.
+ * @version 1.3.0
+ */
+
+import { dirname, resolve } from 'path';
+import { pathToFileURL, URL } from 'url';
+import { extractAssets } from './extractor.js';
+import { minifyAssets } from './minifier.js';
+import { packHTML } from './packer.js';
+import { Logger } from '../utils/logger.js';
+import { ParsedHTML, BundleOptions, PageEntry } from '../types.js';
+import { sanitizeSlug, slugify } from '../utils/slugify.js';
+
+/**
+ * Determines the appropriate base URL for resolving relative assets
+ * based on input HTML file path or URL.
+ *
+ * @param input - The original HTML path or URL.
+ * @param logger - Optional logger instance.
+ * @returns The resolved base URL, ending in a trailing slash.
+ */
+function determineBaseUrl(input: string, logger?: Logger): string {
+    try {
+        if (input.startsWith('http://') || input.startsWith('https://')) {
+            const url = new URL(input);
+            url.pathname = url.pathname.substring(0, url.pathname.lastIndexOf('/') + 1);
+            url.search = '';
+            url.hash = '';
+            const baseUrl = url.toString();
+            logger?.debug(`Determined remote base URL: ${baseUrl}`);
+            return baseUrl;
+        } else {
+            const absoluteDir = dirname(resolve(input));
+            const baseUrl = pathToFileURL(absoluteDir + '/').href;
+            logger?.debug(`Determined local base URL: ${baseUrl}`);
+            return baseUrl;
+        }
+    } catch (error: any) {
+        logger?.error(`Failed to determine base URL for "${input}": ${error.message}`);
+        return './';
+    }
+}
+
+/**
+ * Creates a self-contained HTML file from a parsed HTML structure and options.
+ *
+ * @param parsedHtml - The parsed HTML document.
+ * @param inputPath - The original input file or URL for base URL calculation.
+ * @param options - Optional bundling options.
+ * @param logger - Optional logger instance.
+ * @returns A fully inlined and bundled HTML string.
+ */
+export async function bundleSingleHTML(
+    parsedHtml: ParsedHTML,
+    inputPath: string,
+    options: BundleOptions = {},
+    logger?: Logger
+): Promise<string> {
+    try {
+        const defaultOptions: Required<BundleOptions> = {
+            embedAssets: true,
+            minifyHtml: true,
+            minifyJs: true,
+            minifyCss: true,
+            baseUrl: '',
+            verbose: false,
+            dryRun: false,
+            recursive: false,
+            output: '',
+            logLevel: logger?.level ?? 3,
+        };
+
+        const mergedOptions = { ...defaultOptions, ...options };
+
+        if (!mergedOptions.baseUrl) {
+            mergedOptions.baseUrl = determineBaseUrl(inputPath, logger);
+        }
+
+        logger?.debug(`Starting HTML bundling for ${inputPath}`);
+        logger?.debug(`Effective options: ${JSON.stringify(mergedOptions, null, 2)}`);
+
+        const extracted = await extractAssets(parsedHtml, mergedOptions.embedAssets, mergedOptions.baseUrl, logger);
+        const minified = await minifyAssets(extracted, mergedOptions, logger);
+        const result = packHTML(minified, logger);
+
+        logger?.info(`Single HTML bundling complete for: ${inputPath}`);
+        return result;
+    } catch (error: any) {
+        logger?.error(`Error during single HTML bundling: ${error.message}`);
+        throw error;
+    }
+}
+
+/**
+ * Combines multiple HTML pages into a single HTML file with client-side routing.
+ *
+ * @param pages - An array of PageEntry objects (each with a URL and HTML content).
+ * @param logger - Optional logger for diagnostics.
+ * @returns A complete HTML document as a string.
+ * @throws {Error} If the input is invalid or contains no usable pages.
+ */
+export function bundleMultiPageHTML(pages: PageEntry[], logger?: Logger): string {
+    if (!Array.isArray(pages)) {
+        const errorMsg = 'Input pages must be an array of PageEntry objects';
+        logger?.error(errorMsg);
+        throw new Error(errorMsg);
+    }
+
+    logger?.info(`Bundling ${pages.length} pages into a multi-page HTML document.`);
+
+    const validPages = pages.filter(page => {
+        const isValid = page && typeof page === 'object' && typeof page.url === 'string' && typeof page.html === 'string';
+        if (!isValid) logger?.warn('Skipping invalid page entry');
+        return isValid;
+    });
+
+    if (validPages.length === 0) {
+        const errorMsg = 'No valid page entries found in input array';
+        logger?.error(errorMsg);
+        throw new Error(errorMsg);
+    }
+
+    const slugMap = new Map<string, string>();
+    const usedSlugs = new Set<string>();
+
+    for (const page of validPages) {
+        const baseSlug = sanitizeSlug(page.url);
+        let slug = baseSlug;
+        let counter = 1;
+        while (usedSlugs.has(slug)) {
+            slug = `${baseSlug}-${counter++}`;
+            logger?.warn(`Slug collision detected for "${page.url}". Using "${slug}" instead.`);
+        }
+        usedSlugs.add(slug);
+        slugMap.set(page.url, slug);
+    }
+
+    const defaultPageSlug = slugMap.get(validPages[0].url);
+
+    let output = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Multi-Page Bundle</title>
+</head>
+<body>
+    <nav id="main-nav">
+        ${validPages.map(p => {
+            const slug = slugMap.get(p.url)!;
+            const label = p.url.split('/').pop()?.split('.')[0] || 'Page';
+            return `<a href="#${slug}" data-page="${slug}">${label}</a>`;
+        }).join('\n')}
+    </nav>
+    <div id="page-container"></div>
+    ${validPages.map(p => {
+        const slug = slugMap.get(p.url)!;
+        return `<template id="page-${slug}">${p.html}</template>`;
+    }).join('\n')}
+    <script id="router-script">
+        document.addEventListener('DOMContentLoaded', function() {
+            function navigateTo(slug) {
+                const template = document.getElementById('page-' + slug);
+                const container = document.getElementById('page-container');
+                if (!template || !container) return;
+                container.innerHTML = '';
+                container.appendChild(template.content.cloneNode(true));
+                document.querySelectorAll('#main-nav a').forEach(link => {
+                    if (link.getAttribute('data-page') === slug) link.classList.add('active');
+                    else link.classList.remove('active');
+                });
+                if (window.location.hash.substring(1) !== slug) {
+                    history.pushState(null, '', '#' + slug);
+                }
+            }
+
+            window.addEventListener('hashchange', () => {
+                const slug = window.location.hash.substring(1);
+                if (document.getElementById('page-' + slug)) navigateTo(slug);
+            });
+
+            document.querySelectorAll('#main-nav a').forEach(link => {
+                link.addEventListener('click', function(e) {
+                    e.preventDefault();
+                    const slug = this.getAttribute('data-page');
+                    navigateTo(slug);
+                });
+            });
+
+            const initial = window.location.hash.substring(1);
+            navigateTo(document.getElementById('page-' + initial) ? initial : '${defaultPageSlug}');
+        });
+    </script>
+</body>
+</html>`;
+
+    logger?.info(`Multi-page bundle generated. Size: ${Buffer.byteLength(output, 'utf-8')} bytes.`);
+    return output;
+}