@nathievzm/lumi 1.1.5 → 1.1.6

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,36 @@
+## 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.

package/.jules/palette.md

@@ -0,0 +1,32 @@
+## 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).

package/.jules/sentinel.md

@@ -0,0 +1,47 @@
+## 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.

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,48 @@
+## [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

@@ -3,7 +3,6 @@ pre-commit:
   parallel: true
   jobs:
     - name: format
-      glob: '*.{ts,js,json,yml,yaml,md}'
       run: bun fmt && git add .
 
     - name: lint

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nathievzm/lumi",
-    "version": "1.1.5",
+    "version": "1.1.6",
     "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
         /**

package/src/index.ts

@@ -1,130 +1,119 @@
 #!/usr/bin/env bun
 
-import { readdir } from 'node:fs/promises'
 import { basename, extname } from 'node:path'
 import { exit } from 'node:process'
 
 import { intro, log, note, outro, spinner } from '@clack/prompts'
-import { Temporal } from '@js-temporal/polyfill'
 import boxen from 'boxen'
 import pLimit from 'p-limit'
 import color from 'picocolors'
-import updateNotifier from 'update-notifier'
 
 import { cli } from '@/args'
-import { getMessage } from '@/error'
-import { getInput, getOutput, prepare } from '@/folder'
+import { FolderError, ImageError, LumiError } from '@/error'
+import { getInput, getOutput, prepare, readFiles } from '@/folder'
 import { getExtensions, getImages, getWidthAndHeight, resize } from '@/image'
+import { notifyUpdate } from '@/update'
 
 import pkg from '../package.json' with { type: 'json' }
 
-const notifier = updateNotifier({ pkg })
-notifier.notify({
-    boxenOptions: { borderColor: 'magenta', borderStyle: 'round', padding: 1 }
-})
+try {
+    void notifyUpdate(pkg)
 
-console.clear()
+    console.clear()
 
-const banner = boxen('lumi', {
-    backgroundColor: 'magenta',
-    borderColor: 'magenta',
-    borderStyle: 'round',
-    padding: { bottom: 2, left: 15, right: 15, top: 2 },
-    textAlignment: 'center'
-})
+    const banner = boxen('lumi', {
+        backgroundColor: 'magenta',
+        borderColor: 'magenta',
+        borderStyle: 'round',
+        padding: { bottom: 2, left: 15, right: 15, top: 2 },
+        textAlignment: 'center'
+    })
 
-console.log(banner, '\n')
+    console.log(banner, '\n')
 
-intro(color.magenta(`welcome to lumi v${pkg.version} 🩷`))
+    intro(color.magenta(`welcome to lumi v${pkg.version} 🩷`))
 
-const input = getInput(cli.input)
-const output = getOutput(cli.output)
-await prepare(output)
+    const input = getInput(cli.input)
+    const output = getOutput(cli.output)
+    await prepare(output)
 
-let allFiles: string[] = []
+    const allFiles = await readFiles(input, cli.recursive)
+    const images = getImages(allFiles)
 
-try {
-    allFiles = await readdir(input, { recursive: cli.recursive })
-} catch (error) {
-    const message = getMessage(error)
-    log.error(`yikes! couldn't read the input folder: ${message} 😢`)
-    outro('please check your input path and try again 👋')
-    exit(1)
-}
+    if (images.length === 0) {
+        throw new ImageError('no valid images found in the input folder 😭')
+    }
 
-const images = getImages(allFiles)
+    note(`found ${color.magenta(images.length)} images to process! 🚀`)
 
-if (images.length === 0) {
-    log.error('yikes! no valid images found in the input folder 😭')
-    outro('please add some images to the input folder and try again 👋')
-    exit(1)
-}
+    const { width, height } = await getWidthAndHeight(cli.width, cli.height)
+    const extensions = await getExtensions(images, cli.format)
 
-note(`found ${color.magenta(images.length)} images to process! 🚀`)
+    const limit = pLimit({ concurrency: cli.limit || 10, rejectOnClear: true })
 
-let dimensions = { height: 0, width: 0 }
+    const spin = spinner()
+    spin.start(`processing: ${color.magenta(0)}/${color.magenta(images.length)} images 🔃`)
 
-try {
-    dimensions = await getWidthAndHeight(cli.width, cli.height)
-} catch (error: unknown) {
-    const message = getMessage(error)
-    log.error(message)
-    outro('please check your input dimensions and try again 🛠️')
-    exit(1)
-}
+    let processed = 0
 
-const { width, height } = dimensions
+    const startTime = performance.now()
 
-const extensions = await getExtensions(images, cli.format)
-const limit = pLimit({ concurrency: cli.limit || 10, rejectOnClear: true })
+    const promises = images.map(image =>
+        limit(async () => {
+            const ext = extname(image)
+            const name = basename(image, ext)
+            const extension = extensions['default'] ?? extensions[ext] ?? '.png'
 
-const spin = spinner()
-spin.start(`processing: ${color.magenta(0)}/${color.magenta(images.length)} images 🔃`)
+            await resize({ extension, height, image, input, name, output, width })
 
-let processed = 0
-
-const startTime = Temporal.Now.instant()
-
-const promises = images.map(image =>
-    limit(async () => {
-        const ext = extname(image)
-        const name = basename(image, ext)
-        const extension = extensions['default'] ?? extensions[ext] ?? '.png'
-
-        await resize({ extension, height, image, input, name, output, width })
+            processed++
+            spin.message(`processing: ${color.green(processed)}/${color.magenta(images.length)} images 🔃`)
+        })
+    )
 
-        processed++
-        spin.message(`processing: ${color.green(processed)}/${color.magenta(images.length)} images 🔃`)
-    })
-)
+    log.message()
 
-log.message()
+    const result = await Promise.allSettled(promises)
 
-const result = await Promise.allSettled(promises)
+    const endTime = performance.now()
+    const duration = ((endTime - startTime) / 1000).toFixed(2)
 
-const endTime = Temporal.Now.instant()
-const duration = startTime.until(endTime).total('seconds').toFixed(2)
+    let outroMessage = ''
 
-let outroMessage = ''
+    if (result.some(pr => pr.status === 'rejected')) {
+        spin.error(
+            `yikes! finished with errors. processed ${color.red(processed)}/${color.red(images.length)} images in ${color.yellow(duration)} seconds 😢`
+        )
 
-if (result.some(pr => pr.status === 'rejected')) {
-    spin.error(
-        `yikes! finished with errors. processed ${color.red(processed)}/${color.red(images.length)} images in ${color.yellow(duration)} seconds 😢`
-    )
+        for (const pr of result) {
+            if (pr.status === 'fulfilled') {
+                continue
+            }
 
-    for (const pr of result) {
-        if (pr.status === 'fulfilled') {
-            continue
+            const message = LumiError.getMessage(pr.reason)
+            log.error(color.red(message))
         }
 
-        const message = getMessage(pr.reason)
-        log.error(message)
+        outroMessage = 'please check your input files and try again 🛠️'
+    } else {
+        spin.stop(
+            `yay! ${color.green(images.length)} images processed in ${color.green(duration)} seconds! \u26A1\uFE0F`
+        )
+        outroMessage = 'bye 👋'
     }
 
-    outroMessage = 'please check your input files and try again 🛠️'
-} else {
-    spin.stop(`yay! ${color.green(images.length)} images processed in ${color.green(duration)} seconds! \u26A1\uFE0F`)
-    outroMessage = 'bye 👋'
-}
+    outro(color.magenta(outroMessage))
+} catch (error) {
+    const message = LumiError.getMessage(error)
+
+    if (error instanceof FolderError) {
+        log.error(color.red(`folder issue: ${message}`))
+    } else if (error instanceof ImageError) {
+        log.error(color.red(`image issue: ${message}`))
+    } else {
+        log.error(color.red(`unexpected anomaly: ${message} 👽`))
+    }
 
-outro(color.magenta(outroMessage))
+    outro(color.magenta('please check your configuration and try again 👋'))
+    exit(1)
+}

package/src/lib/args.ts

@@ -5,7 +5,7 @@ const { values } = parseArgs({
     args: Bun.argv.slice(2),
     options: {
         /**
-         * Global output format. Defaults to `FORMAT` env var.
+         * Global output format. Defaults to the `FORMAT` environment variable.
          */
         format: {
             default: Bun.env.FORMAT,
@@ -13,7 +13,7 @@ const { values } = parseArgs({
             type: 'string'
         },
         /**
-         * Target height. Defaults to `HEIGHT` env var.
+         * Target height. Defaults to the `HEIGHT` environment variable.
          */
         height: {
             default: Bun.env.HEIGHT,
@@ -21,7 +21,7 @@ const { values } = parseArgs({
             type: 'string'
         },
         /**
-         * Input directory path. Defaults to `INPUT_FOLDER` env var.
+         * Input directory path. Defaults to the `INPUT_FOLDER` environment variable.
          */
         input: {
             default: Bun.env.INPUT_FOLDER,
@@ -29,7 +29,7 @@ const { values } = parseArgs({
             type: 'string'
         },
         /**
-         * Concurrent processing limit. Defaults to `LIMIT` env var.
+         * Concurrent processing limit. Defaults to the `LIMIT` environment variable.
          */
         limit: {
             default: Bun.env.LIMIT,
@@ -37,7 +37,7 @@ const { values } = parseArgs({
             type: 'string'
         },
         /**
-         * Output directory path. Defaults to `OUTPUT_FOLDER` env var.
+         * Output directory path. Defaults to the `OUTPUT_FOLDER` environment variable.
          */
         output: {
             default: Bun.env.OUTPUT_FOLDER,
@@ -45,7 +45,7 @@ const { values } = parseArgs({
             type: 'string'
         },
         /**
-         * Whether to process the input directory recursively. Defaults to `RECURSIVE` env var.
+         * Whether to process the input directory recursively. Defaults to the `RECURSIVE` environment variable.
          */
         recursive: {
             default: Boolean(Bun.env.RECURSIVE),
@@ -60,7 +60,7 @@ const { values } = parseArgs({
             type: 'string'
         },
         /**
-         * Target width. Defaults to `WIDTH` env var.
+         * Target width. Defaults to the `WIDTH` environment variable.
          */
         width: {
             default: Bun.env.WIDTH,
@@ -83,6 +83,7 @@ const { input, output, format, recursive } = values
 
 /**
  * The consolidated CLI configuration object.
+ *
  * Contains resolved paths, dimensions, and processing limits.
  */
 export const cli = { format, height, input, limit, output, recursive, width }

package/src/lib/error.ts

@@ -1,21 +1,68 @@
 /**
- * Safely extracts a human-readable error message from an unknown error.
+ * Base error class for all Lumi-specific errors.
  *
- * Designed for use in catch blocks where the error type is unknown,
- * ensuring a consistent string output for logging or user feedback.
- *
- * @param error - The caught error to process.
- *
- * @returns The error message string, or a fallback message if the type is unrecognized.
+ * Extends the built-in `Error` class and allows for an optional underlying cause.
  */
-export const getMessage = (error: unknown) => {
-    if (error instanceof Error) {
-        return error.message
+export class LumiError extends Error {
+    /**
+     * Creates a new `LumiError` instance.
+     *
+     * @param message - The error message.
+     * @param error - The underlying error or cause.
+     */
+    constructor(message: string, error?: unknown) {
+        super(message, { cause: error })
+        this.name = 'LumiError'
     }
 
-    if (typeof error === 'string') {
-        return error
+    /**
+     * Extracts a human-readable message from an unknown error object.
+     *
+     * @param error - The error to extract the message from.
+     *
+     * @returns The error message, or a generic string if the type is unknown.
+     */
+    static getMessage(error: unknown) {
+        if (error instanceof Error) {
+            return error.message
+        }
+
+        if (typeof error === 'string') {
+            return error
+        }
+
+        return 'an unknown error occurred'
     }
+}
 
-    return 'an unknown error occurred'
+/**
+ * Error thrown when an issue occurs with folder operations.
+ */
+export class FolderError extends LumiError {
+    /**
+     * Creates a new `FolderError` instance.
+     *
+     * @param message - The error message.
+     * @param error - The underlying error or cause.
+     */
+    constructor(message: string, error?: unknown) {
+        super(message, { cause: error })
+        this.name = 'FolderError'
+    }
+}
+
+/**
+ * Error thrown when an issue occurs with image processing operations.
+ */
+export class ImageError extends LumiError {
+    /**
+     * Creates a new `ImageError` instance.
+     *
+     * @param message - The error message.
+     * @param error - The underlying error or cause.
+     */
+    constructor(message: string, error?: unknown) {
+        super(message, { cause: error })
+        this.name = 'ImageError'
+    }
 }

package/src/lib/folder.ts

@@ -1,17 +1,19 @@
-import { exists, mkdir } from 'node:fs/promises'
+import { exists, mkdir, readdir } from 'node:fs/promises'
 import { resolve, sep } from 'node:path'
 import { cwd } from 'node:process'
 
 import { log } from '@clack/prompts'
 import color from 'picocolors'
 
+import { FolderError } from './error'
+
 /**
  * Resolves the input directory path.
  *
  * If a path is provided via CLI arguments, it resolves to that path and logs the action.
  * Otherwise, it defaults to the current working directory.
  *
- * @param input - An optional input path provided via CLI arguments.
+ * @param input - An input path provided via CLI arguments.
  *
  * @returns The resolved input directory path.
  */
@@ -33,7 +35,7 @@ export const getInput = (input?: string) => {
  * If a path is provided via CLI arguments, it resolves to that path and logs the action.
  * Otherwise, it defaults to an 'output' directory in the current working directory.
  *
- * @param output - An optional output path provided via CLI arguments.
+ * @param output - An output path provided via CLI arguments.
  *
  * @returns The resolved output directory path.
  */
@@ -60,13 +62,34 @@ export const getOutput = (output?: string) => {
  * @returns A promise that resolves when the directory is verified or successfully created.
  */
 export const prepare = async (output: string) => {
-    const outputExists = await exists(output)
+    try {
+        const outputExists = await exists(output)
+
+        if (!outputExists) {
+            await mkdir(output, { recursive: true })
+        }
 
-    if (!outputExists) {
-        await mkdir(output, { recursive: true })
+        log.info(`output folder ready: ${color.cyan(output)} ✨`, { spacing: 0 })
+    } catch (error) {
+        throw new FolderError(`could not prepare the output folder: ${output}`, error)
     }
+}
 
-    log.info(`output folder ready: ${color.cyan(output)} ✅`, { spacing: 0 })
+/**
+ * Reads the contents of a directory.
+ *
+ * @param input - The path to the directory to read.
+ * @param recursive - Whether to read the directory recursively. Defaults to `false`.
+ *
+ * @returns A promise that resolves to an array of file names or relative paths.
+ * @throws { FolderError } If the directory cannot be read.
+ */
+export const readFiles = async (input: string, recursive = false) => {
+    try {
+        return await readdir(input, { recursive })
+    } catch (error) {
+        throw new FolderError(`could not read the input folder: ${input}`, error)
+    }
 }
 
 /**
@@ -76,15 +99,20 @@ export const prepare = async (output: string) => {
  * @param path - The target path to verify.
  *
  * @returns `true` if the target path is securely contained within the base folder.
- * @throws { Error } If the target path resolves outside the base folder, indicating a potential path traversal attempt.
+ * @throws { FolderError } If the target path resolves outside the base folder, indicating a potential path traversal
+ *   attempt.
  */
 export const guard = (folder: string, path: string) => {
+    if (path.includes('\0')) {
+        throw new FolderError('path traversal detected 🚫')
+    }
+
     const resolved = resolve(folder)
     const resolvedPath = resolve(path)
     const normalized = resolved.endsWith(sep) ? resolved : resolved + sep
 
     if (!resolvedPath.startsWith(normalized)) {
-        throw new Error('path traversal detected 🚫')
+        throw new FolderError('path traversal detected 🚫')
     }
 
     return true

package/src/lib/image.ts

@@ -4,6 +4,7 @@ import { type Option } from '@clack/prompts'
 import imageExtensions from 'image-extensions'
 import sharp, { type AvailableFormatInfo } from 'sharp'
 
+import { ImageError } from './error'
 import { guard } from './folder'
 import { askExtensions, askWidthAndHeight } from './prompt'
 
@@ -59,7 +60,7 @@ const isFormatInfo = (value: unknown): value is AvailableFormatInfo =>
  *
  * @returns An array of prompt-compatible `Option` objects representing the supported output formats.
  */
-const getSharpFormats = () => {
+const getSharpFormats = (): Option<string>[] => {
     const sharpFormats = Object.values(sharp.format).filter(format => isFormatInfo(format))
     const formats: Option<string>[] = sharpFormats
         .filter(format => format.output.file)
@@ -94,7 +95,7 @@ export const getImages = (files: readonly string[]) => {
  * @param height - The target height parsed from CLI arguments.
  *
  * @returns A promise resolving to an object containing the validated `width` and `height`.
- * @throws { Error } If the provided or prompted dimensions exceed Sharp's 16383 pixel limit.
+ * @throws { ImageError } If the provided or prompted dimensions exceed Sharp's 16383 pixel limit.
  */
 export const getWidthAndHeight = (width: number, height: number) => {
     const notWidth = isNaN(width) || width <= 0
@@ -105,7 +106,7 @@ export const getWidthAndHeight = (width: number, height: number) => {
     }
 
     if (width > 16_383 || height > 16_383) {
-        throw new Error('dimensions must be less than 16384 pixels 🚫')
+        throw new ImageError('dimensions must be less than 16384 pixels 🚫')
     }
 
     return Promise.resolve({ height, width })
@@ -119,7 +120,7 @@ export const getWidthAndHeight = (width: number, height: number) => {
  * and prompts the user to map each original extension to a specific output format interactively.
  *
  * @param images - A readonly array of input image filenames to analyze for unique extensions.
- * @param format - An optional global output format string provided via CLI arguments.
+ * @param format - A global output format string provided via CLI arguments.
  *
  * @returns A promise resolving to a record that maps input extensions (or 'default') to their chosen output formats.
  */
@@ -150,7 +151,8 @@ export const getExtensions = (images: readonly string[], format?: string) => {
  * @param params - The configuration parameters dictating the resize and conversion operations.
  *
  * @returns A promise that resolves to a descriptive success message upon completion.
- * @throws { Error } If the image processing fails or if a path traversal attempt is detected during output resolution.
+ * @throws { ImageError } If the image processing fails or if a path traversal attempt is detected during output
+ *   resolution.
  */
 export const resize = async (params: ResizeParams) => {
     const { image, input, output, width, height, name, extension } = params
@@ -159,6 +161,7 @@ export const resize = async (params: ResizeParams) => {
         const inputPath = join(input, image)
         const outputPath = join(output, `${name}${extension}`)
 
+        guard(input, inputPath)
         guard(output, outputPath)
 
         await sharp(inputPath, { animated: true })
@@ -166,7 +169,7 @@ export const resize = async (params: ResizeParams) => {
             .toFile(outputPath)
 
         return `processed and saved: ${name}${extension} `
-    } catch (error: any) {
-        throw new Error(`error processing ${image} `, { cause: error })
+    } catch (error: unknown) {
+        throw new ImageError(`error processing ${image} `, error)
     }
 }

package/src/lib/update.ts

@@ -0,0 +1,24 @@
+import { type Package } from 'update-notifier'
+
+/**
+ * Asynchronously checks for package updates and displays a notification if an update is available.
+ *
+ * @param pkg - The package information, typically imported from package.json, used to check for updates.
+ *
+ * @returns A boolean indicating whether the update check and notification process executed without throwing an error.
+ */
+export const notifyUpdate = async (pkg: Readonly<Package>) => {
+    try {
+        const { default: updateNotifier } = await import('update-notifier')
+
+        const notifier = updateNotifier({ pkg })
+
+        notifier.notify({
+            boxenOptions: { borderColor: 'magenta', borderStyle: 'round', padding: 1 }
+        })
+
+        return true
+    } catch {
+        return false
+    }
+}

package/tsconfig.json

@@ -36,5 +36,5 @@
             "@/*": ["./src/lib/*"]
         }
     },
-    "include": ["**/*.ts", "**/*.d.ts"]
+    "include": ["**/*.ts", "**/*.d.ts", ".github/**/*.ts", ".github/**/*.d.ts"]
 }

package/.Jules/bolt.md

@@ -1,8 +0,0 @@
-## 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.

package/.Jules/palette.md

@@ -1,20 +0,0 @@
-## 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.

package/.Jules/sentinel.md

@@ -1,19 +0,0 @@
-## 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.
-
-## 2024-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.