@runalabs/rill-cli 0.1.0 → 0.1.2

package/README.md

@@ -5,23 +5,27 @@ Record, inspect, and share agent-controlled browser runs with Rill.
 ## Install
 
 ```sh
-npm install --global @runalabs/rill-cli@0.1.0
+npm install --global @runalabs/rill-cli@0.1.2
 rill doctor
 ```
 
 Rill requires Node.js 22 or newer, Google Chrome or Chromium, and `ffmpeg`.
-The CLI defaults to the Rill private-alpha staging API. Set `RILL_API_URL` or
-pass `--api-url` to target another environment.
+The CLI connects to `https://userill.dev` by default.
 
 ## Record
 
 ```sh
 rill login
 rill doctor
-rill record start --url https://staging.example.com --title "Agent reproduction"
+rill record start --url https://example.com --title "Agent reproduction"
 # Connect browser automation to the returned cdpUrl.
 rill record stop <recording-id>
 ```
 
+If the local recorder is unavailable, `rill record status <recording-id>` falls
+back to the control plane. Use `rill record cancel <recording-id>` to abandon an
+active recording and release its quota reservation. A failed local startup
+automatically cancels the reservation it just created.
+
 Commands emit one schema-versioned JSON object to stdout. Human-readable
 progress is written to stderr.

package/dist/cli.js

@@ -583,6 +583,15 @@ function json(response, status, value) {
 import { createReadStream } from "fs";
 import { readFile as readFile2, stat } from "fs/promises";
 import { Upload } from "tus-js-client";
+var ControlPlaneError = class extends Error {
+  constructor(code, message, recovery, details) {
+    super(`${code}: ${message}${recovery ? `: ${recovery}` : ""}`);
+    this.code = code;
+    this.recovery = recovery;
+    this.details = details;
+    this.name = "ControlPlaneError";
+  }
+};
 var ControlPlaneClient = class {
   constructor(apiUrl, token) {
     this.apiUrl = apiUrl;
@@ -594,15 +603,36 @@ var ControlPlaneClient = class {
   agentSession() {
     return this.request("/api/agent/session");
   }
+  reportCliCommand(input) {
+    return this.request("/api/analytics/cli-command", { method: "POST", body: JSON.stringify(input) });
+  }
   createRecording(input) {
     return this.request("/api/recordings", { method: "POST", body: JSON.stringify(input) });
   }
+  markRecordingStarted(recordingId, input) {
+    return this.request(`/api/recordings/${recordingId}/local-started`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  markRecordingStopped(recordingId, input) {
+    return this.request(`/api/recordings/${recordingId}/local-stopped`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
   provisionVideo(recordingId, input) {
     return this.request(`/api/recordings/${recordingId}/video-upload`, { method: "POST", body: JSON.stringify(input) });
   }
   recordingStatus(recordingId) {
     return this.request(`/api/recordings/${recordingId}`);
   }
+  cancelRecording(recordingId, reason = "cancelled_by_agent") {
+    return this.request(`/api/recordings/${recordingId}/cancel`, {
+      method: "POST",
+      body: JSON.stringify({ reason })
+    });
+  }
   async waitUntilPlayable(recordingId, timeoutMs = 10 * 6e4) {
     const deadline = Date.now() + timeoutMs;
     let intervalMs = 1e3;
@@ -667,11 +697,41 @@ var ControlPlaneClient = class {
     }
     const response = await fetch(`${this.apiUrl}${path}`, { ...init, headers });
     const value = await response.json().catch(() => null);
-    if (!response.ok) throw new Error([value?.error?.code, value?.error?.message, value?.error?.recovery].filter(Boolean).join(": ") || `Request failed (${response.status}).`);
+    if (!response.ok && value?.error?.code && value.error.message) {
+      throw new ControlPlaneError(value.error.code, value.error.message, value.error.recovery, value.error.details);
+    }
+    if (!response.ok) throw new Error(`Request failed (${response.status}).`);
     return value;
   }
 };
 
+// src/analytics.ts
+var commandCategories = /* @__PURE__ */ new Map([
+  ["doctor", "doctor"],
+  ["record start", "record_start"],
+  ["record stop", "record_stop"],
+  ["record status", "record_status"],
+  ["record cancel", "record_cancel"],
+  ["upload", "upload"],
+  ["drafts list", "drafts_list"],
+  ["drafts purge", "drafts_purge"]
+]);
+function cliCommandCategory(commandPath2) {
+  return commandCategories.get(commandPath2.join(" ")) ?? null;
+}
+function cliDurationBucket(milliseconds) {
+  if (milliseconds < 6e4) return "under_1m";
+  if (milliseconds < 5 * 6e4) return "1m_to_5m";
+  if (milliseconds < 15 * 6e4) return "5m_to_15m";
+  return "15m_plus";
+}
+function cliFailureCode(error) {
+  const directCode = typeof error === "object" && error !== null && "code" in error ? error.code : null;
+  if (typeof directCode === "string" && /^[a-z0-9_]{1,80}$/.test(directCode)) return directCode;
+  const message = error instanceof Error ? error.message : "";
+  return message.match(/^([a-z][a-z0-9_]{0,79}):/)?.[1] ?? "unexpected_error";
+}
+
 // src/keychain.ts
 import { spawn as spawn4 } from "child_process";
 var service = "rill";
@@ -715,11 +775,16 @@ function emit(value, pretty = false) {
   process.stdout.write(`${JSON.stringify(value, null, pretty ? 2 : void 0)}
 `);
 }
-function fail(error) {
+function failureValue(error) {
   const message = error instanceof Error ? error.message : String(error);
   const [candidate] = message.split(":", 1);
   const knownCodes = /* @__PURE__ */ new Set(["authentication_required", "scope_denied", "quota_exceeded", "browser_unavailable", "recording_not_found", "upload_interrupted", "processing_failed", "share_revoked", "validation_failed"]);
-  emit({ error: { code: knownCodes.has(candidate) ? candidate : "internal_error", message } });
+  const structured = error && typeof error === "object" ? error : {};
+  const code = structured.code && knownCodes.has(structured.code) ? structured.code : knownCodes.has(candidate) ? candidate : "internal_error";
+  return { error: { code, message, ...structured.recovery ? { recovery: structured.recovery } : {}, ...structured.details ? { details: structured.details } : {} } };
+}
+function fail(error) {
+  emit(failureValue(error));
   process.exitCode = 1;
 }
 
@@ -762,8 +827,10 @@ async function runDoctor(apiUrl, overrides = {}) {
     checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} could not be checked against the API compatibility policy.`, version: dependencies.cliVersion, recovery: "Deploy a Rill API that advertises minimumCliVersion and recommendedCliVersion." });
   } else if (compareVersions(dependencies.cliVersion, health.minimumCliVersion) < 0) {
     checks.push({ name: "cli_version", status: "fail", message: `CLI ${dependencies.cliVersion} is older than the minimum supported version ${health.minimumCliVersion}.`, version: dependencies.cliVersion, recovery: `Run \`npm install --global @runalabs/rill-cli@${health.recommendedCliVersion}\`.` });
-  } else if (compareVersions(dependencies.cliVersion, health.recommendedCliVersion) !== 0) {
+  } else if (compareVersions(dependencies.cliVersion, health.recommendedCliVersion) < 0) {
     checks.push({ name: "cli_version", status: "warn", message: `CLI ${dependencies.cliVersion} is supported; ${health.recommendedCliVersion} is recommended.`, version: dependencies.cliVersion, recovery: `Run \`npm install --global @runalabs/rill-cli@${health.recommendedCliVersion}\`.` });
+  } else if (compareVersions(dependencies.cliVersion, health.recommendedCliVersion) > 0) {
+    checks.push({ name: "cli_version", status: "pass", message: `CLI ${dependencies.cliVersion} is supported.`, version: dependencies.cliVersion });
   } else {
     checks.push({ name: "cli_version", status: "pass", message: `CLI ${dependencies.cliVersion} is the recommended version.`, version: dependencies.cliVersion });
   }
@@ -837,9 +904,45 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/recording-lifecycle.ts
+async function startRecordingWithCompensation(remote, dependencies) {
+  try {
+    return await dependencies.startLocal();
+  } catch (startupError) {
+    try {
+      await dependencies.cancelRemote(remote.recordingId, "local_start_failed");
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [startupError, cleanupError],
+        "Local recording startup failed and the remote reservation could not be cancelled. Run `rill record cancel <recording-id>`."
+      );
+    }
+    throw startupError;
+  }
+}
+async function remoteAwareRecordingStatus(recordingId, dependencies) {
+  try {
+    return { ...await dependencies.localStatus(recordingId), source: "local" };
+  } catch {
+    const remote = await dependencies.remoteStatus(recordingId);
+    return {
+      ...remote,
+      recordingId: typeof remote.recordingId === "string" ? remote.recordingId : remote.id ?? recordingId,
+      source: "remote"
+    };
+  }
+}
+
+// src/config.ts
+var PRODUCTION_API_URL = "https://userill.dev";
+function controlPlaneUrl(environmentUrl) {
+  return environmentUrl ?? PRODUCTION_API_URL;
+}
+
 // src/cli.ts
 var program = new Command();
-program.name("rill").description("Record, inspect, and share agent browser runs.").version(CLI_VERSION).option("--api-url <url>", "Rill control plane", process.env.RILL_API_URL ?? "https://rill-staging.tight-shadow-8e12.workers.dev").option("--pretty", "Pretty-print JSON output", false);
+program.name("rill").description("Record, inspect, and share agent browser runs.").version(CLI_VERSION).option("--api-url <url>", "Rill control plane", controlPlaneUrl(process.env.RILL_API_URL)).option("--pretty", "Pretty-print JSON output", false);
+var activeTelemetry = null;
 program.command("daemon", { hidden: true }).action(() => runDaemon());
 program.command("doctor").description("Validate Rill prerequisites before recording.").action(async () => {
   const options = program.opts();
@@ -873,8 +976,20 @@ record.command("start").option("--url <url>").option("--title <title>").option("
   const width = Number(commandOptions.width);
   const height = Number(commandOptions.height);
   const remote = await client.createRecording({ title: commandOptions.title ?? `Browser recording \xB7 ${(/* @__PURE__ */ new Date()).toISOString()}`, description: commandOptions.description, sourceUrl: commandOptions.url ?? null, width, height });
-  await ensureDaemon(process.argv[1]);
-  const local = await startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
+  const local = await startRecordingWithCompensation(remote, {
+    startLocal: async () => {
+      await ensureDaemon(process.argv[1]);
+      return startRecording({ recordingId: remote.recordingId, url: commandOptions.url, cdpUrl: commandOptions.cdpUrl, headed: Boolean(commandOptions.headed), width, height, maxDurationSeconds: Number(commandOptions.maxDuration), captureNetworkBodies: remote.bodyCaptureEnabled });
+    },
+    cancelRemote: (recordingId, reason) => client.cancelRecording(recordingId, reason)
+  });
+  await client.markRecordingStarted(remote.recordingId, {
+    cliVersion: CLI_VERSION,
+    os: process.platform,
+    arch: process.arch,
+    headed: Boolean(commandOptions.headed),
+    attached: Boolean(commandOptions.cdpUrl)
+  }).catch(() => void 0);
   emit({ schemaVersion: 1, recordingId: remote.recordingId, status: local.status, cdpUrl: local.cdpUrl, bodyCaptureEnabled: remote.bodyCaptureEnabled, maxDurationSeconds: Number(commandOptions.maxDuration) }, options.pretty);
 });
 record.command("stop").argument("<recording-id>").option("--no-wait").action(async (recordingId, commandOptions) => {
@@ -884,8 +999,13 @@ record.command("stop").argument("<recording-id>").option("--no-wait").action(asy
   if (!local.result) throw new Error(local.error ?? "The recorder did not produce an artifact.");
   const token = await loadCredential(options.apiUrl);
   const client = new ControlPlaneClient(options.apiUrl, token);
+  await client.markRecordingStopped(recordingId, {
+    durationSeconds: local.result.durationSeconds,
+    stoppedReason: local.result.stoppedReason,
+    diagnosticsAvailable: true
+  }).catch(() => void 0);
   const video = await stat2(local.result.videoPath);
-  const provisioned = await client.provisionVideo(recordingId, { sizeBytes: video.size, filename: basename(local.result.videoPath) });
+  const provisioned = await client.provisionVideo(recordingId, { sizeBytes: video.size, filename: basename(local.result.videoPath), uploadKind: "recorded_browser" });
   await Promise.all([client.uploadVideo(provisioned.uploadUrl, local.result.videoPath), client.uploadDiagnostics(recordingId, local.result.diagnosticsPath, local.result.diagnostics)]);
   const remote = commandOptions.wait === false ? null : await client.waitUntilPlayable(recordingId);
   if (remote) process.stderr.write("\n");
@@ -895,8 +1015,22 @@ record.command("stop").argument("<recording-id>").option("--no-wait").action(asy
 });
 record.command("status").argument("<recording-id>").action(async (recordingId) => {
   const options = program.opts();
-  await ensureDaemon(process.argv[1]);
-  emit({ schemaVersion: 1, ...await recordingStatus(recordingId) }, options.pretty);
+  const token = await loadCredential(options.apiUrl);
+  const client = new ControlPlaneClient(options.apiUrl, token);
+  const status = await remoteAwareRecordingStatus(recordingId, {
+    localStatus: async (id) => {
+      await ensureDaemon(process.argv[1]);
+      return recordingStatus(id);
+    },
+    remoteStatus: (id) => client.recordingStatus(id)
+  });
+  emit({ schemaVersion: 1, ...status }, options.pretty);
+});
+record.command("cancel").argument("<recording-id>").description("Cancel an active recording and release its remote quota slot.").action(async (recordingId) => {
+  const options = program.opts();
+  const token = await loadCredential(options.apiUrl);
+  const client = new ControlPlaneClient(options.apiUrl, token);
+  emit(await client.cancelRecording(recordingId), options.pretty);
 });
 program.command("upload").argument("<video-file>").option("--title <title>").option("--no-wait").action(async (videoFile, commandOptions) => {
   const options = program.opts();
@@ -904,7 +1038,7 @@ program.command("upload").argument("<video-file>").option("--title <title>").opt
   const client = new ControlPlaneClient(options.apiUrl, token);
   const file = await stat2(videoFile);
   const recording = await client.createRecording({ title: commandOptions.title ?? basename(videoFile), sourceUrl: null });
-  const upload = await client.provisionVideo(recording.recordingId, { sizeBytes: file.size, filename: basename(videoFile) });
+  const upload = await client.provisionVideo(recording.recordingId, { sizeBytes: file.size, filename: basename(videoFile), uploadKind: "existing_video" });
   await client.uploadVideo(upload.uploadUrl, videoFile);
   const remote = commandOptions.wait === false ? null : await client.waitUntilPlayable(recording.recordingId);
   if (remote) process.stderr.write("\n");
@@ -936,4 +1070,45 @@ drafts.command("purge").action(async () => {
   }
   emit({ schemaVersion: 1, purged }, options.pretty);
 });
-program.parseAsync().catch(fail);
+program.hook("preAction", async (_command, actionCommand) => {
+  const command = cliCommandCategory(commandPath(actionCommand));
+  if (!command) return;
+  const options = program.opts();
+  const token = await loadCredential(options.apiUrl).catch(() => null);
+  if (!token) return;
+  const client = new ControlPlaneClient(options.apiUrl, token);
+  const session = await client.agentSession().catch(() => null);
+  if (!session?.analyticsEnabled) return;
+  activeTelemetry = { client, command, startedAt: Date.now() };
+  await client.reportCliCommand({ phase: "started", command, cliVersion: CLI_VERSION, os: process.platform, arch: process.arch }).catch(() => void 0);
+});
+program.hook("postAction", async () => {
+  await finishCliTelemetry(process.exitCode ? new Error("command_reported_failure: Command returned a failure status.") : null);
+});
+program.parseAsync().catch(async (error) => {
+  await finishCliTelemetry(error);
+  fail(error);
+});
+function commandPath(actionCommand) {
+  const path = [];
+  let command = actionCommand;
+  while (command && command !== program) {
+    path.unshift(command.name());
+    command = command.parent;
+  }
+  return path;
+}
+async function finishCliTelemetry(error) {
+  const telemetry = activeTelemetry;
+  activeTelemetry = null;
+  if (!telemetry) return;
+  await telemetry.client.reportCliCommand({
+    phase: error ? "failed" : "completed",
+    command: telemetry.command,
+    cliVersion: CLI_VERSION,
+    os: process.platform,
+    arch: process.arch,
+    durationBucket: cliDurationBucket(Date.now() - telemetry.startedAt),
+    ...error ? { failureCode: cliFailureCode(error) } : {}
+  }).catch(() => void 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runalabs/rill-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Record, inspect, and share agent-controlled browser runs with Rill.",
   "license": "Apache-2.0",
   "repository": {