@quenty/studio-bridge 0.7.0 → 0.8.0

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

@@ -0,0 +1,342 @@
+/**
+ * CLI adapter — converts a `CommandDefinition` into a yargs `CommandModule`.
+ *
+ * Responsibilities:
+ *   - Maps `ArgDefinition` records to yargs positionals/options
+ *   - Injects universal args based on scope and safety
+ *   - Wraps handler in connect → resolve → fn → disconnect lifecycle
+ *   - Dispatches results to a `ResultReporter` (stdout / file / watch redraw)
+ *   - Honors `--output` (file write), `--open`, `--watch`, `--interval`
+ */
+
+import type { Argv, CommandModule } from 'yargs';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  buildResultReporter,
+  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 { toYargsOptions } from '../../commands/framework/arg-builder.js';
+
+/** Args injected by the adapter (not defined on CommandDefinition). */
+export interface AdapterArgs {
+  target?: string;
+  context?: string;
+  format?: string;
+  output?: string;
+  open?: boolean;
+  watch?: boolean;
+  interval?: number;
+}
+
+/**
+ * Optional lifecycle override for testing. When provided, the adapter
+ * calls these instead of `BridgeConnection.connectAsync`.
+ */
+export interface CliLifecycleProvider {
+  connectAsync(opts: {
+    timeoutMs?: number;
+    remoteHost?: string;
+    local?: boolean;
+    waitForSessions?: boolean;
+  }): Promise<BridgeConnection>;
+}
+
+/** Extract only command-specific args from the full argv object. */
+function extractCommandArgs(
+  argv: Record<string, unknown>,
+  def: CommandDefinition
+): Record<string, unknown> {
+  const commandArgs: Record<string, unknown> = {};
+  for (const name of Object.keys(def.args)) {
+    if (name in argv) {
+      commandArgs[name] = argv[name];
+    }
+  }
+  return commandArgs;
+}
+
+/** Execute a command's handler with appropriate connection lifecycle. */
+async function executeCommandAsync(
+  def: CommandDefinition,
+  commandArgs: Record<string, unknown>,
+  argv: Record<string, unknown>,
+  connect: CliLifecycleProvider['connectAsync'],
+  existingConnection?: BridgeConnection
+): Promise<unknown> {
+  if (def.scope === 'standalone') {
+    return (def.handler as any)(commandArgs);
+  }
+
+  // Reuse existing connection if provided (watch mode), otherwise connect fresh
+  const connection =
+    existingConnection ??
+    (await connect({
+      timeoutMs: argv.timeout as number | undefined,
+      remoteHost: argv.remote as string | undefined,
+      local: argv.local as boolean | undefined,
+      waitForSessions: def.scope === 'connection',
+    }));
+
+  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);
+    }
+    return await (def.handler as any)(connection, commandArgs);
+  } finally {
+    if (!existingConnection) {
+      await connection.disconnectAsync();
+    }
+  }
+}
+
+/** 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;
+  if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+    return { ...result, _warnings: warnings };
+  }
+  return result;
+}
+
+/**
+ * Render a command result for stdout/file output. `--format=json` (or any
+ * explicit non-text format) routes through the command's `json` override or
+ * falls back to `formatJson`. Anything else (default, `--format=text`)
+ * routes through the command's `format` callback, then `result.summary`,
+ * then JSON as a last resort.
+ */
+function renderResult(
+  def: CommandDefinition,
+  result: unknown,
+  explicitFormat: string | undefined
+): string {
+  if (explicitFormat === 'json') {
+    if (def.cli?.json) return def.cli.json(result as any);
+    return formatJson(injectWarnings(result), { pretty: process.stdout.isTTY });
+  }
+
+  if (def.cli?.format) return def.cli.format(result as any);
+
+  if (typeof result === 'object' && result !== null && 'summary' in result) {
+    return (result as any).summary;
+  }
+
+  return formatJson(result);
+}
+
+/**
+ * Extract a Buffer from the result's binary field, or undefined if no
+ * binary field is configured / extractable / requested. When `--format=json`
+ * is explicit the user wants JSON not raw bytes — return undefined so the
+ * file reporter falls back to text rendering.
+ */
+function extractBinaryBuffer(
+  def: CommandDefinition,
+  result: unknown,
+  format: string | undefined
+): Buffer | undefined {
+  if (format === 'json') return undefined;
+  const binaryField = def.cli?.binaryField;
+  if (!binaryField) return undefined;
+  if (typeof result !== 'object' || result === null) return undefined;
+  const data = (result as Record<string, unknown>)[binaryField];
+  if (typeof data !== 'string') return undefined;
+  return Buffer.from(data, 'base64');
+}
+
+export function buildYargsCommand(
+  def: CommandDefinition,
+  options?: { lifecycle?: CliLifecycleProvider }
+): CommandModule {
+  const { positionals, options: yargsOptions } = toYargsOptions(def.args);
+
+  const positionalSuffix = positionals
+    .map((p) => (p.options.demandOption ? `<${p.name}>` : `[${p.name}]`))
+    .join(' ');
+
+  const command = positionalSuffix
+    ? `${def.name} ${positionalSuffix}`
+    : def.name;
+
+  return {
+    command,
+    describe: def.description,
+    builder: (yargs: Argv) => {
+      for (const pos of positionals) {
+        yargs.positional(pos.name, pos.options as any);
+      }
+
+      for (const [name, opt] of Object.entries(yargsOptions)) {
+        yargs.option(name, opt as any);
+      }
+
+      if (def.scope === 'session' || def.scope === 'connection') {
+        yargs.option('target', {
+          alias: 't',
+          type: 'string',
+          describe: 'Target session ID (or "all" for broadcast)',
+        });
+        yargs.option('context', {
+          type: 'string',
+          describe: 'Target context (edit, client, server)',
+          choices: ['edit', 'client', 'server'],
+        });
+      }
+
+      yargs.option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        describe: 'Output format',
+      });
+      yargs.option('output', {
+        alias: 'o',
+        type: 'string',
+        describe: 'Write output to file',
+      });
+      yargs.option('open', {
+        type: 'boolean',
+        default: false,
+        describe: 'Open output file after writing',
+      });
+
+      if (def.safety === 'read') {
+        yargs.option('watch', {
+          alias: 'w',
+          type: 'boolean',
+          default: false,
+          describe: 'Watch for changes',
+        });
+        yargs.option('interval', {
+          type: 'number',
+          default: 1000,
+          describe: 'Watch interval in milliseconds',
+        });
+      }
+
+      return yargs;
+    },
+    handler: async (argv: any) => {
+      const commandArgs = extractCommandArgs(argv, def);
+      const explicitFormat = argv.format as string | undefined;
+      const reporter = buildResultReporter<unknown>({
+        outputPath: argv.output as string | undefined,
+        watch: !!argv.watch && def.safety === 'read',
+        open: argv.open as boolean | undefined,
+        intervalMs: argv.interval as number | undefined,
+        render: (result) => renderResult(def, result, explicitFormat),
+        binary: (result) => extractBinaryBuffer(def, result, explicitFormat),
+      });
+      const connect =
+        options?.lifecycle?.connectAsync.bind(options.lifecycle) ??
+        BridgeConnection.connectAsync.bind(BridgeConnection);
+
+      try {
+        if (argv.watch && def.safety === 'read') {
+          await runWatchModeAsync(def, commandArgs, argv, reporter, connect);
+        } else {
+          await runOnceAsync(def, commandArgs, argv, reporter, connect);
+        }
+      } catch (err) {
+        OutputHelper.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    },
+  };
+}
+
+async function runOnceAsync(
+  def: CommandDefinition,
+  commandArgs: Record<string, unknown>,
+  argv: Record<string, unknown>,
+  reporter: ResultReporter<unknown>,
+  connect: CliLifecycleProvider['connectAsync']
+): Promise<void> {
+  const result = await executeCommandAsync(def, commandArgs, argv, connect);
+
+  await reporter.startAsync();
+  reporter.onResult(result);
+  await reporter.stopAsync();
+
+  if (
+    typeof result === 'object' &&
+    result !== null &&
+    'success' in result &&
+    !(result as any).success
+  ) {
+    process.exit(1);
+  }
+}
+
+async function runWatchModeAsync(
+  def: CommandDefinition,
+  commandArgs: Record<string, unknown>,
+  argv: Record<string, unknown>,
+  reporter: ResultReporter<unknown>,
+  connect: CliLifecycleProvider['connectAsync']
+): Promise<void> {
+  const intervalMs = (argv.interval as number | undefined) ?? 1000;
+
+  // Standalone commands run without a persistent connection
+  const connection: BridgeConnection | undefined =
+    def.scope === 'standalone'
+      ? undefined
+      : await connect({
+          timeoutMs: argv.timeout as number | undefined,
+          remoteHost: argv.remote as string | undefined,
+          local: argv.local as boolean | undefined,
+          waitForSessions: def.scope === 'connection',
+        });
+
+  let stopped = false;
+  const cleanup = (): void => {
+    stopped = true;
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  try {
+    await reporter.startAsync();
+
+    let result = await executeCommandAsync(
+      def,
+      commandArgs,
+      argv,
+      connect,
+      connection
+    );
+    reporter.onResult(result);
+
+    while (!stopped) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      if (stopped) break;
+      try {
+        result = await executeCommandAsync(
+          def,
+          commandArgs,
+          argv,
+          connect,
+          connection
+        );
+        reporter.onResult(result);
+      } catch {
+        // Swallow transient errors during polling
+      }
+    }
+  } finally {
+    await reporter.stopAsync();
+    if (connection) {
+      await connection.disconnectAsync();
+    }
+  }
+}

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

@@ -0,0 +1,146 @@
+/**
+ * Unit tests for the group builder.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { buildGroupCommands } from './group-builder.js';
+import { CommandRegistry } from '../../commands/framework/command-registry.js';
+import { defineCommand } from '../../commands/framework/define-command.js';
+import { arg } from '../../commands/framework/arg-builder.js';
+
+function makeRegistry(): CommandRegistry {
+  const registry = new CommandRegistry();
+
+  registry.register(
+    defineCommand({
+      group: 'console',
+      name: 'exec',
+      description: 'Execute code',
+      category: 'execution',
+      safety: 'mutate',
+      scope: 'session',
+      args: { code: arg.positional({ description: 'Code' }) },
+      handler: async () => ({}),
+    })
+  );
+
+  registry.register(
+    defineCommand({
+      group: 'console',
+      name: 'logs',
+      description: 'View logs',
+      category: 'execution',
+      safety: 'read',
+      scope: 'session',
+      args: {},
+      handler: async () => ({}),
+    })
+  );
+
+  registry.register(
+    defineCommand({
+      group: 'process',
+      name: 'list',
+      description: 'List sessions',
+      category: 'infrastructure',
+      safety: 'read',
+      scope: 'connection',
+      args: {},
+      handler: async () => ({}),
+    })
+  );
+
+  registry.register(
+    defineCommand({
+      group: null,
+      name: 'serve',
+      description: 'Start server',
+      category: 'infrastructure',
+      safety: 'none',
+      scope: 'standalone',
+      args: {},
+      handler: async () => ({}),
+    })
+  );
+
+  return registry;
+}
+
+function createMockYargs() {
+  const commands: any[] = [];
+
+  const mock: any = {
+    commands,
+    command: vi.fn((cmd: any) => {
+      commands.push(cmd);
+      return mock;
+    }),
+    demandCommand: vi.fn(() => mock),
+  };
+
+  return mock;
+}
+
+describe('buildGroupCommands', () => {
+  it('creates a group command for each unique group', () => {
+    const registry = makeRegistry();
+    const result = buildGroupCommands(registry);
+
+    expect(result.groups).toHaveLength(2);
+    const groupNames = result.groups.map(
+      (g) => (g.command as string).split(' ')[0]
+    );
+    expect(groupNames).toContain('console');
+    expect(groupNames).toContain('process');
+  });
+
+  it('creates top-level commands for null-group definitions', () => {
+    const registry = makeRegistry();
+    const result = buildGroupCommands(registry);
+
+    expect(result.topLevel).toHaveLength(1);
+    expect(result.topLevel[0].command).toBe('serve');
+  });
+
+  it('group commands use <command> suffix', () => {
+    const registry = makeRegistry();
+    const result = buildGroupCommands(registry);
+
+    const consoleMod = result.groups.find((g) =>
+      (g.command as string).startsWith('console')
+    );
+    expect(consoleMod!.command).toBe('console <command>');
+  });
+
+  it('group commands have descriptions', () => {
+    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');
+  });
+
+  it('group builder registers subcommands', () => {
+    const registry = makeRegistry();
+    const result = buildGroupCommands(registry);
+
+    const consoleMod = result.groups.find((g) =>
+      (g.command as string).startsWith('console')
+    );
+    const yargs = createMockYargs();
+    (consoleMod!.builder as any)(yargs);
+
+    // Should register 2 subcommands (exec, logs)
+    expect(yargs.commands).toHaveLength(2);
+  });
+
+  it('returns empty arrays for empty registry', () => {
+    const registry = new CommandRegistry();
+    const result = buildGroupCommands(registry);
+
+    expect(result.groups).toEqual([]);
+    expect(result.topLevel).toEqual([]);
+  });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * Group builder — converts a `CommandRegistry` into yargs `CommandModule`
+ * entries with grouped subcommands.
+ *
+ * Grouped commands become parent commands with subcommands:
+ *   `console exec <code>`  →  `console` parent, `exec` subcommand
+ *
+ * Top-level commands (group = null) are returned as standalone modules:
+ *   `serve`, `mcp`, `terminal`
+ */
+
+import type { CommandModule } from 'yargs';
+import type { CommandRegistry } from '../../commands/framework/command-registry.js';
+import type { CliLifecycleProvider } from './cli-command-adapter.js';
+import { buildYargsCommand } from './cli-command-adapter.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',
+  linux: 'Linux/Wine environment management',
+};
+
+export interface GroupBuilderOptions {
+  lifecycle?: CliLifecycleProvider;
+}
+
+export interface GroupBuilderResult {
+  /** Parent commands for each group (e.g. `console <command>`). */
+  groups: CommandModule[];
+  /** Top-level commands with no group (e.g. `serve`, `mcp`). */
+  topLevel: CommandModule[];
+}
+
+/**
+ * Build yargs command modules from a registry. Returns grouped parent
+ * commands and top-level standalone commands separately so the caller
+ * can register them independently.
+ */
+export function buildGroupCommands(
+  registry: CommandRegistry,
+  options: GroupBuilderOptions = {}
+): GroupBuilderResult {
+  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`;
+
+    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: () => {},
+    });
+  }
+
+  // Top-level commands (group = null) → standalone modules
+  for (const cmd of registry.getTopLevel()) {
+    topLevel.push(buildYargsCommand(cmd, options));
+  }
+
+  return { groups, topLevel };
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Unit tests for the help formatter.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatGroupedHelp } from './help-formatter.js';
+import { CommandRegistry } from '../../commands/framework/command-registry.js';
+import { defineCommand } from '../../commands/framework/define-command.js';
+
+function makeRegistry(): CommandRegistry {
+  const registry = new CommandRegistry();
+
+  registry.register(
+    defineCommand({
+      group: 'console',
+      name: 'exec',
+      description: 'Execute code',
+      category: 'execution',
+      safety: 'mutate',
+      scope: 'session',
+      args: {},
+      handler: async () => ({}),
+    })
+  );
+
+  registry.register(
+    defineCommand({
+      group: 'process',
+      name: 'list',
+      description: 'List sessions',
+      category: 'infrastructure',
+      safety: 'read',
+      scope: 'connection',
+      args: {},
+      handler: async () => ({}),
+    })
+  );
+
+  registry.register(
+    defineCommand({
+      group: null,
+      name: 'serve',
+      description: 'Start the bridge server',
+      category: 'infrastructure',
+      safety: 'none',
+      scope: 'standalone',
+      args: {},
+      handler: async () => ({}),
+    })
+  );
+
+  return registry;
+}
+
+describe('formatGroupedHelp', () => {
+  it('includes Execution header', () => {
+    const help = formatGroupedHelp(makeRegistry());
+    expect(help).toContain('Execution:');
+  });
+
+  it('includes Infrastructure header', () => {
+    const help = formatGroupedHelp(makeRegistry());
+    expect(help).toContain('Infrastructure:');
+  });
+
+  it('lists execution groups under Execution', () => {
+    const help = formatGroupedHelp(makeRegistry());
+    const executionSection = help.split('Infrastructure:')[0];
+    expect(executionSection).toContain('console <command>');
+  });
+
+  it('lists infrastructure groups under Infrastructure', () => {
+    const help = formatGroupedHelp(makeRegistry());
+    const infraSection = help.split('Infrastructure:')[1];
+    expect(infraSection).toContain('process <command>');
+  });
+
+  it('lists top-level infrastructure commands', () => {
+    const help = formatGroupedHelp(makeRegistry());
+    const infraSection = help.split('Infrastructure:')[1];
+    expect(infraSection).toContain('serve');
+    expect(infraSection).toContain('Start the bridge server');
+  });
+
+  it('includes group descriptions', () => {
+    const help = formatGroupedHelp(makeRegistry());
+    expect(help).toContain('Execute code and view logs');
+    expect(help).toContain('Manage Studio processes');
+  });
+
+  it('returns empty for empty registry', () => {
+    const help = formatGroupedHelp(new CommandRegistry());
+    expect(help).toContain('studio-bridge <command>');
+    expect(help).not.toContain('Execution:');
+    expect(help).not.toContain('Infrastructure:');
+  });
+});