@vitest-agent/mcp 1.0.0 → 1.0.1

package/bin/vitest-agent-mcp.js

@@ -19,8 +19,8 @@ import { Effect, ManagedRuntime } from "effect";
 * @internal
 */
 function checkVersionDrift() {
-	if ("1.0.0" === "0.0.0") return;
-	if (CURRENT_SDK_VERSION !== "1.0.0") process.stderr.write(`[@vitest-agent/mcp] version drift: @vitest-agent/mcp@${CURRENT_MCP_VERSION} with @vitest-agent/sdk@${CURRENT_SDK_VERSION}. Reinstall @vitest-agent/* packages so versions match.\n`);
+	if ("1.0.1" === "0.0.0") return;
+	if (CURRENT_SDK_VERSION !== "1.0.1") process.stderr.write(`[@vitest-agent/mcp] version drift: @vitest-agent/mcp@${CURRENT_MCP_VERSION} with @vitest-agent/sdk@${CURRENT_SDK_VERSION}. Reinstall @vitest-agent/* packages so versions match.\n`);
 }
 /**
 * Resolve the user's project directory.

package/index.d.ts

@@ -108,7 +108,7 @@ declare const createCallerFactory: import("@trpc/server").TRPCRouterCallerFactor
  * @returns an Effect Layer providing all MCP runtime services
  * @public
  */
-declare const McpLive: (dbPath: string, logLevel?: LogLevel.LogLevel, logFile?: string) => Layer.Layer<import("@vitest-agent/sdk").DataReader | import("@effect/sql/SqlClient").SqlClient | import("@vitest-agent/sdk").DataStore | import("@vitest-agent/sdk").ProjectDiscovery | import("@vitest-agent/sdk").DetailResolver | import("@vitest-agent/sdk").EnvironmentDetector | import("@vitest-agent/sdk").ExecutorResolver | import("@vitest-agent/sdk").FormatSelector | import("@vitest-agent/sdk").OutputRenderer | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | NodeContext.NodeContext, import("@effect/sql/SqlError").SqlError | SqliteMigrator.MigrationError | import("effect/ConfigError").ConfigError, never>;
+declare const McpLive: (dbPath: string, logLevel?: LogLevel.LogLevel, logFile?: string) => Layer.Layer<import("@vitest-agent/sdk").DataReader | import("@effect/sql/SqlClient").SqlClient | import("@vitest-agent/sdk").DataStore | import("@vitest-agent/sdk").ProjectDiscovery | import("@vitest-agent/sdk").FormatSelector | import("@vitest-agent/sdk").ExecutorResolver | import("@vitest-agent/sdk").DetailResolver | import("@vitest-agent/sdk").EnvironmentDetector | import("@vitest-agent/sdk").OutputRenderer | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | NodeContext.NodeContext, import("@effect/sql/SqlError").SqlError | SqliteMigrator.MigrationError | import("effect/ConfigError").ConfigError, never>;
 //#endregion
 //#region src/router.d.ts
 /**

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"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": [
@@ -45,7 +45,7 @@
 		"@effect/sql-sqlite-node": "^0.52.0",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@trpc/server": "^11.18.0",
-		"@vitest-agent/sdk": "1.0.0",
+		"@vitest-agent/sdk": "1.0.1",
 		"effect": "^3.21.4",
 		"zod": "^4.4.3"
 	},

package/public/patterns/_meta.json

@@ -0,0 +1,67 @@
+{
+	"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, console output is config-driven not env-driven, attribution is auto-recovered) with links to the deeper patterns.",
+			"annotations": {
+				"audience": ["assistant"],
+				"priority": 0.95
+			}
+		}
+	]
+}

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

@@ -0,0 +1,82 @@
+# 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/public/patterns/known-issues-and-caveats.md

@@ -0,0 +1,52 @@
+# 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/public/patterns/operating-vitest-agent-as-an-agent.md

@@ -0,0 +1,53 @@
+# 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. **You cannot see stray `console.log` through `run_tests`** — it null-routes
+   Vitest's stdout. Console behavior is configured via the plugin's `console`
+   matrix (e.g. `console: { agent: "passthrough" }`), **not** environment
+   variables. To see intercepted output, run Vitest directly with
+   `--disableConsoleIntercept` (a native Vitest flag).
+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 only vars you might set for
+diagnostics are `VITEST_REPORTER_LOG_LEVEL` / `VITEST_REPORTER_LOG_FILE` (a
+diagnostic log file, separate from the console reporter) and `NO_COLOR`.
+
+## 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/public/patterns/running-tests-via-mcp.md

@@ -0,0 +1,58 @@
+# 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
+```
+
+## 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/public/patterns/silencing-leaking-output-in-tests.md

@@ -0,0 +1,91 @@
+# 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/public/patterns/testing-effect-schema-definitions.md

@@ -0,0 +1,71 @@
+# 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`

package/public/patterns/testing-effect-services-with-mock-layers.md

@@ -0,0 +1,63 @@
+# Testing Effect Services with Mock Layers
+
+## When to use
+
+Reach for this pattern when an Effect service has external dependencies (filesystem, SQLite, network) that you do not want to exercise in unit tests. The codebase under `packages/sdk/src/services/` and `packages/sdk/src/layers/` follows this exact shape.
+
+## The shape
+
+Every Effect service has three pieces:
+
+1. **The service tag** (`Context.Tag`) and interface — under `services/`.
+2. **The live layer** — wires real I/O against `@effect/platform` adapters.
+3. **The test layer** — usually a mutable state container that records what the service was asked to do, with read methods you assert against.
+
+You compose the live layer in production wiring (`ReporterLive`, `CliLive`, `McpLive`); you compose the test layer in tests.
+
+## Minimal example
+
+```typescript
+import { Effect, Layer, Ref } from "effect";
+import { describe, expect, it } from "vitest";
+import { DataStore } from "@vitest-agent/sdk";
+
+// Test layer: accumulates writes into a Ref so tests can read them back.
+const DataStoreTest = Layer.effect(
+ DataStore,
+ Effect.gen(function* () {
+  const writes = yield* Ref.make<{ runs: ReadonlyArray<unknown> }>({ runs: [] });
+  return DataStore.of({
+   writeRun: (input) =>
+    Ref.update(writes, (s) => ({ runs: [...s.runs, input] })).pipe(
+     Effect.as(1),
+    ),
+   // ... other methods stubbed similarly
+  });
+ }),
+);
+
+it("records the run", async () => {
+ const program = Effect.gen(function* () {
+  const store = yield* DataStore;
+  yield* store.writeRun({ project: "x" });
+  // assert via your accumulator pattern
+ });
+ await Effect.runPromise(program.pipe(Effect.provide(DataStoreTest)));
+});
+```
+
+## Why not mock the FileSystem directly?
+
+Layer-level swapping is the testable seam Effect was designed around. Mocking `@effect/platform`'s FileSystem implementation works but loses the type checking that ensures your test layer matches the live interface. Layer.effect with the same Tag forces you to satisfy every method.
+
+## Anti-patterns
+
+- **Don't `Effect.runPromise` inside service implementations** — providing `DataStoreTest` and then having the service call `Effect.runPromise` internally bypasses the layer.
+- **Don't share `Ref`s across tests** — construct the test layer per-test (or use `beforeEach`) so accumulated state doesn't bleed.
+- **Don't assert on layer construction order** — Effect normalizes the merge graph.
+
+## See also
+
+- `vitest://docs/guide/mocking` — Vitest mocking guide (general background)
+- `vitest-agent://patterns/testing-effect-schema-definitions` — Companion pattern; most service inputs are Schema-typed
+- `packages/sdk/src/layers/DataStoreTest.ts` — The canonical example in this codebase

package/public/vendor/vitest-docs/ATTRIBUTION.md

@@ -0,0 +1,5 @@
+# Attribution
+
+The markdown files under `vendor/vitest-docs/` are vendored from the [Vitest project](https://github.com/vitest-dev/vitest) under the MIT License.
+
+See `manifest.json` for the exact upstream tag and commit SHA captured.