@363045841yyt/klinechart-ai-runtime 0.1.0

package/src/__tests__/chartBridge.integration.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, afterAll, beforeEach } from 'vitest'
+import { WebSocketServer, type WebSocket } from 'ws'
+import { ChartBridge } from '@363045841yyt/klinechart-core'
+
+const PORT = 9877
+const wss = new WebSocketServer({ port: PORT, host: '127.0.0.1' })
+
+const receivedMessages: unknown[] = []
+let serverWs: WebSocket | null = null
+
+wss.on('connection', (ws) => {
+  serverWs = ws
+  ws.on('message', (raw) => {
+    const msg = JSON.parse(raw.toString())
+    receivedMessages.push(msg)
+
+    if (msg.type === 'register') {
+      ws.send(JSON.stringify({ type: 'registered', sessionId: msg.sessionId }))
+    }
+  })
+})
+
+afterAll(() => {
+  wss.close()
+})
+
+describe('ChartBridge integration', { timeout: 10_000 }, () => {
+  beforeEach(() => {
+    receivedMessages.length = 0
+  })
+
+  it('connects and registers with server', async () => {
+    const bridge = new ChartBridge({
+      wsUrl: `ws://127.0.0.1:${PORT}`,
+      sessionId: 'bridge-test',
+      autoReconnect: false,
+    })
+
+    await bridge.connect()
+    await new Promise((r) => setTimeout(r, 100))
+
+    const regMsg = receivedMessages.find(
+      (m: unknown) => (m as { type: string }).type === 'register',
+    ) as { sessionId: string } | undefined
+    expect(regMsg).toBeDefined()
+    expect(regMsg!.sessionId).toBe('bridge-test')
+
+    bridge.disconnect()
+  })
+
+  it('sends state update', async () => {
+    const bridge = new ChartBridge({
+      wsUrl: `ws://127.0.0.1:${PORT}`,
+      sessionId: 'state-push-test',
+      autoReconnect: false,
+    })
+
+    await bridge.connect()
+    await new Promise((r) => setTimeout(r, 100))
+
+    bridge.sendStateUpdate({
+      testController: {
+        controllerId: 'testController',
+        summary: 'Test state',
+        facts: { value: 42 },
+      },
+    })
+
+    await new Promise((r) => setTimeout(r, 100))
+    const stateMsg = receivedMessages.find(
+      (m: unknown) => (m as { type: string }).type === 'state:update',
+    )
+    expect(stateMsg).toBeDefined()
+    expect(
+      (stateMsg as { descriptions: Record<string, unknown> }).descriptions
+        .testController,
+    ).toBeDefined()
+
+    bridge.disconnect()
+  })
+
+  it('auto-generates sessionId when not provided', () => {
+    const bridge = new ChartBridge({
+      wsUrl: `ws://127.0.0.1:${PORT}`,
+      autoReconnect: false,
+    })
+    expect(bridge.sessionId).toBeDefined()
+    expect(bridge.sessionId.length).toBeGreaterThan(0)
+    bridge.disconnect()
+  })
+
+  it('isSafe to call destroy multiple times', () => {
+    const bridge = new ChartBridge({
+      wsUrl: `ws://127.0.0.1:${PORT}`,
+      autoReconnect: false,
+    })
+    bridge.destroy()
+    bridge.destroy()
+  })
+})

package/src/__tests__/describeControllers.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest'
+import {
+  describeVolumeProfileState,
+  describeAnchoredVwap,
+  describeFootprintLatestBar,
+  describeAlerts,
+} from '../describeControllers'
+
+describe('describeVolumeProfileState', () => {
+  it('handles null state with a clear summary', () => {
+    const d = describeVolumeProfileState(null)
+    expect(d.controllerId).toBe('volumeProfile')
+    expect(d.summary).toMatch(/has not been computed/)
+    expect(d.facts.ready).toBe(false)
+  })
+
+  it('produces a summary for populated state', () => {
+    const d = describeVolumeProfileState({
+      poc: 67_500,
+      vah: 68_200,
+      val: 66_800,
+      totalVolume: 1000,
+      vaVolume: 700,
+    })
+    const wordCount = d.summary.split(/\s+/).length
+    expect(wordCount).toBeGreaterThanOrEqual(20)
+    expect(wordCount).toBeLessThanOrEqual(100)
+    expect(d.facts.poc).toBe(67_500)
+    expect(d.facts.vaPercent).toBeCloseTo(70.0, 1)
+  })
+})
+
+describe('describeAnchoredVwap', () => {
+  it('reports zero anchors', () => {
+    const d = describeAnchoredVwap([], 100)
+    expect(d.facts.count).toBe(0)
+  })
+
+  it('flags overextension when price is above 1sigma upper', () => {
+    const d = describeAnchoredVwap(
+      [
+        {
+          label: 'Earnings Q1',
+          barIndex: 100,
+          vwap: 100,
+          upper1: 105,
+          lower1: 95,
+          upper2: 110,
+          lower2: 90,
+        },
+      ],
+      120,
+    )
+    expect(d.summary).toMatch(/overextended/)
+  })
+
+  it('flags overextension below 1sigma lower', () => {
+    const d = describeAnchoredVwap(
+      [
+        {
+          label: 'Earnings Q1',
+          barIndex: 100,
+          vwap: 100,
+          upper1: 105,
+          lower1: 95,
+          upper2: 110,
+          lower2: 90,
+        },
+      ],
+      80,
+    )
+    expect(d.summary).toMatch(/overextended/)
+  })
+
+  it('does NOT flag when price is inside the 1sigma band', () => {
+    const d = describeAnchoredVwap(
+      [
+        {
+          label: 'Earnings Q1',
+          barIndex: 100,
+          vwap: 100,
+          upper1: 105,
+          lower1: 95,
+          upper2: 110,
+          lower2: 90,
+        },
+      ],
+      102,
+    )
+    expect(d.summary).not.toMatch(/overextended/)
+  })
+})
+
+describe('describeFootprintLatestBar', () => {
+  it('handles null bar', () => {
+    const d = describeFootprintLatestBar(null, 0)
+    expect(d.facts.ready).toBe(false)
+  })
+
+  it('labels buy-dominated bars', () => {
+    const d = describeFootprintLatestBar(
+      {
+        barIndex: 42,
+        delta: 250,
+        totalVolume: 1000,
+        imbalanceCount: 0,
+        maxImbalanceRatio: 0,
+      },
+      500,
+    )
+    expect(d.facts.tone).toBe('buy-dominated')
+  })
+
+  it('labels sell-dominated bars', () => {
+    const d = describeFootprintLatestBar(
+      {
+        barIndex: 42,
+        delta: -250,
+        totalVolume: 1000,
+        imbalanceCount: 0,
+        maxImbalanceRatio: 0,
+      },
+      -500,
+    )
+    expect(d.facts.tone).toBe('sell-dominated')
+  })
+
+  it('summarises imbalances correctly', () => {
+    const d = describeFootprintLatestBar(
+      {
+        barIndex: 42,
+        delta: 100,
+        totalVolume: 1000,
+        imbalanceCount: 3,
+        maxImbalanceRatio: 5.5,
+      },
+      100,
+    )
+    expect(d.summary).toMatch(/3 diagonal imbalance/)
+    expect(d.summary).toMatch(/5\.5×/)
+  })
+})
+
+describe('describeAlerts', () => {
+  it('zero rules', () => {
+    const d = describeAlerts({
+      rulesEnabled: 0,
+      rulesTotal: 0,
+      recentEventsCount: 0,
+    })
+    expect(d.summary).toBe('No alert rules configured.')
+  })
+
+  it('counts enabled vs total', () => {
+    const d = describeAlerts({
+      rulesEnabled: 3,
+      rulesTotal: 5,
+      recentEventsCount: 2,
+    })
+    expect(d.summary).toMatch(/3 of 5 alert rules/)
+    expect(d.facts.recentEventsCount).toBe(2)
+  })
+})

package/src/__tests__/executeTool.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { ChartController } from '@363045841yyt/klinechart-core'
+import { executeTool } from '../executeTool'
+
+function createMockChart(
+  overrides?: Partial<ChartController>,
+): ChartController {
+  return {
+    catalog: [
+      { id: 'MA', label: 'MA', role: 'main' as const, params: [] },
+      { id: 'RSI', label: 'RSI', role: 'sub' as const, params: [] },
+    ],
+    zoomToLevel: vi.fn(),
+    setTheme: vi.fn(),
+    addIndicator: vi.fn(() => 'inst-1'),
+    removeIndicator: vi.fn(() => true),
+    updateIndicatorParams: vi.fn(() => true),
+    getZoomLevelCount: vi.fn(() => 10),
+    getData: vi.fn(() => []),
+    ...overrides,
+  } as unknown as ChartController
+}
+
+describe('executeTool', () => {
+  it('returns error for unknown tool name', () => {
+    const chart = createMockChart()
+    const result = executeTool(chart, {
+      name: 'chart.nonexistent',
+      input: {},
+    })
+    expect(result.success).toBe(false)
+    expect(result.error).toMatch(/Unknown tool/)
+  })
+
+  describe('chart.zoomToLevel', () => {
+    it('calls chart.zoomToLevel with level only', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'chart.zoomToLevel',
+        input: { level: 5 },
+      })
+      expect(chart.zoomToLevel).toHaveBeenCalledWith(5, undefined)
+      expect(result.success).toBe(true)
+    })
+
+    it('calls chart.zoomToLevel with level and anchorX', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'chart.zoomToLevel',
+        input: { level: 3, anchorX: 200 },
+      })
+      expect(chart.zoomToLevel).toHaveBeenCalledWith(3, 200)
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('chart.setTheme', () => {
+    it('calls chart.setTheme with light', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'chart.setTheme',
+        input: { theme: 'light' },
+      })
+      expect(chart.setTheme).toHaveBeenCalledWith('light')
+      expect(result.success).toBe(true)
+    })
+
+    it('calls chart.setTheme with dark', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'chart.setTheme',
+        input: { theme: 'dark' },
+      })
+      expect(chart.setTheme).toHaveBeenCalledWith('dark')
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('indicators.add', () => {
+    it('looks up role from catalog and delegates', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'indicators.add',
+        input: { definitionId: 'MA' },
+      })
+      expect(chart.addIndicator).toHaveBeenCalledWith('MA', 'main')
+      expect(result.success).toBe(true)
+      expect(result.data).toEqual({ instanceId: 'inst-1' })
+    })
+
+    it('uses sub role when catalog says sub', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'indicators.add',
+        input: { definitionId: 'RSI' },
+      })
+      expect(chart.addIndicator).toHaveBeenCalledWith('RSI', 'sub')
+      expect(result.success).toBe(true)
+    })
+
+    it('falls back to main role for unknown definitionId', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'indicators.add',
+        input: { definitionId: 'BOLL' },
+      })
+      expect(chart.addIndicator).toHaveBeenCalledWith('BOLL', 'main')
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('indicators.remove', () => {
+    it('returns success when chart.removeIndicator returns true', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'indicators.remove',
+        input: { instanceId: 'inst-1' },
+      })
+      expect(chart.removeIndicator).toHaveBeenCalledWith('inst-1')
+      expect(result.success).toBe(true)
+    })
+
+    it('returns error when chart.removeIndicator returns false', () => {
+      const chart = createMockChart({ removeIndicator: vi.fn(() => false) })
+      const result = executeTool(chart, {
+        name: 'indicators.remove',
+        input: { instanceId: 'ghost' },
+      })
+      expect(result.success).toBe(false)
+      expect(result.error).toMatch(/ghost/)
+    })
+  })
+
+  describe('indicators.updateParams', () => {
+    it('returns success when chart.updateIndicatorParams returns true', () => {
+      const chart = createMockChart()
+      const result = executeTool(chart, {
+        name: 'indicators.updateParams',
+        input: { instanceId: 'inst-1', params: { period: 50 } },
+      })
+      expect(chart.updateIndicatorParams).toHaveBeenCalledWith('inst-1', {
+        period: 50,
+      })
+      expect(result.success).toBe(true)
+    })
+
+    it('returns error when chart.updateIndicatorParams returns false', () => {
+      const chart = createMockChart({
+        updateIndicatorParams: vi.fn(() => false),
+      })
+      const result = executeTool(chart, {
+        name: 'indicators.updateParams',
+        input: { instanceId: 'ghost', params: {} },
+      })
+      expect(result.success).toBe(false)
+      expect(result.error).toMatch(/ghost/)
+    })
+  })
+
+  describe('alerts.* — not implemented', () => {
+    const tools = ['alerts.addPriceCross', 'alerts.addIndicatorCross', 'alerts.remove']
+
+    for (const name of tools) {
+      it(`returns not-implemented for ${name}`, () => {
+        const chart = createMockChart()
+        const result = executeTool(chart, { name, input: {} })
+        expect(result.success).toBe(false)
+        expect(result.error).toMatch(/not implemented/)
+        expect(result.error).toMatch(/alerts controller/)
+      })
+    }
+  })
+
+  describe('replay.* — not implemented', () => {
+    const tools = ['replay.seekTo', 'replay.play', 'replay.pause', 'replay.setSpeed']
+
+    for (const name of tools) {
+      it(`returns not-implemented for ${name}`, () => {
+        const chart = createMockChart()
+        const result = executeTool(chart, { name, input: {} })
+        expect(result.success).toBe(false)
+        expect(result.error).toMatch(/not implemented/)
+        expect(result.error).toMatch(/replay controller/)
+      })
+    }
+  })
+})

package/src/__tests__/mcpServer.integration.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, afterAll } from 'vitest'
+import { WebSocket } from 'ws'
+import { createMcpServer } from '../mcpServer'
+
+const PORT = 9876
+
+const server = createMcpServer({
+  serverInfo: { name: 'test', version: '1.0.0' },
+  ws: { port: PORT, host: '127.0.0.1' },
+})
+
+afterAll(async () => {
+  await server.stop()
+})
+
+function connectClient(sessionId = 'test-session'): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${PORT}`)
+    const timeout = setTimeout(() => {
+      ws.close()
+      reject(new Error('connectClient timeout'))
+    }, 3000)
+
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ type: 'register', sessionId }))
+    })
+
+    ws.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString())
+        if (msg.type === 'registered' && msg.sessionId === sessionId) {
+          clearTimeout(timeout)
+          resolve(ws)
+        }
+      } catch {
+        // ignore parse errors during connect
+      }
+    })
+
+    ws.on('error', (err) => {
+      clearTimeout(timeout)
+      reject(err)
+    })
+  })
+}
+
+function waitForMessage(ws: WebSocket, timeout = 3000): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Timeout')), timeout)
+    ws.once('message', (raw) => {
+      clearTimeout(timer)
+      try {
+        resolve(JSON.parse(raw.toString()))
+      } catch {
+        reject(new Error('Failed to parse WS message'))
+      }
+    })
+  })
+}
+
+describe('mcpServer WebSocket integration', { timeout: 10_000 }, () => {
+  it('accepts registration and replies with registered', async () => {
+    const ws = await connectClient('reg-test')
+    expect(server.registry.has('reg-test')).toBe(true)
+    ws.close()
+  })
+
+  it('registers session in the registry', async () => {
+    const ws = await connectClient('registry-test')
+    expect(server.registry.has('registry-test')).toBe(true)
+    ws.close()
+  })
+
+  it('removes session on disconnect', async () => {
+    const ws = await connectClient('disconnect-test')
+    ws.close()
+    await new Promise((r) => setTimeout(r, 150))
+    expect(server.registry.has('disconnect-test')).toBe(false)
+  })
+
+  it('forwards tool:call and receives tool:result', async () => {
+    const ws = await connectClient('tool-test')
+    const handle = server.registry.get('tool-test')!
+
+    const resultPromise = handle.executeTool({
+      name: 'chart.zoomToLevel',
+      input: { level: 5 },
+    })
+
+    const msg = (await waitForMessage(ws)) as {
+      type: string
+      requestId: string
+      call: { name: string; input: Record<string, unknown> }
+    }
+    expect(msg.type).toBe('tool:call')
+    expect(msg.call.name).toBe('chart.zoomToLevel')
+    expect(msg.call.input).toEqual({ level: 5 })
+
+    ws.send(
+      JSON.stringify({
+        type: 'tool:result',
+        requestId: msg.requestId,
+        result: { success: true },
+      }),
+    )
+
+    const result = await resultPromise
+    expect(result.success).toBe(true)
+    ws.close()
+  })
+
+  it('accepts state:update and caches it', async () => {
+    const ws = await connectClient('state-test')
+
+    ws.send(
+      JSON.stringify({
+        type: 'state:update',
+        descriptions: {
+          vp: {
+            controllerId: 'vp',
+            summary: 'Test VP state',
+            facts: { ready: true },
+          },
+        },
+      }),
+    )
+
+    await new Promise((r) => setTimeout(r, 100))
+    const state = server.registry.getState('state-test')
+    expect(state?.vp?.summary).toBe('Test VP state')
+    ws.close()
+  })
+
+  it('handles multiple concurrent sessions', async () => {
+    const ws1 = await connectClient('multi-1')
+    const ws2 = await connectClient('multi-2')
+
+    expect(server.registry.getActiveSessionIds()).toContain('multi-1')
+    expect(server.registry.getActiveSessionIds()).toContain('multi-2')
+
+    ws1.close()
+    ws2.close()
+    await new Promise((r) => setTimeout(r, 150))
+    expect(server.registry.has('multi-1')).toBe(false)
+    expect(server.registry.has('multi-2')).toBe(false)
+  })
+
+  it('rejects invalid JSON gracefully', async () => {
+    const ws = await connectClient('invalid-test')
+    ws.send('not json')
+    await new Promise((r) => setTimeout(r, 50))
+    expect(server.registry.has('invalid-test')).toBe(true)
+    ws.close()
+  })
+})

package/src/__tests__/mcpServer.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import { createMcpServer } from '../mcpServer'
+import { SessionRegistry } from '../sessionRegistry'
+
+describe('createMcpServer', () => {
+  it('returns server components', () => {
+    const instance = createMcpServer({
+      ws: { port: 0 },
+    })
+    expect(instance.server).toBeDefined()
+    expect(instance.registry).toBeDefined()
+    expect(instance.wss).toBeDefined()
+    expect(typeof instance.start).toBe('function')
+    expect(typeof instance.stop).toBe('function')
+  })
+
+  it('uses provided registry', () => {
+    const registry = new SessionRegistry()
+    const instance = createMcpServer({ registry, ws: { port: 0 } })
+    expect(instance.registry).toBe(registry)
+  })
+
+  it('accepts custom server info', () => {
+    const instance = createMcpServer({
+      serverInfo: { name: 'custom', version: '2.0.0' },
+      ws: { port: 0 },
+    })
+    expect(instance.server).toBeDefined()
+  })
+})