@socketsecurity/lib 3.0.1 → 3.0.3

package/dist/spinner.js

@@ -1,3 +1,963 @@
 /* Socket Lib - Built with esbuild */
-var q=Object.create;var x=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var G=Object.getOwnPropertyNames;var M=Object.getPrototypeOf,z=Object.prototype.hasOwnProperty;var F=(r,s)=>{for(var u in s)x(r,u,{get:s[u],enumerable:!0})},I=(r,s,u,t)=>{if(s&&typeof s=="object"||typeof s=="function")for(let i of G(s))!z.call(r,i)&&i!==u&&x(r,i,{get:()=>s[i],enumerable:!(t=Y(s,i))||t.enumerable});return r};var E=(r,s,u)=>(u=r!=null?q(M(r)):{},I(s||!r||!r.__esModule?x(u,"default",{value:r,enumerable:!0}):u,r)),N=r=>I(x({},"__esModule",{value:!0}),r);var Z={};F(Z,{Spinner:()=>L,ciSpinner:()=>W,getCliSpinners:()=>v,getDefaultSpinner:()=>U,toRgb:()=>S,withSpinner:()=>J,withSpinnerRestore:()=>Q,withSpinnerSync:()=>X});module.exports=N(Z);var O=require("#env/ci"),D=require("./effects/pulse-frames"),p=require("./effects/text-shimmer"),T=E(require("./external/@socketregistry/yocto-spinner")),P=require("./objects"),_=require("./strings"),B=require("./themes/context"),$=require("./themes/utils");const j={__proto__:null,black:[0,0,0],blue:[0,0,255],blueBright:[100,149,237],cyan:[0,255,255],cyanBright:[0,255,255],gray:[128,128,128],green:[0,128,0],greenBright:[0,255,0],magenta:[255,0,255],magentaBright:[255,105,180],red:[255,0,0],redBright:[255,69,0],white:[255,255,255],whiteBright:[255,255,255],yellow:[255,255,0],yellowBright:[255,255,153]};function C(r){return Array.isArray(r)}function S(r){return C(r)?r:j[r]}const W={frames:[""],interval:2147483647};function b(r){return{__proto__:null,configurable:!0,value:r,writable:!0}}function R(r){return typeof r=="string"?r.trimStart():""}function H(r){const{current:s,total:u,unit:t}=r,i=Math.round(s/u*100),e=K(i),n=t?`${s}/${u} ${t}`:`${s}/${u}`;return`${e} ${i}% (${n})`}function K(r,s=20){const u=Math.round(r/100*s),t=s-u,i="\u2588".repeat(u)+"\u2591".repeat(t);return require("./external/yoctocolors-cjs").cyan(i)}let y;function v(r){return y===void 0&&(y={__proto__:null,...(0,T.default)({}).constructor.spinners,socket:(0,D.generateSocketSpinnerFrames)()}),typeof r=="string"&&y?(0,P.hasOwn)(y,r)?y[r]:void 0:y}let h,A;function L(r){if(h===void 0){const t=(0,T.default)({}).constructor;h=class extends t{#s="";#o="";#e;#n;#r;constructor(e){const n={__proto__:null,...e},o=(0,B.getTheme)();let l=o.colors.primary;if(o.effects?.spinner?.color){const d=(0,$.resolveColor)(o.effects.spinner.color,o.colors);d==="inherit"||Array.isArray(d[0])?l=o.colors.primary:l=d}const f=n.color??l;if(C(f)&&(f.length!==3||!f.every(d=>typeof d=="number"&&d>=0&&d<=255)))throw new TypeError("RGB color must be an array of 3 numbers between 0 and 255");const c=S(f);let g;if(n.shimmer){let d,m,a=.3333333333333333;if(typeof n.shimmer=="string")d=n.shimmer;else{const w={__proto__:null,...n.shimmer};d=w.dir??p.DIR_LTR,m=w.color??p.COLOR_INHERIT,a=w.speed??1/3}g={__proto__:null,color:m===void 0?p.COLOR_INHERIT:m,currentDir:p.DIR_LTR,mode:d,speed:a,step:0}}super({signal:require("#constants/process").getAbortSignal(),...n,color:c,onRenderFrame:(d,m,a)=>{const V=(0,_.stringWidth)(d)===1?"  ":" ";return d?`${a(d)}${V}${m}`:m},onFrameUpdate:g?()=>{this.#s&&(super.text=this.#d())}:void 0}),this.#n=g,this.#r=g}get color(){const e=super.color;return C(e)?e:S(e)}set color(e){super.color=C(e)?e:S(e)}get shimmerState(){if(this.#n)return{color:this.#n.color,currentDir:this.#n.currentDir,mode:this.#n.mode,speed:this.#n.speed,step:this.#n.step}}#i(e,n){let o,l=n.at(0);typeof l=="string"?o=n.slice(1):(o=n,l="");const f=this.isSpinning,c=R(l);super[e](c);const{getDefaultLogger:g,incLogCallCountSymbol:d,lastWasBlankSymbol:m}=require("./logger.js"),a=g();return e==="stop"?f&&c&&(a[m]((0,_.isBlankString)(c)),a[d]()):(a[m](!1),a[d]()),o.length&&(a.log(...o),a[m](!1)),this}#d(){let e=this.#s;if(this.#e){const n=H(this.#e);e=e?`${e} ${n}`:n}if(e&&this.#n){let n;this.#n.color===p.COLOR_INHERIT?n=this.color:Array.isArray(this.#n.color[0])?n=this.#n.color:n=S(this.#n.color),e=(0,p.applyShimmer)(e,this.#n,{color:n,direction:this.#n.mode})}return this.#o&&e&&(e=this.#o+e),e}#u(e,n){let o=n.at(0),l;typeof o=="string"?l=n.slice(1):(l=n,o="");const{LOG_SYMBOLS:f,getDefaultLogger:c}=require("./logger.js");return c().error(`${f[e]} ${o}`,...l),this}#t(){super.text=this.#d()}debug(e,...n){const{isDebug:o}=require("./debug.js");return o()?this.#u("info",[e,...n]):this}debugAndStop(e,...n){const{isDebug:o}=require("./debug.js");return o()?this.#i("info",[e,...n]):this}dedent(e){if(e===0)this.#o="";else{const n=e??2,o=Math.max(0,this.#o.length-n);this.#o=this.#o.slice(0,o)}return this.#t(),this}done(e,...n){return this.#u("success",[e,...n])}doneAndStop(e,...n){return this.#i("success",[e,...n])}fail(e,...n){return this.#u("fail",[e,...n])}failAndStop(e,...n){return this.#i("error",[e,...n])}indent(e){if(e===0)this.#o="";else{const n=e??2;this.#o+=" ".repeat(n)}return this.#t(),this}info(e,...n){return this.#u("info",[e,...n])}infoAndStop(e,...n){return this.#i("info",[e,...n])}log(...e){const{getDefaultLogger:n}=require("./logger.js");return n().log(...e),this}logAndStop(e,...n){return this.#i("stop",[e,...n])}progress=(e,n,o)=>(this.#e={__proto__:null,current:e,total:n,...o?{unit:o}:{}},this.#t(),this);progressStep(e=1){if(this.#e){const n=this.#e.current+e;this.#e={__proto__:null,current:Math.max(0,Math.min(n,this.#e.total)),total:this.#e.total,...this.#e.unit?{unit:this.#e.unit}:{}},this.#t()}return this}start(...e){if(e.length){const n=e.at(0),o=R(n);o?this.#s=o:(this.#s="",super.text="")}return this.#t(),this.#i("start",[])}step(e,...n){const{getDefaultLogger:o}=require("./logger.js");if(typeof e=="string"){const l=o();l.error(""),l.error(e,...n)}return this}substep(e,...n){if(typeof e=="string"){const{getDefaultLogger:o}=require("./logger.js");o().error(`  ${e}`,...n)}return this}stop(...e){this.#s="",this.#e=void 0,this.#n&&(this.#n.currentDir=p.DIR_LTR,this.#n.step=0);const n=this.#i("stop",e);return super.text="",n}success(e,...n){return this.#u("success",[e,...n])}successAndStop(e,...n){return this.#i("success",[e,...n])}text(e){return arguments.length===0?this.#s:(this.#s=e??"",this.#t(),this)}warn(e,...n){return this.#u("warn",[e,...n])}warnAndStop(e,...n){return this.#i("warning",[e,...n])}enableShimmer(){return this.#r?this.#n={...this.#r}:(this.#n={color:p.COLOR_INHERIT,currentDir:p.DIR_LTR,mode:p.DIR_LTR,speed:1/3,step:0},this.#r=this.#n),this.#t(),this}disableShimmer(){return this.#n=void 0,this.#t(),this}setShimmer(e){return this.#n={color:e.color,currentDir:p.DIR_LTR,mode:e.dir,speed:e.speed,step:0},this.#r=this.#n,this.#t(),this}updateShimmer(e){const n={__proto__:null,...e};return this.#n?(this.#n={...this.#n,...n.color!==void 0?{color:n.color}:{},...n.dir!==void 0?{mode:n.dir}:{},...n.speed!==void 0?{speed:n.speed}:{}},this.#r=this.#n):this.#r?(this.#n={...this.#r,...n.color!==void 0?{color:n.color}:{},...n.dir!==void 0?{mode:n.dir}:{},...n.speed!==void 0?{speed:n.speed}:{}},this.#r=this.#n):(this.#n={color:n.color??p.COLOR_INHERIT,currentDir:p.DIR_LTR,mode:n.dir??p.DIR_LTR,speed:n.speed??1/3,step:0},this.#r=this.#n),this.#t(),this}},Object.defineProperties(h.prototype,{error:b(h.prototype.fail),errorAndStop:b(h.prototype.failAndStop),warning:b(h.prototype.warn),warningAndStop:b(h.prototype.warnAndStop)}),A=(0,O.getCI)()?W:v("socket")}return new h({spinner:A,...r})}let k;function U(){return k===void 0&&(k=L()),k}async function J(r){const{message:s,operation:u,spinner:t,withOptions:i}={__proto__:null,...r};if(!t)return await u();const e=i?.color!==void 0?t.color:void 0,n=i?.shimmer!==void 0?t.shimmerState:void 0;i?.color!==void 0&&(t.color=S(i.color)),i?.shimmer!==void 0&&(typeof i.shimmer=="string"?t.updateShimmer({dir:i.shimmer}):t.setShimmer(i.shimmer)),t.start(s);try{return await u()}finally{t.stop(),e!==void 0&&(t.color=e),i?.shimmer!==void 0&&(n?t.setShimmer({color:n.color,dir:n.mode,speed:n.speed}):t.disableShimmer())}}async function Q(r){const{operation:s,spinner:u,wasSpinning:t}={__proto__:null,...r};try{return await s()}finally{u&&t&&u.start()}}function X(r){const{message:s,operation:u,spinner:t,withOptions:i}={__proto__:null,...r};if(!t)return u();const e=i?.color!==void 0?t.color:void 0,n=i?.shimmer!==void 0?t.shimmerState:void 0;i?.color!==void 0&&(t.color=S(i.color)),i?.shimmer!==void 0&&(typeof i.shimmer=="string"?t.updateShimmer({dir:i.shimmer}):t.setShimmer(i.shimmer)),t.start(s);try{return u()}finally{t.stop(),e!==void 0&&(t.color=e),i?.shimmer!==void 0&&(n?t.setShimmer({color:n.color,dir:n.mode,speed:n.speed}):t.disableShimmer())}}0&&(module.exports={Spinner,ciSpinner,getCliSpinners,getDefaultSpinner,toRgb,withSpinner,withSpinnerRestore,withSpinnerSync});
+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 spinner_exports = {};
+__export(spinner_exports, {
+  Spinner: () => Spinner,
+  ciSpinner: () => ciSpinner,
+  getCliSpinners: () => getCliSpinners,
+  getDefaultSpinner: () => getDefaultSpinner,
+  toRgb: () => toRgb,
+  withSpinner: () => withSpinner,
+  withSpinnerRestore: () => withSpinnerRestore,
+  withSpinnerSync: () => withSpinnerSync
+});
+module.exports = __toCommonJS(spinner_exports);
+var import_ci = require("#env/ci");
+var import_pulse_frames = require("./effects/pulse-frames");
+var import_text_shimmer = require("./effects/text-shimmer");
+var import_yocto_spinner = __toESM(require("./external/@socketregistry/yocto-spinner"));
+var import_objects = require("./objects");
+var import_strings = require("./strings");
+var import_context = require("./themes/context");
+var import_utils = require("./themes/utils");
+const colorToRgb = {
+  __proto__: null,
+  black: [0, 0, 0],
+  blue: [0, 0, 255],
+  blueBright: [100, 149, 237],
+  cyan: [0, 255, 255],
+  cyanBright: [0, 255, 255],
+  gray: [128, 128, 128],
+  green: [0, 128, 0],
+  greenBright: [0, 255, 0],
+  magenta: [255, 0, 255],
+  magentaBright: [255, 105, 180],
+  red: [255, 0, 0],
+  redBright: [255, 69, 0],
+  white: [255, 255, 255],
+  whiteBright: [255, 255, 255],
+  yellow: [255, 255, 0],
+  yellowBright: [255, 255, 153]
+};
+function isRgbTuple(value) {
+  return Array.isArray(value);
+}
+function toRgb(color) {
+  if (isRgbTuple(color)) {
+    return color;
+  }
+  return colorToRgb[color];
+}
+const ciSpinner = {
+  frames: [""],
+  interval: 2147483647
+};
+function desc(value) {
+  return {
+    __proto__: null,
+    configurable: true,
+    value,
+    writable: true
+  };
+}
+function normalizeText(value) {
+  return typeof value === "string" ? value.trimStart() : "";
+}
+function formatProgress(progress) {
+  const { current, total, unit } = progress;
+  const percentage = Math.round(current / total * 100);
+  const bar = renderProgressBar(percentage);
+  const count = unit ? `${current}/${total} ${unit}` : `${current}/${total}`;
+  return `${bar} ${percentage}% (${count})`;
+}
+function renderProgressBar(percentage, width = 20) {
+  const filled = Math.round(percentage / 100 * width);
+  const empty = width - filled;
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+  const colors = require("./external/yoctocolors-cjs");
+  return colors.cyan(bar);
+}
+let _cliSpinners;
+// @__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_objects.hasOwn)(_cliSpinners, styleName) ? _cliSpinners[styleName] : void 0;
+  }
+  return _cliSpinners;
+}
+let _Spinner;
+let _defaultSpinner;
+// @__NO_SIDE_EFFECTS__
+function Spinner(options) {
+  if (_Spinner === void 0) {
+    const YoctoCtor = import_yocto_spinner.default;
+    const tempInstance = YoctoCtor({});
+    const YoctoSpinnerClass = tempInstance.constructor;
+    _Spinner = class SpinnerClass extends YoctoSpinnerClass {
+      #baseText = "";
+      #indentation = "";
+      #progress;
+      #shimmer;
+      #shimmerSavedConfig;
+      constructor(options2) {
+        const opts = { __proto__: null, ...options2 };
+        const theme = (0, import_context.getTheme)();
+        let defaultColor = theme.colors.primary;
+        if (theme.effects?.spinner?.color) {
+          const resolved = (0, import_utils.resolveColor)(
+            theme.effects.spinner.color,
+            theme.colors
+          );
+          if (resolved === "inherit" || Array.isArray(resolved[0])) {
+            defaultColor = theme.colors.primary;
+          } else {
+            defaultColor = resolved;
+          }
+        }
+        const spinnerColor = opts.color ?? defaultColor;
+        if (isRgbTuple(spinnerColor) && (spinnerColor.length !== 3 || !spinnerColor.every(
+          (n) => typeof n === "number" && n >= 0 && n <= 255
+        ))) {
+          throw new TypeError(
+            "RGB color must be an array of 3 numbers between 0 and 255"
+          );
+        }
+        const spinnerColorRgb = toRgb(spinnerColor);
+        let shimmerInfo;
+        if (opts.shimmer) {
+          let shimmerDir;
+          let shimmerColor;
+          let shimmerSpeed = 1 / 3;
+          if (typeof opts.shimmer === "string") {
+            shimmerDir = opts.shimmer;
+          } else {
+            const shimmerConfig = {
+              __proto__: null,
+              ...opts.shimmer
+            };
+            shimmerDir = shimmerConfig.dir ?? import_text_shimmer.DIR_LTR;
+            shimmerColor = shimmerConfig.color ?? import_text_shimmer.COLOR_INHERIT;
+            shimmerSpeed = shimmerConfig.speed ?? 1 / 3;
+          }
+          shimmerInfo = {
+            __proto__: null,
+            color: shimmerColor === void 0 ? import_text_shimmer.COLOR_INHERIT : shimmerColor,
+            currentDir: import_text_shimmer.DIR_LTR,
+            mode: shimmerDir,
+            speed: shimmerSpeed,
+            step: 0
+          };
+        }
+        super({
+          signal: require("#constants/process").getAbortSignal(),
+          ...opts,
+          // Pass RGB color directly to yocto-spinner (it now supports RGB).
+          color: spinnerColorRgb,
+          // onRenderFrame callback provides full control over frame + text layout.
+          // Calculates spacing based on frame width to prevent text jumping.
+          onRenderFrame: (frame, text, applyColor) => {
+            const width = (0, import_strings.stringWidth)(frame);
+            const spacing = width === 1 ? "  " : " ";
+            return frame ? `${applyColor(frame)}${spacing}${text}` : text;
+          },
+          // onFrameUpdate callback is called by yocto-spinner whenever a frame advances.
+          // This ensures shimmer updates are perfectly synchronized with animation beats.
+          onFrameUpdate: shimmerInfo ? () => {
+            if (this.#baseText) {
+              super.text = this.#buildDisplayText();
+            }
+          } : void 0
+        });
+        this.#shimmer = shimmerInfo;
+        this.#shimmerSavedConfig = shimmerInfo;
+      }
+      // Override color getter to ensure it's always RGB.
+      get color() {
+        const value = super.color;
+        return isRgbTuple(value) ? value : toRgb(value);
+      }
+      // Override color setter to always convert to RGB before passing to yocto-spinner.
+      set color(value) {
+        super.color = isRgbTuple(value) ? value : toRgb(value);
+      }
+      // Getter to expose current shimmer state.
+      get shimmerState() {
+        if (!this.#shimmer) {
+          return void 0;
+        }
+        return {
+          color: this.#shimmer.color,
+          currentDir: this.#shimmer.currentDir,
+          mode: this.#shimmer.mode,
+          speed: this.#shimmer.speed,
+          step: this.#shimmer.step
+        };
+      }
+      /**
+       * Apply a yocto-spinner method and update logger state.
+       * Handles text normalization, extra arguments, and logger tracking.
+       * @private
+       */
+      #apply(methodName, args) {
+        let extras;
+        let text = args.at(0);
+        if (typeof text === "string") {
+          extras = args.slice(1);
+        } else {
+          extras = args;
+          text = "";
+        }
+        const wasSpinning = this.isSpinning;
+        const normalized = normalizeText(text);
+        super[methodName](normalized);
+        const {
+          getDefaultLogger,
+          incLogCallCountSymbol,
+          lastWasBlankSymbol
+        } = require("./logger.js");
+        const logger = getDefaultLogger();
+        if (methodName === "stop") {
+          if (wasSpinning && normalized) {
+            logger[lastWasBlankSymbol]((0, import_strings.isBlankString)(normalized));
+            logger[incLogCallCountSymbol]();
+          }
+        } else {
+          logger[lastWasBlankSymbol](false);
+          logger[incLogCallCountSymbol]();
+        }
+        if (extras.length) {
+          logger.log(...extras);
+          logger[lastWasBlankSymbol](false);
+        }
+        return this;
+      }
+      /**
+       * Build the complete display text with progress, shimmer, and indentation.
+       * Combines base text, progress bar, shimmer effects, and indentation.
+       * @private
+       */
+      #buildDisplayText() {
+        let displayText = this.#baseText;
+        if (this.#progress) {
+          const progressText = formatProgress(this.#progress);
+          displayText = displayText ? `${displayText} ${progressText}` : progressText;
+        }
+        if (displayText && this.#shimmer) {
+          let shimmerColor;
+          if (this.#shimmer.color === import_text_shimmer.COLOR_INHERIT) {
+            shimmerColor = this.color;
+          } else if (Array.isArray(this.#shimmer.color[0])) {
+            shimmerColor = this.#shimmer.color;
+          } else {
+            shimmerColor = toRgb(this.#shimmer.color);
+          }
+          displayText = (0, import_text_shimmer.applyShimmer)(displayText, this.#shimmer, {
+            color: shimmerColor,
+            direction: this.#shimmer.mode
+          });
+        }
+        if (this.#indentation && displayText) {
+          displayText = this.#indentation + displayText;
+        }
+        return displayText;
+      }
+      /**
+       * Show a status message without stopping the spinner.
+       * Outputs the symbol and message to stderr, then continues spinning.
+       */
+      #showStatusAndKeepSpinning(symbolType, args) {
+        let text = args.at(0);
+        let extras;
+        if (typeof text === "string") {
+          extras = args.slice(1);
+        } else {
+          extras = args;
+          text = "";
+        }
+        const {
+          LOG_SYMBOLS,
+          getDefaultLogger
+        } = require("./logger.js");
+        const logger = getDefaultLogger();
+        logger.error(`${LOG_SYMBOLS[symbolType]} ${text}`, ...extras);
+        return this;
+      }
+      /**
+       * Update the spinner's displayed text.
+       * Rebuilds display text and triggers render.
+       * @private
+       */
+      #updateSpinnerText() {
+        super.text = this.#buildDisplayText();
+      }
+      /**
+       * Show a debug message (ℹ) without stopping the spinner.
+       * Only displays if debug mode is enabled via environment variable.
+       * Outputs to stderr and continues spinning.
+       *
+       * @param text - Debug message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      debug(text, ...extras) {
+        const { isDebug } = require("./debug.js");
+        if (isDebug()) {
+          return this.#showStatusAndKeepSpinning("info", [text, ...extras]);
+        }
+        return this;
+      }
+      /**
+       * Show a debug message (ℹ) and stop the spinner.
+       * Only displays if debug mode is enabled via environment variable.
+       * Auto-clears the spinner line before displaying the message.
+       *
+       * @param text - Debug message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      debugAndStop(text, ...extras) {
+        const { isDebug } = require("./debug.js");
+        if (isDebug()) {
+          return this.#apply("info", [text, ...extras]);
+        }
+        return this;
+      }
+      /**
+       * Decrease indentation level by removing spaces from the left.
+       * Pass 0 to reset indentation to zero completely.
+       *
+       * @param spaces - Number of spaces to remove
+       * @returns This spinner for chaining
+       * @default spaces=2
+       *
+       * @example
+       * ```ts
+       * spinner.dedent()    // Remove 2 spaces
+       * spinner.dedent(4)   // Remove 4 spaces
+       * spinner.dedent(0)   // Reset to zero indentation
+       * ```
+       */
+      dedent(spaces) {
+        if (spaces === 0) {
+          this.#indentation = "";
+        } else {
+          const amount = spaces ?? 2;
+          const newLength = Math.max(0, this.#indentation.length - amount);
+          this.#indentation = this.#indentation.slice(0, newLength);
+        }
+        this.#updateSpinnerText();
+        return this;
+      }
+      /**
+       * Show a done/success message (✓) without stopping the spinner.
+       * Alias for `success()` with a shorter name.
+       *
+       * DESIGN DECISION: Unlike yocto-spinner, our `done()` does NOT stop the spinner.
+       * Use `doneAndStop()` if you want to stop the spinner.
+       *
+       * @param text - Message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      done(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("success", [text, ...extras]);
+      }
+      /**
+       * Show a done/success message (✓) and stop the spinner.
+       * Auto-clears the spinner line before displaying the success message.
+       *
+       * @param text - Message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      doneAndStop(text, ...extras) {
+        return this.#apply("success", [text, ...extras]);
+      }
+      /**
+       * Show a failure message (✗) without stopping the spinner.
+       * DESIGN DECISION: Unlike yocto-spinner, our `fail()` does NOT stop the spinner.
+       * This allows displaying errors while continuing to spin.
+       * Use `failAndStop()` if you want to stop the spinner.
+       *
+       * @param text - Error message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      fail(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("fail", [text, ...extras]);
+      }
+      /**
+       * Show a failure message (✗) and stop the spinner.
+       * Auto-clears the spinner line before displaying the error message.
+       *
+       * @param text - Error message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      failAndStop(text, ...extras) {
+        return this.#apply("error", [text, ...extras]);
+      }
+      /**
+       * Increase indentation level by adding spaces to the left.
+       * Pass 0 to reset indentation to zero completely.
+       *
+       * @param spaces - Number of spaces to add
+       * @returns This spinner for chaining
+       * @default spaces=2
+       *
+       * @example
+       * ```ts
+       * spinner.indent()    // Add 2 spaces
+       * spinner.indent(4)   // Add 4 spaces
+       * spinner.indent(0)   // Reset to zero indentation
+       * ```
+       */
+      indent(spaces) {
+        if (spaces === 0) {
+          this.#indentation = "";
+        } else {
+          const amount = spaces ?? 2;
+          this.#indentation += " ".repeat(amount);
+        }
+        this.#updateSpinnerText();
+        return this;
+      }
+      /**
+       * Show an info message (ℹ) without stopping the spinner.
+       * Outputs to stderr and continues spinning.
+       *
+       * @param text - Info message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      info(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("info", [text, ...extras]);
+      }
+      /**
+       * Show an info message (ℹ) and stop the spinner.
+       * Auto-clears the spinner line before displaying the message.
+       *
+       * @param text - Info message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      infoAndStop(text, ...extras) {
+        return this.#apply("info", [text, ...extras]);
+      }
+      /**
+       * Log a message to stdout without stopping the spinner.
+       * Unlike other status methods, this outputs to stdout for data logging.
+       *
+       * @param args - Values to log to stdout
+       * @returns This spinner for chaining
+       */
+      log(...args) {
+        const { getDefaultLogger } = require("./logger.js");
+        const logger = getDefaultLogger();
+        logger.log(...args);
+        return this;
+      }
+      /**
+       * Log a message to stdout and stop the spinner.
+       * Auto-clears the spinner line before displaying the message.
+       *
+       * @param text - Message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      logAndStop(text, ...extras) {
+        return this.#apply("stop", [text, ...extras]);
+      }
+      /**
+       * Update progress information displayed with the spinner.
+       * Shows a progress bar with percentage and optional unit label.
+       *
+       * @param current - Current progress value
+       * @param total - Total/maximum progress value
+       * @param unit - Optional unit label (e.g., 'files', 'items')
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.progress(5, 10)            // "███████░░░░░░░░░░░░░ 50% (5/10)"
+       * spinner.progress(7, 20, 'files')   // "███████░░░░░░░░░░░░░ 35% (7/20 files)"
+       * ```
+       */
+      progress = (current, total, unit) => {
+        this.#progress = {
+          __proto__: null,
+          current,
+          total,
+          ...unit ? { unit } : {}
+        };
+        this.#updateSpinnerText();
+        return this;
+      };
+      /**
+       * Increment progress by a specified amount.
+       * Updates the progress bar displayed with the spinner.
+       * Clamps the result between 0 and the total value.
+       *
+       * @param amount - Amount to increment by
+       * @returns This spinner for chaining
+       * @default amount=1
+       *
+       * @example
+       * ```ts
+       * spinner.progress(0, 10, 'files')
+       * spinner.progressStep()    // Progress: 1/10
+       * spinner.progressStep(3)   // Progress: 4/10
+       * ```
+       */
+      progressStep(amount = 1) {
+        if (this.#progress) {
+          const newCurrent = this.#progress.current + amount;
+          this.#progress = {
+            __proto__: null,
+            current: Math.max(0, Math.min(newCurrent, this.#progress.total)),
+            total: this.#progress.total,
+            ...this.#progress.unit ? { unit: this.#progress.unit } : {}
+          };
+          this.#updateSpinnerText();
+        }
+        return this;
+      }
+      /**
+       * Start the spinner animation with optional text.
+       * Begins displaying the animated spinner on stderr.
+       *
+       * @param text - Optional text to display with the spinner
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.start('Loading…')
+       * // Later:
+       * spinner.successAndStop('Done!')
+       * ```
+       */
+      start(...args) {
+        if (args.length) {
+          const text = args.at(0);
+          const normalized = normalizeText(text);
+          if (!normalized) {
+            this.#baseText = "";
+            super.text = "";
+          } else {
+            this.#baseText = normalized;
+          }
+        }
+        this.#updateSpinnerText();
+        return this.#apply("start", []);
+      }
+      /**
+       * Log a main step message to stderr without stopping the spinner.
+       * Adds a blank line before the message for visual separation.
+       * Aligns with `logger.step()` to use stderr for status messages.
+       *
+       * @param text - Step message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.step('Building application')
+       * spinner.substep('Compiling TypeScript')
+       * spinner.substep('Bundling assets')
+       * ```
+       */
+      step(text, ...extras) {
+        const { getDefaultLogger } = require("./logger.js");
+        if (typeof text === "string") {
+          const logger = getDefaultLogger();
+          logger.error("");
+          logger.error(text, ...extras);
+        }
+        return this;
+      }
+      /**
+       * Log an indented substep message to stderr without stopping the spinner.
+       * Adds 2-space indentation to the message.
+       * Aligns with `logger.substep()` to use stderr for status messages.
+       *
+       * @param text - Substep message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.step('Building application')
+       * spinner.substep('Compiling TypeScript')
+       * spinner.substep('Bundling assets')
+       * ```
+       */
+      substep(text, ...extras) {
+        if (typeof text === "string") {
+          const { getDefaultLogger } = require("./logger.js");
+          const logger = getDefaultLogger();
+          logger.error(`  ${text}`, ...extras);
+        }
+        return this;
+      }
+      /**
+       * Stop the spinner animation and clear internal state.
+       * Auto-clears the spinner line via yocto-spinner.stop().
+       * Resets progress, shimmer, and text state.
+       *
+       * @param text - Optional final text to display after stopping
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.start('Processing…')
+       * // Do work
+       * spinner.stop() // Just stop, no message
+       * // or
+       * spinner.stop('Finished processing')
+       * ```
+       */
+      stop(...args) {
+        this.#baseText = "";
+        this.#progress = void 0;
+        if (this.#shimmer) {
+          this.#shimmer.currentDir = import_text_shimmer.DIR_LTR;
+          this.#shimmer.step = 0;
+        }
+        const result = this.#apply("stop", args);
+        super.text = "";
+        return result;
+      }
+      /**
+       * Show a success message (✓) without stopping the spinner.
+       * DESIGN DECISION: Unlike yocto-spinner, our `success()` does NOT stop the spinner.
+       * This allows displaying success messages while continuing to spin for multi-step operations.
+       * Use `successAndStop()` if you want to stop the spinner.
+       *
+       * @param text - Success message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      success(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("success", [text, ...extras]);
+      }
+      /**
+       * Show a success message (✓) and stop the spinner.
+       * Auto-clears the spinner line before displaying the success message.
+       *
+       * @param text - Success message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      successAndStop(text, ...extras) {
+        return this.#apply("success", [text, ...extras]);
+      }
+      text(value) {
+        if (arguments.length === 0) {
+          return this.#baseText;
+        }
+        this.#baseText = value ?? "";
+        this.#updateSpinnerText();
+        return this;
+      }
+      /**
+       * Show a warning message (⚠) without stopping the spinner.
+       * Outputs to stderr and continues spinning.
+       *
+       * @param text - Warning message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      warn(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("warn", [text, ...extras]);
+      }
+      /**
+       * Show a warning message (⚠) and stop the spinner.
+       * Auto-clears the spinner line before displaying the warning message.
+       *
+       * @param text - Warning message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       */
+      warnAndStop(text, ...extras) {
+        return this.#apply("warning", [text, ...extras]);
+      }
+      /**
+       * Enable shimmer effect.
+       * Restores saved config or uses defaults if no saved config exists.
+       *
+       * @returns This spinner for chaining
+       *
+       * @example
+       * spinner.enableShimmer()
+       */
+      enableShimmer() {
+        if (this.#shimmerSavedConfig) {
+          this.#shimmer = { ...this.#shimmerSavedConfig };
+        } else {
+          this.#shimmer = {
+            color: import_text_shimmer.COLOR_INHERIT,
+            currentDir: import_text_shimmer.DIR_LTR,
+            mode: import_text_shimmer.DIR_LTR,
+            speed: 1 / 3,
+            step: 0
+          };
+          this.#shimmerSavedConfig = this.#shimmer;
+        }
+        this.#updateSpinnerText();
+        return this;
+      }
+      /**
+       * Disable shimmer effect.
+       * Preserves config for later re-enable via enableShimmer().
+       *
+       * @returns This spinner for chaining
+       *
+       * @example
+       * spinner.disableShimmer()
+       */
+      disableShimmer() {
+        this.#shimmer = void 0;
+        this.#updateSpinnerText();
+        return this;
+      }
+      /**
+       * Set complete shimmer configuration.
+       * Replaces any existing shimmer config with the provided values.
+       *
+       * @param config - Complete shimmer configuration
+       * @returns This spinner for chaining
+       *
+       * @example
+       * spinner.setShimmer({
+       *   color: [255, 0, 0],
+       *   dir: 'rtl',
+       *   speed: 0.5
+       * })
+       */
+      setShimmer(config) {
+        this.#shimmer = {
+          color: config.color,
+          currentDir: import_text_shimmer.DIR_LTR,
+          mode: config.dir,
+          speed: config.speed,
+          step: 0
+        };
+        this.#shimmerSavedConfig = this.#shimmer;
+        this.#updateSpinnerText();
+        return this;
+      }
+      /**
+       * Update partial shimmer configuration.
+       * Merges with existing config, enabling shimmer if currently disabled.
+       *
+       * @param config - Partial shimmer configuration to merge
+       * @returns This spinner for chaining
+       *
+       * @example
+       * // Update just the speed
+       * spinner.updateShimmer({ speed: 0.5 })
+       *
+       * // Update direction
+       * spinner.updateShimmer({ dir: 'rtl' })
+       *
+       * // Update multiple properties
+       * spinner.updateShimmer({ color: [255, 0, 0], speed: 0.8 })
+       */
+      updateShimmer(config) {
+        const partialConfig = {
+          __proto__: null,
+          ...config
+        };
+        if (this.#shimmer) {
+          this.#shimmer = {
+            ...this.#shimmer,
+            ...partialConfig.color !== void 0 ? { color: partialConfig.color } : {},
+            ...partialConfig.dir !== void 0 ? { mode: partialConfig.dir } : {},
+            ...partialConfig.speed !== void 0 ? { speed: partialConfig.speed } : {}
+          };
+          this.#shimmerSavedConfig = this.#shimmer;
+        } else if (this.#shimmerSavedConfig) {
+          this.#shimmer = {
+            ...this.#shimmerSavedConfig,
+            ...partialConfig.color !== void 0 ? { color: partialConfig.color } : {},
+            ...partialConfig.dir !== void 0 ? { mode: partialConfig.dir } : {},
+            ...partialConfig.speed !== void 0 ? { speed: partialConfig.speed } : {}
+          };
+          this.#shimmerSavedConfig = this.#shimmer;
+        } else {
+          this.#shimmer = {
+            color: partialConfig.color ?? import_text_shimmer.COLOR_INHERIT,
+            currentDir: import_text_shimmer.DIR_LTR,
+            mode: partialConfig.dir ?? import_text_shimmer.DIR_LTR,
+            speed: partialConfig.speed ?? 1 / 3,
+            step: 0
+          };
+          this.#shimmerSavedConfig = this.#shimmer;
+        }
+        this.#updateSpinnerText();
+        return this;
+      }
+    };
+    Object.defineProperties(_Spinner.prototype, {
+      error: desc(_Spinner.prototype.fail),
+      errorAndStop: desc(_Spinner.prototype.failAndStop),
+      warning: desc(_Spinner.prototype.warn),
+      warningAndStop: desc(_Spinner.prototype.warnAndStop)
+    });
+    _defaultSpinner = (0, import_ci.getCI)() ? ciSpinner : /* @__PURE__ */ getCliSpinners("socket");
+  }
+  return new _Spinner({
+    spinner: _defaultSpinner,
+    ...options
+  });
+}
+let _spinner;
+function getDefaultSpinner() {
+  if (_spinner === void 0) {
+    _spinner = /* @__PURE__ */ Spinner();
+  }
+  return _spinner;
+}
+async function withSpinner(options) {
+  const { message, operation, spinner, withOptions } = {
+    __proto__: null,
+    ...options
+  };
+  if (!spinner) {
+    return await operation();
+  }
+  const savedColor = withOptions?.color !== void 0 ? spinner.color : void 0;
+  const savedShimmerState = withOptions?.shimmer !== void 0 ? spinner.shimmerState : void 0;
+  if (withOptions?.color !== void 0) {
+    spinner.color = toRgb(withOptions.color);
+  }
+  if (withOptions?.shimmer !== void 0) {
+    if (typeof withOptions.shimmer === "string") {
+      spinner.updateShimmer({ dir: withOptions.shimmer });
+    } else {
+      spinner.setShimmer(withOptions.shimmer);
+    }
+  }
+  spinner.start(message);
+  try {
+    return await operation();
+  } finally {
+    spinner.stop();
+    if (savedColor !== void 0) {
+      spinner.color = savedColor;
+    }
+    if (withOptions?.shimmer !== void 0) {
+      if (savedShimmerState) {
+        spinner.setShimmer({
+          color: savedShimmerState.color,
+          dir: savedShimmerState.mode,
+          speed: savedShimmerState.speed
+        });
+      } else {
+        spinner.disableShimmer();
+      }
+    }
+  }
+}
+async function withSpinnerRestore(options) {
+  const { operation, spinner, wasSpinning } = {
+    __proto__: null,
+    ...options
+  };
+  try {
+    return await operation();
+  } finally {
+    if (spinner && wasSpinning) {
+      spinner.start();
+    }
+  }
+}
+function withSpinnerSync(options) {
+  const { message, operation, spinner, withOptions } = {
+    __proto__: null,
+    ...options
+  };
+  if (!spinner) {
+    return operation();
+  }
+  const savedColor = withOptions?.color !== void 0 ? spinner.color : void 0;
+  const savedShimmerState = withOptions?.shimmer !== void 0 ? spinner.shimmerState : void 0;
+  if (withOptions?.color !== void 0) {
+    spinner.color = toRgb(withOptions.color);
+  }
+  if (withOptions?.shimmer !== void 0) {
+    if (typeof withOptions.shimmer === "string") {
+      spinner.updateShimmer({ dir: withOptions.shimmer });
+    } else {
+      spinner.setShimmer(withOptions.shimmer);
+    }
+  }
+  spinner.start(message);
+  try {
+    return operation();
+  } finally {
+    spinner.stop();
+    if (savedColor !== void 0) {
+      spinner.color = savedColor;
+    }
+    if (withOptions?.shimmer !== void 0) {
+      if (savedShimmerState) {
+        spinner.setShimmer({
+          color: savedShimmerState.color,
+          dir: savedShimmerState.mode,
+          speed: savedShimmerState.speed
+        });
+      } else {
+        spinner.disableShimmer();
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Spinner,
+  ciSpinner,
+  getCliSpinners,
+  getDefaultSpinner,
+  toRgb,
+  withSpinner,
+  withSpinnerRestore,
+  withSpinnerSync
+});
 //# sourceMappingURL=spinner.js.map