@rayrun/cli 0.1.0 → 0.3.0

package/src/main.js

@@ -1,4 +1,6 @@
 import { clientDefinitions, detectClients } from './clients.js';
+import { executionUsage, isExecutionCommand, runExecutionCommand } from './execution.js';
+import { isManagementCommand, managementUsage, runManagementCommand } from './management.js';
 import { applySetup, rollbackSetup } from './setup.js';
 import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
@@ -9,7 +11,11 @@ const usage = `Usage:
   rayrun setup <endpoint> [--client <id> ... | --all] [--project] [--yes] [--dry-run] [--login | --no-login]
   rayrun setup rollback <backup-id>
 
-Clients: claude-code, codex, cursor, vscode, windsurf, devin, opencode`;
+Clients: claude-code, codex, cursor, vscode, windsurf, devin, opencode
+
+${executionUsage}
+
+${managementUsage}`;
 
 export const validateEndpoint = (value) => {
   let endpoint;
@@ -97,7 +103,7 @@ const selectInteractively = async (clients) => {
   return clients.filter((_client, index) => indexes.has(index));
 };
 
-export const main = async (arguments_) => {
+export const main = async (arguments_, dependencies) => {
   if (arguments_.includes('--help') || arguments_.includes('-h')) {
     process.stdout.write(`${usage}\n`);
     return;
@@ -106,6 +112,14 @@ export const main = async (arguments_) => {
     process.stdout.write(`${String(packageVersion)}\n`);
     return;
   }
+  if (isExecutionCommand(arguments_)) {
+    await runExecutionCommand(arguments_, { ...dependencies, version: packageVersion });
+    return;
+  }
+  if (isManagementCommand(arguments_[0])) {
+    await runManagementCommand(arguments_, dependencies);
+    return;
+  }
   const { options, positional } = parseArguments(arguments_);
 
   if (positional[0] !== 'setup') {

package/src/management.js

@@ -0,0 +1,377 @@
+/* eslint-disable node/no-process-env -- management intentionally reads the invoking user's Rayrun environment */
+import { Rayrun, RayrunApiError } from '@rayrun/sdk';
+import { stripVTControlCharacters } from 'node:util';
+
+export const managementUsage = `Management:
+  rayrun connect mcp <url> --name <name> [--transport <streamable-http|sse>] [--json]
+  rayrun connect openapi <spec-url> [--name <name>] [--base-url <url>] [--json]
+  rayrun connections list [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun clients list [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun tools search <query> [--connection <uid>] [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun policy inspect <client-uid> [--query <query>] [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun approvals list [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun activity list [--limit <1-100>] [--cursor <cursor>] [--json]
+
+Environment:
+  RAYRUN_API_KEY   API key created in Dashboard -> Settings -> API keys
+  RAYRUN_API_URL   Optional API origin (defaults to https://ray.run)`;
+
+const managementCommands = new Set([
+  'activity',
+  'approvals',
+  'clients',
+  'connect',
+  'connections',
+  'policy',
+  'tools',
+]);
+
+export const isManagementCommand = (command) => managementCommands.has(command);
+
+const optionNames = new Map([
+  ['--base-url', 'baseUrl'],
+  ['--connection', 'connectionUid'],
+  ['--cursor', 'cursor'],
+  ['--limit', 'limit'],
+  ['--name', 'name'],
+  ['--query', 'query'],
+  ['--transport', 'transport'],
+]);
+
+const parseCommandArguments = (arguments_, allowedOptions) => {
+  const options = { json: false };
+  const positional = [];
+
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+
+    if (argument === '--json') {
+      if (!allowedOptions.has('json')) throw new Error(`Unknown option: ${argument}`);
+      options.json = true;
+      continue;
+    }
+
+    const optionName = optionNames.get(argument);
+    if (optionName) {
+      if (!allowedOptions.has(optionName)) throw new Error(`Unknown option: ${argument}`);
+      const value = arguments_[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value.`);
+      if (options[optionName] !== undefined) throw new Error(`${argument} can only be used once.`);
+      options[optionName] = value;
+      index += 1;
+      continue;
+    }
+
+    if (argument?.startsWith('--')) throw new Error(`Unknown option: ${argument}`);
+    if (argument) positional.push(argument);
+  }
+
+  if (options.limit !== undefined) {
+    const limit = Number(options.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw new Error('--limit must be an integer from 1 to 100.');
+    }
+    options.limit = limit;
+  }
+
+  return { options, positional };
+};
+
+export const validateApiBaseUrl = (value) => {
+  let url;
+
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('RAYRUN_API_URL must be an absolute HTTP or HTTPS URL.');
+  }
+
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('RAYRUN_API_URL must use HTTP or HTTPS.');
+  }
+  if (url.protocol === 'http:' && !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)) {
+    throw new Error('RAYRUN_API_URL may use HTTP only on localhost.');
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error('RAYRUN_API_URL cannot contain credentials, a query string, or a fragment.');
+  }
+
+  return url.href.replace(/\/$/u, '');
+};
+
+const formatCell = (value) => {
+  if (value === null || value === undefined || value === '') return '-';
+  if (typeof value === 'boolean') return value ? 'yes' : 'no';
+  const sanitized = stripVTControlCharacters(String(value))
+    .replaceAll(/\p{Cc}+/gu, ' ')
+    .replaceAll(/\s+/gu, ' ')
+    .trim();
+
+  return sanitized || '-';
+};
+
+export const renderTable = (items, columns) => {
+  if (items.length === 0) return 'No results.\n';
+
+  const rows = items.map((item) => columns.map(({ value }) => formatCell(value(item))));
+  const widths = columns.map(({ label }, index) =>
+    Math.max(label.length, ...rows.map((row) => row[index].length)),
+  );
+  const line = (cells) =>
+    cells
+      .map((cell, index) => cell.padEnd(widths[index], ' '))
+      .join('  ')
+      .trimEnd();
+
+  return `${line(columns.map(({ label }) => label))}\n${line(widths.map((width) => '-'.repeat(width)))}\n${rows.map(line).join('\n')}\n`;
+};
+
+const pageQuery = (options, extra = {}) => ({
+  ...extra,
+  cursor: options.cursor,
+  limit: options.limit,
+});
+
+const writeValue = (output, value) => {
+  output.write(`${JSON.stringify(value, null, 2)}\n`);
+};
+
+const writePage = ({ columns, options, output, page }) => {
+  if (options.json) {
+    writeValue(output, page);
+    return;
+  }
+
+  output.write(renderTable(page.items, columns));
+  if (page.page.nextCursor) output.write(`Next cursor: ${page.page.nextCursor}\n`);
+};
+
+const requireShape = (condition) => {
+  if (!condition) throw new Error(managementUsage);
+};
+
+const runCommand = async ({ arguments_, client, output }) => {
+  const command = arguments_[0];
+  const action = arguments_[1];
+
+  if (command === 'connect' && action === 'mcp') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'name', 'transport']),
+    );
+    requireShape(positional.length === 1 && typeof options.name === 'string');
+    if (options.transport && !['sse', 'streamable-http'].includes(options.transport)) {
+      throw new Error('--transport must be streamable-http or sse.');
+    }
+    const result = await client.connections.create({
+      kind: 'mcp',
+      name: options.name,
+      transport: options.transport,
+      url: positional[0],
+    });
+    if (options.json) writeValue(output, result);
+    else output.write(`Connected ${result.connection.uid}.\n`);
+    return;
+  }
+
+  if (command === 'connect' && action === 'openapi') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['baseUrl', 'json', 'name']),
+    );
+    requireShape(positional.length === 1);
+    const result = await client.connections.create({
+      baseUrl: options.baseUrl,
+      kind: 'openapi',
+      name: options.name,
+      specificationUrl: positional[0],
+    });
+    if (options.json) writeValue(output, result);
+    else output.write(`Connected ${result.connection.uid}.\n`);
+    return;
+  }
+
+  if (command === 'connections' && action === 'list') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 0);
+    const page = await client.connections.list(pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'NAME', value: (item) => item.displayName },
+        { label: 'KIND', value: (item) => item.kind },
+        { label: 'STATUS', value: (item) => item.status },
+        { label: 'POLICY', value: (item) => item.toolAccessMode },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'clients' && action === 'list') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 0);
+    const page = await client.clients.list(pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'CLIENT', value: (item) => item.clientName },
+        { label: 'USER', value: (item) => item.userName },
+        { label: 'POLICY', value: (item) => item.toolAccessMode },
+        { label: 'PROFILE', value: (item) => item.accessProfile?.name },
+        { label: 'LAST USED', value: (item) => item.lastUsedAt },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'tools' && action === 'search') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['connectionUid', 'cursor', 'json', 'limit']),
+    );
+    const query = positional.join(' ').trim();
+    requireShape(query.length > 0);
+    const page = await client.tools.list(
+      pageQuery(options, { connectionUid: options.connectionUid, query }),
+    );
+    writePage({
+      columns: [
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'NAME', value: (item) => item.name },
+        { label: 'CONNECTION', value: (item) => item.connectionUid },
+        { label: 'RISK', value: (item) => item.risk },
+        { label: 'APPROVED', value: (item) => item.approved },
+        { label: 'RULE', value: (item) => item.rule },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'policy' && action === 'inspect') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit', 'query']),
+    );
+    requireShape(positional.length === 1);
+    const page = await client.clients.listTools(
+      positional[0],
+      pageQuery(options, { query: options.query }),
+    );
+    writePage({
+      columns: [
+        { label: 'SERVICE', value: (item) => item.serviceName },
+        { label: 'TOOL', value: (item) => item.name },
+        { label: 'EFFECTIVE', value: (item) => item.effectiveDecision },
+        { label: 'REASON', value: (item) => item.effectiveReason },
+        { label: 'CLIENT', value: (item) => item.clientDecision },
+        { label: 'WORKSPACE', value: (item) => item.workspaceDecision },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'approvals' && action === 'list') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 0);
+    const page = await client.reviews.list(pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'SERVICE', value: (item) => item.connectionName },
+        { label: 'TOOL', value: (item) => item.toolName },
+        { label: 'STATUS', value: (item) => item.status },
+        { label: 'CREATED', value: (item) => item.createdAt },
+        { label: 'EXPIRES', value: (item) => item.expiresAt },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'activity' && action === 'list') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 0);
+    const page = await client.activity.list(pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'ID', value: (item) => item.id },
+        { label: 'WHEN', value: (item) => item.calledAt },
+        { label: 'TOOL', value: (item) => item.toolName },
+        { label: 'SERVICE', value: (item) => item.connectionName },
+        { label: 'CLIENT', value: (item) => item.clientName },
+        { label: 'DECISION', value: (item) => item.policyDecision },
+        {
+          label: 'RESULT',
+          value: (item) =>
+            item.succeeded === null
+              ? item.errorCode === 'outcome_unknown'
+                ? 'outcome unknown'
+                : 'pending'
+              : item.succeeded
+                ? 'success'
+                : 'failed',
+        },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  throw new Error(managementUsage);
+};
+
+export const runManagementCommand = async (
+  arguments_,
+  {
+    environment = process.env,
+    fetchImplementation = globalThis.fetch,
+    output = process.stdout,
+  } = {},
+) => {
+  const apiKey = environment.RAYRUN_API_KEY;
+  if (!apiKey?.trim()) {
+    throw new Error(
+      'RAYRUN_API_KEY is required. Create a scoped key in Dashboard -> Settings -> API keys.',
+    );
+  }
+  const baseUrl = environment.RAYRUN_API_URL
+    ? validateApiBaseUrl(environment.RAYRUN_API_URL)
+    : undefined;
+  const client = new Rayrun({ apiKey, baseUrl, fetch: fetchImplementation });
+
+  try {
+    await runCommand({ arguments_, client, output });
+  } catch (error) {
+    if (!(error instanceof RayrunApiError)) throw error;
+    const requestId = error.requestId ? `, request ${error.requestId}` : '';
+    throw new Error(`${error.message} (${error.code}${requestId})`, { cause: error });
+  }
+};