byterover-cli 1.7.0 → 1.7.1

package/node_modules/@campfirein/brv-transport-client/README.md

@@ -0,0 +1,409 @@
+# @campfirein/brv-transport-client
+
+Real-time transport client for ByteRover - connects UI/REPL/CLI clients to ByteRover Core server.
+
+## Installation
+
+```bash
+npm install @campfirein/brv-transport-client
+```
+
+**Note:** Requires `.npmrc` configured for GitHub Packages authentication.
+
+## Integration Checklist
+
+How to integrate with your CLI/TUI/REPL application:
+
+**1. Check if ByteRover server is running:**
+```typescript
+import { checkServerStatus } from '@campfirein/brv-transport-client'
+
+const status = await checkServerStatus()
+if (!status.running) {
+  console.log('Server not running:', status.reason)
+}
+```
+
+**2. Start server if needed (your responsibility):**
+```typescript
+if (!status.running) {
+  await startByteRoverServer() // Your server start logic
+}
+```
+
+**3. Connect to transport server:**
+```typescript
+import { connectToTransport } from '@campfirein/brv-transport-client'
+
+const {client, projectRoot} = await connectToTransport()
+// Auto-discovers .brv directory by walking up from current directory
+```
+
+**4. Listen for events:**
+```typescript
+client.on('llmservice:chunk', (data) => {
+  process.stdout.write(data.content) // Stream LLM output
+})
+
+client.on('task:completed', (data) => {
+  console.log('Task completed:', data.result)
+})
+```
+
+**5. Send tasks:**
+```typescript
+await client.requestWithAck('task:create', {
+  taskId: crypto.randomUUID(),
+  type: 'query',
+  content: 'What files handle authentication?'
+})
+```
+
+**6. Cleanup when done:**
+```typescript
+await client.disconnect()
+```
+
+## Quick Start
+
+```typescript
+import { connectToTransport } from '@campfirein/brv-transport-client'
+
+// Connect to ByteRover Core (auto-discovers .brv directory)
+const {client, projectRoot} = await connectToTransport()
+
+// Listen for LLM streaming
+client.on('llmservice:chunk', (data) => {
+  process.stdout.write(data.content)
+})
+
+// Send task request
+await client.requestWithAck('task:create', {
+  taskId: crypto.randomUUID(),
+  type: 'query',
+  content: 'Explain the authentication flow'
+})
+
+// Cleanup when done
+await client.disconnect()
+```
+
+## Integration Patterns
+
+### Pattern 1: CLI Command (Short-Lived)
+
+For one-off commands that connect, execute, and exit:
+
+```typescript
+export class QueryUseCase {
+  async execute(query: string) {
+    const {client} = await connectToTransport()
+
+    try {
+      // Send query as task
+      await client.requestWithAck('task:create', {
+        taskId: crypto.randomUUID(),
+        type: 'query',
+        content: query
+      })
+
+      // Wait for completion
+      return new Promise((resolve, reject) => {
+        client.on('task:completed', (data) => resolve(data.result))
+        client.on('task:error', (data) => reject(data.error))
+      })
+    } finally {
+      await client.disconnect()
+    }
+  }
+}
+```
+
+### Pattern 2: TUI Integration (Long-Running)
+
+For Terminal UI applications that maintain connection:
+
+```typescript
+class TransportClientHelper {
+  #client?: ITransportClient
+
+  async connect() {
+    const {client} = await connectToTransport()
+    this.#client = client
+    this.registerEventHandlers()
+  }
+
+  private registerEventHandlers() {
+    this.#client!.on('llmservice:chunk', (data) => {
+      // Stream to TUI display
+      this.ui.appendChunk(data.content)
+    })
+
+    this.#client!.on('task:completed', (data) => {
+      this.ui.showCompletion(data.result)
+    })
+
+    this.#client!.on('task:error', (data) => {
+      this.ui.showError(data.error)
+    })
+  }
+
+  async disconnect() {
+    await this.#client?.disconnect()
+  }
+}
+```
+
+### Pattern 3: React Integration
+
+For web UI applications:
+
+```typescript
+const TransportContext = createContext<ITransportClient | null>(null)
+
+export const TransportProvider = ({children}) => {
+  const [client, setClient] = useState<ITransportClient | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    connectToTransport()
+      .then(({client}) => setClient(client))
+      .catch(setError)
+
+    return () => {
+      client?.disconnect()
+    }
+  }, [])
+
+  return (
+    <TransportContext.Provider value={client}>
+      {error ? <ErrorDisplay error={error} /> : children}
+    </TransportContext.Provider>
+  )
+}
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `connectToTransport(fromDir?, config?)` | Connect to server (auto-discovery) | `const {client} = await connectToTransport()` |
+| `checkServerStatus(fromDir?)` | Check if server is running (non-throwing) | `const status = await checkServerStatus()` |
+
+**Return types:**
+- `connectToTransport()` → `{client: ITransportClient, projectRoot: string}`
+- `checkServerStatus()` → `{running: true, instanceInfo: InstanceInfo} | {running: false, reason: string}`
+
+### Client Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `client.on(event, handler)` | Listen for server events | `client.on('llmservice:chunk', handler)` |
+| `client.once(event, handler)` | Listen for event (one-time) | `client.once('task:completed', handler)` |
+| `client.request(event, data)` | Send fire-and-forget event | `client.request('custom:event', data)` |
+| `client.requestWithAck(event, data, opts?)` | Send request, wait for response | `await client.requestWithAck('task:create', data)` |
+| `client.disconnect()` | Close connection & cleanup | `await client.disconnect()` |
+
+### When to use `on()` vs `requestWithAck()`?
+
+- **Use `client.on()`** for server broadcasts (LLM chunks, task status updates)
+- **Use `client.requestWithAck()`** for request-response (task creation, session switching)
+- **Use `client.request()`** for fire-and-forget events (no response needed)
+
+## Common Events for CLI Integration
+
+### Task Lifecycle Events
+
+| Event | Type | When to Use |
+|-------|------|-------------|
+| `task:create` | Request | Send query/task to ByteRover server |
+| `task:started` | Broadcast | Task execution began (optional: show loading) |
+| `task:completed` | Broadcast | Task finished successfully |
+| `task:error` | Broadcast | Task failed with error |
+
+**Example:**
+```typescript
+// Send task
+await client.requestWithAck('task:create', {
+  taskId: crypto.randomUUID(),
+  type: 'query',
+  content: 'Explain authentication flow'
+})
+
+// Listen for completion
+client.on('task:completed', (data) => {
+  console.log('Result:', data.result)
+})
+
+client.on('task:error', (data) => {
+  console.error('Error:', data.error)
+})
+```
+
+### LLM Streaming Events
+
+| Event | When to Use |
+|-------|-------------|
+| `llmservice:chunk` | Stream LLM output to console/UI in real-time |
+| `llmservice:toolCall` | Show tool execution (e.g., "Reading file...") |
+| `llmservice:response` | Get final response with token usage |
+
+**Example:**
+```typescript
+// Stream LLM output to console
+client.on('llmservice:chunk', (data) => {
+  process.stdout.write(data.content)
+})
+
+// Show tool execution
+client.on('llmservice:toolCall', (data) => {
+  console.log(`\n[Tool: ${data.toolName}]`)
+})
+
+// Final response
+client.on('llmservice:response', (data) => {
+  console.log(`\nTokens used: ${data.tokenUsage.total}`)
+})
+```
+
+### Session Events
+
+| Event | Type | When to Use |
+|-------|------|-------------|
+| `session:info` | Request | Get current session details |
+| `session:switch` | Request | Switch to different session |
+| `session:switched` | Broadcast | Session changed (update UI) |
+
+**Full event reference:** Import `TaskEventNames`, `LlmEventNames`, `SessionEventNames`, `AgentEventNames`, `CipherEventNames` from the package.
+
+## Error Handling
+
+Handle connection errors specific to CLI integration:
+
+```typescript
+import {
+  checkServerStatus,
+  connectToTransport,
+  NoInstanceRunningError,
+  InstanceCrashedError,
+  ConnectionFailedError,
+  ConnectionTimeoutError
+} from '@campfirein/brv-transport-client'
+
+async function connectSafely() {
+  // Step 1: Check server status first
+  const status = await checkServerStatus()
+
+  if (!status.running) {
+    console.log('ByteRover server not running. Starting...')
+    await startByteRoverServer() // Your server start logic
+  }
+
+  // Step 2: Connect with error handling
+  try {
+    const {client, projectRoot} = await connectToTransport()
+    return {client, projectRoot}
+  } catch (error) {
+    if (error instanceof NoInstanceRunningError) {
+      console.error('No ByteRover instance found. Run: brv')
+      process.exit(1)
+    } else if (error instanceof InstanceCrashedError) {
+      console.error(`Instance crashed (PID ${error.pid}). Restart server.`)
+      process.exit(1)
+    } else if (error instanceof ConnectionFailedError) {
+      console.error('Connection failed:', error.message)
+      process.exit(1)
+    } else if (error instanceof ConnectionTimeoutError) {
+      console.error('Connection timeout. Server may be unresponsive.')
+      process.exit(1)
+    }
+    throw error
+  }
+}
+```
+
+**Built-in Resilience:**
+- Automatic reconnection with exponential backoff (5s, 10s, 20s, 30s, 60s)
+- Auto-rejoin rooms after reconnect
+- Max 30 connection attempts (configurable)
+
+## Configuration
+
+### Custom Directory
+
+```typescript
+// Start discovery from specific directory
+const {client} = await connectToTransport('/path/to/project')
+```
+
+### Custom Logger
+
+```typescript
+import { type IClientLogger } from '@campfirein/brv-transport-client'
+
+const logger: IClientLogger = {
+  debug: (msg) => console.debug('[Transport]', msg),
+  info: (msg) => console.info('[Transport]', msg),
+  warn: (msg) => console.warn('[Transport]', msg),
+  error: (msg) => console.error('[Transport]', msg)
+}
+
+const {client} = await connectToTransport(undefined, {
+  logger,
+  maxRetries: 10 // Override default discovery retries
+})
+```
+
+### Custom Request Timeout
+
+```typescript
+// Per-request timeout override
+await client.requestWithAck('task:create', data, {
+  timeout: 30000 // 30 seconds (default: 10s)
+})
+```
+
+## Typical Integration Flow
+
+The recommended workflow for CLI/TUI/REPL clients:
+
+```typescript
+import {
+  checkServerStatus,
+  connectToTransport,
+  NoInstanceRunningError
+} from '@campfirein/brv-transport-client'
+
+async function main() {
+  // Step 1: Check if server is running
+  const status = await checkServerStatus()
+
+  // Step 2: Start server if needed (your responsibility)
+  if (!status.running) {
+    console.log('Starting ByteRover server...')
+    await startByteRoverServer() // Your server start logic
+  }
+
+  // Step 3: Connect (auto walk-up to find .brv directory)
+  const {client, projectRoot} = await connectToTransport()
+  console.log('Connected to:', projectRoot)
+
+  // Step 4: Use the client
+  // ... your application logic ...
+
+  // Step 5: Cleanup
+  await client.disconnect()
+}
+```
+
+## Resources
+
+- **[CLAUDE.md](./CLAUDE.md)** - Full architecture documentation & design patterns
+- **[TESTING.md](./TESTING.md)** - Testing strategy and patterns
+- **[Socket.IO Docs](https://socket.io/docs/v4/)** - Underlying transport layer
+
+## License
+
+UNLICENSED - Private package for ByteRover ecosystem

package/node_modules/@campfirein/brv-transport-client/dist/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Transport Client Constants
+ *
+ * These constants are duplicated from the main codebase to maintain
+ * leaf component independence (no dependencies on other brv modules).
+ */
+export declare const BRV_DIR = ".brv";
+export declare const INSTANCE_FILE = "instance.json";
+export declare const TRANSPORT_HOST = "127.0.0.1";
+export declare const TRANSPORT_REQUEST_TIMEOUT_MS = 10000;
+export declare const TRANSPORT_ROOM_TIMEOUT_MS = 2000;
+export declare const TRANSPORT_CONNECT_TIMEOUT_MS = 3000;
+export declare const TRANSPORT_RECONNECTION_DELAY_MS = 50;
+export declare const TRANSPORT_RECONNECTION_DELAY_MAX_MS = 1000;
+export declare const TRANSPORT_RECONNECTION_ATTEMPTS = 30;
+export declare const TRANSPORT_DEFAULT_TRANSPORTS: readonly ["websocket"];
+export declare const ROOM_MAX_REJOIN_ATTEMPTS = 5;
+export declare const ROOM_REJOIN_BASE_DELAY_MS = 50;
+//# sourceMappingURL=constants.d.ts.map

package/node_modules/@campfirein/brv-transport-client/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,eAAO,MAAM,OAAO,SAAS,CAAA;AAC7B,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAG5C,eAAO,MAAM,cAAc,cAAc,CAAA;AACzC,eAAO,MAAM,4BAA4B,QAAS,CAAA;AAClD,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAC7C,eAAO,MAAM,4BAA4B,OAAO,CAAA;AAChD,eAAO,MAAM,+BAA+B,KAAK,CAAA;AACjD,eAAO,MAAM,mCAAmC,OAAO,CAAA;AACvD,eAAO,MAAM,+BAA+B,KAAK,CAAA;AAIjD,eAAO,MAAM,4BAA4B,wBAAyB,CAAA;AAGlE,eAAO,MAAM,wBAAwB,IAAI,CAAA;AACzC,eAAO,MAAM,yBAAyB,KAAK,CAAA"}

package/node_modules/@campfirein/brv-transport-client/dist/constants.js

@@ -0,0 +1,24 @@
+/**
+ * Transport Client Constants
+ *
+ * These constants are duplicated from the main codebase to maintain
+ * leaf component independence (no dependencies on other brv modules).
+ */
+// Instance discovery constants
+export const BRV_DIR = '.brv';
+export const INSTANCE_FILE = 'instance.json';
+// Transport layer constants (optimized for localhost real-time)
+export const TRANSPORT_HOST = '127.0.0.1';
+export const TRANSPORT_REQUEST_TIMEOUT_MS = 10_000; // 10s - most operations complete quickly
+export const TRANSPORT_ROOM_TIMEOUT_MS = 2000; // 2s - room ops are instant on localhost
+export const TRANSPORT_CONNECT_TIMEOUT_MS = 3000; // 3s - 127.0.0.1 connects in <10ms
+export const TRANSPORT_RECONNECTION_DELAY_MS = 50; // 50ms - ultra aggressive start
+export const TRANSPORT_RECONNECTION_DELAY_MAX_MS = 1000; // 1s cap - fail fast, retry fast
+export const TRANSPORT_RECONNECTION_ATTEMPTS = 30; // More attempts with faster retry
+// WebSocket-only transport to avoid HTTP polling issues in sandboxed environments (Cursor, etc.)
+// HTTP polling may be blocked by IDE sandboxes causing "xhr poll error"
+export const TRANSPORT_DEFAULT_TRANSPORTS = ['websocket'];
+// Room manager constants
+export const ROOM_MAX_REJOIN_ATTEMPTS = 5; // Max attempts to rejoin a room after reconnect
+export const ROOM_REJOIN_BASE_DELAY_MS = 50; // Base delay for exponential backoff (50ms, 100ms, 200ms...)
+//# sourceMappingURL=constants.js.map

package/node_modules/@campfirein/brv-transport-client/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAA;AAC7B,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAA;AAE5C,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAA;AACzC,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAA,CAAC,yCAAyC;AAC5F,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAA,CAAC,yCAAyC;AACvF,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAA,CAAC,mCAAmC;AACpF,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAA,CAAC,gCAAgC;AAClF,MAAM,CAAC,MAAM,mCAAmC,GAAG,IAAI,CAAA,CAAC,iCAAiC;AACzF,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,CAAA,CAAC,kCAAkC;AAEpF,iGAAiG;AACjG,wEAAwE;AACxE,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,WAAW,CAAU,CAAA;AAElE,yBAAyB;AACzB,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA,CAAC,gDAAgD;AAC1F,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAA,CAAC,6DAA6D"}

package/node_modules/@campfirein/brv-transport-client/dist/core/domain/entities/instance-info.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Raw instance data as stored in instance.json.
+ * Used for serialization/deserialization.
+ *
+ * NOTE: We don't store "status" - we check pid alive at runtime instead.
+ * This avoids stale status when process crashes.
+ */
+export type InstanceInfoJson = {
+    /** Current active session ID (for quick lookup without DB query) */
+    currentSessionId: null | string;
+    /** Process ID of the Core process */
+    pid: number;
+    /** Port the transport server is listening on */
+    port: number;
+    /** Timestamp when instance started (ms since epoch) */
+    startedAt: number;
+};
+/**
+ * Instance information representing a BRV Core process.
+ *
+ * Architecture note:
+ * - File exists + pid alive  → instance is running
+ * - File exists + pid dead   → stale (crash), can overwrite
+ * - File doesn't exist       → no instance
+ *
+ * @remarks
+ * This class is immutable. All properties are readonly and Date is stored
+ * as a timestamp internally to prevent external mutation.
+ */
+export declare class InstanceInfo {
+    #private;
+    readonly currentSessionId: null | string;
+    readonly pid: number;
+    readonly port: number;
+    private constructor();
+    /**
+     * Gets the start time as a new Date object.
+     * Returns a defensive copy to prevent external mutation.
+     */
+    getStartedAt(): Date;
+    /**
+     * Creates a new instance info.
+     */
+    static create(data: {
+        currentSessionId?: null | string;
+        pid: number;
+        port: number;
+    }): InstanceInfo;
+    /**
+     * Creates instance info from JSON data (from instance.json file).
+     * @throws InvalidInstanceDataError if the JSON data is invalid or malformed
+     */
+    static fromJson(json: InstanceInfoJson): InstanceInfo;
+    /**
+     * Validates JSON data before creating an instance.
+     * @throws InvalidInstanceDataError if validation fails
+     */
+    private static validateJson;
+    /**
+     * Returns the transport URL for connecting to this instance.
+     *
+     * @param host - The host address (default: '127.0.0.1' for localhost).
+     *               Using IP address instead of 'localhost' for better sandbox compatibility.
+     * @returns The full URL including protocol, host, and port
+     */
+    getTransportUrl(host?: string): string;
+    /**
+     * Converts instance info to JSON for persistence.
+     */
+    toJson(): InstanceInfoJson;
+    /**
+     * Creates a new instance info with updated session ID.
+     * Returns a new immutable instance.
+     */
+    withSessionId(sessionId: string): InstanceInfo;
+}
+//# sourceMappingURL=instance-info.d.ts.map

package/node_modules/@campfirein/brv-transport-client/dist/core/domain/entities/instance-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-info.d.ts","sourceRoot":"","sources":["../../../../core/domain/entities/instance-info.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oEAAoE;IACpE,gBAAgB,EAAE,IAAI,GAAG,MAAM,CAAA;IAC/B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;;IACvB,SAAgB,gBAAgB,EAAE,IAAI,GAAG,MAAM,CAAA;IAC/C,SAAgB,GAAG,EAAE,MAAM,CAAA;IAC3B,SAAgB,IAAI,EAAE,MAAM,CAAA;IAQ5B,OAAO;IAOP;;;OAGG;IACI,YAAY,IAAI,IAAI;IAI3B;;OAEG;WACW,MAAM,CAAC,IAAI,EAAE;QAAC,gBAAgB,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAG,YAAY;IASvG;;;OAGG;WACW,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY;IAY5D;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAyC3B;;;;;;OAMG;IACI,eAAe,CAAC,IAAI,GAAE,MAA+B,GAAG,MAAM;IAIrE;;OAEG;IACI,MAAM,IAAI,gBAAgB;IASjC;;;OAGG;IACI,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;CAQtD"}

package/node_modules/@campfirein/brv-transport-client/dist/core/domain/entities/instance-info.js

@@ -0,0 +1,135 @@
+import { InvalidInstanceDataError } from '../errors/connection-error.js';
+/**
+ * Default transport host for localhost connections.
+ * Using IP address instead of 'localhost' for better sandbox compatibility.
+ */
+const DEFAULT_TRANSPORT_HOST = '127.0.0.1';
+/**
+ * Instance information representing a BRV Core process.
+ *
+ * Architecture note:
+ * - File exists + pid alive  → instance is running
+ * - File exists + pid dead   → stale (crash), can overwrite
+ * - File doesn't exist       → no instance
+ *
+ * @remarks
+ * This class is immutable. All properties are readonly and Date is stored
+ * as a timestamp internally to prevent external mutation.
+ */
+export class InstanceInfo {
+    currentSessionId;
+    pid;
+    port;
+    /**
+     * Internal timestamp storage to ensure immutability.
+     * Use getStartedAt() to get a Date object.
+     */
+    #startedAtMs;
+    constructor(data) {
+        this.currentSessionId = data.currentSessionId;
+        this.pid = data.pid;
+        this.port = data.port;
+        this.#startedAtMs = data.startedAtMs;
+    }
+    /**
+     * Gets the start time as a new Date object.
+     * Returns a defensive copy to prevent external mutation.
+     */
+    getStartedAt() {
+        return new Date(this.#startedAtMs);
+    }
+    /**
+     * Creates a new instance info.
+     */
+    static create(data) {
+        return new InstanceInfo({
+            currentSessionId: data.currentSessionId ?? null,
+            pid: data.pid,
+            port: data.port,
+            startedAtMs: Date.now(),
+        });
+    }
+    /**
+     * Creates instance info from JSON data (from instance.json file).
+     * @throws InvalidInstanceDataError if the JSON data is invalid or malformed
+     */
+    static fromJson(json) {
+        // Validate required fields exist and have correct types
+        InstanceInfo.validateJson(json);
+        return new InstanceInfo({
+            currentSessionId: json.currentSessionId,
+            pid: json.pid,
+            port: json.port,
+            startedAtMs: json.startedAt,
+        });
+    }
+    /**
+     * Validates JSON data before creating an instance.
+     * @throws InvalidInstanceDataError if validation fails
+     */
+    static validateJson(json) {
+        if (typeof json !== 'object' || json === null) {
+            throw new InvalidInstanceDataError('expected object, got ' + (json === null ? 'null' : typeof json));
+        }
+        const obj = json;
+        // Validate pid
+        if (typeof obj.pid !== 'number') {
+            throw new InvalidInstanceDataError('pid must be a number', 'pid', obj.pid);
+        }
+        if (!Number.isInteger(obj.pid) || obj.pid <= 0) {
+            throw new InvalidInstanceDataError('pid must be a positive integer', 'pid', obj.pid);
+        }
+        // Validate port
+        if (typeof obj.port !== 'number') {
+            throw new InvalidInstanceDataError('port must be a number', 'port', obj.port);
+        }
+        if (!Number.isInteger(obj.port) || obj.port <= 0 || obj.port > 65535) {
+            throw new InvalidInstanceDataError('port must be a valid port number (1-65535)', 'port', obj.port);
+        }
+        // Validate startedAt
+        if (typeof obj.startedAt !== 'number') {
+            throw new InvalidInstanceDataError('startedAt must be a number', 'startedAt', obj.startedAt);
+        }
+        if (!Number.isInteger(obj.startedAt) || obj.startedAt <= 0) {
+            throw new InvalidInstanceDataError('startedAt must be a positive integer timestamp', 'startedAt', obj.startedAt);
+        }
+        // Validate currentSessionId (can be null or string)
+        if (obj.currentSessionId !== null && typeof obj.currentSessionId !== 'string') {
+            throw new InvalidInstanceDataError('currentSessionId must be null or a string', 'currentSessionId', obj.currentSessionId);
+        }
+    }
+    /**
+     * Returns the transport URL for connecting to this instance.
+     *
+     * @param host - The host address (default: '127.0.0.1' for localhost).
+     *               Using IP address instead of 'localhost' for better sandbox compatibility.
+     * @returns The full URL including protocol, host, and port
+     */
+    getTransportUrl(host = DEFAULT_TRANSPORT_HOST) {
+        return `http://${host}:${this.port}`;
+    }
+    /**
+     * Converts instance info to JSON for persistence.
+     */
+    toJson() {
+        return {
+            currentSessionId: this.currentSessionId,
+            pid: this.pid,
+            port: this.port,
+            startedAt: this.#startedAtMs,
+        };
+    }
+    /**
+     * Creates a new instance info with updated session ID.
+     * Returns a new immutable instance.
+     */
+    withSessionId(sessionId) {
+        return new InstanceInfo({
+            currentSessionId: sessionId,
+            pid: this.pid,
+            port: this.port,
+            startedAtMs: this.#startedAtMs,
+        });
+    }
+}
+//# sourceMappingURL=instance-info.js.map

package/node_modules/@campfirein/brv-transport-client/dist/core/domain/entities/instance-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-info.js","sourceRoot":"","sources":["../../../../core/domain/entities/instance-info.ts"],"names":[],"mappings":"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"}