@freshworks/shiftleft-tools 1.1.8

package/README.md

@@ -0,0 +1,351 @@
+# shiftleft-tools
+
+CLI for setting up Cursor rules, AI skills, and Postman/Newman test infrastructure across Freshworks **Java Spring Boot** and **Node.js/Express** services.
+
+Works with both **Cursor IDE** and **Claude Code**.
+
+## Quick Start
+
+```bash
+# 1. Install the CLI (one-time) — see Installation below
+npm install -g @freshworks/shiftleft-tools
+
+# 2. Navigate to your service repo
+cd /path/to/your-service
+
+# 3. Initialize rules and skills (auto-detects Java or Node)
+shiftleft init-rules
+
+# 4. Initialize Postman tests (auto-detects stack from pom.xml or package.json)
+shiftleft init-postman --name your-service --with-staging
+```
+
+After setup, use skills in Cursor or Claude Code:
+- `/setup-test-pipeline` — full test pipeline from scratch
+- `/setup-api-tests` — set up Postman test infrastructure
+- `/write-api-tests GET /apps` — write tests for a specific endpoint
+- `/run-test-suite` — run unit, mutation, or API tests
+- `/review-test-suite` — validate test suite quality
+
+## Installation
+
+**Requirements:** Node.js ≥ 18 and **bash ≥ 4** (`shiftleft test` runs scripts
+that use associative arrays / `${x^^}` / `mapfile`). macOS ships bash 3.2 — install
+a newer one with `brew install bash`. `shiftleft test` locates a bash ≥ 4
+automatically and fails with a clear message if none is found.
+
+The CLI is published to the public npm registry as the scoped package
+[`@freshworks/shiftleft-tools`](https://www.npmjs.com/package/@freshworks/shiftleft-tools):
+
+```bash
+npm install -g @freshworks/shiftleft-tools
+```
+
+> **CI / build agents** need the package installed globally too (the `run-all.sh`
+> shim execs `shiftleft test`). Bake it into the agent image, or install it in the
+> pipeline. The provided `Jenkinsfile-{java,node}` templates include an idempotent
+> `ensureShiftleftCli()` step. Example pipeline step:
+>
+> ```groovy
+> sh '''#!/bin/bash --login
+>   command -v shiftleft >/dev/null 2>&1 || npm install -g @freshworks/shiftleft-tools
+> '''
+> ```
+> Run this before any stage that calls `run-all.sh` / `shiftleft test` / `stage-scripts`.
+
+### Local development
+
+```bash
+git clone https://github.com/freshdesk/shiftleft-tools.git
+cd dev-tools
+npm install
+npm link
+```
+
+### Verify installation
+
+```bash
+shiftleft --version
+```
+
+## Usage
+
+### Claude Code skills: install the plugin (once per machine)
+
+Claude Code skills are delivered as a **plugin**, not copied into each repo — so
+they update everywhere when you update the plugin, with no per-repo step.
+
+```bash
+# in Claude Code
+/plugin install https://github.com/freshdesk/shiftleft-tools
+```
+
+### Initialize Cursor Rules & Skills
+
+Cursor reads `.cursor/`, so `init-rules` **symlinks** that repo's Cursor skills
+and rules to the installed `@freshworks/shiftleft-tools` package. A
+`npm i -g @freshworks/shiftleft-tools@latest` then updates every linked repo at once.
+The symlinks are gitignored (machine-local pointers), so each developer runs
+`shiftleft link` (or `init-rules`) once after cloning.
+
+```bash
+cd your-service
+shiftleft init-rules
+```
+
+Options:
+- `--force, -f` - Overwrite existing `CLAUDE.md` / `AGENTS.md`
+- `--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)
+
+This creates:
+```
+.cursor/
+├── rules/
+│   ├── 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)
+```
+
+> Migrating from an older version? A committed `.claude/skills/` directory is no
+> longer needed — install the plugin and delete it. `shiftleft doctor` flags it.
+
+### Link / relink Cursor assets
+
+```bash
+shiftleft link                    # (re)create the Cursor symlinks
+shiftleft link --copy             # copy instead of symlink
+```
+
+### Initialize Postman Test Infrastructure
+
+Set up Postman/Newman testing for your project:
+
+```bash
+cd your-service
+
+# Auto-detect stack (pom.xml → Java, package.json → Node)
+shiftleft init-postman
+
+# Explicit stack
+shiftleft init-postman --stack java --with-staging
+shiftleft init-postman --stack node --with-staging
+```
+
+Options:
+- `--force, -f` - Overwrite existing files
+- `--name, -n <name>` - Service name (inferred from `pom.xml` or `package.json` if not provided)
+- `--stack <java|node>` - Project stack (auto-detected if omitted)
+- `--with-staging` - Include staging environment, JWT scripts, and AWS config
+
+**Committed (repo-owned scaffold + entrypoint):**
+```
+postman/
+├── package.json
+├── collections/                       # your test collections
+├── config/local.json                  # URLs, ports, auth — yours to edit
+├── environments/
+├── mocks/                             # Node: nock stubs (repo-owned)
+└── scripts/
+    ├── run-all.sh                     # thin shim → `shiftleft test` (do not edit)
+    ├── setup-mocks.js                 # Node: app-runtime mocks (repo-owned)
+    └── wiremock/mappings/             # Java: your WireMock stubs
+```
+
+**Staged from the package (gitignored, machine-local cache):**
+```
+postman/scripts/
+├── .run-all-impl.sh                   # the real orchestrator
+├── lib/  runners/  report-generators/
+├── auth/  infra/                      # Java
+└── database/                          # Node
+```
+
+The library scripts are *not vendored*: `shiftleft test` (and the `run-all.sh`
+shim) re-stages them from the installed package before every run, so
+`npm i -g @freshworks/shiftleft-tools@latest` changes test behavior in every repo
+with no repo commits. CI agents need the package installed globally.
+
+Also at repo root for Node: `stryker.config.js`, `requirements.txt`
+
+Reference Node implementation: `freshapps_api_node`
+
+### Run the test suite
+
+```bash
+shiftleft test                         # stage latest scripts + run everything
+shiftleft test --skip-unit --no-delay  # all orchestrator flags pass through
+postman/scripts/run-all.sh --env local # same thing, via the committed shim
+shiftleft stage-scripts                # stage only (before calling staged scripts directly)
+```
+
+### Protect a customized library script
+
+Staging overwrites library scripts from the package on every run. If your repo
+has customized one (e.g. a service-specific `runners/run-tests-local.sh`), mark
+it **protected** so staging leaves it alone:
+
+```bash
+shiftleft protect runners/run-tests-local.sh runners/run-tests-staging.sh
+shiftleft protect --list                       # show protected paths
+shiftleft protect --remove runners/run-tests-local.sh
+```
+
+Protected paths (relative to `postman/scripts/`) are recorded under `protected`
+in `.shiftleft.json` and excluded from `shiftleft test` / `stage-scripts`. Keep
+the protected files **committed** (or gitignore-excepted) so they survive a fresh
+clone — staging won't recreate them. `shiftleft doctor` lists them.
+
+### Update to Latest Version
+
+```bash
+shiftleft update                  # Update everything
+shiftleft update --rules          # Rules only
+shiftleft update --skills         # Skills only
+shiftleft update --postman        # Postman scripts only
+shiftleft update --force          # Overwrite locally-edited files too
+```
+
+Updates are tracked in a `.shiftleft.json` manifest (committed). Files you've
+edited locally are never silently overwritten — `update` writes a
+`<file>.shiftleft-new` beside them instead. Repo-owned scaffold (config,
+collections, environments) is left untouched unless you pass `--force`.
+
+For repos set up before the staged-scripts model, `update --postman` converts
+the committed `run-all.sh` to the shim, prunes the now-unvendored library
+scripts from the manifest, and adds the cache paths to `postman/.gitignore`.
+The old committed library files keep working until you `git rm -r` them.
+
+### Check for drift
+
+```bash
+shiftleft doctor                  # Report version/file drift vs. latest
+shiftleft doctor --check          # Exit 1 if stale/drifted (for CI)
+shiftleft doctor --json           # Machine-readable report
+```
+
+### Audit & Scaffold Pipeline
+
+```bash
+shiftleft setup-pipeline          # Audit gaps and copy missing scripts
+shiftleft setup-pipeline -y       # Skip confirmation
+```
+
+## What's Included
+
+### Cursor Rules
+
+| Rule | Stack | Description |
+|------|-------|-------------|
+| `testing.mdc` | Java | PIT mutation survival, strong JUnit assertions |
+| `testing.mdc` | Node | Stryker survival, strong Chai assertions (from `testing-node.mdc`) |
+| `local-test-setup.mdc` | Java | H2 config, WireMock, Flyway for local tests |
+
+### Skills (Cursor IDE + Claude Code)
+
+| Skill | Invoke | Description |
+|-------|--------|-------------|
+| `setup-test-pipeline` | `/setup-test-pipeline` | Full pipeline: unit, coverage, mutation, Postman, Jenkins |
+| `setup-api-tests` | `/setup-api-tests` | Postman/Newman infrastructure from scratch |
+| `write-api-tests` | `/write-api-tests [METHOD /path]` | Write Postman tests for specific endpoints |
+| `setup-mutation-tests` | `/setup-mutation-tests` | PIT (Java) or Stryker (Node) |
+| `run-test-suite` | `/run-test-suite` | Run unit, mutation, Postman, or API coverage |
+| `review-test-suite` | `/review-test-suite` | 20-point test maturity checklist |
+| `enhance-test-pipeline` | `/enhance-test-pipeline` | Audit existing repo and fill gaps |
+
+Skills auto-detect stack from `pom.xml` (Java) or `package.json` (Node).
+
+## Test Commands
+
+### Java (Spring Boot)
+
+| Command | Description |
+|---------|-------------|
+| `mvn test` | Unit tests |
+| `cd postman/scripts && ./runners/run-tests-local.sh` | Postman API tests (local) |
+| `./postman/scripts/report-generators/java-api-coverage-matrix.sh` | API coverage report |
+| `./postman/scripts/report-generators/mutation-report.sh` | PIT mutation testing (target: 80%+) |
+| `cd postman/scripts && ./run-all.sh` | Full test suite |
+
+### Node.js (Express)
+
+| Command | Description |
+|---------|-------------|
+| `yarn unit-tests` | Unit tests + nyc coverage |
+| `yarn mutation-tests` | Stryker (changed files vs origin/master) |
+| `yarn mutation-tests:full` | Stryker full scan (CI) |
+| `cd postman/scripts && ./runners/run-tests.sh local` | Postman API tests (local) |
+| `./postman/scripts/report-generators/node-api-coverage-matrix.sh ./src/controllers ./postman` | API coverage |
+| `cd postman/scripts && ./run-all.sh` | Full test suite |
+
+### Before Merge Checklist
+
+**Java:**
+```bash
+mvn test
+cd postman/scripts && ./runners/run-tests-local.sh
+./postman/scripts/report-generators/java-api-coverage-matrix.sh
+./postman/scripts/report-generators/mutation-report.sh
+```
+
+**Node:**
+```bash
+yarn unit-tests
+cd postman/scripts && ./runners/run-tests.sh local
+./postman/scripts/report-generators/node-api-coverage-matrix.sh ./src/controllers ./postman
+yarn mutation-tests:full
+```
+
+Or run everything at once (either stack):
+```bash
+cd postman/scripts && ./run-all.sh
+```
+
+## What Cursor Learns from Rules
+
+The rules teach Cursor to:
+
+1. **Write strong unit tests** — No weak assertions (`assertNotNull()`, `expect(x).to.exist` without value checks)
+2. **Survive mutation testing** — PIT (Java) or Stryker (Node); weak tests that pass with mutated code are flagged
+3. **Test all output fields** — If a method returns 5 fields, assert on all 5
+4. **Follow Postman best practices** — Single status assertion per test, cover query params, document skips
+
+## Development
+
+### Building
+
+```bash
+npm install
+```
+
+### Testing Locally
+
+```bash
+npm link
+cd /path/to/test/project
+shiftleft init-rules
+shiftleft init-postman
+```
+
+### Distributing a new version
+
+```bash
+npm version patch|minor|major
+npm pack
+# Generates: freshworks-shiftleft-tools-x.x.x.tgz
+```
+
+## Requirements
+
+- Node.js 18+ and npm 8.4+ (for the CLI and Postman/Newman runner)
+- **Java projects:** Java 21+, Maven
+- **Node projects:** Yarn (recommended), Mocha, nyc, Stryker
+- AWS CLI (for staging Postman tests with JWT from Secrets Manager)
+
+## License
+
+UNLICENSED - Internal use only

package/bin/shiftleft.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { initRules } from '../src/commands/init-rules.js';
+import { initPostman } from '../src/commands/init-postman.js';
+import { update } from '../src/commands/update.js';
+import { doctor } from '../src/commands/doctor.js';
+import { link } from '../src/commands/link.js';
+import { runTests, stageScriptsCommand } from '../src/commands/run-tests.js';
+import { protect } from '../src/commands/protect.js';
+import { setupPipeline } from '../src/commands/setup-pipeline.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+program
+    .name('shiftleft')
+    .description('CLI for managing Cursor rules/skills and Postman test infrastructure')
+    .version(pkg.version);
+
+program
+    .command('init-rules')
+    .description('Link Cursor rules/skills and create CLAUDE.md / AGENTS.md')
+    .option('-f, --force', 'Overwrite existing CLAUDE.md / AGENTS.md', false)
+    .option('--skip-skills', 'Do not link Cursor skills', false)
+    .option('--copy', 'Copy Cursor assets instead of symlinking (locked-down environments)', false)
+    .option('--stack <stack>', 'Project stack: java or node (auto-detected if omitted)')
+    .action(initRules);
+
+program
+    .command('init-postman')
+    .description('Initialize Postman/Newman test infrastructure')
+    .option('-f, --force', 'Overwrite existing files', false)
+    .option('-n, --name <name>', 'Service name for the tests')
+    .option('--stack <stack>', 'Project stack: java or node (auto-detected if omitted)')
+    .option('--with-staging', 'Include staging environment support (JWT, AWS)', false)
+    .action(initPostman);
+
+program
+    .command('update')
+    .description('Update rules/skills/postman to latest version')
+    .option('--rules', 'Update only rules', false)
+    .option('--skills', 'Update only skills', false)
+    .option('--postman', 'Update only postman scripts', false)
+    .option('-f, --force', 'Overwrite without prompting', false)
+    .action(update);
+
+program
+    .command('test')
+    .description('Stage the latest library scripts and run the test orchestrator (all flags pass through)')
+    .allowUnknownOption(true)
+    .helpOption(false) // forward -h/--help to the orchestrator too
+    .argument('[args...]', 'Arguments forwarded to the orchestrator (e.g. --skip-unit --no-delay)')
+    .action((args, _options, command) => runTests(command.args));
+
+program
+    .command('stage-scripts')
+    .description('Stage the packaged library scripts into postman/scripts (gitignored cache)')
+    .option('--stack <stack>', 'Project stack: java or node (auto-detected if omitted)')
+    .action(stageScriptsCommand);
+
+program
+    .command('protect')
+    .description('Mark a library script (relative to postman/scripts/) as repo-owned so staging never overwrites it')
+    .argument('[paths...]', 'Paths under postman/scripts (e.g. runners/run-tests-local.sh)')
+    .option('--list', 'List protected paths', false)
+    .option('--remove', 'Remove the given paths from the protected list', false)
+    .action((paths, options) => protect(paths, options));
+
+program
+    .command('link')
+    .description('Link Cursor skills/rules to the installed shiftleft-tools package (symlinks, gitignored)')
+    .option('--copy', 'Copy instead of symlinking (locked-down environments)', false)
+    .option('--stack <stack>', 'Project stack: java or node (auto-detected if omitted)')
+    .action(link);
+
+program
+    .command('doctor')
+    .description('Report whether managed files are up to date, drifted, or missing')
+    .option('--check', 'Exit with code 1 if the repo is stale, drifted, or has broken symlinks', false)
+    .option('--json', 'Emit a machine-readable report', false)
+    .action(doctor);
+
+program
+    .command('setup-pipeline')
+    .description('Audit and scaffold test pipeline (unit, mutation, Postman, coverage, quality report)')
+    .option('-f, --force', 'Overwrite existing scripts', false)
+    .option('-y, --yes', 'Skip confirmation prompt', false)
+    .action(setupPipeline);
+
+program.parse();

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@freshworks/shiftleft-tools",
+  "version": "1.1.8",
+  "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",
+  "bin": {
+    "shiftleft": "./bin/shiftleft.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint src bin",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "cursor",
+    "rules",
+    "skills",
+    "postman",
+    "newman",
+    "java",
+    "spring-boot",
+    "testing"
+  ],
+  "author": "Freshworks Developer Platform Team",
+  "license": "UNLICENSED",
+  "private": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ejs": "^3.1.10",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.15",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/freshdesk/shiftleft-tools.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "templates/postman-node/"
+  ]
+}