@quenty/studio-bridge 0.7.0 → 0.8.0

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

@@ -0,0 +1,86 @@
+/**
+ * Custom help formatter that groups commands into "Execution" and
+ * "Infrastructure" categories, matching the target CLI layout.
+ */
+
+import type { CommandRegistry } from '../../commands/framework/command-registry.js';
+
+const GROUP_DESCRIPTIONS: Record<string, string> = {
+  console: 'Execute code and view logs',
+  explorer: 'Query and modify the DataModel',
+  properties: 'Read and write instance properties',
+  viewport: 'Screenshots and camera control',
+  data: 'Load and save serialized data',
+  playtest: 'Control play test sessions',
+  process: 'Manage Studio processes',
+  plugin: 'Manage the bridge plugin',
+  action: 'Invoke a Studio action',
+};
+
+/**
+ * Format a categorized help string from the command registry.
+ * Groups are listed under their category with aligned descriptions.
+ */
+export function formatGroupedHelp(registry: CommandRegistry): string {
+  const lines: string[] = [];
+
+  lines.push('studio-bridge <command> [options]');
+  lines.push('');
+
+  // Collect unique groups per category
+  const executionGroups = new Set<string>();
+  const infrastructureGroups = new Set<string>();
+  const executionTopLevel: Array<{ name: string; description: string }> = [];
+  const infrastructureTopLevel: Array<{ name: string; description: string }> =
+    [];
+
+  for (const cmd of registry.getAll()) {
+    if (cmd.group !== null) {
+      if (cmd.category === 'execution') {
+        executionGroups.add(cmd.group);
+      } else {
+        infrastructureGroups.add(cmd.group);
+      }
+    } else {
+      const entry = { name: cmd.name, description: cmd.description };
+      if (cmd.category === 'execution') {
+        executionTopLevel.push(entry);
+      } else {
+        infrastructureTopLevel.push(entry);
+      }
+    }
+  }
+
+  // Execution section
+  if (executionGroups.size > 0 || executionTopLevel.length > 0) {
+    lines.push('Execution:');
+    for (const group of executionGroups) {
+      const desc = GROUP_DESCRIPTIONS[group] ?? '';
+      lines.push(formatLine(`${group} <command>`, desc));
+    }
+    for (const cmd of executionTopLevel) {
+      lines.push(formatLine(cmd.name, cmd.description));
+    }
+    lines.push('');
+  }
+
+  // Infrastructure section
+  if (infrastructureGroups.size > 0 || infrastructureTopLevel.length > 0) {
+    lines.push('Infrastructure:');
+    for (const group of infrastructureGroups) {
+      const desc = GROUP_DESCRIPTIONS[group] ?? '';
+      lines.push(formatLine(`${group} <command>`, desc));
+    }
+    for (const cmd of infrastructureTopLevel) {
+      lines.push(formatLine(cmd.name, cmd.description));
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatLine(label: string, description: string): string {
+  const padding = Math.max(2, 22 - label.length);
+  return `  ${label}${' '.repeat(padding)}${description}`;
+}

package/src/cli/adapters/target-resolver.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Unit tests for the target resolver.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { resolveTargetAsync, TargetRequiredError } from './target-resolver.js';
+import type { SessionInfo } from '../../bridge/index.js';
+
+function mockSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    sessionId: overrides.sessionId ?? 'sess-1',
+    placeName: overrides.placeName ?? 'TestPlace',
+    state: 'Edit' as any,
+    pluginVersion: '1.0.0',
+    capabilities: [],
+    connectedAt: new Date(),
+    origin: 'user',
+    context: overrides.context ?? 'edit',
+    instanceId: overrides.instanceId ?? 'inst-1',
+    placeId: overrides.placeId ?? 123,
+    gameId: overrides.gameId ?? 456,
+  };
+}
+
+function mockConnection(sessions: SessionInfo[] = []) {
+  const sessionMap = new Map(sessions.map((s) => [s.sessionId, s]));
+
+  return {
+    listSessions: vi.fn().mockReturnValue(sessions),
+    getSession: vi.fn((id: string) => sessionMap.get(id)),
+    resolveSessionAsync: vi.fn(async (id: string) => {
+      const info = sessionMap.get(id);
+      if (!info) throw new Error(`Session '${id}' not found`);
+      return info;
+    }),
+  } as any;
+}
+
+describe('resolveTargetAsync', () => {
+  describe('explicit --target', () => {
+    it('resolves a specific session by ID', async () => {
+      const sess = mockSessionInfo({ sessionId: 'abc-123' });
+      const conn = mockConnection([sess]);
+
+      const result = await resolveTargetAsync(conn, {
+        target: 'abc-123',
+        safety: 'mutate',
+      });
+
+      expect(result.sessions).toHaveLength(1);
+      expect(conn.resolveSessionAsync).toHaveBeenCalledWith(
+        'abc-123',
+        undefined
+      );
+    });
+
+    it('passes context to resolveSessionAsync', async () => {
+      const sess = mockSessionInfo({ sessionId: 'abc-123' });
+      const conn = mockConnection([sess]);
+
+      await resolveTargetAsync(conn, {
+        target: 'abc-123',
+        context: 'edit',
+        safety: 'mutate',
+      });
+
+      expect(conn.resolveSessionAsync).toHaveBeenCalledWith('abc-123', 'edit');
+    });
+
+    it('throws when session ID not found', async () => {
+      const conn = mockConnection([]);
+
+      await expect(
+        resolveTargetAsync(conn, {
+          target: 'nonexistent',
+          safety: 'mutate',
+        })
+      ).rejects.toThrow('not found');
+    });
+  });
+
+  describe('--target all', () => {
+    it('returns all sessions', async () => {
+      const sess1 = mockSessionInfo({ sessionId: 'a' });
+      const sess2 = mockSessionInfo({ sessionId: 'b' });
+      const conn = mockConnection([sess1, sess2]);
+
+      const result = await resolveTargetAsync(conn, {
+        target: 'all',
+        safety: 'read',
+      });
+
+      expect(result.sessions).toHaveLength(2);
+    });
+
+    it('filters by context when provided', async () => {
+      const edit = mockSessionInfo({ sessionId: 'a', context: 'edit' });
+      const server = mockSessionInfo({ sessionId: 'b', context: 'server' });
+      const conn = mockConnection([edit, server]);
+
+      const result = await resolveTargetAsync(conn, {
+        target: 'all',
+        context: 'edit',
+        safety: 'read',
+      });
+
+      expect(result.sessions).toHaveLength(1);
+    });
+
+    it('throws when no sessions available', async () => {
+      const conn = mockConnection([]);
+
+      await expect(
+        resolveTargetAsync(conn, {
+          target: 'all',
+          safety: 'read',
+        })
+      ).rejects.toThrow('No sessions connected');
+    });
+  });
+
+  describe('auto-resolve', () => {
+    it('auto-selects when exactly one session', async () => {
+      const sess = mockSessionInfo({ sessionId: 'only-one' });
+      const conn = mockConnection([sess]);
+
+      const result = await resolveTargetAsync(conn, {
+        safety: 'mutate',
+      });
+
+      expect(result.sessions).toHaveLength(1);
+    });
+
+    it('throws TargetRequiredError for mutate with multiple sessions', async () => {
+      const sess1 = mockSessionInfo({ sessionId: 'a' });
+      const sess2 = mockSessionInfo({ sessionId: 'b' });
+      const conn = mockConnection([sess1, sess2]);
+
+      await expect(
+        resolveTargetAsync(conn, { safety: 'mutate' })
+      ).rejects.toThrow(TargetRequiredError);
+    });
+
+    it('aggregates all sessions for read safety on CLI', async () => {
+      const sess1 = mockSessionInfo({ sessionId: 'a' });
+      const sess2 = mockSessionInfo({ sessionId: 'b' });
+      const conn = mockConnection([sess1, sess2]);
+
+      const result = await resolveTargetAsync(conn, {
+        safety: 'read',
+        isMcp: false,
+      });
+
+      expect(result.sessions).toHaveLength(2);
+    });
+
+    it('throws when no sessions available', async () => {
+      const conn = mockConnection([]);
+
+      await expect(
+        resolveTargetAsync(conn, { safety: 'read' })
+      ).rejects.toThrow('No sessions connected');
+    });
+  });
+
+  describe('MCP targeting', () => {
+    it('throws TargetRequiredError when multiple sessions and isMcp', async () => {
+      const sess1 = mockSessionInfo({ sessionId: 'a' });
+      const sess2 = mockSessionInfo({ sessionId: 'b' });
+      const conn = mockConnection([sess1, sess2]);
+
+      await expect(
+        resolveTargetAsync(conn, {
+          safety: 'read',
+          isMcp: true,
+        })
+      ).rejects.toThrow(TargetRequiredError);
+    });
+
+    it('auto-selects single session even in MCP mode', async () => {
+      const sess = mockSessionInfo({ sessionId: 'only' });
+      const conn = mockConnection([sess]);
+
+      const result = await resolveTargetAsync(conn, {
+        safety: 'read',
+        isMcp: true,
+      });
+
+      expect(result.sessions).toHaveLength(1);
+    });
+  });
+});
+
+describe('TargetRequiredError', () => {
+  it('includes session listing in message', () => {
+    const sessions = [
+      mockSessionInfo({ sessionId: 'a', placeName: 'Place A' }),
+      mockSessionInfo({ sessionId: 'b', placeName: 'Place B' }),
+    ];
+
+    const err = new TargetRequiredError(sessions);
+
+    expect(err.message).toContain('Multiple sessions');
+    expect(err.message).toContain('a');
+    expect(err.message).toContain('b');
+  });
+
+  it('provides structured error payload', () => {
+    const sessions = [mockSessionInfo({ sessionId: 'a' })];
+    const err = new TargetRequiredError(sessions);
+
+    const structured = err.toStructuredError();
+    expect(structured.error).toBe('multiple_sessions');
+    expect(structured.hint).toContain('--target');
+    expect(structured.sessions).toHaveLength(1);
+  });
+
+  it('has correct name', () => {
+    const err = new TargetRequiredError([]);
+    expect(err.name).toBe('TargetRequiredError');
+  });
+});

package/src/cli/adapters/target-resolver.ts

@@ -0,0 +1,144 @@
+/**
+ * Unified target resolution for the `--target` flag.
+ *
+ * Replaces the old `--session`/`--instance` system with a single
+ * `--target` option that supports:
+ *
+ *   - Explicit ID: `--target <sessionId>`
+ *   - All sessions: `--target all`
+ *   - Auto-resolve: omit `--target` → single session auto-selects
+ *
+ * Behavior varies by safety classification:
+ *   - `read`   CLI: aggregate all sessions (no target required)
+ *   - `mutate`  CLI: auto-resolve if 1, prompt/error if multiple
+ *   - `none`:   no targeting needed
+ *   - MCP:      always require explicit target, error with session list
+ */
+
+import type { BridgeConnection } from '../../bridge/index.js';
+import type {
+  BridgeSession,
+  SessionContext,
+  SessionInfo,
+} from '../../bridge/index.js';
+import type { CommandSafety } from '../../commands/framework/define-command.js';
+
+export interface TargetResolveOptions {
+  /** Explicit target from `--target` flag. */
+  target?: string;
+  /** Context filter from `--context` flag. */
+  context?: SessionContext;
+  /** Safety classification of the command. */
+  safety: CommandSafety;
+  /** Whether this is an MCP invocation (stricter targeting). */
+  isMcp?: boolean;
+}
+
+/** Successful resolution — one or more sessions. */
+export interface TargetResolved {
+  sessions: BridgeSession[];
+}
+
+/** Structured error when target cannot be resolved. */
+export interface MultipleSessionsError {
+  error: 'multiple_sessions';
+  hint: string;
+  sessions: SessionInfo[];
+}
+
+/**
+ * Resolve target session(s) from a `BridgeConnection` based on the
+ * `--target` flag, safety classification, and invocation context.
+ *
+ * @throws {Error} When no sessions match or when multiple sessions
+ *   exist and the command requires an explicit target.
+ */
+export async function resolveTargetAsync(
+  connection: BridgeConnection,
+  options: TargetResolveOptions
+): Promise<TargetResolved> {
+  const { target, context, safety, isMcp } = options;
+
+  // Explicit target
+  if (target && target !== 'all') {
+    const session = await connection.resolveSessionAsync(target, context);
+    return { sessions: [session] };
+  }
+
+  // --target all: broadcast to all matching sessions
+  if (target === 'all') {
+    const sessions = filterSessions(connection, context);
+    if (sessions.length === 0) {
+      throw new Error(
+        'No sessions connected. Is Studio running with the studio-bridge plugin?'
+      );
+    }
+    return {
+      sessions: sessions.map((info) => connection.getSession(info.sessionId)!),
+    };
+  }
+
+  // No explicit target — behavior depends on safety and context
+  const sessions = filterSessions(connection, context);
+
+  if (sessions.length === 0) {
+    throw new Error(
+      'No sessions connected. Is Studio running with the studio-bridge plugin?'
+    );
+  }
+
+  // MCP always requires explicit target when multiple sessions exist
+  if (isMcp && sessions.length > 1) {
+    throw new TargetRequiredError(sessions);
+  }
+
+  // CLI read commands: aggregate all sessions
+  if (safety === 'read' && !isMcp) {
+    return {
+      sessions: sessions.map((info) => connection.getSession(info.sessionId)!),
+    };
+  }
+
+  // Single session: auto-resolve
+  if (sessions.length === 1) {
+    const session = connection.getSession(sessions[0].sessionId)!;
+    return { sessions: [session] };
+  }
+
+  // Multiple sessions + mutate: require explicit target
+  throw new TargetRequiredError(sessions);
+}
+
+export class TargetRequiredError extends Error {
+  public readonly sessions: SessionInfo[];
+
+  constructor(sessions: SessionInfo[]) {
+    const listing = sessions
+      .map((s) => `  - ${s.sessionId} (${s.placeName}, context=${s.context})`)
+      .join('\n');
+
+    super(`Multiple sessions connected. Specify --target <id>:\n${listing}`);
+    this.name = 'TargetRequiredError';
+    this.sessions = sessions;
+  }
+
+  /** Structured error payload for non-interactive / MCP responses. */
+  toStructuredError(): MultipleSessionsError {
+    return {
+      error: 'multiple_sessions',
+      hint: 'Specify --target <id>',
+      sessions: this.sessions,
+    };
+  }
+}
+
+function filterSessions(
+  connection: BridgeConnection,
+  context?: SessionContext
+): SessionInfo[] {
+  let sessions = connection.listSessions();
+  if (context) {
+    sessions = sessions.filter((s) => s.context === context);
+  }
+  return sessions;
+}

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

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

package/src/cli/cli.ts

@@ -3,10 +3,13 @@
 /**
  * CLI entry point for @quenty/studio-bridge.
  *
+ * Registry-driven: all commands are `defineCommand()` definitions discovered
+ * from `src/commands/`. The adapter layer converts them into yargs modules.
+ *
  * Usage:
- *   studio-bridge run <file.lua>
- *   studio-bridge exec 'print("hello")'
- *   studio-bridge terminal [--script <file.lua>]
+ *   studio-bridge console exec 'print("hello")'
+ *   studio-bridge console logs
+ *   studio-bridge process list
  */
 
 import yargs from 'yargs';
@@ -16,9 +19,55 @@ import { dirname, join } from 'path';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import { VersionChecker } from '@quenty/nevermore-cli-helpers';
 
-import { RunCommand } from './commands/run-command.js';
-import { ExecCommand } from './commands/exec-command.js';
-import { TerminalCommand } from './commands/terminal/terminal-command.js';
+import { CommandRegistry } from '../commands/framework/command-registry.js';
+import { buildGroupCommands } from './adapters/group-builder.js';
+
+// Command definitions (explicit imports for deterministic ordering)
+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 { 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 { installCommand } from '../commands/plugin/install/install.js';
+import { uninstallCommand } from '../commands/plugin/uninstall/uninstall.js';
+import { serveCommand } from '../commands/serve/serve.js';
+import { linuxSetupCommand } from '../commands/linux/setup/setup.js';
+import { linuxInjectCredentialsCommand } from '../commands/linux/inject-credentials/inject-credentials.js';
+import { linuxStatusCommand } from '../commands/linux/status/status.js';
+
+const registry = new CommandRegistry();
+
+// Execution commands
+registry.register(execCommand);
+registry.register(logsCommand);
+registry.register(queryCommand);
+registry.register(screenshotCommand);
+registry.register(processRunCommand);
+
+// Infrastructure commands
+registry.register(infoCommand);
+registry.register(listCommand);
+registry.register(launchCommand);
+registry.register(processCloseCommand);
+registry.register(installCommand);
+registry.register(uninstallCommand);
+registry.register(serveCommand);
+
+// Linux commands
+registry.register(linuxSetupCommand);
+registry.register(linuxInjectCredentialsCommand);
+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';
 
 const versionData = await VersionChecker.checkForUpdatesAsync({
   humanReadableName: 'Studio Bridge',
@@ -28,22 +77,37 @@ const versionData = await VersionChecker.checkForUpdatesAsync({
     dirname(fileURLToPath(import.meta.url)),
     '../../../package.json'
   ),
+  silent: isMachineReadable,
 });
 
-yargs(hideBin(process.argv))
+// Expose version metadata so the adapter can inject it into JSON output
+if (isMachineReadable && versionData) {
+  const warnings: string[] = [];
+  if (versionData.isLocalDev) {
+    warnings.push(
+      `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(
+      `Studio Bridge update available: ${VersionChecker.getVersionDisplayName(
+        versionData
+      )} → ${
+        versionData.latestVersion
+      }. 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))
   .scriptName('studio-bridge')
   .version(
     (versionData
       ? VersionChecker.getVersionDisplayName(versionData)
       : undefined) as any
   )
-  .option('place', {
-    alias: 'p',
-    description:
-      'Path to a .rbxl place file (builds a minimal place via rojo if omitted)',
-    type: 'string',
-    global: true,
-  })
   .option('timeout', {
     description: 'Timeout in milliseconds',
     type: 'number',
@@ -56,19 +120,34 @@ yargs(hideBin(process.argv))
     default: false,
     global: true,
   })
-  .option('logs', {
-    description: 'Show execution logs in spinner mode',
+  .option('remote', {
+    type: 'string',
+    description: 'Connect to a remote bridge host (host:port)',
+    global: true,
+  })
+  .option('local', {
     type: 'boolean',
-    default: true,
+    description: 'Force local mode (skip devcontainer auto-detection)',
+    default: false,
     global: true,
+    conflicts: 'remote',
   })
   .middleware((argv) => {
     OutputHelper.setVerbose(argv.verbose as boolean);
   })
-  .usage(OutputHelper.formatInfo('Usage: $0 <command> [options]'))
-  .command(new ExecCommand() as any)
-  .command(new RunCommand() as any)
-  .command(new TerminalCommand() as any)
+  .usage(OutputHelper.formatInfo('Usage: $0 <command> [options]'));
+
+// Register grouped commands (console, explorer, viewport, process, plugin)
+for (const group of groups) {
+  cli.command(group as any);
+}
+
+// Register top-level commands from registry (serve)
+for (const cmd of topLevel) {
+  cli.command(cmd as any);
+}
+
+cli
   .recommendCommands()
   .demandCommand(
     1,

package/src/cli/resolve-script-content.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared parsing for commands that accept either inline Luau code or a
+ * file path. Used by `console exec` and `process run`.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+export interface ScriptContentArgs {
+  code?: string;
+  file?: string;
+}
+
+export interface ResolvedScriptContent {
+  scriptContent: string;
+  /** Absolute path of the resolved file, or undefined when using inline code. */
+  filePath?: string;
+}
+
+/**
+ * Reads inline code or a file (resolved against CWD) into a string.
+ * Throws if neither is provided.
+ */
+export async function resolveScriptContentAsync(
+  args: ScriptContentArgs
+): Promise<ResolvedScriptContent> {
+  if (args.file) {
+    const absolutePath = path.resolve(args.file);
+    const scriptContent = await fs.readFile(absolutePath, 'utf-8');
+    return { scriptContent, filePath: absolutePath };
+  }
+  if (args.code) {
+    return { scriptContent: args.code };
+  }
+  throw new Error('Either inline code or --file must be provided');
+}