@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/cli/resolve-session.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Unit tests for the CLI session resolution utility.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { SessionInfo } from '../bridge/index.js';
+import { resolveSessionAsync } from './resolve-session.js';
+
+function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    sessionId: 'session-1',
+    placeName: 'TestPlace',
+    state: 'Edit',
+    pluginVersion: '1.0.0',
+    capabilities: ['execute', 'queryState'],
+    connectedAt: new Date(),
+    origin: 'user',
+    context: 'edit',
+    instanceId: 'inst-1',
+    placeId: 123,
+    gameId: 456,
+    ...overrides,
+  };
+}
+
+function createMockConnection(sessions: SessionInfo[]) {
+  return {
+    listSessions: () => sessions,
+    getSession: (id: string) => sessions.find((s) => s.sessionId === id),
+  } as any;
+}
+
+describe('resolveSessionAsync', () => {
+  it('returns session when sessionId matches', async () => {
+    const session = createSessionInfo({ sessionId: 'abc-123' });
+    const conn = createMockConnection([session]);
+
+    const result = await resolveSessionAsync(conn, { sessionId: 'abc-123' });
+    expect(result.sessionId).toBe('abc-123');
+  });
+
+  it('throws when sessionId does not match', async () => {
+    const conn = createMockConnection([createSessionInfo()]);
+
+    await expect(
+      resolveSessionAsync(conn, { sessionId: 'nonexistent' })
+    ).rejects.toThrow("Session 'nonexistent' not found.");
+  });
+
+  it('returns sole session when no filters and exactly one session', async () => {
+    const session = createSessionInfo({ sessionId: 'only-one' });
+    const conn = createMockConnection([session]);
+
+    const result = await resolveSessionAsync(conn);
+    expect(result.sessionId).toBe('only-one');
+  });
+
+  it('throws when no sessions match', async () => {
+    const conn = createMockConnection([]);
+
+    await expect(resolveSessionAsync(conn)).rejects.toThrow(
+      'No matching sessions found. Is Studio running with the studio-bridge plugin?'
+    );
+  });
+
+  it('throws descriptive error when multiple sessions match', async () => {
+    const sessions = [
+      createSessionInfo({ sessionId: 'ses-1', instanceId: 'inst-a' }),
+      createSessionInfo({ sessionId: 'ses-2', instanceId: 'inst-b' }),
+    ];
+    const conn = createMockConnection(sessions);
+
+    await expect(resolveSessionAsync(conn)).rejects.toThrow(
+      /Multiple sessions found.*--session.*--instance/s
+    );
+  });
+
+  it('filters by instanceId', async () => {
+    const sessions = [
+      createSessionInfo({ sessionId: 'ses-1', instanceId: 'inst-a' }),
+      createSessionInfo({ sessionId: 'ses-2', instanceId: 'inst-b' }),
+    ];
+    const conn = createMockConnection(sessions);
+
+    const result = await resolveSessionAsync(conn, { instanceId: 'inst-b' });
+    expect(result.sessionId).toBe('ses-2');
+  });
+
+  it('filters by context', async () => {
+    const sessions = [
+      createSessionInfo({ sessionId: 'ses-edit', context: 'edit' }),
+      createSessionInfo({ sessionId: 'ses-server', context: 'server' }),
+    ];
+    const conn = createMockConnection(sessions);
+
+    const result = await resolveSessionAsync(conn, { context: 'server' });
+    expect(result.sessionId).toBe('ses-server');
+  });
+
+  it('combines instanceId and context filters', async () => {
+    const sessions = [
+      createSessionInfo({
+        sessionId: 's1',
+        instanceId: 'inst-a',
+        context: 'edit',
+      }),
+      createSessionInfo({
+        sessionId: 's2',
+        instanceId: 'inst-a',
+        context: 'server',
+      }),
+      createSessionInfo({
+        sessionId: 's3',
+        instanceId: 'inst-b',
+        context: 'edit',
+      }),
+    ];
+    const conn = createMockConnection(sessions);
+
+    const result = await resolveSessionAsync(conn, {
+      instanceId: 'inst-a',
+      context: 'server',
+    });
+    expect(result.sessionId).toBe('s2');
+  });
+
+  it('throws when filters match zero sessions', async () => {
+    const sessions = [
+      createSessionInfo({
+        sessionId: 'ses-1',
+        instanceId: 'inst-a',
+        context: 'edit',
+      }),
+    ];
+    const conn = createMockConnection(sessions);
+
+    await expect(
+      resolveSessionAsync(conn, { context: 'server' })
+    ).rejects.toThrow('No matching sessions found');
+  });
+});

package/src/cli/resolve-session.ts

@@ -0,0 +1,66 @@
+/**
+ * CLI utility for resolving which studio-bridge session to target
+ * based on command-line arguments.
+ */
+
+import type { BridgeConnection } from '../bridge/index.js';
+import type { SessionInfo, SessionContext } from '../bridge/index.js';
+
+export interface ResolveSessionOptions {
+  sessionId?: string;
+  instanceId?: string;
+  context?: SessionContext;
+}
+
+/**
+ * Resolve which session to target based on CLI args.
+ *
+ * - If sessionId is provided, looks up that specific session.
+ * - Otherwise lists all sessions and filters by instanceId/context.
+ * - Auto-selects when exactly one session matches.
+ * - Throws descriptive errors on zero or ambiguous matches.
+ */
+export async function resolveSessionAsync(
+  connection: BridgeConnection,
+  options: ResolveSessionOptions = {}
+): Promise<SessionInfo> {
+  if (options.sessionId) {
+    const sessions = connection.listSessions();
+    const session = sessions.find((s) => s.sessionId === options.sessionId);
+    if (!session) {
+      throw new Error(`Session '${options.sessionId}' not found.`);
+    }
+    return session;
+  }
+
+  let sessions = connection.listSessions();
+
+  if (options.instanceId) {
+    sessions = sessions.filter((s) => s.instanceId === options.instanceId);
+  }
+
+  if (options.context) {
+    sessions = sessions.filter((s) => s.context === options.context);
+  }
+
+  if (sessions.length === 1) {
+    return sessions[0];
+  }
+
+  if (sessions.length === 0) {
+    throw new Error(
+      'No matching sessions found. Is Studio running with the studio-bridge plugin?'
+    );
+  }
+
+  const listing = sessions
+    .map(
+      (s) =>
+        `  - ${s.sessionId} (instance=${s.instanceId}, context=${s.context})`
+    )
+    .join('\n');
+
+  throw new Error(
+    `Multiple sessions found. Use --session or --instance to select one:\n${listing}`
+  );
+}

package/src/cli/script-executor.ts

@@ -24,6 +24,7 @@ export interface ExecuteScriptOptions {
   timeoutMs: number;
   verbose: boolean;
   showLogs: boolean;
+  filePath?: string;
 }
 
 /**
@@ -52,8 +53,26 @@ export async function resolvePlacePathAsync(
 export async function executeScriptAsync(
   options: ExecuteScriptOptions
 ): Promise<void> {
-  const { scriptContent, packageName, placePath, timeoutMs, verbose, showLogs } =
-    options;
+  const { shouldDelegateToDockerAsync, delegateToDockerAsync } = await import(
+    '../docker/docker-delegator.js'
+  );
+
+  if (await shouldDelegateToDockerAsync()) {
+    OutputHelper.verbose(
+      '[StudioBridge] No Wine detected, delegating to Docker'
+    );
+    await delegateToDockerAsync(options);
+    return; // unreachable — delegateToDockerAsync calls process.exit
+  }
+
+  const {
+    scriptContent,
+    packageName,
+    placePath,
+    timeoutMs,
+    verbose,
+    showLogs,
+  } = options;
 
   const useSpinner = !!process.stdout.isTTY && !verbose;
 
@@ -124,8 +143,7 @@ export async function executeScriptAsync(
       },
     });
   } catch (error) {
-    const errorMessage =
-      error instanceof Error ? error.message : String(error);
+    const errorMessage = error instanceof Error ? error.message : String(error);
     result = {
       success: false,
       logs: `[StudioBridge] Error: ${errorMessage}`,

package/src/cli/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared type definitions for studio-bridge CLI commands.
+ */
+
+/**
+ * Minimal command definition metadata used by the barrel export pattern.
+ */
+export interface CommandDefinition {
+  name: string;
+  description: string;
+}

package/src/commands/connect.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Unit tests for the connect command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { connectHandlerAsync } from './connect.js';
+
+function createMockConnection(sessionInfo: {
+  sessionId: string;
+  context: string;
+  placeName: string;
+}) {
+  return {
+    resolveSessionAsync: vi.fn().mockResolvedValue({
+      info: sessionInfo,
+    }),
+  } as any;
+}
+
+describe('connectHandlerAsync', () => {
+  it('resolves session and returns metadata', async () => {
+    const conn = createMockConnection({
+      sessionId: 'abc-123',
+      context: 'edit',
+      placeName: 'TestPlace',
+    });
+
+    const result = await connectHandlerAsync(conn, { sessionId: 'abc-123' });
+
+    expect(result.sessionId).toBe('abc-123');
+    expect(result.context).toBe('edit');
+    expect(result.placeName).toBe('TestPlace');
+    expect(result.summary).toContain('abc-123');
+    expect(result.summary).toContain('TestPlace');
+    expect(result.summary).toContain('edit');
+  });
+
+  it('passes sessionId to resolveSession', async () => {
+    const conn = createMockConnection({
+      sessionId: 'xyz-789',
+      context: 'server',
+      placeName: 'GamePlace',
+    });
+
+    await connectHandlerAsync(conn, { sessionId: 'xyz-789' });
+
+    expect(conn.resolveSessionAsync).toHaveBeenCalledWith('xyz-789');
+  });
+
+  it('propagates errors from resolveSession', async () => {
+    const conn = {
+      resolveSessionAsync: vi
+        .fn()
+        .mockRejectedValue(new Error('Session not found')),
+    } as any;
+
+    await expect(
+      connectHandlerAsync(conn, { sessionId: 'bad-id' })
+    ).rejects.toThrow('Session not found');
+  });
+});

package/src/commands/connect.ts

@@ -0,0 +1,32 @@
+/**
+ * Handler for the `connect` command. Resolves a session by ID and
+ * returns metadata about it so the caller can set it as the active session.
+ */
+
+import type { BridgeConnection } from '../bridge/index.js';
+
+export interface ConnectOptions {
+  sessionId: string;
+}
+
+export interface ConnectResult {
+  sessionId: string;
+  context: string;
+  placeName: string;
+  summary: string;
+}
+
+export async function connectHandlerAsync(
+  connection: BridgeConnection,
+  options: ConnectOptions
+): Promise<ConnectResult> {
+  const session = await connection.resolveSessionAsync(options.sessionId);
+  const info = session.info;
+
+  return {
+    sessionId: info.sessionId,
+    context: info.context,
+    placeName: info.placeName,
+    summary: `Connected to session ${info.sessionId} (${info.placeName}, ${info.context})`,
+  };
+}

package/src/commands/console/exec/exec.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Unit tests for the unified exec command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { execHandlerAsync, runHandlerAsync } from './exec.js';
+
+// Mock fs/promises.readFile for runHandlerAsync
+vi.mock('fs/promises', () => ({
+  readFile: vi.fn(),
+}));
+
+import * as fs from 'fs/promises';
+
+function createMockSession(execResult: {
+  success: boolean;
+  output: Array<{ level: string; body: string }>;
+  error?: string;
+}) {
+  return {
+    execAsync: vi.fn().mockResolvedValue(execResult),
+  } as any;
+}
+
+describe('execHandlerAsync', () => {
+  it('returns success result with summary', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [{ level: 'Print', body: 'Hello world' }],
+    });
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'print("Hello world")',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.output).toEqual(['Hello world']);
+    expect(result.error).toBeUndefined();
+    expect(result.summary).toBe('Script executed successfully');
+  });
+
+  it('returns failure result with error', async () => {
+    const session = createMockSession({
+      success: false,
+      output: [],
+      error: 'Syntax error on line 1',
+    });
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'bad code',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.output).toEqual([]);
+    expect(result.error).toBe('Syntax error on line 1');
+    expect(result.summary).toBe('Script failed: Syntax error on line 1');
+  });
+
+  it('forwards timeout to session.execAsync', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    await execHandlerAsync(session, {
+      scriptContent: 'print("test")',
+      timeout: 5000,
+    });
+
+    expect(session.execAsync).toHaveBeenCalledWith('print("test")', 5000);
+  });
+
+  it('passes undefined timeout when not specified', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    await execHandlerAsync(session, {
+      scriptContent: 'print("test")',
+    });
+
+    expect(session.execAsync).toHaveBeenCalledWith('print("test")', undefined);
+  });
+
+  it('captures multiple output lines', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [
+        { level: 'Print', body: 'line 1' },
+        { level: 'Print', body: 'line 2' },
+        { level: 'Warning', body: 'warning line' },
+      ],
+    });
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'print("line 1") print("line 2") warn("warning line")',
+    });
+
+    expect(result.output).toEqual(['line 1', 'line 2', 'warning line']);
+  });
+
+  it('handles empty output array', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'local x = 1',
+    });
+
+    expect(result.output).toEqual([]);
+  });
+
+  it('handles missing output field gracefully', async () => {
+    const session = {
+      execAsync: vi.fn().mockResolvedValue({
+        success: true,
+        output: undefined,
+      }),
+    } as any;
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'local x = 1',
+    });
+
+    expect(result.output).toEqual([]);
+  });
+
+  it('propagates errors from session', async () => {
+    const session = {
+      execAsync: vi.fn().mockRejectedValue(new Error('Connection lost')),
+    } as any;
+
+    await expect(
+      execHandlerAsync(session, { scriptContent: 'print("test")' })
+    ).rejects.toThrow('Connection lost');
+  });
+});
+
+describe('runHandlerAsync', () => {
+  it('reads file and delegates to session.execAsync', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('print("from file")');
+
+    const session = createMockSession({
+      success: true,
+      output: [{ level: 'Print', body: 'from file' }],
+    });
+
+    const result = await runHandlerAsync(session, {
+      scriptPath: '/tmp/test.lua',
+    });
+
+    expect(fs.readFile).toHaveBeenCalledWith('/tmp/test.lua', 'utf-8');
+    expect(session.execAsync).toHaveBeenCalledWith(
+      'print("from file")',
+      undefined
+    );
+    expect(result.success).toBe(true);
+    expect(result.output).toEqual(['from file']);
+    expect(result.summary).toBe('Script /tmp/test.lua executed successfully');
+  });
+
+  it('returns failure result with script path in summary', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('bad code');
+
+    const session = createMockSession({
+      success: false,
+      output: [],
+      error: 'Syntax error',
+    });
+
+    const result = await runHandlerAsync(session, {
+      scriptPath: '/tmp/broken.lua',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Syntax error');
+    expect(result.summary).toBe('Script /tmp/broken.lua failed: Syntax error');
+  });
+
+  it('forwards timeout to session.execAsync', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('print("test")');
+
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    await runHandlerAsync(session, {
+      scriptPath: '/tmp/test.lua',
+      timeout: 10_000,
+    });
+
+    expect(session.execAsync).toHaveBeenCalledWith('print("test")', 10_000);
+  });
+
+  it('throws when file cannot be read', async () => {
+    vi.mocked(fs.readFile).mockRejectedValue(
+      new Error('ENOENT: no such file or directory')
+    );
+
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    await expect(
+      runHandlerAsync(session, { scriptPath: '/tmp/missing.lua' })
+    ).rejects.toThrow('ENOENT');
+  });
+
+  it('captures multiple output lines', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('print("a") print("b")');
+
+    const session = createMockSession({
+      success: true,
+      output: [
+        { level: 'Print', body: 'a' },
+        { level: 'Print', body: 'b' },
+      ],
+    });
+
+    const result = await runHandlerAsync(session, {
+      scriptPath: '/tmp/multi.lua',
+    });
+
+    expect(result.output).toEqual(['a', 'b']);
+  });
+
+  it('handles empty output', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('local x = 1');
+
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    const result = await runHandlerAsync(session, {
+      scriptPath: '/tmp/silent.lua',
+    });
+
+    expect(result.output).toEqual([]);
+  });
+
+  it('propagates errors from session', async () => {
+    vi.mocked(fs.readFile).mockResolvedValue('print("test")');
+
+    const session = {
+      execAsync: vi.fn().mockRejectedValue(new Error('Connection lost')),
+    } as any;
+
+    await expect(
+      runHandlerAsync(session, { scriptPath: '/tmp/test.lua' })
+    ).rejects.toThrow('Connection lost');
+  });
+});