@vitest-agent/mcp 1.1.0 → 1.3.0

package/README.md

@@ -6,12 +6,11 @@
 
 > **Part of the [vitest-agent](https://vitest-agent.dev) ecosystem.** Most users want **[@vitest-agent/plugin](https://www.npmjs.com/package/@vitest-agent/plugin)**, which pulls this package in automatically. Install `@vitest-agent/mcp` directly only if you run the MCP server standalone.
 
-The `vitest-agent-mcp` MCP server bin. Exposes action-keyed tools over stdio that give LLM agents structured access to test data, coverage, history, failure signatures, TDD lifecycle state and more. Also surfaces four MCP resources (vendored Vitest docs and curated testing patterns) and six framing-only prompts.
+The `vitest-agent-mcp` MCP server bin. Exposes action-keyed tools over stdio that give LLM agents structured access to test data, coverage, history, failure signatures, TDD lifecycle state and more. Also surfaces six framing-only prompts.
 
 ## Features
 
 - **29 action-keyed tools** — per-CRUD families collapse into single tools dispatching on an `action` discriminator; covers `test_status`, `test_overview`, `test_coverage`, `test_errors`, `run_tests`, `note`, `hypothesis`, `tdd_task`, `tdd_goal`, `tdd_behavior` and more
-- **Four MCP resources** — vendored Vitest documentation (`vitest://docs/`) and curated testing patterns (`vitest-agent://patterns/`) with per-page titles, descriptions and `audience`/`priority` annotations
 - **Six framing prompts** — `triage`, `why-flaky`, `regression-since-pass`, `explain-failure`, `tdd-resume`, `wrapup`
 - **Idempotency middleware** — `tdd_task`, `tdd_goal`, `tdd_behavior` and `hypothesis` create-actions are idempotent on derived keys
 

package/index.d.ts

@@ -652,6 +652,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
       readonly classifications: {
         readonly [x: string]: string;
       };
+      readonly discoveryLastScannedAt?: string | null | undefined;
     } | {
       readonly kind: "timeout";
       readonly timeoutSeconds: number;
@@ -1529,10 +1530,10 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
 //#endregion
 //#region src/server.d.ts
 /**
- * Starts the MCP server over stdio, registering all tools, resources, and prompts.
+ * Starts the MCP server over stdio, registering all tools and prompts.
  *
  * Constructs the MCP server instance, registers all tRPC-backed tools (wired through
- * `ctx.runtime`), calls `registerAllResources` and `registerAllPrompts`, then connects
+ * `ctx.runtime`), calls `registerAllPrompts`, then connects
  * a `StdioServerTransport`. Returns when the transport disconnects.
  *
  * @param ctx - the MCP context carrying the shared ManagedRuntime and session refs

package/index.js

@@ -11,7 +11,7 @@ import { startMcpServer } from "./server.js";
 *
 * @public
 */
-const CURRENT_MCP_VERSION = "1.1.0";
+const CURRENT_MCP_VERSION = "1.3.0";
 
 //#endregion
 export { CURRENT_MCP_VERSION, McpLive, appRouter, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, startMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "1.1.0",
+	"version": "1.3.0",
 	"private": false,
 	"description": "Model Context Protocol server for vitest-agent. Exposes 53 tools for agent access to test data, TDD lifecycle, and session management.",
 	"keywords": [

package/server.js

@@ -30,7 +30,6 @@ import { TurnSearchAsMarkdown, TurnSearchResult } from "./tools/turn-search.js";
 import { WrapupPromptResult } from "./tools/wrapup-prompt.js";
 import { appRouter } from "./router.js";
 import { registerAllPrompts } from "./prompts/index.js";
-import { registerAllResources } from "./resources/index.js";
 import { effectToZodSchema } from "./utils/effect-to-zod.js";
 import { ChannelEvent, DataReader } from "@vitest-agent/sdk";
 import { Effect, Option, Schema } from "effect";
@@ -123,10 +122,10 @@ function structuredJsonResult(value) {
 	return structuredResult(JSON.stringify(value, null, 2), value);
 }
 /**
-* Starts the MCP server over stdio, registering all tools, resources, and prompts.
+* Starts the MCP server over stdio, registering all tools and prompts.
 *
 * Constructs the MCP server instance, registers all tRPC-backed tools (wired through
-* `ctx.runtime`), calls `registerAllResources` and `registerAllPrompts`, then connects
+* `ctx.runtime`), calls `registerAllPrompts`, then connects
 * a `StdioServerTransport`. Returns when the transport disconnects.
 *
 * @param ctx - the MCP context carrying the shared ManagedRuntime and session refs
@@ -828,7 +827,6 @@ async function startMcpServer(ctx) {
 		const data = await caller.ping();
 		return structuredResult(data.message, data);
 	});
-	registerAllResources(server);
 	registerAllPrompts(server);
 	const transport = new StdioServerTransport();
 	await server.connect(transport);

package/tools/run-tests.js

@@ -12,7 +12,8 @@ const RunTestsOk = Schema.Struct({
 	classifications: Schema.Record({
 		key: Schema.String,
 		value: Schema.String
-	}).annotations({ description: "Per-test classification labels: stable, new-failure, persistent, flaky, recovered." })
+	}).annotations({ description: "Per-test classification labels: stable, new-failure, persistent, flaky, recovered." }),
+	discoveryLastScannedAt: Schema.optional(Schema.NullOr(Schema.String)).annotations({ description: "ISO timestamp of the most recent real disk scan performed by discoverProjects() in this process (issue #100). `null`/absent means discovery has not scanned disk in this process yet (e.g. a config that doesn't call AgentPlugin.discover()). A stale-looking test count is self-explaining when compared against this value." })
 }).annotations({ identifier: "RunTestsOk" });
 const RunTestsTimeout = Schema.Struct({
 	kind: Schema.Literal("timeout"),
@@ -69,6 +70,18 @@ function composeTagExpression(tags) {
 	return parts.join(" and ");
 }
 const FORBIDDEN_CHARS = /[;|&`$(){}[\]<>!#]/;
+const DISCOVERY_LAST_SCAN_SYMBOL = Symbol.for("vitest-agent:discovery:last-scan-at");
+/**
+* Reads the ISO timestamp of the most recent real disk scan performed by
+* `discoverProjects()` in this process. `undefined` when discovery hasn't
+* scanned disk in this process yet.
+*
+* @internal
+*/
+function readDiscoveryLastScannedAt() {
+	const value = globalThis[DISCOVERY_LAST_SCAN_SYMBOL];
+	return typeof value === "string" ? value : void 0;
+}
 const stdoutSinkStorage = new AsyncLocalStorage();
 const stderrSinkStorage = new AsyncLocalStorage();
 let _stdioPatched = false;
@@ -350,7 +363,8 @@ const runTests = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
 			kind: "ok",
 			...project !== void 0 && { project },
 			report,
-			classifications: classifications ? Object.fromEntries(classifications) : {}
+			classifications: classifications ? Object.fromEntries(classifications) : {},
+			discoveryLastScannedAt: readDiscoveryLastScannedAt() ?? null
 		};
 	} catch (err) {
 		if (err instanceof Error && err.message === "VITEST_TIMEOUT") return {
@@ -368,4 +382,4 @@ const runTests = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
 }));
 
 //#endregion
-export { RunTestsAsMarkdown, RunTestsResult, coerceErrors, composeTagExpression, formatNoMatchMarkdown, formatReportMarkdown, formatRunTestsMarkdown, runTests, sanitizeTestArgs, withStdioCaptured };
+export { RunTestsAsMarkdown, RunTestsResult, coerceErrors, composeTagExpression, formatNoMatchMarkdown, formatReportMarkdown, formatRunTestsMarkdown, readDiscoveryLastScannedAt, runTests, sanitizeTestArgs, withStdioCaptured };

package/patterns/_meta.json

@@ -1,67 +0,0 @@
-{
-	"patterns": [
-		{
-			"slug": "testing-effect-services-with-mock-layers",
-			"title": "Testing Effect Services with Mock Layers",
-			"summary": "Compose live and test layers, swap platform layers, assert on accumulated writes via state-container test layers.",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.9
-			}
-		},
-		{
-			"slug": "testing-effect-schema-definitions",
-			"title": "Testing Effect Schema Definitions",
-			"summary": "Round-trip Schema.Class and Schema.Struct, branded types, transformations, and decoding error assertions.",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.9
-			}
-		},
-		{
-			"slug": "authoring-a-custom-vitest-agent-reporter",
-			"title": "Authoring a Custom vitest-agent Reporter",
-			"summary": "Implement the VitestAgentReporterFactory contract: ReporterKit, RenderedOutput targets, stdOsc8 hyperlinks, composing with the default reporter.",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.7
-			}
-		},
-		{
-			"slug": "running-tests-via-mcp",
-			"title": "Running Tests via the MCP run_tests Tool",
-			"summary": "Scope runs with project/files/tags (there is no `filter` param), read the four-variant return shape, and understand why subset runs 'fail' coverage thresholds.",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.9
-			}
-		},
-		{
-			"slug": "silencing-leaking-output-in-tests",
-			"title": "Silencing Leaking Log / Build Output in Tests",
-			"summary": "Decision tree mapping each noise source (Effect logger, console.*, rsbuild, tsdown, API Extractor) to its silencing technique, with an assert-on-output guardrail.",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.8
-			}
-		},
-		{
-			"slug": "known-issues-and-caveats",
-			"title": "Known Issues & Instrumentation Caveats",
-			"summary": "Distinguishes real vitest-agent issues (DataStoreError UNIQUE race) from upstream Vitest caveats (coverage-dir ENOENT), already-fixed bugs (perf_hooks), and misconceptions (discovery-cache staleness).",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.7
-			}
-		},
-		{
-			"slug": "operating-vitest-agent-as-an-agent",
-			"title": "Operating vitest-agent as an Agent",
-			"summary": "Read first: the front-loaded facts an agent needs (no run_tests filter param, coverage-in-subset behavior, consoleLeaks signal in run_tests output, VITEST_AGENT_CONSOLE CLI escape hatch, attribution is auto-recovered) with links to the deeper patterns.",
-			"annotations": {
-				"audience": ["assistant"],
-				"priority": 0.95
-			}
-		}
-	]
-}

package/patterns/authoring-a-custom-vitest-agent-reporter.md

@@ -1,82 +0,0 @@
-# Authoring a Custom vitest-agent Reporter
-
-## When to use
-
-You want output behavior that the named factories in `@vitest-agent/reporter` (`defaultReporter`, `markdownReporter`, `jsonReporter`, etc.) do not provide. Examples: SARIF output for code-scanning ingestion, JUnit XML alongside the default markdown, a side-channel that posts to an internal API.
-
-## The contract
-
-A reporter is a function that takes a `ReporterKit` and returns either a single `VitestAgentReporter` or an array. A reporter has exactly one method: synchronous `render(input)` that returns `RenderedOutput[]`. No I/O, no Vitest lifecycle. The plugin handles persistence, classification, baselines, and trends; reporters render the resulting data and the plugin routes the outputs to their declared targets.
-
-```typescript
-type VitestAgentReporterFactory =
- (kit: ReporterKit) =>
-  VitestAgentReporter | ReadonlyArray<VitestAgentReporter>;
-
-interface VitestAgentReporter {
- readonly render:
-  (input: ReporterRenderInput) => ReadonlyArray<RenderedOutput>;
-}
-```
-
-`ReporterKit` carries `config`, `stdEnv`, and `stdOsc8` (a pre-bound hyperlink helper). `ReporterRenderInput` carries `reports` (one per project), `classifications` (a Map keyed by `TestReport.fullName`), and an optional `trendSummary`.
-
-## Minimal example: a SARIF sidecar
-
-```typescript
-import type { VitestAgentReporterFactory } from "@vitest-agent/sdk";
-
-export const sarifReporter: VitestAgentReporterFactory = (kit) => ({
- render: (input) => {
-  const sarif = buildSarif(input.reports);
-  return [
-   {
-    target: "file",
-    content: JSON.stringify(sarif),
-    contentType: "application/sarif+json",
-   },
-  ];
- },
-});
-```
-
-The `target: "file"` slot is reserved for arbitrary on-disk artifacts; the convention for resolving the path will land in a future minor (currently a no-op routing target). Until then, use `target: "stdout"` for output that should reach the user immediately.
-
-## Composing with the default
-
-If you want your reporter to layer on top of the default rather than replace it, return an array:
-
-```typescript
-import { defaultReporter, type VitestAgentReporterFactory } from "@vitest-agent/reporter";
-
-export const myReporter: VitestAgentReporterFactory = (kit) => {
- const inner = defaultReporter(kit);
- const innerArr = Array.isArray(inner) ? inner : [inner];
- return [...innerArr, sarifReporter(kit)];
-};
-```
-
-## Wiring into the plugin
-
-```typescript
-// vitest.config.ts
-import { defineConfig } from "vitest/config";
-import { agentPlugin } from "@vitest-agent/plugin";
-import { myReporter } from "./my-reporter.js";
-
-export default defineConfig({
- plugins: [agentPlugin({ reporterFactory: myReporter })],
-});
-```
-
-## Anti-patterns
-
-- **Don't reach into Vitest's lifecycle from a reporter.** The plugin owns it. If you need a Vitest hook, you have outgrown this contract — fork the plugin instead.
-- **Don't return Promises from `render`.** The contract is sync. If you have async work, do it ahead of time and pass the resolved data into your factory closure.
-- **Don't use `stdOsc8` outside terminal targets.** OSC-8 escapes only render in capable terminals; `kit.stdOsc8` already gates this for you. Calling it from a `target: "github-summary"` reporter is harmless (it returns the bare label) but signals confused intent.
-
-## See also
-
-- `vitest://docs/api/advanced/reporters` — Vitest's own reporter API (different surface; informative for context)
-- `packages/reporter/src/default.ts` — The composition pattern the default reporter uses
-- `packages/sdk/src/contracts/reporter.ts` — Full type definitions for the contract

package/patterns/known-issues-and-caveats.md

@@ -1,52 +0,0 @@
-# Known Issues & Instrumentation Caveats
-
-## When to use
-
-A test run surfaced an error or oddity that looks like a vitest-agent bug.
-Check it against this list first — several are upstream Vitest behavior, an
-already-shipped fix, or a misconception, not something to investigate as a
-consumer-side problem.
-
-## `DataStoreError` on a UNIQUE collision — live, retry
-
-A concurrent agent registration (on `idempotency_key`) or two concurrent turn
-writes (on `(session_id, turn_no)`) can race the persistence layer's
-check-then-insert and surface a `DataStoreError` carrying
-`UNIQUE constraint failed`. It is not a consumer bug and not data corruption —
-retry the operation. The SELECT pre-check narrows but does not close the race.
-
-## `coverage/.tmp … ENOENT coverage-0.json` — inherent Vitest, not a bug
-
-Running Vitest in two processes at once (for example a CLI run alongside the
-`vitest-vscode` extension) makes them share Vitest's default
-`coverage.reportsDirectory`, and one process can delete the temp dir the other
-is writing. vitest-agent never sets `reportsDirectory`, so this is an upstream
-multi-process Vitest caveat. Give each concurrent process its own
-`coverage.reportsDirectory` (or serialize them).
-
-## `MaxPerformanceEntryBufferExceededWarning` — resolved, stop chasing it
-
-This `perf_hooks` warning on long runs was fixed in a shipped
-`@vitest-agent/reporter` release: React 19's development reconciler emits a
-`performance.measure()` per render, and the live renderer now drains Node's
-user-timing buffer after each render cycle. If you still see it, update
-`@vitest-agent/reporter`. Do not investigate it as a fault in your own repo.
-
-## Stale test counts — re-run, there is no warm cache
-
-Moving or adding test files does not require an MCP restart. Discovery is
-re-walked fresh on every Vitest run; the MCP serves counts from the database,
-which only updates when tests are re-run. Stale numbers mean the tests have not
-been re-run — not that a discovery cache is warm. Restarting the MCP would not
-refresh them.
-
-## A run that rebuilds `dist/` mid-run — expected
-
-A host project's Vitest `globalSetup` may call `AgentPlugin.runScript(...)`
-(for example `pnpm turbo run build:dev`), which can transiently tear down and
-rebuild `dist/` during the run. This is the host project's configuration, not a
-broken workspace.
-
-## See also
-
-- `vitest-agent://patterns/running-tests-via-mcp` — why subset runs "fail" coverage thresholds

package/patterns/operating-vitest-agent-as-an-agent.md

@@ -1,62 +0,0 @@
-# Operating vitest-agent as an Agent
-
-## When to use
-
-Read this first when you are an agent driving a project that uses
-`@vitest-agent/*`. It front-loads the handful of facts that otherwise cost
-trial-and-error, then points you at the deeper patterns.
-
-## The facts that save the most time
-
-1. **Run tests with `run_tests`, not Bash `vitest`.** `run_tests` persists
-   results, classifications, coverage, and history and fires the post-tool-use
-   hooks. Shelling out to `vitest` bypasses all of that.
-2. **`run_tests` has no `filter` parameter.** Scope with `project` (the Vitest
-   project name), `files` (globs), or `tags`. An unknown key like `filter` is
-   silently dropped, so the whole suite runs.
-3. **Subset runs "fail" coverage thresholds by design.** A single-file run
-   exiting with `ERROR: Coverage … does not meet global threshold` is expected
-   — global thresholds applied to partial coverage. There is no per-run
-   coverage toggle in `run_tests`; it inherits your `vitest.config`. For
-   isolated inspection use the CLI: `vitest run <file> --coverage.enabled=false`.
-4. **Stray `console.*` is surfaced by `run_tests` as a signal, not raw logs.**
-   The `ok` result's `report.consoleLeaks` field lists writes by file with
-   counts, optional per-test attribution, and a truncated sample. `run_tests`
-   still null-routes Vitest's stdout; the signal captures what was printed
-   without forwarding raw log lines into agent context. To see the raw output
-   for a flagged file, run Vitest on the CLI:
-   `VITEST_AGENT_CONSOLE=passthrough pnpm test`. Details at
-   `vitest-agent://patterns/running-tests-via-mcp`.
-5. **Session attribution is recovered for you.** The SessionStart hook writes
-   the `VITEST_AGENT_*` identity into the environment and the SDK recovers it —
-   you never set those vars by hand. The only behavioral knobs are
-   `VITEST_REPORTER_LOG_LEVEL`, `VITEST_REPORTER_LOG_FILE`, and `NO_COLOR`.
-6. **Stale counts mean tests were not re-run**, not a warm cache. Discovery
-   re-walks per Vitest run; the MCP serves counts from the database.
-7. **Some "leaks" are guardrail tests** that assert on their own output. Do not
-   silence output a test captures and `expect`s on.
-
-## Environment, briefly
-
-You do not configure vitest-agent through environment variables. The
-`VITEST_AGENT_*` vars (chat id, conversation id, agent ids, project dir,
-sidecar bin) are attribution plumbing written by the Claude Code plugin's
-SessionStart hook and recovered automatically. The vars you might set:
-
-- `VITEST_REPORTER_LOG_LEVEL` / `VITEST_REPORTER_LOG_FILE` — diagnostic
-  logger (separate from the console reporter).
-- `NO_COLOR` — disables ANSI color in rendered output.
-- `VITEST_AGENT_CONSOLE=passthrough` — overrides the resolved console mode
-  for the active executor on a CLI `vitest` run. Useful when investigating
-  files flagged by `report.consoleLeaks`. Invalid-for-slot values warn to
-  stderr and are ignored.
-
-## Where to go next
-
-| You want to… | Read |
-| --- | --- |
-| Scope a run, read the return shape, understand coverage-in-subset | `vitest-agent://patterns/running-tests-via-mcp` |
-| Silence noisy log/build output in tests | `vitest-agent://patterns/silencing-leaking-output-in-tests` |
-| Tell tooling noise apart from real failures | `vitest-agent://patterns/known-issues-and-caveats` |
-| Read the full console-mode matrix (human prose) | <https://vitest-agent.dev/guide/console-modes> |
-| The human-facing version of this page | <https://vitest-agent.dev/guide/operating-as-an-agent> |

package/patterns/running-tests-via-mcp.md

@@ -1,103 +0,0 @@
-# Running Tests via the MCP `run_tests` Tool
-
-## When to use
-
-You want to execute the Vitest suite (or a subset) from an agent. Always prefer `run_tests` over shelling out to `vitest` — it persists results, classifications, coverage, and history to the project database and drives the post-tool-use hooks. Re-running `vitest` over Bash bypasses all of that.
-
-## Scoping a run — there is no `filter` parameter
-
-`run_tests` accepts exactly these inputs:
-
-| Field | Type | Default | Scopes by |
-| --- | --- | --- | --- |
-| `files` | `string[]` | `[]` | Vitest file patterns: exact paths or globs |
-| `project` | `string` | unset | The Vitest **project name** from your config |
-| `tags` | `{ all?: string[]; any?: string[]; none?: string[] }` | unset | Vitest tag expression |
-| `passWithNoTests` | `boolean` | config value | Per-call override of `test.passWithNoTests` |
-| `timeout` | `number` (seconds) | `120` | Per-call run timeout |
-
-There is **no** `filter` field. Passing one (`run_tests({ filter: "@my/pkg" })`) is silently dropped — the call then runs with no filters, so the **entire** suite executes. To scope to one package, pass its Vitest project name as `project`; to scope to one file, pass it in `files`.
-
-`project` matches the project **name** defined in `vitest.config.ts`, not the npm package name. They often differ — check your config for the actual project name.
-
-`tags` sub-filters AND together (with each other and with `project`/`files`): `all` → `"a and b"`, `any` → `"(a or b)"`, `none` → `"not a and not b"`.
-
-## Return shape
-
-`run_tests` returns one of four variants — discriminate on `kind`:
-
-| `kind` | Fields | Meaning |
-| --- | --- | --- |
-| `"ok"` | `report`, `classifications` (map of test full-name → `stable`/`new-failure`/`persistent`/`flaky`/`recovered`), optional `project` | The run completed |
-| `"no-match"` | `filter` (the resolved `project`/`files`/`tags`/`resolvedExpression`) | A filter was supplied but matched zero tests |
-| `"timeout"` | `timeoutSeconds` | Exceeded the timeout |
-| `"error"` | `message` | The run errored |
-
-A `no-match` is filter-driven: it fires when you supplied a filter and zero tests matched. Treat it as a finding (typo in `project`/`files`?) rather than a pass.
-
-## Coverage on subset runs reads as a failure — by design
-
-A single-file or single-project run will commonly exit non-zero with:
-
-```text
-ERROR: Coverage for lines (59.91%) does not meet global threshold (70%)
-```
-
-This is expected: your global coverage thresholds are applied to a partial run, so partial coverage "fails" them. It is not a real test failure.
-
-`run_tests` has **no per-run coverage toggle** — it deliberately inherits your `vitest.config` `coverage.enabled` (forcing it off here used to override intentional "coverage on by default" setups). For clean isolated inspection, drop to the CLI:
-
-```bash
-vitest run path/to/one.test.ts --coverage.enabled=false
-```
-
-## Stray console output — `report.consoleLeaks`
-
-When the run produces stray `console.*` output, the `report` object on an
-`"ok"` result carries an optional `consoleLeaks` field. It is omitted
-entirely when the run produced no user console output.
-
-Shape:
-
-- `total` — total stray console writes across the run
-- `byFile` — one entry per file that produced writes:
-  - `file` — the test file path
-  - `stdout` — writes to stdout-class streams (`log`, `info`, `debug`)
-  - `stderr` — writes to stderr-class streams (`error`, `warn`)
-  - `tests` (optional) — test names where writes were attributed
-  - `sample` (optional) — truncated excerpt of the first write in this file
-- `truncated` (optional) — `true` when `byFile` was capped
-
-Use `byFile[].file` to locate which files to investigate and `sample` to
-find the call site, without dumping full log content into agent context.
-The markdown summary line also surfaces the leak count inline (e.g.
-`⚠ 3 stray console writes across 2 files (see consoleLeaks)`).
-
-### Console-output visibility by surface
-
-| Surface | Sees stray `console.*` | Per-test attribution |
-| --- | --- | --- |
-| `run_tests` (MCP) | yes — `consoleLeaks` signal (counts + sample) | per file, per test where resolvable |
-| Human at a TTY | yes — Vitest's own `stdout \|` / `stderr \|` lines | yes (TTY only) |
-| Piped shell (default) | no — agent-shaped summary suppresses it | n/a |
-| Piped shell + `VITEST_AGENT_CONSOLE=passthrough` | yes — raw passthrough | no (raw, unlabeled) |
-
-### `VITEST_AGENT_CONSOLE` — CLI escape hatch
-
-To see raw console output for a file that `consoleLeaks` flagged, run
-Vitest directly on the CLI with the override set:
-
-```bash
-VITEST_AGENT_CONSOLE=passthrough pnpm test
-```
-
-This overrides the plugin's resolved console mode to `passthrough` for
-the active executor — Vitest's own reporters emit console output
-unfiltered. An invalid value for the current executor slot warns to
-stderr and is ignored.
-
-## See also
-
-- `vitest-agent://patterns/operating-vitest-agent-as-an-agent` — the orientation index
-- `vitest-agent://patterns/known-issues-and-caveats` — coverage-dir races and other instrumentation caveats
-- `vitest://docs/config/index` — Vitest's native config reference

package/patterns/silencing-leaking-output-in-tests.md

@@ -1,91 +0,0 @@
-# Silencing Leaking Log / Build Output in Tests
-
-## When to use
-
-A test run is polluted with stray log lines, build-tool banners, or framework
-diagnostics that drown the signal. The fix differs per source — identify the
-source first, then apply the matching technique.
-
-## Guardrail: do not silence output a test asserts on
-
-Before silencing anything, confirm the test does not capture and `expect` on
-the output. Some tests deliberately spy on `process.stdout.write` /
-`process.stderr.write` (or `console.*`) and assert on `.mock.calls` to verify
-what a formatter emits. Silencing those breaks the assertion. If you see a
-`vi.spyOn(process.stdout, "write")` whose `.mock.calls` are asserted, that
-output is the test subject — leave it alone.
-
-## Decision tree
-
-| Source (what the noise looks like) | Technique |
-| --- | --- |
-| Effect default logger (`timestamp=… level=INFO message=…`) | Provide a silent logger layer |
-| Plain `console.log` / `console.warn` / `console.error` | Spy + mock the method |
-| rsbuild (`info build started…`, file-size table) | Set `@rsbuild/core` logger level to silent |
-| tsdown / rolldown (`ℹ entry:`, `✔ Build complete`) | Pass `logLevel: "silent"` to the build |
-| API Extractor (`(ae-missing-release-tag)` to stderr) | Pass an `onMessage` handler that marks messages handled |
-
-## Effect default logger
-
-Provide a silent logger at the run/layer boundary. This mirrors how the SDK's
-own `LoggerLive` builds its silent variant (`packages/sdk/src/layers/LoggerLive.ts`):
-
-```typescript
-import { Effect, Logger } from "effect";
-
-const silent = Logger.replace(Logger.defaultLogger, Logger.none);
-
-await Effect.runPromise(program.pipe(Effect.provide(silent)));
-```
-
-`Logger.minimumLogLevel(LogLevel.None)` is an equivalent gate.
-
-## Plain `console.*`
-
-```typescript
-import { beforeEach, vi } from "vitest";
-
-beforeEach(() => {
- vi.spyOn(console, "warn").mockImplementation(() => {});
- vi.spyOn(console, "error").mockImplementation(() => {});
-});
-```
-
-## rsbuild reporter
-
-rsbuild writes through its own `logger` singleton, **not** `console.*`, so
-console mocks miss it. Set the level and restore it:
-
-```typescript
-import { logger } from "@rsbuild/core";
-
-const prev = logger.level;
-logger.level = "silent";
-try {
- await build();
-} finally {
- logger.level = prev;
-}
-```
-
-## tsdown / rolldown
-
-Pass `logLevel: "silent"` to the build call (or inject a no-op output writer).
-
-## API Extractor
-
-Mark diagnostics handled so they are not printed — this is the production quiet
-path:
-
-```typescript
-extractorResult = Extractor.invoke(config, {
- messageCallback: (message) => {
-  message.handled = true;
- },
-});
-```
-
-## See also
-
-- `vitest-agent://patterns/known-issues-and-caveats` — distinguishing tooling noise from real failures
-- `vitest://docs/api/vi` — the `vi.spyOn` / mock API

package/patterns/testing-effect-schema-definitions.md

@@ -1,71 +0,0 @@
-# Testing Effect Schema Definitions
-
-## When to use
-
-When you have an Effect Schema (`Schema.Struct`, `Schema.Class`, branded type, transformation) that defines a public-API shape and you want to verify: round-trip encode/decode preserves data, decoding rejects invalid input with useful errors, transformations behave correctly.
-
-## Three test patterns
-
-### Pattern A: round-trip
-
-```typescript
-import { Schema } from "effect";
-import { describe, expect, it } from "vitest";
-
-const User = Schema.Struct({
- id: Schema.Number,
- name: Schema.String,
-});
-
-it("round-trips through encode + decode", () => {
- const value = { id: 42, name: "Ada" };
- const encoded = Schema.encodeUnknownSync(User)(value);
- const decoded = Schema.decodeUnknownSync(User)(encoded);
- expect(decoded).toEqual(value);
-});
-```
-
-### Pattern B: decoding error assertions
-
-```typescript
-import { Either, Schema } from "effect";
-import { describe, expect, it } from "vitest";
-
-it("rejects invalid input with the expected error path", () => {
- const result = Schema.decodeUnknownEither(User)({ id: "not-a-number", name: "Ada" });
- expect(Either.isLeft(result)).toBe(true);
- if (Either.isLeft(result)) {
-  const formatted = String(result.left);
-  expect(formatted).toContain("id");
-  expect(formatted).toMatch(/expected number/i);
- }
-});
-```
-
-### Pattern C: transformations
-
-For `Schema.transform` between two shapes (typical for parsing JSON-stringified payloads):
-
-```typescript
-const Comma = Schema.transform(Schema.String, Schema.Array(Schema.String), {
- decode: (s) => s.split(","),
- encode: (a) => a.join(","),
-});
-
-it("decodes and encodes the inverse", () => {
- expect(Schema.decodeUnknownSync(Comma)("a,b,c")).toEqual(["a", "b", "c"]);
- expect(Schema.encodeUnknownSync(Comma)(["a", "b"])).toBe("a,b");
-});
-```
-
-## Anti-patterns
-
-- **Don't assert on stringified errors verbatim.** Effect Schema's error formatting can shift between minor versions; assert on substrings or use `ParseResult.TreeFormatter` for stable output.
-- **Don't write tests that rely on `Schema.transformOrFail` failing _silently_.** When a transform can fail, exercise the failure path explicitly — `Either` results from `decodeUnknownEither` are the right tool.
-- **Don't recreate the schema in the test.** Import the production definition; otherwise the test passes when the production schema drifts.
-
-## See also
-
-- `vitest://docs/api/expect` — Vitest matcher reference for the assertion patterns
-- `vitest-agent://patterns/testing-effect-services-with-mock-layers` — Companion pattern; services hand around Schema-typed data
-- Effect Schema docs at `https://effect.website/docs/schema/introduction`