portapack 0.3.1 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/.eslintrc.json +67 -8
  2. package/.releaserc.js +25 -27
  3. package/CHANGELOG.md +14 -22
  4. package/LICENSE.md +21 -0
  5. package/README.md +22 -53
  6. package/commitlint.config.js +30 -34
  7. package/dist/cli/cli-entry.cjs +183 -98
  8. package/dist/cli/cli-entry.cjs.map +1 -1
  9. package/dist/index.d.ts +0 -3
  10. package/dist/index.js +178 -97
  11. package/dist/index.js.map +1 -1
  12. package/docs/.vitepress/config.ts +38 -33
  13. package/docs/.vitepress/sidebar-generator.ts +89 -38
  14. package/docs/architecture.md +186 -0
  15. package/docs/cli.md +23 -23
  16. package/docs/code-of-conduct.md +7 -1
  17. package/docs/configuration.md +12 -11
  18. package/docs/contributing.md +6 -2
  19. package/docs/deployment.md +10 -5
  20. package/docs/development.md +8 -5
  21. package/docs/getting-started.md +13 -13
  22. package/docs/index.md +1 -1
  23. package/docs/public/android-chrome-192x192.png +0 -0
  24. package/docs/public/android-chrome-512x512.png +0 -0
  25. package/docs/public/apple-touch-icon.png +0 -0
  26. package/docs/public/favicon-16x16.png +0 -0
  27. package/docs/public/favicon-32x32.png +0 -0
  28. package/docs/public/favicon.ico +0 -0
  29. package/docs/roadmap.md +233 -0
  30. package/docs/site.webmanifest +1 -0
  31. package/docs/troubleshooting.md +12 -1
  32. package/examples/main.ts +5 -30
  33. package/examples/sample-project/script.js +1 -1
  34. package/jest.config.ts +8 -13
  35. package/nodemon.json +5 -10
  36. package/package.json +2 -5
  37. package/src/cli/cli-entry.ts +2 -2
  38. package/src/cli/cli.ts +21 -16
  39. package/src/cli/options.ts +127 -113
  40. package/src/core/bundler.ts +253 -222
  41. package/src/core/extractor.ts +632 -565
  42. package/src/core/minifier.ts +173 -162
  43. package/src/core/packer.ts +141 -137
  44. package/src/core/parser.ts +74 -73
  45. package/src/core/web-fetcher.ts +270 -258
  46. package/src/index.ts +18 -17
  47. package/src/types.ts +9 -11
  48. package/src/utils/font.ts +12 -6
  49. package/src/utils/logger.ts +110 -105
  50. package/src/utils/meta.ts +75 -76
  51. package/src/utils/mime.ts +50 -50
  52. package/src/utils/slugify.ts +33 -34
  53. package/tests/unit/cli/cli-entry.test.ts +72 -70
  54. package/tests/unit/cli/cli.test.ts +314 -278
  55. package/tests/unit/cli/options.test.ts +294 -301
  56. package/tests/unit/core/bundler.test.ts +426 -329
  57. package/tests/unit/core/extractor.test.ts +793 -549
  58. package/tests/unit/core/minifier.test.ts +374 -274
  59. package/tests/unit/core/packer.test.ts +298 -264
  60. package/tests/unit/core/parser.test.ts +538 -150
  61. package/tests/unit/core/web-fetcher.test.ts +389 -359
  62. package/tests/unit/index.test.ts +238 -197
  63. package/tests/unit/utils/font.test.ts +26 -21
  64. package/tests/unit/utils/logger.test.ts +267 -260
  65. package/tests/unit/utils/meta.test.ts +29 -28
  66. package/tests/unit/utils/mime.test.ts +73 -74
  67. package/tests/unit/utils/slugify.test.ts +14 -12
  68. package/tsconfig.build.json +9 -10
  69. package/tsconfig.jest.json +1 -1
  70. package/tsconfig.json +2 -2
  71. package/tsup.config.ts +8 -9
  72. package/typedoc.json +5 -9
  73. /package/docs/{portapack-transparent.png → public/portapack-transparent.png} +0 -0
  74. /package/docs/{portapack.jpg → public/portapack.jpg} +0 -0
package/.eslintrc.json CHANGED
@@ -1,9 +1,68 @@
1
1
  {
2
- "singleQuote": true,
3
- "semi": true,
4
- "tabWidth": 2,
5
- "printWidth": 100,
6
- "trailingComma": "es5",
7
- "arrowParens": "avoid",
8
- "endOfLine": "lf"
9
- }
2
+ // Specifies this is the root config; ESLint won't look higher up.
3
+ "root": true,
4
+
5
+ // Specifies the parser ESLint should use. Needed for TypeScript.
6
+ "parser": "@typescript-eslint/parser",
7
+
8
+ // Configures parser options.
9
+ "parserOptions": {
10
+ "ecmaVersion": "latest", // Use the latest ECMAScript features
11
+ "sourceType": "module" // Use ES modules, matching your package.json "type": "module"
12
+ // "project": "./tsconfig.json" // Uncomment this line if you want to enable rules that require type information.
13
+ // This can provide more powerful linting but might slow down linting.
14
+ // Ensure your tsconfig.json is correctly set up if you enable this.
15
+ },
16
+
17
+ // Defines the global environments available.
18
+ "env": {
19
+ "node": true, // Enable Node.js global variables and Node.js scoping.
20
+ "es2022": true, // Enable ES2022 globals (aligns with ecmaVersion: 'latest').
21
+ "jest/globals": true // Enable Jest global variables (like describe, it, expect). Requires eslint-plugin-jest.
22
+ },
23
+
24
+ // Specifies plugins to use.
25
+ "plugins": [
26
+ "@typescript-eslint", // Plugin for TypeScript-specific linting rules.
27
+ "jest" // Plugin for Jest-specific linting rules.
28
+ ],
29
+
30
+ // Extends base configurations. Rules are inherited and potentially overridden.
31
+ "extends": [
32
+ // Base recommended ESLint rules.
33
+ "eslint:recommended",
34
+
35
+ // Recommended rules from the @typescript-eslint plugin.
36
+ "plugin:@typescript-eslint/recommended",
37
+
38
+ // Recommended rules from the eslint-plugin-jest.
39
+ "plugin:jest/recommended",
40
+
41
+ // IMPORTANT: This MUST be the LAST configuration in the extends array.
42
+ // It uses 'eslint-config-prettier' to disable ESLint rules that would conflict with Prettier formatting.
43
+ // This lets Prettier handle all formatting concerns without fighting ESLint.
44
+ "prettier"
45
+ ],
46
+
47
+ // Custom rules or overrides for rules from extended configs.
48
+ "rules": {
49
+ // --- Add specific rule overrides here if needed ---
50
+ // Example: Warn about unused variables, but allow if prefixed with _
51
+ // "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
52
+ // Example: Warn instead of error for console logs
53
+ // "no-console": "warn",
54
+ // You can turn off specific rules if they are too noisy or don't fit your style:
55
+ // "@typescript-eslint/no-explicit-any": "off",
56
+ // Add any other custom rules or overrides here.
57
+ },
58
+
59
+ // Specifies files and directories that ESLint should ignore.
60
+ "ignorePatterns": [
61
+ "node_modules/",
62
+ "dist/", // Your build output directory
63
+ "coverage/", // Your test coverage directory
64
+ "docs/.vitepress/dist/", // Your VitePress build output
65
+ "*.cjs" // Often auto-generated CommonJS wrappers might not need linting
66
+ // Add any other patterns for generated files or directories
67
+ ]
68
+ }
package/.releaserc.js CHANGED
@@ -1,29 +1,27 @@
1
1
  module.exports = {
2
- branches: ['main'],
3
- plugins: [
4
- '@semantic-release/commit-analyzer',
5
- '@semantic-release/release-notes-generator',
6
- '@semantic-release/npm',
7
- [
8
- '@semantic-release/github',
9
- {
10
- assets: [
11
- { path: 'dist/**', label: 'Distribution' },
12
- ],
13
- },
14
- ],
15
- [
16
- '@semantic-release/changelog',
17
- {
18
- changelogFile: 'CHANGELOG.md',
19
- },
20
- ],
21
- [
22
- '@semantic-release/git',
23
- {
24
- assets: ['package.json', 'CHANGELOG.md'],
25
- message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
26
- },
27
- ],
2
+ branches: ['main'],
3
+ plugins: [
4
+ '@semantic-release/commit-analyzer',
5
+ '@semantic-release/release-notes-generator',
6
+ '@semantic-release/npm',
7
+ [
8
+ '@semantic-release/github',
9
+ {
10
+ assets: [{ path: 'dist/**', label: 'Distribution' }],
11
+ },
28
12
  ],
29
- };
13
+ [
14
+ '@semantic-release/changelog',
15
+ {
16
+ changelogFile: 'CHANGELOG.md',
17
+ },
18
+ ],
19
+ [
20
+ '@semantic-release/git',
21
+ {
22
+ assets: ['package.json', 'CHANGELOG.md'],
23
+ message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
24
+ },
25
+ ],
26
+ ],
27
+ };
package/CHANGELOG.md CHANGED
@@ -1,41 +1,33 @@
1
- ## [0.3.1](https://github.com/manicinc/portapack/compare/v0.3.0...v0.3.1) (2025-04-14)
1
+ ## [0.3.3](https://github.com/manicinc/portapack/compare/v0.3.2...v0.3.3) (2025-04-20)
2
2
 
3
3
 
4
4
  ### Bug Fixes
5
5
 
6
- * **ci:** update Codecov config [skip release] ([593b126](https://github.com/manicinc/portapack/commit/593b1262183d05a9a7099463b6da0f4deb916576))
7
- * **extractor:** resolve test failures and coverage issues ([40ea42c](https://github.com/manicinc/portapack/commit/40ea42cbdbeec67657225c50eb97ef0965cd2769))
6
+ * typo in link ([e79e1d1](https://github.com/manicinc/portapack/commit/e79e1d105f800550d067d62ec04d0af6888eb82d))
8
7
 
9
- # [0.3.0](https://github.com/manicinc/portapack/compare/v0.2.1...v0.3.0) (2025-04-13)
8
+ ## [0.3.2](https://github.com/manicinc/portapack/compare/v0.3.1...v0.3.2) (2025-04-18)
10
9
 
11
10
 
12
11
  ### Bug Fixes
13
12
 
14
- * **cli:** fix CLI execution via npx and global install ([88774e8](https://github.com/manicinc/portapack/commit/88774e80d28d0ac9292906ac7454d4528a5396ec))
15
-
16
-
17
- ### Features
18
-
19
- * api upgrades / revamps; update types; more robust core features and test fixes; update docs ([34e7b4a](https://github.com/manicinc/portapack/commit/34e7b4af55c6c934af8be0f1c43d427fd00a9594))
20
-
21
- ## [0.2.1](https://github.com/manicinc/portapack/compare/v0.2.0...v0.2.1) (2025-04-11)
13
+ * add mit license ([17ad892](https://github.com/manicinc/portapack/commit/17ad89295c98eee56704841ae25670559874f4fb))
14
+ * cleanup comments; add back in missing tests; fix docs ([1348aab](https://github.com/manicinc/portapack/commit/1348aab5561842e29b6e434d6bb109780b95c486))
15
+ * linting and fix eslintjson ([76edb19](https://github.com/manicinc/portapack/commit/76edb19c96e563c778cadf06a00a27f7171041a2))
16
+ * more formatting ([7730aad](https://github.com/manicinc/portapack/commit/7730aadefc6310a58f483bfcdce2243e3279bdb2))
22
17
 
18
+ ## [0.3.1](https://github.com/manicinc/portapack/compare/v0.3.0...v0.3.1) (2025-04-14)
23
19
 
24
20
  ### Bug Fixes
25
21
 
26
- * rmv prepublishOnly for debug release ([6469768](https://github.com/manicinc/portapack/commit/6469768d6c14bd2ab243acfd5358115b7771f612))
27
-
28
- # [0.2.0](https://github.com/manicinc/portapack/compare/v0.1.0...v0.2.0) (2025-04-11)
22
+ - **ci:** update Codecov config [skip release] ([593b126](https://github.com/manicinc/portapack/commit/593b1262183d05a9a7099463b6da0f4deb916576))
23
+ - **extractor:** resolve test failures and coverage issues ([40ea42c](https://github.com/manicinc/portapack/commit/40ea42cbdbeec67657225c50eb97ef0965cd2769))
29
24
 
25
+ # [0.3.0](https://github.com/manicinc/portapack/compare/v0.2.1...v0.3.0) (2025-04-13)
30
26
 
31
- ### Features
32
-
33
- * cleanup rerelease ([f8e599b](https://github.com/manicinc/portapack/commit/f8e599b596b18c62941e5bd46740283b013262b1))
34
-
35
- # [1.2.0](https://github.com/manicinc/portapack/compare/v1.1.0...v1.2.0) (2025-04-11)
27
+ ### Bug Fixes
36
28
 
29
+ - **cli:** fix CLI execution via npx and global install ([88774e8](https://github.com/manicinc/portapack/commit/88774e80d28d0ac9292906ac7454d4528a5396ec))
37
30
 
38
31
  ### Features
39
32
 
40
- * cleanup rerelease ([f8e599b](https://github.com/manicinc/portapack/commit/f8e599b596b18c62941e5bd46740283b013262b1))
41
- * fix right version; trigger first release ([96147fc](https://github.com/manicinc/portapack/commit/96147fc61f5dc8e8f39e9d4343e22c79b25f0139))
33
+ - api upgrades / revamps; update types; more robust core features and test fixes; update docs ([34e7b4a](https://github.com/manicinc/portapack/commit/34e7b4af55c6c934af8be0f1c43d427fd00a9594))
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) [2025] [Manic.agency]
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -5,9 +5,13 @@
5
5
  [![Codecov](https://img.shields.io/codecov/c/github/manicinc/portapack?style=for-the-badge&logo=codecov)](https://codecov.io/gh/manicinc/portapack)
6
6
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)](./LICENSE)
7
7
 
8
- **PortaPack** bundles your entire website — HTML, CSS, JS, images, and fonts — into one self-contained HTML file. Perfect for snapshots, demos, testing, and offline apps.
8
+ <p align="center">
9
+ <img src="https://raw.githubusercontent.com/manicinc/portapack/master/docs/public/portapack-transparent.png" alt="PortaPack Logo" width="200"/>
10
+ </p>
9
11
 
10
- *Minimal input. Maximal output.*
12
+ **PortaPack** bundles your entire website — HTML, CSS, JS, images, and fonts — into one self-contained HTML file. Perfect for snapshots, demos, testing, and offline apps.
13
+
14
+ _Minimal input. Maximal output._
11
15
 
12
16
  ## 📚 Documentation
13
17
 
@@ -15,6 +19,8 @@
15
19
  - [⚙️ CLI Reference](https://manicinc.github.io/portapack/cli)
16
20
  - [🛠 Configuration Guide](https://manicinc.github.io/portapack/configuration)
17
21
  - [💻 API Reference](https://manicinc.github.io/portapack/api/)
22
+ - [🏛️ Architecture](https://manicinc.github.io/portapack/architecture/)
23
+ - [🚧 Roadmap](https://manicinc.github.io/portapack/roadmap/)
18
24
  - [🤝 Contributing Guidelines](https://manicinc.github.io/portapack/contributing)
19
25
 
20
26
  ## 🚀 Quick Start
@@ -29,26 +35,6 @@ npm install -g portapack
29
35
  npx portapack ./index.html -o bundle.html
30
36
  ```
31
37
 
32
- ### 🧰 CLI Options
33
-
34
- ```bash
35
- portapack [input] [options]
36
- ```
37
-
38
- | Option | Description |
39
- |--------|-------------|
40
- | `-o, --output <file>` | Output file path |
41
- | `-r, --recursive [n]` | Crawl site up to n levels deep |
42
- | `--max-depth <n>` | Explicit crawl depth |
43
- | `-m, --minify` | Enable all minification |
44
- | `--no-minify-*` | Disable html, css, or js minify |
45
- | `-e, --embed-assets` | Inline all assets (default: true) |
46
- | `--no-embed-assets` | Leave links as-is |
47
- | `-b, --base-url <url>` | Override base URL resolution |
48
- | `-v, --verbose` | Show debug output |
49
- | `--log-level <lvl>` | Set log level: debug, info, warn, error |
50
- | `-d, --dry-run` | Run without writing file |
51
-
52
38
  ### 📋 CLI Examples
53
39
 
54
40
  ```bash
@@ -89,22 +75,18 @@ console.log(result.html); // bundled HTML
89
75
 
90
76
  ```typescript
91
77
  import { pack, LogLevel } from 'portapack';
78
+ import fs from 'fs';
92
79
 
93
80
  const result = await pack('https://example.com', {
94
81
  minifyCss: true,
95
82
  minifyJs: false,
96
83
  recursive: 2,
97
84
  output: 'site.html',
98
- logLevel: LogLevel.INFO
85
+ logLevel: LogLevel.INFO,
99
86
  });
100
- ```
101
-
102
- ### Save to Disk
103
87
 
104
- ```typescript
105
- import fs from 'fs';
88
+ // Save to disk
106
89
  fs.writeFileSync('output.html', result.html);
107
- ```
108
90
 
109
91
  ### Advanced API Usage
110
92
 
@@ -114,37 +96,24 @@ You can access individual building blocks too:
114
96
  import {
115
97
  generatePortableHTML,
116
98
  generateRecursivePortableHTML,
117
- bundleMultiPageHTML,
118
- fetchAndPackWebPage,
99
+ bundleMultiPageHTML
119
100
  } from 'portapack';
120
101
  ```
121
102
 
122
- | Function | Purpose |
123
- |----------|---------|
124
- | `generatePortableHTML()` | Bundle a single file or URL |
125
- | `generateRecursivePortableHTML()` | Crawl & bundle entire site |
126
- | `fetchAndPackWebPage()` | Just fetch HTML (no asset processing) |
127
- | `bundleMultiPageHTML()` | Combine multiple HTMLs with router |
128
-
129
- ## 🤝 Contribute
130
-
131
- ```bash
132
- # Get started
133
- git clone https://github.com/manicinc/portapack
134
- cd portapack
135
- npm install
136
- npm run dev
137
- ```
103
+ | Function | Purpose |
104
+ | --------------------------------- | ------------------------------------- |
105
+ | `generatePortableHTML()` | Bundle a single file or URL |
106
+ | `generateRecursivePortableHTML()` | Crawl & bundle entire site |
107
+ | `bundleMultiPageHTML()` | Combine multiple HTMLs with router |
138
108
 
139
109
  ## 📊 Project Health
140
110
 
141
- | Metric | Value |
142
- |--------------|-------|
143
- | 📦 Version | [![npm](https://img.shields.io/npm/v/portapack.svg)](https://www.npmjs.com/package/portapack) |
144
- | ✅ Build | [![Build Status](https://img.shields.io/github/actions/workflow/status/manicinc/portapack/ci.yml?branch=master)](https://github.com/manicinc/portapack/actions) |
145
- | 🧪 Coverage | [![Codecov](https://img.shields.io/codecov/c/github/manicinc/portapack)](https://codecov.io/gh/manicinc/portapack) |
111
+ | Metric | Value |
112
+ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
113
+ | 📦 Version | [![npm](https://img.shields.io/npm/v/portapack.svg)](https://www.npmjs.com/package/portapack) |
114
+ | ✅ Build | [![Build Status](https://img.shields.io/github/actions/workflow/status/manicinc/portapack/ci.yml?branch=master)](https://github.com/manicinc/portapack/actions) |
115
+ | 🧪 Coverage | [![Codecov](https://img.shields.io/codecov/c/github/manicinc/portapack)](https://codecov.io/gh/manicinc/portapack) |
146
116
 
147
117
  ## 📄 License
148
118
 
149
119
  MIT — Built by Manic.agency
150
-
@@ -1,36 +1,32 @@
1
1
  module.exports = {
2
- extends: ['@commitlint/config-conventional'],
3
- rules: {
4
- 'body-leading-blank': [1, 'always'],
5
- 'body-max-line-length': [2, 'always', 100],
6
- 'footer-leading-blank': [1, 'always'],
7
- 'footer-max-line-length': [2, 'always', 100],
8
- 'header-max-length': [2, 'always', 100],
9
- 'subject-case': [
10
- 2,
11
- 'never',
12
- ['sentence-case', 'start-case', 'pascal-case', 'upper-case'],
2
+ extends: ['@commitlint/config-conventional'],
3
+ rules: {
4
+ 'body-leading-blank': [1, 'always'],
5
+ 'body-max-line-length': [2, 'always', 100],
6
+ 'footer-leading-blank': [1, 'always'],
7
+ 'footer-max-line-length': [2, 'always', 100],
8
+ 'header-max-length': [2, 'always', 100],
9
+ 'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
10
+ 'subject-empty': [2, 'never'],
11
+ 'subject-full-stop': [2, 'never', '.'],
12
+ 'type-case': [2, 'always', 'lower-case'],
13
+ 'type-empty': [2, 'never'],
14
+ 'type-enum': [
15
+ 2,
16
+ 'always',
17
+ [
18
+ 'build',
19
+ 'chore',
20
+ 'ci',
21
+ 'docs',
22
+ 'feat',
23
+ 'fix',
24
+ 'perf',
25
+ 'refactor',
26
+ 'revert',
27
+ 'style',
28
+ 'test',
13
29
  ],
14
- 'subject-empty': [2, 'never'],
15
- 'subject-full-stop': [2, 'never', '.'],
16
- 'type-case': [2, 'always', 'lower-case'],
17
- 'type-empty': [2, 'never'],
18
- 'type-enum': [
19
- 2,
20
- 'always',
21
- [
22
- 'build',
23
- 'chore',
24
- 'ci',
25
- 'docs',
26
- 'feat',
27
- 'fix',
28
- 'perf',
29
- 'refactor',
30
- 'revert',
31
- 'style',
32
- 'test',
33
- ],
34
- ],
35
- },
36
- };
30
+ ],
31
+ },
32
+ };