Merge pull request #5992 from Shopify/henry-eh-develop-logs

[Feature] Display UI Extension Logs from Extensibility Host

Author: henryStelle

.changeset/chatty-rats-pull.md

@@ -0,0 +1,6 @@
+---
+'@shopify/ui-extensions-server-kit': minor
+'@shopify/app': minor
+---
+
+Add support for displaying UI Extension dev logs

packages/app/src/cli/services/dev/extension/websocket/handlers.test.ts

@@ -2,15 +2,24 @@ import {
   getConnectionDoneHandler,
   getOnMessageHandler,
   getPayloadUpdateHandler,
+  handleLogEvent,
+  parseLogMessage,
   websocketUpgradeHandler,
 } from './handlers.js'
 import {SetupWebSocketConnectionOptions} from './models.js'
 import {ExtensionsEndpointPayload} from '../payload/models.js'
-import {vi, describe, test, expect} from 'vitest'
+import {vi, describe, test, expect, Mock} from 'vitest'
+import {useConcurrentOutputContext} from '@shopify/cli-kit/node/ui/components'
 import WebSocket, {RawData, WebSocketServer} from 'ws'
 import {IncomingMessage} from 'h3'
+import colors from '@shopify/cli-kit/node/colors'
+import {outputContent, outputToken} from '@shopify/cli-kit/node/output'
 import {Duplex} from 'stream'
 
+vi.mock('@shopify/cli-kit/node/ui/components', () => ({
+  useConcurrentOutputContext: vi.fn(),
+}))
+
 function getMockRequest() {
   const request = {
     url: '/extensions',
@@ -57,6 +66,9 @@ function getMockSetupWebSocketConnectionOptions() {
       updateExtensions: vi.fn(),
     },
     manifestVersion: '3',
+    stdout: {
+      write: vi.fn(),
+    },
   } as unknown as SetupWebSocketConnectionOptions
 }
 
@@ -183,4 +195,134 @@ describe('getOnMessageHandler()', () => {
     }) as unknown as RawData
     wss.clients.forEach((ws) => expect(ws.send).toHaveBeenCalledWith(outgoingMessage))
   })
+
+  test('on an incoming log event calls handleLogMessage and does not notify clients', () => {
+    const wss = getMockWebsocketServer()
+    const options = getMockSetupWebSocketConnectionOptions()
+    const data = JSON.stringify({
+      event: 'log',
+      data: {
+        type: 'info',
+        message: 'Test log message',
+        extensionName: 'test-extension',
+      },
+    }) as unknown as RawData
+
+    getOnMessageHandler(wss, options)(data)
+
+    // Verify useConcurrentOutputContext (any therefore handleLogMessage) was called with correct parameters
+    expect(useConcurrentOutputContext).toHaveBeenCalledWith(
+      {outputPrefix: 'test-extension', stripAnsi: false},
+      expect.any(Function),
+    )
+
+    // Verify no client messages were sent since this was a log event
+    wss.clients.forEach((ws) => expect(ws.send).not.toHaveBeenCalled())
+  })
+})
+
+describe('parseLogMessage()', () => {
+  test('parses and formats JSON array of strings', () => {
+    const message = JSON.stringify(['Hello', 'world', 'test'], null, 2)
+    const result = parseLogMessage(message)
+    expect(result).toBe('Hello world test')
+  })
+
+  test('parses and formats JSON array with mixed types', () => {
+    const message = JSON.stringify(['String', 42, true, null], null, 2)
+    const result = parseLogMessage(message)
+    expect(result).toBe('String 42 true null')
+  })
+
+  test('parses and formats JSON array with objects', () => {
+    const object = {user: 'john', age: 30}
+    const message = JSON.stringify(['Message:', object], null, 2)
+    const result = parseLogMessage(message)
+    expect(result).toBe(outputContent`Message: ${outputToken.json(object)}`.value)
+  })
+
+  test('returns original message when JSON parsing fails', () => {
+    const invalidJson = 'This is not JSON'
+    const result = parseLogMessage(invalidJson)
+    expect(result).toBe('This is not JSON')
+  })
+
+  test('returns original message for JSON that is not an array', () => {
+    const malformedJson = '{"invalid": json}'
+    const result = parseLogMessage(malformedJson)
+    expect(result).toBe('{"invalid": json}')
+  })
+})
+
+describe('handleLogEvent()', () => {
+  // Helper function to abstract the common expect pattern
+  function expectLogMessageOutput(
+    extensionName: string,
+    expectedOutput: string,
+    options: SetupWebSocketConnectionOptions,
+  ) {
+    expect(useConcurrentOutputContext).toHaveBeenCalledWith(
+      {outputPrefix: extensionName, stripAnsi: false},
+      expect.any(Function),
+    )
+    const contextCallback = (useConcurrentOutputContext as Mock).mock.calls[0]?.[1]
+    contextCallback()
+
+    expect(options.stdout.write).toHaveBeenCalledWith(expectedOutput)
+  }
+
+  test('outputs info level log message with correct formatting', () => {
+    const options = getMockSetupWebSocketConnectionOptions()
+    const eventData = {
+      type: 'info',
+      message: 'Test info message',
+      extensionName: 'test-extension',
+    }
+    handleLogEvent(eventData, options)
+
+    expectLogMessageOutput('test-extension', `Test info message`, options)
+  })
+
+  test('outputs log message with parsed JSON array', () => {
+    const options = getMockSetupWebSocketConnectionOptions()
+    const message = JSON.stringify(['Hello', 'world', {user: 'test'}], null, 2)
+    const eventData = {
+      type: 'info',
+      message,
+      extensionName: 'test-extension',
+    }
+
+    handleLogEvent(eventData, options)
+
+    expectLogMessageOutput(
+      'test-extension',
+      outputContent`Hello world ${outputToken.json({user: 'test'})}`.value,
+      options,
+    )
+  })
+
+  test('outputs error level log message with error formatting', () => {
+    const options = getMockSetupWebSocketConnectionOptions()
+    const eventData = {
+      type: 'error',
+      message: 'Test error message',
+      extensionName: 'error-extension',
+    }
+
+    handleLogEvent(eventData, options)
+
+    expectLogMessageOutput('error-extension', `${colors.bold.redBright('ERROR')}: Test error message`, options)
+  })
+
+  test('handles unknown log type without erroring', () => {
+    const options = getMockSetupWebSocketConnectionOptions()
+    const eventData = {
+      type: 'unknown-type',
+      message: 'Message with unknown log type',
+      extensionName: 'test-extension',
+    }
+    handleLogEvent(eventData, options)
+
+    expectLogMessageOutput('test-extension', 'UNKNOWN-TYPE: Message with unknown log type', options)
+  })
 })

packages/app/src/cli/services/dev/extension/websocket/handlers.ts

@@ -1,12 +1,14 @@
 import {
   EventType,
   IncomingDispatchMessage,
+  LogPayload,
   OutgoingDispatchMessage,
   OutgoingMessage,
   SetupWebSocketConnectionOptions,
 } from './models.js'
 import {RawData, WebSocket, WebSocketServer} from 'ws'
 import {outputDebug, outputContent, outputToken} from '@shopify/cli-kit/node/output'
+import {useConcurrentOutputContext} from '@shopify/cli-kit/node/ui/components'
 import {IncomingMessage} from 'http'
 import {Duplex} from 'stream'
 
@@ -37,6 +39,63 @@ export function getConnectionDoneHandler(wss: WebSocketServer, options: SetupWeb
   }
 }
 
+export function parseLogMessage(message: string): string {
+  try {
+    const parsed = JSON.parse(message)
+
+    // it is expected that the message is an array of console arguments
+    if (!Array.isArray(parsed)) {
+      return message
+    }
+
+    const formatted = parsed
+      .map((arg) => {
+        if (typeof arg === 'object' && arg !== null) {
+          return outputToken.json(arg).output()
+        } else {
+          return String(arg)
+        }
+      })
+      .join(' ')
+
+    return outputContent`${formatted}`.value
+  } catch (error) {
+    // If parsing fails, return the original message
+    if (error instanceof SyntaxError) {
+      return message
+    }
+    throw error
+  }
+}
+
+const consoleTypeColors = {
+  debug: (text: string) => outputToken.gray(text),
+  warn: (text: string) => outputToken.yellow(text),
+  error: (text: string) => outputToken.errorText(text),
+} as const
+
+function getOutput({type, message}: LogPayload) {
+  const formattedMessage = parseLogMessage(message)
+
+  switch (type) {
+    case 'debug':
+    case 'warn':
+    case 'error':
+      return outputContent`${consoleTypeColors[type](type.toUpperCase())}: ${formattedMessage}`.value
+    case 'log':
+    case 'info':
+      return formattedMessage
+    default:
+      return `${type.toUpperCase()}: ${formattedMessage}`
+  }
+}
+
+export function handleLogEvent(eventData: LogPayload, options: SetupWebSocketConnectionOptions) {
+  useConcurrentOutputContext({outputPrefix: eventData.extensionName, stripAnsi: false}, () => {
+    options.stdout.write(getOutput(eventData))
+  })
+}
+
 export function getOnMessageHandler(wss: WebSocketServer, options: SetupWebSocketConnectionOptions) {
   return (data: RawData) => {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -50,7 +109,7 @@ ${outputToken.json(eventData)}
       options.stdout,
     )
 
-    if (eventType === 'update') {
+    if (eventType === EventType.Update) {
       const payloadStoreApiKey = options.payloadStore.getRawPayload().app.apiKey
       const eventAppApiKey = eventData.app?.apiKey
 
@@ -68,10 +127,12 @@ ${outputToken.json(eventData)}
       if (eventData.extensions) {
         options.payloadStore.updateExtensions(eventData.extensions)
       }
-    } else if (eventType === 'dispatch') {
+    } else if (eventType === EventType.Dispatch) {
       const outGoingMessage = getOutgoingDispatchMessage(jsonData, options)
 
       notifyClients(wss, outGoingMessage, options)
+    } else if (eventType === EventType.Log) {
+      handleLogEvent(eventData, options)
     }
   }
 }

packages/app/src/cli/services/dev/extension/websocket/models.ts

@@ -4,6 +4,7 @@ import {Server} from 'http'
 export enum EventType {
   Update = 'update',
   Dispatch = 'dispatch',
+  Log = 'log',
 }
 
 type DataType = 'focus' | 'unfocus'
@@ -42,3 +43,9 @@ export interface OutgoingMessage {
   version: string
   data: {[key: string]: unknown}
 }
+
+export interface LogPayload {
+  type: string
+  message: string
+  extensionName: string
+}