Add command side event infrastructure

[gonzaloriestra]

WHY are these changes introduced?

Closes shop/issues-develop#23661

Finite commands need structured diagnostics and progress that remain separate from their final result.

Based on prototypes:

• Prototype store info diagnostic event sink #8241
• Prototype JSON event streaming for app dev #8315

WHAT is this pull request doing?

• Adds typed diagnostic and progress events with timestamps.
• Adds an AsyncLocalStorage-backed event context for each command execution.
• Wraps the full CLI lifecycle so prerun hooks, command services, and postrun hooks share the same context, with BaseCommand covering direct command runs.
• Automatically converts standard info, warning, debug, success, and completion output into diagnostic events in JSON mode.
• Makes renderSingleTask emit start, status, and completion progress events automatically.
• Keeps outputResult on stdout and suppresses standalone newlines in JSON mode.
• Keeps custom loggers, text output, and concurrent command executions isolated.

How to test your changes?

See #8415

Also: pnpm shopify app info --json --verbose

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
• This internal infrastructure change does not require a changeset.

[gonzaloriestra]

• Add typed JSON output to store authentication #8443
• Add typed JSON output to store inspection #8442
• Add typed JSON output to store creation #8441
• Add JSON schema flag to commands #8413
• Require JSON support for new commands #8406
• Emit fatal errors as JSON #8405
• Add JSON result schema infrastructure #8404
• Add command side event infrastructure #8403 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[dmerand]

This is a really clever approach. I have a few questions to iron out before we ship.

[amcaplan]

Nit: Isn't this basically testing command-event-context behavior? If so, doesn't it belong in a command-event-context.test.ts file?

[amcaplan]

This seems like just a passthrough, what do we gain through an explicit call instead of just re-exporting?

[amcaplan]

This pattern is unusual for our codebase. We have other patterns for lazy-creating globals; usually we do it in a function so loading a file has no side effects; this also has the benefit of keeping types simple because the function can more easily guarantee a return type.

[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/command-event-context.d.ts

import { type CommandEvent, type CommandEventChannelOptions, type CommandEventEmissionOptions, type CommandEventInput } from '../../public/common/command-events.js';
export type CommandEventOutputMode = 'text' | 'json';
interface RunWithCommandEventsOptions extends CommandEventChannelOptions<CommandEvent> {
    outputMode?: CommandEventOutputMode;
}
/**
 * Runs a command execution with an event channel available to all nested asynchronous work.
 *
 * @param options - The event sink, clock, and output mode used by the channel.
 * @param execute - The command execution to run with the channel.
 * @returns The result of the command execution.
 */
export declare function runWithCommandEvents<TResult>(options: RunWithCommandEventsOptions, execute: () => TResult): TResult;
/**
 * Emits an event for the current command execution.
 *
 * Events emitted outside a command execution are ignored.
 *
 * @param event - The event to emit before its timestamp is added.
 * @param options - Presentation details that are not included in the event.
 */
export declare function emitCommandEvent(event: CommandEventInput, options?: CommandEventEmissionOptions): void;
/**
 * Returns how command events are presented for the current execution.
 *
 * @returns The current event output mode, or undefined outside a command event context.
 */
export declare function commandEventOutputMode(): CommandEventOutputMode | undefined;
export {};

packages/cli-kit/dist/private/node/command-event-output.d.ts

import { type CommandEvent } from '../../public/common/command-events.js';
/**
 * Writes a command event as JSON without routing it back through the command event context.
 *
 * @param event - The event to write.
 */
export declare function outputCommandEventAsJson(event: CommandEvent): void;

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

import { z } from 'zod';
/** Schema for a diagnostic emitted while a command executes. */
export declare const commandDiagnosticEventSchema: z.ZodObject<{
    type: z.ZodLiteral<"diagnostic">;
    timestamp: z.ZodString;
    level: z.ZodEnum<["debug", "info", "warning", "error"]>;
    message: z.ZodString;
    code: z.ZodOptional<z.ZodString>;
}, "strict", z.ZodTypeAny, {
    type: "diagnostic";
    message: string;
    timestamp: string;
    level: "info" | "error" | "debug" | "warning";
    code?: string | undefined;
}, {
    type: "diagnostic";
    message: string;
    timestamp: string;
    level: "info" | "error" | "debug" | "warning";
    code?: string | undefined;
}>;
/** Schema for a progress update emitted while a command executes. */
export declare const commandProgressEventSchema: z.ZodObject<{
    type: z.ZodLiteral<"progress">;
    timestamp: z.ZodString;
    status: z.ZodEnum<["started", "updated", "completed"]>;
    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";
    timestamp: string;
    operation: string;
    message?: string | undefined;
    current?: number | undefined;
    total?: number | undefined;
}, {
    type: "progress";
    status: "started" | "updated" | "completed";
    timestamp: string;
    operation: string;
    message?: string | undefined;
    current?: number | undefined;
    total?: number | undefined;
}>;
/** Schema for side events emitted while a command executes. */
export declare const commandEventSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
    type: z.ZodLiteral<"diagnostic">;
    timestamp: z.ZodString;
    level: z.ZodEnum<["debug", "info", "warning", "error"]>;
    message: z.ZodString;
    code: z.ZodOptional<z.ZodString>;
}, "strict", z.ZodTypeAny, {
    type: "diagnostic";
    message: string;
    timestamp: string;
    level: "info" | "error" | "debug" | "warning";
    code?: string | undefined;
}, {
    type: "diagnostic";
    message: string;
    timestamp: string;
    level: "info" | "error" | "debug" | "warning";
    code?: string | undefined;
}>, z.ZodObject<{
    type: z.ZodLiteral<"progress">;
    timestamp: z.ZodString;
    status: z.ZodEnum<["started", "updated", "completed"]>;
    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";
    timestamp: string;
    operation: string;
    message?: string | undefined;
    current?: number | undefined;
    total?: number | undefined;
}, {
    type: "progress";
    status: "started" | "updated" | "completed";
    timestamp: string;
    operation: string;
    message?: string | undefined;
    current?: number | undefined;
    total?: number | undefined;
}>]>;
/** A diagnostic emitted while a command executes. */
export type CommandDiagnosticEvent = z.infer<typeof commandDiagnosticEventSchema>;
/** A progress update emitted while a command executes. */
export type CommandProgressEvent = z.infer<typeof commandProgressEventSchema>;
/** A side event emitted while a command executes. */
export type CommandEvent = z.infer<typeof commandEventSchema>;
/** An event before its emission timestamp is added. */
export type CommandEventInput<TEvent extends CommandEvent = CommandEvent> = TEvent extends unknown ? Omit<TEvent, 'timestamp'> : never;
/** Presentation details that are not included in the emitted event. */
export interface CommandEventEmissionOptions {
    /** The event is already visible in the command's text UI. */
    alreadyRendered?: boolean;
}
/** Receives one timestamped event from a command execution. */
export type CommandEventSink<TEvent extends CommandEvent = CommandEvent> = (event: TEvent, options?: CommandEventEmissionOptions) => void;
/** Emits timestamped side events from one command execution. */
export interface CommandEventChannel<TEvent extends CommandEvent = CommandEvent> {
    emit: (event: CommandEventInput<TEvent>, options?: CommandEventEmissionOptions) => void;
}
/** Supplies the current time when an event is emitted. */
export type CommandEventClock = () => Date;
/** Options for a command event channel. */
export interface CommandEventChannelOptions<TEvent extends CommandEvent> {
    sink?: CommandEventSink<TEvent>;
    clock?: CommandEventClock;
}
/**
 * Creates a synchronous, execution-scoped channel for command side events.
 * Adapters validate events at their output boundary; the channel preserves domain-specific event fields.
 *
 * @param options - The event sink and clock used by the channel.
 * @returns A channel that adds an ISO timestamp before synchronously delivering each event.
 */
export declare function createCommandEventChannel<TEvent extends CommandEvent = CommandEvent>(options?: CommandEventChannelOptions<TEvent>): CommandEventChannel<TEvent>;

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

import { type CommandEvent, type CommandEventChannelOptions, type CommandEventEmissionOptions, type CommandEventInput } from '../common/command-events.js';
import { type CommandEventOutputMode } from '../../private/node/command-event-context.js';
export type { CommandEventOutputMode } from '../../private/node/command-event-context.js';
interface RunWithCommandEventsOptions extends CommandEventChannelOptions<CommandEvent> {
    outputMode?: CommandEventOutputMode;
}
/**
 * Runs a command execution with an event channel available to all nested asynchronous work.
 *
 * @param options - The event sink, clock, and output mode used by the channel.
 * @param execute - The command execution to run with the channel.
 * @returns The result of the command execution.
 */
export declare function runWithCommandEvents<TResult>(options: RunWithCommandEventsOptions, execute: () => TResult): TResult;
/**
 * Runs the complete CLI lifecycle with the event presentation selected by its arguments.
 *
 * @param argv - The command arguments used to determine whether JSON output is enabled.
 * @param execute - The command lifecycle to run.
 * @returns The result of the command lifecycle.
 */
export declare function runWithCommandEventsForCommand<TResult>(argv: string[], execute: () => TResult): TResult;
/**
 * Emits an event for the current command execution.
 *
 * Events emitted outside a command execution are ignored.
 *
 * @param event - The event to emit before its timestamp is added.
 * @param options - Presentation details that are not included in the event.
 */
export declare function emitCommandEvent(event: CommandEventInput, options?: CommandEventEmissionOptions): void;
/**
 * Returns how command events are presented for the current execution.
 *
 * @returns The current event output mode, or undefined outside a command event context.
 */
export declare function commandEventOutputMode(): CommandEventOutputMode | undefined;
/**
 * Renders a command side event to stderr using the existing CLI output behavior.
 *
 * @param event - The event to render.
 */
export declare function renderCommandEvent(event: CommandEvent): void;
/**
 * Renders a command side event as compact JSON to stderr.
 *
 * @param event - The event to render.
 */
export declare function renderCommandEventAsJson(event: CommandEvent): void;

Existing type declarations

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

@@ -18,6 +18,7 @@ declare abstract class BaseCommand extends Command {
     catch(error: Error & {
         skipOclifErrorHandling: boolean;
     }): Promise<void>;
+    protected _run<T>(): Promise<T>;
     protected init(): Promise<unknown>;
     protected showNpmFlagWarning(): void;
     protected exitWithTimestampWhenEnvVariablePresent(): void;

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

@@ -42,9 +42,10 @@ export declare function getIdentityTokenInformation(): {
  * Checks if the JSON output is enabled via flag (--json or -j) or environment variable (SHOPIFY_FLAG_JSON).
  *
  * @param environment - Process environment variables.
+ * @param argv - Command arguments to inspect for JSON flags.
  * @returns True if the JSON output is enabled, false otherwise.
  */
-export declare function jsonOutputEnabled(environment?: NodeJS.ProcessEnv): boolean;
+export declare function jsonOutputEnabled(environment?: NodeJS.ProcessEnv, argv?: string[]): boolean;
 /**
  * If true, the CLI should not use the network level retry.
  *