portapack 0.3.0 → 0.3.2

package/docs/configuration.md

@@ -1,151 +1,137 @@
-# 🛠 PortaPack Configuration Guide
+# 🚀 Getting Started with PortaPack
 
-## 📝 Configuration Options
+## Prerequisites
 
-PortaPack provides multiple ways to configure its behavior:
+- Node.js (v16.0.0+)
+- npm (v8.0.0+)
 
-### CLI Configuration
+## Quick Installation
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `-i, --input` | String | Required | Input HTML file or URL |
-| `-o, --output` | String | `{input}.packed.html` | Output file path |
-| `-m, --minify` | Number | `2` | Minification level (0-3) |
-| `--no-minify` | Flag | - | Disable minification |
-| `-r, --recursive` | Boolean/Number | `false` | Crawl site recursively, optionally with depth |
-| `-b, --base-url` | String | Detected | Base URL for resolving paths |
-| `-d, --dry-run` | Flag | `false` | Preview without generating output |
-| `-v, --verbose` | Flag | `false` | Enable verbose logging |
-
-### Programmatic Configuration
-
-```typescript
-// Simple string input
-await generatePortableHTML('./index.html');
-
-// With options as second parameter
-await generatePortableHTML('./index.html', {
-  minify: true,
-  minifyLevel: 2,
-  baseUrl: 'https://example.com'
-});
+```bash
+# Global installation
+npm install -g portapack
 
-// Or with options object
-await generatePortableHTML({
-  input: './index.html',
-  minify: true,
-  minifyLevel: 2,
-  baseUrl: 'https://example.com',
-  
-  // Asset handling
-  embedAssets: true,
-  embedLimit: 1000000,
-  
-  // Minification controls
-  minifyHtml: true,
-  minifyCss: true,
-  minifyJs: true,
-  
-  // Advanced options
-  removeComments: true,
-  collapseWhitespace: true
-});
+# Or as a project dependency
+npm install --save-dev portapack
 ```
 
-## 🔧 Configuration Examples
+## Basic Usage
 
-### CLI Configuration
+### CLI Quickstart
 
 ```bash
-# Basic usage
-portapack -i ./index.html -o bundled.html
-
-# Maximum minification
-portapack -i ./site -m 3 -o min.html
+# Bundle a local HTML file
+portapack ./index.html -o portable.html
 
-# Disable minification
-portapack -i ./site --no-minify
-
-# Set custom base URL
-portapack -i ./local/site -b https://example.com
+# Bundle a remote website
+portapack https://example.com --recursive -o site.html
+```
 
-# Recursive crawling with depth
-portapack -i https://site.com -r 2
+### Node.js API Basic Example
 
-# Dry run to preview
-portapack -i https://example.com --dry-run -v
+```typescript
+import { pack } from 'portapack';
+
+// Simple usage with a string path
+async function bundleLocalSite() {
+  const result = await pack('./index.html');
+  console.log(result.html);
+
+  // Access metadata about the build
+  console.log(`Output size: ${result.metadata.outputSize} bytes`);
+  console.log(`Build time: ${result.metadata.buildTimeMs} ms`);
+}
+
+// Advanced options using configuration object
+async function bundleWithOptions() {
+  const result = await pack('./index.html', {
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true,
+    baseUrl: 'https://example.com',
+    embedAssets: true,
+  });
+
+  // Use or save the bundled HTML
+  console.log(result.html);
+}
+
+// Recursive bundling of a website
+async function bundleWebsite() {
+  const result = await pack('https://example.com', {
+    recursive: 2, // Crawl up to 2 levels deep
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true,
+  });
+
+  console.log(`Bundled ${result.metadata.pagesBundled} pages`);
+}
 ```
 
-### Programmatic Configuration
+### Advanced API Usage
+
+For more specific use cases, you can access individual components:
 
 ```typescript
-// Basic local file
-const html = await generatePortableHTML('index.html');
-
-// Remote URL with minification options
-const html = await generatePortableHTML({
-  input: 'https://example.com',
-  minify: true,
-  minifyLevel: 3,
-  removeComments: true
+import {
+  generatePortableHTML,
+  generateRecursivePortableHTML,
+  bundleMultiPageHTML,
+  fetchAndPackWebPage,
+} from 'portapack';
+
+// Bundle a single HTML file or URL
+const singleResult = await generatePortableHTML('./index.html', {
+  minifyHtml: true,
 });
 
-// With custom base URL
-const html = await generatePortableHTML({
-  input: './index.html',
-  baseUrl: 'https://example.com',
-  embedAssets: true
+// Recursively bundle a site
+const recursiveResult = await generateRecursivePortableHTML('https://example.com', 2, {
+  minifyCss: true,
 });
 
-// Recursive site bundling
-await bundleSiteRecursively(
-  'https://example.com',
-  'output.html',
-  2 // Depth
-);
+// Create multi-page bundle
+const multiPageBundle = await bundleMultiPageHTML([
+  { path: '/', html: '<html>...</html>' },
+  { path: '/about', html: '<html>...</html>' },
+]);
 ```
 
-## 💡 Best Practices
+## Configuration
+
+See our full [Configuration Guide](https://manicinc.github.io/portapack/configuration) for detailed options.
+
+## CLI Options
+
+PortaPack offers many command-line options for customizing the bundling process:
+
+```bash
+# Get full help
+portapack --help
+```
 
-- **Base URL Handling**: Always specify a `baseUrl` when working with relative paths
-- **Asset Size**: Be mindful of embedding large assets; use `embedLimit` to set thresholds
-- **Minification Levels**: Start with level 2 and adjust based on needs:
-  - Level 0: No minification
-  - Level 1: Basic whitespace removal
-  - Level 2: Standard minification (recommended)
-  - Level 3: Aggressive minification (may affect readability)
-- **Testing**: Use `--dry-run -v` to preview configuration without generating files
-- **Performance**: For large sites, increase Node's memory limit with `NODE_OPTIONS=--max-old-space-size=4096`
+For details, see the [CLI Reference](https://manicinc.github.io/portapack/cli).
 
-## 🚨 Configuration Warnings
+## Next Steps
 
-- Deep recursive crawling can be resource-intensive
-- Large sites may require increased memory allocation
-- Some asset embedding might fail with complex dynamic sites
-- External scripts with CORS restrictions may not embed properly
+- 📖 [Explore CLI Options](https://manicinc.github.io/portapack/cli)
+- 🛠 [Advanced Configuration](https://manicinc.github.io/portapack/configuration)
+- 💻 [API Reference](https://manicinc.github.io/portapack/api/README.html)
 
-## 📂 File Types Supported
+## Troubleshooting
 
-PortaPack automatically detects and processes:
+Encountering issues? Check our [Troubleshooting Guide](https://manicinc.github.io/portapack/troubleshooting)
 
-- **HTML files**: Main content files
-- **CSS stylesheets**: Both inline and external
-- **JavaScript**: Script files and inline scripts
-- **Images**: PNG, JPEG, GIF, SVG, WebP (converted to data URLs)
-- **Fonts**: WOFF, WOFF2, TTF, EOT (embedded)
-- **Other assets**: PDFs, JSON, text files, etc.
+## Contributing
 
-## 🔄 Environment Variables
+Interested in improving PortaPack?
 
-PortaPack also supports configuration via environment variables:
+- [View Contributing Guidelines](https://manicinc.github.io/portapack/contributing)
 
-- `PORTAPACK_BASE_URL`: Sets the base URL
-- `PORTAPACK_MINIFY_LEVEL`: Sets minification level
-- `PORTAPACK_NO_EMBED`: Disables asset embedding when set to "true"
+## Support
 
-## 📚 Related Documentation
+- 🐛 [Report an Issue](https://github.com/manicinc/portapack/issues)
+- 💬 [Community Support](https://discord.gg/DzNgXdYm)
 
-- [CLI Reference](/cli)
-- [API Reference](/api/README)
-- [Getting Started Guide](/getting-started)
-- [Troubleshooting](/troubleshooting)
+Built by [Manic.agency](https://manic.agency)

package/docs/contributing.md

@@ -17,10 +17,12 @@ Refer to our detailed [Development Guide](./development.md) for comprehensive se
 ### 🧪 Development Workflow
 
 1. **Fork the Repository**
+
    - Navigate to [PortaPack GitHub Repository](https://github.com/manicinc/portapack)
-   - Click "Fork" 
+   - Click "Fork"
 
 2. **Clone Your Fork**
+
    ```bash
    git clone https://github.com/YOUR_USERNAME/portapack.git
    cd portapack
@@ -38,6 +40,7 @@ Refer to our detailed [Development Guide](./development.md) for comprehensive se
 We use [Conventional Commits](https://www.conventionalcommits.org/) for structured commit messages.
 
 #### Commit Types
+
 - `feat`: New features
 - `fix`: Bug fixes
 - `docs`: Documentation changes
@@ -47,6 +50,7 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) for structur
 - `chore`: Maintenance tasks
 
 #### Commit Command
+
 ```bash
 npm run commit
 ```
@@ -104,4 +108,4 @@ Please review our [Code of Conduct](./code-of-conduct.md) before contributing.
 
 Open source thrives on community contributions. Your effort helps improve PortaPack for everyone! 🎉
 
-**Happy Coding!** 💻✨
+**Happy Coding!** 💻✨

package/docs/deployment.md

@@ -16,10 +16,10 @@ When changes are pushed to master, semantic-release will:
 
 ### Release Types
 
-| Commit Format | Result |
-|--------------|--------|
-| `fix:` | 🔧 PATCH release |
-| `feat:` | ✨ MINOR release |
+| Commit Format                | Result           |
+| ---------------------------- | ---------------- |
+| `fix:`                       | 🔧 PATCH release |
+| `feat:`                      | ✨ MINOR release |
 | `feat:` + `BREAKING CHANGE:` | 🚨 MAJOR release |
 
 ## 📦 Manual Release (Optional Fallback)
@@ -45,6 +45,7 @@ In your GitHub repository:
 2. Add the following secrets:
 
 - `NPM_TOKEN`
+
   - Create at npmjs.com > Access Tokens
   - Choose type: `Automation` (read + publish)
   - Paste into GitHub as `NPM_TOKEN`
@@ -61,6 +62,7 @@ In your GitHub repository:
 ## 🧪 Test Coverage
 
 ### Tools Used
+
 - Jest
 - Coveralls
 
@@ -102,17 +104,20 @@ The project automatically generates a test coverage report and makes it accessib
 ## 🧼 Pre-commit Hooks
 
 We use Husky + `lint-staged`:
+
 - ✅ Auto-lint + format on commit
 - ✅ Validate commit messages via Commitizen
 
 ## 🧯 Troubleshooting
 
 ### Commit Fails?
+
 - Use `npm run commit` (or `git cz`) to follow the correct format
 - Check Husky is installed (`.husky/` exists)
 - Run `npm install` again to restore hooks
 
 ### Release Fails?
+
 - Check GitHub Actions logs
 - Ensure `NPM_TOKEN` secret is added
 - Ensure commit messages follow Conventional Commits
@@ -129,4 +134,4 @@ npm run commit
 feat(fonts): add base64 embedding with MIME detection
 fix(extractor): fallback on missing asset
 chore(ci): enable docs deploy with GitHub Pages
-```
+```

package/docs/development.md

@@ -16,6 +16,7 @@ npm install -g commitizen
 ## 🚀 Getting Started
 
 1. Clone the repository:
+
    ```bash
    git clone https://github.com/manicinc/portapack.git
    cd portapack
@@ -38,17 +39,18 @@ npm run dev
 ```
 
 This command simultaneously runs:
+
 - TypeScript rebuild watcher
 - Documentation server
 - Test runner
 
 ### Specific Development Scripts
 
-| Command | Purpose |
-|---------|---------|
+| Command             | Purpose                      |
+| ------------------- | ---------------------------- |
 | `npm run dev:build` | Watch and rebuild TypeScript |
-| `npm run dev:docs` | Start documentation server |
-| `npm run dev:test` | Run tests in watch mode |
+| `npm run dev:docs`  | Start documentation server   |
+| `npm run dev:test`  | Run tests in watch mode      |
 
 ## 🧪 Testing Strategies
 
@@ -89,6 +91,7 @@ npm run build
 ```
 
 Builds include:
+
 - TypeScript compilation
 - API documentation generation
 - Documentation site build
@@ -165,4 +168,4 @@ portapack/
 
 ## 📄 License
 
-MIT License - Built by Manic Agency
+MIT License - Built by Manic Agency

package/docs/getting-started.md

@@ -15,92 +15,123 @@ npm install -g portapack
 npm install --save-dev portapack
 ```
 
-## Documentation
-
-Our documentation is automatically generated and hosted locally:
-
-- 🌐 **Local Docs**: at `http://localhost:5173`
-- 📦 **Auto-Generated API Docs**: Dynamically created from TypeDoc comments
-- 🧩 **Sidebar Generation**: Intelligent, automated sidebar creation
-
-### Running Documentation Locally
-
-```bash
-# Start documentation development server
-npm run docs:dev
-```
-
 ## Basic Usage
 
 ### CLI Quickstart
 
 ```bash
 # Bundle a local HTML file
-portapack -i ./index.html -o portable.html
+portapack ./index.html -o portable.html
 
 # Bundle a remote website
-portapack -i https://example.com --recursive -o site.html
+portapack https://example.com --recursive -o site.html
 ```
 
 ### Node.js API Basic Example
 
 ```typescript
-import { generatePortableHTML } from 'portapack';
+import { pack } from 'portapack';
 
 // Simple usage with a string path
 async function bundleLocalSite() {
-  const portableHtml = await generatePortableHTML('./index.html');
-  console.log(portableHtml);
+  const result = await pack('./index.html');
+  console.log(result.html);
+
+  // Access metadata about the build
+  console.log(`Output size: ${result.metadata.outputSize} bytes`);
+  console.log(`Build time: ${result.metadata.buildTimeMs} ms`);
 }
 
 // Advanced options using configuration object
 async function bundleWithOptions() {
-  const portableHtml = await generatePortableHTML({
-    input: './index.html',
-    minify: true,
-    minifyLevel: 2,
-    baseUrl: 'https://example.com'
+  const result = await pack('./index.html', {
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true,
+    baseUrl: 'https://example.com',
+    embedAssets: true,
   });
-  
+
   // Use or save the bundled HTML
-  console.log(portableHtml);
+  console.log(result.html);
+}
+
+// Recursive bundling of a website
+async function bundleWebsite() {
+  const result = await pack('https://example.com', {
+    recursive: 2, // Crawl up to 2 levels deep
+    minifyHtml: true,
+    minifyCss: true,
+    minifyJs: true,
+  });
+
+  console.log(`Bundled ${result.metadata.pagesBundled} pages`);
 }
 ```
 
-## Documentation Architecture
+### Advanced API Usage
+
+For more specific use cases, you can access individual components:
+
+```typescript
+import {
+  generatePortableHTML,
+  generateRecursivePortableHTML,
+  bundleMultiPageHTML,
+  fetchAndPackWebPage,
+} from 'portapack';
+
+// Bundle a single HTML file or URL
+const singleResult = await generatePortableHTML('./index.html', {
+  minifyHtml: true,
+});
+
+// Recursively bundle a site
+const recursiveResult = await generateRecursivePortableHTML('https://example.com', 2, {
+  minifyCss: true,
+});
+
+// Create multi-page bundle
+const multiPageBundle = await bundleMultiPageHTML([
+  { path: '/', html: '<html>...</html>' },
+  { path: '/about', html: '<html>...</html>' },
+]);
+```
 
-### Automatic Documentation Generation
+## Configuration
 
-PortaPack uses a custom sidebar generator (`buildDocsSidebar()`) to:
-- Automatically scan TypeDoc-generated markdown files
-- Create dynamic, organized documentation sidebars
-- Support multiple documentation types (modules, classes, interfaces, etc.)
+See our full [Configuration Guide](https://manicinc.github.io/portapack/configuration) for detailed options.
 
-#### How It Works
+## CLI Options
 
-1. TypeDoc generates markdown from source code comments
-2. Custom sidebar generator reads generated files
-3. VitePress renders dynamically generated sidebar
+PortaPack offers many command-line options for customizing the bundling process:
+
+```bash
+# Get full help
+portapack --help
+```
+
+For details, see the [CLI Reference](https://manicinc.github.io/portapack/cli).
 
 ## Next Steps
 
-- 📖 [Explore CLI Options](/cli)
-- 🛠 [Advanced Configuration](/configuration)
-- 💻 [API Reference](/api/README)
+- 📖 [Explore CLI Options](https://manicinc.github.io/portapack/cli)
+- 🛠 [Advanced Configuration](https://manicinc.github.io/portapack/configuration)
+- 💻 [API Reference](https://manicinc.github.io/portapack/api/README.html)
 
 ## Troubleshooting
 
-Encountering issues? Check our [Troubleshooting Guide](/troubleshooting)
+Encountering issues? Check our [Troubleshooting Guide](https://manicinc.github.io/portapack/troubleshooting)
 
 ## Contributing
 
-Interested in improving PortaPack? 
-- [View Contributing Guidelines](/contributing)
-- [Development Guide](/development)
+Interested in improving PortaPack?
+
+- [View Contributing Guidelines](https://manicinc.github.io/portapack/contributing)
 
 ## Support
 
 - 🐛 [Report an Issue](https://github.com/manicinc/portapack/issues)
 - 💬 [Community Support](https://discord.gg/DzNgXdYm)
 
-Built by [Manic.agency](https://manic.agency)
+Built by [Manic.agency](https://manic.agency)

package/docs/index.md

@@ -37,4 +37,4 @@ features:
     details: MIT licensed, tested, documented, and easy to contribute to.
 
 footer: Built by [Manic.agency](https://manic.agency) — Open Source & Empowering Designers and Developers
----
+---

package/docs/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

package/docs/troubleshooting.md

@@ -5,8 +5,10 @@
 ### 1. Installation Problems
 
 #### npm Install Fails
+
 - **Symptom**: Error during `npm install`
 - **Solutions**:
+
   ```bash
   # Clear npm cache
   npm cache clean --force
@@ -19,8 +21,10 @@
 ### 2. CLI Errors
 
 #### Permission Denied
+
 - **Symptom**: `EACCES` errors
 - **Solutions**:
+
   ```bash
   # Use npm with sudo (not recommended long-term)
   sudo npm install -g portapack
@@ -31,6 +35,7 @@
   ```
 
 #### Asset Embedding Failures
+
 - **Symptom**: Some assets not embedded
 - **Possible Causes**:
   - Incorrect base URL
@@ -40,6 +45,7 @@
 ### 3. Performance Issues
 
 #### Slow Recursive Crawling
+
 - **Solution**: Limit crawl depth
   ```bash
   portapack -i https://site.com --recursive --max-depth 2
@@ -48,6 +54,7 @@
 ### 4. Minification Problems
 
 #### CSS/JS Not Minifying
+
 - **Check**:
   - Use `--no-minify-css` or `--no-minify-js` flags
   - Verify asset paths
@@ -56,12 +63,14 @@
 ## 🔍 Debugging Techniques
 
 ### Verbose Logging
+
 ```bash
 # Enable verbose output
 portapack -i ./site --verbose
 ```
 
 ### Dry Run
+
 ```bash
 # Preview bundling without generating file
 portapack -i ./site --dry-run
@@ -70,6 +79,7 @@ portapack -i ./site --dry-run
 ## 🌐 Network & Security
 
 ### Proxy Configuration
+
 ```bash
 # Set proxy for asset fetching
 export HTTP_PROXY=http://proxy.example.com
@@ -79,6 +89,7 @@ portapack -i https://site.com
 ## 📊 Diagnostics
 
 ### Generate Diagnostic Report
+
 ```bash
 # Create debug information
 portapack --diagnostics > portapack-debug.log
@@ -104,4 +115,4 @@ portapack --diagnostics > portapack-debug.log
 
 - Limited support for complex Single Page Applications (SPAs)
 - Some dynamic content may not embed correctly
-- Large sites might require significant memory
+- Large sites might require significant memory