From b95cb9b3347ed378741e25b48ac98f9ad9e6ff90 Mon Sep 17 00:00:00 2001
From: Andrey Avtomonov <7889985+andreybavt@users.noreply.github.com>
Date: Tue, 12 May 2026 11:32:49 +0200
Subject: [PATCH] feat(cli): formalize dev-friendly result output

---
 packages/cli/src/io/print-list.ts | 15 ++++++++++++---
 packages/cli/src/sl.test.ts       | 12 ++++++++++--
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/packages/cli/src/io/print-list.ts b/packages/cli/src/io/print-list.ts
index b66fa7ad..d2129d7d 100644
--- a/packages/cli/src/io/print-list.ts
+++ b/packages/cli/src/io/print-list.ts
@@ -28,6 +28,16 @@ export interface PrintListArgs<Row> {
   io: KtxCliIo;
 }
 
+export interface KtxJsonResultEnvelope<T> {
+  kind: string;
+  data: T;
+  meta?: Record<string, unknown>;
+}
+
+export function writeJsonResult<T>(io: KtxCliIo, envelope: KtxJsonResultEnvelope<T>): void {
+  io.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}
+
 export function printList<Row extends object>(args: PrintListArgs<Row>): void {
   switch (args.mode) {
     case 'json':
@@ -61,12 +71,11 @@ function printListPlain<Row extends object>(args: PrintListArgs<Row>): void {
 }
 
 function printListJson<Row extends object>(args: PrintListArgs<Row>): void {
-  const envelope = {
+  writeJsonResult(args.io, {
     kind: 'list',
     data: { items: args.rows },
     meta: { command: args.command },
-  };
-  args.io.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  });
 }
 
 function pluralize(count: number, singular: string): string {
diff --git a/packages/cli/src/sl.test.ts b/packages/cli/src/sl.test.ts
index bd746b0b..8752d0ec 100644
--- a/packages/cli/src/sl.test.ts
+++ b/packages/cli/src/sl.test.ts
@@ -398,10 +398,18 @@ joins: []
       listIo.io,
     );
     expect(code).toBe(0);
+    expect(listIo.stderr()).toBe('');
 
     const parsed = JSON.parse(listIo.stdout());
-    expect(parsed.kind).toBe('list');
-    expect(parsed.meta).toEqual({ command: 'sl list' });
+    expect(parsed).toMatchObject({
+      kind: 'list',
+      data: {
+        items: expect.any(Array),
+      },
+      meta: {
+        command: 'sl list',
+      },
+    });
     expect(parsed.data.items).toHaveLength(1);
     expect(parsed.data.items[0]).toMatchObject({
       connectionId: 'warehouse',