feat: improve code base

.github/workflows/nodejs.yml

@@ -3,14 +3,16 @@ run-name: Node.js ⬢ CI
 
 on:
   push:
-    branches: [develop]
+    branches: [master]
+  pull_request:
+    branches: [master]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [22.x]
+        node-version: [24.x]
 
     name: Node.js ${{ matrix.node-version }} 🚀
     steps:
@@ -45,6 +47,10 @@ jobs:
         run: |
           pnpm install --frozen-lockfile
 
+      - name: Typecheck 🔎
+        run: |
+          pnpm run typecheck
+
       - name: Run tests 🧪
         run: |
           make test

.gitignore

@@ -2,3 +2,4 @@
 .vscode
 bin
 node_modules
+*.tsbuildinfo

.npmrc

@@ -1,3 +1,2 @@
 save-exact=true
 legacy-peer-deps=true
-ignore-scripts=true #giflossy, zopflipng

.nvmrc

@@ -1 +1 @@
-v22.5.1
+v26.8.1

.swcrc

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://json.schemastore.org/swcrc",
+  "$schema": "https://swc.rs/schema.json",
   "jsc": {
     "target": "esnext",
     "parser": {

CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DVX CLI is a TypeScript-based command-line tool for image processing and asset optimization in frontend development. It provides utilities for image minification, format conversion, resizing, HTML validation, and CSS source map cleaning.
+
+## Build & Development Commands
+
+### Building the project
+
+```bash
+pnpm run build
+```
+
+This compiles TypeScript to JavaScript using SWC, outputs to `bin/` directory, and replaces import paths.
+
+### Clean build artifacts
+
+```bash
+pnpm run build:clean
+```
+
+### Typechecking
+
+```bash
+pnpm run typecheck
+```
+
+SWC does not typecheck during build — run this before committing. CI runs it too.
+
+### Running tests
+
+```bash
+pnpm run test        # Run all tests (unit + features)
+pnpm run test:unit   # Run only unit tests
+make test            # Alternative using Makefile
+```
+
+### Running a single test file
+
+```bash
+node --import @swc-node/register/esm-register --test tests/lib/file.test.ts
+```
+
+### Code formatting
+
+```bash
+# Project uses Biome for formatting and linting
+# Configuration in biome.json
+```
+
+### Rebuilding native dependencies
+
+```bash
+pnpm run rebuild     # Rebuild native image processing binaries
+```
+
+### Dependency management
+
+```bash
+pnpm run package:update  # Update dependencies
+make deps/update         # Comprehensive dependency update with deduplication
+```
+
+## Code Architecture
+
+### Entry Point
+
+- `src/index.ts` - CLI entry: configures yargs and auto-registers commands via `.commandDir()`
+- `bin/index.js` - Built entry point for the CLI binary
+
+### Command Structure
+
+Commands are auto-discovered from `src/commands/` (recursively) using the pattern `*.command.ts`. Each command is a module-style yargs command exporting `command`, `description`, `builder`, and `handler`. Handlers must return/await their promise so yargs waits for completion.
+
+Available command categories:
+
+- **Images**: `img:minify`, `img:towebp`, `img:resize`, `img:optimize` (all support `--quality high|medium|low`)
+- **HTML**: `html:validate` (using HTMLHint)
+- **Files**: `files:clean-sourcemaps`
+
+### Key Directories
+
+- `src/commands/` - Command implementations organized by category
+- `src/shared/domain/` - Pure utilities (file ops, worker runner, quality presets, formatting)
+- `src/shared/infrastructure/` - Side-effectful services (logger, notifications, config)
+- `tests/` - Test files using Node.js native test runner
+- `bin/` - Compiled output directory
+
+### Architecture Patterns
+
+- Module-style yargs commands loaded with `.commandDir()`
+- Worker-based processing for image operations: helper (`image-minifier.ts`) chunks files per CPU and spawns a `*.job.ts` worker per chunk via `runWorker`; workers post `WorkerResult` (`processed`, `endTime`, optional `bytesIn`/`bytesOut`)
+- Quality presets shared across jobs in `src/shared/domain/quality-presets.ts`
+
+### Testing Structure
+
+- Uses Node.js native test runner (`node:test`)
+- Test files follow `*.test.ts` pattern
+- Tests use `node:assert/strict` for assertions
+- Test stubs in `tests/stubs/` directory
+
+## Key Dependencies
+
+### Runtime
+
+- `yargs` - CLI argument parsing
+- `imagemin` ecosystem - Image optimization
+- `sharp` - Image processing fallback
+- `htmlhint` - HTML validation
+
+### Build
+
+- `@swc/core` - TypeScript compilation
+- `@swc/cli` - SWC command-line interface
+- `@swc-node/register` - SWC Node.js loader for tests
+- `replace-in-file` - Post-build path replacement
+
+## Development Notes
+
+- Uses ES modules (`"type": "module"` in package.json)
+- Import paths use `#/` prefix that gets replaced during build
+- Node.js >=24 required (`engineStrict: true`)
+- Package manager: pnpm >=11
+- Build target: ESNext with SWC compiler
+- Code formatting with Biome (configuration in biome.json)
+- Native dependencies require periodic rebuilding (`pnpm run rebuild`)
+- Make targets available for common tasks (test, dependency updates)

Makefile

@@ -1,3 +1,4 @@
+SHELL:=$(shell which bash)
 MAKEFLAGS += -s
 
 current_work_directory := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
@@ -23,11 +24,31 @@ help: ## 📋 Display help message with descriptions of all available commands.
 .PHONY: deps/update
 .SILENT: deps/update
 deps/update: ## ⬆️ Update all project dependencies to their latest versions.
-	$(print_message) "updating dependencies"
-	ncu -u && ncu --target minor -u && ncu --target patch -u
-	corepack up
-	NODE_ENV= pnpm install
-	NODE_ENV= pnpm audit --fix
+	set -eo pipefail
+	$(print_message) "bump dependencies"
+	PNPM_QUIET_FLAGS="--config.loglevel=error"
+	NODE_ENV= pnpm audit || true
+	find . -type d -name node_modules -not -path '*/.git/*' -prune -exec rm -rf '{}' +
+	rm -f pnpm-lock.yaml
+	CI=true corepack use pnpm@latest-11
+	if command -v ncu &>/dev/null; then
+		NCU_CMD=ncu
+	elif [ -f ./node_modules/.bin/ncu ]; then
+		NCU_CMD=./node_modules/.bin/ncu
+	else
+		echo "ncu (npm-check-updates) not found. Install with one of:"
+		echo "  npm i -g npm-check-updates"
+		echo "  pnpm add -g npm-check-updates"
+		echo "  pnpm add -O npm-check-updates   # optional/local"
+		exit 1
+	fi
+	$$NCU_CMD --target patch -u && $$NCU_CMD --target minor -u && $$NCU_CMD -u
+	NODE_ENV= pnpm install --no-frozen-lockfile $$PNPM_QUIET_FLAGS
+	NODE_ENV= pnpm up --recursive $$PNPM_QUIET_FLAGS
+	NODE_ENV= pnpm audit --fix=update $$PNPM_QUIET_FLAGS
+	NODE_ENV= pnpm dedupe $$PNPM_QUIET_FLAGS
+	NODE_ENV= pnpm rebuild @swc-node/register @swc/cli @swc/core sharp
+	NODE_ENV= pnpm audit --ignore-unfixable
 
 .PHONY: test
 .SILENT: test

NOTES.md

@@ -270,3 +270,15 @@ https://nodejs.org/api/process.html#processargv0
 node ~/src/github.com/devlegacy/dvx-cli html:validate
 @squoosh/lib
 imagemin-svgo
+
+bun pm untrusted
+bun pm trust
+
+pnpm approve-builds
+
+img:minify open TODOs:
+
+- Skip unchanged files — no mtime/hash check; reruns on already-optimized images
+- Progress indicator — large batches (24+ files) have no ETA or count
+- Results table — before/after per-file KB would help identify worst offenders
+- exclude only filters the resizer — minifier still processes excluded patterns (inconsistent with docs)

README.md

@@ -2,6 +2,15 @@
 
 <h2 align="center">📦 Install</h2>
 
+### macOS prerequisites
+
+Some optimizers build native binaries from source and need these libraries:
+
+```sh
+brew install libpng libimagequant
+brew link libpng
+```
+
 ### Global installation
 
 To install the CLI tool globally, run the following command:

biome.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineEnding": "lf",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "trailingCommas": "all",
+      "expand": "always"
+    }
+  }
+}