@freshworks/shiftleft-tools 1.1.8

package/src/utils/template.js

@@ -0,0 +1,135 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import ejs from 'ejs';
+import { fileState, recordFile, manifestKey } from './manifest.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const TEMPLATES_DIR = join(__dirname, '../../templates');
+
+/**
+ * Get the path to a template file
+ */
+export function getTemplatePath(relativePath) {
+    return join(TEMPLATES_DIR, relativePath);
+}
+
+/**
+ * Read and render a template with the given context
+ */
+export function renderTemplate(templatePath, context = {}) {
+    const fullPath = getTemplatePath(templatePath);
+    const template = readFileSync(fullPath, 'utf8');
+    return ejs.render(template, context);
+}
+
+/**
+ * Resolve a template's final content (rendered if EJS, raw otherwise).
+ */
+export function templateContent(templatePath, context = {}, render = false) {
+    return render
+        ? renderTemplate(templatePath, context)
+        : readFileSync(getTemplatePath(templatePath), 'utf8');
+}
+
+function writeFile(destPath, content) {
+    const destDir = dirname(destPath);
+    if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
+    }
+    writeFileSync(destPath, content, 'utf8');
+}
+
+/**
+ * Copy a template to destination, optionally rendering EJS.
+ * "Create" semantics: skips an existing file unless `force`.
+ * Returns the resolved content so callers can record it in a manifest.
+ */
+export function copyTemplate(templatePath, destPath, context = {}, options = {}) {
+    const { render = false, force = false } = options;
+    const content = templateContent(templatePath, context, render);
+
+    if (existsSync(destPath) && !force) {
+        return { skipped: true, path: destPath, content };
+    }
+
+    writeFile(destPath, content);
+    return { skipped: false, path: destPath, content };
+}
+
+/**
+ * Manifest-aware write. Branches on the three-way file state instead of
+ * blindly overwriting, so a locally-edited file is never silently clobbered.
+ *
+ * Returns { status, path, content } where status is one of:
+ *   'written'  – file (re)written to match the template
+ *   'created'  – file did not exist and was created
+ *   'uptodate' – already matches the template, left as-is
+ *   'skipped'  – scaffold file the repo owns, left as-is
+ *   'conflict' – local edits diverged; wrote `${dest}.shiftleft-new` instead
+ */
+export function syncTemplate(templatePath, destPath, context = {}, options = {}) {
+    const { render = false, force = false, manifest, cwd, source, scaffold = false, adopt = false } = options;
+    const content = templateContent(templatePath, context, render);
+
+    // Adopt-on-first-run: if we have no record of this file but it exists on
+    // disk, seed the baseline from the current disk content. An out-of-date
+    // file then reads as 'clean' and updates cleanly instead of 'local-edit'.
+    if (adopt) {
+        const key = manifestKey(cwd, destPath);
+        if (!manifest.managed[key] && existsSync(destPath)) {
+            recordFile(manifest, cwd, destPath, readFileSync(destPath, 'utf8'), {
+                source: 'adopted',
+                scaffold,
+                template: templatePath,
+            });
+        }
+    }
+
+    const state = fileState(cwd, destPath, manifest, content);
+
+    // Scaffold files are repo-owned: only create when missing, never overwrite
+    // (unless an explicit --force is given).
+    if (scaffold && !force && (state === 'clean' || state === 'local-edit' || state === 'uptodate')) {
+        if (state === 'uptodate') recordFile(manifest, cwd, destPath, content, { source, scaffold, template: templatePath });
+        return { status: state === 'uptodate' ? 'uptodate' : 'skipped', path: destPath, content };
+    }
+
+    switch (state) {
+        case 'uptodate':
+            recordFile(manifest, cwd, destPath, content, { source, scaffold, template: templatePath });
+            return { status: 'uptodate', path: destPath, content };
+
+        case 'new':
+        case 'missing':
+            writeFile(destPath, content);
+            recordFile(manifest, cwd, destPath, content, { source, scaffold, template: templatePath });
+            return { status: state === 'new' ? 'created' : 'written', path: destPath, content };
+
+        case 'clean':
+            writeFile(destPath, content);
+            recordFile(manifest, cwd, destPath, content, { source, scaffold, template: templatePath });
+            return { status: 'written', path: destPath, content };
+
+        case 'local-edit':
+        default:
+            if (force) {
+                writeFile(destPath, content);
+                recordFile(manifest, cwd, destPath, content, { source, scaffold, template: templatePath });
+                return { status: 'written', path: destPath, content };
+            }
+            writeFile(`${destPath}.shiftleft-new`, content);
+            return { status: 'conflict', path: destPath, content };
+    }
+}
+
+/**
+ * Ensure a directory exists
+ */
+export function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+}

package/templates/AGENTS.md

@@ -0,0 +1,109 @@
+# Agent Instructions — Freshworks Test Pipeline Dev Tools
+
+This file is the agent entry point for AI assistants (Claude Code, Cursor, Codex) working in a Freshworks platform service repo. It routes to the right skill based on what needs to be done.
+
+## How to use skills
+
+When the user invokes `/skill-name`:
+1. Read `.claude/skills/<skill-name>/SKILL.md` (Claude Code) or `.cursor/skills/<skill-name>/SKILL.md` (Cursor)
+2. Follow the instructions in that file completely — skills are step-by-step agent workflows, not static templates
+3. Skills inspect the repo first, reason about what's needed, confirm with the user, then execute
+
+**Never copy-paste from templates without first reading the actual repo structure.** Every project has unique package names, module layouts, port numbers, and test patterns.
+
+---
+
+## Which skill to use
+
+| Goal | Skill | Notes |
+|---|---|---|
+| New repo — set up everything from scratch | `/setup-test-pipeline` | Covers unit tests, JaCoCo/nyc, mutation, Postman, API coverage, quality report, Jenkins |
+| Existing repo — find and fill gaps | `/enhance-test-pipeline` | Audits what's present, adds only what's missing, checks security guardrails |
+| Add mutation tests only | `/setup-mutation-tests` | PIT for Java, Stryker for Node — discovers actual package scope before configuring |
+| Set up Postman/Newman infrastructure | `/setup-api-tests` | Collections, environments, scripts (Java: WireMock; Node: nock) |
+| Write tests for specific endpoints | `/write-api-tests [METHOD /path]` | e.g. `/write-api-tests POST /api/v3/installations` |
+| Run tests | `/run-test-suite` | Knows all `run-all.sh` flags, CI stage-by-stage patterns |
+| Review test quality | `/review-test-suite` | 20-point maturity check |
+
+---
+
+## Auto-detect: no skill specified
+
+If the user asks to "set up tests", "improve the pipeline", or similar without specifying a skill, inspect the repo first and decide:
+
+```bash
+# Is this Java or Node?
+ls pom.xml 2>/dev/null && echo "Java" || echo "Node"
+
+# What pipeline pieces already exist?
+ls postman/scripts/run-all.sh 2>/dev/null && echo "run-all.sh present"
+grep -l "pitest-maven" pom.xml 2>/dev/null && echo "PIT present"           # Java
+grep '"mutation-tests"' package.json 2>/dev/null && echo "Stryker present"  # Node
+ls postman/scripts/report-generators/java-api-coverage-matrix.sh 2>/dev/null && echo "Java API coverage present"
+ls postman/scripts/report-generators/node-api-coverage-matrix.sh 2>/dev/null && echo "Node API coverage present"
+ls postman/reports/ 2>/dev/null && echo "Reports present"
+grep -l "Quality Report\|generateQualityReport" Jenkinsfile 2>/dev/null && echo "Jenkins quality report present"
+```
+
+- **Nothing exists** → use `/setup-test-pipeline`
+- **Some things exist** → use `/enhance-test-pipeline`
+- **Specific component missing** → use the targeted skill
+
+---
+
+## Non-negotiables (always enforce, regardless of skill)
+
+These apply to every repo this tooling touches. If any of these are violated, fix them as part of the work — do not skip even if the user didn't ask.
+
+### Node security guardrails
+
+**`.npmrc` must exist** in the `postman/` directory with:
+```ini
+ignore-scripts=true        # blocks postinstall supply chain attacks
+audit-level=high
+audit-signatures=true      # verifies package signing (npm 8.4+)
+strict-ssl=true
+registry=https://registry.npmjs.org/
+```
+
+**`package-lock.json` must exist** — never `npm install` without a lockfile. In CI always use `npm ci --ignore-scripts`, never `npm install`.
+
+**Secrets must never reach npm packages:**
+- AWS credentials: fetch secret → generate JWT → `unset` the secret variable immediately before running Newman
+- `GH_TOKEN` / `GITHUB_RUNWAYCI_TOKEN`: only inside `withCredentials` blocks, never in `environment {}` block
+- Never pass secrets as environment variables to `npm run` commands
+
+**npm audit in Jenkins:** Every ShiftLeft / staging test run must include:
+```bash
+npm ci --ignore-scripts
+npm audit --audit-level=critical 2>&1 || echo "WARNING: audit found issues"
+npm audit signatures 2>&1 || echo "WARNING: signature verification failed"
+npm audit --json > ../audit-report.json 2>&1 || true
+archiveArtifacts artifacts: 'audit-report.json', allowEmptyArchive: true
+```
+
+### Java security guardrails
+
+- Never commit secrets or credentials in `pom.xml` or `application.properties`
+- `application-test.properties` / `application-integration.properties`: H2 only, never real DB credentials
+- PIT mutation tests must be in a `<profile>` — never in the main build (prevents accidental slow runs)
+
+### Jenkins guardrails (both Java and Node)
+
+- IRSA (pod IAM role) for AWS — never static `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in Jenkins env
+- `withCredentials` scope: credentials exposed only for the specific `sh` block that needs them, not the whole stage
+- `deleteDir()` in `post { always }` — clean workspace after every build
+
+---
+
+## Reference implementations
+
+These repos are the canonical examples of a fully set-up pipeline:
+
+| Repo | Type | What it demonstrates |
+|---|---|---|
+| `mp-installation` | Java/Spring Boot | PIT mutation, JaCoCo, multi-product Postman, API coverage matrix, quality report, Jenkins ShiftLeft |
+| `freshapps_api_node` | Node/Express | Stryker since/full modes, nyc coverage, Newman staging, node-api-coverage-matrix, quality report |
+| `dp-apps` | Java/Spring Boot | Same as mp-installation — the original reference |
+
+When a skill needs a concrete example of a script, config, or Jenkinsfile stage, refer to these repos.

package/templates/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project AI Instructions
+
+See [AGENTS.md](AGENTS.md) for full instructions — skill routing, auto-detection, security guardrails, and reference implementations.

package/templates/jenkins/Jenkinsfile-java.groovy

@@ -0,0 +1,432 @@
+pipeline {
+    agent {
+        kubernetes {
+            yaml k8sPodTemplate(pod: 'jnlp+java11+dind')
+            defaultContainer 'java-base'
+        }
+    }
+
+    // Artifacts will be retained 10 days or 10 builds
+    options {
+        buildDiscarder(logRotator(numToKeepStr: '10', artifactNumToKeepStr: '20'))
+        disableConcurrentBuilds()
+    }
+
+    parameters {
+        choice(choices: 'dev\nstaging\nproduction', description: '', name: 'deployTo')
+        string(name: 'image_version', defaultValue: '', description: 'Image version for Staging/Production deployment [Recommended]')
+        booleanParam(defaultValue: false, description: 'Selecting this option will only deploy the image and will not run any of the other stages', name: 'deployOnly')
+    }
+
+    stages {
+        stage('Unit tests') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                script {
+                    sh """
+                        mvn clean install
+                    """
+                }
+            }
+        }
+
+        stage('Mutation Tests') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                script {
+                    runMutationTests()
+                }
+            }
+            post {
+                always {
+                    // Publish the PIT mutation report every build, regardless of the
+                    // shiftleft-gated report stage. Requires <timestampedReports>false</timestampedReports>
+                    // in the pitest config so the HTML lands at target/pit-reports.
+                    publishHTML([
+                        allowMissing: true,
+                        alwaysLinkToLastBuild: true,
+                        keepAll: true,
+                        reportDir: 'target/pit-reports',
+                        reportFiles: 'index.html',
+                        reportName: 'Mutation Report (PIT)'
+                    ])
+                    archiveArtifacts artifacts: 'target/pit-reports/**', allowEmptyArchive: true
+                }
+            }
+        }
+
+        stage('SonarQube Analysis') {
+            when {
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                runJavaSonarQubeAnalysis()
+            }
+        }
+
+        stage('Shift Left Integration Test - Isolation') {
+            when {
+                expression {
+                    params.deployTo == 'dev'
+                }
+            }
+            steps {
+                script {
+                    runShiftLeftIntegration()
+                }
+            }
+        }
+
+        stage('Build Image') {
+            when {
+                branch 'main'
+                expression {
+                    params.deployTo == 'dev' && params.image_version == ''
+                }
+            }
+            steps {
+                buildJavaProject()
+            }
+        }
+
+        stage('Promote Image') {
+            when {
+                expression {
+                    params.deployTo == 'production' && !params.deployOnly
+                }
+            }
+            steps {
+                promoteJavaImage(params.image_version)
+            }
+        }
+
+        stage('Security scan') {
+            when {
+                branch 'main'
+                expression {
+                    params.deployTo == 'dev' && !params.deployOnly
+                }
+            }
+            steps {
+                runSecurityTests('SERVICE_NAME')
+            }
+        }
+
+        stage('Deploy Image') {
+            when {
+                branch 'main'
+            }
+            steps {
+                deployArgo(params.deployTo, 'SERVICE_NAME', params.image_version)
+            }
+        }
+    }
+    post {
+        always {
+            script {
+                deleteDir()
+            }
+        }
+    }
+}
+
+def runShiftLeftIntegration() {
+    ensureShiftleftCli()
+    utilObj = new Utils()
+    def buildCause = ''
+    def latest_argo_sha = ''
+    def latest_stable_version = ''
+    def lsr_stage_result = ''
+
+    // Extract comment body safely without storing non-serializable object
+    try {
+        def causes = currentBuild.rawBuild.getCauses()
+        if (causes && causes.size() > 0) {
+            def cause = causes[0]
+            if (cause?.class?.toString()?.contains('GitHubPullRequestCommentCause')) {
+                buildCause = cause.getCommentBody() ?: ''
+            }
+            cause = null  // Clear the non-serializable reference immediately
+        }
+    } catch (Exception e) {
+        echo "Could not get build cause: ${e.message}"
+    }
+
+    echo "Build Cause = ${buildCause}"
+    if (!buildCause.trim().toLowerCase().startsWith('shiftleft')) {
+        echo 'Branch build with no intention of shift left integration test.'
+        return
+    }
+
+    lock(resource: 'SERVICE_NAME-shiftleft-postman') {
+        def sl = shiftleftBuildLabels()
+        def branch_name_setup = "${sl.gitBranchBase}/SERVICE_NAME-apFeatureStack"
+        def branch_name_teardown = "${sl.gitBranchBase.replace('iso-setup-', 'iso-teardown-')}/SERVICE_NAME-apFeatureStack"
+
+        buildJavaProject(sl.imageTag)
+        def serviceName = utilObj.getK8ServiceName(utilObj.getRepoName())
+
+        echo "serviceName = ${serviceName}"
+
+        // SECURITY: GH_TOKEN only exposed to git/gh commands, not to npm packages
+        withCredentials([string(credentialsId: 'GITHUB_RUNWAYCI_TOKEN', variable: 'GH_TOKEN')]) {
+            sh """#!/bin/bash --login
+                git clone git@github.com:freshdesk/freshapps-k8s.git
+                cd freshapps-k8s
+                ls -la
+                isoforge version
+                git checkout -b ${branch_name_setup}
+
+                isoforge setup \
+                    --service SERVICE_NAME \
+                    --namespace shiftleft_feature_stack \
+                    --imageTag ${sl.imageTag} \
+                    --header ISO_HEADER \
+                    --headerValue 'ISO_HEADER_VALUE' \
+                    --accountHeader 'SERVICE_NAME-iso-account-id' \
+                    --accountIdValue 'ACCOUNT_ID_VALUE'
+
+                if [[ -n "\$(git status --porcelain)" ]]; then
+                    git add .
+                    git commit -m "Added changes for SERVICE_NAME in apFeatureStack"
+                    git push origin ${branch_name_setup}
+                else
+                    echo "No changes to commit, check previous steps"
+                    exit 1
+                fi
+
+                gh pr create \
+                    --title "Isolation-${BUILD_NUMBER} Changes for SERVICE_NAME in apFeatureStack" \
+                    --body "This PR includes changes for SERVICE_NAME in apFeatureStack" \
+                    --base main \
+                    --head ${branch_name_setup}
+
+                echo "PR created successfully"
+
+                gh pr merge ${branch_name_setup} \
+                    --squash \
+                    --admin
+
+                git checkout main
+                git pull origin main
+            """
+
+            // get the latest sha for SERVICE_NAME in apFeatureStack
+            latest_argo_sha = sh(returnStdout: true, script:'''
+                cd freshapps-k8s && git rev-parse HEAD
+            ''').trim()
+        }
+        echo "Latest SHA for SERVICE_NAME in apFeatureStack = ${latest_argo_sha}"
+
+        // wait for deployment to complete
+        withCredentials([string(credentialsId: 'ARGO_API_TOKEN', variable: 'ARGO_API_TOKEN')]) {
+            sh """
+                argoapi application --revision ${latest_argo_sha} --service SERVICE_NAME --namespace NAMESPACE
+            """
+        }
+
+        // run the integration tests
+        // NOTE: AWS credentials are automatically available via the Kubernetes pod's IAM role (IRSA)
+        updateShiftLeftStatus('pending')
+        try {
+            sh """#!/bin/bash --login
+                echo 'Running npm security audit...'
+                cd postman
+
+                # Install dependencies securely
+                if [ -f "package-lock.json" ]; then
+                    npm ci --ignore-scripts
+                else
+                    npm install --ignore-scripts
+                fi
+
+                # Run npm audit
+                echo "=== npm audit ==="
+                npm audit --audit-level=critical 2>&1 || {
+                    AUDIT_EXIT_CODE=\$?
+                    echo ""
+                    echo "Warning: Security vulnerabilities detected (exit code: \$AUDIT_EXIT_CODE)"
+                    echo "Continuing with tests..."
+                }
+
+                # Verify package signatures
+                npm audit signatures 2>&1 || echo "Warning: Signature verification not available"
+
+                # Save audit report
+                npm audit --json > ../audit-report.json 2>&1 || true
+
+                echo 'Running integration tests'
+                cd scripts
+                AWS_PROFILE=staging ./run-tests-staging.sh
+            """
+            echo "Integration tests completed"
+            updateShiftLeftStatus('success', '/QualityReport/')
+        } catch (Exception e) {
+            updateShiftLeftStatus('failure', '/QualityReport/')
+            echo "Integration tests failed: ${e.getMessage()}"
+            currentBuild.result = 'UNSTABLE'
+        }
+
+        // Archive audit report
+        if (fileExists('audit-report.json')) {
+            archiveArtifacts artifacts: 'audit-report.json', allowEmptyArchive: true
+        }
+
+        // Publish Postman staging report
+        if (fileExists('postman/reports')) {
+            publishHTML([
+                allowMissing: false,
+                alwaysLinkToLastBuild: true,
+                keepAll: true,
+                reportDir: 'postman/reports',
+                reportFiles: 'consolidated-staging-*.html',
+                includes: '**/*',
+                reportName: 'PostmanTestReport-ShiftLeft',
+                reportTitles: 'ShiftLeft Integration Tests'
+            ])
+        } else {
+            echo 'postman/reports folder does not exist, skipping HTML report publication'
+        }
+
+        // Generate API Coverage Matrix
+        echo "Generating API Coverage Matrix..."
+        try {
+            sh """#!/bin/bash --login
+                cd postman/scripts
+                ./run-all.sh --skip-unit --skip-mutation --skip-postman --skip-report --no-delay
+            """
+        } catch (Exception e) {
+            echo "API Coverage generation failed: ${e.getMessage()}"
+            currentBuild.result = 'UNSTABLE'
+        }
+
+        // Generate Combined Quality Report
+        echo "Generating Combined Quality Report..."
+        try {
+            sh """#!/bin/bash --login
+                cd postman/scripts
+                ./stage-report-artifacts.sh "\${WORKSPACE}" "\${WORKSPACE}/postman/reports" || true
+                ./run-all.sh --skip-unit --skip-mutation --skip-postman --skip-coverage --no-delay
+            """
+        } catch (Exception e) {
+            echo "Quality report generation failed: ${e.getMessage()}"
+            currentBuild.result = 'UNSTABLE'
+        }
+
+        // Publish Combined Quality Report
+        if (fileExists('postman/reports')) {
+            def qualityReport = sh(
+                returnStdout: true,
+                script: "ls -t postman/reports/quality-report-*.html 2>/dev/null | head -1 | xargs -r basename"
+            ).trim()
+            if (qualityReport) {
+                publishHTML([
+                    allowMissing: true,
+                    alwaysLinkToLastBuild: true,
+                    keepAll: true,
+                    reportDir: 'postman/reports',
+                    reportFiles: qualityReport,
+                    includes: '**/*',
+                    reportName: 'QualityReport',
+                    reportTitles: 'Combined Quality Report'
+                ])
+            }
+            archiveArtifacts artifacts: 'postman/reports/**', allowEmptyArchive: true
+        }
+
+        // teardown the isolation stack
+        withCredentials([string(credentialsId: 'GITHUB_RUNWAYCI_TOKEN', variable: 'GH_TOKEN')]) {
+            sh """#!/bin/bash --login
+                cd freshapps-k8s
+                git pull origin main
+                git checkout -b ${branch_name_teardown}
+
+                isoforge teardown \
+                    --service SERVICE_NAME \
+                    --namespace shiftleft_feature_stack
+
+                if [[ -n "\$(git status --porcelain)" ]]; then
+                    git add .
+                    git commit -m "Added changes for SERVICE_NAME in apFeatureStack"
+                    git push origin ${branch_name_teardown}
+                else
+                    echo "No changes to commit, check previous steps"
+                    exit 1
+                fi
+
+                gh pr create \
+                    --title "Isolation-Teardown-${BUILD_NUMBER} Changes for SERVICE_NAME in apFeatureStack" \
+                    --body "This PR includes teardown changes for SERVICE_NAME in apFeatureStack" \
+                    --base main \
+                    --head ${branch_name_teardown}
+
+                echo "PR created successfully"
+
+                gh pr merge ${branch_name_teardown} \
+                    --squash \
+                    --admin
+            """
+        }
+
+        // argo sync to complete the teardown
+        withCredentials([string(credentialsId: 'ARGO_API_TOKEN', variable: 'ARGO_API_TOKEN')]) {
+            sh """
+                argoapi sync
+            """
+        }
+    }
+}
+
+def updateShiftLeftStatus(String state, String targetUrlPath = '') {
+    withCredentials([string(credentialsId: 'GITHUB_RUNWAYCI_TOKEN', variable: 'GITHUB_RUNWAYCI_TOKEN')]) {
+        def targetUrl = targetUrlPath ? "${env.BUILD_URL}${targetUrlPath}" : "${env.BUILD_URL}"
+        sh """#!/bin/bash --login
+            octocat status --context shiftleft-SERVICE_NAME-postman --description "ShiftLeft SERVICE_NAME Postman" --state ${state} --target_url "${targetUrl}"
+            octocat label --label shifted-left
+        """
+    }
+}
+
+// Ensure the shiftleft CLI is installed. run-all.sh execs `shiftleft test`,
+// which stages the library scripts from the package — so CI agents need the CLI.
+// Idempotent (skips if already present). Requires a Jenkins "Secret text"
+// credential (id below) holding the Nexus npm basic-auth token, i.e. the value
+// for  //nexuscentral.runwayci.com/repository/npm-group/:_auth=  (base64 of user:pass).
+def ensureShiftleftCli() {
+    withCredentials([string(credentialsId: 'nexus-npm-auth', variable: 'NEXUS_NPM_AUTH')]) {
+        sh '''#!/bin/bash --login
+            set -e
+            if ! command -v shiftleft >/dev/null 2>&1; then
+                echo "//nexuscentral.runwayci.com/repository/npm-group/:_auth=${NEXUS_NPM_AUTH}" >> "$HOME/.npmrc"
+                npm install -g shiftleft-tools \
+                    --registry=https://nexuscentral.runwayci.com/repository/npm-group/ --prefer-online
+            fi
+        '''
+    }
+}
+
+def runMutationTests() {
+    ensureShiftleftCli()
+    echo "Running PIT Mutation Tests..."
+    try {
+        sh """#!/bin/bash --login
+            cd postman/scripts
+
+            # Run only mutation tests (Phase 2: PIT), reusing unit test output from Unit Tests stage
+            ./run-all.sh --skip-unit --skip-postman --skip-coverage --skip-report --no-delay
+        """
+    } catch (Exception e) {
+        echo "Mutation tests failed: ${e.getMessage()}"
+        throw e
+    }
+}