portapack 0.2.1

package/docs/cli.md

@@ -0,0 +1,117 @@
+# ⚙️ CLI Reference
+
+PortaPack provides a powerful command-line interface for bundling HTML files and websites.
+
+## Installation
+
+To use the CLI, install PortaPack globally:
+
+```bash
+npm install -g portapack
+```
+
+## Command Syntax
+
+The basic command structure is:
+
+```bash
+portapack [options]
+```
+
+## Options
+
+| Option | Shorthand | Description | Default |
+|--------|----------|------------|---------|
+| `--input <path>` | `-i` | Input file or URL to process | - |
+| `--output <file>` | `-o` | Output file path | `{input}.packed.html` |
+| `--minify [level]` | `-m` | Minification level (0-3) | `2` |
+| `--no-minify` | - | Disable minification | - |
+| `--recursive [depth]` | `-r` | Recursively bundle links up to specified depth | - |
+| `--base-url <url>` | `-b` | Base URL for resolving relative URLs | - |
+| `--dry-run` | `-d` | Show what would be done without writing files | - |
+| `--verbose` | `-v` | Enable verbose logging | - |
+| `--help` | `-h` | Show help information | - |
+| `--version` | - | Show version information | - |
+
+## Examples
+
+### Basic Usage
+
+Bundle a local HTML file:
+
+```bash
+portapack -i ./index.html -o bundle.html
+```
+
+### Web Page Bundling
+
+Bundle a remote website:
+
+```bash
+portapack -i https://example.com -o example-bundle.html
+```
+
+### Recursive Bundling
+
+Bundle a website and follow its links to a depth of 2:
+
+```bash
+portapack -i https://example.com -r 2 -o site-bundle.html
+```
+
+### Minification Control
+
+Apply maximum minification:
+
+```bash
+portapack -i ./index.html -m 3 -o min-bundle.html
+```
+
+Disable minification:
+
+```bash
+portapack -i ./index.html --no-minify -o unmin-bundle.html
+```
+
+### Base URL for Relative Links
+
+Specify a base URL for resolving relative paths:
+
+```bash
+portapack -i ./index.html -b https://example.com -o bundle.html
+```
+
+### Dry Run
+
+Preview what would be bundled without creating an output file:
+
+```bash
+portapack -i ./index.html --dry-run
+```
+
+### Verbose Logging
+
+Enable detailed logs during bundling:
+
+```bash
+portapack -i ./index.html -v -o bundle.html
+```
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| `0` | Success |
+| `1` | Error (missing input, invalid URL, processing error, etc.) |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NODE_ENV` | Set to `test` during testing to suppress console output |
+
+## Related Resources
+
+- [Getting Started](/getting-started)
+- [API Reference](/api/README)
+- [Configuration Guide](/configuration)

package/docs/code-of-conduct.md

@@ -0,0 +1,65 @@
+# 🤝 Code of Conduct
+
+## Our Pledge
+
+We are committed to providing a friendly, safe, and welcoming environment for all contributors, regardless of:
+- Age
+- Body size
+- Disability
+- Ethnicity
+- Gender identity and expression
+- Level of experience
+- Nationality
+- Personal appearance
+- Race
+- Religion
+- Sexual identity and orientation
+
+## Our Standards
+
+### Positive Behavior
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+### Unacceptable Behavior
+- Trolling, insulting/derogatory comments
+- Public or private harassment
+- Publishing others' private information
+- Other conduct reasonably considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for:
+- Clarifying acceptable behavior standards
+- Providing fair and consistent feedback
+- Removing, editing, or rejecting contributions that violate this Code of Conduct
+
+## Reporting Issues
+
+If you experience or witness unacceptable behavior:
+1. Email [conduct@manicinc.com](mailto:conduct@manicinc.com)
+2. Provide:
+   - Your contact information
+   - Names of involved parties
+   - Description of the incident
+   - Any additional context
+
+## Consequences
+
+Violations may result in:
+- Temporary or permanent ban from community spaces
+- Removal of contributions
+- Public or private warnings
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1.
+
+[homepage]: https://www.contributor-covenant.org
+
+## License
+
+This Code of Conduct is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).

package/docs/configuration.md

@@ -0,0 +1,151 @@
+# 🛠 PortaPack Configuration Guide
+
+## 📝 Configuration Options
+
+PortaPack provides multiple ways to configure its behavior:
+
+### CLI Configuration
+
+| 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'
+});
+
+// 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
+});
+```
+
+## 🔧 Configuration Examples
+
+### CLI Configuration
+
+```bash
+# Basic usage
+portapack -i ./index.html -o bundled.html
+
+# Maximum minification
+portapack -i ./site -m 3 -o min.html
+
+# Disable minification
+portapack -i ./site --no-minify
+
+# Set custom base URL
+portapack -i ./local/site -b https://example.com
+
+# Recursive crawling with depth
+portapack -i https://site.com -r 2
+
+# Dry run to preview
+portapack -i https://example.com --dry-run -v
+```
+
+### Programmatic Configuration
+
+```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
+});
+
+// With custom base URL
+const html = await generatePortableHTML({
+  input: './index.html',
+  baseUrl: 'https://example.com',
+  embedAssets: true
+});
+
+// Recursive site bundling
+await bundleSiteRecursively(
+  'https://example.com',
+  'output.html',
+  2 // Depth
+);
+```
+
+## 💡 Best Practices
+
+- **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`
+
+## 🚨 Configuration Warnings
+
+- 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
+
+## 📂 File Types Supported
+
+PortaPack automatically detects and processes:
+
+- **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.
+
+## 🔄 Environment Variables
+
+PortaPack also supports configuration via environment variables:
+
+- `PORTAPACK_BASE_URL`: Sets the base URL
+- `PORTAPACK_MINIFY_LEVEL`: Sets minification level
+- `PORTAPACK_NO_EMBED`: Disables asset embedding when set to "true"
+
+## 📚 Related Documentation
+
+- [CLI Reference](/cli)
+- [API Reference](/api/README)
+- [Getting Started Guide](/getting-started)
+- [Troubleshooting](/troubleshooting)

package/docs/contributing.md

@@ -0,0 +1,107 @@
+# 🤝 Contributing to PortaPack
+
+## 🌟 Ways to Contribute
+
+1. **Code Improvements**
+2. **Bug Fixes**
+3. **Documentation Enhancements**
+4. **Feature Development**
+5. **Testing and Quality Assurance**
+
+## 📋 Contribution Guidelines
+
+### 🛠 Setup
+
+Refer to our detailed [Development Guide](./development.md) for comprehensive setup instructions.
+
+### 🧪 Development Workflow
+
+1. **Fork the Repository**
+   - Navigate to [PortaPack GitHub Repository](https://github.com/manicinc/portapack)
+   - Click "Fork" 
+
+2. **Clone Your Fork**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/portapack.git
+   cd portapack
+   ```
+
+3. **Create a Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b bugfix/issue-description
+   ```
+
+### 📝 Commit Guidelines
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) for structured commit messages.
+
+#### Commit Types
+- `feat`: New features
+- `fix`: Bug fixes
+- `docs`: Documentation changes
+- `style`: Code formatting
+- `refactor`: Code restructuring
+- `test`: Test-related changes
+- `chore`: Maintenance tasks
+
+#### Commit Command
+```bash
+npm run commit
+```
+
+### 🧪 Before Submitting a Pull Request
+
+```bash
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+### 📤 Pull Request Process
+
+1. Ensure all tests pass
+2. Update documentation if needed
+3. Add description of changes
+4. Link any related issues
+
+## 🏆 Contributor Recognition
+
+- Contributors are listed in `CONTRIBUTORS.md`
+- Significant contributions may be highlighted in release notes
+
+## 📋 Code of Conduct
+
+Please review our [Code of Conduct](./code-of-conduct.md) before contributing.
+
+## 🚨 Reporting Issues
+
+- Use GitHub Issues
+- Provide detailed description
+- Include reproduction steps
+- Share relevant code snippets or error logs
+
+## 🛡️ Security Vulnerabilities
+
+- Do NOT open public issues for security vulnerabilities
+- Email security details to security@portapack.dev
+- Include reproduction steps
+- Allow time for responsible disclosure
+
+## 💬 Community
+
+- Join our [Discord Community](#)
+- Follow us on [Twitter](#)
+- Use GitHub Discussions for ideas and questions
+
+## 🙌 Thank You!
+
+Open source thrives on community contributions. Your effort helps improve PortaPack for everyone! 🎉
+
+**Happy Coding!** 💻✨

package/docs/demo.md

@@ -0,0 +1,46 @@
+---
+# 🌐 Live Demo
+
+## What You’ll See
+
+- A fully portable HTML site
+- Every internal page inlined
+- No external requests
+
+---
+
+## Example Output
+
+> Download this page and open it offline. It works!
+
+<!-- [Download Demo Portable HTML](./bootstrap-packed.html) -->
+
+---
+
+## How It Was Generated
+
+```bash
+portapack -i https://getbootstrap.com --recursive --max-depth 1 -o bootstrap-packed.html
+```
+
+---
+
+## Client-Side Navigation
+
+Recursively packed pages are wrapped in `<template>` blocks with an embedded router.
+
+```html
+<template id="page-home">
+  <h1>Homepage</h1>
+</template>
+<template id="page-about">
+  <h1>About</h1>
+</template>
+```
+
+```js
+window.addEventListener('hashchange', () => {
+  const id = location.hash.replace('#', '') || 'home';
+  showPage(id);
+});
+```

package/docs/deployment.md

@@ -0,0 +1,132 @@
+# 🚀 Deployment Guide
+
+## 🔁 Release Process
+
+This project uses [`semantic-release`](https://github.com/semantic-release/semantic-release) to automate versioning and publishing to npm.
+
+### Automatic Publishing
+
+When changes are pushed to master, semantic-release will:
+
+1. Analyze your commit messages (using [Conventional Commits](https://www.conventionalcommits.org/))
+2. Automatically bump the version (`patch`, `minor`, `major`)
+3. Generate or update `CHANGELOG.md`
+4. Create a GitHub release
+5. Publish the package to npm
+
+### Release Types
+
+| Commit Format | Result |
+|--------------|--------|
+| `fix:` | 🔧 PATCH release |
+| `feat:` | ✨ MINOR release |
+| `feat:` + `BREAKING CHANGE:` | 🚨 MAJOR release |
+
+## 📦 Manual Release (Optional Fallback)
+
+```bash
+# Build the project
+npm run build
+
+# Run tests and check coverage
+npm test
+
+# Publish to npm manually
+npm run publish:npm
+```
+
+## 🔐 GitHub Actions + NPM Setup
+
+### Required Secrets
+
+In your GitHub repository:
+
+1. Go to **Settings > Secrets and variables > Actions**
+2. Add the following secrets:
+
+- `NPM_TOKEN`
+  - Create at npmjs.com > Access Tokens
+  - Choose type: `Automation` (read + publish)
+  - Paste into GitHub as `NPM_TOKEN`
+
+- `GITHUB_TOKEN`
+  - This is automatically available in GitHub Actions
+
+### GitHub Repo Settings
+
+1. Go to **Settings > Actions > General**
+2. Under **Workflow Permissions**:
+   - ✅ Enable: **Read and write permissions**
+
+## 🧪 Test Coverage
+
+### Tools Used
+- Jest
+- Coveralls
+
+### CLI Usage
+
+```bash
+# Run all tests with coverage
+npm test
+
+# View interactive HTML coverage report
+npm run coverage
+# (opens coverage/lcov-report/index.html)
+
+# Generate and copy coverage report to docs
+npm run docs:coverage
+```
+
+### Coverage Badge Setup (Optional)
+
+1. Go to https://coveralls.io/
+2. Log in with GitHub
+3. Enable your repo
+4. Your GitHub Actions workflow (CI) will push coverage data automatically
+
+Add badge to README:
+
+```markdown
+[![Coverage Status](https://coveralls.io/repos/github/YOUR_USERNAME/portapack/badge.svg?branch=master)](https://coveralls.io/github/YOUR_USERNAME/portapack?branch=master)
+```
+
+## 📊 VitePress Coverage Page
+
+The project automatically generates a test coverage report and makes it accessible via VitePress:
+
+- Coverage report is generated to `docs/test-coverage/`
+- Accessible at `/test-coverage/` in your documentation site
+- Automatically updated with each test run
+
+## 🧼 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
+
+## ✍️ Recommended Commit Format
+
+```bash
+npm run commit
+```
+
+### Examples
+
+```
+feat(fonts): add base64 embedding with MIME detection
+fix(extractor): fallback on missing asset
+chore(ci): enable docs deploy with GitHub Pages
+```