@zairakai/dev-tools 1.0.11

package/scripts/stylelint-fix.sh

@@ -0,0 +1,39 @@
+#!/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 "Stylelint Fix"
+
+ensure_bin_optional "$STYLELINT_BIN" "stylelint" || exit 0
+
+STYLELINT_CONFIG="$(resolve_config "stylelint.config.js")"
+STYLELINT_IGNORE="$(resolve_config ".stylelintignore")"
+
+if [[ -n "$STYLELINT_CONFIG" ]]; then
+    log_step "Using configuration: ${STYLELINT_CONFIG#"$PROJECT_ROOT"/}"
+fi
+
+if [[ "$PROJECT_TYPE" == "laravel-app" ]]; then
+    STYLELINT_TARGET="${STYLELINT_TARGET:-resources/**/*.scss}"
+else
+    STYLELINT_TARGET="${STYLELINT_TARGET:-src/**/*.scss}"
+fi
+
+log_step "Fixing: $STYLELINT_TARGET"
+
+STYLELINT_ARGS=(--fix)
+
+if [[ -n "$STYLELINT_CONFIG" ]] && [[ "$STYLELINT_CONFIG" != "${PROJECT_ROOT}/stylelint.config.js" ]]; then
+    STYLELINT_ARGS+=(--config "$STYLELINT_CONFIG")
+fi
+
+if [[ -n "$STYLELINT_IGNORE" ]]; then
+    STYLELINT_ARGS+=(--ignore-path "$STYLELINT_IGNORE")
+fi
+
+"$STYLELINT_BIN" "${STYLELINT_ARGS[@]}" "$STYLELINT_TARGET"
+
+log_success "Stylelint fix applied"

package/scripts/stylelint.sh

@@ -0,0 +1,47 @@
+#!/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 "Stylelint Check"
+
+# Stylelint is optional — skip gracefully if not installed
+ensure_bin_optional "$STYLELINT_BIN" "stylelint" || exit 0
+
+STYLELINT_CONFIG="$(resolve_config "stylelint.config.js")"
+STYLELINT_IGNORE="$(resolve_config ".stylelintignore")"
+
+if [[ -n "$STYLELINT_CONFIG" ]]; then
+    log_step "Using configuration: ${STYLELINT_CONFIG#"$PROJECT_ROOT"/}"
+fi
+
+# Lint target depends on project type (overridable via env)
+if [[ "$PROJECT_TYPE" == "laravel-app" ]]; then
+    STYLELINT_TARGET="${STYLELINT_TARGET:-resources/**/*.scss}"
+else
+    STYLELINT_TARGET="${STYLELINT_TARGET:-src/**/*.scss}"
+fi
+
+log_step "Checking: $STYLELINT_TARGET"
+
+# Skip gracefully if no matching files exist (stylelint v16 errors on empty glob)
+if ! compgen -G "${PROJECT_ROOT}/${STYLELINT_TARGET}" > /dev/null 2>&1; then
+    log_info "No SCSS files found — skipping"
+    exit 0
+fi
+
+STYLELINT_ARGS=()
+
+if [[ -n "$STYLELINT_CONFIG" ]] && [[ "$STYLELINT_CONFIG" != "${PROJECT_ROOT}/stylelint.config.js" ]]; then
+    STYLELINT_ARGS+=(--config "$STYLELINT_CONFIG")
+fi
+
+if [[ -n "$STYLELINT_IGNORE" ]]; then
+    STYLELINT_ARGS+=(--ignore-path "$STYLELINT_IGNORE")
+fi
+
+"$STYLELINT_BIN" "${STYLELINT_ARGS[@]}" "$STYLELINT_TARGET"
+
+log_success "Stylelint check passed"

package/scripts/test.sh

@@ -0,0 +1,43 @@
+#!/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 "Vitest Tests"
+
+if ! ensure_bin_optional "$VITEST_BIN" "vitest"; then
+    log_warning "vitest not installed — add it to devDependencies to run tests"
+    exit 0
+fi
+
+COVERAGE="${COVERAGE:-false}"
+CI="${CI:-false}"
+
+# CI mode: always run with coverage
+if [[ "$CI" == "true" ]]; then
+    log_info "Running in CI mode (strict + coverage)"
+    COVERAGE="true"
+fi
+
+# Resolve vitest config
+VITEST_CONFIG="$(resolve_config "vitest.config.js")"
+
+VITEST_ARGS=()
+
+if [[ -n "$VITEST_CONFIG" ]]; then
+    log_step "Using configuration: ${VITEST_CONFIG#"$PROJECT_ROOT"/}"
+    VITEST_ARGS+=(--config "$VITEST_CONFIG")
+fi
+
+if [[ "$COVERAGE" == "true" ]]; then
+    log_info "Running with coverage report"
+    ensure_dir "build/coverage"
+    ensure_dir "build/logs"
+    "$VITEST_BIN" run --coverage --passWithNoTests "${VITEST_ARGS[@]}"
+else
+    "$VITEST_BIN" run --passWithNoTests "${VITEST_ARGS[@]}"
+fi
+
+log_success "Tests passed"

package/scripts/typecheck.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# TypeScript Type Checking (tsc --noEmit)
+# Validates types without emitting output files.
+# Equivalent to PHPStan for TypeScript.
+#
+# Usage:
+#   bash scripts/typecheck.sh
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/config.sh"
+
+TSC_BIN="${BIN_DIR}/tsc"
+
+log_header "TypeScript Type Checking"
+
+ensure_bin "$TSC_BIN" "tsc (typescript)"
+
+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"
+log_info "Mode: --noEmit (type validation only)"
+
+"$TSC_BIN" --noEmit
+
+log_success "TypeScript type checking passed"

package/scripts/validate-shellcheck.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# scripts/validate-shellcheck.sh
+# Runs ShellCheck validation on all shell scripts (100% compliance required)
+#
+# Usage:
+#   bash scripts/validate-shellcheck.sh
+#
+# Environment Variables:
+#   SHELLCHECK_SEVERITY - Severity level (default: warning)
+#   SHELLCHECK_FORMAT   - Output format (default: gcc)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/config.sh"
+
+SEVERITY="${SHELLCHECK_SEVERITY:-warning}"
+FORMAT="${SHELLCHECK_FORMAT:-gcc}"
+
+log_header "Running ShellCheck Validation"
+log_info "Severity: ${SEVERITY}"
+log_info "Format: ${FORMAT}"
+
+if ! command_exists shellcheck; then
+    log_error "ShellCheck not found. Please install shellcheck."
+    log_info "  Alpine: apk add shellcheck"
+    log_info "  Debian/Ubuntu: apt-get install shellcheck"
+    log_info "  macOS: brew install shellcheck"
+    exit 1
+fi
+
+SHELLCHECK_VERSION="$(shellcheck --version | grep "version:" | awk '{print $2}')"
+log_info "ShellCheck version: ${SHELLCHECK_VERSION}"
+
+log_info "→ Finding shell scripts…"
+
+mapfile -t SHELL_SCRIPTS < <(find . \( -name "*.sh" -o -name "*.bats" \) -type f ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*")
+
+SCRIPT_COUNT=${#SHELL_SCRIPTS[@]}
+log_info "Found ${SCRIPT_COUNT} shell scripts"
+
+if [[ ${SCRIPT_COUNT} -eq 0 ]]; then
+    log_warning "No shell scripts found"
+    exit 0
+fi
+
+log_info "→ Running ShellCheck validation…"
+
+FAILED=0
+TOTAL=0
+
+for script in "${SHELL_SCRIPTS[@]}"; do
+    TOTAL=$((TOTAL + 1))
+
+    if shellcheck --severity="${SEVERITY}" --format="${FORMAT}" "${script}"; then
+        :
+    else
+        log_error "  ✗ ${script} — ShellCheck failed"
+        FAILED=$((FAILED + 1))
+    fi
+done
+
+if [[ ${FAILED} -eq 0 ]]; then
+    log_success "All ${TOTAL} scripts passed ShellCheck"
+    exit 0
+else
+    log_error "${FAILED}/${TOTAL} scripts failed ShellCheck"
+    exit 1
+fi

package/stubs/eslint.config.js.stub

@@ -0,0 +1,18 @@
+/**
+ * Project ESLint configuration.
+ * Extends the @zairakai/dev-tools base config — customize as needed.
+ *
+ * Example of adding project-specific rules:
+ *   export default [
+ *     ...baseConfig,
+ *     {
+ *       rules: {
+ *         'no-console': 'warn',
+ *       },
+ *     },
+ *   ]
+ */
+
+import baseConfig from '@zairakai/dev-tools/config/eslint.config.js'
+
+export default [...baseConfig]

package/stubs/gitlab-ci.yml.stub

@@ -0,0 +1,18 @@
+# .gitlab-ci.yml
+# Generated by @zairakai/dev-tools setup-project.sh
+# Inherits the full shared template — only project-specific variables are defined here.
+#
+# To regenerate:
+#   bash node_modules/@zairakai/dev-tools/scripts/setup-project.sh --publish=gitlab-ci --force
+
+include:
+  - project: 'zairakai/npm/dev-tools'
+    ref: v0.0.0
+    file: '.gitlab/ci/pipeline-npm-package.yml'
+
+variables:
+  # Unique cache key for this project (update suffix when changing dependencies)
+  CACHE_KEY: "PACKAGE_CACHE_KEY"
+
+  # Full package name on npm (used in the GitLab release link)
+  NPM_PACKAGE_NAME: "PACKAGE_NPM_NAME"

package/stubs/gitlab-pipeline-js.yml.stub

@@ -0,0 +1,16 @@
+# .gitlab/pipeline-js.yml
+# JavaScript/Frontend CI jobs for this Laravel application.
+# Generated by @zairakai/dev-tools setup-project.sh
+# Included from .gitlab-ci.yml via: include: - local: '.gitlab/pipeline-js.yml'
+#
+# To regenerate:
+#   bash node_modules/@zairakai/dev-tools/scripts/setup-project.sh --publish=gitlab-ci --force
+
+include:
+  - project: 'zairakai/npm/dev-tools'
+    ref: v0.0.0
+    file: '.gitlab/ci/pipeline-js.yml'
+
+variables:
+  # Unique JS cache key for this project
+  CACHE_KEY: "PACKAGE_CACHE_KEY"

package/stubs/prettier.config.js.stub

@@ -0,0 +1,16 @@
+/**
+ * Project Prettier configuration.
+ * Extends the @zairakai/dev-tools base config — customize as needed.
+ *
+ * Example of adding project-specific overrides:
+ *   module.exports = {
+ *     ...baseConfig,
+ *     printWidth: 100,
+ *   }
+ */
+
+const baseConfig = require('@zairakai/dev-tools/config/prettier.config.js')
+
+module.exports = {
+  ...baseConfig,
+}

package/stubs/stylelint.config.js.stub

@@ -0,0 +1,17 @@
+/**
+ * Project Stylelint configuration.
+ * Extends the @zairakai/dev-tools base config — customize as needed.
+ *
+ * Example of adding project-specific rules:
+ *   export default {
+ *     ...baseConfig,
+ *     rules: {
+ *       ...baseConfig.rules,
+ *       'color-no-invalid-hex': true,
+ *     },
+ *   }
+ */
+
+import baseConfig from '@zairakai/dev-tools/config/stylelint.config.js'
+
+export default { ...baseConfig }

package/stubs/tsconfig.json.stub

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@zairakai/dev-tools/config/tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "build", "**/*.test.ts", "**/*.spec.ts"]
+}

package/stubs/vitest.config.js.stub

@@ -0,0 +1,18 @@
+/**
+ * Project Vitest configuration.
+ * Extends the @zairakai/dev-tools base config — customize as needed.
+ *
+ * Example of adding project-specific settings (e.g. Vue plugin, jsdom):
+ *   import vue from '@vitejs/plugin-vue'
+ *   export default mergeConfig(baseConfig, defineConfig({
+ *     plugins: [vue()],
+ *     test: {
+ *       environment: 'jsdom',
+ *     },
+ *   }))
+ */
+
+import { defineConfig, mergeConfig } from 'vitest/config'
+import baseConfig from '@zairakai/dev-tools/config/vitest.config.js'
+
+export default mergeConfig(baseConfig, defineConfig({}))

package/tools/make/bats.mk

@@ -0,0 +1,49 @@
+# BATS Testing Targets
+# Shell script testing with Bash Automated Testing System
+## —— 🧪 Shell Script Testing ——
+
+.PHONY: bats
+bats:: ## Run shell script tests (BATS)
+	@if [ ! -d tests/bats/unit ] && [ ! -d tests/bats/integration ]; then \
+		echo "ℹ️  No BATS tests found — skipping"; \
+		exit 0; \
+	fi
+	@if ! command -v bats &>/dev/null; then \
+		echo "❌ BATS not installed - run: make install-bats"; \
+		exit 1; \
+	fi
+	@bats tests/bats/unit/*.bats tests/bats/integration/*.bats
+
+.PHONY: bats-unit
+bats-unit:: ## Run BATS unit tests
+	@if [ ! -d tests/bats/unit ]; then \
+		echo "ℹ️  No BATS unit tests found — skipping"; \
+		exit 0; \
+	fi
+	@if ! command -v bats &>/dev/null; then \
+		echo "❌ BATS not installed - run: make install-bats"; \
+		exit 1; \
+	fi
+	@bats tests/bats/unit/*.bats
+
+.PHONY: bats-integration
+bats-integration:: ## Run BATS integration tests
+	@if [ ! -d tests/bats/integration ]; then \
+		echo "ℹ️  No BATS integration tests found — skipping"; \
+		exit 0; \
+	fi
+	@if ! command -v bats &>/dev/null; then \
+		echo "❌ BATS not installed - run: make install-bats"; \
+		exit 1; \
+	fi
+	@bats tests/bats/integration/*.bats
+
+.PHONY: test-all
+test-all:: test bats ## Run all tests (JS + Shell)
+	@echo ""
+	@echo "✅ All tests passed"
+
+##
+.PHONY: install-bats
+install-bats:: ## Install BATS framework
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/install-bats.sh

package/tools/make/code-style.mk

@@ -0,0 +1,29 @@
+# ESLint + Prettier Code Style Targets
+
+## —— 🎨 Code Style ——
+
+.PHONY: eslint
+eslint: ## Check code style
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/eslint.sh
+
+.PHONY: eslint-fix
+eslint-fix: ## Fix code style automatically
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/eslint-fix.sh
+
+##
+.PHONY: prettier
+prettier: ## Check formatting
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/prettier.sh
+
+.PHONY: prettier-fix
+prettier-fix: ## Fix formatting automatically
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/prettier-fix.sh
+
+##
+.PHONY: stylelint
+stylelint: ## Check CSS/SCSS style
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/stylelint.sh
+
+.PHONY: stylelint-fix
+stylelint-fix: ## Fix CSS/SCSS style automatically
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/stylelint-fix.sh

package/tools/make/core.mk

@@ -0,0 +1,50 @@
+# Core Makefile — Zairakai NPM Dev Tools
+# Aggregates all modular targets for JavaScript/TypeScript/Vue projects.
+#
+# Usage in a consumer project (Makefile):
+#   DEV_TOOLS_NPM := node_modules/@zairakai/dev-tools
+#   include $(DEV_TOOLS_NPM)/tools/make/core.mk
+#
+# Or generate via:
+#   bash node_modules/@zairakai/dev-tools/scripts/setup-project.sh --with-makefile
+
+# Default goal (only if not already set by the project Makefile)
+ifeq ($(origin .DEFAULT_GOAL), undefined)
+    .DEFAULT_GOAL := help
+endif
+
+SHELL := /bin/bash
+
+# Resolve make files directory from the current MAKEFILE_LIST entry
+NPM_DIRECTORY_TOOLS_MAKE_DIR := $(dir $(lastword $(MAKEFILE_LIST)))
+
+# Include variables first (paths, colors, project info)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)variables.mk
+
+# Include specialized make files in logical development workflow order:
+# 1. Help system (discover available commands)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)help.mk
+
+# 4. Documentation linting (Markdown)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)markdownlint.mk
+
+# 5. ShellCheck validation
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)shellcheck.mk
+
+# 2. Code style — ESLint + Prettier
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)code-style.mk
+
+# 3. CSS/SCSS — Stylelint (optional)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)stylelint.mk
+
+# 8. TypeScript type checking and build
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)typescript.mk
+
+# 6. Quality aggregation (combines all checks)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)quality.mk
+
+# 7. Testing (Vitest)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)test.mk
+
+# 9. BATS shell script testing
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)bats.mk

package/tools/make/help.mk

@@ -0,0 +1,32 @@
+# Help target
+
+## —— 📚 Help ——
+
+.PHONY: help
+help:: ## Show available commands
+	@echo ""
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_HEADER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_HEADER_BG)%*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $(NPM_DIRECTORY_TOOLS_HELP_WIDTH) ""
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_HEADER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_HEADER_BG)   %-*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $$(($(NPM_DIRECTORY_TOOLS_HELP_WIDTH)-3)) "$(NPM_DIRECTORY_TOOLS_PROJECT_NAME) - Available Commands"
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_HEADER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_HEADER_BG)%*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $(NPM_DIRECTORY_TOOLS_HELP_WIDTH) ""
+	@echo ""
+	@grep -hE '(^[[:alnum:]_.-]+:.*?##.*$$)|(^##)' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS=":.*?## "; color_section="$(NPM_DIRECTORY_TOOLS_COLOR_SECTION)"; color_target="$(NPM_DIRECTORY_TOOLS_COLOR_TARGET)"; color_reset="$(NPM_DIRECTORY_TOOLS_COLOR_RESET)"} \
+			/^##/ { \
+				gsub(/^##[[:space:]]*/, "", $$0); \
+				if ($$0 != "") { \
+					if (!seen_sections[$$0]++) { \
+						if (NR > 1) { printf "\n" } \
+						printf "%s%s%s\n", color_section, $$0, color_reset \
+					} \
+				} else { \
+					printf "\n" \
+				} \
+				next \
+			} \
+			!seen_targets[$$1]++ { printf "  %s%-28s%s %s\n", color_target, $$1, color_reset, $$2 }'
+	@echo ""
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_BG)%*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $(NPM_DIRECTORY_TOOLS_HELP_WIDTH) ""
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_BG)   Twitch: %-*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $$(($(NPM_DIRECTORY_TOOLS_HELP_WIDTH)-11)) "$(NPM_DIRECTORY_TOOLS_TWITCH_URL)"
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_BG)   GitLab: %-*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $$(($(NPM_DIRECTORY_TOOLS_HELP_WIDTH)-11)) "$(NPM_DIRECTORY_TOOLS_GITLAB_URL)"
+	@printf "$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_FG)$(NPM_DIRECTORY_TOOLS_COLOR_FOOTER_BG)%*s$(NPM_DIRECTORY_TOOLS_COLOR_RESET)\n" $(NPM_DIRECTORY_TOOLS_HELP_WIDTH) ""
+	@echo ""

package/tools/make/markdownlint.mk

@@ -0,0 +1,17 @@
+# Markdownlint Targets
+# Delegates to scripts/markdownlint.sh
+
+## —— 📝 Markdownlint (Documentation Linting) ——
+
+.PHONY: markdownlint
+markdownlint: ## Validate Markdown documentation style and formatting
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/markdownlint.sh
+
+.PHONY: markdownlint-fix
+markdownlint-fix: ## Fix Markdown documentation issues automatically
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/markdownlint.sh --fix
+
+##
+.PHONY: install-markdownlint
+install-markdownlint: ## Install Markdownlint
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/install-markdownlint.sh

package/tools/make/quality.mk

@@ -0,0 +1,20 @@
+# Quality Gate Targets
+## —— ✅ Quality Gates ——
+
+.PHONY: quality
+quality:: eslint prettier stylelint markdownlint shellcheck ## Run all quality checks
+	@echo "✅ All quality checks passed"
+
+.PHONY: quality-fix
+quality-fix:: eslint-fix prettier-fix stylelint-fix markdownlint-fix ## Auto-fix all fixable issues
+	@echo "✅ All auto-fixes applied"
+
+.PHONY: quality-fast
+quality-fast:: ## Run quality checks via aggregator script
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/ci-quality.sh
+
+.PHONY: ci
+ci:: quality test bats ## Full CI validation (quality + tests + BATS)
+	@echo ""
+	@echo "✅ CI validation passed"
+	@echo "💡 If using TypeScript, also run: make typecheck"

package/tools/make/shellcheck.mk

@@ -0,0 +1,14 @@
+# ShellCheck Targets
+# Delegates to scripts/validate-shellcheck.sh
+
+## —— 🐚 ShellCheck (Shell Script Validation) ——
+
+.PHONY: shellcheck
+shellcheck: ## Validate shell scripts with ShellCheck (100% compliance required)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/validate-shellcheck.sh
+
+
+##
+.PHONY: install-shellcheck
+install-shellcheck: ## Install shellcheck
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/install-shellcheck.sh

package/tools/make/test.mk

@@ -0,0 +1,19 @@
+# Vitest Testing Targets
+# Delegates to scripts/test.sh with appropriate environment variables
+## —— 🧪 Testing ——
+
+.PHONY: test
+test:: ## Run all tests (without coverage)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/test.sh
+
+.PHONY: test-coverage
+test-coverage:: ## Run tests with coverage report
+	@COVERAGE=true bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/test.sh
+
+.PHONY: test-watch
+test-watch:: ## Run tests in watch mode
+	@$(NPM_DIRECTORY_TOOLS_PROJECT_ROOT)/node_modules/.bin/vitest
+
+.PHONY: test-ci
+test-ci:: ## Run tests in CI mode (strict + coverage)
+	@CI=true bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/test.sh

package/tools/make/typescript.mk

@@ -0,0 +1,14 @@
+## —— 🧩 Typescript ——
+
+.PHONY: typecheck
+typecheck: ## Type-check TypeScript without emitting files (tsc --noEmit)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/typecheck.sh
+
+.PHONY: build
+build: ## Transpile TypeScript to JavaScript (tsup preferred, tsc fallback)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/build.sh
+
+.PHONY: knip
+knip: ## Find unused exports, files and dependencies (requires: npm install --save-dev knip)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/knip.sh
+

package/tools/make/variables.mk

@@ -0,0 +1,35 @@
+# Variables - Zairakai NPM Dev Tools
+# Shared configuration and styling
+
+# Critical path detection — works from any inclusion depth
+NPM_DIRECTORY_TOOLS_MAKE_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+NPM_DIRECTORY_TOOLS_PACKAGE_ROOT := $(abspath $(NPM_DIRECTORY_TOOLS_MAKE_DIR)../../)
+NPM_DIRECTORY_TOOLS_SCRIPTS_DIR := $(NPM_DIRECTORY_TOOLS_PACKAGE_ROOT)/scripts
+
+# Project root (caller context). Prefer $(shell pwd) over $(CURDIR).
+NPM_DIRECTORY_TOOLS_PROJECT_ROOT ?= $(shell pwd)
+
+# Project information (can be overridden in project Makefile BEFORE including core.mk)
+NPM_DIRECTORY_TOOLS_PROJECT_NAME ?= Zairakai Project
+NPM_DIRECTORY_TOOLS_TWITCH_URL   ?= https://twitch.tv/zairakai
+NPM_DIRECTORY_TOOLS_GITLAB_URL   ?= https://gitlab.com/zairakai
+
+# Help styling
+NPM_DIRECTORY_TOOLS_HELP_WIDTH := 70
+
+# ANSI Colors (only used in Make, not exported to scripts)
+NPM_DIRECTORY_TOOLS_COLOR_RESET     := \033[0m
+NPM_DIRECTORY_TOOLS_COLOR_HEADER_BG := \033[46m
+NPM_DIRECTORY_TOOLS_COLOR_HEADER_FG := \033[1;37m
+NPM_DIRECTORY_TOOLS_COLOR_SECTION   := \033[1;33m
+NPM_DIRECTORY_TOOLS_COLOR_TARGET    := \033[32m
+NPM_DIRECTORY_TOOLS_COLOR_FOOTER_BG := \033[44m
+NPM_DIRECTORY_TOOLS_COLOR_FOOTER_FG := \033[1;37m
+
+# Export only what shell scripts need
+export NPM_DIRECTORY_TOOLS_PROJECT_ROOT
+export NPM_DIRECTORY_TOOLS_PACKAGE_ROOT
+export NPM_DIRECTORY_TOOLS_SCRIPTS_DIR
+export NPM_DIRECTORY_TOOLS_PROJECT_NAME
+export NPM_DIRECTORY_TOOLS_TWITCH_URL
+export NPM_DIRECTORY_TOOLS_GITLAB_URL