@rubicon-caliga/cli 0.1.1 → 0.1.2

package/src/circle.ts

@@ -0,0 +1,232 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export type CircleRunner = (command: string, args: string[]) => Promise<string>;
+
+export interface CircleErrorInfo {
+  code: "network_unavailable" | "otp_expired" | "not_logged_in" | "missing_cli" | "command_failed";
+  message: string;
+  guidance: string;
+}
+
+export interface CircleWalletInfo {
+  address: `0x${string}`;
+  raw?: unknown;
+}
+
+export interface CircleBalanceInfo {
+  balanceAtomic: `${bigint}`;
+  backingEOA?: `0x${string}`;
+  raw?: unknown;
+}
+
+export function defaultCircleCommand(): string {
+  return process.env.CIRCLE_CLI_COMMAND ?? "circle";
+}
+
+export async function runCircleCli(command: string, args: string[]): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(command, args, { maxBuffer: 1024 * 1024 });
+    return stdout;
+  } catch (error) {
+    throw classifyCircleError(error);
+  }
+}
+
+export function classifyCircleError(error: unknown): Error & { circle?: CircleErrorInfo } {
+  const message = error instanceof Error ? error.message : String(error);
+  const output = [
+    message,
+    isRecord(error) && typeof error.stdout === "string" ? error.stdout : undefined,
+    isRecord(error) && typeof error.stderr === "string" ? error.stderr : undefined,
+  ]
+    .filter(Boolean)
+    .join("\n");
+  const lower = output.toLowerCase();
+  let info: CircleErrorInfo;
+  if (lower.includes("fetch failed") || lower.includes("network") || lower.includes("enotfound") || lower.includes("econnrefused")) {
+    info = {
+      code: "network_unavailable",
+      message: "Circle CLI network request failed.",
+      guidance: "Retry this command in a network-capable shell or agent context. Restricted sandboxes often block Circle auth and Gateway calls.",
+    };
+  } else if (lower.includes("otp") && (lower.includes("expired") || lower.includes("invalid") || lower.includes("request"))) {
+    info = {
+      code: "otp_expired",
+      message: "Circle OTP request id is invalid or expired.",
+      guidance: "Start a fresh Circle auth OTP flow, then rerun the Rubicon command after login completes.",
+    };
+  } else if (lower.includes("login") || lower.includes("logged in") || lower.includes("unauthorized") || lower.includes("auth")) {
+    info = {
+      code: "not_logged_in",
+      message: "Circle CLI is not logged in.",
+      guidance: "Run Circle CLI login/auth again, then rerun Rubicon. If an OTP flow was interrupted, start a fresh OTP init.",
+    };
+  } else if (lower.includes("enoent") || lower.includes("not found")) {
+    info = {
+      code: "missing_cli",
+      message: "Circle CLI was not found.",
+      guidance: "Install Circle CLI and make sure the `circle` binary is on PATH.",
+    };
+  } else {
+    info = {
+      code: "command_failed",
+      message: "Circle CLI command failed.",
+      guidance: "Inspect the Circle CLI output, confirm login, wallet, selected chain, and network access, then retry.",
+    };
+  }
+  const wrapped = new Error(`${info.message} ${output}`.trim()) as Error & { circle?: CircleErrorInfo };
+  wrapped.circle = info;
+  return wrapped;
+}
+
+export function circleGuidance(error: unknown): CircleErrorInfo | undefined {
+  if (isRecord(error) && isRecord(error.circle)) {
+    return error.circle as unknown as CircleErrorInfo;
+  }
+  return undefined;
+}
+
+export async function circleVersion(input: { command?: string; runner?: CircleRunner } = {}): Promise<string> {
+  const command = input.command ?? defaultCircleCommand();
+  const runner = input.runner ?? runCircleCli;
+  return (await runner(command, ["--version"])).trim();
+}
+
+export async function circleAuthStatus(input: { command?: string; runner?: CircleRunner } = {}): Promise<unknown> {
+  const command = input.command ?? defaultCircleCommand();
+  const runner = input.runner ?? runCircleCli;
+  const output = await runner(command, ["auth", "status", "--output", "json"]);
+  return parseMaybeJson(output);
+}
+
+export async function circleAgentWallet(input: {
+  chain: string;
+  configuredAddress?: `0x${string}`;
+  command?: string;
+  runner?: CircleRunner;
+}): Promise<CircleWalletInfo> {
+  if (input.configuredAddress) return { address: input.configuredAddress };
+  const command = input.command ?? defaultCircleCommand();
+  const runner = input.runner ?? runCircleCli;
+  const output = await runner(command, ["wallet", "list", "--chain", input.chain, "--type", "agent", "--output", "json"]);
+  const raw = parseMaybeJson(output);
+  const address = parseWalletAddress(raw);
+  return { address, raw };
+}
+
+export async function circleGatewayBalance(input: {
+  address: `0x${string}`;
+  chain: string;
+  command?: string;
+  runner?: CircleRunner;
+}): Promise<CircleBalanceInfo> {
+  const command = input.command ?? defaultCircleCommand();
+  const runner = input.runner ?? runCircleCli;
+  const output = await runner(command, ["gateway", "balance", "--address", input.address, "--chain", input.chain, "--output", "json"]);
+  const raw = parseMaybeJson(output);
+  return {
+    balanceAtomic: parseBalanceAtomic(raw),
+    backingEOA: parseBackingEOA(raw),
+    raw,
+  };
+}
+
+export async function circleGatewayFaucet(input: {
+  address: `0x${string}`;
+  chain: string;
+  command?: string;
+  runner?: CircleRunner;
+}): Promise<unknown> {
+  const command = input.command ?? defaultCircleCommand();
+  const runner = input.runner ?? runCircleCli;
+  const output = await runner(command, ["gateway", "faucet", "--address", input.address, "--chain", input.chain, "--output", "json"]);
+  return parseMaybeJson(output);
+}
+
+function parseWalletAddress(value: unknown): `0x${string}` {
+  const wallets = collectRecords(value);
+  const addresses = wallets
+    .map((wallet) => findString(wallet, ["address", "walletAddress", "blockchainAddress"]))
+    .filter((address): address is `0x${string}` => Boolean(address && isAddress(address)));
+  const unique = [...new Set(addresses.map((address) => address.toLowerCase()))];
+  if (unique.length === 1) return addresses.find((address) => address.toLowerCase() === unique[0])!;
+  if (unique.length === 0) throw new Error("Circle CLI did not return an Agent Wallet address.");
+  throw new Error("Multiple Circle Agent Wallets found; configure agent-wallet-address.");
+}
+
+function parseBalanceAtomic(value: unknown): `${bigint}` {
+  const direct =
+    findString(value, [
+      "data.balanceAtomic",
+      "data.availableAtomic",
+      "data.usdc.balanceAtomic",
+      "balanceAtomic",
+      "availableAtomic",
+      "usdc.balanceAtomic",
+    ]) ?? findNumber(value, ["data.balance", "data.available", "balance", "available"]);
+  if (typeof direct === "number") return `${BigInt(Math.trunc(direct * 1_000_000))}`;
+  if (direct && /^\d+$/.test(direct)) return direct as `${bigint}`;
+  if (direct && /^\d+(\.\d+)?$/.test(direct)) return `${decimalUsdcToAtomic(direct)}`;
+  return "0";
+}
+
+function parseBackingEOA(value: unknown): `0x${string}` | undefined {
+  const address = findString(value, ["data.backingEOA", "backingEOA", "data.backingEoa", "backingEoa"]);
+  return address && isAddress(address) ? address : undefined;
+}
+
+function parseMaybeJson(output: string): unknown {
+  const trimmed = output.trim();
+  if (!trimmed) return {};
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed;
+  }
+}
+
+function decimalUsdcToAtomic(value: string): bigint {
+  const [whole = "0", fraction = ""] = value.split(".");
+  const padded = `${fraction}000000`.slice(0, 6);
+  return BigInt(whole) * 1_000_000n + BigInt(padded);
+}
+
+function collectRecords(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) return value.filter(isRecord);
+  if (!isRecord(value)) return [];
+  const records: Record<string, unknown>[] = [value];
+  for (const key of ["wallets", "items", "data"]) {
+    const nested = value[key];
+    if (Array.isArray(nested)) records.push(...nested.filter(isRecord));
+    if (isRecord(nested)) records.push(...collectRecords(nested));
+  }
+  return records;
+}
+
+function findString(value: unknown, paths: string[]): string | undefined {
+  for (const path of paths) {
+    const found = path.split(".").reduce<unknown>((current, part) => (isRecord(current) ? current[part] : undefined), value);
+    if (typeof found === "string") return found;
+  }
+  return undefined;
+}
+
+function findNumber(value: unknown, paths: string[]): number | undefined {
+  for (const path of paths) {
+    const found = path.split(".").reduce<unknown>((current, part) => (isRecord(current) ? current[part] : undefined), value);
+    if (typeof found === "number") return found;
+    if (typeof found === "string" && /^\d+(\.\d+)?$/.test(found)) return Number(found);
+  }
+  return undefined;
+}
+
+function isAddress(value: string): value is `0x${string}` {
+  return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/errors.ts

@@ -10,6 +10,21 @@ export class CliError extends Error {
 
 export function toCliError(error: unknown): CliError {
   if (error instanceof CliError) return error;
-  if (error instanceof Error) return new CliError("COMMAND_FAILED", error.message);
+  if (error instanceof Error) {
+    const lower = error.message.toLowerCase();
+    if (lower.includes("fetch failed") || lower.includes("enotfound") || lower.includes("econnrefused")) {
+      return new CliError(
+        "CIRCLE_NETWORK_UNAVAILABLE",
+        `${error.message} Retry in a network-capable shell or agent context; restricted sandboxes often block Circle auth and Gateway calls.`,
+      );
+    }
+    if (lower.includes("otp") && (lower.includes("expired") || lower.includes("invalid") || lower.includes("request"))) {
+      return new CliError(
+        "CIRCLE_OTP_EXPIRED",
+        `${error.message} Start a fresh Circle auth OTP flow, then rerun the Rubicon command after login completes.`,
+      );
+    }
+    return new CliError("COMMAND_FAILED", error.message);
+  }
   return new CliError("COMMAND_FAILED", String(error));
 }

package/src/index.ts

@@ -20,7 +20,9 @@ import {
   receiptSummaryJson,
 } from "./format.js";
 import { selectPaymentEngine, type PaymentMode } from "./payments.js";
+import { runDoctor, runQuickstartRead } from "./quickstart.js";
 import { listReceipts, loadReceipt, saveReceipt } from "./receipts.js";
+import packageJson from "../package.json" with { type: "json" };
 
 interface Runtime {
   parsed: ParsedArgs;
@@ -70,11 +72,24 @@ async function main(): Promise<void> {
 async function dispatch(runtime: Runtime): Promise<void> {
   const [command, subcommand, ...rest] = runtime.parsed.positionals;
 
+  if (booleanFlag(runtime.parsed.flags, "version") || command === "version") {
+    process.stdout.write(`${packageJson.version}\n`);
+    return;
+  }
+
   if (!command || command === "help" || booleanFlag(runtime.parsed.flags, "help")) {
     showHelp(runtime.json);
     return;
   }
 
+  if (command === "doctor") {
+    printJson(await runDoctor(runtime, { cliVersion: packageJson.version }));
+    return;
+  }
+  if (command === "quickstart-read") {
+    printJson(await runQuickstartRead(runtime));
+    return;
+  }
   if (command === "repository") {
     await repository(runtime);
     return;
@@ -596,6 +611,8 @@ function matchesQuery(article: ArticleSummary, query: string): boolean {
 function showHelp(json: boolean): void {
   const usage = [
     "rubicon repository",
+    "rubicon doctor --json",
+    "rubicon quickstart-read --first --goal \"<goal>\" --max-usdc 0.10 --json",
     "rubicon search \"<query>\"",
     "rubicon article show <article-id>",
     "rubicon article navigation <article-id> --goal \"<goal>\"",

package/src/quickstart.test.ts

@@ -0,0 +1,264 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { ReadReceipt, RubiconClient } from "@rubicon-caliga/agent-sdk";
+import type { ArticleSummary } from "@rubicon-caliga/core";
+import { parseArgs } from "./args.js";
+import { CliError } from "./errors.js";
+import { finalReceiptJson, runDoctor, runQuickstartRead, type CommandRuntime } from "./quickstart.js";
+
+test("doctor reports missing gateway config and Circle CLI missing", async () => {
+  const runtime = runtimeFor();
+  const result = await runDoctor(runtime, {
+    cliVersion: "0.1.1",
+    fetch: okFetch,
+    circleRunner: async () => {
+      throw new Error("spawn circle ENOENT");
+    },
+  });
+
+  const checks = result.checks as Array<{ name: string; status: string; guidance?: string }>;
+  assert.equal(checks.find((check) => check.name === "gatewayConfig")?.status, "warning");
+  assert.match(checks.find((check) => check.name === "gatewayConfig")?.guidance ?? "", /hosted default/);
+  assert.equal(checks.find((check) => check.name === "circleCli")?.status, "error");
+  assert.match(checks.find((check) => check.name === "circleCli")?.guidance ?? "", /Install Circle CLI/);
+});
+
+test("doctor explains Circle CLI not logged in and sandbox network failures", async () => {
+  const notLoggedIn = await runDoctor(runtimeFor(), {
+    fetch: okFetch,
+    circleRunner: async (_command, args) => {
+      if (args[0] === "--version") return "circle 1.0.0";
+      throw new Error("unauthorized: please login");
+    },
+  });
+  const notLoggedChecks = notLoggedIn.checks as Array<{ name: string; guidance?: string }>;
+  assert.match(notLoggedChecks.find((check) => check.name === "circleAuth")?.guidance ?? "", /login/);
+
+  const networkFailure = await runDoctor(runtimeFor(), {
+    fetch: (async () => {
+      throw new Error("fetch failed");
+    }) as unknown as typeof fetch,
+    circleRunner: async () => "circle 1.0.0",
+  });
+  const networkChecks = networkFailure.checks as Array<{ name: string; guidance?: string }>;
+  assert.match(networkChecks.find((check) => check.name === "gatewayReachability")?.guidance ?? "", /network-capable/);
+});
+
+test("quickstart refuses paid reads without explicit budget", async () => {
+  await assert.rejects(
+    () => runQuickstartRead(runtimeFor({ argv: ["quickstart-read", "--first", "--goal", "answer"] })),
+    (error) => error instanceof CliError && error.code === "MISSING_BUDGET",
+  );
+});
+
+test("quickstart detects expired OTP request IDs", async () => {
+  await assert.rejects(
+    () =>
+      runQuickstartRead(runtimeFor(), {
+        circleRunner: async (_command, args) => {
+          if (args[0] === "auth") throw new Error("OTP request id expired");
+          return circleOutput(args, "1000000");
+        },
+      }),
+    (error) => error instanceof CliError && error.code === "OTP_EXPIRED" && /fresh Circle auth OTP/.test(error.message),
+  );
+});
+
+test("quickstart stops when dry-run estimate exceeds budget", async () => {
+  await assert.rejects(
+    () => runQuickstartRead(runtimeFor({ article: article({ pricePerWordAtomic: "1000000" }) })),
+    (error) => error instanceof CliError && error.code === "DRY_RUN_OVER_BUDGET",
+  );
+});
+
+test("quickstart uses existing Arc Testnet balance without faucet", async () => {
+  const calls: string[][] = [];
+  const result = await runQuickstartRead(runtimeFor(), {
+    circleRunner: async (_command, args) => {
+      calls.push(args);
+      return circleOutput(args, "1000000");
+    },
+  });
+
+  assert.equal((result.receipt as Record<string, unknown>).amountPaidAtomic, "2");
+  assert.equal(calls.some((args) => args[0] === "gateway" && args[1] === "faucet"), false);
+});
+
+test("quickstart faucet-funds only the testnet path when needed", async () => {
+  const calls: string[][] = [];
+  let funded = false;
+  const result = await runQuickstartRead(runtimeFor(), {
+    circleRunner: async (_command, args) => {
+      calls.push(args);
+      if (args[0] === "gateway" && args[1] === "faucet") {
+        funded = true;
+        return JSON.stringify({ ok: true });
+      }
+      return circleOutput(args, funded ? "1000000" : "0");
+    },
+  });
+
+  assert.equal(calls.some((args) => args[0] === "gateway" && args[1] === "faucet"), true);
+  assert.equal((result.wallet as Record<string, unknown>).balanceAtomic, "1000000");
+});
+
+test("quickstart refuses to suggest mainnet funding", async () => {
+  await assert.rejects(
+    () =>
+      runQuickstartRead(runtimeFor({ article: article({ environment: "mainnet", network: "eip155:1", circleChain: "ETH" }) }), {
+        circleRunner: async (_command, args) => circleOutput(args, "0"),
+      }),
+    (error) => error instanceof CliError && error.code === "INSUFFICIENT_FUNDS" && /Refusing to suggest mainnet funding/.test(error.message),
+  );
+});
+
+test("final receipt schema includes buyer/Circle wallet mismatch explanation", () => {
+  const shaped = finalReceiptJson({
+    article: article(),
+    receipt: receipt(),
+    receiptId: "receipt_1",
+    goal: "answer",
+    approvedBudgetUsdc: "0.01",
+    circleWalletAddress: "0x1111111111111111111111111111111111111111",
+  });
+
+  assert.deepEqual(Object.keys(shaped), [
+    "articleId",
+    "title",
+    "author",
+    "sessionId",
+    "receiptId",
+    "goal",
+    "approvedBudgetUsdc",
+    "amountPaidAtomic",
+    "amountPaidUsdc",
+    "wordsRead",
+    "completed",
+    "stopReason",
+    "paymentIds",
+    "settlementIds",
+    "transactionHashes",
+    "buyerWalletAddress",
+    "circleWalletAddress",
+    "walletAddressMismatchExplanation",
+  ]);
+  assert.match(String(shaped.walletAddressMismatchExplanation), /Gateway backing EOA/);
+});
+
+function runtimeFor(input: { argv?: string[]; article?: ArticleSummary } = {}): CommandRuntime {
+  process.env.HOME = mkdtempSync(join(tmpdir(), "rubicon-cli-test-"));
+  const articleFixture = input.article ?? article();
+  const client = {
+    async getRepository() {
+      return { repository: "articles" as const, articles: [articleFixture] };
+    },
+    async getNavigation() {
+      return {
+        article: articleFixture,
+        navigation: {
+          articleId: articleFixture.articleId,
+          sections: articleFixture.sections,
+          sellerAgent: {
+            recommendedSectionId: "intro",
+            alternativeSectionIds: [],
+            rationale: "Start here.",
+            safeHints: [],
+            withheld: [],
+          },
+          stopConditions: [],
+        },
+      };
+    },
+    async run() {
+      return receipt();
+    },
+  } as unknown as RubiconClient;
+  return {
+    parsed: parseArgs(input.argv ?? ["quickstart-read", "--first", "--goal", "answer", "--max-usdc", "0.01"]),
+    config: {},
+    gatewayUrl: "https://rubicon.test",
+    paymentMode: "circle-cli",
+    circleChain: "ARC-TESTNET",
+    client,
+  };
+}
+
+function article(input: {
+  pricePerWordAtomic?: `${bigint}`;
+  network?: string;
+  circleChain?: string;
+  environment?: "testnet" | "mainnet" | "unknown";
+} = {}): ArticleSummary {
+  return {
+    articleId: "article_1",
+    creatorId: "creator_1",
+    creatorUsername: "creator",
+    title: "Rubicon Field Notes",
+    author: "Ada",
+    state: "live",
+    totalWords: 2,
+    pricePerWordAtomic: input.pricePerWordAtomic ?? "1",
+    maxArticlePriceAtomic: `${BigInt(input.pricePerWordAtomic ?? "1") * 2n}` as `${bigint}`,
+    paymentTerms: {
+      asset: "USDC",
+      network: input.network ?? "eip155:5042002",
+      circleChain: input.circleChain ?? "ARC-TESTNET",
+      environment: input.environment ?? "testnet",
+      fundingMethod: "Circle testnet faucet.",
+      payTo: "0x3333333333333333333333333333333333333333",
+      pricePerWordAtomic: input.pricePerWordAtomic ?? "1",
+      meteringUnit: "word",
+    },
+    sections: [{ sectionId: "intro", heading: "Intro", level: 1, wordStart: 0, wordCount: 2 }],
+  };
+}
+
+function receipt(): ReadReceipt {
+  return {
+    sessionId: "session_1",
+    articleId: "article_1",
+    conversationId: "conversation_1",
+    wordsRead: 2,
+    amountPaidAtomic: "2",
+    payments: [
+      {
+        paymentId: "payment_1",
+        sessionId: "session_1",
+        articleId: "article_1",
+        sequence: 0,
+        meteringUnit: "word",
+        amountAtomic: "2",
+        currency: "USDC",
+        settlementIds: ["settlement_1"],
+        transactionHashes: ["0xtx"],
+        buyerWalletAddress: "0x2222222222222222222222222222222222222222",
+        settledAt: "2026-06-19T12:00:00.000Z",
+      },
+    ],
+    transactionHashes: ["0xtx"],
+    settlementIds: ["settlement_1"],
+    buyerWalletAddress: "0x2222222222222222222222222222222222222222",
+    sellerPayTo: "0x3333333333333333333333333333333333333333",
+    network: "eip155:5042002",
+    text: "hello world",
+    completed: true,
+    stopReason: "article_completed",
+  };
+}
+
+function circleOutput(args: string[], balanceAtomic: `${bigint}`): string {
+  if (args[0] === "--version") return "circle 1.0.0";
+  if (args[0] === "auth") return JSON.stringify({ loggedIn: true });
+  if (args[0] === "wallet") {
+    return JSON.stringify({ data: { wallets: [{ address: "0x1111111111111111111111111111111111111111" }] } });
+  }
+  if (args[0] === "gateway" && args[1] === "balance") {
+    return JSON.stringify({ data: { balanceAtomic, backingEOA: "0x2222222222222222222222222222222222222222" } });
+  }
+  return JSON.stringify({ ok: true });
+}
+
+const okFetch = (async () => new Response("ok", { status: 200 })) as unknown as typeof fetch;