@nathievzm/lumi 1.1.2 → 1.1.5

package/.Jules/bolt.md

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

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

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

package/.commitlintrc.json

@@ -1,3 +1,3 @@
-{
-    "extends": ["@commitlint/config-conventional"]
-}
+{
+    "extends": ["@commitlint/config-conventional"]
+}

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

@@ -1,30 +1,30 @@
-name: auto assign author
-
-on:
-  issues:
-    types: [opened]
-  pull_request:
-    types: [opened]
-
-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: auto assign author
+
+on:
+  issues:
+    types: [opened]
+  pull_request:
+    types: [opened]
+
+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]
+            })

package/.oxlintrc.json

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

package/.vscode/settings.json

@@ -1,12 +1,12 @@
-{
-    "oxc.fmt.configPath": ".oxfmtrc.json",
-    "editor.defaultFormatter": "oxc.oxc-vscode",
-    "editor.formatOnSave": true,
-    "oxc.enable.oxlint": true,
-    "oxc.enable.oxfmt": true,
-    "editor.codeActionsOnSave": {
-        "source.fixAll.oxc": "always"
-    },
-    "files.insertFinalNewline": false,
-    "files.trimTrailingWhitespace": true
-}
+{
+    "oxc.fmt.configPath": ".oxfmtrc.json",
+    "editor.defaultFormatter": "oxc.oxc-vscode",
+    "editor.formatOnSave": true,
+    "oxc.enable.oxlint": true,
+    "oxc.enable.oxfmt": true,
+    "editor.codeActionsOnSave": {
+        "source.fixAll.oxc": "always"
+    },
+    "files.insertFinalNewline": false,
+    "files.trimTrailingWhitespace": true
+}

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [1.1.5](https://github.com/nathievzm/lumi/compare/v1.1.4...v1.1.5) (2026-05-14)
+
+### Bug Fixes
+
+- restrict image dimensions to prevent resource exhaustion
+  ([40e65f3](https://github.com/nathievzm/lumi/commit/40e65f34f04f22cea1d7f543beddc6d45c66d87a))
+
+### Features
+
+- provide smart default for CLI format selection prompt
+  ([7e31044](https://github.com/nathievzm/lumi/commit/7e31044e841610b660388258a5cc971246ad2884))
+- **ux:** improve error handling for missing input folders
+  ([b4ad267](https://github.com/nathievzm/lumi/commit/b4ad26711348c3f0c38f990531c4f2ea0b3ad0ff))
+
+### Performance Improvements
+
+- improve readability of code suggested by jules
+  ([aa11125](https://github.com/nathievzm/lumi/commit/aa11125156cec42f97a3e3ab08cdf98fb63aa432))
+- **index:** use getMessage function to get the error message
+  ([5571325](https://github.com/nathievzm/lumi/commit/557132529d782af777fa9df3bac03b1fa800f48c))
+- remove oxlint disabled comments by jules
+  ([7f6ece6](https://github.com/nathievzm/lumi/commit/7f6ece6379c944504e08865a34bfd0c28819566c))
+
+## [1.1.4](https://github.com/nathievzm/lumi/compare/v1.1.3...v1.1.4) (2026-05-13)
+
+## [1.1.3](https://github.com/nathievzm/lumi/compare/v1.1.2...v1.1.3) (2026-05-13)
+
+### Features
+
+- add update notifier to notify when there'a a new version ([#67](https://github.com/nathievzm/lumi/issues/67))
+  ([b567f03](https://github.com/nathievzm/lumi/commit/b567f03b3c6617b18bdc34587d65055c5726bcfc))
+
 ## [1.1.2](https://github.com/nathievzm/lumi/compare/v1.1.1...v1.1.2) (2026-05-13)
 
 ### Bug Fixes

package/lefthook.yml

@@ -1,24 +1,24 @@
-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 {staged_files} && git add {staged_files}
-
-    - name: lint
-      run: bun lint
-
-    - name: types
-      run: bunx --bun tsc --noEmit
-
-commit-msg:
-  jobs:
-    - name: commitlint
-      # using bun to run commitlint as fast as possible 🌸
-      run: bunx --bun commitlint --edit {1}
-
-pre-push:
-  jobs:
-    - name: test-placeholder
-      run: echo "ready to push! tests will go here in the future ✨"
+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
+      run: bun lint
+
+    - name: types
+      run: bunx --bun tsc --noEmit
+
+commit-msg:
+  jobs:
+    - name: commitlint
+      # using bun to run commitlint as fast as possible 🌸
+      run: bunx --bun commitlint --edit {1}
+
+pre-push:
+  jobs:
+    - name: test-placeholder
+      run: echo "ready to push! tests will go here in the future ✨"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nathievzm/lumi",
-    "version": "1.1.2",
+    "version": "1.1.5",
     "description": "a concurrent cli tool to resize and convert images using bun and sharp",
     "keywords": [
         "bun",
@@ -45,7 +45,7 @@
         "fmt:check": "oxfmt --check",
         "lint": "oxlint",
         "lint:fix": "oxlint --fix",
-        "postinstall": "lefthook install",
+        "prepare": "bunx lefthook install",
         "release": "bumpp --execute \"bun changelog\" --all",
         "start": "bun src/index.ts"
     },
@@ -56,12 +56,14 @@
         "image-extensions": "^1.1.0",
         "p-limit": "^7.3.0",
         "picocolors": "^1.1.1",
-        "sharp": "^0.34.5"
+        "sharp": "^0.34.5",
+        "update-notifier": "^7.3.1"
     },
     "devDependencies": {
         "@commitlint/cli": "^20.5.3",
         "@commitlint/config-conventional": "^20.5.3",
         "@types/bun": "latest",
+        "@types/update-notifier": "^6.0.8",
         "bumpp": "^11.1.0",
         "conventional-changelog-cli": "^5.0.0",
         "lefthook": "^2.1.6",

package/src/index.ts

@@ -9,12 +9,19 @@ 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 { ensureOutputExists, getInputPath, getOutputPath } from '@/folder'
+import { getMessage } from '@/error'
+import { getInput, getOutput, prepare } from '@/folder'
 import { getExtensions, getImages, getWidthAndHeight, resize } from '@/image'
 
-import pkg from '../package.json'
+import pkg from '../package.json' with { type: 'json' }
+
+const notifier = updateNotifier({ pkg })
+notifier.notify({
+    boxenOptions: { borderColor: 'magenta', borderStyle: 'round', padding: 1 }
+})
 
 console.clear()
 
@@ -30,9 +37,21 @@ console.log(banner, '\n')
 
 intro(color.magenta(`welcome to lumi v${pkg.version} 🩷`))
 
-const input = getInputPath(cli.input)
+const input = getInput(cli.input)
+const output = getOutput(cli.output)
+await prepare(output)
+
+let allFiles: string[] = []
+
+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)
+}
 
-const allFiles = await readdir(input, { recursive: cli.recursive })
 const images = getImages(allFiles)
 
 if (images.length === 0) {
@@ -43,10 +62,18 @@ if (images.length === 0) {
 
 note(`found ${color.magenta(images.length)} images to process! 🚀`)
 
-const output = getOutputPath(cli.output)
-await ensureOutputExists(output)
+let dimensions = { height: 0, width: 0 }
 
-const { width, height } = await getWidthAndHeight(cli.width, cli.height)
+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)
+}
+
+const { width, height } = dimensions
 
 const extensions = await getExtensions(images, cli.format)
 const limit = pLimit({ concurrency: cli.limit || 10, rejectOnClear: true })
@@ -84,6 +111,16 @@ 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
+        }
+
+        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`)

package/src/lib/error.ts

@@ -0,0 +1,21 @@
+/**
+ * Safely extracts a human-readable error message from an unknown error.
+ *
+ * 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.
+ */
+export const getMessage = (error: unknown) => {
+    if (error instanceof Error) {
+        return error.message
+    }
+
+    if (typeof error === 'string') {
+        return error
+    }
+
+    return 'an unknown error occurred'
+}

package/src/lib/folder.ts

@@ -1,5 +1,5 @@
 import { exists, mkdir } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import { cwd } from 'node:process'
 
 import { log } from '@clack/prompts'
@@ -8,14 +8,14 @@ import color from 'picocolors'
 /**
  * Resolves the input directory path.
  *
- * If a path is provided via CLI arguments, it uses that path and logs it.
- * Otherwise, it prompts the user to enter an input 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 - The input path provided via CLI, if any.
+ * @param input - An optional input path provided via CLI arguments.
  *
- * @returns A promise that resolves to the chosen input path string.
+ * @returns The resolved input directory path.
  */
-export const getInputPath = (input?: string) => {
+export const getInput = (input?: string) => {
     if (input !== undefined && input !== '') {
         log.info(`input folder provided: ${color.cyan(input)} 📂`)
         return input
@@ -30,14 +30,14 @@ export const getInputPath = (input?: string) => {
 /**
  * Resolves the output directory path.
  *
- * If a path is provided via CLI arguments, it uses that path and logs it.
- * Otherwise, it prompts the user to enter an output path.
+ * 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 - The output path provided via CLI, if any.
+ * @param output - An optional output path provided via CLI arguments.
  *
- * @returns A promise that resolves to the chosen output path string.
+ * @returns The resolved output directory path.
  */
-export const getOutputPath = (output?: string) => {
+export const getOutput = (output?: string) => {
     if (output !== undefined && output !== '') {
         log.info(`output folder provided: ${color.cyan(output)} 📂`)
         return output
@@ -52,14 +52,14 @@ export const getOutputPath = (output?: string) => {
 /**
  * Ensures that the specified output directory exists.
  *
- * If the directory does not exist, it creates it recursively.
- * Logs a confirmation message once the folder is ready.
+ * If the directory does not exist, it is created recursively.
+ * A confirmation message is logged once the directory is ready.
  *
- * @param output - The path to the output directory.
+ * @param output - The absolute or relative path to the output directory.
  *
- * @returns A promise that resolves when the directory is verified or created.
+ * @returns A promise that resolves when the directory is verified or successfully created.
  */
-export const ensureOutputExists = async (output: string) => {
+export const prepare = async (output: string) => {
     const outputExists = await exists(output)
 
     if (!outputExists) {
@@ -68,3 +68,24 @@ export const ensureOutputExists = async (output: string) => {
 
     log.info(`output folder ready: ${color.cyan(output)} ✅`, { spacing: 0 })
 }
+
+/**
+ * Guards against path traversal attacks by ensuring a target path is strictly within a specified base folder.
+ *
+ * @param folder - The base directory path that the target path must reside within.
+ * @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.
+ */
+export const guard = (folder: string, path: string) => {
+    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 🚫')
+    }
+
+    return true
+}

package/src/lib/image.ts

@@ -4,56 +4,60 @@ import { type Option } from '@clack/prompts'
 import imageExtensions from 'image-extensions'
 import sharp, { type AvailableFormatInfo } from 'sharp'
 
+import { guard } from './folder'
 import { askExtensions, askWidthAndHeight } from './prompt'
 
 /**
- * Parameters for the image resizing operation.
+ * Configuration parameters required for the image resizing and conversion operation.
  */
 interface ResizeParams {
     /**
-     * The relative path of the image within the input directory.
+     * The relative file path of the source image within the input directory.
      */
     readonly image: string
     /**
-     * The absolute or relative path to the input directory.
+     * The absolute or relative path to the source directory containing the input images.
      */
     readonly input: string
     /**
-     * The absolute or relative path to the output directory.
+     * The absolute or relative path to the destination directory for the processed images.
      */
     readonly output: string
     /**
-     * The target width for the resized image.
+     * The target width in pixels for the resized image.
      */
     readonly width: number
     /**
-     * The target height for the resized image.
+     * The target height in pixels for the resized image.
      */
     readonly height: number
     /**
-     * The filename (without extension) for the output file.
+     * The desired filename for the output file, excluding the extension.
      */
     readonly name: string
     /**
-     * The target file extension (e.g., '.png', '.webp') for the output file.
+     * The target file extension (e.g., '.png', '.webp') dictating the output format.
      */
     readonly extension: string
 }
 
+const inputFormats = imageExtensions.map(format => `.${format}`)
+const validExtensions = new Set(inputFormats)
+
 /**
- * Type guard to check if a value is a Sharp AvailableFormatInfo object.
+ * A type guard to verify if an unknown value conforms to the `AvailableFormatInfo` structure from Sharp.
  *
- * @param value - The value to check.
+ * @param value - The unknown value to evaluate.
  *
- * @returns True if the value matches the AvailableFormatInfo structure.
+ * @returns `true` if the value is a valid `AvailableFormatInfo` object, otherwise `false`.
  */
 const isFormatInfo = (value: unknown): value is AvailableFormatInfo =>
     typeof value === 'object' && value !== null && 'output' in value && 'id' in value
 
 /**
- * Retrieves the list of image formats supported by Sharp for output.
+ * Retrieves a list of image formats supported by the Sharp library for output processing.
  *
- * @returns An array of options representing the supported formats.
+ * @returns An array of prompt-compatible `Option` objects representing the supported output formats.
  */
 const getSharpFormats = () => {
     const sharpFormats = Object.values(sharp.format).filter(format => isFormatInfo(format))
@@ -65,16 +69,13 @@ const getSharpFormats = () => {
 }
 
 /**
- * Filters a list of files to return only those with supported image extensions.
+ * Filters an array of file paths, returning only those with recognized image extensions.
  *
- * @param files - An array of file paths to filter.
+ * @param files - A readonly array of file paths or filenames to filter.
  *
- * @returns An array of file paths that are recognized as images.
+ * @returns An array containing only the file paths that correspond to supported image formats.
  */
 export const getImages = (files: readonly string[]) => {
-    const inputFormats = imageExtensions.map(format => `.${format}`)
-    const validExtensions = new Set(inputFormats)
-
     const images = files.filter(file => {
         const ext = extname(file)
         return validExtensions.has(ext.toLowerCase())
@@ -84,15 +85,16 @@ export const getImages = (files: readonly string[]) => {
 }
 
 /**
- * Resolves the target width and height for image processing.
+ * Resolves the target width and height for the image processing operation.
  *
- * If both dimensions are provided via CLI and are valid, they are used.
- * Otherwise, it prompts the user to enter the desired dimensions.
+ * If valid dimensions (greater than 0) are provided via CLI arguments, they are utilized.
+ * If either dimension is missing or invalid, an interactive prompt will request the dimensions from the user.
  *
- * @param width - The width provided via CLI.
- * @param height - The height provided via CLI.
+ * @param width - The target width parsed from CLI arguments.
+ * @param height - The target height parsed from CLI arguments.
  *
- * @returns A promise that resolves to an object containing the width and height.
+ * @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.
  */
 export const getWidthAndHeight = (width: number, height: number) => {
     const notWidth = isNaN(width) || width <= 0
@@ -102,49 +104,53 @@ export const getWidthAndHeight = (width: number, height: number) => {
         return askWidthAndHeight()
     }
 
+    if (width > 16_383 || height > 16_383) {
+        throw new Error('dimensions must be less than 16384 pixels 🚫')
+    }
+
     return Promise.resolve({ height, width })
 }
 
 /**
- * Determines the output extensions for a set of images.
+ * Determines the target output formats for a collection of input images.
  *
- * If a global format is specified, it returns that format as the default for all images.
- * Otherwise, it identifies the unique extensions present in the input images and prompts
- * the user to map each original extension to a desired output format.
+ * If a global format flag is provided, it dictates the default output format for all images.
+ * In the absence of a global format, it extracts the unique extensions from the input images
+ * and prompts the user to map each original extension to a specific output format interactively.
  *
- * @param images - An array of image filenames to analyze.
- * @param format - An optional global output format.
+ * @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.
  *
- * @returns A promise that resolves to a record mapping input extensions to output formats.
+ * @returns A promise resolving to a record that maps input extensions (or 'default') to their chosen output formats.
  */
 export const getExtensions = (images: readonly string[], format?: string) => {
     if (format !== undefined && format !== '') {
         return Promise.resolve({ default: format } as Record<string, string>)
     }
 
-    const extensions = [
-        ...new Set(
-            images.flatMap(image => {
-                const ext = extname(image)
-                return ext ? ext.toLowerCase() : ''
-            })
-        )
-    ].filter(Boolean)
+    const extensionsSet = new Set<string>()
+    for (const image of images) {
+        const ext = image ? extname(image) : ''
+        if (ext) {
+            extensionsSet.add(ext.toLowerCase())
+        }
+    }
+    const extensions = [...extensionsSet]
 
     const formats = getSharpFormats()
     return askExtensions(extensions, formats)
 }
 
 /**
- * Resizes an image using the Sharp library.
+ * Processes an image by resizing and potentially converting its format using the Sharp library.
  *
- * Handles both static and animated images (e.g., GIFs, WebP), maintaining
- * aspect ratio with a 'contain' fit and transparent background where applicable.
+ * This operation supports both static and animated images (e.g., GIFs, WebP). It maintains
+ * the original aspect ratio utilizing a 'contain' fit and applies a transparent background where necessary.
  *
- * @param params - The parameters for the resize operation.
+ * @param params - The configuration parameters dictating the resize and conversion operations.
  *
- * @returns A promise that resolves to a success message string.
- * @throws Error if the image processing fails.
+ * @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.
  */
 export const resize = async (params: ResizeParams) => {
     const { image, input, output, width, height, name, extension } = params
@@ -153,6 +159,8 @@ export const resize = async (params: ResizeParams) => {
         const inputPath = join(input, image)
         const outputPath = join(output, `${name}${extension}`)
 
+        guard(output, outputPath)
+
         await sharp(inputPath, { animated: true })
             .resize(width, height, { background: 'transparent', fit: 'contain' })
             .toFile(outputPath)

package/src/lib/prompt.ts

@@ -4,11 +4,56 @@ import { type Option, cancel, group, select, text } from '@clack/prompts'
 import color from 'picocolors'
 
 /**
- * Prompts the user for the target width and height of the images.
+ * Validates the quantity of numeric matches extracted from the user's dimension input.
  *
- * Validates that both inputs are positive numbers.
+ * Ensures the user provides at least one and at most two valid numeric strings.
  *
- * @returns A promise that resolves to an object containing the numeric width and height.
+ * @param matches - A readonly array of numeric strings extracted via regex, or `null`/`undefined` if no matches were
+ *   found.
+ *
+ * @returns An error message string if the validation fails, or `undefined` if the matches are valid.
+ */
+const validateMatches = (matches: readonly string[] | null | undefined) => {
+    if (!matches || matches.length === 0) {
+        return 'please enter at least one valid positive number 🚫'
+    }
+
+    if (matches.length > 2) {
+        return 'please enter at most two numbers (width and height) 🚫'
+    }
+
+    return undefined
+}
+
+/**
+ * Verifies that the parsed dimensions fall within the acceptable boundaries for image processing.
+ *
+ * Enforces that both dimensions are strictly positive and do not exceed Sharp's maximum pixel limit.
+ *
+ * @param width - The target width in pixels.
+ * @param height - The target height in pixels.
+ *
+ * @returns An error message string detailing the failure reason, or `undefined` if the dimensions are valid.
+ */
+const validateLimits = (width: number, height: number) => {
+    if (width <= 0 || height <= 0) {
+        return 'dimensions must be greater than zero 🚫'
+    }
+
+    if (width > 16_383 || height > 16_383) {
+        return 'dimensions must be less than 16_384 pixels 🚫'
+    }
+
+    return undefined
+}
+
+/**
+ * Interactively prompts the user to provide the target width and height for the processed images.
+ *
+ * Parses the input to support either a single value (for square dimensions) or two values
+ * (for specific width and height). If the user cancels the prompt, the process exits.
+ *
+ * @returns A promise resolving to an object containing the validated, numeric `width` and `height`.
  */
 export const askWidthAndHeight = async () => {
     const regex = /\d+/gv
@@ -18,23 +63,18 @@ export const askWidthAndHeight = async () => {
         placeholder: 'e.g. "1080" (square) or "1920 1080" (width x height)',
         validate: value => {
             const matches = value?.match(regex)
+            const matchError = validateMatches(matches)
 
-            if (!matches || matches.length === 0) {
-                return 'please enter at least one valid positive number 🚫'
-            }
-
-            if (matches.length > 2) {
-                return 'please enter at most two numbers (width and height) 🚫'
+            // If the regex parsing failed or gave bad counts, return the error early 🛡️
+            if (matchError !== undefined || !matches) {
+                return matchError
             }
 
             const width = Number(matches[0])
-            const height = matches.length === 2 ? Number(matches[1]) : width
+            const height = matches[1] === undefined ? width : Number(matches[1])
 
-            if (width <= 0 || height <= 0) {
-                return 'dimensions must be greater than zero 🚫'
-            }
-
-            return undefined
+            // Delegate the final math check to our helper ✨
+            return validateLimits(width, height)
         }
     })
 
@@ -46,21 +86,21 @@ export const askWidthAndHeight = async () => {
     const matches = result.match(regex) ?? []
 
     const width = Number(matches[0])
-    const height = matches.length === 2 ? Number(matches[1]) : width
+    const height = matches[1] === undefined ? width : Number(matches[1])
 
     return { height, width }
 }
 
 /**
- * Prompts the user to select an output format for each unique file extension found.
+ * Interactively prompts the user to select a desired output format for each unique input file extension.
  *
- * Dynamically generates a group of selection prompts based on the provided extensions.
- * If the user cancels any selection, the process exits.
+ * Dynamically constructs a series of selection prompts based on the provided list of extensions.
+ * If the user cancels any of the prompts, the process exits.
  *
- * @param extensions - An array of unique file extensions found in the input.
- * @param formats - An array of available output formats supported by the system.
+ * @param extensions - A readonly array of unique file extensions detected in the input images.
+ * @param formats - A readonly array of output format options supported by the Sharp library.
  *
- * @returns A promise that resolves to a record mapping each original extension to its chosen output format.
+ * @returns A promise resolving to a record that maps each original file extension to its selected output format string.
  */
 export const askExtensions = (extensions: readonly string[], formats: readonly Readonly<Option<string>>[]) => {
     const promptGroups: Record<string, () => Promise<string | symbol>> = {}
@@ -70,11 +110,15 @@ export const askExtensions = (extensions: readonly string[], formats: readonly R
             continue
         }
 
-        promptGroups[extension] = () =>
-            select({
+        promptGroups[extension] = () => {
+            const initialValue = formats.some(format => format.value === extension) ? extension : undefined
+
+            return select({
+                initialValue,
                 message: `what ${color.magenta('format')} do you want to use for ${color.cyan(extension)} files? 🎨`,
                 options: [...formats]
             })
+        }
     }
 
     return group(promptGroups, {

package/tsconfig.json

@@ -1,40 +1,40 @@
-{
-    "compilerOptions": {
-        // Environment setup & latest features
-        "lib": ["ESNext"],
-        "target": "ESNext",
-        "module": "Preserve",
-        "moduleDetection": "force",
-        "jsx": "react-jsx",
-        "allowJs": true,
-        "types": ["bun"],
-
-        // Bundler mode
-        "moduleResolution": "bundler",
-        "allowImportingTsExtensions": true,
-        "verbatimModuleSyntax": true,
-        "noEmit": true,
-
-        // Best practices
-        "strict": true,
-        "skipLibCheck": true,
-        "noFallthroughCasesInSwitch": true,
-        "noUncheckedIndexedAccess": true,
-        "noImplicitOverride": true,
-
-        // Some stricter flags (disabled by default)
-        "noUnusedLocals": true,
-        "noUnusedParameters": true,
-        "noImplicitReturns": true,
-        "noImplicitAny": true,
-        "noImplicitThis": true,
-        "noUncheckedSideEffectImports": true,
-        "noPropertyAccessFromIndexSignature": true,
-
-        // Paths
-        "paths": {
-            "@/*": ["./src/lib/*"]
-        }
-    },
-    "include": ["**/*.ts", "**/*.d.ts"]
-}
+{
+    "compilerOptions": {
+        // Environment setup & latest features
+        "lib": ["ESNext"],
+        "target": "ESNext",
+        "module": "Preserve",
+        "moduleDetection": "force",
+        "jsx": "react-jsx",
+        "allowJs": true,
+        "types": ["bun"],
+
+        // Bundler mode
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+        "noEmit": true,
+
+        // Best practices
+        "strict": true,
+        "skipLibCheck": true,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedIndexedAccess": true,
+        "noImplicitOverride": true,
+
+        // Some stricter flags (disabled by default)
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noImplicitReturns": true,
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "noUncheckedSideEffectImports": true,
+        "noPropertyAccessFromIndexSignature": true,
+
+        // Paths
+        "paths": {
+            "@/*": ["./src/lib/*"]
+        }
+    },
+    "include": ["**/*.ts", "**/*.d.ts"]
+}