@mknrt/autotests-overkill 1.2.0 → 1.2.1

package/README.md

@@ -2,6 +2,11 @@
 
 `Autotests Overkill` is a standalone AI-assisted testing platform for `autotests2`, `caseplatform-web`, optional `fis_platform` backend context, and CI artifacts. It is designed for Codex-style work: inspect existing coverage, extract frontend/backend contracts and runtime logic, generate draft specs, triage failures, and narrow rerun scope without silently mutating consumer repositories.
 
+Runtime requirement:
+
+- Node.js 22.5+ in both Windows and WSL environments
+- No native database addon is required; the knowledge store runs on the built-in `node:sqlite` module so the same package install works from either environment
+
 ## What v1.1 adds
 
 - Legacy widget contract extraction for files such as `dateRangeInput_control.js` and `dateRangeInput_singleton.js`
@@ -87,6 +92,11 @@ The platform reads `overkill.config.json` with these keys:
 
 The default path is local and artifacts-first. Missing ReportPortal or GitLab credentials do not break tools; the platform keeps using local stats, screenshots, videos, and captured API payloads.
 
+## Troubleshooting
+
+- If MCP or indexing fails with `ERR_UNKNOWN_BUILTIN_MODULE` for `node:sqlite`, your Node.js version is too old. Upgrade to Node.js 22.5 or newer in that environment.
+- If startup fails with `database is locked`, another process is already using the same cache database. Stop the competing process or configure a different `cacheDir`.
+
 ## Backend integration
 
 Backend indexing is discovery-first and evidence-driven, not hardcoded. The first bridge is an `ApiDiscoveryCatalog` built from `autotests2` support code such as request wrappers, endpoint constants, `cy.request`, `fetch`, `XMLHttpRequest`, and API capture helpers. Selected high-signal families become `api-interaction` documents with `normalizedPaths`, `consumerSignalIds`, `evidencePaths`, `confidence`, and `whySelected`.

package/dist/src/cli/indexKnowledge.js

@@ -1,5 +1,6 @@
 import { createRuntimeAppContext } from '../appContext.js';
 import { refreshKnowledge } from '../indexer/refreshPipeline.js';
+import { formatRuntimeStartupError } from './runtimeStartupError.js';
 import { isDirectExecution } from './shared.js';
 export async function runIndexKnowledge() {
     const context = await createRuntimeAppContext();
@@ -7,5 +8,11 @@ export async function runIndexKnowledge() {
     console.log(JSON.stringify(result, null, 2));
 }
 if (isDirectExecution(import.meta.url)) {
-    await runIndexKnowledge();
+    try {
+        await runIndexKnowledge();
+    }
+    catch (error) {
+        console.error(formatRuntimeStartupError('index', error));
+        process.exitCode = 1;
+    }
 }

package/dist/src/cli/runMcpServer.js

@@ -1,10 +1,17 @@
 import { createRuntimeAppContext } from '../appContext.js';
 import { runMcpServer } from '../mcp/server.js';
+import { formatRuntimeStartupError } from './runtimeStartupError.js';
 import { isDirectExecution } from './shared.js';
 export async function startMcpServer() {
     const context = await createRuntimeAppContext();
     await runMcpServer(context);
 }
 if (isDirectExecution(import.meta.url)) {
-    await startMcpServer();
+    try {
+        await startMcpServer();
+    }
+    catch (error) {
+        console.error(formatRuntimeStartupError('mcp', error));
+        process.exitCode = 1;
+    }
 }

package/dist/src/cli/runtimeStartupError.d.ts

@@ -0,0 +1,3 @@
+type StartupCommand = 'index' | 'mcp';
+export declare function formatRuntimeStartupError(command: StartupCommand, error: unknown): string;
+export {};

package/dist/src/cli/runtimeStartupError.js

@@ -0,0 +1,60 @@
+function asError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+}
+function detectStartupError(error) {
+    const code = 'code' in error ? String(error.code) : '';
+    const message = `${error.message}\n${error.stack ?? ''}`;
+    if (code === 'ERR_UNKNOWN_BUILTIN_MODULE'
+        && message.includes('node:sqlite')) {
+        return {
+            kind: 'unsupported-node-version',
+            summary: 'The current Node.js runtime does not provide the built-in node:sqlite module.',
+            recoverySteps: [
+                'Upgrade Node.js to version 22.5 or newer in the environment where the server will run.',
+                'After upgrading Node.js, reinstall dependencies in that same environment.',
+            ],
+        };
+    }
+    if (code === 'SQLITE_BUSY' || message.includes('database is locked')) {
+        return {
+            kind: 'sqlite-busy',
+            summary: 'The knowledge database is locked by another process.',
+            recoverySteps: [
+                'Stop other autotests-overkill indexing or MCP processes that use the same cache directory.',
+                'If you need concurrent sessions, point them to different `cacheDir` values in `overkill.config.json`.',
+            ],
+        };
+    }
+    return {
+        kind: 'unknown',
+        summary: error.message,
+        recoverySteps: [],
+    };
+}
+export function formatRuntimeStartupError(command, error) {
+    const normalized = asError(error);
+    const details = detectStartupError(normalized);
+    const lines = [
+        `Failed to start autotests-overkill ${command}.`,
+        details.summary,
+    ];
+    if (details.kind !== 'unknown') {
+        lines.push('');
+        lines.push('How to fix:');
+        for (const step of details.recoverySteps) {
+            lines.push(`- ${step}`);
+        }
+    }
+    lines.push('');
+    lines.push(`cwd: ${process.cwd()}`);
+    lines.push(`node: ${process.version}`);
+    if (normalized.stack) {
+        lines.push('');
+        lines.push('Original error:');
+        lines.push(normalized.stack);
+    }
+    return lines.join('\n');
+}

package/dist/src/indexer/extractors/backendContractExtractor.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 export function extractBackendContracts(input) {
     const documents = input.sources.flatMap((source) => extractRecordsFromSource(source));
     return {
@@ -26,7 +27,14 @@ function createRecord(source, httpMethod, endpointPath, body) {
     ].filter((value) => Boolean(value));
     const ruleHints = extractRuleHints(body);
     return {
-        id: `fis-platform:${source.matchedFamily}:${httpMethod ?? 'RESOURCE'}:${source.path}:${resolvedEndpointPath}`,
+        id: [
+            'fis-platform',
+            source.matchedFamily,
+            httpMethod ?? 'RESOURCE',
+            source.path,
+            resolvedEndpointPath,
+            crypto.createHash('sha1').update(body).digest('hex').slice(0, 12),
+        ].join(':'),
         title: `${httpMethod ? `${httpMethod} ` : ''}${resolvedEndpointPath}`,
         path: source.path,
         body,

package/dist/src/indexer/refreshPipeline.js

@@ -96,6 +96,7 @@ export async function refreshKnowledge(context) {
         }
         for (const record of apiInteractions.documents) {
             documents.push(documentFrom({
+                id: record.id,
                 sourceKind: record.sourceKind,
                 repoKind: record.repoKind,
                 path: record.path,
@@ -112,6 +113,7 @@ export async function refreshKnowledge(context) {
             snapshotStore.write('backend-contracts', backendContracts);
             for (const record of backendContracts.documents) {
                 documents.push(documentFrom({
+                    id: record.id,
                     sourceKind: record.sourceKind,
                     repoKind: record.repoKind,
                     path: record.path,
@@ -201,7 +203,12 @@ function repoState(root) {
 }
 function documentFrom(input) {
     return {
-        id: crypto.createHash('sha1').update(`${input.sourceKind}:${input.path}`).digest('hex'),
+        id: input.id ?? crypto.createHash('sha1').update([
+            input.repoKind,
+            input.sourceKind,
+            input.path,
+            input.title,
+        ].join(':')).digest('hex'),
         sourceKind: input.sourceKind,
         repoKind: input.repoKind,
         path: input.path,

package/dist/src/knowledge/database.d.ts

@@ -1,3 +1,3 @@
-import Database from 'better-sqlite3';
-export type KnowledgeDatabase = Database.Database;
+import { DatabaseSync } from 'node:sqlite';
+export type KnowledgeDatabase = DatabaseSync;
 export declare function createKnowledgeDatabase(filePath: string): KnowledgeDatabase;

package/dist/src/knowledge/database.js

@@ -1,8 +1,15 @@
-import Database from 'better-sqlite3';
+import { DatabaseSync } from 'node:sqlite';
 import { baseMigrations } from './migrations.js';
 export function createKnowledgeDatabase(filePath) {
-    const db = new Database(filePath);
-    db.pragma('journal_mode = WAL');
+    const db = new DatabaseSync(filePath);
+    // This database is a rebuildable cache, so we optimize for fast refreshes over crash durability.
+    db.exec(`
+    PRAGMA journal_mode = MEMORY;
+    PRAGMA synchronous = OFF;
+    PRAGMA temp_store = MEMORY;
+    PRAGMA cache_size = -20000;
+    PRAGMA busy_timeout = 5000;
+  `);
     db.exec(baseMigrations);
     return db;
 }

package/dist/src/knowledge/repositories.js

@@ -1,7 +1,11 @@
+const INSERT_DOCUMENT_SQL = `
+  INSERT INTO documents (id, source_kind, repo_kind, path, title, body, metadata_json, updated_at)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`;
+const INSERT_FTS_SQL = 'INSERT INTO documents_fts (id, path, title, body) VALUES (?, ?, ?, ?)';
 export function upsertDocuments(db, documents) {
     const upsertDocument = db.prepare(`
-    INSERT INTO documents (id, source_kind, repo_kind, path, title, body, metadata_json, updated_at)
-    VALUES (@id, @sourceKind, @repoKind, @path, @title, @body, @metadataJson, @updatedAt)
+    ${INSERT_DOCUMENT_SQL}
     ON CONFLICT(id) DO UPDATE SET
       source_kind = excluded.source_kind,
       repo_kind = excluded.repo_kind,
@@ -12,35 +16,32 @@ export function upsertDocuments(db, documents) {
       updated_at = excluded.updated_at
   `);
     const deleteFts = db.prepare('DELETE FROM documents_fts WHERE id = ?');
-    const insertFts = db.prepare('INSERT INTO documents_fts (id, path, title, body) VALUES (?, ?, ?, ?)');
-    const transaction = db.transaction((records) => {
-        for (const record of records) {
-            upsertDocument.run(record);
+    const insertFts = db.prepare(INSERT_FTS_SQL);
+    runInTransaction(db, () => {
+        for (const record of documents) {
+            upsertDocument.run(record.id, record.sourceKind, record.repoKind, record.path, record.title, record.body, record.metadataJson, record.updatedAt);
             deleteFts.run(record.id);
             insertFts.run(record.id, record.path, record.title, record.body);
         }
     });
-    transaction(documents);
 }
 export function syncDocumentsByRepoKinds(db, documents, repoKinds) {
-    upsertDocuments(db, documents);
     const normalizedRepoKinds = [...new Set(repoKinds)];
-    const selectIds = db.prepare('SELECT id FROM documents WHERE repo_kind = ?');
-    const deleteDocument = db.prepare('DELETE FROM documents WHERE id = ?');
-    const deleteFts = db.prepare('DELETE FROM documents_fts WHERE id = ?');
-    const transaction = db.transaction(() => {
-        for (const repoKind of normalizedRepoKinds) {
-            const desiredIds = new Set(documents.filter((record) => record.repoKind === repoKind).map((record) => record.id));
-            const existingIds = selectIds.all(repoKind);
-            for (const row of existingIds) {
-                if (!desiredIds.has(row.id)) {
-                    deleteDocument.run(row.id);
-                    deleteFts.run(row.id);
-                }
-            }
+    const insertDocument = db.prepare(INSERT_DOCUMENT_SQL);
+    const insertFts = db.prepare(INSERT_FTS_SQL);
+    runInTransaction(db, () => {
+        if (normalizedRepoKinds.length > 0) {
+            const placeholders = normalizedRepoKinds.map(() => '?').join(', ');
+            db.prepare(`DELETE FROM documents_fts WHERE id IN (SELECT id FROM documents WHERE repo_kind IN (${placeholders}))`)
+                .run(...normalizedRepoKinds);
+            db.prepare(`DELETE FROM documents WHERE repo_kind IN (${placeholders})`)
+                .run(...normalizedRepoKinds);
+        }
+        for (const record of documents) {
+            insertDocument.run(record.id, record.sourceKind, record.repoKind, record.path, record.title, record.body, record.metadataJson, record.updatedAt);
+            insertFts.run(record.id, record.path, record.title, record.body);
         }
     });
-    transaction();
 }
 export function countDocuments(db) {
     const row = db.prepare('SELECT COUNT(*) AS count FROM documents').get();
@@ -76,3 +77,14 @@ function normalizeFtsQuery(query) {
         .map((token) => `"${token.replaceAll('"', '""')}"`)
         .join(' OR ');
 }
+function runInTransaction(db, operation) {
+    db.exec('BEGIN');
+    try {
+        operation();
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}

package/docs/superpowers/plans/2026-04-19-autotests-overkill-v1.md

@@ -6,7 +6,7 @@
 
 **Architecture:** The repository will be a TypeScript Node.js workspace with a thin MCP server over focused domain services. Data flows through configurable connectors into a SQLite + FTS knowledge store plus JSON snapshots; each MCP tool is a small orchestration layer over reusable analyzers, not a monolithic “smart tool”. Skills and prompt templates sit on top of tool contracts, while integration docs and sample consumer config keep `autotests2` as a consumer, not a host.
 
-**Tech Stack:** Node.js, TypeScript, `@modelcontextprotocol/server`, `zod`, `better-sqlite3`, SQLite FTS5, `fast-glob`, `typescript`, `tsx`, `vitest`
+**Tech Stack:** Node.js, TypeScript, `@modelcontextprotocol/server`, `zod`, built-in `node:sqlite`, SQLite FTS5, `fast-glob`, `typescript`, `tsx`, `vitest`
 
 ---
 

package/docs/superpowers/plans/2026-04-20-fis-platform-backend-integration.md

@@ -6,7 +6,7 @@
 
 **Architecture:** Extend the existing `connectors -> extractors -> SQLite FTS -> domain -> MCP tools` pipeline with one explicit bridge object, `ApiDiscoveryCatalog`, plus two narrow knowledge layers: `api-interaction` and `backend-contract`. Build the catalog from `autotests2` support code first, pass it into `fis_platform` backend discovery explicitly, then store only evidence-backed documents with confidence metadata. Runtime API captures stay on-demand triage evidence in iteration 1; persistent runtime observation indexing is deferred until static interaction indexing proves useful.
 
-**Tech Stack:** TypeScript, Node.js, Zod, better-sqlite3/FTS5, Vitest, MCP SDK, Java source parsing via regex/structured text extraction.
+**Tech Stack:** TypeScript, Node.js, Zod, built-in node:sqlite/FTS5, Vitest, MCP SDK, Java source parsing via regex/structured text extraction.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mknrt/autotests-overkill",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "private": false,
   "type": "module",
   "description": "AI-assisted testing intelligence platform for autotests2, caseplatform-web, and CI artifacts",
@@ -15,7 +15,7 @@
     "url": "git+https://github.com/iamknrt/autotests-overkill.git"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.5.0"
   },
   "bin": {
     "autotests-overkill": "./bin/autotests-overkill.js"
@@ -61,12 +61,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.0",
-    "better-sqlite3": "^12.6.2",
     "fast-glob": "^3.3.3",
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^22.15.3",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",