@rayrun/cli 0.4.0 → 0.5.0

package/src/management.js

@@ -1,20 +1,64 @@
+import {
+  parseSecretBindings,
+  readDeploymentDirectory,
+  readDeploymentProjectState,
+  writeDeploymentProjectState,
+} from './deployments.js';
+import { readSkillDirectory, writeSkillDirectory } from './skills.js';
 /* eslint-disable node/no-process-env -- management intentionally reads the invoking user's Rayrun environment */
 import { Rayrun, RayrunApiError } from '@rayrun/sdk';
+import { diffLines } from 'diff';
+import { createHash } from 'node:crypto';
 import { readFile, writeFile } from 'node:fs/promises';
 import { stripVTControlCharacters } from 'node:util';
 
 export const managementUsage = `Management:
+  rayrun deploy [directory] [--connection <uid>] [--name <name>] [--secret <NAME=secret-uid> ...] [--wait] [--json]
+  rayrun deployments list [--connection <uid>] [--limit <1-100>] [--json]
+  rayrun deployments get <build-uid> [--json]
+  rayrun deployments logs <build-uid> [--json]
+  rayrun deployments releases <connection-uid> [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun deployments rollback <connection-uid> <release-uid> [--wait] [--json]
   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 connections history <connection-uid> [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun connections diff <connection-uid> <version-uid> [--json]
+  rayrun connections restore <connection-uid> <version-uid> [--reason <note>] [--json]
+  rayrun access-profiles list [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun access-profiles history <profile-uid> [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun access-profiles diff <profile-uid> <version-uid> [--json]
+  rayrun access-profiles restore <profile-uid> <version-uid> [--reason <note>] [--confirm-risk] [--json]
+  rayrun webhooks list [--json]
+  rayrun webhooks update <webhook-uid> --config <json> [--reason <note>] [--json]
+  rayrun webhooks history <webhook-uid> [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun webhooks diff <webhook-uid> <version-uid> [--json]
+  rayrun webhooks restore <webhook-uid> <version-uid> [--reason <note>] [--json]
+  rayrun skills validate <directory> [--json]
+  rayrun skills push <directory> [--publish] [--confirm-risk] [--mode <both|code|direct>] [--profiles <uid,uid>|--all-clients] [--reason <note>] [--json]
+  rayrun skills list [--json]
+  rayrun skills show <skill-uid> [--json]
+  rayrun skills history <skill-uid> [--json]
+  rayrun skills diff <skill-uid> <version-uid> [--json]
+  rayrun skills pull <skill-uid> --output <new-directory> [--version <version-uid>] [--json]
+  rayrun skills publish <skill-uid> [--confirm-risk] [--mode <both|code|direct>] [--profiles <uid,uid>|--all-clients] [--reason <note>] [--json]
+  rayrun skills audience <skill-uid> [--mode <both|code|direct>] [--profiles <uid,uid>|--all-clients] [--json]
+  rayrun skills enable|disable|archive <skill-uid> [--json]
+  rayrun skills restore <skill-uid> <version-uid> [--reason <note>] [--json]
+  rayrun skills delete <skill-uid> --confirm-name <name> [--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 save <connection-uid> <tool-uid> [--file <file>] [--config <json>] [--reason <note>] [--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 deploy <connection-uid> <tool-uid> [--file <file>] [--config <json>] [--reason <note>] [--shadow] [--json]
+  rayrun hooks history <connection-uid> <tool-uid> [--limit <1-100>] [--cursor <cursor>] [--json]
+  rayrun hooks diff <connection-uid> <tool-uid> <version-uid> [--json]
+  rayrun hooks restore <connection-uid> <tool-uid> <version-uid> [--reason <note>] [--json]
+  rayrun hooks reset <connection-uid> <tool-uid> --confirm <hook-uid>@<version> --reason <note>
   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]
@@ -24,14 +68,19 @@ Environment:
   RAYRUN_API_URL   Optional API origin (defaults to https://ray.run)`;
 
 const managementCommands = new Set([
+  'access-profiles',
   'activity',
   'approvals',
   'clients',
   'connect',
   'connections',
+  'deploy',
+  'deployments',
   'hooks',
   'policy',
+  'skills',
   'tools',
+  'webhooks',
 ]);
 
 export const isManagementCommand = (command) => managementCommands.has(command);
@@ -40,20 +89,27 @@ const optionNames = new Map([
   ['--base-url', 'baseUrl'],
   ['--arguments', 'argumentsJson'],
   ['--config', 'configJson'],
+  ['--confirm', 'confirmationHookUid'],
   ['--connection', 'connectionUid'],
+  ['--confirm-name', 'confirmationName'],
   ['--cursor', 'cursor'],
   ['--limit', 'limit'],
   ['--file', 'filePath'],
   ['--mock-result', 'mockResultJson'],
   ['--name', 'name'],
+  ['--mode', 'mode'],
+  ['--profiles', 'profiles'],
   ['--query', 'query'],
+  ['--reason', 'reason'],
   ['--output', 'outputPath'],
   ['--transport', 'transport'],
+  ['--secret', 'secret'],
+  ['--version', 'versionUid'],
   ['--types-output', 'typesOutputPath'],
 ]);
 
 const parseCommandArguments = (arguments_, allowedOptions) => {
-  const options = { json: false };
+  const options = { json: false, secrets: [] };
   const positional = [];
 
   for (let index = 0; index < arguments_.length; index += 1) {
@@ -69,14 +125,38 @@ const parseCommandArguments = (arguments_, allowedOptions) => {
       options.shadow = true;
       continue;
     }
+    if (argument === '--confirm-risk') {
+      if (!allowedOptions.has('confirmRisk')) throw new Error(`Unknown option: ${argument}`);
+      options.confirmRisk = true;
+      continue;
+    }
+    if (argument === '--publish') {
+      if (!allowedOptions.has('publish')) throw new Error(`Unknown option: ${argument}`);
+      options.publish = true;
+      continue;
+    }
+    if (argument === '--wait') {
+      if (!allowedOptions.has('wait')) throw new Error(`Unknown option: ${argument}`);
+      options.wait = true;
+      continue;
+    }
+    if (argument === '--all-clients') {
+      if (!allowedOptions.has('allClients')) throw new Error(`Unknown option: ${argument}`);
+      options.allClients = 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;
+      if (optionName === 'secret') options.secrets.push(value);
+      else {
+        if (options[optionName] !== undefined)
+          throw new Error(`${argument} can only be used once.`);
+        options[optionName] = value;
+      }
       index += 1;
       continue;
     }
@@ -123,12 +203,31 @@ const formatCell = (value) => {
   if (typeof value === 'boolean') return value ? 'yes' : 'no';
   const sanitized = stripVTControlCharacters(String(value))
     .replaceAll(/\p{Cc}+/gu, ' ')
+    .replaceAll(
+      /\p{Bidi_Control}/gu,
+      (character) => `\\u{${character.codePointAt(0).toString(16).toUpperCase()}}`,
+    )
     .replaceAll(/\s+/gu, ' ')
     .trim();
 
   return sanitized || '-';
 };
 
+const formatTerminalText = (value) => {
+  return stripVTControlCharacters(String(value))
+    .replaceAll(/\r\n?/gu, '\n')
+    .split('\n')
+    .map((line) =>
+      line
+        .replaceAll(/\p{Cc}+/gu, ' ')
+        .replaceAll(
+          /\p{Bidi_Control}/gu,
+          (character) => `\\u{${character.codePointAt(0).toString(16).toUpperCase()}}`,
+        ),
+    )
+    .join('\n');
+};
+
 export const renderTable = (items, columns) => {
   if (items.length === 0) return 'No results.\n';
 
@@ -181,10 +280,491 @@ const parseJsonOption = (value, option, fallback) => {
 
 const hookMode = (options) => (options.shadow ? 'shadow' : 'active');
 
+const deploymentFinished = (deployment) =>
+  ['cancelled', 'failed'].includes(deployment.build.status) ||
+  (deployment.release &&
+    ['active', 'cancelled', 'failed', 'superseded'].includes(deployment.release.status));
+
+const waitForDeployment = async (client, { buildUid, connectionUid, releaseUid }) => {
+  const deadline = Date.now() + 60 * 60 * 1_000;
+  while (Date.now() < deadline) {
+    const deployment = await client.deployments.get(buildUid);
+    if (releaseUid) {
+      const exactRelease = await client.deployments.getRelease(connectionUid, releaseUid);
+      const exactDeployment = { ...deployment, release: exactRelease };
+      if (deploymentFinished(exactDeployment)) return exactDeployment;
+    } else if (deploymentFinished(deployment)) {
+      return deployment;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2_000));
+  }
+  throw new Error(
+    'Deployment is still running after 60 minutes. Inspect it with rayrun deployments get.',
+  );
+};
+
+const writeDeployment = ({ deployment, options, output }) => {
+  if (options.json) {
+    writeValue(output, deployment);
+    return;
+  }
+  const status = deployment.release?.status ?? deployment.build.status;
+  const toolSummary = deployment.release?.toolNames.map(formatCell).join(', ');
+  output.write(
+    `${formatCell(deployment.connection.displayName)}: ${formatCell(status)} (build ${formatCell(deployment.build.uid)}, source r${String(deployment.source.revision)})${toolSummary ? ` — ${toolSummary}` : ''}\n`,
+  );
+};
+
+const renderLineDiff = (before, after, beforeLabel, afterLabel) => {
+  const parts = diffLines(before, after, { timeout: 75 });
+  if (!parts) {
+    return `--- ${beforeLabel}\n+++ ${afterLabel}\nDiff exceeded the 75 ms safety limit. Use --json to inspect both versions.\n`;
+  }
+
+  const lines = parts
+    .flatMap((part) => {
+      const prefix = part.added ? '+' : part.removed ? '-' : ' ';
+      const partLines = stripVTControlCharacters(part.value)
+        .split('\n')
+        .map((line) =>
+          line
+            .replaceAll(/\p{Cc}+/gu, ' ')
+            .replaceAll(
+              /\p{Bidi_Control}/gu,
+              (character) => `\\u{${character.codePointAt(0).toString(16).toUpperCase()}}`,
+            ),
+        );
+
+      if (partLines.at(-1) === '') partLines.pop();
+
+      return partLines.map((line) => `${prefix}${line}`);
+    })
+    .join('\n');
+
+  return `--- ${beforeLabel}\n+++ ${afterLabel}\n${lines}\n`;
+};
+
+const skillFileSummary = (files) => {
+  return files.map((file) => {
+    const bytes = Buffer.from(file.contentBase64, 'base64');
+    return {
+      digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
+      path: file.path,
+      size: bytes.byteLength,
+    };
+  });
+};
+
+const skillAudience = (options, fallback) => {
+  if (options.allClients && options.profiles !== undefined) {
+    throw new Error('Use either --profiles or --all-clients, not both.');
+  }
+  const deliveryMode = options.mode ?? fallback?.deliveryMode ?? 'both';
+  if (!['both', 'code', 'direct'].includes(deliveryMode)) {
+    throw new Error('--mode must be both, code, or direct.');
+  }
+  let profileUids;
+  if (options.allClients) {
+    profileUids = [];
+  } else if (options.profiles !== undefined) {
+    profileUids = options.profiles
+      .split(',')
+      .map((uid) => uid.trim())
+      .filter(Boolean);
+    if (profileUids.length === 0) {
+      throw new Error('--profiles requires at least one profile UID.');
+    }
+  } else if (fallback) {
+    profileUids = fallback.profileUids;
+  } else {
+    throw new Error('Choose an audience with --profiles <uid,uid> or --all-clients.');
+  }
+  return {
+    deliveryMode,
+    profileUids,
+  };
+};
+
 const runCommand = async ({ arguments_, client, output }) => {
   const command = arguments_[0];
   const action = arguments_[1];
 
+  if (command === 'deploy') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(1),
+      new Set(['connectionUid', 'json', 'name', 'secret', 'wait']),
+    );
+    requireShape(positional.length <= 1);
+    const directory = positional[0] ?? '.';
+    const state = options.connectionUid ? null : await readDeploymentProjectState(directory);
+    const connectionUid = options.connectionUid ?? state?.connectionUid;
+    if (connectionUid && options.name) {
+      throw new Error('--name is only available when creating a source deployment.');
+    }
+    const files = await readDeploymentDirectory(directory);
+    await client.deployments.validate(files);
+    const created = await client.deployments.create({
+      connectionUid,
+      displayName: options.name,
+      files,
+      secretBindings: parseSecretBindings(options.secrets),
+    });
+    await writeDeploymentProjectState(directory, created.connectionUid);
+    if (options.wait) {
+      const deployment = await waitForDeployment(client, created);
+      writeDeployment({ deployment, options, output });
+      if (
+        ['cancelled', 'failed'].includes(deployment.build.status) ||
+        (deployment.release &&
+          ['cancelled', 'failed', 'superseded'].includes(deployment.release.status))
+      ) {
+        throw new Error(
+          `Deployment ${created.buildUid} failed. Run rayrun deployments logs ${created.buildUid}.`,
+        );
+      }
+    } else if (options.json) writeValue(output, created);
+    else {
+      output.write(
+        created.unchanged
+          ? `Already active as build ${created.buildUid}.\n`
+          : `Queued build ${created.buildUid}. Wait with: rayrun deployments get ${created.buildUid}\n`,
+      );
+    }
+    return;
+  }
+
+  if (command === 'deployments' && action === 'list') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['connectionUid', 'json', 'limit']),
+    );
+    requireShape(positional.length === 0);
+    const response = await client.deployments.list({
+      connectionUid: options.connectionUid,
+      limit: options.limit,
+    });
+    if (options.json) writeValue(output, response);
+    else {
+      output.write(
+        renderTable(response.items, [
+          { label: 'BUILD', value: (item) => item.build.uid },
+          { label: 'SERVICE', value: (item) => item.connection.displayName },
+          { label: 'SOURCE', value: (item) => `r${String(item.source.revision)}` },
+          { label: 'STATUS', value: (item) => item.release?.status ?? item.build.status },
+          { label: 'CREATED', value: (item) => item.build.createdAt },
+        ]),
+      );
+    }
+    return;
+  }
+
+  if (command === 'deployments' && action === 'get') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 1);
+    writeDeployment({ deployment: await client.deployments.get(positional[0]), options, output });
+    return;
+  }
+
+  if (command === 'deployments' && action === 'logs') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 1);
+    const buildLog = await client.deployments.getLog(positional[0]);
+    if (options.json) writeValue(output, buildLog);
+    else
+      output.write(
+        `${buildLog.truncated ? '[older output truncated]\n' : ''}${formatTerminalText(buildLog.text)}\n`,
+      );
+    return;
+  }
+
+  if (command === 'deployments' && action === 'releases') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 1);
+    const response = await client.deployments.listReleases(positional[0], pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'RELEASE', value: (item) => item.uid },
+        { label: 'NUMBER', value: (item) => item.number },
+        { label: 'SOURCE', value: (item) => `r${String(item.sourceRevision)}` },
+        { label: 'STATUS', value: (item) => item.status },
+        { label: 'ACTIVATED', value: (item) => item.activatedAt },
+      ],
+      options,
+      output,
+      page: response,
+    });
+    return;
+  }
+
+  if (command === 'deployments' && action === 'rollback') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'wait']),
+    );
+    requireShape(positional.length === 2);
+    const created = await client.deployments.rollback(positional[0], positional[1]);
+    if (options.wait) {
+      const deadline = Date.now() + 20 * 60 * 1_000;
+      let release;
+      while (Date.now() < deadline) {
+        release = await client.deployments.getRelease(positional[0], created.releaseUid);
+        if (['active', 'cancelled', 'failed', 'superseded'].includes(release.status)) break;
+        await new Promise((resolve) => setTimeout(resolve, 2_000));
+      }
+      if (!release || !['active', 'cancelled', 'failed', 'superseded'].includes(release.status)) {
+        throw new Error('Rollback is still running after 20 minutes.');
+      }
+      if (options.json) writeValue(output, release);
+      else output.write(`Release ${release.uid}: ${release.status}.\n`);
+      if (release.status !== 'active') throw new Error(`Rollback ${release.uid} failed.`);
+    } else if (options.json) writeValue(output, created);
+    else output.write(`Queued rollback release ${created.releaseUid}.\n`);
+    return;
+  }
+
+  if (command === 'skills' && action === 'validate') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 1);
+    const result = await client.skills.validate(await readSkillDirectory(positional[0]));
+    if (options.json) writeValue(output, result);
+    else {
+      output.write(
+        `Valid ${result.name}: ${String(result.fileCount)} files, ${String(result.byteCount)} bytes${result.riskFlags.length ? `; review ${result.riskFlags.join(', ')}` : ''}.\n`,
+      );
+    }
+    return;
+  }
+
+  if (command === 'skills' && action === 'push') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['allClients', 'confirmRisk', 'json', 'mode', 'profiles', 'publish', 'reason']),
+    );
+    requireShape(positional.length === 1);
+    const files = await readSkillDirectory(positional[0]);
+    const validation = await client.skills.validate(files);
+    const listed = await client.skills.list();
+    const existing = listed.items.find((item) => item.name === validation.name);
+    const audience = options.publish
+      ? skillAudience(
+          options,
+          existing
+            ? {
+                deliveryMode: existing.deliveryMode,
+                profileUids: existing.profiles.map((profile) => profile.uid),
+              }
+            : undefined,
+        )
+      : undefined;
+    let result = existing
+      ? await client.skills.saveDraft(existing.uid, {
+          changeReason: options.reason,
+          expectedVersion: existing.configurationVersion,
+          files,
+          source: 'cli',
+        })
+      : await client.skills.create({ changeReason: options.reason, files, source: 'cli' });
+    if (options.publish) {
+      result = await client.skills.publish(result.skillUid, {
+        ...audience,
+        changeReason: options.reason,
+        expectedVersion: result.configurationVersion,
+        riskConfirmed: options.confirmRisk,
+      });
+    }
+    if (options.json) writeValue(output, result);
+    else {
+      output.write(
+        `${options.publish ? 'Published' : result.unchanged ? 'Unchanged' : 'Saved'} ${validation.name} (${result.skillUid}) at configuration v${String(result.configurationVersion)}.\n`,
+      );
+    }
+    return;
+  }
+
+  if (command === 'skills' && action === 'list') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 0);
+    const result = await client.skills.list();
+    if (options.json) writeValue(output, result);
+    else {
+      output.write(
+        renderTable(result.items, [
+          { label: 'UID', value: (item) => item.uid },
+          { label: 'NAME', value: (item) => item.name },
+          { label: 'STATE', value: (item) => item.state },
+          { label: 'REVISION', value: (item) => item.publishedRevisionNumber },
+          { label: 'MODE', value: (item) => item.deliveryMode },
+          { label: 'FETCHES', value: (item) => item.fetchCount },
+        ]),
+      );
+    }
+    return;
+  }
+
+  if (command === 'skills' && ['history', 'show'].includes(action)) {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 1);
+    const detail = await client.skills.get(positional[0]);
+    if (options.json || action === 'show') writeValue(output, detail);
+    else {
+      output.write(
+        renderTable(detail.versions, [
+          { label: 'REVISION', value: (item) => item.revisionNumber },
+          { label: 'UID', value: (item) => item.uid },
+          { label: 'WHEN', value: (item) => item.createdAt },
+          { label: 'ACTOR', value: (item) => item.actorName },
+          { label: 'DRAFT', value: (item) => item.isCurrentDraft },
+          { label: 'PUBLISHED', value: (item) => item.isPublished },
+          { label: 'NOTE', value: (item) => item.changeReason },
+        ]),
+      );
+    }
+    return;
+  }
+
+  if (command === 'skills' && action === 'diff') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 2);
+    const [draft, version] = await Promise.all([
+      client.skills.export(positional[0]),
+      client.skills.exportVersion(positional[0], positional[1]),
+    ]);
+    const comparison = {
+      draft: skillFileSummary(draft.files),
+      version: skillFileSummary(version.files),
+    };
+    if (options.json) writeValue(output, comparison);
+    else {
+      output.write(
+        renderLineDiff(
+          `${JSON.stringify(comparison.version, null, 2)}\n`,
+          `${JSON.stringify(comparison.draft, null, 2)}\n`,
+          positional[1],
+          'current draft',
+        ),
+      );
+    }
+    return;
+  }
+
+  if (command === 'skills' && action === 'pull') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'outputPath', 'versionUid']),
+    );
+    requireShape(positional.length === 1 && typeof options.outputPath === 'string');
+    const result = options.versionUid
+      ? await client.skills.exportVersion(positional[0], options.versionUid)
+      : await client.skills.export(positional[0]);
+    await writeSkillDirectory(options.outputPath, result.files);
+    if (options.json)
+      writeValue(output, { fileCount: result.files.length, output: options.outputPath });
+    else output.write(`Wrote ${String(result.files.length)} files to ${options.outputPath}.\n`);
+    return;
+  }
+
+  if (command === 'skills' && action === 'publish') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['allClients', 'confirmRisk', 'json', 'mode', 'profiles', 'reason']),
+    );
+    requireShape(positional.length === 1);
+    const detail = await client.skills.get(positional[0]);
+    const result = await client.skills.publish(positional[0], {
+      ...skillAudience(options, {
+        deliveryMode: detail.skill.deliveryMode,
+        profileUids: detail.skill.profiles.map((profile) => profile.uid),
+      }),
+      changeReason: options.reason,
+      expectedVersion: detail.skill.configurationVersion,
+      riskConfirmed: options.confirmRisk,
+    });
+    if (options.json) writeValue(output, result);
+    else
+      output.write(
+        `Published ${detail.skill.name} at configuration v${String(result.configurationVersion)}.\n`,
+      );
+    return;
+  }
+
+  if (command === 'skills' && action === 'audience') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['allClients', 'json', 'mode', 'profiles']),
+    );
+    requireShape(positional.length === 1);
+    const detail = await client.skills.get(positional[0]);
+    const result = await client.skills.updateAudience(positional[0], {
+      ...skillAudience(options, {
+        deliveryMode: detail.skill.deliveryMode,
+        profileUids: detail.skill.profiles.map((profile) => profile.uid),
+      }),
+      expectedVersion: detail.skill.configurationVersion,
+    });
+    if (options.json) writeValue(output, result);
+    else {
+      output.write(
+        `${result.unchanged ? 'Kept' : 'Updated'} audience for ${detail.skill.name} at configuration v${String(result.configurationVersion)}.\n`,
+      );
+    }
+    return;
+  }
+
+  if (command === 'skills' && ['archive', 'disable', 'enable'].includes(action)) {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 1);
+    const detail = await client.skills.get(positional[0]);
+    const result =
+      action === 'archive'
+        ? await client.skills.archive(positional[0], detail.skill.configurationVersion)
+        : await client.skills.setEnabled(
+            positional[0],
+            action === 'enable',
+            detail.skill.configurationVersion,
+          );
+    if (options.json) writeValue(output, result);
+    else output.write(`${action[0].toUpperCase()}${action.slice(1)}d ${detail.skill.name}.\n`);
+    return;
+  }
+
+  if (command === 'skills' && action === 'restore') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'reason']),
+    );
+    requireShape(positional.length === 2);
+    const detail = await client.skills.get(positional[0]);
+    const result = await client.skills.restoreVersion(positional[0], positional[1], {
+      changeReason: options.reason,
+      expectedVersion: detail.skill.configurationVersion,
+    });
+    if (options.json) writeValue(output, result);
+    else output.write(`Restored ${positional[1]} as a new draft.\n`);
+    return;
+  }
+
+  if (command === 'skills' && action === 'delete') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['confirmationName', 'json']),
+    );
+    requireShape(positional.length === 1 && typeof options.confirmationName === 'string');
+    const detail = await client.skills.get(positional[0]);
+    const result = await client.skills.delete(positional[0], {
+      confirmationName: options.confirmationName,
+      expectedVersion: detail.skill.configurationVersion,
+    });
+    if (options.json) writeValue(output, result);
+    else
+      output.write(
+        `Permanently deleted content for ${detail.skill.name}; its name remains reserved.\n`,
+      );
+    return;
+  }
+
   if (command === 'connect' && action === 'mcp') {
     const { options, positional } = parseCommandArguments(
       arguments_.slice(2),
@@ -244,6 +824,306 @@ const runCommand = async ({ arguments_, client, output }) => {
     return;
   }
 
+  if (command === 'connections' && action === 'history') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 1);
+    const page = await client.connections.listConfigurationVersions(
+      positional[0],
+      pageQuery(options),
+    );
+    writePage({
+      columns: [
+        { label: 'VERSION', value: (item) => item.revisionNumber },
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'WHEN', value: (item) => item.createdAt },
+        { label: 'ACTOR', value: (item) => `${item.actor.name} (${item.actor.type})` },
+        { label: 'CHANGE', value: (item) => item.changeType },
+        { label: 'NOTE', value: (item) => item.changeReason },
+        { label: 'CURRENT', value: (item) => item.isCurrent },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'connections' && action === 'diff') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 2);
+    const result = await client.connections.getConfigurationVersion(positional[0], positional[1]);
+    if (options.json) {
+      writeValue(output, result);
+      return;
+    }
+    const previousLabel = result.version.previous
+      ? `configuration v${String(result.version.previous.revisionNumber)}`
+      : 'empty configuration';
+    output.write(
+      renderLineDiff(
+        `${JSON.stringify(result.version.previous?.snapshot ?? {}, null, 2)}\n`,
+        `${JSON.stringify(result.version.snapshot, null, 2)}\n`,
+        previousLabel,
+        `configuration v${String(result.version.revisionNumber)}`,
+      ),
+    );
+    return;
+  }
+
+  if (command === 'connections' && action === 'restore') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'reason']),
+    );
+    requireShape(positional.length === 2);
+    const history = await client.connections.listConfigurationVersions(positional[0], { limit: 1 });
+    const current = history.items[0];
+    if (!current?.isCurrent) {
+      throw new Error('The current connection configuration could not be read.');
+    }
+    const result = await client.connections.restoreConfigurationVersion(
+      positional[0],
+      positional[1],
+      { expectedVersion: current.revisionNumber, reason: options.reason },
+    );
+    if (options.json) writeValue(output, result);
+    else
+      output.write(
+        `Restored ${positional[1]} as connection configuration v${String(result.configurationVersion)} (${result.versionUid}).\n`,
+      );
+    return;
+  }
+
+  if (command === 'access-profiles' && action === 'list') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 0);
+    const page = await client.accessProfiles.list(pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'NAME', value: (item) => item.name },
+        { label: 'POLICY', value: (item) => item.toolAccessMode },
+        { label: 'VERSION', value: (item) => item.toolPolicyVersion },
+        { label: 'CLIENTS', value: (item) => item.assignedClientCount },
+        { label: 'SKILLS', value: (item) => item.assignedSkillCount },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'access-profiles' && action === 'history') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 1);
+    const page = await client.accessProfiles.listConfigurationVersions(
+      positional[0],
+      pageQuery(options),
+    );
+    writePage({
+      columns: [
+        { label: 'VERSION', value: (item) => item.revisionNumber },
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'WHEN', value: (item) => item.createdAt },
+        { label: 'ACTOR', value: (item) => `${item.actor.name} (${item.actor.type})` },
+        { label: 'CHANGE', value: (item) => item.changeType },
+        { label: 'NOTE', value: (item) => item.changeReason },
+        { label: 'CURRENT', value: (item) => item.isCurrent },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'access-profiles' && action === 'diff') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 2);
+    const result = await client.accessProfiles.getConfigurationVersion(
+      positional[0],
+      positional[1],
+    );
+    if (options.json) {
+      writeValue(output, result);
+      return;
+    }
+    const previousLabel = result.version.previous
+      ? `profile v${String(result.version.previous.revisionNumber)}`
+      : 'empty profile';
+    output.write(
+      renderLineDiff(
+        `${JSON.stringify(result.version.previous?.snapshot ?? {}, null, 2)}\n`,
+        `${JSON.stringify(result.version.snapshot, null, 2)}\n`,
+        previousLabel,
+        `profile v${String(result.version.revisionNumber)}`,
+      ),
+    );
+    return;
+  }
+
+  if (command === 'access-profiles' && action === 'restore') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['confirmRisk', 'json', 'reason']),
+    );
+    requireShape(positional.length === 2);
+    const history = await client.accessProfiles.listConfigurationVersions(positional[0], {
+      limit: 1,
+    });
+    const current = history.items[0];
+    if (!current?.isCurrent) {
+      throw new Error('The current access-profile configuration could not be read.');
+    }
+    const result = await client.accessProfiles.restoreConfigurationVersion(
+      positional[0],
+      positional[1],
+      {
+        expectedVersion: current.revisionNumber,
+        reason: options.reason,
+        riskConfirmed: options.confirmRisk === true,
+      },
+    );
+    if (options.json) writeValue(output, result);
+    else
+      output.write(
+        `Restored ${positional[1]} as access-profile configuration v${String(result.toolPolicyVersion)} (${result.versionUid}).\n`,
+      );
+    return;
+  }
+
+  if (command === 'webhooks' && action === 'list') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 0);
+    const result = await client.webhooks.list();
+    if (options.json) {
+      writeValue(output, result);
+      return;
+    }
+    output.write(
+      renderTable(result.items, [
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'DESCRIPTION', value: (item) => item.description },
+        { label: 'DESTINATION', value: (item) => item.url },
+        { label: 'ENABLED', value: (item) => item.enabled },
+        { label: 'VERSION', value: (item) => item.configurationVersion },
+        { label: 'HEALTH', value: (item) => item.health },
+      ]),
+    );
+    return;
+  }
+
+  if (command === 'webhooks' && action === 'update') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['configJson', 'json', 'reason']),
+    );
+    requireShape(positional.length === 1 && options.configJson !== undefined);
+    const configuration = parseJsonOption(options.configJson, '--config');
+    if (!configuration || typeof configuration !== 'object' || Array.isArray(configuration)) {
+      throw new Error('--config must be a JSON object.');
+    }
+    const listed = await client.webhooks.list();
+    const current = listed.items.find((webhook) => webhook.uid === positional[0]);
+    if (!current) {
+      throw new Error(`Webhook ${positional[0]} was not found.`);
+    }
+    const result = await client.webhooks.update(positional[0], {
+      ...configuration,
+      expectedVersion: current.configurationVersion,
+      reason: options.reason,
+    });
+    if (options.json) writeValue(output, result);
+    else if (result.unchanged)
+      output.write(
+        `No changes; webhook configuration v${String(result.configurationVersion)} is current.\n`,
+      );
+    else
+      output.write(
+        `Saved webhook configuration v${String(result.configurationVersion)} (${result.versionUid}).\n`,
+      );
+    return;
+  }
+
+  if (command === 'webhooks' && action === 'history') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 1);
+    const page = await client.webhooks.listConfigurationVersions(positional[0], pageQuery(options));
+    writePage({
+      columns: [
+        { label: 'VERSION', value: (item) => item.revisionNumber },
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'WHEN', value: (item) => item.createdAt },
+        { label: 'ACTOR', value: (item) => `${item.actor.name} (${item.actor.type})` },
+        { label: 'CHANGE', value: (item) => item.changeType },
+        { label: 'NOTE', value: (item) => item.changeReason },
+        { label: 'CURRENT', value: (item) => item.isCurrent },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'webhooks' && action === 'diff') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 2);
+    const result = await client.webhooks.getConfigurationVersion(positional[0], positional[1]);
+    if (options.json) {
+      writeValue(output, result);
+      return;
+    }
+    const previousLabel = result.version.previous
+      ? `webhook v${String(result.version.previous.revisionNumber)}`
+      : 'empty webhook configuration';
+    output.write(
+      renderLineDiff(
+        `${JSON.stringify(result.version.previous?.snapshot ?? {}, null, 2)}\n`,
+        `${JSON.stringify(result.version.snapshot, null, 2)}\n`,
+        previousLabel,
+        `webhook v${String(result.version.revisionNumber)}`,
+      ),
+    );
+    return;
+  }
+
+  if (command === 'webhooks' && action === 'restore') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'reason']),
+    );
+    requireShape(positional.length === 2);
+    const history = await client.webhooks.listConfigurationVersions(positional[0], { limit: 1 });
+    const current = history.items[0];
+    if (!current?.isCurrent) {
+      throw new Error('The current webhook configuration could not be read.');
+    }
+    const result = await client.webhooks.restoreConfigurationVersion(positional[0], positional[1], {
+      expectedVersion: current.revisionNumber,
+      reason: options.reason,
+    });
+    if (options.json) writeValue(output, result);
+    else
+      output.write(
+        `Restored ${positional[1]} as webhook configuration v${String(result.configurationVersion)} (${result.versionUid}).\n`,
+      );
+    return;
+  }
+
   if (command === 'clients' && action === 'list') {
     const { options, positional } = parseCommandArguments(
       arguments_.slice(2),
@@ -413,10 +1293,142 @@ const runCommand = async ({ arguments_, client, output }) => {
     return;
   }
 
+  if (command === 'hooks' && action === 'save') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['configJson', 'filePath', 'json', 'reason']),
+    );
+    requireShape(positional.length === 2);
+    const { hook } = await client.hooks.get(positional[0], positional[1]);
+    const source = options.filePath ? await readFile(options.filePath, 'utf8') : hook.draftSource;
+    const result = await client.hooks.saveDraft(positional[0], positional[1], {
+      config: parseJsonOption(options.configJson, '--config', hook.draftConfig),
+      expectedVersion: hook.version,
+      reason: options.reason,
+      source,
+    });
+
+    if (options.json) writeValue(output, result);
+    else if (result.draftVersion.unchanged)
+      output.write(
+        `No changes; draft v${String(result.draftVersion.revisionNumber)} is current.\n`,
+      );
+    else
+      output.write(
+        `Saved draft v${String(result.draftVersion.revisionNumber)} (${result.draftVersion.uid}).\n`,
+      );
+    return;
+  }
+
+  if (command === 'hooks' && action === 'history') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['cursor', 'json', 'limit']),
+    );
+    requireShape(positional.length === 2);
+    const page = await client.hooks.listDraftVersions(
+      positional[0],
+      positional[1],
+      pageQuery(options),
+    );
+    writePage({
+      columns: [
+        { label: 'VERSION', value: (item) => item.revisionNumber },
+        { label: 'UID', value: (item) => item.uid },
+        { label: 'WHEN', value: (item) => item.createdAt },
+        { label: 'ACTOR', value: (item) => `${item.actor.name} (${item.actor.type})` },
+        { label: 'CHANGE', value: (item) => item.changeType },
+        { label: 'NOTE', value: (item) => item.changeReason },
+        { label: 'CURRENT', value: (item) => item.isCurrent },
+      ],
+      options,
+      output,
+      page,
+    });
+    return;
+  }
+
+  if (command === 'hooks' && action === 'diff') {
+    const { options, positional } = parseCommandArguments(arguments_.slice(2), new Set(['json']));
+    requireShape(positional.length === 3);
+    const result = await client.hooks.getDraftVersion(positional[0], positional[1], positional[2]);
+
+    if (options.json) {
+      writeValue(output, result);
+      return;
+    }
+    const previousLabel = result.version.previous
+      ? `draft v${String(result.version.previous.revisionNumber)}`
+      : 'empty draft';
+    const currentLabel = `draft v${String(result.version.revisionNumber)}`;
+    output.write(
+      renderLineDiff(
+        result.version.previous?.source ?? '',
+        result.version.source,
+        `${previousLabel} source`,
+        `${currentLabel} source`,
+      ),
+    );
+    output.write(
+      renderLineDiff(
+        `${JSON.stringify(result.version.previous?.config ?? {}, null, 2)}\n`,
+        `${JSON.stringify(result.version.config, null, 2)}\n`,
+        `${previousLabel} config`,
+        `${currentLabel} config`,
+      ),
+    );
+    return;
+  }
+
+  if (command === 'hooks' && action === 'restore') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['json', 'reason']),
+    );
+    requireShape(positional.length === 3);
+    const { hook } = await client.hooks.get(positional[0], positional[1]);
+    const result = await client.hooks.restoreDraft(positional[0], positional[1], positional[2], {
+      expectedVersion: hook.version,
+      reason: options.reason,
+    });
+
+    if (options.json) writeValue(output, result);
+    else
+      output.write(
+        `Restored ${positional[2]} as draft v${String(result.draftVersion.revisionNumber)} (${result.draftVersion.uid}).\n`,
+      );
+    return;
+  }
+
+  if (command === 'hooks' && action === 'reset') {
+    const { options, positional } = parseCommandArguments(
+      arguments_.slice(2),
+      new Set(['confirmationHookUid', 'reason']),
+    );
+    requireShape(
+      positional.length === 2 &&
+        typeof options.confirmationHookUid === 'string' &&
+        typeof options.reason === 'string',
+    );
+    const separatorIndex = options.confirmationHookUid.lastIndexOf('@');
+    const hookUid = options.confirmationHookUid.slice(0, separatorIndex);
+    const expectedVersion = Number(options.confirmationHookUid.slice(separatorIndex + 1));
+    if (separatorIndex <= 0 || !Number.isInteger(expectedVersion) || expectedVersion <= 0) {
+      throw new Error('--confirm must be the current hook UID and version: <hook-uid>@<version>.');
+    }
+    await client.hooks.reset(positional[0], positional[1], {
+      confirmationHookUid: hookUid,
+      expectedVersion,
+      reason: options.reason,
+    });
+    output.write(`Permanently reset hook ${hookUid} at version ${String(expectedVersion)}.\n`);
+    return;
+  }
+
   if (command === 'hooks' && action === 'deploy') {
     const { options, positional } = parseCommandArguments(
       arguments_.slice(2),
-      new Set(['configJson', 'filePath', 'json', 'shadow']),
+      new Set(['configJson', 'filePath', 'json', 'reason', 'shadow']),
     );
     requireShape(positional.length === 2);
     const connectionUid = positional[0];
@@ -428,6 +1440,7 @@ const runCommand = async ({ arguments_, client, output }) => {
       const saved = await client.hooks.saveDraft(connectionUid, toolUid, {
         config: parseJsonOption(options.configJson, '--config', hook.draftConfig),
         expectedVersion: hook.version,
+        reason: options.reason,
         source,
       });
       hook = saved.hook;
@@ -538,10 +1551,11 @@ export const runManagementCommand = async (
   } catch (error) {
     if (!(error instanceof RayrunApiError)) throw error;
     const requestId = error.requestId ? `, request ${error.requestId}` : '';
+    const diagnosticTarget = error.code === 'invalid_source' ? 'source' : 'hook.ts';
     const diagnostics = error.diagnostics
       .map(
         (entry) =>
-          `hook.ts${entry.line === undefined ? '' : `:${String(entry.line)}${entry.column === undefined ? '' : `:${String(entry.column)}`}`}: ${entry.message}`,
+          `${diagnosticTarget}${entry.line === undefined ? '' : `:${String(entry.line)}${entry.column === undefined ? '' : `:${String(entry.column)}`}`}: ${entry.message}`,
       )
       .join('\n');
     throw new Error(