avifify 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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,220 @@
+# avifify
+
+Production-ready CLI tool to convert images to AVIF format. Run on demand, in CI/CD pipelines, or as a git pre-push hook.
+
+AVIF offers **30-60% better compression** than JPEG and **20-40% better** than WebP at equivalent visual quality. This tool makes adoption painless.
+
+## Quick Start
+
+```bash
+# Install
+npm install avifify --save-dev
+
+# Convert all images in the current directory
+npx avifify
+
+# Convert specific paths
+npx avifify src/assets "public/images/**/*.png"
+
+# Preview without changing anything
+npx avifify --dry-run --verbose
+
+# Install as a git pre-push hook
+npx avifify hook install
+```
+
+## Features
+
+- **Fast** — parallel conversion using [sharp](https://sharp.pixelplumbing.com/) (libvips)
+- **Smart defaults** — quality 50, skips if AVIF is larger, auto-concurrency
+- **Git hook ready** — install as `pre-push` or `pre-commit` hook in one command
+- **Pipeline friendly** — `--json` output, proper exit codes, non-TTY aware
+- **Configurable** — `.avififyrc.json`, `package.json`, or CLI flags
+- **Safe** — dry-run mode, skip-larger protection, preserves originals on demand
+- **Programmatic API** — import and use in Node.js scripts or build tools
+
+## Supported Input Formats
+
+JPEG, PNG, WebP, TIFF, GIF, BMP, HEIF/HEIC
+
+> SVG is excluded by default (vector format — converting to AVIF is lossy and almost never desirable). You can force it by passing SVG files explicitly.
+
+## CLI Reference
+
+```
+avifify [options] [paths...]
+```
+
+### Encoding Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-q, --quality <n>` | `50` | AVIF quality (1-100, lower = smaller) |
+| `-s, --speed <n>` | `5` | Encoding speed (0-8, lower = better compression) |
+| `--lossless` | `false` | Lossless encoding |
+| `--chroma <mode>` | `4:2:0` | Chroma subsampling (`4:2:0` or `4:4:4`) |
+
+### Output Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-o, --out-dir <dir>` | in-place | Write AVIF files to a separate directory |
+| `--suffix <str>` | none | Suffix before extension (e.g. `--suffix .min` → `photo.min.avif`) |
+| `--preserve` | `false` | Keep original files after conversion |
+
+### Behavior Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--skip-larger` | `true` | Don't keep AVIF if it's bigger than the original |
+| `--no-skip-larger` | | Always keep AVIF output |
+| `--skip-existing` | `false` | Skip conversion if `.avif` already exists |
+| `--staged-only` | `false` | Only process git-staged images |
+| `--changed-since-push` | `false` | Only process images changed since last push |
+| `-c, --concurrency <n>` | CPU-1 | Number of parallel conversions |
+| `-n, --dry-run` | `false` | Preview changes without writing files |
+
+### Output Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON Lines output (for piping to `jq` etc.) |
+| `-v, --verbose` | Detailed per-file progress |
+| `--debug` | Everything (very noisy) |
+| `--silent` | Suppress all output |
+
+### Hook Commands
+
+```bash
+avifify hook install              # Install pre-push hook
+avifify hook install --hook-type pre-commit  # Use pre-commit instead
+avifify hook uninstall            # Remove the hook
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All files converted (or nothing to do) |
+| `1` | Some files failed to convert |
+| `2` | Bad arguments or config error |
+
+## Configuration
+
+Config is resolved with this precedence: **CLI flags > `.avififyrc.json` > `package.json` > defaults**
+
+### `.avififyrc.json`
+
+```json
+{
+  "quality": 40,
+  "speed": 4,
+  "include": ["src/images/**"],
+  "exclude": ["**/thumbnails/**"],
+  "preserveOriginal": true,
+  "skipLarger": true
+}
+```
+
+### `package.json`
+
+```json
+{
+  "avifify": {
+    "quality": 40,
+    "include": ["assets/**"]
+  }
+}
+```
+
+## Git Hook Integration
+
+### Standalone
+
+```bash
+npx avifify hook install
+```
+
+This creates a `pre-push` hook that:
+1. Scans staged image files
+2. Converts them to AVIF
+3. Auto-stages the new `.avif` files
+4. Blocks the push if conversion fails
+
+### With Husky
+
+If you're already using Husky, `avifify` detects the `.husky/` directory and installs there:
+
+```bash
+npx avifify hook install
+# Creates .husky/pre-push with avifify block
+```
+
+Or add it manually to an existing Husky hook:
+
+```bash
+# .husky/pre-push
+npx avifify --staged-only
+```
+
+### CI/CD Pipeline
+
+```yaml
+# GitHub Actions example
+- name: Convert images to AVIF
+  run: npx avifify --json --verbose
+```
+
+```yaml
+# GitLab CI example
+optimize-images:
+  script:
+    - npx avifify --json | tee avifify-report.json
+  artifacts:
+    reports:
+      dotenv: avifify-report.json
+```
+
+## Programmatic API
+
+```js
+import { avifify, convertFile } from 'avifify';
+
+// Batch convert
+const results = await avifify({
+  quality: 40,
+  paths: ['src/images'],
+  preserveOriginal: true,
+});
+
+console.log(`Converted ${results.filter(r => r.status === 'converted').length} files`);
+
+// Single file
+const result = await convertFile('photo.jpg', { quality: 50 });
+console.log(result);
+// { file: 'photo.jpg', output: 'photo.avif', status: 'converted', savedBytes: 123456, ... }
+```
+
+## Why AVIF?
+
+| Format | Lossy Compression | Browser Support (2024) |
+|--------|-------------------|----------------------|
+| JPEG | Baseline | 100% |
+| WebP | ~30% better than JPEG | 97% |
+| **AVIF** | **~50% better than JPEG** | **95%+** |
+
+AVIF supports transparency, HDR, wide color gamuts, and both lossy and lossless modes. It's the clear successor for web images.
+
+## Quality Guide
+
+| Quality | Use Case | Typical Savings |
+|---------|----------|-----------------|
+| 30-40 | Thumbnails, backgrounds | 70-80% smaller |
+| 50 | General web images (default) | 50-65% smaller |
+| 60-70 | Photography, hero images | 40-55% smaller |
+| 80-90 | High-fidelity, print-ready | 20-35% smaller |
+| 100 / `--lossless` | Archival, pixel-perfect | 10-30% smaller |
+
+## License
+
+MIT

package/bin/avifify.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/**
+ * avifify - Convert images to AVIF format
+ *
+ * Usage:
+ *   avifify [options] [paths...]
+ *   avifify hook install
+ *   avifify hook uninstall
+ *
+ * Run `avifify --help` for full usage info.
+ */
+
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "avifify",
+  "version": "1.0.0",
+  "description": "Production-ready CLI tool to convert images to AVIF. Run standalone, in CI/CD pipelines, or as a git pre-push hook.",
+  "keywords": [
+    "avif",
+    "image",
+    "converter",
+    "compression",
+    "optimize",
+    "git-hook",
+    "pre-push",
+    "cli",
+    "pipeline",
+    "sharp"
+  ],
+  "author": "is-harshul",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "avifify": "./bin/avifify.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test 'tests/**/*.test.js'",
+    "lint": "echo 'Add your linter here'",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "sharp": "^0.33.0",
+    "fast-glob": "^3.3.0"
+  },
+  "devDependencies": {
+    "c8": "^8.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,251 @@
+/**
+ * CLI entry point — parses args, resolves config, orchestrates conversion.
+ */
+
+import { resolveConfig } from './config.js';
+import { scanFiles, getChangedSinceLastPush } from './scanner.js';
+import { convertBatch } from './converter.js';
+import { createLogger } from './logger.js';
+import { installHook, uninstallHook } from './hooks.js';
+
+const VERSION = '1.0.0';
+
+const HELP = `
+  avifify v${VERSION}
+  Convert images to AVIF — on demand, in CI/CD, or as a git hook.
+
+  USAGE
+    avifify [options] [paths...]         Convert matching images to AVIF
+    avifify hook install [--hook-type]   Install git hook (default: pre-push)
+    avifify hook uninstall               Remove git hook
+
+  PATHS
+    Provide files, directories, or glob patterns.
+    Defaults to scanning the current directory using include/exclude config.
+
+  OPTIONS
+    -q, --quality <n>        AVIF quality 1-100           (default: 50)
+    -s, --speed <n>          Encoding speed 0-8            (default: 5)
+    --lossless               Enable lossless encoding
+    --chroma <mode>          Chroma subsampling 4:2:0|4:4:4 (default: 4:2:0)
+
+    -o, --out-dir <dir>      Output directory (default: in-place)
+    --suffix <str>           Add suffix before .avif       (e.g. ".min")
+    --preserve               Keep original files            (default: delete)
+
+    --skip-larger            Don't keep AVIF if it's bigger (default: true)
+    --no-skip-larger         Always keep the AVIF output
+    --skip-existing          Skip if .avif file exists
+    --staged-only            Only process git-staged images
+    --changed-since-push     Only process images changed since last push
+
+    -c, --concurrency <n>    Parallel conversions           (default: CPU-1)
+    -n, --dry-run            Preview changes without writing
+    --json                   Output JSON lines (for pipelines)
+
+    -v, --verbose            Show detailed progress
+    --debug                  Show everything (very noisy)
+    --silent                 Suppress all output
+
+    --hook-type <type>       Hook type: pre-push|pre-commit (default: pre-push)
+    -h, --help               Show this help
+    --version                Show version
+
+  CONFIG FILES
+    .avififyrc or .avififyrc.json in project root:
+      { "quality": 40, "include": ["src/images/**"], "preserve": true }
+
+    Or in package.json:
+      { "avifify": { "quality": 40 } }
+
+    CLI args override config files. Config files override defaults.
+
+  EXAMPLES
+    avifify                         # Convert all images in current dir
+    avifify src/assets              # Convert images in specific directory
+    avifify "**/*.png"              # Convert only PNGs
+    avifify -q 30 --preserve        # Low quality, keep originals
+    avifify --dry-run --verbose     # Preview what would happen
+    avifify --json | jq             # Pipe JSON output to jq
+    avifify hook install            # Install pre-push git hook
+    avifify --changed-since-push    # Only convert images changed since last push
+
+  EXIT CODES
+    0  All files converted successfully (or nothing to do)
+    1  Some files failed to convert
+    2  Invalid arguments or configuration error
+`;
+
+/**
+ * Parse CLI arguments (minimal parser, no dependencies).
+ */
+function parseArgs(argv) {
+  const args = { _: [] };
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    // Flags with values
+    const withValue = {
+      '-q': 'quality', '--quality': 'quality',
+      '-s': 'speed', '--speed': 'speed',
+      '-o': 'outDir', '--out-dir': 'outDir',
+      '-c': 'concurrency', '--concurrency': 'concurrency',
+      '--suffix': 'suffix',
+      '--chroma': 'chromaSubsampling',
+      '--hook-type': 'hookType',
+    };
+
+    // Boolean flags
+    const booleans = {
+      '--lossless': 'lossless',
+      '--preserve': 'preserveOriginal',
+      '--skip-larger': ['skipLarger', true],
+      '--no-skip-larger': ['skipLarger', false],
+      '--skip-existing': 'skipExisting',
+      '--staged-only': 'stagedOnly',
+      '--changed-since-push': 'changedSincePush',
+      '-n': 'dryRun', '--dry-run': 'dryRun',
+      '--json': 'json',
+      '-v': 'verbose', '--verbose': 'verbose',
+      '--debug': 'debug',
+      '--silent': 'silent',
+      '-h': 'help', '--help': 'help',
+      '--version': 'version',
+    };
+
+    if (withValue[arg]) {
+      const key = withValue[arg];
+      const val = argv[++i];
+      if (val === undefined) {
+        console.error(`Missing value for ${arg}`);
+        process.exit(2);
+      }
+      // Convert numeric values
+      args[key] = ['quality', 'speed', 'concurrency'].includes(key) ? Number(val) : val;
+    } else if (booleans[arg]) {
+      const mapping = booleans[arg];
+      if (Array.isArray(mapping)) {
+        args[mapping[0]] = mapping[1];
+      } else {
+        args[mapping] = true;
+      }
+    } else if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}\nRun 'avifify --help' for usage.`);
+      process.exit(2);
+    } else {
+      args._.push(arg);
+    }
+
+    i++;
+  }
+
+  return args;
+}
+
+/**
+ * Main CLI entry point.
+ */
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  // Simple flags
+  if (args.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (args.version) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  // Sub-commands
+  const subcommand = args._[0];
+  if (subcommand === 'hook') {
+    return handleHookCommand(args);
+  }
+
+  // Main conversion flow
+  try {
+    const config = await resolveConfig(args);
+    const logger = createLogger({ level: config.logLevel, json: config.json });
+
+    logger.debug('Resolved config:', config);
+
+    // Discover files
+    let files;
+    if (config.changedSincePush) {
+      logger.info('Scanning for images changed since last push…');
+      files = await getChangedSinceLastPush(process.cwd());
+    } else {
+      logger.info('Scanning for images…');
+      files = await scanFiles(config, args._.length > 0 ? args._ : [], process.cwd());
+    }
+
+    if (files.length === 0) {
+      logger.info('No images found matching the configured patterns.');
+      process.exit(0);
+    }
+
+    logger.info(`Found ${files.length} image${files.length === 1 ? '' : 's'} to process`);
+
+    if (config.dryRun) {
+      logger.info('Dry run — no files will be modified\n');
+    }
+
+    // Convert
+    const results = await convertBatch(files, config, logger);
+
+    // Summarize
+    const summary = results.reduce(
+      (acc, r) => {
+        acc.total++;
+        if (r.status === 'converted') {
+          acc.converted++;
+          acc.savedBytes += r.savedBytes ?? 0;
+        } else if (r.status === 'skipped') {
+          acc.skipped++;
+        } else {
+          acc.errors++;
+        }
+        return acc;
+      },
+      { total: 0, converted: 0, skipped: 0, errors: 0, savedBytes: 0 }
+    );
+
+    logger.summary(summary);
+
+    // Exit code: 1 if any errors, 0 otherwise
+    process.exit(summary.errors > 0 ? 1 : 0);
+  } catch (err) {
+    const logger = createLogger({ level: 'error', json: args.json });
+    logger.error(err.message);
+    if (args.debug) logger.error(err.stack);
+    process.exit(2);
+  }
+}
+
+/**
+ * Handle `avifify hook install` / `avifify hook uninstall`
+ */
+async function handleHookCommand(args) {
+  const action = args._[1];
+  const hookType = args.hookType ?? 'pre-push';
+  const logger = createLogger({ level: args.silent ? 'silent' : 'info', json: args.json });
+
+  try {
+    if (action === 'install') {
+      await installHook({ hookType }, logger);
+    } else if (action === 'uninstall') {
+      await uninstallHook({ hookType }, logger);
+    } else {
+      console.error(`Unknown hook action: ${action}\nUsage: avifify hook install|uninstall`);
+      process.exit(2);
+    }
+  } catch (err) {
+    logger.error(err.message);
+    process.exit(2);
+  }
+}

package/src/config.js

@@ -0,0 +1,128 @@
+/**
+ * Configuration resolution with layered precedence:
+ *   defaults < .avififyrc.json < package.json["avifify"] < CLI args
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const DEFAULTS = {
+  // Paths / Globs
+  include: ['**/*.{jpg,jpeg,png,webp,tiff,tif,gif,bmp,heif,heic}'],
+  exclude: ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/vendor/**'],
+
+  // Output
+  outDir: null,          // null = convert in-place (same directory)
+  suffix: '',            // e.g. '.min' → photo.min.avif  (empty = photo.avif)
+  preserveOriginal: false,
+
+  // AVIF encoding options
+  quality: 50,           // 1-100, lower = smaller. 50 is a solid default
+  speed: 5,              // 0-8, lower = slower but better compression
+  effort: 5,             // alias for speed (sharp uses this)
+  lossless: false,
+  chromaSubsampling: '4:2:0', // '4:2:0' or '4:4:4'
+
+  // Behavior
+  concurrency: null,     // null = auto (CPU count)
+  skipLarger: true,      // skip if AVIF is bigger than the original
+  skipExisting: false,   // skip if .avif already exists
+  dryRun: false,
+  json: false,
+  verbose: false,
+  debug: false,
+  silent: false,
+
+  // Git hook specific
+  stagedOnly: false,     // only process git-staged files
+};
+
+const RC_FILENAMES = ['.avififyrc', '.avififyrc.json'];
+
+/**
+ * Walk up from `cwd` to find the nearest config file.
+ */
+async function findRcFile(cwd) {
+  let dir = resolve(cwd);
+  const root = dirname(dir) === dir ? dir : undefined;
+
+  while (true) {
+    for (const name of RC_FILENAMES) {
+      const candidate = resolve(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir || dir === root) break;
+    dir = parent;
+  }
+  return null;
+}
+
+async function loadJsonFile(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the final config object.
+ *
+ * @param {object} cliArgs - Parsed CLI arguments (only defined keys)
+ * @param {string} cwd     - Working directory
+ * @returns {Promise<object>} Merged configuration
+ */
+export async function resolveConfig(cliArgs = {}, cwd = process.cwd()) {
+  // Layer 1: RC file
+  const rcPath = await findRcFile(cwd);
+  const rcConfig = rcPath ? (await loadJsonFile(rcPath)) ?? {} : {};
+
+  // Layer 2: package.json "avifify" key
+  const pkgPath = resolve(cwd, 'package.json');
+  const pkg = await loadJsonFile(pkgPath);
+  const pkgConfig = pkg?.avifify ?? {};
+
+  // Merge with precedence
+  const merged = { ...DEFAULTS, ...rcConfig, ...pkgConfig, ...stripUndefined(cliArgs) };
+
+  // Normalize
+  merged.quality = clamp(merged.quality, 1, 100);
+  merged.speed = clamp(merged.speed, 0, 8);
+  merged.effort = merged.speed; // sharp calls it `effort`
+
+  if (merged.concurrency === null) {
+    const { availableParallelism } = await import('node:os');
+    merged.concurrency = Math.max(1, (availableParallelism?.() ?? 4) - 1);
+  }
+
+  if (merged.outDir) {
+    merged.outDir = resolve(cwd, merged.outDir);
+  }
+
+  // Determine log level
+  if (merged.silent) merged.logLevel = 'silent';
+  else if (merged.debug) merged.logLevel = 'debug';
+  else if (merged.verbose) merged.logLevel = 'verbose';
+  else merged.logLevel = 'info';
+
+  // Source info for debugging
+  merged._sources = {
+    rc: rcPath ?? null,
+    pkg: pkg?.avifify ? pkgPath : null,
+  };
+
+  return merged;
+}
+
+function stripUndefined(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+
+function clamp(val, min, max) {
+  return Math.min(max, Math.max(min, Number(val) || min));
+}
+
+export { DEFAULTS };

package/src/converter.js

@@ -0,0 +1,189 @@
+/**
+ * Core AVIF converter: processes files with concurrency control,
+ * progress reporting, and detailed result tracking.
+ */
+
+import sharp from 'sharp';
+import { stat, mkdir, unlink, access } from 'node:fs/promises';
+import { dirname, basename, extname, join, relative, resolve } from 'node:path';
+import { formatBytes } from './logger.js';
+
+/**
+ * @typedef {Object} ConvertResult
+ * @property {string}  file         - Original file path
+ * @property {string}  output       - Output file path
+ * @property {'converted'|'skipped'|'error'} status
+ * @property {number}  [inputSize]  - Original file size in bytes
+ * @property {number}  [outputSize] - AVIF file size in bytes
+ * @property {number}  [savedBytes] - Bytes saved (positive = smaller)
+ * @property {string}  [reason]     - Why it was skipped or errored
+ * @property {number}  [duration]   - Conversion time in ms
+ */
+
+/**
+ * Convert a batch of image files to AVIF.
+ *
+ * @param {string[]} files  - Absolute paths of source images
+ * @param {object}   config - Resolved configuration
+ * @param {object}   logger - Logger instance
+ * @returns {Promise<ConvertResult[]>}
+ */
+export async function convertBatch(files, config, logger) {
+  const results = [];
+  const { concurrency } = config;
+  let completed = 0;
+
+  // Process files in chunks for controlled concurrency
+  for (let i = 0; i < files.length; i += concurrency) {
+    const chunk = files.slice(i, i + concurrency);
+
+    const chunkResults = await Promise.allSettled(
+      chunk.map(file => convertSingle(file, config, logger))
+    );
+
+    for (const result of chunkResults) {
+      const res = result.status === 'fulfilled'
+        ? result.value
+        : { file: 'unknown', status: 'error', reason: result.reason?.message ?? String(result.reason) };
+
+      results.push(res);
+      completed++;
+      logger.progress(completed, files.length, res.file);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Convert a single image file to AVIF.
+ *
+ * @param {string} filePath - Absolute path to the source image
+ * @param {object} config   - Resolved configuration
+ * @param {object} logger   - Logger instance
+ * @returns {Promise<ConvertResult>}
+ */
+export async function convertSingle(filePath, config, logger) {
+  const start = Date.now();
+  const cwd = process.cwd();
+  const relPath = relative(cwd, filePath);
+
+  try {
+    // Determine output path
+    const outputPath = getOutputPath(filePath, config);
+    const relOutput = relative(cwd, outputPath);
+
+    // Check if output already exists
+    if (config.skipExisting) {
+      try {
+        await access(outputPath);
+        logger.verbose(`Skipped (exists): ${relPath}`);
+        return { file: relPath, output: relOutput, status: 'skipped', reason: 'already exists' };
+      } catch {
+        // File doesn't exist, proceed
+      }
+    }
+
+    // Get input file size
+    const inputStat = await stat(filePath);
+    const inputSize = inputStat.size;
+
+    // Dry run — report what would happen
+    if (config.dryRun) {
+      logger.info(`[dry-run] Would convert: ${relPath} → ${relOutput}`);
+      return { file: relPath, output: relOutput, status: 'skipped', reason: 'dry run', inputSize };
+    }
+
+    // Ensure output directory exists
+    const outDir = dirname(outputPath);
+    await mkdir(outDir, { recursive: true });
+
+    // Build the sharp pipeline
+    let pipeline = sharp(filePath, {
+      failOn: 'none',       // Don't fail on minor issues
+      sequentialRead: true,  // Better memory usage for large images
+    });
+
+    // Optionally get metadata for logging
+    const metadata = logger.isVerbose ? await pipeline.metadata() : null;
+
+    // Convert to AVIF
+    pipeline = pipeline.avif({
+      quality: config.lossless ? 100 : config.quality,
+      effort: config.effort,
+      lossless: config.lossless,
+      chromaSubsampling: config.chromaSubsampling,
+    });
+
+    // Write output
+    const outputInfo = await pipeline.toFile(outputPath);
+    const outputSize = outputInfo.size;
+    const savedBytes = inputSize - outputSize;
+    const duration = Date.now() - start;
+
+    // Skip if AVIF is larger and config says so
+    if (config.skipLarger && outputSize >= inputSize) {
+      // Remove the larger AVIF file
+      try { await unlink(outputPath); } catch { /* ignore */ }
+      logger.verbose(`Skipped (AVIF larger): ${relPath} — ${formatBytes(inputSize)} → ${formatBytes(outputSize)}`);
+      return {
+        file: relPath,
+        output: relOutput,
+        status: 'skipped',
+        reason: 'avif is larger',
+        inputSize,
+        outputSize,
+        savedBytes,
+        duration,
+      };
+    }
+
+    // Delete original if not preserving
+    if (!config.preserveOriginal && outputPath !== filePath) {
+      try { await unlink(filePath); } catch { /* ignore */ }
+    }
+
+    const pct = inputSize > 0 ? Math.round((1 - outputSize / inputSize) * 100) : 0;
+    logger.verbose(
+      `Converted: ${relPath} → ${formatBytes(inputSize)} → ${formatBytes(outputSize)} (${pct}% smaller, ${duration}ms)`,
+      metadata ? { dimensions: `${metadata.width}×${metadata.height}` } : undefined
+    );
+
+    return {
+      file: relPath,
+      output: relOutput,
+      status: 'converted',
+      inputSize,
+      outputSize,
+      savedBytes,
+      duration,
+    };
+  } catch (err) {
+    const duration = Date.now() - start;
+    logger.error(`Failed: ${relPath} — ${err.message}`);
+    logger.debug(err.stack);
+    return {
+      file: relPath,
+      output: null,
+      status: 'error',
+      reason: err.message,
+      duration,
+    };
+  }
+}
+
+/**
+ * Compute the output .avif path for a given input file.
+ */
+function getOutputPath(filePath, config) {
+  const ext = extname(filePath);
+  const base = basename(filePath, ext);
+  const dir = config.outDir
+    ? resolve(config.outDir, relative(process.cwd(), dirname(filePath)))
+    : dirname(filePath);
+
+  const suffix = config.suffix || '';
+  return join(dir, `${base}${suffix}.avif`);
+}
+
+export { getOutputPath };

package/src/hooks.js

@@ -0,0 +1,161 @@
+/**
+ * Git hook management — install/uninstall avifify as a git hook.
+ *
+ * Supports:
+ *   - Direct .git/hooks/ installation
+ *   - Husky v4+ integration (detects .husky/ directory)
+ *   - Custom hooks directory (core.hooksPath)
+ */
+
+import { readFile, writeFile, chmod, mkdir, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const HOOK_MARKER_START = '# >>> avifify pre-push hook >>>';
+const HOOK_MARKER_END = '# <<< avifify pre-push hook <<<';
+
+const HOOK_TYPES = ['pre-push', 'pre-commit'];
+
+/**
+ * Generate the hook script content.
+ */
+function hookScript(hookType) {
+  return `${HOOK_MARKER_START}
+# Auto-generated by avifify — do not edit between markers
+npx avifify --staged-only
+AVIFIFY_EXIT=$?
+if [ $AVIFIFY_EXIT -ne 0 ]; then
+  echo "avifify: image conversion failed or found unconverted images"
+  echo "Run 'npx avifify' to convert images before pushing."
+  exit 1
+fi
+# If images were converted, auto-stage them
+git diff --name-only | grep '\\.avif$' | xargs -r git add
+${HOOK_MARKER_END}`;
+}
+
+/**
+ * Detect the git hooks directory.
+ */
+async function getHooksDir(cwd) {
+  // Check for husky directory
+  const huskyDir = resolve(cwd, '.husky');
+  if (existsSync(huskyDir)) {
+    return { type: 'husky', path: huskyDir };
+  }
+
+  // Check for custom hooksPath in git config
+  try {
+    const { stdout } = await execFileAsync('git', ['config', 'core.hooksPath'], { cwd });
+    const customPath = stdout.trim();
+    if (customPath) {
+      return { type: 'custom', path: resolve(cwd, customPath) };
+    }
+  } catch {
+    // No custom hooks path set
+  }
+
+  // Default to .git/hooks
+  const gitHooksDir = resolve(cwd, '.git', 'hooks');
+  if (existsSync(resolve(cwd, '.git'))) {
+    return { type: 'git', path: gitHooksDir };
+  }
+
+  throw new Error('Not a git repository (no .git directory found)');
+}
+
+/**
+ * Install the git hook.
+ *
+ * @param {object}  options
+ * @param {string}  [options.hookType='pre-push']  - Hook type
+ * @param {string}  [options.cwd=process.cwd()]    - Working directory
+ * @param {object}  logger                         - Logger instance
+ */
+export async function installHook({ hookType = 'pre-push', cwd = process.cwd() } = {}, logger) {
+  if (!HOOK_TYPES.includes(hookType)) {
+    throw new Error(`Unsupported hook type: ${hookType}. Supported: ${HOOK_TYPES.join(', ')}`);
+  }
+
+  const { type, path: hooksDir } = await getHooksDir(cwd);
+  await mkdir(hooksDir, { recursive: true });
+
+  const hookPath = join(hooksDir, hookType);
+  const script = hookScript(hookType);
+
+  if (existsSync(hookPath)) {
+    const existing = await readFile(hookPath, 'utf-8');
+
+    // Already installed?
+    if (existing.includes(HOOK_MARKER_START)) {
+      // Replace existing avifify block
+      const regex = new RegExp(
+        `${escapeRegex(HOOK_MARKER_START)}[\\s\\S]*?${escapeRegex(HOOK_MARKER_END)}`,
+        'm'
+      );
+      const updated = existing.replace(regex, script);
+      await writeFile(hookPath, updated, 'utf-8');
+      logger.success(`Updated avifify in existing ${hookType} hook (${type})`);
+    } else {
+      // Append to existing hook
+      const updated = existing.trimEnd() + '\n\n' + script + '\n';
+      await writeFile(hookPath, updated, 'utf-8');
+      logger.success(`Appended avifify to existing ${hookType} hook (${type})`);
+    }
+  } else {
+    // Create new hook file
+    const content = `#!/usr/bin/env sh\n\n${script}\n`;
+    await writeFile(hookPath, content, 'utf-8');
+    logger.success(`Created ${hookType} hook at ${hookPath} (${type})`);
+  }
+
+  // Make executable
+  await chmod(hookPath, 0o755);
+  logger.info(`Hook installed via ${type} at ${hookPath}`);
+}
+
+/**
+ * Uninstall the git hook (removes only the avifify block).
+ */
+export async function uninstallHook({ hookType = 'pre-push', cwd = process.cwd() } = {}, logger) {
+  const { type, path: hooksDir } = await getHooksDir(cwd);
+  const hookPath = join(hooksDir, hookType);
+
+  if (!existsSync(hookPath)) {
+    logger.warn(`No ${hookType} hook found at ${hookPath}`);
+    return;
+  }
+
+  const existing = await readFile(hookPath, 'utf-8');
+
+  if (!existing.includes(HOOK_MARKER_START)) {
+    logger.warn(`No avifify block found in ${hookType} hook`);
+    return;
+  }
+
+  const regex = new RegExp(
+    `\\n?${escapeRegex(HOOK_MARKER_START)}[\\s\\S]*?${escapeRegex(HOOK_MARKER_END)}\\n?`,
+    'm'
+  );
+  const cleaned = existing.replace(regex, '\n').trim();
+
+  // If the hook only had our content, remove the file entirely
+  const isShebangOnly = /^#!\/usr\/bin\/env\s+sh\s*$/m.test(cleaned) && cleaned.split('\n').filter(l => l.trim()).length <= 1;
+
+  if (!cleaned || isShebangOnly) {
+    await unlink(hookPath);
+    logger.success(`Removed ${hookType} hook entirely (was only avifify)`);
+  } else {
+    await writeFile(hookPath, cleaned + '\n', 'utf-8');
+    await chmod(hookPath, 0o755);
+    logger.success(`Removed avifify block from ${hookType} hook`);
+  }
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/index.js

@@ -0,0 +1,52 @@
+/**
+ * avifify — Programmatic API
+ *
+ * Usage:
+ *   import { avifify, convertFile } from 'avifify';
+ *
+ *   // Convert all images in a directory
+ *   const results = await avifify({ quality: 40, include: ['src/**'] });
+ *
+ *   // Convert a single file
+ *   const result = await convertFile('photo.jpg', { quality: 50 });
+ */
+
+import { resolveConfig } from './config.js';
+import { scanFiles } from './scanner.js';
+import { convertBatch, convertSingle, getOutputPath } from './converter.js';
+import { createLogger } from './logger.js';
+import { installHook, uninstallHook } from './hooks.js';
+
+/**
+ * Convert images to AVIF.
+ *
+ * @param {object}   [options]         - Override any config option
+ * @param {string[]} [options.paths]   - Explicit file/glob paths to process
+ * @param {string}   [options.cwd]     - Working directory (default: process.cwd())
+ * @returns {Promise<import('./converter.js').ConvertResult[]>}
+ */
+export async function avifify(options = {}) {
+  const { paths = [], cwd = process.cwd(), ...rest } = options;
+  const config = await resolveConfig({ ...rest, silent: rest.silent ?? true }, cwd);
+  const logger = createLogger({ level: config.logLevel, json: config.json });
+
+  const files = await scanFiles(config, paths, cwd);
+  if (files.length === 0) return [];
+
+  return convertBatch(files, config, logger);
+}
+
+/**
+ * Convert a single file to AVIF.
+ *
+ * @param {string}  filePath  - Path to the source image
+ * @param {object}  [options] - Override any config option
+ * @returns {Promise<import('./converter.js').ConvertResult>}
+ */
+export async function convertFile(filePath, options = {}) {
+  const config = await resolveConfig({ ...options, silent: options.silent ?? true });
+  const logger = createLogger({ level: 'silent' });
+  return convertSingle(filePath, config, logger);
+}
+
+export { installHook, uninstallHook, getOutputPath, resolveConfig };

package/src/logger.js

@@ -0,0 +1,125 @@
+/**
+ * Logger with TTY-aware formatting.
+ * - Interactive terminal: colored, human-readable output
+ * - Piped / CI: structured JSON lines (--json) or plain text
+ */
+
+const LEVELS = { silent: 0, error: 1, warn: 2, info: 3, verbose: 4, debug: 5 };
+
+// ANSI codes — stripped automatically when not a TTY
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const MAGENTA = '\x1b[35m';
+
+class Logger {
+  #level;
+  #json;
+  #isTTY;
+  #startTime;
+
+  constructor({ level = 'info', json = false } = {}) {
+    this.#level = LEVELS[level] ?? LEVELS.info;
+    this.#json = json;
+    this.#isTTY = process.stdout.isTTY && !json;
+    this.#startTime = Date.now();
+  }
+
+  get isVerbose() {
+    return this.#level >= LEVELS.verbose;
+  }
+
+  get isDebug() {
+    return this.#level >= LEVELS.debug;
+  }
+
+  #elapsed() {
+    return `${((Date.now() - this.#startTime) / 1000).toFixed(1)}s`;
+  }
+
+  #write(level, color, label, message, data) {
+    if (LEVELS[level] > this.#level) return;
+
+    if (this.#json) {
+      const entry = { level, message, timestamp: new Date().toISOString(), ...data };
+      process.stdout.write(JSON.stringify(entry) + '\n');
+      return;
+    }
+
+    const prefix = this.#isTTY ? `${color}${BOLD}${label}${RESET}` : label;
+    const dim = this.#isTTY ? DIM : '';
+    const reset = this.#isTTY ? RESET : '';
+
+    let line = `${prefix} ${message}`;
+    if (data?.file) line += ` ${dim}${data.file}${reset}`;
+    if (data?.saved) line += ` ${dim}(${data.saved})${reset}`;
+
+    const stream = level === 'error' ? process.stderr : process.stdout;
+    stream.write(line + '\n');
+  }
+
+  error(message, data) { this.#write('error', RED, '✖', message, data); }
+  warn(message, data) { this.#write('warn', YELLOW, '⚠', message, data); }
+  info(message, data) { this.#write('info', CYAN, '●', message, data); }
+  success(message, data) { this.#write('info', GREEN, '✔', message, data); }
+  verbose(message, data) { this.#write('verbose', MAGENTA, '…', message, data); }
+  debug(message, data) { this.#write('debug', DIM, '⊡', message, data); }
+
+  /** Print a summary table at the end */
+  summary({ total, converted, skipped, errors, savedBytes }) {
+    if (this.#json) {
+      process.stdout.write(JSON.stringify({
+        level: 'summary',
+        total,
+        converted,
+        skipped,
+        errors,
+        savedBytes,
+        elapsed: this.#elapsed(),
+      }) + '\n');
+      return;
+    }
+
+    const saved = formatBytes(savedBytes);
+    const c = this.#isTTY;
+    console.log('');
+    console.log(c ? `${BOLD}${GREEN}  avifify complete${RESET}` : '  avifify complete');
+    console.log(`  ─────────────────────────────`);
+    console.log(`  Files scanned   ${total}`);
+    console.log(`  Converted       ${c ? GREEN : ''}${converted}${c ? RESET : ''}`);
+    console.log(`  Skipped         ${skipped}`);
+    if (errors > 0) {
+      console.log(`  Errors          ${c ? RED : ''}${errors}${c ? RESET : ''}`);
+    }
+    console.log(`  Space saved     ${c ? CYAN : ''}${saved}${c ? RESET : ''}`);
+    console.log(`  Elapsed         ${this.#elapsed()}`);
+    console.log('');
+  }
+
+  /** Inline progress for TTY */
+  progress(current, total, file) {
+    if (!this.#isTTY || this.#level < LEVELS.info) return;
+    const pct = Math.round((current / total) * 100);
+    const bar = '█'.repeat(Math.floor(pct / 4)) + '░'.repeat(25 - Math.floor(pct / 4));
+    process.stdout.write(`\r${DIM}  ${bar} ${pct}% (${current}/${total})${RESET}  `);
+    if (current === total) process.stdout.write('\n');
+  }
+}
+
+export function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const neg = bytes < 0;
+  const abs = Math.abs(bytes);
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.min(Math.floor(Math.log(abs) / Math.log(1024)), units.length - 1);
+  const val = (abs / Math.pow(1024, i)).toFixed(i === 0 ? 0 : 1);
+  return `${neg ? '-' : ''}${val} ${units[i]}`;
+}
+
+export function createLogger(opts) {
+  return new Logger(opts);
+}

package/src/scanner.js

@@ -0,0 +1,127 @@
+/**
+ * File discovery: glob-based scanning or git-staged file detection.
+ */
+
+import fg from 'fast-glob';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve, extname } from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+const IMAGE_EXTENSIONS = new Set([
+  '.jpg', '.jpeg', '.png', '.webp', '.tiff', '.tif',
+  '.gif', '.bmp', '.heif', '.heic',
+]);
+
+/**
+ * Find image files matching the config patterns.
+ *
+ * @param {object} config - Resolved config
+ * @param {string[]} explicitPaths - Explicit file/dir paths from CLI positional args
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string[]>} Absolute paths of image files
+ */
+export async function scanFiles(config, explicitPaths = [], cwd = process.cwd()) {
+  // Mode 1: git-staged files only (for pre-push hook)
+  if (config.stagedOnly) {
+    return getStagedImages(cwd);
+  }
+
+  // Mode 2: explicit paths provided
+  if (explicitPaths.length > 0) {
+    const { statSync } = await import('node:fs');
+    const patterns = explicitPaths.map(p => {
+      // If it looks like a glob, use as-is
+      if (p.includes('*') || p.includes('{')) return p;
+      // If it's a directory, append recursive glob
+      try {
+        if (statSync(resolve(cwd, p)).isDirectory()) return `${p}/**/*`;
+      } catch { /* not a dir, treat as file path */ }
+      return p;
+    });
+
+    const files = await fg(patterns, {
+      cwd,
+      absolute: true,
+      onlyFiles: true,
+      ignore: config.exclude,
+      followSymbolicLinks: false,
+    });
+
+    return files.filter(f => IMAGE_EXTENSIONS.has(extname(f).toLowerCase()));
+  }
+
+  // Mode 3: scan using include/exclude globs
+  const files = await fg(config.include, {
+    cwd,
+    absolute: true,
+    onlyFiles: true,
+    ignore: config.exclude,
+    followSymbolicLinks: false,
+    dot: false,
+  });
+
+  return files.filter(f => IMAGE_EXTENSIONS.has(extname(f).toLowerCase()));
+}
+
+/**
+ * Get image files staged in git (for hook usage).
+ */
+async function getStagedImages(cwd) {
+  try {
+    // Get files staged for commit (including ones that are added/modified)
+    const { stdout } = await execFileAsync(
+      'git',
+      ['diff', '--cached', '--name-only', '--diff-filter=ACMR'],
+      { cwd, maxBuffer: 10 * 1024 * 1024 }
+    );
+
+    return stdout
+      .split('\n')
+      .map(f => f.trim())
+      .filter(f => f && IMAGE_EXTENSIONS.has(extname(f).toLowerCase()))
+      .map(f => resolve(cwd, f));
+  } catch (err) {
+    // Not a git repo or git not available
+    throw new Error(`Failed to get staged files: ${err.message}`);
+  }
+}
+
+/**
+ * Get image files changed since the last push (for pre-push hook).
+ */
+export async function getChangedSinceLastPush(cwd) {
+  try {
+    const { stdout } = await execFileAsync(
+      'git',
+      ['diff', '--name-only', '@{push}..HEAD', '--diff-filter=ACMR'],
+      { cwd, maxBuffer: 10 * 1024 * 1024 }
+    );
+
+    return stdout
+      .split('\n')
+      .map(f => f.trim())
+      .filter(f => f && IMAGE_EXTENSIONS.has(extname(f).toLowerCase()))
+      .map(f => resolve(cwd, f));
+  } catch {
+    // Fallback: if no upstream, scan all tracked images
+    try {
+      const { stdout } = await execFileAsync(
+        'git',
+        ['ls-files', '--cached'],
+        { cwd, maxBuffer: 10 * 1024 * 1024 }
+      );
+
+      return stdout
+        .split('\n')
+        .map(f => f.trim())
+        .filter(f => f && IMAGE_EXTENSIONS.has(extname(f).toLowerCase()))
+        .map(f => resolve(cwd, f));
+    } catch (err) {
+      throw new Error(`Failed to list git files: ${err.message}`);
+    }
+  }
+}
+
+export { IMAGE_EXTENSIONS };