@zairakai/js-dev-tools 1.0.0

package/config/vitest.config.js

@@ -0,0 +1,25 @@
+/**
+ * Default Vitest configuration for @zairakai packages.
+ * Provides sensible defaults for TypeScript projects.
+ *
+ * To customize, publish this file to your project:
+ *   bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=vitest
+ *
+ * The published config (config/dev-tools/vitest.config.js) can extend this
+ * base config and add project-specific settings (Vue plugin, jsdom, etc.).
+ */
+
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov', 'html', 'cobertura'],
+      reportsDirectory: 'build/coverage',
+      exclude: ['node_modules/**', 'dist/**', 'build/**', '**/*.config.*', '**/*.d.ts'],
+    },
+  },
+})

package/index.js

@@ -0,0 +1,24 @@
+/**
+ * @zairakai/js-dev-tools
+ * Development toolkit - ESLint, Prettier, Stylelint, TypeScript, and Vitest.
+ */
+
+import eslint from './config/eslint.config.js'
+import knip from './config/knip.config.js'
+import prettier from './config/prettier.config.js'
+import stylelint from './config/stylelint.config.js'
+import tsconfig from './config/tsconfig.base.json' with { type: 'json' }
+import vitest from './config/vitest.config.js'
+
+// Named exports
+export { eslint, knip, prettier, stylelint, tsconfig, vitest }
+
+// Named paths for consumers
+export const configs = {
+  eslint: '@zairakai/js-dev-tools/config/eslint.config.js',
+  prettier: '@zairakai/js-dev-tools/config/prettier.config.js',
+  stylelint: '@zairakai/js-dev-tools/config/stylelint.config.js',
+  vitest: '@zairakai/js-dev-tools/config/vitest.config.js',
+  knip: '@zairakai/js-dev-tools/config/knip.config.js',
+  tsconfig: '@zairakai/js-dev-tools/config/tsconfig.base.json',
+}

package/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "@zairakai/js-dev-tools",
+  "version": "1.0.0",
+  "description": "The unified and centralized development toolkit for JavaScript/TypeScript projects - ESLint, Prettier, Stylelint, Knip, Vitest, Git Hooks, and GitLab CI pipeline templates",
+  "keywords": [
+    "dev-tools",
+    "toolkit",
+    "unified",
+    "centralized",
+    "makefile",
+    "git-hooks",
+    "gitlab-ci",
+    "eslint",
+    "prettier",
+    "stylelint",
+    "vitest",
+    "knip",
+    "typescript"
+  ],
+  "homepage": "https://gitlab.com/zairakai/npm-packages/js-dev-tools",
+  "bugs": {
+    "url": "https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/issues",
+    "email": "contact-project+zairakai-npm-packages-js-dev-tools-80188322-issue-@incoming.gitlab.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/zairakai/npm-packages/js-dev-tools.git"
+  },
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/c/zairakai"
+    },
+    {
+      "type": "twitch",
+      "url": "https://www.twitch.tv/zairakai"
+    }
+  ],
+  "license": "MIT",
+  "author": "Stanislas Poisson <stanislas.p@the-white-rabbits.fr> (https://the-white-rabbits.fr)",
+  "contributors": [
+    {
+      "name": "Stanislas Poisson",
+      "url": "https://gitlab.com/zairakai",
+      "role": "Maintainer"
+    }
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    },
+    "./prettier": "./config/prettier.config.js",
+    "./eslint": "./config/eslint.config.js",
+    "./stylelint": "./config/stylelint.config.js",
+    "./vitest": "./config/vitest.config.js",
+    "./knip": "./config/knip.config.js",
+    "./tsconfig": "./config/tsconfig.base.json",
+    "./config/*": "./config/*"
+  },
+  "main": "index.js",
+  "files": [
+    ".gitlab/",
+    "config/",
+    "scripts/",
+    "stubs/",
+    "tools/",
+    "index.js",
+    ".editorconfig",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "eslint": "eslint --config config/eslint.config.js config/*.{js,ts}",
+    "eslint:fix": "eslint --config config/eslint.config.js config/*.{js,ts} --fix",
+    "postinstall": "bash ./scripts/setup-project.sh --silent || true",
+    "knip": "bash ./scripts/knip.sh",
+    "markdownlint": "markdownlint-cli2 --config config/.markdownlint.json --ignore-path config/.markdownlintignore '**/*.md' '#node_modules'",
+    "markdownlint:fix": "markdownlint-cli2 --fix --config config/.markdownlint.json --ignore-path config/.markdownlintignore '**/*.md' '#node_modules'",
+    "normalize": "make package-normalize",
+    "package:validate": "make package-validate",
+    "prettier": "prettier . --check --config ./config/prettier.config.js --ignore-path ./config/.prettierignore",
+    "prettier:fix": "prettier . --write --config ./config/prettier.config.js --ignore-path ./config/.prettierignore",
+    "setup": "bash ./scripts/setup-project.sh",
+    "stylelint": "stylelint --config config/stylelint.config.js --ignore-path config/.stylelintignore '**/*.scss'",
+    "stylelint:fix": "stylelint --config config/stylelint.config.js --ignore-path config/.stylelintignore '**/*.scss' --fix",
+    "test": "make test-all",
+    "validate": "make quality"
+  },
+  "dependencies": {
+    "@eslint/js": "^10.0.0",
+    "@prettier/plugin-php": "^0.24.0",
+    "@typescript-eslint/eslint-plugin": "^8.40.0",
+    "@typescript-eslint/parser": "^8.40.0",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-vue": "^10.0.0",
+    "globals": "^17.0.0",
+    "markdownlint-cli2": "^0.21.0",
+    "prettier": "^3.0.0",
+    "prettier-plugin-blade": "^2.1.0",
+    "prettier-plugin-organize-imports": "^4.0.0",
+    "stylelint": "^17.0.0",
+    "stylelint-config-html": "^1.1.0",
+    "stylelint-config-recommended-vue": "^1.5.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-config-standard-scss": "^17.0.0",
+    "stylelint-order": "^8.0.0",
+    "stylelint-scss": "^7.0.0",
+    "vue-eslint-parser": "^10.0.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.0.3",
+    "@vitest/coverage-v8": "^4.0.0",
+    "knip": "^5.85.0",
+    "sort-package-json": "^3.6.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "eslint": "^10.0.0",
+    "prettier": "^3.0.0",
+    "stylelint": "^17.0.0",
+    "typedoc": "^0.28.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "stylelint": {
+      "optional": true
+    },
+    "typedoc": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "outdatedIgnore": [
+    "prettier-plugin-blade"
+  ]
+}

package/scripts/build.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+#
+# TypeScript Build / Transpilation
+# Compiles TypeScript to JavaScript for distribution.
+#
+# Supports (in order of preference):
+#   1. tsup  — fast, esbuild-based bundler (recommended for npm packages)
+#   2. tsc   — official TypeScript compiler
+#
+# Usage:
+#   bash scripts/build.sh
+#
+# Recommendation:
+#   Use tsup for npm packages:  npm install --save-dev tsup
+#   Use tsc for apps:           npm install --save-dev typescript
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/config.sh"
+
+TSUP_BIN="${BIN_DIR}/tsup"
+TSC_BIN="${BIN_DIR}/tsc"
+
+log_header "TypeScript Build"
+
+if [[ -f "$TSUP_BIN" ]]; then
+    log_info "Builder: tsup (fast, esbuild-based)"
+    if [[ -n "$TSUP_CONFIG" ]]; then
+        "$TSUP_BIN" --config "$TSUP_CONFIG"
+    else
+        "$TSUP_BIN"
+    fi
+    log_success "Build complete — output in dist/"
+
+elif [[ -f "$TSC_BIN" ]]; then
+    log_info "Builder: tsc (official TypeScript compiler)"
+
+    if [[ ! -f "${PROJECT_ROOT}/tsconfig.json" ]]; then
+        log_error "No tsconfig.json found at project root"
+        log_info "Publish one with:"
+        log_info "  bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=tsconfig"
+        exit 1
+    fi
+
+    log_info "Config: tsconfig.json"
+    "$TSC_BIN"
+    log_success "Build complete"
+
+else
+    log_error "No TypeScript builder found in node_modules/.bin/"
+    log_info "Install one of:"
+    log_info "  npm install --save-dev tsup       (recommended for npm packages)"
+    log_info "  npm install --save-dev typescript (for apps or when you need full tsc control)"
+    exit 1
+fi

package/scripts/ci-quality.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+#
+# CI Quality Aggregator
+# Runs all quality checks (ESLint, Prettier, Stylelint, TypeScript)
+# and reports all failures at once rather than stopping on the first error.
+#
+# Usage:
+#   bash scripts/ci-quality.sh
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/config.sh"
+
+log_header "Quality Checks"
+
+init_error_counter
+
+# 1. Documentation & Shell (Foundational)
+run_check "Documentation (Markdownlint)" "bash '${SCRIPT_DIR}/markdownlint.sh'" || true
+echo ""
+
+run_check "Shell Scripts (ShellCheck)" "bash '${SCRIPT_DIR}/validate-shellcheck.sh'" || true
+echo ""
+
+# 2. Code Quality & Style (Language Specific)
+run_check "Code Style (ESLint)" "bash '${SCRIPT_DIR}/eslint.sh'" || true
+echo ""
+
+run_check "Formatting (Prettier)" "bash '${SCRIPT_DIR}/prettier.sh'" || true
+echo ""
+
+run_check "CSS/SCSS (Stylelint)" "bash '${SCRIPT_DIR}/stylelint.sh'" || true
+echo ""
+
+# 3. Static Analysis (Optional, Project aware)
+if [[ -f "${PROJECT_ROOT}/tsconfig.json" ]] && [[ -f "${BIN_DIR}/tsc" ]]; then
+    run_check "TypeScript (tsc --noEmit)" "bash '${SCRIPT_DIR}/typecheck.sh'" || true
+    echo ""
+else
+    log_info "TypeScript: no tsconfig.json or tsc — skipping"
+    echo ""
+fi
+
+if exit_with_error_count "Quality Checks"; then
+    exit 0
+else
+    exit 1
+fi

package/scripts/config.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# Zairakai NPM Dev Tools - Central Configuration
+
+set -euo pipefail
+
+# ─── PATH DETECTION ───────────────────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Vendor context: node_modules/@zairakai/js-dev-tools/scripts/
+# Dev context:    npm/dev-tools/scripts/
+if [[ "$SCRIPT_DIR" =~ /node_modules/@zairakai/js-dev-tools/scripts ]]; then
+    PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+    DEV_TOOLS_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+else
+    PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+    DEV_TOOLS_ROOT="$PROJECT_ROOT"
+fi
+
+export PROJECT_ROOT
+export DEV_TOOLS_ROOT
+
+# ─── PACKAGE MANAGER DETECTION ────────────────────────────────────────────────
+detect_package_manager() {
+    if [[ -f "$PROJECT_ROOT/yarn.lock" ]] || [[ -f "$PROJECT_ROOT/.yarnrc.yml" ]]; then
+        echo "yarn"
+    else
+        echo "npm"
+    fi
+}
+
+PM="$(detect_package_manager)"
+export PM
+
+# ─── PROJECT TYPE DETECTION ───────────────────────────────────────────────────
+detect_project_type() {
+    if [[ -f "${PROJECT_ROOT}/artisan" ]] && [[ -d "${PROJECT_ROOT}/resources/js" ]]; then
+        echo "laravel-app"
+        return 0
+    fi
+    echo "npm-package"
+}
+
+PROJECT_TYPE="$(detect_project_type)"
+export PROJECT_TYPE
+
+# ─── BINARY PATHS ─────────────────────────────────────────────────────────────
+BIN_DIR="${PROJECT_ROOT}/node_modules/.bin"
+export ESLINT_BIN="${BIN_DIR}/eslint"
+export PRETTIER_BIN="${BIN_DIR}/prettier"
+export STYLELINT_BIN="${BIN_DIR}/stylelint"
+export VITEST_BIN="${BIN_DIR}/vitest"
+export MARKDOWNLINT_BIN="${BIN_DIR}/markdownlint-cli2"
+
+# ─── CONFIG RESOLUTION ────────────────────────────────────────────────────────
+# Cascade: project root → config/dev-tools/ → config/ → bundled default
+resolve_config() {
+    local filename="$1"
+
+    # 1. Project root (full override)
+    if [[ -f "${PROJECT_ROOT}/${filename}" ]]; then
+        echo "${PROJECT_ROOT}/${filename}"
+        return 0
+    fi
+
+    # 2. config/dev-tools/ (published — can extend bundled default)
+    if [[ -f "${PROJECT_ROOT}/config/dev-tools/${filename}" ]]; then
+        echo "${PROJECT_ROOT}/config/dev-tools/${filename}"
+        return 0
+    fi
+
+    # 3. config/ (local usage or internal package structure)
+    if [[ -f "${PROJECT_ROOT}/config/${filename}" ]]; then
+        echo "${PROJECT_ROOT}/config/${filename}"
+        return 0
+    fi
+
+    # 4. Bundled default in dev-tools package (fallback when in node_modules)
+    if [[ -f "${DEV_TOOLS_ROOT}/config/${filename}" ]]; then
+        echo "${DEV_TOOLS_ROOT}/config/${filename}"
+        return 0
+    fi
+
+    echo ""
+}
+
+export -f resolve_config
+
+# ─── COLORS ───────────────────────────────────────────────────────────────────
+export RED='\033[0;31m'
+export GREEN='\033[0;32m'
+export YELLOW='\033[1;33m'
+export BLUE='\033[0;34m'
+export CYAN='\033[0;36m'
+export MAGENTA='\033[0;35m'
+export NC='\033[0m'
+
+# ─── LOGGING ──────────────────────────────────────────────────────────────────
+log_info()    { echo -e "${CYAN}ℹ ${NC}$*"; }
+log_success() { echo -e "${GREEN}✅ ${NC}$*"; }
+log_warning() { echo -e "${YELLOW}⚠️  ${NC}$*"; }
+log_error()   { echo -e "${RED}❌ ${NC}$*" >&2; }
+log_step()    { echo -e "${BLUE}→${NC} $*"; }
+log_header()  { echo -e "\n${MAGENTA}  $*${NC}\n${MAGENTA}════════════════${NC}\n"; }
+
+export -f log_info
+export -f log_success
+export -f log_warning
+export -f log_error
+export -f log_step
+export -f log_header
+
+# ─── BINARY CHECKS ────────────────────────────────────────────────────────────
+ensure_bin() {
+    local bin="$1"
+    local name="${2:-$(basename "$bin")}"
+    if [[ ! -f "$bin" ]]; then
+        log_error "${name} not found in node_modules/.bin/"
+        log_error "Run: ${PM} install"
+        return 1
+    fi
+}
+export -f ensure_bin
+
+ensure_bin_optional() {
+    local bin="$1"
+    local name="${2:-$(basename "$bin")}"
+    if [[ ! -f "$bin" ]]; then
+        log_warning "${name} not installed — skipping (optional)"
+        return 1
+    fi
+    return 0
+}
+export -f ensure_bin_optional
+
+# Check if files matching pattern exist
+has_files() {
+    local pattern="$1"
+    # SC2086: unquoted intentionally — we need word splitting + glob expansion via nullglob
+    # shellcheck disable=SC2086
+    ( shopt -s nullglob; set -- $pattern; [ $# -gt 0 ] )
+}
+export -f has_files
+
+# ─── ERROR COUNTER ────────────────────────────────────────────────────────────
+ERROR_COUNT=0
+export ERROR_COUNT
+init_error_counter()      { ERROR_COUNT=0; }
+increment_error_counter() { ERROR_COUNT=$((ERROR_COUNT + 1)); }
+get_error_count()         { echo "$ERROR_COUNT"; }
+
+exit_with_error_count() {
+    local name="${1:-Checks}"
+    if [[ $ERROR_COUNT -eq 0 ]]; then
+        log_header "✅ All ${name} Passed"
+        return 0
+    else
+        log_header "❌ ${ERROR_COUNT} ${name} Failed"
+        return 1
+    fi
+}
+
+export -f init_error_counter
+export -f increment_error_counter
+export -f get_error_count
+export -f exit_with_error_count
+
+run_check() {
+    local name="$1"
+    local cmd="$2"
+    log_info "Running: ${name}"
+    if eval "$cmd"; then
+        log_success "${name} passed"
+    else
+        log_error "${name} failed"
+        increment_error_counter
+        return 1
+    fi
+}
+
+# ─── BACKUP ──────────────────────────────────────────────────────────────────
+BACKUP_DIR=""
+backup_file() {
+    local file="$1"
+    local base="${2:-${PROJECT_ROOT}/.dev-tools-backup}"
+    [[ ! -f "$file" || -L "$file" ]] && return 1
+    if [[ -z "$BACKUP_DIR" ]]; then
+        BACKUP_DIR="${base}/$(date +%Y%m%d-%H%M%S)"
+        mkdir -p "$BACKUP_DIR"
+    fi
+    local rel="${file#"${PROJECT_ROOT}"/}"
+    local dest="${BACKUP_DIR}/${rel}"
+    mkdir -p "$(dirname "$dest")"
+    cp "$file" "$dest" 2>/dev/null
+}
+
+# ─── HELPERS ──────────────────────────────────────────────────────────────────
+command_exists() { command -v "$1" >/dev/null 2>&1; }
+ensure_dir() {
+    if [[ ! -d "$1" ]]; then
+        mkdir -p "$1"
+        log_step "Created directory: $1"
+    fi
+}
+
+# ─── FILE PROTECTION (SHA-256) ────────────────────────────────────────────────
+file_hash() {
+    local file="$1"
+    if command_exists sha256sum; then
+        sha256sum "$file" | cut -d' ' -f1
+    elif command_exists shasum; then
+        shasum -a 256 "$file" | cut -d' ' -f1
+    else
+        echo ""
+    fi
+}
+
+# ─── ENVIRONMENT DETECTION ────────────────────────────────────────────────────
+export IS_CI="${CI:-false}"
+export IS_GITLAB_CI="${GITLAB_CI:-false}"
+export IS_GITHUB_ACTIONS="${GITHUB_ACTIONS:-false}"
+
+# ─── TOOL CONFIG RESOLUTION ───────────────────────────────────────────────────
+# Pre-resolved at startup so individual scripts don't call resolve_config themselves.
+ESLINT_CONFIG="$(resolve_config "eslint.config.js")"
+export ESLINT_CONFIG
+
+PRETTIER_CONFIG="$(resolve_config "prettier.config.js")"
+PRETTIER_IGNORE="$(resolve_config ".prettierignore")"
+export PRETTIER_CONFIG PRETTIER_IGNORE
+
+STYLELINT_CONFIG="$(resolve_config "stylelint.config.js")"
+STYLELINT_IGNORE="$(resolve_config ".stylelintignore")"
+export STYLELINT_CONFIG STYLELINT_IGNORE
+
+MARKDOWNLINT_CONFIG="$(resolve_config ".markdownlint.json")"
+MARKDOWNLINT_IGNORE="$(resolve_config ".markdownlintignore")"
+export MARKDOWNLINT_CONFIG MARKDOWNLINT_IGNORE
+
+VITEST_CONFIG="$(resolve_config "vitest.config.js")"
+export VITEST_CONFIG
+
+KNIP_CONFIG="$(resolve_config "knip.config.js")"
+export KNIP_CONFIG
+
+TSUP_CONFIG="$(resolve_config "tsup.config.js")"
+export TSUP_CONFIG
+
+# ─── VALIDATION ───────────────────────────────────────────────────────────────
+cd "$PROJECT_ROOT"
+
+if [[ ! -d "${PROJECT_ROOT}/node_modules" ]]; then
+    log_error "Dependencies not installed. Run: ${PM} install"
+    exit 1
+fi

package/scripts/doctor.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/config.sh"
+
+log_header "Environment Diagnostics"
+
+echo -e "${CYAN}Node.js Version:${NC}"
+node --version
+
+echo ""
+echo -e "${CYAN}Package Manager:${NC}"
+echo "  → ${PM} $(${PM} --version)"
+
+echo ""
+echo -e "${CYAN}Project Type:${NC}"
+echo "  → ${PROJECT_TYPE}"
+
+echo ""
+echo -e "${CYAN}Available Tools:${NC}"
+[[ -f "$ESLINT_BIN" ]]      && echo "  ✅ ESLint:       $("$ESLINT_BIN" --version 2>/dev/null)" || echo "  ❌ ESLint not found"
+[[ -f "$PRETTIER_BIN" ]]    && echo "  ✅ Prettier:     $("$PRETTIER_BIN" --version 2>/dev/null)" || echo "  ❌ Prettier not found"
+[[ -f "$STYLELINT_BIN" ]]   && echo "  ✅ Stylelint:    $("$STYLELINT_BIN" --version 2>/dev/null)" || echo "  ℹ️  Stylelint not installed (optional)"
+[[ -f "$VITEST_BIN" ]]      && echo "  ✅ Vitest:       $("$VITEST_BIN" --version 2>/dev/null)" || echo "  ℹ️  Vitest not installed"
+[[ -f "$MARKDOWNLINT_BIN" ]] && echo "  ✅ Markdownlint: installed" || echo "  ❌ Markdownlint not found"
+[[ -f "${BIN_DIR}/knip" ]]  && echo "  ✅ Knip:         installed" || echo "  ℹ️  Knip not installed (optional)"
+[[ -f "${BIN_DIR}/tsc" ]]   && echo "  ✅ TypeScript:   $("${BIN_DIR}/tsc" --version 2>/dev/null)" || echo "  ℹ️  TypeScript not installed (optional)"
+[[ -f "${BIN_DIR}/tsup" ]]  && echo "  ✅ tsup:         installed" || echo "  ℹ️  tsup not installed (optional)"
+
+echo ""
+echo -e "${CYAN}CI/CD Detection:${NC}"
+if [[ "$IS_CI" == "true" ]]; then
+    echo "  ✅ Running in CI environment"
+    [[ "$IS_GITLAB_CI" == "true" ]]      && echo "  → Platform: GitLab CI"
+    [[ "$IS_GITHUB_ACTIONS" == "true" ]] && echo "  → Platform: GitHub Actions"
+else
+    echo "  ℹ️  Local development environment"
+fi
+
+echo ""
+echo -e "${CYAN}Configuration Files (resolved):${NC}"
+
+show_config() {
+    local label="$1"
+    local value="$2"
+    if [[ -n "$value" ]] && [[ -f "$value" ]]; then
+        echo "  ✅ ${label}: ${value#"$PROJECT_ROOT"/}"
+    else
+        echo "  ℹ️  ${label}: Using defaults (no config file)"
+    fi
+}
+
+show_config "ESLint"       "$ESLINT_CONFIG"
+show_config "Prettier"     "$PRETTIER_CONFIG"
+show_config ".prettierignore" "$PRETTIER_IGNORE"
+show_config "Stylelint"    "$STYLELINT_CONFIG"
+show_config ".stylelintignore" "$STYLELINT_IGNORE"
+show_config "Markdownlint" "$MARKDOWNLINT_CONFIG"
+show_config ".markdownlintignore" "$MARKDOWNLINT_IGNORE"
+show_config "Vitest"       "$VITEST_CONFIG"
+show_config "Knip"         "$KNIP_CONFIG"
+show_config "tsup"         "$TSUP_CONFIG"
+
+echo ""
+echo -e "${CYAN}Configuration Fallback Order (all tools):${NC}"
+echo "    1. {file}                  (project root override)"
+echo "    2. config/dev-tools/{file} (published — can extend bundled default)"
+echo "    3. config/{file}           (legacy or intermediate)"
+echo "    4. node_modules/@zairakai/js-dev-tools/config/{file} (bundled default)"
+
+echo ""
+log_success "Diagnostics complete"

package/scripts/eslint-fix.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/config.sh"
+
+log_header "ESLint Fix"
+
+ensure_bin "$ESLINT_BIN" "eslint" || exit 1
+
+if [[ -n "$ESLINT_CONFIG" ]]; then
+    log_step "Using configuration: ${ESLINT_CONFIG#"$PROJECT_ROOT"/}"
+fi
+
+if [[ "$PROJECT_TYPE" == "laravel-app" ]]; then
+    LINT_TARGET="${LINT_TARGET:-resources/js/}"
+else
+    LINT_TARGET="${LINT_TARGET:-src/}"
+fi
+
+log_step "Fixing: $LINT_TARGET"
+
+# Skip gracefully if no matching files exist
+if ! has_files "${PROJECT_ROOT}/${LINT_TARGET}**/*.{js,ts,vue,jsx,tsx}"; then
+    log_info "No JS/TS files found in ${LINT_TARGET} — skipping"
+    exit 0
+fi
+
+ESLINT_ARGS=(--fix)
+
+if [[ -n "$ESLINT_CONFIG" ]] && [[ "$ESLINT_CONFIG" != "${PROJECT_ROOT}/eslint.config.js" ]]; then
+    ESLINT_ARGS+=(--config "$ESLINT_CONFIG")
+fi
+
+"$ESLINT_BIN" "${ESLINT_ARGS[@]}" "$LINT_TARGET"
+
+log_success "ESLint fix applied"