@socketsecurity/lib 3.3.11 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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
+
+- **Spinner**: New `skip()` and `skipAndStop()` methods for displaying skipped operations
+  - `skip(text)`: Display skip message alongside spinner (e.g., "Skipping optional step...")
+  - `skipAndStop(text)`: Display skip message and stop spinner in one call
+  - Uses cyan ↻ (refresh/reload) symbol with @ ASCII fallback
+  - Normalizes text formatting consistently with other spinner methods
+  - Useful for communicating skipped steps during long-running operations
+
+- **Logger**: New `skip()` method and symbol for skipped operations
+  - `LOG_SYMBOLS.skip`: New cyan ↻ symbol for skip output (@ ASCII fallback)
+  - `skip(message)`: Display skip messages with dedicated symbol
+  - Complements existing info/step/success/error/warning/reason methods
+
 ## [3.3.11](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.11) - 2025-11-14
 
 ### Fixed

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/dist/logger.d.ts

@@ -26,6 +26,8 @@ type LogSymbols = {
     progress: string;
     /** Dimmed yellow reasoning/working symbol (∴ or :. in ASCII) */
     reason: string;
+    /** Cyan colored skip symbol (↻ or @ in ASCII) */
+    skip: string;
     /** Cyan colored step symbol (→ or > in ASCII) */
     step: string;
     /** Green colored success symbol (✔ or √ in ASCII) */
@@ -741,6 +743,24 @@ export declare class Logger {
      * ```
      */
     resetIndent(): this;
+    /**
+     * Logs a skip message with a cyan colored skip symbol.
+     *
+     * Automatically prefixes the message with `LOG_SYMBOLS.skip` (cyan ↻).
+     * Always outputs to stderr. If the message starts with an existing
+     * symbol, it will be stripped and replaced.
+     *
+     * @param args - Message and additional arguments to log
+     * @returns The logger instance for chaining
+     *
+     * @example
+     * ```typescript
+     * logger.skip('Test skipped due to environment')
+     * logger.skip('Skipping optional step')
+     * logger.skip('Feature disabled, skipping')
+     * ```
+     */
+    skip(...args: unknown[]): this;
     /**
      * Logs a main step message with a cyan arrow symbol and blank line before it.
      *

package/dist/logger.js

@@ -92,6 +92,7 @@ const LOG_SYMBOLS = /* @__PURE__ */ (() => {
     target.reason = colors.dim(
       /* @__PURE__ */ applyColor(supported ? "\u2234" : ":.", warningColor, colors)
     );
+    target.skip = /* @__PURE__ */ applyColor(supported ? "\u21BB" : "@", stepColor, colors);
     target.step = /* @__PURE__ */ applyColor(supported ? "\u2192" : ">", stepColor, colors);
     target.success = /* @__PURE__ */ applyColor(supported ? "\u2714" : "\u221A", successColor, colors);
     target.warn = /* @__PURE__ */ applyColor(supported ? "\u26A0" : "\u203C", warningColor, colors);
@@ -332,6 +333,7 @@ class Logger {
       reason: colors.dim(
         /* @__PURE__ */ applyColor(supported ? "\u2234" : ":.", theme.colors.warning, colors)
       ),
+      skip: /* @__PURE__ */ applyColor(supported ? "\u21BB" : "@", theme.colors.step, colors),
       step: /* @__PURE__ */ applyColor(supported ? "\u2192" : ">", theme.colors.step, colors),
       success: /* @__PURE__ */ applyColor(supported ? "\u2714" : "\u221A", theme.colors.success, colors),
       warn: /* @__PURE__ */ applyColor(supported ? "\u26A0" : "\u203C", theme.colors.warning, colors)
@@ -381,7 +383,7 @@ class Logger {
    * @private
    */
   #stripSymbols(text) {
-    return text.replace(/^(?:[✖✗×⚠‼✔✓√ℹ→∴]|:.)[\uFE0F\s]*/u, "");
+    return text.replace(/^(?:[✖✗×⚠‼✔✓√ℹ→∴↻]|:.)[\uFE0F\s]*/u, "");
   }
   /**
    * Apply a method with a symbol prefix.
@@ -1119,6 +1121,26 @@ class Logger {
     }
     return this;
   }
+  /**
+   * Logs a skip message with a cyan colored skip symbol.
+   *
+   * Automatically prefixes the message with `LOG_SYMBOLS.skip` (cyan ↻).
+   * Always outputs to stderr. If the message starts with an existing
+   * symbol, it will be stripped and replaced.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.skip('Test skipped due to environment')
+   * logger.skip('Skipping optional step')
+   * logger.skip('Feature disabled, skipping')
+   * ```
+   */
+  skip(...args) {
+    return this.#symbolApply("skip", args);
+  }
   /**
    * Logs a main step message with a cyan arrow symbol and blank line before it.
    *

package/dist/spinner.d.ts

@@ -7,9 +7,9 @@ import type { ColorInherit, ColorRgb, ColorValue } from './colors';
 import type { ShimmerColorGradient, ShimmerConfig, ShimmerDirection, ShimmerState } from './effects/text-shimmer';
 /**
  * Symbol types for status messages.
- * Maps to log symbols: fail (✗), info (ℹ), reason (∴), success (✓), warn (⚠).
+ * Maps to log symbols: fail (✗), info (ℹ), reason (∴), skip (↻), success (✓), warn (⚠).
  */
-export type SymbolType = 'fail' | 'info' | 'reason' | 'success' | 'warn';
+export type SymbolType = 'fail' | 'info' | 'reason' | 'skip' | 'success' | 'warn';
 /**
  * Progress tracking information for display in spinner.
  * Used by `progress()` and `progressStep()` methods to show animated progress bars.
@@ -107,6 +107,10 @@ export type Spinner = {
     reasonAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
     /** Set complete shimmer configuration */
     setShimmer(config: ShimmerConfig): Spinner;
+    /** Show skip (↻) message without stopping the spinner */
+    skip(text?: string | undefined, ...extras: unknown[]): Spinner;
+    /** Show skip (↻) message and stop the spinner, auto-clearing the line */
+    skipAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
     /** Start spinning with optional text */
     start(text?: string | undefined): Spinner;
     /** Show main step message to stderr without stopping */

package/dist/spinner.js

@@ -605,6 +605,37 @@ function Spinner(options) {
         }
         return this;
       }
+      /**
+       * Show a skip message (↻) without stopping the spinner.
+       * Outputs to stderr and continues spinning.
+       *
+       * @param text - Skip message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      skip(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("skip", [text, ...extras]);
+      }
+      /**
+       * Show a skip message (↻) and stop the spinner.
+       * Auto-clears the spinner line before displaying the message.
+       *
+       * Implementation note: Similar to reasonAndStop(), this method cannot use #apply()
+       * with a 'skip' method name because yocto-spinner doesn't have a built-in 'skip'
+       * method. Instead, we manually stop the spinner then log the message with the skip symbol.
+       *
+       * @param text - Skip message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      skipAndStop(text, ...extras) {
+        this.#apply("stop", []);
+        const normalized = normalizeText(text);
+        if (normalized) {
+          logger.error(`${import_logger.LOG_SYMBOLS.skip} ${normalized}`, ...extras);
+        }
+        return this;
+      }
       /**
        * Set complete shimmer configuration.
        * Replaces any existing shimmer config with the provided values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "3.3.11",
+  "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",