@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/smol/vfs.js

@@ -0,0 +1,43 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 vfs_exports = {};
+__export(vfs_exports, {
+  getSmolVfs: () => getSmolVfs
+});
+module.exports = __toCommonJS(vfs_exports);
+var import_module = require("../node/module");
+let _smolVfs;
+let _smolVfsProbed = false;
+// @__NO_SIDE_EFFECTS__
+function getSmolVfs() {
+  if (!_smolVfsProbed) {
+    _smolVfsProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-vfs")) {
+      const binding = require("node:smol-vfs");
+      _smolVfs = binding.getSmolVfs();
+    }
+  }
+  return _smolVfs;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSmolVfs
+});

package/dist/sorts/_internal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Private internals for `sorts/*` modules — lazy module accessors for
+ *   fast-sort + semver, and the cached Intl.Collator instances. Used by the
+ *   locale / natural / semver comparison entrypoints.
+ */
+import type * as fastSortType from '../external/fast-sort';
+import type * as semverType from '../external/semver';
+export declare function getFastSort(): typeof fastSortType;
+export declare function getSemver(): typeof semverType;

package/dist/sorts/_internal.js

@@ -0,0 +1,47 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 internal_exports = {};
+__export(internal_exports, {
+  getFastSort: () => getFastSort,
+  getSemver: () => getSemver
+});
+module.exports = __toCommonJS(internal_exports);
+let _fastSort;
+let _semver;
+// @__NO_SIDE_EFFECTS__
+function getFastSort() {
+  if (_fastSort === void 0) {
+    _fastSort = require("../external/fast-sort.js");
+  }
+  return _fastSort;
+}
+// @__NO_SIDE_EFFECTS__
+function getSemver() {
+  if (_semver === void 0) {
+    _semver = require("../external/semver.js");
+  }
+  return _semver;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getFastSort,
+  getSemver
+});

package/dist/sorts/natural.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Locale-aware + numeric-aware comparison via `Intl.Collator`, plus the
+ *   `naturalSorter` helper that wires the fast-sort engine to the natural
+ *   comparator. Collator instances are lazy-created and cached because `new
+ *   Intl.Collator()` is 10-14ms in Node — too expensive to call
+ *   per-comparison.
+ */
+import type { FastSortFunction } from './types';
+/**
+ * Compare two strings using locale-aware comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   localeCompare('a', 'b') // -1
+ *   localeCompare('b', 'a') // 1
+ *   localeCompare('a', 'a') // 0
+ *   ```
+ */
+export declare function localeCompare(x: string, y: string): number;
+/**
+ * Compare two strings using natural sorting (numeric-aware, case-insensitive).
+ *
+ * @example
+ *   ;```typescript
+ *   naturalCompare('file2', 'file10') // negative (file2 before file10)
+ *   naturalCompare('img10', 'img2') // positive (img10 after img2)
+ *   ```
+ */
+export declare function naturalCompare(x: string, y: string): number;
+/**
+ * Sort an array using natural comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   naturalSorter(['file10', 'file2', 'file1']).asc()
+ *   // ['file1', 'file2', 'file10']
+ *   ```
+ */
+export declare function naturalSorter<T>(arrayToSort: T[]): ReturnType<FastSortFunction>;

package/dist/{sorts.js → sorts/natural.js}

@@ -18,52 +18,17 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var sorts_exports = {};
-__export(sorts_exports, {
-  compareSemver: () => compareSemver,
-  compareStr: () => compareStr,
+var natural_exports = {};
+__export(natural_exports, {
   localeCompare: () => localeCompare,
   naturalCompare: () => naturalCompare,
   naturalSorter: () => naturalSorter
 });
-module.exports = __toCommonJS(sorts_exports);
-let _fastSort;
+module.exports = __toCommonJS(natural_exports);
+var import_internal = require("./_internal");
 let _localeCompare;
 let _naturalCompare;
 let _naturalSorter;
-let _semver;
-function getFastSort() {
-  if (_fastSort === void 0) {
-    _fastSort = require("./external/fast-sort.js");
-  }
-  return _fastSort;
-}
-function getSemver() {
-  if (_semver === void 0) {
-    _semver = require("./external/semver.js");
-  }
-  return _semver;
-}
-// @__NO_SIDE_EFFECTS__
-function compareSemver(a, b) {
-  const semver = getSemver();
-  const validA = semver.valid(a);
-  const validB = semver.valid(b);
-  if (!validA && !validB) {
-    return 0;
-  }
-  if (!validA) {
-    return -1;
-  }
-  if (!validB) {
-    return 1;
-  }
-  return semver.compare(a, b);
-}
-// @__NO_SIDE_EFFECTS__
-function compareStr(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
 // @__NO_SIDE_EFFECTS__
 function localeCompare(x, y) {
   if (_localeCompare === void 0) {
@@ -94,7 +59,7 @@ function naturalCompare(x, y) {
 // @__NO_SIDE_EFFECTS__
 function naturalSorter(arrayToSort) {
   if (_naturalSorter === void 0) {
-    const fastSort = getFastSort();
+    const fastSort = (0, import_internal.getFastSort)();
     _naturalSorter = fastSort.createNewSortInstance({
       comparer: naturalCompare
     });
@@ -103,8 +68,6 @@ function naturalSorter(arrayToSort) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  compareSemver,
-  compareStr,
   localeCompare,
   naturalCompare,
   naturalSorter

package/dist/sorts/semver.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Semver-aware string comparison. Wraps the vendored `external/semver`
+ *   accessor so callers don't have to thread the lazy-load themselves.
+ */
+/**
+ * Compare semantic versions.
+ *
+ * @example
+ *   ;```typescript
+ *   compareSemver('1.0.0', '2.0.0') // -1
+ *   compareSemver('2.0.0', '1.0.0') // 1
+ *   compareSemver('1.0.0', '1.0.0') // 0
+ *   ```
+ */
+export declare function compareSemver(a: string, b: string): number;

package/dist/sorts/semver.js

@@ -0,0 +1,46 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 semver_exports = {};
+__export(semver_exports, {
+  compareSemver: () => compareSemver
+});
+module.exports = __toCommonJS(semver_exports);
+var import_internal = require("./_internal");
+// @__NO_SIDE_EFFECTS__
+function compareSemver(a, b) {
+  const semver = (0, import_internal.getSemver)();
+  const validA = semver.valid(a);
+  const validB = semver.valid(b);
+  if (!validA && !validB) {
+    return 0;
+  }
+  if (!validA) {
+    return -1;
+  }
+  if (!validB) {
+    return 1;
+  }
+  return semver.compare(a, b);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compareSemver
+});

package/dist/sorts/strings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Plain string comparison. The straight-ASCII three-way compare, no
+ *   locale/numeric awareness — use `localeCompare` / `naturalCompare` from the
+ *   sibling files when those matter.
+ */
+/**
+ * Simple string comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   compareStr('a', 'b') // -1
+ *   compareStr('b', 'a') // 1
+ *   compareStr('a', 'a') // 0
+ *   ```
+ */
+export declare function compareStr(a: string, b: string): number;

package/dist/sorts/strings.js

@@ -0,0 +1,33 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+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 strings_exports = {};
+__export(strings_exports, {
+  compareStr: () => compareStr
+});
+module.exports = __toCommonJS(strings_exports);
+// @__NO_SIDE_EFFECTS__
+function compareStr(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compareStr
+});

package/dist/sorts/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Public type surface for `sorts/*` modules — the `FastSortFunction`
+ *   shape returned by `naturalSorter`. Pure types, no runtime side effects.
+ */
+import type * as fastSortType from '../external/fast-sort';
+export type FastSortFunction = ReturnType<typeof import('fast-sort').createNewSortInstance>;
+export type { fastSortType };

package/dist/sorts/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/spinner/default.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file Spinner-style registry — exposes the union of the standard
+ *   `cli-spinners` collection and Socket's custom `socket` pulse animation,
+ *   plus a lazy default-spinner singleton. The registry itself is built once
+ *   and memoized; `getDefaultSpinner()` defers `Spinner()` construction until
+ *   first call so module initialization stays cheap.
+ */
+import type { SpinnerInstance, SpinnerStyle } from './types';
+/**
+ * Get available CLI spinner styles or a specific style by name. Extends the
+ * standard cli-spinners collection with Socket custom spinners.
+ *
+ * Custom spinners: - `socket` (default): Socket pulse animation with sparkles
+ * and lightning.
+ *
+ * @example
+ *   ;```ts
+ *   // Get all available spinner styles
+ *   const allSpinners = getCliSpinners()
+ *
+ *   // Get specific style
+ *   const socketStyle = getCliSpinners('socket')
+ *   const dotsStyle = getCliSpinners('dots')
+ *   ```
+ *
+ * @param styleName - Optional name of specific spinner style to retrieve.
+ *
+ * @returns Specific spinner style if name provided, all styles if omitted,
+ *   `undefined` if style not found.
+ *
+ * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
+ */
+export declare function getCliSpinners(styleName?: string | undefined): SpinnerStyle | Record<string, SpinnerStyle> | undefined;
+/**
+ * Get the default spinner instance. Lazily creates the spinner to avoid
+ * circular dependencies during module initialization. Reuses the same instance
+ * across calls.
+ *
+ * @example
+ *   ;```ts
+ *   import { getDefaultSpinner } from '@socketsecurity/lib/spinner/default'
+ *
+ *   const spinner = getDefaultSpinner()
+ *   spinner.start('Loading…')
+ *   ```
+ *
+ * @returns Shared default spinner instance
+ */
+export declare function getDefaultSpinner(): SpinnerInstance;

package/dist/spinner/default.js

@@ -0,0 +1,70 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var default_exports = {};
+__export(default_exports, {
+  getCliSpinners: () => getCliSpinners,
+  getDefaultSpinner: () => getDefaultSpinner
+});
+module.exports = __toCommonJS(default_exports);
+var import_pulse_frames = require("../effects/pulse-frames");
+var import_yocto_spinner = __toESM(require("../external/@socketregistry/yocto-spinner"));
+var import_predicates = require("../objects/predicates");
+var import_spinner = require("./spinner");
+let _cliSpinners;
+let _spinner;
+// @__NO_SIDE_EFFECTS__
+function getCliSpinners(styleName) {
+  if (_cliSpinners === void 0) {
+    const YoctoCtor = import_yocto_spinner.default;
+    const tempInstance = YoctoCtor({});
+    const YoctoSpinnerClass = tempInstance.constructor;
+    _cliSpinners = {
+      __proto__: null,
+      ...YoctoSpinnerClass.spinners,
+      socket: (0, import_pulse_frames.generateSocketSpinnerFrames)()
+    };
+  }
+  if (typeof styleName === "string" && _cliSpinners) {
+    return (0, import_predicates.hasOwn)(_cliSpinners, styleName) ? _cliSpinners[styleName] : void 0;
+  }
+  return _cliSpinners;
+}
+function getDefaultSpinner() {
+  if (_spinner === void 0) {
+    _spinner = (0, import_spinner.Spinner)();
+  }
+  return _spinner;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getCliSpinners,
+  getDefaultSpinner
+});

package/dist/spinner/format.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file Stateless helpers shared by `spinner/*` modules — the `ciSpinner`
+ *   constant for non-interactive output, the `COLOR_INHERIT` sentinel for
+ *   shimmer color references, plus pure formatters (`desc`, `formatProgress`,
+ *   `normalizeText`, `renderProgressBar`) used by both the factory and the
+ *   `withSpinner*` wrappers.
+ */
+import type { ProgressInfo, SpinnerStyle } from './types';
+/**
+ * Sentinel value indicating the shimmer should track the spinner's current
+ * color rather than holding its own palette reference.
+ */
+export declare const COLOR_INHERIT = "inherit";
+/**
+ * Minimal spinner style for CI environments. Uses empty frame and max interval
+ * to effectively disable animation in CI.
+ */
+export declare const ciSpinner: SpinnerStyle;
+/**
+ * Create a property descriptor for defining non-enumerable properties. Used for
+ * adding aliased methods to the Spinner prototype.
+ *
+ * @param value - Value for the property.
+ *
+ * @returns Property descriptor object
+ */
+export declare function desc(value: unknown): {
+    __proto__: null;
+    configurable: boolean;
+    value: unknown;
+    writable: boolean;
+};
+/**
+ * Format progress information as a visual progress bar with percentage and
+ * count.
+ *
+ * @example
+ *   '███████░░░░░░░░░░░░░ 35% (7/20 files)'
+ *
+ * @param progress - Progress tracking information.
+ *
+ * @returns Formatted string with colored progress bar, percentage, and count
+ */
+export declare function formatProgress(progress: ProgressInfo): string;
+/**
+ * Normalize text input by trimming leading whitespace. Non-string values are
+ * converted to empty string.
+ *
+ * @param value - Text to normalize.
+ *
+ * @returns Normalized string with leading whitespace removed
+ */
+export declare function normalizeText(value: unknown): string;
+/**
+ * Render a progress bar using block characters (█ for filled, ░ for empty).
+ *
+ * @default width=20
+ *
+ * @param percentage - Progress percentage (0-100)
+ * @param width - Total width of progress bar in characters.
+ *
+ * @returns Colored progress bar string
+ */
+export declare function renderProgressBar(percentage: number, width?: number): string;

package/dist/spinner/format.js

@@ -0,0 +1,83 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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, desc2) => {
+  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: !(desc2 = __getOwnPropDesc(from, key)) || desc2.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var format_exports = {};
+__export(format_exports, {
+  COLOR_INHERIT: () => COLOR_INHERIT,
+  ciSpinner: () => ciSpinner,
+  desc: () => desc,
+  formatProgress: () => formatProgress,
+  normalizeText: () => normalizeText,
+  renderProgressBar: () => renderProgressBar
+});
+module.exports = __toCommonJS(format_exports);
+var import_yoctocolors_cjs = __toESM(require("../external/yoctocolors-cjs"));
+var import_math = require("../primordials/math");
+const COLOR_INHERIT = "inherit";
+const ciSpinner = {
+  frames: [""],
+  interval: 2147483647
+};
+function desc(value) {
+  return {
+    __proto__: null,
+    configurable: true,
+    value,
+    writable: true
+  };
+}
+function formatProgress(progress) {
+  const { current, total, unit } = progress;
+  const percentage = total === 0 ? 0 : (0, import_math.MathRound)(current / total * 100);
+  const bar = renderProgressBar(percentage);
+  const count = unit ? `${current}/${total} ${unit}` : `${current}/${total}`;
+  return `${bar} ${percentage}% (${count})`;
+}
+function normalizeText(value) {
+  return typeof value === "string" ? value.trimStart() : "";
+}
+function renderProgressBar(percentage, width = 20) {
+  const filled = (0, import_math.MathMax)(
+    0,
+    Math.min(width, Math.round(percentage / 100 * width))
+  );
+  const empty = (0, import_math.MathMax)(0, width - filled);
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+  return import_yoctocolors_cjs.default.cyan(bar);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  COLOR_INHERIT,
+  ciSpinner,
+  desc,
+  formatProgress,
+  normalizeText,
+  renderProgressBar
+});

package/dist/spinner/spinner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Spinner factory — builds the lazy-init `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.
+ */
+import type { SpinnerInstance, SpinnerOptions } from './types';
+/**
+ * Create a spinner instance for displaying loading indicators. Provides an
+ * animated CLI spinner with status messages, progress tracking, and shimmer
+ * effects.
+ *
+ * AUTO-CLEAR BEHAVIOR:
+ *
+ * - All *AndStop() methods AUTO-CLEAR the spinner line via yocto-spinner.stop()
+ *   Examples: `doneAndStop()`, `successAndStop()`, `failAndStop()`, etc.
+ * - Methods WITHOUT "AndStop" do NOT clear (spinner keeps spinning) Examples:
+ *   `done()`, `success()`, `fail()`, etc.
+ *
+ * STREAM USAGE:
+ *
+ * - Spinner animation: stderr (yocto-spinner default)
+ * - Status methods (done, success, fail, info, warn, step, substep): stderr
+ * - Data methods (`log()`): stdout
+ *
+ * COMPARISON WITH LOGGER:
+ *
+ * - `logger.done()` does NOT auto-clear (requires manual `logger.clearLine()`)
+ * - `spinner.doneAndStop()` DOES auto-clear (built into yocto-spinner.stop())
+ * - Pattern: `logger.clearLine().done()` vs `spinner.doneAndStop()`
+ *
+ * @param options - Configuration options for the spinner.
+ *
+ * @returns New spinner instance
+ */
+export declare function Spinner(options?: SpinnerOptions | undefined): SpinnerInstance;