pixelkit-cli 0.0.0-stage → 1.0.0

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 (96) hide show
  1. package/CONTRIBUTING.md +395 -0
  2. package/LICENSE +21 -0
  3. package/README.md +323 -2
  4. package/dist/cli/arguments.d.ts +10 -0
  5. package/dist/cli/arguments.d.ts.map +1 -0
  6. package/dist/cli/arguments.js +44 -0
  7. package/dist/cli/arguments.js.map +1 -0
  8. package/dist/cli/commands.d.ts +6 -0
  9. package/dist/cli/commands.d.ts.map +1 -0
  10. package/dist/cli/commands.js +103 -0
  11. package/dist/cli/commands.js.map +1 -0
  12. package/dist/cli/index.d.ts +3 -0
  13. package/dist/cli/index.d.ts.map +1 -0
  14. package/dist/cli/index.js +50 -0
  15. package/dist/cli/index.js.map +1 -0
  16. package/dist/commands/png.d.ts +3 -0
  17. package/dist/commands/png.d.ts.map +1 -0
  18. package/dist/commands/png.js +100 -0
  19. package/dist/commands/png.js.map +1 -0
  20. package/dist/commands/webp.d.ts +3 -0
  21. package/dist/commands/webp.d.ts.map +1 -0
  22. package/dist/commands/webp.js +100 -0
  23. package/dist/commands/webp.js.map +1 -0
  24. package/dist/converters/png/index.d.ts +4 -0
  25. package/dist/converters/png/index.d.ts.map +1 -0
  26. package/dist/converters/png/index.js +23 -0
  27. package/dist/converters/png/index.js.map +1 -0
  28. package/dist/converters/png/options.d.ts +8 -0
  29. package/dist/converters/png/options.d.ts.map +1 -0
  30. package/dist/converters/png/options.js +6 -0
  31. package/dist/converters/png/options.js.map +1 -0
  32. package/dist/converters/registry.d.ts +5 -0
  33. package/dist/converters/registry.d.ts.map +1 -0
  34. package/dist/converters/registry.js +48 -0
  35. package/dist/converters/registry.js.map +1 -0
  36. package/dist/converters/types.d.ts +12 -0
  37. package/dist/converters/types.d.ts.map +1 -0
  38. package/dist/converters/types.js +2 -0
  39. package/dist/converters/types.js.map +1 -0
  40. package/dist/converters/webp/index.d.ts +4 -0
  41. package/dist/converters/webp/index.d.ts.map +1 -0
  42. package/dist/converters/webp/index.js +23 -0
  43. package/dist/converters/webp/index.js.map +1 -0
  44. package/dist/converters/webp/options.d.ts +9 -0
  45. package/dist/converters/webp/options.d.ts.map +1 -0
  46. package/dist/converters/webp/options.js +8 -0
  47. package/dist/converters/webp/options.js.map +1 -0
  48. package/dist/core/converter.d.ts +16 -0
  49. package/dist/core/converter.d.ts.map +1 -0
  50. package/dist/core/converter.js +50 -0
  51. package/dist/core/converter.js.map +1 -0
  52. package/dist/core/file-validator.d.ts +12 -0
  53. package/dist/core/file-validator.d.ts.map +1 -0
  54. package/dist/core/file-validator.js +29 -0
  55. package/dist/core/file-validator.js.map +1 -0
  56. package/dist/core/output-manager.d.ts +9 -0
  57. package/dist/core/output-manager.d.ts.map +1 -0
  58. package/dist/core/output-manager.js +27 -0
  59. package/dist/core/output-manager.js.map +1 -0
  60. package/dist/core/path-resolver.d.ts +6 -0
  61. package/dist/core/path-resolver.d.ts.map +1 -0
  62. package/dist/core/path-resolver.js +26 -0
  63. package/dist/core/path-resolver.js.map +1 -0
  64. package/dist/core/scanner.d.ts +9 -0
  65. package/dist/core/scanner.d.ts.map +1 -0
  66. package/dist/core/scanner.js +45 -0
  67. package/dist/core/scanner.js.map +1 -0
  68. package/dist/ui/image-selector.d.ts +3 -0
  69. package/dist/ui/image-selector.d.ts.map +1 -0
  70. package/dist/ui/image-selector.js +30 -0
  71. package/dist/ui/image-selector.js.map +1 -0
  72. package/dist/ui/messages.d.ts +8 -0
  73. package/dist/ui/messages.d.ts.map +1 -0
  74. package/dist/ui/messages.js +23 -0
  75. package/dist/ui/messages.js.map +1 -0
  76. package/dist/ui/progress.d.ts +3 -0
  77. package/dist/ui/progress.d.ts.map +1 -0
  78. package/dist/ui/progress.js +23 -0
  79. package/dist/ui/progress.js.map +1 -0
  80. package/dist/ui/spinner.d.ts +10 -0
  81. package/dist/ui/spinner.d.ts.map +1 -0
  82. package/dist/ui/spinner.js +35 -0
  83. package/dist/ui/spinner.js.map +1 -0
  84. package/dist/utils/constants.d.ts +19 -0
  85. package/dist/utils/constants.d.ts.map +1 -0
  86. package/dist/utils/constants.js +31 -0
  87. package/dist/utils/constants.js.map +1 -0
  88. package/dist/utils/errors.d.ts +10 -0
  89. package/dist/utils/errors.d.ts.map +1 -0
  90. package/dist/utils/errors.js +27 -0
  91. package/dist/utils/errors.js.map +1 -0
  92. package/dist/utils/logger.d.ts +10 -0
  93. package/dist/utils/logger.d.ts.map +1 -0
  94. package/dist/utils/logger.js +30 -0
  95. package/dist/utils/logger.js.map +1 -0
  96. package/package.json +69 -4
@@ -0,0 +1,395 @@
1
+ Contributing to PixelKit CLI
2
+
3
+ First of all, thank you for your interest in contributing to PixelKit CLI! 💙
4
+
5
+ PixelKit is an open-source, modular command-line image conversion toolkit built with TypeScript and Node.js.
6
+
7
+ We welcome contributions that improve the codebase, fix bugs, improve performance, enhance the CLI experience, add image converters, or improve documentation.
8
+
9
+ This guide explains how to set up the project, understand its architecture, follow coding rules, and submit contributions.
10
+
11
+ ---
12
+
13
+ 📌 Before You Start
14
+
15
+ Before contributing, make sure you have:
16
+
17
+ - Node.js 20 or later
18
+ - pnpm package manager
19
+ - Git
20
+ - Basic knowledge of TypeScript and Node.js
21
+
22
+ Important: This project uses pnpm.
23
+
24
+ Please use pnpm for installing dependencies, running scripts, and managing packages.
25
+
26
+ Do not use npm or yarn to install project dependencies.
27
+
28
+ ---
29
+
30
+ 📥 Getting Started
31
+
32
+ 1. Fork the repository
33
+
34
+ Visit the official repository:
35
+
36
+ https://github.com/rsavnani18/pixelkit-cli
37
+
38
+ Click the Fork button to create your own copy.
39
+
40
+ 2. Clone your fork
41
+
42
+ Replace "YOUR_USERNAME" with your GitHub username.
43
+
44
+ git clone https://github.com/YOUR_USERNAME/pixelkit-cli.git
45
+
46
+ Navigate into the project:
47
+
48
+ cd pixelkit-cli
49
+
50
+ 3. Install dependencies
51
+
52
+ pnpm install
53
+
54
+ This installs the dependencies defined in "package.json" and uses "pnpm-lock.yaml" to maintain consistent versions.
55
+
56
+ 4. Verify the project
57
+
58
+ Run the following commands:
59
+
60
+ pnpm typecheck
61
+ pnpm test
62
+ pnpm build
63
+
64
+ All checks should pass before you begin making changes.
65
+
66
+ ---
67
+
68
+ 🏗️ Project Architecture
69
+
70
+ PixelKit uses a modular architecture. Each part of the application has a specific responsibility.
71
+
72
+ Here are the main files contributors should understand.
73
+
74
+ CLI ("src/cli/")
75
+
76
+ File| Responsibility
77
+ "index.ts"| Main CLI entry point and command dispatching
78
+ "arguments.ts"| Parses user-provided arguments and paths
79
+ "commands.ts"| Handles global options such as help, list, version and info
80
+
81
+ Commands ("src/commands/")
82
+
83
+ File| Responsibility
84
+ "webp.ts"| WebP converter command
85
+ "png.ts"| PNG converter command
86
+
87
+ Command files connect user input with the appropriate converter and CLI interface.
88
+
89
+ Converters ("src/converters/")
90
+
91
+ File| Responsibility
92
+ "registry.ts"| Registers and exposes available converters
93
+ "types.ts"| Shared TypeScript types for converter definitions
94
+ "webp/"| WebP-specific conversion implementation
95
+ "png/"| PNG-specific conversion implementation
96
+
97
+ New image formats should follow the existing modular converter architecture.
98
+
99
+ Core ("src/core/")
100
+
101
+ File| Responsibility
102
+ "converter.ts"| Coordinates image conversion operations
103
+ "file-validator.ts"| Validates image files
104
+ "output-manager.ts"| Manages output paths and existing files
105
+ "path-resolver.ts"| Resolves user-provided file and directory paths
106
+ "scanner.ts"| Scans directories for supported image files
107
+
108
+ Core modules should contain reusable application logic rather than converter-specific terminal presentation.
109
+
110
+ UI ("src/ui/")
111
+
112
+ File| Responsibility
113
+ "image-selector.ts"| Interactive image selection
114
+ "messages.ts"| Terminal messages and user feedback
115
+ "progress.ts"| Conversion progress display
116
+ "spinner.ts"| Terminal loading indicators
117
+
118
+ Utilities ("src/utils/")
119
+
120
+ File| Responsibility
121
+ "constants.ts"| Shared application constants
122
+ "errors.ts"| Common error definitions and handling
123
+ "logger.ts"| Logging utilities
124
+
125
+ Tests ("tests/")
126
+
127
+ Automated tests verify CLI behavior, image conversion, path resolution, and directory scanning.
128
+
129
+ Existing test files include:
130
+
131
+ - "commands.test.ts"
132
+ - "converter.test.ts"
133
+ - "path-resolver.test.ts"
134
+ - "scanner.test.ts"
135
+
136
+ When adding a feature or fixing a bug, add or update the relevant tests.
137
+
138
+ ---
139
+
140
+ 📏 Contribution Rules
141
+
142
+ Please follow these rules when contributing.
143
+
144
+ 1. Package Manager
145
+
146
+ pnpm is mandatory.
147
+
148
+ Use:
149
+
150
+ pnpm install
151
+ pnpm add package-name
152
+ pnpm add -D package-name
153
+ pnpm remove package-name
154
+
155
+ Do not commit "package-lock.json" or "yarn.lock".
156
+
157
+ The "pnpm-lock.yaml" file must be committed whenever dependency changes require an updated lockfile.
158
+
159
+ 2. TypeScript
160
+
161
+ - Write new application code in TypeScript.
162
+ - Prefer explicit and meaningful types.
163
+ - Avoid using "any" unless there is a clear technical reason.
164
+ - Use the existing ESM import conventions.
165
+ - Keep functions small and focused.
166
+ - Avoid unnecessary dependencies.
167
+
168
+ 3. Code Organization
169
+
170
+ - Keep converter-specific logic inside its respective converter module.
171
+ - Keep reusable processing logic inside "src/core/".
172
+ - Keep terminal presentation inside "src/ui/".
173
+ - Keep shared constants and utilities inside "src/utils/".
174
+ - Do not place all application logic inside the CLI entry point.
175
+ - Follow the existing architecture when adding new features.
176
+
177
+ 4. Image Processing
178
+
179
+ - Preserve original input files.
180
+ - Never overwrite an existing output file without an explicit user-approved feature.
181
+ - Validate input files before processing.
182
+ - Handle invalid or unsupported image files gracefully.
183
+ - Preserve image transparency where the target format supports it.
184
+ - Handle conversion errors without crashing the entire application unnecessarily.
185
+
186
+ 5. CLI Experience
187
+
188
+ - Keep commands simple and predictable.
189
+ - Provide clear error messages.
190
+ - Maintain consistent terminal styling using the existing UI utilities.
191
+ - Support paths containing spaces.
192
+ - Avoid unnecessary terminal output.
193
+ - Keep interactive selection behavior consistent with the existing interface.
194
+
195
+ 6. Dependencies
196
+
197
+ Before adding a new dependency:
198
+
199
+ - Check whether existing packages can handle the requirement.
200
+ - Prefer lightweight and actively maintained packages.
201
+ - Avoid adding dependencies for trivial functionality.
202
+ - Explain the reason for introducing a new dependency in your Pull Request.
203
+
204
+ 7. Documentation
205
+
206
+ Update relevant documentation when changing:
207
+
208
+ - CLI commands
209
+ - Installation instructions
210
+ - Converter behavior
211
+ - Package configuration
212
+ - Supported image formats
213
+ - Development workflows
214
+
215
+ ---
216
+
217
+ 🔧 Development Commands
218
+
219
+ Use the existing project scripts.
220
+
221
+ Command| Purpose
222
+ "pnpm dev"| Run the main CLI in development mode
223
+ "pnpm dev:webp"| Run the WebP command
224
+ "pnpm dev:png"| Run the PNG command
225
+ "pnpm typecheck"| Check TypeScript types
226
+ "pnpm test"| Run automated tests
227
+ "pnpm test:watch"| Run tests in watch mode
228
+ "pnpm build"| Generate production files
229
+ "pnpm clean"| Remove the production build
230
+ "pnpm check"| Run typecheck, tests and build
231
+ "pnpm format"| Format project files
232
+ "pnpm format:check"| Check formatting
233
+
234
+ Before submitting a Pull Request, run:
235
+
236
+ pnpm check
237
+
238
+ Make sure all checks pass.
239
+
240
+ ---
241
+
242
+ 🌿 Branch Naming
243
+
244
+ Use descriptive branch names.
245
+
246
+ Examples:
247
+
248
+ feature/avif-converter
249
+ feature/conversion-quality
250
+ fix/png-transparency
251
+ fix/path-validation
252
+ docs/update-readme
253
+ test/converter-coverage
254
+
255
+ Recommended prefixes:
256
+
257
+ - "feature/" for new functionality
258
+ - "fix/" for bug fixes
259
+ - "docs/" for documentation
260
+ - "test/" for tests
261
+ - "refactor/" for code improvements
262
+
263
+ ---
264
+
265
+ 🔄 How to Contribute
266
+
267
+ Follow this workflow:
268
+
269
+ 1. Create a branch
270
+
271
+ git checkout -b feature/your-feature-name
272
+
273
+ 2. Make your changes
274
+
275
+ Implement your feature or bug fix while following the project architecture and coding rules.
276
+
277
+ 3. Test your changes
278
+
279
+ pnpm typecheck
280
+ pnpm test
281
+ pnpm build
282
+
283
+ 4. Review your changes
284
+
285
+ git status
286
+ git diff
287
+
288
+ Make sure you are not committing unnecessary files, generated build artifacts, local test images, or personal configuration.
289
+
290
+ 5. Commit your changes
291
+
292
+ Use clear and descriptive commit messages.
293
+
294
+ Examples:
295
+
296
+ git add .
297
+ git commit -m "feat: add AVIF converter"
298
+
299
+ git commit -m "fix: preserve PNG transparency"
300
+
301
+ git commit -m "docs: improve installation guide"
302
+
303
+ 6. Push your branch
304
+
305
+ git push origin feature/your-feature-name
306
+
307
+ 7. Open a Pull Request
308
+
309
+ Go to your fork on GitHub and open a Pull Request against the original repository's "main" branch.
310
+
311
+ Include:
312
+
313
+ - A clear title
314
+ - Description of the changes
315
+ - Reason for the contribution
316
+ - Related issue, if applicable
317
+ - Testing performed
318
+ - Screenshots or terminal output when useful
319
+
320
+ ---
321
+
322
+ 📝 Pull Request Guidelines
323
+
324
+ A good Pull Request should:
325
+
326
+ - Solve one focused problem.
327
+ - Follow the existing project architecture.
328
+ - Include tests for new behavior.
329
+ - Pass TypeScript checks.
330
+ - Pass automated tests.
331
+ - Build successfully.
332
+ - Update documentation when necessary.
333
+ - Avoid unrelated changes.
334
+
335
+ Pull Requests may be reviewed and requested to be revised before merging.
336
+
337
+ ---
338
+
339
+ 🐛 Reporting Bugs
340
+
341
+ Found a bug?
342
+
343
+ Please open a GitHub Issue:
344
+
345
+ https://github.com/rsavnani18/pixelkit-cli/issues
346
+
347
+ Include:
348
+
349
+ 1. A clear description of the problem.
350
+ 2. Steps to reproduce it.
351
+ 3. Expected behavior.
352
+ 4. Actual behavior.
353
+ 5. Node.js and operating system versions.
354
+ 6. Relevant terminal output or screenshots.
355
+
356
+ Please avoid including private information in issue reports.
357
+
358
+ ---
359
+
360
+ 💡 Suggesting Features
361
+
362
+ Have an idea for PixelKit?
363
+
364
+ We welcome suggestions for:
365
+
366
+ - New image converters
367
+ - Better image optimization
368
+ - Improved terminal interactions
369
+ - Batch conversion capabilities
370
+ - Performance improvements
371
+ - Developer experience enhancements
372
+
373
+ Open a GitHub Issue and describe the problem your proposed feature solves.
374
+
375
+ For larger changes, discuss the idea before investing time in implementation.
376
+
377
+ ---
378
+
379
+ 📜 License
380
+
381
+ By contributing to PixelKit CLI, you agree that your contributions will be licensed under the project's "MIT License" (LICENSE).
382
+
383
+ ---
384
+
385
+ 💙 Thank You
386
+
387
+ Every bug report, documentation improvement, test, suggestion, and Pull Request helps PixelKit become better.
388
+
389
+ Thank you for helping build an open-source image conversion toolkit for developers.
390
+
391
+ <p align="center">
392
+ <b>Built for developers. Powered by PixelKit.</b>
393
+ </p><p align="center">
394
+ Made with ❤️ by <a href="https://github.com/rsavnani18">Rahul Savnani</a>
395
+ </p>
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rahul Savnani
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.