refactor(studio-bridge): reorganize CLI into declarative grouped commands

Replace 13 flat CLI commands with a declarative defineCommand() system
that drives CLI, MCP, and terminal from a single source per command.
Commands are now grouped (console, explorer, viewport, process, plugin)
and co-located with their Luau action files, which are pushed to the
plugin dynamically over the wire instead of bundled statically.

Author: Quenty

tools/studio-bridge/README.md

@@ -26,6 +26,9 @@ import type {
 import type { SessionInfo, SessionContext, InstanceInfo } from './types.js';
 import { SessionNotFoundError, ContextNotFoundError } from './types.js';
 import type { ServerMessage } from '../server/web-socket-protocol.js';
+import { pushActionsToSessionAsync } from './internal/action-pusher.js';
+import { loadActionSourcesAsync, type ActionSource } from '../commands/framework/action-loader.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -118,6 +121,9 @@ export class BridgeConnection extends EventEmitter {
   private _hostSessions: Map<string, BridgeSession> = new Map();
   private _hostHandles: Map<string, HostTransportHandle> = new Map();
 
+  /** Cached action sources loaded once for pushing to new plugin sessions. */
+  private _actionSources: ActionSource[] | undefined;
+
   // Client mode internals
   private _client: BridgeClient | undefined;
 
@@ -569,6 +575,15 @@ export class BridgeConnection extends EventEmitter {
       const handle = new HostTransportHandle(info.sessionId, this._host!);
       this._hostHandles.set(info.sessionId, handle);
       this._tracker!.addSession(info.sessionId, sessionInfo, handle);
+
+      // Push action modules to the newly connected plugin (fire and forget)
+      if (info.capabilities.includes('registerAction')) {
+        this._pushActionsAsync(info.sessionId).catch((err) => {
+          OutputHelper.verbose(
+            `[BridgeConnection] Failed to push actions to ${info.sessionId}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        });
+      }
     });
 
     this._host.on('plugin-disconnected', (sessionId: string) => {
@@ -743,4 +758,41 @@ export class BridgeConnection extends EventEmitter {
       this._idleTimer = undefined;
     }
   }
+
+  // -----------------------------------------------------------------------
+  // Private: Dynamic action push
+  // -----------------------------------------------------------------------
+
+  /**
+   * Load action sources (cached) and push them to the given plugin session.
+   */
+  private async _pushActionsAsync(sessionId: string): Promise<void> {
+    if (!this._host) return;
+
+    // Lazy-load and cache action sources
+    if (!this._actionSources) {
+      this._actionSources = await loadActionSourcesAsync();
+    }
+
+    if (this._actionSources.length === 0) return;
+
+    const results = await pushActionsToSessionAsync(
+      this._host,
+      sessionId,
+      this._actionSources,
+    );
+
+    const succeeded = results.filter((r) => r.success).length;
+    const failed = results.filter((r) => !r.success).length;
+
+    if (failed > 0) {
+      OutputHelper.verbose(
+        `[BridgeConnection] Pushed ${succeeded}/${results.length} actions to ${sessionId} (${failed} failed)`,
+      );
+    } else {
+      OutputHelper.verbose(
+        `[BridgeConnection] Pushed ${succeeded} action(s) to ${sessionId}`,
+      );
+    }
+  }
 }

tools/studio-bridge/src/bridge/bridge-connection.ts

@@ -0,0 +1,83 @@
+/**
+ * Pushes co-located `.luau` action modules to a connected plugin session.
+ * Called after a plugin registers with the bridge to dynamically install
+ * all action handlers.
+ *
+ * Uses the `registerAction` request/response protocol message. Each action
+ * is sent individually and the result is awaited before proceeding to the
+ * next, ensuring deterministic registration order.
+ */
+
+import type { ActionSource } from '../../commands/framework/action-loader.js';
+import type { BridgeHost } from './bridge-host.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ActionPushResult {
+  name: string;
+  success: boolean;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Push logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Push all action sources to a specific plugin session. Returns results
+ * for each action (success or failure). Failures are logged but do not
+ * abort the remaining pushes.
+ */
+export async function pushActionsToSessionAsync(
+  host: BridgeHost,
+  sessionId: string,
+  actions: ActionSource[],
+): Promise<ActionPushResult[]> {
+  const results: ActionPushResult[] = [];
+
+  for (const action of actions) {
+    try {
+      const response = await host.sendToPluginAsync<{
+        type: string;
+        payload: {
+          name: string;
+          success: boolean;
+          error?: string;
+        };
+      }>(
+        sessionId,
+        {
+          type: 'registerAction',
+          sessionId,
+          requestId: `register-${action.name}-${Date.now()}`,
+          payload: {
+            name: action.name,
+            source: action.source,
+          },
+        },
+        10_000,
+      );
+
+      if (response.payload?.success) {
+        results.push({ name: action.name, success: true });
+      } else {
+        const error = response.payload?.error ?? 'Unknown registration error';
+        OutputHelper.verbose(
+          `[ActionPusher] Failed to register action '${action.name}' on session ${sessionId}: ${error}`,
+        );
+        results.push({ name: action.name, success: false, error });
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      OutputHelper.verbose(
+        `[ActionPusher] Error pushing action '${action.name}' to session ${sessionId}: ${error}`,
+      );
+      results.push({ name: action.name, success: false, error });
+    }
+  }
+
+  return results;
+}

tools/studio-bridge/src/bridge/internal/action-pusher.ts

@@ -0,0 +1,210 @@
+/**
+ * Unit tests for the CLI command adapter.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { buildYargsCommand } from './cli-command-adapter.js';
+import { defineCommand, type CommandDefinition } from '../../commands/framework/define-command.js';
+import { arg } from '../../commands/framework/arg-builder.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sessionCommand(
+  overrides: Partial<{ name: string; safety: 'read' | 'mutate' | 'none' }> = {},
+): CommandDefinition {
+  return defineCommand({
+    group: 'console',
+    name: overrides.name ?? 'exec',
+    description: 'Execute code',
+    category: 'execution',
+    safety: overrides.safety ?? 'mutate',
+    scope: 'session',
+    args: {
+      code: arg.positional({ description: 'Luau source code' }),
+      timeout: arg.option({ description: 'Timeout', type: 'number', alias: 'T' }),
+    },
+    handler: async (_session, _args) => ({ success: true }),
+  });
+}
+
+function standaloneCommand(): CommandDefinition {
+  return defineCommand({
+    group: null,
+    name: 'serve',
+    description: 'Start the bridge server',
+    category: 'infrastructure',
+    safety: 'none',
+    scope: 'standalone',
+    args: {
+      port: arg.option({ description: 'Port number', type: 'number', default: 38741 }),
+    },
+    handler: async () => ({ started: true }),
+  });
+}
+
+function connectionCommand(): CommandDefinition {
+  return defineCommand({
+    group: 'process',
+    name: 'list',
+    description: 'List sessions',
+    category: 'infrastructure',
+    safety: 'read',
+    scope: 'connection',
+    args: {},
+    handler: async () => ({ sessions: [] }),
+  });
+}
+
+/** Mock yargs Argv object that records calls. */
+function createMockYargs() {
+  const positionals: Record<string, any> = {};
+  const options: Record<string, any> = {};
+
+  const mock: any = {
+    positionals,
+    options,
+    positional: vi.fn((name: string, opts: any) => {
+      positionals[name] = opts;
+      return mock;
+    }),
+    option: vi.fn((name: string, opts: any) => {
+      options[name] = opts;
+      return mock;
+    }),
+    demandCommand: vi.fn(() => mock),
+  };
+
+  return mock;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('buildYargsCommand', () => {
+  describe('command string', () => {
+    it('includes positional args in command string', () => {
+      const module = buildYargsCommand(sessionCommand());
+      expect(module.command).toBe('exec <code>');
+    });
+
+    it('produces simple command string with no positionals', () => {
+      const module = buildYargsCommand(standaloneCommand());
+      expect(module.command).toBe('serve');
+    });
+
+    it('uses command description', () => {
+      const module = buildYargsCommand(sessionCommand());
+      expect(module.describe).toBe('Execute code');
+    });
+  });
+
+  describe('builder — arg registration', () => {
+    it('registers positional args', () => {
+      const module = buildYargsCommand(sessionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.positionals.code).toBeDefined();
+      expect(yargs.positionals.code.describe).toBe('Luau source code');
+      expect(yargs.positionals.code.type).toBe('string');
+      expect(yargs.positionals.code.demandOption).toBe(true);
+    });
+
+    it('registers command-specific options', () => {
+      const module = buildYargsCommand(sessionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.timeout).toBeDefined();
+      expect(yargs.options.timeout.describe).toBe('Timeout');
+      expect(yargs.options.timeout.type).toBe('number');
+      expect(yargs.options.timeout.alias).toBe('T');
+    });
+  });
+
+  describe('builder — universal args', () => {
+    it('injects --target and --context for session-scoped commands', () => {
+      const module = buildYargsCommand(sessionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.target).toBeDefined();
+      expect(yargs.options.target.alias).toBe('t');
+      expect(yargs.options.context).toBeDefined();
+    });
+
+    it('injects --target and --context for connection-scoped commands', () => {
+      const module = buildYargsCommand(connectionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.target).toBeDefined();
+      expect(yargs.options.context).toBeDefined();
+    });
+
+    it('does not inject --target for standalone commands', () => {
+      const module = buildYargsCommand(standaloneCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.target).toBeUndefined();
+      expect(yargs.options.context).toBeUndefined();
+    });
+
+    it('always injects --format, --output, --open', () => {
+      const module = buildYargsCommand(standaloneCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.format).toBeDefined();
+      expect(yargs.options.output).toBeDefined();
+      expect(yargs.options.open).toBeDefined();
+    });
+
+    it('injects --watch and --interval for read-safety commands', () => {
+      const module = buildYargsCommand(connectionCommand()); // safety: 'read'
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.watch).toBeDefined();
+      expect(yargs.options.watch.alias).toBe('w');
+      expect(yargs.options.interval).toBeDefined();
+      expect(yargs.options.interval.default).toBe(1000);
+    });
+
+    it('does not inject --watch for mutate-safety commands', () => {
+      const module = buildYargsCommand(sessionCommand({ safety: 'mutate' }));
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.watch).toBeUndefined();
+      expect(yargs.options.interval).toBeUndefined();
+    });
+  });
+
+  describe('handler — standalone', () => {
+    it('calls standalone handler with extracted args', async () => {
+      const handler = vi.fn().mockResolvedValue({ started: true });
+      const cmd = defineCommand({
+        group: null,
+        name: 'serve',
+        description: 'Start server',
+        category: 'infrastructure',
+        safety: 'none',
+        scope: 'standalone',
+        args: {
+          port: arg.option({ description: 'Port', type: 'number', default: 38741 }),
+        },
+        handler,
+      });
+
+      const module = buildYargsCommand(cmd);
+      await (module.handler as any)({ port: 9999, verbose: false, timeout: 120000 });
+
+      expect(handler).toHaveBeenCalledWith({ port: 9999 });
+    });
+  });
+});