@agentstage/bridge 0.1.0

package/src/gateway/fileStore.ts

@@ -0,0 +1,244 @@
+import { mkdirSync, watch, type FSWatcher } from 'fs';
+import { mkdir, readFile, rename, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+
+export interface StoreData<T = unknown> {
+  state: T;
+  version: number;
+  updatedAt: string;
+  pageId: string;
+}
+
+export interface FileStoreOptions {
+  pagesDir: string;
+}
+
+const PAGE_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+export class InvalidPageIdError extends Error {
+  readonly pageId: string;
+
+  constructor(pageId: string) {
+    super(`Invalid pageId "${pageId}". pageId must match /^[a-zA-Z0-9_-]+$/.`);
+    this.name = 'InvalidPageIdError';
+    this.pageId = pageId;
+  }
+}
+
+export class VersionConflictError extends Error {
+  readonly pageId: string;
+  readonly expectedVersion: number;
+  readonly actualVersion: number | null;
+
+  constructor(pageId: string, expectedVersion: number, actualVersion: number | null) {
+    super(
+      `Version conflict for "${pageId}": expected ${expectedVersion}, actual ${
+        actualVersion === null ? 'null' : actualVersion
+      }.`
+    );
+    this.name = 'VersionConflictError';
+    this.pageId = pageId;
+    this.expectedVersion = expectedVersion;
+    this.actualVersion = actualVersion;
+  }
+}
+
+export function validatePageId(pageId: string): void {
+  if (!PAGE_ID_PATTERN.test(pageId)) {
+    throw new InvalidPageIdError(pageId);
+  }
+}
+
+export class FileStore {
+  private pagesDir: string;
+  private watchers = new Map<string, FSWatcher>();
+  private writeQueue: Array<{
+    pageId: string;
+    path: string;
+    data: StoreData<unknown>;
+    expectedVersion?: number;
+    resolve: (savedData: StoreData<unknown>) => void;
+    reject: (error: unknown) => void;
+  }> = [];
+  private processing = false;
+  private versionClock = new Map<string, number>();
+
+  constructor(options: FileStoreOptions) {
+    this.pagesDir = options.pagesDir;
+  }
+
+  private getStorePath(pageId: string): string {
+    return join(this.pagesDir, pageId, 'store.json');
+  }
+
+  async load<T>(pageId: string): Promise<StoreData<T> | null> {
+    validatePageId(pageId);
+    const path = this.getStorePath(pageId);
+
+    try {
+      const content = await readFile(path, 'utf8');
+      const parsed = JSON.parse(content) as StoreData<T>;
+      if (typeof parsed.version === 'number') {
+        this.bumpVersionClock(pageId, parsed.version);
+      }
+      return parsed;
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      if (err.code === 'ENOENT') {
+        return null;
+      }
+
+      throw error;
+    }
+  }
+
+  async save<T>(pageId: string, data: StoreData<T>, expectedVersion?: number): Promise<StoreData<T>> {
+    validatePageId(pageId);
+    const path = this.getStorePath(pageId);
+
+    return new Promise<StoreData<T>>((resolve, reject) => {
+      this.writeQueue.push({
+        pageId,
+        path,
+        data: data as StoreData<unknown>,
+        expectedVersion,
+        resolve: (savedData) => resolve(savedData as StoreData<T>),
+        reject,
+      });
+      void this.processWriteQueue();
+    });
+  }
+
+  private async processWriteQueue(): Promise<void> {
+    if (this.processing) {
+      return;
+    }
+
+    this.processing = true;
+
+    while (this.writeQueue.length > 0) {
+      const task = this.writeQueue.shift();
+      if (!task) {
+        continue;
+      }
+
+      try {
+        const current = await this.readStoreData(task.path);
+        const currentVersion = current?.version ?? null;
+
+        if (task.expectedVersion !== undefined && currentVersion !== null && currentVersion !== task.expectedVersion) {
+          throw new VersionConflictError(task.pageId, task.expectedVersion, currentVersion);
+        }
+
+        const nextVersion = this.nextVersion(task.pageId, current?.version ?? 0);
+        const savedData: StoreData<unknown> = {
+          ...task.data,
+          pageId: task.pageId,
+          version: nextVersion,
+          updatedAt: new Date().toISOString(),
+        };
+
+        await this.writeAtomically(task.path, JSON.stringify(savedData, null, 2));
+        task.resolve(savedData);
+      } catch (error) {
+        task.reject(error);
+      }
+    }
+
+    this.processing = false;
+
+    if (this.writeQueue.length > 0) {
+      void this.processWriteQueue();
+    }
+  }
+
+  private async writeAtomically(path: string, content: string): Promise<void> {
+    await mkdir(dirname(path), { recursive: true });
+    const tmpPath = `${path}.tmp`;
+    await writeFile(tmpPath, content, 'utf8');
+    await rename(tmpPath, path);
+  }
+
+  private async readStoreData(path: string): Promise<StoreData<unknown> | null> {
+    try {
+      const content = await readFile(path, 'utf8');
+      return JSON.parse(content) as StoreData<unknown>;
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      if (err.code === 'ENOENT') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  private bumpVersionClock(pageId: string, version: number): void {
+    const current = this.versionClock.get(pageId) ?? 0;
+    if (version > current) {
+      this.versionClock.set(pageId, version);
+    }
+  }
+
+  private nextVersion(pageId: string, fileVersion: number): number {
+    const clock = this.versionClock.get(pageId) ?? 0;
+    const next = Math.max(clock, fileVersion) + 1;
+    this.versionClock.set(pageId, next);
+    return next;
+  }
+
+  watch<T>(pageId: string, callback: (data: StoreData<T>) => void): () => void {
+    validatePageId(pageId);
+    const path = this.getStorePath(pageId);
+    const pageDir = dirname(path);
+
+    const existing = this.watchers.get(pageId);
+    if (existing) {
+      existing.close();
+      this.watchers.delete(pageId);
+    }
+
+    mkdirSync(pageDir, { recursive: true });
+
+    const watcher = watch(pageDir, (_, filename) => {
+      if (filename && filename.toString() !== 'store.json') {
+        return;
+      }
+
+      void this.load<T>(pageId)
+        .then((data) => {
+          if (data) {
+            callback(data);
+          }
+        })
+        .catch(() => {
+          // Ignore transient read/parse errors during file change events.
+        });
+    });
+
+    watcher.on('error', () => {
+      const activeWatcher = this.watchers.get(pageId);
+      if (activeWatcher) {
+        activeWatcher.close();
+        this.watchers.delete(pageId);
+      }
+    });
+
+    this.watchers.set(pageId, watcher);
+
+    return () => {
+      const activeWatcher = this.watchers.get(pageId);
+      if (activeWatcher) {
+        activeWatcher.close();
+        this.watchers.delete(pageId);
+      }
+    };
+  }
+
+  destroy(): void {
+    for (const watcher of this.watchers.values()) {
+      watcher.close();
+    }
+
+    this.watchers.clear();
+  }
+}

package/src/gateway/index.ts

@@ -0,0 +1,12 @@
+export type * from './types.js';
+export { createBridgeGateway } from './createBridgeGateway.js';
+export { createBridgeApiHandler } from './apiHandler.js';
+export { StoreRegistry } from './registry.js';
+export {
+  FileStore,
+  InvalidPageIdError,
+  VersionConflictError,
+  validatePageId,
+  type FileStoreOptions,
+  type StoreData,
+} from './fileStore.js';

package/src/gateway/registry.ts

@@ -0,0 +1,166 @@
+import { WebSocket } from 'ws';
+import type {
+  StoreId,
+  PageId,
+  StoreKey,
+  RegisteredStore,
+  StoreChangeEvent
+} from './types.js';
+
+export class StoreRegistry {
+  private stores = new Map<StoreId, RegisteredStore>();
+  private index = new Map<`${PageId}:${StoreKey}`, StoreId>();
+  private byPage = new Map<PageId, Set<StoreId>>();
+  private changeHandlers = new Set<(event: StoreChangeEvent) => void>();
+  
+  register(store: RegisteredStore): void {
+    const key: `${PageId}:${StoreKey}` = `${store.pageId}:${store.storeKey}`;
+    
+    const existingId = this.index.get(key);
+    if (existingId) {
+      const existing = this.stores.get(existingId);
+      if (existing) {
+        this.disconnect(existingId, 'replaced');
+      }
+    }
+    
+    this.stores.set(store.id, store);
+    this.index.set(key, store.id);
+    
+    if (!this.byPage.has(store.pageId)) {
+      this.byPage.set(store.pageId, new Set());
+    }
+    this.byPage.get(store.pageId)!.add(store.id);
+    
+    this.emit({
+      type: 'stateChanged',
+      storeId: store.id,
+      state: store.currentState,
+      version: store.version,
+      source: 'register',
+    });
+  }
+  
+  get(id: StoreId): RegisteredStore | undefined {
+    return this.stores.get(id);
+  }
+  
+  find(pageId: PageId, storeKey: StoreKey): RegisteredStore | undefined {
+    const key: `${PageId}:${StoreKey}` = `${pageId}:${storeKey}`;
+    const storeId = this.index.get(key);
+    return storeId ? this.stores.get(storeId) : undefined;
+  }
+
+  findStoreByKey(pageId: PageId, storeKey: StoreKey): RegisteredStore | undefined {
+    return this.find(pageId, storeKey);
+  }
+  
+  findByPage(pageId: PageId): RegisteredStore[] {
+    const ids = this.byPage.get(pageId);
+    if (!ids) return [];
+    return Array.from(ids)
+      .map(id => this.stores.get(id))
+      .filter((s): s is RegisteredStore => s !== undefined);
+  }
+  
+  list(): RegisteredStore[] {
+    return Array.from(this.stores.values());
+  }
+  
+  updateState(id: StoreId, state: unknown, version: number): void {
+    const store = this.stores.get(id);
+    if (!store) return;
+    
+    store.currentState = state;
+    store.version = version;
+    store.lastActivity = new Date();
+    
+    this.emit({
+      type: 'stateChanged',
+      storeId: id,
+      state,
+      version,
+      source: 'browser',
+    });
+  }
+  
+  disconnect(id: StoreId, reason: string): void {
+    const store = this.stores.get(id);
+    if (!store) return;
+    
+    for (const sub of store.subscribers) {
+      if (sub.readyState === WebSocket.OPEN) {
+        sub.send(JSON.stringify({
+          type: 'store.disconnected',
+          payload: { storeId: id, reason },
+        }));
+      }
+    }
+    
+    this.stores.delete(id);
+    
+    const key: `${PageId}:${StoreKey}` = `${store.pageId}:${store.storeKey}`;
+    if (this.index.get(key) === id) {
+      this.index.delete(key);
+    }
+    
+    const pageStores = this.byPage.get(store.pageId);
+    if (pageStores) {
+      pageStores.delete(id);
+      if (pageStores.size === 0) {
+        this.byPage.delete(store.pageId);
+      }
+    }
+    
+    this.emit({
+      type: 'disconnected',
+      storeId: id,
+    });
+  }
+  
+  addSubscriber(id: StoreId, ws: WebSocket): () => void {
+    const store = this.stores.get(id);
+    if (!store) {
+      throw new Error(`Store not found: ${id}`);
+    }
+    
+    store.subscribers.add(ws);
+    
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({
+        type: 'store.stateChanged',
+        payload: {
+          storeId: id,
+          state: store.currentState,
+          version: store.version,
+          source: 'snapshot',
+        },
+      }));
+    }
+    
+    return () => {
+      store.subscribers.delete(ws);
+    };
+  }
+  
+  onChange(handler: (event: StoreChangeEvent) => void): () => void {
+    this.changeHandlers.add(handler);
+    return () => this.changeHandlers.delete(handler);
+  }
+  
+  private emit(event: StoreChangeEvent): void {
+    for (const handler of this.changeHandlers) {
+      handler(event);
+    }
+  }
+  
+  cleanup(): void {
+    for (const store of this.stores.values()) {
+      for (const sub of store.subscribers) {
+        if (sub.readyState !== WebSocket.OPEN) {
+          store.subscribers.delete(sub);
+        }
+      }
+    }
+  }
+}

package/src/gateway/types.ts

@@ -0,0 +1,65 @@
+import type { Server } from 'http';
+import type WebSocket from 'ws';
+import type {
+  StoreId,
+  PageId,
+  StoreKey,
+  StoreDescription,
+  StoreChangeEvent,
+  GatewayMessage as BrowserMessage,
+  ServerMessage as ClientMessage,
+  SubscriberMessage,
+  SetStateOptions,
+} from '../shared/types.js';
+
+export type {
+  StoreId,
+  PageId,
+  StoreKey,
+  BrowserMessage,
+  ClientMessage,
+  SubscriberMessage,
+  StoreChangeEvent,
+};
+
+export interface RegisteredStore {
+  id: StoreId;
+  pageId: PageId;
+  storeKey: StoreKey;
+  description: StoreDescription;
+  currentState: unknown;
+  version: number;
+  ws: WebSocket;
+  subscribers: Set<WebSocket>;
+  connectedAt: Date;
+  lastActivity: Date;
+}
+
+export interface Gateway {
+  readonly stores: ReadonlyMap<StoreId, RegisteredStore>;
+  listStores(): Array<{
+    id: StoreId;
+    pageId: PageId;
+    storeKey: StoreKey;
+    version: number;
+    connectedAt: Date;
+  }>;
+  getStore(id: StoreId): RegisteredStore | undefined;
+  findStore(pageId: PageId, storeKey: StoreKey): RegisteredStore | undefined;
+  findStoreByKey(pageId: PageId, storeKey: StoreKey): RegisteredStore | undefined;
+  getDescription(id: StoreId): StoreDescription | undefined;
+  getState(id: StoreId): { state: unknown; version: number } | undefined;
+  setState(id: StoreId, state: unknown, options?: SetStateOptions): Promise<void>;
+  dispatch(id: StoreId, action: { type: string; payload?: unknown }): Promise<void>;
+  subscribe(id: StoreId, ws: WebSocket, callback?: (event: StoreChangeEvent) => void): () => void;
+  attach(server: Server | import('http2').Http2SecureServer): import('ws').WebSocketServer;
+  destroy(): void;
+}
+
+export interface GatewayOptions {
+  wsPath?: string;
+  heartbeatTimeout?: number;
+  pagesDir?: string;
+  ackTimeout?: number;
+  ackRetryCount?: number;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Agentstage Bridge
+ *
+ * Agent 控制浏览器页面的核心基础设施
+ *
+ * @example
+ * // Gateway side (TanStack Start)
+ * import { createBridgeGateway, createBridgeApiHandler } from 'agent-stage-bridge';
+ *
+ * // Browser side
+ * import { createBridgeStore } from 'agent-stage-bridge/browser';
+ *
+ * // CLI/SDK side
+ * import { BridgeClient } from 'agent-stage-bridge/sdk';
+ *
+ * // Vite Plugin
+ * import { bridgePlugin } from 'agent-stage-bridge/vite';
+ */
+
+export type * from './shared/types.js';
+export type * from './gateway/types.js';
+export { createBridgeGateway } from './gateway/createBridgeGateway.js';
+export { createBridgeApiHandler } from './gateway/apiHandler.js';
+export { StoreRegistry } from './gateway/registry.js';
+export {
+  FileStore,
+  InvalidPageIdError,
+  VersionConflictError,
+  validatePageId,
+  type FileStoreOptions,
+  type StoreData,
+} from './gateway/fileStore.js';
+export { bridgePlugin } from './vite/index.js';