@zairakai/dev-tools 1.0.11

package/.editorconfig

@@ -0,0 +1,86 @@
+# ===============================================
+# EDITORCONFIG
+# Coding standards for consistent formatting
+# ===============================================
+
+root = true
+
+# ======================
+# ALL FILES
+# ======================
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# ======================
+# MARKDOWN FILES
+# ======================
+[markdown]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = false
+insert_final_newline = true
+max_line_length = 120
+
+[*.md]
+trim_trailing_whitespace = false
+
+# ======================
+# SHELL SCRIPTS
+# ======================
+[*.sh]
+end_of_line = lf
+
+# ======================
+# YAML FILES
+# ======================
+[*.{yml,yaml}]
+indent_size = 2
+
+[docker-compose.yml]
+indent_size = 4
+
+# ======================
+# BUILD FILES
+# ======================
+[Makefile]
+indent_style = tab
+
+[Dockerfile*]
+indent_size = 4
+
+# ======================
+# CONFIGURATION FILES
+# ======================
+[*.{ini,conf}]
+indent_size = 4
+
+# ======================
+# FRONTEND FILES
+# ======================
+[*.json]
+indent_size = 2
+
+# ======================
+# PHP FILES
+# ======================
+[*.php]
+indent_size = 4
+max_line_length = 120
+
+# ======================
+# Test FILES
+# ======================
+[*.feature]
+charset = utf-8
+gherkin_indent_feature_children = true
+gherkin_indent_steps = true
+gherkin_indent_datatable = true
+gherkin_indent_docstring = true
+gherkin_indent_examples_table = true
+gherkin_table_cell_padding_size = 2
+gherkin_table_cell_right_align_numeric_content = true

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

@@ -0,0 +1,189 @@
+# ================================
+# PIPELINE TEMPLATE — Laravel App JS/Frontend
+# ================================
+# Provides JS/Frontend CI jobs for a Laravel application.
+# PHP jobs come from laravel-dev-tools (pipeline-laravel-app.yml).
+#
+# Fullstack usage (recommended — single include):
+# ─────────────────────────────────────────────────────
+#   include:
+#     - project: 'zairakai/packagist/laravel-dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-laravel-fullstack.yml'
+#
+# Standalone usage (without laravel-dev-tools):
+# ─────────────────────────────────────────────────────
+#   include:
+#     - project: 'zairakai/packagist/laravel-dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-laravel-app.yml'
+#     - project: 'zairakai/npm/dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-js.yml'
+#
+#   variables:
+#     CACHE_KEY: "my-app-v1"
+# ================================
+
+# ================================
+# STAGES
+# ================================
+# Merges with PHP pipeline stages — GitLab deduplicates identical names.
+stages:
+  - security
+  - install
+  - validate
+  - quality
+  - test
+  - deploy
+  - metrics
+
+# ================================
+# DEFAULT VARIABLES
+# ================================
+variables:
+  # ── OVERRIDE PER PROJECT ──────────────────────────────────────────────────
+  CACHE_KEY: "zairakai-laravel-app"
+
+  # Points to the installed npm dev-tools package
+  DEV_TOOLS_SCRIPTS: "node_modules/@zairakai/dev-tools/scripts"
+
+  # ── NODE ──────────────────────────────────────────────────────────────────
+  NODE_VERSION: "22"
+  NODE_IMAGE: "zairakai/node:latest-dev"
+
+  # ── GIT ───────────────────────────────────────────────────────────────────
+  GIT_DEPTH: 1
+  GIT_STRATEGY: fetch
+  # Note: GIT_CLEAN_FLAGS is intentionally NOT set here.
+  # In fullstack mode, pipeline-laravel-fullstack.yml sets the combined value
+  # to exclude both vendor/ and node_modules/ from git clean.
+
+# ================================
+# ANCHORS
+# ================================
+.base_job_js: &base_job_js
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+
+.cache_node_js: &cache_node_js
+  cache:
+    key:
+      files:
+        - package-lock.json
+      prefix: "js-${CACHE_KEY}"
+    paths:
+      - node_modules/
+      - .npm/
+    policy: pull
+
+.cache_node_js_push: &cache_node_js_push
+  cache:
+    key:
+      files:
+        - package-lock.json
+      prefix: "js-${CACHE_KEY}"
+    paths:
+      - node_modules/
+      - .npm/
+    policy: pull-push
+
+.job_node_js: &job_node_js
+  <<: [*base_job_js, *cache_node_js]
+  image: ${NODE_IMAGE}
+  before_script:
+    - node --version
+    - npm --version
+
+.js_validate_needs: &js_validate_needs
+  needs:
+    - validate:js:markdownlint
+
+# ================================
+# INSTALL (JS)
+# ================================
+install:js:
+  <<: [*base_job_js, *cache_node_js_push]
+  stage: install
+  image: ${NODE_IMAGE}
+  script:
+    - npm ci --cache .npm --prefer-offline
+  artifacts:
+    paths:
+      - node_modules/
+    expire_in: 1 hour
+
+# ================================
+# VALIDATE (JS)
+# ================================
+validate:js:markdownlint:
+  <<: *job_node_js
+  stage: validate
+  needs:
+    - install:js
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/markdownlint.sh"
+
+# ================================
+# QUALITY (JS)
+# ================================
+quality:js:lint:
+  <<: [*job_node_js, *js_validate_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/eslint.sh"
+  artifacts:
+    reports:
+      junit: reports/eslint.xml
+    paths:
+      - reports/
+    expire_in: 1 week
+    when: always
+
+quality:js:format:
+  <<: [*job_node_js, *js_validate_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/prettier.sh"
+
+quality:js:stylelint:
+  <<: [*job_node_js, *js_validate_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/stylelint.sh"
+  allow_failure: true
+
+quality:js:typecheck:
+  <<: [*job_node_js, *js_validate_needs]
+  stage: quality
+  script:
+    - |
+      if [ -f tsconfig.json ] && [ -f node_modules/.bin/tsc ]; then
+        bash "$DEV_TOOLS_SCRIPTS/typecheck.sh"
+      else
+        echo "TypeScript not configured — skipping (add tsconfig.json + typescript to devDependencies)"
+      fi
+  allow_failure: true
+
+# ================================
+# TEST (JS)
+# ================================
+test:js:
+  <<: *job_node_js
+  stage: test
+  script:
+    - CI=true bash "$DEV_TOOLS_SCRIPTS/test.sh"
+  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
+  artifacts:
+    reports:
+      junit: build/coverage/junit.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: build/coverage/cobertura-coverage.xml
+    paths:
+      - build/coverage/
+    expire_in: 1 week
+    when: always

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

@@ -0,0 +1,353 @@
+# ================================
+# PIPELINE TEMPLATE — NPM Package
+# ================================
+# Shared pipeline template for NPM packages in the Zairakai namespace.
+# Self-contained: anchors and jobs are all in this single file.
+# YAML anchors do not survive cross-file include: — this is a YAML parser
+# limitation, not a GitLab one. Everything is therefore kept here.
+#
+# USAGE in a consumer project:
+# ─────────────────────────────────────────
+#   include:
+#     - project: 'zairakai/npm/dev-tools'
+#       ref: main
+#       file: '.gitlab/ci/pipeline-npm-package.yml'
+#
+#   variables:
+#     CACHE_KEY: "my-package-v1"
+#     NPM_PACKAGE_NAME: "@myorg/my-package"
+#
+# FOR dev-tools ITSELF (self-hosted mode):
+# ─────────────────────────────────────────────────────
+#   include:
+#     - local: '.gitlab/ci/pipeline-npm-package.yml'
+#
+#   variables:
+#     CACHE_KEY: "dev-tools-v1"
+#     NPM_PACKAGE_NAME: "@zairakai/dev-tools"
+#     DEV_TOOLS_SCRIPTS: "scripts"
+# ================================
+
+include:
+  - template: Jobs/Secret-Detection.gitlab-ci.yml
+
+# ================================
+# WORKFLOW
+# ================================
+workflow:
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
+    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
+    - if: $CI_COMMIT_REF_NAME =~ /^feature\// || $CI_COMMIT_REF_NAME =~ /^fix\// || $CI_COMMIT_REF_NAME =~ /^hotfix\//
+    - when: never
+
+# ================================
+# STAGES
+# ================================
+stages:
+  - security
+  - install
+  - validate
+  - quality
+  - test
+  - build
+  - publish
+  - release
+
+# ================================
+# DEFAULT VARIABLES
+# ================================
+variables:
+  # ── OVERRIDE PER PROJECT ──────────────────────────────────────────────────
+  CACHE_KEY: "zairakai-npm-package"
+  NPM_PACKAGE_NAME: "@zairakai/package"
+
+  # Paths to dev-tools scripts.
+  # Consumer projects do NOT need to override these.
+  # dev-tools itself overrides them in its own .gitlab-ci.yml.
+  DEV_TOOLS_SCRIPTS: "node_modules/@zairakai/dev-tools/scripts"
+
+  # ── NODE ──────────────────────────────────────────────────────────────────
+  NODE_VERSION: "22"
+  NODE_IMAGE: "zairakai/node:latest-dev"
+  NODE_TEST_IMAGE: "zairakai/node:latest-test"
+  SHELLCHECK_IMAGE: "koalaman/shellcheck-alpine:v0.10.0"
+  RELEASE_CLI_IMAGE: "registry.gitlab.com/gitlab-org/release-cli:v0.18.0"
+  ALPINE_IMAGE: "alpine:3.18"
+
+  # ── GIT ───────────────────────────────────────────────────────────────────
+  GIT_DEPTH: 1
+  GIT_STRATEGY: fetch
+  GIT_CLEAN_FLAGS: "-ffdx -e node_modules/ -e .npm/"
+
+  # ── SECURITY ──────────────────────────────────────────────────────────────
+  SECRET_DETECTION_EXCLUDED_PATHS: "node_modules/,dist/,build/,coverage/"
+
+# ================================
+# ANCHORS
+# ================================
+.base_job: &base_job
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+
+.cache_node: &cache_node
+  cache:
+    key:
+      files:
+        - package-lock.json
+      prefix: $CACHE_KEY
+    paths:
+      - node_modules/
+      - .npm/
+    policy: pull
+
+.cache_node_push: &cache_node_push
+  cache:
+    key:
+      files:
+        - package-lock.json
+      prefix: $CACHE_KEY
+    paths:
+      - node_modules/
+      - .npm/
+    policy: pull-push
+
+.job_node: &job_node
+  <<: [*base_job, *cache_node]
+  image: ${NODE_IMAGE}
+  before_script:
+    - node --version
+    - npm --version
+
+.quality_needs: &quality_needs
+  needs:
+    - validate:shellcheck
+
+# ================================
+# SECURITY
+# ================================
+secret_detection:
+  stage: security
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
+    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
+
+# ================================
+# INSTALL
+# ================================
+install:dependencies:
+  <<: [*base_job, *cache_node_push]
+  stage: install
+  image: ${NODE_IMAGE}
+  script:
+    - npm ci --cache .npm --prefer-offline
+  artifacts:
+    paths:
+      - node_modules/
+    expire_in: 1 hour
+
+# ================================
+# VALIDATE
+# ================================
+validate:shellcheck:
+  <<: *base_job
+  stage: validate
+  image: ${SHELLCHECK_IMAGE}
+  needs:
+    - install:dependencies
+  before_script:
+    - apk add --no-cache bash
+  script:
+    - |
+      if [[ -d scripts/ ]]; then
+        bash "$DEV_TOOLS_SCRIPTS/validate-shellcheck.sh"
+      else
+        echo "No scripts/ directory found — skipping ShellCheck"
+      fi
+
+# ================================
+# QUALITY
+# ================================
+quality:lint:
+  <<: [*job_node, *quality_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/eslint.sh"
+  artifacts:
+    reports:
+      junit: reports/eslint.xml
+    paths:
+      - reports/
+    expire_in: 1 week
+    when: always
+
+quality:format:
+  <<: [*job_node, *quality_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/prettier.sh"
+
+quality:markdownlint:
+  <<: [*job_node, *quality_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/markdownlint.sh"
+
+quality:stylelint:
+  <<: [*job_node, *quality_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/stylelint.sh"
+
+quality:typecheck:
+  <<: [*job_node, *quality_needs]
+  stage: quality
+  script:
+    - |
+      if [ -f tsconfig.json ] && [ -f node_modules/.bin/tsc ]; then
+        bash "$DEV_TOOLS_SCRIPTS/typecheck.sh"
+      else
+        echo "TypeScript not configured — skipping (add tsconfig.json + typescript to devDependencies)"
+      fi
+
+quality:knip:
+  <<: [*job_node, *quality_needs]
+  stage: quality
+  script:
+    - bash "$DEV_TOOLS_SCRIPTS/knip.sh"
+
+quality:bats:
+  <<: [*base_job, *cache_node, *quality_needs]
+  stage: quality
+  image: alpine:3.18
+  before_script:
+    - apk add --no-cache bash bats
+  script:
+    - |
+      if [[ -d tests/bats ]]; then
+        bats tests/bats --recursive
+      else
+        echo "No BATS tests found — skipping"
+      fi
+
+# ================================
+# TEST
+# ================================
+test:
+  <<: [*base_job, *cache_node]
+  stage: test
+  image: ${NODE_TEST_IMAGE}
+  script:
+    - CI=true bash "$DEV_TOOLS_SCRIPTS/test.sh"
+  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
+  artifacts:
+    reports:
+      junit: build/coverage/junit.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: build/coverage/cobertura-coverage.xml
+    paths:
+      - build/coverage/
+    expire_in: 1 week
+    when: always
+
+# ================================
+# BUILD
+# ================================
+build:
+  <<: *job_node
+  stage: build
+  needs:
+    - test
+  script:
+    - |
+      if [ -f node_modules/.bin/tsup ] || [ -f node_modules/.bin/tsc ]; then
+        bash "$DEV_TOOLS_SCRIPTS/build.sh"
+      else
+        echo "No TypeScript builder configured — skipping (install tsup or typescript)"
+      fi
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+    when: on_success
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+    - if: $CI_COMMIT_BRANCH == "main"
+    - when: never
+  allow_failure: true
+
+# ================================
+# PUBLISH
+# ================================
+publish:npm:
+  <<: [*base_job, *cache_node]
+  stage: publish
+  image: ${NODE_IMAGE}
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  needs:
+    - build
+  script:
+    - |
+      if [[ -z "${NPM_TOKEN:-}" ]]; then
+        echo "ERROR: NPM_TOKEN is not set or empty"
+        echo "Go to: GitLab → Settings → CI/CD → Variables → add NPM_TOKEN (type: Variable, protected, masked)"
+        exit 1
+      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
+        npm publish --access public
+      else
+        echo "Invalid tag format: ${CI_COMMIT_TAG}. Expected: v1.0.0"
+        exit 1
+      fi
+  environment:
+    name: production
+    url: https://www.npmjs.com/package/${NPM_PACKAGE_NAME}
+
+# ================================
+# RELEASE
+# ================================
+release:gitlab:
+  <<: *base_job
+  stage: release
+  image: ${RELEASE_CLI_IMAGE}
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  needs:
+    - publish:npm
+  before_script:
+    - apk add --no-cache bash git jq
+    - git config --global --add safe.directory '*'
+    - git config --global user.name "GitLab CI"
+    - git config --global user.email "ci@gitlab.com"
+  script:
+    - |
+      PREVIOUS_TAG=$(git tag --sort=-version:refname | head -n 2 | 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
+        COMMITS="- Initial release"
+      fi
+      cat > release_notes.md << NOTES
+      ## ${CI_COMMIT_TAG}
+
+      ${COMMITS}
+      NOTES
+      release-cli create \
+        --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}\"}"
+  artifacts:
+    paths:
+      - release_notes.md
+    expire_in: 1 year

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stanislas Poisson (Zairakai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.