@procedures/pnpm 0.0.0-stage → 0.2.0

package/src/procedures/pnpm/run.ts

@@ -0,0 +1,41 @@
+/**
+ * pnpm.run procedure
+ *
+ * Run package scripts using pnpm.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { pnpmArg, runPnpm } from "./shared.js";
+import type { PnpmRunInput, PnpmCommandOutput } from "../../types.js";
+
+/**
+ * Run a package script using pnpm
+ *
+ * @example
+ * // Run build script
+ * await client.call(["pnpm", "run"], {
+ *   script: "build",
+ * });
+ *
+ * @example
+ * // Run test with arguments
+ * await client.call(["pnpm", "run"], {
+ *   script: "test",
+ *   args: ["--watch"],
+ * });
+ */
+export async function pnpmRun(
+  input: PnpmRunInput,
+  ctx: ProcedureContext
+): Promise<PnpmCommandOutput> {
+  {
+    const args: string[] = ["run", pnpmArg("script", input.script)];
+
+    // Add additional arguments
+    if (input.args && input.args.length > 0) {
+      args.push("--", ...input.args);
+    }
+
+    return runPnpm(args, input, ctx);
+  }
+}

package/src/procedures/pnpm/shared.ts

@@ -0,0 +1,85 @@
+/**
+ * The way every pnpm procedure runs pnpm: an argument list through `shell.run`, no shell.
+ *
+ * Before, each procedure joined its arguments into one string for `shell.exec`, which runs a
+ * shell, so a package name such as `x & calc` ran a second command (deep dive WRP-5).
+ *
+ * On Windows, `pnpm` is often a `.cmd` file, and Node runs a `.cmd` file only through a shell.
+ * So the helper finds the real program: a `pnpm.exe` (the standalone pnpm), or the `pnpm.cjs`
+ * script that the `.cmd` file starts, run with Node.
+ */
+
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import type { PnpmCommandOutput } from "../../types.js";
+
+/** A value that pnpm reads as an argument (a package, a script, a path): it must not start with "-". */
+export function pnpmArg(name: string, value: string): string {
+  if (value.startsWith("-")) {
+    throw new Error(`Invalid ${name} (starts with "-"): ${value}`);
+  }
+  return value;
+}
+
+/** The program and the first arguments that start pnpm without a shell. */
+export function resolvePnpm(): { command: string; prefix: string[] } {
+  // When pnpm runs this process, npm_execpath is its script
+  const execPath = process.env["npm_execpath"];
+  if (execPath && /pnpm\.c?js$/.test(execPath) && existsSync(execPath)) {
+    return { command: process.execPath, prefix: [execPath] };
+  }
+  if (process.platform !== "win32") {
+    return { command: "pnpm", prefix: [] };
+  }
+  for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
+    if (!dir) continue;
+    if (existsSync(join(dir, "pnpm.exe"))) {
+      return { command: join(dir, "pnpm.exe"), prefix: [] };
+    }
+    const script = join(dir, "node_modules", "pnpm", "bin", "pnpm.cjs");
+    if (existsSync(script)) {
+      return { command: process.execPath, prefix: [script] };
+    }
+  }
+  throw new Error("pnpm was not found: install pnpm, or run this from a pnpm script");
+}
+
+/** This function runs `pnpm <args>` and gives its result. It does not throw for a failed command. */
+export async function runPnpm(
+  args: string[],
+  input: { cwd?: string | undefined; timeout?: number | undefined },
+  ctx: ProcedureContext
+): Promise<PnpmCommandOutput> {
+  const startTime = Date.now();
+  try {
+    const pnpm = resolvePnpm();
+    const shellInput: { command: string; args: string[]; cwd?: string; timeout?: number } = {
+      command: pnpm.command,
+      args: [...pnpm.prefix, ...args],
+    };
+    if (input.cwd !== undefined) shellInput.cwd = input.cwd;
+    if (input.timeout !== undefined) shellInput.timeout = input.timeout;
+
+    const result = await ctx.client.call<
+      typeof shellInput,
+      { exitCode: number; stdout: string; stderr: string }
+    >(["shell", "run"], shellInput);
+
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      success: result.exitCode === 0,
+      duration: Date.now() - startTime,
+    };
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      success: false,
+      duration: Date.now() - startTime,
+    };
+  }
+}

package/src/procedures/pnpm/store.ts

@@ -0,0 +1,97 @@
+/**
+ * pnpm.store.path procedure
+ *
+ * Get the pnpm store path for snapshot/restore operations.
+ * Cross-platform support for Windows, macOS, and Linux.
+ */
+
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import type { PnpmStorePathInput, PnpmStorePathOutput } from "../../types.js";
+
+/**
+ * Get pnpm store path
+ *
+ * Uses `pnpm store path` command to get the actual store location.
+ * Falls back to platform-specific defaults if command fails.
+ *
+ * Store locations by platform:
+ * - Windows: %LocalAppData%\pnpm\store or %AppData%\pnpm\store
+ * - macOS/Linux: ~/.local/share/pnpm/store or ~/.pnpm-store
+ *
+ * @example
+ * const result = await client.call(["pnpm", "store", "path"], {});
+ * console.log(result.path); // "C:\Users\user\AppData\Local\pnpm\store\v3"
+ */
+export async function pnpmStorePath(input: PnpmStorePathInput): Promise<PnpmStorePathOutput> {
+  const platform = process.platform;
+  let storePath = "";
+
+  try {
+    // Try to get store path from pnpm directly
+    const opts: { cwd?: string; encoding: "utf8" } = { encoding: "utf8" };
+    if (input.cwd) {
+      opts.cwd = input.cwd;
+    }
+
+    storePath = execSync("pnpm store path", opts).trim();
+  } catch {
+    // Fallback to platform-specific defaults
+    storePath = getDefaultStorePath(platform);
+  }
+
+  return {
+    path: storePath,
+    exists: existsSync(storePath),
+    platform,
+  };
+}
+
+/**
+ * Get default pnpm store path based on platform
+ */
+function getDefaultStorePath(platform: string): string {
+  if (platform === "win32") {
+    // Windows: Check LocalAppData first, then AppData
+    const localAppData = process.env["LOCALAPPDATA"];
+    const appData = process.env["APPDATA"];
+
+    if (localAppData) {
+      const localPath = `${localAppData}\\pnpm\\store\\v3`;
+      if (existsSync(localPath)) {
+        return localPath;
+      }
+    }
+
+    if (appData) {
+      const appDataPath = `${appData}\\pnpm\\store\\v3`;
+      if (existsSync(appDataPath)) {
+        return appDataPath;
+      }
+    }
+
+    // Return default LocalAppData path even if it doesn't exist
+    return localAppData
+      ? `${localAppData}\\pnpm\\store\\v3`
+      : `${process.env["USERPROFILE"]}\\AppData\\Local\\pnpm\\store\\v3`;
+  }
+
+  // macOS/Linux
+  const home = process.env["HOME"] || "";
+
+  // Check XDG data home first
+  const xdgDataHome = process.env["XDG_DATA_HOME"] || `${home}/.local/share`;
+  const xdgPath = `${xdgDataHome}/pnpm/store/v3`;
+  if (existsSync(xdgPath)) {
+    return xdgPath;
+  }
+
+  // Check legacy ~/.pnpm-store
+  const legacyPath = `${home}/.pnpm-store/v3`;
+  if (existsSync(legacyPath)) {
+    return legacyPath;
+  }
+
+  // Return XDG path as default
+  return xdgPath;
+}

package/src/register.ts

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

package/src/types.ts

@@ -0,0 +1,180 @@
+/**
+ * Type definitions for client-pnpm procedures
+ *
+ * client-pnpm wraps pnpm commands as procedures using client-shell.
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// Shared Output Type
+// =============================================================================
+
+export interface PnpmCommandOutput {
+  /** Exit code of the command */
+  exitCode: number;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+  /** Whether command succeeded (exit code 0) */
+  success: boolean;
+  /** Duration in milliseconds */
+  duration: number;
+}
+
+// =============================================================================
+// pnpm.install Types
+// =============================================================================
+
+export const PnpmInstallInputSchema: z.ZodObject<{
+  packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  dev: z.ZodOptional<z.ZodBoolean>;
+  frozen: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Packages to install. If not provided, installs from package.json */
+  packages: z.array(z.string()).optional().describe("Packages to install. If not provided, installs from package.json"),
+  /** Save as dev dependency */
+  dev: z.boolean().optional().describe("Save as dev dependency"),
+  /** Use frozen lockfile (--frozen-lockfile) */
+  frozen: z.boolean().optional().describe("Use frozen lockfile (--frozen-lockfile)"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type PnpmInstallInput = z.infer<typeof PnpmInstallInputSchema>;
+
+// =============================================================================
+// pnpm.add Types
+// =============================================================================
+
+export const PnpmAddInputSchema: z.ZodObject<{
+  packages: z.ZodArray<z.ZodString>;
+  dev: z.ZodOptional<z.ZodBoolean>;
+  global: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Packages to add */
+  packages: z.array(z.string()).describe("Packages to add"),
+  /** Save as dev dependency */
+  dev: z.boolean().optional().describe("Save as dev dependency"),
+  /** Install globally */
+  global: z.boolean().optional().describe("Install globally"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type PnpmAddInput = z.infer<typeof PnpmAddInputSchema>;
+
+// =============================================================================
+// pnpm.remove Types
+// =============================================================================
+
+export const PnpmRemoveInputSchema: z.ZodObject<{
+  packages: z.ZodArray<z.ZodString>;
+  global: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Packages to remove */
+  packages: z.array(z.string()).describe("Packages to remove"),
+  /** Remove from global */
+  global: z.boolean().optional().describe("Remove from global"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type PnpmRemoveInput = z.infer<typeof PnpmRemoveInputSchema>;
+
+// =============================================================================
+// pnpm.link Types
+// =============================================================================
+
+export const PnpmLinkInputSchema: z.ZodObject<{
+  path: z.ZodOptional<z.ZodString>;
+  global: z.ZodOptional<z.ZodBoolean>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Path to package to link. If not provided, links current directory globally */
+  path: z.string().optional().describe("Path to package to link. If not provided, links current directory globally"),
+  /** Link globally */
+  global: z.boolean().optional().describe("Link globally"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type PnpmLinkInput = z.infer<typeof PnpmLinkInputSchema>;
+
+// =============================================================================
+// pnpm.run Types
+// =============================================================================
+
+export const PnpmRunInputSchema: z.ZodObject<{
+  script: z.ZodString;
+  args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Script name to run */
+  script: z.string().describe("Script name to run"),
+  /** Additional arguments to pass to the script */
+  args: z.array(z.string()).optional().describe("Additional arguments to pass to the script"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+});
+
+export type PnpmRunInput = z.infer<typeof PnpmRunInputSchema>;
+
+// =============================================================================
+// pnpm.store.path Types - Get pnpm store path for snapshot/restore
+// =============================================================================
+
+export const PnpmStorePathInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  /** Working directory (affects store path on some configurations) */
+  cwd: z.string().optional().describe("Working directory (affects store path on some configurations)"),
+});
+
+export type PnpmStorePathInput = z.infer<typeof PnpmStorePathInputSchema>;
+
+export interface PnpmStorePathOutput {
+  /** Absolute path to the pnpm store */
+  path: string;
+  /** Whether store exists */
+  exists: boolean;
+  /** Platform (win32, darwin, linux) */
+  platform: string;
+}
+
+// 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).
+
+/** The result of a pnpm command: add, install, remove, link and run give it. */
+export const PnpmCommandOutputSchema: z.ZodType<PnpmCommandOutput> = z.looseObject({
+  exitCode: z.number().describe("The exit code of pnpm (0 is success)"),
+  stdout: z.string().describe("The standard output of pnpm"),
+  stderr: z.string().describe("The standard error of pnpm"),
+  success: z.boolean().describe("True when the exit code is 0"),
+  duration: z.number().describe("The time of the command, in milliseconds"),
+});
+
+export const PnpmStorePathOutputSchema: z.ZodType<PnpmStorePathOutput> = z.looseObject({
+  path: z.string().describe("The absolute path of the pnpm store"),
+  exists: z.boolean().describe("True when the store folder exists"),
+  platform: z.string().describe("The platform (win32, darwin, linux)"),
+});