feat(toolkit-lib): `withListeners` API for IoHost by sai-ray · Pull Request #1708 · aws/aws-cdk-cli

sai-ray · 2026-07-07T14:03:14Z

The CLI's CliIoHost has a listener mechanism that's private and welded to that one class. Programmatic toolkit-lib users have no way to observe or reshape what flows through their IoHost short of writing a whole custom host.

This PR extracts that engine into a shared ListenerRegistry and adds a public withListeners(host) wrapper, so listeners can be attached to any IIoHost:

 const host = withListeners(new NonInteractiveIoHost());
 host.on('CDK_TOOLKIT_I2901', (m) => { count += (m.data as StackDetailsPayload).stacks.length; });  // observe
 host.on((m) => m.level === 'warn', (m) => { warnings++; });                                        // or by predicate
 const toolkit = new Toolkit({ ioHost: host });

A listener can observe a message (on/once), rewrite its text (rewrite/rewriteOnce), suppress it, or answer a prompt (respond/respondOnce), and each registration returns a disposer. CliIoHost is refactored to delegate to the same ListenerRegistry, so there's one implementation of matching/ordering/rewriting/request-answering instead of two.

The additions users interact with:

withListeners(host) and its return type IoHostWithListeners.
MessagePredicate for matching on anything other than a single code.
MessageListenerResult, MessageListenerResultOrPromise

Listeners are keyed on a message code string (IoMessageCode, e.g. 'CDK_TOOLKIT_I2901') or a predicate. msg.data is delivered as unknown; cast it to the payload interface documented for that code in the message registry.

Checklist

This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
- Release notes for the new version:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

codecov-commenter · 2026-07-07T15:05:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.39%. Comparing base (9bf08e5) to head (13bcf0a).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1708      +/-   ##
==========================================
- Coverage   89.59%   89.39%   -0.20%     
==========================================
  Files          77       77              
  Lines       11758    11552     -206     
  Branches     1651     1624      -27     
==========================================
- Hits        10534    10327     -207     
- Misses       1195     1197       +2     
+ Partials       29       28       -1

Flag	Coverage Δ
suite.unit	`89.39% <100.00%> (-0.20%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-07-07T17:18:52Z

Total lines changed 1101 is greater than 1000. Please consider breaking this PR down.

mrgrain · 2026-07-08T11:38:51Z

Nope, these are private on purpose. Do not export them.

Done. MessageInfo, CodeInfo, ActionLessMessage, ActionLessRequest are all un-exported again, and IO and the maker types are off the public barrel too. Nothing maker internal is public now

mrgrain · 2026-07-08T11:39:55Z

+ */
+export type MessageSelector<T> =
+  | IoMessageMaker<T>
+  | IoRequestMaker<T, any>


These are not public types, nor should they be. We can accept string here (a single code) or a new MessageMatcher class (via IMessageMatcher). We can make the MessageMakers implement that interface so we can keep passing them in.

Went with the string option. The public selector is now IoMessageCode (a single code) or a (msg) => boolean predicate, so it no longer references the maker types. I tried the IMessageMatcher route first but dropped it. To keep the typed maker path it wanted, IO would have to be public, and exporting IO pulls the maker internal types back onto the public surface through the same forgotten export cascade with api extractor. With IO private there's also no way for an external caller to obtain an IMessageMatcher. CliIoHost keeps passing makers internally through the private registry unchanged.

yes there is, the CLI is a privileged caller that can use private exports from toolkit-lib.

In either case I don't understand why it's not possible. Can you share the IMessageMatcher interface you attempted?

mrgrain · 2026-07-10T13:44:12Z

+ */
+export type MessageSelector<T> =
+  | IoMessageMaker<T>
+  | IoRequestMaker<T, any>


yes there is, the CLI is a privileged caller that can use private exports from toolkit-lib.

In either case I don't understand why it's not possible. Can you share the IMessageMatcher interface you attempted?

mrgrain · 2026-07-10T13:45:21Z

+   * ```
+   */
+  rewrite(
+    code: IoMessageCode,


why no predicate?

mrgrain · 2026-07-10T13:46:36Z

+   * const dispose = host.respond('CDK_TOOLKIT_I7010', true);
+   * ```
+   */
+  respond(code: IoMessageCode, value: unknown, suppressQuestion?: boolean): () => void;


I know is copied from what we currently have, but for a public API we need to think more careful about the design. If we ever want to add an other option this gets messy. We can preemptively put suppressQuestion in a property bag (options).

mrgrain · 2026-07-10T13:46:55Z

+export function withListeners(host: IIoHost): IoHostWithListeners {
+  return new ListeningIoHost(host);
+}


Not sure I love this, but I guess it doesn't hurt either. 🤷🏻

mrgrain · 2026-07-10T13:48:16Z

+ * codes are listed in the message registry:
+ * https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/
+ */
+export interface IoHostWithListeners extends IIoHost {


do we need to extend the IIoHost interface? Or is IoEmitter a separate independent interface?

mrgrain · 2026-07-10T13:49:32Z

+ * const toolkit = new Toolkit({ ioHost: host });
+ * ```
+ */
+export function withListeners(host: IIoHost): IoHostWithListeners {


We have this, we can at least make this a generic type so that the inner host keeps its higher fidelity.

mrgrain · 2026-07-10T13:51:03Z

+  public on<T>(
+    selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>),
+    listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise,
+  ): () => void;
+  public on(
+    predicate: (msg: IoMessage<any>) => boolean,
+    listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise,
+  ): () => void;
+  public on(selector: MessageSelector<any>, listener: MessageListenerFn): () => void {


since this is a private class, it feels strange to have so many different signatures. But I guess thats because we couldn't make IIoMessageMatcher yet.

chore: midwork

74815a5

sai-ray temporarily deployed to automation July 7, 2026 14:03 — with GitHub Actions Inactive

aws-cdk-automation requested a review from a team July 7, 2026 14:03

sai-ray temporarily deployed to no-approval July 7, 2026 14:03 — with GitHub Actions Inactive

github-actions Bot added the p2 label Jul 7, 2026

sai-ray changed the title ~~feat(toolkit-lib): public withListeners API for IoHost~~ feat(toolkit-lib): public withListeners API for IoHost Jul 7, 2026

aws-cdk-automation enabled auto-merge July 7, 2026 14:03

sai-ray changed the title ~~feat(toolkit-lib): public withListeners API for IoHost~~ feat(toolkit-lib): withListeners API for IoHost Jul 7, 2026

sai-ray temporarily deployed to run-tests July 7, 2026 14:07 — with GitHub Actions Inactive

sai-ray temporarily deployed to run-tests July 7, 2026 14:58 — with GitHub Actions Inactive

sai-ray added the pr/exempt-size-check Skips PR size check label Jul 7, 2026

chore: keep AbsentData off public API

bca9162

sai-ray temporarily deployed to no-approval July 7, 2026 18:25 — with GitHub Actions Inactive

sai-ray temporarily deployed to run-tests July 7, 2026 18:27 — with GitHub Actions Inactive

mrgrain requested changes Jul 8, 2026

View reviewed changes

sai-ray added 2 commits July 9, 2026 01:12

chore: midwork

f9e68aa

Merge branch 'main' into sai/iohost-public-listener-api

e9a6c1b

mrgrain requested changes Jul 10, 2026

View reviewed changes

sai-ray added 3 commits July 10, 2026 16:58

chore: midwork

b9195c5

chore: midwork

48b3b31

chore: midwork

13bcf0a

Uh oh!

Conversation

sai-ray commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

codecov-commenter commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sai-ray commented Jul 7, 2026 •

edited

Loading

codecov-commenter commented Jul 7, 2026 •

edited

Loading