Add JSON progress and retry support to task runners

[gonzaloriestra]

WHY are these changes introduced?

Task lists need to run without terminal UI in JSON mode, and progress consumers need to see retries and final failures.

WHAT is this pull request doing?

Run renderTasks without Ink in JSON mode while preserving shared context, subtasks, retries, and skipped tasks. Both task runners emit retry and failure events, and renderSingleTask gains an optional retry count that defaults to zero.

Theme commands adopt this support higher in the stack.

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• Added a minor changeset for the public cli-kit additions.

[fredericoo]

one more thing: since this changes the behaviour of a public cli-kit API for every plugin (not just theme commands), could the changeset in #8682 get a line for @shopify/cli-kit along the lines of "renderTasks runs without Ink and emits JSON progress events in JSON mode"? Right now it only mentions theme commands, so plugin authors wouldn't know.

[isaacroldan]

Just a minor comment about the onComplete

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/private/node/ui/tasks.d.ts

import { TokenizedString } from '../../../public/node/output.js';
export interface Task<TContext = unknown> {
    title: string | TokenizedString;
    task: (ctx: TContext, task: Task<TContext>) => Promise<void | Task<TContext>[]>;
    retry?: number;
    retryCount?: number;
    errors?: Error[];
    skip?: (ctx: TContext) => boolean;
}
export declare function runTasks<TContext>(tasks: Task<TContext>[], onTask?: (task: Task<TContext>) => void): Promise<TContext>;

Existing type declarations

packages/cli-kit/dist/public/common/command-events.d.ts

@@ -23,14 +23,14 @@ export declare const commandDiagnosticEventSchema: z.ZodObject<{
 export declare const commandProgressEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"progress">;
     timestamp: z.ZodString;
-    status: z.ZodEnum<["started", "updated", "completed"]>;
+    status: z.ZodEnum<["started", "updated", "retrying", "completed", "failed"]>;
     operation: z.ZodString;
     message: z.ZodOptional<z.ZodString>;
     current: z.ZodOptional<z.ZodNumber>;
     total: z.ZodOptional<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     type: "progress";
-    status: "started" | "updated" | "completed";
+    status: "started" | "updated" | "retrying" | "completed" | "failed";
     timestamp: string;
     operation: string;
     message?: string | undefined;
@@ -38,7 +38,7 @@ export declare const commandProgressEventSchema: z.ZodObject<{
     total?: number | undefined;
 }, {
     type: "progress";
-    status: "started" | "updated" | "completed";
+    status: "started" | "updated" | "retrying" | "completed" | "failed";
     timestamp: string;
     operation: string;
     message?: string | undefined;
@@ -67,14 +67,14 @@ export declare const commandEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }>, z.ZodObject<{
     type: z.ZodLiteral<"progress">;
     timestamp: z.ZodString;
-    status: z.ZodEnum<["started", "updated", "completed"]>;
+    status: z.ZodEnum<["started", "updated", "retrying", "completed", "failed"]>;
     operation: z.ZodString;
     message: z.ZodOptional<z.ZodString>;
     current: z.ZodOptional<z.ZodNumber>;
     total: z.ZodOptional<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     type: "progress";
-    status: "started" | "updated" | "completed";
+    status: "started" | "updated" | "retrying" | "completed" | "failed";
     timestamp: string;
     operation: string;
     message?: string | undefined;
@@ -82,7 +82,7 @@ export declare const commandEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
     total?: number | undefined;
 }, {
     type: "progress";
-    status: "started" | "updated" | "completed";
+    status: "started" | "updated" | "retrying" | "completed" | "failed";
     timestamp: string;
     operation: string;
     message?: string | undefined;

packages/cli-kit/dist/public/node/command-events.d.ts

@@ -29,14 +29,14 @@ export declare const commandEventOutputSchema: import("./json-output-schema.js")
 }>, import("zod").ZodObject<{
     type: import("zod").ZodLiteral<"progress">;
     timestamp: import("zod").ZodString;
-    status: import("zod").ZodEnum<["started", "updated", "completed"]>;
+    status: import("zod").ZodEnum<["started", "updated", "retrying", "completed", "failed"]>;
     operation: import("zod").ZodString;
     message: import("zod").ZodOptional<import("zod").ZodString>;
     current: import("zod").ZodOptional<import("zod").ZodNumber>;
     total: import("zod").ZodOptional<import("zod").ZodNumber>;
 }, "strict", import("zod").ZodTypeAny, {
     type: "progress";
-    status: "started" | "updated" | "completed";
+    status: "started" | "updated" | "retrying" | "completed" | "failed";
     timestamp: string;
     operation: string;
     message?: string | undefined;
@@ -44,7 +44,7 @@ export declare const commandEventOutputSchema: import("./json-output-schema.js")
     total?: number | undefined;
 }, {
     type: "progress";
-    status: "started" | "updated" | "completed";
+    status: "started" | "updated" | "retrying" | "completed" | "failed";
     timestamp: string;
     operation: string;
     message?: string | undefined;

packages/cli-kit/dist/public/node/ui.d.ts

@@ -318,6 +318,8 @@ export declare function renderTasks<TContext>(tasks: Task<TContext>[], { renderO
 export interface RenderSingleTaskOptions<T> {
     title: TokenizedString;
     task: (updateStatus: (status: TokenizedString) => void) => Promise<T>;
+    /** The number of additional attempts after a failure. Defaults to zero. */
+    retry?: number;
     onAbort?: () => void;
     renderOptions?: RenderOptions;
 }
@@ -326,12 +328,13 @@ export interface RenderSingleTaskOptions<T> {
  * @param options - Configuration object
  * @param options.title - The initial title to display with the loading bar
  * @param options.task - The async task to execute. Receives an updateStatus callback to change the displayed title.
+ * @param options.retry - The number of additional attempts after a failure. Defaults to zero.
  * @param options.renderOptions - Optional render configuration
  * @returns The result of the task
  * @example
  * Loading app ...
  */
-export declare function renderSingleTask<T>({ title, task, onAbort, renderOptions, }: RenderSingleTaskOptions<T>): Promise<T>;
+export declare function renderSingleTask<T>({ title, task, retry, onAbort, renderOptions, }: RenderSingleTaskOptions<T>): Promise<T>;
 export interface RenderTextPromptOptions extends Omit<TextPromptProps, 'onSubmit'> {
     renderOptions?: RenderOptions;
 }

packages/cli-kit/dist/private/node/ui/hooks/use-async-and-unmount.d.ts

@@ -1,6 +1,6 @@
-interface Options {
-    onFulfilled?: () => unknown;
+interface Options<T> {
+    onFulfilled?: (result: T) => unknown;
     onRejected?: (error: Error) => void;
 }
-export default function useAsyncAndUnmount(asyncFunction: () => Promise<unknown>, { onFulfilled, onRejected }?: Options): void;
+export default function useAsyncAndUnmount<T>(asyncFunction: () => Promise<T>, { onFulfilled, onRejected }?: Options<T>): void;
 export {};
\ No newline at end of file

packages/cli-kit/dist/private/node/ui/components/Tasks.d.ts

@@ -1,14 +1,7 @@
 import { AbortSignal } from '../../../../public/node/abort.js';
-import { TokenizedString } from '../../../../public/node/output.js';
+import { Task } from '../tasks.js';
 import React from 'react';
-export interface Task<TContext = unknown> {
-    title: string | TokenizedString;
-    task: (ctx: TContext, task: Task<TContext>) => Promise<void | Task<TContext>[]>;
-    retry?: number;
-    retryCount?: number;
-    errors?: Error[];
-    skip?: (ctx: TContext) => boolean;
-}
+export type { Task } from '../tasks.js';
 interface TasksProps<TContext> {
     tasks: Task<TContext>[];
     silent?: boolean;