@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/commands/framework/define-command.ts

@@ -9,7 +9,11 @@
  *   - `standalone` — `(args) => Promise<TResult>`
  */
 
-import type { BridgeSession, BridgeConnection } from '../../bridge/index.js';
+import type {
+  BridgeSession,
+  BridgeConnection,
+  SessionContext,
+} from '../../bridge/index.js';
 import type { ArgDefinition } from './arg-builder.js';
 
 /**
@@ -48,6 +52,17 @@ interface BaseFields<TArgs, TResult> {
   description: string;
   category: CommandCategory;
   safety: CommandSafety;
+  /**
+   * Changes the DataModel. Refused on an edit session while a playtest of it
+   * runs, since those edits are not what the playtest is running, unless
+   * `--allow-edit` is passed.
+   */
+  changesDataModel?: boolean;
+  /**
+   * Reports on every session, so without `--target` it is not narrowed to the
+   * Studio that has the current folder's `deploy.nevermore.json` place open.
+   */
+  coversAllSessions?: boolean;
   args: Record<string, ArgDefinition>;
   cli?: CliConfig<TResult>;
 }
@@ -55,13 +70,27 @@ interface BaseFields<TArgs, TResult> {
 export interface SessionCommandInput<TArgs, TResult>
   extends BaseFields<TArgs, TResult> {
   scope: 'session';
-  handler: (session: BridgeSession, args: TArgs) => Promise<TResult>;
+  handler: (
+    session: BridgeSession,
+    args: TArgs,
+    connection: BridgeConnection
+  ) => Promise<TResult>;
+}
+
+/** The `--target` and `--context` flags, for handlers that resolve sessions themselves. */
+export interface SessionTargeting {
+  target?: string;
+  context?: SessionContext;
 }
 
 export interface ConnectionCommandInput<TArgs, TResult>
   extends BaseFields<TArgs, TResult> {
   scope: 'connection';
-  handler: (connection: BridgeConnection, args: TArgs) => Promise<TResult>;
+  handler: (
+    connection: BridgeConnection,
+    args: TArgs,
+    targeting: SessionTargeting
+  ) => Promise<TResult>;
 }
 
 export interface StandaloneCommandInput<TArgs, TResult>

package/src/commands/framework/index.ts

@@ -15,6 +15,7 @@ export {
   type SessionCommandInput,
   type ConnectionCommandInput,
   type StandaloneCommandInput,
+  type SessionTargeting,
   type CliConfig,
 } from './define-command.js';
 

package/src/commands/index.ts

@@ -40,6 +40,25 @@ export {
   type QueryOptions,
   type DataModelNode,
 } from './explorer/query/query.js';
+export {
+  exportInstancesHandlerAsync,
+  type ExportResult,
+} from './explorer/export/export.js';
+export {
+  importInstancesHandlerAsync,
+  type ImportResult,
+  type ImportOptions,
+} from './explorer/import/import.js';
+export {
+  findInstancesHandlerAsync,
+  type FindResult,
+  type FindOptions,
+} from './explorer/find/find.js';
+export {
+  grepScriptsHandlerAsync,
+  type GrepResult,
+  type GrepOptions,
+} from './explorer/grep/grep.js';
 export {
   execHandlerAsync,
   type ExecOptions,
@@ -61,6 +80,37 @@ export {
   type ConnectResult,
 } from './connect.js';
 export { disconnectHandler, type DisconnectResult } from './disconnect.js';
+export {
+  playtestStartHandlerAsync,
+  type PlaytestStartOptions,
+  type PlaytestStartResult,
+} from './playtest/start/start.js';
+export {
+  playtestStopHandlerAsync,
+  type PlaytestStopOptions,
+  type PlaytestStopResult,
+} from './playtest/stop/stop.js';
+export {
+  playtestRunHandlerAsync,
+  type PlaytestRunOptions,
+  type PlaytestRunResult,
+} from './playtest/run/run.js';
+export {
+  playtestRestartHandlerAsync,
+  type PlaytestRestartOptions,
+} from './playtest/restart/restart.js';
+export {
+  playtestPlayerListHandlerAsync,
+  type PlaytestPlayerListResult,
+} from './playtest/player/list/list.js';
+export {
+  playtestPlayerAddHandlerAsync,
+  type PlaytestPlayerAddResult,
+} from './playtest/player/add/add.js';
+export {
+  playtestPlayerRemoveHandlerAsync,
+  type PlaytestPlayerRemoveResult,
+} from './playtest/player/remove/remove.js';
 export {
   processRunHandlerAsync,
   type ProcessRunOptions,

package/src/commands/linux/inject-credentials/inject-credentials.ts

@@ -36,8 +36,7 @@ export async function injectCredentialsHandlerAsync(
   try {
     const envError = await checkLinuxEnvironmentAsync();
     if (envError) {
-      OutputHelper.error(envError);
-      process.exit(1);
+      return { success: false, summary: envError };
     }
 
     const linux = await import('../../../linux/index.js');
@@ -92,7 +91,6 @@ export async function injectCredentialsHandlerAsync(
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    OutputHelper.error(message);
     return { success: false, summary: message };
   }
 }

package/src/commands/linux/setup/setup.ts

@@ -25,8 +25,7 @@ export async function setupHandlerAsync(args: SetupArgs): Promise<SetupResult> {
   try {
     const envError = await checkLinuxEnvironmentAsync();
     if (envError) {
-      OutputHelper.error(envError);
-      process.exit(1);
+      return { success: false, summary: envError };
     }
 
     const linux = await import('../../../linux/index.js');
@@ -113,7 +112,6 @@ export async function setupHandlerAsync(args: SetupArgs): Promise<SetupResult> {
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    OutputHelper.error(message);
     return { success: false, summary: message };
   }
 }

package/src/commands/linux/status/status.ts

@@ -18,17 +18,26 @@ interface PrerequisiteStatus {
   hint?: string;
 }
 
-interface StatusResult {
+export interface StatusResult {
+  /** False only when the check could not run; an unhealthy environment still reports. */
+  success: boolean;
   healthy: boolean;
+  summary: string;
+  error?: string;
   prerequisites: PrerequisiteStatus[];
-  display: { xvfb: boolean; openbox: boolean };
+  display: { name?: string; xvfb: boolean; openbox: boolean };
   studio: {
+    dir?: string;
     installed: boolean;
     version?: string;
     fflags: boolean;
     shaders: boolean;
   };
-  auth: { writeCredExe: boolean; credentialsInjected: boolean };
+  auth: {
+    writeCredExe: boolean;
+    winePrefix: boolean;
+    credentialsInjected: boolean;
+  };
 }
 
 async function fileExistsAsync(filePath: string): Promise<boolean> {
@@ -40,133 +49,128 @@ async function fileExistsAsync(filePath: string): Promise<boolean> {
   }
 }
 
+function unhealthy(error: string): StatusResult {
+  return {
+    success: false,
+    healthy: false,
+    summary: error,
+    error,
+    prerequisites: [],
+    display: { xvfb: false, openbox: false },
+    studio: { installed: false, fflags: false, shaders: false },
+    auth: {
+      writeCredExe: false,
+      winePrefix: false,
+      credentialsInjected: false,
+    },
+  };
+}
+
 export async function statusHandlerAsync(
   _args: StatusArgs
 ): Promise<StatusResult> {
   try {
     const envError = await checkLinuxEnvironmentAsync();
     if (envError) {
-      OutputHelper.error(envError);
-      process.exit(1);
+      return unhealthy(envError);
     }
 
     const linux = await import('../../../linux/index.js');
     const config = linux.resolveLinuxConfig();
-    let allOk = true;
 
-    // 1. Prerequisites
-    OutputHelper.info('System prerequisites:');
-    const prereqs = linux.checkPrerequisites();
-    for (const p of prereqs) {
-      const status = p.available
-        ? `  OK  ${p.name}${p.version ? ` (${p.version})` : ''}`
-        : `  MISSING  ${p.name} — ${p.hint}`;
-      if (p.available) {
-        OutputHelper.info(status);
-      } else {
-        OutputHelper.error(status);
-        allOk = false;
-      }
-    }
+    const prerequisites = linux.checkPrerequisites();
 
-    // 2. Display
     const displayNum = config.display.replace(':', '');
-    const xvfbOk = linux.isXvfbRunning(displayNum);
-    const openboxOk = linux.isOpenboxRunning();
-    OutputHelper.info('');
-    OutputHelper.info('Display:');
-    OutputHelper.info(
-      `  Xvfb (${config.display}): ${xvfbOk ? 'running' : 'not running'}`
-    );
-    OutputHelper.info(`  openbox: ${openboxOk ? 'running' : 'not running'}`);
-    if (!xvfbOk || !openboxOk) allOk = false;
-
-    // 3. Studio installation
-    OutputHelper.info('');
-    OutputHelper.info('Studio installation:');
-    const studioExists = await fileExistsAsync(config.studioExe);
-    OutputHelper.info(
-      `  ${config.studioDir}: ${studioExists ? 'installed' : 'not found'}`
-    );
-    if (!studioExists) allOk = false;
+    const xvfb = linux.isXvfbRunning(displayNum);
+    const openbox = linux.isOpenboxRunning();
 
+    const installed = await fileExistsAsync(config.studioExe);
     const { readInstalledVersionAsync } = await import(
       '../../../linux/linux-version-resolver.js'
     );
     const version = await readInstalledVersionAsync(config.studioDir);
-    if (version) {
-      OutputHelper.info(`  Version: ${version}`);
-    }
-
-    // 4. FFlags
-    const fflagsExist = await fileExistsAsync(config.clientSettingsPath);
-    OutputHelper.info(`  FFlags: ${fflagsExist ? 'configured' : 'not found'}`);
-
-    // 5. Shaders
-    const shadersExist = await fileExistsAsync(
+    const fflags = await fileExistsAsync(config.clientSettingsPath);
+    const shaders = await fileExistsAsync(
       `${config.shadersDir}/shaders_glsl3.pack`
     );
-    OutputHelper.info(`  Shaders: ${shadersExist ? 'present' : 'not found'}`);
-
-    // 6. Credentials
-    OutputHelper.info('');
-    OutputHelper.info('Authentication:');
-    const writeCredExists = await fileExistsAsync(config.writeCredExe);
-    OutputHelper.info(
-      `  write-cred.exe: ${writeCredExists ? 'compiled' : 'not found'}`
-    );
 
-    // Check Wine registry for credential entries
-    let credentialsInjected = false;
+    const writeCredExe = await fileExistsAsync(config.writeCredExe);
     const wineRegPath = `${config.winePrefix}/user.reg`;
-    const wineRegExists = await fileExistsAsync(wineRegPath);
-    if (wineRegExists) {
-      const regContent = await fs.readFile(wineRegPath, 'utf-8');
-      credentialsInjected = regContent.includes('RobloxStudioAuth');
-      OutputHelper.info(
-        `  Wine credentials: ${
-          credentialsInjected ? 'present' : 'not injected'
-        }`
-      );
-      if (!credentialsInjected) allOk = false;
-    } else {
-      OutputHelper.info('  Wine prefix: not initialized');
-      allOk = false;
-    }
-
-    // Summary
-    OutputHelper.info('');
-    if (allOk) {
-      OutputHelper.info('Environment is ready for Studio.');
-    } else {
-      OutputHelper.warn('Environment has issues. See above for details.');
-    }
+    const winePrefix = await fileExistsAsync(wineRegPath);
+    const credentialsInjected =
+      winePrefix &&
+      (await fs.readFile(wineRegPath, 'utf-8')).includes('RobloxStudioAuth');
+
+    const healthy =
+      prerequisites.every((p) => p.available) &&
+      xvfb &&
+      openbox &&
+      installed &&
+      credentialsInjected;
 
     return {
-      healthy: allOk,
-      prerequisites: prereqs,
-      display: { xvfb: xvfbOk, openbox: openboxOk },
+      success: true,
+      healthy,
+      summary: healthy
+        ? 'Environment is ready for Studio.'
+        : 'Environment has issues. See above for details.',
+      prerequisites,
+      display: { name: config.display, xvfb, openbox },
       studio: {
-        installed: studioExists,
+        dir: config.studioDir,
+        installed,
         version: version ?? undefined,
-        fflags: fflagsExist,
-        shaders: shadersExist,
+        fflags,
+        shaders,
       },
-      auth: { writeCredExe: writeCredExists, credentialsInjected },
+      auth: { writeCredExe, winePrefix, credentialsInjected },
     };
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    OutputHelper.error(message);
-    return {
-      healthy: false,
-      prerequisites: [],
-      display: { xvfb: false, openbox: false },
-      studio: { installed: false, fflags: false, shaders: false },
-      auth: { writeCredExe: false, credentialsInjected: false },
-    };
+    return unhealthy(err instanceof Error ? err.message : String(err));
   }
 }
 
+export function formatStatusText(result: StatusResult): string {
+  if (result.error) return OutputHelper.formatError(result.error);
+
+  const { prerequisites, display, studio, auth } = result;
+  const lines = ['System prerequisites:'];
+  for (const p of prerequisites) {
+    lines.push(
+      p.available
+        ? `  OK  ${p.name}${p.version ? ` (${p.version})` : ''}`
+        : OutputHelper.formatError(`  MISSING  ${p.name} — ${p.hint}`)
+    );
+  }
+
+  lines.push(
+    '',
+    'Display:',
+    `  Xvfb (${display.name}): ${display.xvfb ? 'running' : 'not running'}`,
+    `  openbox: ${display.openbox ? 'running' : 'not running'}`,
+    '',
+    'Studio installation:',
+    `  ${studio.dir}: ${studio.installed ? 'installed' : 'not found'}`
+  );
+  if (studio.version) lines.push(`  Version: ${studio.version}`);
+  lines.push(
+    `  FFlags: ${studio.fflags ? 'configured' : 'not found'}`,
+    `  Shaders: ${studio.shaders ? 'present' : 'not found'}`,
+    '',
+    'Authentication:',
+    `  write-cred.exe: ${auth.writeCredExe ? 'compiled' : 'not found'}`,
+    auth.winePrefix
+      ? `  Wine credentials: ${
+          auth.credentialsInjected ? 'present' : 'not injected'
+        }`
+      : '  Wine prefix: not initialized',
+    '',
+    result.healthy ? result.summary : OutputHelper.formatWarning(result.summary)
+  );
+
+  return lines.join('\n');
+}
+
 export const linuxStatusCommand = defineCommand<StatusArgs, StatusResult>({
   group: 'linux',
   name: 'status',
@@ -176,5 +180,8 @@ export const linuxStatusCommand = defineCommand<StatusArgs, StatusResult>({
   safety: 'none',
   scope: 'standalone',
   args: {},
+  cli: {
+    format: formatStatusText,
+  },
   handler: async (args) => statusHandlerAsync(args),
 });

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

@@ -0,0 +1,85 @@
+/**
+ * `playtest player add` — add players to the running multiplayer test.
+ */
+
+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 {
+  addPlaytestPlayersAsync,
+  formatPlayersTable,
+  type PlaytestPlayer,
+} from '../playtest-players.js';
+
+export interface PlaytestPlayerAddResult {
+  players: PlaytestPlayer[];
+  summary: string;
+}
+
+interface PlaytestPlayerAddArgs {
+  count?: number;
+}
+
+export async function playtestPlayerAddHandlerAsync(
+  connection: BridgeConnection,
+  count: number,
+  target?: string
+): Promise<PlaytestPlayerAddResult> {
+  if (!Number.isInteger(count) || count < 1) {
+    throw new Error(`Player count must be a whole number of at least 1`);
+  }
+
+  const serverSession = await resolvePlaytestServerSessionAsync(
+    connection,
+    target
+  );
+  const players = await addPlaytestPlayersAsync(
+    connection,
+    serverSession,
+    count
+  );
+
+  return {
+    players,
+    summary:
+      players.length < count
+        ? `Added ${players.length} of ${count} player(s); the rest did not join in time`
+        : `Added ${players.length} player(s)`,
+  };
+}
+
+export function formatPlayerAddText(result: PlaytestPlayerAddResult): string {
+  return result.players.length === 0
+    ? result.summary
+    : `${result.summary}\n${formatPlayersTable(result.players)}`;
+}
+
+export const playtestPlayerAddCommand = defineCommand<
+  PlaytestPlayerAddArgs,
+  PlaytestPlayerAddResult
+>({
+  group: 'playtest player',
+  name: 'add',
+  description:
+    'Add players to the running multiplayer test (playtest start --players)',
+  category: 'execution',
+  safety: 'mutate',
+  scope: 'connection',
+  args: {
+    count: arg.positional({
+      description: 'How many players to add',
+      type: 'number',
+      required: false,
+    }),
+  },
+  cli: {
+    format: formatPlayerAddText,
+  },
+  handler: async (connection, args, targeting) =>
+    playtestPlayerAddHandlerAsync(
+      connection,
+      args.count ?? 1,
+      targeting.target
+    ),
+});

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

@@ -0,0 +1,57 @@
+/**
+ * `playtest player list` — list the players in the running playtest.
+ */
+
+import { defineCommand } from '../../../framework/define-command.js';
+import type { BridgeConnection } from '../../../../bridge/index.js';
+import { resolvePlaytestServerSessionAsync } from '../../playtest-sessions.js';
+import {
+  formatPlayersTable,
+  listPlaytestPlayersAsync,
+  type PlaytestPlayer,
+} from '../playtest-players.js';
+
+export interface PlaytestPlayerListResult {
+  players: PlaytestPlayer[];
+  summary: string;
+}
+
+export async function playtestPlayerListHandlerAsync(
+  connection: BridgeConnection,
+  target?: string
+): Promise<PlaytestPlayerListResult> {
+  const serverSession = await resolvePlaytestServerSessionAsync(
+    connection,
+    target
+  );
+  const players = await listPlaytestPlayersAsync(connection, serverSession);
+
+  return {
+    players,
+    summary: `${players.length} player(s) in the playtest`,
+  };
+}
+
+export function formatPlayerListText(result: PlaytestPlayerListResult): string {
+  return result.players.length === 0
+    ? 'No players in the playtest'
+    : formatPlayersTable(result.players);
+}
+
+export const playtestPlayerListCommand = defineCommand<
+  Record<string, never>,
+  PlaytestPlayerListResult
+>({
+  group: 'playtest player',
+  name: 'list',
+  description: 'List the players in the running playtest',
+  category: 'execution',
+  safety: 'read',
+  scope: 'connection',
+  args: {},
+  cli: {
+    format: formatPlayerListText,
+  },
+  handler: async (connection, _args, targeting) =>
+    playtestPlayerListHandlerAsync(connection, targeting.target),
+});