@procedures/vite 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,80 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/vite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Vite as procedures: dev server, build, preview and stop, with no shell and managed processes.",
+  "keywords": [
+    "vite",
+    "build",
+    "dev-server",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-vite"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0",
+    "@procedures/shell": "0.2.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3",
+    "vite": "^6.4.4"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * client-vite - Vite dev server management procedures
+ */
+
+export * from "./module.js";
+
+export * from "./types.js";
+export * from "./procedures/vite/index.js";
+export { serverManager } from "./server-manager.js";

package/src/module.ts

@@ -0,0 +1,109 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for Vite dev server management
+ */
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import { viteDev } from "./procedures/vite/dev.js";
+import { viteBuild } from "./procedures/vite/build.js";
+import { vitePreview } from "./procedures/vite/preview.js";
+import { viteStop } from "./procedures/vite/stop.js";
+import {
+  ViteDevInputSchema,
+  ViteBuildInputSchema,
+  VitePreviewInputSchema,
+  ViteStopInputSchema,
+  type ViteDevInput,
+  type ViteDevOutput,
+  type ViteBuildInput,
+  type ViteBuildOutput,
+  type VitePreviewInput,
+  type VitePreviewOutput,
+  type ViteStopInput,
+  type ViteStopOutput,
+  ViteDevOutputSchema,
+  ViteBuildOutputSchema,
+  VitePreviewOutputSchema,
+  ViteStopOutputSchema,
+} from "./types.js";
+
+const viteDevProcedure = createProcedure()
+  .path(["vite", "dev"])
+  .input(zodAdapter<ViteDevInput>(ViteDevInputSchema))
+  .output(zodAdapter<ViteDevOutput>(ViteDevOutputSchema))
+  .meta({
+    description: "Start Vite dev server",
+    // vite runs the config and the plugins of the project, and the server listens on a port
+    effects: { reads: ["fs"], writes: ["network", "process", "server"] },
+    args: ["cwd"],
+    shorts: { port: "p", host: "h" },
+    output: "json",
+  })
+  .handler(async (input: ViteDevInput): Promise<ViteDevOutput> => viteDev(input))
+  .build();
+
+const viteBuildProcedure = createProcedure()
+  .path(["vite", "build"])
+  .input(zodAdapter<ViteBuildInput>(ViteBuildInputSchema))
+  .output(zodAdapter<ViteBuildOutput>(ViteBuildOutputSchema))
+  .meta({
+    description: "Build for production",
+    // vite runs the config and the plugins of the project, and writes the output folder
+    effects: { reads: ["fs"], writes: ["fs", "process"] },
+    args: ["cwd"],
+    shorts: { outDir: "o", mode: "m" },
+    output: "json",
+  })
+  .handler(async (input: ViteBuildInput, ctx): Promise<ViteBuildOutput> => viteBuild(input, ctx))
+  .build();
+
+const vitePreviewProcedure = createProcedure()
+  .path(["vite", "preview"])
+  .input(zodAdapter<VitePreviewInput>(VitePreviewInputSchema))
+  .output(zodAdapter<VitePreviewOutput>(VitePreviewOutputSchema))
+  .meta({
+    description: "Preview production build",
+    effects: { reads: ["fs"], writes: ["network", "process", "server"] },
+    args: ["cwd"],
+    shorts: { port: "p" },
+    output: "json",
+  })
+  .handler(async (input: VitePreviewInput): Promise<VitePreviewOutput> => vitePreview(input))
+  .build();
+
+const viteStopProcedure = createProcedure()
+  .path(["vite", "stop"])
+  .input(zodAdapter<ViteStopInput>(ViteStopInputSchema))
+  .output(zodAdapter<ViteStopOutput>(ViteStopOutputSchema))
+  .meta({
+    description: "Stop a running Vite server",
+    effects: { reads: ["server"], writes: ["server"], idempotent: true },
+    args: ["serverId"],
+    shorts: {},
+    output: "json",
+  })
+  .handler(async (input: ViteStopInput): Promise<ViteStopOutput> => viteStop(input))
+  .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 viteModule: ProcedureModule = defineModule("@procedures/vite", [
+    viteDevProcedure,
+    viteBuildProcedure,
+    vitePreviewProcedure,
+    viteStopProcedure,
+  ]);
+
+export default viteModule;
+
+/**
+ * This function registers the procedures of @procedures/vite, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerViteProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [viteModule]);
+}

package/src/procedures/vite/build.ts

@@ -0,0 +1,44 @@
+/**
+ * vite.build procedure - Build for production
+ */
+
+import { resolve } from "node:path";
+import { runCommand } from "@procedures/shell/command";
+import { resolveViteCli, viteArg } from "../../vite-cli.js";
+import type { ViteBuildInput, ViteBuildOutput } from "../../types.js";
+
+export async function viteBuild(
+  input: ViteBuildInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): Promise<ViteBuildOutput> {
+  const { outDir, mode } = input;
+  // Without cwd, the build runs in the current folder. (Before, `resolve(undefined, ...)` threw.)
+  const cwd = input.cwd ?? process.cwd();
+
+  // The project's own vite, run with Node and an argument list: no shell (deep dive WRP-8)
+  const args = [resolveViteCli(cwd), "build"];
+  if (outDir) args.push("--outDir", viteArg("outDir", outDir));
+  if (mode) args.push("--mode", viteArg("mode", mode));
+
+  // The signal kills vite and the processes that it started (roadmap 2.2)
+  const result = await runCommand(process.execPath, {
+    args,
+    cwd,
+    env: { NO_COLOR: "1" },
+    signal: ctx?.signal,
+    keep: "tail",
+    maxOutputBytes: 1024 * 1024,
+  });
+  if (result.aborted) {
+    const error = new Error("vite.build was aborted");
+    error.name = "AbortError";
+    throw error;
+  }
+  if (!result.success) {
+    throw new Error(`Build failed with code ${result.exitCode}: ${result.error ?? result.stderr}`);
+  }
+  return {
+    success: true,
+    outDir: resolve(cwd, outDir ?? "dist"),
+  };
+}

package/src/procedures/vite/dev.ts

@@ -0,0 +1,19 @@
+/**
+ * vite.dev procedure - Start Vite dev server
+ */
+
+import { viteArg } from "../../vite-cli.js";
+import type { ViteDevInput, ViteDevOutput } from "../../types.js";
+import { serverManager } from "../../server-manager.js";
+
+export async function viteDev(input: ViteDevInput): Promise<ViteDevOutput> {
+  const { cwd, port, host, open } = input;
+
+  // The project's own vite, run with Node and an argument list: no shell (deep dive WRP-8)
+  const args: string[] = [];
+  if (port) args.push("--port", String(port));
+  if (host) args.push("--host", viteArg("host", host));
+  if (open) args.push("--open");
+
+  return serverManager.start(args, cwd);
+}

package/src/procedures/vite/index.ts

@@ -0,0 +1,4 @@
+export { viteDev } from "./dev.js";
+export { viteBuild } from "./build.js";
+export { vitePreview } from "./preview.js";
+export { viteStop } from "./stop.js";

package/src/procedures/vite/preview.ts

@@ -0,0 +1,16 @@
+/**
+ * vite.preview procedure - Preview production build
+ */
+
+import type { VitePreviewInput, VitePreviewOutput } from "../../types.js";
+import { serverManager } from "../../server-manager.js";
+
+export async function vitePreview(input: VitePreviewInput): Promise<VitePreviewOutput> {
+  const { cwd, port } = input;
+
+  // The project's own vite, run with Node and an argument list: no shell (deep dive WRP-8)
+  const args = ["preview"];
+  if (port) args.push("--port", String(port));
+
+  return serverManager.start(args, cwd);
+}

package/src/procedures/vite/stop.ts

@@ -0,0 +1,12 @@
+/**
+ * vite.stop procedure - Stop a running server
+ */
+
+import type { ViteStopInput, ViteStopOutput } from "../../types.js";
+import { serverManager } from "../../server-manager.js";
+
+export async function viteStop(input: ViteStopInput): Promise<ViteStopOutput> {
+  const { serverId } = input;
+  const success = await serverManager.stop(serverId);
+  return { success };
+}

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/vite, and of the modules that it
+ * requires, in the global registry: `import "@procedures/vite/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerViteProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerViteProcedures();

package/src/server-manager.ts

@@ -0,0 +1,61 @@
+/**
+ * Vite Server Manager - Manages running Vite servers
+ *
+ * The manager is a view of the process registry of client-shell, for the group "vite"
+ * (deep dive WRP-4, WRP-10): `stop` ends the whole process tree (vite and esbuild), the registry
+ * reads the output of each server, and the servers end when the host ends.
+ */
+
+import { processes } from "@procedures/shell/command";
+import { resolveViteCli } from "./vite-cli.js";
+
+/** The group of the vite servers in the process registry. */
+export const VITE_GROUP = "vite";
+
+/** The line where vite prints the URL of a server that is ready. */
+const READY = /Local:\s+(https?:\/\/\S+)/;
+
+export interface StartedServer {
+  serverId: string;
+  url: string;
+  pid: number;
+}
+
+class ServerManager {
+  /**
+   * Start `vite <args>` with the project's own vite and no shell, and wait for its URL.
+   * When the server does not get ready, the manager stops it and throws.
+   */
+  async start(args: string[], cwd: string | undefined, timeout = 30000): Promise<StartedServer> {
+    const root = cwd ?? process.cwd();
+    const started = processes.start(process.execPath, {
+      args: [resolveViteCli(root), ...args],
+      cwd: root,
+      // No colors: the output stays plain text for the readers of the registry
+      env: { NO_COLOR: "1" },
+      group: VITE_GROUP,
+      label: `vite ${args.join(" ")}`.trim(),
+    });
+    try {
+      const match = await processes.waitFor(started.id, READY, timeout);
+      return { serverId: started.id, url: match[1]!, pid: started.pid };
+    } catch (error) {
+      await processes.stop(started.id);
+      throw error;
+    }
+  }
+
+  /** True when the server has a record and is running. */
+  running(serverId: string): boolean {
+    const info = processes.get(serverId);
+    return info?.group === VITE_GROUP && info.status === "running";
+  }
+
+  /** Stop a server and the processes that it started, and wait for its end. */
+  async stop(serverId: string): Promise<boolean> {
+    if (!this.running(serverId)) return false;
+    return (await processes.stop(serverId)).stopped;
+  }
+}
+
+export const serverManager: ServerManager = new ServerManager();

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Type definitions for client-vite procedures
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// vite.dev - Start Vite dev server
+// ============================================================================
+
+export const ViteDevInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+  port: z.ZodOptional<z.ZodNumber>;
+  host: z.ZodOptional<z.ZodString>;
+  open: z.ZodOptional<z.ZodBoolean>;
+}> = z.object({
+  /** Working directory containing vite config (default: the current folder) */
+  cwd: z.string().optional().describe("Working directory containing vite config (default: the current folder)"),
+  /** Port to run on */
+  port: z.number().optional().describe("Port to run on"),
+  /** Host to bind to */
+  host: z.string().optional().describe("Host to bind to"),
+  /** Open browser automatically */
+  open: z.boolean().optional().describe("Open browser automatically"),
+});
+
+export type ViteDevInput = z.infer<typeof ViteDevInputSchema>;
+
+export interface ViteDevOutput {
+  /** Server identifier for management */
+  serverId: string;
+  /** Server URL */
+  url: string;
+  /** Process ID */
+  pid: number;
+}
+
+// ============================================================================
+// vite.build - Build for production
+// ============================================================================
+
+export const ViteBuildInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+  outDir: z.ZodOptional<z.ZodString>;
+  mode: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  /** Working directory containing vite config (default: the current folder) */
+  cwd: z.string().optional().describe("Working directory containing vite config (default: the current folder)"),
+  /** Output directory */
+  outDir: z.string().optional().describe("Output directory"),
+  /** Build mode */
+  mode: z.string().optional().describe("Build mode"),
+});
+
+export type ViteBuildInput = z.infer<typeof ViteBuildInputSchema>;
+
+export interface ViteBuildOutput {
+  /** Whether build succeeded */
+  success: boolean;
+  /** Output directory path */
+  outDir: string;
+}
+
+// ============================================================================
+// vite.preview - Preview production build
+// ============================================================================
+
+export const VitePreviewInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+  port: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Working directory containing built output (default: the current folder) */
+  cwd: z.string().optional().describe("Working directory containing built output (default: the current folder)"),
+  /** Port to run on */
+  port: z.number().optional().describe("Port to run on"),
+});
+
+export type VitePreviewInput = z.infer<typeof VitePreviewInputSchema>;
+
+export interface VitePreviewOutput {
+  /** Server identifier */
+  serverId: string;
+  /** Server URL */
+  url: string;
+  /** Process ID */
+  pid: number;
+}
+
+// ============================================================================
+// vite.stop - Stop a running server
+// ============================================================================
+
+export const ViteStopInputSchema: z.ZodObject<{
+  serverId: z.ZodString;
+}> = z.object({
+  /** Server ID to stop */
+  serverId: z.string().describe("Server ID to stop"),
+});
+
+export type ViteStopInput = z.infer<typeof ViteStopInputSchema>;
+
+export interface ViteStopOutput {
+  /** Whether stop succeeded */
+  success: boolean;
+}
+
+// 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).
+
+const serverFields = {
+  serverId: z.string().describe("The id of the server: vite.stop takes it"),
+  url: z.string().describe("The URL of the server"),
+  pid: z.number().describe("The process id of vite"),
+};
+
+export const ViteDevOutputSchema: z.ZodType<ViteDevOutput> = z.looseObject(serverFields);
+
+export const VitePreviewOutputSchema: z.ZodType<VitePreviewOutput> = z.looseObject(serverFields);
+
+export const ViteBuildOutputSchema: z.ZodType<ViteBuildOutput> = z.looseObject({
+  success: z.boolean().describe("True when the build succeeded"),
+  outDir: z.string().describe("The output folder of the build"),
+});
+
+export const ViteStopOutputSchema: z.ZodType<ViteStopOutput> = z.looseObject({
+  success: z.boolean().describe("True when the server stopped"),
+});

package/src/vite-cli.ts

@@ -0,0 +1,35 @@
+/**
+ * Locate the vite CLI of a project.
+ *
+ * The procedures run vite as `node <vite.js> ...args` with no shell. Before, they ran
+ * `npx vite` with `shell: true`: `host`, `mode` and `outDir` reached the shell unescaped
+ * (deep dive WRP-8), and npx could download vite when the project did not have it.
+ */
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+
+export function resolveViteCli(cwd: string): string {
+  const require = createRequire(join(resolve(cwd), "package.json"));
+  let packageJsonPath: string;
+  try {
+    packageJsonPath = require.resolve("vite/package.json");
+  } catch {
+    throw new Error(`vite 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?.["vite"];
+  if (!bin) {
+    throw new Error(`The vite package at ${dirname(packageJsonPath)} has no "vite" bin.`);
+  }
+  return join(dirname(packageJsonPath), bin);
+}
+
+/** A value that vite reads as an argument (a mode, a folder, a host): it must not start with "-". */
+export function viteArg(name: string, value: string): string {
+  if (value.startsWith("-")) {
+    throw new Error(`Invalid ${name} (starts with "-"): ${value}`);
+  }
+  return value;
+}