@mknrt/autotests-overkill 1.1.0

package/dist/src/mcp/registerTools.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { analyzeDiffImpact } from '../domain/analyzeDiffImpact.js';
+import { analyzeTestGaps } from '../domain/analyzeTestGaps.js';
+import { buildRerunScope } from '../domain/buildRerunScope.js';
+import { buildSetupTeardownPlan } from '../domain/buildSetupTeardownPlan.js';
+import { findExistingTestAssets } from '../domain/findExistingTestAssets.js';
+import { findFrontendContract } from '../domain/findFrontendContract.js';
+import { findFrontendRuntimeLogic } from '../domain/findFrontendRuntimeLogic.js';
+import { findTestAreaContext } from '../domain/findTestAreaContext.js';
+import { generateSpecBlueprint } from '../domain/generateSpecBlueprint.js';
+import { mapFeatureToExistingCoverage } from '../domain/mapFeatureToExistingCoverage.js';
+import { recommendSelectorStrategy } from '../domain/recommendSelectorStrategy.js';
+import { summarizeCiContext } from '../domain/summarizeCiContext.js';
+import { triageFailedRun } from '../domain/triageFailedRun.js';
+import { toolOutputSchema } from '../contracts/toolOutput.js';
+export function buildToolRegistry() {
+    return [
+        {
+            name: 'find_existing_test_assets',
+            description: 'Finds reusable specs, commands, helpers, and selectors in autotests2.',
+            inputSchema: z.object({ query: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: findExistingTestAssets,
+        },
+        {
+            name: 'find_test_area_context',
+            description: 'Returns conventions, init patterns, and area context for constructor or formRunner.',
+            inputSchema: z.object({ area: z.string().optional(), feature: z.string().optional() }),
+            outputSchema: toolOutputSchema,
+            execute: findTestAreaContext,
+        },
+        {
+            name: 'find_frontend_contract',
+            description: 'Extracts widget properties, events, methods, and source evidence from caseplatform-web.',
+            inputSchema: z.object({ widget: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: findFrontendContract,
+        },
+        {
+            name: 'find_frontend_runtime_logic',
+            description: 'Extracts runtime branches, transitions, and event wiring for a widget.',
+            inputSchema: z.object({ widget: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: findFrontendRuntimeLogic,
+        },
+        {
+            name: 'map_feature_to_existing_coverage',
+            description: 'Maps a feature or widget to existing coverage in autotests2.',
+            inputSchema: z.object({ widget: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: mapFeatureToExistingCoverage,
+        },
+        {
+            name: 'analyze_test_gaps',
+            description: 'Highlights likely uncovered runtime methods, events, and branches.',
+            inputSchema: z.object({ widget: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: analyzeTestGaps,
+        },
+        {
+            name: 'generate_spec_blueprint',
+            description: 'Builds a draft spec blueprint using existing project patterns.',
+            inputSchema: z.object({ feature: z.string().min(1), area: z.string().optional() }),
+            outputSchema: toolOutputSchema,
+            execute: generateSpecBlueprint,
+        },
+        {
+            name: 'recommend_selector_strategy',
+            description: 'Recommends stable selectors and project helper usage for a feature.',
+            inputSchema: z.object({ feature: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: recommendSelectorStrategy,
+        },
+        {
+            name: 'build_setup_teardown_plan',
+            description: 'Builds a reuse-first setup and teardown plan.',
+            inputSchema: z.object({ area: z.string().min(1), feature: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: buildSetupTeardownPlan,
+        },
+        {
+            name: 'analyze_diff_impact',
+            description: 'Maps changed files to affected tests and risk areas.',
+            inputSchema: z.object({ changedFiles: z.array(z.string()).min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: analyzeDiffImpact,
+        },
+        {
+            name: 'triage_failed_run',
+            description: 'Analyzes failed run artifacts and returns evidence-backed hypotheses.',
+            inputSchema: z.object({
+                statsFile: z.string().min(1),
+                screenshotsRoot: z.string().min(1),
+                videosRoot: z.string().min(1),
+                apiCaptureRoot: z.string().min(1),
+            }),
+            outputSchema: toolOutputSchema,
+            execute: triageFailedRun,
+        },
+        {
+            name: 'build_rerun_scope',
+            description: 'Builds a minimal rerun scope from changed files and failed specs.',
+            inputSchema: z.object({
+                changedFiles: z.array(z.string()).optional(),
+                statsFile: z.string().min(1),
+            }),
+            outputSchema: toolOutputSchema,
+            execute: buildRerunScope,
+        },
+        {
+            name: 'summarize_ci_context',
+            description: 'Summarizes CI stats, launch metadata, and artifact availability.',
+            inputSchema: z.object({ statsFile: z.string().min(1) }),
+            outputSchema: toolOutputSchema,
+            execute: summarizeCiContext,
+        },
+    ];
+}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AppContext } from '../appContext.js';
+export declare function createMcpServer(context: AppContext): Promise<McpServer>;
+export declare function runMcpServer(context: AppContext): Promise<void>;

package/dist/src/mcp/server.js

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildToolRegistry } from './registerTools.js';
+export async function createMcpServer(context) {
+    const server = new McpServer({
+        name: 'autotests-ultimate-testing-overkill',
+        version: '1.1.0',
+    });
+    for (const tool of buildToolRegistry()) {
+        server.registerTool(tool.name, {
+            title: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+        }, async (args) => {
+            const structuredContent = await tool.execute(args, context);
+            return {
+                content: [{ type: 'text', text: structuredContent.summary }],
+                structuredContent,
+            };
+        });
+    }
+    return server;
+}
+export async function runMcpServer(context) {
+    const server = await createMcpServer(context);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/utils/fileUtils.d.ts

@@ -0,0 +1,4 @@
+export declare function readTextIfExists(filePath: string): string;
+export declare function ensureDirectory(directoryPath: string): void;
+export declare function writeJson(filePath: string, value: unknown): void;
+export declare function readJson<T>(filePath: string): T;

package/dist/src/utils/fileUtils.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+export function readTextIfExists(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return '';
+    }
+    return fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '');
+}
+export function ensureDirectory(directoryPath) {
+    fs.mkdirSync(directoryPath, { recursive: true });
+}
+export function writeJson(filePath, value) {
+    fs.writeFileSync(filePath, JSON.stringify(value, null, 2), 'utf8');
+}
+export function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}

package/dist/src/utils/pathUtils.d.ts

@@ -0,0 +1,7 @@
+export declare function toPosixPath(value: string): string;
+export declare function unique<T>(items: T[]): T[];
+export declare function pathIncludes(pathValue: string, query: string): boolean;
+export declare function safeRelative(from: string, to: string): string;
+export declare function basenameWithoutExt(filePath: string): string;
+export declare function widgetNameCandidates(widgetHint: string): string[];
+export declare function featureNameCandidates(featureHint: string): string[];

package/dist/src/utils/pathUtils.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+export function toPosixPath(value) {
+    return value.replaceAll('\\', '/');
+}
+export function unique(items) {
+    return [...new Set(items)];
+}
+export function pathIncludes(pathValue, query) {
+    return toPosixPath(pathValue).toLowerCase().includes(query.toLowerCase());
+}
+export function safeRelative(from, to) {
+    return toPosixPath(path.relative(from, to));
+}
+export function basenameWithoutExt(filePath) {
+    return path.basename(filePath, path.extname(filePath));
+}
+export function widgetNameCandidates(widgetHint) {
+    const clean = widgetHint.trim();
+    const pascal = clean
+        .replace(/[_\-]+/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+    return unique([clean, clean.toLowerCase(), pascal, `${pascal}s`]);
+}
+export function featureNameCandidates(featureHint) {
+    const clean = featureHint.trim();
+    const normalized = clean
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/[_\-]+/g, ' ')
+        .trim();
+    const parts = normalized.split(/\s+/).filter(Boolean);
+    const pascal = parts.map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+    const lowerJoined = parts.join('').toLowerCase();
+    const singular = lowerJoined.endsWith('s') && lowerJoined.length > 4 ? lowerJoined.slice(0, -1) : lowerJoined;
+    const capitalizedSingular = singular ? singular[0].toUpperCase() + singular.slice(1) : '';
+    const candidates = [
+        clean,
+        clean.toLowerCase(),
+        normalized,
+        normalized.toLowerCase(),
+        lowerJoined,
+        singular,
+        pascal,
+        capitalizedSingular,
+        singular ? `${singular}s` : '',
+    ];
+    if (/error/i.test(clean)) {
+        candidates.push('apperror', 'AppError', 'ErrorTree', 'ErrorsGrid', 'validate');
+    }
+    if (/application|app/i.test(clean)) {
+        candidates.push('application', 'Application');
+    }
+    if (/process/i.test(clean)) {
+        candidates.push('process', 'Process');
+    }
+    return unique(candidates.filter(Boolean));
+}

package/dist/src/utils/textUtils.d.ts

@@ -0,0 +1,3 @@
+export declare function truncate(value: string, maxLength?: number): string;
+export declare function extractMatches(source: string, expression: RegExp): string[];
+export declare function scoreTextMatch(source: string, query: string): number;

package/dist/src/utils/textUtils.js

@@ -0,0 +1,26 @@
+export function truncate(value, maxLength = 220) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength - 3)}...`;
+}
+export function extractMatches(source, expression) {
+    const results = [];
+    let match;
+    const regex = new RegExp(expression.source, expression.flags.includes('g') ? expression.flags : `${expression.flags}g`);
+    while ((match = regex.exec(source)) !== null) {
+        if (match[1]) {
+            results.push(match[1]);
+        }
+    }
+    return results;
+}
+export function scoreTextMatch(source, query) {
+    const normalizedSource = source.toLowerCase();
+    const normalizedQuery = query.toLowerCase();
+    if (normalizedSource.includes(normalizedQuery)) {
+        return 2;
+    }
+    const queryTokens = normalizedQuery.split(/[\s_\-/]+/).filter(Boolean);
+    return queryTokens.reduce((score, token) => score + (normalizedSource.includes(token) ? 1 : 0), 0);
+}

package/docs/architecture/overview.md

@@ -0,0 +1,31 @@
+# Architecture Overview
+
+## Boundaries
+
+- `autotests-overkill` is the platform repository.
+- `autotests2` is a consumer and evidence source.
+- `caseplatform-web` is a frontend knowledge source.
+- CI artifacts are ingested as data, not treated as source code.
+
+## Runtime Model
+
+1. Consumer config points to repo roots and CI artifacts.
+2. Connectors scan those sources without mutating them.
+3. Extractors normalize test assets, frontend contracts, runtime signals, and CI context.
+4. The refresh pipeline stores searchable documents in SQLite + FTS and writes JSON snapshots under `.overkill-cache`.
+5. Domain services compose evidence into normalized tool outputs.
+6. The MCP server exposes those services as independent tools for Codex.
+
+## Design Decisions
+
+- TypeScript is used for explicit contracts and maintainability.
+- SQLite + FTS gives fast local retrieval without requiring vector infrastructure.
+- Tools are intentionally narrow and composable.
+- Skills are documentation/orchestration layers; they do not bypass tool contracts.
+- Consumer repositories stay read-only by default from the platform point of view.
+
+## v1 Limitations
+
+- Extractors are structural and regex-based rather than AST-complete.
+- ReportPortal and GitLab integrations are config-ready but optional; local artifact analysis is the default path.
+- Diff impact relies on naming and path heuristics, which is acceptable for v1 but should be hardened with richer relation indexing later.

package/docs/consumer-integration.md

@@ -0,0 +1,64 @@
+# Consumer Integration
+
+## Goal
+
+Connect this package to `autotests2`, `caseplatform-web`, and CI artifacts without moving platform logic into those repositories.
+
+## Prerequisites
+
+- Local clone of `autotests2`
+- Local clone of `caseplatform-web`
+- Local Cypress artifacts or a synced CI artifact directory
+- Node.js 20+
+
+## Setup
+
+1. Install the package with `npm install -D @mknrt/autotests-overkill`.
+2. Copy `node_modules/@mknrt/autotests-overkill/overkill.config.example.json` to `overkill.config.json`.
+3. Point `repos.autotests2` to the local `autotests2` clone.
+4. Point `repos.caseplatformWeb` to the local `caseplatform-web` clone.
+5. Point `ci.artifactsRoot` to the local Cypress artifact root, usually `../autotests2/cypress`.
+6. Optionally set `ci.reportPortal.*` and `ci.gitlab.*` for live CI enrichment.
+7. Run `npx autotests-overkill index`.
+
+## Integration contract
+
+- The platform core stays in this repository.
+- `autotests2` remains the consumer and reuse source for commands, helpers, selectors, and spec patterns.
+- `caseplatform-web` remains the frontend knowledge source.
+- Consumer repositories are not mutated unless an operator explicitly copies a generated draft into them.
+
+## Recommended operator flow
+
+1. Run `npx autotests-overkill index` after fresh pulls or artifact sync.
+2. Start the MCP server through a consumer-local MCP manifest or run `npx autotests-overkill mcp` directly.
+3. Use the bundled skills or direct MCP tools to gather context.
+4. Review the generated blueprint, gap analysis, or failure triage.
+5. Apply test edits manually in `autotests2` only after review.
+
+## Consumer-local MCP example
+
+Create `.mcp.json` in the consumer repository:
+
+```json
+{
+  "mcpServers": {
+    "autotests-overkill": {
+      "command": "node",
+      "args": [
+        "./node_modules/@mknrt/autotests-overkill/dist/src/cli/runMcpServer.js"
+      ],
+      "cwd": "."
+    }
+  }
+}
+```
+
+Because the package is published publicly to npm, consumers do not need private registry setup to install it.
+
+## CI integration notes
+
+- Local artifacts stay the default source of truth.
+- ReportPortal and GitLab are optional enrichment layers.
+- If tokens, project IDs, or CI metadata are missing, the platform stays operational and emits warnings instead of failing.
+- Re-run `npx autotests-overkill index` after syncing fresh artifacts if you want the knowledge cache refreshed before analysis.

package/docs/operator-cookbook.md

@@ -0,0 +1,39 @@
+# Operator Cookbook
+
+## Generate a draft test
+
+1. Run `find_existing_test_assets` for the target widget or feature.
+2. Run `find_frontend_contract`.
+3. Run `find_frontend_runtime_logic`.
+4. Run `generate_spec_blueprint`.
+5. Review reuse candidates, setup hints, and selector guidance before editing `autotests2`.
+
+## Find coverage gaps
+
+1. Run `map_feature_to_existing_coverage`.
+2. Run `analyze_test_gaps`.
+3. Run `recommend_selector_strategy`.
+4. Run `build_setup_teardown_plan`.
+
+## Triage a failed run
+
+1. Run `summarize_ci_context`.
+2. Run `triage_failed_run`.
+3. Run `build_rerun_scope`.
+4. If frontend files changed, run `analyze_diff_impact`.
+
+## Onboard a new engineer
+
+1. Start with `skills/overkill-onboard/SKILL.md`.
+2. Confirm that `overkill.config.json` points to real repo paths.
+3. Let the client start MCP through `.mcp.json` and use the acceptance commands to prove the installation against local data.
+
+## Useful verification commands
+
+- `npm run verify`
+- `npm run mcp:smoke`
+- `npm run acceptance:coverage`
+- `npm run acceptance:coverage:legacy`
+- `npm run acceptance:blueprint`
+- `npm run acceptance:failure`
+- `npm run acceptance:impact`

package/docs/plugin-packaging.md

@@ -0,0 +1,33 @@
+# Codex Plugin Packaging
+
+## Included plugin files
+
+- `.codex-plugin/plugin.json` defines the plugin metadata
+- `.mcp.json` registers the local MCP server command
+- `skills/` contains the bundled skill set used by Codex
+
+## Local installation shape
+
+The repository is self-contained for local checkout-based Codex usage:
+
+1. Keep the repository checked out locally.
+2. Ensure `npm install` has been run once.
+3. Create `overkill.config.json`.
+4. Let Codex discover `.codex-plugin/plugin.json`.
+5. Let Codex start the MCP server through `.mcp.json`.
+
+For npm-installed usage inside a consumer repository, prefer a consumer-local `.mcp.json` that points to `./node_modules/@mknrt/autotests-overkill/dist/src/cli/runMcpServer.js`.
+
+## MCP registration
+
+The local MCP definition starts the server through:
+
+- command: `node`
+- args: `./node_modules/tsx/dist/cli.mjs`, `src/cli/runMcpServer.ts`
+- cwd: `C:\gitrep\autotests-overkill`
+
+The server reads `overkill.config.json` from the repository root and keeps all writes inside `cacheDir`.
+
+## Skills discovery
+
+The plugin manifest points `skills` to `./skills/`, so bundled skills such as `overkill-generate-test`, `overkill-find-gaps`, and `overkill-debug-failure` can be discovered without copying files elsewhere.