aws-cdk 2.1128.0 → 2.1129.0

package/lib/cli/io-host/cli-io-host.d.ts

@@ -1,7 +1,7 @@
 import type { Agent } from 'node:https';
 import { RequireApproval } from '@aws-cdk/cloud-assembly-schema';
 import type { IIoHost, IoMessage, IoMessageCode, IoMessageLevel, IoRequest, ToolkitAction } from '@aws-cdk/toolkit-lib';
-import type { IoHelper, IoMessageMaker, IoDefaultMessages } from '../../../lib/api-private';
+import type { IoHelper, IoMessageMaker, IoRequestMaker, IoDefaultMessages } from '../../../lib/api-private';
 import type { Context } from '../../api/context';
 import { StackActivityProgress } from '../../commands/deploy';
 import { TelemetrySession } from '../telemetry/session';
@@ -72,9 +72,9 @@ export type TargetStream = 'stdout' | 'stderr' | 'drop';
 /**
  * The result a message listener may return to influence how a message is handled.
  *
- * A listener can only update the message _text_; it cannot change any other
- * field of the message (such as its `code`), which keeps the code-keyed
- * listener registry valid.
+ * A listener may update the message _text_ and/or its _level_; it cannot change
+ * any other field of the message (such as its `code`), which keeps the
+ * code-keyed listener registry valid.
  */
 export interface MessageListenerResult {
     /**
@@ -84,16 +84,113 @@ export interface MessageListenerResult {
      */
     readonly message?: string;
     /**
-     * Skip the default processing of the message, i.e. do not write it to a stream.
+     * Override the level of this message.
+     *
+     * The new level is used for both verbosity filtering and stream selection, so
+     * this can move a message between stdout/stderr (e.g. downgrade a `result` to
+     * `info`). The `code` is intentionally left unchanged.
+     *
+     * @default - the message level is left unchanged
+     */
+    readonly level?: IoMessageLevel;
+    /**
+     * Skip the default handling of the message.
+     *
+     * For a notification this means it is not written to a stream. For a request
+     * it stops processing entirely: the user is not prompted, nothing is written,
+     * and the request resolves with its (possibly `respond`-overridden) default
+     * response.
      *
      * @default false
      */
     readonly preventDefault?: boolean;
+    /**
+     * For requests only: the value to resolve the request with. It is folded into
+     * the request's default response and skips the prompt (the request is treated
+     * as not promptable). The question is still written unless `preventDefault` is
+     * also set. Ignored for plain notifications.
+     *
+     * The presence of the key is what matters, so `false`/`0`/`''` are valid
+     * answers. Use the `respond`/`respondOnce` helpers for the common case.
+     *
+     * @default - this listener does not supply a response
+     */
+    readonly respond?: unknown;
+}
+/**
+ * What a message listener may return: nothing, a `MessageListenerResult`, or a
+ * `Promise` of either.
+ *
+ * Listeners may be async. The host awaits each listener before running the
+ * next, so registration order — and the cumulative effect on the message — is
+ * preserved regardless of whether listeners are sync or async.
+ */
+export type MessageListenerResultOrPromise = void | MessageListenerResult | Promise<void | MessageListenerResult>;
+/**
+ * Selects which messages a listener applies to.
+ *
+ * Either a message/request *maker* — the listener fires for messages with that
+ * maker's `code` (the original behavior) — or a custom *predicate* over the
+ * message. A maker's `.is` type guard (e.g. `IO.CDK_TOOLKIT_I7010.is`) is a
+ * convenient predicate, but any `(msg) => boolean` works (e.g. to match a family
+ * of codes, or on the message level).
+ */
+export type MessageSelector<T> = IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => boolean);
+/**
+ * How an IoHost processed a single message or request.
+ *
+ * This describes the message *as the host handled it*, which can differ from
+ * what was emitted: listeners may rewrite the text or level, prevent it from
+ * being written at all, or (for requests) answer it on the user's behalf.
+ *
+ * Both notifications (`notify`) and requests (`requestResponse`) are reported,
+ * so an observer sees the complete, ordered stream the host handled. Use
+ * `type` to tell them apart.
+ */
+export interface IoMessageObservation {
+    /**
+     * Whether this observation describes a plain notification (`notify`) or a
+     * request that asked for a response (`requestResponse`).
+     */
+    readonly type: 'notify' | 'request';
+    /**
+     * The message exactly as it was emitted to the host (before any listeners).
+     */
+    readonly emitted: IoMessage<unknown>;
+    /**
+     * The message after the host's listeners ran (text and/or level may differ).
+     */
+    readonly effective: IoMessage<unknown>;
+    /**
+     * Whether a listener prevented this message from being written, i.e. the user
+     * would not see it. Always `false` for requests (a request is reported once
+     * it has been resolved, regardless of how it was answered).
+     */
+    readonly dropped: boolean;
+}
+/**
+ * An IoHost whose message handling can be observed.
+ *
+ * This is a CLI-internal contract used by tests to record the *effective*,
+ * user-facing message stream (after listeners) without reaching into host
+ * internals. It is intentionally separate from `IIoHost` so that the recorder
+ * can work with any `IIoHost` and only enrich its output when the host also
+ * implements this interface.
+ */
+export interface ObservableIoHost {
+    /**
+     * Register an observer that is invoked for every message the host handles —
+     * both notifications and requests — with the disposition the host computed
+     * for it (its effective form after listeners and whether it was dropped). For
+     * a request, the resolved answer is the effective message's `defaultResponse`.
+     * Returns a function that removes the observer again.
+     */
+    observeMessages(observer: (observation: IoMessageObservation) => void): () => void;
 }
 /**
  * A simple IO host for the CLI that writes messages to the console.
  */
-export declare class CliIoHost implements IIoHost {
+export declare class CliIoHost implements IIoHost, ObservableIoHost {
     /**
      * Returns the singleton instance
      */
@@ -142,6 +239,8 @@ export declare class CliIoHost implements IIoHost {
     private corkedCounter;
     private readonly corkedLoggingBuffer;
     private readonly messageListeners;
+    private readonly messageObservers;
+    private corkReplaying;
     private readonly autoRespond;
     /**
      * The telemetry session object
@@ -178,51 +277,108 @@ export declare class CliIoHost implements IIoHost {
      *
      * The listener may return a `MessageListenerResult` to update the message
      * text and/or prevent the default processing (writing it to a stream);
-     * returning nothing leaves the message untouched. Returns a function that
-     * removes the listener again.
+     * returning nothing leaves the message untouched. The listener may be async
+     * (return a `Promise`); the host awaits it before processing the message
+     * further. Returns a function that removes the listener again.
      *
      * @example
-     * const dispose = ioHost.on(IO.CDK_TOOLKIT_I2901, (msg) => {
+     * const dispose = ioHost.on(IO.CDK_TOOLKIT_I2901, async (msg) => {
      *   myCount += msg.data.stacks.length;
+     *   await persist(myCount);
      * });
+     *
+     * @example
+     * // Match with a custom predicate instead of a code, e.g. a maker's `.is`:
+     * const dispose = ioHost.on(IO.CDK_TOOLKIT_I7010.is, (msg) => ({ respond: true }));
+     */
+    on<T>(selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>), listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise): () => void;
+    on(predicate: (msg: IoMessage<any>) => boolean, listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise): () => void;
+    /**
+     * Register an observer that is invoked for every message the host handles —
+     * both notifications and requests — with the disposition the host computed
+     * for it (its effective form after listeners and whether it was dropped). For
+     * a request, the resolved answer is the effective message's `defaultResponse`.
+     * Returns a function that removes the observer.
+     *
+     * @see ObservableIoHost
      */
-    on<T>(code: IoMessageMaker<T>, listener: (msg: IoMessage<T>) => void | MessageListenerResult): () => void;
+    observeMessages(observer: (observation: IoMessageObservation) => void): () => void;
     /**
      * Like `on`, but the listener is automatically removed after it has been
      * invoked once.
      */
-    once<T>(code: IoMessageMaker<T>, listener: (msg: IoMessage<T>) => void | MessageListenerResult): () => void;
+    once<T>(selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>), listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise): () => void;
+    once(predicate: (msg: IoMessage<any>) => boolean, listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise): () => void;
+    /**
+     * Remove every message listener registered via `on`/`once`/`rewrite`/`respond`.
+     *
+     * The host's own internal listeners (such as stack-activity routing) are kept,
+     * so the host keeps working afterwards. Message observers registered via
+     * `observeMessages` are a separate mechanism and are not affected.
+     *
+     * This is mainly useful for tests that share the singleton host and need to
+     * reset listener state between cases (a leftover listener would otherwise
+     * leak into the next test).
+     */
+    removeAllListeners(): void;
+    /**
+     * Answer a request (by its code) on the user's behalf with a fixed value, so
+     * the host does not prompt. Syntactic sugar for an `on` listener returning
+     * `{ respond: value, preventDefault: suppressQuestion }`; for conditional
+     * answers or to also reword the question, use `on`/`once` directly. Returns a
+     * function that removes the responder again.
+     *
+     * @param suppressQuestion - whether to also suppress writing the question text.
+     *   Defaults to `true` (answer silently). Pass `false` to still surface the
+     *   question while answering it.
+     *
+     * @example
+     * // Under --force, auto-confirm the destroy prompt without prompting.
+     * const dispose = ioHost.respond(IO.CDK_TOOLKIT_I7010, true);
+     */
+    respond<T, U>(code: IoRequestMaker<T, U>, value: U, suppressQuestion?: boolean): () => void;
+    /**
+     * Like `respond`, but the answer is given only once and then removed.
+     */
+    respondOnce<T, U>(code: IoRequestMaker<T, U>, value: U, suppressQuestion?: boolean): () => void;
     /**
      * Register a formatter that replaces the printed text of messages with the
      * given code. This lets a caller define _how_ a toolkit message is presented
      * without the IoHost needing to know about it.
      *
-     * Syntactic sugar for an `on` listener that returns `{ message }`. Returns a
-     * function that removes the formatter again.
+     * Optionally pass a `level` to also override the message's level (which moves
+     * it between stdout/stderr and changes verbosity filtering). For the rarer
+     * case of overriding only the level, use `on`/`once` returning `{ level }`.
+     *
+     * Syntactic sugar for an `on` listener that returns `{ message, level? }`.
+     * Returns a function that removes the formatter again.
      *
      * @example
      * const dispose = ioHost.rewrite(IO.CDK_TOOLKIT_I2901, (msg) =>
      *   serializeStructure(msg.data.stacks, true));
      */
-    rewrite<T>(code: IoMessageMaker<T>, formatter: (msg: IoMessage<T>) => string): () => void;
+    rewrite<T>(code: IoMessageMaker<T> | IoRequestMaker<T, any>, formatter: (msg: IoMessage<T>) => string, level?: IoMessageLevel): () => void;
     /**
      * Like `rewrite`, but the formatter is automatically removed after it has
      * been applied once.
      */
-    rewriteOnce<T>(code: IoMessageMaker<T>, formatter: (msg: IoMessage<T>) => string): () => void;
+    rewriteOnce<T>(code: IoMessageMaker<T> | IoRequestMaker<T, any>, formatter: (msg: IoMessage<T>) => string, level?: IoMessageLevel): () => void;
     /**
      * Add a listener to the registry and return a function that removes it.
      */
     private addMessageListener;
     /**
-     * Run all registered listeners for a message's code, in registration order.
+     * Run every registered listener that matches the message, in registration
+     * order. A listener matches by its code (maker) or its custom predicate.
      *
-     * A listener may update the message text (which is passed on to subsequent
-     * listeners and the rest of the pipeline) and/or request that the default
-     * processing be skipped. `once` listeners are removed after they have run.
+     * A listener may update the message text/level (passed on to subsequent
+     * listeners and the rest of the pipeline), prevent the default processing, or
+     * (for requests) answer it. `once` listeners are removed after they have run.
+     * Matching is decided against the message as emitted, so a rewrite by an
+     * earlier listener does not change which later listeners apply.
      *
-     * Returns the (possibly text-updated) message and whether any listener
-     * prevented the default processing.
+     * Returns the (possibly updated) message, whether the default processing was
+     * prevented, and whether a listener answered the request (and with what).
      */
     private applyMessageListeners;
     /**
@@ -230,6 +386,18 @@ export declare class CliIoHost implements IIoHost {
      * The caller waits until the notification completes.
      */
     notify(msg: IoMessage<unknown>): Promise<void>;
+    /**
+     * Notify every registered message observer of how a message or request was
+     * handled. A no-op when nothing is observing (i.e. outside of tests), so the
+     * surrounding hot paths pay nothing in production.
+     */
+    private notifyObservers;
+    /**
+     * Write a (already listener-processed) message to its target stream, honoring
+     * the log level and corked-logging buffer. Shared by `notify` and the
+     * non-prompting `requestResponse` path.
+     */
+    private writeMessage;
     private maybeEmitTelemetry;
     /**
      * Route stack-activity messages to the activity printer (progress bar or
@@ -256,10 +424,21 @@ export declare class CliIoHost implements IIoHost {
     /**
      * Notifies the host of a message that requires a response.
      *
-     * If the host does not return a response the suggested
-     * default response from the input message will be used.
+     * Registered listeners run first: a listener may reword the question (its text
+     * or level) or answer it outright via `respond` (e.g. `--force` auto-confirms
+     * a destroy). If no listener answers and the host cannot prompt, the suggested
+     * default response is used.
      */
     requestResponse<DataType, ResponseType>(msg: IoRequest<DataType, ResponseType>): Promise<ResponseType>;
+    /**
+     * Resolve a request to its response: a listener's answer if one was given,
+     * otherwise the answer prompted from the user, otherwise the suggested
+     * default when the host cannot prompt.
+     *
+     * Kept separate from `requestResponse` so the response can be observed in a
+     * single place regardless of which of these paths produced it.
+     */
+    private resolveRequest;
     /**
      * Formats a message for console output with optional color support
      */
@@ -273,3 +452,12 @@ export declare class CliIoHost implements IIoHost {
      */
     private makeActivityPrinter;
 }
+/**
+ * Combine several selectors into a single predicate that matches a message when
+ * *any* of them matches. Each selector may be a maker (matched by its `code`)
+ * or a predicate.
+ *
+ * Useful for one listener that spans multiple codes, e.g.
+ * `ioHost.on(matchAny(IO.CDK_TOOLKIT_I5501, IO.CDK_TOOLKIT_I5502), listener)`.
+ */
+export declare function matchAny(...selectors: MessageSelector<any>[]): (msg: IoMessage<unknown>) => boolean;