@rayrun/cli 0.1.0 → 0.4.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,552 @@
+/* eslint-disable node/no-process-env -- management intentionally reads the invoking user's Rayrun environment */
+import { Rayrun, RayrunApiError } from '@rayrun/sdk';
+import { readFile, writeFile } from 'node:fs/promises';
+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]
+  rayrun hooks pull <connection-uid> <tool-uid> [--output <file>] [--types-output <file>] [--json]
+  rayrun hooks test <connection-uid> <tool-uid> --arguments <json> [--file <file>] [--mock-result <json>] [--config <json>] [--json]
+  rayrun hooks deploy <connection-uid> <tool-uid> [--file <file>] [--config <json>] [--shadow] [--json]
+  rayrun hooks rollback <connection-uid> <tool-uid> <revision-uid> [--shadow] [--json]
+  rayrun hooks deactivate <connection-uid> <tool-uid> [--shadow] [--json]
+  rayrun hooks logs <connection-uid> <tool-uid> [--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',
+  'hooks',
+  'policy',
+  'tools',
+]);
+
+export const isManagementCommand = (command) => managementCommands.has(command);
+
+const optionNames = new Map([
+  ['--base-url', 'baseUrl'],
+  ['--arguments', 'argumentsJson'],
+  ['--config', 'configJson'],
+  ['--connection', 'connectionUid'],
+  ['--cursor', 'cursor'],
+  ['--limit', 'limit'],
+  ['--file', 'filePath'],
+  ['--mock-result', 'mockResultJson'],
+  ['--name', 'name'],
+  ['--query', 'query'],
+  ['--output', 'outputPath'],
+  ['--transport', 'transport'],
+  ['--types-output', 'typesOutputPath'],
+]);
+
+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;
+    }
+    if (argument === '--shadow') {
+      if (!allowedOptions.has('shadow')) throw new Error(`Unknown option: ${argument}`);
+      options.shadow = 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 parseJsonOption = (value, option, fallback) => {
+  if (value === undefined) return fallback;
+
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new Error(`${option} must be valid JSON.`);
+  }
+};
+
+const hookMode = (options) => (options.shadow ? 'shadow' : 'active');
+
+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;
+  }
+
+  if (command === 'hooks' && action === 'pull') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'outputPath', 'typesOutputPath']),
+    );
+    requireShape(positional.length === 2);
+    const { hook } = await client.hooks.get(positional[0], positional[1]);
+
+    if (options.outputPath) await writeFile(options.outputPath, hook.draftSource, 'utf8');
+    if (options.typesOutputPath) await writeFile(options.typesOutputPath, hook.types, 'utf8');
+    if (options.json) writeValue(output, { hook });
+    else if (!options.outputPath) output.write(hook.draftSource);
+    else output.write(`Wrote hook source to ${options.outputPath}.\n`);
+    return;
+  }
+
+  if (command === 'hooks' && action === 'test') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['argumentsJson', 'configJson', 'filePath', 'json', 'mockResultJson']),
+    );
+    requireShape(positional.length === 2 && options.argumentsJson !== undefined);
+    const { hook } = await client.hooks.get(positional[0], positional[1]);
+    const source = options.filePath ? await readFile(options.filePath, 'utf8') : hook.draftSource;
+    const body = {
+      arguments: parseJsonOption(options.argumentsJson, '--arguments'),
+      config: parseJsonOption(options.configJson, '--config', hook.draftConfig),
+      source,
+      ...(options.mockResultJson === undefined
+        ? {}
+        : { mockResult: parseJsonOption(options.mockResultJson, '--mock-result') }),
+    };
+    const result = await client.hooks.test(positional[0], positional[1], body);
+    writeValue(output, result);
+    return;
+  }
+
+  if (command === 'hooks' && action === 'deploy') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['configJson', 'filePath', 'json', 'shadow']),
+    );
+    requireShape(positional.length === 2);
+    const connectionUid = positional[0];
+    const toolUid = positional[1];
+    let { hook } = await client.hooks.get(connectionUid, toolUid);
+
+    if (hook.hookUid === null || options.filePath || options.configJson !== undefined) {
+      const source = options.filePath ? await readFile(options.filePath, 'utf8') : hook.draftSource;
+      const saved = await client.hooks.saveDraft(connectionUid, toolUid, {
+        config: parseJsonOption(options.configJson, '--config', hook.draftConfig),
+        expectedVersion: hook.version,
+        source,
+      });
+      hook = saved.hook;
+    }
+
+    const result = await client.hooks.deploy(connectionUid, toolUid, {
+      expectedVersion: hook.version,
+      mode: hookMode(options),
+    });
+    if (options.json) writeValue(output, result);
+    else {
+      const revisionUid =
+        hookMode(options) === 'shadow'
+          ? result.hook.shadowRevisionUid
+          : result.hook.activeRevisionUid;
+      output.write(`Deployed ${String(revisionUid)} in ${hookMode(options)} mode.\n`);
+    }
+    return;
+  }
+
+  if (command === 'hooks' && ['deactivate', 'rollback'].includes(action)) {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'shadow']),
+    );
+    requireShape(positional.length === (action === 'rollback' ? 3 : 2));
+    const { hook } = await client.hooks.get(positional[0], positional[1]);
+    const result = await client.hooks.setDeployment(positional[0], positional[1], {
+      expectedVersion: hook.version,
+      mode: hookMode(options),
+      revisionUid: action === 'rollback' ? positional[2] : null,
+    });
+    if (options.json) writeValue(output, result);
+    else {
+      output.write(
+        action === 'rollback'
+          ? `Deployed ${positional[2]} in ${hookMode(options)} mode.\n`
+          : `Deactivated ${hookMode(options)} mode.\n`,
+      );
+    }
+    return;
+  }
+
+  if (command === 'hooks' && action === 'logs') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 2);
+    const page = await client.hooks.listRuns(positional[0], positional[1], pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'WHEN', value: (item) => item.createdAt },
+        { label: 'REQUEST', value: (item) => item.requestId },
+        { label: 'REVISION', value: (item) => item.revisionUid },
+        { label: 'MODE', value: (item) => (item.shadow ? 'shadow' : 'active') },
+        { label: 'STAGE', value: (item) => item.stage },
+        { label: 'OUTCOME', value: (item) => item.outcome },
+        {
+          label: 'CHANGED',
+          value: (item) =>
+            item.differsFromActive === null ? undefined : item.differsFromActive ? 'yes' : 'no',
+        },
+        { label: 'DURATION', value: (item) => `${String(item.durationMs)}ms` },
+        {
+          label: 'LOGS',
+          value: (item) =>
+            item.logs
+              ?.map(
+                (entry) =>
+                  `[${entry.level}] ${entry.message}${entry.data === undefined ? '' : ` ${JSON.stringify(entry.data)}`}`,
+              )
+              .join(' | ') ?? 'not captured',
+        },
+        { label: 'ERROR', value: (item) => item.errorMessage },
+      ],
+      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}` : '';
+    const diagnostics = error.diagnostics
+      .map(
+        (entry) =>
+          `hook.ts${entry.line === undefined ? '' : `:${String(entry.line)}${entry.column === undefined ? '' : `:${String(entry.column)}`}`}: ${entry.message}`,
+      )
+      .join('\n');
+    throw new Error(
+      `${error.message} (${error.code}${requestId})${diagnostics ? `\n${diagnostics}` : ''}`,
+      { cause: error },
+    );
+  }
+};