@osfactory/har 1.15.1 → 1.16.0

package/dist/templates/plugins/cypress/.github/workflows/cypress.yml

@@ -0,0 +1,25 @@
+# Cypress end-to-end tests — official GitHub Action
+# https://github.com/cypress-io/github-action
+#
+# Adapt `start` and `wait-on` to this repo's dev server. The action installs
+# dependencies, downloads the Cypress binary, and runs `cypress run`.
+name: Cypress tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  cypress-run:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Cypress run
+        uses: cypress-io/github-action@v7
+        with:
+          start: npm run dev
+          wait-on: http://localhost:3000
+          browser: chrome
+        env:
+          CYPRESS_BASE_URL: http://localhost:3000

package/dist/templates/plugins/cypress/.har/stages/CYPRESS.md

@@ -0,0 +1,81 @@
+# Cypress (cypress-e2e)
+
+Adapt specs under `cypress/e2e/` for your application. Full verification (`verify --full`) runs this stage when it is listed in `verificationStages` (the plugin adds it).
+
+| Path | Purpose |
+|------|---------|
+| `cypress/e2e/` | End-to-end specs — extend when you add UI |
+| `cypress/support/e2e.js` | Shared commands loaded before every spec |
+| `cypress.config.js` | Base URL, spec pattern, artifact folders |
+
+## Run
+
+After `har env launch <id>` and `npm install`:
+
+```bash
+npx cypress verify
+./.har/stages/cypress-e2e.sh <id>
+# included in:
+har env verify <id> --full
+```
+
+`cypress run` is headless. Cypress 16 deprecates the bundled Electron browser, so the stage uses Chrome when `google-chrome` is on PATH (or Google Chrome.app on macOS), then Chromium, then Electron. Set `HARNESS_CYPRESS_BROWSER` (`chrome`, `chromium`, `firefox`, `electron`) to override. Electron still runs in Cypress 16 and prints a deprecation warning.
+
+## Ports
+
+The stage reads the slot env file and points Cypress at that slot:
+
+| Variable | Source | Cypress |
+|----------|--------|---------|
+| Frontend | `FE_PORT` (or `HARNESS_FE_BASE_PORT + id * 10`) | `CYPRESS_BASE_URL` → `cy.visit('/')` |
+| API | `API_PORT` (or `HARNESS_API_BASE_PORT + id * 10`) | `CYPRESS_API_URL` → `Cypress.expose('API_URL')` |
+| Health path | `HARNESS_HEALTH_CHECK_PATH` (default `/health`) | `Cypress.expose('HEALTH_PATH')` |
+
+Do not hardcode slot ports in specs. A monolith that serves UI and API on one port should set both bases to that origin in `.har/harness.env` (or only assert against `baseUrl`).
+
+The scaffold `api.cy.js` expects `GET /health` to return 200. Change the path, or set `HARNESS_HEALTH_CHECK_PATH`, to match your app.
+
+## Artifacts
+
+Written under the main repo's `.har/artifacts/cypress-e2e/` (not the worktree):
+
+| Path | Contents |
+|------|----------|
+| `cypress.log` | Full `cypress run` output |
+| `screenshots/` | Automatic failure screenshots |
+| `videos/` | Present when you set `video: true` in `cypress.config.js` |
+
+Video recording is off by default (`video: false`), matching current Cypress. Turn it on in config when you want a video per spec.
+
+Exit codes use `--posix-exit-codes`: `0` when every spec passes, `1` when Cypress fails. The stage propagates that code. Without the flag, Cypress exits with the number of failed tests.
+
+## Linux libraries
+
+`npx cypress verify` checks that the Electron binary can start. If it reports missing libraries, install the packages listed in the [Cypress Linux prerequisites](https://docs.cypress.io/app/get-started/install-cypress#Linux-Prerequisites) and verify again.
+
+## Existing Cypress projects
+
+`add-plugin` will not overwrite a `cypress.config.js` you already have. Point `specPattern` at your specs, keep artifact folders under `.har/artifacts/cypress-e2e/`, and let the stage export `CYPRESS_BASE_URL` rather than a fixed `baseUrl`.
+
+## New UI features
+
+Add or update a spec so `cypress-e2e` covers the change. Prefer one file per feature under `cypress/e2e/<feature>.cy.js`. Full verification must pass before done.
+
+## CI
+
+`har env add-plugin cypress --with-ci` copies `.github/workflows/cypress.yml`, the official `cypress-io/github-action@v7` recipe. Change `start` and `wait-on` to this repo's dev command and URL.
+
+## Plugin updates
+
+When HAR ships a new plugin template version, merge drift from:
+
+```bash
+har env maintain
+# review .har/maintain/plugins/cypress/
+```
+
+Or refresh all plugin-owned files:
+
+```bash
+har env add-plugin cypress --force
+```

package/dist/templates/plugins/cypress/.har/stages/cypress-e2e.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Cypress end-to-end tests for an agent slot.
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/stages/cypress-e2e.sh <agent-id>
+# Prerequisite: har env launch <agent-id> AND npm install (Cypress binary)
+# See: ./.har/stages/CYPRESS.md
+set -euo pipefail
+
+# 1.0 stage surface: the runner exports WORK_DIR, ENV_FILE, AGENT_ID and
+# HAR_HARNESS_DIR, with harness.env and the slot env file already sourced —
+# agent-slot.sh is retired (1.0 migration).
+HARNESS_DIR="${HAR_HARNESS_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+AGENT_ID="${1:-${AGENT_ID:?Usage: cypress-e2e.sh <agent-id>}}"
+
+# Direct invocation (the manifest nextSteps) has no runner in front of it.
+# Recover the slot work dir from the registry launch wrote.
+if [ -z "${ENV_FILE:-}" ] || [ -z "${WORK_DIR:-}" ]; then
+  SLOT_FILE="$HARNESS_DIR/slots/agent-${AGENT_ID}.json"
+  if [ -f "$SLOT_FILE" ]; then
+    SLOT_WORK="$(node -e 'const fs=require("fs"); const s=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); process.stdout.write(s.workDir||"")' "$SLOT_FILE" 2>/dev/null || true)"
+    if [ -n "$SLOT_WORK" ] && [ -f "$SLOT_WORK/.env.agent.${AGENT_ID}" ]; then
+      WORK_DIR="$SLOT_WORK"
+      ENV_FILE="$SLOT_WORK/.env.agent.${AGENT_ID}"
+      set -a
+      # shellcheck disable=SC1091
+      [ -f "$HARNESS_DIR/harness.env" ] && . "$HARNESS_DIR/harness.env"
+      # shellcheck disable=SC1090
+      . "$ENV_FILE"
+      set +a
+    fi
+  fi
+fi
+
+now_ms() { node -e 'process.stdout.write(String(Date.now()))' 2>/dev/null || echo 0; }
+
+log() { echo "==> [cypress-e2e agent-$AGENT_ID] $*" >&2; }
+
+ENV_FILE="${ENV_FILE:?No slot env for agent ${AGENT_ID} — run har env launch ${AGENT_ID} first}"
+WORK_DIR="${WORK_DIR:?No slot work dir for agent ${AGENT_ID} — run har env launch ${AGENT_ID} first}"
+
+FE_PORT="${FE_PORT:-$(( ${HARNESS_FE_BASE_PORT:-3000} + AGENT_ID * 10 ))}"
+API_PORT="${API_PORT:-$(( ${HARNESS_API_BASE_PORT:-8000} + AGENT_ID * 10 ))}"
+
+export BASE_URL="${BASE_URL:-http://localhost:${FE_PORT}}"
+export API_URL="${API_URL:-http://localhost:${API_PORT}}"
+export CYPRESS_BASE_URL="${CYPRESS_BASE_URL:-$BASE_URL}"
+export CYPRESS_API_URL="${CYPRESS_API_URL:-$API_URL}"
+HEALTH_PATH="${HARNESS_HEALTH_CHECK_PATH:-${HARNESS_HEALTH_PATH:-/health}}"
+export CYPRESS_HEALTH_PATH="${CYPRESS_HEALTH_PATH:-$HEALTH_PATH}"
+
+# Artifacts land next to this harness (main checkout), not inside a worktree
+# whose .env.agent file may rewrite REPO_ROOT.
+ARTIFACT_DIR="$(cd "$HARNESS_DIR/.." && pwd)/.har/artifacts/cypress-e2e"
+mkdir -p "$ARTIFACT_DIR"
+export HARNESS_CYPRESS_ARTIFACT_DIR="$ARTIFACT_DIR"
+
+# Cypress 16 deprecates the bundled Electron browser. Prefer an installed Chrome
+# or Chromium; fall back to Electron so `npm install` is still enough to run.
+if [ -n "${HARNESS_CYPRESS_BROWSER:-}" ]; then
+  BROWSER="$HARNESS_CYPRESS_BROWSER"
+elif command -v google-chrome >/dev/null 2>&1 || command -v google-chrome-stable >/dev/null 2>&1 || [ -d "/Applications/Google Chrome.app" ]; then
+  BROWSER="chrome"
+elif command -v chromium >/dev/null 2>&1 || command -v chromium-browser >/dev/null 2>&1; then
+  BROWSER="chromium"
+else
+  BROWSER="electron"
+fi
+export HARNESS_CYPRESS_BROWSER="$BROWSER"
+
+if [ ! -x "$WORK_DIR/node_modules/.bin/cypress" ]; then
+  echo "Error: Cypress is not installed in $WORK_DIR." >&2
+  echo "  npm install" >&2
+  echo "  npx cypress verify" >&2
+  echo "  Then re-run: ./.har/stages/cypress-e2e.sh ${AGENT_ID}" >&2
+  exit 1
+fi
+
+log "Running Cypress ($BROWSER) against $CYPRESS_BASE_URL (API: $CYPRESS_API_URL)"
+log "Work dir: $WORK_DIR"
+log "Artifacts: $ARTIFACT_DIR"
+
+START_TOTAL=$(now_ms)
+LOG_FILE="$ARTIFACT_DIR/cypress.log"
+
+set +e
+(
+  cd "$WORK_DIR"
+  npx cypress run \
+    --e2e \
+    --browser "$BROWSER" \
+    --posix-exit-codes
+) >"$LOG_FILE" 2>&1
+CYPRESS_EXIT=$?
+set -e
+
+END_TOTAL=$(now_ms)
+TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
+
+if [ "$CYPRESS_EXIT" -eq 0 ]; then
+  log "Cypress passed (${TOTAL_MS}ms)"
+else
+  log "Cypress failed with exit $CYPRESS_EXIT (${TOTAL_MS}ms) — see $LOG_FILE"
+  tail -30 "$LOG_FILE" | sed 's/^/    /' >&2
+fi
+
+HARNESS_CYPRESS_ARTIFACT_DIR="$ARTIFACT_DIR" node -e "
+const fs = require('fs');
+const artifactDir = process.env.HARNESS_CYPRESS_ARTIFACT_DIR;
+const out = {
+  status: ${CYPRESS_EXIT} === 0 ? 'pass' : 'fail',
+  stageId: 'cypress-e2e',
+  kind: 'test',
+  agent_id: ${AGENT_ID},
+  total_ms: ${TOTAL_MS},
+  exit_code: ${CYPRESS_EXIT},
+  browser: process.env.HARNESS_CYPRESS_BROWSER || 'electron',
+  urls: [
+    { label: 'frontend', url: process.env.CYPRESS_BASE_URL || '' },
+    { label: 'api', url: process.env.CYPRESS_API_URL || '' },
+  ],
+  artifacts: [
+    { path: '.har/artifacts/cypress-e2e', kind: 'directory' },
+    { path: '.har/artifacts/cypress-e2e/cypress.log', kind: 'log' },
+  ],
+};
+if (fs.existsSync(artifactDir + '/screenshots')) {
+  out.artifacts.push({ path: '.har/artifacts/cypress-e2e/screenshots', kind: 'directory' });
+}
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+exit "$CYPRESS_EXIT"

package/dist/templates/plugins/cypress/README.md

@@ -0,0 +1,14 @@
+# Cypress HAR plugin
+
+This plugin was added by `har env add-plugin cypress`. It registers a `cypress-e2e` stage and scaffolds a minimal Cypress end-to-end suite.
+
+## Next steps
+
+```bash
+npm install
+npx cypress verify
+har env launch 1
+./.har/stages/cypress-e2e.sh 1
+```
+
+See `.har/stages/CYPRESS.md` for adaptation checklist, ports, and artifact layout.

package/dist/templates/plugins/cypress/cypress/e2e/api.cy.js

@@ -0,0 +1,13 @@
+// TODO: adapt the path for your app's health endpoint.
+// Public config comes from cypress.config.js `expose` (Cypress.env was removed in Cypress 16).
+describe('api health', () => {
+  it('health endpoint responds', () => {
+    const healthPath = Cypress.expose('HEALTH_PATH') || '/health';
+    const apiUrl = String(Cypress.expose('API_URL') || Cypress.config('baseUrl') || '').replace(
+      /\/$/,
+      '',
+    );
+    const requestPath = String(healthPath).startsWith('/') ? String(healthPath) : `/${healthPath}`;
+    cy.request(`${apiUrl}${requestPath}`).its('status').should('eq', 200);
+  });
+});

package/dist/templates/plugins/cypress/cypress/e2e/smoke.cy.js

@@ -0,0 +1,7 @@
+// TODO: adapt routes and selectors for your app.
+describe('smoke', () => {
+  it('homepage loads', () => {
+    cy.visit('/');
+    cy.get('body').should('be.visible');
+  });
+});

package/dist/templates/plugins/cypress/cypress/support/e2e.js

@@ -0,0 +1 @@
+// Loaded before every spec. Add app-wide commands here.

package/dist/templates/plugins/cypress/cypress.config.js

@@ -0,0 +1,68 @@
+// Cypress config for the HAR `cypress-e2e` verification stage.
+//
+// Harness integration
+// -------------------
+// - Stage id: `cypress-e2e` (`.har/stages/cypress-e2e.sh`, registered in `stages.json`).
+// - Runs on FULL verify only — not on quick verify:
+//     har env verify <id> --full
+// - Quick verify stops at the quick-tier stages (typecheck, unit tests, api-health).
+//
+// Prerequisites
+// -------------
+// 1. Launch a slot first:  har env launch <id>
+// 2. Install Cypress:       npm install && npx cypress verify
+//    The Cypress npm package downloads the Electron binary. On Linux, system
+//    libraries from the Cypress docs may also be required.
+//
+// Environment (injected by cypress-e2e.sh — never hardcode slot ports in specs)
+// ------------------------------------------------------------------------------
+// CYPRESS_BASE_URL   Frontend origin for cy.visit('/') (slot FE port)
+// CYPRESS_API_URL    API origin (Cypress.expose('API_URL'); Cypress.env was removed in Cypress 16)
+// CYPRESS_HEALTH_PATH  Health path (Cypress.expose('HEALTH_PATH'), default /health)
+// HARNESS_CYPRESS_ARTIFACT_DIR  Absolute artifact directory for this run
+// HARNESS_CYPRESS_BROWSER       Browser passed to `cypress run` (chrome when installed, else electron)
+//
+// Test layout — agents must add or update specs for every UI change
+// ------------------------------------------------------------------
+// cypress/e2e/<feature>.cy.js   End-to-end flows (prefer one file per feature)
+//
+// Full verify only proves existing specs pass. New UI behavior needs new or
+// updated specs here — the harness does not auto-generate flows per feature.
+// Widen `specPattern` to `cypress/e2e/**/*.cy.{js,jsx,ts,tsx}` when you add
+// TypeScript specs.
+//
+// Artifacts (gitignored under .har/artifacts/)
+// --------------------------------------------
+// cypress-e2e/cypress.log     Runner log
+// cypress-e2e/screenshots/    Failure screenshots (cypress run)
+// cypress-e2e/videos/         Videos when `video: true` (off by default)
+//
+// Local-only (without cypress-e2e.sh):  npm run test:cypress
+// Set CYPRESS_BASE_URL (and CYPRESS_API_URL if split) when the app is not on
+// the default below.
+const path = require('path');
+const { defineConfig } = require('cypress');
+
+const baseUrl = process.env.CYPRESS_BASE_URL || process.env.BASE_URL || 'http://localhost:3000';
+const apiUrl = process.env.CYPRESS_API_URL || process.env.API_URL || baseUrl;
+const healthPath = process.env.CYPRESS_HEALTH_PATH || '/health';
+const artifactDir =
+  process.env.HARNESS_CYPRESS_ARTIFACT_DIR || path.join('.har', 'artifacts', 'cypress-e2e');
+
+module.exports = defineConfig({
+  expose: {
+    API_URL: apiUrl,
+    HEALTH_PATH: healthPath,
+  },
+  e2e: {
+    baseUrl,
+    specPattern: 'cypress/e2e/**/*.cy.js',
+    supportFile: 'cypress/support/e2e.js',
+    fixturesFolder: false,
+    screenshotsFolder: path.join(artifactDir, 'screenshots'),
+    videosFolder: path.join(artifactDir, 'videos'),
+    downloadsFolder: path.join(artifactDir, 'downloads'),
+    video: false,
+    screenshotOnRunFailure: true,
+  },
+});

package/dist/templates/plugins/cypress/package.fragment.json

@@ -0,0 +1,10 @@
+{
+  "scripts": {
+    "test:cypress": "cypress run",
+    "test:cypress:open": "cypress open",
+    "test:cypress:ci": "cypress run --posix-exit-codes"
+  },
+  "devDependencies": {
+    "cypress": "^16.1.1"
+  }
+}

package/dist/templates/plugins/cypress/template.manifest.json

@@ -0,0 +1,74 @@
+{
+  "id": "cypress",
+  "stageId": "cypress-e2e",
+  "verificationStages": [
+    "cypress-e2e"
+  ],
+  "stage": {
+    "id": "cypress-e2e",
+    "kind": "test",
+    "description": "Cypress end-to-end tests against the slot's running app",
+    "script": "stages/cypress-e2e.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/cypress-e2e",
+        "kind": "directory",
+        "description": "Cypress run log, screenshots, and videos"
+      },
+      {
+        "path": ".har/artifacts/cypress-e2e/cypress.log",
+        "kind": "log"
+      }
+    ],
+    "tier": "full"
+  },
+  "files": [
+    {
+      "src": ".har/stages/cypress-e2e.sh",
+      "dest": ".har/stages/cypress-e2e.sh",
+      "executable": true
+    },
+    {
+      "src": ".har/stages/CYPRESS.md",
+      "dest": ".har/stages/CYPRESS.md"
+    },
+    {
+      "src": "cypress.config.js",
+      "dest": "cypress.config.js"
+    },
+    {
+      "src": "cypress/e2e/smoke.cy.js",
+      "dest": "cypress/e2e/smoke.cy.js"
+    },
+    {
+      "src": "cypress/e2e/api.cy.js",
+      "dest": "cypress/e2e/api.cy.js"
+    },
+    {
+      "src": "cypress/support/e2e.js",
+      "dest": "cypress/support/e2e.js"
+    },
+    {
+      "src": "README.md",
+      "dest": "cypress/README.md"
+    }
+  ],
+  "optionalFiles": [
+    {
+      "src": ".github/workflows/cypress.yml",
+      "dest": ".github/workflows/cypress.yml",
+      "skipFlag": "skipCi"
+    }
+  ],
+  "merge": {
+    "package.json": "package.fragment.json"
+  },
+  "nextSteps": [
+    "npm install",
+    "npx cypress verify",
+    "har env launch 1",
+    "./.har/stages/cypress-e2e.sh 1"
+  ],
+  "docsPath": ".har/stages/CYPRESS.md"
+}

package/dist/templates/runtime-bundles/shared-kernel/STAGES.md

@@ -104,7 +104,8 @@ committed.
 playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
 add-plugin kerno` (backend), `har env add-plugin gitleaks` (secrets scanning, any
 stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack),
-or `har env add-plugin semgrep` (SAST, any stack)
+or `har env add-plugin semgrep` (SAST, any stack),
+or `har env add-plugin cypress` (browser e2e)
 installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as everything else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "HAR: open agent harness CLI and MCP server for coding agents, isolated worktrees, and software-factory workflows",
   "keywords": [
     "har",