@vitest-agent/cli 1.0.0

package/lib/internal-register-agent.js

@@ -0,0 +1,76 @@
+import { DataReader, DataStore, PerClientSessionMapWriter, RunContextService, deriveIdempotencyKey } from "@vitest-agent/sdk";
+import { Effect, Option } from "effect";
+
+//#region src/lib/internal-register-agent.ts
+const deriveDefaultClientNonce = (input) => {
+	const parent = input.parentAgentId ?? "__ROOT__";
+	return `${input.hostSessionId}|${input.agentType}|${parent}`;
+};
+/**
+* End-to-end agent registration.
+*
+* Returns the canonical `agentId` + the conversation it belongs to +
+* the resolved `idempotencyKey`. The `idempotencyHit` flag is `true`
+* when the per-project store recovered an existing agent row instead
+* of inserting a new one.
+*
+* @param input - registration inputs including host identifiers and agent metadata
+* @returns an Effect resolving to `RegisterAgentOutput`
+* @public
+*/
+const registerAgentEffect = (input) => Effect.gen(function* () {
+	const sessionMap = yield* PerClientSessionMapWriter;
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	const ctx = yield* RunContextService;
+	const conversationId = yield* sessionMap.mapConversation(input.transcriptPath);
+	const sessionMapping = yield* sessionMap.mapSession({
+		hostSessionId: input.hostSessionId,
+		conversationId,
+		projectKey: input.projectKey,
+		projectDir: input.cwd
+	});
+	const existingSession = yield* reader.getSessionByChatId(input.hostSessionId);
+	const sessionRowId = yield* Option.match(existingSession, {
+		onNone: () => store.writeSession({
+			chatId: input.hostSessionId,
+			project: input.projectKey,
+			cwd: input.cwd,
+			agentKind: input.parentAgentId === void 0 ? "main" : "subagent",
+			agentType: input.agentType,
+			triageWasNonEmpty: false,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}),
+		onSome: (s) => Effect.succeed(s.id)
+	});
+	const agentContext = yield* ctx.captureAgentContext(input.cwd);
+	const clientNonce = input.clientNonce ?? deriveDefaultClientNonce(input);
+	const idempotencyKey = deriveIdempotencyKey({
+		agentType: input.agentType,
+		parentAgentId: input.parentAgentId ?? null,
+		clientNonce
+	});
+	const result = yield* store.registerAgent({
+		sessionId: sessionRowId,
+		agentType: input.agentType,
+		parentAgentId: input.parentAgentId ?? null,
+		conversationId,
+		startedAt: Math.floor(Date.now() / 1e3),
+		...agentContext.startGitBranch !== null && { startGitBranch: agentContext.startGitBranch },
+		...agentContext.startGitCommitSha !== null && { startGitCommitSha: agentContext.startGitCommitSha },
+		...agentContext.startWorktreeDir !== null && { startWorktreeDir: agentContext.startWorktreeDir },
+		idempotencyKey,
+		agentId: sessionMapping.mainAgentId
+	});
+	const isHit = result._tag === "IdempotencyHit";
+	return {
+		agentId: isHit ? result.existingAgentId : result.agentId,
+		conversationId,
+		mainAgentId: sessionMapping.mainAgentId,
+		idempotencyKey,
+		idempotencyHit: isHit
+	};
+});
+
+//#endregion
+export { registerAgentEffect };

package/lib/record-session.js

@@ -0,0 +1,33 @@
+import { DataReader, DataStore } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+
+//#region src/lib/record-session.ts
+const recordSessionStart = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	let parentSessionId;
+	if (input.parentChatId !== void 0) {
+		const parent = yield* reader.getSessionByChatId(input.parentChatId);
+		if (parent._tag === "Some") parentSessionId = parent.value.id;
+	}
+	return { sessionId: yield* store.upsertSession({
+		chatId: input.chatId,
+		project: input.project,
+		cwd: input.cwd,
+		agentKind: input.agentKind,
+		...input.agentType !== void 0 && { agentType: input.agentType },
+		...parentSessionId !== void 0 && { parentSessionId },
+		triageWasNonEmpty: input.triageWasNonEmpty,
+		startedAt: input.startedAt
+	}) };
+});
+const recordSessionEnd = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	if ((yield* reader.getSessionByChatId(input.chatId))._tag === "None") return yield* Effect.fail(/* @__PURE__ */ new Error(`Unknown chatId: ${input.chatId}`));
+	yield* store.endSession(input.chatId, input.endedAt, input.endReason);
+	return { ok: true };
+});
+
+//#endregion
+export { recordSessionEnd, recordSessionStart };

package/lib/record-tdd-artifact.js

@@ -0,0 +1,40 @@
+import { resolveSessionForRecording } from "./resolve-session-for-recording.js";
+import { DataReader, DataStore } from "@vitest-agent/sdk";
+import { Effect, Option } from "effect";
+
+//#region src/lib/record-tdd-artifact.ts
+const recordTddArtifactEffect = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	const session = yield* resolveSessionForRecording({
+		chatId: input.chatId,
+		recordedAt: input.recordedAt,
+		...input.project !== void 0 && { project: input.project },
+		...input.cwd !== void 0 && { cwd: input.cwd }
+	});
+	const openTdd = (yield* reader.listTddTasksForSession(session.id, { walkParents: true })).find((t) => t.endedAt === null);
+	if (openTdd === void 0) return yield* Effect.fail(/* @__PURE__ */ new Error(`No open TDD task under chat_id ${input.chatId}. Call tdd_task start first.`));
+	const phaseOpt = yield* reader.getCurrentTddPhase(openTdd.id);
+	const phaseId = Option.isSome(phaseOpt) ? phaseOpt.value.id : (yield* store.writeTddPhase({
+		tddTaskId: openTdd.id,
+		phase: "spike",
+		startedAt: input.recordedAt,
+		transitionReason: "auto-opened by record tdd-artifact (no prior phase)"
+	})).id;
+	return {
+		id: yield* store.writeTddArtifact({
+			phaseId,
+			artifactKind: input.artifactKind,
+			...input.fileId !== void 0 && { fileId: input.fileId },
+			...input.testCaseId !== void 0 && { testCaseId: input.testCaseId },
+			...input.testRunId !== void 0 && { testRunId: input.testRunId },
+			...input.testFirstFailureRunId !== void 0 && { testFirstFailureRunId: input.testFirstFailureRunId },
+			...input.diffExcerpt !== void 0 && { diffExcerpt: input.diffExcerpt },
+			recordedAt: input.recordedAt
+		}),
+		phaseId
+	};
+});
+
+//#endregion
+export { recordTddArtifactEffect };

package/lib/record-turn.js

@@ -0,0 +1,44 @@
+import { resolveSessionForRecording } from "./resolve-session-for-recording.js";
+import { DataStore, TurnPayload } from "@vitest-agent/sdk";
+import { Effect, Schema } from "effect";
+
+//#region src/lib/record-turn.ts
+const parseAndValidateTurnPayload = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		return {
+			ok: false,
+			error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`
+		};
+	}
+	const decoded = Schema.decodeUnknownEither(TurnPayload)(parsed);
+	if (decoded._tag === "Left") return {
+		ok: false,
+		error: `Invalid TurnPayload: ${decoded.left.message}`
+	};
+	return {
+		ok: true,
+		payload: decoded.right
+	};
+};
+const recordTurnEffect = (input) => Effect.gen(function* () {
+	const parse = parseAndValidateTurnPayload(input.payloadJson);
+	if (!parse.ok) return yield* Effect.fail(new Error(parse.error));
+	const session = yield* resolveSessionForRecording({
+		chatId: input.chatId,
+		recordedAt: input.occurredAt,
+		...input.project !== void 0 && { project: input.project },
+		...input.cwd !== void 0 && { cwd: input.cwd }
+	});
+	return { turnId: yield* (yield* DataStore).writeTurn({
+		sessionId: session.id,
+		type: parse.payload.type,
+		payload: input.payloadJson,
+		occurredAt: input.occurredAt
+	}) };
+});
+
+//#endregion
+export { recordTurnEffect };

package/lib/record-workspace-changes.js

@@ -0,0 +1,64 @@
+import { DataStore } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+import { SqlClient } from "@effect/sql/SqlClient";
+
+//#region src/lib/record-workspace-changes.ts
+/**
+* Lib function for the `record run-workspace-changes` CLI subcommand.
+*
+* Driven by the PostToolUse hook on `git commit` / `git push`. Writes a
+* commits row (idempotent on sha via ON CONFLICT DO NOTHING in
+* DataStore.writeCommit) and zero or more run_changed_files rows.
+*
+* Optionally associates the changed files with a test_run_id; for the
+* commit-side write path we don't have a run, so we associate the files
+* with the most-recent test_run for the project (best-effort) or skip
+* the file rows entirely if no test_run exists yet.
+*
+* @packageDocumentation
+*/
+/**
+* `ProjectRunSummary` doesn't expose `lastRunId`, so we query it directly
+* via SqlClient. This is the run id of the most-recent test run for a
+* given project (or any project, when `project` is unspecified). Used
+* only as a best-effort association target for `run_changed_files`.
+*/
+const findLatestRunId = (project) => Effect.gen(function* () {
+	const sql = yield* SqlClient;
+	const rows = project !== void 0 ? yield* sql`
+						SELECT id FROM test_runs
+						WHERE project = ${project}
+						ORDER BY timestamp DESC LIMIT 1
+					` : yield* sql`
+						SELECT id FROM test_runs
+						ORDER BY timestamp DESC LIMIT 1
+					`;
+	return rows.length === 0 ? null : rows[0].id;
+}).pipe(Effect.orElseSucceed(() => null));
+const recordRunWorkspaceChangesEffect = (input) => Effect.gen(function* () {
+	const store = yield* DataStore;
+	yield* store.writeCommit({
+		sha: input.sha,
+		...input.parentSha !== void 0 && { parentSha: input.parentSha },
+		...input.message !== void 0 && { message: input.message },
+		...input.author !== void 0 && { author: input.author },
+		...input.committedAt !== void 0 && { committedAt: input.committedAt },
+		...input.branch !== void 0 && { branch: input.branch }
+	});
+	const runId = yield* findLatestRunId(input.project);
+	if (runId !== null && input.files.length > 0) yield* store.writeRunChangedFiles({
+		runId,
+		files: input.files.map((f) => ({
+			filePath: f.filePath,
+			changeKind: f.changeKind,
+			commitSha: input.sha
+		}))
+	});
+	return {
+		sha: input.sha,
+		fileRowsWritten: runId !== null ? input.files.length : 0
+	};
+});
+
+//#endregion
+export { recordRunWorkspaceChangesEffect };

package/lib/resolve-session-for-recording.js

@@ -0,0 +1,71 @@
+import { DataReader, DataStore } from "@vitest-agent/sdk";
+import { Effect, Option } from "effect";
+import { readFileSync } from "node:fs";
+
+//#region src/lib/resolve-session-for-recording.ts
+/**
+* Shared session-resolution helper for hook-driven recording paths.
+*
+* Background: Claude Code can rotate the chat id (host `session_id`)
+* mid-window — after a continuation, compaction, or `/mcp` reconnect —
+* without the `SessionStart` hook firing for the new id. PostToolUse
+* hooks then deliver tool calls under a `chat_id` that has no row in
+* `sessions`, and the strict `getSessionByChatId` lookup fails with
+* "Unknown chat_id". A second flavour of the same bug: the
+* SubagentStart hook mints a synthetic per-dispatch key
+* (`<parentChatId>-subagent-<ts>-<pid>`) for the subagent row, but
+* subsequent PostToolUse hooks under that subagent receive the bare
+* parent chat id. Exact-match lookup of the bare id misses the
+* synthetic suffix.
+*
+* This resolver applies a three-step fallback that recovers either
+* case without crashing the recording path:
+*
+*   1. Exact match by `chat_id`.
+*   2. Prefix match `<chatId>-subagent-` to recover the synthetic
+*      subagent row (most recent first).
+*   3. Idempotent bootstrap of a `main` session row keyed on the
+*      input `chat_id`, so future calls in this window resolve via
+*      step 1.
+*
+* Step 3 means recording paths can no longer fail with "Unknown
+* chat_id". Bootstrapped rows carry `agent_kind = "main"` and
+* `triage_was_non_empty = false` because the SessionStart triage
+* pipeline never ran for them; downstream metrics consumers should
+* treat triage-empty bootstrapped rows the same as any other
+* SessionStart-less row.
+*
+* @packageDocumentation
+*/
+const resolveSessionForRecording = (input) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const store = yield* DataStore;
+	const exact = yield* reader.getSessionByChatId(input.chatId);
+	if (Option.isSome(exact)) return exact.value;
+	const synthetic = yield* reader.findSessionsByChatPrefix(`${input.chatId}-subagent-`);
+	if (synthetic.length > 0) return synthetic[0];
+	const cwd = input.cwd ?? process.cwd();
+	const project = input.project ?? readPackageName(cwd) ?? "unknown";
+	yield* store.upsertSession({
+		chatId: input.chatId,
+		project,
+		cwd,
+		agentKind: "main",
+		triageWasNonEmpty: false,
+		startedAt: input.recordedAt
+	});
+	const created = yield* reader.getSessionByChatId(input.chatId);
+	return Option.getOrThrowWith(created, () => /* @__PURE__ */ new Error(`upsertSession succeeded but row not found for ${input.chatId}`));
+});
+const readPackageName = (cwd) => {
+	try {
+		const raw = readFileSync(`${cwd}/package.json`, "utf8");
+		const parsed = JSON.parse(raw);
+		return typeof parsed.name === "string" ? parsed.name : void 0;
+	} catch {
+		return;
+	}
+};
+
+//#endregion
+export { resolveSessionForRecording };

package/lib/sidecar-paths.js

@@ -0,0 +1,101 @@
+import { ProjectIdentityNotResolvableError } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+//#region src/lib/sidecar-paths.ts
+const APP_NAMESPACE = "vitest-agent";
+/**
+* Filename of the per-project test-data SQLite database.
+*
+* @public
+*/
+const DATA_DB_FILENAME = "data.db";
+/**
+* Filename of the per-client session-map SQLite database.
+*
+* @public
+*/
+const SESSIONS_DB_FILENAME = "sessions.db";
+/**
+* Filename of the global discovery-registry SQLite database.
+*
+* @public
+*/
+const REGISTRY_DB_FILENAME = "registry.db";
+const resolveXdgDataHome = () => {
+	const xdg = process.env.XDG_DATA_HOME;
+	if (xdg !== void 0 && xdg.length > 0) return xdg;
+	return join(homedir(), ".local", "share");
+};
+/**
+* Resolve (and create) the per-project data directory for the supplied
+* normalized `projectKey`. Returns the directory; callers join
+* {@link DATA_DB_FILENAME} onto it for the `data.db` path.
+*
+* @param projectKey - normalized project key (e.g. `@org__pkg`)
+* @returns absolute path to the resolved (and created) data directory
+* @public
+*/
+const resolveProjectDataDir = (projectKey) => {
+	const dir = join(resolveXdgDataHome(), APP_NAMESPACE, projectKey);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+};
+/**
+* Resolve (and create) the directory holding the global `registry.db`.
+* Callers join {@link REGISTRY_DB_FILENAME} onto it.
+*
+* @returns absolute path to the resolved (and created) registry directory
+* @public
+*/
+const resolveRegistryDir = () => {
+	const dir = join(resolveXdgDataHome(), APP_NAMESPACE);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+};
+/**
+* Resolve the per-client `sessions.db` path.
+*
+* Precedence: the `CLAUDE_PLUGIN_DATA` env var, then
+* `VITEST_AGENT_SESSION_MAP_DIR`, then `~/.vitest-agent/`. Fails
+* with `ProjectIdentityNotResolvableError` when no home directory
+* is resolvable.
+*
+* @returns an Effect resolving to the absolute `sessions.db` path
+* @public
+*/
+const resolveSessionMapPath = () => Effect.sync(() => {
+	const claudePluginData = process.env.CLAUDE_PLUGIN_DATA;
+	if (claudePluginData !== void 0 && claudePluginData.length > 0) {
+		mkdirSync(claudePluginData, { recursive: true });
+		return join(claudePluginData, SESSIONS_DB_FILENAME);
+	}
+	const overrideDir = process.env.VITEST_AGENT_SESSION_MAP_DIR;
+	if (overrideDir !== void 0 && overrideDir.length > 0) {
+		mkdirSync(overrideDir, { recursive: true });
+		return join(overrideDir, SESSIONS_DB_FILENAME);
+	}
+	const home = process.env.HOME ?? process.env.USERPROFILE;
+	if (home === void 0 || home.length === 0) return null;
+	const fallbackDir = join(home, ".vitest-agent");
+	mkdirSync(fallbackDir, { recursive: true });
+	return join(fallbackDir, SESSIONS_DB_FILENAME);
+}).pipe(Effect.flatMap((path) => path !== null ? Effect.succeed(path) : Effect.fail(new ProjectIdentityNotResolvableError({ tried: [
+	{
+		source: "CLAUDE_PLUGIN_DATA",
+		reason: "env var not set"
+	},
+	{
+		source: "VITEST_AGENT_SESSION_MAP_DIR",
+		reason: "env var not set"
+	},
+	{
+		source: "HOME",
+		reason: "env var not set (USERPROFILE also unset)"
+	}
+] }))));
+
+//#endregion
+export { DATA_DB_FILENAME, REGISTRY_DB_FILENAME, SESSIONS_DB_FILENAME, resolveProjectDataDir, resolveRegistryDir, resolveSessionMapPath };

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@vitest-agent/cli",
+	"version": "1.0.0",
+	"private": false,
+	"description": "On-demand CLI for vitest-agent. Reads cached test data and reports status, overview, coverage, history, trends, and cache health.",
+	"keywords": [
+		"vitest",
+		"agent",
+		"cli",
+		"tests",
+		"coverage"
+	],
+	"homepage": "https://github.com/spencerbeggs/vitest-agent#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/vitest-agent/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/vitest-agent.git",
+		"directory": "packages/cli"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"vitest-agent": "bin/vitest-agent.js"
+	},
+	"dependencies": {
+		"@effect/cli": "^0.75.2",
+		"@effect/cluster": "^0.59.0",
+		"@effect/platform": "^0.96.2",
+		"@effect/platform-node": "^0.107.0",
+		"@effect/rpc": "^0.75.1",
+		"@effect/sql": "^0.51.1",
+		"@effect/sql-sqlite-node": "^0.52.0",
+		"@vitest-agent/sdk": "1.0.0",
+		"@vitest-agent/sidecar": "1.0.0",
+		"effect": "^3.21.4"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}