@vitest-agent/sdk 1.0.0

package/utils/probe-host-metadata.js

@@ -0,0 +1,99 @@
+//#region src/utils/probe-host-metadata.ts
+const isUseful = (value) => value !== void 0 && value.length > 0;
+/**
+* Walk the priority chain of env-var probes. Returns the first match
+* along with any decorating metadata (`term_program`, `ci_provider`,
+* etc.) for that source. When no probe matches, `source`/`value`/
+* `metadata` are all `null`.
+*
+* The probe order matches the plan's table exactly:
+*
+* 1. `TMUX_PANE` (tmux reattach-stable)
+* 2. `WT_SESSION` (Windows Terminal pane)
+* 3. `WEZTERM_PANE` (WezTerm pane)
+* 4. `KITTY_WINDOW_ID` (kitty window)
+* 5. `TERM_SESSION_ID` (iTerm2, Terminal.app)
+* 6. `VSCODE_INJECTION` + `process.ppid` (handled by the Live layer
+*    since it needs `process.ppid`, not env)
+* 7. `GITHUB_RUN_ID` + `GITHUB_RUN_ATTEMPT`
+* 8. `BUILDKITE_JOB_ID` / `CIRCLE_BUILD_NUM` / `GITLAB_CI_JOB_ID`
+* 9. `process.ppid` walk (handled by the Live layer)
+* @public
+*/
+const probeHostMetadataFromEnv = (env) => {
+	const decoration = (extra) => {
+		const baseDecoration = {};
+		if (isUseful(env.TERM_PROGRAM)) baseDecoration.term_program = env.TERM_PROGRAM;
+		if (isUseful(env.TERM_PROGRAM_VERSION)) baseDecoration.term_program_version = env.TERM_PROGRAM_VERSION;
+		return {
+			...baseDecoration,
+			...extra
+		};
+	};
+	if (isUseful(env.TMUX_PANE)) return {
+		source: "TMUX_PANE",
+		value: env.TMUX_PANE,
+		metadata: decoration(isUseful(env.TMUX) ? { tmux_socket: env.TMUX } : {})
+	};
+	if (isUseful(env.WT_SESSION)) return {
+		source: "WT_SESSION",
+		value: env.WT_SESSION,
+		metadata: decoration({})
+	};
+	if (isUseful(env.WEZTERM_PANE)) return {
+		source: "WEZTERM_PANE",
+		value: env.WEZTERM_PANE,
+		metadata: decoration({})
+	};
+	if (isUseful(env.KITTY_WINDOW_ID)) return {
+		source: "KITTY_WINDOW_ID",
+		value: env.KITTY_WINDOW_ID,
+		metadata: decoration({})
+	};
+	if (isUseful(env.TERM_SESSION_ID)) return {
+		source: "TERM_SESSION_ID",
+		value: env.TERM_SESSION_ID,
+		metadata: decoration({})
+	};
+	if (isUseful(env.GITHUB_RUN_ID)) return {
+		source: "GITHUB_RUN_ID",
+		value: env.GITHUB_RUN_ID,
+		metadata: decoration({
+			ci: true,
+			ci_provider: "github",
+			...isUseful(env.GITHUB_RUN_ATTEMPT) ? { github_run_attempt: env.GITHUB_RUN_ATTEMPT } : {}
+		})
+	};
+	if (isUseful(env.BUILDKITE_JOB_ID)) return {
+		source: "BUILDKITE_JOB_ID",
+		value: env.BUILDKITE_JOB_ID,
+		metadata: decoration({
+			ci: true,
+			ci_provider: "buildkite"
+		})
+	};
+	if (isUseful(env.CIRCLE_BUILD_NUM)) return {
+		source: "CIRCLE_BUILD_NUM",
+		value: env.CIRCLE_BUILD_NUM,
+		metadata: decoration({
+			ci: true,
+			ci_provider: "circle"
+		})
+	};
+	if (isUseful(env.GITLAB_CI_JOB_ID)) return {
+		source: "GITLAB_CI_JOB_ID",
+		value: env.GITLAB_CI_JOB_ID,
+		metadata: decoration({
+			ci: true,
+			ci_provider: "gitlab"
+		})
+	};
+	return {
+		source: null,
+		value: null,
+		metadata: null
+	};
+};
+
+//#endregion
+export { probeHostMetadataFromEnv };

package/utils/resolve-data-path.js

@@ -0,0 +1,66 @@
+import { VitestAgentConfig } from "../schemas/Config.js";
+import { VitestAgentConfigFile } from "../services/Config.js";
+import { normalizeWorkspaceKey } from "./normalize-workspace-key.js";
+import { resolveProjectKeyFromCwd } from "./resolve-project-key-from-cwd.js";
+import { Effect } from "effect";
+import { join } from "node:path";
+import { mkdirSync } from "node:fs";
+import { AppDirs } from "xdg-effect";
+
+//#region src/utils/resolve-data-path.ts
+/**
+* Filename of the SQLite database that stores all reporter data.
+* @public
+*/
+const DATABASE_FILENAME = "data.db";
+/**
+* Resolve the absolute path to the SQLite database for `projectDir`.
+*
+* The directory containing the database is ensured to exist before the
+* function returns, so callers can open the database immediately without
+* needing to create parent directories. better-sqlite3 creates the file but
+* not its parent.
+*
+* Precedence (highest first):
+*
+* 1. `options.cacheDir` — programmatic override.
+* 2. `cacheDir` from `vitest-agent.config.toml`.
+* 3. `<XDG data>/<normalized projectKey from config>/data.db`.
+* 4. `<XDG data>/<projectKey resolved from cwd's package.json>/data.db`.
+*    Source 4 prefers `repository.url` (canonicalized to `host__path`),
+*    falling back to the normalized `name`. This matches the sidecar
+*    CLI's `_internal register-agent` resolver so the reporter and
+*    sidecar always write to the same `data.db`.
+*
+* The XDG data directory is namespaced via `AppDirs` (typically
+* `$XDG_DATA_HOME/vitest-agent`, defaulting to
+* `~/.local/share/vitest-agent`).
+*
+* The path is a function of identity, not filesystem layout. When no
+* `package.json` is reachable from `projectDir`, the cwd basename is used
+* as the final fallback so the function never throws on identity lookup.
+*
+* @param projectDir - Absolute path inside the user's workspace.
+* @param options - Optional programmatic overrides.
+* @public
+*/
+const resolveDataPath = (projectDir, options = {}) => Effect.gen(function* () {
+	if (options.cacheDir) {
+		ensureDirSync(options.cacheDir);
+		return join(options.cacheDir, DATABASE_FILENAME);
+	}
+	const loaded = yield* (yield* VitestAgentConfigFile).loadOrDefault(new VitestAgentConfig({}));
+	if (loaded.cacheDir) {
+		ensureDirSync(loaded.cacheDir);
+		return join(loaded.cacheDir, DATABASE_FILENAME);
+	}
+	const dir = join(yield* (yield* AppDirs).ensureData, loaded.projectKey ? normalizeWorkspaceKey(loaded.projectKey) : resolveProjectKeyFromCwd(projectDir));
+	ensureDirSync(dir);
+	return join(dir, DATABASE_FILENAME);
+});
+const ensureDirSync = (path) => {
+	mkdirSync(path, { recursive: true });
+};
+
+//#endregion
+export { DATABASE_FILENAME, resolveDataPath };

package/utils/resolve-project-key-from-cwd.js

@@ -0,0 +1,52 @@
+import { gitUrlToProjectKey } from "./canonicalize-git-url.js";
+import { normalizeWorkspaceKey } from "./normalize-workspace-key.js";
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+//#region src/utils/resolve-project-key-from-cwd.ts
+const PACKAGE_JSON = "package.json";
+const findNearestPackageJson = (startDir) => {
+	let dir = startDir;
+	while (true) {
+		const candidate = join(dir, PACKAGE_JSON);
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+};
+const readRepositoryUrl = (parsed) => {
+	const repo = parsed.repository;
+	if (typeof repo === "string" && repo.trim().length > 0) return repo.trim();
+	if (repo !== null && typeof repo === "object" && "url" in repo && typeof repo.url === "string") {
+		const url = repo.url.trim();
+		return url.length > 0 ? url : null;
+	}
+	return null;
+};
+/**
+* Compute the project key for a workspace by reading `package.json`
+* fields directly. Returns the canonical `host__path` form when a git
+* remote URL is present, otherwise the normalized package name.
+*
+* Always returns a non-empty string — falls back to the cwd basename
+* (or `"anonymous-project"`) so callers don't have to handle the
+* empty case.
+* @public
+*/
+const resolveProjectKeyFromCwd = (cwd) => {
+	const pkgPath = findNearestPackageJson(cwd);
+	if (pkgPath !== null) try {
+		const parsed = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		const repoUrl = readRepositoryUrl(parsed);
+		if (repoUrl !== null) {
+			const key = gitUrlToProjectKey(repoUrl);
+			if (key !== null) return key;
+		}
+		if (typeof parsed.name === "string" && parsed.name.length > 0) return normalizeWorkspaceKey(parsed.name);
+	} catch {}
+	return normalizeWorkspaceKey(cwd.split("/").filter((segment) => segment.length > 0).pop() ?? "anonymous-project");
+};
+
+//#endregion
+export { resolveProjectKeyFromCwd };

package/utils/resolve-workspace-key.js

@@ -0,0 +1,33 @@
+import { normalizeWorkspaceKey } from "./normalize-workspace-key.js";
+import { Effect } from "effect";
+import { WorkspaceDiscovery, WorkspaceRootNotFoundError } from "workspaces-effect";
+
+//#region src/utils/resolve-workspace-key.ts
+/**
+* Resolve the normalized workspace key for the workspace containing
+* `projectDir`.
+*
+* The key is the root `package.json`'s `name`, normalized via
+* `normalizeWorkspaceKey`. This becomes the directory segment under
+* `$XDG_DATA_HOME/vitest-agent/` where the SQLite database lives.
+*
+* Fails with `WorkspaceRootNotFoundError` when no root workspace is
+* discoverable from `projectDir`. `WorkspacePackage.name` is enforced
+* non-empty by `workspaces-effect`'s schema, so a successful root lookup
+* always yields a usable name.
+*
+* @param projectDir - Absolute path inside the workspace. Typically the
+*   reporter's resolved `projectDir` (CLAUDE_PROJECT_DIR or process.cwd()).
+* @public
+*/
+const resolveWorkspaceKey = (projectDir) => Effect.gen(function* () {
+	const root = (yield* (yield* WorkspaceDiscovery).listPackages(projectDir)).find((pkg) => pkg.isRootWorkspace);
+	if (!root) return yield* Effect.fail(new WorkspaceRootNotFoundError({
+		searchPath: projectDir,
+		reason: "No root workspace package found in the discovered package list."
+	}));
+	return normalizeWorkspaceKey(root.name);
+});
+
+//#endregion
+export { resolveWorkspaceKey };

package/utils/safe-filename.js

@@ -0,0 +1,34 @@
+//#region src/utils/safe-filename.ts
+/**
+* Convert a project name to a filesystem-safe filename.
+*
+* Replaces `/` and `:` characters with `__` (double underscore).
+* Returns `"default"` for empty strings, which is used as the
+* fallback project name for single-repo configurations.
+*
+* @param name - Project name to sanitize
+* @returns Filesystem-safe filename string
+*
+* @example
+* ```typescript
+* import { safeFilename } from "@vitest-agent/sdk/utils";
+*
+* safeFilename("\@savvy-web/my-lib:unit");
+* // Returns: "\@savvy-web__my-lib__unit"
+*
+* safeFilename("core");
+* // Returns: "core"
+*
+* safeFilename("");
+* // Returns: "default"
+* ```
+*
+* @public
+*/
+function safeFilename(name) {
+	if (!name) return "default";
+	return name.replace(/[/:]/g, "__");
+}
+
+//#endregion
+export { safeFilename };

package/utils/validate-coverage-targets-shape.js

@@ -0,0 +1,84 @@
+//#region src/utils/validate-coverage-targets-shape.ts
+/** Metric keys that may appear at the top level or inside a glob-pattern entry. */
+const METRIC_KEYS = /* @__PURE__ */ new Set([
+	"lines",
+	"functions",
+	"branches",
+	"statements",
+	"100"
+]);
+/** Pushes an INVALID_TARGET_VALUE error when the numeric value is zero or negative. */
+function checkNumericValue(value, path, errors) {
+	if (value <= 0) errors.push({
+		code: "INVALID_TARGET_VALUE",
+		path,
+		message: `Coverage target at "${path}" must be a positive number greater than zero, got ${value}.`
+	});
+}
+/** Emits an INVALID_TARGET_VALUE error when `true` appears at a key other than `"100"`. */
+function checkBooleanShortcut(key, path, errors) {
+	if (key === "100") return;
+	errors.push({
+		code: "INVALID_TARGET_VALUE",
+		path,
+		message: `Coverage target at "${path}" cannot be true. The "true" shorthand is only valid at key "100" (meaning 100% across all metrics).`
+	});
+}
+/** Checks all values inside a nested per-metric object (glob-pattern entry). */
+function checkNestedMetrics(nested, prefix, errors) {
+	for (const [metricKey, metricValue] of Object.entries(nested)) {
+		const path = `${prefix}.${metricKey}`;
+		if (typeof metricValue === "number") checkNumericValue(metricValue, path, errors);
+		else if (metricValue === true) checkBooleanShortcut(metricKey, path, errors);
+	}
+}
+/**
+* Validates the shape of a raw coverageTargets value, producing structured
+* diagnostic entries. This is a pure function with no Effect or I/O.
+*
+* Codes emitted:
+* - `INVALID_TARGET_VALUE` — a numeric metric value is zero or negative,
+*   OR a literal `true` appears at any key other than `"100"`. The
+*   offending `path` is included (e.g. `"lines"`, `"src/**.ts.lines"`,
+*   or `"statements"` when misused as a boolean shortcut).
+* - `PERFILE_ON_TARGETS` — the `perFile` key appears inside coverageTargets;
+*   it should be set on `coverage.thresholds.perFile` instead.
+*
+* @param input - The raw value passed as coverageTargets.
+* @returns A result object with errors, warnings, and info arrays.
+* @public
+*/
+function validateCoverageTargetsShape(input) {
+	const errors = [];
+	const warnings = [];
+	const info = [];
+	if (input === null || typeof input !== "object" || Array.isArray(input)) return {
+		errors,
+		warnings,
+		info
+	};
+	for (const [key, value] of Object.entries(input)) {
+		if (key === "perFile") {
+			warnings.push({
+				code: "PERFILE_ON_TARGETS",
+				path: key,
+				message: "The \"perFile\" key is not valid inside coverageTargets. Set coverage.thresholds.perFile instead."
+			});
+			continue;
+		}
+		if (METRIC_KEYS.has(key)) {
+			if (typeof value === "number") checkNumericValue(value, key, errors);
+			else if (value === true) checkBooleanShortcut(key, key, errors);
+		} else if (typeof value === "number") checkNumericValue(value, key, errors);
+		else if (value === true) checkBooleanShortcut(key, key, errors);
+		else if (value !== null && typeof value === "object" && !Array.isArray(value)) checkNestedMetrics(value, key, errors);
+	}
+	return {
+		errors,
+		warnings,
+		info
+	};
+}
+
+//#endregion
+export { validateCoverageTargetsShape };

package/utils/validate-phase-transition.js

@@ -0,0 +1,113 @@
+//#region src/utils/validate-phase-transition.ts
+/**
+* Return the artifact kind a phase transition requires, plus a
+* human-readable hint for surfacing in remediations.
+*
+* Exported so the MCP `tdd_phase_transition_request` tool can pre-compute
+* the expected kind when the agent omits `citedArtifactId` (auto-resolve
+* to the most recent matching artifact). The transitions without a
+* required artifact (`spike→red`, `*→red`, etc.) return `null`.
+* @public
+*/
+const requiredArtifactForTransition = (from, to) => {
+	if (from === "red" && to === "green") return {
+		kind: "test_failed_run",
+		humanHint: "Run the failing test via run_tests, then record the test_failed_run artifact before requesting red→green."
+	};
+	if (from === "green" && to === "refactor") return {
+		kind: "test_passed_run",
+		humanHint: "Run the test via run_tests and confirm it passes; record test_passed_run before requesting green→refactor."
+	};
+	if (from === "refactor" && to === "red") return {
+		kind: "test_passed_run",
+		humanHint: "Refactor must end with all tests still passing; record test_passed_run before starting the next behavior."
+	};
+	return null;
+};
+/** @public */
+const validatePhaseTransition = (ctx) => {
+	if (ctx.requested_phase === "green" && ctx.current_phase !== "red" && ctx.current_phase !== "red.triangulate" && ctx.current_phase !== "green.fake-it") return {
+		accepted: false,
+		phase: ctx.current_phase,
+		denialReason: "wrong_source_phase",
+		remediation: {
+			suggestedTool: "tdd_phase_transition_request",
+			suggestedArgs: { requestedPhase: "red" },
+			humanHint: `Cannot transition from '${ctx.current_phase}' directly to 'green'. The red phase must be entered explicitly first (${ctx.current_phase}→red), then a failing test written and run, then red→green requested with a test_failed_run artifact.`
+		}
+	};
+	const expected = requiredArtifactForTransition(ctx.current_phase, ctx.requested_phase);
+	if (expected === null) return {
+		accepted: true,
+		phase: ctx.requested_phase
+	};
+	if (ctx.cited_artifact.artifact_kind !== expected.kind) return {
+		accepted: false,
+		phase: ctx.current_phase,
+		denialReason: "wrong_artifact_kind",
+		remediation: {
+			suggestedTool: "run_tests",
+			suggestedArgs: {},
+			humanHint: expected.humanHint
+		}
+	};
+	if (ctx.cited_artifact.test_case_id === null) return {
+		accepted: false,
+		phase: ctx.current_phase,
+		denialReason: "missing_artifact_evidence",
+		remediation: {
+			suggestedTool: "run_tests",
+			suggestedArgs: {},
+			humanHint: "The cited artifact has no specific test (test_case_id is null), so it cannot be bound to this phase. Run a specific failing test via run_tests so the resulting artifact carries a test_case_id, then cite that artifact."
+		}
+	};
+	if (expected.kind === "test_failed_run") {
+		if (ctx.cited_artifact.test_case_created_turn_at !== null && ctx.cited_artifact.test_case_created_turn_at < ctx.phase_started_at) return {
+			accepted: false,
+			phase: ctx.current_phase,
+			denialReason: "evidence_not_in_phase_window",
+			remediation: {
+				suggestedTool: "run_tests",
+				suggestedArgs: {},
+				humanHint: "The cited test was authored before this phase started. Write a new failing test inside the current phase."
+			}
+		};
+		if (!ctx.cited_artifact.test_case_authored_in_session) return {
+			accepted: false,
+			phase: ctx.current_phase,
+			denialReason: "evidence_not_in_phase_window",
+			remediation: {
+				suggestedTool: "run_tests",
+				suggestedArgs: {},
+				humanHint: "The cited test was not authored in this TDD session. Write the test yourself in the current phase."
+			}
+		};
+	}
+	if (ctx.requested_behavior_id !== null && ctx.cited_artifact.behavior_id !== ctx.requested_behavior_id) return {
+		accepted: false,
+		phase: ctx.current_phase,
+		denialReason: "evidence_not_for_behavior",
+		remediation: {
+			suggestedTool: "run_tests",
+			suggestedArgs: {},
+			humanHint: "The cited artifact references a different behavior than the one being transitioned. Run the test for the requested behavior."
+		}
+	};
+	if (expected.kind === "test_failed_run" && ctx.cited_artifact.test_run_id !== null && ctx.cited_artifact.test_first_failure_run_id !== null && ctx.cited_artifact.test_first_failure_run_id !== ctx.cited_artifact.test_run_id) return {
+		accepted: false,
+		phase: ctx.current_phase,
+		denialReason: "evidence_test_was_already_failing",
+		remediation: {
+			suggestedTool: "run_tests",
+			suggestedArgs: {},
+			humanHint: "The cited test was already failing before this TDD session. Write a new test for the goal."
+		}
+	};
+	return {
+		accepted: true,
+		phase: ctx.requested_phase
+	};
+};
+
+//#endregion
+export { requiredArtifactForTransition, validatePhaseTransition };