@zairakai/js-dev-tools 1.0.0

package/scripts/eslint.sh

@@ -0,0 +1,49 @@
+#!/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
+
+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"
+
+# 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=()
+
+# 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"

package/scripts/install-bats.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+#
+# Zairakai NPM Dev Tools - BATS Installer
+# Installs BATS (Bash Automated Testing System) for shell script testing
+#
+# Platform: Linux/macOS/WSL
+#
+# Usage:
+#   bash scripts/install-bats.sh
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/config.sh"
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+CI_MODE="${CI:-false}"
+TOOL_VERSIONS_FILE="${DEV_TOOLS_ROOT}/.tool-versions"
+INSTALL_DIR="${HOME}/.local/share/bats"
+BIN_DIR="${HOME}/.local/bin"
+
+# ============================================================================
+# Helpers
+# ============================================================================
+
+get_bats_version() {
+    local version=""
+
+    if [[ -f "${TOOL_VERSIONS_FILE}" ]]; then
+        version="$(grep "^bats=" "${TOOL_VERSIONS_FILE}" | awk -F "=" '{print $2}' || echo "")"
+        if [[ -n "${version}" ]]; then
+            log_info "Found .tool-versions: ${version}"
+        fi
+    fi
+
+    if [[ -z "${version}" ]]; then
+        version="1.11.0"
+        log_info "Using default version: ${version}"
+    fi
+
+    if [[ ! "${version}" =~ ^v ]]; then
+        version="v${version}"
+    fi
+
+    echo "${version}"
+}
+
+version_ge() {
+    local ver1="${1#v}"
+    local ver2="${2#v}"
+
+    if [[ "${ver1}" == "${ver2}" ]]; then
+        return 0
+    fi
+
+    local IFS=.
+    # shellcheck disable=SC2206
+    local ver1_arr=($ver1) ver2_arr=($ver2)
+
+    local i
+    for ((i=${#ver1_arr[@]}; i<${#ver2_arr[@]}; i++)); do
+        ver1_arr[i]=0
+    done
+
+    for ((i=0; i<${#ver1_arr[@]}; i++)); do
+        if [[ -z "${ver2_arr[i]:-}" ]]; then
+            ver2_arr[i]=0
+        fi
+
+        if ((10#${ver1_arr[i]} > 10#${ver2_arr[i]})); then
+            return 0
+        fi
+
+        if ((10#${ver1_arr[i]} < 10#${ver2_arr[i]})); then
+            return 1
+        fi
+    done
+
+    return 0
+}
+
+check_bats_installed() {
+    local required_version="$1"
+
+    if ! command_exists bats; then
+        return 1
+    fi
+
+    local current_version
+    current_version="$(bats --version 2>/dev/null | awk '{print $2}' || echo "")"
+
+    if [[ -z "${current_version}" ]]; then
+        log_warning "Could not determine BATS version"
+        return 1
+    fi
+
+    log_info "Current version: ${current_version}"
+
+    if version_ge "${current_version}" "${required_version}"; then
+        log_success "BATS ${current_version} is sufficient (need >=${required_version})"
+        return 0
+    fi
+
+    log_warning "Version ${current_version} is outdated (need >=${required_version})"
+
+    if [[ "${CI_MODE}" != "true" ]]; then
+        echo ""
+        read -rp "Upgrade to ${required_version}? (y/N) " -n 1
+        echo ""
+
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            log_info "Keeping existing installation"
+            return 0
+        fi
+    else
+        log_info "CI mode: upgrading automatically"
+    fi
+
+    return 1
+}
+
+install_bats_core() {
+    local version="$1"
+
+    log_step "Installing BATS ${version} from source…"
+    mkdir -p "${INSTALL_DIR}" "${BIN_DIR}"
+
+    if [[ -d "${INSTALL_DIR}/bats-core" ]]; then
+        log_info "BATS repository exists, updating…"
+        git -C "${INSTALL_DIR}/bats-core" fetch --tags --quiet
+        git -C "${INSTALL_DIR}/bats-core" checkout "${version}" --quiet
+    else
+        log_info "Cloning BATS repository…"
+        git clone --quiet --depth 1 --branch "${version}" \
+            https://github.com/bats-core/bats-core.git "${INSTALL_DIR}/bats-core"
+    fi
+
+    "${INSTALL_DIR}/bats-core/install.sh" "${HOME}/.local"
+    log_success "BATS core installed to: ${BIN_DIR}/bats"
+
+    if [[ ":$PATH:" != *":${BIN_DIR}:"* ]]; then
+        echo ""
+        log_warning "${BIN_DIR} is not in your PATH"
+        echo ""
+        echo "Add this to your ~/.bashrc or ~/.zshrc:"
+        echo ""
+        echo -e "  ${CYAN}export PATH=\"\${HOME}/.local/bin:\${PATH}\"${NC}"
+        echo ""
+    fi
+}
+
+install_bats_libraries() {
+    log_step "Installing BATS support libraries…"
+
+    local libraries=(
+        "bats-support:https://github.com/bats-core/bats-support.git"
+        "bats-assert:https://github.com/bats-core/bats-assert.git"
+        "bats-file:https://github.com/bats-core/bats-file.git"
+    )
+
+    local lib_info lib_name lib_url lib_path
+    for lib_info in "${libraries[@]}"; do
+        lib_name="${lib_info%%:*}"
+        lib_url="${lib_info#*:}"
+        lib_path="${INSTALL_DIR}/${lib_name}"
+
+        if [[ -d "${lib_path}" ]]; then
+            log_info "${lib_name} already installed"
+        else
+            log_info "Installing ${lib_name}…"
+            git clone --quiet --depth 1 "${lib_url}" "${lib_path}"
+            log_success "${lib_name} installed"
+        fi
+    done
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+main() {
+    local required_version
+    required_version="$(get_bats_version)"
+
+    echo ""
+    log_header "BATS Installer"
+    echo ""
+
+    if check_bats_installed "${required_version}"; then
+        echo ""
+        log_info "No action needed — BATS is already available"
+        echo ""
+        exit 0
+    fi
+
+    echo ""
+    log_warning "BATS not found or outdated — installing…"
+    echo ""
+
+    install_bats_core "${required_version}"
+    install_bats_libraries
+
+    echo ""
+    log_success "BATS installation complete"
+    echo ""
+
+    if command_exists bats; then
+        bats --version
+        echo ""
+        log_info "Libraries installed in: ${INSTALL_DIR}"
+        echo ""
+        log_info "Run tests with:"
+        echo -e "  ${CYAN}make bats${NC}"
+        echo -e "  ${CYAN}bats tests/bats/ --recursive${NC}"
+        echo ""
+    else
+        log_error "BATS installation verification failed"
+        exit 1
+    fi
+}
+
+main "$@"

package/scripts/install-hooks.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+#
+# Zairakai NPM Dev Tools - Git Hooks Installer
+# Installs quality check hooks into .git/hooks
+#
+# Usage:
+#   bash scripts/install-hooks.sh           # Install hooks
+#   bash scripts/install-hooks.sh --remove  # Remove hooks
+#
+
+set -euo pipefail
+
+# Load central configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/config.sh"
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+HOOKS_SOURCE_DIR="${DEV_TOOLS_ROOT}/stubs/githooks"
+HOOKS_TARGET_DIR="${PROJECT_ROOT}/.git/hooks"
+
+# Available hooks (auto-discovered from stubs/githooks directory)
+HOOKS=(
+    "commit-msg"
+    "prepare-commit-msg"
+    "pre-commit"
+    "pre-push"
+)
+
+# ============================================================================
+# Functions
+# ============================================================================
+
+install_hooks() {
+    log_header "📦 Installing Git Hooks"
+
+    if [[ ! -d ".git" ]]; then
+        log_error "Not a git repository"
+        log_info "Git hooks can only be installed in a git repository"
+        exit 1
+    fi
+
+    if [[ ! -d "$HOOKS_SOURCE_DIR" ]]; then
+        log_error "Hooks source directory not found: $HOOKS_SOURCE_DIR"
+        exit 1
+    fi
+
+    mkdir -p "$HOOKS_TARGET_DIR"
+
+    local installed=0
+
+    for hook in "${HOOKS[@]}"; do
+        local source="${HOOKS_SOURCE_DIR}/${hook}"
+        local target="${HOOKS_TARGET_DIR}/${hook}"
+
+        if [[ ! -f "$source" ]]; then
+            log_warning "Hook not found: ${hook} (skipping)"
+            continue
+        fi
+
+        echo -e "  ${BLUE}•${NC} ${hook}"
+
+        # Backup existing hook if present
+        if [[ -f "$target" ]] && [[ ! -L "$target" ]]; then
+            local backup
+            backup="${target}.backup-$(date +%Y%m%d-%H%M%S)"
+            mv "$target" "$backup"
+            log_warning "  Existing hook backed up to: ${backup}"
+        fi
+
+        # Remove existing symlink
+        rm -f "$target"
+
+        # Install hook
+        ln -s "$source" "$target"
+        log_success "  ${hook} installed"
+
+        installed=$((installed + 1))
+    done
+
+    echo ""
+
+    if [[ $installed -eq 0 ]]; then
+        log_warning "No hooks were installed"
+        exit 1
+    fi
+
+    log_header "✅ ${installed} Hook(s) Installed Successfully"
+
+    echo ""
+    log_info "Installed hooks:"
+    for hook in "${HOOKS[@]}"; do
+        case "$hook" in
+            commit-msg)
+                echo -e "  ${GREEN}✓${NC} ${hook} ${YELLOW}→${NC} Validate Conventional Commits format"
+                ;;
+            prepare-commit-msg)
+                echo -e "  ${GREEN}✓${NC} ${hook} ${YELLOW}→${NC} Auto-prefix ticket number from branch"
+                ;;
+            pre-commit)
+                echo -e "  ${GREEN}✓${NC} ${hook} ${YELLOW}→${NC} Quality checks (ESLint, Prettier, Markdown)"
+                ;;
+            pre-push)
+                echo -e "  ${GREEN}✓${NC} ${hook} ${YELLOW}→${NC} Full quality gate before push"
+                ;;
+            *)
+                echo -e "  ${GREEN}✓${NC} ${hook}"
+                ;;
+        esac
+    done
+
+    echo ""
+    log_info "To bypass hooks (emergency only):"
+    echo -e "  ${CYAN}git commit --no-verify${NC}"
+    echo ""
+}
+
+remove_hooks() {
+    log_header "🗑️  Removing Git Hooks"
+
+    if [[ ! -d ".git" ]]; then
+        log_error "Not a git repository"
+        exit 1
+    fi
+
+    local removed=0
+
+    for hook in "${HOOKS[@]}"; do
+        local target="${HOOKS_TARGET_DIR}/${hook}"
+
+        if [[ -L "$target" ]]; then
+            # Only remove if it's a symlink (managed by us)
+            echo -e "  ${BLUE}•${NC} ${hook}"
+            rm -f "$target"
+            log_success "  ${hook} removed"
+            removed=$((removed + 1))
+        elif [[ -f "$target" ]]; then
+            log_warning "  ${hook} exists but is not a symlink (skipping)"
+        fi
+    done
+
+    echo ""
+
+    if [[ $removed -eq 0 ]]; then
+        log_info "No hooks were removed"
+        exit 0
+    fi
+
+    log_header "✅ ${removed} Hook(s) Removed"
+    echo ""
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+case "${1:-install}" in
+    --remove|-r)
+        remove_hooks
+        ;;
+    --install|-i|install|*)
+        install_hooks
+        ;;
+esac

package/scripts/install-markdownlint.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Zairakai NPM Dev Tools - Markdownlint Installer
+# Installs markdownlint-cli2 as a local npm dev dependency.
+#
+# Usage:
+#   bash scripts/install-markdownlint.sh
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=config.sh
+source "${SCRIPT_DIR}/config.sh"
+
+log_header "Markdownlint Installer"
+
+if [[ -f "$MARKDOWNLINT_BIN" ]]; then
+    version=$("$MARKDOWNLINT_BIN" --version 2>/dev/null || echo "unknown")
+    log_success "markdownlint-cli2 already installed: ${version}"
+    log_info "Run: make markdownlint"
+    exit 0
+fi
+
+log_info "markdownlint-cli2 not found in node_modules/.bin/"
+log_step "Installing markdownlint-cli2 as a dev dependency…"
+
+"$PM" install --save-dev markdownlint-cli2
+
+log_success "markdownlint-cli2 installed"
+log_info "Run: make markdownlint"

package/scripts/install-shellcheck.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+#
+# Zairakai NPM Dev Tools - ShellCheck Installer
+# Installs ShellCheck for shell script static analysis
+#
+# Platform: Linux/WSL only
+#
+# Features:
+#   - Reads version from .tool-versions
+#   - Supports apt/dnf/pacman/apk
+#   - CI-aware
+#
+# Usage:
+#   bash scripts/install-shellcheck.sh
+#
+
+set -euo pipefail
+
+# Load central configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=config.sh
+source "${SCRIPT_DIR}/config.sh"
+
+# ============
+# Configuration
+# ============
+
+CI_MODE="${CI:-false}"
+TOOL_VERSIONS_FILE="${SCRIPT_DIR}/../.tool-versions"
+
+# ============
+# Functions
+# ============
+
+# Get ShellCheck version from .tool-versions or use default
+get_shellcheck_version() {
+    local version=""
+
+    if [[ -f "${TOOL_VERSIONS_FILE}" ]]; then
+        version=$(grep "^shellcheck=" "${TOOL_VERSIONS_FILE}" | awk -F "="  '{print $2}' || echo "")
+
+        if [[ -n "${version}" ]]; then
+            log_info "Found .tool-versions: ${version}"
+        fi
+    fi
+
+    # Fallback to default if not found
+    if [[ -z "${version}" ]]; then
+        version="0.10.0"
+        log_info "Using default version: ${version}"
+    fi
+
+    echo "${version}"
+}
+
+# Compare versions (returns 0 if ver1 >= ver2)
+version_ge() {
+    local ver1="$1"
+    local ver2="$2"
+
+    if [[ "${ver1}" == "${ver2}" ]]; then
+        return 0
+    fi
+
+    local IFS=.
+    local i ver1_arr=("$ver1") ver2_arr=("$ver2")
+
+    # Fill empty positions with zeros
+    for ((i=${#ver1_arr[@]}; i<${#ver2_arr[@]}; i++)); do
+        ver1_arr[i]=0
+    done
+
+    for ((i=0; i<${#ver1_arr[@]}; i++)); do
+        if [[ -z ${ver2_arr[i]} ]]; then
+            ver2_arr[i]=0
+        fi
+
+        if ((10#${ver1_arr[i]} > 10#${ver2_arr[i]})); then
+            return 0
+        fi
+
+        if ((10#${ver1_arr[i]} < 10#${ver2_arr[i]})); then
+            return 1
+        fi
+    done
+
+    return 0
+}
+
+# Check if ShellCheck is already installed with sufficient version
+check_shellcheck_installed() {
+    local required_version="$1"
+
+    if ! command_exists shellcheck; then
+        return 1
+    fi
+
+    local current_version
+    current_version=$(shellcheck --version | grep "version:" | awk '{print $2}' || echo "")
+
+    if [[ -z "${current_version}" ]]; then
+        log_warning "Could not determine ShellCheck version"
+        return 1
+    fi
+
+    log_info "Current version: ${current_version}"
+
+    if version_ge "${current_version}" "${required_version}"; then
+        log_success "ShellCheck ${current_version} is sufficient (need >=${required_version})"
+        return 0
+    fi
+
+    log_warning "Version ${current_version} is outdated (need >=${required_version})"
+
+    # Ask for upgrade confirmation if not in CI
+    if [[ "${CI_MODE}" != "true" ]]; then
+        echo ""
+        read -rp "Upgrade to ${required_version}? (y/N) " -n 1
+        echo ""
+
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            log_info "Keeping existing installation"
+            return 0
+        fi
+    else
+        log_info "CI mode: upgrading automatically"
+    fi
+
+    return 1
+}
+
+# Detect package manager and install ShellCheck
+install_shellcheck() {
+    local version="$1"
+
+    log_header "🐚 Installing ShellCheck ${version}"
+    echo ""
+
+    local use_sudo=true
+
+    # Don't use sudo in CI or if running as root
+    if [[ "${CI_MODE}" == "true" ]] || [[ "$(id -u)" -eq 0 ]]; then
+        use_sudo=false
+    fi
+
+    # Detect and use package manager
+    if command_exists apt-get; then
+        log_step "Installing via apt-get..."
+
+        if [[ "${use_sudo}" == "true" ]]; then
+            sudo apt-get update -qq
+            sudo apt-get install -y -qq shellcheck
+        else
+            apt-get update -qq
+            apt-get install -y -qq shellcheck
+        fi
+
+    elif command_exists dnf; then
+        log_step "Installing via dnf..."
+
+        if [[ "${use_sudo}" == "true" ]]; then
+            sudo dnf install -y -q ShellCheck
+        else
+            dnf install -y -q ShellCheck
+        fi
+
+    elif command_exists pacman; then
+        log_step "Installing via pacman..."
+
+        if [[ "${use_sudo}" == "true" ]]; then
+            sudo pacman -S --noconfirm --quiet shellcheck
+        else
+            pacman -S --noconfirm --quiet shellcheck
+        fi
+
+    elif command_exists apk; then
+        log_step "Installing via apk..."
+        apk add --no-cache -q shellcheck
+
+    else
+        log_error "No supported package manager found (apt-get, dnf, pacman, apk)"
+        echo ""
+        log_info "Install manually from: https://github.com/koalaman/shellcheck"
+        return 1
+    fi
+
+    log_success "ShellCheck installed successfully"
+
+    echo ""
+    log_header "✅ ShellCheck Installation Complete"
+    echo ""
+
+    # Verify installation
+    if command_exists shellcheck; then
+        shellcheck --version
+        echo ""
+        log_info "Run linter with:"
+        echo -e "  ${CYAN}make shellcheck${NC}"
+        echo -e "  ${CYAN}shellcheck scripts/*.sh${NC}"
+        echo ""
+    else
+        log_error "ShellCheck installation verification failed"
+        return 1
+    fi
+}
+
+# ============
+# Main
+# ============
+
+main() {
+    local required_version
+    required_version=$(get_shellcheck_version)
+
+    echo ""
+
+    # Check if already installed with sufficient version
+    if check_shellcheck_installed "${required_version}"; then
+        echo ""
+        log_info "No action needed - ShellCheck is already available"
+        echo ""
+        exit 0
+    fi
+
+    echo ""
+    log_warning "ShellCheck not found or outdated - installing..."
+    echo ""
+
+    install_shellcheck "${required_version}"
+}
+
+main "$@"