@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/cli/cli.ts

@@ -18,6 +18,7 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import { VersionChecker } from '@quenty/nevermore-cli-helpers';
+import { addWarning, setJsonOutput } from './cli-output-context.js';
 
 import { CommandRegistry } from '../commands/framework/command-registry.js';
 import { buildGroupCommands } from './adapters/group-builder.js';
@@ -26,12 +27,23 @@ import { buildGroupCommands } from './adapters/group-builder.js';
 import { execCommand } from '../commands/console/exec/exec.js';
 import { logsCommand } from '../commands/console/logs/logs.js';
 import { queryCommand } from '../commands/explorer/query/query.js';
+import { exportCommand } from '../commands/explorer/export/export.js';
+import { importCommand } from '../commands/explorer/import/import.js';
+import { findCommand } from '../commands/explorer/find/find.js';
+import { grepCommand } from '../commands/explorer/grep/grep.js';
 import { screenshotCommand } from '../commands/viewport/screenshot/screenshot.js';
 import { infoCommand } from '../commands/process/info/info.js';
 import { listCommand } from '../commands/process/list/list.js';
 import { launchCommand } from '../commands/process/launch/launch.js';
 import { processRunCommand } from '../commands/process/run/run.js';
 import { processCloseCommand } from '../commands/process/close/close.js';
+import { playtestStartCommand } from '../commands/playtest/start/start.js';
+import { playtestStopCommand } from '../commands/playtest/stop/stop.js';
+import { playtestRunCommand } from '../commands/playtest/run/run.js';
+import { playtestRestartCommand } from '../commands/playtest/restart/restart.js';
+import { playtestPlayerListCommand } from '../commands/playtest/player/list/list.js';
+import { playtestPlayerAddCommand } from '../commands/playtest/player/add/add.js';
+import { playtestPlayerRemoveCommand } from '../commands/playtest/player/remove/remove.js';
 import { installCommand } from '../commands/plugin/install/install.js';
 import { uninstallCommand } from '../commands/plugin/uninstall/uninstall.js';
 import { serveCommand } from '../commands/serve/serve.js';
@@ -45,14 +57,25 @@ const registry = new CommandRegistry();
 registry.register(execCommand);
 registry.register(logsCommand);
 registry.register(queryCommand);
+registry.register(exportCommand);
+registry.register(importCommand);
+registry.register(findCommand);
+registry.register(grepCommand);
 registry.register(screenshotCommand);
-registry.register(processRunCommand);
+registry.register(launchCommand);
+registry.register(playtestStartCommand);
+registry.register(playtestStopCommand);
+registry.register(playtestRunCommand);
+registry.register(playtestRestartCommand);
+registry.register(playtestPlayerListCommand);
+registry.register(playtestPlayerAddCommand);
+registry.register(playtestPlayerRemoveCommand);
 
 // Infrastructure commands
-registry.register(infoCommand);
 registry.register(listCommand);
-registry.register(launchCommand);
+registry.register(infoCommand);
 registry.register(processCloseCommand);
+registry.register(processRunCommand);
 registry.register(installCommand);
 registry.register(uninstallCommand);
 registry.register(serveCommand);
@@ -64,10 +87,13 @@ registry.register(linuxStatusCommand);
 
 const { groups, topLevel } = buildGroupCommands(registry);
 
-const formatArg = process.argv.includes('--format')
-  ? process.argv[process.argv.indexOf('--format') + 1]
-  : undefined;
-const isMachineReadable = formatArg === 'json';
+OutputHelper.setDiagnosticsToStderr(true);
+
+const formatIndex = process.argv.indexOf('--format');
+const isMachineReadable =
+  process.argv.includes('--format=json') ||
+  (formatIndex !== -1 && process.argv[formatIndex + 1] === 'json');
+setJsonOutput(isMachineReadable);
 
 const versionData = await VersionChecker.checkForUpdatesAsync({
   humanReadableName: 'Studio Bridge',
@@ -80,15 +106,13 @@ const versionData = await VersionChecker.checkForUpdatesAsync({
   silent: isMachineReadable,
 });
 
-// Expose version metadata so the adapter can inject it into JSON output
 if (isMachineReadable && versionData) {
-  const warnings: string[] = [];
   if (versionData.isLocalDev) {
-    warnings.push(
+    addWarning(
       `Studio Bridge is running in local development mode. Run 'npm install -g @quenty/studio-bridge@latest' to switch to production copy.`
     );
   } else if (versionData.updateAvailable) {
-    warnings.push(
+    addWarning(
       `Studio Bridge update available: ${VersionChecker.getVersionDisplayName(
         versionData
       )} → ${
@@ -96,9 +120,6 @@ if (isMachineReadable && versionData) {
       }. Run 'npm install -g @quenty/studio-bridge@latest' to update.`
     );
   }
-  if (warnings.length > 0) {
-    (globalThis as any).__studioBridgeWarnings = warnings;
-  }
 }
 
 const cli = yargs(hideBin(process.argv))
@@ -109,9 +130,9 @@ const cli = yargs(hideBin(process.argv))
       : undefined) as any
   )
   .option('timeout', {
-    description: 'Timeout in milliseconds',
+    description:
+      'How long to wait for a Studio session to connect, in milliseconds',
     type: 'number',
-    default: 120_000,
     global: true,
   })
   .option('verbose', {
@@ -135,7 +156,17 @@ const cli = yargs(hideBin(process.argv))
   .middleware((argv) => {
     OutputHelper.setVerbose(argv.verbose as boolean);
   })
-  .usage(OutputHelper.formatInfo('Usage: $0 <command> [options]'));
+  .usage(OutputHelper.formatInfo('Usage: $0 <command> [options]'))
+  .example(
+    '$0 process launch',
+    "Open the place of the nearest deploy.nevermore.json's default target in Studio"
+  )
+  .example('$0 process list', 'List the connected Studio sessions')
+  .example(
+    "$0 console exec 'return workspace:GetChildren()'",
+    'Run Luau in Studio and print what it returns'
+  )
+  .example('$0 playtest start', 'Start a playtest');
 
 // Register grouped commands (console, explorer, viewport, process, plugin)
 for (const group of groups) {
@@ -154,4 +185,5 @@ cli
     OutputHelper.formatHint("Hint: See 'studio-bridge help' for more help")
   )
   .wrap(null)
+  .parserConfiguration({ 'populate--': true })
   .strict().argv;

package/src/cli/managed-studio-run.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { EventEmitter } from 'events';
+import { waitForLaunchedSessionAsync } from './managed-studio-run.js';
+
+function createConnection() {
+  const emitter = new EventEmitter();
+  const sessions: Array<{
+    sessionId: string;
+    launchId?: string;
+    context: string;
+  }> = [];
+  const connection = Object.assign(emitter, {
+    listSessions: () => sessions,
+    getSession: (id: string) =>
+      sessions.some((s) => s.sessionId === id) ? { id } : undefined,
+  });
+  return {
+    connection: connection as any,
+    addSession(session: {
+      sessionId: string;
+      launchId?: string;
+      context: string;
+    }) {
+      sessions.push(session);
+      emitter.emit('session-connected');
+    },
+  };
+}
+
+describe('waitForLaunchedSessionAsync', () => {
+  it('resolves with the edit session carrying the launch id', async () => {
+    const { connection, addSession } = createConnection();
+    const promise = waitForLaunchedSessionAsync(connection, 'launch-1', 1_000);
+
+    addSession({ sessionId: 'other-edit', context: 'edit' });
+    addSession({
+      sessionId: 'run-server',
+      launchId: 'launch-1',
+      context: 'server',
+    });
+    addSession({
+      sessionId: 'run-edit',
+      launchId: 'launch-1',
+      context: 'edit',
+    });
+
+    await expect(promise).resolves.toEqual({ id: 'run-edit' });
+  });
+
+  it('resolves right away when the session already connected', async () => {
+    const { connection, addSession } = createConnection();
+    addSession({
+      sessionId: 'run-edit',
+      launchId: 'launch-1',
+      context: 'edit',
+    });
+
+    await expect(
+      waitForLaunchedSessionAsync(connection, 'launch-1', 1_000)
+    ).resolves.toEqual({ id: 'run-edit' });
+  });
+
+  it('rejects when the launched Studio never connects', async () => {
+    const { connection, addSession } = createConnection();
+    const promise = waitForLaunchedSessionAsync(connection, 'launch-1', 50);
+
+    addSession({ sessionId: 'other-edit', context: 'edit' });
+
+    await expect(promise).rejects.toThrow(/did not connect/);
+  });
+});

package/src/cli/managed-studio-run.ts

@@ -0,0 +1,135 @@
+/**
+ * Runs a script in a Studio launched for the run, through the regular bridge.
+ * The place copy carries a launch id that the persistent plugin reports when
+ * it registers, so the script runs in that Studio and no other. While the run
+ * lasts, the launched Studio is an ordinary session other commands can target.
+ */
+
+import { randomUUID } from 'crypto';
+import * as path from 'path';
+import {
+  BuildContext,
+  resolvePackagePath,
+  resolveTemplatePath,
+} from '@quenty/nevermore-template-helpers';
+import { BridgeConnection } from '../bridge/index.js';
+import type { BridgeSession, ExecResult } from '../bridge/index.js';
+import type { StudioBridgePhase } from '../server/studio-bridge-server.js';
+import { launchStudioAsync } from '../process/studio-process-manager.js';
+
+const DEFAULT_LAUNCH_TIMEOUT_MS = 120_000;
+
+const defaultProjectPath = resolveTemplatePath(
+  import.meta.url,
+  path.join('default-test-place', 'default.project.json')
+);
+
+const launchIdTransformScript = resolvePackagePath(
+  import.meta.url,
+  'build-scripts',
+  'transform-add-session-attribute.lua'
+);
+
+export interface ManagedStudioRunOptions {
+  scriptContent: string;
+  placePath?: string;
+  timeoutMs: number;
+  launchTimeoutMs?: number;
+  onPhase?: (phase: StudioBridgePhase) => void;
+  /** Passed to the script as `...`. */
+  args?: string[];
+}
+
+export async function runInManagedStudioAsync(
+  options: ManagedStudioRunOptions
+): Promise<ExecResult> {
+  const launchId = randomUUID();
+  const buildContext = await BuildContext.createAsync({
+    prefix: 'studio-bridge-run-',
+  });
+  // Kept alive while Studio boots, which takes longer than the idle shutdown
+  const connection = await BridgeConnection.connectAsync({ keepAlive: true });
+  let killStudioAsync: (() => Promise<void>) | undefined;
+
+  try {
+    let sourcePlacePath = options.placePath;
+    if (!sourcePlacePath) {
+      options.onPhase?.('building');
+      sourcePlacePath = buildContext.resolvePath('minimal.rbxl');
+      await buildContext.rojoBuildAsync({
+        projectPath: defaultProjectPath,
+        output: sourcePlacePath,
+      });
+    }
+
+    // Keep the place's file name, which is what its session id is made from
+    const launchedPlacePath = buildContext.resolvePath(
+      options.placePath ? path.basename(options.placePath) : 'place.rbxl'
+    );
+    await buildContext.executeLuneTransformScriptAsync(
+      launchIdTransformScript,
+      sourcePlacePath,
+      launchedPlacePath,
+      launchId
+    );
+
+    options.onPhase?.('launching');
+    const sessionPromise = waitForLaunchedSessionAsync(
+      connection,
+      launchId,
+      options.launchTimeoutMs ?? DEFAULT_LAUNCH_TIMEOUT_MS
+    );
+    const studio = await launchStudioAsync(launchedPlacePath);
+    killStudioAsync = studio.killAsync;
+
+    options.onPhase?.('connecting');
+    const session = await sessionPromise;
+
+    options.onPhase?.('executing');
+    return await session.execAsync(
+      options.scriptContent,
+      options.timeoutMs,
+      options.args
+    );
+  } finally {
+    await killStudioAsync?.();
+    await connection.disconnectAsync();
+    await buildContext.cleanupAsync();
+  }
+}
+
+export function waitForLaunchedSessionAsync(
+  connection: BridgeConnection,
+  launchId: string,
+  timeoutMs: number
+): Promise<BridgeSession> {
+  return new Promise((resolve, reject) => {
+    const findSession = (): BridgeSession | undefined => {
+      const info = connection
+        .listSessions()
+        .find((s) => s.launchId === launchId && s.context === 'edit');
+      return info ? connection.getSession(info.sessionId) : undefined;
+    };
+
+    const onSession = (): void => {
+      const session = findSession();
+      if (session) {
+        clearTimeout(timer);
+        connection.off('session-connected', onSession);
+        resolve(session);
+      }
+    };
+
+    const timer = setTimeout(() => {
+      connection.off('session-connected', onSession);
+      reject(
+        new Error(
+          `The launched Studio did not connect within ${timeoutMs}ms. Is the studio-bridge plugin installed?`
+        )
+      );
+    }, timeoutMs);
+
+    connection.on('session-connected', onSession);
+    onSession();
+  });
+}

package/src/cli/resolve-session.test.ts

@@ -71,7 +71,7 @@ describe('resolveSessionAsync', () => {
     const conn = createMockConnection(sessions);
 
     await expect(resolveSessionAsync(conn)).rejects.toThrow(
-      /Multiple sessions found.*--session.*--instance/s
+      /Multiple sessions found.*--target/s
     );
   });
 

package/src/cli/resolve-session.ts

@@ -61,6 +61,6 @@ export async function resolveSessionAsync(
     .join('\n');
 
   throw new Error(
-    `Multiple sessions found. Use --session or --instance to select one:\n${listing}`
+    `Multiple sessions found. Use --target <id> to select one:\n${listing}`
   );
 }

package/src/cli/script-executor.ts

@@ -14,8 +14,15 @@ import {
 } from '@quenty/cli-output-helpers/reporting';
 import {
   StudioBridgeServer,
+  type StudioBridgeResult,
   type StudioBridgePhase,
 } from '../server/studio-bridge-server.js';
+import type {
+  OutputLevel,
+  SerializedReturnValue,
+} from '../server/web-socket-protocol.js';
+import { isPersistentPluginInstalled } from '../plugin/plugin-discovery.js';
+import { runInManagedStudioAsync } from './managed-studio-run.js';
 
 export interface ExecuteScriptOptions {
   scriptContent: string;
@@ -25,6 +32,18 @@ export interface ExecuteScriptOptions {
   verbose: boolean;
   showLogs: boolean;
   filePath?: string;
+  /** Skip the progress reporter, for when stdout carries JSON. */
+  quiet?: boolean;
+  /** Passed to the script as `...`. */
+  args?: string[];
+}
+
+export interface ExecuteScriptResult {
+  success: boolean;
+  output: string[];
+  error?: string;
+  returnValues?: SerializedReturnValue[];
+  durationMs: number;
 }
 
 /**
@@ -52,7 +71,7 @@ export async function resolvePlacePathAsync(
  */
 export async function executeScriptAsync(
   options: ExecuteScriptOptions
-): Promise<void> {
+): Promise<ExecuteScriptResult> {
   const { shouldDelegateToDockerAsync, delegateToDockerAsync } = await import(
     '../docker/docker-delegator.js'
   );
@@ -62,7 +81,7 @@ export async function executeScriptAsync(
       '[StudioBridge] No Wine detected, delegating to Docker'
     );
     await delegateToDockerAsync(options);
-    return; // unreachable — delegateToDockerAsync calls process.exit
+    throw new Error('delegateToDockerAsync returned without exiting');
   }
 
   const {
@@ -72,9 +91,10 @@ export async function executeScriptAsync(
     timeoutMs,
     verbose,
     showLogs,
+    quiet = false,
   } = options;
 
-  const useSpinner = !!process.stdout.isTTY && !verbose;
+  const useSpinner = !quiet && !!process.stdout.isTTY && !verbose;
 
   const reporter = new CompositeReporter(
     [packageName],
@@ -85,15 +105,17 @@ export async function executeScriptAsync(
             actionVerb: 'Running',
           })
         : new SimpleReporter(state, {
-            alwaysShowLogs: showLogs,
+            alwaysShowLogs: false,
             successMessage: 'Script completed successfully.',
             failureMessage: 'Script failed.',
           }),
     ]
   );
 
-  await reporter.startAsync();
-  reporter.onPackageStart(packageName);
+  if (!quiet) {
+    await reporter.startAsync();
+    reporter.onPackageStart(packageName);
+  }
 
   const startTime = performance.now();
 
@@ -103,45 +125,63 @@ export async function executeScriptAsync(
   }
 
   const outputLines: string[] = [];
+  const onOutput = (level: OutputLevel, body: string): void => {
+    // Filter internal plugin messages that leak through LogService
+    if (body.startsWith('[StudioBridge]')) {
+      return;
+    }
+
+    // Collect output for the result logs
+    outputLines.push(body);
+
+    // In verbose/simple mode, print output in real-time
+    if (!useSpinner && !quiet) {
+      switch (level) {
+        case 'Warning':
+          OutputHelper.warn(body);
+          break;
+        case 'Error':
+          OutputHelper.error(body);
+          break;
+        default:
+          console.log(body);
+          break;
+      }
+    }
+  };
+  const onPhase = (phase: StudioBridgePhase): void => {
+    if (phase === 'done' || quiet) return;
+    reporter.onPackagePhaseChange(packageName, phase);
+  };
+
   let server: StudioBridgeServer | undefined;
-  let result;
+  let result: StudioBridgeResult;
   try {
-    server = new StudioBridgeServer({
-      placePath,
-      timeoutMs,
-      onPhase: (phase: StudioBridgePhase) => {
-        if (phase === 'done') return;
-        reporter.onPackagePhaseChange(packageName, phase);
-      },
-    });
-    await server.startAsync();
-    result = await server.executeAsync({
-      scriptContent,
-      onOutput: (level, body) => {
-        // Filter internal plugin messages that leak through LogService
-        if (body.startsWith('[StudioBridge]')) {
-          return;
-        }
-
-        // Collect output for the result logs
-        outputLines.push(body);
-
-        // In verbose/simple mode, print output in real-time
-        if (!useSpinner) {
-          switch (level) {
-            case 'Warning':
-              OutputHelper.warn(body);
-              break;
-            case 'Error':
-              OutputHelper.error(body);
-              break;
-            default:
-              console.log(body);
-              break;
-          }
-        }
-      },
-    });
+    if (isPersistentPluginInstalled()) {
+      const execResult = await runInManagedStudioAsync({
+        scriptContent,
+        placePath,
+        timeoutMs,
+        onPhase,
+        args: options.args,
+      });
+      for (const entry of execResult.output) {
+        onOutput(entry.level, entry.body);
+      }
+      result = {
+        success: execResult.success,
+        logs: execResult.error ?? '',
+        returnValues: execResult.returnValues,
+      };
+    } else {
+      server = new StudioBridgeServer({ placePath, timeoutMs, onPhase });
+      await server.startAsync();
+      result = await server.executeAsync({
+        scriptContent,
+        onOutput,
+        args: options.args,
+      });
+    }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     result = {
@@ -154,14 +194,22 @@ export async function executeScriptAsync(
 
   const elapsed = performance.now() - startTime;
 
-  reporter.onPackageResult({
-    packageName,
-    success: result.success,
-    logs: outputLines.length > 0 ? outputLines.join('\n') : result.logs,
-    durationMs: elapsed,
-  });
+  if (!quiet) {
+    reporter.onPackageResult({
+      packageName,
+      success: result.success,
+      logs: outputLines.length > 0 ? outputLines.join('\n') : result.logs,
+      durationMs: elapsed,
+    });
 
-  await reporter.stopAsync();
+    await reporter.stopAsync();
+  }
 
-  process.exit(result.success ? 0 : 1);
+  return {
+    success: result.success,
+    output: outputLines,
+    error: result.success || !result.logs ? undefined : result.logs,
+    returnValues: result.returnValues,
+    durationMs: elapsed,
+  };
 }