@procedures/node 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * client-node - Node.js process management procedures
+ */
+
+export * from "./module.js";
+
+// Export types
+export * from "./types.js";
+
+// Export procedures
+export { nodeRun } from "./procedures/node/run.js";
+export { nodeSpawn } from "./procedures/node/spawn.js";
+export { nodeKill } from "./procedures/node/kill.js";
+export { nodeStatus } from "./procedures/node/status.js";
+
+// Export process manager
+export { processManager } from "./process-manager.js";

package/src/module.ts

@@ -0,0 +1,121 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for Node.js process management
+ */
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import { nodeRun } from "./procedures/node/run.js";
+import { nodeSpawn } from "./procedures/node/spawn.js";
+import { nodeKill } from "./procedures/node/kill.js";
+import { nodeStatus } from "./procedures/node/status.js";
+import {
+  NodeRunInputSchema,
+  NodeSpawnInputSchema,
+  NodeKillInputSchema,
+  NodeStatusInputSchema,
+  type NodeRunInput,
+  type NodeRunOutput,
+  type NodeSpawnInput,
+  type NodeSpawnOutput,
+  type NodeKillInput,
+  type NodeKillOutput,
+  type NodeStatusInput,
+  type NodeStatusOutput,
+  NodeRunOutputSchema,
+  NodeSpawnOutputSchema,
+  NodeKillOutputSchema,
+  NodeStatusOutputSchema,
+} from "./types.js";
+
+// Procedure definitions
+const nodeRunProcedure = createProcedure()
+  .path(["node", "run"])
+  .input(zodAdapter<NodeRunInput>(NodeRunInputSchema))
+  .output(zodAdapter<NodeRunOutput>(NodeRunOutputSchema))
+  .meta({
+    description: "Run a Node.js script and wait for completion",
+    args: ["script"],
+    shorts: { cwd: "C", timeout: "t" },
+    output: "json",
+    // The caller chooses the script, and the script can do anything
+    effects: { reads: ["process"], writes: ["process"] },
+  })
+  .handler(async (input: NodeRunInput, ctx): Promise<NodeRunOutput> => {
+    return nodeRun(input, ctx);
+  })
+  .build();
+
+const nodeSpawnProcedure = createProcedure()
+  .path(["node", "spawn"])
+  .input(zodAdapter<NodeSpawnInput>(NodeSpawnInputSchema))
+  .output(zodAdapter<NodeSpawnOutput>(NodeSpawnOutputSchema))
+  .meta({
+    description: "Spawn a long-running Node.js process",
+    args: ["script"],
+    shorts: { cwd: "C" },
+    output: "json",
+    // It adds the process to the jobs of the host
+    effects: { reads: ["process"], writes: ["process", "jobs"] },
+  })
+  .handler(async (input: NodeSpawnInput): Promise<NodeSpawnOutput> => {
+    return nodeSpawn(input);
+  })
+  .build();
+
+const nodeKillProcedure = createProcedure()
+  .path(["node", "kill"])
+  .input(zodAdapter<NodeKillInput>(NodeKillInputSchema))
+  .output(zodAdapter<NodeKillOutput>(NodeKillOutputSchema))
+  .meta({
+    description: "Kill a spawned Node.js process",
+    args: ["processId"],
+    shorts: { signal: "s" },
+    output: "json",
+    // It ends a process of node.spawn. A second call finds the process already ended.
+    // It stops a job of the host: a process that node.spawn started
+    effects: { reads: ["jobs"], writes: ["jobs"], idempotent: true },
+  })
+  .handler(async (input: NodeKillInput): Promise<NodeKillOutput> => {
+    return nodeKill(input);
+  })
+  .build();
+
+const nodeStatusProcedure = createProcedure()
+  .path(["node", "status"])
+  .input(zodAdapter<NodeStatusInput>(NodeStatusInputSchema))
+  .output(zodAdapter<NodeStatusOutput>(NodeStatusOutputSchema))
+  .meta({
+    description: "Get status of running Node.js processes",
+    args: [],
+    shorts: {},
+    output: "json",
+    // It reads the records of the processes of node.spawn
+    effects: { reads: ["jobs"], writes: [] },
+  })
+  .handler(async (input: NodeStatusInput): Promise<NodeStatusOutput> => {
+    return nodeStatus(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 nodeModule: ProcedureModule = defineModule("@procedures/node", [
+    nodeRunProcedure,
+    nodeSpawnProcedure,
+    nodeKillProcedure,
+    nodeStatusProcedure,
+  ]);
+
+export default nodeModule;
+
+/**
+ * This function registers the procedures of @procedures/node, 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 registerNodeProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [nodeModule]);
+}

package/src/procedures/node/index.ts

@@ -0,0 +1,4 @@
+export { nodeRun } from "./run.js";
+export { nodeSpawn } from "./spawn.js";
+export { nodeKill } from "./kill.js";
+export { nodeStatus } from "./status.js";

package/src/procedures/node/kill.ts

@@ -0,0 +1,30 @@
+/**
+ * node.kill procedure
+ *
+ * Kills a spawned Node.js process and the processes that it started.
+ */
+
+import type { NodeKillInput, NodeKillOutput } from "../../types.js";
+import { processManager } from "../../process-manager.js";
+
+/**
+ * Kill a spawned process by ID, and wait for its end
+ */
+export async function nodeKill(input: NodeKillInput): Promise<NodeKillOutput> {
+  const { processId, signal = "SIGTERM" } = input;
+
+  if (!processManager.get(processId)) {
+    return {
+      success: false,
+    };
+  }
+
+  const success = await processManager.kill(processId, signal as NodeJS.Signals);
+  const processInfo = processManager.getStatus(processId)[0];
+
+  const result: NodeKillOutput = { success };
+  if (processInfo?.exitCode !== undefined) {
+    result.exitCode = processInfo.exitCode;
+  }
+  return result;
+}

package/src/procedures/node/run.ts

@@ -0,0 +1,56 @@
+/**
+ * node.run procedure
+ *
+ * Runs a Node.js script and waits for completion.
+ *
+ * The script runs with the Node.js of the host (`process.execPath`), through `runCommand` of
+ * client-shell: the output has a limit, and the timeout and the signal kill the script and the
+ * processes that it started (deep dive WRP-10). Before, the output had no limit, and the timeout
+ * killed only the direct child.
+ */
+
+import { runCommand } from "@procedures/shell/command";
+import type { NodeRunInput, NodeRunOutput } from "../../types.js";
+
+/** The end of the output that a timeout error shows. */
+const ERROR_OUTPUT_CHARS = 2000;
+
+/**
+ * Run a Node.js script and wait for completion
+ */
+export async function nodeRun(
+  input: NodeRunInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): Promise<NodeRunOutput> {
+  const { script, args = [], cwd, env, timeout, maxOutputBytes } = input;
+
+  const result = await runCommand(process.execPath, {
+    args: [script, ...args],
+    cwd,
+    env,
+    timeout,
+    signal: ctx?.signal,
+    maxOutputBytes,
+  });
+
+  if (result.error) {
+    throw new Error(`node did not start: ${result.error}`);
+  }
+  if (result.timedOut) {
+    const output = `${result.stdout}${result.stderr}`.slice(-ERROR_OUTPUT_CHARS);
+    throw new Error(`Process timed out after ${timeout}ms${output ? `. Output:\n${output}` : ""}`);
+  }
+  if (result.aborted) {
+    const error = new Error("node.run was aborted");
+    error.name = "AbortError";
+    throw error;
+  }
+
+  const output: NodeRunOutput = {
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+  if (result.truncated) output.truncated = true;
+  return output;
+}

package/src/procedures/node/spawn.ts

@@ -0,0 +1,39 @@
+/**
+ * node.spawn procedure
+ *
+ * Spawns a long-running Node.js process.
+ *
+ * The process is a record of the process registry of client-shell: node.status shows it,
+ * node.kill ends its whole tree, and it ends with the host (deep dive WRP-4, WRP-10).
+ */
+
+import type { NodeSpawnInput, NodeSpawnOutput } from "../../types.js";
+import { processManager } from "../../process-manager.js";
+
+/**
+ * Spawn a long-running Node.js process
+ */
+export async function nodeSpawn(input: NodeSpawnInput): Promise<NodeSpawnOutput> {
+  const { script, args = [], cwd, env, ready } = input;
+
+  const started = processManager.start(script, { args, cwd, env });
+  if (started.status === "error") {
+    throw new Error(`node did not start for ${script}`);
+  }
+
+  // Wait for ready pattern if specified
+  if (ready) {
+    try {
+      await processManager.waitForReady(started.processId, ready.pattern, ready.timeout ?? 30000);
+    } catch (error) {
+      // A process that is not ready is of no use to the caller: stop it
+      await processManager.kill(started.processId);
+      throw error;
+    }
+  }
+
+  return {
+    processId: started.processId,
+    pid: started.pid,
+  };
+}

package/src/procedures/node/status.ts

@@ -0,0 +1,23 @@
+/**
+ * node.status procedure
+ *
+ * Gets status of spawned Node.js processes.
+ */
+
+import type { NodeStatusInput, NodeStatusOutput } from "../../types.js";
+import { processManager } from "../../process-manager.js";
+
+/**
+ * Get status of running processes (and the recent exits)
+ */
+export async function nodeStatus(input: NodeStatusInput): Promise<NodeStatusOutput> {
+  const { processId } = input;
+
+  const processes = processManager.getStatus(processId).map((info) =>
+    input.output ? { ...info, output: processManager.output(info.processId) } : info
+  );
+
+  return {
+    processes,
+  };
+}

package/src/process-manager.ts

@@ -0,0 +1,102 @@
+/**
+ * Process Manager - Manages spawned Node.js processes
+ *
+ * The manager is a view of the process registry of client-shell, for the group "node"
+ * (deep dive WRP-4, WRP-10):
+ * - `kill` ends the whole process tree, not only the direct child;
+ * - the registry reads the output of each process, so a full pipe does not stop it;
+ * - the processes end when the host ends (before, they were detached and kept running);
+ * - the registry removes old exit records, and `cleanup` removes the rest.
+ */
+
+import { processes, type ManagedProcessInfo } from "@procedures/shell/command";
+import type { ProcessInfo } from "./types.js";
+
+/** The group of the node processes in the process registry. */
+export const NODE_GROUP = "node";
+
+function toProcessInfo(info: ManagedProcessInfo): ProcessInfo {
+  const result: ProcessInfo = {
+    processId: info.id,
+    pid: info.pid,
+    script: info.label ?? info.args[0] ?? "",
+    status: info.status,
+    startedAt: info.startedAt,
+  };
+  if (info.exitCode !== undefined) result.exitCode = info.exitCode;
+  if (info.exitedAt !== undefined) result.exitedAt = info.exitedAt;
+  return result;
+}
+
+class ProcessManager {
+  /**
+   * Start a Node.js script and record it
+   */
+  start(
+    script: string,
+    options: { args?: string[] | undefined; cwd?: string | undefined; env?: Record<string, string> | undefined }
+  ): ProcessInfo {
+    const info = processes.start(process.execPath, {
+      args: [script, ...(options.args ?? [])],
+      cwd: options.cwd,
+      env: options.env,
+      group: NODE_GROUP,
+      label: script,
+    });
+    return toProcessInfo(info);
+  }
+
+  /**
+   * Get a managed process by ID
+   */
+  get(processId: string): ProcessInfo | undefined {
+    const info = processes.get(processId);
+    return info && info.group === NODE_GROUP ? toProcessInfo(info) : undefined;
+  }
+
+  /**
+   * Kill a process (and the processes that it started) by ID, and wait for its end
+   */
+  async kill(processId: string, signal: NodeJS.Signals = "SIGTERM"): Promise<boolean> {
+    if (!this.get(processId)) return false;
+    return (await processes.stop(processId, signal)).stopped;
+  }
+
+  /**
+   * Wait for a ready pattern in the output
+   */
+  async waitForReady(processId: string, pattern: string, timeout: number = 30000): Promise<void> {
+    await processes.waitFor(processId, new RegExp(pattern), timeout);
+  }
+
+  /**
+   * The end of the output of a process (the last 64 KiB)
+   */
+  output(processId: string): string {
+    return this.get(processId) ? processes.output(processId) : "";
+  }
+
+  /**
+   * Get status of all or specific processes
+   */
+  getStatus(processId?: string): ProcessInfo[] {
+    return processes
+      .list({ group: NODE_GROUP })
+      .filter((info) => processId === undefined || info.id === processId)
+      .map(toProcessInfo);
+  }
+
+  /**
+   * Cleanup exited processes
+   */
+  cleanup(): number {
+    let cleaned = 0;
+    for (const info of processes.list({ group: NODE_GROUP })) {
+      if (info.exitedAt && processes.forget(info.id)) cleaned++;
+    }
+    return cleaned;
+  }
+}
+
+// Singleton instance
+export const processManager: ProcessManager = new ProcessManager();

package/src/register.ts

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

package/src/types.ts

@@ -0,0 +1,184 @@
+/**
+ * Type definitions for client-node procedures
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// node.run - Run script and wait for completion
+// ============================================================================
+
+export const NodeRunInputSchema: z.ZodObject<{
+  script: z.ZodString;
+  args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+  maxOutputBytes: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  /** Script path to run */
+  script: z.string().describe("Script path to run"),
+  /** Arguments to pass to the script */
+  args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Environment variables */
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+  /** Timeout in milliseconds. At the timeout, the script and its child processes are killed. */
+  timeout: z.number().optional().describe("Timeout in milliseconds. At the timeout, the script and its child processes are killed."),
+  /** The most bytes kept of each output stream (default: 64 MiB). The procedure keeps the first bytes. */
+  maxOutputBytes: z.number().int().positive().optional().describe("The most bytes kept of each output stream (default: 64 MiB). The procedure keeps the first bytes."),
+});
+
+export type NodeRunInput = z.infer<typeof NodeRunInputSchema>;
+
+export interface NodeRunOutput {
+  /** Exit code of the process */
+  exitCode: number;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+  /** True when an output stream was longer than `maxOutputBytes` */
+  truncated?: boolean | undefined;
+}
+
+// ============================================================================
+// node.spawn - Spawn long-running process
+// ============================================================================
+
+export const NodeSpawnInputSchema: z.ZodObject<{
+  script: z.ZodString;
+  args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  ready: z.ZodOptional<z.ZodObject<{
+    pattern: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+  }>>;
+}> = z.object({
+  /** Script path to run */
+  script: z.string().describe("Script path to run"),
+  /** Arguments to pass to the script */
+  args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Environment variables */
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+  /** Ready pattern - wait for this in stdout before returning */
+  ready: z
+    .object({
+      pattern: z.string(),
+      timeout: z.number().optional(),
+    })
+    .optional().describe("Ready pattern - wait for this in stdout before returning"),
+});
+
+export type NodeSpawnInput = z.infer<typeof NodeSpawnInputSchema>;
+
+export interface NodeSpawnOutput {
+  /** Unique process identifier for management */
+  processId: string;
+  /** OS process ID */
+  pid: number;
+}
+
+// ============================================================================
+// node.kill - Kill a spawned process
+// ============================================================================
+
+export const NodeKillInputSchema: z.ZodObject<{
+  processId: z.ZodString;
+  signal: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  /** Process ID returned from node.spawn */
+  processId: z.string().describe("Process ID returned from node.spawn"),
+  /** Signal to send (default: SIGTERM) */
+  signal: z.string().optional().describe("Signal to send (default: SIGTERM)"),
+});
+
+export type NodeKillInput = z.infer<typeof NodeKillInputSchema>;
+
+export interface NodeKillOutput {
+  /** Whether the kill was successful */
+  success: boolean;
+  /** Exit code if process exited */
+  exitCode?: number | undefined;
+}
+
+// ============================================================================
+// node.status - Get status of running processes
+// ============================================================================
+
+export const NodeStatusInputSchema: z.ZodObject<{
+  processId: z.ZodOptional<z.ZodString>;
+  output: z.ZodOptional<z.ZodBoolean>;
+}> = z.object({
+  /** Optional process ID to filter by */
+  processId: z.string().optional().describe("Optional process ID to filter by"),
+  /** 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 NodeStatusInput = z.infer<typeof NodeStatusInputSchema>;
+
+export interface ProcessInfo {
+  /** Process identifier */
+  processId: string;
+  /** OS process ID */
+  pid: number;
+  /** Script path */
+  script: string;
+  /** Current status */
+  status: "running" | "exited" | "error";
+  /** Exit code if exited */
+  exitCode?: number | undefined;
+  /** Start time */
+  startedAt: string;
+  /** Exit time if exited */
+  exitedAt?: string | undefined;
+  /** With `output: true`, the end of the output */
+  output?: string | undefined;
+}
+
+export interface NodeStatusOutput {
+  /** List of processes */
+  processes: ProcessInfo[];
+}
+
+// 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 NodeRunOutputSchema: z.ZodType<NodeRunOutput> = z.looseObject({
+  exitCode: z.number().describe("The exit code of the script"),
+  stdout: z.string().describe("The standard output"),
+  stderr: z.string().describe("The standard error"),
+  truncated: z.boolean().optional().describe("True when an output stream was longer than maxOutputBytes"),
+});
+
+export const NodeSpawnOutputSchema: z.ZodType<NodeSpawnOutput> = z.looseObject({
+  processId: z.string().describe("The id of the process: node.kill and node.status take it"),
+  pid: z.number().describe("The process id of the operating system"),
+});
+
+export const NodeKillOutputSchema: z.ZodType<NodeKillOutput> = z.looseObject({
+  success: z.boolean().describe("True when the process ended"),
+  exitCode: z.number().optional().describe("The exit code, when the process exited"),
+});
+
+export const NodeStatusOutputSchema: z.ZodType<NodeStatusOutput> = z.looseObject({
+  processes: z
+    .array(
+      z.looseObject({
+        processId: z.string().describe("The id of the process"),
+        pid: z.number().describe("The process id of the operating system"),
+        script: z.string().describe("The script"),
+        status: z.enum(["running", "exited", "error"]).describe("The state of the process"),
+        exitCode: z.number().optional().describe("The exit code, when the process exited"),
+        startedAt: z.string().describe("The start time (ISO 8601)"),
+        exitedAt: z.string().optional().describe("The end time (ISO 8601), when the process ended"),
+        output: z.string().optional().describe("With output: true, the end of the output"),
+      })
+    )
+    .describe("The processes of this host"),
+});