@a9n-shoji/rvw 0.2.0 → 0.2.2

package/skills/rvw-watch-comments/scripts/preflight.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import { runRvw } from "./rvw-command.mjs";
+
+const REQUIRED_NODE = [24, 15, 0];
+const REQUIRED_PROTOCOL = 3;
+const REQUIRED_CAPABILITIES = [
+  "agent.transport",
+  "comment.watch",
+  "comment.read",
+  "comment.reply",
+  "comment.edit",
+  "comment.codeReferences",
+  "pullRequest.sync",
+];
+
+function nodeIsSupported(version) {
+  const actual = version.split(".").map(Number);
+  for (let index = 0; index < REQUIRED_NODE.length; index += 1) {
+    if ((actual[index] ?? 0) > REQUIRED_NODE[index]) return true;
+    if ((actual[index] ?? 0) < REQUIRED_NODE[index]) return false;
+  }
+  return true;
+}
+
+function commandSummary(result) {
+  return {
+    exitCode: result.code,
+    signal: result.signal,
+    output: result.json,
+    ...(result.stderr.trim() ? { stderr: result.stderr.trim() } : {}),
+    ...(!result.json && result.stdout.trim() ? { stdout: result.stdout.trim() } : {}),
+  };
+}
+
+async function main() {
+  const settled = await Promise.allSettled([
+    runRvw(["protocol", "--json"]),
+    runRvw(["agent", "status", "--json"]),
+    runRvw(["agent", "ping", "--json"]),
+  ]);
+  const [protocolResult, statusResult, pingResult] = settled.map((result) =>
+    result.status === "fulfilled" ? result.value : null,
+  );
+  const protocol = protocolResult?.json;
+  const agentStatus = statusResult?.json;
+  const agentPing = pingResult?.json;
+  const capabilities = Array.isArray(protocol?.capabilities) ? protocol.capabilities : [];
+  const missingCapabilities = REQUIRED_CAPABILITIES.filter(
+    (capability) => !capabilities.includes(capability),
+  );
+  const checks = {
+    nodeVersion: nodeIsSupported(process.versions.node),
+    rvwBinary: protocolResult !== null,
+    appVersion: typeof protocol?.appVersion === "string" && protocol.appVersion.length > 0,
+    protocol: protocol?.protocolVersion === REQUIRED_PROTOCOL,
+    capabilities: missingCapabilities.length === 0,
+    agentStatus: agentStatus?.ok === true && agentStatus.selectedTransport !== "unavailable",
+    agentPingInspected: agentPing !== null && typeof agentPing === "object",
+    agentPingConnected: agentPing?.ok === true && agentPing.connected === true,
+  };
+  const ok =
+    checks.nodeVersion &&
+    checks.rvwBinary &&
+    checks.appVersion &&
+    checks.protocol &&
+    checks.capabilities &&
+    checks.agentStatus &&
+    checks.agentPingInspected;
+  const output = {
+    ok,
+    node: {
+      version: process.versions.node,
+      required: ">=24.15.0",
+      ok: checks.nodeVersion,
+    },
+    rvw: {
+      binary: protocolResult?.binary ?? process.env.RVW_BIN ?? "rvw",
+      appVersion: typeof protocol?.appVersion === "string" ? protocol.appVersion : null,
+      protocolVersion:
+        typeof protocol?.protocolVersion === "number" ? protocol.protocolVersion : null,
+      requiredProtocolVersion: REQUIRED_PROTOCOL,
+      capabilities,
+      requiredCapabilities: REQUIRED_CAPABILITIES,
+      missingCapabilities,
+    },
+    agent: {
+      status: statusResult ? commandSummary(statusResult) : null,
+      ping: pingResult ? commandSummary(pingResult) : null,
+      pingRequired: false,
+    },
+    checks,
+    errors: settled.flatMap((result, index) =>
+      result.status === "rejected"
+        ? [
+            {
+              command: ["protocol", "agent status", "agent ping"][index],
+              error: String(result.reason),
+            },
+          ]
+        : [],
+    ),
+  };
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (!ok) process.exitCode = 1;
+}
+
+await main();

package/skills/rvw-watch-comments/scripts/rvw-command.mjs

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+
+const MAX_CAPTURE_BYTES = 40 * 1024 * 1024;
+
+function commandPrefix() {
+  const binary = process.env.RVW_BIN?.trim() || "rvw";
+  const rawPrefix = process.env.RVW_BIN_ARGS_JSON;
+  if (!rawPrefix) return { binary, prefix: [] };
+  let parsed;
+  try {
+    parsed = JSON.parse(rawPrefix);
+  } catch (error) {
+    throw new Error(`RVW_BIN_ARGS_JSON must be a JSON string array: ${String(error)}`, {
+      cause: error,
+    });
+  }
+  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== "string")) {
+    throw new Error("RVW_BIN_ARGS_JSON must be a JSON string array");
+  }
+  return { binary, prefix: parsed };
+}
+
+export function spawnRvw(args, options = {}) {
+  const { binary, prefix } = commandPrefix();
+  return spawn(binary, [...prefix, ...args], {
+    stdio: options.stdio ?? ["pipe", "pipe", "pipe"],
+    env: process.env,
+  });
+}
+
+export async function runRvw(args, options = {}) {
+  const child = spawnRvw(args);
+  const stdout = [];
+  const stderr = [];
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  child.stdout.on("data", (chunk) => {
+    stdoutBytes += chunk.length;
+    if (stdoutBytes <= MAX_CAPTURE_BYTES) stdout.push(chunk);
+  });
+  child.stderr.on("data", (chunk) => {
+    stderrBytes += chunk.length;
+    if (stderrBytes <= MAX_CAPTURE_BYTES) stderr.push(chunk);
+  });
+  if (options.input === undefined) child.stdin.end();
+  else
+    child.stdin.end(
+      typeof options.input === "string" ? options.input : JSON.stringify(options.input),
+    );
+  const status = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  if (stdoutBytes > MAX_CAPTURE_BYTES || stderrBytes > MAX_CAPTURE_BYTES) {
+    throw new Error("rvw command output exceeded 40 MiB");
+  }
+  const stdoutText = Buffer.concat(stdout).toString("utf8");
+  const stderrText = Buffer.concat(stderr).toString("utf8");
+  let json = null;
+  if (stdoutText.trim()) {
+    try {
+      json = JSON.parse(stdoutText);
+    } catch {
+      // The caller reports malformed output with the original stdout attached.
+    }
+  }
+  return {
+    args,
+    binary: commandPrefix().binary,
+    code: status.code,
+    signal: status.signal,
+    stdout: stdoutText,
+    stderr: stderrText,
+    json,
+  };
+}
+
+export function successfulJson(result) {
+  return result.code === 0 && result.json && result.json.ok !== false;
+}

package/skills/rvw-watch-comments/scripts/watch-driver.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+import { spawnRvw } from "./rvw-command.mjs";
+
+const EXIT_WATCH = 20;
+const EXIT_SEQUENCE = 21;
+const EXIT_INGEST = 22;
+const EXIT_AUTO_ACK = 23;
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const stateScript = path.join(scriptDirectory, "watch-state.mjs");
+const autoAckScript = path.join(scriptDirectory, "auto-ack.mjs");
+
+class DriverError extends Error {
+  constructor(message, exitCode, details = null) {
+    super(message);
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+function parseArguments(values) {
+  let state = null;
+  let autoAck = false;
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--auto-ack") {
+      autoAck = true;
+      continue;
+    }
+    if (value === "--state") {
+      const next = values[index + 1];
+      if (!next || next.startsWith("--")) {
+        throw new DriverError("--state requires a path", EXIT_WATCH);
+      }
+      state = next;
+      index += 1;
+      continue;
+    }
+    if (!value.startsWith("--") && state === null) {
+      state = value;
+      continue;
+    }
+    throw new DriverError(`Unexpected argument: ${value}`, EXIT_WATCH);
+  }
+  if (!state) throw new DriverError("Pass the task state database path", EXIT_WATCH);
+  return { state: path.resolve(state), autoAck };
+}
+
+async function runNodeScript(script, args, input) {
+  const child = spawn(process.execPath, [script, ...args], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  const stdout = [];
+  const stderr = [];
+  child.stdout.on("data", (chunk) => stdout.push(chunk));
+  child.stderr.on("data", (chunk) => stderr.push(chunk));
+  child.stdin.end(input === undefined ? undefined : JSON.stringify(input));
+  const status = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  const stdoutText = Buffer.concat(stdout).toString("utf8");
+  const stderrText = Buffer.concat(stderr).toString("utf8");
+  let json = null;
+  try {
+    json = JSON.parse(stdoutText);
+  } catch {
+    // The caller selects the appropriate driver exit contract.
+  }
+  return { ...status, stdout: stdoutText, stderr: stderrText, json };
+}
+
+async function stateCommand(state, command, args = [], input) {
+  const result = await runNodeScript(stateScript, [command, "--state", state, ...args], input);
+  if (result.code !== 0 || !result.json?.ok) {
+    throw new DriverError(`watch-state ${command} failed`, EXIT_INGEST, result);
+  }
+  return result.json;
+}
+
+function write(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+async function dispatchAutoAck(state, pullRequest) {
+  const pending = await stateCommand(state, "list");
+  if (!pending.pending.some((batch) => batch.pullRequest === pullRequest)) {
+    write({ ok: true, type: "queued", pullRequest, reason: "batch-not-yet-eligible" });
+    return;
+  }
+  const result = await runNodeScript(autoAckScript, [
+    "--state",
+    state,
+    "--pull-request",
+    pullRequest,
+  ]);
+  if (result.code !== 0 || !result.json?.ok) {
+    throw new DriverError(`auto-ack failed for ${pullRequest}`, EXIT_AUTO_ACK, result);
+  }
+  write({ ...result.json, type: "batch-acknowledged" });
+}
+
+async function dispatchPendingAutoAcks(state) {
+  const pending = await stateCommand(state, "list");
+  for (const batch of pending.pending) {
+    await dispatchAutoAck(state, batch.pullRequest);
+  }
+}
+
+async function processFrame(state, frame, autoAck, pullRequests) {
+  if (!frame || typeof frame !== "object" || typeof frame.type !== "string") {
+    throw new DriverError("Invalid RFC 7464 frame", EXIT_SEQUENCE, frame);
+  }
+  if (frame.type === "error") {
+    throw new DriverError("rvw comment watch returned an error frame", EXIT_WATCH, frame);
+  }
+  const ingested = await stateCommand(state, "ingest", [], frame);
+  if (frame.type === "ready") {
+    write({
+      ok: true,
+      type: "watch-ready",
+      cursor: ingested.cursor,
+      databaseId: frame.databaseId,
+      anchoredAtCurrent: frame.anchoredAtCurrent,
+      autoAck,
+    });
+  } else if (frame.type === "comment-posted" && ingested.status === "queued") {
+    if (autoAck) pullRequests.add(frame.event.pullRequestUrl);
+    else {
+      write({
+        ok: true,
+        type: "pending",
+        pullRequest: frame.event.pullRequestUrl,
+        commentRef: frame.event.commentRef,
+        cursor: ingested.cursor,
+      });
+    }
+  }
+}
+
+async function runWatchOnce(state, autoAck, stopping) {
+  const current = await stateCommand(state, "status");
+  const args = ["comment", "watch"];
+  if (current.cursor) args.push("--after", current.cursor);
+  args.push("--interval", "1", "--json-seq");
+  const child = spawnRvw(args);
+  stopping.child = child;
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk;
+    process.stderr.write(chunk);
+  });
+  const statusPromise = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  child.stdin.end();
+  const decoder = new StringDecoder("utf8");
+  let buffered = "";
+  let readySeen = false;
+  let stoppedSeen = false;
+  try {
+    for await (const chunk of child.stdout) {
+      buffered += decoder.write(chunk);
+      const lines = buffered.split("\n");
+      buffered = lines.pop() ?? "";
+      const pullRequests = new Set();
+      for (const rawLine of lines) {
+        if (!rawLine) continue;
+        if (!rawLine.startsWith("\u001e")) {
+          throw new DriverError("RFC 7464 frame does not start with RS", EXIT_SEQUENCE, rawLine);
+        }
+        let frame;
+        try {
+          frame = JSON.parse(rawLine.slice(1));
+        } catch (error) {
+          throw new DriverError("RFC 7464 frame is not valid JSON", EXIT_SEQUENCE, String(error));
+        }
+        readySeen ||= frame.type === "ready";
+        stoppedSeen ||= frame.type === "stopped";
+        await processFrame(state, frame, autoAck, pullRequests);
+      }
+      for (const pullRequest of pullRequests) await dispatchAutoAck(state, pullRequest);
+    }
+    buffered += decoder.end();
+    if (buffered.trim()) {
+      throw new DriverError(
+        "rvw comment watch ended with a truncated frame",
+        EXIT_SEQUENCE,
+        buffered,
+      );
+    }
+    const status = await statusPromise;
+    stopping.child = null;
+    return { ...status, stderr, readySeen, stoppedSeen };
+  } catch (error) {
+    child.kill("SIGTERM");
+    await statusPromise.catch(() => undefined);
+    stopping.child = null;
+    throw error;
+  }
+}
+
+function retryDelay(attempt) {
+  const base = Number(process.env.RVW_WATCH_DRIVER_RETRY_MS ?? "1000");
+  const safeBase = Number.isFinite(base) && base >= 0 ? base : 1000;
+  return Math.min(safeBase * 2 ** Math.max(0, attempt - 1), 30_000);
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function main() {
+  const { state, autoAck } = parseArguments(process.argv.slice(2));
+  const stopping = { requested: false, child: null };
+  const stop = () => {
+    stopping.requested = true;
+    stopping.child?.kill("SIGTERM");
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  const maxRestarts = Number(process.env.RVW_WATCH_DRIVER_MAX_RESTARTS ?? "5");
+  let restarts = 0;
+  try {
+    while (!stopping.requested) {
+      const startedAt = Date.now();
+      if (autoAck) await dispatchPendingAutoAcks(state);
+      const result = await runWatchOnce(state, autoAck, stopping);
+      if (stopping.requested) return;
+      if (Date.now() - startedAt >= 30_000) restarts = 0;
+      restarts += 1;
+      if (restarts > maxRestarts) {
+        throw new DriverError("rvw comment watch exceeded its reconnect limit", EXIT_WATCH, result);
+      }
+      const delayMs = retryDelay(restarts);
+      write({
+        ok: true,
+        type: "reconnecting",
+        attempt: restarts,
+        delayMs,
+        lastExitCode: result.code,
+        lastSignal: result.signal,
+        readySeen: result.readySeen,
+      });
+      await delay(delayMs);
+    }
+  } finally {
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+  }
+}
+
+try {
+  await main();
+} catch (error) {
+  const exitCode = error instanceof DriverError ? error.exitCode : EXIT_WATCH;
+  process.stderr.write(
+    `${JSON.stringify({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      details: error?.details ?? null,
+      exitCode,
+    })}\n`,
+  );
+  process.exitCode = exitCode;
+}