@mknrt/autotests-overkill 1.2.2 → 1.2.5

package/README.md

@@ -15,7 +15,7 @@ Runtime requirement:
 - Knowledge-store-backed retrieval for asset search, area context, impact analysis, and blueprint support
 - Optional `fis_platform` backend knowledge through an evidence-driven `ApiDiscoveryCatalog`, `api-interaction` documents, and `backend-endpoint` contracts
 - Optional ReportPortal and GitLab adapters with graceful artifacts-first fallback
-- Codex plugin packaging via `.codex-plugin/plugin.json` and `.mcp.json`
+- Codex MCP setup for npm package usage and local checkout development
 
 ## Repository layout
 
@@ -48,7 +48,7 @@ Repository-local development:
 ## Daily workflow
 
 1. Refresh local knowledge with `npm run index`.
-2. Start the MCP server through the checked-in MCP manifest or by running `npx autotests-overkill mcp`.
+2. Start the MCP server through the consumer repository's `.codex/config.toml`, or run `npx autotests-overkill mcp` directly for manual checks.
 3. Use `find_frontend_contract`, `find_existing_test_assets`, and `generate_spec_blueprint` for a new feature draft.
 4. Use `review_test_draft` to critique a draft for reuse, selector stability, setup drift, and likely gap coverage before editing `autotests2`.
 5. Use `find_backend_test_context` when a request flow needs backend validation, params, async completion, or contract-drift evidence.
@@ -132,12 +132,22 @@ Every tool returns the same normalized shape:
 - `confidence`
 - `warnings`
 
-## Codex plugin packaging
+## Codex MCP setup
 
 This repository can be consumed either from a Git checkout or as a published npm package:
 
-- `.codex-plugin/plugin.json` exposes the plugin metadata
-- `.mcp.json` registers the local MCP server command for checkout-based usage
+- `.mcp.json` registers a local checkout MCP command only
 - `skills/` is auto-discovered as the bundled skill set
 
-See [consumer-integration.md](/C:/gitrep/autotests-overkill/docs/consumer-integration.md), [operator-cookbook.md](/C:/gitrep/autotests-overkill/docs/operator-cookbook.md), and [plugin-packaging.md](/C:/gitrep/autotests-overkill/docs/plugin-packaging.md) for setup details.
+For npm package consumers such as `autotests2`, prefer a project-local Codex config:
+
+```toml
+[mcp_servers.autotests-overkill]
+command = "node"
+args = ["./node_modules/@mknrt/autotests-overkill/dist/src/cli/runMcpServer.js"]
+enabled = true
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+See [consumer-integration.md](docs/consumer-integration.md), [operator-cookbook.md](docs/operator-cookbook.md), and [plugin-packaging.md](docs/plugin-packaging.md) for setup details.

package/dist/src/cli/runAcceptance.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { createRuntimeAppContext } from '../appContext.js';
 import { analyzeDiffImpact } from '../domain/analyzeDiffImpact.js';
 import { analyzeTestGaps } from '../domain/analyzeTestGaps.js';
@@ -35,7 +36,7 @@ export async function evaluateAcceptanceMode(mode, args, context) {
         };
     }
     if (mode === 'impact') {
-        const changedFile = args[0] ?? 'C:/gitrep/caseplatform-web/vcm/jqVCM/widget/caption/CaptionSingleton.ts';
+        const changedFile = args[0] ?? path.join(context.config.repos.caseplatformWeb, 'vcm/jqVCM/widget/caption/CaptionSingleton.ts');
         const impact = await analyzeDiffImpact({ changedFiles: [changedFile] }, context);
         return {
             mode,

package/dist/src/cli/runMcpServer.js

@@ -1,11 +1,46 @@
-import { createRuntimeAppContext } from '../appContext.js';
-import { runMcpServer } from '../mcp/server.js';
 import { formatRuntimeStartupError } from './runtimeStartupError.js';
 import { isDirectExecution } from './shared.js';
+let sqliteWarningSuppressionInstalled = false;
 export async function startMcpServer() {
+    suppressSqliteExperimentalWarning();
+    const [{ createRuntimeAppContext }, { runMcpServer }] = await Promise.all([
+        import('../appContext.js'),
+        import('../mcp/server.js'),
+    ]);
     const context = await createRuntimeAppContext();
     await runMcpServer(context);
 }
+function suppressSqliteExperimentalWarning() {
+    if (sqliteWarningSuppressionInstalled) {
+        return;
+    }
+    sqliteWarningSuppressionInstalled = true;
+    const originalEmitWarning = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...args) => {
+        if (isSqliteExperimentalWarning(warning, args)) {
+            return;
+        }
+        originalEmitWarning(warning, ...args);
+    });
+}
+function isSqliteExperimentalWarning(warning, args) {
+    const message = warning instanceof Error ? warning.message : warning;
+    const type = warning instanceof Error
+        ? warning.name
+        : readWarningType(args[0]);
+    return type === 'ExperimentalWarning'
+        && message.includes('SQLite is an experimental feature');
+}
+function readWarningType(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value && typeof value === 'object' && 'type' in value) {
+        const { type } = value;
+        return typeof type === 'string' ? type : undefined;
+    }
+    return undefined;
+}
 if (isDirectExecution(import.meta.url)) {
     try {
         await startMcpServer();

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

@@ -0,0 +1,23 @@
+import type { Readable, Writable } from 'node:stream';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Accepts both SDK newline-delimited stdio JSON-RPC and Content-Length framed MCP messages.
+ */
+export declare class FramingAwareStdioServerTransport implements Transport {
+    private readonly stdin;
+    private readonly stdout;
+    private readonly readBuffer;
+    private started;
+    private responseFraming;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(stdin?: Readable, stdout?: Writable);
+    private readonly ondata;
+    private readonly onstreamerror;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    private processReadBuffer;
+}

package/dist/src/mcp/framingAwareStdioTransport.js

@@ -0,0 +1,152 @@
+import process from 'node:process';
+import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+class FramingAwareReadBuffer {
+    buffer;
+    append(chunk) {
+        this.buffer = this.buffer ? Buffer.concat([this.buffer, chunk]) : chunk;
+    }
+    clear() {
+        this.buffer = undefined;
+    }
+    readMessage() {
+        if (!this.buffer || this.buffer.length === 0) {
+            return null;
+        }
+        if (startsWithContentLengthHeader(this.buffer)) {
+            return this.readContentLengthMessage();
+        }
+        return this.readNewlineMessage();
+    }
+    readNewlineMessage() {
+        if (!this.buffer) {
+            return null;
+        }
+        const newlineIndex = this.buffer.indexOf('\n');
+        if (newlineIndex === -1) {
+            return null;
+        }
+        const line = this.buffer.toString('utf8', 0, newlineIndex).replace(/\r$/, '');
+        this.buffer = this.buffer.subarray(newlineIndex + 1);
+        return {
+            message: deserializeMessage(line),
+            framing: 'newline',
+        };
+    }
+    readContentLengthMessage() {
+        if (!this.buffer) {
+            return null;
+        }
+        const header = findHeader(this.buffer);
+        if (!header) {
+            return null;
+        }
+        const headerText = this.buffer.toString('utf8', 0, header.endIndex);
+        const contentLength = parseContentLength(headerText);
+        if (contentLength === undefined) {
+            this.buffer = this.buffer.subarray(header.endIndex + header.separatorLength);
+            throw new Error('Invalid MCP stdio Content-Length header');
+        }
+        const bodyStart = header.endIndex + header.separatorLength;
+        const bodyEnd = bodyStart + contentLength;
+        if (this.buffer.length < bodyEnd) {
+            return null;
+        }
+        const body = this.buffer.toString('utf8', bodyStart, bodyEnd);
+        this.buffer = this.buffer.subarray(bodyEnd);
+        return {
+            message: deserializeMessage(body),
+            framing: 'content-length',
+        };
+    }
+}
+/**
+ * Accepts both SDK newline-delimited stdio JSON-RPC and Content-Length framed MCP messages.
+ */
+export class FramingAwareStdioServerTransport {
+    stdin;
+    stdout;
+    readBuffer = new FramingAwareReadBuffer();
+    started = false;
+    responseFraming = 'newline';
+    onclose;
+    onerror;
+    onmessage;
+    constructor(stdin = process.stdin, stdout = process.stdout) {
+        this.stdin = stdin;
+        this.stdout = stdout;
+    }
+    ondata = (chunk) => {
+        this.readBuffer.append(chunk);
+        this.processReadBuffer();
+    };
+    onstreamerror = (error) => {
+        this.onerror?.(error);
+    };
+    async start() {
+        if (this.started) {
+            throw new Error('FramingAwareStdioServerTransport already started');
+        }
+        this.started = true;
+        this.stdin.on('data', this.ondata);
+        this.stdin.on('error', this.onstreamerror);
+    }
+    async close() {
+        this.stdin.off('data', this.ondata);
+        this.stdin.off('error', this.onstreamerror);
+        if (this.stdin.listenerCount('data') === 0) {
+            this.stdin.pause();
+        }
+        this.readBuffer.clear();
+        this.onclose?.();
+    }
+    send(message) {
+        return new Promise((resolve) => {
+            const json = JSON.stringify(message);
+            const output = this.responseFraming === 'content-length'
+                ? `Content-Length: ${Buffer.byteLength(json, 'utf8')}\r\n\r\n${json}`
+                : `${json}\n`;
+            if (this.stdout.write(output)) {
+                resolve();
+            }
+            else {
+                this.stdout.once('drain', resolve);
+            }
+        });
+    }
+    processReadBuffer() {
+        while (true) {
+            try {
+                const parsed = this.readBuffer.readMessage();
+                if (parsed === null) {
+                    break;
+                }
+                this.responseFraming = parsed.framing;
+                this.onmessage?.(parsed.message);
+            }
+            catch (error) {
+                this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    }
+}
+function deserializeMessage(json) {
+    return JSONRPCMessageSchema.parse(JSON.parse(json));
+}
+function startsWithContentLengthHeader(buffer) {
+    return buffer.subarray(0, 'Content-Length:'.length).toString('utf8').toLowerCase() === 'content-length:';
+}
+function findHeader(buffer) {
+    const crlfIndex = buffer.indexOf('\r\n\r\n');
+    if (crlfIndex !== -1) {
+        return { endIndex: crlfIndex, separatorLength: 4 };
+    }
+    const lfIndex = buffer.indexOf('\n\n');
+    if (lfIndex !== -1) {
+        return { endIndex: lfIndex, separatorLength: 2 };
+    }
+    return undefined;
+}
+function parseContentLength(header) {
+    const match = /^Content-Length:\s*(\d+)\s*$/im.exec(header);
+    return match ? Number(match[1]) : undefined;
+}

package/dist/src/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { FramingAwareStdioServerTransport } from './framingAwareStdioTransport.js';
 import { buildToolRegistry } from './registerTools.js';
 export async function createMcpServer(context) {
     const server = new McpServer({
@@ -24,6 +24,6 @@ export async function createMcpServer(context) {
 }
 export async function runMcpServer(context) {
     const server = await createMcpServer(context);
-    const transport = new StdioServerTransport();
+    const transport = new FramingAwareStdioServerTransport();
     await server.connect(transport);
 }

package/docs/consumer-integration.md

@@ -9,7 +9,7 @@ Connect this package to `autotests2`, `caseplatform-web`, and CI artifacts witho
 - Local clone of `autotests2`
 - Local clone of `caseplatform-web`
 - Local Cypress artifacts or a synced CI artifact directory
-- Node.js 20+
+- Node.js 22.5+
 
 ## Setup
 
@@ -31,29 +31,28 @@ Connect this package to `autotests2`, `caseplatform-web`, and CI artifacts witho
 ## 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.
+2. Start the MCP server through a consumer-local Codex config or run `npx autotests-overkill mcp` directly for manual checks.
 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": "."
-    }
-  }
-}
+## Consumer-local Codex MCP example
+
+Create `.codex/config.toml` in the consumer repository:
+
+```toml
+[mcp_servers.autotests-overkill]
+command = "node"
+args = ["./node_modules/@mknrt/autotests-overkill/dist/src/cli/runMcpServer.js"]
+enabled = true
+startup_timeout_sec = 20
+tool_timeout_sec = 120
 ```
 
+Do not set `required = true` until the server has been verified locally. A required MCP server blocks Codex session startup if the package, Node.js runtime, or `overkill.config.json` is not ready.
+
+The command is intentionally relative to the consumer repository. It works in Windows or WSL as long as dependencies were installed in the same environment where Codex starts the server.
+
 Because the package is published publicly to npm, consumers do not need private registry setup to install it.
 
 ## CI integration notes

package/docs/operator-cookbook.md

@@ -37,7 +37,7 @@
 
 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.
+3. Let the client start MCP through the consumer repository's `.codex/config.toml` and use the acceptance commands to prove the installation against local data.
 
 ## Useful verification commands
 

package/docs/plugin-packaging.md

@@ -1,9 +1,8 @@
-# Codex Plugin Packaging
+# Codex MCP Packaging
 
-## Included plugin files
+## Included MCP files
 
-- `.codex-plugin/plugin.json` defines the plugin metadata
-- `.mcp.json` registers the local MCP server command
+- `.mcp.json` registers the local checkout MCP server command
 - `skills/` contains the bundled skill set used by Codex
 
 ## Local installation shape
@@ -13,10 +12,18 @@ 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`.
+4. Let Codex start the MCP server through `.mcp.json` when using the checkout directly.
 
-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`.
+For npm-installed usage inside a consumer repository, prefer a consumer-local `.codex/config.toml`:
+
+```toml
+[mcp_servers.autotests-overkill]
+command = "node"
+args = ["./node_modules/@mknrt/autotests-overkill/dist/src/cli/runMcpServer.js"]
+enabled = true
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
 
 ## MCP registration
 
@@ -24,7 +31,7 @@ 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`
+- cwd: `.`
 
 The server reads `overkill.config.json` from the repository root and keeps all writes inside `cacheDir`.
 

package/package.json

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

package/skills/overkill-onboard/SKILL.md

@@ -9,8 +9,9 @@ Start Here:
 4. Run `npm run build`.
 5. Run `npm run index`.
 6. Run `npm run mcp:smoke`.
-7. Use the checked-in `.mcp.json` manifest for client integration instead of `npm run mcp`, because stdio MCP servers must keep `stdout` clean.
-7. Run the acceptance commands against local repos.
+7. For npm package consumers, configure the consumer repository's `.codex/config.toml` to run `node ./node_modules/@mknrt/autotests-overkill/dist/src/cli/runMcpServer.js`.
+8. Use the checked-in `.mcp.json` only for local checkout development.
+9. Run the acceptance commands against local repos.
 
 Key Idea:
 - The platform analyzes and drafts; it does not silently edit consumer repos.

package/docs/audits/2026-04-20-iteration-1.md

@@ -1,251 +0,0 @@
-# Audit Iteration 1
-
-Date: 2026-04-20
-
-## Goal
-
-Evaluate the current state of `autotests-overkill` as a strong assistant for:
-
-- test design
-- test drafting
-- test debugging
-- coverage and impact analysis
-
-This first iteration focuses on architectural quality, product readiness, verification coverage, portability, and obvious drift risks.
-
-## Scope
-
-Reviewed:
-
-- product docs and positioning
-- MCP and CLI entrypoints
-- domain and indexing architecture
-- bundled skills
-- package and plugin manifests
-- current verification commands
-- representative tests
-
-Key files reviewed:
-
-- `README.md`
-- `package.json`
-- `.codex-plugin/plugin.json`
-- `.mcp.json`
-- `src/mcp/registerTools.ts`
-- `src/mcp/server.ts`
-- `src/indexer/refreshPipeline.ts`
-- `src/contracts/toolOutput.ts`
-- `src/contracts/confidence.ts`
-- `src/cli/runAcceptance.ts`
-- `docs/architecture/overview.md`
-
-## Verified State
-
-The following command was run during the audit:
-
-```bash
-npm run verify
-```
-
-Observed result:
-
-- TypeScript lint passed
-- Vitest suite passed
-- Build passed
-- `75` tests passed across `40` test files
-
-This means the repository is currently in a healthy technical state at the baseline verification level.
-
-## Strong Areas
-
-### 1. Clear architecture
-
-The project already has a strong boundary model:
-
-- connectors gather evidence
-- indexers normalize and persist it
-- domain services compose outputs
-- MCP exposes narrow, composable tools
-
-This is one of the strongest parts of the repository because it matches the actual product goal: helping an agent reason about tests without silently editing consumer repositories.
-
-Relevant files:
-
-- `docs/architecture/overview.md`
-- `src/indexer/refreshPipeline.ts`
-- `src/mcp/registerTools.ts`
-
-### 2. Strong normalized tool contract
-
-The unified output shape is a major strength:
-
-- `summary`
-- `evidence`
-- `recommended_actions`
-- `repo_paths`
-- `confidence`
-- `warnings`
-
-This makes the project much more reliable as an LLM-facing tool platform because every MCP tool returns a predictable structure.
-
-Relevant files:
-
-- `src/contracts/toolOutput.ts`
-- `src/contracts/confidence.ts`
-- `src/domain/shared.ts`
-
-### 3. Good product stance
-
-The platform consistently keeps the right operating boundary:
-
-- analyze
-- explain
-- draft
-- suggest
-- do not silently mutate consumer repositories
-
-That principle is visible in README, skills, and domain behavior. This is important because it makes the tool safer and more trustworthy in real engineering workflows.
-
-Relevant files:
-
-- `README.md`
-- `skills/overkill-generate-test/SKILL.md`
-- `skills/overkill-onboard/SKILL.md`
-
-### 4. Better-than-average verification mindset
-
-The project does not stop at unit-level checks. It already includes:
-
-- docs checks
-- packaging checks
-- MCP handshake coverage
-- acceptance-style checks for coverage, blueprint, failure triage, and impact analysis
-
-That is a strong base for a tool whose value is mostly in workflow quality and output usefulness.
-
-Relevant files:
-
-- `tests/mcp/stdioHandshake.test.ts`
-- `tests/docs/pluginManifest.test.ts`
-- `tests/docs/packageManifest.test.ts`
-- `tests/cli/runAcceptance.test.ts`
-
-## Weak Areas
-
-### 1. Release metadata drift
-
-There is already visible drift between package, plugin, and MCP metadata.
-
-Observed examples:
-
-- `package.json` version: `1.1.5`
-- `.codex-plugin/plugin.json` version: `1.1.0`
-- `src/mcp/server.ts` version: `1.1.0`
-
-There is also identity drift in plugin metadata:
-
-- plugin manifest still points to `openai.com`
-- plugin manifest still points to `https://github.com/openai/plugins`
-- plugin manifest still uses `OpenAI Codex` as project author/developer identity
-
-Why this matters:
-
-- packaging looks less trustworthy
-- plugin identity is partially incorrect
-- release information can become misleading for users and tooling
-
-Relevant files:
-
-- `package.json`
-- `.codex-plugin/plugin.json`
-- `src/mcp/server.ts`
-
-### 2. Poor portability
-
-The project currently contains machine-specific assumptions that reduce reliability outside the current workstation.
-
-Observed examples:
-
-- `.mcp.json` contains hardcoded `cwd: C:\\gitrep\\autotests-overkill`
-- docs repeat that exact local path
-- tests assert that exact path
-- test helpers assume `C:/gitrep/autotests2` and `C:/gitrep/caseplatform-web`
-
-Why this matters:
-
-- local checkout usage is brittle
-- plugin packaging is less reusable
-- tests are tightly coupled to one environment shape
-- onboarding quality drops sharply outside the author machine
-
-Relevant files:
-
-- `.mcp.json`
-- `docs/plugin-packaging.md`
-- `tests/docs/pluginManifest.test.ts`
-- `tests/helpers/testContext.ts`
-
-### 3. Verify command does not fully protect the product promise
-
-The docs position `mcp:smoke` and acceptance commands as important proof of installation and behavior, but `npm run verify` currently includes only:
-
-- lint
-- test
-- build
-
-This is not broken, but it does leave a gap between:
-
-- what the product says matters
-- what the main verification gate actually enforces
-
-Why this matters:
-
-- release confidence depends on social discipline instead of automation
-- MCP/package workflow regressions may survive longer than necessary
-- product-level trust is slightly weaker than the current architecture deserves
-
-Relevant files:
-
-- `README.md`
-- `docs/operator-cookbook.md`
-- `package.json`
-
-## Assessment
-
-This repository is already a strong first-generation foundation for an AI-assisted testing platform. Its strongest qualities are:
-
-- disciplined architecture
-- evidence-first tool outputs
-- strong problem framing
-- good initial verification culture
-
-Its most important current risks are not algorithmic quality failures or test instability. The higher-priority risks are:
-
-- release/metadata drift
-- portability problems
-- incomplete automation around product-level verification
-
-In other words: the core is promising, but the outer delivery shell is weaker than the inner design.
-
-## Recommended Next Iteration
-
-Recommended focus for the next improvement cycle:
-
-`operability / release integrity`
-
-That iteration should prioritize:
-
-1. Synchronizing package, plugin, and MCP versions and identity metadata
-2. Reducing machine-specific assumptions in MCP packaging and test setup
-3. Adding anti-drift checks so metadata divergence is caught automatically
-4. Strengthening the verification gate around packaging and MCP operability
-
-## Short Conclusion
-
-Iteration 1 verdict:
-
-- the project is technically healthy
-- the architecture is strong
-- the product direction is correct
-- the most valuable next work is not feature expansion
-- the most valuable next work is making the platform more portable, more release-safe, and harder to drift out of sync