@nathievzm/lumi 1.1.6 → 1.2.0

package/.jules/bolt.md

@@ -34,3 +34,29 @@ 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

@@ -30,3 +30,29 @@ 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

@@ -45,3 +45,26 @@ 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/CHANGELOG.md

@@ -1,3 +1,39 @@
+# [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

package/lefthook.yml

@@ -1,6 +1,4 @@
 pre-commit:
-  # running all checks at the same time for maximum speed ⚡
-  parallel: true
   jobs:
     - name: format
       run: bun fmt && git add .
@@ -14,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.6",
+    "version": "1.2.0",
     "description": "a concurrent cli tool to resize and convert images using bun and sharp",
     "keywords": [
         "bun",

package/src/index.ts

@@ -38,10 +38,11 @@ try {
     await prepare(output)
 
     const allFiles = await readFiles(input, cli.recursive)
-    const images = getImages(allFiles)
+    const images = getImages(allFiles, input, output)
 
     if (images.length === 0) {
-        throw new ImageError('no valid images found in the input folder 😭')
+        const hint = cli.recursive ? '' : ' (try adding the --recursive flag to check subfolders)'
+        throw new ImageError(`no valid images found in the input folder 😭${hint}`)
     }
 
     note(`found ${color.magenta(images.length)} images to process! 🚀`)

package/src/lib/args.ts

@@ -48,7 +48,7 @@ const { values } = parseArgs({
          * Whether to process the input directory recursively. Defaults to the `RECURSIVE` environment variable.
          */
         recursive: {
-            default: Boolean(Bun.env.RECURSIVE),
+            default: Bun.env.RECURSIVE === 'true',
             short: 'r',
             type: 'boolean'
         },

package/src/lib/folder.ts

@@ -19,6 +19,7 @@ import { FolderError } from './error'
  */
 export const getInput = (input?: string) => {
     if (input !== undefined && input !== '') {
+        guard(cwd(), input)
         log.info(`input folder provided: ${color.cyan(input)} 📂`)
         return input
     }
@@ -41,6 +42,7 @@ export const getInput = (input?: string) => {
  */
 export const getOutput = (output?: string) => {
     if (output !== undefined && output !== '') {
+        guard(cwd(), output)
         log.info(`output folder provided: ${color.cyan(output)} 📂`)
         return output
     }
@@ -103,16 +105,21 @@ export const readFiles = async (input: string, recursive = false) => {
  *   attempt.
  */
 export const guard = (folder: string, path: string) => {
-    if (path.includes('\0')) {
-        throw new FolderError('path traversal detected 🚫')
+    if (path.includes('\0') || folder.includes('\0')) {
+        throw new FolderError('path traversal detected 🚨')
     }
 
     const resolved = resolve(folder)
     const resolvedPath = resolve(path)
+
+    if (resolved === resolvedPath) {
+        return true
+    }
+
     const normalized = resolved.endsWith(sep) ? resolved : resolved + sep
 
     if (!resolvedPath.startsWith(normalized)) {
-        throw new FolderError('path traversal detected 🚫')
+        throw new FolderError('path traversal detected 🚨')
     }
 
     return true

package/src/lib/image.ts

@@ -1,8 +1,8 @@
-import { extname, join } from 'node:path'
+import { extname, join, resolve, sep } from 'node:path'
 
 import { type Option } from '@clack/prompts'
 import imageExtensions from 'image-extensions'
-import sharp, { type AvailableFormatInfo } from 'sharp'
+import { type AvailableFormatInfo, type default as sharpType } from 'sharp'
 
 import { ImageError } from './error'
 import { guard } from './folder'
@@ -42,9 +42,32 @@ interface ResizeParams {
     readonly extension: string
 }
 
+/**
+ * Array of supported input image format extensions prefixed with a dot (e.g., '.jpg', '.png').
+ */
 const inputFormats = imageExtensions.map(format => `.${format}`)
+
+/**
+ * Set of valid input image extensions for optimized lookup.
+ */
 const validExtensions = new Set(inputFormats)
 
+/**
+ * Cached promise for the dynamically imported sharp module.
+ */
+let sharpPromise: Promise<{ default: typeof sharpType }> | undefined = undefined
+
+/**
+ * Helper to get the cached sharp module promise.
+ *
+ * @returns A promise resolving to the default export of the sharp module.
+ */
+const getSharp = async () => {
+    sharpPromise ??= import('sharp')
+    const { default: sharp } = await sharpPromise
+    return sharp
+}
+
 /**
  * A type guard to verify if an unknown value conforms to the `AvailableFormatInfo` structure from Sharp.
  *
@@ -60,8 +83,10 @@ const isFormatInfo = (value: unknown): value is AvailableFormatInfo =>
  *
  * @returns An array of prompt-compatible `Option` objects representing the supported output formats.
  */
-const getSharpFormats = (): Option<string>[] => {
+const getSharpFormats = async () => {
+    const sharp = await getSharp()
     const sharpFormats = Object.values(sharp.format).filter(format => isFormatInfo(format))
+
     const formats: Option<string>[] = sharpFormats
         .filter(format => format.output.file)
         .map(format => ({ label: format.id, value: `.${format.id}` }))
@@ -70,17 +95,48 @@ const getSharpFormats = (): Option<string>[] => {
 }
 
 /**
- * Filters an array of file paths, returning only those with recognized image extensions.
+ * Determines whether a given file is a valid, processable image.
+ *
+ * A file is considered processable if it has a valid image extension and is not
+ * already located within the output directory.
  *
- * @param files - A readonly array of file paths or filenames to filter.
+ * @param file - The name or relative path of the file to check.
+ * @param input - The absolute or relative path to the input directory.
+ * @param output - The absolute or relative path to the output directory.
  *
- * @returns An array containing only the file paths that correspond to supported image formats.
+ * @returns `true` if the file is a processable image, otherwise `false`.
  */
-export const getImages = (files: readonly string[]) => {
-    const images = files.filter(file => {
-        const ext = extname(file)
-        return validExtensions.has(ext.toLowerCase())
-    })
+const isProcessable = (file: string, input: string, output: string) => {
+    const ext = extname(file)
+    const isImage = validExtensions.has(ext.toLowerCase())
+    const isInOutput = join(input, file).startsWith(output)
+
+    return isImage && !isInOutput
+}
+
+/**
+ * Filters a list of files to identify valid images that are not already present in the output directory.
+ *
+ * @param files - A readonly array of file paths to filter.
+ * @param input - The absolute or relative path to the source directory containing the input files.
+ * @param output - The absolute or relative path to the destination directory for the processed images.
+ *
+ * @returns An array of string paths representing valid, unprocessed images.
+ */
+export const getImages = (files: readonly string[], input: string, output: string) => {
+    const resolvedInput = resolve(input)
+    const resolvedOutput = resolve(output)
+    const normalizedOutput = resolvedOutput.endsWith(sep) ? resolvedOutput : resolvedOutput + sep
+
+    const images: string[] = []
+
+    for (const file of files) {
+        if (!isProcessable(file, resolvedInput, normalizedOutput)) {
+            continue
+        }
+
+        images.push(file)
+    }
 
     return images
 }
@@ -124,12 +180,13 @@ export const getWidthAndHeight = (width: number, height: number) => {
  *
  * @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) => {
+export const getExtensions = async (images: readonly string[], format?: string) => {
     if (format !== undefined && format !== '') {
-        return Promise.resolve({ default: format } as Record<string, string>)
+        return { default: format } as Record<string, string>
     }
 
     const extensionsSet = new Set<string>()
+
     for (const image of images) {
         const ext = image ? extname(image) : ''
         if (ext) {
@@ -138,7 +195,7 @@ export const getExtensions = (images: readonly string[], format?: string) => {
     }
     const extensions = [...extensionsSet]
 
-    const formats = getSharpFormats()
+    const formats = await getSharpFormats()
     return askExtensions(extensions, formats)
 }
 
@@ -164,6 +221,8 @@ export const resize = async (params: ResizeParams) => {
         guard(input, inputPath)
         guard(output, outputPath)
 
+        const sharp = await getSharp()
+
         await sharp(inputPath, { animated: true })
             .resize(width, height, { background: 'transparent', fit: 'contain' })
             .toFile(outputPath)