@zairakai/js-dev-tools 2.0.0 → 3.0.0

package/.gitlab/ci/pipeline-js-package.yml

@@ -40,7 +40,7 @@ include:
 # ================================
 workflow:
   rules:
-    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_TAG
     - if: $CI_PIPELINE_SOURCE == "schedule"
     - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
     - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
@@ -137,6 +137,29 @@ secret_detection:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
     - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
 
+# A tag whose format is not the one of VERSION_TAG_REGEX (group variable) fails here,
+# and the jobs that publish do not run for it.
+js:tag-format:
+  <<: *base_job
+  stage: security
+  image: ${ALPINE_IMAGE}
+  rules:
+    - if: $CI_COMMIT_TAG
+  script:
+    - |
+      regex="${VERSION_TAG_REGEX:-}"
+      regex="${regex#/}"
+      regex="${regex%/}"
+      if [ -z "$regex" ]; then
+        echo "ERROR: VERSION_TAG_REGEX is not set. It is a variable of the zairakai group."
+        exit 1
+      fi
+      if ! printf '%s\n' "$CI_COMMIT_TAG" | grep -Eq "$regex"; then
+        echo "ERROR: the tag \"$CI_COMMIT_TAG\" does not match $VERSION_TAG_REGEX (X.Y.Z or X.Y.Z-prerelease)."
+        exit 1
+      fi
+      echo "Tag $CI_COMMIT_TAG: format OK"
+
 # ================================
 # INSTALL
 # ================================
@@ -229,7 +252,7 @@ js:quality:bats:
   stage: quality
   image: ${ALPINE_IMAGE}
   before_script:
-    - apk add --no-cache bash bats
+    - apk add --no-cache bash bats git
   script:
     - |
       if [[ -d tests/bats ]]; then
@@ -291,7 +314,7 @@ js:build:
     expire_in: 1 week
     when: on_success
   rules:
-    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
     - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
     - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
 
@@ -303,7 +326,7 @@ js:publish:
   stage: publish
   image: ${NODE_IMAGE}
   rules:
-    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
   script:
     - |
       if [[ -z "${NPM_TOKEN:-}" ]]; then
@@ -313,14 +336,14 @@ js:publish:
       fi
     - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "${CI_PROJECT_DIR}/.npmrc"
     - |
-      if [[ $CI_COMMIT_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+.*$ ]]; then
-        echo "Publishing ${NPM_PACKAGE_NAME}@${CI_COMMIT_TAG#v} to npm..."
-        npm version "${CI_COMMIT_TAG#v}" --no-git-tag-version --allow-same-version
-        npm publish --access public
-      else
-        echo "Invalid tag format: ${CI_COMMIT_TAG}. Expected: v1.0.0"
-        exit 1
+      # A pre-release (2.3.0-rc.1) goes to the npm tag "next", so it never becomes "latest"
+      npm_tag="latest"
+      if [[ $CI_COMMIT_TAG == *-* ]]; then
+        npm_tag="next"
       fi
+      echo "Publishing ${NPM_PACKAGE_NAME}@${CI_COMMIT_TAG} to npm (tag ${npm_tag})..."
+      npm version "${CI_COMMIT_TAG}" --no-git-tag-version --allow-same-version
+      npm publish --access public --tag "${npm_tag}"
   environment:
     name: production
     url: https://www.npmjs.com/package/${NPM_PACKAGE_NAME}
@@ -333,7 +356,7 @@ js:release:
   stage: release
   image: ${RELEASE_CLI_IMAGE}
   rules:
-    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
   before_script:
     - apk add --no-cache bash git jq
     - git config --global --add safe.directory '*'
@@ -341,7 +364,8 @@ js:release:
     - git config --global user.email "ci@gitlab.com"
   script:
     - |
-      PREVIOUS_TAG=$(git tag --sort=-version:refname | head -n 2 | tail -n 1 || echo "")
+      # Tags are listed newest first, with or without the old "v" prefix (v2.1.0 then 2.2.0)
+      PREVIOUS_TAG=$(git tag | sed -E 's/^v?(.*)$/\1 &/' | sort -k1,1 -Vr | cut -d' ' -f2 | grep -A1 -Fx "${CI_COMMIT_TAG}" | tail -n 1 || echo "")
       if [[ -n "$PREVIOUS_TAG" && "$PREVIOUS_TAG" != "$CI_COMMIT_TAG" ]]; then
         COMMITS=$(git log --pretty=format:"- %s" "${PREVIOUS_TAG}..${CI_COMMIT_TAG}" | head -20)
       else
@@ -356,7 +380,7 @@ js:release:
         --tag-name "${CI_COMMIT_TAG}" \
         --name "Release ${CI_COMMIT_TAG}" \
         --description "$(cat release_notes.md)" \
-        --assets-link "{\"name\":\"npm\",\"url\":\"https://www.npmjs.com/package/${NPM_PACKAGE_NAME}/v/${CI_COMMIT_TAG#v}\"}"
+        --assets-link "{\"name\":\"npm\",\"url\":\"https://www.npmjs.com/package/${NPM_PACKAGE_NAME}/v/${CI_COMMIT_TAG}\"}"
   artifacts:
     paths:
       - release_notes.md

package/README.md

@@ -146,7 +146,7 @@ Include in your consumer project's `.gitlab-ci.yml`:
 # npm package pipeline
 include:
   - project: 'zairakai/npm-packages/js-dev-tools'
-    ref: v1.0.0          # pin to a release tag for reproducible builds
+    ref: 1.0.0          # pin to a release tag for reproducible builds
     file: '.gitlab/ci/pipeline-js-package.yml'
 
 variables:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zairakai/js-dev-tools",
-  "version": "2.0.0",
+  "version": "3.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",

package/scripts/config.sh

@@ -43,6 +43,59 @@ detect_project_type() {
 PROJECT_TYPE="$(detect_project_type)"
 export PROJECT_TYPE
 
+# ─── DOCKER AUTO-DISPATCH ──────────────────────────────────────────────────────
+# Tool scripts that need a real Node runtime (eslint, prettier, stylelint, knip,
+# tsc/vue-tsc, vitest, npm outdated) call maybe_dockerize right after sourcing
+# this file. When a docker-compose stack is already running for this project,
+# the script transparently re-execs itself inside the "node" service instead of
+# depending on whatever Node happens to be on the host.
+#
+# Utility scripts (doctor.sh, install-hooks.sh, git-*.sh, setup-project.sh) never
+# call this — they inspect or act on the host on purpose and must keep doing so.
+#
+# Opt out with DEV_TOOLS_NO_DOCKER=true. Override target service/mount with
+# DEV_TOOLS_NODE_SERVICE / DEV_TOOLS_NODE_SERVICE_MOUNT if a project's compose
+# file diverges from the "node" / "/app" convention.
+DEV_TOOLS_DOCKER_ENV_VARS=(CI COVERAGE)
+
+maybe_dockerize() {
+    local script_path="$1"
+    shift
+
+    # Already running inside a container — nothing to dispatch.
+    [[ -f /.dockerenv ]] && return 0
+
+    # Explicit opt-out.
+    [[ "${DEV_TOOLS_NO_DOCKER:-false}" == "true" ]] && return 0
+
+    # CI runners execute inside a single job image, not this dev compose stack.
+    [[ "${CI:-false}" == "true" || "${GITLAB_CI:-false}" == "true" ]] && return 0
+
+    command -v docker >/dev/null 2>&1 || return 0
+    [[ -f "${PROJECT_ROOT}/docker-compose.yml" ]] || return 0
+
+    local service="${DEV_TOOLS_NODE_SERVICE:-node}"
+    local mount="${DEV_TOOLS_NODE_SERVICE_MOUNT:-/app}"
+
+    # Only dispatch when the target service is already running — never start
+    # it as a side effect of running a quality check.
+    if ! (cd "$PROJECT_ROOT" && docker compose ps --status running --services 2>/dev/null | grep -qx "$service"); then
+        return 0
+    fi
+
+    local rel_script="${script_path#"${PROJECT_ROOT}"/}"
+    local env_flags=()
+    local var
+    for var in "${DEV_TOOLS_DOCKER_ENV_VARS[@]}"; do
+        [[ -n "${!var:-}" ]] && env_flags+=(-e "$var")
+    done
+
+    log_step "Dispatching to '${service}' container..."
+    cd "$PROJECT_ROOT"
+    exec docker compose exec -T "${env_flags[@]}" "$service" bash "${mount}/${rel_script}" "$@"
+}
+export -f maybe_dockerize
+
 # ─── BINARY PATHS ─────────────────────────────────────────────────────────────
 BIN_DIR="${PROJECT_ROOT}/node_modules/.bin"
 export ESLINT_BIN="${BIN_DIR}/eslint"

package/scripts/eslint-fix.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 log_header "ESLint Fix"
 

package/scripts/eslint.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 log_header "ESLint Check"
 

package/scripts/knip.sh

@@ -18,6 +18,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "${SCRIPT_DIR}/config.sh"
+maybe_dockerize "$0" "$@"
 
 KNIP_BIN="${BIN_DIR}/knip"
 

package/scripts/outdated.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 log_header "NPM Outdated Check"
 

package/scripts/prettier-fix.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 EXTRA_IGNORES=()
 while [[ $# -gt 0 ]]; do

package/scripts/prettier.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 EXTRA_IGNORES=()
 while [[ $# -gt 0 ]]; do

package/scripts/setup-project.sh

@@ -382,7 +382,7 @@ replace_gitlab_ci_placeholders() {
     fi
 
     if [[ -n "$dev_tools_version" ]]; then
-        sed -i "s|v0.0.0|v${dev_tools_version}|g" "$target"
+        sed -i "s|ref: 0\.0\.0|ref: ${dev_tools_version}|g" "$target"
     fi
 }
 
@@ -417,7 +417,7 @@ publish_gitlab_ci_npm() {
 
     track_published ".gitlab-ci.yml"
     log_success "Published: .gitlab-ci.yml"
-    log_info "ref: v0.0.0 will be updated automatically on: ${PM} update @zairakai/js-dev-tools"
+    log_info "ref: 0.0.0 will be updated automatically on: ${PM} update @zairakai/js-dev-tools"
 }
 
 # ============================================================================
@@ -650,7 +650,7 @@ sync_gitlab_ci_ref() {
 
     # Resolve installed version from the package's own package.json
     local installed_version
-    installed_version="$(node -e "try{const p=require('${DEV_TOOLS_ROOT}/package.json');console.log('v'+(p.version||'').replace(/^v/,''))}catch(e){}" 2>/dev/null || echo "")"
+    installed_version="$(node -e "try{const p=require('${DEV_TOOLS_ROOT}/package.json');console.log((p.version||'').replace(/^v/,''))}catch(e){}" 2>/dev/null || echo "")"
 
     [[ -n "$installed_version" ]] || return 0
 

package/scripts/stylelint-fix.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 EXTRA_IGNORES=()
 while [[ $# -gt 0 ]]; do

package/scripts/stylelint.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 EXTRA_IGNORES=()
 while [[ $# -gt 0 ]]; do

package/scripts/test.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/config.sh"
+maybe_dockerize "$0" "$@"
 
 log_header "Vitest Tests"
 

package/scripts/typecheck.sh

@@ -13,6 +13,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 source "${SCRIPT_DIR}/config.sh"
+maybe_dockerize "$0" "$@"
 
 TSC_BIN="${BIN_DIR}/tsc"
 VUE_TSC_BIN="${BIN_DIR}/vue-tsc"

package/stubs/githooks/commit-msg

@@ -1,34 +1,59 @@
 #!/usr/bin/env bash
+# Commit message validation hook
+# Published by: zairakai/laravel-dev-tools. Same hook as php-dev-tools and js-dev-tools, aligned on the commit convention of the zairakai handbook
+# (policies/git-rules.md), which is the only convention of the zairakai tools:
 #
-# Zairakai Git Hooks - Commit Message Validator
-# Ensures commit messages follow Conventional Commits format
+#   <type>(<scope>): #TICKET <subject>
+#
+#   - type: feat, fix, docs, style, refactor, perf, test, chore, ci or build
+#   - scope: optional, in lowercase
+#   - #TICKET: the number of the issue
+#   - the first line has 72 characters at most, and the second line is blank
+#
+# A work in progress follows the same format. The messages that Git writes itself
+# (Merge, Revert, fixup!, squash!) are accepted as they are.
 #
 # To bypass (emergency only):
 #   git commit --no-verify
 
-set -euo pipefail
-
-# ANSI Colors
-RED='\033[0;31m'
-NC='\033[0m'
+commit_msg_file="$1"
+first_line=$(sed -n 1p "$commit_msg_file")
+second_line=$(sed -n 2p "$commit_msg_file")
 
-COMMIT_MSG_FILE=$1
-COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+case "$first_line" in
+    "Merge "* | "Revert \""* | "fixup! "* | "squash! "* | "amend! "*) exit 0 ;;
+esac
 
-# Conventional Commits regex
-# Format: <type>(<scope>): <subject>
-CONVENTIONAL_RE='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|init)(\(.+\))?!?: .+$'
+PATTERN='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build)(\([a-z0-9][a-z0-9._/-]*\))?: #[0-9]+ [^[:space:]].*$'
 
-if [[ ! $COMMIT_MSG =~ $CONVENTIONAL_RE ]]; then
+fail() {
     echo ""
-    echo -e "${RED}❌ Invalid commit message format!${NC}"
+    echo "❌ $1"
     echo ""
-    echo "Commit messages must follow Conventional Commits:"
-    echo "  feat: add new feature"
-    echo "  fix: resolve a bug"
-    echo "  chore(deps): update dependencies"
+    echo "  Format of the zairakai handbook:  <type>(<scope>): #TICKET <subject>"
+    echo "  Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build"
     echo ""
-    echo "See: https://www.conventionalcommits.org/"
+    echo "  Your message: \"$first_line\""
+    echo ""
+    echo "  Examples:"
+    echo "    feat(auth): #102 add OAuth2 provider support"
+    echo "    fix(api): #87 handle null response from payment gateway"
+    echo "    docs: #31 update installation instructions"
     echo ""
     exit 1
+}
+
+if ! [[ $first_line =~ $PATTERN ]]; then
+    fail "Invalid commit message format"
 fi
+
+if [[ ${#first_line} -gt 72 ]]; then
+    fail "The first line has ${#first_line} characters: the limit is 72"
+fi
+
+if [[ -n $second_line ]]; then
+    fail "The second line must be blank"
+fi
+
+echo "✅ Commit message OK"
+exit 0

package/stubs/githooks/prepare-commit-msg

@@ -1,39 +1,33 @@
 #!/usr/bin/env bash
+# Prepare commit message hook - adds the ticket of the branch to the message
+# Published by: zairakai/laravel-dev-tools. Same hook as php-dev-tools and js-dev-tools. The fix: the ticket goes after "type(scope): ",
+# which is the form that the hook commit-msg asks for.
 #
-# Zairakai Git Hooks - Commit Message Preparer
-# Auto-prefixes the ticket number from branch name (e.g. feature/ABC-123 -> ABC-123: )
+# Branch naming convention:
+#   feature/#123-description  → "feat(scope): subject" becomes "feat(scope): #123 subject"
+#   fix/#456-bug-description  → the same with #456
+#   hotfix/#789-critical      → the same with #789
 #
+# Nothing is changed for a merge, a squash or an amend, when the message already has the ticket,
+# or when its first line is not "type(scope): subject".
 
-set -euo pipefail
+commit_msg_file="$1"
+commit_source="$2"
 
-COMMIT_MSG_FILE=$1
-BRANCH_NAME=$(git symbolic-ref --short HEAD 2>/dev/null || true)
+case "$commit_source" in
+    merge | squash | commit) exit 0 ;;
+esac
 
-# Skip for special commits
-COMMIT_SOURCE=${2:-}
-if [[ "$COMMIT_SOURCE" == "merge" || "$COMMIT_SOURCE" == "squash" || "$COMMIT_SOURCE" == "message" ]]; then
-    exit 0
-fi
+branch=$(git symbolic-ref --short HEAD 2>/dev/null)
 
-# Extract ticket number (Jira/GitLab style: PROJECT-123)
-TICKET_RE='[A-Z]+-[0-9]+'
-if [[ $BRANCH_NAME =~ $TICKET_RE ]]; then
-    TICKET="${BASH_REMATCH[0]}"
-    COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+# Extract the ticket from a branch named type/#NUMBER-description
+if [[ $branch =~ (feature|fix|hotfix)/#([0-9]+) ]]; then
+    ticket="#${BASH_REMATCH[2]}"
 
-    # Only prefix if not already present
-    if [[ ! $COMMIT_MSG =~ $TICKET ]]; then
-        # If it's a conventional commit type: subject format, inject after type:
-        # Before: feat: my change
-        # After: feat(ABC-123): my change
-        CONVENTIONAL_RE='^([a-z]+)(\(.*\))?!?: (.+)$'
-        if [[ $COMMIT_MSG =~ $CONVENTIONAL_RE ]]; then
-            TYPE="${BASH_REMATCH[1]}"
-            REMAINDER="${BASH_REMATCH[3]}"
-            echo "${TYPE}(${TICKET}): ${REMAINDER}" > "$COMMIT_MSG_FILE"
-        else
-            # Fallback: simple prefix
-            echo "${TICKET}: ${COMMIT_MSG}" > "$COMMIT_MSG_FILE"
-        fi
+    if ! grep -qE "${ticket}([^0-9]|$)" "$commit_msg_file"; then
+        sed -i.bak -E "1s/^([a-z]+(\([^)]*\))?: )/\1${ticket} /" "$commit_msg_file"
+        rm -f "$commit_msg_file.bak"
     fi
 fi
+
+exit 0

package/stubs/gitlab-ci/gitlab-ci.yml.stub

@@ -7,7 +7,7 @@
 
 include:
   - project: 'zairakai/npm-packages/js-dev-tools'
-    ref: v0.0.0
+    ref: 0.0.0
     file: '.gitlab/ci/pipeline-js-package.yml'
 
 variables:

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

@@ -8,7 +8,7 @@
 
 include:
   - project: 'zairakai/npm-packages/js-dev-tools'
-    ref: v0.0.0
+    ref: 0.0.0
     file: '.gitlab/ci/pipeline-js-app.yml'
 
 variables: