@rayrun/cli 0.3.0 → 0.4.0

package/README.md

@@ -84,3 +84,30 @@ List commands show a compact table. Add `--json` for stable machine-readable out
 request up to 100 rows, and `--cursor` with the printed next cursor to continue. The CLI calls the
 same hosted API and policy evaluator as the dashboard; it does not run a local gateway or store API
 keys.
+
+## Author hosted tool hooks
+
+Use a full-control API key. Hook source executes in Rayrun’s hosted sandbox, not in the CLI process.
+
+```sh
+rayrun hooks pull <connection-uid> <tool-uid> \
+  --output hook.ts --types-output rayrun-hooks.d.ts
+
+rayrun hooks test <connection-uid> <tool-uid> \
+  --file hook.ts --arguments '{"query":"release"}' --mock-result '{"items":[]}'
+
+rayrun hooks deploy <connection-uid> <tool-uid> --file hook.ts --shadow
+rayrun hooks logs <connection-uid> <tool-uid>
+rayrun hooks rollback <connection-uid> <tool-uid> <revision-uid>
+rayrun hooks deactivate <connection-uid> <tool-uid> --shadow
+```
+
+`pull` can write the draft and generated TypeScript declarations separately. `test` compiles and
+runs before plus an optional after stage using your mock result; it never contacts the upstream.
+`deploy` saves `--file` and optional `--config` before creating an immutable revision. Omit `--shadow`
+to deploy active. Rollback and deactivate default to active and accept `--shadow` for the shadow
+pointer. Hook log payloads appear only when the service’s payload-capture setting is enabled; timing,
+outcome, revision, request correlation, and the shadow changed/unchanged signal remain available
+either way. Captured messages, structured data, and errors require a full-control key. Use
+`hooks logs --json` for the full-fidelity retained record. Compiler errors include hook.ts line and
+column diagnostics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayrun/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Set up MCP clients, execute tools, and manage Rayrun from the command line",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/client": "2.0.0",
-    "@rayrun/sdk": "^0.4.0",
+    "@rayrun/sdk": "^0.5.0",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.8.0"
   },

package/src/management.js

@@ -1,5 +1,6 @@
 /* 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:
@@ -11,6 +12,12 @@ export const managementUsage = `Management:
   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
@@ -22,6 +29,7 @@ const managementCommands = new Set([
   'clients',
   'connect',
   'connections',
+  'hooks',
   'policy',
   'tools',
 ]);
@@ -30,12 +38,18 @@ 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) => {
@@ -50,6 +64,11 @@ const parseCommandArguments = (arguments_, allowedOptions) => {
       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) {
@@ -150,6 +169,18 @@ 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];
@@ -345,6 +376,141 @@ const runCommand = async ({ arguments_, client, output }) => {
     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);
 };
 
@@ -372,6 +538,15 @@ export const runManagementCommand = async (
   } 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 });
+    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 },
+    );
   }
 };