@oclif/multi-stage-output 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Salesforce.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+<img src="https://user-images.githubusercontent.com/449385/38243295-e0a47d58-372e-11e8-9bc0-8c02a6f4d2ac.png" width="260" height="73">
+
+[![Version](https://img.shields.io/npm/v/@oclif/multi-stage-output.svg)](https://npmjs.org/package/@oclif/multi-stage-output)
+[![Downloads/week](https://img.shields.io/npm/dw/@oclif/multi-stage-output.svg)](https://npmjs.org/package/@oclif/multi-stage-output)
+[![License](https://img.shields.io/npm/l/@oclif/multi-stage-output.svg)](https://github.com/oclif/multi-stage-output/blob/main/LICENSE)
+
+# Description
+
+This is a framework for showing multi-stage output in the terminal. It's integrated with oclif's builtin [Performance](https://oclif.io/docs/performance/) capabilities so that perf metrics are automatically captured for each stage.
+
+# Examples
+
+You can see examples of how to use it in the [examples](./examples/) directory.
+
+You can run any of these with the following:
+
+```
+node --loader=ts-node/esm examples/basic.ts
+```
+
+# Contributing
+
+See the [contributing guide](./CONRTIBUTING.md).

package/lib/components/divider.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export declare function Divider({ dividerChar, dividerColor, padding, title, titleColor, titlePadding, width, }: {
+    readonly title?: string;
+    readonly width?: number | 'full';
+    readonly padding?: number;
+    readonly titleColor?: string;
+    readonly titlePadding?: number;
+    readonly dividerChar?: string;
+    readonly dividerColor?: string;
+}): React.ReactNode;

package/lib/components/divider.js

@@ -0,0 +1,22 @@
+import { Box, Text } from 'ink';
+import React from 'react';
+const getSideDividerWidth = (width, titleWidth) => (width - titleWidth) / 2;
+const getNumberOfCharsPerWidth = (char, width) => width / char.length;
+const PAD = ' ';
+export function Divider({ dividerChar = '─', dividerColor = 'dim', padding = 1, title = '', titleColor = 'white', titlePadding = 1, width = 50, }) {
+    const titleString = title ? `${PAD.repeat(titlePadding) + title + PAD.repeat(titlePadding)}` : '';
+    const titleWidth = titleString.length;
+    const terminalWidth = process.stdout.columns ?? 80;
+    const widthToUse = width === 'full' ? terminalWidth - titlePadding : width > terminalWidth ? terminalWidth : width;
+    const dividerWidth = getSideDividerWidth(widthToUse, titleWidth);
+    const numberOfCharsPerSide = getNumberOfCharsPerWidth(dividerChar, dividerWidth);
+    const dividerSideString = dividerChar.repeat(numberOfCharsPerSide);
+    const paddingString = PAD.repeat(padding);
+    return (React.createElement(Box, { flexDirection: "row" },
+        React.createElement(Text, null,
+            paddingString,
+            React.createElement(Text, { color: dividerColor }, dividerSideString),
+            React.createElement(Text, { color: titleColor }, titleString),
+            React.createElement(Text, { color: dividerColor }, dividerSideString),
+            paddingString)));
+}

package/lib/components/multi-stage-output.d.ts

@@ -0,0 +1,135 @@
+import React from 'react';
+import { StageTracker } from '../stage-tracker.js';
+type Info<T extends Record<string, unknown>> = {
+    /**
+     * key-value: Display a key-value pair with a spinner.
+     * static-key-value: Display a key-value pair without a spinner.
+     * message: Display a message.
+     */
+    type: 'dynamic-key-value' | 'static-key-value' | 'message';
+    /**
+     * Color of the value.
+     */
+    color?: string;
+    /**
+     * Get the value to display. Takes the data property on the MultiStageComponent as an argument.
+     * Useful if you want to apply some logic (like rendering a link) to the data before displaying it.
+     *
+     * @param data The data property on the MultiStageComponent.
+     * @returns {string | undefined}
+     */
+    get: (data?: T) => string | undefined;
+    /**
+     * Whether the value should be bold.
+     */
+    bold?: boolean;
+};
+type KeyValuePair<T extends Record<string, unknown>> = Info<T> & {
+    /**
+     * Label of the key-value pair.
+     */
+    label: string;
+    type: 'dynamic-key-value' | 'static-key-value';
+};
+type SimpleMessage<T extends Record<string, unknown>> = Info<T> & {
+    type: 'message';
+};
+type StageInfoBlock<T extends Record<string, unknown>> = Array<(KeyValuePair<T> & {
+    stage: string;
+}) | (SimpleMessage<T> & {
+    stage: string;
+})>;
+export type FormattedKeyValue = {
+    readonly color?: string;
+    readonly isBold?: boolean;
+    readonly label?: string;
+    readonly value: string | undefined;
+    readonly stage?: string;
+    readonly type: 'dynamic-key-value' | 'static-key-value' | 'message';
+};
+type MultiStageComponentOptions<T extends Record<string, unknown>> = {
+    /**
+     * Stages to render.
+     */
+    readonly stages: readonly string[] | string[];
+    /**
+     * Title to display at the top of the stages component.
+     */
+    readonly title: string;
+    /**
+     * Information to display at the bottom of the stages component.
+     */
+    readonly postStagesBlock?: Array<KeyValuePair<T> | SimpleMessage<T>>;
+    /**
+     * Information to display below the title but above the stages.
+     */
+    readonly preStagesBlock?: Array<KeyValuePair<T> | SimpleMessage<T>>;
+    /**
+     * Whether to show the total elapsed time. Defaults to true
+     */
+    readonly showElapsedTime?: boolean;
+    /**
+     * Whether to show the time spent on each stage. Defaults to true
+     */
+    readonly showStageTime?: boolean;
+    /**
+     * Information to display for a specific stage. Each object must have a stage property set.
+     */
+    readonly stageSpecificBlock?: StageInfoBlock<T>;
+    /**
+     * The unit to use for the timer. Defaults to 'ms'
+     */
+    readonly timerUnit?: 'ms' | 's';
+    /**
+     * Data to display in the stages component. This data will be passed to the get function in the info object.
+     */
+    readonly data?: Partial<T>;
+    /**
+     * Whether JSON output is enabled. Defaults to false.
+     *
+     * Pass in this.jsonEnabled() from the command class to determine if JSON output is enabled.
+     */
+    readonly jsonEnabled: boolean;
+    /**
+     * Whether to override the CI detection and force the component to render as if it's in a CI environment.
+     */
+    readonly isInCiOverride?: boolean;
+};
+type StagesProps = {
+    readonly error?: Error | undefined;
+    readonly postStagesBlock?: FormattedKeyValue[];
+    readonly preStagesBlock?: FormattedKeyValue[];
+    readonly stageSpecificBlock?: FormattedKeyValue[];
+    readonly title: string;
+    readonly hasElapsedTime?: boolean;
+    readonly hasStageTime?: boolean;
+    readonly timerUnit?: 'ms' | 's';
+    readonly stageTracker: StageTracker;
+};
+declare function SimpleMessage({ color, isBold, value }: FormattedKeyValue): React.ReactNode;
+export declare function Stages({ error, hasElapsedTime, hasStageTime, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, timerUnit, title, }: StagesProps): React.ReactNode;
+export declare class MultiStageOutput<T extends Record<string, unknown>> implements Disposable {
+    private ciInstance;
+    private data?;
+    private readonly hasElapsedTime?;
+    private readonly hasStageTime?;
+    private inkInstance;
+    private readonly isInCi;
+    private readonly postStagesBlock?;
+    private readonly preStagesBlock?;
+    private readonly stages;
+    private readonly stageSpecificBlock?;
+    private stageTracker;
+    private stopped;
+    private readonly timerUnit?;
+    private readonly title;
+    constructor({ data, isInCiOverride, jsonEnabled, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }: MultiStageComponentOptions<T>);
+    goto(stage: string, data?: Partial<T>): void;
+    next(data?: Partial<T>): void;
+    stop(error?: Error): void;
+    [Symbol.dispose](): void;
+    updateData(data: Partial<T>): void;
+    private formatKeyValuePairs;
+    private update;
+}
+export {};

package/lib/components/multi-stage-output.js

@@ -0,0 +1,312 @@
+import { ux } from '@oclif/core/ux';
+import { capitalCase } from 'change-case';
+import { Box, Text, render } from 'ink';
+import { env } from 'node:process';
+import React from 'react';
+import { icons, spinners } from '../design-elements.js';
+import { StageTracker } from '../stage-tracker.js';
+import { readableTime } from '../utils.js';
+import { Divider } from './divider.js';
+import { SpinnerOrError, SpinnerOrErrorOrChildren } from './spinner.js';
+import { Timer } from './timer.js';
+// Taken from https://github.com/sindresorhus/is-in-ci
+const isInCi = env.CI !== '0' &&
+    env.CI !== 'false' &&
+    ('CI' in env || 'CONTINUOUS_INTEGRATION' in env || Object.keys(env).some((key) => key.startsWith('CI_')));
+function StaticKeyValue({ color, isBold, label, value }) {
+    if (!value)
+        return;
+    return (React.createElement(Box, { key: label },
+        React.createElement(Text, { bold: isBold },
+            label,
+            ": "),
+        React.createElement(Text, { color: color }, value)));
+}
+function SimpleMessage({ color, isBold, value }) {
+    if (!value)
+        return;
+    return (React.createElement(Text, { bold: isBold, color: color }, value));
+}
+function Infos({ error, keyValuePairs, stage, }) {
+    return (keyValuePairs
+        // If stage is provided, only show info for that stage
+        // otherwise, show all infos that don't have a specified stage
+        .filter((kv) => (stage ? kv.stage === stage : !kv.stage))
+        .map((kv) => {
+        const key = `${kv.label}-${kv.value}`;
+        if (kv.type === 'message') {
+            return React.createElement(SimpleMessage, { key: key, ...kv });
+        }
+        if (kv.type === 'dynamic-key-value') {
+            return (React.createElement(SpinnerOrErrorOrChildren, { key: key, error: error, label: `${kv.label}: `, labelPosition: "left", type: spinners.info }, kv.value && (React.createElement(Text, { bold: kv.isBold, color: kv.color }, kv.value))));
+        }
+        if (kv.type === 'static-key-value') {
+            return React.createElement(StaticKeyValue, { key: key, ...kv });
+        }
+        return null;
+    }));
+}
+export function Stages({ error, hasElapsedTime = true, hasStageTime = true, postStagesBlock, preStagesBlock, stageSpecificBlock, stageTracker, timerUnit = 'ms', title, }) {
+    return (React.createElement(Box, { flexDirection: "column", paddingTop: 1 },
+        React.createElement(Divider, { title: title }),
+        preStagesBlock && preStagesBlock.length > 0 && (React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingTop: 1 },
+            React.createElement(Infos, { error: error, keyValuePairs: preStagesBlock }))),
+        React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingTop: 1 }, [...stageTracker.entries()].map(([stage, status]) => (React.createElement(Box, { key: stage, flexDirection: "column" },
+            React.createElement(Box, null,
+                (status === 'current' || status === 'failed') && (React.createElement(SpinnerOrError, { error: error, label: capitalCase(stage), type: spinners.stage })),
+                status === 'skipped' && (React.createElement(Text, { color: "dim" },
+                    icons.skipped,
+                    " ",
+                    capitalCase(stage),
+                    " - Skipped")),
+                status === 'completed' && (React.createElement(Box, null,
+                    React.createElement(Text, { color: "green" }, icons.completed),
+                    React.createElement(Text, null, capitalCase(stage)))),
+                status === 'pending' && (React.createElement(Text, { color: "dim" },
+                    icons.pending,
+                    " ",
+                    capitalCase(stage))),
+                status !== 'pending' && status !== 'skipped' && hasStageTime && (React.createElement(Box, null,
+                    React.createElement(Text, null, " "),
+                    React.createElement(Timer, { color: "dim", isStopped: status === 'completed', unit: timerUnit })))),
+            stageSpecificBlock && stageSpecificBlock.length > 0 && status !== 'pending' && status !== 'skipped' && (React.createElement(Box, { flexDirection: "column", marginLeft: 5 },
+                React.createElement(Infos, { error: error, keyValuePairs: stageSpecificBlock, stage: stage }))))))),
+        postStagesBlock && postStagesBlock.length > 0 && (React.createElement(Box, { flexDirection: "column", marginLeft: 1, paddingTop: 1 },
+            React.createElement(Infos, { error: error, keyValuePairs: postStagesBlock }))),
+        hasElapsedTime && (React.createElement(Box, { marginLeft: 1, paddingTop: 1 },
+            React.createElement(Text, null, "Elapsed Time: "),
+            React.createElement(Timer, { unit: timerUnit })))));
+}
+class CIMultiStageOutput {
+    data;
+    hasElapsedTime;
+    hasStageTime;
+    lastUpdateTime;
+    messageTimeout = Number.parseInt(env.SF_CI_MESSAGE_TIMEOUT ?? '5000', 10) ?? 5000;
+    postStagesBlock;
+    preStagesBlock;
+    seenStages = new Set();
+    stages;
+    stageSpecificBlock;
+    startTime;
+    startTimes = new Map();
+    timerUnit;
+    title;
+    constructor({ data, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }) {
+        this.title = title;
+        this.stages = stages;
+        this.postStagesBlock = postStagesBlock;
+        this.preStagesBlock = preStagesBlock;
+        this.hasElapsedTime = showElapsedTime ?? true;
+        this.hasStageTime = showStageTime ?? true;
+        this.stageSpecificBlock = stageSpecificBlock;
+        this.timerUnit = timerUnit ?? 'ms';
+        this.data = data;
+        this.lastUpdateTime = Date.now();
+        ux.stdout(`───── ${this.title} ─────`);
+        ux.stdout('Steps:');
+        for (const stage of this.stages) {
+            ux.stdout(`${this.stages.indexOf(stage) + 1}. ${capitalCase(stage)}`);
+        }
+        ux.stdout();
+        if (this.hasElapsedTime) {
+            this.startTime = Date.now();
+        }
+    }
+    stop(stageTracker) {
+        this.update(stageTracker);
+        if (this.startTime) {
+            const elapsedTime = Date.now() - this.startTime;
+            ux.stdout();
+            const displayTime = readableTime(elapsedTime, this.timerUnit);
+            ux.stdout(`Elapsed time: ${displayTime}`);
+            ux.stdout();
+        }
+        this.printInfo(this.preStagesBlock);
+        this.printInfo(this.postStagesBlock);
+    }
+    update(stageTracker, data) {
+        this.data = { ...this.data, ...data };
+        for (const [stage, status] of stageTracker.entries()) {
+            // no need to re-render completed, failed, or skipped stages
+            if (this.seenStages.has(stage))
+                continue;
+            switch (status) {
+                case 'pending': {
+                    // do nothing
+                    break;
+                }
+                case 'current': {
+                    if (Date.now() - this.lastUpdateTime < this.messageTimeout)
+                        break;
+                    this.lastUpdateTime = Date.now();
+                    if (!this.startTimes.has(stage))
+                        this.startTimes.set(stage, Date.now());
+                    ux.stdout(`${icons.current} ${capitalCase(stage)}...`);
+                    this.printInfo(this.preStagesBlock, 3);
+                    this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
+                    this.printInfo(this.postStagesBlock, 3);
+                    break;
+                }
+                case 'failed':
+                case 'skipped':
+                case 'completed': {
+                    this.seenStages.add(stage);
+                    if (this.hasStageTime && status !== 'skipped') {
+                        const startTime = this.startTimes.get(stage);
+                        const elapsedTime = startTime ? Date.now() - startTime : 0;
+                        const displayTime = readableTime(elapsedTime, this.timerUnit);
+                        ux.stdout(`${icons[status]} ${capitalCase(stage)} (${displayTime})`);
+                        this.printInfo(this.preStagesBlock, 3);
+                        this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
+                        this.printInfo(this.postStagesBlock, 3);
+                    }
+                    else if (status === 'skipped') {
+                        ux.stdout(`${icons[status]} ${capitalCase(stage)} - Skipped`);
+                    }
+                    else {
+                        ux.stdout(`${icons[status]} ${capitalCase(stage)}`);
+                        this.printInfo(this.preStagesBlock, 3);
+                        this.printInfo(this.stageSpecificBlock?.filter((info) => info.stage === stage), 3);
+                        this.printInfo(this.postStagesBlock, 3);
+                    }
+                    break;
+                }
+                default:
+                // do nothing
+            }
+        }
+    }
+    printInfo(infoBlock, indent = 0) {
+        const spaces = ' '.repeat(indent);
+        if (infoBlock?.length) {
+            for (const info of infoBlock) {
+                const formattedData = info.get ? info.get(this.data) : undefined;
+                if (!formattedData)
+                    continue;
+                if (info.type === 'message') {
+                    ux.stdout(`${spaces}${formattedData}`);
+                }
+                else {
+                    ux.stdout(`${spaces}${info.label}: ${formattedData}`);
+                }
+            }
+        }
+    }
+}
+export class MultiStageOutput {
+    ciInstance;
+    data;
+    hasElapsedTime;
+    hasStageTime;
+    inkInstance;
+    isInCi;
+    postStagesBlock;
+    preStagesBlock;
+    stages;
+    stageSpecificBlock;
+    stageTracker;
+    stopped = false;
+    timerUnit;
+    title;
+    constructor({ data, isInCiOverride, jsonEnabled, postStagesBlock, preStagesBlock, showElapsedTime, showStageTime, stageSpecificBlock, stages, timerUnit, title, }) {
+        this.data = data;
+        this.stages = stages;
+        this.title = title;
+        this.postStagesBlock = postStagesBlock;
+        this.preStagesBlock = preStagesBlock;
+        this.hasElapsedTime = showElapsedTime ?? true;
+        this.hasStageTime = showStageTime ?? true;
+        this.timerUnit = timerUnit ?? 'ms';
+        this.stageTracker = new StageTracker(stages);
+        this.stageSpecificBlock = stageSpecificBlock;
+        this.isInCi = isInCiOverride ?? isInCi;
+        if (jsonEnabled)
+            return;
+        if (this.isInCi) {
+            this.ciInstance = new CIMultiStageOutput({
+                data,
+                jsonEnabled,
+                postStagesBlock,
+                preStagesBlock,
+                showElapsedTime,
+                showStageTime,
+                stageSpecificBlock,
+                stages,
+                timerUnit,
+                title,
+            });
+        }
+        else {
+            this.inkInstance = render(React.createElement(Stages, { hasElapsedTime: this.hasElapsedTime, hasStageTime: this.hasStageTime, postStagesBlock: this.formatKeyValuePairs(this.postStagesBlock), preStagesBlock: this.formatKeyValuePairs(this.preStagesBlock), stageSpecificBlock: this.formatKeyValuePairs(this.stageSpecificBlock), stageTracker: this.stageTracker, timerUnit: this.timerUnit, title: this.title }));
+        }
+    }
+    goto(stage, data) {
+        if (this.stopped)
+            return;
+        // ignore non-existent stages
+        if (!this.stages.includes(stage))
+            return;
+        // prevent going to a previous stage
+        if (this.stages.indexOf(stage) < this.stages.indexOf(this.stageTracker.current ?? this.stages[0]))
+            return;
+        this.update(stage, data);
+    }
+    next(data) {
+        if (this.stopped)
+            return;
+        const nextStageIndex = this.stages.indexOf(this.stageTracker.current ?? this.stages[0]) + 1;
+        if (nextStageIndex < this.stages.length) {
+            this.update(this.stages[nextStageIndex], data);
+        }
+    }
+    stop(error) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.stageTracker.refresh(this.stageTracker.current ?? this.stages[0], { hasError: Boolean(error), isStopping: true });
+        if (this.isInCi) {
+            this.ciInstance?.stop(this.stageTracker);
+            return;
+        }
+        if (error) {
+            this.inkInstance?.rerender(React.createElement(Stages, { error: error, hasElapsedTime: this.hasElapsedTime, hasStageTime: this.hasStageTime, postStagesBlock: this.formatKeyValuePairs(this.postStagesBlock), preStagesBlock: this.formatKeyValuePairs(this.preStagesBlock), stageSpecificBlock: this.formatKeyValuePairs(this.stageSpecificBlock), stageTracker: this.stageTracker, timerUnit: this.timerUnit, title: this.title }));
+        }
+        else {
+            this.inkInstance?.rerender(React.createElement(Stages, { hasElapsedTime: this.hasElapsedTime, hasStageTime: this.hasStageTime, postStagesBlock: this.formatKeyValuePairs(this.postStagesBlock), preStagesBlock: this.formatKeyValuePairs(this.preStagesBlock), stageSpecificBlock: this.formatKeyValuePairs(this.stageSpecificBlock), stageTracker: this.stageTracker, timerUnit: this.timerUnit, title: this.title }));
+        }
+        this.inkInstance?.unmount();
+    }
+    [Symbol.dispose]() {
+        this.inkInstance?.unmount();
+    }
+    updateData(data) {
+        if (this.stopped)
+            return;
+        this.data = { ...this.data, ...data };
+        this.update(this.stageTracker.current ?? this.stages[0], data);
+    }
+    formatKeyValuePairs(infoBlock) {
+        return (infoBlock?.map((info) => {
+            const formattedData = info.get ? info.get(this.data) : undefined;
+            return {
+                color: info.color,
+                isBold: info.bold,
+                type: info.type,
+                value: formattedData,
+                ...(info.type === 'message' ? {} : { label: info.label }),
+                ...('stage' in info ? { stage: info.stage } : {}),
+            };
+        }) ?? []);
+    }
+    update(stage, data) {
+        this.data = { ...this.data, ...data };
+        this.stageTracker.refresh(stage);
+        if (this.isInCi) {
+            this.ciInstance?.update(this.stageTracker, this.data);
+        }
+        else {
+            this.inkInstance?.rerender(React.createElement(Stages, { hasElapsedTime: this.hasElapsedTime, hasStageTime: this.hasStageTime, postStagesBlock: this.formatKeyValuePairs(this.postStagesBlock), preStagesBlock: this.formatKeyValuePairs(this.preStagesBlock), stageSpecificBlock: this.formatKeyValuePairs(this.stageSpecificBlock), stageTracker: this.stageTracker, timerUnit: this.timerUnit, title: this.title }));
+        }
+    }
+}

package/lib/components/spinner.d.ts

@@ -0,0 +1,31 @@
+import { type SpinnerName } from 'cli-spinners';
+import React from 'react';
+export type UseSpinnerProps = {
+    /**
+     * Type of a spinner.
+     * See [cli-spinners](https://github.com/sindresorhus/cli-spinners) for available spinners.
+     *
+     * @default dots
+     */
+    readonly type?: SpinnerName;
+};
+export type UseSpinnerResult = {
+    frame: string;
+};
+export declare function useSpinner({ type }: UseSpinnerProps): UseSpinnerResult;
+export type SpinnerProps = UseSpinnerProps & {
+    /**
+     * Label to show near the spinner.
+     */
+    readonly label?: string;
+    readonly isBold?: boolean;
+    readonly labelPosition?: 'left' | 'right';
+};
+export declare function Spinner({ isBold, label, labelPosition, type }: SpinnerProps): React.ReactElement;
+export declare function SpinnerOrError({ error, labelPosition, ...props }: SpinnerProps & {
+    readonly error?: Error;
+}): React.ReactElement;
+export declare function SpinnerOrErrorOrChildren({ children, error, ...props }: SpinnerProps & {
+    readonly children?: React.ReactNode;
+    readonly error?: Error;
+}): React.ReactElement;

package/lib/components/spinner.js

@@ -0,0 +1,59 @@
+import spinners from 'cli-spinners';
+import { Box, Text } from 'ink';
+import React, { useEffect, useState } from 'react';
+import { icons } from '../design-elements.js';
+export function useSpinner({ type = 'dots' }) {
+    const [frame, setFrame] = useState(0);
+    const spinner = spinners[type];
+    useEffect(() => {
+        const timer = setInterval(() => {
+            setFrame((previousFrame) => {
+                const isLastFrame = previousFrame === spinner.frames.length - 1;
+                return isLastFrame ? 0 : previousFrame + 1;
+            });
+        }, spinner.interval);
+        return () => {
+            clearInterval(timer);
+        };
+    }, [spinner]);
+    return {
+        frame: spinner.frames[frame] ?? '',
+    };
+}
+export function Spinner({ isBold, label, labelPosition = 'right', type }) {
+    const { frame } = useSpinner({ type });
+    return (React.createElement(Box, null,
+        label && labelPosition === 'left' && React.createElement(Text, null,
+            label,
+            " "),
+        isBold ? (React.createElement(Text, { bold: true, color: "magenta" }, frame)) : (React.createElement(Text, { color: "magenta" }, frame)),
+        label && labelPosition === 'right' && React.createElement(Text, null,
+            " ",
+            label)));
+}
+export function SpinnerOrError({ error, labelPosition = 'right', ...props }) {
+    if (error) {
+        return (React.createElement(Box, null,
+            props.label && labelPosition === 'left' && React.createElement(Text, null,
+                props.label,
+                " "),
+            React.createElement(Text, { color: "red" }, icons.failed),
+            props.label && labelPosition === 'right' && React.createElement(Text, null,
+                " ",
+                props.label)));
+    }
+    return React.createElement(Spinner, { labelPosition: labelPosition, ...props });
+}
+export function SpinnerOrErrorOrChildren({ children, error, ...props }) {
+    if (children) {
+        return (React.createElement(Box, null,
+            props.label && props.labelPosition === 'left' && React.createElement(Text, null,
+                props.label,
+                " "),
+            children,
+            props.label && props.labelPosition === 'right' && React.createElement(Text, null,
+                " ",
+                props.label)));
+    }
+    return React.createElement(SpinnerOrError, { error: error, ...props });
+}

package/lib/components/timer.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export declare function Timer({ color, isStopped, unit, }: {
+    readonly color?: string;
+    readonly isStopped?: boolean;
+    readonly unit: 'ms' | 's';
+}): React.ReactNode;

package/lib/components/timer.js

@@ -0,0 +1,22 @@
+import { Text } from 'ink';
+import React from 'react';
+import { readableTime } from '../utils.js';
+export function Timer({ color, isStopped, unit, }) {
+    const [time, setTime] = React.useState(0);
+    const [previousDate, setPreviousDate] = React.useState(Date.now());
+    React.useEffect(() => {
+        if (isStopped) {
+            setTime(time + (Date.now() - previousDate));
+            setPreviousDate(Date.now());
+            return () => { };
+        }
+        const intervalId = setInterval(() => {
+            setTime(time + (Date.now() - previousDate));
+            setPreviousDate(Date.now());
+        }, unit === 'ms' ? 1 : 1000);
+        return () => {
+            clearInterval(intervalId);
+        };
+    }, [time, isStopped, previousDate, unit]);
+    return React.createElement(Text, { color: color }, readableTime(time, unit));
+}

package/lib/design-elements.d.ts

@@ -0,0 +1,9 @@
+import { type SpinnerName } from 'cli-spinners';
+export declare const icons: {
+    completed: string;
+    current: string;
+    failed: string;
+    pending: string;
+    skipped: string;
+};
+export declare const spinners: Record<string, SpinnerName>;

package/lib/design-elements.js

@@ -0,0 +1,12 @@
+import figures from 'figures';
+export const icons = {
+    completed: figures.tick,
+    current: figures.play,
+    failed: figures.cross,
+    pending: figures.squareSmallFilled,
+    skipped: figures.circle,
+};
+export const spinners = {
+    info: process.platform === 'win32' ? 'line' : 'arc',
+    stage: process.platform === 'win32' ? 'line' : 'dots2',
+};

package/lib/index.d.ts

@@ -0,0 +1 @@
+export { MultiStageOutput } from './components/multi-stage-output.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { MultiStageOutput } from './components/multi-stage-output.js';

package/lib/stage-tracker.d.ts

@@ -0,0 +1,12 @@
+export type StageStatus = 'pending' | 'current' | 'completed' | 'skipped' | 'failed';
+export declare class StageTracker extends Map<string, StageStatus> {
+    current: string | undefined;
+    private markers;
+    constructor(stages: readonly string[] | string[]);
+    refresh(nextStage: string, opts?: {
+        hasError?: boolean;
+        isStopping?: boolean;
+    }): void;
+    set(stage: string, status: StageStatus): this;
+    private stopMarker;
+}

package/lib/stage-tracker.js

@@ -0,0 +1,63 @@
+import { Performance } from '@oclif/core/performance';
+export class StageTracker extends Map {
+    current;
+    markers = new Map();
+    constructor(stages) {
+        super(stages.map((stage) => [stage, 'pending']));
+    }
+    refresh(nextStage, opts) {
+        const stages = [...this.keys()];
+        for (const stage of stages) {
+            if (this.get(stage) === 'skipped')
+                continue;
+            if (this.get(stage) === 'failed')
+                continue;
+            // .stop() was called with an error => set the stage to failed
+            if (nextStage === stage && opts?.hasError) {
+                this.set(stage, 'failed');
+                this.stopMarker(stage);
+                continue;
+            }
+            // .stop() was called without an error => set the stage to completed
+            if (nextStage === stage && opts?.isStopping) {
+                this.set(stage, 'completed');
+                this.stopMarker(stage);
+                continue;
+            }
+            // set the current stage
+            if (nextStage === stage) {
+                this.set(stage, 'current');
+                // create a marker for the current stage if it doesn't exist
+                if (!this.markers.has(stage)) {
+                    this.markers.set(stage, Performance.mark('MultiStageComponent', stage.replaceAll(' ', '-').toLowerCase()));
+                }
+                continue;
+            }
+            // any stage before the current stage should be marked as skipped if it's still pending
+            if (stages.indexOf(stage) < stages.indexOf(nextStage) && this.get(stage) === 'pending') {
+                this.set(stage, 'skipped');
+                continue;
+            }
+            // any stage before the current stage should be as completed (if it hasn't been marked as skipped or failed yet)
+            if (stages.indexOf(nextStage) > stages.indexOf(stage)) {
+                this.set(stage, 'completed');
+                this.stopMarker(stage);
+                continue;
+            }
+            // default to pending
+            this.set(stage, 'pending');
+        }
+    }
+    set(stage, status) {
+        if (status === 'current') {
+            this.current = stage;
+        }
+        return super.set(stage, status);
+    }
+    stopMarker(stage) {
+        const marker = this.markers.get(stage);
+        if (marker && !marker.stopped) {
+            marker.stop();
+        }
+    }
+}

package/lib/utils.d.ts

@@ -0,0 +1 @@
+export declare function readableTime(time: number, granularity: 's' | 'ms', decimalPlaces?: number): string;

package/lib/utils.js

@@ -0,0 +1,31 @@
+function truncate(value, decimals = 2) {
+    const remainder = value % 1;
+    // truncate remainder to specified decimals
+    const fractionalPart = remainder ? remainder.toString().split('.')[1].slice(0, decimals) : '0'.repeat(decimals);
+    const wholeNumberPart = Math.floor(value).toString();
+    return decimals ? `${wholeNumberPart}.${fractionalPart}` : wholeNumberPart;
+}
+export function readableTime(time, granularity, decimalPlaces = 2) {
+    if (granularity === 's' && time < 1000) {
+        return '< 1s';
+    }
+    const decimals = granularity === 'ms' ? decimalPlaces : 0;
+    // if time < 1000ms, return time in ms
+    if (time < 1000) {
+        return `${time}ms`;
+    }
+    // if time < 60s, return time in seconds
+    if (time < 60_000) {
+        return `${truncate(time / 1000, decimals)}s`;
+    }
+    // if time < 60m, return time in minutes and seconds
+    if (time < 3_600_000) {
+        const minutes = Math.floor(time / 60_000);
+        const seconds = truncate((time % 60_000) / 1000, decimals);
+        return `${minutes}m ${seconds}s`;
+    }
+    // if time >= 60m, return time in hours and minutes
+    const hours = Math.floor(time / 3_600_000);
+    const minutes = Math.floor((time % 3_600_000) / 60_000);
+    return `${hours}h ${minutes}m`;
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@oclif/multi-stage-output",
+  "description": "Terminal output for oclif commands with multiple stages",
+  "version": "0.1.0",
+  "author": "Salesforce",
+  "bugs": "https://github.com/oclif/multi-stage-output/issues",
+  "dependencies": {
+    "@oclif/core": "^4",
+    "change-case": "^5.4.4",
+    "cli-spinners": "^2",
+    "figures": "^6.1.0",
+    "ink": "^5.0.1",
+    "react": "^18.3.1",
+    "terminal-link": "^3.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19",
+    "@oclif/prettier-config": "^0.2.1",
+    "@types/chai": "^4.3.16",
+    "@types/mocha": "^10.0.7",
+    "@types/node": "^18",
+    "@types/react": "^18.3.3",
+    "@types/sinon": "^17.0.3",
+    "chai": "^4.5.0",
+    "commitlint": "^19",
+    "eslint": "^8.57.0",
+    "eslint-config-oclif": "^5.2.0",
+    "eslint-config-oclif-typescript": "^3.1.8",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-config-xo": "^0.45.0",
+    "eslint-config-xo-react": "^0.27.0",
+    "eslint-plugin-react": "^7.34.3",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "husky": "^9.1.3",
+    "ink-testing-library": "^4.0.0",
+    "lint-staged": "^15",
+    "mocha": "^10.7.0",
+    "prettier": "^3.3.3",
+    "shx": "^0.3.4",
+    "sinon": "^18",
+    "strip-ansi": "^7.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "/lib"
+  ],
+  "homepage": "https://github.com/oclif/core",
+  "keywords": [
+    "oclif",
+    "cli",
+    "stages"
+  ],
+  "license": "MIT",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "repository": "oclif/core",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "shx rm -rf lib && tsc",
+    "compile": "tsc",
+    "format": "prettier --write \"+(src|test)/**/*.+(ts|js|json)\"",
+    "lint": "eslint . --ext .ts",
+    "posttest": "yarn lint",
+    "prepack": "yarn run build",
+    "prepare": "husky",
+    "test": "mocha --forbid-only \"test/**/*.test.+(ts|tsx)\" --parallel"
+  },
+  "types": "lib/index.d.ts",
+  "type": "module"
+}