@agentstage/bridge 0.1.0

package/src/sdk/BridgeClient.ts

@@ -0,0 +1,203 @@
+import WebSocket from 'ws';
+import type { BridgeEvent, SetStateOptions, StateSnapshot, StoreDescription, StoreSummary } from '../shared/types.js';
+
+export type { BridgeEvent, StoreDescription, StoreSummary, StateSnapshot };
+
+export class BridgeClient {
+  private ws: WebSocket | null = null;
+  private url: string;
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 5;
+  private reconnectDelay = 1000;
+  private eventHandlers = new Set<(event: BridgeEvent) => void>();
+  private pendingRequests = new Map<number, { resolve: (v: unknown) => void; reject: (e: unknown) => void }>();
+  private requestId = 0;
+  private subscribedStores = new Set<string>();
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.url + '?type=client');
+
+      this.ws.on('open', () => {
+        this.reconnectAttempts = 0;
+
+        for (const storeId of this.subscribedStores) {
+          this.send({ type: 'subscribe', payload: { storeId } });
+        }
+
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        this.handleMessage(data.toString());
+      });
+
+      this.ws.on('close', () => {
+        this.attemptReconnect();
+      });
+
+      this.ws.on('error', (err) => {
+        reject(err);
+      });
+    });
+  }
+
+  private attemptReconnect(): void {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      return;
+    }
+
+    this.reconnectAttempts++;
+
+    setTimeout(() => {
+      this.connect().catch(() => {});
+    }, this.reconnectDelay * this.reconnectAttempts);
+  }
+
+  private send(message: unknown): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+
+  private handleMessage(data: string): void {
+    try {
+      const msg = JSON.parse(data);
+
+      if (msg.id !== undefined && this.pendingRequests.has(msg.id)) {
+        const pending = this.pendingRequests.get(msg.id)!;
+        this.pendingRequests.delete(msg.id);
+
+        if (msg.error) {
+          pending.reject(new Error(msg.error.message || msg.error));
+        } else {
+          pending.resolve(msg.result);
+        }
+        return;
+      }
+
+      if (msg.type) {
+        switch (msg.type) {
+          case 'store.stateChanged':
+            this.emit({
+              type: 'stateChanged',
+              storeId: msg.payload.storeId,
+              state: msg.payload.state,
+              version: msg.payload.version,
+              source: msg.payload.source,
+            });
+            break;
+
+          case 'store.disconnected':
+            this.emit({
+              type: 'disconnected',
+              storeId: msg.payload.storeId,
+              reason: msg.payload.reason,
+            });
+            this.subscribedStores.delete(msg.payload.storeId);
+            break;
+
+          case 'store.registered':
+            this.emit({
+              type: 'connected',
+              storeId: msg.payload.storeId,
+              pageId: msg.payload.pageId,
+              storeKey: msg.payload.storeKey,
+            });
+            break;
+        }
+      }
+    } catch {
+      // Ignore malformed messages from unknown clients.
+    }
+  }
+
+  private emit(event: BridgeEvent): void {
+    for (const handler of this.eventHandlers) {
+      handler(event);
+    }
+  }
+
+  onEvent(handler: (event: BridgeEvent) => void): () => void {
+    this.eventHandlers.add(handler);
+    return () => this.eventHandlers.delete(handler);
+  }
+
+  private async request<T>(method: string, params: unknown): Promise<T> {
+    const id = ++this.requestId;
+
+    return new Promise<T>((resolve, reject) => {
+      this.pendingRequests.set(id, {
+        resolve: (v) => resolve(v as T),
+        reject: (e) => reject(e),
+      });
+      this.send({ id, method, params });
+
+      setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          reject(new Error('Request timeout'));
+        }
+      }, 5000);
+    });
+  }
+
+  async listStores(): Promise<StoreSummary[]> {
+    return this.request<StoreSummary[]>('listStores', {});
+  }
+
+  async describe(storeId: string): Promise<StoreDescription | undefined> {
+    const res = await this.request<StoreDescription | null>('describe', { storeId });
+    return res ?? undefined;
+  }
+
+  async getState(storeId: string): Promise<StateSnapshot | undefined> {
+    const res = await this.request<StateSnapshot | null>('getState', { storeId });
+    return res ?? undefined;
+  }
+
+  async findStoreByKey(pageId: string, storeKey: string): Promise<StoreSummary | undefined> {
+    const stores = await this.listStores();
+    return stores.find((store) => store.pageId === pageId && store.storeKey === storeKey);
+  }
+
+  async getStateByKey(pageId: string, storeKey = 'main'): Promise<StateSnapshot | undefined> {
+    const res = await this.request<StateSnapshot | null>('getState', { pageId, storeKey });
+    return res ?? undefined;
+  }
+
+  subscribe(storeId: string): void {
+    this.subscribedStores.add(storeId);
+    this.send({ type: 'subscribe', payload: { storeId } });
+  }
+
+  unsubscribe(storeId: string): void {
+    this.subscribedStores.delete(storeId);
+    this.send({ type: 'unsubscribe', payload: { storeId } });
+  }
+
+  async setState(storeId: string, state: unknown, options?: SetStateOptions): Promise<void> {
+    await this.request<null>('setState', { storeId, state, ...options });
+  }
+
+  async setStateByKey(
+    pageId: string,
+    storeKey: string,
+    state: unknown,
+    options?: SetStateOptions
+  ): Promise<{ version: number }> {
+    return this.request<{ version: number }>('setState', { pageId, storeKey, state, ...options });
+  }
+
+  async dispatch(storeId: string, action: { type: string; payload?: unknown }): Promise<void> {
+    await this.request<null>('dispatch', { storeId, action });
+  }
+
+  disconnect(): void {
+    this.ws?.close();
+  }
+}

package/src/sdk/index.ts

@@ -0,0 +1,2 @@
+export { BridgeClient } from './BridgeClient.js';
+export type { StoreSummary, StoreDescription, StateSnapshot, BridgeEvent } from './BridgeClient.js';

package/src/shared/types.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared types for Bridge
+ */
+
+export type StoreId = string;
+export type PageId = string;
+export type StoreKey = string;
+
+export interface ActionDefinition {
+  description: string;
+  payload?: unknown;
+}
+
+export interface EventDefinition {
+  description: string;
+  payload?: unknown;
+}
+
+export interface StoreDescription {
+  pageId: PageId;
+  storeKey: StoreKey;
+  schema: unknown;
+  actions: Record<string, ActionDefinition>;
+  events?: Record<string, EventDefinition>;
+}
+
+export interface StoreSummary {
+  id: StoreId;
+  pageId: PageId;
+  storeKey: StoreKey;
+  version: number;
+  connectedAt: Date;
+}
+
+export interface StateSnapshot {
+  state: unknown;
+  version: number;
+}
+
+export interface StoreState<T = unknown> {
+  data: T;
+  version: number;
+  updatedAt: number;
+}
+
+export interface SetStateOptions {
+  expectedVersion?: number;
+  waitForAck?: boolean;
+  timeoutMs?: number;
+}
+
+export interface RegisterPayload {
+  storeId: StoreId;
+  pageId: PageId;
+  storeKey: StoreKey;
+  description: StoreDescription;
+  initialState: unknown;
+}
+
+export interface StateChangedPayload {
+  storeId: StoreId;
+  state: unknown;
+  version: number;
+  source: string;
+}
+
+export interface StateAppliedPayload {
+  storeId: StoreId;
+  requestId: string;
+  status: 'applied' | 'version_mismatch' | 'failed';
+  version: number;
+  error?: string;
+}
+
+// Messages from Browser to Gateway
+export type GatewayMessage =
+  | { type: 'store.register'; payload: RegisterPayload }
+  | { type: 'store.stateChanged'; payload: StateChangedPayload }
+  | { type: 'store.stateApplied'; payload: StateAppliedPayload }
+  | { type: 'store.heartbeat' }
+  | { type: 'store.disconnect' };
+
+export interface ClientSetStatePayload {
+  storeId?: StoreId;
+  state: unknown;
+  expectedVersion?: number;
+  requestId?: string;
+  version?: number;
+}
+
+// Messages from Gateway to Browser
+export type ServerMessage =
+  | { type: 'client.setState'; payload: ClientSetStatePayload }
+  | { type: 'client.dispatch'; payload: { action: { type: string; payload?: unknown } } }
+  | { type: 'client.ping' };
+
+export type SubscriberMessage =
+  | { type: 'store.registered'; payload: { storeId: StoreId; pageId: PageId; storeKey: StoreKey } }
+  | { type: 'store.stateChanged'; payload: { storeId: StoreId; state: unknown; version: number; source: string } }
+  | { type: 'store.disconnected'; payload: { storeId: StoreId; reason: string } };
+
+export type GatewayClientMessage =
+  | { type: 'subscribe'; payload: { storeId: StoreId } }
+  | { type: 'unsubscribe'; payload: { storeId: StoreId } };
+
+export interface StoreChangeEvent {
+  type: 'stateChanged' | 'disconnected';
+  storeId: StoreId;
+  state?: unknown;
+  version?: number;
+  source?: string;
+}
+
+export type BridgeEvent =
+  | { type: 'stateChanged'; storeId: StoreId; state: unknown; version: number; source: string }
+  | { type: 'disconnected'; storeId: StoreId; reason: string }
+  | { type: 'connected'; storeId: StoreId; pageId: PageId; storeKey: StoreKey };

package/src/utils/logger.ts

@@ -0,0 +1,262 @@
+import { existsSync } from 'fs';
+import { appendFile, mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type SinkMode = 'console' | 'file' | 'both' | 'disabled';
+
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  data?: unknown;
+  timestamp: string;
+}
+
+export interface LoggerSink {
+  write(entry: LogEntry): Promise<void> | void;
+  clear?(): Promise<void>;
+  flush?(): Promise<void>;
+}
+
+interface LoggerRuntimeOptions {
+  level: LogLevel;
+  mode: SinkMode;
+  logDir: string;
+  fileName: string;
+}
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+const TEST_DEFAULT_DIR = join(process.cwd(), '.agentstage-test-logs');
+
+function normalizeLogLevel(value: string | undefined): LogLevel {
+  if (!value) {
+    return 'info';
+  }
+  const level = value.toLowerCase();
+  if (level === 'debug' || level === 'info' || level === 'warn' || level === 'error') {
+    return level;
+  }
+  return 'info';
+}
+
+function normalizeSinkMode(value: string | undefined): SinkMode {
+  if (!value) {
+    return process.env.NODE_ENV === 'test' ? 'disabled' : 'both';
+  }
+  const mode = value.toLowerCase();
+  if (mode === 'console' || mode === 'file' || mode === 'both' || mode === 'disabled') {
+    return mode;
+  }
+  return process.env.NODE_ENV === 'test' ? 'disabled' : 'both';
+}
+
+function defaultOptions(): LoggerRuntimeOptions {
+  return {
+    level: normalizeLogLevel(process.env.BRIDGE_LOG_LEVEL),
+    mode: normalizeSinkMode(process.env.BRIDGE_LOG_SINK),
+    logDir: process.env.BRIDGE_LOG_DIR || (process.env.NODE_ENV === 'test' ? TEST_DEFAULT_DIR : join(homedir(), '.agentstage', 'logs')),
+    fileName: process.env.BRIDGE_LOG_FILE || 'bridge.log',
+  };
+}
+
+function toLine(entry: LogEntry): string {
+  const dataStr = entry.data !== undefined ? ` ${JSON.stringify(entry.data)}` : '';
+  return `[${entry.timestamp}] [${entry.level.toUpperCase()}] ${entry.message}${dataStr}\n`;
+}
+
+class FileBatchSink implements LoggerSink {
+  private readonly path: string;
+  private queue: string[] = [];
+  private writing = false;
+  private flushScheduled = false;
+  private initialized = false;
+
+  constructor(path: string) {
+    this.path = path;
+  }
+
+  async write(entry: LogEntry): Promise<void> {
+    this.queue.push(toLine(entry));
+    if (!this.flushScheduled) {
+      this.flushScheduled = true;
+      setTimeout(() => {
+        this.flushScheduled = false;
+        void this.flush();
+      }, 10);
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.writing || this.queue.length === 0) {
+      return;
+    }
+
+    this.writing = true;
+    try {
+      if (!this.initialized) {
+        await mkdir(join(this.path, '..'), { recursive: true });
+        this.initialized = true;
+      }
+
+      while (this.queue.length > 0) {
+        const chunk = this.queue.splice(0, this.queue.length).join('');
+        await appendFile(this.path, chunk, 'utf8');
+      }
+    } finally {
+      this.writing = false;
+    }
+  }
+
+  async clear(): Promise<void> {
+    this.queue = [];
+    await mkdir(join(this.path, '..'), { recursive: true });
+    await writeFile(this.path, '', 'utf8');
+  }
+}
+
+class ConsoleSink implements LoggerSink {
+  write(entry: LogEntry): void {
+    if (entry.level === 'error') {
+      console.error(entry.message, entry.data ?? '');
+    } else if (entry.level === 'warn') {
+      console.warn(entry.message, entry.data ?? '');
+    } else {
+      console.log(entry.message, entry.data ?? '');
+    }
+  }
+}
+
+class DisabledSink implements LoggerSink {
+  write(): void {}
+}
+
+class CompositeSink implements LoggerSink {
+  private sinks: LoggerSink[];
+
+  constructor(sinks: LoggerSink[]) {
+    this.sinks = sinks;
+  }
+
+  async write(entry: LogEntry): Promise<void> {
+    for (const sink of this.sinks) {
+      await sink.write(entry);
+    }
+  }
+
+  async clear(): Promise<void> {
+    for (const sink of this.sinks) {
+      if (sink.clear) {
+        await sink.clear();
+      }
+    }
+  }
+
+  async flush(): Promise<void> {
+    for (const sink of this.sinks) {
+      if (sink.flush) {
+        await sink.flush();
+      }
+    }
+  }
+}
+
+function createBuiltinSink(options: LoggerRuntimeOptions): LoggerSink {
+  const logPath = join(options.logDir, options.fileName);
+  switch (options.mode) {
+    case 'disabled':
+      return new DisabledSink();
+    case 'console':
+      return new ConsoleSink();
+    case 'file':
+      return new FileBatchSink(logPath);
+    case 'both':
+    default:
+      return new CompositeSink([new ConsoleSink(), new FileBatchSink(logPath)]);
+  }
+}
+
+let runtimeOptions = defaultOptions();
+let activeSink: LoggerSink = createBuiltinSink(runtimeOptions);
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[runtimeOptions.level];
+}
+
+function write(level: LogLevel, message: string, data?: unknown): void {
+  if (!shouldLog(level)) {
+    return;
+  }
+
+  const entry: LogEntry = {
+    level,
+    message,
+    data,
+    timestamp: new Date().toISOString(),
+  };
+
+  void activeSink.write(entry);
+}
+
+export const logger = {
+  configure(overrides: Partial<LoggerRuntimeOptions> = {}) {
+    runtimeOptions = {
+      ...runtimeOptions,
+      ...overrides,
+    };
+    activeSink = createBuiltinSink(runtimeOptions);
+  },
+
+  setSink(sink: LoggerSink) {
+    activeSink = sink;
+  },
+
+  debug(message: string, data?: unknown) {
+    write('debug', message, data);
+  },
+
+  info(message: string, data?: unknown) {
+    write('info', message, data);
+  },
+
+  warn(message: string, data?: unknown) {
+    write('warn', message, data);
+  },
+
+  error(message: string, data?: unknown) {
+    write('error', message, data);
+  },
+
+  wsMessage(direction: 'in' | 'out', clientType: string, data: string) {
+    const arrow = direction === 'in' ? '->' : '<-';
+    write('debug', `[WS] ${arrow} [${clientType}] ${data}`);
+  },
+
+  getLogPath(): string {
+    return join(runtimeOptions.logDir, runtimeOptions.fileName);
+  },
+
+  async clear(): Promise<void> {
+    if (activeSink.clear) {
+      await activeSink.clear();
+      return;
+    }
+
+    const logPath = this.getLogPath();
+    if (existsSync(logPath)) {
+      await writeFile(logPath, '', 'utf8');
+    }
+  },
+
+  async flush(): Promise<void> {
+    if (activeSink.flush) {
+      await activeSink.flush();
+    }
+  },
+};

package/src/vite/index.ts

@@ -0,0 +1,31 @@
+import type { Plugin, ViteDevServer } from 'vite';
+import type { Server } from 'http';
+import type { Http2SecureServer } from 'http2';
+import { join } from 'path';
+import { createBridgeGateway } from '../gateway/createBridgeGateway.js';
+
+export interface BridgePluginOptions {
+  pagesDir?: string;
+}
+
+export function bridgePlugin(options: BridgePluginOptions = {}): Plugin {
+  return {
+    name: 'agentstage-bridge',
+    configureServer(server: ViteDevServer) {
+      const pagesDir = options.pagesDir || join(process.cwd(), 'src', 'pages');
+      const gateway = createBridgeGateway({ pagesDir });
+
+      // 保存 gateway 引用供后续使用
+      (server as any).bridgeGateway = gateway;
+
+      // 同步检查 httpServer 是否可用
+      if (server.httpServer) {
+        gateway.attach(server.httpServer as Server | Http2SecureServer);
+        console.log('[Bridge] WebSocket mounted at /_bridge');
+        console.log('[Bridge] Pages directory:', pagesDir);
+      } else {
+        console.warn('[Bridge] httpServer not available during configureServer');
+      }
+    },
+  };
+}