@quenty/studio-bridge 0.21.1 → 0.22.0

package/dist/src/commands/playtest/playtest-sessions.js

@@ -0,0 +1,283 @@
+/**
+ * Starting, finding, and ending StudioTestService playtests.
+ *
+ * A playtest opens fresh server (and, in play mode, client) DataModels, and
+ * each connects to the bridge as its own session. Those sessions can't be
+ * matched to the Studio that started them by instance id, since unpublished
+ * places give every DataModel its own. Instead, `startPlaytestAsync` passes a
+ * playtest id as the StudioTestService test args, and each new session is
+ * asked for it back through `GetTestArgs`.
+ */
+import { randomUUID } from 'crypto';
+import { ContextNotFoundError } from '../../bridge/index.js';
+import { getPluginBuildVersionAsync } from '../../plugin/plugin-build-version.js';
+import { tryReadLoadUserPluginsOnPlaytestAsync } from '../../process/studio-settings.js';
+/** How long a started playtest may run before its pending start request is dropped. */
+const PLAYTEST_MAX_DURATION_MS = 24 * 60 * 60 * 1000;
+const SESSION_WAIT_TIMEOUT_MS = 30_000;
+/** Each player of a multiplayer test boots its own Studio process. */
+const MULTIPLAYER_SESSION_WAIT_TIMEOUT_MS = 90_000;
+const SESSION_CLOSE_TIMEOUT_MS = 10_000;
+const READ_RETRY_DELAY_MS = 1_000;
+const PLAYTEST_PLUGINS_OFF_MESSAGE = `Studio's "Load user plugins on playtest" setting is off, so the studio-bridge plugin doesn't load into playtests and their sessions can't connect. Turn it on in Studio Settings, or run a script in a playtest's server with 'studio-bridge playtest run', which works without it.`;
+const READ_PLAYTEST_ID_SCRIPT = [
+    'local ok, args = pcall(function()',
+    '\treturn game:GetService("StudioTestService"):GetTestArgs()',
+    'end)',
+    'return if ok and type(args) == "table" then args.studioBridgePlaytestId else nil',
+].join('\n');
+/** The sessions a playtest opens, by mode. Run mode has no player, so no client. */
+export function getPlaytestContexts(mode) {
+    return mode === 'play' ? ['server', 'client'] : ['server'];
+}
+/**
+ * Start a playtest from `editSession` and resolve once every session it opens
+ * has connected. With `players`, it is a multiplayer test with a client per
+ * player. Rejects if Studio refuses to start it, e.g. because a playtest is
+ * already running.
+ */
+export async function startPlaytestAsync(connection, editSession, mode, players) {
+    if (editSession.context !== 'edit') {
+        throw new Error(`Playtests start from an edit session, but '${editSession.info.sessionId}' is a ${editSession.context} session`);
+    }
+    if (await isPlaytestPluginsOffAsync(connection)) {
+        throw new Error(PLAYTEST_PLUGINS_OFF_MESSAGE);
+    }
+    if (players !== undefined) {
+        await assertCanStartMultiplayerAsync(editSession, mode, players);
+    }
+    const playtestId = randomUUID();
+    const ended = editSession
+        .runPlaytestAsync(mode, playtestId, connection.port, PLAYTEST_MAX_DURATION_MS, players)
+        .catch((err) => ({
+        playtestId,
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+    }));
+    const clientCount = players ?? (mode === 'play' ? 1 : 0);
+    const waitTimeoutMs = players !== undefined
+        ? MULTIPLAYER_SESSION_WAIT_TIMEOUT_MS
+        : SESSION_WAIT_TIMEOUT_MS;
+    const abort = new AbortController();
+    let outcome;
+    try {
+        outcome = await Promise.race([
+            waitForPlaytestSessionsAsync(connection, playtestId, clientCount, waitTimeoutMs, abort.signal).then((sessions) => ({ sessions })),
+            ended.then((result) => ({ result })),
+        ]);
+    }
+    finally {
+        abort.abort();
+    }
+    if ('result' in outcome) {
+        throw new Error(outcome.result.success
+            ? 'Playtest ended before its sessions connected'
+            : `Playtest failed to start: ${outcome.result.error}`);
+    }
+    const { server, clients } = outcome.sessions;
+    const missing = [
+        ...(server ? [] : ['server']),
+        ...(clients.length < clientCount
+            ? [`${clientCount - clients.length} client`]
+            : []),
+    ];
+    if (server && missing.length === 0) {
+        return {
+            playtestId,
+            mode,
+            players,
+            sessions: { server, client: clients[0] },
+            clients,
+            ended,
+        };
+    }
+    const waited = `its ${missing.join(' and ')} session${missing.length > 1 || clientCount - clients.length > 1 ? 's' : ''} did not connect within ${waitTimeoutMs / 1000}s`;
+    // Without its server session the playtest can't be ended from here
+    if (!server?.isConnected) {
+        throw new Error(`Playtest started, but ${waited}, so stop it in Studio. Play sessions only connect with Studio's "Load user plugins on playtest" setting on.`);
+    }
+    await endPlaytestAsync(connection, server);
+    throw new Error(`Playtest started, but ${waited}, so it was stopped.`);
+}
+async function assertCanStartMultiplayerAsync(editSession, mode, players) {
+    if (!Number.isInteger(players) || players < 1) {
+        throw new Error(`--players must be a whole number of at least 1, not ${players}`);
+    }
+    if (mode !== 'play') {
+        throw new Error('A multiplayer test runs in play mode');
+    }
+    // Older plugins give every client the same session id, so all but one drop off
+    const expected = await getPluginBuildVersionAsync();
+    if (editSession.info.pluginVersion !== expected) {
+        throw new Error(`Multiplayer tests need the current studio-bridge plugin, but '${editSession.info.placeName}' has an older one. Run 'studio-bridge plugin install' first.`);
+    }
+}
+/**
+ * Resolve the server session of a running playtest. `target` names it or
+ * any session of its Studio; otherwise there must be exactly one connected.
+ */
+export async function resolvePlaytestServerSessionAsync(connection, target) {
+    if (target) {
+        try {
+            return await connection.resolveSessionAsync(target, 'server');
+        }
+        catch (err) {
+            throw await explainMissingPlaytestContextAsync(connection, err);
+        }
+    }
+    const servers = connection
+        .listSessions()
+        .filter((info) => info.context === 'server');
+    if (servers.length === 0) {
+        throw new Error(await explainNoPlaytestAsync(connection));
+    }
+    if (servers.length > 1) {
+        const list = servers
+            .map((info) => `  - ${info.sessionId}: ${info.placeName}`)
+            .join('\n');
+        throw new Error(`Multiple playtests are running. Use --target <id> to pick a server session.\n${list}`);
+    }
+    const session = connection.getSession(servers[0].sessionId);
+    if (!session) {
+        throw new Error(`Session '${servers[0].sessionId}' disconnected`);
+    }
+    return session;
+}
+/**
+ * Explains a missing `server` or `client` session: no playtest is running, a
+ * run-mode playtest has no client, or the playtest's sessions can't connect.
+ * Other errors pass through unchanged.
+ */
+export async function explainMissingPlaytestContextAsync(connection, err) {
+    if (!(err instanceof ContextNotFoundError) ||
+        (err.context !== 'server' && err.context !== 'client')) {
+        return err;
+    }
+    const placeName = connection
+        .listSessions()
+        .find((info) => info.instanceId === err.instanceId)?.placeName;
+    const studio = placeName ? `'${placeName}'` : `instance '${err.instanceId}'`;
+    if (err.context === 'client' && err.availableContexts.includes('server')) {
+        return new Error(`The playtest of ${studio} runs in run mode, which has no client. Restart it in play mode with 'studio-bridge playtest restart --mode play'.`);
+    }
+    return new Error(await explainNoPlaytestAsync(connection, studio, err.context));
+}
+/**
+ * Whether this machine's Studio has "Load user plugins on playtest" off. A
+ * remote Studio's settings aren't on this machine, so they count as unknown.
+ */
+async function isPlaytestPluginsOffAsync(connection) {
+    return (!connection.isRemote &&
+        (await tryReadLoadUserPluginsOnPlaytestAsync()) === false);
+}
+async function explainNoPlaytestAsync(connection, studio, context) {
+    const of = studio ? ` of ${studio}` : '';
+    if (await isPlaytestPluginsOffAsync(connection)) {
+        return `No playtest${of} is connected. ${PLAYTEST_PLUGINS_OFF_MESSAGE}`;
+    }
+    const missing = context ? `, so there is no ${context} session` : '';
+    return `No playtest${of} is running${missing}. Start one with 'studio-bridge playtest start'.`;
+}
+/**
+ * End the playtest `serverSession` belongs to, resolving once the session has
+ * closed with what the playtest reported about itself.
+ */
+export async function endPlaytestAsync(connection, serverSession) {
+    const ended = await serverSession.endPlaytestAsync();
+    await waitForSessionCloseAsync(connection, serverSession.info.sessionId);
+    return ended;
+}
+async function waitForPlaytestSessionsAsync(connection, playtestId, clientCount, timeoutMs, signal) {
+    return new Promise((resolve) => {
+        const found = { clients: [] };
+        const checked = new Set();
+        const cleanup = () => {
+            clearTimeout(timer);
+            connection.off('session-connected', onSession);
+            signal.removeEventListener('abort', cleanup);
+        };
+        const onSession = (session) => {
+            const { sessionId } = session.info;
+            if (session.context === 'edit' || checked.has(sessionId)) {
+                return;
+            }
+            checked.add(sessionId);
+            void readPlaytestIdAsync(connection, sessionId, signal).then((read) => {
+                if (signal.aborted || !read)
+                    return;
+                if (read.id !== playtestId) {
+                    // The last playtest's session can linger under the same id; read its replacement too
+                    checked.delete(sessionId);
+                    return;
+                }
+                if (read.session.context === 'server') {
+                    found.server = read.session;
+                }
+                else {
+                    found.clients.push(read.session);
+                }
+                if (found.server && found.clients.length >= clientCount) {
+                    cleanup();
+                    resolve(found);
+                }
+            });
+        };
+        // Resolves with whichever sessions connected; the caller reports the rest
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve(found);
+        }, timeoutMs);
+        signal.addEventListener('abort', cleanup);
+        connection.on('session-connected', onSession);
+        for (const info of connection.listSessions()) {
+            const session = connection.getSession(info.sessionId);
+            if (session)
+                onSession(session);
+        }
+    });
+}
+/**
+ * Reads the playtest id a session was started under, retrying while the read
+ * fails: a playtest's DataModels are slow to answer while their Studio boots,
+ * and a session that reconnects is read again under the same id.
+ */
+async function readPlaytestIdAsync(connection, sessionId, signal) {
+    while (!signal.aborted) {
+        const session = connection.getSession(sessionId);
+        if (session) {
+            try {
+                const result = await session.execAsync(READ_PLAYTEST_ID_SCRIPT, 5_000);
+                if (result.success) {
+                    const value = result.returnValues?.[0];
+                    return { session, id: typeof value === 'string' ? value : undefined };
+                }
+            }
+            catch {
+                // Retried below
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, READ_RETRY_DELAY_MS));
+    }
+    return undefined;
+}
+async function waitForSessionCloseAsync(connection, sessionId) {
+    return new Promise((resolve, reject) => {
+        if (!connection.getSession(sessionId)) {
+            resolve();
+            return;
+        }
+        const onDisconnected = (disconnectedId) => {
+            if (disconnectedId !== sessionId)
+                return;
+            clearTimeout(timer);
+            connection.off('session-disconnected', onDisconnected);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            connection.off('session-disconnected', onDisconnected);
+            reject(new Error(`Playtest did not close within ${SESSION_CLOSE_TIMEOUT_MS / 1000}s`));
+        }, SESSION_CLOSE_TIMEOUT_MS);
+        connection.on('session-disconnected', onDisconnected);
+    });
+}
+//# sourceMappingURL=playtest-sessions.js.map

package/dist/src/commands/playtest/playtest-sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playtest-sessions.js","sourceRoot":"","sources":["../../../../src/commands/playtest/playtest-sessions.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=playtest-sessions.test.d.ts.map

package/dist/src/commands/playtest/playtest-sessions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playtest-sessions.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/playtest/playtest-sessions.test.ts"],"names":[],"mappings":""}

package/dist/src/commands/playtest/playtest-sessions.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('../../plugin/plugin-build-version.js', () => ({
+    getPluginBuildVersionAsync: async () => 'current',
+}));
+const settings = vi.hoisted(() => ({
+    loadUserPluginsOnPlaytest: 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) {
+    return {
+        context: 'edit',
+        info: {
+            sessionId: 'place-1a2b-edit',
+            placeName: 'place.rbxl',
+            pluginVersion,
+        },
+        runPlaytestAsync: vi.fn(),
+    };
+}
+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({}, 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({}, 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({}, 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({}, 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: () => [] };
+        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 };
+        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' },
+        ],
+    };
+    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.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.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.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);
+    });
+});
+//# sourceMappingURL=playtest-sessions.test.js.map

package/dist/src/commands/playtest/playtest-sessions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playtest-sessions.test.js","sourceRoot":"","sources":["../../../../src/commands/playtest/playtest-sessions.test.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/playtest/restart/restart.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `playtest restart` — stop the running playtest and start a new one in the
+ * same mode, so it picks up code changed since it started. Starts one when
+ * none is running.
+ */
+import type { BridgeConnection, PlaytestMode } from '../../../bridge/index.js';
+import { type PlaytestStartResult } from '../start/start.js';
+export interface PlaytestRestartOptions {
+    /** Defaults to the running playtest's mode, or play when none is running. */
+    mode?: PlaytestMode;
+    /** Defaults to the running multiplayer test's player count. */
+    players?: number;
+    /** Picks the Studio: any of its sessions. */
+    target?: string;
+}
+interface PlaytestRestartArgs {
+    mode?: PlaytestMode;
+    players?: number;
+}
+export declare function playtestRestartHandlerAsync(connection: BridgeConnection, options?: PlaytestRestartOptions): Promise<PlaytestStartResult>;
+export declare const playtestRestartCommand: import("../../framework/define-command.js").CommandDefinition<PlaytestRestartArgs, PlaytestStartResult>;
+export {};
+//# sourceMappingURL=restart.d.ts.map

package/dist/src/commands/playtest/restart/restart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.d.ts","sourceRoot":"","sources":["../../../../../src/commands/playtest/restart/restart.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAEhB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,mBAAmB;IAC3B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CA0D9B;AA6DD,eAAO,MAAM,sBAAsB,yGAgCjC,CAAC"}

package/dist/src/commands/playtest/restart/restart.js

@@ -0,0 +1,105 @@
+/**
+ * `playtest restart` — stop the running playtest and start a new one in the
+ * same mode, so it picks up code changed since it started. Starts one when
+ * none is running.
+ */
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { endPlaytestAsync, startPlaytestAsync, } from '../playtest-sessions.js';
+import { listPlaytestPlayersAsync } from '../player/playtest-players.js';
+import { describePlaytest, formatPlaytestStartText, toPlaytestStartResult, } from '../start/start.js';
+/** Studio refuses a new playtest until the old one has fully wound down. */
+const START_ATTEMPTS = 5;
+const START_RETRY_DELAY_MS = 1_000;
+export async function playtestRestartHandlerAsync(connection, options = {}) {
+    const targetSession = options.target
+        ? await connection.resolveSessionAsync(options.target)
+        : undefined;
+    const serverSession = findServerSession(connection, targetSession?.info.instanceId);
+    if (!serverSession) {
+        const editSession = targetSession?.context === 'edit'
+            ? targetSession
+            : await connection.resolveSessionAsync(undefined, 'edit', targetSession?.info.instanceId);
+        const playtest = await startWithRetryAsync(connection, editSession, options.mode ?? 'play', options.players);
+        return toPlaytestStartResult(playtest, `No playtest was running; started one (${describePlaytest(playtest)})`);
+    }
+    const editSession = await connection.resolveSessionAsync(undefined, 'edit', serverSession.info.instanceId);
+    // Players added since the start count too, so read who is in the test now
+    const livePlayers = options.players === undefined && options.mode === undefined
+        ? await tryCountMultiplayerPlayersAsync(connection, serverSession)
+        : undefined;
+    const ended = await endPlaytestAsync(connection, serverSession);
+    const mode = options.mode ?? ended.mode ?? 'play';
+    const players = options.players ??
+        (options.mode === undefined && ended.players !== undefined
+            ? livePlayers || ended.players
+            : undefined);
+    const playtest = await startWithRetryAsync(connection, editSession, mode, players);
+    return toPlaytestStartResult(playtest, `Playtest restarted (${describePlaytest(playtest)})`);
+}
+/** How many players the running test has, or undefined when it can't tell. */
+async function tryCountMultiplayerPlayersAsync(connection, serverSession) {
+    try {
+        return (await listPlaytestPlayersAsync(connection, serverSession)).length;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The running playtest's server session, within `instanceId` when given. */
+function findServerSession(connection, instanceId) {
+    const servers = connection
+        .listSessions()
+        .filter((info) => info.context === 'server' &&
+        (instanceId === undefined || info.instanceId === instanceId));
+    if (servers.length > 1) {
+        const list = servers
+            .map((info) => `  - ${info.sessionId}: ${info.placeName}`)
+            .join('\n');
+        throw new Error(`Multiple playtests are running. Use --target <id> to pick one.\n${list}`);
+    }
+    return servers.length === 1
+        ? connection.getSession(servers[0].sessionId)
+        : undefined;
+}
+async function startWithRetryAsync(connection, editSession, mode, players) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await startPlaytestAsync(connection, editSession, mode, players);
+        }
+        catch (err) {
+            const stillWindingDown = err instanceof Error && err.message.includes('still in progress');
+            if (!stillWindingDown || attempt >= START_ATTEMPTS) {
+                throw err;
+            }
+            await new Promise((resolve) => setTimeout(resolve, START_RETRY_DELAY_MS));
+        }
+    }
+}
+export const playtestRestartCommand = defineCommand({
+    group: 'playtest',
+    name: 'restart',
+    description: 'Stop the running playtest and start a new one in the same mode, to pick up code changes',
+    category: 'execution',
+    safety: 'mutate',
+    scope: 'connection',
+    args: {
+        mode: arg.option({
+            description: "Start in this mode instead of the running playtest's (play or run)",
+            choices: ['play', 'run'],
+        }),
+        players: arg.option({
+            description: "Start a multiplayer test with this many players instead of the running playtest's",
+            type: 'number',
+        }),
+    },
+    cli: {
+        format: formatPlaytestStartText,
+    },
+    handler: async (connection, args, targeting) => playtestRestartHandlerAsync(connection, {
+        mode: args.mode,
+        players: args.players,
+        target: targeting.target,
+    }),
+});
+//# sourceMappingURL=restart.js.map

package/dist/src/commands/playtest/restart/restart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart.js","sourceRoot":"","sources":["../../../../../src/commands/playtest/restart/restart.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,47 @@
+/**
+ * `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 type { BridgeConnection, PlaytestMode, SessionContext } from '../../../bridge/index.js';
+import type { SerializedReturnValue } from '../../../server/web-socket-protocol.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[];
+}
+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 declare function playtestRunHandlerAsync(connection: BridgeConnection, options: PlaytestRunOptions): Promise<PlaytestRunResult>;
+export declare const playtestRunCommand: import("../../framework/define-command.js").CommandDefinition<PlaytestRunArgs, PlaytestRunResult>;
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/src/commands/playtest/run/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../../../src/commands/playtest/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,OAAO,KAAK,EACV,gBAAgB,EAGhB,YAAY,EACZ,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAOpF,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,8CAA8C;IAC9C,OAAO,EAAE,cAAc,CAAC;IACxB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAKD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACvC,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAgD5B;AA4DD,eAAO,MAAM,kBAAkB,mGAuD7B,CAAC"}