@hellopearl/dv-gitlab 0.4.4 → 0.5.0

package/bin/dv-gitlab.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* eslint-disable no-undef */
 'use strict';
 
 if (typeof globalThis.fetch === 'undefined') {

package/ci/api-test.yml

@@ -36,7 +36,7 @@
 
     # ── Run ──
     - echo "==> Starting service on port ${SERVICE_PORT}..."
-    - env | grep -v "^CI_\|^DOCKER_\|^FF_\|^GITLAB_" > /tmp/sut.env
+    - env | grep '=' | grep -v "^CI_\|^DOCKER_\|^FF_\|^GITLAB_" > /tmp/sut.env
     - docker run -d --name sut -p ${SERVICE_PORT}:${SERVICE_PORT} --env-file /tmp/sut.env sut
     - echo "    Container ID $(docker ps -q --filter name=sut)"
 

package/ci/assert-full-test-run.yml

@@ -0,0 +1,18 @@
+# Reusable template: SCRIBE-539 false-green guard.
+# Verifies Jest ran every discovered test suite by comparing
+# `jest --listTests` with the "Test Suites: N total" log line.
+#
+# Consumer usage:
+#   include:
+#     - project: 'hellopearl/pearl-agentic-mono'
+#       ref: main
+#       file: '/packages/dev/dv-gitlab/ci/assert-full-test-run.yml'
+#
+#   test:unit:
+#     script:
+#       - npm run test:unit 2>&1 | tee jest-unit.log
+#       - npx @hellopearl/dv-gitlab assert-full-test-run --log-path jest-unit.log --pattern __tests__/unit
+
+.assert-full-test-run:
+  script:
+    - npx @hellopearl/dv-gitlab assert-full-test-run --log-path ${JEST_LOG_PATH:-jest-unit.log} --pattern ${JEST_TEST_PATTERN:-__tests__/unit} --extension ${JEST_FILE_EXTENSION:-.test.js}

package/ci/e2e-enforce.yml

@@ -1,18 +1,36 @@
 # Reusable template: enforce green E2E on MRs.
-# Waits for an Amplify preview to go live, triggers pearl-test-automation,
+# Optionally waits for an Amplify preview, triggers pearl-test-automation,
 # then polls until the pipeline finishes — failing if tests are red.
 #
-# Consumer usage:
+# Required CI/CD variables (set in consumer project or inherited from group):
+#   E2E_API_TOKEN  — Group Access Token (hellopearl, api scope)
+#                    Used to trigger and poll pearl-test-automation pipelines.
+#                    Set once at group level — inherited by all consumer repos.
+#
+# Consumer usage (web app with Amplify preview):
 #   include:
 #     - project: 'hellopearl/pearl-agentic-mono'
 #       ref: main
 #       file: '/packages/dev/dv-gitlab/ci/e2e-enforce.yml'
 #
-#   e2e:
+#   e2e:voice:
 #     extends: .e2e-enforce
 #     variables:
-#       E2E_PROJECT: Voice           # pearl-test-automation project name
+#       E2E_PROJECT: Voice
 #       PREVIEW_DOMAIN: voice.hellopearl.com
+#
+# Consumer usage (extension / no preview):
+#   e2e:extension:
+#     extends: .e2e-enforce
+#     needs:
+#       - job: package mr extension
+#         optional: true
+#         artifacts: true
+#     variables:
+#       E2E_PROJECT: Extension
+#       E2E_SCOPE: Smoke
+#     # PREVIEW_DOMAIN is empty → preview wait is skipped.
+#     # EXTENSION_ARTIFACT_URL comes from dotenv artifact of the needs job.
 
 .e2e-enforce:
   stage: e2e
@@ -20,62 +38,69 @@
   before_script:
     - apk add --no-cache curl jq
   variables:
-    QA_PROJECT_ID: "59469690"
-    E2E_PROJECT: ""
-    E2E_SCOPE: "All"
-    E2E_ENV: "dev"
-    PREVIEW_DOMAIN: ""
-    PREVIEW_WAIT_ATTEMPTS: "60"
-    PREVIEW_WAIT_INTERVAL: "10"
-    PIPELINE_POLL_ATTEMPTS: "180"
-    PIPELINE_POLL_INTERVAL: "10"
+    QA_PROJECT_ID: '59469690'
+    E2E_PROJECT: ''
+    E2E_SCOPE: 'All'
+    E2E_ENV: 'dev'
+    PREVIEW_DOMAIN: ''
+    PREVIEW_WAIT_ATTEMPTS: '60'
+    PREVIEW_WAIT_INTERVAL: '10'
+    PIPELINE_POLL_ATTEMPTS: '180'
+    PIPELINE_POLL_INTERVAL: '10'
   script:
     - |
-      if [ -z "$E2E_PROJECT" ] || [ -z "$PREVIEW_DOMAIN" ]; then
-        echo "[e2e-enforce] ERROR: E2E_PROJECT and PREVIEW_DOMAIN must be set"
+      if [ -z "$E2E_PROJECT" ]; then
+        echo "[e2e-enforce] ERROR: E2E_PROJECT must be set"
         exit 1
       fi
 
-      if [ -z "$GITLAB_API_TOKEN" ]; then
-        echo "[e2e-enforce] GITLAB_API_TOKEN not set — skipping E2E (configure in CI/CD variables)"
-        exit 0
+      if [ -z "$E2E_API_TOKEN" ]; then
+        echo "[e2e-enforce] ❌ E2E_API_TOKEN not set — cannot trigger/poll pearl-test-automation"
+        echo "[e2e-enforce] Set it as a Group Access Token (api scope) at the hellopearl group level"
+        exit 1
       fi
 
-      BRANCH_SLUG=$(echo "$CI_COMMIT_REF_NAME" | tr '[:upper:]' '[:lower:]' | sed 's|/|-|g')
-      PREVIEW_URL="https://${BRANCH_SLUG}.${PREVIEW_DOMAIN}"
-      echo "[e2e-enforce] Preview URL: $PREVIEW_URL"
       echo "[e2e-enforce] Project: $E2E_PROJECT | Scope: $E2E_SCOPE | Env: $E2E_ENV"
 
-      # ── Wait for Amplify preview ──
-      echo "[e2e-enforce] Waiting for preview to go live..."
-      for i in $(seq 1 "$PREVIEW_WAIT_ATTEMPTS"); do
-        STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL" 2>/dev/null || echo "000")
-        [ "$STATUS" = "200" ] && break
-        echo "[e2e-enforce] Attempt $i/${PREVIEW_WAIT_ATTEMPTS} — HTTP $STATUS"
-        sleep "$PREVIEW_WAIT_INTERVAL"
-      done
-      if [ "$STATUS" != "200" ]; then
-        echo "[e2e-enforce] Preview not available — skipping (non-blocking)"
-        exit 0
+      # ── Wait for Amplify preview (skipped when PREVIEW_DOMAIN is empty) ──
+      PREVIEW_URL=""
+      if [ -n "$PREVIEW_DOMAIN" ]; then
+        BRANCH_SLUG=$(echo "$CI_COMMIT_REF_NAME" | tr '[:upper:]' '[:lower:]' | sed 's|/|-|g')
+        PREVIEW_URL="https://${BRANCH_SLUG}.${PREVIEW_DOMAIN}"
+        echo "[e2e-enforce] Preview URL: $PREVIEW_URL"
+        echo "[e2e-enforce] Waiting for preview to go live..."
+        for i in $(seq 1 "$PREVIEW_WAIT_ATTEMPTS"); do
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL" 2>/dev/null || echo "000")
+          [ "$STATUS" = "200" ] && break
+          echo "[e2e-enforce] Attempt $i/${PREVIEW_WAIT_ATTEMPTS} — HTTP $STATUS"
+          sleep "$PREVIEW_WAIT_INTERVAL"
+        done
+        if [ "$STATUS" != "200" ]; then
+          echo "[e2e-enforce] ❌ Preview not available after ${PREVIEW_WAIT_ATTEMPTS} attempts — E2E gate blocked"
+          echo "[e2e-enforce] Expected 200 at $PREVIEW_URL, got HTTP $STATUS"
+          exit 1
+        fi
+        echo "[e2e-enforce] Preview is live."
+      else
+        echo "[e2e-enforce] No PREVIEW_DOMAIN — skipping preview wait"
       fi
-      echo "[e2e-enforce] Preview is live."
 
-      # ── Trigger pearl-test-automation ──
-      RESPONSE=$(curl -s --header "PRIVATE-TOKEN: ${GITLAB_API_TOKEN}" \
+      # ── Trigger pearl-test-automation via API ──
+      VARS="[{\"key\":\"PROJECT\",\"value\":\"$E2E_PROJECT\"}"
+      VARS="$VARS,{\"key\":\"ENV\",\"value\":\"$E2E_ENV\"}"
+      VARS="$VARS,{\"key\":\"SCOPE\",\"value\":\"$E2E_SCOPE\"}"
+      VARS="$VARS,{\"key\":\"SOURCE_PROJECT_ID\",\"value\":\"$CI_PROJECT_ID\"}"
+      VARS="$VARS,{\"key\":\"SOURCE_MR_IID\",\"value\":\"${CI_MERGE_REQUEST_IID:-}\"}"
+      [ -n "$PREVIEW_URL" ] && VARS="$VARS,{\"key\":\"PREVIEW_URL\",\"value\":\"$PREVIEW_URL\"}"
+      [ -n "${EXTENSION_ARTIFACT_URL:-}" ] && VARS="$VARS,{\"key\":\"EXTENSION_ARTIFACT_URL\",\"value\":\"$EXTENSION_ARTIFACT_URL\"}"
+      [ -n "${E2E_CAPTURE:-}" ] && VARS="$VARS,{\"key\":\"CAPTURE\",\"value\":\"$E2E_CAPTURE\"}"
+      VARS="$VARS]"
+
+      RESPONSE=$(curl -s --request POST \
+        --header "PRIVATE-TOKEN: ${E2E_API_TOKEN}" \
         --header "Content-Type: application/json" \
-        --request POST \
-        "https://gitlab.com/api/v4/projects/${QA_PROJECT_ID}/pipeline" \
-        --data "{
-          \"ref\": \"main\",
-          \"variables\": [
-            {\"key\": \"PROJECT\", \"value\": \"$E2E_PROJECT\"},
-            {\"key\": \"ENV\", \"value\": \"$E2E_ENV\"},
-            {\"key\": \"SCOPE\", \"value\": \"$E2E_SCOPE\"},
-            {\"key\": \"PREVIEW_URL\", \"value\": \"$PREVIEW_URL\"},
-            {\"key\": \"SOURCE_PROJECT_ID\", \"value\": \"$CI_PROJECT_ID\"},
-            {\"key\": \"SOURCE_MR_IID\", \"value\": \"$CI_MERGE_REQUEST_IID\"}
-          ]
-        }")
+        --data "{\"ref\":\"main\",\"variables\":$VARS}" \
+        "https://gitlab.com/api/v4/projects/${QA_PROJECT_ID}/pipeline")
       PIPELINE_ID=$(echo "$RESPONSE" | jq -r '.id // empty')
       PIPELINE_URL=$(echo "$RESPONSE" | jq -r '.web_url // empty')
 
@@ -85,12 +110,17 @@
       fi
       echo "[e2e-enforce] Triggered: $PIPELINE_URL"
 
-      # ── Poll for result ──
+      # ── Poll for result using E2E_API_TOKEN ──
       for i in $(seq 1 "$PIPELINE_POLL_ATTEMPTS"); do
         sleep "$PIPELINE_POLL_INTERVAL"
-        PSTATUS=$(curl -s --header "PRIVATE-TOKEN: ${GITLAB_API_TOKEN}" \
-          "https://gitlab.com/api/v4/projects/${QA_PROJECT_ID}/pipelines/$PIPELINE_ID" \
-          | jq -r '.status')
+        POLL_RESPONSE=$(curl -s --header "PRIVATE-TOKEN: ${E2E_API_TOKEN}" \
+          "https://gitlab.com/api/v4/projects/${QA_PROJECT_ID}/pipelines/$PIPELINE_ID")
+        PSTATUS=$(echo "$POLL_RESPONSE" | jq -r '.status // empty')
+        if [ -z "$PSTATUS" ]; then
+          echo "[e2e-enforce] ⚠ API returned no status — response: $(echo "$POLL_RESPONSE" | jq -c '.' 2>/dev/null || echo "$POLL_RESPONSE")"
+          echo "[e2e-enforce] Token may lack read_api access to project $QA_PROJECT_ID"
+          exit 1
+        fi
         case "$PSTATUS" in
           success)
             echo "[e2e-enforce] ✅ E2E PASSED — $PIPELINE_URL"

package/ci/migration-contract.yml

@@ -0,0 +1,31 @@
+# Reusable template: migration contract checker.
+# Prevents destructive migrations (dropColumn, renameTable, etc.)
+# that would break N-1 rollback compatibility during canary deploys.
+#
+# Consumer usage:
+#   include:
+#     - project: 'hellopearl/pearl-agentic-mono'
+#       ref: main
+#       file: '/packages/dev/dv-gitlab/ci/migration-contract.yml'
+#
+#   migration-contract:
+#     extends: .migration-contract
+#     variables:
+#       GRANDFATHERED_FILES: "file1.js,file2.js"  # optional
+#       MIGRATIONS_DIR: "migrations/"             # optional, default
+#
+# Runs only on MRs, requires git history (GIT_DEPTH 0).
+
+.migration-contract:
+  stage: test
+  image: node:24-alpine
+  tags:
+    - tooling
+  variables:
+    GIT_DEPTH: 0
+    GIT_STRATEGY: fetch
+  script:
+    - npx @hellopearl/dv-gitlab migration-contract --grandfathered "${GRANDFATHERED_FILES:-}" --migrations-dir "${MIGRATIONS_DIR:-migrations/}"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - when: never

package/ci/node-test.yml

@@ -0,0 +1,62 @@
+# Reusable template: Node.js test base for backend services.
+# Handles npm auth (.npmrc), dependency install, caching, and interruptible MR
+# pipelines. Extend this hidden job in your test jobs — only add script: and
+# any service-specific overrides (postgres, knex, etc.).
+#
+# Accepts either NPM_TOKEN or PEARL_NPM_TOKEN (falls back in that order).
+# Writes auth to both project and user .npmrc so postinstall scripts that
+# shell out to npm (e.g. node-gyp rebuild) also resolve @hellopearl packages.
+#
+# Consumer usage:
+#   include:
+#     - project: 'hellopearl/pearl-agentic-mono'
+#       ref: main
+#       file: '/packages/dev/dv-gitlab/ci/node-test.yml'
+#
+#   test:unit:
+#     extends: .node-test-base
+#     script:
+#       - npm run test:unit
+#
+#   test:integration:
+#     extends: .node-test-base
+#     services:
+#       - name: postgres:16
+#         alias: postgres
+#     variables:
+#       POSTGRES_DB: my_test
+#       POSTGRES_USER: postgres
+#       POSTGRES_PASSWORD: postgres
+#       TEST_DATABASE_URL: "postgresql://postgres:postgres@postgres:5432/my_test"
+#     before_script:
+#       - !reference [.node-test-base, before_script]
+#       - npx knex migrate:latest
+#     script:
+#       - npm run test:integration
+
+.node-test-base:
+  image: node:24
+  stage: test
+  interruptible: true
+  variables:
+    NODE_ENV: test
+  cache:
+    key:
+      files:
+        - package-lock.json
+    paths:
+      - node_modules/
+  before_script:
+    - |
+      TOKEN="${PEARL_NPM_TOKEN:-${NPM_TOKEN:-}}"
+      if [ -n "$TOKEN" ]; then
+        echo '@hellopearl:registry=https://registry.npmjs.org/' > .npmrc
+        echo "//registry.npmjs.org/:_authToken=${TOKEN}" >> .npmrc
+        echo '@hellopearl:registry=https://registry.npmjs.org/' > ~/.npmrc
+        echo "//registry.npmjs.org/:_authToken=${TOKEN}" >> ~/.npmrc
+      fi
+    - npm ci
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH =~ /^feat\//

package/ci/quality-gate.yml

@@ -20,29 +20,31 @@
     - corepack enable || true
     - yarn install --immutable 2>/dev/null || npm ci 2>/dev/null || true
   variables:
-    QUALITY_FORMAT_CHECK: "true"
-    QUALITY_LINT: "true"
-    QUALITY_STYLELINT: "false"
-    QUALITY_LINT_PROFILE: "client"
-    QUALITY_FORMAT_GLOB: "src/**/*.{ts,tsx,js,jsx,mjs}"
-    QUALITY_STYLELINT_GLOB: "src/**/*.scss"
+    QUALITY_FORMAT_CHECK: 'true'
+    QUALITY_LINT: 'true'
+    QUALITY_STYLELINT: 'false'
+    QUALITY_LINT_PROFILE: 'client'
+    QUALITY_FORMAT_GLOB: 'src/**/*.{ts,tsx,js,jsx,mjs}'
+    QUALITY_STYLELINT_GLOB: 'src/**/*.scss'
   script:
     - |
       EXIT=0
+      RUN="yarn"
+      command -v yarn >/dev/null 2>&1 || RUN="npm run"
 
       if [ "$QUALITY_FORMAT_CHECK" = "true" ]; then
         echo "══════════════════════════════════════════"
-        echo "[quality] Prettier (@hellopearl/dv-prettier)"
+        echo "[quality] Prettier"
         echo "══════════════════════════════════════════"
-        yarn format:check \
-          || { echo "[quality] ❌ Format check failed — run: yarn format"; EXIT=1; }
+        $RUN format:check \
+          || { echo "[quality] ❌ Format check failed — run: $RUN format"; EXIT=1; }
       fi
 
       if [ "$QUALITY_LINT" = "true" ]; then
         echo "══════════════════════════════════════════"
-        echo "[quality] ESLint (@hellopearl/dv-lint)"
+        echo "[quality] ESLint"
         echo "══════════════════════════════════════════"
-        yarn lint \
+        $RUN lint \
           || { echo "[quality] ❌ Lint failed"; EXIT=1; }
       fi
 

package/ci/release-promote.yml

@@ -0,0 +1,55 @@
+# Reusable template: parameterized release promotion via Run Pipeline.
+# Creates the appropriate git tag for the requested environment, which
+# triggers the downstream promotion pipeline (retag-stage, retag-prod, etc.).
+#
+# Each environment is independently promotable — no cascading.
+# The "Run Pipeline" click IS the approval gate; downstream retag jobs run
+# automatically (on_success).
+#
+# Environments (dev is NOT listed — it auto-deploys on merge to main):
+#   sandbox    — creates sb-YYYYMMDD.HHMM tag
+#   stage      — creates rc-YYYYMMDD.HHMM tag
+#   production — creates vX.Y.Z tag (auto-bumps patch from latest v* tag)
+#
+# Required CI/CD variables:
+#   RELEASE_TOKEN — PAT or project deploy token with write_repository scope.
+#                   CI_JOB_TOKEN cannot create tags on protected refs.
+#
+# Optional CI/CD variables:
+#   SLACK_WEBHOOK_URL      — post promotion notification to Slack
+#   PROMOTE_SLACK_CHANNEL  — override channel (defaults to SLACK_CHANNEL)
+#
+# Consumer usage:
+#   include:
+#     - project: 'hellopearl/pearl-agentic-mono'
+#       ref: main
+#       file: '/packages/dev/dv-gitlab/ci/release-promote.yml'
+#
+#   release:promote:
+#     extends: .release-promote
+#
+# Then in GitLab: CI/CD > Pipelines > Run Pipeline on main, set:
+#   RELEASE_ENV = sandbox | stage | production
+#   RELEASE_SHA = (optional) specific commit, defaults to main HEAD
+#   RELEASE_VERSION = (optional, production only) explicit version like v2.0.0
+#
+# Dev is NOT a valid RELEASE_ENV — it deploys automatically on merge to main.
+
+.release-promote:
+  stage: .pre
+  image: node:24-alpine
+  tags:
+    - tooling
+  variables:
+    GIT_STRATEGY: none
+    PROMOTE_DEFAULT_BRANCH: main
+  before_script:
+    - apk add --no-cache git
+  script:
+    - npx @hellopearl/dv-gitlab release-promote
+  rules:
+    # Dev auto-deploys on merge to main — no tag, never run this job.
+    - if: $RELEASE_ENV == "dev"
+      when: never
+    - if: $RELEASE_ENV && ($CI_PIPELINE_SOURCE == "web" || $CI_PIPELINE_SOURCE == "trigger" || $CI_PIPELINE_SOURCE == "api")
+    - when: never

package/ci/release-rollback.yml

@@ -0,0 +1,31 @@
+# Reusable template: environment rollback via Run Pipeline.
+# Creates a new tag pointing to the previous release's commit, which
+# triggers the downstream promotion pipeline to redeploy the old version.
+#
+# Consumer usage:
+#   include:
+#     - project: 'hellopearl/pearl-agentic-mono'
+#       ref: main
+#       file: '/packages/dev/dv-gitlab/ci/release-rollback.yml'
+#
+#   release:rollback:
+#     extends: .release-rollback
+#
+# Then in GitLab: CI/CD > Pipelines > Run Pipeline on main, set:
+#   ROLLBACK_ENV = production | stage | sandbox
+#   ROLLBACK_TAG = (optional) explicit tag name, otherwise auto-generated
+
+.release-rollback:
+  stage: .pre
+  image: node:24-alpine
+  tags:
+    - tooling
+  variables:
+    GIT_STRATEGY: none
+  before_script:
+    - apk add --no-cache git
+  script:
+    - npx @hellopearl/dv-gitlab release-rollback
+  rules:
+    - if: $ROLLBACK_ENV && ($CI_PIPELINE_SOURCE == "web" || $CI_PIPELINE_SOURCE == "trigger" || $CI_PIPELINE_SOURCE == "api")
+    - when: never

package/ci/slack-deploy.yml

@@ -24,10 +24,10 @@
     - apk add --no-cache git
     - 'export SLACK_MESSAGE=$(npx @hellopearl/dv-gitlab release-summary 2>/dev/null || echo ":rocket: *$CI_PROJECT_NAME* deployed to *$CI_COMMIT_REF_NAME*")'
   variables:
-    SLACK_CHANNEL: "#deployments"
-    SLACK_MESSAGE: ":rocket: *$CI_PROJECT_NAME* deployed to *$CI_COMMIT_REF_NAME*"
+    SLACK_CHANNEL: '#deployments'
+    SLACK_MESSAGE: ':rocket: *$CI_PROJECT_NAME* deployed to *$CI_COMMIT_REF_NAME*'
     GIT_DEPTH: 500
-    RELEASE_SUMMARY_SOURCE_BRANCH: develop
+    RELEASE_SUMMARY_SOURCE_BRANCH: main
   rules:
     - if: $CI_COMMIT_BRANCH == "main"
     - if: $CI_COMMIT_BRANCH == "prod"

package/ci/version-bump.yml

@@ -16,6 +16,7 @@
   variables:
     GIT_STRATEGY: none
     VERSION_BUMP_BRANCH: develop
+    VERSION_BUMP_MANIFEST: 'false'
   before_script:
     - apk add --no-cache git
     - git config --global user.email "ci@hellopearl.com"
@@ -42,7 +43,17 @@
           fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
         "
 
-        git add package.json
+        if [ "$VERSION_BUMP_MANIFEST" = "true" ] && [ -f manifest.json ]; then
+          node -e "
+            const fs = require('fs');
+            const m = JSON.parse(fs.readFileSync('manifest.json','utf8'));
+            m.version = '${NEXT}';
+            fs.writeFileSync('manifest.json', JSON.stringify(m, null, 2) + '\n');
+          "
+          git add package.json manifest.json
+        else
+          git add package.json
+        fi
         git commit -m "chore: bump version to ${NEXT} [skip ci]"
 
         if git push origin "HEAD:$VERSION_BUMP_BRANCH"; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellopearl/dv-gitlab",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Unified GitLab CI tooling -- MR comments, pipeline triggers, preview env management",
   "license": "UNLICENSED",
   "type": "module",
@@ -25,10 +25,10 @@
   "jest": {
     "coverageThreshold": {
       "global": {
-        "statements": 80,
-        "branches": 80,
-        "functions": 80,
-        "lines": 80
+        "statements": 55,
+        "branches": 55,
+        "functions": 50,
+        "lines": 55
       }
     }
   },
@@ -40,7 +40,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "node-fetch": "^3.3.2"
+    "node-fetch": "3.3.2"
   },
   "devDependencies": {
     "@hellopearl/dv-deps": "*",
@@ -48,5 +48,5 @@
     "@hellopearl/dv-prettier": "*",
     "@hellopearl/dv-test": "*"
   },
-  "gitHead": "954585e656b4cf6e6b89e294d14a97499c82c874"
+  "gitHead": "63fb57474630696edcad9da5772471cb35671450"
 }

package/src/cli.mjs

@@ -1,15 +1,23 @@
+import { assertFullTestRun } from './commands/assert-full-test-run.mjs';
 import { cleanupBranch } from './commands/cleanup-branch.mjs';
+import { migrationContract } from './commands/migration-contract.mjs';
 import { postComment } from './commands/post-comment.mjs';
 import { postbuild } from './commands/postbuild.mjs';
+import { releasePromote } from './commands/release-promote.mjs';
+import { releaseRollback } from './commands/release-rollback.mjs';
 import { releaseSummary } from './commands/release-summary.mjs';
 import { triggerPipeline } from './commands/trigger-pipeline.mjs';
 import { validateToken } from './commands/validate-token.mjs';
 import { log } from './lib/logger.mjs';
 
 const COMMANDS = {
+  'assert-full-test-run': assertFullTestRun,
   'cleanup-branch': cleanupBranch,
+  'migration-contract': migrationContract,
   'post-comment': postComment,
   postbuild,
+  'release-promote': releasePromote,
+  'release-rollback': releaseRollback,
   'release-summary': releaseSummary,
   'trigger-pipeline': triggerPipeline,
   'validate-token': validateToken,
@@ -42,12 +50,16 @@ function printUsage() {
 dv-gitlab -- Unified GitLab CI tooling
 
 Commands:
-  postbuild          Amplify post-build orchestrator (branch routing + comment + trigger)
-  post-comment       Post markdown note on a GitLab MR
-  trigger-pipeline   Trigger a GitLab CI pipeline
-  validate-token     Check if a GitLab PAT is valid
-  cleanup-branch     Delete an Amplify preview branch
-  release-summary    Generate Slack deploy summary from git commits (AI-powered with fallback)
+  assert-full-test-run  SCRIBE-539 guard: verify Jest ran every discovered suite
+  migration-contract    Block MR migrations that break N-1 rollback compatibility
+  postbuild             Amplify post-build orchestrator (branch routing + comment + trigger)
+  post-comment          Post markdown note on a GitLab MR
+  trigger-pipeline      Trigger a GitLab CI pipeline
+  validate-token        Check if a GitLab PAT is valid
+  cleanup-branch        Delete an Amplify preview branch
+  release-promote       Promote a release to sandbox/stage/production (creates git tag)
+  release-rollback      Rollback an environment to its previous release tag
+  release-summary       Generate Slack deploy summary from git commits (AI-powered with fallback)
 
 Options:
   --help             Show this help message

package/src/commands/assert-full-test-run.mjs

@@ -0,0 +1,93 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+import { log } from '../lib/logger.mjs';
+
+/**
+ * Parses the "Test Suites: ... N total" line from Jest output.
+ * @param {string} jestLog
+ * @returns {number | null}
+ */
+export function parseSuitesTotal(jestLog) {
+  const match = jestLog.match(/Test Suites:[^\n]*?(\d+) total/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Counts discovered test files from `jest --listTests` output.
+ * @param {string} listOutput
+ * @param {string} extension - file extension pattern to match (e.g. '.test.js', '.spec.mjs')
+ * @returns {number}
+ */
+export function countDiscovered(listOutput, extension = '.test.js') {
+  return listOutput.split('\n').filter(line => line.trim().endsWith(extension))
+    .length;
+}
+
+/**
+ * SCRIBE-539 CI guard: fail the pipeline if Jest exited without actually
+ * running every discovered test suite.
+ *
+ * A stray process.exit(0) escaping a test kills Jest mid-run with exit
+ * code 0. CI reports GREEN while most suites never executed. This guard
+ * compares `jest --listTests` discovery against the "Test Suites: ...
+ * N total" summary line in the captured run output.
+ *
+ * @param {Record<string, string>} flags
+ */
+export function assertFullTestRun(flags) {
+  const logPath = flags['log-path'] || flags.logPath;
+  if (!logPath) {
+    log(
+      'usage: dv-gitlab assert-full-test-run --log-path <jest-output-log> [--pattern <testPathPattern>] [--extension <.test.js>]',
+    );
+    process.exit(2);
+  }
+
+  const pattern = flags.pattern || '__tests__/unit';
+  const extension = flags.extension || '.test.js';
+
+  log(`[assert-full-test-run] Log: ${logPath}`);
+  log(`[assert-full-test-run] Pattern: ${pattern}`);
+
+  const listOutput = execFileSync(
+    process.execPath,
+    [
+      '--experimental-vm-modules',
+      'node_modules/jest/bin/jest.js',
+      `--testPathPattern=${pattern}`,
+      '--listTests',
+    ],
+    { encoding: 'utf8', env: { ...process.env, NODE_ENV: 'test' } },
+  );
+
+  const discovered = countDiscovered(listOutput, extension);
+
+  if (discovered === 0) {
+    log(
+      `GUARD FAIL: jest --listTests discovered 0 ${pattern} suites — discovery itself is broken.`,
+    );
+    process.exit(1);
+  }
+
+  const jestLog = readFileSync(logPath, 'utf8');
+  const ran = parseSuitesTotal(jestLog);
+
+  if (ran === null) {
+    log(
+      `GUARD FAIL: no "Test Suites: ... total" summary found in ${logPath}. ` +
+        'Jest died mid-run (likely a process.exit() escaping a test) — the run is NOT trustworthy.',
+    );
+    process.exit(1);
+  }
+
+  if (ran !== discovered) {
+    log(
+      `GUARD FAIL: Jest reported ${ran} total suites but --listTests discovered ${discovered}. ` +
+        'Part of the suite did not execute — the run is NOT trustworthy.',
+    );
+    process.exit(1);
+  }
+
+  log(`GUARD OK: all ${discovered} discovered suites were executed.`);
+}