@vitest-agent/sdk 3.1.2 → 4.0.0

package/README.md

@@ -4,18 +4,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-> **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/sdk` directly only if you build tooling on the shared schemas or data layer.
+> **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/sdk` directly only if you build tooling on the shared schemas or contract types.
 
-The no-internal-deps base for the vitest-agent ecosystem. Carries the Effect Schemas, SQLite migrations and data layer, services and live layers, formatters, XDG path resolution, the public reporter and dispatcher contract types, and testing utilities.
+The platform-free core of the vitest-agent ecosystem. Carries the Effect Schemas, the public reporter and dispatcher contract types, the tagged errors, the pure formatters and utilities, the pure sidecar `dispatch` entry, and the published JSON Schemas. It has no workspace dependencies and never imports `node:*`, so it runs anywhere Effect does.
+
+Everything that touches a filesystem, a process, or SQLite — the `DataStore` / `DataReader` services and their live layers, migrations, `ensureMigrated`, `PlatformLive`, `resolveDataPath`, and the test-layer helpers — lives in **[@vitest-agent/engine](https://www.npmjs.com/package/@vitest-agent/engine)**.
 
 ## Features
 
-- **Effect Schemas** — all domain types (`RunEvent`, `RenderState`, `CoverageTargets`, `TurnPayload`, identity types) defined with Effect Schema; runtime validation and TypeScript types from one source
-- **SQLite data layer** — `DataStore` and `DataReader` Effect services with live and `:memory:` test layers; `ensureMigrated` for safe multi-project setups
-- **XDG path resolution** — deterministic `dbPath` derivation from workspace identity with a five-source fallback chain
+- **Effect Schemas** — all domain types (`AgentReport`, `RunEvent`, `RenderState`, `CoverageTargets`, `TurnPayload`, identity types) defined with Effect Schema; runtime validation and TypeScript types from one source
 - **Reporter and dispatcher contracts** — `VitestAgentReporterFactory`, `ReporterKit`, `ResolvedReporterConfig`, `DispatchInputs` and the types consumed by every other package
+- **Tagged errors** — `Data.TaggedError` families for data-store, discovery, path-resolution, project-identity, run-context, TDD and agent failures
+- **Pure formatters and utilities** — terminal, markdown, GFM, JSON and CI-annotation formatters, plus `classifyTestPath`, `buildAgentReport`, `validatePhaseTransition` and the posix path helpers
 - **Sidecar dispatch core** — `dispatch`, `injectEnv` and `exitCodeForTag` on the `@vitest-agent/sdk/dispatch` sub-path for a minimal SEA bundle
-- **Test utilities** — `makeTestLayer`, `DataStoreTestLayer` and five preset factory functions on the `@vitest-agent/sdk/testing` sub-path
+- **JSON Schemas** — generated schemas on the `@vitest-agent/sdk/schemas/*.json` sub-path (for example the run-report file schema)
 
 ## Install
 
@@ -28,19 +30,21 @@ pnpm add @vitest-agent/sdk
 ## Quick start
 
 ```ts
-import { Effect } from "effect";
-import { DataReader } from "@vitest-agent/sdk";
-import { singlePassingRun } from "@vitest-agent/sdk/testing";
-
-const layer = singlePassingRun(":memory:");
-
-await Effect.runPromise(
-  Effect.provide(
-    Effect.flatMap(DataReader, (r) => r.getLatestRun("default", null)),
-    layer,
-  ),
-);
-// returns the seeded run row
+import { Schema } from "effect";
+import { AgentReport, CoverageLevel } from "@vitest-agent/sdk";
+
+// Decode a persisted run report with the shared schema
+const report = Schema.decodeUnknownSync(AgentReport)(JSON.parse(raw));
+
+// Reuse the coverage presets that AgentPlugin.COVERAGE_LEVELS is built on
+const targets = CoverageLevel.standard.withPerFile();
+```
+
+Need the data layer, services, or an in-memory test layer? Reach for the engine:
+
+```ts
+import { DataReader } from "@vitest-agent/engine";
+import { singlePassingRun } from "@vitest-agent/engine/testing";
 ```
 
 ## Documentation

package/dispatch.d.ts

@@ -12,6 +12,11 @@ interface InjectEnvInput {
   readonly command: string;
   readonly cwd: string;
   readonly env: Record<string, string | undefined>;
+  /**
+   * Synchronous file reader, injected so the core never touches
+   * `node:fs`. Throws on a missing file; {@link injectEnv} catches.
+   */
+  readonly readFile: (path: string) => string;
 }
 /**
  * Compute the (possibly rewritten) Bash command. Returns the original
@@ -21,13 +26,26 @@ interface InjectEnvInput {
  *   - `VITEST_AGENT_CONVERSATION_ID` or `VITEST_AGENT_AGENT_ID` is
  *     missing from env (no agent context to attribute to)
  *
- * Always synchronous — the package.json read is the only I/O and is
- * fast enough not to need Effect wrapping.
+ * Always synchronous — the package.json read is the only I/O, goes through
+ * the injected `readFile`, and is fast enough not to need Effect wrapping.
  * @public
  */
 export declare const injectEnv: (input: InjectEnvInput) => string;
 //#endregion
 //#region src/sidecar-dispatch.d.ts
+/**
+ * The process-level inputs {@link dispatch} needs, supplied by the bin
+ * runner so the dispatch core itself never reads `process` or `node:fs`.
+ * @public
+ */
+interface DispatchIo {
+  /** Default working directory when `--cwd` is not passed. */
+  readonly cwd: string;
+  /** Environment map (`process.env` in the sidecar bins). */
+  readonly env: Record<string, string | undefined>;
+  /** Synchronous file reader; throws on a miss — dispatch/injectEnv catch. */
+  readonly readFile: (path: string) => string;
+}
 /** Result of a {@link dispatch} call: captured stdout/stderr + exit code.
  * @public
  */
@@ -38,11 +56,12 @@ interface DispatchResult {
 }
 /**
  * Dispatch one argv invocation. `argv` is the post-`node post-bin`
- * slice — i.e. `process.argv.slice(2)`. Never throws: every failure is
- * folded into the returned {@link DispatchResult}.
+ * slice — i.e. `process.argv.slice(2)` — and `io` carries the process
+ * facts (cwd, env, a file reader) the runner owns. Never throws: every
+ * failure is folded into the returned {@link DispatchResult}.
  * @public
  */
-export declare const dispatch: (argv: readonly string[]) => Promise<DispatchResult>;
+export declare const dispatch: (argv: readonly string[], io: DispatchIo) => Promise<DispatchResult>;
 //#endregion
-export type { DispatchResult, InjectEnvInput };
+export type { DispatchIo, DispatchResult, InjectEnvInput };
 //# sourceMappingURL=dispatch.d.ts.map

package/formatters/markdown.js

@@ -20,6 +20,7 @@ const MarkdownFormatter = {
 			const md = formatConsoleMarkdown(report, {
 				consoleOutput: context.detail === "minimal" ? "failures" : "full",
 				coverageConsoleLimit: context.coverageConsoleLimit,
+				cwd: context.cwd,
 				noColor: context.noColor,
 				...context.trendSummary !== void 0 ? { trendSummary: context.trendSummary } : {},
 				...context.runCommand !== void 0 ? { runCommand: context.runCommand } : {},

package/formatters/terminal.js

@@ -1,6 +1,6 @@
 import { formatTerminal } from "../utils/format-terminal.js";
 import { osc8 } from "../utils/hyperlink.js";
-import * as path from "node:path";
+import { joinPosix } from "../utils/posix-path.js";
 
 //#region src/formatters/terminal.ts
 /**
@@ -25,13 +25,13 @@ import * as path from "node:path";
 * requires an absolute filesystem path inside a `file://` URL —
 * iTerm2 / WezTerm / Kitty / VSCode all silently fail to open
 * relative targets. Resolve the captured value back to absolute
-* against the cwd before handing it to `osc8`. The display label
+* against `ctx.cwd` before handing it to `osc8`. The display label
 * stays relative so the rendered output is unchanged.
 * @public
 */
 const FAILED_TEST_ROW = /^( {4}(?:\x1b\[\d+m)?✗(?:\x1b\[\d+m)? )([^ ]+)( > )/gm;
 const wrapHyperlinks = (text, ctx) => text.replace(FAILED_TEST_ROW, (_match, prefix, captured, suffix) => {
-	const absolute = path.resolve(process.cwd(), captured);
+	const absolute = captured.startsWith("/") ? captured : joinPosix(ctx.cwd, captured);
 	return `${prefix}${osc8(`file://${absolute}`, captured, { enabled: !ctx.noColor })}${suffix}`;
 });
 /** @public */
@@ -39,6 +39,7 @@ const TerminalFormatter = {
 	format: "terminal",
 	render: (reports, context) => {
 		const text = formatTerminal(reports, {
+			cwd: context.cwd,
 			noColor: context.noColor,
 			coverageConsoleLimit: context.coverageConsoleLimit,
 			...context.trendSummary !== void 0 ? { trendSummary: context.trendSummary } : {},