@procedures/pnpm 0.2.3 → 0.3.0

package/src/module.ts

@@ -29,6 +29,38 @@ import {
   PnpmStorePathOutputSchema,
 } from "./types.js";
 import type { ProcedureContext } from "@procedures/client";
+import { pnpmExec } from "./procedures/pnpm/exec.js";
+import { pnpmList } from "./procedures/pnpm/list.js";
+import { pnpmWhy } from "./procedures/pnpm/why.js";
+import { pnpmOutdated } from "./procedures/pnpm/outdated.js";
+import { pnpmUpdate } from "./procedures/pnpm/update.js";
+import { pnpmPack } from "./procedures/pnpm/pack.js";
+import {
+  PnpmExecInputSchema,
+  PnpmExecOutputSchema,
+  type PnpmExecInput,
+  type PnpmExecOutput,
+  PnpmListInputSchema,
+  PnpmListOutputSchema,
+  type PnpmListInput,
+  type PnpmListOutput,
+  PnpmWhyInputSchema,
+  PnpmWhyOutputSchema,
+  type PnpmWhyInput,
+  type PnpmWhyOutput,
+  PnpmOutdatedInputSchema,
+  PnpmOutdatedOutputSchema,
+  type PnpmOutdatedInput,
+  type PnpmOutdatedOutput,
+  PnpmUpdateInputSchema,
+  PnpmUpdateOutputSchema,
+  type PnpmUpdateInput,
+  type PnpmUpdateOutput,
+  PnpmPackInputSchema,
+  PnpmPackOutputSchema,
+  type PnpmPackInput,
+  type PnpmPackOutput,
+} from "./types.js";
 
 // =============================================================================
 // Procedures
@@ -40,6 +72,7 @@ const pnpmInstallProcedure = createProcedure()
   .output(zodAdapter<PnpmCommandOutput>(PnpmCommandOutputSchema))
   .meta({
     description: "Install packages using pnpm",
+    calls: ["shell.run"],
     // pnpm reads the npm registry, rewrites node_modules and the lockfile, and runs the
     // lifecycle scripts and the pnpmfile of the project
     effects: { reads: ["fs", "network"], writes: ["fs", "process"] },
@@ -57,6 +90,7 @@ const pnpmAddProcedure = createProcedure()
   .output(zodAdapter<PnpmCommandOutput>(PnpmCommandOutputSchema))
   .meta({
     description: "Add packages using pnpm",
+    calls: ["shell.run"],
     effects: { reads: ["fs", "network"], writes: ["fs", "process"] },
     args: ["packages"],
     shorts: { cwd: "C", dev: "D", global: "g" },
@@ -73,6 +107,7 @@ const pnpmRemoveProcedure = createProcedure()
   .output(zodAdapter<PnpmCommandOutput>(PnpmCommandOutputSchema))
   .meta({
     description: "Remove packages using pnpm",
+    calls: ["shell.run"],
     // pnpm resolves the remaining dependencies again, so it can read the npm registry
     effects: { reads: ["fs", "network"], writes: ["fs", "process"] },
     args: ["packages"],
@@ -90,6 +125,7 @@ const pnpmLinkProcedure = createProcedure()
   .output(zodAdapter<PnpmCommandOutput>(PnpmCommandOutputSchema))
   .meta({
     description: "Link packages using pnpm",
+    calls: ["shell.run"],
     effects: { reads: ["fs", "network"], writes: ["fs", "process"] },
     shorts: { cwd: "C", global: "g" },
     output: "json",
@@ -105,6 +141,7 @@ const pnpmRunProcedure = createProcedure()
   .output(zodAdapter<PnpmCommandOutput>(PnpmCommandOutputSchema))
   .meta({
     description: "Run package scripts using pnpm",
+    calls: ["shell.run"],
     // A package script is code of the project: it can do anything
     effects: { reads: ["fs"], writes: ["process"] },
     args: ["script"],
@@ -133,6 +170,106 @@ const pnpmStorePathProcedure = createProcedure()
   })
   .build();
 
+// =============================================================================
+// Roadmap R41: exec, list, why, outdated, update, pack
+// =============================================================================
+
+const pnpmExecProcedure = createProcedure()
+  .path(["pnpm", "exec"])
+  .input(zodAdapter<PnpmExecInput>(PnpmExecInputSchema))
+  .output(zodAdapter<PnpmExecOutput>(PnpmExecOutputSchema))
+  .meta({
+    description: "Run a program of the dependencies (node_modules/.bin) with pnpm exec",
+    calls: ["shell.run"],
+    // The program is any program of the dependencies: it can do anything, as pnpm.run
+    effects: { reads: ["fs"], writes: ["process"] },
+    args: ["command", "args"],
+    shorts: { cwd: "C", recursive: "r" },
+    output: "json",
+  })
+  .handler(async (input: PnpmExecInput, ctx: ProcedureContext): Promise<PnpmExecOutput> => pnpmExec(input, ctx))
+  .build();
+
+const pnpmListProcedure = createProcedure()
+  .path(["pnpm", "list"])
+  .input(zodAdapter<PnpmListInput>(PnpmListInputSchema))
+  .output(zodAdapter<PnpmListOutput>(PnpmListOutputSchema))
+  .meta({
+    description: "List the installed packages: data is the JSON of pnpm list --json",
+    calls: ["shell.run"],
+    // It reads package.json, the lockfile and node_modules
+    effects: { reads: ["fs"], writes: [] },
+    args: ["packages"],
+    shorts: { cwd: "C", depth: "d", recursive: "r" },
+    output: "json",
+  })
+  .handler(async (input: PnpmListInput, ctx: ProcedureContext): Promise<PnpmListOutput> => pnpmList(input, ctx))
+  .build();
+
+const pnpmWhyProcedure = createProcedure()
+  .path(["pnpm", "why"])
+  .input(zodAdapter<PnpmWhyInput>(PnpmWhyInputSchema))
+  .output(zodAdapter<PnpmWhyOutput>(PnpmWhyOutputSchema))
+  .meta({
+    description: "Show the packages that depend on a package: data is the JSON of pnpm why --json",
+    calls: ["shell.run"],
+    effects: { reads: ["fs"], writes: [] },
+    args: ["packages"],
+    shorts: { cwd: "C", depth: "d", recursive: "r" },
+    output: "json",
+  })
+  .handler(async (input: PnpmWhyInput, ctx: ProcedureContext): Promise<PnpmWhyOutput> => pnpmWhy(input, ctx))
+  .build();
+
+const pnpmOutdatedProcedure = createProcedure()
+  .path(["pnpm", "outdated"])
+  .input(zodAdapter<PnpmOutdatedInput>(PnpmOutdatedInputSchema))
+  .output(zodAdapter<PnpmOutdatedOutput>(PnpmOutdatedOutputSchema))
+  .meta({
+    description: "List the outdated packages: data is the JSON of pnpm outdated",
+    calls: ["shell.run"],
+    // pnpm reads the versions of the npm registry
+    effects: { reads: ["fs", "network"], writes: [] },
+    args: ["packages"],
+    shorts: { cwd: "C", recursive: "r" },
+    output: "json",
+  })
+  .handler(async (input: PnpmOutdatedInput, ctx: ProcedureContext): Promise<PnpmOutdatedOutput> => pnpmOutdated(input, ctx))
+  .build();
+
+const pnpmUpdateProcedure = createProcedure()
+  .path(["pnpm", "update"])
+  .input(zodAdapter<PnpmUpdateInput>(PnpmUpdateInputSchema))
+  .output(zodAdapter<PnpmUpdateOutput>(PnpmUpdateOutputSchema))
+  .meta({
+    description: "Update packages to their newest versions in the ranges, or with latest to the latest versions",
+    calls: ["shell.run"],
+    // As pnpm.install: the registry, node_modules, the lockfile and the lifecycle scripts
+    effects: { reads: ["fs", "network"], writes: ["fs", "process"] },
+    args: ["packages"],
+    shorts: { cwd: "C", latest: "L", recursive: "r" },
+    output: "json",
+  })
+  .handler(async (input: PnpmUpdateInput, ctx: ProcedureContext): Promise<PnpmUpdateOutput> => pnpmUpdate(input, ctx))
+  .build();
+
+const pnpmPackProcedure = createProcedure()
+  .path(["pnpm", "pack"])
+  .input(zodAdapter<PnpmPackInput>(PnpmPackInputSchema))
+  .output(zodAdapter<PnpmPackOutput>(PnpmPackOutputSchema))
+  .meta({
+    description: "Make a tarball of the package: data gives its file name and files",
+    calls: ["shell.run"],
+    // It writes the tarball (it replaces a tarball of the same name), and pnpm runs the prepack,
+    // prepare and postpack scripts of the package
+    effects: { reads: ["fs"], writes: ["fs", "process"] },
+    args: [],
+    shorts: { cwd: "C", destination: "d", dryRun: "n" },
+    output: "json",
+  })
+  .handler(async (input: PnpmPackInput, ctx: ProcedureContext): Promise<PnpmPackOutput> => pnpmPack(input, ctx))
+  .build();
+
 // =============================================================================
 // Registration
 // =============================================================================
@@ -148,6 +285,12 @@ export const pnpmModule: ProcedureModule = defineModule("@procedures/pnpm", [
     pnpmLinkProcedure,
     pnpmRunProcedure,
     pnpmStorePathProcedure,
+    pnpmExecProcedure,
+    pnpmListProcedure,
+    pnpmWhyProcedure,
+    pnpmOutdatedProcedure,
+    pnpmUpdateProcedure,
+    pnpmPackProcedure,
   ], [shellModule]);
 
 export default pnpmModule;

package/src/procedures/pnpm/add.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ProcedureContext } from "@procedures/client";
-import { pnpmArg, runPnpm } from "./shared.js";
+import { pnpmArg, runPnpm, selectionArgs } from "./shared.js";
 import type { PnpmAddInput, PnpmCommandOutput } from "../../types.js";
 
 /**
@@ -29,7 +29,7 @@ export async function pnpmAdd(
   ctx: ProcedureContext
 ): Promise<PnpmCommandOutput> {
   {
-    const args: string[] = ["add", ...input.packages.map((p) => pnpmArg("package", p))];
+    const args: string[] = [...selectionArgs(input), "add", ...input.packages.map((p) => pnpmArg("package", p))];
 
     // Add flags
     if (input.dev) args.push("--save-dev");

package/src/procedures/pnpm/exec.ts

@@ -0,0 +1,22 @@
+/**
+ * pnpm.exec procedure
+ *
+ * Run a program of the dependencies with `pnpm exec` (roadmap R41). pnpm finds the program in
+ * `node_modules/.bin`. No shell runs it: "--" ends the options of pnpm, and each argument goes
+ * to the program as it is.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { pnpmArg, runPnpm, selectionArgs } from "./shared.js";
+import type { PnpmExecInput, PnpmExecOutput } from "../../types.js";
+
+/**
+ * Run a program of the dependencies with pnpm exec
+ *
+ * @example
+ * await client.call(["pnpm", "exec"], { command: "tsc", args: ["--noEmit"], filter: ["@scope/app"] });
+ */
+export async function pnpmExec(input: PnpmExecInput, ctx: ProcedureContext): Promise<PnpmExecOutput> {
+  const args = [...selectionArgs(input), "exec", "--", pnpmArg("command", input.command), ...(input.args ?? [])];
+  return runPnpm(args, input, ctx);
+}

package/src/procedures/pnpm/index.ts

@@ -8,3 +8,9 @@ export { pnpmRemove } from "./remove.js";
 export { pnpmLink } from "./link.js";
 export { pnpmRun } from "./run.js";
 export { pnpmStorePath } from "./store.js";
+export { pnpmExec } from "./exec.js";
+export { pnpmList } from "./list.js";
+export { pnpmWhy } from "./why.js";
+export { pnpmOutdated } from "./outdated.js";
+export { pnpmUpdate } from "./update.js";
+export { pnpmPack } from "./pack.js";

package/src/procedures/pnpm/install.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ProcedureContext } from "@procedures/client";
-import { pnpmArg, runPnpm } from "./shared.js";
+import { pnpmArg, runPnpm, selectionArgs } from "./shared.js";
 import type { PnpmInstallInput, PnpmCommandOutput } from "../../types.js";
 
 /**
@@ -27,7 +27,7 @@ export async function pnpmInstall(
   ctx: ProcedureContext
 ): Promise<PnpmCommandOutput> {
   {
-    const args: string[] = ["install"];
+    const args: string[] = [...selectionArgs(input), "install"];
 
     // Add packages if specified
     if (input.packages && input.packages.length > 0) {

package/src/procedures/pnpm/list.ts

@@ -0,0 +1,31 @@
+/**
+ * pnpm.list procedure
+ *
+ * List the installed packages as JSON (roadmap R41). `data` is the parsed output of
+ * `pnpm list --json`: one entry for each project.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { pnpmArg, runPnpmJson, selectionArgs } from "./shared.js";
+import type { PnpmListInput, PnpmListOutput } from "../../types.js";
+
+/** The options of list and why: the depth and the kinds of dependencies. */
+export function treeOptions(input: { depth?: number | undefined; prod?: boolean | undefined; dev?: boolean | undefined }): string[] {
+  const args: string[] = [];
+  if (input.depth !== undefined) args.push("--depth", String(input.depth));
+  if (input.prod) args.push("--prod");
+  if (input.dev) args.push("--dev");
+  return args;
+}
+
+/**
+ * List the installed packages as JSON
+ *
+ * @example
+ * const { data } = await client.call(["pnpm", "list"], { depth: 0, recursive: true });
+ */
+export async function pnpmList(input: PnpmListInput, ctx: ProcedureContext): Promise<PnpmListOutput> {
+  const args = [...selectionArgs(input), "list", "--json", ...treeOptions(input)];
+  args.push(...(input.packages ?? []).map((name) => pnpmArg("package", name)));
+  return runPnpmJson(args, input, ctx);
+}

package/src/procedures/pnpm/outdated.ts

@@ -0,0 +1,29 @@
+/**
+ * pnpm.outdated procedure
+ *
+ * List the outdated packages as JSON (roadmap R41). pnpm reads the npm registry. `data` is the
+ * parsed output of `pnpm outdated --format json`.
+ *
+ * pnpm exits with 1 when a package is outdated. That is an answer, not a failure: when the output
+ * is JSON, the result has `success: true`.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { pnpmArg, runPnpmJson, selectionArgs } from "./shared.js";
+import type { PnpmOutdatedInput, PnpmOutdatedOutput } from "../../types.js";
+
+/**
+ * List the outdated packages as JSON
+ *
+ * @example
+ * const { data } = await client.call(["pnpm", "outdated"], { recursive: true });
+ */
+export async function pnpmOutdated(input: PnpmOutdatedInput, ctx: ProcedureContext): Promise<PnpmOutdatedOutput> {
+  const args = [...selectionArgs(input), "outdated", "--format", "json"];
+  if (input.prod) args.push("--prod");
+  if (input.dev) args.push("--dev");
+  args.push(...(input.packages ?? []).map((name) => pnpmArg("package", name)));
+  const result = await runPnpmJson(args, input, ctx);
+  if (result.exitCode === 1 && result.data !== undefined) result.success = true;
+  return result;
+}

package/src/procedures/pnpm/pack.ts

@@ -0,0 +1,25 @@
+/**
+ * pnpm.pack procedure
+ *
+ * Make a tarball of the package (roadmap R41). `data` is the parsed output of
+ * `pnpm pack --json`: the name, the version, the file name and the files of the tarball. With
+ * `dryRun`, pnpm writes no tarball.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { runPnpmJson } from "./shared.js";
+import type { PnpmPackInput, PnpmPackOutput } from "../../types.js";
+
+/**
+ * Make a tarball of the package
+ *
+ * @example
+ * const { data } = await client.call(["pnpm", "pack"], { cwd: "packages/app", dryRun: true });
+ */
+export async function pnpmPack(input: PnpmPackInput, ctx: ProcedureContext): Promise<PnpmPackOutput> {
+  const args = ["pack", "--json"];
+  if (input.dryRun) args.push("--dry-run");
+  // With "=", a folder that starts with "-" stays the value of the option
+  if (input.destination !== undefined) args.push(`--pack-destination=${input.destination}`);
+  return runPnpmJson(args, input, ctx);
+}

package/src/procedures/pnpm/remove.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ProcedureContext } from "@procedures/client";
-import { pnpmArg, runPnpm } from "./shared.js";
+import { pnpmArg, runPnpm, selectionArgs } from "./shared.js";
 import type { PnpmRemoveInput, PnpmCommandOutput } from "../../types.js";
 
 /**
@@ -22,7 +22,7 @@ export async function pnpmRemove(
   ctx: ProcedureContext
 ): Promise<PnpmCommandOutput> {
   {
-    const args: string[] = ["remove", ...input.packages.map((p) => pnpmArg("package", p))];
+    const args: string[] = [...selectionArgs(input), "remove", ...input.packages.map((p) => pnpmArg("package", p))];
 
     // Add flags
     if (input.global) args.push("--global");

package/src/procedures/pnpm/run.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ProcedureContext } from "@procedures/client";
-import { pnpmArg, runPnpm } from "./shared.js";
+import { pnpmArg, runPnpm, selectionArgs } from "./shared.js";
 import type { PnpmRunInput, PnpmCommandOutput } from "../../types.js";
 
 /**
@@ -29,7 +29,7 @@ export async function pnpmRun(
   ctx: ProcedureContext
 ): Promise<PnpmCommandOutput> {
   {
-    const args: string[] = ["run", pnpmArg("script", input.script)];
+    const args: string[] = [...selectionArgs(input), "run", pnpmArg("script", input.script)];
 
     // Add additional arguments
     if (input.args && input.args.length > 0) {

package/src/procedures/pnpm/shared.ts

@@ -12,7 +12,7 @@
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import type { ProcedureContext } from "@procedures/client";
-import type { PnpmCommandOutput } from "../../types.js";
+import type { PnpmCommandOutput, PnpmJsonOutput } 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 {
@@ -22,13 +22,33 @@ export function pnpmArg(name: string, value: string): string {
   return value;
 }
 
+/** The selection of the workspace packages of a command (roadmap R41). */
+export interface PnpmSelection {
+  filter?: string[] | undefined;
+  recursive?: boolean | undefined;
+}
+
+/**
+ * The selection options, before the command: `--filter=<selector>` for each selector, and
+ * `--recursive`. With "=", pnpm reads each selector as the value of `--filter`, also when it
+ * starts with "-" or "!".
+ */
+export function selectionArgs(input: PnpmSelection): string[] {
+  const args = (input.filter ?? []).map((selector) => `--filter=${selector}`);
+  if (input.recursive) args.push("--recursive");
+  return args;
+}
+
 /** 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
+  // When pnpm runs this process, npm_execpath is its script, or its executable from pnpm 12 on
   const execPath = process.env["npm_execpath"];
   if (execPath && /pnpm\.c?js$/.test(execPath) && existsSync(execPath)) {
     return { command: process.execPath, prefix: [execPath] };
   }
+  if (execPath && /(^|[\\/])pnpm(\.exe)?$/i.test(execPath) && existsSync(execPath)) {
+    return { command: execPath, prefix: [] };
+  }
   if (process.platform !== "win32") {
     return { command: "pnpm", prefix: [] };
   }
@@ -42,7 +62,7 @@ export function resolvePnpm(): { command: string; prefix: string[] } {
       return { command: process.execPath, prefix: [script] };
     }
   }
-  throw new Error("pnpm was not found: install pnpm, or run this from a pnpm script");
+  throw new Error(`pnpm was not found: install pnpm, or run this from a pnpm script (npm_execpath: ${execPath ?? "not set"})`);
 }
 
 /** This function runs `pnpm <args>` and gives its result. It does not throw for a failed command. */
@@ -83,3 +103,24 @@ export async function runPnpm(
     };
   }
 }
+
+/**
+ * This function runs `pnpm <args>` for a command that writes JSON, and gives `data`: the parsed
+ * standard output. Output that is not JSON gives no `data`. It does not throw.
+ */
+export async function runPnpmJson(
+  args: string[],
+  input: { cwd?: string | undefined; timeout?: number | undefined },
+  ctx: ProcedureContext
+): Promise<PnpmJsonOutput> {
+  const result: PnpmJsonOutput = await runPnpm(args, input, ctx);
+  const text = result.stdout.trim();
+  if (text.startsWith("{") || text.startsWith("[")) {
+    try {
+      result.data = JSON.parse(text);
+    } catch {
+      // Not JSON: stdout has the text
+    }
+  }
+  return result;
+}

package/src/procedures/pnpm/update.ts

@@ -0,0 +1,25 @@
+/**
+ * pnpm.update procedure
+ *
+ * Update packages (roadmap R41). Without `latest`, pnpm keeps each version in the range of
+ * package.json. With `latest`, it changes the ranges too.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { pnpmArg, runPnpm, selectionArgs } from "./shared.js";
+import type { PnpmUpdateInput, PnpmUpdateOutput } from "../../types.js";
+
+/**
+ * Update packages to their newest versions in the ranges
+ *
+ * @example
+ * await client.call(["pnpm", "update"], { packages: ["vitest"], latest: true, filter: ["@scope/app"] });
+ */
+export async function pnpmUpdate(input: PnpmUpdateInput, ctx: ProcedureContext): Promise<PnpmUpdateOutput> {
+  const args = [...selectionArgs(input), "update"];
+  if (input.latest) args.push("--latest");
+  if (input.prod) args.push("--prod");
+  if (input.dev) args.push("--dev");
+  args.push(...(input.packages ?? []).map((name) => pnpmArg("package", name)));
+  return runPnpm(args, input, ctx);
+}

package/src/procedures/pnpm/why.ts

@@ -0,0 +1,23 @@
+/**
+ * pnpm.why procedure
+ *
+ * Show why a package is installed, as JSON (roadmap R41). `data` is the parsed output of
+ * `pnpm why --json`: the packages that depend on it.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import { pnpmArg, runPnpmJson, selectionArgs } from "./shared.js";
+import { treeOptions } from "./list.js";
+import type { PnpmWhyInput, PnpmWhyOutput } from "../../types.js";
+
+/**
+ * Show why a package is installed, as JSON
+ *
+ * @example
+ * const { data } = await client.call(["pnpm", "why"], { packages: ["zod"] });
+ */
+export async function pnpmWhy(input: PnpmWhyInput, ctx: ProcedureContext): Promise<PnpmWhyOutput> {
+  const args = [...selectionArgs(input), "why", "--json", ...treeOptions(input)];
+  args.push(...input.packages.map((name) => pnpmArg("package", name)));
+  return runPnpmJson(args, input, ctx);
+}