@freshworks/shiftleft-tools 1.1.12 → 1.1.14

package/README.md

@@ -94,7 +94,7 @@ shiftleft init-rules
 ```
 
 Options:
-- `--force, -f` - Overwrite existing `CLAUDE.md` / `AGENTS.md`
+- `--force, -f` - Overwrite existing managed files
 - `--skip-skills` - Link rules only, not Cursor skills
 - `--stack <java|node>` - Project stack (auto-detected from `pom.xml` or `package.json`)
 - `--copy` - Copy assets instead of symlinking (locked-down environments / Windows without symlink permission)
@@ -106,11 +106,12 @@ This creates:
 │   ├── testing.mdc           -> (symlink) package rule for your stack
 │   └── local-test-setup.mdc  -> (symlink) Java only
 └── skills/                   -> (symlink) package skills directory
-CLAUDE.md                     # Skill invocation instructions for Claude Code (real file)
-AGENTS.md                     # Agent routing and guardrails (real file)
 .gitignore                    # symlink paths added here (not committed)
 ```
 
+Skill routing and security guardrails live in the skills themselves
+(`skills/_shared/guardrails.md`) — no per-repo `CLAUDE.md` / `AGENTS.md` is written.
+
 > Migrating from an older version? A committed `.claude/skills/` directory is no
 > longer needed — install the plugin and delete it. `shiftleft doctor` flags it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freshworks/shiftleft-tools",
-  "version": "1.1.12",
+  "version": "1.1.14",
   "description": "CLI for managing Cursor rules/skills and Postman test infrastructure across Java Spring Boot and Node.js/Express projects",
   "type": "module",
   "main": "src/index.js",

package/src/commands/init-rules.js

@@ -1,17 +1,16 @@
-import { join } from 'path';
-import { copyTemplate } from '../utils/template.js';
 import { detectStack } from '../utils/stack.js';
-import { loadManifest, createManifest, saveManifest, recordFile } from '../utils/manifest.js';
+import { loadManifest, createManifest, saveManifest } from '../utils/manifest.js';
 import { linkAssets } from './link.js';
 import { logger } from '../utils/logger.js';
 
 /**
- * Initialize Cursor rules/skills and the agent guide files in the project.
+ * Initialize Cursor rules/skills in the project.
  *
  * Cursor skills and rules are linked to the installed shiftleft-tools package
  * (symlinks, gitignored) so they update with a single global install. Claude
  * Code skills are provided by the shiftleft-tools plugin, not copied per repo.
- * CLAUDE.md / AGENTS.md remain real, manifest-managed files.
+ * No CLAUDE.md / AGENTS.md are written — skill routing and security guardrails
+ * live in the skills themselves (see skills/_shared/guardrails.md).
  */
 export async function initRules(options) {
     const cwd = process.cwd();
@@ -34,9 +33,6 @@ export async function initRules(options) {
             logger.success(`Copied ${copied.length} Cursor asset(s) (symlinks unavailable)`);
         }
 
-        copyClaude(cwd, options, manifest);
-        copyAgents(cwd, options, manifest);
-
         saveManifest(cwd, manifest);
 
         console.log();
@@ -49,30 +45,3 @@ export async function initRules(options) {
     }
 }
 
-/** Record a copyTemplate result in the manifest when it actually wrote a file. */
-function record(manifest, cwd, templatePath, result) {
-    if (result && !result.skipped) {
-        recordFile(manifest, cwd, result.path, result.content, { template: templatePath });
-    }
-    return result;
-}
-
-function copyClaude(cwd, options, manifest) {
-    const claudeMdDest = join(cwd, 'CLAUDE.md');
-    const result = record(manifest, cwd, 'CLAUDE.md', copyTemplate('CLAUDE.md', claudeMdDest, {}, { force: options.force }));
-    if (result.skipped) {
-        logger.skip('Skipped CLAUDE.md (already exists, use --force to overwrite)');
-    } else {
-        logger.success('Created CLAUDE.md');
-    }
-}
-
-function copyAgents(cwd, options, manifest) {
-    const agentsMdDest = join(cwd, 'AGENTS.md');
-    const result = record(manifest, cwd, 'AGENTS.md', copyTemplate('AGENTS.md', agentsMdDest, {}, { force: options.force }));
-    if (result.skipped) {
-        logger.skip('Skipped AGENTS.md (already exists, use --force to overwrite)');
-    } else {
-        logger.success('Created AGENTS.md');
-    }
-}

package/src/commands/update.js

@@ -67,7 +67,7 @@ export async function update(options) {
     const totals = { copied: 0, skipped: 0, conflicts: 0 };
 
     if (updateRules) {
-        accumulate(totals, await updateRulesFiles(cwd, manifest, options.force, adopt));
+        accumulate(totals, await updateRulesFiles(cwd, manifest));
     }
 
     if (updateSkills) {
@@ -105,7 +105,7 @@ function tally(result, status) {
     else result.copied++;
 }
 
-async function updateRulesFiles(cwd, manifest, force, adopt) {
+async function updateRulesFiles(cwd, manifest) {
     const spinner = ora('Updating rules...').start();
     const result = { copied: 0, skipped: 0, conflicts: 0 };
 
@@ -121,14 +121,7 @@ async function updateRulesFiles(cwd, manifest, force, adopt) {
     result.skipped += linked.length;
     result.copied += copied.length;
 
-    // CLAUDE.md and AGENTS.md remain real, manifest-managed files.
-    const claudeMdDest = join(cwd, 'CLAUDE.md');
-    if (existsSync(claudeMdDest)) {
-        tally(result, syncTemplate('CLAUDE.md', claudeMdDest, {}, { manifest, cwd, force, adopt }).status);
-    }
-    tally(result, syncTemplate('AGENTS.md', join(cwd, 'AGENTS.md'), {}, { manifest, cwd, force, adopt }).status);
-
-    spinner.succeed(`Rules: ${linked.length} linked, ${copied.length} copied, CLAUDE/AGENTS ${result.conflicts ? `${result.conflicts} conflict(s)` : 'in sync'}`);
+    spinner.succeed(`Rules: ${linked.length} linked, ${copied.length} copied`);
     return result;
 }
 

package/templates/postman/scripts/run-all.sh

@@ -400,11 +400,17 @@ fi
 # links to a stale consolidated report whose per-collection detail files have
 # already been cleaned up. Only fall back to the newest existing one if this
 # run produced no consolidated JSON to render.
-POSTMAN_CONSOLIDATED_HTML="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${TIMESTAMP}.html"
-CONSOLIDATED_JSON_THIS_RUN="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${TIMESTAMP}.json"
-if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ] && [ -f "$CONSOLIDATED_JSON_THIS_RUN" ]; then
-    echo -e "${YELLOW}Generating consolidated HTML report...${NC}"
-    "$SCRIPT_DIR/report-generators/generate-consolidated-report.sh" "$POSTMAN_ENV" "$TIMESTAMP" "$REPORTS_DIR" "$POSTMAN_PASSED" "$POSTMAN_FAILED" 0 >/dev/null 2>&1 || true
+# The Postman runner self-timestamps its artifacts, so the consolidated JSON's
+# timestamp differs from this orchestrator's $TIMESTAMP. Derive the HTML name
+# from the actual consolidated JSON (resolved above) rather than $TIMESTAMP.
+POSTMAN_CONSOLIDATED_HTML=""
+if [ -n "$CONSOLIDATED_JSON" ] && [ -f "$CONSOLIDATED_JSON" ]; then
+    CONSOLIDATED_TS=$(basename "$CONSOLIDATED_JSON" .json | sed "s/^consolidated-${POSTMAN_ENV}-//")
+    POSTMAN_CONSOLIDATED_HTML="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${CONSOLIDATED_TS}.html"
+    if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ]; then
+        echo -e "${YELLOW}Generating consolidated HTML report...${NC}"
+        "$SCRIPT_DIR/report-generators/generate-consolidated-report.sh" "$POSTMAN_ENV" "$CONSOLIDATED_TS" "$REPORTS_DIR" "$POSTMAN_PASSED" "$POSTMAN_FAILED" 0 >/dev/null 2>&1 || true
+    fi
 fi
 if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ]; then
     POSTMAN_CONSOLIDATED_HTML=$(ls -t "$REPORTS_DIR"/consolidated-*.html 2>/dev/null | head -1 || true)

package/templates/postman-node/scripts/run-all.sh

@@ -276,10 +276,16 @@ if [ "$SKIP_REPORT" = false ]; then
     # combined report never links to a stale consolidated whose per-collection
     # detail files have been cleaned up. Fall back to the newest only if this run
     # produced no consolidated JSON to render.
-    POSTMAN_CONSOLIDATED_HTML="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${TIMESTAMP}.html"
-    CONSOLIDATED_JSON_THIS_RUN="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${TIMESTAMP}.json"
-    if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ] && [ -f "$CONSOLIDATED_JSON_THIS_RUN" ]; then
-        "$SCRIPT_DIR/report-generators/generate-consolidated-report.sh" "$POSTMAN_ENV" "$TIMESTAMP" "$REPORTS_DIR" "$POSTMAN_PASSED" "$POSTMAN_FAILED" 0 >/dev/null 2>&1 || true
+    # The Postman runner self-timestamps, so the consolidated JSON's timestamp
+    # differs from this orchestrator's $TIMESTAMP. Derive the HTML name from the
+    # actual consolidated JSON rather than $TIMESTAMP.
+    POSTMAN_CONSOLIDATED_HTML=""
+    if [ -n "$CONSOLIDATED_JSON" ] && [ -f "$CONSOLIDATED_JSON" ]; then
+        CONSOLIDATED_TS=$(basename "$CONSOLIDATED_JSON" .json | sed "s/^consolidated-${POSTMAN_ENV}-//")
+        POSTMAN_CONSOLIDATED_HTML="$REPORTS_DIR/consolidated-${POSTMAN_ENV}-${CONSOLIDATED_TS}.html"
+        if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ]; then
+            "$SCRIPT_DIR/report-generators/generate-consolidated-report.sh" "$POSTMAN_ENV" "$CONSOLIDATED_TS" "$REPORTS_DIR" "$POSTMAN_PASSED" "$POSTMAN_FAILED" 0 >/dev/null 2>&1 || true
+        fi
     fi
     if [ ! -f "$POSTMAN_CONSOLIDATED_HTML" ]; then
         POSTMAN_CONSOLIDATED_HTML=$(ls -t "$REPORTS_DIR"/consolidated-*.html 2>/dev/null | head -1 || true)

package/templates/skills/_shared/guardrails.md

@@ -0,0 +1,44 @@
+# Security Guardrails — Non-negotiables
+
+These apply to every repo this tooling touches. Enforce them regardless of which
+skill is running and regardless of whether the user asked. If any are violated,
+fix them as part of the work.
+
+## 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

package/templates/skills/enhance-test-pipeline/SKILL-java.md

@@ -2,6 +2,8 @@
 
 Detect gaps and fill them in a Java/Spring Boot repo that ALREADY HAS some test pipeline pieces but not all. The key difference from `/setup-test-pipeline` is being careful NOT to overwrite existing configs that are working correctly.
 
+> **Security guardrails (non-negotiable):** audit against `../_shared/guardrails.md` (Node/Java/Jenkins) and fix any violations as part of this skill, regardless of what was asked.
+
 ## When to Use
 
 Invoke when:

package/templates/skills/enhance-test-pipeline/SKILL-node.md

@@ -2,6 +2,8 @@
 
 Detect gaps and fill them in a Node.js/Express repo that ALREADY HAS some test pipeline pieces but not all. The key difference from `/setup-test-pipeline` is being careful NOT to overwrite existing configs that are working correctly.
 
+> **Security guardrails (non-negotiable):** audit against `../_shared/guardrails.md` (Node/Java/Jenkins) and fix any violations as part of this skill, regardless of what was asked.
+
 ## When to Use
 
 Invoke when:

package/templates/skills/setup-test-pipeline/SKILL-java.md

@@ -4,6 +4,8 @@ Set up a complete test pipeline from scratch (or near-scratch) for a Java/Spring
 
 Use this skill when a repo has NOTHING (or only bare unit tests). For repos that already have partial pipeline setup, use `/enhance-test-pipeline` instead.
 
+> **Security guardrails (non-negotiable):** enforce everything in `../_shared/guardrails.md` (Node/Java/Jenkins) as part of this skill, regardless of what was asked.
+
 ## When to Use
 
 Invoke when:

package/templates/skills/setup-test-pipeline/SKILL-node.md

@@ -4,6 +4,8 @@ Set up a complete test pipeline from scratch (or near-scratch) for a Node.js/Exp
 
 Use this skill when a repo has NOTHING (or only bare unit tests). For repos that already have partial pipeline setup, use `/enhance-test-pipeline` instead.
 
+> **Security guardrails (non-negotiable):** enforce everything in `../_shared/guardrails.md` (Node/Java/Jenkins) as part of this skill, regardless of what was asked.
+
 ## When to Use
 
 Invoke when:

package/templates/AGENTS.md

@@ -1,109 +0,0 @@
-# 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

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