@socketsecurity/lib 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.5.0) - 2025-11-14
+
+### Added
+
+- **argv/quote**: New utilities for quoting command-line arguments when using `spawn()` with `shell: true`
+  - `posixQuote(arg)`: Quote arguments for POSIX shells (bash, sh, zsh) using single quotes
+  - `win32Quote(arg)`: Quote arguments for Windows cmd.exe using double quotes
+
 ## [3.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.4.0) - 2025-11-14
 
 ### Added

package/dist/argv/quote.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Argument quoting utilities for shell execution with spawn()
+ *
+ * These functions handle quoting of command-line arguments when using
+ * child_process.spawn() with shell: true.
+ *
+ * IMPORTANT: Only needed when shell: true. With shell: false, arguments
+ * are passed directly to the OS kernel as an array (no quoting needed).
+ */
+/**
+ * Quote an argument for POSIX shell execution (bash, sh, zsh).
+ *
+ * Uses single quotes (POSIX standard) which prevent all expansions except
+ * single quotes themselves. Internal single quotes are escaped using '\''
+ *
+ * @param arg - Argument to quote
+ * @returns Quoted argument safe for POSIX shells when using shell: true
+ *
+ * @example
+ * ```ts
+ * import { posixQuote } from '@socketsecurity/lib/argv/quote'
+ *
+ * // With shell: true on Unix
+ * const path = '/path/with spaces/file.txt'
+ * spawn('sh', ['-c', 'cat', posixQuote(path)], { shell: true })
+ * // sh receives: sh -c cat '/path/with spaces/file.txt'
+ * ```
+ */
+export declare function posixQuote(arg: string): string;
+/**
+ * Quote an argument for Windows cmd.exe shell execution.
+ *
+ * Uses double quotes (cmd.exe standard) and escapes internal quotes by doubling.
+ * Handles all cmd.exe special characters: space, &, |, <, >, ^, %, (, ), !, "
+ *
+ * @param arg - Argument to quote
+ * @returns Quoted argument safe for cmd.exe when using shell: true
+ *
+ * @example
+ * ```ts
+ * import { win32Quote } from '@socketsecurity/lib/argv/quote'
+ *
+ * // With shell: true on Windows
+ * const path = 'C:\\Program Files\\app.exe'
+ * spawn('cmd', ['/c', 'app', win32Quote(path)], { shell: true })
+ * // cmd.exe receives: cmd /c app "C:\Program Files\app.exe"
+ * ```
+ */
+export declare function win32Quote(arg: string): string;

package/dist/argv/quote.js

@@ -0,0 +1,42 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var quote_exports = {};
+__export(quote_exports, {
+  posixQuote: () => posixQuote,
+  win32Quote: () => win32Quote
+});
+module.exports = __toCommonJS(quote_exports);
+function posixQuote(arg) {
+  if (!/[\s&|<>$`\\*?[\](){};"'~!#]/.test(arg)) {
+    return arg;
+  }
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+function win32Quote(arg) {
+  if (!/[\s&|<>^%()!"]/.test(arg)) {
+    return arg;
+  }
+  return `"${arg.replace(/"/g, '""')}"`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  posixQuote,
+  win32Quote
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "packageManager": "pnpm@10.22.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
@@ -111,6 +111,10 @@
       "types": "./dist/argv/parse.d.ts",
       "default": "./dist/argv/parse.js"
     },
+    "./argv/quote": {
+      "types": "./dist/argv/quote.d.ts",
+      "default": "./dist/argv/quote.js"
+    },
     "./arrays": {
       "types": "./dist/arrays.d.ts",
       "default": "./dist/arrays.js"
@@ -687,7 +691,7 @@
     "@socketregistry/is-unicode-supported": "1.0.5",
     "@socketregistry/packageurl-js": "1.3.5",
     "@socketregistry/yocto-spinner": "1.0.25",
-    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@3.3.7",
+    "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@3.4.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250920.1",
     "@vitest/coverage-v8": "4.0.3",