portapack 0.2.1

package/src/types.ts

@@ -0,0 +1,163 @@
+/**
+ * @file types.ts
+ *
+ * @description
+ * Centralized types used across the PortaPack CLI, API, core modules, and bundling pipeline.
+ *
+ * This file defines:
+ * - Asset structure
+ * - HTML parsing result
+ * - Bundling options and metadata
+ * - Page structures for recursive bundling
+ * - CLI execution output format
+ */
+
+/**
+ * Represents a single discovered, downloaded, or embedded asset.
+ * This includes JS, CSS, images, fonts, etc.
+ */
+export interface Asset {
+  type: 'css' | 'js' | 'image' | 'font' | 'video' | 'audio' | 'other'; // Add video and audio
+  
+  /** The resolved or original URL of the asset */
+  url: string;
+
+  /** Inlined or fetched content */
+  content?: string; // Content is optional as it might not be embedded
+
+  /** Font-specific metadata for font-face usage */
+  fontMeta?: {
+    familyName: string;
+    weight?: number;
+    style?: 'normal' | 'italic' | 'oblique';
+    format?: string;
+  };
+}
+
+/**
+ * Represents raw HTML and any linked/discovered assets.
+ * Result of the parsing stage.
+ */
+export interface ParsedHTML {
+  htmlContent: string;
+  assets: Asset[]; // List of assets found in the HTML
+}
+
+/**
+ * Represents a single page crawled during recursive bundling.
+ * Used as input for the multi-page bundler.
+ */
+export interface PageEntry {
+  /** Full resolved URL of the crawled page */
+  url: string;
+
+  /** Raw HTML content of the crawled page */
+  html: string;
+}
+
+/**
+ * Configuration options provided by the user via CLI or API call.
+ * Controls various aspects of the bundling process.
+ */
+export interface BundleOptions {
+  /** Embed all discovered assets as data URIs (default: true) */
+  embedAssets?: boolean;
+
+  /** Enable HTML minification using html-minifier-terser (default: true) */
+  minifyHtml?: boolean;
+
+  /** Enable CSS minification using clean-css (default: true) */
+  minifyCss?: boolean;
+
+  /** Enable JavaScript minification using terser (default: true) */
+  minifyJs?: boolean;
+
+  /** Base URL for resolving relative links, especially for remote fetches or complex local structures */
+  baseUrl?: string;
+
+  /** Enable verbose logging during CLI execution */
+  verbose?: boolean;
+
+  /** Skip writing output file to disk (CLI dry-run mode) */
+  dryRun?: boolean;
+
+  /** Enable recursive crawling. If a number, specifies max depth. If true, uses default depth. */
+  recursive?: number | boolean;
+
+  /** Optional output file path override (CLI uses this) */
+  output?: string;
+
+  /** Log level for the internal logger */
+  logLevel?: LogLevel;
+}
+
+// --- LogLevel Enum ---
+// Defines available log levels as a numeric enum for comparisons.
+export enum LogLevel {
+  NONE = 0,   // No logging (equivalent to 'silent')
+  ERROR = 1,  // Only errors
+  WARN = 2,   // Errors and warnings
+  INFO = 3,   // Errors, warnings, and info (Default)
+  DEBUG = 4   // All messages (Verbose)
+}
+
+// --- String Literal Type for LogLevel Names (Optional, useful for CLI parsing) ---
+export type LogLevelName = 'debug' | 'info' | 'warn' | 'error' | 'silent' | 'none';
+
+
+/**
+ * Summary statistics and metadata returned after the packing/bundling process completes.
+ */
+export interface BundleMetadata {
+  /** Source HTML file path or URL */
+  input: string;
+
+  /** Total number of unique assets discovered (CSS, JS, images, fonts etc.) */
+  assetCount: number; // Kept as required - should always be calculated or defaulted (e.g., to 0)
+
+  /** Final output HTML size in bytes */
+  outputSize: number;
+
+  /** Elapsed build time in milliseconds */
+  buildTimeMs: number;
+
+  /** If recursive bundling was performed, the number of pages successfully crawled and included */
+  pagesBundled?: number; // Optional, only relevant for recursive mode
+
+  /** Any non-critical errors or warnings encountered during bundling (e.g., asset fetch failure) */
+  errors?: string[]; // Optional array of error/warning messages
+}
+
+/**
+ * Standard result object returned from the main public API functions.
+ */
+export interface BuildResult {
+  /** The final generated HTML string */
+  html: string;
+  /** Metadata summarizing the build process */
+  metadata: BundleMetadata;
+}
+
+
+/** CLI-specific options extending BundleOptions. */
+export interface CLIOptions extends BundleOptions {
+  /** Input file or URL (positional). */
+  input?: string;
+  /** Max depth for recursive crawling (numeric alias for recursive). */
+   maxDepth?: number; // Used by commander, then merged into 'recursive'
+   minify?: boolean; // Minify assets (defaults to true)
+}
+
+/**
+ * Result object specifically for the CLI runner, capturing output streams and exit code.
+ */
+export interface CLIResult {
+  /** Captured content written to stdout */
+  stdout?: string;
+
+  /** Captured content written to stderr */
+  stderr?: string;
+
+  /** Final exit code intended for the process (0 for success, non-zero for errors) */
+  exitCode: number;
+}

package/src/utils/font.ts

@@ -0,0 +1,41 @@
+/**
+ * utils/font.ts
+ *
+ * Utilities for detecting and encoding font files for embedding.
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+/**
+ * Returns the correct MIME type for a given font file.
+ *
+ * @param fontUrl - The path or URL of the font file
+ */
+export function getFontMimeType(fontUrl: string): string {
+  const ext = path.extname(fontUrl).toLowerCase().replace('.', '');
+
+  switch (ext) {
+    case 'woff': return 'font/woff';
+    case 'woff2': return 'font/woff2';
+    case 'ttf': return 'font/ttf';
+    case 'otf': return 'font/otf';
+    case 'eot': return 'application/vnd.ms-fontobject';
+    default: return 'application/octet-stream';
+  }
+}
+
+/**
+ * Reads a font file and encodes it as a base64 data URI.
+ *
+ * NOTE: Not currently used in the pipeline, but useful for testing and future features.
+ *
+ * @param fontPath - Absolute or relative path to font
+ * @returns Full `data:` URI as a string
+ */
+export async function encodeFontToDataURI(fontPath: string): Promise<string> {
+  const mime = getFontMimeType(fontPath);
+  const buffer = await fs.readFile(fontPath);
+  const base64 = buffer.toString('base64');
+  return `data:${mime};base64,${base64}`;
+}

package/src/utils/logger.ts

@@ -0,0 +1,139 @@
+/**
+ * @file src/utils/logger.ts
+ * @description Provides a standardized logging utility with configurable levels (based on an enum)
+ * to control output verbosity throughout the application (core, API, CLI).
+ */
+
+// FIX: Use a regular import for the enum, not 'import type'
+import { LogLevel } from '../types';
+// Assuming LogLevel enum is defined and exported in '../types' like:
+// export enum LogLevel { NONE = 0, ERROR = 1, WARN = 2, INFO = 3, DEBUG = 4 }
+
+/**
+ * Optional configuration for creating a Logger instance.
+ * (Note: Currently constructor only accepts LogLevel directly)
+ */
+export interface LoggerOptions {
+    level?: LogLevel;
+}
+
+/**
+ * A simple logger class that allows filtering messages based on severity levels.
+ * Uses standard console methods (debug, info, warn, error) for output.
+ */
+export class Logger {
+    /** The current minimum log level required for a message to be output. */
+    public level: LogLevel;
+
+    /**
+     * Creates a new Logger instance.
+     * Defaults to LogLevel.INFO if no level is provided.
+     *
+     * @param {LogLevel} [level=LogLevel.INFO] - The initial log level for this logger instance.
+     * Must be one of the values from the LogLevel enum.
+     */
+    constructor(level: LogLevel = LogLevel.INFO) { // Defaulting to INFO level using the enum value
+        // Ensure a valid LogLevel enum member is provided or default correctly
+        this.level = (level !== undefined && LogLevel[level] !== undefined)
+            ? level
+            : LogLevel.INFO; // Use the enum value for default
+    }
+
+    /**
+     * Updates the logger's current level. Messages below this level will be suppressed.
+     *
+     * @param {LogLevel} level - The new log level to set. Must be a LogLevel enum member.
+     */
+    setLevel(level: LogLevel): void {
+        this.level = level;
+    }
+
+    /**
+     * Logs a debug message if the current log level is DEBUG or higher.
+     *
+     * @param {string} message - The debug message string.
+     */
+    debug(message: string): void {
+        // Use enum member for comparison
+        if (this.level >= LogLevel.DEBUG) {
+            console.debug(`[DEBUG] ${message}`);
+        }
+    }
+
+    /**
+     * Logs an informational message if the current log level is INFO or higher.
+     *
+     * @param {string} message - The informational message string.
+     */
+    info(message: string): void {
+        // Use enum member for comparison
+        if (this.level >= LogLevel.INFO) {
+            console.info(`[INFO] ${message}`);
+        }
+    }
+
+    /**
+     * Logs a warning message if the current log level is WARN or higher.
+     *
+     * @param {string} message - The warning message string.
+     */
+    warn(message: string): void {
+        // Use enum member for comparison
+        if (this.level >= LogLevel.WARN) {
+            console.warn(`[WARN] ${message}`);
+        }
+    }
+
+    /**
+     * Logs an error message if the current log level is ERROR or higher.
+     *
+     * @param {string} message - The error message string.
+     */
+    error(message: string): void {
+        // Use enum member for comparison
+        if (this.level >= LogLevel.ERROR) {
+            console.error(`[ERROR] ${message}`);
+        }
+    }
+
+    /**
+     * Static factory method to create a Logger instance based on a simple boolean `verbose` flag.
+     *
+     * @static
+     * @param {{ verbose?: boolean }} [options={}] - An object potentially containing a `verbose` flag.
+     * @returns {Logger} A new Logger instance set to LogLevel.DEBUG if options.verbose is true,
+     * otherwise set to LogLevel.INFO.
+     */
+    static fromVerboseFlag(options: { verbose?: boolean } = {}): Logger {
+        // Use enum members for assignment
+        return new Logger(options.verbose ? LogLevel.DEBUG : LogLevel.INFO);
+    }
+
+     /**
+      * Static factory method to create a Logger instance based on a LogLevel string name.
+      * Useful for creating a logger from config files or environments variables.
+      *
+      * @static
+      * @param {string | undefined} levelName - The name of the log level (e.g., 'debug', 'info', 'warn', 'error', 'silent'/'none'). Case-insensitive.
+      * @param {LogLevel} [defaultLevel=LogLevel.INFO] - The level to use if levelName is invalid or undefined.
+      * @returns {Logger} A new Logger instance set to the corresponding LogLevel.
+      */
+     static fromLevelName(levelName?: string, defaultLevel: LogLevel = LogLevel.INFO): Logger {
+         if (!levelName) {
+             return new Logger(defaultLevel);
+         }
+         switch (levelName.toLowerCase()) {
+             // Return enum members
+             case 'debug': return new Logger(LogLevel.DEBUG);
+             case 'info': return new Logger(LogLevel.INFO);
+             case 'warn': return new Logger(LogLevel.WARN);
+             case 'error': return new Logger(LogLevel.ERROR);
+             case 'silent':
+             case 'none': return new Logger(LogLevel.NONE);
+             default:
+                 // Use console.warn directly here as logger might not be ready
+                 console.warn(`[Logger] Invalid log level name "${levelName}". Defaulting to ${LogLevel[defaultLevel]}.`);
+                 return new Logger(defaultLevel);
+         }
+     }
+}

package/src/utils/meta.ts

@@ -0,0 +1,100 @@
+/**
+ * @file src/utils/meta.ts
+ * @description Utility class for tracking bundle statistics like size, time,
+ * asset counts, page counts, and errors during the build process.
+ * Used by both CLI and API to return metadata consistently.
+ */
+
+import type { BundleMetadata } from '../types'; // Assuming types are in ../types
+
+/**
+ * Tracks build performance (timing, output size) and collects metadata
+ * (asset counts, page counts, errors) during the HTML bundling process.
+ */
+export class BuildTimer {
+    private startTime: number;
+    private input: string;
+    private pagesBundled?: number; // Tracks pages for recursive bundles
+    private assetCount: number = 0; // Tracks discovered/processed assets
+    private errors: string[] = []; // Collects warnings/errors
+
+    /**
+     * Creates and starts a build timer session for a given input.
+     *
+     * @param {string} input - The source file path or URL being processed.
+     */
+    constructor(input: string) {
+        this.startTime = Date.now();
+        this.input = input;
+    }
+
+    /**
+     * Explicitly sets the number of assets discovered or processed.
+     * This might be called after asset extraction/minification.
+     *
+     * @param {number} count - The total number of assets.
+     */
+    setAssetCount(count: number): void {
+        this.assetCount = count;
+    }
+
+    /**
+     * Records a warning or error message encountered during the build.
+     * These are added to the final metadata.
+     *
+     * @param {string} message - The warning or error description.
+     */
+    addError(message: string): void {
+        this.errors.push(message);
+    }
+
+    /**
+     * Sets the number of pages bundled, typically used in multi-page
+     * or recursive bundling scenarios.
+     *
+     * @param {number} count - The number of HTML pages included in the bundle.
+     */
+    setPageCount(count: number): void {
+        this.pagesBundled = count;
+    }
+
+    /**
+     * Stops the timer, calculates final metrics, and returns the complete
+     * BundleMetadata object. Merges any explicitly provided metadata
+     * (like assetCount calculated elsewhere) with the timer's tracked data.
+     *
+     * @param {string} finalHtml - The final generated HTML string, used to calculate output size.
+     * @param {Partial<BundleMetadata>} [extra] - Optional object containing metadata fields
+     * (like assetCount or pre-calculated errors) that should override the timer's internal values.
+     * @returns {BundleMetadata} The finalized metadata object for the build process.
+     */
+    finish(html: string, extra?: Partial<BundleMetadata>): BundleMetadata {
+      const buildTimeMs = Date.now() - this.startTime;
+      const outputSize = Buffer.byteLength(html || '', 'utf-8');
+
+      // Combine internal errors with any errors passed in 'extra', avoiding duplicates
+      // FIX: Ensure extra.errors is treated as an empty array if undefined/null
+      const combinedErrors = Array.from(new Set([...this.errors, ...(extra?.errors ?? [])]));
+
+      const finalMetadata: BundleMetadata = {
+          input: this.input,
+          outputSize,
+          buildTimeMs,
+          assetCount: extra?.assetCount ?? this.assetCount,
+          pagesBundled: extra?.pagesBundled ?? this.pagesBundled,
+          // Assign the combined errors array
+          errors: combinedErrors,
+      };
+
+      // Clean up optional fields if they weren't set/provided or are empty
+      if (finalMetadata.pagesBundled === undefined) {
+          delete finalMetadata.pagesBundled;
+      }
+      // Delete errors only if the *combined* array is empty
+      if (finalMetadata.errors?.length === 0) {
+          delete finalMetadata.errors;
+      }
+
+      return finalMetadata;
+  }
+}

package/src/utils/mime.ts

@@ -0,0 +1,90 @@
+/**
+ * @file src/utils/mime.ts
+ * @description Utilities for guessing MIME types and asset types from URLs/paths.
+ */
+
+import path from 'path';
+import type { Asset } from '../types'; // Assuming types are in ../types
+
+/**
+ * Maps common file extensions to their corresponding MIME types and general Asset types.
+ */
+const MIME_MAP: Record<string, { mime: string; assetType: Asset['type'] }> = {
+    // CSS
+    '.css': { mime: 'text/css', assetType: 'css' },
+    // JavaScript
+    '.js': { mime: 'application/javascript', assetType: 'js' },
+    '.mjs': { mime: 'application/javascript', assetType: 'js' },
+    // Images
+    '.png': { mime: 'image/png', assetType: 'image' },
+    '.jpg': { mime: 'image/jpeg', assetType: 'image' },
+    '.jpeg': { mime: 'image/jpeg', assetType: 'image' },
+    '.gif': { mime: 'image/gif', assetType: 'image' },
+    '.svg': { mime: 'image/svg+xml', assetType: 'image' },
+    '.webp': { mime: 'image/webp', assetType: 'image' },
+    '.ico': { mime: 'image/x-icon', assetType: 'image' },
+    '.avif': { mime: 'image/avif', assetType: 'image' },
+    // Fonts
+    '.woff': { mime: 'font/woff', assetType: 'font' },
+    '.woff2': { mime: 'font/woff2', assetType: 'font' },
+    '.ttf': { mime: 'font/ttf', assetType: 'font' },
+    '.otf': { mime: 'font/otf', assetType: 'font' },
+    '.eot': { mime: 'application/vnd.ms-fontobject', assetType: 'font' },
+    // Audio/Video (add more as needed)
+    '.mp3': { mime: 'audio/mpeg', assetType: 'other' },
+    '.ogg': { mime: 'audio/ogg', assetType: 'other' },
+    '.wav': { mime: 'audio/wav', assetType: 'other' },
+    '.mp4': { mime: 'video/mp4', assetType: 'other' },
+    '.webm': { mime: 'video/webm', assetType: 'other' },
+    // Other common web types
+    '.json': { mime: 'application/json', assetType: 'other' },
+    '.webmanifest': { mime: 'application/manifest+json', assetType: 'other' },
+    '.xml': { mime: 'application/xml', assetType: 'other' },
+    '.html': { mime: 'text/html', assetType: 'other' }, // Usually not needed as asset, but for completeness
+    '.txt': { mime: 'text/plain', assetType: 'other' },
+};
+
+/**
+ * Default MIME type and Asset type for unknown file extensions.
+ */
+const DEFAULT_MIME_TYPE = {
+    mime: 'application/octet-stream',
+    assetType: 'other' as Asset['type'] // Explicit cast needed
+};
+
+/**
+ * Guesses the MIME type and general Asset type based on a URL or file path's extension.
+ *
+ * @param {string} urlOrPath - The URL or file path string.
+ * @returns {{ mime: string; assetType: Asset['type'] }} An object containing the guessed MIME type
+ * and the corresponding Asset type (e.g., 'image', 'font', 'css', 'js', 'other'). Returns a default
+ * if the extension is unknown.
+ */
+export function guessMimeType(urlOrPath: string): { mime: string; assetType: Asset['type'] } {
+    if (!urlOrPath) {
+        return DEFAULT_MIME_TYPE;
+    }
+    // Extract the extension, handling potential query parameters or fragments
+    let ext = '';
+    try {
+        // Use URL parsing first to handle URLs correctly
+        const parsedUrl = new URL(urlOrPath);
+        ext = path.extname(parsedUrl.pathname).toLowerCase();
+    } catch {
+        // If it's not a valid URL, treat it as a path
+        ext = path.extname(urlOrPath).toLowerCase();
+    }
+
+    return MIME_MAP[ext] || DEFAULT_MIME_TYPE;
+}
+
+/**
+ * Gets the appropriate font MIME type based on the file extension.
+ * Deprecated: Prefer `guessMimeType`.
+ * @deprecated Use guessMimeType instead.
+ * @param {string} fontUrl - The URL or path of the font file.
+ * @returns {string} The corresponding font MIME type or a default.
+ */
+export function getFontMimeType(fontUrl: string): string {
+    return guessMimeType(fontUrl).mime; // Delegate to the main function
+}

package/src/utils/slugify.ts

@@ -0,0 +1,70 @@
+/**
+ * @file src/utils/slugify.ts
+ * @description Converts any URL or string to a safe HTML slug usable in IDs, hashes, filenames, etc.
+ */
+
+/**
+ * Converts a URL or path string into a clean slug suitable for use as an HTML ID or filename segment.
+ * - Handles relative and absolute URLs.
+ * - Removes common file extensions (.html, .htm, .php, etc.).
+ * - Removes URL fragments (#...).
+ * - Attempts to parse pathname and search parameters.
+ * - Replaces spaces, slashes, and other unsafe characters with hyphens.
+ * - Converts to lowercase.
+ * - Collapses and trims hyphens.
+ * - Returns 'index' for empty or invalid input.
+ *
+ * @param url - The raw URL or string to slugify.
+ * @returns A safe, lowercase slug string.
+ */
+export function slugify(url: string): string {
+    if (!url || typeof url !== 'string') return 'index';
+
+    let cleaned = url.trim();
+    let pathAndSearch = '';
+
+    try {
+        const urlObj = new URL(url, 'https://placeholder.base');
+        pathAndSearch = (urlObj.pathname ?? '') + (urlObj.search ?? '');
+    } catch {
+        pathAndSearch = cleaned.split('#')[0]; // Remove fragment
+    }
+
+    // Decode URI components AFTER parsing from URL to handle %20 etc.
+    try {
+        cleaned = decodeURIComponent(pathAndSearch);
+    } catch (e) {
+        cleaned = pathAndSearch; // Proceed if decoding fails
+    }
+
+    cleaned = cleaned
+        // Remove common web extensions FIRST
+        .replace(/\.(html?|php|aspx?|jsp)$/i, '')
+        // Replace path separators and common separators/spaces with a hyphen
+        .replace(/[\s/?=&\\]+/g, '-') // Target spaces, /, ?, =, &, \
+        // Remove any remaining characters that are not alphanumeric, hyphen, underscore, or period
+        .replace(/[^\w._-]+/g, '')    // Allow word chars, '.', '_', '-'
+        // Collapse consecutive hyphens
+        .replace(/-+/g, '-')
+        // Trim leading/trailing hyphens
+        .replace(/^-+|-+$/g, '')
+        // Convert to lowercase
+        .toLowerCase();
+
+    // Return 'index' if the process results in an empty string
+    return cleaned || 'index';
+}
+
+
+/**
+ * Converts a URL or path string into a clean slug suitable for use as an HTML ID.
+ * Note: This implementation might be very similar or identical to slugify depending on exact needs.
+ * This example uses the refined slugify logic. Consider consolidating if appropriate.
+ *
+ * @param rawUrl - The raw page URL or path.
+ * @returns A safe, lowercase slug string (e.g. "products-item-1", "search-q-test-page-2")
+ */
+export function sanitizeSlug(rawUrl: string): string {
+    // Re-use the improved slugify logic for consistency
+    return slugify(rawUrl);
+}

package/tests/__fixtures__/sample-project/index.html

@@ -0,0 +1,5 @@
+<!DOCTYPE html>
+      <html>
+        <head><title>Test</title></head>
+        <body><h1>Test Page</h1></body>
+      </html>