@quenty/studio-bridge 0.21.1 → 0.22.1

package/src/commands/playtest/player/playtest-players.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  addPlaytestPlayersAsync,
+  listPlaytestPlayersAsync,
+  removePlaytestPlayersAsync,
+} from './playtest-players.js';
+
+function createSession(
+  sessionId: string,
+  context: string,
+  returnValues: unknown[][],
+  playerName?: string
+) {
+  const scripts: string[] = [];
+  return {
+    scripts,
+    info: { sessionId, instanceId: 'place-1a2b', context, playerName },
+    context,
+    execAsync: vi.fn(async (script: string) => {
+      scripts.push(script);
+      return { success: true, output: [], returnValues: returnValues.shift() };
+    }),
+  };
+}
+
+function createConnection(sessions: Array<ReturnType<typeof createSession>>) {
+  return {
+    listSessions: () => sessions.map((s) => s.info),
+    getSession: (id: string) => sessions.find((s) => s.info.sessionId === id),
+  } as any;
+}
+
+const player = (name: string, userId: number) => ({
+  name,
+  userId,
+  displayName: name,
+});
+
+describe('listPlaytestPlayersAsync', () => {
+  it('pairs each player with its client session', async () => {
+    const server = createSession('place-1a2b-server', 'server', [
+      [[player('Player1', -1), player('Player2', -2)]],
+    ]);
+    const client = createSession(
+      'place-1a2b-client-player1',
+      'client',
+      [],
+      'Player1'
+    );
+
+    const players = await listPlaytestPlayersAsync(
+      createConnection([server, client]),
+      server as any
+    );
+
+    expect(players).toEqual([
+      { ...player('Player1', -1), sessionId: 'place-1a2b-client-player1' },
+      player('Player2', -2),
+    ]);
+  });
+});
+
+describe('addPlaytestPlayersAsync', () => {
+  it('adds players from the server and reports the ones that joined', async () => {
+    const server = createSession('place-1a2b-server', 'server', [
+      [[player('Player3', -3)]],
+    ]);
+    const client = createSession(
+      'place-1a2b-client-player3',
+      'client',
+      [],
+      'Player3'
+    );
+
+    const players = await addPlaytestPlayersAsync(
+      createConnection([server, client]),
+      server as any,
+      1
+    );
+
+    expect(server.scripts[0]).toContain('AddPlayers(1)');
+    expect(players).toEqual([
+      { ...player('Player3', -3), sessionId: 'place-1a2b-client-player3' },
+    ]);
+  });
+});
+
+describe('removePlaytestPlayersAsync', () => {
+  it('has a connected client leave and kicks the rest', async () => {
+    const server = createSession('place-1a2b-server', 'server', [
+      [[player('Player1', -1), player('Player2', -2)]],
+      [],
+      [[]],
+    ]);
+    const client = createSession(
+      'place-1a2b-client-player1',
+      'client',
+      [[]],
+      'Player1'
+    );
+
+    const removed = await removePlaytestPlayersAsync(
+      createConnection([server, client]),
+      server as any,
+      ['player1', 'Player2']
+    );
+
+    expect(removed).toEqual([
+      { name: 'Player1', how: 'left' },
+      { name: 'Player2', how: 'kicked' },
+    ]);
+    expect(client.scripts[0]).toContain('LeaveTest');
+    expect(server.scripts[1]).toContain('"Player2"');
+    expect(server.scripts[1]).not.toContain('"Player1"');
+  });
+
+  it('removes a player named twice only once', async () => {
+    const server = createSession('place-1a2b-server', 'server', [
+      [[player('Player2', -2)]],
+      [],
+      [[]],
+    ]);
+
+    const removed = await removePlaytestPlayersAsync(
+      createConnection([server]),
+      server as any,
+      ['Player2', 'player2']
+    );
+
+    expect(removed).toEqual([{ name: 'Player2', how: 'kicked' }]);
+  });
+
+  it('refuses an unknown name before removing anyone', async () => {
+    const server = createSession('place-1a2b-server', 'server', [
+      [[player('Player1', -1)]],
+    ]);
+
+    await expect(
+      removePlaytestPlayersAsync(createConnection([server]), server as any, [
+        'Player1',
+        'Nobody',
+      ])
+    ).rejects.toThrow("No player named 'Nobody' (players: Player1)");
+    expect(server.scripts).toHaveLength(1);
+  });
+});

package/src/commands/playtest/player/playtest-players.ts

@@ -0,0 +1,270 @@
+/**
+ * The players of a running playtest, read and changed through its server
+ * session.
+ *
+ * StudioTestService only adds players from the server DataModel of a
+ * multiplayer test, and each player is a client in its own Studio process.
+ * Kicking a player leaves that process open, so a player whose client
+ * session is connected leaves through `LeaveTest` instead, which closes it.
+ */
+
+import type { BridgeConnection, BridgeSession } from '../../../bridge/index.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  formatTable,
+  type TableColumn,
+} from '@quenty/cli-output-helpers/reporting';
+
+const PLAYER_CHANGE_TIMEOUT_SEC = 60;
+const CLIENT_SESSION_TIMEOUT_MS = 30_000;
+const SCRIPT_GRACE_MS = 10_000;
+
+export interface PlaytestPlayer {
+  name: string;
+  userId: number;
+  displayName: string;
+  /** The player's client session, when it is connected. */
+  sessionId?: string;
+}
+
+const PLAYER_INFO_FUNCTION = [
+  'local function playerInfo(player)',
+  '\treturn { name = player.Name, userId = player.UserId, displayName = player.DisplayName }',
+  'end',
+].join('\n');
+
+const LIST_PLAYERS_SCRIPT = [
+  PLAYER_INFO_FUNCTION,
+  'local players = {}',
+  'for _, player in game:GetService("Players"):GetPlayers() do',
+  '\ttable.insert(players, playerInfo(player))',
+  'end',
+  'return players',
+].join('\n');
+
+function addPlayersScript(count: number): string {
+  return [
+    PLAYER_INFO_FUNCTION,
+    'local Players = game:GetService("Players")',
+    'local before = {}',
+    'for _, player in Players:GetPlayers() do',
+    '\tbefore[player] = true',
+    'end',
+    `game:GetService("StudioTestService"):AddPlayers(${count})`,
+    `local deadline = os.clock() + ${PLAYER_CHANGE_TIMEOUT_SEC}`,
+    'local added = {}',
+    'repeat',
+    '\ttask.wait(0.25)',
+    '\tadded = {}',
+    '\tfor _, player in Players:GetPlayers() do',
+    '\t\tif not before[player] then',
+    '\t\t\ttable.insert(added, playerInfo(player))',
+    '\t\tend',
+    '\tend',
+    `until #added >= ${count} or os.clock() > deadline`,
+    'return added',
+  ].join('\n');
+}
+
+function kickPlayersScript(names: string[]): string {
+  return [
+    `local names = ${luaStringList(names)}`,
+    'local Players = game:GetService("Players")',
+    'for _, name in names do',
+    '\tlocal player = Players:FindFirstChild(name)',
+    '\tif player then',
+    '\t\tplayer:Kick("Removed by studio-bridge")',
+    '\tend',
+    'end',
+  ].join('\n');
+}
+
+function waitForPlayersGoneScript(names: string[]): string {
+  return [
+    `local names = ${luaStringList(names)}`,
+    'local Players = game:GetService("Players")',
+    `local deadline = os.clock() + ${PLAYER_CHANGE_TIMEOUT_SEC}`,
+    'local remaining',
+    'repeat',
+    '\tremaining = {}',
+    '\tfor _, name in names do',
+    '\t\tif Players:FindFirstChild(name) then',
+    '\t\t\ttable.insert(remaining, name)',
+    '\t\tend',
+    '\tend',
+    '\tif #remaining > 0 then',
+    '\t\ttask.wait(0.25)',
+    '\tend',
+    'until #remaining == 0 or os.clock() > deadline',
+    'return remaining',
+  ].join('\n');
+}
+
+const LEAVE_TEST_SCRIPT =
+  'task.defer(function() game:GetService("StudioTestService"):LeaveTest() end)';
+
+function luaStringList(values: string[]): string {
+  return `{ ${values.map((value) => JSON.stringify(value)).join(', ')} }`;
+}
+
+async function runScriptAsync(
+  session: BridgeSession,
+  script: string
+): Promise<unknown> {
+  const result = await session.execAsync(
+    script,
+    PLAYER_CHANGE_TIMEOUT_SEC * 1000 + SCRIPT_GRACE_MS
+  );
+  if (!result.success) {
+    throw new Error(result.error ?? 'Player script failed');
+  }
+  return result.returnValues?.[0];
+}
+
+function toPlayers(value: unknown): PlaytestPlayer[] {
+  if (!Array.isArray(value)) return [];
+  return value.map((entry) => ({
+    name: String(entry.name),
+    userId: Number(entry.userId),
+    displayName: String(entry.displayName),
+  }));
+}
+
+function findClientSession(
+  connection: BridgeConnection,
+  instanceId: string,
+  playerName: string
+): BridgeSession | undefined {
+  const info = connection
+    .listSessions()
+    .find(
+      (s) =>
+        s.instanceId === instanceId &&
+        s.context === 'client' &&
+        s.playerName === playerName
+    );
+  return info ? connection.getSession(info.sessionId) : undefined;
+}
+
+function withSessions(
+  connection: BridgeConnection,
+  instanceId: string,
+  players: PlaytestPlayer[]
+): PlaytestPlayer[] {
+  return players.map((player) => {
+    const session = findClientSession(connection, instanceId, player.name);
+    return session ? { ...player, sessionId: session.info.sessionId } : player;
+  });
+}
+
+/** The players in the playtest `serverSession` belongs to. */
+export async function listPlaytestPlayersAsync(
+  connection: BridgeConnection,
+  serverSession: BridgeSession
+): Promise<PlaytestPlayer[]> {
+  const players = toPlayers(
+    await runScriptAsync(serverSession, LIST_PLAYERS_SCRIPT)
+  );
+  return withSessions(connection, serverSession.info.instanceId, players);
+}
+
+/**
+ * Add `count` players to a multiplayer test, resolving with them once they
+ * have joined and their client sessions have connected, or after a timeout.
+ */
+export async function addPlaytestPlayersAsync(
+  connection: BridgeConnection,
+  serverSession: BridgeSession,
+  count: number
+): Promise<PlaytestPlayer[]> {
+  const added = toPlayers(
+    await runScriptAsync(serverSession, addPlayersScript(count))
+  );
+  const { instanceId } = serverSession.info;
+
+  const deadline = Date.now() + CLIENT_SESSION_TIMEOUT_MS;
+  while (
+    Date.now() < deadline &&
+    added.some(
+      (player) => !findClientSession(connection, instanceId, player.name)
+    )
+  ) {
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+
+  return withSessions(connection, instanceId, added);
+}
+
+export interface RemovedPlayer {
+  name: string;
+  /** `left` closed the player's client; `kicked` leaves its window open. */
+  how: 'left' | 'kicked';
+}
+
+/**
+ * Remove players by name, case-insensitively, resolving once they are gone.
+ * Throws for a name that is not in the playtest, before removing anyone.
+ */
+export async function removePlaytestPlayersAsync(
+  connection: BridgeConnection,
+  serverSession: BridgeSession,
+  names: string[]
+): Promise<RemovedPlayer[]> {
+  const current = await listPlaytestPlayersAsync(connection, serverSession);
+  const found = names.map((name) => {
+    const player = current.find(
+      (p) => p.name.toLowerCase() === name.toLowerCase()
+    );
+    if (!player) {
+      const known = current.map((p) => p.name).join(', ') || 'none';
+      throw new Error(`No player named '${name}' (players: ${known})`);
+    }
+    return player;
+  });
+  const targets = [...new Set(found)];
+
+  const removed: RemovedPlayer[] = [];
+  const toKick: string[] = [];
+  for (const player of targets) {
+    const client = player.sessionId
+      ? connection.getSession(player.sessionId)
+      : undefined;
+    if (client) {
+      await runScriptAsync(client, LEAVE_TEST_SCRIPT);
+      removed.push({ name: player.name, how: 'left' });
+    } else {
+      toKick.push(player.name);
+      removed.push({ name: player.name, how: 'kicked' });
+    }
+  }
+  if (toKick.length > 0) {
+    await runScriptAsync(serverSession, kickPlayersScript(toKick));
+  }
+
+  const remaining = await runScriptAsync(
+    serverSession,
+    waitForPlayersGoneScript(targets.map((p) => p.name))
+  );
+  if (Array.isArray(remaining) && remaining.length > 0) {
+    throw new Error(
+      `Players still in the playtest after ${PLAYER_CHANGE_TIMEOUT_SEC}s: ${remaining.join(
+        ', '
+      )}`
+    );
+  }
+  return removed;
+}
+
+const playerColumns: TableColumn<PlaytestPlayer>[] = [
+  { header: 'Player', value: (p) => p.name },
+  { header: 'UserId', value: (p) => String(p.userId) },
+  {
+    header: 'Session',
+    value: (p) => p.sessionId ?? '',
+    format: (v) => OutputHelper.formatHint(v),
+  },
+];
+
+export function formatPlayersTable(players: PlaytestPlayer[]): string {
+  return formatTable(players, playerColumns);
+}

package/src/commands/playtest/player/remove/remove.ts

@@ -0,0 +1,78 @@
+/**
+ * `playtest player remove` — remove players from the running playtest.
+ */
+
+import { defineCommand } from '../../../framework/define-command.js';
+import { arg } from '../../../framework/arg-builder.js';
+import type { BridgeConnection } from '../../../../bridge/index.js';
+import { resolvePlaytestServerSessionAsync } from '../../playtest-sessions.js';
+import {
+  removePlaytestPlayersAsync,
+  type RemovedPlayer,
+} from '../playtest-players.js';
+
+export interface PlaytestPlayerRemoveResult {
+  players: RemovedPlayer[];
+  summary: string;
+}
+
+interface PlaytestPlayerRemoveArgs {
+  names: string[];
+}
+
+export async function playtestPlayerRemoveHandlerAsync(
+  connection: BridgeConnection,
+  names: string[],
+  target?: string
+): Promise<PlaytestPlayerRemoveResult> {
+  const serverSession = await resolvePlaytestServerSessionAsync(
+    connection,
+    target
+  );
+  const players = await removePlaytestPlayersAsync(
+    connection,
+    serverSession,
+    names
+  );
+
+  return {
+    players,
+    summary: `Removed ${players.map((p) => p.name).join(', ')}`,
+  };
+}
+
+export function formatPlayerRemoveText(
+  result: PlaytestPlayerRemoveResult
+): string {
+  const kicked = result.players.filter((p) => p.how === 'kicked');
+  if (kicked.length === 0) return result.summary;
+
+  return `${result.summary}\nKicked ${kicked
+    .map((p) => p.name)
+    .join(
+      ', '
+    )}, whose client session was not connected, so its window stays open`;
+}
+
+export const playtestPlayerRemoveCommand = defineCommand<
+  PlaytestPlayerRemoveArgs,
+  PlaytestPlayerRemoveResult
+>({
+  group: 'playtest player',
+  name: 'remove',
+  description: 'Remove players from the running playtest by name',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'connection',
+  args: {
+    names: arg.positional({
+      description: 'Player names (e.g. Player2)',
+      array: true,
+    }),
+  },
+  cli: {
+    format: formatPlayerRemoveText,
+  },
+  handler: async (connection, args, targeting) =>
+    playtestPlayerRemoveHandlerAsync(connection, args.names, targeting.target),
+});

package/src/commands/playtest/playtest-sessions.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../plugin/plugin-build-version.js', () => ({
+  getPluginBuildVersionAsync: async () => 'current',
+}));
+
+const settings = vi.hoisted(() => ({
+  loadUserPluginsOnPlaytest: undefined as boolean | undefined,
+}));
+vi.mock('../../process/studio-settings.js', () => ({
+  tryReadLoadUserPluginsOnPlaytestAsync: async () =>
+    settings.loadUserPluginsOnPlaytest,
+}));
+
+import { ContextNotFoundError } from '../../bridge/index.js';
+import {
+  explainMissingPlaytestContextAsync,
+  resolvePlaytestServerSessionAsync,
+  startPlaytestAsync,
+} from './playtest-sessions.js';
+
+beforeEach(() => {
+  settings.loadUserPluginsOnPlaytest = undefined;
+});
+
+function createEditSession(pluginVersion: string) {
+  return {
+    context: 'edit',
+    info: {
+      sessionId: 'place-1a2b-edit',
+      placeName: 'place.rbxl',
+      pluginVersion,
+    },
+    runPlaytestAsync: vi.fn(),
+  } as any;
+}
+
+describe('startPlaytestAsync multiplayer checks', () => {
+  it('refuses a player count that is not a whole number of at least 1', async () => {
+    for (const players of [0, 2.5, -1]) {
+      const editSession = createEditSession('current');
+      await expect(
+        startPlaytestAsync({} as any, editSession, 'play', players)
+      ).rejects.toThrow('--players must be a whole number of at least 1');
+      expect(editSession.runPlaytestAsync).not.toHaveBeenCalled();
+    }
+  });
+
+  it('refuses run mode', async () => {
+    await expect(
+      startPlaytestAsync({} as any, createEditSession('current'), 'run', 2)
+    ).rejects.toThrow('A multiplayer test runs in play mode');
+  });
+
+  it('refuses a Studio with an older plugin before starting anything', async () => {
+    const editSession = createEditSession('old');
+
+    await expect(
+      startPlaytestAsync({} as any, editSession, 'play', 2)
+    ).rejects.toThrow("Run 'studio-bridge plugin install' first");
+    expect(editSession.runPlaytestAsync).not.toHaveBeenCalled();
+  });
+});
+
+describe('with "Load user plugins on playtest" off', () => {
+  it('refuses to start a playtest whose sessions could never connect', async () => {
+    settings.loadUserPluginsOnPlaytest = false;
+    const editSession = createEditSession('current');
+
+    await expect(
+      startPlaytestAsync({} as any, editSession, 'play')
+    ).rejects.toThrow(
+      `Studio's "Load user plugins on playtest" setting is off`
+    );
+    expect(editSession.runPlaytestAsync).not.toHaveBeenCalled();
+  });
+
+  it('names the setting when no server session is connected', async () => {
+    settings.loadUserPluginsOnPlaytest = false;
+    const connection = { listSessions: () => [] } as any;
+
+    await expect(resolvePlaytestServerSessionAsync(connection)).rejects.toThrow(
+      `No playtest is connected. Studio's "Load user plugins on playtest" setting is off`
+    );
+  });
+
+  it("ignores this machine's setting when Studio is remote", async () => {
+    settings.loadUserPluginsOnPlaytest = false;
+    const connection = { listSessions: () => [], isRemote: true } as any;
+
+    await expect(resolvePlaytestServerSessionAsync(connection)).rejects.toThrow(
+      "No playtest is running. Start one with 'studio-bridge playtest start'."
+    );
+  });
+});
+
+describe('explainMissingPlaytestContextAsync', () => {
+  const connection = {
+    listSessions: () => [
+      { instanceId: 'inst-1', placeName: 'place.rbxl', context: 'edit' },
+    ],
+  } as any;
+
+  it('says no playtest is running when the setting is on', async () => {
+    settings.loadUserPluginsOnPlaytest = true;
+    const err = await explainMissingPlaytestContextAsync(
+      connection,
+      new ContextNotFoundError('server', 'inst-1', ['edit'])
+    );
+
+    expect((err as Error).message).toBe(
+      "No playtest of 'place.rbxl' is running, so there is no server session. Start one with 'studio-bridge playtest start'."
+    );
+  });
+
+  it('names the setting when it is off', async () => {
+    settings.loadUserPluginsOnPlaytest = false;
+    const err = await explainMissingPlaytestContextAsync(
+      connection,
+      new ContextNotFoundError('client', 'inst-1', ['edit'])
+    );
+
+    expect((err as Error).message).toContain(
+      `No playtest of 'place.rbxl' is connected. Studio's "Load user plugins on playtest" setting is off`
+    );
+  });
+
+  it('points a client request at play mode when a run-mode playtest is running', async () => {
+    const err = await explainMissingPlaytestContextAsync(
+      connection,
+      new ContextNotFoundError('client', 'inst-1', ['edit', 'server'])
+    );
+
+    expect((err as Error).message).toContain('runs in run mode');
+  });
+
+  it('passes other errors through', async () => {
+    const original = new ContextNotFoundError('edit', 'inst-1', ['server']);
+    expect(await explainMissingPlaytestContextAsync(connection, original)).toBe(
+      original
+    );
+  });
+});