@nathievzm/lumi 1.0.0

package/.commitlintrc.json

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

package/.env.example

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

package/.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+
+# enforce conventional commits to keep the git history aesthetic 💅
+bunx --bun commitlint --edit $1

package/.husky/pre-commit

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+
+# auto-format all files using the fmt script from package.json
+bun run fmt
+
+# check for code smells and errors using the lint script
+bun run lint
+
+# verify typescript types are correct based on the tsconfig rules
+bunx --bun tsc --noEmit

package/.husky/pre-push

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+# we will run all automated tests before pushing to github to ensure the code never breaks 🎀
+# bun test
+
+echo "ready to push! tests will go here in the future ✨"

package/.oxfmtrc.json

@@ -0,0 +1,32 @@
+{
+	"$schema": "./node_modules/oxfmt/configuration_schema.json",
+	"arrowParens": "avoid",
+	"bracketSameLine": true,
+	"bracketSpacing": true,
+	"embeddedLanguageFormatting": "auto",
+	"endOfLine": "crlf",
+	"insertFinalNewline": true,
+	"jsdoc": {
+		"bracketSpacing": true,
+		"lineWrappingStyle": "balance",
+		"separateReturnsFromParam": true,
+		"capitalizeDescriptions": true,
+		"descriptionWithDot": false,
+		"commentLineStrategy": "multiline"
+	},
+	"objectWrap": "preserve",
+	"printWidth": 120,
+	"proseWrap": "always",
+	"quoteProps": "consistent",
+	"semi": false,
+	"singleQuote": true,
+	"sortImports": {
+		"newlinesBetween": true
+	},
+	"sortPackageJson": {
+		"sortScripts": true
+	},
+	"tabWidth": 4,
+	"trailingComma": "none",
+	"useTabs": true
+}

package/.oxlintrc.json

@@ -0,0 +1,35 @@
+{
+	"$schema": "./node_modules/oxlint/configuration_schema.json",
+	"plugins": ["typescript", "unicorn", "oxc", "eslint", "import", "jsdoc", "node", "promise"],
+	"categories": {
+		"correctness": "error",
+		"suspicious": "error",
+		"pedantic": "warn",
+		"perf": "warn",
+		"style": "warn",
+		"restriction": "off",
+		"nursery": "off"
+	},
+	"rules": {
+		"no-nodejs-modules": "off",
+		"no-magic-numbers": "off",
+		"no-ternary": "off",
+		"sort-imports": ["warn", { "ignoreDeclarationSort": true }],
+		"consistent-type-specifier-style": ["warn", "prefer-inline"],
+		"prefer-default-export": "off",
+		"no-named-export": "off",
+		"prefer-readonly-parameter-types": ["warn", { "ignoreInferredTypes": true }],
+		"group-exports": "off",
+		"unicorn/no-useless-undefined": "off",
+		"no-continue": "off",
+		"require-param-type": "off",
+		"require-returns-type": "off"
+	},
+	"env": {
+		"builtin": true
+	},
+	"options": {
+		"typeAware": true,
+		"typeCheck": true
+	}
+}

package/.vscode/launch.json

@@ -0,0 +1,36 @@
+{
+	// Use IntelliSense to learn about possible attributes.
+	// Hover to view descriptions of existing attributes.
+	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"type": "bun",
+			"internalConsoleOptions": "neverOpen",
+			"request": "launch",
+			"name": "Debug File",
+			"program": "${file}",
+			"cwd": "${workspaceFolder}",
+			"stopOnEntry": false,
+			"watchMode": false
+		},
+		{
+			"type": "bun",
+			"internalConsoleOptions": "neverOpen",
+			"request": "launch",
+			"name": "Run File",
+			"program": "${file}",
+			"cwd": "${workspaceFolder}",
+			"noDebug": true,
+			"watchMode": false
+		},
+		{
+			"type": "bun",
+			"internalConsoleOptions": "neverOpen",
+			"request": "attach",
+			"name": "Attach Bun",
+			"url": "ws://localhost:6499/",
+			"stopOnEntry": false
+		}
+	]
+}

package/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+	"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
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathalie Victoria Zambrano Molero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# ✨ lumi ✨
+
+A fast, interactive CLI tool for batch image processing. Resize, convert, and optimize your images with ease, powered by
+[Bun](https://bun.sh) and [Sharp](https://sharp.pixelplumbing.com/).
+
+## 🚀 Features
+
+- **Batch Processing:** Process hundreds of images in seconds with high concurrency.
+- **Interactive UI:** User-friendly prompts for missing configurations using `@clack/prompts`.
+- **Progress Tracking:** Real-time feedback with `spinnies` progress indicators.
+- **Smart Resizing:** Automatically fits images while maintaining aspect ratio (`contain` fit).
+- **Multi-Format Support:** Convert between all formats supported by Sharp (WebP, PNG, JPEG, GIF, AVIF, etc.).
+- **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.
+
+## 📦 Installation
+
+You don't even need to install it if you use `bunx`! Run it directly from anywhere in your terminal:
+
+```bash
+bunx @nathievzm/lumi
+```
+
+Or install it globally:
+
+```bash
+bun install -g @nathievzm/lumi
+```
+
+## 🛠️ Usage
+
+If installed globally, simply run:
+
+```bash
+lumi [options]
+```
+
+### Interactive Mode
+
+If you run **lumi** without providing required flags (like input/output folders or dimensions), it will guide you
+through the configuration using cute, interactive prompts. You can even choose specific output formats for each unique
+extension found!
+
+### CLI Options
+
+You can bypass the prompts by providing the flags directly:
+
+```bash
+bunx @nathievzm/lumi -i ./my-vacation-pics -s 1080 -f .webp
+```
+
+| Flag       | Shortcut | Description                   | Default             |
+| :--------- | :------- | :---------------------------- | :------------------ |
+| `--input`  | `-i`     | Input directory path          | `INPUT_FOLDER` env  |
+| `--output` | `-o`     | Output directory path         | `OUTPUT_FOLDER` env |
+| `--width`  | `-w`     | Target width in pixels        | `WIDTH` env         |
+| `--height` | `-h`     | Target height in pixels       | `HEIGHT` env        |
+| `--size`   | `-s`     | Sets both width and height    | -                   |
+| `--format` | `-f`     | Output format (e.g., `.webp`) | `FORMAT` env        |
+| `--limit`  | `-l`     | Max concurrent operations     | `LIMIT` env         |
+
+### 🌍 Environment Variables
+
+**lumi** also reads from a `.env` file in your current working directory. This is useful for saving your preferred
+defaults:
+
+```env
+WIDTH = '800'
+HEIGHT = '600'
+INPUT_FOLDER = './input'
+OUTPUT_FOLDER = './output'
+FORMAT = '.webp'
+LIMIT = '10'
+```
+
+---
+
+## 🧑‍💻 Local Development
+
+If you want to contribute or run the project from source:
+
+### Clone the repository
+
+```bash
+git clone https://github.com/nathievzm/lumi.git
+cd lumi
+```
+
+### Install dependencies
+
+```bash
+bun install
+```
+
+### Available Scripts
+
+- `bun start`: Run the application.
+- `bun dev`: Start with hot reloading.
+- `bun lint`: Check for code quality issues.
+- `bun lint:fix`: Fix linting issues automatically.
+- `bun fmt`: Format the codebase.
+- `bun fmt:check`: Check for formatting issues.
+- `bun prepare`: Setup husky hooks.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@nathievzm/lumi",
+	"version": "1.0.0",
+	"description": "a concurrent cli tool to resize and convert images using bun and sharp",
+	"keywords": [
+		"bun",
+		"clack",
+		"cli",
+		"concurrency",
+		"concurrent",
+		"image",
+		"image-processing",
+		"media",
+		"p-limit",
+		"sharp",
+		"spinnies",
+		"typescript"
+	],
+	"bugs": {
+		"url": "https://github.com/nathievzm/lumi/issues",
+		"email": "nathalievzm@gmail.com"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "Nathalie Zambrano",
+		"email": "nathalievzm@gmail.com",
+		"url": "https://github.com/nathievzm"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nathievzm/lumi.git"
+	},
+	"bin": {
+		"lumi": "src/index.ts"
+	},
+	"type": "module",
+	"module": "index.ts",
+	"scripts": {
+		"dev": "bun --hot src/index.ts",
+		"fmt": "oxfmt",
+		"fmt:check": "oxfmt --check",
+		"lint": "oxlint",
+		"lint:fix": "oxlint --fix",
+		"prepare": "bunx husky",
+		"start": "bun run src/index.ts"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.3.0",
+		"p-limit": "^7.3.0",
+		"sharp": "^0.34.5",
+		"spinnies": "^0.5.1"
+	},
+	"devDependencies": {
+		"@commitlint/cli": "^20.5.3",
+		"@commitlint/config-conventional": "^20.5.3",
+		"@types/bun": "latest",
+		"@types/spinnies": "^0.5.3",
+		"husky": "^9.1.7",
+		"oxfmt": "^0.47.0",
+		"oxlint": "^1.62.0",
+		"oxlint-tsgolint": "^0.22.1",
+		"typescript": "^6.0.3"
+	}
+}

package/src/env.d.ts

@@ -0,0 +1,28 @@
+declare module 'bun' {
+	interface Env {
+		/**
+		 * Default target width for resized images.
+		 */
+		WIDTH: string
+		/**
+		 * Default target height for resized images.
+		 */
+		HEIGHT: string
+		/**
+		 * Default path to the input folder containing images.
+		 */
+		INPUT_FOLDER: string
+		/**
+		 * Default path where processed images will be saved.
+		 */
+		OUTPUT_FOLDER: string
+		/**
+		 * Default global output format (e.g., '.webp', '.png').
+		 */
+		FORMAT: string
+		/**
+		 * Default concurrent processing limit.
+		 */
+		LIMIT: string
+	}
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+
+import { readdir } from 'node:fs/promises'
+import { parse } from 'node:path'
+
+import { intro, log, note, outro } from '@clack/prompts'
+import pLimit from 'p-limit'
+import Spinnies from 'spinnies'
+
+import { cli } from '@/args'
+import { getMessage } from '@/error'
+import { ensureOutputExists, getInputPath, getOutputPath } from '@/folder'
+import { getExtensions, getWidthAndHeight, resize } from '@/image'
+
+intro('✨ welcome to media-processor ✨')
+
+const input = await getInputPath(cli.input)
+
+const images = await readdir(input, { recursive: true })
+note(`found ${images.length} images to process! 🚀`)
+
+const output = await getOutputPath(cli.output)
+await ensureOutputExists(output)
+
+const { width, height } = await getWidthAndHeight(cli.width, cli.height)
+
+const spinnies = new Spinnies({
+	failColor: 'red',
+	spinnerColor: 'magenta',
+	succeedColor: 'green'
+})
+
+const extensions = await getExtensions(images)
+const limit = pLimit({ concurrency: cli.limit || 10, rejectOnClear: true })
+
+const promises = images.map(image =>
+	limit(async () => {
+		spinnies.add(image, { text: `🔃 processing: ${image}` })
+
+		const { name, ext } = parse(image)
+		const extension = extensions['default'] ?? extensions[ext] ?? '.png'
+
+		try {
+			const result = await resize({ extension, height, image, input, name, output, width })
+			spinnies.succeed(image, { text: result })
+		} catch (error: unknown) {
+			const message = getMessage(error)
+			spinnies.fail(image, { text: message })
+		}
+	})
+)
+
+log.message()
+
+const result = await Promise.allSettled(promises)
+let outroMessage = ''
+
+if (result.some(pr => pr.status === 'rejected')) {
+	log.error('yikes, some images failed to process! 😢')
+	outroMessage = 'please check the error messages above and try again 🛠️'
+} else {
+	log.success('yay! all images processed and saved successfully! 💖')
+	outroMessage = 'bye 👋'
+}
+
+outro(outroMessage)

package/src/lib/args.ts

@@ -0,0 +1,80 @@
+import { parseArgs } from 'node:util'
+
+const { values } = parseArgs({
+	allowPositionals: true,
+	args: Bun.argv.slice(2),
+	options: {
+		/**
+		 * Global output format. Defaults to `FORMAT` env var.
+		 */
+		format: {
+			default: Bun.env.FORMAT,
+			short: 'f',
+			type: 'string'
+		},
+		/**
+		 * Target height. Defaults to `HEIGHT` env var.
+		 */
+		height: {
+			default: Bun.env.HEIGHT,
+			short: 'h',
+			type: 'string'
+		},
+		/**
+		 * Input directory path. Defaults to `INPUT_FOLDER` env var.
+		 */
+		input: {
+			default: Bun.env.INPUT_FOLDER,
+			short: 'i',
+			type: 'string'
+		},
+		/**
+		 * Concurrent processing limit. Defaults to `LIMIT` env var.
+		 */
+		limit: {
+			default: Bun.env.LIMIT,
+			short: 'l',
+			type: 'string'
+		},
+		/**
+		 * Output directory path. Defaults to `OUTPUT_FOLDER` env var.
+		 */
+		output: {
+			default: Bun.env.OUTPUT_FOLDER,
+			short: 'o',
+			type: 'string'
+		},
+		/**
+		 * Shortcut to set both width and height to the same value.
+		 */
+		size: {
+			short: 's',
+			type: 'string'
+		},
+		/**
+		 * Target width. Defaults to `WIDTH` env var.
+		 */
+		width: {
+			default: Bun.env.WIDTH,
+			short: 'w',
+			type: 'string'
+		}
+	},
+	strict: true
+})
+
+const hasSize = Number(values.size) > 0
+
+const rawWidth = hasSize ? values.size : values.width
+const rawHeight = hasSize ? values.size : values.height
+
+const width = Number(rawWidth)
+const height = Number(rawHeight)
+const limit = Number(values.limit)
+const { input, output, format } = values
+
+/**
+ * The consolidated CLI configuration object.
+ * Contains resolved paths, dimensions, and processing limits.
+ */
+export const cli = { format, height, input, limit, output, width }

package/src/lib/error.ts

@@ -0,0 +1,21 @@
+/**
+ * Extracts a human-readable error message from an unknown error type.
+ *
+ * This utility is used to safely handle errors caught in catch blocks,
+ * ensuring that the output is always a string that can be displayed or logged.
+ *
+ * @param error - The error to extract the message from.
+ *
+ * @returns The error message if it's an Error instance or a string; otherwise, a default message.
+ */
+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

@@ -0,0 +1,62 @@
+import { exists, mkdir } from 'node:fs/promises'
+
+import { log } from '@clack/prompts'
+
+import { askInputPath, askOutputPath } from '@/prompt'
+
+/**
+ * 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.
+ *
+ * @param input - The input path provided via CLI, if any.
+ *
+ * @returns A promise that resolves to the chosen input path string.
+ */
+export const getInputPath = (input: string) => {
+	if (input) {
+		log.info(`input folder provided: ${input}`)
+		return Promise.resolve(input)
+	}
+
+	return askInputPath()
+}
+
+/**
+ * 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.
+ *
+ * @param output - The output path provided via CLI, if any.
+ *
+ * @returns A promise that resolves to the chosen output path string.
+ */
+export const getOutputPath = (output: string) => {
+	if (output) {
+		log.info(`output folder provided: ${output}`)
+		return Promise.resolve(output)
+	}
+	return askOutputPath()
+}
+
+/**
+ * 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.
+ *
+ * @param output - The path to the output directory.
+ *
+ * @returns A promise that resolves when the directory is verified or created.
+ */
+export const ensureOutputExists = async (output: string) => {
+	const outputExists = await exists(output)
+
+	if (!outputExists) {
+		await mkdir(output, { recursive: true })
+	}
+
+	log.info(`output folder ready: ${output} ✅\n`, { spacing: 0 })
+}

package/src/lib/image.ts

@@ -0,0 +1,144 @@
+import { join, parse } from 'node:path'
+
+import { type Option } from '@clack/prompts'
+import sharp, { type AvailableFormatInfo } from 'sharp'
+
+import { askExtensions, askWidthAndHeight } from '@/prompt'
+
+/**
+ * Parameters for the image resizing operation.
+ */
+interface ResizeParams {
+	/**
+	 * The relative path of the image within the input directory.
+	 */
+	readonly image: string
+	/**
+	 * The absolute or relative path to the input directory.
+	 */
+	readonly input: string
+	/**
+	 * The absolute or relative path to the output directory.
+	 */
+	readonly output: string
+	/**
+	 * The target width for the resized image.
+	 */
+	readonly width: number
+	/**
+	 * The target height for the resized image.
+	 */
+	readonly height: number
+	/**
+	 * The filename (without extension) for the output file.
+	 */
+	readonly name: string
+	/**
+	 * The target file extension (e.g., '.png', '.webp') for the output file.
+	 */
+	readonly extension: string
+}
+
+/**
+ * Type guard to check if a value is a Sharp AvailableFormatInfo object.
+ *
+ * @param value - The value to check.
+ *
+ * @returns True if the value matches the AvailableFormatInfo structure.
+ */
+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.
+ *
+ * @returns An array of Clack prompt options representing supported formats.
+ */
+const getSharpFormats = () => {
+	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}` }))
+
+	return formats
+}
+
+/**
+ * Resolves the target width and height for image processing.
+ *
+ * If both dimensions are provided via CLI and are valid, they are used.
+ * Otherwise, it prompts the user to enter the desired dimensions.
+ *
+ * @param width - The width provided via CLI.
+ * @param height - The height provided via CLI.
+ *
+ * @returns A promise that resolves to an object containing the width and height.
+ */
+export const getWidthAndHeight = (width: number, height: number) => {
+	const notWidth = isNaN(width) || width <= 0
+	const notHeight = isNaN(height) || height <= 0
+
+	if (notWidth && notHeight) {
+		return askWidthAndHeight()
+	}
+
+	return Promise.resolve({ height, width })
+}
+
+/**
+ * Determines the output extensions for a set of 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.
+ *
+ * @param images - An array of image filenames to analyze.
+ * @param format - An optional global output format.
+ *
+ * @returns A promise that resolves to a record mapping input extensions to 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 file = parse(image)
+				return file.ext ? file.ext.toLowerCase() : ''
+			})
+		)
+	].filter(Boolean)
+
+	const formats = getSharpFormats()
+	return askExtensions(extensions, formats)
+}
+
+/**
+ * Resizes an image 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.
+ *
+ * @param params - The parameters for the resize operation.
+ *
+ * @returns A promise that resolves to a success message string.
+ * @throws Error if the image processing fails.
+ */
+export const resize = async (params: ResizeParams) => {
+	const { image, input, output, width, height, name, extension } = params
+
+	try {
+		const inputPath = join(input, image)
+		const outputPath = join(output, `${name}${extension}`)
+
+		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 })
+	}
+}

package/src/lib/prompt.ts

@@ -0,0 +1,151 @@
+import { join } from 'node:path'
+
+import { type Option, cancel, group, path, select, text } from '@clack/prompts'
+
+/**
+ * Prompts the user to select the input directory containing images.
+ *
+ * Uses a directory picker with validation to ensure a non-empty path is provided.
+ * If the user cancels the prompt, the process exits.
+ *
+ * @returns A promise that resolves to the selected input path string.
+ */
+export const askInputPath = async () => {
+	const result = await path({
+		directory: true,
+		message: 'where are the images you want to transform? 📂',
+		root: process.cwd(),
+		validate: value => {
+			if (value === null || value?.trim().length === 0) {
+				return 'folder path is required'
+			}
+			return undefined
+		}
+	})
+
+	if (typeof result === 'symbol') {
+		cancel('operation cancelled by the user! 💀')
+		process.exit(0)
+	}
+
+	return result
+}
+
+/**
+ * Prompts the user for the output location and folder name.
+ *
+ * Combines two prompts: one for the parent directory and another for the new folder's name.
+ * The results are joined to create a complete output path.
+ * If the user cancels either prompt, the process exits.
+ *
+ * @returns A promise that resolves to the combined output directory path.
+ */
+export const askOutputPath = async () => {
+	const { location, name } = await group(
+		{
+			location: () =>
+				path({
+					directory: true,
+					message: 'where do you want to save the images? 📂',
+					root: process.cwd(),
+					validate: value => {
+						if (value === null || value?.trim().length === 0) {
+							return 'folder path is required'
+						}
+						return undefined
+					}
+				}),
+			name: () =>
+				text({
+					message: 'how do you wish to name the output folder? 🏷️',
+					placeholder: 'output',
+					validate: value => {
+						if (value === null || value?.trim().length === 0) {
+							return 'folder name is required'
+						}
+						return undefined
+					}
+				})
+		},
+		{
+			onCancel: () => {
+				cancel('operation cancelled by the user! 💀')
+				process.exit(0)
+			}
+		}
+	)
+
+	return join(location, name)
+}
+
+/**
+ * Prompts the user for the target width and height of the images.
+ *
+ * Validates that both inputs are positive numbers.
+ *
+ * @returns A promise that resolves to an object containing the numeric width and height.
+ */
+export const askWidthAndHeight = async () => {
+	const { width, height } = await group({
+		height: () =>
+			text({
+				message: 'what height do you want to use for the output images? 📐',
+				placeholder: 'e.g. 600',
+				validate: value => {
+					const number = Number(value)
+					if (isNaN(number) || number <= 0) {
+						return 'please enter a valid positive number for height 🚫'
+					}
+					return undefined
+				}
+			}),
+		width: () =>
+			text({
+				message: 'what width do you want to use for the output images? 📏',
+				placeholder: 'e.g. 800',
+				validate: value => {
+					const number = Number(value)
+					if (isNaN(number) || number <= 0) {
+						return 'please enter a valid positive number for width 🚫'
+					}
+					return undefined
+				}
+			})
+	})
+
+	return { height: Number(height), width: Number(width) }
+}
+
+/**
+ * Prompts the user to select an output format for each unique file extension found.
+ *
+ * Dynamically generates a group of selection prompts based on the provided extensions.
+ * If the user cancels any selection, 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.
+ *
+ * @returns A promise that resolves to a record mapping each original extension to its chosen output format.
+ */
+export const askExtensions = (extensions: readonly string[], formats: readonly Readonly<Option<string>>[]) => {
+	const promptGroups: Record<string, () => Promise<string | symbol>> = {}
+
+	for (const extension of extensions) {
+		if (!extension) {
+			continue
+		}
+
+		promptGroups[extension] = () =>
+			select({
+				message: `what format do you want to use for ${extension} files? 🎨`,
+				options: [...formats]
+			})
+	}
+
+	return group(promptGroups, {
+		onCancel: () => {
+			cancel('operation cancelled by the user! 💀')
+			process.exit(0)
+		}
+	})
+}

package/tsconfig.json

@@ -0,0 +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"]
+}