portapack 0.2.1

package/src/core/minifier.ts

@@ -0,0 +1,233 @@
+/**
+ * @file src/core/minifier.ts
+ * @description
+ * Provides the core functionality for minifying HTML, CSS, and JavaScript content
+ * within the PortaPack bundling process. Uses `html-minifier-terser`, `clean-css`,
+ * and `terser` libraries. Handles errors gracefully by logging warnings and returning
+ * original content for the specific asset that failed minification.
+ * Includes workarounds for apparent issues in @types/clean-css definitions.
+ */
+
+// --- Imports ---
+import { minify as htmlMinify } from 'html-minifier-terser';
+import type { Options as HtmlMinifyOptions } from 'html-minifier-terser';
+import CleanCSS from 'clean-css';
+// Import specific types from clean-css. Note: Using these directly caused issues.
+import type { Options as CleanCSSOptions } from 'clean-css';
+import { minify as jsMinify } from 'terser';
+import type { MinifyOptions, MinifyOutput } from 'terser';
+// Import necessary types from project - ensure these paths are correct and use .js extension
+import type { ParsedHTML, BundleOptions, Asset } from '../types.js';
+import { Logger } from '../utils/logger.js';
+
+// --- Helper Interface for Workaround ---
+
+/**
+ * Represents the expected structure of the synchronous output from clean-css.
+ * Used with type assertion as a workaround for problematic official type definitions.
+ */
+export interface CleanCSSSyncResult { // <<< MUST HAVE 'export'
+    styles?: string;
+    errors?: string[];
+    warnings?: string[];
+    stats?: {
+        originalSize: number;
+        minifiedSize: number;
+    };
+}
+
+// --- Default Minification Options Constants ---
+
+/**
+ * Default options for html-minifier-terser.
+ */
+const HTML_MINIFY_OPTIONS: HtmlMinifyOptions = {
+    collapseWhitespace: true,
+    removeComments: true,
+    conservativeCollapse: true,
+    minifyCSS: false, // Handled separately
+    minifyJS: false,  // Handled separately
+    removeAttributeQuotes: false,
+    removeRedundantAttributes: true,
+    removeScriptTypeAttributes: true,
+    removeStyleLinkTypeAttributes: true,
+    useShortDoctype: true,
+};
+
+/**
+ * Default options for clean-css.
+ * Explicitly set returnPromise to false to ensure synchronous operation.
+ */
+const CSS_MINIFY_OPTIONS: CleanCSSOptions = {
+    returnPromise: false, // <<< *** Ensures sync operation at runtime ***
+    level: {
+        1: { // Level 1 optimizations (safe transformations)
+            optimizeBackground: true,
+            optimizeBorderRadius: true,
+            optimizeFilter: true,
+            optimizeFontWeight: true,
+            optimizeOutline: true,
+        },
+        2: { // Level 2 optimizations (structural changes, generally safe)
+            mergeMedia: true,
+            mergeNonAdjacentRules: true,
+            removeDuplicateFontRules: true,
+            removeDuplicateMediaBlocks: true,
+            removeDuplicateRules: true,
+            restructureRules: true,
+        }
+    }
+    // Note: Type checking based on these options seems problematic with current @types/clean-css
+};
+
+/**
+ * Default options for terser (JavaScript minifier).
+ */
+const JS_MINIFY_OPTIONS: MinifyOptions = {
+    compress: {
+        dead_code: true,
+        drop_console: false,
+        drop_debugger: true,
+        ecma: 2020,
+        keep_classnames: true,
+        keep_fnames: true
+    },
+    mangle: {
+        keep_classnames: true,
+        keep_fnames: true
+    },
+    format: { comments: false }
+};
+
+// --- Main Minification Function ---
+
+/**
+ * Applies HTML, CSS, and JS minification conditionally based on BundleOptions.
+ * Uses type assertion for clean-css result and @ts-ignore for its constructor
+ * due to persistent type definition issues.
+ * Creates and returns a *new* ParsedHTML object containing the potentially minified content.
+ *
+ * @param {ParsedHTML} parsed - Input ParsedHTML object.
+ * @param {BundleOptions} [options={}] - Options controlling minification.
+ * @param {Logger} [logger] - Optional logger instance.
+ * @returns {Promise<ParsedHTML>} A Promise resolving to a new ParsedHTML object.
+ */
+export async function minifyAssets(
+    parsed: ParsedHTML,
+    options: BundleOptions = {},
+    logger?: Logger
+): Promise<ParsedHTML> {
+    const { htmlContent, assets } = parsed;
+
+    // Use optional chaining and nullish coalescing for safer access
+    const currentHtmlContent = htmlContent ?? '';
+    const currentAssets = assets ?? [];
+
+
+    if (!currentHtmlContent && currentAssets.length === 0) {
+        logger?.debug('Minification skipped: No content.');
+        return { htmlContent: currentHtmlContent, assets: currentAssets };
+    }
+
+    const minifyFlags = {
+        minifyHtml: options.minifyHtml !== false,
+        minifyCss: options.minifyCss !== false,
+        minifyJs: options.minifyJs !== false
+    };
+
+    logger?.debug(`Minification flags: ${JSON.stringify(minifyFlags)}`);
+
+    const minifiedAssets: Asset[] = await Promise.all(
+        currentAssets.map(async (asset): Promise<Asset> => {
+            // Make a shallow copy to avoid modifying the original asset object
+             let processedAsset = { ...asset };
+
+            if (typeof processedAsset.content !== 'string' || processedAsset.content.length === 0) {
+                return processedAsset; // Return the copy
+            }
+
+            let newContent = processedAsset.content; // Work with the content of the copy
+            const assetIdentifier = processedAsset.url || `inline ${processedAsset.type}`;
+
+            try {
+                // --- Minify CSS (Synchronous Call with Type Assertion Workaround) ---
+                if (minifyFlags.minifyCss && processedAsset.type === 'css') {
+                    logger?.debug(`Minifying CSS: ${assetIdentifier}`);
+
+                    // @ts-ignore - Suppress error TS2769 due to likely faulty @types/clean-css constructor overload definitions for sync mode.
+                    const cssMinifier = new CleanCSS(CSS_MINIFY_OPTIONS); // <<< @ts-ignore HERE
+
+                    // WORKAROUND using Type Assertion
+                    const result = cssMinifier.minify(processedAsset.content) as CleanCSSSyncResult;
+
+                    // Access properties based on the asserted type
+                    if (result.errors && result.errors.length > 0) {
+                        logger?.warn(`⚠️ CleanCSS failed for ${assetIdentifier}: ${result.errors.join(', ')}`);
+                    } else {
+                        if (result.warnings && result.warnings.length > 0) {
+                            logger?.debug(`CleanCSS warnings for ${assetIdentifier}: ${result.warnings.join(', ')}`);
+                        }
+                        if (result.styles) {
+                           newContent = result.styles; // Update newContent
+                           logger?.debug(`CSS minified successfully: ${assetIdentifier}`);
+                        } else {
+                           logger?.warn(`⚠️ CleanCSS produced no styles but reported no errors for ${assetIdentifier}. Keeping original.`);
+                        }
+                    }
+                }
+
+                // --- Minify JS (Asynchronous Call) ---
+                if (minifyFlags.minifyJs && processedAsset.type === 'js') {
+                    logger?.debug(`Minifying JS: ${assetIdentifier}`);
+                    const result: MinifyOutput = await jsMinify(processedAsset.content, JS_MINIFY_OPTIONS);
+                    if (result.code) {
+                        newContent = result.code; // Update newContent
+                        logger?.debug(`JS minified successfully: ${assetIdentifier}`);
+                    } else {
+                        const terserError = (result as any).error;
+                        if (terserError) {
+                            logger?.warn(`⚠️ Terser failed for ${assetIdentifier}: ${terserError.message || terserError}`);
+                        } else {
+                            logger?.warn(`⚠️ Terser produced no code but reported no errors for ${assetIdentifier}. Keeping original.`);
+                        }
+                    }
+                }
+            } catch (err: unknown) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                logger?.warn(`⚠️ Failed to minify asset ${assetIdentifier} (${processedAsset.type}): ${errorMessage}`);
+                // Keep original content if error occurs (newContent remains unchanged)
+            }
+
+             // Update the content property of the copied asset
+            processedAsset.content = newContent;
+            return processedAsset; // Return the modified copy
+        })
+    );
+
+    // --- Minify the main HTML content itself ---
+    let finalHtml = currentHtmlContent; // Start with potentially empty original HTML
+    if (minifyFlags.minifyHtml && finalHtml.length > 0) {
+        logger?.debug('Minifying HTML content...');
+        try {
+            finalHtml = await htmlMinify(finalHtml, {
+                ...HTML_MINIFY_OPTIONS,
+                minifyCSS: minifyFlags.minifyCss,
+                minifyJS: minifyFlags.minifyJs
+            });
+            logger?.debug('HTML minified successfully.');
+        } catch (err: unknown) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            logger?.warn(`⚠️ HTML minification failed: ${errorMessage}`);
+            // Keep original HTML (finalHtml already holds it)
+        }
+    } else if (finalHtml.length > 0) {
+        logger?.debug('HTML minification skipped (disabled).');
+    }
+
+
+    // --- Return the final result object ---
+    return {
+        htmlContent: finalHtml,
+        assets: minifiedAssets // The array of processed asset copies
+    };
+}

package/src/core/packer.ts

@@ -0,0 +1,191 @@
+/**
+ * @file src/core/packer.ts
+ * @description Inlines CSS, JS, and images into an HTML document for full portability.
+ * Uses Cheerio for safe DOM manipulation.
+ */
+
+import * as cheerio from 'cheerio';
+// Import CheerioAPI type
+import type { CheerioAPI } from 'cheerio';
+import type { ParsedHTML, Asset } from '../types'; // Assuming correct path
+import { Logger } from '../utils/logger'; // Assuming correct path
+import { guessMimeType } from '../utils/mime'; // Assuming correct path
+
+/**
+ * Escapes characters potentially problematic within inline `<script>` tags.
+ */
+function escapeScriptContent(code: string): string {
+    return code.replace(/<\/(script)/gi, '<\\/$1');
+}
+
+/**
+ * Ensures a `<base href="./">` tag exists within the `<head>` of the HTML.
+ * Creates <head> or even <html> if necessary using Cheerio.
+ *
+ * @param {CheerioAPI} $ - The Cheerio instance representing the HTML document.
+ * @param {Logger} [logger] - Optional logger instance.
+ */
+function ensureBaseTag($: CheerioAPI, logger?: Logger): void {
+    let head = $('head');
+
+    // If <head> doesn't exist, create it, ensuring <html> exists first.
+    if (head.length === 0) {
+        logger?.debug('No <head> tag found. Creating <head> and ensuring <html> exists.');
+        let htmlElement = $('html');
+
+        // If <html> doesn't exist, create it and wrap the existing content.
+        if (htmlElement.length === 0) {
+            logger?.debug('No <html> tag found. Wrapping content in <html><body>...');
+            const bodyContent = $.root().html() || '';
+            $.root().empty();
+            // FIX: Use 'as any' for type assertion
+            htmlElement = $('<html>').appendTo($.root()) as any;
+            // FIX: Use 'as any' for type assertion
+            head = $('<head>').appendTo(htmlElement) as any;
+            $('<body>').html(bodyContent).appendTo(htmlElement);
+        } else {
+            // If <html> exists but <head> doesn't, prepend <head> to <html>
+            // FIX: Use 'as any' for type assertion
+            head = $('<head>').prependTo(htmlElement) as any;
+        }
+    }
+
+    // Now head should represent the head element selection.
+    // Check if <base> exists within the guaranteed <head>.
+    // Use type guard just in case head couldn't be created properly
+    if (head && head.length > 0 && head.find('base[href]').length === 0) {
+        logger?.debug('Prepending <base href="./"> to <head>.');
+        head.prepend('<base href="./">');
+    }
+}
+
+
+/**
+ * Inlines assets into the HTML document using Cheerio for safe DOM manipulation.
+ */
+function inlineAssets($: CheerioAPI, assets: Asset[], logger?: Logger): void {
+    logger?.debug(`Inlining ${assets.filter(a => a.content).length} assets with content...`);
+    const assetMap = new Map<string, Asset>(assets.map(asset => [asset.url, asset]));
+
+    // 1. Inline CSS (<link rel="stylesheet" href="...">)
+    $('link[rel="stylesheet"][href]').each((_, el) => {
+        const link = $(el);
+        const href = link.attr('href');
+        const asset = href ? assetMap.get(href) : undefined;
+        if (asset?.content && typeof asset.content === 'string') {
+            if (asset.content.startsWith('data:')) {
+                 logger?.debug(`Replacing link with style tag using existing data URI: ${asset.url}`);
+                 const styleTag = $('<style>').text(`@import url("${asset.content}");`);
+                 link.replaceWith(styleTag);
+            } else {
+                 logger?.debug(`Inlining CSS: ${asset.url}`);
+                 const styleTag = $('<style>').text(asset.content);
+                 link.replaceWith(styleTag);
+            }
+        } else if (href) {
+             logger?.warn(`Could not inline CSS: ${href}. Content missing or invalid.`);
+        }
+    });
+
+    // 2. Inline JS (<script src="...">)
+    $('script[src]').each((_, el) => {
+        const script = $(el);
+        const src = script.attr('src');
+        const asset = src ? assetMap.get(src) : undefined;
+        if (asset?.content && typeof asset.content === 'string') {
+            logger?.debug(`Inlining JS: ${asset.url}`);
+            const inlineScript = $('<script>');
+            inlineScript.text(escapeScriptContent(asset.content));
+            Object.entries(script.attr() || {}).forEach(([key, value]) => {
+                 if (key.toLowerCase() !== 'src') inlineScript.attr(key, value);
+            });
+            script.replaceWith(inlineScript);
+        } else if (src) {
+            logger?.warn(`Could not inline JS: ${src}. Content missing or not string.`);
+        }
+    });
+
+    // 3. Inline Images (<img src="...">, <video poster="...">, etc.)
+    $('img[src], video[poster], input[type="image"][src]').each((_, el) => {
+        const element = $(el);
+        const srcAttr = element.is('video') ? 'poster' : 'src';
+        const src = element.attr(srcAttr);
+        const asset = src ? assetMap.get(src) : undefined;
+        if (asset?.content && typeof asset.content === 'string' && asset.content.startsWith('data:')) {
+            logger?.debug(`Inlining image via ${srcAttr}: ${asset.url}`);
+            element.attr(srcAttr, asset.content);
+        } else if (src) {
+            logger?.warn(`Could not inline image via ${srcAttr}: ${src}. Content missing or not a data URI.`);
+        }
+    });
+
+     // 4. Inline srcset attributes (<img srcset="...">, <source srcset="...">)
+     $('img[srcset], source[srcset]').each((_, el) => {
+         const element = $(el);
+         const srcset = element.attr('srcset');
+         if (!srcset) return;
+         const newSrcsetParts: string[] = [];
+         let changed = false;
+         srcset.split(',').forEach(part => {
+             const trimmedPart = part.trim();
+             const [url, descriptor] = trimmedPart.split(/\s+/, 2);
+             const asset = url ? assetMap.get(url) : undefined;
+             if (asset?.content && typeof asset.content === 'string' && asset.content.startsWith('data:')) {
+                 newSrcsetParts.push(`${asset.content}${descriptor ? ' ' + descriptor : ''}`);
+                 changed = true;
+             } else {
+                 newSrcsetParts.push(trimmedPart);
+             }
+         });
+         if (changed) {
+              element.attr('srcset', newSrcsetParts.join(', '));
+         }
+     });
+
+     // 5. Inline other asset types (video, audio sources)
+      $('video[src], audio[src], video > source[src], audio > source[src]').each((_, el) => {
+         const element = $(el);
+         const src = element.attr('src');
+         const asset = src ? assetMap.get(src) : undefined;
+         if (asset?.content && typeof asset.content === 'string' && asset.content.startsWith('data:')) {
+             logger?.debug(`Inlining media source: ${asset.url}`);
+             element.attr('src', asset.content);
+         }
+     });
+
+    logger?.debug('Asset inlining process complete.');
+}
+
+
+/**
+ * Packs a ParsedHTML object into a single, self-contained HTML string.
+ * This involves ensuring a base tag exists and inlining all assets
+ * that have content available. Uses Cheerio for safe DOM manipulation.
+ *
+ * @export
+ * @param {ParsedHTML} parsed - The parsed HTML document object, including its list of assets (which may have content).
+ * @param {Logger} [logger] - Optional logger instance.
+ * @returns {string} The packed HTML string with assets inlined. Returns a minimal HTML structure if input is invalid.
+ */
+export function packHTML(parsed: ParsedHTML, logger?: Logger): string {
+    const { htmlContent, assets } = parsed;
+    if (!htmlContent || typeof htmlContent !== 'string') {
+        logger?.warn('Packer received empty or invalid htmlContent. Returning minimal HTML shell.');
+        return '<!DOCTYPE html><html><head><base href="./"></head><body></body></html>';
+    }
+
+    logger?.debug('Loading HTML content into Cheerio for packing...');
+    const $ = cheerio.load(htmlContent);
+
+    logger?.debug('Ensuring <base> tag exists...');
+    ensureBaseTag($, logger); // Ensure base tag safely
+
+    logger?.debug('Starting asset inlining...');
+    inlineAssets($, assets, logger); // Inline assets safely
+
+    logger?.debug('Generating final packed HTML string...');
+    const finalHtml = $.html();
+
+    logger?.debug(`Packing complete. Final size: ${Buffer.byteLength(finalHtml)} bytes.`);
+    return finalHtml;
+}

package/src/core/parser.ts

@@ -0,0 +1,115 @@
+/**
+ * @file src/core/parser.ts
+ * @description
+ * Parses an HTML file using Cheerio to extract the basic structure
+ * and identify top-level linked assets (CSS, JS, images, fonts, video, audio etc.).
+ * It relies on tag names, link relations, and file extensions to guess asset types.
+ * It does *not* fetch or analyze the content of linked assets. Inline styles/scripts
+ * and data URIs are ignored. Duplicate asset URLs are ignored.
+ */
+
+// FIX: Use only the named import for readFile
+import { readFile } from 'fs/promises';
+// NOTE: 'path' module was imported but not used, so removed. Add back if needed later.
+// import path from 'path';
+import * as cheerio from 'cheerio';
+import type { CheerioAPI } from 'cheerio';
+import type { Asset, ParsedHTML } from '../types.js';
+import { Logger } from '../utils/logger.js';
+import { guessMimeType } from '../utils/mime.js';
+
+/**
+ * Parses an HTML file from the given path using Cheerio.
+ * Extracts references to external assets like CSS, JS, images, fonts, video, audio
+ * found in common HTML tags (<link>, <script>, <img>, <source>, <video>, <audio>, <input type="image">).
+ * Does not extract assets linked *within* CSS (like @import, fonts or background images).
+ * Data URIs and empty URLs are ignored. Duplicate URLs are ignored.
+ *
+ * @async
+ * @function parseHTML
+ * @param {string} entryFilePath - Absolute or relative path to the input HTML file.
+ * @param {Logger} [logger] - Optional logger instance.
+ * @returns {Promise<ParsedHTML>} A promise that resolves to the parsed HTML content
+ * and a list of discovered asset URLs with their inferred types.
+ * @throws {Error} Throws an error with cause if the file cannot be read.
+ */
+export async function parseHTML(entryFilePath: string, logger?: Logger): Promise<ParsedHTML> {
+    logger?.debug(`Parsing HTML file: ${entryFilePath}`);
+    let htmlContent: string;
+    try {
+        // FIX: Use the correctly imported 'readFile' function directly
+        htmlContent = await readFile(entryFilePath, 'utf-8');
+        logger?.debug(`Successfully read HTML file (${Buffer.byteLength(htmlContent)} bytes).`);
+    } catch (err: any) {
+        logger?.error(`Failed to read HTML file "${entryFilePath}": ${err.message}`);
+        throw new Error(`Could not read input HTML file: ${entryFilePath}`, { cause: err });
+    }
+
+    const $: CheerioAPI = cheerio.load(htmlContent);
+    const assets: Asset[] = [];
+    const addedUrls = new Set<string>();
+
+    /** Helper to add unique assets */
+    const addAsset = (url?: string, forcedType?: Asset['type']): void => {
+        if (!url || url.trim() === '' || url.startsWith('data:')) {
+            return;
+        }
+        if (!addedUrls.has(url)) {
+            addedUrls.add(url);
+            const mimeInfo = guessMimeType(url);
+            const type = forcedType ?? mimeInfo.assetType;
+            assets.push({ type, url });
+            logger?.debug(`Discovered asset: Type='${type}', URL='${url}'`);
+        } else {
+             logger?.debug(`Skipping duplicate asset URL: ${url}`);
+        }
+    };
+
+    logger?.debug('Extracting assets from HTML tags...');
+
+    // --- Extract Assets from Various Tags ---
+    // Stylesheets: <link rel="stylesheet" href="...">
+    $('link[rel="stylesheet"][href]').each((_, el) => {
+        addAsset($(el).attr('href'), 'css');
+    });
+    // JavaScript: <script src="...">
+    $('script[src]').each((_, el) => {
+        addAsset($(el).attr('src'), 'js');
+    });
+    // Images: <img src="...">, <input type="image" src="...">
+    $('img[src]').each((_, el) => addAsset($(el).attr('src'), 'image'));
+    $('input[type="image"][src]').each((_, el) => addAsset($(el).attr('src'), 'image'));
+    // Image srcset: <img srcset="...">, <source srcset="..."> (within picture)
+    $('img[srcset], picture source[srcset]').each((_, el) => {
+        const srcset = $(el).attr('srcset');
+        srcset?.split(',').forEach(entry => {
+            const [url] = entry.trim().split(/\s+/);
+            addAsset(url, 'image');
+        });
+    });
+    // Video: <video src="...">, <video poster="...">
+    $('video[src]').each((_, el) => addAsset($(el).attr('src'), 'video'));
+    $('video[poster]').each((_, el) => addAsset($(el).attr('poster'), 'image'));
+    // Audio: <audio src="...">
+    $('audio[src]').each((_, el) => addAsset($(el).attr('src'), 'audio'));
+    // Media Sources: <source src="..."> within <video> or <audio>
+    $('video > source[src]').each((_, el) => addAsset($(el).attr('src'), 'video'));
+    $('audio > source[src]').each((_, el) => addAsset($(el).attr('src'), 'audio'));
+    // Icons and Manifest: <link rel="icon/shortcut icon/apple-touch-icon/manifest" href="...">
+    $('link[href]').filter((_, el) => {
+        const rel = $(el).attr('rel')?.toLowerCase() ?? '';
+        return ['icon', 'shortcut icon', 'apple-touch-icon', 'manifest'].includes(rel);
+    }).each((_, el) => {
+         const rel = $(el).attr('rel')?.toLowerCase() ?? '';
+         const isIcon = ['icon', 'shortcut icon', 'apple-touch-icon'].includes(rel);
+         addAsset($(el).attr('href'), isIcon ? 'image' : undefined);
+     });
+    // Preloaded Fonts: <link rel="preload" as="font" href="...">
+    $('link[rel="preload"][as="font"][href]').each((_, el) => {
+        addAsset($(el).attr('href'), 'font');
+    });
+
+    // --- Parsing Complete ---
+    logger?.info(`HTML parsing complete. Discovered ${assets.length} unique asset links.`);
+    return { htmlContent, assets };
+}