@zairakai/dev-tools 1.0.11

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "@zairakai/dev-tools",
+  "version": "1.0.11",
+  "description": "Development tools umbrella for Zairakai projects - ESLint, Prettier, Stylelint all-in-one",
+  "keywords": [
+    "zairakai",
+    "dev-tools",
+    "umbrella",
+    "eslint",
+    "prettier",
+    "stylelint",
+    "vue",
+    "typescript",
+    "javascript",
+    "scss"
+  ],
+  "homepage": "https://gitlab.com/zairakai/npm/dev-tools",
+  "bugs": {
+    "url": "https://gitlab.com/zairakai/npm/dev-tools/-/issues",
+    "email": "contact-project+zairakai-npm-dev-tools-73530803-issue-@incoming.gitlab.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/zairakai/npm/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",
+    "./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",
+    "markdownlint": "markdownlint '**/*.md' --config config/.markdownlint.json --ignore-path config/.markdownlintignore --ignore node_modules",
+    "markdownlint:fix": "markdownlint '**/*.md' --config config/.markdownlint.json --ignore-path config/.markdownlintignore --ignore node_modules --fix",
+    "package:normalize": "sort-package-json",
+    "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": "bash ./scripts/test.sh",
+    "validate": "node --input-type=module < /dev/null"
+  },
+  "dependencies": {
+    "@eslint/js": "^9.34.0",
+    "@prettier/plugin-php": "^0.22.0",
+    "@typescript-eslint/eslint-plugin": "^8.40.0",
+    "@typescript-eslint/parser": "^8.40.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-vue": "^9.30.0",
+    "globals": "^16.3.0",
+    "markdownlint-cli": "^0.47.0",
+    "prettier": "^3.0.0",
+    "prettier-plugin-blade": "^2.1.0",
+    "prettier-plugin-organize-imports": "^3.2.4",
+    "sort-package-json": "^3.6.1",
+    "stylelint": "^16.0.0",
+    "stylelint-config-html": "^1.1.0",
+    "stylelint-config-recommended-vue": "^1.5.0",
+    "stylelint-config-standard": "^36.0.0",
+    "stylelint-config-standard-scss": "^13.0.0",
+    "stylelint-order": "^6.0.4",
+    "stylelint-scss": "^6.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.0.0",
+    "knip": "^5.85.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "stylelint": "^16.0.0",
+    "typedoc": "^0.28.0",
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "stylelint": {
+      "optional": true
+    },
+    "typedoc": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build.sh

@@ -0,0 +1,54 @@
+#!/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)"
+    "$TSUP_BIN"
+    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/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,47 @@
+#!/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
+
+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 ""
+
+# Markdown linting
+run_check "Documentation (Markdownlint)" "bash '${SCRIPT_DIR}/markdownlint.sh'" || true
+echo ""
+
+# TypeScript type checking (optional — only if tsc + tsconfig.json are present)
+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,193 @@
+#!/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/dev-tools/scripts/
+# Dev context:    npm/dev-tools/scripts/
+if [[ "$SCRIPT_DIR" =~ /node_modules/@zairakai/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"
+
+# ─── CONFIG RESOLUTION ────────────────────────────────────────────────────────
+# Cascade: project root → config/dev-tools/ → 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. Bundled default in dev-tools package
+    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"; }
+
+# ─── 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
+}
+
+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
+}
+
+# ─── ERROR COUNTER ────────────────────────────────────────────────────────────
+ERROR_COUNT=0
+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
+}
+
+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
+}
+
+# ─── VALIDATION ───────────────────────────────────────────────────────────────
+cd "$PROJECT_ROOT"
+
+if [[ ! -d "${PROJECT_ROOT}/node_modules" ]]; then
+    log_error "Dependencies not installed. Run: ${PM} install"
+    exit 1
+fi

package/scripts/eslint-fix.sh

@@ -0,0 +1,34 @@
+#!/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
+
+ESLINT_CONFIG="$(resolve_config "eslint.config.js")"
+
+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"
+
+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"

package/scripts/eslint.sh

@@ -0,0 +1,46 @@
+#!/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 Check"
+
+ensure_bin "$ESLINT_BIN" "eslint" || exit 1
+
+# Resolve config (cascade: root → config/dev-tools/ → bundled)
+ESLINT_CONFIG="$(resolve_config "eslint.config.js")"
+
+if [[ -n "$ESLINT_CONFIG" ]]; then
+    log_step "Using configuration: ${ESLINT_CONFIG#"$PROJECT_ROOT"/}"
+else
+    log_warning "No ESLint configuration found — using ESLint defaults"
+fi
+
+# Lint target depends on project type (overridable via env)
+if [[ "$PROJECT_TYPE" == "laravel-app" ]]; then
+    LINT_TARGET="${LINT_TARGET:-resources/js/}"
+else
+    # Default to src/, but fallback to . if src/ doesn't exist
+    if [[ -z "${LINT_TARGET:-}" ]]; then
+        if [[ -d "${PROJECT_ROOT}/src" ]]; then
+            LINT_TARGET="src/"
+        else
+            LINT_TARGET="."
+        fi
+    fi
+fi
+
+log_step "Checking: $LINT_TARGET"
+
+ESLINT_ARGS=()
+
+# Only pass --config when the config is not at project root (ESLint 9 auto-discovers root)
+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 check passed"