@doist/cli-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.3.0](https://github.com/Doist/cli-core/compare/v0.2.0...v0.3.0) (2026-05-06)
+
+### Features
+
+* add createSpinner factory ([#5](https://github.com/Doist/cli-core/issues/5)) ([7092427](https://github.com/Doist/cli-core/commit/70924271385bb9ad2009a0d56df5a8768c9943f7))
+
 ## [0.2.0](https://github.com/Doist/cli-core/compare/v0.1.0...v0.2.0) (2026-05-06)
 
 ### Features

package/dist/config.d.ts

@@ -65,13 +65,13 @@ export type ConfigErrorCode = (typeof BROKEN_CONFIG_STATE_TO_CODE)[keyof typeof
  * decode in the consumer.
  */
 export declare function readConfigStrict(path: string): Promise<ReadConfigStrictResult>;
-export interface WriteConfigOptions {
+export type WriteConfigOptions = {
     /**
      * When true and the supplied config has no own enumerable keys, delete the
      * file instead of writing an empty `{}`. Default false.
      */
     deleteWhenEmpty?: boolean;
-}
+};
 /**
  * Write a config file with restrictive permissions (parent dir 0700, file 0600)
  * and a trailing newline. Creates parent directories as needed and tightens

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAGpF;AAED,MAAM,MAAM,sBAAsB,GAC5B;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;CAAE,GACtF;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAU3D;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;CAIc,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAA;AAElF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAqBpF;AAED,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAGpF;AAED,MAAM,MAAM,sBAAsB,GAC5B;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACtC;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;CAAE,GACtF;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAU3D;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;CAIc,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAA;AAElF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAqBpF;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC/C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/errors.d.ts

@@ -1,9 +1,9 @@
 import type { ConfigErrorCode } from './config.js';
 export type ErrorType = 'error' | 'info';
-export interface CliErrorOptions {
+export type CliErrorOptions = {
     hints?: string[];
     type?: ErrorType;
-}
+};
 /**
  * Aggregator of every error code that cli-core itself defines. Baked into the
  * `CliError` constructor so consumers don't have to redeclare these strings in

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExC,MAAM,WAAW,eAAe;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,YAAY,CAAA;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;gBAEZ,IAAI,EAAE,KAAK,GAAG,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAOzF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExC,MAAM,MAAM,eAAe,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,YAAY,CAAA;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;gBAEZ,IAAI,EAAE,KAAK,GAAG,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;CAOzF"}

package/dist/index.d.ts

@@ -3,5 +3,7 @@ export type { ConfigErrorCode, ReadConfigStrictResult, WriteConfigOptions } from
 export { CliError } from './errors.js';
 export type { CliErrorCode, CliErrorOptions, ErrorType } from './errors.js';
 export { formatJson, formatNdjson } from './json.js';
+export { createSpinner } from './spinner.js';
+export type { LoadingSpinner, SpinnerColor, SpinnerConfig, SpinnerKit, SpinnerOptions, } from './spinner.js';
 export { isCI, isStderrTTY, isStdinTTY, isStdoutTTY } from './terminal.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACd,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACd,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EACR,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,cAAc,GACjB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { BROKEN_CONFIG_STATE_TO_CODE, getConfigPath, readConfig, readConfigStrict, updateConfig, writeConfig, } from './config.js';
 export { CliError } from './errors.js';
 export { formatJson, formatNdjson } from './json.js';
+export { createSpinner } from './spinner.js';
 export { isCI, isStderrTTY, isStdinTTY, isStdoutTTY } from './terminal.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACd,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACd,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAQ5C,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/spinner.d.ts

@@ -0,0 +1,60 @@
+export type SpinnerColor = 'green' | 'yellow' | 'blue' | 'red' | 'gray' | 'cyan' | 'magenta';
+export type SpinnerOptions = {
+    text: string;
+    color?: SpinnerColor;
+    /** Per-call opt-out (e.g. when a flag like `--no-spinner` was passed). */
+    noSpinner?: boolean;
+};
+export type SpinnerConfig = {
+    /**
+     * Returns true to suppress every spinner produced by this kit. CLIs
+     * supply this to combine well-known signals (CI, `--json`, etc.) with
+     * their own opt-out env vars (e.g. `TD_SPINNER=false`).
+     *
+     * Defaults to `() => false`.
+     */
+    isDisabled?: () => boolean;
+    /** Default colour name. Defaults to `'blue'`. */
+    defaultColor?: SpinnerColor;
+    /** Default text shown by `startEarlySpinner` when no override is passed. */
+    earlySpinnerText?: string;
+};
+export type LoadingSpinner = {
+    start(options: SpinnerOptions): LoadingSpinner;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    stop(): void;
+};
+export type SpinnerKit = {
+    /** Class so consumers can use `new spinner.LoadingSpinner()` if they want
+     *  to manage start/stop manually. Most call sites should prefer `withSpinner`. */
+    LoadingSpinner: new () => LoadingSpinner;
+    /** Run an async operation flanked by a spinner. Stops on success, fails on throw. */
+    withSpinner: <T>(options: SpinnerOptions, op: () => Promise<T>) => Promise<T>;
+    /** Show a long-running spinner before the command module loads. Intercepts
+     *  stdout.write so it auto-clears the moment any output is produced. */
+    startEarlySpinner: (text?: string) => void;
+    /** Stop the early spinner if running and restore stdout.write. */
+    stopEarlySpinner: () => void;
+    /**
+     * @internal Reset internal state without calling `.stop()`. Exposed only
+     * so consumer test suites can fully reset the kit between cases; do not
+     * call from production code.
+     */
+    resetEarlySpinner: () => void;
+};
+/**
+ * Build a spinner kit configured for one CLI. Each kit owns its own early-
+ * spinner singleton state, so two kits running in the same process don't
+ * step on each other.
+ *
+ * ```ts
+ * import { createSpinner } from '@doist/cli-core'
+ * import { shouldDisableSpinner } from './global-args.js'
+ *
+ * const { LoadingSpinner, withSpinner, startEarlySpinner, stopEarlySpinner } =
+ *     createSpinner({ isDisabled: shouldDisableSpinner })
+ * ```
+ */
+export declare function createSpinner(config?: SpinnerConfig): SpinnerKit;
+//# sourceMappingURL=spinner.d.ts.map

package/dist/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../src/spinner.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AAE5F,MAAM,MAAM,cAAc,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IACxB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,OAAO,CAAA;IAC1B,iDAAiD;IACjD,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAAA;IAC9C,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,IAAI,IAAI,IAAI,CAAA;CACf,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACrB;sFACkF;IAClF,cAAc,EAAE,UAAU,cAAc,CAAA;IACxC,qFAAqF;IACrF,WAAW,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAC7E;4EACwE;IACxE,iBAAiB,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,IAAI,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,aAAkB,GAAG,UAAU,CAiJpE"}

package/dist/spinner.js

@@ -0,0 +1,151 @@
+import chalk from 'chalk';
+import yoctoSpinner from 'yocto-spinner';
+import { isStdoutTTY } from './terminal.js';
+/**
+ * Build a spinner kit configured for one CLI. Each kit owns its own early-
+ * spinner singleton state, so two kits running in the same process don't
+ * step on each other.
+ *
+ * ```ts
+ * import { createSpinner } from '@doist/cli-core'
+ * import { shouldDisableSpinner } from './global-args.js'
+ *
+ * const { LoadingSpinner, withSpinner, startEarlySpinner, stopEarlySpinner } =
+ *     createSpinner({ isDisabled: shouldDisableSpinner })
+ * ```
+ */
+export function createSpinner(config = {}) {
+    const isDisabled = config.isDisabled ?? (() => false);
+    const defaultColor = config.defaultColor ?? 'blue';
+    const earlyText = config.earlySpinnerText ?? 'Loading...';
+    let earlyInstance = null;
+    let originalStdoutWrite = null;
+    let stdoutInterceptor = null;
+    function restoreStdoutWrite() {
+        if (!originalStdoutWrite)
+            return;
+        // Only restore if our interceptor is still on top — anything else that
+        // monkey-patched process.stdout.write after us should keep its hook.
+        if (process.stdout.write === stdoutInterceptor) {
+            process.stdout.write = originalStdoutWrite;
+        }
+        originalStdoutWrite = null;
+        stdoutInterceptor = null;
+    }
+    function startEarlySpinner(text = earlyText) {
+        if (!isStdoutTTY() || isDisabled())
+            return;
+        earlyInstance = yoctoSpinner({ text: chalk[defaultColor](text) });
+        earlyInstance.start();
+        // Capture the original in a local closure variable (no .bind()) so
+        // repeat startEarlySpinner calls don't nest .bind() copies, and so
+        // the wrapper's reference survives `stopEarlySpinner` clearing the
+        // module-level `originalStdoutWrite` field.
+        const savedWrite = process.stdout.write;
+        originalStdoutWrite = savedWrite;
+        const wrapper = function (...args) {
+            stopEarlySpinner();
+            return savedWrite.apply(this, args);
+        };
+        stdoutInterceptor = wrapper;
+        process.stdout.write = wrapper;
+    }
+    function stopEarlySpinner() {
+        restoreStdoutWrite();
+        if (earlyInstance) {
+            earlyInstance.stop();
+            earlyInstance = null;
+        }
+    }
+    function resetEarlySpinner() {
+        restoreStdoutWrite();
+        earlyInstance = null;
+    }
+    class LoadingSpinnerImpl {
+        instance = null;
+        adopted = false;
+        start(options) {
+            if (!isStdoutTTY() || options.noSpinner || isDisabled()) {
+                return this;
+            }
+            const colorFn = chalk[options.color ?? defaultColor];
+            // Adopt an existing early spinner if one's running rather than
+            // stacking a second one on top.
+            if (earlyInstance) {
+                this.instance = earlyInstance;
+                this.adopted = true;
+                earlyInstance = null;
+                // Adoption transfers stdout-clear responsibility to this
+                // spinner. The early-spinner's stdout interceptor would
+                // otherwise still fire (calling stopEarlySpinner with a now-
+                // null earlyInstance) while the adopted spinner kept running.
+                restoreStdoutWrite();
+                this.instance.text = colorFn(options.text);
+                return this;
+            }
+            this.instance = yoctoSpinner({ text: colorFn(options.text) });
+            this.instance.start();
+            return this;
+        }
+        /** Release an adopted spinner back to the pool. Returns true if released. */
+        releaseAdopted() {
+            if (!this.adopted || !this.instance)
+                return false;
+            earlyInstance = this.instance;
+            this.instance = null;
+            this.adopted = false;
+            return true;
+        }
+        succeed(text) {
+            if (!this.instance)
+                return;
+            // Release-back is silent; only do it when the caller didn't ask
+            // for a visible success line. With text, the user wants the
+            // checkmark + message and we terminate.
+            if (text === undefined && this.releaseAdopted())
+                return;
+            // yocto-spinner prepends its own ✔ glyph; passing the bare text
+            // (coloured) avoids a duplicated symbol.
+            this.instance.success(text ? chalk.green(text) : undefined);
+            this.instance = null;
+            this.adopted = false;
+        }
+        fail(text) {
+            if (!this.instance)
+                return;
+            // yocto-spinner prepends its own ✖ glyph; passing the bare text
+            // (coloured) avoids a duplicated symbol. Errors always terminate.
+            this.instance.error(text ? chalk.red(text) : undefined);
+            this.instance = null;
+            this.adopted = false;
+        }
+        stop() {
+            if (!this.instance)
+                return;
+            if (this.releaseAdopted())
+                return;
+            this.instance.stop();
+            this.instance = null;
+        }
+    }
+    async function withSpinner(options, op) {
+        const spinner = new LoadingSpinnerImpl().start(options);
+        try {
+            const result = await op();
+            spinner.stop();
+            return result;
+        }
+        catch (error) {
+            spinner.fail();
+            throw error;
+        }
+    }
+    return {
+        LoadingSpinner: LoadingSpinnerImpl,
+        withSpinner,
+        startEarlySpinner,
+        stopEarlySpinner,
+        resetEarlySpinner,
+    };
+}
+//# sourceMappingURL=spinner.js.map

package/dist/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../src/spinner.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/cli-core",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Shared core utilities for Doist CLI projects",
     "type": "module",
     "main": "dist/index.js",
@@ -58,5 +58,9 @@
         "semantic-release": "25.0.3",
         "typescript": "6.0.3",
         "vitest": "4.1.5"
+    },
+    "dependencies": {
+        "chalk": "5.6.2",
+        "yocto-spinner": "1.1.0"
     }
 }