@quenty/studio-bridge 0.21.1 → 0.22.1

package/src/cli/adapters/cli-command-adapter.ts

@@ -9,6 +9,7 @@
  *   - Honors `--output` (file write), `--open`, `--watch`, `--interval`
  */
 
+import * as path from 'path';
 import type { Argv, CommandModule } from 'yargs';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import {
@@ -16,10 +17,20 @@ import {
   type ResultReporter,
   formatJson,
 } from '@quenty/cli-output-helpers/reporting';
-import { BridgeConnection } from '../../bridge/index.js';
-import type { SessionContext } from '../../bridge/index.js';
-import type { CommandDefinition } from '../../commands/framework/define-command.js';
+import { BridgeConnection, SessionNotFoundError } from '../../bridge/index.js';
+import type { BridgeSession, SessionContext } from '../../bridge/index.js';
+import type {
+  CommandDefinition,
+  SessionTargeting,
+} from '../../commands/framework/define-command.js';
 import { toYargsOptions } from '../../commands/framework/arg-builder.js';
+import { explainMissingPlaytestContextAsync } from '../../commands/playtest/playtest-sessions.js';
+import { tryFindFolderInstanceAsync } from '../../deploy/deploy-places.js';
+import {
+  addWarning,
+  getWarnings,
+  warnIfPluginStaleAsync,
+} from '../cli-output-context.js';
 
 /** Args injected by the adapter (not defined on CommandDefinition). */
 export interface AdapterArgs {
@@ -51,8 +62,12 @@ function extractCommandArgs(
   def: CommandDefinition
 ): Record<string, unknown> {
   const commandArgs: Record<string, unknown> = {};
-  for (const name of Object.keys(def.args)) {
-    if (name in argv) {
+  for (const [name, argDef] of Object.entries(def.args)) {
+    if (argDef.kind === 'passthrough') {
+      commandArgs[name] = ((argv['--'] as unknown[] | undefined) ?? []).map(
+        String
+      );
+    } else if (name in argv) {
       commandArgs[name] = argv[name];
     }
   }
@@ -81,15 +96,33 @@ async function executeCommandAsync(
       waitForSessions: def.scope === 'connection',
     }));
 
+  const targeting: SessionTargeting = {
+    target: argv.target as string | undefined,
+    context: argv.context as SessionContext | undefined,
+  };
+
+  // Connection commands start once Studios have connected, so this can look now
+  if (def.scope === 'connection' && !def.coversAllSessions) {
+    await tryTargetFolderInstanceAsync(connection, targeting);
+  }
+
+  if (connection.isHostOutdated) {
+    addWarning(
+      `The bridge host on port ${connection.port} runs an older studio-bridge, which may drop newer options. Restart it (e.g. stop 'studio-bridge serve') to use this version.`
+    );
+  }
+
   try {
     if (def.scope === 'session') {
-      const session = await connection.resolveSessionAsync(
-        argv.target as string | undefined,
-        argv.context as SessionContext | undefined
-      );
-      return await (def.handler as any)(session, commandArgs);
+      const session = await resolveTargetSessionAsync(connection, targeting);
+      if (def.changesDataModel && !argv.allowEdit) {
+        assertNotEditingDuringPlaytest(connection, session);
+      }
+      await warnIfPluginStaleAsync([session.info]);
+      return await (def.handler as any)(session, commandArgs, connection);
     }
-    return await (def.handler as any)(connection, commandArgs);
+    await warnIfPluginStaleAsync(connection.listSessions());
+    return await (def.handler as any)(connection, commandArgs, targeting);
   } finally {
     if (!existingConnection) {
       await connection.disconnectAsync();
@@ -97,12 +130,85 @@ async function executeCommandAsync(
   }
 }
 
+/**
+ * The session `targeting` names. When it names none and several Studios are
+ * connected, the one with the current folder's deploy.nevermore.json place open.
+ */
+async function resolveTargetSessionAsync(
+  connection: BridgeConnection,
+  targeting: SessionTargeting
+): Promise<BridgeSession> {
+  try {
+    return await connection.resolveSessionAsync(
+      targeting.target,
+      targeting.context
+    );
+  } catch (err) {
+    if (
+      err instanceof SessionNotFoundError &&
+      (await tryTargetFolderInstanceAsync(connection, targeting))
+    ) {
+      return connection
+        .resolveSessionAsync(targeting.target, targeting.context)
+        .catch(async (retryErr: unknown) => {
+          throw await explainMissingPlaytestContextAsync(connection, retryErr);
+        });
+    }
+    throw await explainMissingPlaytestContextAsync(connection, err);
+  }
+}
+
+/**
+ * Without a --target, targets the one connected Studio that has the current
+ * folder's deploy.nevermore.json place open, and says so.
+ */
+async function tryTargetFolderInstanceAsync(
+  connection: BridgeConnection,
+  targeting: SessionTargeting
+): Promise<boolean> {
+  if (targeting.target) {
+    return false;
+  }
+  const folder = await tryFindFolderInstanceAsync(connection, process.cwd());
+  if (!folder) {
+    return false;
+  }
+
+  targeting.target = folder.instanceId;
+  OutputHelper.hint(
+    `Using ${folder.instanceId}, which has '${
+      folder.deployPlace.selector
+    }' of ${path.relative(process.cwd(), folder.deployPlace.configPath)} open`
+  );
+  return true;
+}
+
+/**
+ * Refuses to change an edit DataModel while a playtest of it runs: the
+ * playtest runs a copy, so the change would not show up there.
+ */
+export function assertNotEditingDuringPlaytest(
+  connection: BridgeConnection,
+  session: BridgeSession
+): void {
+  if (session.context !== 'edit') return;
+
+  const playtest = connection
+    .listSessions()
+    .find(
+      (s) => s.instanceId === session.info.instanceId && s.context === 'server'
+    );
+  if (playtest) {
+    throw new Error(
+      `A playtest of '${session.info.placeName}' is running, so this would change Edit, not the playtest. Target the playtest with --context server (or client), or pass --allow-edit to change Edit anyway.`
+    );
+  }
+}
+
 /** Inject version/diagnostic warnings into JSON result objects. */
 function injectWarnings(result: unknown): unknown {
-  const warnings = (globalThis as any).__studioBridgeWarnings as
-    | string[]
-    | undefined;
-  if (!warnings || warnings.length === 0) return result;
+  const warnings = getWarnings();
+  if (warnings.length === 0) return result;
   if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
     return { ...result, _warnings: warnings };
   }
@@ -162,7 +268,10 @@ export function buildYargsCommand(
   const { positionals, options: yargsOptions } = toYargsOptions(def.args);
 
   const positionalSuffix = positionals
-    .map((p) => (p.options.demandOption ? `<${p.name}>` : `[${p.name}]`))
+    .map((p) => {
+      const name = p.options.array ? `${p.name}..` : p.name;
+      return p.options.demandOption ? `<${name}>` : `[${name}]`;
+    })
     .join(' ');
 
   const command = positionalSuffix
@@ -177,6 +286,12 @@ export function buildYargsCommand(
         yargs.positional(pos.name, pos.options as any);
       }
 
+      for (const argDef of Object.values(def.args)) {
+        if (argDef.kind === 'passthrough') {
+          yargs.epilogue(`-- <args..>  ${argDef.description}`);
+        }
+      }
+
       for (const [name, opt] of Object.entries(yargsOptions)) {
         yargs.option(name, opt as any);
       }
@@ -185,7 +300,7 @@ export function buildYargsCommand(
         yargs.option('target', {
           alias: 't',
           type: 'string',
-          describe: 'Target session ID (or "all" for broadcast)',
+          describe: 'Target session or instance ID',
         });
         yargs.option('context', {
           type: 'string',
@@ -194,6 +309,14 @@ export function buildYargsCommand(
         });
       }
 
+      if (def.changesDataModel && def.scope === 'session') {
+        yargs.option('allow-edit', {
+          type: 'boolean',
+          default: false,
+          describe: 'Allow changing Edit while a playtest of it runs',
+        });
+      }
+
       yargs.option('format', {
         type: 'string',
         choices: ['text', 'json'],
@@ -248,7 +371,16 @@ export function buildYargsCommand(
           await runOnceAsync(def, commandArgs, argv, reporter, connect);
         }
       } catch (err) {
-        OutputHelper.error(err instanceof Error ? err.message : String(err));
+        const message = err instanceof Error ? err.message : String(err);
+        if (explicitFormat === 'json') {
+          console.log(
+            formatJson(injectWarnings({ success: false, error: message }), {
+              pretty: process.stdout.isTTY,
+            })
+          );
+        } else {
+          OutputHelper.error(message);
+        }
         process.exit(1);
       }
     },

package/src/cli/adapters/group-builder.test.ts

@@ -112,14 +112,14 @@ describe('buildGroupCommands', () => {
     expect(consoleMod!.command).toBe('console <command>');
   });
 
-  it('group commands have descriptions', () => {
+  it('group commands have descriptions that name their subcommands', () => {
     const registry = makeRegistry();
     const result = buildGroupCommands(registry);
 
     const consoleMod = result.groups.find((g) =>
       (g.command as string).startsWith('console')
     );
-    expect(consoleMod!.describe).toBe('Execute code and view logs');
+    expect(consoleMod!.describe).toBe('Execute code and view logs: exec, logs');
   });
 
   it('group builder registers subcommands', () => {
@@ -136,6 +136,38 @@ describe('buildGroupCommands', () => {
     expect(yargs.commands).toHaveLength(2);
   });
 
+  it('nests a group with a space under its first word', () => {
+    const registry = makeRegistry();
+    registry.register(
+      defineCommand({
+        group: 'console player',
+        name: 'list',
+        description: 'List players',
+        category: 'execution',
+        safety: 'read',
+        scope: 'connection',
+        args: {},
+        handler: async () => ({}),
+      })
+    );
+    const result = buildGroupCommands(registry);
+
+    const consoleMods = result.groups.filter((g) =>
+      (g.command as string).startsWith('console')
+    );
+    expect(consoleMods).toHaveLength(1);
+
+    const yargs = createMockYargs();
+    (consoleMods[0].builder as any)(yargs);
+    expect(yargs.commands).toHaveLength(3);
+
+    const playerMod = yargs.commands[2];
+    expect(playerMod.command).toBe('player <command>');
+    const playerYargs = createMockYargs();
+    playerMod.builder(playerYargs);
+    expect(playerYargs.commands.map((c: any) => c.command)).toEqual(['list']);
+  });
+
   it('returns empty arrays for empty registry', () => {
     const registry = new CommandRegistry();
     const result = buildGroupCommands(registry);

package/src/cli/adapters/group-builder.ts

@@ -5,6 +5,9 @@
  * Grouped commands become parent commands with subcommands:
  *   `console exec <code>`  →  `console` parent, `exec` subcommand
  *
+ * A group name with a space nests under its first word:
+ *   `playtest player list`  →  `player` subcommand group of `playtest`
+ *
  * Top-level commands (group = null) are returned as standalone modules:
  *   `serve`, `mcp`, `terminal`
  */
@@ -21,7 +24,8 @@ const GROUP_DESCRIPTIONS: Record<string, string> = {
   viewport: 'Screenshots and camera control',
   data: 'Load and save serialized data',
   playtest: 'Control play test sessions',
-  process: 'Manage Studio processes',
+  'playtest player': 'List, add and remove the players of a multiplayer test',
+  process: 'Open and manage Studio',
   plugin: 'Manage the bridge plugin',
   action: 'Invoke a Studio action',
   linux: 'Linux/Wine environment management',
@@ -50,26 +54,12 @@ export function buildGroupCommands(
   const groups: CommandModule[] = [];
   const topLevel: CommandModule[] = [];
 
-  // Grouped commands → parent module with subcommands
-  for (const groupName of registry.getGroups()) {
-    const commands = registry.getByGroup(groupName);
-    const description =
-      GROUP_DESCRIPTIONS[groupName] ?? `${groupName} commands`;
+  const allGroups = registry.getGroups();
+  const topGroups = [...new Set(allGroups.map((name) => name.split(' ')[0]))];
 
-    groups.push({
-      command: `${groupName} <command>`,
-      describe: description,
-      builder: (yargs) => {
-        for (const cmd of commands) {
-          yargs.command(buildYargsCommand(cmd, options) as any);
-        }
-        return yargs.demandCommand(
-          1,
-          `Run 'studio-bridge ${groupName} --help' for available commands`
-        );
-      },
-      handler: () => {},
-    });
+  // Grouped commands → parent module with subcommands
+  for (const groupName of topGroups) {
+    groups.push(buildGroupModule(registry, allGroups, groupName, options));
   }
 
   // Top-level commands (group = null) → standalone modules
@@ -79,3 +69,45 @@ export function buildGroupCommands(
 
   return { groups, topLevel };
 }
+
+function buildGroupModule(
+  registry: CommandRegistry,
+  allGroups: string[],
+  groupName: string,
+  options: GroupBuilderOptions
+): CommandModule {
+  const commands = registry.getByGroup(groupName);
+  const subgroups = allGroups.filter(
+    (name) =>
+      name.startsWith(`${groupName} `) &&
+      !name.slice(groupName.length + 1).includes(' ')
+  );
+  // Naming the subcommands lets a reader find e.g. `process launch` from the top-level help
+  const names = [
+    ...commands.map((cmd) => cmd.name),
+    ...subgroups.map((subgroup) => subgroup.split(' ').pop()),
+  ];
+  const description = `${
+    GROUP_DESCRIPTIONS[groupName] ?? `${groupName} commands`
+  }: ${names.join(', ')}`;
+
+  return {
+    command: `${groupName.split(' ').pop()} <command>`,
+    describe: description,
+    builder: (yargs) => {
+      for (const cmd of commands) {
+        yargs.command(buildYargsCommand(cmd, options) as any);
+      }
+      for (const subgroup of subgroups) {
+        yargs.command(
+          buildGroupModule(registry, allGroups, subgroup, options) as any
+        );
+      }
+      return yargs.demandCommand(
+        1,
+        `Run 'studio-bridge ${groupName} --help' for available commands`
+      );
+    },
+    handler: () => {},
+  };
+}

package/src/cli/adapters/help-formatter.test.ts

@@ -85,7 +85,7 @@ describe('formatGroupedHelp', () => {
   it('includes group descriptions', () => {
     const help = formatGroupedHelp(makeRegistry());
     expect(help).toContain('Execute code and view logs');
-    expect(help).toContain('Manage Studio processes');
+    expect(help).toContain('Open and manage Studio');
   });
 
   it('returns empty for empty registry', () => {

package/src/cli/adapters/help-formatter.ts

@@ -12,7 +12,7 @@ const GROUP_DESCRIPTIONS: Record<string, string> = {
   viewport: 'Screenshots and camera control',
   data: 'Load and save serialized data',
   playtest: 'Control play test sessions',
-  process: 'Manage Studio processes',
+  process: 'Open and manage Studio',
   plugin: 'Manage the bridge plugin',
   action: 'Invoke a Studio action',
 };
@@ -36,10 +36,11 @@ export function formatGroupedHelp(registry: CommandRegistry): string {
 
   for (const cmd of registry.getAll()) {
     if (cmd.group !== null) {
+      const topGroup = cmd.group.split(' ')[0];
       if (cmd.category === 'execution') {
-        executionGroups.add(cmd.group);
+        executionGroups.add(topGroup);
       } else {
-        infrastructureGroups.add(cmd.group);
+        infrastructureGroups.add(topGroup);
       }
     } else {
       const entry = { name: cmd.name, description: cmd.description };

package/src/cli/adapters/playtest-edit-guard.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { assertNotEditingDuringPlaytest } from './cli-command-adapter.js';
+
+function createSession(context: string, instanceId = 'test-place-3f9a') {
+  return {
+    context,
+    info: { instanceId, placeName: 'test-place.rbxl', context },
+  } as any;
+}
+
+function createConnection(contexts: string[]) {
+  return {
+    listSessions: () =>
+      contexts.map((context) => ({ instanceId: 'test-place-3f9a', context })),
+  } as any;
+}
+
+describe('assertNotEditingDuringPlaytest', () => {
+  it('refuses to change Edit while its playtest runs', () => {
+    expect(() =>
+      assertNotEditingDuringPlaytest(
+        createConnection(['edit', 'server', 'client']),
+        createSession('edit')
+      )
+    ).toThrow(/playtest of 'test-place.rbxl' is running/);
+  });
+
+  it('allows changing Edit with no playtest running', () => {
+    expect(() =>
+      assertNotEditingDuringPlaytest(
+        createConnection(['edit']),
+        createSession('edit')
+      )
+    ).not.toThrow();
+  });
+
+  it('allows changing the playtest itself', () => {
+    expect(() =>
+      assertNotEditingDuringPlaytest(
+        createConnection(['edit', 'server']),
+        createSession('server')
+      )
+    ).not.toThrow();
+  });
+
+  it('ignores playtests of other Studios', () => {
+    expect(() =>
+      assertNotEditingDuringPlaytest(
+        createConnection(['edit', 'server']),
+        createSession('edit', 'other-place-1111')
+      )
+    ).not.toThrow();
+  });
+});

package/src/cli/args/global-args.ts

@@ -4,7 +4,7 @@
 export interface StudioBridgeGlobalArgs {
   verbose: boolean;
   place?: string;
-  timeout: number;
+  timeout?: number;
   logs: boolean;
   remote?: string;
   local?: boolean;

package/src/cli/cli-output-context.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+
+vi.mock('../plugin/plugin-build-version.js', () => ({
+  getPluginBuildVersionAsync: async () => 'current',
+}));
+
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  addWarning,
+  clearWarnings,
+  getWarnings,
+  setJsonOutput,
+  warnIfPluginStaleAsync,
+} from './cli-output-context.js';
+
+describe('cli-output-context', () => {
+  afterEach(() => {
+    clearWarnings();
+    setJsonOutput(false);
+    vi.restoreAllMocks();
+  });
+
+  it('prints warnings right away in text mode', () => {
+    const warn = vi.spyOn(OutputHelper, 'warn').mockImplementation(() => {});
+
+    addWarning('careful');
+
+    expect(warn).toHaveBeenCalledWith('careful');
+    expect(getWarnings()).toEqual(['careful']);
+  });
+
+  it('only collects warnings in JSON mode', () => {
+    const warn = vi.spyOn(OutputHelper, 'warn').mockImplementation(() => {});
+    setJsonOutput(true);
+
+    addWarning('careful');
+    addWarning('careful');
+
+    expect(warn).not.toHaveBeenCalled();
+    expect(getWarnings()).toEqual(['careful']);
+  });
+
+  it('warns about plugins built from a different template', async () => {
+    setJsonOutput(true);
+
+    await warnIfPluginStaleAsync([
+      { sessionId: 'a-edit', placeName: 'A', pluginVersion: 'current' },
+      { sessionId: 'b-edit', placeName: 'B', pluginVersion: 'old' },
+    ] as any);
+
+    expect(getWarnings()).toEqual([
+      expect.stringContaining("'B' (b-edit) is out of date"),
+    ]);
+  });
+});

package/src/cli/cli-output-context.ts

@@ -0,0 +1,50 @@
+/**
+ * Process-wide output state: whether stdout carries JSON, and warnings about
+ * the CLI's own setup (outdated CLI, stale Studio plugin). Text output prints
+ * warnings to stderr as they come up. JSON output carries them in the
+ * result's `_warnings` field instead, so they are not lost.
+ */
+
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import type { SessionInfo } from '../bridge/index.js';
+import { getPluginBuildVersionAsync } from '../plugin/plugin-build-version.js';
+
+let isJsonOutput = false;
+const warnings: string[] = [];
+
+export function setJsonOutput(json: boolean): void {
+  isJsonOutput = json;
+}
+
+export function isJsonOutputEnabled(): boolean {
+  return isJsonOutput;
+}
+
+export function addWarning(message: string): void {
+  if (warnings.includes(message)) return;
+  warnings.push(message);
+  if (!isJsonOutput) {
+    OutputHelper.warn(message);
+  }
+}
+
+export function getWarnings(): readonly string[] {
+  return warnings;
+}
+
+export function clearWarnings(): void {
+  warnings.length = 0;
+}
+
+export async function warnIfPluginStaleAsync(
+  sessions: SessionInfo[]
+): Promise<void> {
+  const expected = await getPluginBuildVersionAsync();
+  for (const session of sessions) {
+    if (session.pluginVersion !== expected) {
+      addWarning(
+        `The studio-bridge plugin in '${session.placeName}' (${session.sessionId}) is out of date. Run 'studio-bridge plugin install' to update it.`
+      );
+    }
+  }
+}