portapack 0.2.1

package/jest.setup.cjs

@@ -0,0 +1,211 @@
+/**
+ * @file jest.setup.cjs
+ * @description Jest global setup script executed before test suites run (per file).
+ * Responsible for creating temporary directories for test outputs and fixtures,
+ * setting up mock data (like the sample project), and cleaning up afterwards.
+ * Uses CommonJS syntax as Jest setup files often run in a CJS context.
+ */
+
+// Node.js core modules required for setup
+const fs = require('fs/promises'); // Using promises API for async operations
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+// Generate a unique ID for each test execution session.
+// This helps isolate test runs if running concurrently or prevents conflicts
+// if cleanup fails on a previous run.
+const TEST_RUN_ID = crypto.randomBytes(4).toString('hex');
+
+// Helper function for resolving paths relative to this setup file's directory
+// (usually the project root or a specific test config directory)
+const resolve = (...args) => path.resolve(__dirname, ...args);
+
+/**
+ * Utility function to ensure a directory exists.
+ * Creates the directory recursively if it doesn't exist.
+ * Ignores 'EEXIST' error if the directory is already present.
+ * @param {string} dir - The absolute path of the directory to ensure.
+ * @returns {Promise<void>}
+ * @throws {Error} Throws errors other than 'EEXIST' during directory creation.
+ */
+const ensureDir = async (dir) => {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+    } catch (e) {
+        // If the error is simply that the directory already exists, ignore it.
+        if (e.code !== 'EEXIST') {
+            console.error(`Failed to ensure directory ${dir}:`, e); // Log unexpected errors
+            throw e; // Re-throw other errors
+        }
+    }
+};
+
+// Define the base temporary directory using the OS's temp location and the unique run ID.
+// Using os.tmpdir() is generally safer regarding permissions and OS conventions.
+const tempDir = path.join(os.tmpdir(), 'portapack-tests', TEST_RUN_ID);
+
+/**
+ * Object containing base paths for various test-related directories.
+ * These are constructed relative to the main temporary directory.
+ */
+const baseDirs = {
+    root: resolve(), // Project root (where jest.config / setup file likely is)
+    output: path.join(tempDir, 'test-output'), // General output for test artifacts
+    fixtures: path.join(tempDir, '__fixtures__'), // Base for fixture data (if needed)
+    fixturesOutput: path.join(tempDir, '__fixtures__/output'), // Output specifically related to fixtures
+    sampleProject: path.join(tempDir, 'sample-project') // Directory for the mock HTML project
+};
+
+/**
+ * Jest's global beforeAll hook. Runs once before any tests in a suite file execute.
+ * Sets up the necessary directory structure and global variables/mocks for tests.
+ */
+beforeAll(async () => {
+    console.log(`Setting up test environment in: ${tempDir}`); // Log setup start
+
+    // Create essential output/fixture directories early.
+    // Using Promise.all here is likely safe as they are independent paths.
+    await Promise.all([
+        ensureDir(baseDirs.output),
+        ensureDir(baseDirs.fixturesOutput)
+    ]);
+
+    // Define paths specific to this test run using the TEST_RUN_ID for further isolation.
+    const runDirs = {
+        uniqueOutput: path.join(baseDirs.output, TEST_RUN_ID),
+        uniqueFixturesOutput: path.join(baseDirs.fixturesOutput, TEST_RUN_ID)
+    };
+
+    // Create the run-specific directories.
+    await Promise.all([
+        fs.mkdir(runDirs.uniqueOutput, { recursive: true }),
+        fs.mkdir(runDirs.uniqueFixturesOutput, { recursive: true })
+    ]);
+
+    // --- Set up global variables accessible within tests ---
+    // This provides a consistent way for tests to access temporary paths.
+    global.__TEST_DIRECTORIES__ = {
+        ...baseDirs,
+        ...runDirs
+    };
+
+    // Helper function for tests to get a path within the unique test output directory.
+    global.getTestFilePath = (relPath) =>
+        path.join(global.__TEST_DIRECTORIES__.uniqueOutput, relPath);
+
+    // Helper function for tests to get a path within the unique fixture output directory.
+    global.getTestFixturePath = (relPath) =>
+        path.join(global.__TEST_DIRECTORIES__.uniqueFixturesOutput, relPath);
+
+    // --- Create specific mock files needed by certain tests ---
+    // Example: Creating virtual font files for font processing tests.
+    await ensureDir(path.dirname(path.join(tempDir, 'font.woff2'))); // Ensure parent dir exists
+    await ensureDir(path.dirname(path.join(tempDir, 'font.ttf')));
+    // No need to ensureDir for 'missing.ttf' as we only need the path, not the file
+
+    // Write mock content to the font files.
+    await fs.writeFile(path.join(tempDir, 'font.woff2'), 'mock woff2 data');
+    await fs.writeFile(path.join(tempDir, 'font.ttf'), 'mock ttf data');
+
+    // Set up a global variable pointing to the temp directory for potential use in mocks.
+    global.__MOCK_FILE_PATH__ = tempDir;
+
+    // --- Create the stub/mock sample HTML project ---
+    // **FIX APPLIED HERE:** Ensure directory exists *before* writing files into it
+    // to prevent ENOENT race conditions.
+
+    console.log(`Ensuring sample project directory exists: ${baseDirs.sampleProject}`);
+    // 1. Ensure the sample project directory exists FIRST
+    await ensureDir(baseDirs.sampleProject);
+
+    // 2. THEN write all the files into it using Promise.all for concurrency (safe now).
+    try {
+        console.log(`Writing sample project files to ${baseDirs.sampleProject}...`);
+        await Promise.all([
+            fs.writeFile(
+                path.join(baseDirs.sampleProject, 'index.html'),
+                `<!DOCTYPE html><html><head><link rel="stylesheet" href="styles.css"></head><body><img src="logo.png"/><script src="script.js"></script></body></html>`
+            ),
+            fs.writeFile(path.join(baseDirs.sampleProject, 'styles.css'), 'body { margin: 0; }'),
+            fs.writeFile(path.join(baseDirs.sampleProject, 'script.js'), `console.log('hello');`),
+            fs.writeFile(path.join(baseDirs.sampleProject, 'logo.png'), 'fake image data') // Using string for simplicity
+        ]);
+        console.log(`Successfully wrote sample project files.`);
+    } catch (writeError) {
+        console.error(`Failed to write sample project files to ${baseDirs.sampleProject}:`, writeError);
+        // Depending on setup needs, you might want to stop the tests here.
+        throw writeError; // Re-throw to potentially fail the setup.
+    }
+    // --- End Fix ---
+
+    // --- Mock console methods ---
+    // This helps keep test output clean and allows assertions on console messages.
+    const originalLog = console.log;
+    const originalWarn = console.warn;
+    const originalError = console.error;
+
+    // Replace global console methods with Jest mocks.
+    global.console.log = jest.fn((...args) => {
+        // Only log to actual console if DEBUG environment variable is set.
+        if (process.env.DEBUG) {
+            originalLog(...args);
+        }
+    });
+
+    global.console.warn = jest.fn((...args) => {
+        // Optionally filter specific warnings you expect and don't want cluttering output.
+        const msg = args.join(' ');
+        if (
+            msg.includes('Could not fetch asset') ||
+            msg.includes('Error minifying')
+            // Add other expected warning patterns here if needed
+        ) {
+            return; // Suppress specific known warnings
+        }
+        // Log other warnings, potentially only in debug mode.
+        if (process.env.DEBUG) {
+            originalWarn(...args);
+        }
+    });
+
+    global.console.error = jest.fn((...args) => {
+        // Always show errors, especially in debug mode.
+        // Could add filtering if there are known, non-critical errors to ignore.
+        if (process.env.DEBUG) {
+            originalError(...args);
+        }
+        // Potentially log even without DEBUG for visibility during tests
+        // originalError(...args);
+    });
+
+    console.log("Test setup complete."); // Log setup finish
+});
+
+/**
+ * Jest's global afterAll hook. Runs once after all tests in a suite file have completed.
+ * Cleans up the temporary directory created for the test run.
+ */
+afterAll(async () => {
+    console.log(`Cleaning up test environment in: ${tempDir}`); // Log cleanup start
+    const dirs = global.__TEST_DIRECTORIES__; // Retrieve paths from global scope
+    if (!dirs) {
+        console.warn("Global test directories not found during cleanup.");
+        return;
+    }
+
+    try {
+        // Recursively remove the entire temporary directory for this test run.
+        // Using force: true helps ignore errors if files are missing (e.g., cleanup already ran partially).
+        await fs.rm(tempDir, { recursive: true, force: true });
+        console.log(`Successfully cleaned up test directory: ${tempDir}`);
+    } catch (e) {
+        // Log errors during cleanup but don't fail the tests typically.
+        // ENOENT means the directory was already gone, which is fine.
+        if (e.code !== 'ENOENT') {
+            console.warn(`Could not fully clean test directory ${tempDir}:`, e.message);
+        } else {
+            console.log(`Test directory already removed: ${tempDir}`);
+        }
+    }
+});

package/nodemon.json

@@ -0,0 +1,11 @@
+{
+    "watch": ["src"],
+    "ext": "ts,tsx",
+    "ignore": [
+      "src/**/*.spec.ts",
+      "src/**/*.test.ts",
+      "dist",
+      "node_modules"
+    ],
+    "exec": "npm run docs:api"
+  }

package/output.html

@@ -0,0 +1 @@
+<html>Warning</html>

package/package.json

@@ -0,0 +1,161 @@
+{
+  "name": "portapack",
+  "version": "0.2.1",
+  "description": "📦 A tool to bundle and minify HTML and all its dependencies into a single portable file.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "portapack": "./dist/cli/cli-entry.js"
+  },
+  "scripts": {
+    "dev": "concurrently --success=all -n BUILD,DOCS,TEST -c green,blue,magenta \"npm run dev:build\" \"npm run dev:docs\" \"npm run dev:test\"",
+    "dev:build": "tsup --watch",
+    "dev:docs": "concurrently \"npm run docs:api:watch\" \"npm run docs:dev\"",
+    "dev:test": "cross-env FORCE_COLOR=1 jest --watch --clearCache --passWithNoTests --watchPathIgnorePatterns=\"<rootDir>/tests/__fixtures__/output\"",
+    "dev:test:debug": "cross-env NODE_OPTIONS=--experimental-vm-modules FORCE_COLOR=1 jest --watch --runTestsByPath",
+    "build": "npm run build:code && npm run docs:api && npm run docs:build",
+    "build:code": "tsup",
+    "example": "npx tsx examples/main.ts",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "test:ci": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage --ci",
+    "test:clear": "jest --clearCache",
+    "coverage": "jest --coverage && open coverage/lcov-report/index.html",
+    "docs:coverage": "npm run test && mkdir -p docs/test-coverage && cp -r coverage/lcov-report/* docs/test-coverage/",
+    "prepare": "npm run build",
+    "publish:npm": "npm publish",
+    "lint": "eslint . --ext .ts,.js",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
+    "commit": "git-cz",
+    "semantic-release": "semantic-release",
+    "coveralls": "jest --coverage && coveralls < coverage/lcov.info",
+    "docs:dev": "vitepress dev docs",
+    "docs:api": "typedoc --options typedoc.json",
+    "docs:api:watch": "nodemon --watch src --ext ts,tsx --exec \"npm run docs:api\"",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:deploy": "npm run docs:api && vitepress build docs && gh-pages -d docs/.vitepress/dist",
+    "docs:serve": "npm run docs:api && vitepress build docs && vitepress serve docs"
+  },
+  "keywords": [
+    "html",
+    "bundler",
+    "portable",
+    "minify",
+    "packer",
+    "assets",
+    "cli",
+    "offline",
+    "webapp",
+    "static-site",
+    "bundle",
+    "recursive"
+  ],
+  "author": "Manic.agency",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manicinc/portapack.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manicinc/portapack/issues"
+  },
+  "homepage": "https://github.com/manicinc/portapack#readme",
+  "dependencies": {
+    "axios": "^1.8.4",
+    "chalk": "^5.4.1",
+    "cheerio": "^1.0.0",
+    "clean-css": "^5.3.3",
+    "commander": "^13.0.0",
+    "html-minifier-terser": "^7.2.0",
+    "puppeteer": "^24.6.0",
+    "terser": "^5.39.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/clean-css": "^4.2.11",
+    "@types/html-minifier-terser": "^7.0.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.14",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "commitizen": "^4.3.0",
+    "concurrently": "^9.1.2",
+    "coveralls": "^3.1.1",
+    "cross-env": "^7.0.3",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-jest": "^27.9.0",
+    "execa": "^9.5.2",
+    "gh-pages": "^6.3.0",
+    "glob": "^11.0.1",
+    "husky": "^9.0.0",
+    "jest": "^29.7.0",
+    "jest-environment-node": "^29.7.0",
+    "jest-watch-typeahead": "^2.2.2",
+    "lint-staged": "^15.2.0",
+    "nodemon": "^3.1.9",
+    "prettier": "^3.2.5",
+    "semantic-release": "^23.0.0",
+    "ts-jest": "^29.3.1",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.4.0",
+    "typedoc": "^0.28.1",
+    "typedoc-plugin-markdown": "^4.6.0",
+    "typescript": "^5.8.2",
+    "vitepress": "^1.6.3"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "lint-staged": {
+    "*.{ts,js}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release": {
+    "branches": [
+      "master"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}

package/site-packed.html

@@ -0,0 +1 @@
+<html>Generated Recursive Number</html>

package/src/cli/cli-entry.ts

@@ -0,0 +1,28 @@
+/**
+ * @file cli-entry.ts
+ * @description
+ * Node.js entry point for PortaPack CLI (compatible with ESM).
+ * 
+ * Supports:
+ * - Direct execution: `node cli-entry.js`
+ * - Programmatic import for testing: `import { startCLI } from './cli-entry'`
+ */
+
+import type { CLIResult } from '../types';
+
+/**
+ * Starts the CLI by importing and invoking the main CLI logic.
+ * 
+ * @returns {Promise<CLIResult>} - Exit code and any captured output
+ */
+const startCLI = async (): Promise<CLIResult> => {
+  const { main } = await import('./cli.js');
+  return await main(process.argv);
+};
+
+// If executed directly from the command line, run and exit.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  startCLI().then(({ exitCode }) => process.exit(Number(exitCode))); // Cast exitCode to Number
+}
+
+export { startCLI };

package/src/cli/cli.ts

@@ -0,0 +1,139 @@
+/**
+ * @file cli.ts
+ * @description
+ * Main CLI runner for PortaPack. Handles parsing CLI args, executing the HTML bundler,
+ * writing output to disk, logging metadata, and returning structured results.
+ */
+
+import fs from 'fs'; // Use default import if mocking default below
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { parseOptions } from './options.js';
+import { generatePortableHTML, generateRecursivePortableHTML } from '../index';
+import type { CLIResult } from '../types';
+
+import { LogLevel } from '../types';
+
+/**
+ * Dynamically loads package.json metadata.
+ */
+function getPackageJson(): Record<string, any> {
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const pkgPath = path.resolve(__dirname, '../../package.json');
+
+        // Use fs directly, assuming mock works or it's okay in non-test env
+        if (fs.existsSync(pkgPath)) {
+            return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        }
+    } catch (_) {
+        // Ignore and fallback
+    }
+    return { version: '0.1.0' }; // Default fallback version
+}
+
+/**
+ * Entry function for running the CLI.
+ */
+export async function runCli(argv: string[] = process.argv): Promise<CLIResult> {
+    let stdout = '';
+    let stderr = '';
+    let exitCode = 0;
+
+    // Capture console output for result object
+    const originalLog = console.log;
+    const originalErr = console.error;
+    const originalWarn = console.warn;
+    console.log = (...args) => { stdout += args.join(' ') + '\n'; };
+    console.error = (...args) => { stderr += args.join(' ') + '\n'; };
+    console.warn = (...args) => { stderr += args.join(' ') + '\n'; }; // Capture warnings in stderr too
+
+    let opts: ReturnType<typeof parseOptions> | undefined;
+    try {
+        opts = parseOptions(argv);
+        const version = getPackageJson().version || '0.1.0';
+
+        if (opts.verbose) {
+            console.log(`📦 PortaPack v${version}`);
+        }
+
+        if (!opts.input) {
+            console.error('❌ Missing input file or URL');
+            // Restore console before returning
+            console.log = originalLog; console.error = originalErr; console.warn = originalWarn;
+            return { stdout, stderr, exitCode: 1 };
+        }
+
+        // Determine output path using nullish coalescing
+        const outputPath = opts.output ?? `${path.basename(opts.input).split('.')[0] || 'output'}.packed.html`;
+
+        if (opts.verbose) {
+            console.log(`📥 Input: ${opts.input}`);
+            console.log(`📤 Output: ${outputPath}`);
+            // Log other effective options if verbose
+            console.log(`   Recursive: ${opts.recursive ?? false}`);
+            console.log(`   Embed Assets: ${opts.embedAssets}`);
+            console.log(`   Minify HTML: ${opts.minifyHtml}`);
+            console.log(`   Minify CSS: ${opts.minifyCss}`);
+            console.log(`   Minify JS: ${opts.minifyJs}`);
+            console.log(`   Log Level: ${LogLevel[opts.logLevel ?? LogLevel.INFO]}`);
+        }
+
+        if (opts.dryRun) {
+            console.log('💡 Dry run mode — no output will be written');
+            // Restore console before returning
+            console.log = originalLog; console.error = originalErr; console.warn = originalWarn;
+            return { stdout, stderr, exitCode: 0 };
+        }
+
+        // --- FIX: Pass 'opts' object to generate functions ---
+        const result = opts.recursive
+            // Convert boolean recursive flag to depth 1 if needed, otherwise use number
+            ? await generateRecursivePortableHTML(opts.input, typeof opts.recursive === 'boolean' ? 1 : opts.recursive, opts)
+            : await generatePortableHTML(opts.input, opts);
+        // ----------------------------------------------------
+
+        // Use fs directly - ensure mock is working in tests
+        fs.writeFileSync(outputPath, result.html, 'utf-8');
+
+        const meta = result.metadata;
+        console.log(`✅ Packed: ${meta.input} → ${outputPath}`);
+        console.log(`📦 Size: ${(meta.outputSize / 1024).toFixed(2)} KB`);
+        console.log(`⏱️ Time: ${meta.buildTimeMs} ms`); // Use alternative emoji
+        console.log(`🖼️ Assets: ${meta.assetCount}`); // Add asset count log
+
+        if (meta.pagesBundled && meta.pagesBundled > 0) { // Check > 0 for clarity
+            console.log(`🧩 Pages: ${meta.pagesBundled}`);
+        }
+
+        if (meta.errors && meta.errors.length > 0) {
+            console.warn(`\n⚠️  ${meta.errors.length} warning(s):`); // Add newline for separation
+            for (const err of meta.errors) {
+                console.warn(`  - ${err}`);
+            }
+        }
+    } catch (err: any) {
+        console.error(`\n💥 Error: ${err?.message || 'Unknown failure'}`); // Add newline
+        if (err?.stack && opts?.verbose) { // Show stack only if verbose
+            console.error(err.stack);
+        }
+        exitCode = 1;
+    } finally {
+        // Restore original console methods
+        console.log = originalLog;
+        console.error = originalErr;
+        console.warn = originalWarn;
+    }
+
+    return { stdout, stderr, exitCode };
+}
+
+// Optional: Define main export if this file is intended to be run directly
+export const main = runCli;
+
+// Example direct execution (usually handled by bin entry in package.json)
+// if (require.main === module) {
+//     runCli();
+// }