@zairakai/js-dev-tools 1.0.0

package/stubs/testing/vitest.config.js.stub

@@ -0,0 +1,18 @@
+/**
+ * Project Vitest configuration.
+ * Extends the @zairakai/js-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/js-dev-tools/config/vitest.config.js'
+
+export default mergeConfig(baseConfig, defineConfig({}))

package/stubs/typescript/tsconfig.json.stub

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

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 ! command -v bats &>/dev/null; then \
+		echo "❌ BATS not installed - run: make install-bats"; \
+		exit 1; \
+	fi; \
+	FILES=$$(find tests/bats -name "*.bats" 2>/dev/null); \
+	if [ -z "$$FILES" ]; then \
+		echo "ℹ️  No BATS tests found — skipping"; \
+	else \
+		bats $$FILES; \
+	fi
+
+.PHONY: bats-unit
+bats-unit:: ## Run BATS unit tests
+	@if ! command -v bats &>/dev/null; then \
+		echo "❌ BATS not installed - run: make install-bats"; \
+		exit 1; \
+	fi; \
+	if [ ! -d tests/bats/unit ] || [ -z "$$(find tests/bats/unit -name "*.bats" 2>/dev/null)" ]; then \
+		echo "ℹ️  No BATS unit tests found — skipping"; \
+	else \
+		bats tests/bats/unit/*.bats; \
+	fi
+
+.PHONY: bats-integration
+bats-integration:: ## Run BATS integration tests
+	@if ! command -v bats &>/dev/null; then \
+		echo "❌ BATS not installed - run: make install-bats"; \
+		exit 1; \
+	fi; \
+	if [ ! -d tests/bats/integration ] || [ -z "$$(find tests/bats/integration -name "*.bats" 2>/dev/null)" ]; then \
+		echo "ℹ️  No BATS integration tests found — skipping"; \
+	else \
+		bats tests/bats/integration/*.bats; \
+	fi
+.PHONY: test-all
+test-all:: test bats ## Run all tests (Vitest + BATS)
+	@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,20 @@
+# 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

package/tools/make/core.mk

@@ -0,0 +1,56 @@
+# 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/js-dev-tools
+#   include $(DEV_TOOLS_NPM)/tools/make/core.mk
+#
+# Or generate via:
+#   bash node_modules/@zairakai/js-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
+
+# 2. Documentation linting (Markdown)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)markdownlint.mk
+
+# 3. ShellCheck validation
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)shellcheck.mk
+
+# 4. Code style — ESLint + Prettier
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)code-style.mk
+
+# 5. CSS/SCSS — Stylelint (optional)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)stylelint.mk
+
+# 6. Dead code detection (Knip)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)knip.mk
+
+# 7. TypeScript type checking and build
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)typescript.mk
+
+# 8. Quality aggregation (combines all checks)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)quality.mk
+
+# 9. Testing (Vitest)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)test.mk
+
+# 10. BATS shell script testing
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)bats.mk
+
+# 11. Utilities (git, npm)
+include $(NPM_DIRECTORY_TOOLS_MAKE_DIR)utils.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/knip.mk

@@ -0,0 +1,7 @@
+# Knip Dead Code Analysis Targets
+# Delegates to scripts/knip.sh
+
+## —— ✂️  Knip ——
+.PHONY: knip
+knip: ## Run dead code analysis (Knip)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/knip.sh

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-fix.sh
+
+##
+.PHONY: install-markdownlint
+install-markdownlint: ## Install Markdownlint
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/install-markdownlint.sh

package/tools/make/quality.mk

@@ -0,0 +1,19 @@
+# Quality Gate Targets
+## —— ✅ Quality Gates ——
+
+.PHONY: quality
+quality:: markdownlint shellcheck eslint prettier stylelint knip ## 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 fast quality checks only (ESLint + Prettier + Markdownlint)
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/ci-quality.sh
+
+.PHONY: ci
+ci:: quality typecheck test bats ## Full CI validation (quality + typecheck + tests + BATS)
+	@echo ""
+	@echo "✅ CI validation passed"

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/stylelint.mk

@@ -0,0 +1,11 @@
+# Stylelint Targets
+# Delegates to scripts/stylelint.sh
+
+## —— 🎨 Stylelint ——
+.PHONY: stylelint
+stylelint: ## Check CSS/SCSS style (Stylelint)
+	@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/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,10 @@
+## —— 🧩 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
+

package/tools/make/utils.mk

@@ -0,0 +1,44 @@
+# Utility Targets
+# Miscellaneous commands for development
+
+## —— 🎼  Package Manager ——
+.PHONY: package-install
+package-install: ## Install dependencies
+	@echo "📦 Installing dependencies…"
+	@npm install
+
+.PHONY: package-update
+package-update: ## Update dependencies
+	@echo "⬆️  Updating dependencies…"
+	@npm update
+
+.PHONY: package-normalize
+package-normalize: ## Normalize package.json structure (sort-package-json)
+	@$(NPM_DIRECTORY_TOOLS_PROJECT_ROOT)/node_modules/.bin/sort-package-json package.json
+
+.PHONY: package-validate
+package-validate: ## Validate package.json and lockfile sync
+	@echo "🔍 Validating package.json and lockfile…"
+	@npm install --package-lock-only --dry-run
+	@$(NPM_DIRECTORY_TOOLS_PROJECT_ROOT)/node_modules/.bin/sort-package-json --check package.json
+
+## —— 🧰 Utils ——
+.PHONY: doctor
+doctor: ## Run environment diagnostics
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/doctor.sh
+
+.PHONY: outdated
+outdated: ## Check for outdated npm dependencies
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/outdated.sh
+
+.PHONY: install-hooks
+install-hooks: ## Install git hooks into .git/hooks
+	@bash $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)/install-hooks.sh
+
+.PHONY: git-update
+git-update: ## Fast-forward all local branches that track a remote
+	@bash $(NPM_DIRECTORY_TOOLS_PACKAGE_ROOT)/tools/scripts/git-update.sh
+
+.PHONY: git-cleanup
+git-cleanup: ## Remove local branches whose remote tracking branch no longer exists
+	@bash $(NPM_DIRECTORY_TOOLS_PACKAGE_ROOT)/tools/scripts/git-cleanup.sh

package/tools/make/variables.mk

@@ -0,0 +1,42 @@
+# 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/
+NPM_DIRECTORY_TOOLS_TOOLS_SCRIPTS_DIR := $(NPM_DIRECTORY_TOOLS_PACKAGE_ROOT)tools/scripts/
+
+# Project root (caller context). Prefer $(shell pwd) over $(CURDIR).
+NPM_DIRECTORY_TOOLS_PROJECT_ROOT ?= $(shell pwd)
+
+# Validate paths exist
+ifeq ($(wildcard $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR)),)
+$(error Zairakai scripts directory not found: $(NPM_DIRECTORY_TOOLS_SCRIPTS_DIR))
+endif
+
+# 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_TOOLS_SCRIPTS_DIR
+export NPM_DIRECTORY_TOOLS_PROJECT_NAME
+export NPM_DIRECTORY_TOOLS_TWITCH_URL
+export NPM_DIRECTORY_TOOLS_GITLAB_URL

package/tools/scripts/git-cleanup.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo ""
+echo "==== Git Branch Cleanup ===="
+echo "This script will DELETE local branches whose remote has been deleted."
+echo ""
+
+# List local branches whose remote has been deleted
+gone_branches=$(git for-each-ref --format='%(refname:short) %(upstream:track)' refs/heads/ | grep '\[gone\]' | awk '{print $1}' || true)
+
+if [ -z "$gone_branches" ]; then
+  echo "No branches with deleted remotes found. ✅"
+  exit 0
+fi
+
+current_branch=$(git symbolic-ref --short HEAD)
+
+echo "Found branches with deleted remotes:"
+echo "━━━━━━━━━━━━━━━━"
+echo "$gone_branches"
+echo "━━━━━━━━━━━━━━━━"
+echo ""
+echo "⚠️  WARNING: This will permanently delete these local branches!"
+echo ""
+
+# Count branches
+count=$(echo "$gone_branches" | wc -l)
+echo "Total: $count branch(es) to delete"
+echo ""
+
+# Ask for confirmation
+read -rp "Continue? [y/N] " -n 1
+echo ""
+
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+  echo "Aborted. No branches deleted."
+  exit 0
+fi
+
+echo ""
+echo "==== Deleting branches ===="
+for branch in $gone_branches; do
+  if [ "$branch" != "$current_branch" ]; then
+    echo "Deleting: $branch"
+    git branch -D "$branch"
+  else
+    echo "⚠️  Skipping $branch (currently checked out)"
+  fi
+done
+
+echo ""
+echo "==== Cleanup completed ===="

package/tools/scripts/git-update.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Fetch and prune remote refs
+git fetch --all --prune
+
+# Abort if working tree is dirty
+if ! git diff-index --quiet HEAD --; then
+  echo "Working tree dirty. Commit/stash changes before running this script."
+  exit 1
+fi
+
+current_branch=$(git symbolic-ref --short HEAD)
+
+echo ""
+echo "==== Updating local branches ===="
+for branch in $(git for-each-ref --format='%(refname:short)' refs/heads/); do
+  upstream=$(git rev-parse --abbrev-ref "$branch@{upstream}" 2>/dev/null || true)
+  if [ -n "$upstream" ]; then
+    echo "---- Updating $branch from $upstream ----"
+    git checkout "$branch"
+    # Fast-forward only; will fail if a merge is required
+    if git merge --ff-only "$upstream"; then
+      echo "Updated $branch ✅"
+    else
+      echo "Cannot fast-forward $branch (diverged). Skipping."
+    fi
+  fi
+done
+
+# Return to original branch
+git checkout "$current_branch"
+
+echo ""
+echo "==== Update completed ===="
+echo ""
+echo "💡 Tip: Use 'make git-cleanup' to remove local branches with deleted remotes"