@quenty/studio-bridge 0.21.1 → 0.22.0

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

@@ -3,7 +3,12 @@
  */
 
 import { describe, it, expect, vi } from 'vitest';
-import { execHandlerAsync, runHandlerAsync } from './exec.js';
+import {
+  execCommand,
+  execHandlerAsync,
+  runHandlerAsync,
+  type ExecResult,
+} from './exec.js';
 
 // Mock fs/promises.readFile for runHandlerAsync
 vi.mock('fs/promises', () => ({
@@ -67,7 +72,28 @@ describe('execHandlerAsync', () => {
       timeout: 5000,
     });
 
-    expect(session.execAsync).toHaveBeenCalledWith('print("test")', 5000);
+    expect(session.execAsync).toHaveBeenCalledWith(
+      'print("test")',
+      5000,
+      undefined
+    );
+  });
+
+  it('forwards script args to session.execAsync', async () => {
+    const session = createMockSession({
+      success: true,
+      output: [],
+    });
+
+    await execHandlerAsync(session, {
+      scriptContent: 'return ...',
+      args: ['Player1', '3'],
+    });
+
+    expect(session.execAsync).toHaveBeenCalledWith('return ...', undefined, [
+      'Player1',
+      '3',
+    ]);
   });
 
   it('passes undefined timeout when not specified', async () => {
@@ -80,7 +106,11 @@ describe('execHandlerAsync', () => {
       scriptContent: 'print("test")',
     });
 
-    expect(session.execAsync).toHaveBeenCalledWith('print("test")', undefined);
+    expect(session.execAsync).toHaveBeenCalledWith(
+      'print("test")',
+      undefined,
+      undefined
+    );
   });
 
   it('captures multiple output lines', async () => {
@@ -137,6 +167,69 @@ describe('execHandlerAsync', () => {
       execHandlerAsync(session, { scriptContent: 'print("test")' })
     ).rejects.toThrow('Connection lost');
   });
+
+  it('carries the return values through', async () => {
+    const session = {
+      execAsync: vi.fn().mockResolvedValue({
+        success: true,
+        output: [],
+        returnValues: [12345, { type: 'Nil' }],
+      }),
+    } as any;
+
+    const result = await execHandlerAsync(session, {
+      scriptContent: 'return game.PlaceId, nil',
+    });
+
+    expect(result.returnValues).toEqual([12345, { type: 'Nil' }]);
+  });
+});
+
+describe('execCommand text format', () => {
+  const format = execCommand.cli!.format!;
+
+  function formatResult(result: Partial<ExecResult>): string {
+    return format({
+      success: true,
+      output: [],
+      summary: 'Script executed successfully',
+      ...result,
+    });
+  }
+
+  it('prints a returned string raw so returned JSON stays parseable', () => {
+    expect(formatResult({ returnValues: ['{"ok":true}'] })).toBe('{"ok":true}');
+  });
+
+  it('prints output lines before the return values', () => {
+    expect(formatResult({ output: ['hello'], returnValues: [42, true] })).toBe(
+      'hello\n42\ttrue'
+    );
+  });
+
+  it('spells a returned nil and JSON-encodes tables and datatypes', () => {
+    expect(
+      formatResult({
+        returnValues: [
+          { type: 'Nil' },
+          [1, 2],
+          { type: 'Vector3', value: [1, 2, 3] },
+        ],
+      })
+    ).toBe('nil\t[1,2]\t{"type":"Vector3","value":[1,2,3]}');
+  });
+
+  it('falls back to the summary when nothing was printed or returned', () => {
+    expect(formatResult({ returnValues: [] })).toBe(
+      'Script executed successfully'
+    );
+  });
+
+  it('appends the error after any output', () => {
+    expect(
+      formatResult({ success: false, output: ['before'], error: 'boom' })
+    ).toBe('before\nboom');
+  });
 });
 
 describe('runHandlerAsync', () => {

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

@@ -6,20 +6,26 @@
  */
 
 import * as fs from 'fs/promises';
+import { OutputHelper } from '@quenty/cli-output-helpers';
 import { defineCommand } from '../../framework/define-command.js';
 import { arg } from '../../framework/arg-builder.js';
 import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
 import type { BridgeSession } from '../../../bridge/index.js';
+import type { SerializedReturnValue } from '../../../server/web-socket-protocol.js';
 
 export interface ExecOptions {
   scriptContent: string;
   timeout?: number;
+  /** Passed to the script as `...`. */
+  args?: string[];
 }
 
 export interface ExecResult {
   success: boolean;
   output: string[];
   error?: string;
+  traceback?: string;
+  returnValues?: SerializedReturnValue[];
   summary: string;
 }
 
@@ -32,6 +38,8 @@ export interface RunResult {
   success: boolean;
   output: string[];
   error?: string;
+  traceback?: string;
+  returnValues?: SerializedReturnValue[];
   summary: string;
 }
 
@@ -39,6 +47,7 @@ interface ConsoleExecArgs {
   code?: string;
   file?: string;
   timeout?: number;
+  scriptArgs?: string[];
 }
 
 /**
@@ -50,7 +59,8 @@ export async function execHandlerAsync(
 ): Promise<ExecResult> {
   const result = await session.execAsync(
     options.scriptContent,
-    options.timeout
+    options.timeout,
+    options.args
   );
 
   const output = (result.output ?? []).map((entry) =>
@@ -61,6 +71,8 @@ export async function execHandlerAsync(
     success: result.success,
     output,
     error: result.error,
+    traceback: result.traceback,
+    returnValues: result.returnValues,
     summary: result.success
       ? 'Script executed successfully'
       : `Script failed: ${result.error}`,
@@ -85,18 +97,58 @@ export async function runHandlerAsync(
     success: result.success,
     output,
     error: result.error,
+    traceback: result.traceback,
+    returnValues: result.returnValues,
     summary: result.success
       ? `Script ${options.scriptPath} executed successfully`
       : `Script ${options.scriptPath} failed: ${result.error}`,
   };
 }
 
+export function formatReturnValues(
+  returnValues: SerializedReturnValue[]
+): string {
+  return returnValues
+    .map((value) => {
+      if (typeof value === 'string') return value;
+      if (
+        typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.type === 'Nil'
+      ) {
+        return 'nil';
+      }
+      return JSON.stringify(value);
+    })
+    .join('\t');
+}
+
+/** Render an exec result as its output, then its return values, then its error. */
+export function formatExecText(result: {
+  output: string[];
+  returnValues?: SerializedReturnValue[];
+  error?: string;
+  traceback?: string;
+  summary: string;
+}): string {
+  const lines = [...result.output];
+  if (result.returnValues && result.returnValues.length > 0) {
+    lines.push(formatReturnValues(result.returnValues));
+  }
+  if (result.error) lines.push(result.error);
+  if (result.traceback)
+    lines.push(OutputHelper.formatDim(result.traceback.trimEnd()));
+  return lines.length > 0 ? lines.join('\n') : result.summary;
+}
+
 export const execCommand = defineCommand<ConsoleExecArgs, ExecResult>({
   group: 'console',
   name: 'exec',
   description: 'Execute Luau code in a connected Studio session',
   category: 'execution',
   safety: 'mutate',
+  changesDataModel: true,
   scope: 'session',
   args: {
     code: arg.positional({
@@ -111,13 +163,13 @@ export const execCommand = defineCommand<ConsoleExecArgs, ExecResult>({
       description: 'Execution timeout in milliseconds',
       type: 'number',
     }),
+    scriptArgs: arg.passthrough({
+      description:
+        'Arguments after --, passed to the script as ... (all strings)',
+    }),
   },
   cli: {
-    format: (result) => {
-      const lines = result.output.join('\n');
-      if (result.error) return lines + (lines ? '\n' : '') + result.error;
-      return lines || result.summary;
-    },
+    format: formatExecText,
   },
   handler: async (session, args) => {
     const { scriptContent } = await resolveScriptContentAsync(args);
@@ -125,6 +177,7 @@ export const execCommand = defineCommand<ConsoleExecArgs, ExecResult>({
     return execHandlerAsync(session, {
       scriptContent,
       timeout: args.timeout,
+      args: args.scriptArgs,
     });
   },
 });