@mknrt/autotests-overkill 1.2.6 → 1.3.0

package/dist/src/runtime/cypressTap.js

@@ -0,0 +1,175 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { cypressEnvironment, cypressInstallation, cypressTapArguments } from './cypressProcess.js';
+import { redactValue } from './redact.js';
+const text = z.string().min(1).max(2000).refine((value) => !/[\0\r\n]/.test(value), 'Control characters are not allowed');
+export const cypressTapInput = z.object({
+    action: z.enum(['sessions', 'status', 'specs', 'run', 'reporter', 'command', 'pin', 'dom', 'aria', 'inspect']),
+    sessionId: z.number().int().positive().optional(), requestId: z.string().uuid().optional(),
+    spec: text.optional(), testId: text.optional(), commandId: text.optional(),
+    attempt: z.number().int().min(1).max(100).optional(),
+    depth: z.union([z.number().int().min(0).max(20), z.literal('all')]).optional(),
+    selector: text.optional(), at: z.union([z.number().int().nonnegative(), text]).optional(), clear: z.boolean().optional(),
+    maxChars: z.number().int().min(1).max(100000).optional(), maxNodes: z.number().int().min(1).max(1000).optional(),
+    timeoutMs: z.number().int().min(1000).max(60000).optional(),
+    runTimeoutSeconds: z.number().int().min(1).max(7200).optional(),
+}).strict().superRefine((input, context) => {
+    const required = { run: ['spec'], command: ['testId', 'commandId'], inspect: ['selector'] };
+    if (input.action === 'pin' && !input.clear)
+        required.pin = ['testId', 'commandId'];
+    for (const key of required[input.action] ?? []) {
+        if (input[key] === undefined)
+            context.addIssue({ code: 'custom', path: [key], message: `${key} is required for ${input.action}` });
+    }
+    const allowed = {
+        sessions: [], status: ['requestId'], specs: [], run: ['spec', 'runTimeoutSeconds'], reporter: ['testId', 'attempt'],
+        command: ['testId', 'commandId', 'attempt', 'depth'], pin: input.clear ? ['clear'] : ['testId', 'commandId', 'attempt', 'at'],
+        dom: ['selector', 'maxChars', 'at'], aria: ['selector', 'maxNodes', 'at'], inspect: ['selector', 'at'],
+    };
+    for (const key of Object.keys(input)) {
+        if (!['action', 'sessionId', 'timeoutMs', ...allowed[input.action]].includes(key))
+            context.addIssue({ code: 'custom', path: [key], message: `${key} is not valid for ${input.action}` });
+    }
+    if (['dom', 'aria', 'inspect'].includes(input.action) && input.at !== undefined && typeof input.at !== 'number') {
+        context.addIssue({ code: 'custom', path: ['at'], message: 'Element index must be a nonnegative integer' });
+    }
+    if (input.action === 'pin' && typeof input.at === 'number' && input.at < 1) {
+        context.addIssue({ code: 'custom', path: ['at'], message: 'Snapshot indices start at 1' });
+    }
+    if (input.attempt !== undefined && !input.testId)
+        context.addIssue({ code: 'custom', path: ['testId'], message: 'testId is required with attempt' });
+});
+function omitNetworkPayload(value, parent = '') {
+    if (Array.isArray(value))
+        return value.map((entry) => omitNetworkPayload(entry, parent));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+        const name = key.replace(/[^a-z]/gi, '').toLowerCase();
+        const sensitive = /^(request|response)(body|headers)$|^headers$/.test(name) || (/^(request|response)$/.test(parent) && name === 'body');
+        return [key, sensitive ? '[omitted network payload]' : omitNetworkPayload(entry, name)];
+    }));
+}
+export class CypressTap {
+    sanitize;
+    requests = new Map();
+    running = new Set();
+    root;
+    controller = new AbortController();
+    constructor(repoRoot, sanitize = (value) => value) {
+        this.sanitize = sanitize;
+        this.root = fs.realpathSync(repoRoot);
+    }
+    close() { this.controller.abort(); }
+    async execute(raw) {
+        const input = cypressTapInput.parse(raw);
+        if (this.controller.signal.aborted)
+            throw new Error('Cypress TAP is closed.');
+        const sessions = await this.sessions(input.timeoutMs);
+        if (input.action === 'sessions')
+            return redactValue(sessions, this.sanitize);
+        const session = sessions.find((item) => item.pid === input.sessionId)
+            ?? (input.sessionId === undefined && sessions.length === 1 ? sessions[0] : undefined);
+        if (!session)
+            throw new Error(input.sessionId === undefined
+                ? `Found ${sessions.length} open Cypress sessions for this project. Start open mode or choose sessionId from sessions.`
+                : `Cypress session ${input.sessionId} is not an open session for the configured project.`);
+        const args = ['--session', String(session.pid), '--timeout', String(input.timeoutMs ?? 30000)];
+        if (input.action === 'run') {
+            if (this.running.has(session.pid))
+                throw new Error('A TAP run request is already in progress for this session.');
+            let spec = input.spec.replaceAll('\\', '/');
+            if (!spec.startsWith('cypress/') || !/\.cy\.[cm]?[jt]sx?$/.test(spec))
+                throw new Error('spec must be an existing Cypress spec inside cypress/.');
+            const relative = path.relative(this.root, fs.realpathSync(path.resolve(this.root, spec)));
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                throw new Error('spec escapes the configured project.');
+            spec = relative.replaceAll('\\', '/');
+            this.running.add(session.pid);
+            try {
+                const before = await this.call('status', args, input.timeoutMs);
+                const response = await this.call('run', [spec, ...args], input.timeoutMs);
+                const request = { requestId: randomUUID(), spec, previousStartedAt: before.startedAt, deadline: Date.now() + (input.runTimeoutSeconds ?? 900) * 1000 };
+                this.requests.set(session.pid, request);
+                return { ...redactValue(response, this.sanitize), sessionId: session.pid, ...request,
+                    note: 'Run requested, not completed. Poll status with requestId; a previous startedAt is a stale verdict.' };
+            }
+            finally {
+                this.running.delete(session.pid);
+            }
+        }
+        const flags = { testId: 'test-id', commandId: 'command-id', attempt: 'attempt', depth: 'depth', selector: 'selector', at: 'at', maxChars: 'max-chars', maxNodes: 'max-nodes' };
+        for (const [key, flag] of Object.entries(flags)) {
+            const value = input[key];
+            if (value !== undefined)
+                args.push(`--${flag}`, String(value));
+        }
+        if (input.clear)
+            args.push('--clear');
+        const output = await this.call(input.action, args, input.timeoutMs);
+        if (input.action !== 'status')
+            return redactValue(omitNetworkPayload(output), this.sanitize);
+        const request = this.requests.get(session.pid);
+        if (input.requestId && input.requestId !== request?.requestId)
+            throw new Error('Unknown or superseded TAP requestId for this session.');
+        const stale = Boolean(request && (!output.startedAt || output.startedAt === request.previousStartedAt || output.spec?.replaceAll('\\', '/') !== request.spec));
+        const terminal = ['passed', 'failed'].includes(output.status);
+        const counts = output.results;
+        const validCounts = counts && ['passed', 'failed', 'pending', 'skipped'].every((key) => Number.isInteger(counts[key]) && counts[key] >= 0)
+            && Number.isInteger(output.totalTests) && Object.values(counts).reduce((sum, count) => sum + Number(count), 0) === output.totalTests;
+        const testsExecuted = validCounts ? counts.passed + counts.failed : null;
+        const timedOut = Boolean(request && Date.now() > request.deadline && (!terminal || stale));
+        const validTimestamp = typeof output.startedAt === 'string' && Number.isFinite(Date.parse(output.startedAt));
+        const consistentStage = output.status === 'failed' ? counts?.failed > 0 : counts?.failed === 0;
+        const verdict = terminal && !stale && validCounts && validTimestamp && consistentStage
+            ? counts.failed > 0 ? 'failed' : testsExecuted > 0 ? 'passed' : 'no_tests'
+            : null;
+        return { ...redactValue(output, this.sanitize), sessionId: session.pid, requestId: request?.requestId,
+            stale, timedOut, verdict, testsExecuted,
+            note: timedOut ? 'The requested spec did not finish before its deadline; inspect the build/log or stop the session.'
+                : stale ? 'This is the previous run or another spec; keep polling for the requested startedAt.'
+                    : verdict === 'no_tests' ? 'No tests executed; skipped/pending/empty specs are not validation.'
+                        : terminal && (!validCounts || !validTimestamp || !consistentStage) ? 'Missing or inconsistent run timestamp/results; do not treat this as a verified pass.' : undefined };
+    }
+    async sessions(timeoutMs) {
+        const output = await this.call('sessions', ['--timeout', String(timeoutMs ?? 30000)], timeoutMs);
+        if (!Array.isArray(output))
+            throw new Error('Invalid Cypress TAP sessions JSON: expected an array.');
+        return output.filter((session) => {
+            if (!Number.isInteger(session?.pid) || session.pid <= 0 || typeof session.projectRoot !== 'string')
+                return false;
+            try {
+                return fs.realpathSync(session.projectRoot) === this.root;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    async call(action, args, timeoutMs = 30000) {
+        const { cli } = cypressInstallation(this.root, true);
+        const stdout = await new Promise((resolve, reject) => {
+            execFile(process.execPath, cypressTapArguments(cli, [action, '--json', ...args]), {
+                cwd: this.root, env: cypressEnvironment(), windowsHide: true, encoding: 'utf8',
+                timeout: timeoutMs + 2000, maxBuffer: 2 * 1024 * 1024, signal: this.controller.signal,
+            }, (error, stdout, stderr) => {
+                if (error)
+                    reject(new Error(this.sanitize(`Cypress TAP ${action} failed: ${stderr || stdout || error.message}`).slice(0, 4000)));
+                else
+                    resolve(stdout);
+            });
+        });
+        // Cypress 16 emits this one non-JSON success response before the first open session.
+        if (action === 'sessions' && stdout.trim() === 'No running Cypress session found. Start Cypress in open mode (e.g. `cypress open`) and select a testing type to get started.')
+            return [];
+        try {
+            return JSON.parse(stdout);
+        }
+        catch {
+            throw new Error(`Cypress TAP ${action} returned invalid JSON.`);
+        }
+    }
+}

package/dist/src/runtime/redact.d.ts

@@ -0,0 +1,3 @@
+export declare function createRedactor(values?: Record<string, unknown>): (text: string) => string;
+export declare function projectRedactor(repoRoot: string): (text: string) => string;
+export declare function redactValue(value: unknown, sanitize?: (text: string) => string): any;

package/dist/src/runtime/redact.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const secretKey = /password|passwd|(?:^|_)pass(?:$|_)|token|secret|authorization|cookie|private.?key/i;
+export function createRedactor(values = {}) {
+    const secrets = Object.entries(values)
+        .filter(([key, value]) => secretKey.test(key) && typeof value === 'string' && value.length > 0)
+        .map(([, value]) => value).sort((a, b) => b.length - a.length);
+    return (text) => {
+        let result = text;
+        for (const secret of secrets)
+            result = result.split(secret).join('[redacted]');
+        return result
+            .replace(/\bBearer\s+[^\s"']+/gi, 'Bearer [redacted]')
+            .replace(/\b(https?:\/\/[^\s?#"']+)[?#][^\s"']*/gi, '$1')
+            .replace(/((?:password|passwd|token|secret|authorization|cookie)\s*[=:]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi, '$1[redacted]');
+    };
+}
+export function projectRedactor(repoRoot) {
+    let local = {};
+    const envPath = path.join(repoRoot, '.env');
+    if (fs.existsSync(envPath)) {
+        // Reuse the consumer's dotenv parser without loading secrets into this process's environment.
+        const require = createRequire(path.join(repoRoot, 'package.json'));
+        local = require('dotenv').parse(fs.readFileSync(envPath));
+    }
+    return createRedactor({ ...local, ...process.env });
+}
+export function redactValue(value, sanitize = createRedactor()) {
+    if (typeof value === 'string')
+        return sanitize(value);
+    if (Array.isArray(value))
+        return value.map((entry) => redactValue(entry, sanitize));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key, secretKey.test(key) ? '[redacted]' : redactValue(entry, sanitize),
+        ]));
+    }
+    return value;
+}

package/docs/superpowers/plans/2026-09-07-cypress-runtime.md

@@ -0,0 +1,42 @@
+# Integrated Cypress runtime
+
+**Goal:** one existing Overkill MCP connection can launch project tests, inspect the live Cypress browser, retain failure evidence, and compare repeat/retry outcomes.
+
+**Architecture:** keep stdio and existing analysis tools. A run manager invokes the project's interactive wrapper with an opt-in companion Cypress config. Native Node WebSocket connects to the run's Chrome debugging port. The support bridge captures failure DOM before cleanup; reports and logs belong to a unique run directory. Codex edits test files with its existing editor and reruns the selected spec.
+
+**Constraints:** preserve existing WSL wrapper edits; no commits, dependency installations, broad refactors, automatic publication, or changes to normal Cypress runs. One active managed run per checkout avoids collisions in legacy plugins. No secret-bearing config, headers, or bodies in default output.
+
+- [x] Runner agent: implement and check start/status/stop, bounded repeats, timeouts, strict spec paths, per-run artifacts, and optional companion config/wrapper support.
+- [x] Browser agent: implement and check CDP connection, AUT/runner contexts, DOM, console/network summaries, screenshots, evaluate, pause/resume, and cleanup.
+- [x] Root: implement and check failure capture, sanitized MCP output, tool registration, flakiness comparison, single-command setup, and workflow instructions.
+- [x] Integrate: build and run targeted protocol/lifecycle/security checks; execute an actual Cypress self-check and a suitable existing project spec; inspect real DOM, capture a deliberate failure and retry, then verify corrected rerun.
+- [x] Review: cross-review shared behavior, preserve pre-existing changes, update usage docs and report verified capabilities and practical limits.
+
+**Verification:** use installed TypeScript and test tools. If platform-specific test dependencies are unavailable, use Node's test runner for independent runtime checks and report the existing suite's limitation. Live testing must use the project wrapper and isolated diagnostic files.
+
+## Verification evidence
+
+- TypeScript typecheck and build passed.
+- 23 targeted Overkill checks passed: browser protocol, lifecycle/timeout/shutdown, capture/redaction, MCP registration and existing triage/tools; two project support capture checks passed; changed JavaScript passed formatting and targeted lint, and wrapper syntax passed `bash -n`.
+- Existing `criticalPathTests/stage1/[0]loginAndLogout.cy.js`: two tests passed through the managed wrapper.
+- `npm run mcp:check`: real MCP transport, pause gate/resume, live AUT DOM, screenshot image, browser evaluation, deliberate failed attempt, preserved DOM, successful retry classified flaky, and two independent corrected executions passed.
+- A new MCP client read the completed two-repeat archive successfully. Setup verified all 19 tools and registered the updated local checkout in Codex.
+- Review fixed actual Cypress `Your project`/`Your Spec` context selection, preserved filesystem paths when a credential coincides with a folder name, duplicate captures, shutdown/connect races, and moved generated self-check specs outside normal test discovery.
+- The existing dependency tree contains Windows-only Rollup/esbuild binaries. Targeted Vitest checks used already installed Linux packages through a temporary test-process resolver, without installing dependencies. The full existing suite was not green: baseline indexer checks depend on sibling frontend content and tsx-based handshake checks also hit that platform mismatch. The compiled production MCP and its real handshake/self-check passed without that workaround.
+
+
+## Cypress 16 / TAP release extension (1.3.0)
+
+The user approved preparing native Windows/Linux execution and TAP in parallel with the consumer Cypress 16 upgrade, including the necessary platform dependency installation. The original wrapper-only restriction above describes the first implementation, and is superseded for this release.
+
+- The managed runner now invokes the consumer's Cypress Node CLI directly, preserving spec bracket escaping, ports, opt-in configuration, retries/repeats, artifacts and CDP. It strips inherited Electron Node mode and stops the native Windows process tree or POSIX process group.
+- `mode: open` retains a managed session for TAP; one additional `cypress_tap` tool exposes sessions/status/specs/run/reporter/command/pin/dom/aria/inspect on the same stdio MCP. Run mode remains the path for independent repeats.
+- Session selection stays within the configured project. Rerun status rejects stale timestamps, incomplete/inconsistent result counts and zero executed tests. CLI calls use JSON, bounded time/output and separated arguments; the exact Cypress 16 plain-text no-session response is treated as an empty list.
+- Full verification is now green after making the six prior environment-dependent test failures deterministic with native paths and temporary CI/frontend fixtures. Production indexing and adapter behavior were unchanged.
+- Real Cypress 16 Linux verification passed the managed debug/failure/retry/corrected-repeat check and the open TAP failure → reporter → command → historical pin → DOM/ARIA/inspect → clear → corrected fresh pass check.
+- Native Windows Node 24.14 process-tree verification passed with actual `taskkill /T /F` and descendant PID checks. This verifies process handling; it is not a claim that every desktop/browser combination was exercised.
+- Package version is 1.3.0. The npm artifact includes runtime and TAP code without a sibling checkout, local caches, secrets or node_modules. No Git commit, tag or publication was performed.
+
+- Native Windows TAP initially exposed Node's `UV_HANDLE_CLOSING` shutdown assertion. Cypress 16 sends guest telemetry with `fetch` immediately before `process.exit`, matching nodejs/node#56645. Native A/B checks with piped, ignored and inherited stdin all failed before; all succeeded with `CYPRESS_DISABLE_GUEST_TELEMETRY=1`. Managed child environments now set that flag without changing the parent environment or ignoring CLI failures.
+
+- A later native corrected-rerun check reproduced the same Node assertion after TAP's local GraphQL `fetch`, even with telemetry disabled. The Windows TAP invocation now loads the public CLI in a small CommonJS bootstrap that sets `process.exitCode` instead of forcing `process.exit`. This lets pending work drain under the existing timeout and preserves nonzero failures; it does not patch Cypress, retry crashes, or discard stderr. The regression checks real subprocess argv, pending-work completion and both success/failure exit codes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mknrt/autotests-overkill",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "private": false,
   "type": "module",
   "description": "AI-assisted testing intelligence platform for autotests2, caseplatform-web, and CI artifacts",

package/skills/overkill-debug-failure/SKILL.md

@@ -1,13 +1,18 @@
 # overkill-debug-failure
 
-Goal: triage failed runs using real artifacts and metadata.
+Goal: debug Cypress through the integrated Overkill runtime using actual browser state, errors and artifacts.
 
 Workflow:
-1. Run `summarize_ci_context`.
-2. Run `triage_failed_run`.
-3. Run `build_rerun_scope`.
-4. If code changed recently, run `analyze_diff_impact`.
+0. For a local spec, use `start_cypress_run` and poll `get_cypress_run`. It launches the project's Cypress CLI natively on Windows or Linux with the opt-in adapter. Use `debug: true` for a pause before each test; use `inspect_cypress_browser` (`snapshot`, `screenshot`, `evaluate`, `pause`, `resume`) on that run. Live AUT context and the Cypress runner/spec contexts are distinct. Prefer captured failure DOM for pre-teardown state. Use bounded `repeats`/`retries` to investigate flakiness, and stop unused runs with `stop_cypress_run`.
+1. For completed Command Log and time travel, use `mode: "open"` (Cypress 15.21+, Chromium). Poll `get_cypress_run.tap` for `sessionId`/`requestId`, then `cypress_tap` status. Trust its fresh `verdict`, not the raw stage: `no_tests` is not a pass. Use reporter → command → pin → dom/aria/inspect; clear the pin afterward. TAP cannot inspect run mode. Open sessions stay alive until stop/timeout/disconnect; use `run` for a rerun and the new requestId, or managed run mode for independent repeats.
+2. Run `summarize_ci_context`.
+3. Run `triage_failed_run`.
+4. Run `build_rerun_scope`.
+5. If code changed recently, run `analyze_diff_impact`.
 
 Rules:
 - Separate artifact-backed hypotheses from generic guesses.
 - Mention screenshots, videos, or API captures explicitly when they inform the conclusion.
+- A completed process may contain failed tests. Read errors and attempt states; skipped tests and incomplete launches are not passes. Report observed flakiness without claiming small samples prove stability.
+- Search existing project helpers/selectors before changing a test. Codex edits files through its normal editor, then reruns the affected spec and checks lint. Do not weaken assertions to obtain a green result.
+- Keep credentials out of diagnostics. Browser evaluation can change state. Runtime launch/inspection is local Windows or Linux/WSL and needs no separate browser MCP. Managed runs stop when the MCP connection closes; completed archives can be read afterward.