tewip-ai 0.23.0 → 0.24.0

package/README.md

@@ -8,7 +8,7 @@ It works for every stack: Node.js (node:test, Jest, Vitest, Mocha), Python (pyte
 |---|---|
 | **Terminal** | `npm install -g tewip-ai`, then `tewip explain report.xml`, `tewip ci owner/repo --pr 12`, `tewip mcp` |
 | **VS Code, Cursor, Windsurf, VSCodium** | the Tewip extension ([download](https://github.com/hmamut39/tewip/releases/tag/vscode-0.5.0)): registers Tewip with the editor's AI assistant and adds six commands - explain a report, why CI failed on this branch, the risk review of your change, which flaky tests to quarantine, the security check, and what your corrections add up to |
-| **JetBrains, Claude, other AI assistants** | add the MCP server `tewip mcp` (see [editor setup](#use-it-from-your-editor-any-ide-that-speaks-mcp)) |
+| **JetBrains, Claude, other AI assistants** | add the MCP server `tewip mcp`: fifteen tools, including *has this happened here before?*, *is this requirement covered and passing?* and *what should be done next about this goal?* (see [editor setup](#use-it-from-your-editor-any-ide-that-speaks-mcp)) |
 | **Any model** | OpenAI, Claude, Gemini, Azure, or a model on your own machine with Ollama (no account, nothing leaves the computer): `TEWIP_PROVIDER` |
 | **GitHub CI** | the Tewip Action: a comment on every pull request, an optional merge gate, verified fix PRs ([QUICKSTART](QUICKSTART.md)) |
 
@@ -71,6 +71,10 @@ On every run, the action:
 - **Developers:** posts one diagnosis comment on the pull request and keeps it updated. For each failure it says whether the change likely caused it, why, and what to do next.
 - **SDETs:** writes the triage board into the job summary.
 - **DevOps:** collects environment failures (server errors, connection resets, outages) in **one** GitHub issue, and each new run adds a single grouped comment to it.
+- **Evidence, every run:** the Action writes an attestation into its artifact - the claims with
+  their evidence and which layer decided each, what Tewip **refused** to decide, and what it did
+  not check at all. Nothing enters it that Tewip did not verify itself, so a release decision can
+  be taken from it without opening CI.
 - **Fixes (`autofix: true`):** for drifted locators that the deterministic rule matched to a renamed element, it rewrites the locator, re-runs that test, and opens a separate pull request with the changes that passed. It never merges and never edits application code.
 - **Every role:** uploads all role views as the `tewip-report` artifact.
 - **When the job dies before any test runs** (an image that would not pull, a runner out of disk, a service container that never came up): it reads the failed job's log and names the cause, instead of leaving a red X with no explanation.

package/dist/cli/help.js

@@ -125,10 +125,14 @@ Usage:
                                     it fails for the incident's own reason. A test that passes, or
                                     fails its own way, is reported and thrown away.
   tewip attest [--run <id>] [--out attestation.md] [--json bundle.json]
+  tewip attest --verify <bundle.json> [--key <public.pem>]
                                     What Tewip checked for a build, as one artifact: the claims with
                                     their evidence and which layer decided each, what it refused to
                                     decide and why, and what it did not check at all. Nothing enters
-                                    it that Tewip did not verify itself. No model, no cost.
+                                    it that Tewip did not verify itself. Every bundle carries a
+                                    digest; set TEWIP_ATTEST_KEY to an ed25519 private key to sign
+                                    it too. --verify says what it checked and what that does not
+                                    establish - a digest means undamaged, not unedited. No cost.
   tewip mcp                         Serve Tewip over MCP (stdio) for an editor or AI assistant.
   tewip --version                   Print the version.
 

package/dist/cli/tewip.js

@@ -210,6 +210,15 @@ async function main() {
             return;
         }
         case 'attest': {
+            const verify = flag(args, 'verify');
+            if (verify) {
+                const { verifyAttestation } = await import('../engine/attest/attest-command.js');
+                const { ok, report } = verifyAttestation(verify, flag(args, 'key'));
+                console.log(report);
+                if (!ok)
+                    process.exitCode = 1;
+                return;
+            }
             const { runAttest } = await import('../engine/attest/attest-command.js');
             runAttest({ root: process.cwd(), name: flag(args, 'name'), runId: flag(args, 'run'), out: flag(args, 'out'), json: flag(args, 'json') });
             return;

package/dist/engine/attest/attest-command.js

@@ -1,9 +1,32 @@
 // `tewip attest`: the evidence for one run, as an artifact a build can carry.
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { datasetFiles, readJsonl, readTriageRecords } from '../../reporters/store.js';
 import { ENGINE_VERSION } from '../engine.js';
 import { attestRun, renderAttestation } from './attest.js';
+import { check } from './seal.js';
+/**
+ * Checks a bundle somebody was handed. It reports what the check establishes and, just as
+ * importantly, what it does not: a digest that matches proves the file is undamaged, and only a
+ * signature checked against a key says who made it.
+ */
+export function verifyAttestation(file, keyFile) {
+    const bundle = JSON.parse(readFileSync(resolve(file), 'utf8'));
+    const publicKey = keyFile ? readFileSync(resolve(keyFile), 'utf8') : undefined;
+    const checked = check(bundle, publicKey);
+    const ok = checked.contentMatches && checked.signature !== 'invalid';
+    const report = [
+        `# ${ok ? 'Checked' : 'Do not trust this bundle'}: ${file.split(/[\/]/).pop()}`,
+        '',
+        `Content matches its digest: ${checked.contentMatches ? 'yes' : 'NO'}`,
+        `Signature: ${checked.signature.replace(/-/g, ' ')}`,
+        '',
+        checked.says + '.',
+        '',
+        ...(checked.signature === 'no-key-given' ? ['Pass `--key <public.pem>` to check the signature itself.'] : []),
+    ].join(String.fromCharCode(10));
+    return { ok, report };
+}
 /** Everything Tewip kept for one project, newest run last. */
 function history(root, only) {
     const dir = join(root, '.tewip', 'history');

package/dist/engine/attest/attest.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { seal } from './seal.js';
 const sourceOf = (record) => String(record.diagnosis?.source ?? '');
 /** The evidence line a person reads: the first thing the deciding layer actually said. */
 function evidenceOf(record) {
@@ -33,7 +35,7 @@ export function attestRun(project, run, records, { checked, notChecked, tool, en
             confidence: Number(diagnosis?.confidence ?? 0),
         });
     }
-    return {
+    const bundle = {
         project,
         commit: run.gitSha ?? '',
         runId: run.runId,
@@ -47,6 +49,22 @@ export function attestRun(project, run, records, { checked, notChecked, tool, en
         refusals,
         producedBy: { tool, engine, at: new Date().toISOString() },
     };
+    // Sealed last, over everything above: the digest is of the content, never of itself.
+    return { ...bundle, seal: seal(bundle, signingKey()) };
+}
+/** The Ed25519 private key to sign with, from TEWIP_ATTEST_KEY: a PEM, or a path to one. */
+function signingKey() {
+    const given = process.env.TEWIP_ATTEST_KEY?.trim();
+    if (!given)
+        return undefined;
+    if (given.includes('BEGIN'))
+        return given;
+    try {
+        return readFileSync(given, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`TEWIP_ATTEST_KEY points at ${given}, which could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 /** The bundle as a person reads it. The refusals are not hidden at the bottom; they are the point. */
 export function renderAttestation(a) {
@@ -84,6 +102,10 @@ export function renderAttestation(a) {
         lines.push(`- **${refusal.what}**`);
         lines.push(`  - Why: ${refusal.why}`);
     }
-    lines.push('', '---', '', `Produced by ${a.producedBy.tool} (${a.producedBy.engine}) at ${a.producedBy.at.slice(0, 19).replace('T', ' ')} UTC.`, 'Every claim above names the run it came from and the layer that decided it. This is a statement', 'about the checks listed under "what was checked" and nothing else.');
+    lines.push('', '---', '', `Produced by ${a.producedBy.tool} (${a.producedBy.engine}) at ${a.producedBy.at.slice(0, 19).replace('T', ' ')} UTC.`, a.seal?.signature
+        ? `Signed (${a.seal.algorithm}); digest ${a.seal.digest.slice(0, 16)}…. Check it with \`tewip attest --verify <bundle.json> --key <public.pem>\`.`
+        : a.seal
+            ? `Digest ${a.seal.digest.slice(0, 16)}…, which is not a signature: it shows the bundle is undamaged, not that nobody edited it. Set TEWIP_ATTEST_KEY to sign.`
+            : '', 'Every claim above names the run it came from and the layer that decided it. This is a statement', 'about the checks listed under "what was checked" and nothing else.');
     return lines.join('\n');
 }

package/dist/engine/attest/seal.js

@@ -0,0 +1,90 @@
+// Sealing an attestation, and being precise about what a seal is worth.
+//
+// The roadmap promised a "signed" bundle and the first implementation signed nothing. This closes
+// that, but the honest part is the distinction it refuses to blur:
+//
+//   A **digest** says the content matches the fingerprint recorded inside it. Anybody who edits the
+//   bundle can recompute the fingerprint, so on its own it proves only that nothing was corrupted
+//   in transit - not that nobody changed it on purpose. It is still worth having: it gives a bundle
+//   a stable identity that a release note or a ticket can quote.
+//
+//   A **signature** says the holder of a private key produced this exact content. That is the claim
+//   people mean by "signed", and it is only available when a key exists.
+//
+// A tool that prints "signed" over a bare hash is doing the thing this whole project exists not to
+// do, so the words are kept apart everywhere: in the type, in the report, and in the verifier.
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+/**
+ * The bundle's content, in a form that hashes the same everywhere: keys in order, the seal itself
+ * left out, and the time it was produced kept in, because a bundle for a different moment is a
+ * different bundle.
+ */
+export function canonical(bundle) {
+    const ordered = (value) => {
+        if (Array.isArray(value))
+            return value.map(ordered);
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value)
+                .filter(([k]) => k !== 'seal')
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => [k, ordered(v)]));
+        }
+        return value;
+    };
+    return JSON.stringify(ordered(bundle));
+}
+export const digestOf = (bundle) => createHash('sha256').update(canonical(bundle)).digest('hex');
+/**
+ * Seals a bundle: always a digest, and a signature when a key is given. The key is a PEM Ed25519
+ * private key, from `TEWIP_ATTEST_KEY` (a path or the PEM itself). Nothing is generated silently:
+ * without a key there is no signature and the bundle says so rather than implying one.
+ */
+export function seal(bundle, privateKeyPem) {
+    const digest = digestOf(bundle);
+    if (!privateKeyPem?.trim())
+        return { digest };
+    try {
+        const key = createPrivateKey(privateKeyPem);
+        if (key.asymmetricKeyType !== 'ed25519')
+            throw new Error(`the signing key is ${key.asymmetricKeyType}, and Tewip signs with ed25519`);
+        return { digest, signature: cryptoSign(null, Buffer.from(digest, 'hex'), key).toString('base64'), algorithm: 'ed25519' };
+    }
+    catch (error) {
+        // A key that does not work is not a reason to ship an unmarked bundle quietly.
+        throw new Error(`the attestation could not be signed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Checks a sealed bundle, and says exactly what that check does and does not establish. */
+export function check(bundle, publicKeyPem) {
+    const recorded = bundle.seal?.digest ?? '';
+    const contentMatches = Boolean(recorded) && recorded === digestOf(bundle);
+    if (!recorded) {
+        return { contentMatches: false, signature: 'absent', says: 'this bundle carries no digest at all, so nothing about it can be checked' };
+    }
+    if (!contentMatches) {
+        return { contentMatches: false, signature: bundle.seal?.signature ? 'invalid' : 'absent', says: 'the content does not match the digest recorded inside it: it has been changed since it was written' };
+    }
+    if (!bundle.seal?.signature) {
+        return {
+            contentMatches: true,
+            signature: 'absent',
+            says: 'the content matches its own digest, and nothing more: no signature was made, so this shows the bundle is undamaged, not that nobody edited it - an editor can recompute a digest',
+        };
+    }
+    if (!publicKeyPem?.trim()) {
+        return { contentMatches: true, signature: 'no-key-given', says: 'the content matches its own digest and carries a signature, but no public key was given, so the signature was not checked' };
+    }
+    try {
+        const ok = cryptoVerify(null, Buffer.from(recorded, 'hex'), createPublicKey(publicKeyPem), Buffer.from(bundle.seal.signature, 'base64'));
+        return {
+            contentMatches: true,
+            signature: ok ? 'valid' : 'invalid',
+            says: ok
+                ? 'the content matches its digest and the signature is the holder of that key over this exact content'
+                : 'the content matches its digest, but the signature does not belong to this key and this content',
+        };
+    }
+    catch (error) {
+        return { contentMatches: true, signature: 'invalid', says: `the signature could not be checked: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

package/dist/engine/recall/recall-command.js

@@ -20,17 +20,24 @@ function kept(root, only) {
     }
     return { records, corrections };
 }
-export function runRecall(cmd) {
+/**
+ * The report, without printing it. An MCP server speaks JSON-RPC over stdout, so anything one of
+ * its tools calls has to return its answer: a stray console.log corrupts every response the
+ * assistant receives, and the corruption looks like the tool being broken rather than noisy.
+ */
+export function recallReport(cmd) {
     const { records, corrections } = kept(cmd.root, cmd.name);
     if (records.length === 0) {
-        const empty = 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.';
-        console.log(empty);
-        return empty;
+        return { report: 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.', searched: 0, corrections: 0 };
     }
     const found = recall(cmd.question, memories(records, corrections), { testId: cmd.testId, limit: cmd.limit ?? 5 });
-    const report = renderRecall(cmd.question, found);
+    return { report: renderRecall(cmd.question, found), searched: records.length, corrections: corrections.length };
+}
+export function runRecall(cmd) {
+    const { report, searched, corrections } = recallReport(cmd);
     console.log(report);
-    console.error(`\nSearched ${records.length} kept failure(s) and ${corrections.length} correction(s). No model was called.`);
+    if (searched > 0)
+        console.error(`\nSearched ${searched} kept failure(s) and ${corrections} correction(s). No model was called.`);
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/engine/trace/trace-command.js

@@ -46,15 +46,18 @@ function history(root, only) {
     runs.sort((a, b) => (a.finishedAt > b.finishedAt ? 1 : -1));
     return { runs, records };
 }
-export function runTrace(cmd) {
+/** The thread and its report, without printing: an MCP tool must return, never write to stdout. */
+export function traceReport(cmd) {
     const found = plans(cmd.root, cmd.only);
     const { runs, records } = history(cmd.root, cmd.name);
     const traced = found.map((plan) => tracePlan(plan, runs, records));
-    const report = renderTrace(traced);
+    return { traced, report: renderTrace(traced), plans: found.length, runs: runs.length };
+}
+export function runTrace(cmd) {
+    const { traced, report, plans: found, runs } = traceReport(cmd);
     console.log(report);
-    if (found.length > 0) {
-        console.error(`\nTraced ${found.length} plan(s) against ${runs.length} kept run(s). No model was called.`);
-    }
+    if (found > 0)
+        console.error(`\nTraced ${found} plan(s) against ${runs} kept run(s). No model was called.`);
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/mcp/server.js

@@ -12,7 +12,7 @@ import { isAbsolute } from 'node:path';
 import { z } from 'zod';
 import { githubCiReport } from './github-report.js';
 import { explainFailure, listDatasets, listFailedRuns, runView, windowView } from './tools.js';
-const server = new McpServer({ name: 'tewip', version: '0.4.0' });
+const server = new McpServer({ name: 'tewip', version: '0.5.0' });
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
 const dataset = z.string().optional().describe('Dataset directory relative to the Tewip repo, e.g. "data/real/gutenberg-holdout". Default: data/ (what the reporter collected). See list_datasets.');
 const run = z.string().optional().describe('Run id or a unique part of it. Default: the latest run with failures.');
@@ -77,4 +77,50 @@ server.registerTool('test_plan', {
     const { markdown, out } = await planProject({ feature, root: project, diffRange: diff, urls: urls ?? [] });
     return `${markdown}\n\n(Saved to ${out}. To turn it into verified tests, run \`tewip write\` in that folder.)`;
 }));
+/**
+ * The project's own memory, its thread from requirement to run, and its evidence bundle. All three
+ * read what Tewip already kept for a project on this machine, call no model, and change nothing -
+ * which is what makes them safe to hand an assistant that may call them on its own.
+ */
+const project = z.string().describe('Absolute path of the project folder');
+server.registerTool('recall', {
+    title: 'Has this happened here before?',
+    description: "What this project already concluded about a failure like this one: earlier failures that resemble it, what was decided, by which rule or which person, and the run each came from. Answers from records Tewip kept, never from a guess - and says plainly when nothing resembles it. Use before deciding what a failure means, and for questions like \"have we seen this error before?\".",
+    inputSchema: {
+        question: z.string().describe('An error message, or a question in plain words'),
+        project,
+        test: z.string().optional().describe('Narrow to one test id, when the question is about a particular test'),
+    },
+    annotations: readOnly,
+}, ({ question, project: root, test }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { recallReport } = await import('../engine/recall/recall-command.js');
+    return recallReport({ root, question, testId: test }).report;
+}));
+server.registerTool('trace_requirements', {
+    title: 'Is this requirement covered, and is it passing?',
+    description: 'Joins the plans Tewip wrote for a project to the tests that cover them and the runs that attempted them. A scenario counts as covered only when a real test can be named, and as passing only when a real run attempted it; everything else is reported as never run or not covered. Use for "are we ready to release?" and "what is not tested?".',
+    inputSchema: { project, only: z.string().optional().describe('Only plans whose title, ticket or feature contains this') },
+    annotations: readOnly,
+}, ({ project: root, only }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { traceReport } = await import('../engine/trace/trace-command.js');
+    return traceReport({ root, only }).report;
+}));
+server.registerTool('next_action', {
+    title: 'What should be done next about a goal?',
+    description: 'Given a goal in plain words - "keep the checkout flow green" - says what Tewip would do next and why, from what it can actually see in the project. The order is fixed and published: a real bug first, then the environment, then flakiness, then anything failing it cannot explain, then a coverage gap. It decides only; it never changes a file.',
+    inputSchema: { goal: z.string().describe('The goal, in plain words'), project },
+    annotations: readOnly,
+}, ({ goal, project: root }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    // observe/decide/render are pure; runPursue prints, which would corrupt the protocol.
+    const { observe, renderPursuit } = await import('../engine/pursue/pursue-command.js');
+    const { decide } = await import('../engine/pursue/policy.js');
+    const observed = observe(root, goal);
+    return renderPursuit(goal, observed, decide(goal, observed), false);
+}));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",