@socketsecurity/lib 6.0.6 → 6.0.7

package/dist/spinner/default.js

@@ -16,8 +16,8 @@ src_external__socketregistry_yocto_spinner = require_runtime.__toESM(src_externa
 *   and memoized; `getDefaultSpinner()` defers `Spinner()` construction until
 *   first call so module initialization stays cheap.
 */
-let _cliSpinners;
-let _spinner;
+let cliSpinners;
+let spinner;
 /**
 * Get available CLI spinner styles or a specific style by name. Extends the
 * standard cli-spinners collection with Socket custom spinners.
@@ -42,17 +42,16 @@ let _spinner;
 *
 * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
 */
-/*@__NO_SIDE_EFFECTS__*/
 function getCliSpinners(styleName) {
-	if (_cliSpinners === void 0)
+	if (cliSpinners === void 0)
  /* c8 ignore stop */
-	_cliSpinners = {
+	cliSpinners = {
 		__proto__: null,
 		...(0, src_external__socketregistry_yocto_spinner.default)({}).constructor.spinners,
 		socket: require_effects_pulse_frames.generateSocketSpinnerFrames()
 	};
-	if (typeof styleName === "string" && _cliSpinners) return /* @__PURE__ */ require_objects_predicates.hasOwn(_cliSpinners, styleName) ? _cliSpinners[styleName] : void 0;
-	return _cliSpinners;
+	if (typeof styleName === "string" && cliSpinners) return require_objects_predicates.hasOwn(cliSpinners, styleName) ? cliSpinners[styleName] : void 0;
+	return cliSpinners;
 }
 /**
 * Get the default spinner instance. Lazily creates the spinner to avoid
@@ -70,8 +69,8 @@ function getCliSpinners(styleName) {
 * @returns Shared default spinner instance
 */
 function getDefaultSpinner() {
-	if (_spinner === void 0) _spinner = /* @__PURE__ */ require_spinner_spinner.Spinner();
-	return _spinner;
+	if (spinner === void 0) spinner = require_spinner_spinner.Spinner();
+	return spinner;
 }
 
 //#endregion

package/dist/spinner/spinner-internals.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Pure helpers extracted from the Socket `Spinner` class body: option
+ *   parsing (theme/color resolution, shimmer config) and the shimmer rendering
+ *   pass. Keeping these side-effect-free and outside the class keeps the class
+ *   module focused on method wiring and under the file-size cap.
+ */
+import type { ColorRgb } from '../colors/types';
+import type { ShimmerInfo, SpinnerOptions } from './types';
+/**
+ * Apply the shimmer effect to display text. Mutates the shimmer frame counter
+ * as it advances. Skips work in CI or when the direction is 'none'.
+ *
+ * @param displayText - Text to colorize.
+ * @param shimmer - Mutable shimmer state (frame counter is advanced).
+ * @param currentColor - The spinner's current RGB color (used for inherit).
+ *
+ * @returns Colorized text, or the input unchanged when shimmer is skipped.
+ */
+export declare function applyShimmer(displayText: string, shimmer: ShimmerInfo, currentColor: ColorRgb): string;
+/**
+ * Parse the shimmer option (object or direction string) into a `ShimmerInfo`.
+ *
+ * @param shimmer - The `shimmer` option value.
+ *
+ * @returns Parsed shimmer state, or undefined when shimmer is disabled.
+ */
+export declare function parseShimmerOption(shimmer: SpinnerOptions['shimmer']): ShimmerInfo | undefined;
+/**
+ * Resolve the spinner's RGB color from options and the active theme. Validates
+ * RGB tuples and falls back to the theme's primary color.
+ *
+ * @param opts - Normalized spinner options.
+ *
+ * @returns Resolved RGB color tuple.
+ */
+export declare function resolveSpinnerColorRgb(opts: SpinnerOptions): ColorRgb;

package/dist/spinner/spinner-internals.js

@@ -0,0 +1,101 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_primordials_array = require('../primordials/array.js');
+const require_themes_themes = require('../themes/themes.js');
+const require_themes_context = require('../themes/context.js');
+const require_env_ci = require('../env/ci.js');
+const require_colors_convert = require('../colors/convert.js');
+const require_spinner_format = require('./format.js');
+const require_effects_shimmer = require('../effects/shimmer.js');
+const require_effects_shimmer_terminal = require('../effects/shimmer-terminal.js');
+const require_themes_resolve = require('../themes/resolve.js');
+
+//#region src/spinner/spinner-internals.ts
+/**
+* Apply the shimmer effect to display text. Mutates the shimmer frame counter
+* as it advances. Skips work in CI or when the direction is 'none'.
+*
+* @param displayText - Text to colorize.
+* @param shimmer - Mutable shimmer state (frame counter is advanced).
+* @param currentColor - The spinner's current RGB color (used for inherit).
+*
+* @returns Colorized text, or the input unchanged when shimmer is skipped.
+*/
+function applyShimmer(displayText, shimmer, currentColor) {
+	let shimmerColor;
+	if (shimmer.color === "inherit") shimmerColor = currentColor;
+	else if (require_primordials_array.ArrayIsArray(shimmer.color[0])) shimmerColor = shimmer.color;
+	else shimmerColor = require_colors_convert.toRgb(shimmer.color);
+	if (!require_env_ci.getCI() && shimmer.direction !== "none") {
+		const chars = [...displayText];
+		const colors = require_effects_shimmer.frameColors(require_effects_shimmer.configToSpec({
+			color: shimmerColor,
+			dir: shimmer.direction,
+			speed: shimmer.speed
+		}, chars.length), chars.length, shimmer.frame);
+		shimmer.frame++;
+		return require_effects_shimmer_terminal.colorsToAnsi(displayText, colors);
+	}
+	return displayText;
+}
+/**
+* Parse the shimmer option (object or direction string) into a `ShimmerInfo`.
+*
+* @param shimmer - The `shimmer` option value.
+*
+* @returns Parsed shimmer state, or undefined when shimmer is disabled.
+*/
+function parseShimmerOption(shimmer) {
+	if (!shimmer) return;
+	let shimmerDir;
+	let shimmerColor;
+	let shimmerSpeed = 1 / 3;
+	if (typeof shimmer === "string") {
+		shimmerDir = shimmer;
+		shimmerColor = require_spinner_format.COLOR_INHERIT;
+	} else {
+		const shimmerConfig = {
+			__proto__: null,
+			...shimmer
+		};
+		shimmerDir = shimmerConfig.dir ?? "ltr";
+		shimmerColor = shimmerConfig.color ?? "inherit";
+		shimmerSpeed = shimmerConfig.speed ?? 1 / 3;
+	}
+	return {
+		__proto__: null,
+		color: shimmerColor,
+		direction: shimmerDir,
+		speed: shimmerSpeed,
+		frame: 0
+	};
+}
+/**
+* Resolve the spinner's RGB color from options and the active theme. Validates
+* RGB tuples and falls back to the theme's primary color.
+*
+* @param opts - Normalized spinner options.
+*
+* @returns Resolved RGB color tuple.
+*/
+function resolveSpinnerColorRgb(opts) {
+	let theme = require_themes_context.getTheme();
+	if (opts.theme) if (typeof opts.theme === "string") theme = require_themes_themes.THEMES[opts.theme] ?? theme;
+	else theme = opts.theme;
+	let defaultColor = theme.colors.primary;
+	if (theme.effects?.spinner?.color) {
+		const resolved = require_themes_resolve.resolveColor(theme.effects.spinner.color, theme.colors);
+		if (resolved === "inherit" || require_primordials_array.ArrayIsArray(resolved[0])) defaultColor = theme.colors.primary;
+		else defaultColor = resolved;
+	}
+	const spinnerColor = opts.color ?? defaultColor;
+	if (require_colors_convert.isRgbTuple(spinnerColor) && (spinnerColor.length !== 3 || !spinnerColor.every((n) => typeof n === "number" && n >= 0 && n <= 255))) throw new require_primordials_error.TypeErrorCtor("RGB color must be an array of 3 numbers between 0 and 255");
+	return require_colors_convert.toRgb(spinnerColor);
+}
+
+//#endregion
+exports.applyShimmer = applyShimmer;
+exports.parseShimmerOption = parseShimmerOption;
+exports.resolveSpinnerColorRgb = resolveSpinnerColorRgb;

package/dist/spinner/spinner-shimmer-methods.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Shimmer-configuration methods for the Socket `Spinner` class, split out
+ *   of `create-spinner-class.ts` to keep that module under the file-size cap.
+ *   The methods read and write the spinner's shimmer state through well-known
+ *   symbols (`getShimmerSymbol`, `setShimmerSymbol`, `getSavedShimmerSymbol`,
+ *   `setSavedShimmerSymbol`, `updateTextSymbol`) the class exposes, so they
+ *   share the same private state without crossing the private-field boundary.
+ *   `installShimmerMethods()` defines them on the prototype after the class is
+ *   built.
+ */
+import type { ShimmerInfo, SpinnerInstance } from './types';
+/**
+ * Well-known symbol the spinner class exposes to read its current shimmer
+ * state.
+ */
+export declare const getShimmerSymbol: unique symbol;
+/**
+ * Well-known symbol the spinner class exposes to replace its current shimmer
+ * state.
+ */
+export declare const setShimmerSymbol: unique symbol;
+/**
+ * Well-known symbol the spinner class exposes to read the saved shimmer config
+ * that `enableShimmer()` restores from.
+ */
+export declare const getSavedShimmerSymbol: unique symbol;
+/**
+ * Well-known symbol the spinner class exposes to replace the saved shimmer
+ * config.
+ */
+export declare const setSavedShimmerSymbol: unique symbol;
+/**
+ * Well-known symbol the spinner class exposes for its `#updateSpinnerText`
+ * helper so the shimmer methods can trigger a re-render after a state change.
+ */
+export declare const updateTextSymbol: unique symbol;
+/**
+ * Runtime shape of the spinner instance the shimmer methods operate on.
+ */
+export type ShimmerHost = SpinnerInstance & {
+    [getShimmerSymbol]: () => ShimmerInfo | undefined;
+    [setShimmerSymbol]: (value: ShimmerInfo | undefined) => void;
+    [getSavedShimmerSymbol]: () => ShimmerInfo | undefined;
+    [setSavedShimmerSymbol]: (value: ShimmerInfo | undefined) => void;
+    [updateTextSymbol]: () => void;
+};
+/**
+ * Install the shimmer-configuration methods + `shimmerState` getter onto the
+ * spinner prototype. The methods reach the spinner's private shimmer state
+ * through the well-known symbols the class exposes.
+ *
+ * @param proto - The spinner class prototype to augment.
+ */
+export declare function installShimmerMethods(proto: object): void;

package/dist/spinner/spinner-shimmer-methods.js

@@ -0,0 +1,143 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_spinner_format = require('./format.js');
+
+//#region src/spinner/spinner-shimmer-methods.ts
+/**
+* Well-known symbol the spinner class exposes to read its current shimmer
+* state.
+*/
+const getShimmerSymbol = Symbol.for("socket.spinner.getShimmer");
+/**
+* Well-known symbol the spinner class exposes to replace its current shimmer
+* state.
+*/
+const setShimmerSymbol = Symbol.for("socket.spinner.setShimmer");
+/**
+* Well-known symbol the spinner class exposes to read the saved shimmer config
+* that `enableShimmer()` restores from.
+*/
+const getSavedShimmerSymbol = Symbol.for("socket.spinner.getSavedShimmer");
+/**
+* Well-known symbol the spinner class exposes to replace the saved shimmer
+* config.
+*/
+const setSavedShimmerSymbol = Symbol.for("socket.spinner.setSavedShimmer");
+/**
+* Well-known symbol the spinner class exposes for its `#updateSpinnerText`
+* helper so the shimmer methods can trigger a re-render after a state change.
+*/
+const updateTextSymbol = Symbol.for("socket.spinner.updateText");
+/**
+* Install the shimmer-configuration methods + `shimmerState` getter onto the
+* spinner prototype. The methods reach the spinner's private shimmer state
+* through the well-known symbols the class exposes.
+*
+* @param proto - The spinner class prototype to augment.
+*/
+function installShimmerMethods(proto) {
+	const target = proto;
+	function shimmerState() {
+		const shimmer = this[getShimmerSymbol]();
+		if (!shimmer) return;
+		return {
+			__proto__: null,
+			color: shimmer.color,
+			direction: shimmer.direction,
+			speed: shimmer.speed,
+			frame: shimmer.frame
+		};
+	}
+	function disableShimmer() {
+		this[setShimmerSymbol](void 0);
+		this[updateTextSymbol]();
+		return this;
+	}
+	function enableShimmer() {
+		const saved = this[getSavedShimmerSymbol]();
+		if (saved) this[setShimmerSymbol]({
+			...saved,
+			frame: 0
+		});
+		else {
+			const next = {
+				__proto__: null,
+				color: require_spinner_format.COLOR_INHERIT,
+				direction: "ltr",
+				speed: 1 / 3,
+				frame: 0
+			};
+			this[setShimmerSymbol](next);
+			this[setSavedShimmerSymbol](next);
+		}
+		this[updateTextSymbol]();
+		return this;
+	}
+	function setShimmer(config) {
+		const next = {
+			__proto__: null,
+			color: config.color ?? "inherit",
+			direction: config.dir ?? "ltr",
+			speed: config.speed ?? 1 / 3,
+			frame: 0
+		};
+		this[setShimmerSymbol](next);
+		this[setSavedShimmerSymbol](next);
+		this[updateTextSymbol]();
+		return this;
+	}
+	function updateShimmer(config) {
+		/* c8 ignore start - each partial-config field branch fires only when caller updates that field; shimmer-state cascade covers three init paths */
+		const partialConfig = {
+			__proto__: null,
+			...config
+		};
+		const update = { __proto__: null };
+		if (partialConfig.color !== void 0) update.color = partialConfig.color;
+		if (partialConfig.dir !== void 0) update.direction = partialConfig.dir;
+		if (partialConfig.speed !== void 0) update.speed = partialConfig.speed;
+		const shimmer = this[getShimmerSymbol]();
+		const saved = this[getSavedShimmerSymbol]();
+		let next;
+		if (shimmer) next = {
+			...shimmer,
+			...update
+		};
+		else if (saved) next = {
+			...saved,
+			...update,
+			frame: 0
+		};
+		else next = {
+			__proto__: null,
+			color: require_spinner_format.COLOR_INHERIT,
+			direction: "ltr",
+			speed: 1 / 3,
+			frame: 0,
+			...update
+		};
+		this[setShimmerSymbol](next);
+		this[setSavedShimmerSymbol](next);
+		this[updateTextSymbol]();
+		return this;
+		/* c8 ignore stop */
+	}
+	Object.defineProperty(target, "shimmerState", {
+		configurable: true,
+		enumerable: false,
+		get: shimmerState
+	});
+	target["disableShimmer"] = disableShimmer;
+	target["enableShimmer"] = enableShimmer;
+	target["setShimmer"] = setShimmer;
+	target["updateShimmer"] = updateShimmer;
+}
+
+//#endregion
+exports.getSavedShimmerSymbol = getSavedShimmerSymbol;
+exports.getShimmerSymbol = getShimmerSymbol;
+exports.installShimmerMethods = installShimmerMethods;
+exports.setSavedShimmerSymbol = setSavedShimmerSymbol;
+exports.setShimmerSymbol = setShimmerSymbol;
+exports.updateTextSymbol = updateTextSymbol;

package/dist/spinner/spinner-status-methods.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Status-presentation methods for the Socket `Spinner` class, split out
+ *   of `create-spinner-class.ts` to keep that module under the file-size cap.
+ *   Each method is a thin delegation to one of the two internal helpers the
+ *   class exposes via well-known symbols (`applyStatusSymbol`,
+ *   `showStatusSymbol`); `installStatusMethods()` defines them on the spinner
+ *   prototype after the class is built so they share the same private state.
+ */
+import type { SpinnerLogger } from './create-spinner-class';
+import type { SpinnerInstance, SymbolType } from './types';
+/**
+ * Well-known symbol the spinner class uses to expose its `#apply` helper so the
+ * status methods in this module can drive a yocto-spinner method + logger
+ * update without reaching into a private field across the file boundary.
+ */
+export declare const applyStatusSymbol: unique symbol;
+/**
+ * Well-known symbol the spinner class uses to expose its
+ * `#showStatusAndKeepSpinning` helper so the status methods here can emit a
+ * symbol-prefixed status line without stopping the spinner.
+ */
+export declare const showStatusSymbol: unique symbol;
+/**
+ * Runtime shape of the spinner instance the status methods operate on. Only the
+ * two symbol-keyed helpers are needed; everything else is reached through the
+ * module-scope `logger`.
+ */
+export type StatusHost = SpinnerInstance & {
+    [applyStatusSymbol]: (methodName: string, args: unknown[]) => SpinnerInstance;
+    [showStatusSymbol]: (symbolType: SymbolType, args: unknown[]) => SpinnerInstance;
+};
+/**
+ * Install the status-presentation methods onto the spinner prototype. The
+ * methods close over `logger` for the stdout/stderr writes and reach the
+ * spinner's private helpers through the two well-known symbols.
+ *
+ * @param proto - The spinner class prototype to augment.
+ * @param logger - Default logger used for status output.
+ */
+export declare function installStatusMethods(proto: object, logger: SpinnerLogger): void;

package/dist/spinner/spinner-status-methods.js

@@ -0,0 +1,133 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_logger_symbols = require('../logger/symbols.js');
+const require_spinner_format = require('./format.js');
+const require_debug_namespace = require('../debug/namespace.js');
+
+//#region src/spinner/spinner-status-methods.ts
+/**
+* @file Status-presentation methods for the Socket `Spinner` class, split out
+*   of `create-spinner-class.ts` to keep that module under the file-size cap.
+*   Each method is a thin delegation to one of the two internal helpers the
+*   class exposes via well-known symbols (`applyStatusSymbol`,
+*   `showStatusSymbol`); `installStatusMethods()` defines them on the spinner
+*   prototype after the class is built so they share the same private state.
+*/
+/**
+* Well-known symbol the spinner class uses to expose its `#apply` helper so the
+* status methods in this module can drive a yocto-spinner method + logger
+* update without reaching into a private field across the file boundary.
+*/
+const applyStatusSymbol = Symbol.for("socket.spinner.applyStatus");
+/**
+* Well-known symbol the spinner class uses to expose its
+* `#showStatusAndKeepSpinning` helper so the status methods here can emit a
+* symbol-prefixed status line without stopping the spinner.
+*/
+const showStatusSymbol = Symbol.for("socket.spinner.showStatus");
+/**
+* Install the status-presentation methods onto the spinner prototype. The
+* methods close over `logger` for the stdout/stderr writes and reach the
+* spinner's private helpers through the two well-known symbols.
+*
+* @param proto - The spinner class prototype to augment.
+* @param logger - Default logger used for status output.
+*/
+function installStatusMethods(proto, logger) {
+	const target = proto;
+	function debug(text, ...extras) {
+		if (require_debug_namespace.isDebug()) return this[showStatusSymbol]("info", [text, ...extras]);
+		return this;
+	}
+	function debugAndStop(text, ...extras) {
+		if (require_debug_namespace.isDebug()) return this[applyStatusSymbol]("info", [text, ...extras]);
+		return this;
+	}
+	function done(text, ...extras) {
+		return this[showStatusSymbol]("success", [text, ...extras]);
+	}
+	function doneAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("success", [text, ...extras]);
+	}
+	function fail(text, ...extras) {
+		return this[showStatusSymbol]("fail", [text, ...extras]);
+	}
+	function failAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("error", [text, ...extras]);
+	}
+	function info(text, ...extras) {
+		return this[showStatusSymbol]("info", [text, ...extras]);
+	}
+	function infoAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("info", [text, ...extras]);
+	}
+	function log(...args) {
+		logger.log(...args);
+		return this;
+	}
+	function logAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("stop", [text, ...extras]);
+	}
+	function skip(text, ...extras) {
+		return this[showStatusSymbol]("skip", [text, ...extras]);
+	}
+	function skipAndStop(text, ...extras) {
+		this[applyStatusSymbol]("stop", []);
+		const normalized = require_spinner_format.normalizeText(text);
+		/* c8 ignore start - empty-text no-op fires when text is undefined or whitespace-only */
+		if (normalized) logger.error(`${require_logger_symbols.LOG_SYMBOLS["skip"]} ${normalized}`, ...extras);
+		return this;
+		/* c8 ignore stop */
+	}
+	function step(text, ...extras) {
+		/* c8 ignore start - text-omitted no-op arm fires when caller invokes step() bare */
+		if (typeof text === "string") {
+			logger.error("");
+			logger.error(text, ...extras);
+		}
+		return this;
+		/* c8 ignore stop */
+	}
+	function substep(text, ...extras) {
+		/* c8 ignore start - text-omitted no-op arm fires when caller invokes substep() bare */
+		if (typeof text === "string") logger.error(`  ${text}`, ...extras);
+		return this;
+		/* c8 ignore stop */
+	}
+	function success(text, ...extras) {
+		return this[showStatusSymbol]("success", [text, ...extras]);
+	}
+	function successAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("success", [text, ...extras]);
+	}
+	function warn(text, ...extras) {
+		return this[showStatusSymbol]("warn", [text, ...extras]);
+	}
+	function warnAndStop(text, ...extras) {
+		return this[applyStatusSymbol]("warning", [text, ...extras]);
+	}
+	target["debug"] = debug;
+	target["debugAndStop"] = debugAndStop;
+	target["done"] = done;
+	target["doneAndStop"] = doneAndStop;
+	target["fail"] = fail;
+	target["failAndStop"] = failAndStop;
+	target["info"] = info;
+	target["infoAndStop"] = infoAndStop;
+	target["log"] = log;
+	target["logAndStop"] = logAndStop;
+	target["skip"] = skip;
+	target["skipAndStop"] = skipAndStop;
+	target["step"] = step;
+	target["substep"] = substep;
+	target["success"] = success;
+	target["successAndStop"] = successAndStop;
+	target["warn"] = warn;
+	target["warnAndStop"] = warnAndStop;
+}
+
+//#endregion
+exports.applyStatusSymbol = applyStatusSymbol;
+exports.installStatusMethods = installStatusMethods;
+exports.showStatusSymbol = showStatusSymbol;

package/dist/spinner/spinner.d.ts

@@ -1,12 +1,11 @@
 /**
- * @file Spinner factory — builds the lazy-init `Spinner` class that wraps
+ * @file Spinner factory — lazily builds the Socket `Spinner` class that wraps
  *   `yocto-spinner` with Socket-specific behaviors (custom RGB color pipeline,
  *   shimmer, progress bar, indented step messages, status methods that don't
  *   auto-stop, *AndStop variants that auto-clear). The class graph is
- *   constructed inside the factory body so the `super()` call binds against the
- *   live `YoctoSpinner` constructor; splitting it further would require
- *   exposing the parent class as a module-level dependency, which breaks the
- *   lazy-init guarantee.
+ *   constructed by `createSpinnerClass()` so the `super()` call binds against
+ *   the live `YoctoSpinner` constructor resolved here; building it lazily keeps
+ *   the module free of side effects at import time.
  */
 import type { SpinnerInstance, SpinnerOptions } from './types';
 /**