@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/commands/playtest/run/run.ts

@@ -0,0 +1,239 @@
+/**
+ * `playtest run` — start a playtest, execute Luau inside it, then stop it.
+ *
+ * The code runs in the playtest's server by default, or its client with
+ * `--context client`. Its output and return values come back the same way as
+ * `console exec`.
+ *
+ * In the server, the edit session plants a runner script in the playtest
+ * (playtest-runner.luau), so this works even when Studio does not load user
+ * plugins into playtests. The client has no such path: it needs the
+ * playtest's client session, so it needs that Studio setting on.
+ */
+
+import * as fs from 'fs/promises';
+import { resolvePackagePath } from '@quenty/nevermore-template-helpers';
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
+import {
+  execHandlerAsync,
+  formatExecText,
+  type ExecResult as CommandExecResult,
+} from '../../console/exec/exec.js';
+import type {
+  BridgeConnection,
+  BridgeSession,
+  ExecResult,
+  PlaytestMode,
+  SessionContext,
+} from '../../../bridge/index.js';
+import type { SerializedReturnValue } from '../../../server/web-socket-protocol.js';
+import {
+  endPlaytestAsync,
+  getPlaytestContexts,
+  startPlaytestAsync,
+} from '../playtest-sessions.js';
+
+export interface PlaytestRunOptions {
+  scriptContent: string;
+  mode: PlaytestMode;
+  /** Which playtest DataModel runs the code. */
+  context: SessionContext;
+  /** Picks the edit session to start the playtest from. */
+  target?: string;
+  timeout?: number;
+  /** Passed to the script as `...`. */
+  args?: string[];
+}
+
+/** Matches `console exec`'s default execution timeout. */
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface PlaytestRunResult {
+  success: boolean;
+  /** Absent when the script ran through the planted runner. */
+  playtestId?: string;
+  output: string[];
+  error?: string;
+  returnValues?: SerializedReturnValue[];
+  /** Set when the script ran but the playtest could not be stopped. */
+  stopError?: string;
+  summary: string;
+}
+
+interface PlaytestRunArgs {
+  code?: string;
+  file?: string;
+  mode?: PlaytestMode;
+  timeout?: number;
+  scriptArgs?: string[];
+}
+
+export async function playtestRunHandlerAsync(
+  connection: BridgeConnection,
+  options: PlaytestRunOptions
+): Promise<PlaytestRunResult> {
+  if (!getPlaytestContexts(options.mode).includes(options.context)) {
+    throw new Error(
+      `A ${options.mode} mode playtest has no ${options.context} session to run code in`
+    );
+  }
+
+  const editSession = await connection.resolveSessionAsync(
+    options.target,
+    'edit'
+  );
+
+  if (options.context === 'server') {
+    return runWithPlantedRunnerAsync(editSession, options);
+  }
+
+  const playtest = await startPlaytestAsync(
+    connection,
+    editSession,
+    options.mode
+  );
+
+  let result: PlaytestRunResult;
+  try {
+    const session = playtest.sessions[options.context];
+    if (!session) {
+      throw new Error(`Playtest has no ${options.context} session`);
+    }
+
+    result = {
+      ...(await execHandlerAsync(session, {
+        scriptContent: options.scriptContent,
+        timeout: options.timeout,
+        args: options.args,
+      })),
+      playtestId: playtest.playtestId,
+    };
+  } catch (err) {
+    await tryEndPlaytestAsync(connection, playtest.sessions.server);
+    throw err;
+  }
+
+  // A playtest left running keeps the script's result worth reporting
+  const stopError = await tryEndPlaytestAsync(
+    connection,
+    playtest.sessions.server
+  );
+  return stopError ? { ...result, stopError } : result;
+}
+
+async function runWithPlantedRunnerAsync(
+  editSession: BridgeSession,
+  options: PlaytestRunOptions
+): Promise<PlaytestRunResult> {
+  const runnerSource = await fs.readFile(
+    resolvePackagePath(
+      import.meta.url,
+      'src',
+      'commands',
+      'playtest',
+      'run',
+      'playtest-runner.luau'
+    ),
+    'utf-8'
+  );
+
+  const result = await editSession.runPlaytestScriptAsync({
+    mode: options.mode,
+    script: options.scriptContent,
+    runnerSource,
+    timeoutSec: (options.timeout ?? DEFAULT_TIMEOUT_MS) / 1000,
+    args: options.args,
+  });
+
+  return toCommandResult(result);
+}
+
+/** Shapes a bridge ExecResult the way `console exec` reports it. */
+function toCommandResult(result: ExecResult): CommandExecResult {
+  return {
+    success: result.success,
+    output: result.output.map((entry) => entry.body),
+    error: result.error,
+    returnValues: result.returnValues,
+    summary: result.success
+      ? 'Script executed successfully'
+      : `Script failed: ${result.error}`,
+  };
+}
+
+/** Ends the playtest, returning why it could not instead of throwing. */
+async function tryEndPlaytestAsync(
+  connection: BridgeConnection,
+  serverSession: BridgeSession | undefined
+): Promise<string | undefined> {
+  // The script may have ended the playtest itself
+  if (!serverSession?.isConnected) {
+    return undefined;
+  }
+
+  try {
+    await endPlaytestAsync(connection, serverSession);
+    return undefined;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+export const playtestRunCommand = defineCommand<
+  PlaytestRunArgs,
+  PlaytestRunResult
+>({
+  group: 'playtest',
+  name: 'run',
+  description:
+    'Start a playtest, execute Luau in it, then stop it (--context picks server or client)',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'connection',
+  args: {
+    code: arg.positional({
+      description: 'Inline Luau code to execute',
+      required: false,
+    }),
+    file: arg.option({
+      description: 'Path to a Luau script file to execute',
+      alias: 'f',
+    }),
+    mode: arg.option({
+      description:
+        'play runs a server and a client with a player, run runs only the server',
+      choices: ['play', 'run'],
+      default: 'play',
+    }),
+    timeout: arg.option({
+      description: 'Execution timeout in milliseconds',
+      type: 'number',
+    }),
+    scriptArgs: arg.passthrough({
+      description:
+        'Arguments after --, passed to the script as ... (all strings)',
+    }),
+  },
+  cli: {
+    format: (result) =>
+      result.stopError
+        ? `${formatExecText(result)}\nPlaytest is still running: ${
+            result.stopError
+          }`
+        : formatExecText(result),
+  },
+  handler: async (connection, args, targeting) => {
+    const { scriptContent } = await resolveScriptContentAsync(args);
+
+    return playtestRunHandlerAsync(connection, {
+      scriptContent,
+      mode: args.mode ?? 'play',
+      context: targeting.context ?? 'server',
+      target: targeting.target,
+      timeout: args.timeout,
+      args: args.scriptArgs,
+    });
+  },
+});

package/src/commands/playtest/start/start-playtest.lua

@@ -0,0 +1,108 @@
+--!strict
+--[=[
+	Action that starts a Studio playtest through StudioTestService, answering with
+	`playtestEnded` once the playtest is over.
+
+	- ExecutePlayModeAsync and ExecuteRunModeAsync yield until the playtest ends,
+	  so the reply comes at the end, not the start. The bridge learns the
+	  playtest started from its server session connecting.
+	- A playtest already in progress fails the call only after it yields, so a
+	  refusal also arrives as a `playtestEnded` reply, with `success = false`.
+	- With `players`, it starts a multiplayer test instead: a server and a
+	  client per player, each in its own Studio process.
+	- The playtest id, bridge port and edit instance id ride along as the test
+	  args. The playtest's DataModels cannot make the HTTP requests port
+	  discovery needs, so the plugin in each connects straight to that port,
+	  registers under the edit session's instance, and answers with the
+	  playtest id when asked which playtest it belongs to.
+
+	Request: `{ type: "startPlaytest", payload: { mode: "play" | "run", playtestId, bridgePort, instanceId, players? } }`
+	Response: `{ type: "playtestEnded", payload: { playtestId, success, error? } }`
+
+	@class StartPlaytestAction
+]=]
+
+local StartPlaytestAction = {}
+
+type SendMessage = (message: { [string]: any }) -> ()
+
+--[=[
+	Registers the `startPlaytest` handler. The reply waits for the playtest to
+	end, so it needs `sendMessage`.
+]=]
+function StartPlaytestAction.register(router: any, sendMessage: SendMessage?)
+	router:setResponseType("startPlaytest", "playtestEnded")
+	router:register(
+		"startPlaytest",
+		function(payload: { [string]: any }, requestId: string, sessionId: string): { [string]: any }?
+			local mode = payload.mode
+			if mode ~= "play" and mode ~= "run" then
+				error(`Unknown playtest mode: {tostring(mode)}`)
+			end
+
+			local playtestId = payload.playtestId
+			local bridgePort = payload.bridgePort
+			local instanceId = payload.instanceId
+			if type(playtestId) ~= "string" or type(bridgePort) ~= "number" or type(instanceId) ~= "string" then
+				error("Missing playtestId, bridgePort or instanceId in startPlaytest request")
+			end
+
+			if not sendMessage then
+				error("Starting a playtest requires a sendMessage callback")
+			end
+
+			local players = payload.players
+			if players ~= nil and (type(players) ~= "number" or players < 1) then
+				error(`Invalid player count: {tostring(players)}`)
+			end
+
+			local testArgs = {
+				studioBridgePlaytestId = playtestId,
+				studioBridgePort = bridgePort,
+				studioBridgeInstanceId = instanceId,
+				studioBridgePlayers = players,
+			}
+			task.spawn(StartPlaytestAction._runAsync, sendMessage, mode, testArgs, requestId, sessionId)
+
+			-- Replied through sendMessage, so the router must not reply as well
+			return nil
+		end
+	)
+end
+
+function StartPlaytestAction._runAsync(
+	sendMessage: SendMessage,
+	mode: string,
+	testArgs: {
+		studioBridgePlaytestId: string,
+		studioBridgePort: number,
+		studioBridgeInstanceId: string,
+		studioBridgePlayers: number?,
+	},
+	requestId: string,
+	sessionId: string
+)
+	local ok, err = pcall(function()
+		local studioTestService = game:GetService("StudioTestService") :: any
+		if testArgs.studioBridgePlayers then
+			studioTestService:ExecuteMultiplayerTestAsync(testArgs.studioBridgePlayers, testArgs)
+		elseif mode == "play" then
+			studioTestService:ExecutePlayModeAsync(testArgs)
+		else
+			studioTestService:ExecuteRunModeAsync(testArgs)
+		end
+	end)
+
+	sendMessage({
+		type = "playtestEnded",
+		sessionId = sessionId,
+		requestId = if requestId ~= "" then requestId else nil,
+		payload = {
+			playtestId = testArgs.studioBridgePlaytestId,
+			success = ok,
+			error = if ok then nil else tostring(err),
+		},
+	})
+end
+
+return StartPlaytestAction

package/src/commands/playtest/start/start.ts

@@ -0,0 +1,138 @@
+/**
+ * `playtest start` — start a StudioTestService playtest and leave it running.
+ *
+ * Resolves once the playtest's sessions connect, so the next command can
+ * target them with `--context server` or `--context client`.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type {
+  BridgeConnection,
+  PlaytestMode,
+  SessionContext,
+} from '../../../bridge/index.js';
+import {
+  startPlaytestAsync,
+  type StartedPlaytest,
+} from '../playtest-sessions.js';
+
+export interface PlaytestStartOptions {
+  mode: PlaytestMode;
+  /** Starts a multiplayer test with this many players. */
+  players?: number;
+  target?: string;
+}
+
+export interface PlaytestStartResult {
+  playtestId: string;
+  mode: PlaytestMode;
+  /** How many players a multiplayer test started with. */
+  playerCount?: number;
+  sessions: Array<{
+    sessionId: string;
+    context: SessionContext;
+    playerName?: string;
+  }>;
+  summary: string;
+}
+
+interface PlaytestStartArgs {
+  mode?: PlaytestMode;
+  players?: number;
+}
+
+export async function playtestStartHandlerAsync(
+  connection: BridgeConnection,
+  options: PlaytestStartOptions
+): Promise<PlaytestStartResult> {
+  const editSession = await connection.resolveSessionAsync(
+    options.target,
+    'edit'
+  );
+  const playtest = await startPlaytestAsync(
+    connection,
+    editSession,
+    options.mode,
+    options.players
+  );
+
+  return toPlaytestStartResult(
+    playtest,
+    `Playtest started (${describePlaytest(playtest)})`
+  );
+}
+
+/** `play mode`, `run mode`, or `3 players` for a multiplayer test. */
+export function describePlaytest(playtest: {
+  mode: PlaytestMode;
+  players?: number;
+}): string {
+  return playtest.players !== undefined
+    ? `${playtest.players} player${playtest.players === 1 ? '' : 's'}`
+    : `${playtest.mode} mode`;
+}
+
+/** Report a started playtest and the sessions it opened. */
+export function toPlaytestStartResult(
+  playtest: StartedPlaytest,
+  summary: string
+): PlaytestStartResult {
+  return {
+    playtestId: playtest.playtestId,
+    mode: playtest.mode,
+    playerCount: playtest.players,
+    sessions: [playtest.sessions.server, ...playtest.clients]
+      .filter((session) => session !== undefined)
+      .map((session) => ({
+        sessionId: session.info.sessionId,
+        context: session.context,
+        playerName: session.info.playerName,
+      })),
+    summary,
+  };
+}
+
+export function formatPlaytestStartText(result: PlaytestStartResult): string {
+  return [
+    result.summary,
+    ...result.sessions.map(
+      (session) => `  ${session.context.padEnd(7)}${session.sessionId}`
+    ),
+  ].join('\n');
+}
+
+export const playtestStartCommand = defineCommand<
+  PlaytestStartArgs,
+  PlaytestStartResult
+>({
+  group: 'playtest',
+  name: 'start',
+  description:
+    'Start a playtest and leave it running (--target picks the edit session)',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'connection',
+  args: {
+    mode: arg.option({
+      description:
+        'play runs a server and a client with a player, run runs only the server',
+      choices: ['play', 'run'],
+      default: 'play',
+    }),
+    players: arg.option({
+      description:
+        'Start a multiplayer test: a server and a client per player, each in its own Studio window',
+      type: 'number',
+    }),
+  },
+  cli: {
+    format: formatPlaytestStartText,
+  },
+  handler: async (connection, args, targeting) =>
+    playtestStartHandlerAsync(connection, {
+      mode: args.mode ?? 'play',
+      players: args.players,
+      target: targeting.target,
+    }),
+});

package/src/commands/playtest/stop/end-playtest.lua

@@ -0,0 +1,47 @@
+--!strict
+--[=[
+	Action that ends the playtest the session belongs to, answering with the
+	playtest id studio-bridge started it under and the mode it runs in, so the
+	playtest can be restarted the same way.
+
+	StudioTestService only allows `EndTest` in the server DataModel of a running
+	playtest, so this must target the server session. The playtest stops after
+	the reply is sent, since stopping tears down the DataModel answering.
+
+	Request: `{ type: "endPlaytest", payload: {} }`
+	Response: `{ type: "endPlaytestResult", payload: { playtestId?, mode, players? } }`
+
+	@class EndPlaytestAction
+]=]
+
+local EndPlaytestAction = {}
+
+--[=[
+	Registers the `endPlaytest` handler.
+]=]
+function EndPlaytestAction.register(router: any)
+	router:setResponseType("endPlaytest", "endPlaytestResult")
+	router:register("endPlaytest", function(_payload: { [string]: any }, _requestId: string, _sessionId: string)
+		local runService = game:GetService("RunService")
+		if not (runService:IsRunning() and runService:IsServer()) then
+			error("Only the server session of a running playtest can end it")
+		end
+
+		local studioTestService = game:GetService("StudioTestService") :: any
+		local testArgs = studioTestService:GetTestArgs()
+
+		-- EndTest rejects nil; the value goes unused, since the bridge reads results through execute
+		task.defer(function()
+			studioTestService:EndTest(true)
+		end)
+
+		local isStudioBridgeTest = type(testArgs) == "table"
+		return {
+			playtestId = if isStudioBridgeTest then testArgs.studioBridgePlaytestId else nil,
+			mode = if runService:IsRunMode() then "run" else "play",
+			players = if isStudioBridgeTest then testArgs.studioBridgePlayers else nil,
+		}
+	end)
+end
+
+return EndPlaytestAction

package/src/commands/playtest/stop/stop.ts

@@ -0,0 +1,51 @@
+/**
+ * `playtest stop` — end a running playtest from its server session.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import type { BridgeConnection } from '../../../bridge/index.js';
+import {
+  endPlaytestAsync,
+  resolvePlaytestServerSessionAsync,
+} from '../playtest-sessions.js';
+
+export interface PlaytestStopOptions {
+  target?: string;
+}
+
+export interface PlaytestStopResult {
+  /** Absent when the playtest was not started by studio-bridge. */
+  playtestId?: string;
+  summary: string;
+}
+
+export async function playtestStopHandlerAsync(
+  connection: BridgeConnection,
+  options: PlaytestStopOptions = {}
+): Promise<PlaytestStopResult> {
+  const serverSession = await resolvePlaytestServerSessionAsync(
+    connection,
+    options.target
+  );
+  const { playtestId } = await endPlaytestAsync(connection, serverSession);
+
+  return {
+    playtestId,
+    summary: 'Playtest stopped',
+  };
+}
+
+export const playtestStopCommand = defineCommand<
+  Record<string, never>,
+  PlaytestStopResult
+>({
+  group: 'playtest',
+  name: 'stop',
+  description: 'Stop the running playtest (--target picks its server session)',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'connection',
+  args: {},
+  handler: async (connection, _args, targeting) =>
+    playtestStopHandlerAsync(connection, { target: targeting.target }),
+});