portapack 0.3.0 → 0.3.2

package/docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
-import { defineConfig } from 'vitepress'
-import { buildDocsSidebar } from './sidebar-generator'
+import { defineConfig } from 'vitepress';
+import { buildDocsSidebar } from './sidebar-generator';
 
 export default defineConfig({
   base: '/portapack/',
@@ -7,49 +7,51 @@ export default defineConfig({
   description: 'Bundle & Minify HTML into a Single Portable File',
   appearance: 'dark',
   lastUpdated: true,
-  
+
   head: [
-    ['link', { rel: 'icon', href: '/favicon.png' }],
+    ['link', { rel: 'icon', href: '/portapack/favicon.ico' }],
     ['meta', { name: 'og:title', content: 'PortaPack' }],
-    ['meta', { name: 'og:description', content: 'Bundle & Minify HTML into a Single Portable File' }],
-    ['meta', { name: 'og:image', content: '/og-image.png' }],
-    ['meta', { name: 'twitter:card', content: 'summary_large_image' }]
+    [
+      'meta',
+      { name: 'og:description', content: 'Bundle & Minify HTML into a Single Portable File' },
+    ],
+    ['meta', { name: 'og:image', content: '/portapack/portapack.jpg' }], // Updated to use your non-transparent logo
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
   ],
 
   themeConfig: {
-    logo: '/logo.png',
-    
+    logo: '/portapack-transparent.png', // This path is relative to the public directory
+
     socialLinks: [
       { icon: 'github', link: 'https://github.com/manicinc/portapack' },
       { icon: 'twitter', link: 'https://x.com/manicagency' },
       { icon: 'discord', link: 'https://discord.gg/DzNgXdYm' },
-      { 
+      {
         icon: {
-          svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 0h-14c-2.761 0-5 2.239-5 5v14c0 2.761 2.239 5 5 5h14c2.762 0 5-2.239 5-5v-14c0-2.761-2.238-5-5-5zm-11 19h-3v-11h3v11zm-1.5-12.268c-.966 0-1.75-.79-1.75-1.764s.784-1.764 1.75-1.764 1.75.79 1.75 1.764-.783 1.764-1.75 1.764zm13.5 12.268h-3v-5.604c0-3.368-4-3.113-4 0v5.604h-3v-11h3v1.765c1.396-2.586 7-2.777 7 2.476v6.759z"/></svg>'
-        }, 
-        link: 'https://www.linkedin.com/company/manic-agency-llc/' 
-      }
+          svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 0h-14c-2.761 0-5 2.239-5 5v14c0 2.761 2.239 5 5 5h14c2.762 0 5-2.239 5-5v-14c0-2.761-2.238-5-5-5zm-11 19h-3v-11h3v11zm-1.5-12.268c-.966 0-1.75-.79-1.75-1.764s.784-1.764 1.75-1.764 1.75.79 1.75 1.764-.783 1.764-1.75 1.764zm13.5 12.268h-3v-5.604c0-3.368-4-3.113-4 0v5.604h-3v-11h3v1.765c1.396-2.586 7-2.777 7 2.476v6.759z"/></svg>',
+        },
+        link: 'https://www.linkedin.com/company/manic-agency-llc/',
+      },
     ],
 
     footer: {
       message: 'Released under the MIT License',
-      copyright: '© 2025 Manic Agency. All rights reserved.'
+      copyright: '© 2025 Manic Agency. All rights reserved.',
     },
 
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Getting Started', link: '/getting-started' },
-      { 
-        text: 'Docs', 
+      {
+        text: 'Docs',
         items: [
           { text: 'CLI Reference', link: '/cli' },
           { text: 'API', link: '/api/README' },
           { text: 'Configuration', link: '/configuration' },
-          { text: 'Advanced Usage', link: '/advanced' }
-        ]
+          { text: 'Advanced Usage', link: '/advanced' },
+        ],
       },
-      { text: 'Demo', link: '/demo' },
-      { text: 'Contributing', link: '/contributing' }
+      { text: 'Contributing', link: '/contributing' },
     ],
 
     sidebar: {
@@ -60,9 +62,9 @@ export default defineConfig({
           items: [
             { text: 'Introduction', link: '/getting-started/' },
             { text: 'Installation', link: '/getting-started/installation' },
-            { text: 'Quick Start', link: '/getting-started/quick-start' }
-          ]
-        }
+            { text: 'Quick Start', link: '/getting-started/quick-start' },
+          ],
+        },
       ],
       '/cli/': [
         {
@@ -70,9 +72,9 @@ export default defineConfig({
           items: [
             { text: 'Overview', link: '/cli/' },
             { text: 'Commands', link: '/cli/commands' },
-            { text: 'Options', link: '/cli/options' }
-          ]
-        }
+            { text: 'Options', link: '/cli/options' },
+          ],
+        },
       ],
       '/configuration/': [
         {
@@ -80,10 +82,10 @@ export default defineConfig({
           items: [
             { text: 'Overview', link: '/configuration/' },
             { text: 'Options', link: '/configuration/options' },
-            { text: 'Advanced', link: '/configuration/advanced' }
-          ]
-        }
-      ]
-    }
-  }
-})
+            { text: 'Advanced', link: '/configuration/advanced' },
+          ],
+        },
+      ],
+    },
+  },
+});

package/docs/.vitepress/sidebar-generator.ts

@@ -1,5 +1,6 @@
-import { glob } from 'glob'
-import path from 'path'
+import { glob } from 'glob';
+import path from 'path';
+import { fileURLToPath } from 'url'; // Needed for ESM __dirname equivalent
 
 /**
  * Sidebar item interface for VitePress configuration
@@ -11,63 +12,113 @@ export interface SidebarItem {
   collapsed?: boolean;
 }
 
+// --- Helper to get the directory name in ES Modules ---
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// --- Assuming sidebar-generator.ts is directly inside 'docs' ---
+// If it's deeper, adjust accordingly (e.g., path.resolve(__dirname, '..'))
+const docsDir = __dirname;
+const apiDir = path.join(docsDir, 'api'); // Absolute path to the api directory
+
 /**
  * Automatically builds sidebar from generated TypeDoc files
  * @returns Dynamically generated sidebar configuration
  */
 export function buildDocsSidebar(): SidebarItem[] {
   try {
+    // Log the directory being scanned
+    console.log(`Scanning for markdown files in: ${apiDir}`);
+
     // Get all markdown files from the API docs directory using absolute path
-    const apiFiles = glob.sync('docs/api/**/*.md', { absolute: true })
-    
+    // Use path.join for cross-platform compatibility
+    const apiFiles = glob.sync(path.join(apiDir, '**/*.md').replace(/\\/g, '/'), {
+      absolute: true,
+    }); // Use forward slashes for glob
+
+    // Log found files for debugging
+    console.log(`Found ${apiFiles.length} API files:`, apiFiles);
+
     // Build sidebar structure
-    const apiSidebar: SidebarItem[] = []
-    
+    const apiSidebar: SidebarItem[] = [];
+
     // Define documentation sections to process
     const sections = [
       { name: 'Modules', path: 'modules' },
       { name: 'Classes', path: 'classes' },
       { name: 'Interfaces', path: 'interfaces' },
       { name: 'Functions', path: 'functions' },
-      { name: 'Types', path: 'types' }
-    ]
+      { name: 'Types', path: 'types' },
+      // Add other sections if needed
+    ];
 
     // Process each section
     sections.forEach(({ name, path: sectionPath }) => {
-      const sectionFiles = apiFiles.filter(file => {
-        const relativePath = path.relative('docs', file)
-        return relativePath.includes(`/api/${sectionPath}/`) && !relativePath.endsWith('index.md')
-      }).map(file => {
-        const relativePath = path.relative('docs', file)
-        const basename = path.basename(file, '.md')
-        return {
-          text: basename.replace(/^_/, '').replace(/-/g, ' '),
-          link: '/' + relativePath.replace(/\.md$/, '')
-        }
-      })
-      
+      // Filter files based on the absolute path to the section directory
+      const sectionDir = path.join(apiDir, sectionPath);
+      const sectionFiles = apiFiles
+        .filter(file => {
+          // Check if the file is within the current section's directory
+          // and is not an index file directly within that section directory
+          const fileDirPath = path.dirname(file);
+          return (
+            file.startsWith(sectionDir) && fileDirPath !== sectionDir && !file.endsWith('index.md')
+          );
+          // Alternative, simpler check if structure is flat within sections:
+          // return file.startsWith(path.join(apiDir, sectionPath, '/')) && !file.endsWith('index.md');
+        })
+        .map(file => {
+          // Calculate path relative to the 'docs' directory for the link
+          const relativePath = path.relative(docsDir, file);
+          const basename = path.basename(file, '.md');
+          const link = '/' + relativePath.replace(/\\/g, '/').replace(/\.md$/, ''); // Ensure forward slashes for URL
+
+          console.log(`Processing file: ${file}, Relative Path: ${relativePath}, Link: ${link}`); // Debug log
+
+          return {
+            text: basename.replace(/^_/, '').replace(/-/g, ' '), // Basic cleanup
+            link: link,
+          };
+        })
+        .sort((a, b) => a.text.localeCompare(b.text)); // Sort items alphabetically
+
       if (sectionFiles.length > 0) {
         apiSidebar.push({
           text: name,
-          collapsed: false,
-          items: sectionFiles
-        })
+          collapsed: false, // Or true if you prefer them collapsed
+          items: sectionFiles,
+        });
       }
-    })
-    
-    // Add main API index as first item
-    apiSidebar.unshift({
-      text: 'API Reference',
-      link: '/api/'
-    })
-    
-    return apiSidebar
+    });
+
+    // Add main API index if it exists (relative to docsDir)
+    const mainApiIndex = path.join(apiDir, 'index.md'); // Or maybe README.md? Check your TypeDoc output
+    // Check if the main index file exists using glob result or fs.existsSync
+    const mainApiIndexExists = apiFiles.some(file => file === mainApiIndex);
+
+    if (mainApiIndexExists) {
+      apiSidebar.unshift({
+        text: 'API Overview', // Or 'API Reference'
+        link: '/api/', // Link to the root index file of the API section
+      });
+    } else {
+      // Maybe add a placeholder or log a warning if the main index is missing
+      console.warn(
+        'Main API index file (e.g., docs/api/index.md or docs/api/README.md) not found.'
+      );
+    }
+
+    // Log the final generated sidebar
+    console.log('Generated API Sidebar:', JSON.stringify(apiSidebar, null, 2));
+
+    return apiSidebar;
   } catch (error) {
-    console.error('Error building docs sidebar:', error)
+    console.error('Error building docs sidebar:', error);
     // Return basic sidebar if there's an error
-    return [{
-      text: 'API Reference',
-      link: '/api/'
-    }]
+    return [
+      {
+        text: 'API Reference (Error)',
+        link: '/api/',
+      },
+    ];
   }
-}
+}

package/docs/cli.md

@@ -16,46 +16,35 @@ npm install -g portapack
 
 ## Command Syntax
 
-PortaPack supports two command styles for specifying input:
+The basic syntax for the PortaPack CLI is:
 
 ```bash
-# Positional argument style (recommended)
-portapack <path_or_url> [options]
-
-# Named argument style
-portapack --input <path_or_url> [options]
-# or using shorthand
-portapack -i <path_or_url> [options]
+portapack [input] [options]
 ```
 
-Both methods work identically - choose whichever you prefer.
+Where `[input]` is the path to a local HTML file or a remote URL.
 
 ## Options
 
-| Option | Shorthand | Description | Default |
-|--------|-----------|-------------|---------|
-| `<path_or_url>` or `--input <path_or_url>` | `-i` | Required. Input local file path or remote URL (http/https) to process. | - |
-| `--output <file>` | `-o` | Output file path for the bundled HTML. | `{input}.packed.html` |
-| `--minify` | `-m` | Enable all minification (HTML, CSS, JS). | - |
-| `--no-minify` | | Disable all asset minification (HTML, CSS, JS). | `false` |
-| `--no-minify-html` | | Disable only HTML minification. | `false` |
-| `--no-minify-css` | | Disable only CSS minification. | `false` |
-| `--no-minify-js` | | Disable only JavaScript minification. | `false` |
-| `--recursive [depth]` | `-r` | Recursively bundle links up to depth. If depth omitted, defaults to 1. Only applies to remote URLs. | - (disabled) |
-| `--max-depth <n>` | | Set maximum depth for recursive crawling (alternative to `-r <n>`). | - |
-| `--base-url <url>` | `-b` | Base URL for resolving relative URLs found in the input HTML. | Input path/URL |
-| `--embed-assets` | `-e` | Embed external assets (CSS, JS, images, fonts) as data URIs or inline content. | `true` |
-| `--no-embed-assets` | | Keep external assets as links (requires network access when viewing). | `false` |
-| `--timeout <ms>` | `-t` | Network timeout in milliseconds for fetching remote resources. | `30000` (30 seconds) |
-| `--user-agent <string>` | `-U` | Custom User-Agent string for network requests. | Default Node.js agent |
-| `--include <glob>` | | Glob pattern for URLs to include during recursion (can be specified multiple times). | `**` (all) |
-| `--exclude <glob>` | | Glob pattern for URLs to exclude during recursion (can be specified multiple times). | - |
-| `--log-level <level>` | `-l` | Set logging level (debug, info, warn, error, silent). | `info` |
-| `--verbose` | `-v` | Enable verbose logging (shortcut for `--log-level debug`). | `false` |
-| `--config <path>` | `-c` | Path to a configuration file (e.g., `.portapackrc.json`) to load options from. | - |
-| `--dry-run` | `-d` | Perform all steps except writing the output file. Logs intended actions. | `false` |
-| `--help` | `-h` | Show help information and exit. | - |
-| `--version` | | Show PortaPack CLI version number and exit. | - |
+| Option                | Shorthand | Description                                                                                                       | Default                        |
+| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `[input]`             |           | Required. Input local file path or remote URL (http/https) to process.                                            | -                              |
+| `--output <file>`     | `-o`      | Output file path for the bundled HTML.                                                                            | `{input-basename}.packed.html` |
+| `--recursive [depth]` | `-r`      | Recursively bundle links up to depth. If depth omitted, defaults to true (no limit). Only applies to remote URLs. | `false` (disabled)             |
+| `--max-depth <n>`     |           | Set maximum depth for recursive crawling (alternative to `-r <n>`).                                               | -                              |
+| `--minify`            | `-m`      | Enable all minification (HTML, CSS, JS).                                                                          | -                              |
+| `--no-minify`         |           | Disable all asset minification (HTML, CSS, JS).                                                                   | `false`                        |
+| `--no-minify-html`    |           | Disable only HTML minification.                                                                                   | `false`                        |
+| `--no-minify-css`     |           | Disable only CSS minification.                                                                                    | `false`                        |
+| `--no-minify-js`      |           | Disable only JavaScript minification.                                                                             | `false`                        |
+| `--embed-assets`      | `-e`      | Embed external assets (CSS, JS, images, fonts) as data URIs or inline content.                                    | `true`                         |
+| `--no-embed-assets`   |           | Keep external assets as links (requires network access when viewing).                                             | `false`                        |
+| `--base-url <url>`    | `-b`      | Base URL for resolving relative URLs found in the input HTML.                                                     | Input path/URL                 |
+| `--log-level <level>` |           | Set logging level (debug, info, warn, error, silent, none).                                                       | `info`                         |
+| `--verbose`           | `-v`      | Enable verbose logging (shortcut for `--log-level debug`).                                                        | `false`                        |
+| `--dry-run`           | `-d`      | Perform all steps except writing the output file. Logs intended actions.                                          | `false`                        |
+| `--help`              | `-h`      | Show help information and exit.                                                                                   | -                              |
+| `--version`           |           | Show PortaPack CLI version number and exit.                                                                       | -                              |
 
 ## Examples
 
@@ -64,21 +53,13 @@ Both methods work identically - choose whichever you prefer.
 Bundle `index.html` into `bundle.html`:
 
 ```bash
-# Using positional argument style
 portapack ./index.html -o bundle.html
-
-# Using named argument style
-portapack -i ./index.html -o bundle.html
 ```
 
-Use default output name (`index.html.packed.html`):
+Use default output name (`index.packed.html`):
 
 ```bash
-# Using positional argument style
 portapack ./index.html
-
-# Using named argument style
-portapack -i ./index.html
 ```
 
 ### Web Page Bundling
@@ -86,11 +67,7 @@ portapack -i ./index.html
 Bundle a single remote webpage:
 
 ```bash
-# Using positional argument style
 portapack https://example.com -o example-bundle.html
-
-# Using named argument style
-portapack -i https://example.com -o example-bundle.html
 ```
 
 ### Recursive Bundling
@@ -113,15 +90,6 @@ Alternative using `--max-depth` option:
 portapack https://example.com --max-depth 2 -o site-bundle-depth2.html
 ```
 
-Recursively bundle only blog posts, excluding images:
-
-```bash
-portapack https://example.com -r \
-  --include "/blog/**" \
-  --exclude "**/*.{jpg,png,gif}" \
-  -o blog-bundle.html
-```
-
 ### Asset Handling
 
 Bundle without embedding assets (keep external links):
@@ -160,14 +128,6 @@ portapack ./index.html --no-minify-html -o selective-min.html
 portapack ./index.html --no-minify-js -o no-js-min.html
 ```
 
-### Advanced Network Options
-
-Bundle a remote page with a longer timeout and custom user agent:
-
-```bash
-portapack https://example.com -t 60000 -U "MyCustomBot/1.0" -o example-custom.html
-```
-
 ### Base URL for Relative Links
 
 Process a local file as if it were hosted at https://example.com:
@@ -198,14 +158,6 @@ See what files and assets would be processed without saving:
 portapack ./index.html --dry-run
 ```
 
-### Using a Configuration File
-
-Load options from a config file:
-
-```bash
-portapack -c ./.portapackrc.json
-```
-
 ### NPX Usage
 
 Use PortaPack without installing globally:
@@ -217,17 +169,12 @@ npx portapack ./index.html -o bundle.html
 ## Exit Codes
 
 | Code | Description |
-|------|-------------|
-| 0 | Success |
-| 1 | General Error (e.g., invalid options, file IO) |
-| 2 | Input Error (e.g., missing input, invalid URL) |
-| 3 | Network Error (e.g., fetch failed, timeout) |
-| 4 | Processing Error (e.g., parsing failed) |
-
-(Note: Specific error codes might vary)
+| ---- | ----------- |
+| 0    | Success     |
+| 1    | Error       |
 
 ## Related Resources
 
-- Getting Started (Link needs validation)
-- API Reference (Link needs validation)
-- Configuration Guide (Link needs validation)
+- [Getting Started](https://manicinc.github.io/portapack/getting-started)
+- [API Reference](https://manicinc.github.io/portapack/api/)
+- [Configuration Guide](https://manicinc.github.io/portapack/configuration)

package/docs/code-of-conduct.md

@@ -3,6 +3,7 @@
 ## Our Pledge
 
 We are committed to providing a friendly, safe, and welcoming environment for all contributors, regardless of:
+
 - Age
 - Body size
 - Disability
@@ -18,6 +19,7 @@ We are committed to providing a friendly, safe, and welcoming environment for al
 ## Our Standards
 
 ### Positive Behavior
+
 - Using welcoming and inclusive language
 - Being respectful of differing viewpoints
 - Gracefully accepting constructive criticism
@@ -25,6 +27,7 @@ We are committed to providing a friendly, safe, and welcoming environment for al
 - Showing empathy towards other community members
 
 ### Unacceptable Behavior
+
 - Trolling, insulting/derogatory comments
 - Public or private harassment
 - Publishing others' private information
@@ -33,6 +36,7 @@ We are committed to providing a friendly, safe, and welcoming environment for al
 ## 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
@@ -40,6 +44,7 @@ Community leaders are responsible for:
 ## Reporting Issues
 
 If you experience or witness unacceptable behavior:
+
 1. Email [conduct@manicinc.com](mailto:conduct@manicinc.com)
 2. Provide:
    - Your contact information
@@ -50,6 +55,7 @@ If you experience or witness unacceptable behavior:
 ## Consequences
 
 Violations may result in:
+
 - Temporary or permanent ban from community spaces
 - Removal of contributions
 - Public or private warnings
@@ -62,4 +68,4 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], versi
 
 ## License
 
-This Code of Conduct is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
+This Code of Conduct is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).