@shell-shock/core 0.15.2 → 0.16.1

package/dist/components/spawn-builtin.mjs

@@ -0,0 +1,653 @@
+import { createComponent, mergeProps } from "@alloy-js/core/jsx-runtime";
+import defu$1 from "defu";
+import { Show, code, splitProps } from "@alloy-js/core";
+import { Spacing } from "@powerlines/plugin-alloy/core/components/spacing";
+import { FunctionDeclaration, InterfaceDeclaration, InterfaceMember, VarDeclaration } from "@alloy-js/typescript";
+import { ReflectionKind } from "@powerlines/deepkit/vendor/type";
+import { BuiltinFile } from "@powerlines/plugin-alloy/typescript/components/builtin-file";
+import { TSDoc, TSDocDefaultValue, TSDocParam, TSDocReturns } from "@powerlines/plugin-alloy/typescript/components/tsdoc";
+
+//#region src/components/spawn-builtin.tsx
+/**
+* A built-in module for handling child process spawning in Shell Shock.
+*/
+function SpawnBuiltin(props) {
+	const [{ children }, rest] = splitProps(props, ["children"]);
+	return createComponent(BuiltinFile, mergeProps({
+		id: "spawn",
+		description: "A module to handle spawning child processes."
+	}, rest, {
+		get imports() {
+			return defu$1(rest.imports ?? {}, {
+				"node:path": [
+					"basename",
+					"extname",
+					"dirname",
+					"join"
+				],
+				"node:fs": ["existsSync"],
+				"node:child_process": [{
+					name: "spawn",
+					alias: "_spawn"
+				}],
+				"node:stream": [{
+					name: "Stream",
+					default: true,
+					type: true
+				}]
+			});
+		},
+		get builtinImports() {
+			return defu$1(rest.builtinImports ?? {}, { env: ["isWindows"] });
+		},
+		get children() {
+			return [
+				createComponent(FunctionDeclaration, {
+					name: "resolveCommandEnv",
+					parameters: [{
+						name: "params",
+						type: "{ argv: string[]; env?: NodeJS.ProcessEnv; baseEnv?: NodeJS.ProcessEnv; }"
+					}],
+					returnType: "NodeJS.ProcessEnv",
+					children: code`const baseEnv = params.baseEnv ?? process.env;
+const argv = params.argv;
+const shouldSuppressNpmFund = (() => {
+  const cmd = basename(argv[0] ?? "");
+  if (cmd === "npm" || cmd === "npm.cmd" || cmd === "npm.exe") {
+    return true;
+  }
+  if (cmd === "node" || cmd === "node.exe") {
+    const script = argv[1] ?? "";
+
+    return script.includes("npm-cli.js");
+  }
+  return false;
+})();
+
+const mergedEnv = params.env ? { ...baseEnv, ...params.env } : { ...baseEnv };
+const resolvedEnv = Object.fromEntries(
+  Object.entries(mergedEnv)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => [key, String(value)])
+);
+if (shouldSuppressNpmFund) {
+  resolvedEnv.NPM_CONFIG_FUND ??= "false";
+  resolvedEnv.npm_config_fund ??= "false";
+}
+return resolvedEnv;`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "isWindowsBatchCommand",
+					parameters: [{
+						name: "resolvedCommand",
+						type: "string"
+					}],
+					returnType: "boolean",
+					children: code`if (!isWindows) {
+  return false;
+}
+const ext = extname(resolvedCommand).toLowerCase();
+
+return ext === ".cmd" || ext === ".bat";`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "escapeForCmdExe",
+					parameters: [{
+						name: "arg",
+						type: "string"
+					}],
+					returnType: "string",
+					children: code`if (/[&|<>^%\\\\r\\\\n]/.test(arg)) {
+  throw new Error(
+    \`Unsafe Windows cmd.exe argument detected: \${JSON.stringify(arg)}. \` +
+      "Pass an explicit shell-wrapper argv at the call site instead."
+  );
+}
+if (!arg.includes(" ") && !arg.includes('"')) {
+  return arg;
+}
+return \`"\${arg.replace(/"/g, '""')}"\`;`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "buildCmdExeCommandLine",
+					parameters: [{
+						name: "resolvedCommand",
+						type: "string"
+					}, {
+						name: "args",
+						type: "string[]"
+					}],
+					returnType: "string",
+					children: code`return [escapeForCmdExe(resolvedCommand), ...args.map(escapeForCmdExe)].join(
+  " "
+);`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "resolveNpmArgvForWindows",
+					doc: "On Windows, Node 18.20.2+ (CVE-2024-27980) rejects spawning .cmd/.bat directly without shell, causing EINVAL. Resolve npm/npx to node + cli script so we spawn node.exe instead of npm.cmd.",
+					parameters: [{
+						name: "argv",
+						type: "string[]"
+					}],
+					returnType: "string[] | null",
+					children: code`if (!isWindows || argv.length === 0) {
+  return null;
+}
+const base = basename(argv[0] ?? "")
+  .toLowerCase()
+  .replace(/\.(?:cmd|exe|bat)$/, "");
+const cliName =
+  base === "npx" ? "npx-cli.js" : base === "npm" ? "npm-cli.js" : null;
+if (!cliName) {
+  return null;
+}
+const nodeDir = dirname(process.execPath);
+const cliPath = join(nodeDir, "node_modules", "npm", "bin", cliName);
+if (!existsSync(cliPath)) {
+  const command = argv[0] ?? "";
+  const ext = extname(command).toLowerCase();
+  const shimmedCommand = ext ? command : \`\${command}.cmd\`;
+
+  return [shimmedCommand, ...argv.slice(1)];
+}
+return [process.execPath, cliPath, ...argv.slice(1)];`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "resolveCommand",
+					doc: "Resolves a command for Windows compatibility. On Windows, non-.exe commands (like pnpm, yarn) are resolved to .cmd; npm/npx are handled by resolveNpmArgvForWindows to avoid spawn EINVAL (no direct .cmd).",
+					parameters: [{
+						name: "command",
+						type: "string"
+					}],
+					returnType: "string",
+					children: code`if (!isWindows) {
+  return command;
+}
+const base = basename(command).toLowerCase();
+if (extname(base)) {
+  return command;
+}
+if (["pnpm", "yarn"].includes(base)) {
+  return \`\${command}.cmd\`;
+}
+return command;`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "resolveCommandStdio",
+					parameters: [{
+						name: "params",
+						type: "{ hasInput: boolean; preferInherit: boolean; }"
+					}],
+					returnType: "[\"pipe\" | \"inherit\" | \"ignore\", \"pipe\", \"pipe\"]",
+					children: code`const stdin = params.hasInput
+  ? "pipe"
+  : params.preferInherit
+    ? "inherit"
+    : "pipe";
+
+return [stdin, "pipe", "pipe"];`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "resolveChildProcessInvocation",
+					parameters: [{
+						name: "params",
+						type: "{ argv: string[]; windowsVerbatimArguments?: boolean; }"
+					}],
+					returnType: "{ args: string[]; command: string; usesWindowsExitCodeShim: boolean; windowsHide: true; windowsVerbatimArguments?: boolean; }",
+					children: code`const finalArgv =
+  isWindows
+    ? (resolveNpmArgvForWindows(params.argv) ?? params.argv)
+    : params.argv;
+const resolvedCommand =
+  finalArgv !== params.argv
+    ? (finalArgv[0] ?? "")
+    : resolveCommand(params.argv[0] ?? "");
+const useCmdWrapper = isWindowsBatchCommand(resolvedCommand);
+
+return {
+  command: useCmdWrapper
+    ? (process.env.ComSpec ?? "cmd.exe")
+    : resolvedCommand,
+  args: useCmdWrapper
+    ? [
+        "/d",
+        "/s",
+        "/c",
+        buildCmdExeCommandLine(resolvedCommand, finalArgv.slice(1))
+      ]
+    : finalArgv.slice(1),
+  usesWindowsExitCodeShim:
+    isWindows &&
+    (useCmdWrapper || finalArgv !== params.argv),
+  windowsHide: true,
+  windowsVerbatimArguments: useCmdWrapper
+    ? true
+    : params.windowsVerbatimArguments
+};`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "resolveProcessExitCode",
+					parameters: [{
+						name: "params",
+						type: "{ explicitCode: number | null | undefined; childExitCode: number | null | undefined; resolvedSignal: NodeJS.Signals | null; usesWindowsExitCodeShim: boolean; timedOut: boolean; noOutputTimedOut: boolean; killIssuedByTimeout: boolean; }"
+					}],
+					returnType: "number | null",
+					children: code`return (
+  params.explicitCode ??
+  params.childExitCode ??
+  (params.usesWindowsExitCodeShim &&
+  params.resolvedSignal == null &&
+  !params.timedOut &&
+  !params.noOutputTimedOut &&
+  !params.killIssuedByTimeout
+    ? 0
+    : null)
+);`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(FunctionDeclaration, {
+					name: "shouldSpawnWithShell",
+					parameters: [{
+						name: "params",
+						type: "{ resolvedCommand: string; platform: NodeJS.Platform; }"
+					}],
+					returnType: "boolean",
+					children: code`// SECURITY: never enable \`shell\` for argv-based execution.
+// \`shell\` routes through cmd.exe on Windows, which turns untrusted argv values
+// (like chat prompts passed as CLI args) into command-injection primitives.
+// If you need a shell, use an explicit shell-wrapper argv (e.g. \`cmd.exe /c ...\`)
+// and validate/escape at the call site.
+void params;
+return false;`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(TSDoc, { heading: "The result of a spawn operation." }),
+				createComponent(InterfaceDeclaration, {
+					"export": true,
+					name: "SpawnResult",
+					get children() {
+						return [
+							createComponent(TSDoc, { heading: "The PID of the spawned child process, if available." }),
+							createComponent(InterfaceMember, {
+								name: "pid",
+								optional: true,
+								type: "number"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The standard output produced by the child process." }),
+							createComponent(InterfaceMember, {
+								name: "stdout",
+								type: "string"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The standard error produced by the child process." }),
+							createComponent(InterfaceMember, {
+								name: "stderr",
+								type: "string"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The exit code of the child process, if available." }),
+							createComponent(InterfaceMember, {
+								name: "code",
+								type: "number | null"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The signal that caused the child process to terminate, if it was killed by a signal." }),
+							createComponent(InterfaceMember, {
+								name: "signal",
+								type: "NodeJS.Signals | null"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "Whether the child process was killed." }),
+							createComponent(InterfaceMember, {
+								name: "killed",
+								type: "boolean"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The reason for the child process termination." }),
+							createComponent(InterfaceMember, {
+								name: "termination",
+								type: code`"exit" | "timeout" | "no-output-timeout" | "signal"`
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "Whether the child process timed out due to no output." }),
+							createComponent(InterfaceMember, {
+								name: "noOutputTimedOut",
+								optional: true,
+								type: "boolean"
+							})
+						];
+					}
+				}),
+				createComponent(Spacing, {}),
+				createComponent(TSDoc, { heading: "Options for spawning a child process." }),
+				createComponent(InterfaceDeclaration, {
+					"export": true,
+					name: "SpawnOptions",
+					get children() {
+						return [
+							createComponent(TSDoc, {
+								heading: "The timeout in milliseconds for the spawn operation. If the process runs longer than this, it will be killed and the spawn promise will reject. This can also be provided as a number directly to the spawn function for convenience. Providing \\`-1\\` will disable the timeout.",
+								get children() {
+									return createComponent(TSDocDefaultValue, {
+										get type() {
+											return ReflectionKind.number;
+										},
+										defaultValue: "300000"
+									});
+								}
+							}),
+							createComponent(InterfaceMember, {
+								name: "timeoutMs",
+								type: "number"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The current working directory of the child process." }),
+							createComponent(InterfaceMember, {
+								name: "cwd",
+								optional: true,
+								type: "string"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The input to be passed to the child process." }),
+							createComponent(InterfaceMember, {
+								name: "input",
+								optional: true,
+								type: "string"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The environment variables for the child process." }),
+							createComponent(InterfaceMember, {
+								name: "env",
+								optional: true,
+								type: "NodeJS.ProcessEnv"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "Whether to pass arguments to the child process verbatim on Windows." }),
+							createComponent(InterfaceMember, {
+								name: "windowsVerbatimArguments",
+								optional: true,
+								type: "boolean"
+							}),
+							createComponent(Spacing, {}),
+							createComponent(TSDoc, { heading: "The timeout in milliseconds for the child process to produce output on stdout or stderr. If the process produces no output for this duration, it will be killed and the spawn promise will reject with a no-output-timeout termination reason." }),
+							createComponent(InterfaceMember, {
+								name: "noOutputTimeoutMs",
+								optional: true,
+								type: "number"
+							})
+						];
+					}
+				}),
+				createComponent(Spacing, {}),
+				createComponent(VarDeclaration, {
+					"const": true,
+					name: "WINDOWS_CLOSE_STATE_SETTLE_TIMEOUT_MS",
+					initializer: code`250`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(VarDeclaration, {
+					"const": true,
+					name: "WINDOWS_CLOSE_STATE_POLL_MS",
+					initializer: code`10`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(TSDoc, {
+					heading: "Spawns a child process with the given arguments and options, returning a promise that resolves with the result of the spawn operation.",
+					get children() {
+						return [
+							createComponent(TSDocParam, {
+								name: "argv",
+								children: "The command and its arguments to spawn."
+							}),
+							createComponent(TSDocParam, {
+								name: "optionsOrTimeoutMs",
+								children: `The options for spawning the command, or a number representing the timeout in milliseconds. This allows for a convenient shorthand when only a timeout is needed. Providing \`-1\` will disable the timeout. If no options or timeout are provided, a default timeout of 5 minutes will be used.`
+							}),
+							createComponent(TSDocReturns, { children: "A promise that resolves with the result of the spawn operation, including stdout, stderr, exit code, signal, and termination reason." })
+						];
+					}
+				}),
+				createComponent(FunctionDeclaration, {
+					"export": true,
+					async: true,
+					name: "spawn",
+					parameters: [{
+						name: "argv",
+						type: "string[]"
+					}, {
+						name: "optionsOrTimeoutMs",
+						type: "number | SpawnOptions",
+						default: "300000"
+					}],
+					returnType: "Promise<SpawnResult>",
+					children: code`const options: SpawnOptions =
+  typeof optionsOrTimeoutMs === "number"
+    ? { timeoutMs: optionsOrTimeoutMs }
+    : optionsOrTimeoutMs;
+const { timeoutMs, cwd, input, env, noOutputTimeoutMs } = options;
+const hasInput = input !== undefined;
+const resolvedEnv = resolveCommandEnv({ argv, env });
+const stdio = resolveCommandStdio({ hasInput, preferInherit: true });
+const invocation = resolveChildProcessInvocation({
+  argv,
+  windowsVerbatimArguments: options.windowsVerbatimArguments
+});
+
+const child = _spawn(invocation.command, invocation.args, {
+  stdio,
+  cwd,
+  env: resolvedEnv,
+  windowsHide: invocation.windowsHide,
+  windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+  ...(shouldSpawnWithShell({
+    resolvedCommand: invocation.command,
+    platform: process.platform
+  })
+    ? { shell: true }
+    : {})
+});
+
+return new Promise((resolve, reject) => {
+  let stdout = "";
+  let stderr = "";
+  let settled = false;
+  let timedOut = false;
+  let noOutputTimedOut = false;
+  let killIssuedByTimeout = false;
+  let childExitState: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  } | null = null;
+  let closeFallbackTimer: NodeJS.Timeout | null = null;
+  let noOutputTimer: NodeJS.Timeout | null = null;
+  const shouldTrackOutputTimeout =
+    typeof noOutputTimeoutMs === "number" &&
+    Number.isFinite(noOutputTimeoutMs) &&
+    noOutputTimeoutMs > 0;
+
+  const clearNoOutputTimer = () => {
+    if (!noOutputTimer) {
+      return;
+    }
+    clearTimeout(noOutputTimer);
+    noOutputTimer = null;
+  };
+
+  const clearCloseFallbackTimer = () => {
+    if (!closeFallbackTimer) {
+      return;
+    }
+    clearTimeout(closeFallbackTimer);
+    closeFallbackTimer = null;
+  };
+
+  const killChild = () => {
+    if (settled || typeof child?.kill !== "function") {
+      return;
+    }
+    killIssuedByTimeout = true;
+    child.kill("SIGKILL");
+  };
+
+  const armNoOutputTimer = () => {
+    if (!shouldTrackOutputTimeout || settled) {
+      return;
+    }
+    clearNoOutputTimer();
+    noOutputTimer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      noOutputTimedOut = true;
+      killChild();
+    }, Math.floor(noOutputTimeoutMs));
+  };
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killChild();
+  }, timeoutMs >= 0 ? timeoutMs : Number.POSITIVE_INFINITY);
+  armNoOutputTimer();
+
+  if (hasInput && child.stdin) {
+    child.stdin.write(input ?? "");
+    child.stdin.end();
+  }
+
+  child.stdout?.on("data", (d: Stream) => {
+    stdout += d.toString();
+    armNoOutputTimer();
+  });
+  child.stderr?.on("data", (d: Stream) => {
+    stderr += d.toString();
+    armNoOutputTimer();
+  });
+  child.on("error", err => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    clearTimeout(timer);
+    clearNoOutputTimer();
+    clearCloseFallbackTimer();
+    reject(err);
+  });
+  child.on("exit", (code, signal) => {
+    childExitState = { code, signal };
+    if (settled || closeFallbackTimer) {
+      return;
+    }
+    closeFallbackTimer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+    }, 250);
+  });
+  const resolveFromClose = (
+    code: number | null,
+    signal: NodeJS.Signals | null
+  ) => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    clearTimeout(timer);
+    clearNoOutputTimer();
+    clearCloseFallbackTimer();
+    const resolvedSignal =
+      childExitState?.signal ?? signal ?? child.signalCode ?? null;
+    const resolvedCode = resolveProcessExitCode({
+      explicitCode: childExitState?.code ?? code,
+      childExitCode: child.exitCode,
+      resolvedSignal,
+      usesWindowsExitCodeShim: invocation.usesWindowsExitCodeShim,
+      timedOut,
+      noOutputTimedOut,
+      killIssuedByTimeout
+    });
+    const termination = noOutputTimedOut
+      ? "no-output-timeout"
+      : timedOut
+        ? "timeout"
+        : resolvedSignal != null
+          ? "signal"
+          : "exit";
+    const normalizedCode =
+      termination === "timeout" || termination === "no-output-timeout"
+        ? resolvedCode === 0
+          ? 124
+          : resolvedCode
+        : resolvedCode;
+    resolve({
+      pid: child.pid ?? undefined,
+      stdout,
+      stderr,
+      code: normalizedCode,
+      signal: resolvedSignal,
+      killed: child.killed,
+      termination,
+      noOutputTimedOut
+    });
+  };
+  child.on("close", (code, signal) => {
+    if (
+      !isWindows ||
+      childExitState != null ||
+      code != null ||
+      signal != null ||
+      child.exitCode != null ||
+      child.signalCode != null
+    ) {
+      resolveFromClose(code, signal);
+      return;
+    }
+
+    const startedAt = Date.now();
+    const waitForExitState = () => {
+      if (settled) {
+        return;
+      }
+      if (
+        childExitState != null ||
+        child.exitCode != null ||
+        child.signalCode != null
+      ) {
+        resolveFromClose(code, signal);
+        return;
+      }
+      if (Date.now() - startedAt >= WINDOWS_CLOSE_STATE_SETTLE_TIMEOUT_MS) {
+        resolveFromClose(code, signal);
+        return;
+      }
+      setTimeout(waitForExitState, WINDOWS_CLOSE_STATE_POLL_MS);
+    };
+    waitForExitState();
+  });
+});`
+				}),
+				createComponent(Spacing, {}),
+				createComponent(Show, {
+					get when() {
+						return Boolean(children);
+					},
+					children
+				})
+			];
+		}
+	}));
+}
+
+//#endregion
+export { SpawnBuiltin };
+//# sourceMappingURL=spawn-builtin.mjs.map