@rubicon-caliga/cli 0.1.0 → 0.1.2

package/src/index.ts

@@ -2,7 +2,7 @@
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { RubiconClient } from "@rubicon-caliga/agent-sdk";
-import { parseUsdcToAtomic, type ArticleSummary } from "@rubicon-caliga/core";
+import { parseUsdcToAtomic, settlementNetworkInfo, type ArticleSectionSummary, type ArticleSummary, type StreamMode } from "@rubicon-caliga/core";
 import { parseArgs, booleanFlag, stringFlag, type ParsedArgs } from "./args.js";
 import { configPath, HOSTED_GATEWAY_URL, readConfig, writeConfig, type RubiconCliConfig } from "./config.js";
 import { CliError, toCliError } from "./errors.js";
@@ -12,11 +12,17 @@ import {
   humanArticle,
   humanNavigation,
   humanReceipt,
+  humanReceiptSummary,
   printJson,
   printJsonEvent,
+  readReceiptSummaryJson,
+  recommendedReadCommandFor,
+  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;
@@ -25,6 +31,7 @@ interface Runtime {
   gatewayUrl: string;
   apiKey?: string;
   paymentMode: PaymentMode;
+  circleChain?: string;
   client: RubiconClient;
 }
 
@@ -50,7 +57,7 @@ async function main(): Promise<void> {
       authorization: apiKey ? `Bearer ${apiKey}` : undefined,
       paymentEngine: payment.engine,
     });
-    await dispatch({ parsed, json, config, gatewayUrl, apiKey, paymentMode: payment.mode, client });
+    await dispatch({ parsed, json, config, gatewayUrl, apiKey, paymentMode: payment.mode, circleChain: payment.circleChain, client });
   } catch (error) {
     const cliError = toCliError(error);
     if (json) {
@@ -65,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;
@@ -156,8 +176,12 @@ async function articleNavigation(runtime: Runtime, articleId: string | undefined
   const goal = stringFlag(runtime.parsed.flags, "goal");
   if (!goal) throw new CliError("MISSING_GOAL", "rubicon article navigation requires --goal.");
   const response = await runtime.client.getNavigation(articleId, goal);
+  const recommendedReadCommand = recommendedReadCommandFor(
+    response.article.articleId,
+    response.navigation.sellerAgent.recommendedSectionId,
+  );
   if (runtime.json) {
-    printJson({ success: true, article: articleJson(response.article), navigation: response.navigation });
+    printJson({ success: true, article: articleJson(response.article), navigation: response.navigation, recommendedReadCommand });
     return;
   }
   process.stdout.write(`${humanArticle(response.article)}\n\n${humanNavigation(response.navigation)}\n`);
@@ -167,60 +191,129 @@ async function readArticle(runtime: Runtime, articleId: string | undefined): Pro
   if (!articleId) throw new CliError("MISSING_ARTICLE_ID", "rubicon read requires an article id.");
   const maxSpendAtomic = parseBudget(runtime.parsed);
   const goal = stringFlag(runtime.parsed.flags, "goal");
+  const sectionId = sectionFlag(runtime.parsed);
+  const stopAfterSection = booleanFlag(runtime.parsed.flags, "stop-after-section");
+  const summary = booleanFlag(runtime.parsed.flags, "summary") || booleanFlag(runtime.parsed.flags, "receipt-summary");
+  const chunkWords = chunkWordsFlag(runtime.parsed);
+  const streamMode = streamModeFlag(runtime.parsed);
   const maxWordsFlag = stringFlag(runtime.parsed.flags, "max-words");
   const maxWords = maxWordsFlag === undefined ? undefined : Number(maxWordsFlag);
   if (maxWords !== undefined && (!Number.isInteger(maxWords) || maxWords < 1)) {
     throw new CliError("INVALID_MAX_WORDS", "--max-words must be a positive integer.");
   }
+  if (stopAfterSection && !sectionId && !goal) {
+    throw new CliError("MISSING_SECTION", "--stop-after-section requires --section/--section-id or --goal.");
+  }
+  if (sectionId) {
+    await validateSection(runtime, articleId, sectionId);
+  }
 
   if (booleanFlag(runtime.parsed.flags, "dry-run")) {
-    await dryRun(runtime, articleId, maxSpendAtomic, goal, maxWords);
+    await dryRun(runtime, articleId, maxSpendAtomic, goal, maxWords, sectionId, stopAfterSection, chunkWords, streamMode);
     return;
   }
 
   let finalReceipt = undefined;
+  let storedReceipt = undefined;
+  let currentSessionId: string | undefined;
+  let cancelled = false;
+  const abortOnSigint = (): void => {
+    cancelled = true;
+    process.exitCode = 130;
+    if (!runtime.json) {
+      process.stderr.write("\nCancelling read and aborting the active session...\n");
+    }
+    if (currentSessionId) {
+      void runtime.client.abort(currentSessionId, "agent_cancelled").catch(() => {});
+    }
+  };
+  process.once("SIGINT", abortOnSigint);
+
   const stream = runtime.client.read({
     articleId,
     goal,
+    sectionId,
     maxSpendAtomic,
     maxWords,
+    chunkWords,
+    streamMode,
+    metadata: stopAfterSection ? { stopAfterSection: true } : undefined,
   });
 
-  for await (const event of stream) {
-    if (runtime.json) {
-      printJsonEvent("event", { event });
-      if (event.type === "article.completed") {
-        finalReceipt = event.receipt;
+  try {
+    for await (const event of stream) {
+      if (event.type === "session.started") {
+        currentSessionId = event.session.sessionId;
+      }
+      if (runtime.json && !summary) {
+        printJsonEvent("event", { event });
+        if (event.type === "article.completed") {
+          finalReceipt = event.receipt;
+        }
+        continue;
       }
-      continue;
-    }
 
-    switch (event.type) {
-      case "seller.message":
-        process.stdout.write(`Seller: ${event.content}\n\n`);
-        break;
-      case "session.started":
-        process.stdout.write(`Session: ${event.session.sessionId}\n\n`);
-        break;
-      case "article.word":
-        process.stdout.write(`${event.word} `);
-        break;
-      case "article.error":
-        process.stderr.write(`\nError: ${event.message}\n`);
-        break;
-      case "article.completed":
-        finalReceipt = event.receipt;
-        process.stdout.write(`\n\n${humanReceipt(event.receipt)}\n`);
-        break;
-      case "article.usage":
+      if (runtime.json && summary) {
+        if (event.type === "article.completed") {
+          finalReceipt = event.receipt;
+        }
+        continue;
+      }
+
+      switch (event.type) {
+        case "seller.message":
+          if (!summary) process.stdout.write(`Seller: ${event.content}\n\n`);
+          break;
+        case "session.started":
+          if (!summary) process.stdout.write(`Session: ${event.session.sessionId}\n\n`);
+          break;
+        case "article.word":
+          if (!summary) process.stdout.write(`${event.word} `);
+          break;
+        case "article.bundle":
+        case "article.chunk":
+          if (!summary) process.stdout.write(`${event.words.map((entry) => entry.word).join(" ")} `);
+          break;
+        case "article.error":
+          process.stderr.write(`\nError: ${event.message}\n`);
+          break;
+        case "article.completed":
+          finalReceipt = event.receipt;
+          if (!summary) {
+            process.stdout.write(`\n\n${humanReceipt(event.receipt)}\n`);
+          }
+          break;
+        case "article.usage":
+          break;
+      }
+
+      if (cancelled) {
         break;
+      }
     }
+  } finally {
+    process.removeListener("SIGINT", abortOnSigint);
   }
 
   if (finalReceipt) {
-    const stored = await saveReceipt(finalReceipt);
+    storedReceipt = await saveReceipt(finalReceipt);
+    if (runtime.json && !summary) {
+      printJson({ type: "receipt.saved", success: true, receiptId: storedReceipt.receiptId, savedAt: storedReceipt.savedAt, receipt: storedReceipt.receipt });
+    } else if (!runtime.json && !summary) {
+      process.stdout.write(`Receipt ID: ${storedReceipt.receiptId}\n`);
+    }
+  }
+
+  if (summary && finalReceipt) {
     if (runtime.json) {
-      printJson({ type: "receipt.saved", success: true, receiptId: stored.receiptId, savedAt: stored.savedAt, receipt: stored.receipt });
+      printJson({
+        success: true,
+        receiptId: storedReceipt?.receiptId,
+        savedAt: storedReceipt?.savedAt,
+        receipt: readReceiptSummaryJson(finalReceipt),
+      });
+    } else {
+      process.stdout.write(`${humanReceiptSummary(finalReceipt, storedReceipt?.receiptId)}\n`);
     }
   }
 }
@@ -231,20 +324,54 @@ async function dryRun(
   maxSpendAtomic: `${bigint}`,
   goal: string | undefined,
   maxWords: number | undefined,
+  sectionId: string | undefined,
+  stopAfterSection: boolean,
+  chunkWords: number | undefined,
+  streamMode: StreamMode,
 ): Promise<void> {
   const article = await findArticle(runtime, articleId);
+  const navigation = goal && !sectionId ? await runtime.client.getNavigation(articleId, goal).catch(() => undefined) : undefined;
+  const effectiveSectionId = sectionId ?? navigation?.navigation.sellerAgent.recommendedSectionId;
+  const effectiveSection = effectiveSectionId ? findSection(article, effectiveSectionId) : undefined;
+  const estimatedWords = Math.min(maxWords ?? Number.MAX_SAFE_INTEGER, effectiveSection?.wordCount ?? article.totalWords);
+  const estimatedMaxCostAtomic = BigInt(article.pricePerWordAtomic) * BigInt(estimatedWords);
+  const budgetAtomic = BigInt(maxSpendAtomic);
+  const networkInfo = settlementNetworkInfo(article.paymentTerms?.network);
+  const fundingMethod = article.paymentTerms?.fundingMethod ?? networkInfo.fundingMethod;
+  const balanceCheck = {
+    checked: false,
+    sufficient: undefined,
+    reason: "Live Circle Gateway balance is not checked during dry-run.",
+  };
+  const budgetSufficiency = {
+    sufficientForEstimatedMax: budgetAtomic >= estimatedMaxCostAtomic,
+    estimatedMaxCostAtomic: `${estimatedMaxCostAtomic}`,
+    estimatedMaxCostUsdc: formatAtomic(`${estimatedMaxCostAtomic}`),
+    estimatedWords,
+  };
   if (runtime.json) {
     printJson({
       success: true,
       dryRun: true,
       gatewayUrl: runtime.gatewayUrl,
       paymentMode: runtime.paymentMode,
+      circleChain: article.paymentTerms?.circleChain ?? networkInfo.circleChain ?? runtime.circleChain,
       budget: {
         maxSpendAtomic,
         maxSpendUsdc: formatAtomic(maxSpendAtomic),
         maxWords,
       },
       goal,
+      sectionId,
+      recommendedSectionId: navigation?.navigation.sellerAgent.recommendedSectionId,
+      effectiveSectionId,
+      readStartsAt: effectiveSectionId ? `section:${effectiveSectionId}` : "full-article",
+      stopAfterSection,
+      chunkWords,
+      streamMode,
+      fundingMethod,
+      estimatedMax: budgetSufficiency,
+      walletBalance: balanceCheck,
       article: articleJson(article),
     });
     return;
@@ -255,9 +382,22 @@ async function dryRun(
       "Dry run: no paid read started.",
       `Gateway: ${runtime.gatewayUrl}`,
       `Payment mode: ${runtime.paymentMode}`,
+      article.paymentTerms?.circleChain ?? networkInfo.circleChain ?? runtime.circleChain
+        ? `Circle chain: ${article.paymentTerms?.circleChain ?? networkInfo.circleChain ?? runtime.circleChain}`
+        : undefined,
       `Budget: ${formatAtomic(maxSpendAtomic)} USDC (${maxSpendAtomic} atomic)`,
+      `Estimated max for ${effectiveSectionId ? effectiveSectionId : "full article"}: ${formatAtomic(`${estimatedMaxCostAtomic}`)} USDC (${estimatedWords.toLocaleString("en-US")} words)`,
+      `Budget covers estimate: ${budgetSufficiency.sufficientForEstimatedMax ? "yes" : "no"}`,
+      `Wallet balance check: not checked`,
+      fundingMethod ? `Funding: ${fundingMethod}` : undefined,
       maxWords ? `Max words: ${maxWords}` : undefined,
       goal ? `Goal: ${goal}` : undefined,
+      navigation?.navigation.sellerAgent.recommendedSectionId ? `Recommended section: ${navigation.navigation.sellerAgent.recommendedSectionId}` : undefined,
+      `Read starts at: ${effectiveSectionId ? `section ${effectiveSectionId}` : "full article"}`,
+      sectionId ? `Section: ${sectionId}` : undefined,
+      stopAfterSection ? "Stop after section: yes" : undefined,
+      `Stream mode: ${streamMode}`,
+      streamMode === "bundled" ? `Bundle words: ${chunkWords ?? 32}` : undefined,
       "",
       humanArticle(article),
       "",
@@ -268,9 +408,11 @@ async function dryRun(
 }
 
 async function receiptsList(runtime: Runtime): Promise<void> {
-  const receipts = await listReceipts();
+  const limit = limitFlag(runtime.parsed);
+  const receipts = (await listReceipts()).slice(0, limit);
+  const summary = booleanFlag(runtime.parsed.flags, "summary") || booleanFlag(runtime.parsed.flags, "receipt-summary");
   if (runtime.json) {
-    printJson({ success: true, receipts });
+    printJson({ success: true, receipts: summary ? receipts.map(receiptSummaryJson) : receipts });
     return;
   }
   if (receipts.length === 0) {
@@ -290,8 +432,13 @@ async function receiptsList(runtime: Runtime): Promise<void> {
 async function receiptsShow(runtime: Runtime, receiptId: string | undefined): Promise<void> {
   if (!receiptId) throw new CliError("MISSING_RECEIPT_ID", "rubicon receipts show requires a receipt id.");
   const stored = await loadReceipt(receiptId);
+  const summary = booleanFlag(runtime.parsed.flags, "summary") || booleanFlag(runtime.parsed.flags, "receipt-summary");
   if (runtime.json) {
-    printJson({ success: true, ...stored });
+    printJson({ success: true, ...(summary ? receiptSummaryJson(stored) : stored) });
+    return;
+  }
+  if (summary) {
+    process.stdout.write(`${humanReceiptSummary(stored.receipt, stored.receiptId)}\n`);
     return;
   }
   process.stdout.write(`Receipt ID: ${stored.receiptId}\nSaved: ${stored.savedAt}\n${humanReceipt(stored.receipt)}\n`);
@@ -309,6 +456,7 @@ async function configShow(runtime: Runtime): Promise<void> {
       gatewayUrl: runtime.gatewayUrl,
       apiKey: runtime.apiKey ? "set" : undefined,
       paymentMode: runtime.paymentMode,
+      circleChain: runtime.circleChain,
     },
   };
   if (runtime.json) {
@@ -381,6 +529,67 @@ function parseBudget(parsed: ParsedArgs): `${bigint}` {
   }
 }
 
+function sectionFlag(parsed: ParsedArgs): string | undefined {
+  const section = stringFlag(parsed.flags, "section");
+  const sectionId = stringFlag(parsed.flags, "section-id");
+  if (section && sectionId && section !== sectionId) {
+    throw new CliError("MULTIPLE_SECTIONS", "Use either --section or --section-id, not both.");
+  }
+  return section ?? sectionId;
+}
+
+function limitFlag(parsed: ParsedArgs): number | undefined {
+  const rawLimit = stringFlag(parsed.flags, "limit");
+  if (rawLimit === undefined) return undefined;
+  const limit = Number(rawLimit);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new CliError("INVALID_LIMIT", "--limit must be a positive integer.");
+  }
+  return limit;
+}
+
+function chunkWordsFlag(parsed: ParsedArgs): number | undefined {
+  const fast = booleanFlag(parsed.flags, "fast");
+  const mode = stringFlag(parsed.flags, "mode");
+  if (mode !== undefined && mode !== "batch" && mode !== "word") {
+    throw new CliError("INVALID_READ_MODE", "--mode must be batch or word.");
+  }
+  const rawChunkWords = stringFlag(parsed.flags, "chunk-words");
+  if (rawChunkWords === undefined) return fast || mode === "batch" ? 32 : undefined;
+  const chunkWords = Number(rawChunkWords);
+  if (!Number.isInteger(chunkWords) || chunkWords < 1) {
+    throw new CliError("INVALID_CHUNK_WORDS", "--chunk-words must be a positive integer.");
+  }
+  return Math.min(chunkWords, 256);
+}
+
+function streamModeFlag(parsed: ParsedArgs): StreamMode {
+  const streamMode = stringFlag(parsed.flags, "stream-mode");
+  const legacyMode = stringFlag(parsed.flags, "mode");
+  const perWord = booleanFlag(parsed.flags, "per-word");
+  if (streamMode !== undefined && streamMode !== "bundled" && streamMode !== "word") {
+    throw new CliError("INVALID_STREAM_MODE", "--stream-mode must be bundled or word.");
+  }
+  if (perWord && streamMode === "bundled") {
+    throw new CliError("INVALID_STREAM_MODE", "--per-word cannot be combined with --stream-mode bundled.");
+  }
+  if ((perWord || legacyMode === "word" || streamMode === "word") && stringFlag(parsed.flags, "chunk-words") !== undefined) {
+    throw new CliError("INVALID_STREAM_MODE", "Per-word mode cannot be combined with --chunk-words.");
+  }
+  return perWord || legacyMode === "word" ? "word" : streamMode ?? "bundled";
+}
+
+function findSection(article: ArticleSummary, sectionId: string): ArticleSectionSummary | undefined {
+  return article.sections.find((section) => section.sectionId === sectionId);
+}
+
+async function validateSection(runtime: Runtime, articleId: string, sectionId: string): Promise<void> {
+  const article = await findArticle(runtime, articleId);
+  if (!article.sections.some((section) => section.sectionId === sectionId)) {
+    throw new CliError("SECTION_NOT_FOUND", `Section not found for ${articleId}: ${sectionId}`);
+  }
+}
+
 function matchesQuery(article: ArticleSummary, query: string): boolean {
   const haystack = [
     article.articleId,
@@ -402,12 +611,14 @@ 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>\"",
-    "rubicon read <article-id> --max-usdc 0.10 [--goal \"...\"] [--max-words 50] [--dry-run]",
-    "rubicon receipts list",
-    "rubicon receipts show <receipt-id>",
+    "rubicon read <article-id> --max-usdc 0.10 [--goal \"...\"] [--section <section-id>] [--stop-after-section] [--stream-mode bundled|word] [--chunk-words 32] [--per-word] [--max-words 50] [--summary] [--dry-run]",
+    "rubicon receipts list [--limit 10] [--summary]",
+    "rubicon receipts show <receipt-id> [--summary]",
     "rubicon config show",
     "rubicon config set gateway-url <url>",
     "rubicon config set api-key <key>",

package/src/payments.ts

@@ -11,6 +11,7 @@ export type PaymentMode = "static" | "circle-cli";
 export interface PaymentSelection {
   mode: PaymentMode;
   engine: AgentPaymentEngine;
+  circleChain?: string;
 }
 
 export function selectPaymentEngine(input: {
@@ -25,12 +26,14 @@ export function selectPaymentEngine(input: {
     return { mode: selectedMode, engine: new StaticPaymentEngine() };
   }
 
+  const circleChain = process.env.CIRCLE_CLI_CHAIN ?? input.config.circleChain ?? "ARC-TESTNET";
   return {
     mode: selectedMode,
     engine: new CircleCliGatewayPaymentEngine({
       agentWalletAddress: envAddress("CIRCLE_AGENT_WALLET_ADDRESS") ?? input.config.agentWalletAddress,
-      chain: process.env.CIRCLE_CLI_CHAIN ?? input.config.circleChain ?? "ARC-TESTNET",
+      chain: circleChain,
     }),
+    circleChain,
   };
 }