@nathievzm/lumi 1.1.5 → 1.2.0

package/src/index.ts

@@ -1,130 +1,120 @@
 #!/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, input, output)
 
-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) {
+        const hint = cli.recursive ? '' : ' (try adding the --recursive flag to check subfolders)'
+        throw new ImageError(`no valid images found in the input folder 😭${hint}`)
+    }
 
-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,10 +45,10 @@ 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),
+            default: Bun.env.RECURSIVE === 'true',
             short: 'r',
             type: 'boolean'
         },
@@ -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,22 +1,25 @@
-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.
  */
 export const getInput = (input?: string) => {
     if (input !== undefined && input !== '') {
+        guard(cwd(), input)
         log.info(`input folder provided: ${color.cyan(input)} 📂`)
         return input
     }
@@ -33,12 +36,13 @@ 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.
  */
 export const getOutput = (output?: string) => {
     if (output !== undefined && output !== '') {
+        guard(cwd(), output)
         log.info(`output folder provided: ${color.cyan(output)} 📂`)
         return output
     }
@@ -60,13 +64,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 +101,25 @@ 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') || 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 Error('path traversal detected 🚫')
+        throw new FolderError('path traversal detected 🚨')
     }
 
     return true

package/src/lib/image.ts

@@ -1,9 +1,10 @@
-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'
 import { askExtensions, askWidthAndHeight } from './prompt'
 
@@ -41,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.
  *
@@ -59,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 = () => {
+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}` }))
@@ -69,17 +95,48 @@ const getSharpFormats = () => {
 }
 
 /**
- * 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
 }
@@ -94,7 +151,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 +162,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,16 +176,17 @@ 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.
  */
-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) {
@@ -137,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)
 }
 
@@ -150,7 +208,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,14 +218,17 @@ export const resize = async (params: ResizeParams) => {
         const inputPath = join(input, image)
         const outputPath = join(output, `${name}${extension}`)
 
+        guard(input, inputPath)
         guard(output, outputPath)
 
+        const sharp = await getSharp()
+
         await sharp(inputPath, { animated: true })
             .resize(width, height, { background: 'transparent', fit: 'contain' })
             .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)
     }
 }