@quenty/studio-bridge 0.21.0 → 0.22.0

package/src/commands/process/launch/launch.test.ts

@@ -2,7 +2,10 @@
  * Unit tests for the launch command handler.
  */
 
-import { describe, it, expect, vi } from 'vitest';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
 
 // Mock the process manager before importing the handler
 vi.mock('../../../process/studio-process-manager.js', () => ({
@@ -15,11 +18,36 @@ vi.mock('../../../process/studio-process-manager.js', () => ({
 import { launchHandlerAsync } from './launch.js';
 import { launchStudioAsync } from '../../../process/studio-process-manager.js';
 
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'launch-test-'));
+  vi.mocked(launchStudioAsync).mockClear();
+});
+
+afterEach(async () => {
+  await fs.rm(tempDir, { recursive: true, force: true });
+});
+
+async function writeDeployConfigAsync(dir: string, config: unknown) {
+  await fs.writeFile(
+    path.join(dir, 'deploy.nevermore.json'),
+    JSON.stringify(config)
+  );
+}
+
+const place = (placeId: number, name?: string) => ({
+  name,
+  universeId: 900,
+  placeId,
+  project: 'default.project.json',
+});
+
 describe('launchHandlerAsync', () => {
-  it('calls launchStudioAsync and returns result', async () => {
-    const result = await launchHandlerAsync();
+  it('launches a bare Studio outside any deploy.nevermore.json', async () => {
+    const result = await launchHandlerAsync({ cwd: tempDir });
 
-    expect(launchStudioAsync).toHaveBeenCalled();
+    expect(launchStudioAsync).toHaveBeenCalledWith({});
     expect(result.launched).toBe(true);
     expect(result.summary).toBe('Studio launched');
   });
@@ -27,12 +55,12 @@ describe('launchHandlerAsync', () => {
   it('passes place path to launchStudioAsync', async () => {
     const result = await launchHandlerAsync({
       placePath: '/tmp/game.rbxl',
+      cwd: tempDir,
     });
 
     expect(launchStudioAsync).toHaveBeenCalledWith({
       placePath: '/tmp/game.rbxl',
     });
-    expect(result.launched).toBe(true);
     expect(result.summary).toBe('Studio launched with /tmp/game.rbxl');
   });
 
@@ -40,6 +68,7 @@ describe('launchHandlerAsync', () => {
     const result = await launchHandlerAsync({
       placeId: 84760113521251,
       universeId: 9893751595,
+      cwd: tempDir,
     });
 
     expect(launchStudioAsync).toHaveBeenCalledWith({
@@ -52,37 +81,125 @@ describe('launchHandlerAsync', () => {
   });
 
   it('summarizes a cloud place id without a universe id', async () => {
-    const result = await launchHandlerAsync({ placeId: 123 });
+    const result = await launchHandlerAsync({ placeId: 123, cwd: tempDir });
 
     expect(result.summary).toBe('Studio launched with place 123');
   });
 
-  it('passes an empty options object when nothing is specified', async () => {
-    await launchHandlerAsync({});
+  it('propagates errors from launchStudioAsync', async () => {
+    vi.mocked(launchStudioAsync).mockRejectedValueOnce(
+      new Error('Studio not found')
+    );
 
-    expect(launchStudioAsync).toHaveBeenCalledWith({});
+    await expect(launchHandlerAsync({ cwd: tempDir })).rejects.toThrow(
+      'Studio not found'
+    );
   });
+});
 
-  it('returns correct summary without place path', async () => {
-    const result = await launchHandlerAsync({});
+describe('launchHandlerAsync with deploy.nevermore.json', () => {
+  it("opens the default target's place from a parent directory's config", async () => {
+    await writeDeployConfigAsync(tempDir, { targets: { test: place(111) } });
+    const nested = path.join(tempDir, 'src', 'Server');
+    await fs.mkdir(nested, { recursive: true });
 
+    const result = await launchHandlerAsync({ cwd: nested });
+
+    expect(launchStudioAsync).toHaveBeenCalledWith({
+      placeId: 111,
+      universeId: 900,
+    });
+    expect(result).toMatchObject({
+      deployTarget: 'test',
+      placeId: 111,
+      universeId: 900,
+    });
+    expect(result.summary).toBe(
+      `Studio launched with 'test' (place 111, universe 900) from ${path.join(
+        '..',
+        '..',
+        'deploy.nevermore.json'
+      )}`
+    );
+  });
+
+  it('opens a named target and narrows to one of its places', async () => {
+    await writeDeployConfigAsync(tempDir, {
+      targets: {
+        test: place(111),
+        integration: { places: [place(222, 'hub'), place(333, 'arena')] },
+      },
+    });
+
+    const result = await launchHandlerAsync({
+      deployTarget: 'integration.places.arena',
+      cwd: tempDir,
+    });
+
+    expect(launchStudioAsync).toHaveBeenCalledWith({
+      placeId: 333,
+      universeId: 900,
+    });
+    expect(result.deployTarget).toBe('integration.places.arena');
+  });
+
+  it('asks which place to open for a target with several', async () => {
+    await writeDeployConfigAsync(tempDir, {
+      targets: {
+        integration: { places: [place(222, 'hub'), place(333, 'arena')] },
+      },
+    });
+
+    await expect(
+      launchHandlerAsync({ deployTarget: 'integration', cwd: tempDir })
+    ).rejects.toThrow(
+      "Target 'integration' has 2 places. Pick one:\n  - integration.places.hub\n  - integration.places.arena"
+    );
+    expect(launchStudioAsync).not.toHaveBeenCalled();
+  });
+
+  it('skips a config without targets, like a repo root universe id', async () => {
+    await writeDeployConfigAsync(tempDir, { universeId: 900 });
+
+    const result = await launchHandlerAsync({ cwd: tempDir });
+
+    expect(launchStudioAsync).toHaveBeenCalledWith({});
     expect(result.summary).toBe('Studio launched');
   });
 
-  it('propagates errors from launchStudioAsync', async () => {
-    vi.mocked(launchStudioAsync).mockRejectedValueOnce(
-      new Error('Studio not found')
+  it('asks for a target when the config has no default', async () => {
+    await writeDeployConfigAsync(tempDir, {
+      targets: { alpha: place(1), beta: place(2) },
+    });
+
+    await expect(launchHandlerAsync({ cwd: tempDir })).rejects.toThrow(
+      'has several targets and no default. Name one: alpha, beta'
     );
+  });
 
-    await expect(launchHandlerAsync()).rejects.toThrow('Studio not found');
+  it('fails on a target when no deploy.nevermore.json is found', async () => {
+    await expect(
+      launchHandlerAsync({ deployTarget: 'test', cwd: tempDir })
+    ).rejects.toThrow(/No deploy.nevermore.json in .* to find target 'test'/);
   });
 
-  it('result shape matches LaunchResult interface', async () => {
-    const result = await launchHandlerAsync();
+  it('refuses a target together with --place', async () => {
+    await expect(
+      launchHandlerAsync({
+        deployTarget: 'test',
+        placePath: '/tmp/game.rbxl',
+        cwd: tempDir,
+      })
+    ).rejects.toThrow('not both');
+  });
+
+  it('prefers an explicit --place over the config', async () => {
+    await writeDeployConfigAsync(tempDir, { targets: { test: place(111) } });
+
+    await launchHandlerAsync({ placePath: '/tmp/game.rbxl', cwd: tempDir });
 
-    expect(result).toHaveProperty('launched');
-    expect(result).toHaveProperty('summary');
-    expect(typeof result.launched).toBe('boolean');
-    expect(typeof result.summary).toBe('string');
+    expect(launchStudioAsync).toHaveBeenCalledWith({
+      placePath: '/tmp/game.rbxl',
+    });
   });
 });

package/src/commands/process/launch/launch.ts

@@ -1,39 +1,92 @@
 /**
- * `process launch` — launch Roblox Studio, optionally with a place file.
+ * `process launch` — launch Roblox Studio, optionally with a place file, a
+ * cloud place, or a target from the nearest `deploy.nevermore.json`.
  */
 
+import * as path from 'path';
 import { defineCommand } from '../../framework/define-command.js';
 import { arg } from '../../framework/arg-builder.js';
 import { launchStudioAsync } from '../../../process/studio-process-manager.js';
+import {
+  DEPLOY_CONFIG_FILE_NAME,
+  resolveDeployPlaceAsync,
+} from '../../../deploy/deploy-places.js';
 
 export interface LaunchOptions {
   placePath?: string;
   placeId?: number;
   universeId?: number;
+  /** A `deploy.nevermore.json` target, e.g. `test` or `integration.places.hub`. */
+  deployTarget?: string;
+  /** Where to start looking for `deploy.nevermore.json`. Default: the current directory. */
+  cwd?: string;
 }
 
 export interface LaunchResult {
   launched: boolean;
+  /** The `deploy.nevermore.json` target that was opened, if any. */
+  deployTarget?: string;
+  placeId?: number;
+  universeId?: number;
   summary: string;
 }
 
 export async function launchHandlerAsync(
   options: LaunchOptions = {}
 ): Promise<LaunchResult> {
-  await launchStudioAsync(options);
-  const target =
-    options.placeId != null
-      ? `place ${options.placeId}${
-          options.universeId != null ? ` (universe ${options.universeId})` : ''
+  const hasExplicitPlace =
+    options.placePath !== undefined || options.placeId !== undefined;
+  if (hasExplicitPlace && options.deployTarget !== undefined) {
+    throw new Error(
+      `Pass a deploy target or --place / --place-id, not both (got '${options.deployTarget}')`
+    );
+  }
+
+  const deployPlace = hasExplicitPlace
+    ? undefined
+    : await resolveDeployPlaceAsync(
+        options.cwd ?? process.cwd(),
+        options.deployTarget
+      );
+  if (deployPlace) {
+    const { placeId, universeId } = deployPlace.place;
+    await launchStudioAsync({ placeId, universeId });
+    const configDir = path.relative(
+      options.cwd ?? process.cwd(),
+      path.dirname(deployPlace.configPath)
+    );
+    return {
+      launched: true,
+      deployTarget: deployPlace.selector,
+      placeId,
+      universeId,
+      summary: `Studio launched with '${
+        deployPlace.selector
+      }' (place ${placeId}, universe ${universeId}) from ${path.join(
+        configDir,
+        DEPLOY_CONFIG_FILE_NAME
+      )}`,
+    };
+  }
+
+  const { placePath, placeId, universeId } = options;
+  await launchStudioAsync({ placePath, placeId, universeId });
+  const opened =
+    placeId != null
+      ? `place ${placeId}${
+          universeId != null ? ` (universe ${universeId})` : ''
         }`
-      : options.placePath;
+      : placePath;
   return {
     launched: true,
-    summary: `Studio launched${target ? ` with ${target}` : ''}`,
+    placeId,
+    universeId,
+    summary: `Studio launched${opened ? ` with ${opened}` : ''}`,
   };
 }
 
 interface LaunchArgs {
+  deployTarget?: string;
   place?: string;
   placeId?: number;
   universeId?: number;
@@ -42,11 +95,17 @@ interface LaunchArgs {
 export const launchCommand = defineCommand<LaunchArgs, LaunchResult>({
   group: 'process',
   name: 'launch',
-  description: 'Launch Roblox Studio',
+  description:
+    "Launch Roblox Studio, by default with the place of the nearest deploy.nevermore.json's default target",
   category: 'infrastructure',
   safety: 'none',
   scope: 'standalone',
   args: {
+    deployTarget: arg.positional({
+      description:
+        'deploy.nevermore.json target to open, e.g. test or integration.places.hub (default: its default target)',
+      required: false,
+    }),
     place: arg.option({ description: 'Path to a .rbxl place file' }),
     placeId: arg.option({
       description:
@@ -61,6 +120,7 @@ export const launchCommand = defineCommand<LaunchArgs, LaunchResult>({
   },
   handler: async (args) =>
     launchHandlerAsync({
+      deployTarget: args.deployTarget,
       placePath: args.place,
       placeId: args.placeId,
       universeId: args.universeId,

package/src/commands/process/list/list.test.ts

@@ -26,6 +26,7 @@ function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
 function createMockConnection(sessions: SessionInfo[]) {
   return {
     listSessions: () => sessions,
+    findSessions: () => sessions,
     getSession: (id: string) => sessions.find((s) => s.sessionId === id),
   } as any;
 }

package/src/commands/process/list/list.ts

@@ -2,7 +2,10 @@
  * `process list` — list connected Studio sessions.
  */
 
-import { defineCommand } from '../../framework/define-command.js';
+import {
+  defineCommand,
+  type SessionTargeting,
+} from '../../framework/define-command.js';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import {
   formatTable,
@@ -22,15 +25,18 @@ export interface SessionsResult {
  * List all connected Studio sessions with a summary message.
  */
 export async function listSessionsHandlerAsync(
-  connection: BridgeConnection
+  connection: BridgeConnection,
+  targeting: SessionTargeting = {}
 ): Promise<SessionsResult> {
-  const sessions = connection.listSessions();
+  const sessions = connection.findSessions(targeting.target, targeting.context);
 
   if (sessions.length === 0) {
     return {
       sessions: [],
       summary:
-        'No active sessions. Is Studio running with the studio-bridge plugin?',
+        connection.listSessions().length > 0
+          ? 'No sessions match --target/--context.'
+          : 'No active sessions. Is Studio running with the studio-bridge plugin?',
     };
   }
 
@@ -43,7 +49,7 @@ export async function listSessionsHandlerAsync(
 const sessionColumns: TableColumn<SessionInfo>[] = [
   {
     header: 'Session',
-    value: (s) => s.sessionId.slice(0, 8),
+    value: (s) => s.sessionId,
     format: (v) => OutputHelper.formatHint(v),
   },
   { header: 'Context', value: (s) => s.context },
@@ -67,9 +73,11 @@ export const listCommand = defineCommand({
   category: 'infrastructure',
   safety: 'read',
   scope: 'connection',
+  coversAllSessions: true,
   args: {},
   cli: {
     format: formatSessionsTable,
   },
-  handler: async (connection) => listSessionsHandlerAsync(connection),
+  handler: async (connection, _args, targeting) =>
+    listSessionsHandlerAsync(connection, targeting),
 });

package/src/commands/process/run/run.ts

@@ -11,6 +11,9 @@ import { OutputHelper } from '@quenty/cli-output-helpers';
 import { defineCommand } from '../../framework/define-command.js';
 import { arg } from '../../framework/arg-builder.js';
 import { resolveScriptContentAsync } from '../../../cli/resolve-script-content.js';
+import { isJsonOutputEnabled } from '../../../cli/cli-output-context.js';
+import { formatReturnValues } from '../../console/exec/exec.js';
+import type { SerializedReturnValue } from '../../../server/web-socket-protocol.js';
 
 export interface ProcessRunOptions {
   scriptContent: string;
@@ -20,10 +23,17 @@ export interface ProcessRunOptions {
   verbose: boolean;
   showLogs: boolean;
   filePath?: string;
+  quiet?: boolean;
+  /** Passed to the script as `...`. */
+  args?: string[];
 }
 
 export interface ProcessRunResult {
   success: boolean;
+  output: string[];
+  error?: string;
+  returnValues?: SerializedReturnValue[];
+  durationMs: number;
   summary: string;
 }
 
@@ -32,6 +42,7 @@ interface ProcessRunArgs {
   file?: string;
   place?: string;
   timeout?: number;
+  scriptArgs?: string[];
 }
 
 export async function processRunHandlerAsync(
@@ -42,13 +53,11 @@ export async function processRunHandlerAsync(
     '../../../cli/script-executor.js'
   );
 
-  // executeScriptAsync calls process.exit internally, so this return
-  // is only reachable in test scenarios where it's mocked.
-  await executeScriptAsync(options);
+  const result = await executeScriptAsync(options);
 
   return {
-    success: true,
-    summary: 'Script execution completed.',
+    ...result,
+    summary: result.success ? 'Script completed.' : 'Script failed.',
   };
 }
 
@@ -80,6 +89,16 @@ export const processRunCommand = defineCommand<
       description: 'Execution timeout in milliseconds',
       type: 'number',
     }),
+    scriptArgs: arg.passthrough({
+      description:
+        'Arguments after --, passed to the script as ... (all strings)',
+    }),
+  },
+  cli: {
+    format: (result) =>
+      result.returnValues && result.returnValues.length > 0
+        ? formatReturnValues(result.returnValues)
+        : '',
   },
   handler: async (args) => {
     const { scriptContent, filePath } = await resolveScriptContentAsync(args);
@@ -92,6 +111,8 @@ export const processRunCommand = defineCommand<
       verbose: OutputHelper.isVerbose(),
       showLogs: true,
       filePath,
+      quiet: isJsonOutputEnabled(),
+      args: args.scriptArgs,
     });
   },
   // No MCP config -- process run is CLI-only

package/src/commands/serve/serve.test.ts

@@ -17,14 +17,19 @@ vi.mock('../../bridge/index.js', () => {
 import { BridgeConnection } from '../../bridge/index.js';
 import { serveHandlerAsync } from './serve.js';
 
-function createMockConnection(port: number): EventEmitter & {
+function createMockConnection(
+  port: number,
+  role: 'host' | 'client' = 'host'
+): EventEmitter & {
   disconnectAsync: ReturnType<typeof vi.fn>;
   port: number;
+  role: 'host' | 'client';
 } {
   const emitter = new EventEmitter();
   return Object.assign(emitter, {
     disconnectAsync: vi.fn().mockResolvedValue(undefined),
     port,
+    role,
   });
 }
 
@@ -86,6 +91,16 @@ describe('serveHandlerAsync', () => {
     );
   });
 
+  it('exits instead of lingering as a client when a host already runs', async () => {
+    mockConnection = createMockConnection(38741, 'client');
+    connectAsyncMock.mockResolvedValue(mockConnection);
+
+    await expect(serveHandlerAsync({ port: 38741 })).rejects.toThrow(
+      'Port 38741 is already in use'
+    );
+    expect(mockConnection.disconnectAsync).toHaveBeenCalled();
+  });
+
   it('re-throws non-EADDRINUSE errors', async () => {
     connectAsyncMock.mockRejectedValue(new Error('some other error'));
 
@@ -98,7 +113,7 @@ describe('serveHandlerAsync', () => {
     const result = await serveHandlerAsync({ timeout: 10 });
 
     expect(mockConnection.disconnectAsync).toHaveBeenCalled();
-    expect(result).toEqual({ port: 38741, event: 'stopped' });
+    expect(result).toMatchObject({ port: 38741, event: 'stopped' });
   });
 
   it('logs JSON startup when json option is set', async () => {

package/src/commands/serve/serve.ts

@@ -7,6 +7,7 @@ import { defineCommand } from '../framework/define-command.js';
 import { arg } from '../framework/arg-builder.js';
 import { BridgeConnection } from '../../bridge/index.js';
 import type { BridgeSession } from '../../bridge/index.js';
+import { isJsonOutputEnabled } from '../../cli/cli-output-context.js';
 
 export interface ServeOptions {
   port?: number;
@@ -17,6 +18,8 @@ export interface ServeOptions {
 export interface ServeResult {
   port: number;
   event: string;
+  timestamp: string;
+  summary: string;
 }
 
 /** Blocks until shutdown signal or timeout. */
@@ -24,6 +27,12 @@ export async function serveHandlerAsync(
   options: ServeOptions = {}
 ): Promise<ServeResult> {
   const port = options.port ?? 38741;
+  options = { ...options, json: options.json || isJsonOutputEnabled() };
+
+  const alreadyRunning = new Error(
+    `Port ${port} is already in use. A bridge host is already running. ` +
+      `Connect as a client with any studio-bridge command, or use --port to start on a different port.`
+  );
 
   let connection: BridgeConnection;
   try {
@@ -37,14 +46,18 @@ export async function serveHandlerAsync(
       'code' in err &&
       (err as NodeJS.ErrnoException).code === 'EADDRINUSE'
     ) {
-      throw new Error(
-        `Port ${port} is already in use. A bridge host is already running. ` +
-          `Connect as a client with any studio-bridge command, or use --port to start on a different port.`
-      );
+      throw alreadyRunning;
     }
     throw err;
   }
 
+  if (connection.role !== 'host') {
+    await connection.disconnectAsync();
+    throw alreadyRunning;
+  }
+
+  const listeningPort = connection.port;
+
   // Log startup
   if (options.json) {
     console.log(
@@ -136,13 +149,19 @@ export async function serveHandlerAsync(
     });
   }
 
-  return { port: connection.port, event: 'stopped' };
+  return {
+    port: listeningPort,
+    event: 'stopped',
+    timestamp: new Date().toISOString(),
+    summary: 'Bridge host stopped.',
+  };
 }
 
 export const serveCommand = defineCommand<ServeOptions, ServeResult>({
   group: null,
   name: 'serve',
-  description: 'Start the bridge server',
+  description:
+    'Start the bridge server (optional: keeps Studio connected, so commands run in about a second instead of ten)',
   category: 'infrastructure',
   safety: 'none',
   scope: 'standalone',