@mark1russell7/client-vitest 0.0.0-stage → 0.1.0

package/src/module.ts

@@ -0,0 +1,104 @@
+/**
+ * Module (no side effects): the vitest procedures as data, for `createRegistry()`.
+ */
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule } from "@mark1russell7/client";
+import {
+  VitestCoverageInputSchema,
+  VitestListInputSchema,
+  VitestRunInputSchema,
+  VitestStopInputSchema,
+  VitestWatchInputSchema,
+  type VitestListOutput,
+  type VitestRunOutput,
+  type VitestStopOutput,
+  type VitestWatchOutput,
+  VitestRunOutputSchema,
+  VitestWatchOutputSchema,
+  VitestStopOutputSchema,
+  VitestListOutputSchema,
+} from "./types.js";
+import { vitestCoverage, vitestRun } from "./procedures/vitest/run.js";
+import { vitestWatch } from "./procedures/vitest/watch.js";
+import { vitestStop } from "./procedures/vitest/stop.js";
+import { vitestList } from "./procedures/vitest/list.js";
+
+const vitestRunProcedure = createProcedure()
+  .path(["vitest", "run"])
+  .input(zodAdapter(VitestRunInputSchema))
+  .output(zodAdapter<VitestRunOutput>(VitestRunOutputSchema))
+  .meta({
+    description: "Run vitest tests once (no shell; uses the project's own vitest)",
+    // Positional field names, and field -> short flag (the convention mark's CLI parser reads)
+    args: ["cwd"],
+    shorts: { coverage: "c" },
+    output: "json",
+  })
+  .handler(vitestRun)
+  .build();
+
+const vitestCoverageProcedure = createProcedure()
+  .path(["vitest", "coverage"])
+  .input(zodAdapter(VitestCoverageInputSchema))
+  .output(zodAdapter<VitestRunOutput>(VitestRunOutputSchema))
+  .meta({
+    description: "Run vitest once with coverage, and check a minimum line coverage (no shell)",
+    args: ["cwd"],
+    shorts: { threshold: "t" },
+    output: "json",
+  })
+  .handler(vitestCoverage)
+  .build();
+
+const vitestWatchProcedure = createProcedure()
+  .path(["vitest", "watch"])
+  .input(zodAdapter(VitestWatchInputSchema))
+  .output(zodAdapter<VitestWatchOutput>(VitestWatchOutputSchema))
+  .meta({
+    description: "Start vitest in watch mode (no shell; uses the project's own vitest)",
+    args: ["cwd"],
+    shorts: {},
+    output: "json",
+  })
+  .handler(vitestWatch)
+  .build();
+
+const vitestStopProcedure = createProcedure()
+  .path(["vitest", "stop"])
+  .input(zodAdapter(VitestStopInputSchema))
+  .output(zodAdapter<VitestStopOutput>(VitestStopOutputSchema))
+  .meta({
+    description: "Stop a vitest watch process (all of them without an id)",
+    args: ["id"],
+    shorts: {},
+    output: "json",
+  })
+  .handler(vitestStop)
+  .build();
+
+const vitestListProcedure = createProcedure()
+  .path(["vitest", "list"])
+  .input(zodAdapter(VitestListInputSchema))
+  .output(zodAdapter<VitestListOutput>(VitestListOutputSchema))
+  .meta({
+    description: "List the vitest watch processes of this host",
+    args: [],
+    shorts: {},
+    output: "json",
+  })
+  .handler(vitestList)
+  .build();
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const vitestModule: ProcedureModule = defineModule("@mark1russell7/client-vitest", [
+  vitestRunProcedure,
+  vitestCoverageProcedure,
+  vitestWatchProcedure,
+  vitestStopProcedure,
+  vitestListProcedure,
+]);
+
+export default vitestModule;

package/src/procedures/vitest/index.ts

@@ -0,0 +1,4 @@
+export { vitestRun, vitestCoverage } from "./run.js";
+export { vitestWatch } from "./watch.js";
+export { vitestStop } from "./stop.js";
+export { vitestList } from "./list.js";

package/src/procedures/vitest/list.ts

@@ -0,0 +1,33 @@
+/**
+ * vitest.list procedure
+ *
+ * List the vitest watch processes
+ */
+
+import { processes } from "@mark1russell7/client-shell/command";
+import type { VitestListInput, VitestListOutput, VitestProcessInfo } from "../../types.js";
+import { VITEST_GROUP } from "./watch.js";
+
+/**
+ * List the vitest watch processes of this host: the running ones and the recent exits
+ */
+export async function vitestList(
+  input: VitestListInput,
+  _ctx: { metadata: Record<string, unknown> }
+): Promise<VitestListOutput> {
+  return {
+    processes: processes.list({ group: VITEST_GROUP }).map((info) => {
+      const entry: VitestProcessInfo = {
+        id: info.id,
+        pid: info.pid,
+        status: info.status,
+        startedAt: info.startedAt,
+      };
+      if (info.cwd !== undefined) entry.cwd = info.cwd;
+      if (info.exitedAt !== undefined) entry.exitedAt = info.exitedAt;
+      if (info.exitCode !== undefined) entry.exitCode = info.exitCode;
+      if (input.output) entry.output = processes.output(info.id);
+      return entry;
+    }),
+  };
+}

package/src/procedures/vitest/run.ts

@@ -0,0 +1,145 @@
+/**
+ * vitest.run and vitest.coverage: run the tests of a project once, with the project's own vitest.
+ *
+ * The result has the counts from vitest's JSON report, the exit code and the end of the output.
+ * With `coverage`, it also has the coverage percentages from a `json-summary` report. Both reports
+ * go to a temporary folder. (vitest.coverage replaces test.coverage of the retired client-test.)
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCommand } from "@mark1russell7/client-shell/command";
+import type { VitestCoverageInput, VitestRunInput, VitestRunOutput } from "../../types.js";
+import { resolveVitestCli } from "../../vitest-cli.js";
+
+/** The procedure keeps the last 64 KiB of each output stream. */
+const OUTPUT_LIMIT = 64 * 1024;
+
+function assertPattern(pattern: string): string {
+  if (pattern.startsWith("-")) {
+    throw new Error(`Invalid test pattern (starts with "-"): ${pattern}`);
+  }
+  return pattern;
+}
+
+interface VitestJsonReport {
+  success?: boolean;
+  numPassedTests?: number;
+  numFailedTests?: number;
+  numPendingTests?: number;
+  startTime?: number;
+}
+
+interface CoverageSummary {
+  total?: Record<"lines" | "branches" | "functions" | "statements", { pct?: number } | undefined>;
+}
+
+function readCoverage(file: string): VitestRunOutput["coverage"] {
+  if (!existsSync(file)) return undefined;
+  const total = (JSON.parse(readFileSync(file, "utf8")) as CoverageSummary).total;
+  if (!total) return undefined;
+  return {
+    lines: total.lines?.pct ?? 0,
+    branches: total.branches?.pct ?? 0,
+    functions: total.functions?.pct ?? 0,
+    statements: total.statements?.pct ?? 0,
+  };
+}
+
+/** The part of the procedure context that the vitest procedures read. */
+interface VitestContext {
+  metadata: Record<string, unknown>;
+  signal?: AbortSignal | undefined;
+}
+
+export async function vitestRun(
+  input: VitestRunInput,
+  ctx: VitestContext
+): Promise<VitestRunOutput> {
+  if (input.watch) {
+    throw new Error("vitest.run runs the tests once. Use vitest.watch for watch mode.");
+  }
+
+  const cwd = input.cwd ?? process.cwd();
+  const cli = resolveVitestCli(cwd);
+
+  // The reports go to files, so the reporter of the reader prints to stdout
+  const reportDir = mkdtempSync(join(tmpdir(), "vitest-run-"));
+  const reportFile = join(reportDir, "report.json");
+  const coverageDir = join(reportDir, "coverage");
+
+  const reporter = input.reporter && input.reporter !== "json" ? input.reporter : "default";
+  const args = [cli, "run", "--reporter", reporter, "--reporter", "json", "--outputFile.json", reportFile];
+  for (const pattern of input.include ?? []) {
+    args.push(assertPattern(pattern));
+  }
+  for (const pattern of input.exclude ?? []) {
+    args.push("--exclude", assertPattern(pattern));
+  }
+  if (input.coverage) {
+    args.push(
+      "--coverage.enabled",
+      "--coverage.reporter=json-summary",
+      "--coverage.reporter=text-summary",
+      `--coverage.reportsDirectory=${coverageDir}`,
+    );
+  }
+  if (input.passWithNoTests) {
+    args.push("--passWithNoTests");
+  }
+
+  const started = Date.now();
+  // No shell: test patterns cannot inject commands. The signal kills vitest and its workers.
+  const run = await runCommand(process.execPath, {
+    args,
+    cwd,
+    signal: ctx.signal,
+    maxOutputBytes: OUTPUT_LIMIT,
+    keep: "tail",
+  });
+  if (run.error) {
+    rmSync(reportDir, { recursive: true, force: true });
+    throw new Error(`vitest did not start: ${run.error}`);
+  }
+  const code = run.signal ? null : run.exitCode;
+
+  const output = { exitCode: code ?? -1, stdout: run.stdout, stderr: run.stderr };
+  try {
+    const coverage = input.coverage ? readCoverage(join(coverageDir, "coverage-summary.json")) : undefined;
+    let report: VitestJsonReport | undefined;
+    try {
+      report = JSON.parse(readFileSync(reportFile, "utf8")) as VitestJsonReport;
+    } catch {
+      // No report: vitest failed before it ran the tests (for example, a config error)
+    }
+    return {
+      success: report?.success ?? code === 0,
+      passed: report?.numPassedTests ?? 0,
+      failed: report?.numFailedTests ?? (code === 0 ? 0 : 1),
+      skipped: report?.numPendingTests ?? 0,
+      duration: report?.startTime ? Date.now() - report.startTime : Date.now() - started,
+      ...output,
+      ...(coverage ? { coverage } : {}),
+    };
+  } finally {
+    rmSync(reportDir, { recursive: true, force: true });
+  }
+}
+
+export async function vitestCoverage(
+  input: VitestCoverageInput,
+  ctx: VitestContext
+): Promise<VitestRunOutput> {
+  const { threshold, ...run } = input;
+  const result = await vitestRun({ ...run, coverage: true }, ctx);
+  if (threshold === undefined || !result.success) return result;
+  if (!result.coverage) {
+    return {
+      ...result,
+      success: false,
+      stderr: `${result.stderr}\nNo coverage report: is a coverage provider (@vitest/coverage-v8) installed?`,
+    };
+  }
+  return { ...result, success: result.coverage.lines >= threshold };
+}

package/src/procedures/vitest/stop.ts

@@ -0,0 +1,29 @@
+/**
+ * vitest.stop procedure
+ *
+ * Stop a vitest watch process
+ */
+
+import { processes } from "@mark1russell7/client-shell/command";
+import type { VitestStopInput, VitestStopOutput } from "../../types.js";
+import { VITEST_GROUP } from "./watch.js";
+
+/**
+ * Stop a vitest watch process (the whole process tree), or every one when no id is given
+ */
+export async function vitestStop(
+  input: VitestStopInput,
+  _ctx: { metadata: Record<string, unknown> }
+): Promise<VitestStopOutput> {
+  const running = processes
+    .list({ group: VITEST_GROUP })
+    .filter((info) => info.status === "running" && (input.id === undefined || info.id === input.id));
+  if (input.id !== undefined && running.length === 0) {
+    return { success: false, stopped: [] };
+  }
+  const stopped: string[] = [];
+  for (const info of running) {
+    if ((await processes.stop(info.id)).stopped) stopped.push(info.id);
+  }
+  return { success: true, stopped };
+}

package/src/procedures/vitest/watch.ts

@@ -0,0 +1,46 @@
+/**
+ * vitest.watch procedure
+ *
+ * Start vitest in watch mode, as a process of the process registry of client-shell. vitest.list
+ * shows it and vitest.stop ends it, and it ends with the host (deep dive WRP-4). Before, the
+ * process started detached and the procedure forgot it: nothing could stop it.
+ */
+
+import { processes } from "@mark1russell7/client-shell/command";
+import type { VitestWatchInput, VitestWatchOutput } from "../../types.js";
+import { resolveVitestCli } from "../../vitest-cli.js";
+
+/** The group of the vitest processes in the process registry. */
+export const VITEST_GROUP = "vitest";
+
+export async function vitestWatch(
+  input: VitestWatchInput,
+  _ctx: { metadata: Record<string, unknown> }
+): Promise<VitestWatchOutput> {
+  const cwd = input.cwd ?? process.cwd();
+  const args = [resolveVitestCli(cwd), "watch"];
+
+  for (const pattern of input.include ?? []) {
+    if (pattern.startsWith("-")) {
+      throw new Error(`Invalid test pattern (starts with "-"): ${pattern}`);
+    }
+    args.push(pattern);
+  }
+
+  // No shell: test patterns cannot inject commands
+  const started = processes.start(process.execPath, {
+    args,
+    cwd,
+    group: VITEST_GROUP,
+    label: `vitest watch ${cwd}`,
+  });
+  if (started.status === "error") {
+    throw new Error(`vitest did not start: ${started.error ?? "unknown error"}`);
+  }
+
+  return {
+    id: started.id,
+    pid: started.pid,
+    status: "started",
+  };
+}

package/src/register.ts

@@ -0,0 +1,17 @@
+/**
+ * Importing this file registers the procedures of @mark1russell7/client-vitest in the global
+ * registry (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as
+ * data are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+
+import { registerProcedures } from "@mark1russell7/client";
+import { vitestModule } from "./module.js";
+
+export * from "./module.js";
+
+export function registerVitestProcedures(): void {
+  registerProcedures(vitestModule.procedures);
+}
+
+// Auto-register when this module is loaded
+registerVitestProcedures();

package/src/types.ts

@@ -0,0 +1,164 @@
+import { z } from "zod";
+
+export const VitestRunInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+  include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  watch: z.ZodOptional<z.ZodBoolean>;
+  coverage: z.ZodOptional<z.ZodBoolean>;
+  reporter: z.ZodOptional<z.ZodEnum<{ default: "default"; verbose: "verbose"; json: "json"; junit: "junit" }>>;
+  passWithNoTests: z.ZodOptional<z.ZodBoolean>;
+}> = z.object({
+  cwd: z.string().optional().describe("The folder of the project (default: the current folder)"),
+  include: z.array(z.string()).optional().describe("Test files or patterns to run (default: all tests)"),
+  exclude: z.array(z.string()).optional().describe("Test files or patterns to leave out"),
+  watch: z.boolean().optional().describe("Run in watch mode (use vitest.watch for a long-running watcher)"),
+  coverage: z.boolean().optional().describe("Measure the coverage and give the percentages"),
+  reporter: z.enum(["default", "verbose", "json", "junit"]).optional().describe("The vitest reporter"),
+  passWithNoTests: z.boolean().optional().describe("Succeed when no test file matches"),
+});
+export type VitestRunInput = z.infer<typeof VitestRunInputSchema>;
+
+export interface VitestRunOutput {
+  success: boolean;
+  passed: number;
+  failed: number;
+  skipped: number;
+  duration: number;
+  /** The exit code of vitest (-1 when a signal ended it) */
+  exitCode: number;
+  /** The last 64 KiB of the output */
+  stdout: string;
+  stderr: string;
+  coverage?: { lines: number; branches: number; functions: number; statements: number } | undefined;
+}
+
+// Output schemas (roadmap 2.1). Loose objects: a field that a schema does not name stays in the
+// result (a strict schema would remove it when the output is validated).
+
+export const VitestRunOutputSchema: z.ZodType<VitestRunOutput> = z.looseObject({
+  success: z.boolean().describe("True when vitest ended with exit code 0 (and, for vitest.coverage, the threshold is met)"),
+  passed: z.number().describe("The number of tests that passed"),
+  failed: z.number().describe("The number of tests that failed"),
+  skipped: z.number().describe("The number of tests that were skipped"),
+  duration: z.number().describe("The time of the run, in milliseconds"),
+  exitCode: z.number().describe("The exit code of vitest (-1 when a signal ended it)"),
+  stdout: z.string().describe("The last 64 KiB of the output"),
+  stderr: z.string().describe("The last 64 KiB of the error output"),
+  coverage: z
+    .looseObject({
+      lines: z.number().describe("The line coverage, in percent"),
+      branches: z.number().describe("The branch coverage, in percent"),
+      functions: z.number().describe("The function coverage, in percent"),
+      statements: z.number().describe("The statement coverage, in percent"),
+    })
+    .optional()
+    .describe("The coverage percentages, when the run measured coverage"),
+});
+
+export const VitestCoverageInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+  include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  threshold: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  cwd: z.string().optional().describe("The folder of the project (default: the current folder)"),
+  include: z.array(z.string()).optional().describe("Test files or patterns to run (default: all tests)"),
+  exclude: z.array(z.string()).optional().describe("Test files or patterns to leave out"),
+  /** The minimum line coverage in percent. Below it, the result has `success: false`. */
+  threshold: z.number().optional().describe("The minimum line coverage in percent. Below it, the result has `success: false`."),
+});
+export type VitestCoverageInput = z.infer<typeof VitestCoverageInputSchema>;
+
+export const VitestWatchInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+  include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}> = z.object({
+  cwd: z.string().optional().describe("The folder of the project (default: the current folder)"),
+  include: z.array(z.string()).optional().describe("Test files or patterns to watch (default: all tests)"),
+});
+export type VitestWatchInput = z.infer<typeof VitestWatchInputSchema>;
+
+export interface VitestWatchOutput {
+  /** The id of the process in the process registry: vitest.stop takes it */
+  id: string;
+  pid: number;
+  status: "started" | "stopped";
+}
+
+export const VitestWatchOutputSchema: z.ZodType<VitestWatchOutput> = z.looseObject({
+  id: z.string().describe("The id of the process in the process registry: vitest.stop takes it"),
+  pid: z.number().describe("The process id of vitest"),
+  status: z.enum(["started", "stopped"]).describe("started, or stopped when vitest ended at once"),
+});
+
+// =============================================================================
+// vitest.stop Types - Stop a vitest watch process
+// =============================================================================
+
+export const VitestStopInputSchema: z.ZodObject<{
+  id: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  /** The id that vitest.watch gave. Without it, every vitest watch process stops. */
+  id: z.string().optional().describe("The id that vitest.watch gave. Without it, every vitest watch process stops."),
+});
+
+export type VitestStopInput = z.infer<typeof VitestStopInputSchema>;
+
+export interface VitestStopOutput {
+  /** False when an id was given and no running watch process has it */
+  success: boolean;
+  /** The ids of the processes that stopped */
+  stopped: string[];
+}
+
+// =============================================================================
+// vitest.list Types - List the vitest watch processes
+// =============================================================================
+
+export const VitestListInputSchema: z.ZodObject<{
+  output: z.ZodOptional<z.ZodBoolean>;
+}> = z.object({
+  /** Also give the end of the output of each process (the last 64 KiB) */
+  output: z.boolean().optional().describe("Also give the end of the output of each process (the last 64 KiB)"),
+});
+
+export type VitestListInput = z.infer<typeof VitestListInputSchema>;
+
+export interface VitestProcessInfo {
+  id: string;
+  pid: number;
+  cwd?: string | undefined;
+  status: "running" | "exited" | "error";
+  startedAt: string;
+  exitedAt?: string | undefined;
+  exitCode?: number | undefined;
+  /** With `output: true`, the end of the output */
+  output?: string | undefined;
+}
+
+export interface VitestListOutput {
+  processes: VitestProcessInfo[];
+}
+
+export const VitestStopOutputSchema: z.ZodType<VitestStopOutput> = z.looseObject({
+  success: z.boolean().describe("False when an id was given and no running watch process has it"),
+  stopped: z.array(z.string()).describe("The ids of the processes that stopped"),
+});
+
+export const VitestListOutputSchema: z.ZodType<VitestListOutput> = z.looseObject({
+  processes: z
+    .array(
+      z.looseObject({
+        id: z.string().describe("The id that vitest.stop takes"),
+        pid: z.number().describe("The process id"),
+        cwd: z.string().optional().describe("The folder of the project"),
+        status: z.enum(["running", "exited", "error"]).describe("The state of the process"),
+        startedAt: z.string().describe("The start time (ISO 8601)"),
+        exitedAt: z.string().optional().describe("The end time (ISO 8601), when the process ended"),
+        exitCode: z.number().optional().describe("The exit code, when the process ended"),
+        output: z.string().optional().describe("With output: true, the last 64 KiB of the output"),
+      })
+    )
+    .describe("The vitest watch processes of this host"),
+});

package/src/vitest-cli.ts

@@ -0,0 +1,28 @@
+/**
+ * Locate the vitest CLI of a project.
+ *
+ * The procedures run vitest as `node <vitest.mjs> ...args` with no shell:
+ * - no shell means test patterns cannot inject commands;
+ * - running the project's own vitest (instead of `npx vitest`) never downloads a package,
+ *   and avoids the .cmd shim that Node cannot spawn without a shell on Windows.
+ */
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+
+export function resolveVitestCli(cwd: string): string {
+  const require = createRequire(join(resolve(cwd), "package.json"));
+  let packageJsonPath: string;
+  try {
+    packageJsonPath = require.resolve("vitest/package.json");
+  } catch {
+    throw new Error(`vitest is not installed for ${cwd}. Add it as a devDependency.`);
+  }
+  const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { bin?: string | Record<string, string> };
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.["vitest"];
+  if (!bin) {
+    throw new Error(`The vitest package at ${dirname(packageJsonPath)} has no "vitest" bin.`);
+  }
+  return join(dirname(packageJsonPath), bin);
+}