@nathievzm/lumi 1.1.5 → 1.2.0

package/.env.example

@@ -1,11 +1,12 @@
-# Default target dimensions for images
-WIDTH = '800'
-HEIGHT = '600'
-
-# Default folder paths (can be relative or absolute)
-INPUT_FOLDER = './input'
-OUTPUT_FOLDER = './output'
-
-# Default processing settings
-FORMAT = '.webp'
-LIMIT = '10'
+# Default target dimensions for images
+WIDTH = '800'
+HEIGHT = '600'
+
+# Default folder paths (can be relative or absolute)
+INPUT_FOLDER = './input'
+OUTPUT_FOLDER = './output'
+
+# Default processing settings
+FORMAT = '.webp'
+LIMIT = '10'
+RECURSIVE = 'false'

package/.github/github.d.ts

@@ -0,0 +1,8 @@
+declare module 'bun' {
+    interface Env {
+        /**
+         * The GitHub personal access token used for authentication in GitHub Actions scripts.
+         */
+        GITHUB_TOKEN?: string
+    }
+}

package/.github/scripts/add-labels-pr.ts

@@ -0,0 +1,44 @@
+import { exit } from 'node:process'
+
+import { type PullRequest } from '@octokit/webhooks-types'
+
+import { context, octokit } from './octokit'
+
+const isPullRequest = (data: unknown): data is PullRequest =>
+    typeof data === 'object' && data !== null && 'head' in data
+
+const pullRequest = context.payload.pull_request
+
+if (!isPullRequest(pullRequest)) {
+    throw new Error('this event does not contain a pull request! 😢')
+}
+
+const branch = /\w+\/(\d+)-\w+/v.exec(pullRequest.head.ref)
+
+if (branch === null || branch.length < 2 || branch[1] === undefined) {
+    console.log(`skipping: branch ${pullRequest.head.ref} does not match the issue format. ⏭️`)
+    exit(0)
+}
+
+const issueNumber = Number(branch[1])
+
+const { data: issue, status } = await octokit.rest.issues.get({
+    issue_number: issueNumber,
+    owner: context.repo.owner,
+    repo: context.repo.repo
+})
+
+if (status !== 200) {
+    throw new Error('failed to fetch the issue! 😟')
+}
+
+const labels = issue.labels
+    .map(label => (typeof label === 'string' ? label : label.name))
+    .filter((name): name is string => typeof name === 'string' && name.length > 0)
+
+await octokit.rest.issues.addLabels({
+    issue_number: context.issue.number,
+    labels,
+    owner: context.repo.owner,
+    repo: context.repo.repo
+})

package/.github/scripts/auto-assign.ts

@@ -0,0 +1,8 @@
+import { context, octokit } from './octokit'
+
+await octokit.rest.issues.addAssignees({
+    assignees: [context.actor],
+    issue_number: context.issue.number,
+    owner: context.repo.owner,
+    repo: context.repo.repo
+})

package/.github/scripts/octokit.ts

@@ -0,0 +1,10 @@
+import { context, getOctokit } from '@actions/github'
+
+const token = Bun.env.GITHUB_TOKEN
+
+if (token === undefined) {
+    throw new Error('GITHUB_TOKEN is missing! 😭')
+}
+
+const octokit = getOctokit(token)
+export { context, octokit }

package/.github/workflows/add-labels-pr.yml

@@ -0,0 +1,20 @@
+name: add labels from issue to pull request
+
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  add-labels:
+    runs-on: ubuntu-latest
+    steps:
+      - name: check out repository code
+        uses: actions/checkout@v6
+      - name: set up bun
+        uses: oven-sh/setup-bun@v2
+      - name: install dependencies
+        run: bun install
+      - name: run bun script to add labels from issue to pull request
+        run: bun .github/scripts/add-labels-pr
+        env:
+          GITHUB_TOKEN: ${{ secrets.LUMI_ADD_LABELS_PR }}

package/.github/workflows/auto-assign.yml

@@ -1,4 +1,6 @@
-name: auto assign author
+name: auto assign author to issue or pr
+
+run-name: ${{ github.actor }} is automatically assigned to the issue or pr they just opened ✅
 
 on:
   issues:
@@ -9,22 +11,14 @@ on:
 jobs:
   assign:
     runs-on: ubuntu-latest
-    permissions:
-      issues: write
-      pull-requests: write
     steps:
-      - name: assign the user who opened the ticket or pr
-        uses: actions/github-script@v7
-        with:
-          github-token: ${{ secrets.LUMI_AUTOASSIGN_TOKEN }}
-          script: |
-            // grab the username of the person who triggered the action
-            const author = context.actor
-
-            // tell github's api to assign the ticket to that username
-            await github.rest.issues.addAssignees({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-              assignees: [author]
-            })
+      - name: check out repository code
+        uses: actions/checkout@v6
+      - name: set up bun
+        uses: oven-sh/setup-bun@v2
+      - name: install dependencies
+        run: bun install
+      - name: run bun script to auto-assign the author
+        run: bun .github/scripts/auto-assign
+        env:
+          GITHUB_TOKEN: ${{ secrets.LUMI_AUTOASSIGN }}

package/.jules/bolt.md

@@ -0,0 +1,62 @@
+## 2026-05-12 - [Optimizing Array & Set Operations]
+
+**Learning:** In hot paths handling large numbers of files, using chained array methods like `.flatMap()`, `new Set()`,
+spread operators, and `.filter()` creates unnecessary intermediate arrays and memory allocations. Furthermore,
+repeatedly creating static Sets inside functions adds unnecessary O(N) overhead per call.
+
+**Action:** When iterating over potentially large lists (like file paths), favor a single-pass `for...of` loop over
+chained array methods to minimize memory footprint. Always pull static Set creation outside of function scopes to
+initialize them once at the module level.
+
+## 2026-05-15 - [Avoid Caching in Run-Once CLI Apps]
+
+**Learning:** Implementing in-memory caching (like storing `sharp.format` values in a module-scoped variable) is
+ineffective and adds unnecessary complexity in a CLI application that has a strictly 'run-once-and-exit' lifecycle. The
+cache is built but never reused because the process terminates immediately after its primary task.
+
+**Action:** Always consider the application's lifecycle (e.g., long-running server vs. short-lived CLI script) before
+introducing caching or memoization. Prefer pure functions, readability, and KISS/YAGNI principles over
+micro-optimizations that create global mutable state without a measurable benefit in the specific execution context.
+
+## 2024-05-18 - [Replace Heavy Polyfills with Native APIs]
+
+**Learning:** Using heavy polyfills like `@js-temporal/polyfill` solely for simple duration measurement introduces
+significant (~90ms) startup overhead, which is detrimental to CLI performance.
+
+**Action:** Always prefer native APIs like `performance.now()` for simple duration tracking to avoid the overhead of
+parsing and instantiating large external libraries.
+
+## 2024-05-19 - [Avoid Awaiting Dynamic Imports in Critical Path]
+
+**Learning:** Using \`await import(...)\` for a heavy module during the synchronous CLI startup phase blocks execution,
+failing to deliver the intended performance benefit of a dynamic import (it just shifts the penalty to a different
+point).
+
+**Action:** If deferring a heavy module for a non-critical side effect (like update checking), use promise chaining
+(\`.then().catch()\`) without \`await\` to allow the main execution thread to continue immediately.
+
+## 2025-02-14 - [Dynamic Import of Heavy Modules in CLI]
+
+**Learning:** `sharp` is a heavyweight module that blocks execution for >130ms on import. This severely impacts the
+startup time of the CLI, making `lumi --help` and error reporting feel slow.
+
+**Action:** Used dynamic imports (`await import('sharp')`) to lazily load the library only when image processing methods
+(`resize` and `getSharpFormats`) are called. This avoids importing `sharp` during the synchronous CLI startup path.
+
+## 2024-05-18 - Avoid typeof on imported default types
+
+**Learning:** When asserting a type on a dynamically imported module by extracting its default export (e.g.
+`typeof sharp`), the `typeof` keyword must not be applied if the module has been imported specifically into the type
+space via `import { type default as sharp } from 'sharp'`. Applying `typeof` to a type-only import results in a `TS2693`
+compilation error because `typeof` operates on values, not types.
+
+**Action:** When strictly importing types to satisfy `import(consistent-type-specifier-style)`, directly apply the
+imported type without `typeof`.
+
+## 2025-05-25 - [Optimize getImages path resolution]
+
+**Learning:** `resolve` is significantly slower than `join` in Node's path module, particularly within tight loops.
+Repeatedly resolving a known directory prefix causes measurable overhead when processing large volumes of files.
+
+**Action:** Whenever iterating over many files that share a base directory, `resolve` the base directory once outside
+the loop and use `join(resolvedBase, file)` inside the loop to drastically improve performance.

package/.jules/palette.md

@@ -0,0 +1,58 @@
+## 2026-05-12 - Added error output for failed images
+
+**Learning:** Users need to know exactly which images failed during batch processing. An overall error message is not
+actionable.
+
+**Action:** Always output detailed errors for individual batch items when a batch process fails, even if it adds to
+terminal noise, because the user needs to correct specific items.
+
+## 2026-05-13 - Friendly CLI Errors
+
+**Learning:** Raw stack traces from unhandled Promise rejections (like `readdir` on a non-existent directory) are
+intimidating for CLI users.
+
+**Action:** Always wrap file I/O operations in `try...catch` blocks and use UI logging tools (like `@clack/prompts`) to
+provide actionable, human-readable error messages before gracefully exiting.
+
+## 2026-05-14 - Default CLI Prompt Values
+
+**Learning:** When prompting users for repeated or common file conversions, failing to default to the original format
+creates unnecessary friction. Users expect smart defaults that save keystrokes.
+
+**Action:** Always set an `initialValue` in CLI selection prompts (`@clack/prompts`) where a logical default exists,
+such as defaulting to a file's original extension during conversion options.
+
+## 2026-05-18 - Rejected Default Value for Dimensions
+
+**Learning:** Adding a strict `defaultValue` (e.g., '1080') to the dimensions prompt overrides the helpful `placeholder`
+text visually in the UI, making the interface less descriptive and potentially confusing for users who need custom
+sizes.
+
+**Action:** Prioritize descriptive placeholders over hardcoded default values for free-text inputs where the user might
+legitimately need a wide variety of formats (like dimensions).
+
+## 2026-05-20 - Rejected Initial Value for Dimensions
+
+**Learning:** Using `initialValue` for dimensions also overrides the `placeholder` text visually in the UI just like
+`defaultValue` does, making the interface less descriptive since users can't see that they can provide two values.
+
+**Action:** Avoid using `initialValue` or `defaultValue` in free-text inputs like dimensions, where a helpful
+placeholder explaining multiple formats is more valuable.
+
+## 2025-02-23 - Use placeholder instead of initialValue for CLI text prompts with descriptive help
+
+**Learning:** In CLI text prompts (like @clack/prompts), `initialValue` fills the text field, which hides any
+descriptive `placeholder` text that would otherwise provide helpful instructions to the user. Using no `initialValue`
+(or `defaultValue`) ensures the `placeholder` remains visible, guiding the user on the expected input format without
+them needing to clear the field first.
+
+**Action:** Avoid setting an `initialValue` in CLI text prompts when a descriptive `placeholder` is present, to ensure
+the helpful placeholder text remains visible to the user.
+
+## 2026-05-25 - Actionable Empty State Errors
+
+**Learning:** When users run the tool on a directory that has images in subfolders but not in the root, an error simply
+stating "no valid images found" is confusing and unhelpful.
+
+**Action:** Always provide actionable hints in empty states or error messages, such as suggesting the `--recursive`
+flag, to guide the user toward a solution.

package/.jules/sentinel.md

@@ -0,0 +1,70 @@
+## 2026-05-12 - Fix Missing Input Length Limits (DoS Risk)
+
+**Vulnerability:** Denial of Service (DoS) vulnerability via resource exhaustion caused by unconstrained width and
+height parameters during image resizing with Sharp.
+
+**Learning:** Tools handling image processing can easily be abused to consume excessive memory if user-provided
+dimensions are unchecked, potentially crashing the Node.js/Bun process.
+
+**Prevention:** Implement strict length and dimension validation boundaries for all user input governing asset
+generation, catching errors gracefully without leaking system details.
+
+## 2026-05-14 - Fix Path Traversal in Image Output
+
+**Vulnerability:** A path traversal vulnerability existed in `src/lib/image.ts`. The output file path was constructed by
+blindly concatenating user input (`cli.format` passed as `extension`) using `join`. An attacker could pass a format
+string like `/../../../tmp/evil.png` to write files to arbitrary locations outside the intended output directory.
+
+**Learning:** We must not blindly trust user input that influences file paths, especially file extensions or format
+modifiers. When working with Node.js `path.join`, it resolves relative segments, which can escape the current directory.
+
+**Prevention:** Always validate constructed file paths. Before performing any file operation, resolve the final output
+path and check if it strictly starts with the resolved target directory path to prevent path traversals.
+
+## 2026-05-18 - [Path Traversal in Input Resolution]
+
+**Vulnerability:** The application was vulnerable to path traversal because it resolved the input image path via
+`join(input, image)` and passed it directly to `sharp` without validation.
+
+**Learning:** Even though the `outputPath` was properly guarded against path traversal, the missing guard on `inputPath`
+could allow an attacker to read arbitrary files off the filesystem by specifying a malicious `image` filename with `../`
+sequences.
+
+**Prevention:** Always sanitize and guard both input and output paths to ensure they strictly reside within the intended
+boundaries.
+
+## 2026-05-19 - [Null Byte Injection in Path Resolution]
+
+**Vulnerability:** The `guard` function used to prevent path traversal was relying on `node:path`'s `resolve` and
+`startsWith` to verify paths. However, strings containing null bytes (`\0`) could cause `resolve` to behave unexpectedly
+or terminate strings prematurely in underlying C++ extensions or certain filesystem API scenarios, effectively bypassing
+the `startsWith` validation check.
+
+**Learning:** Node's built-in path module does not inherently protect against null byte injection, and combining strings
+with null bytes can lead to bypassing directory containment checks.
+
+**Prevention:** Always explicitly check for and reject null bytes (`\0`) in user-supplied paths before using them in
+file system operations or path resolutions.
+
+## 2026-05-20 - [Null Byte Injection in Folder Parameter]
+
+**Vulnerability:** While the `guard` function previously checked for null bytes (`\0`) in the `path` parameter, it
+neglected to perform the same check on the `folder` parameter. This inconsistency left a potential path traversal bypass
+vector open if the base folder path itself originated from untrusted input.
+
+**Learning:** Null byte injection protections must be consistently applied to all path components involved in a security
+boundary check, not just the immediately obvious file path.
+
+**Prevention:** Ensure comprehensive null byte validation (`\0`) on all path inputs (both base directories and target
+paths) prior to resolving them with `node:path` functions.
+
+## 2025-05-21 - Early Path Component Validation
+
+**Vulnerability:** Path traversal and null byte injection vectors existed because inputs to `node:path` functions were
+not sanitised early enough.
+
+**Learning:** By passing an unsanitised component into `node:path` functions like `join`, a null byte could prematurely
+terminate strings and bypass directory boundary checks.
+
+**Prevention:** Explicitly reject null bytes ('\0') in all user-provided path components before passing them to
+`node:path` functions or combining them.

package/.oxlintrc.json

@@ -24,7 +24,8 @@
         "no-continue": "off",
         "require-param-type": "off",
         "require-returns-type": "off",
-        "max-dependencies": ["warn", { "max": 16 }]
+        "max-dependencies": ["warn", { "max": 16 }],
+        "max-classes-per-file": ["warn", { "max": 3 }]
     },
     "env": {
         "builtin": true

package/.vscode/settings.json

@@ -5,7 +5,9 @@
     "oxc.enable.oxlint": true,
     "oxc.enable.oxfmt": true,
     "editor.codeActionsOnSave": {
-        "source.fixAll.oxc": "always"
+        "source.fixAll.oxc": "always",
+        "source.format.oxc": "always",
+        "source.fixAll": "always"
     },
     "files.insertFinalNewline": false,
     "files.trimTrailingWhitespace": true

package/CHANGELOG.md

@@ -1,3 +1,84 @@
+# [1.2.0](https://github.com/nathievzm/lumi/compare/v1.1.6...v1.2.0) (2026-05-29)
+
+### Bug Fixes
+
+- guard function and recursive flag
+  ([41fcb3e](https://github.com/nathievzm/lumi/commit/41fcb3e38c7c271971543b2cc38665f7c545c9c2))
+
+### Features
+
+- **image:** cache sharp dynamic import promise to improve performance
+  ([08a02fd](https://github.com/nathievzm/lumi/commit/08a02fd0a166dfd3587b76c9635fee323ddff38c))
+- **ui:** add initialValue to dimensions prompt to reduce user friction
+  ([b72ccaf](https://github.com/nathievzm/lumi/commit/b72ccafe8dfbd66d35a5b3abbe727500f36e5921))
+- **ux:** add initialValue to askWidthAndHeight prompt
+  ([027ec53](https://github.com/nathievzm/lumi/commit/027ec536da421716121f306fefa5d23fa5c49696))
+- **ux:** add initialValue to askWidthAndHeight prompt
+  ([a095643](https://github.com/nathievzm/lumi/commit/a09564304ba0b49d3e9d2d45ed64a9460c578a97))
+- **ux:** update journal learning about initialValue vs placeholder
+  ([80c873f](https://github.com/nathievzm/lumi/commit/80c873fb16ded0ad9b098670f92f9839cf0c66d7))
+- **ux:** update journal learning about initialValue vs placeholder
+  ([3f75765](https://github.com/nathievzm/lumi/commit/3f7576541d7792a0004e8ba2dddb8d8873106303))
+- **ux:** update journal learning about initialValue vs placeholder
+  ([b56fd87](https://github.com/nathievzm/lumi/commit/b56fd876ee00478efe24b604c5084e8c27d49509))
+
+### Performance Improvements
+
+- **image:** lazily load heavy sharp module to improve startup time
+  ([5c3c9a4](https://github.com/nathievzm/lumi/commit/5c3c9a424e21d46c7830feb5e80517a4e274ba91))
+- optimize path resolution in `getImages`
+  ([1b91635](https://github.com/nathievzm/lumi/commit/1b91635306851cd1840e1a11b9eacd361741993d))
+
+### Reverts
+
+- Remove initialValue from dimension prompt to show placeholder
+  ([06b9a0c](https://github.com/nathievzm/lumi/commit/06b9a0c35089d89d056fecc8ff50e7a31b34a789))
+
+## [1.1.6](https://github.com/nathievzm/lumi/compare/v1.1.5...v1.1.6) (2026-05-19)
+
+### Bug Fixes
+
+- prevent path traversal on input image resolution
+  ([cfe9f2a](https://github.com/nathievzm/lumi/commit/cfe9f2a78d570b63fbfe2051bc21b13710930c0e))
+- **prompt:** remove defaultValue to prefer descriptive placeholder
+  ([bf63182](https://github.com/nathievzm/lumi/commit/bf631822bf0ab3c9bbc99600692ca7143d651bb6))
+- remove step that logs the whole github json
+  ([1ff461d](https://github.com/nathievzm/lumi/commit/1ff461d9192421c6562d85436e45d30fd0b22085))
+- revert changes from jules
+  ([2a4db48](https://github.com/nathievzm/lumi/commit/2a4db4843b381da26fb42b1c11839f469029e78e))
+
+### Features
+
+- add code to add the issue labels to the pr
+  ([d8b5d87](https://github.com/nathievzm/lumi/commit/d8b5d8789879f76a9969a67223593db89638a3ac))
+- add test workflow to sync pr with issue
+  ([a4f8e10](https://github.com/nathievzm/lumi/commit/a4f8e1032d12283a456003d5d274bef98914028f))
+- add ts script to get pull request
+  ([c7f0e2d](https://github.com/nathievzm/lumi/commit/c7f0e2d9b20b0040889d6dcae76b62eaf5fb17f9))
+- log found connected found issue
+  ([edb6375](https://github.com/nathievzm/lumi/commit/edb6375a3881361afc0819b27f71418d560d62b4))
+- move notify function to update module
+  ([d701256](https://github.com/nathievzm/lumi/commit/d701256b69b54eae195090ff23dd4ed64f2b0cc1))
+- **prompt:** add default value to dimension prompt
+  ([7271ae5](https://github.com/nathievzm/lumi/commit/7271ae5aaef008a8024b916deaae6d6465b9c7bc))
+- remove error when branch doesn't have correct format
+  ([03fc8fb](https://github.com/nathievzm/lumi/commit/03fc8fb50466cedd78b959b51c52cd5c52800144))
+- replace auto-assign workflow with ts script and bun action
+  ([aeda5fa](https://github.com/nathievzm/lumi/commit/aeda5fa6d09b030a50c079c0ca628ecbd1cd3d50))
+- replace small try/catch by global try/catch block with new errors
+  ([74f3d2c](https://github.com/nathievzm/lumi/commit/74f3d2cff8f95e7d521670d9eefca55510ccd3e9))
+- use gh script action to run js scripts
+  ([3afe134](https://github.com/nathievzm/lumi/commit/3afe134d76c5d7d14c7cd1dbdce384e0507d5f48))
+
+### Performance Improvements
+
+- cache sharp formats to avoid redundant computation
+  ([3eea037](https://github.com/nathievzm/lumi/commit/3eea037679b3b9677a13fa4898c2bb81ff31b0c9))
+- cache sharp formats to avoid redundant computation and fix CI
+  ([4eeea88](https://github.com/nathievzm/lumi/commit/4eeea88ce1daebafcf8417e996dde515aa6fbf86))
+- replace @js-temporal/polyfill with performance.now()
+  ([e28a380](https://github.com/nathievzm/lumi/commit/e28a38065d9f5bc08ea31d04fa37d7e171f42d29))
+
 ## [1.1.5](https://github.com/nathievzm/lumi/compare/v1.1.4...v1.1.5) (2026-05-14)
 
 ### Bug Fixes

package/README.md

@@ -14,6 +14,7 @@ A fast, interactive CLI tool for batch image processing. Resize, convert, and op
 - **Animated Support:** Seamlessly handles animated GIFs and WebP files.
 - **Concurrency Control:** Fine-tune performance with configurable processing limits.
 - **Environment Driven:** Fully configurable via `.env` files or CLI flags.
+- **Update Notifications:** Automatically alerts you when a new version is available.
 
 ## 📦 Installation
 
@@ -111,6 +112,7 @@ bun install
 - `bun fmt:check`: Check for formatting issues.
 - `bun changelog`: Update the changelog.
 - `bun release`: Release a new version with `bumpp` and update the changelog.
+- `bun prepare`: Install git hooks with `lefthook`.
 
 ## 📄 License
 

package/lefthook.yml

@@ -1,9 +1,6 @@
 pre-commit:
-  # running all checks at the same time for maximum speed ⚡
-  parallel: true
   jobs:
     - name: format
-      glob: '*.{ts,js,json,yml,yaml,md}'
       run: bun fmt && git add .
 
     - name: lint
@@ -15,7 +12,6 @@ pre-commit:
 commit-msg:
   jobs:
     - name: commitlint
-      # using bun to run commitlint as fast as possible 🌸
       run: bunx --bun commitlint --edit {1}
 
 pre-push:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nathievzm/lumi",
-    "version": "1.1.5",
+    "version": "1.2.0",
     "description": "a concurrent cli tool to resize and convert images using bun and sharp",
     "keywords": [
         "bun",
@@ -50,8 +50,7 @@
         "start": "bun src/index.ts"
     },
     "dependencies": {
-        "@clack/prompts": "^1.3.0",
-        "@js-temporal/polyfill": "^0.5.1",
+        "@clack/prompts": "^1.4.0",
         "boxen": "^8.0.1",
         "image-extensions": "^1.1.0",
         "p-limit": "^7.3.0",
@@ -60,15 +59,17 @@
         "update-notifier": "^7.3.1"
     },
     "devDependencies": {
+        "@actions/github": "^9.1.1",
         "@commitlint/cli": "^20.5.3",
         "@commitlint/config-conventional": "^20.5.3",
+        "@octokit/webhooks-types": "^7.6.1",
         "@types/bun": "latest",
         "@types/update-notifier": "^6.0.8",
         "bumpp": "^11.1.0",
         "conventional-changelog-cli": "^5.0.0",
         "lefthook": "^2.1.6",
         "oxfmt": "^0.47.0",
-        "oxlint": "^1.64.0",
+        "oxlint": "^1.65.0",
         "oxlint-tsgolint": "^0.22.1",
         "typescript": "^6.0.3"
     }

package/src/env.d.ts

@@ -1,27 +1,27 @@
 declare module 'bun' {
     interface Env {
         /**
-         * Default target width for resized images.
+         * The default target width in pixels for resized images.
          */
         WIDTH?: string
         /**
-         * Default target height for resized images.
+         * The default target height in pixels for resized images.
          */
         HEIGHT?: string
         /**
-         * Default path to the input folder containing images.
+         * The default path to the input directory containing source images.
          */
         INPUT_FOLDER?: string
         /**
-         * Default path where processed images will be saved.
+         * The default path to the destination directory where processed images will be saved.
          */
         OUTPUT_FOLDER?: string
         /**
-         * Default global output format (e.g., '.webp', '.png').
+         * The default global output format extension (e.g., `.webp`, `.png`).
          */
         FORMAT?: string
         /**
-         * Default concurrent processing limit.
+         * The default concurrent processing limit.
          */
         LIMIT?: string
         /**