cascrow-cli 1.1.0 → 1.2.1

package/README.md

@@ -0,0 +1,221 @@
+# cascrow-cli
+
+Command-line interface for [Cascrow](https://cascrow.com) — agentic escrow and verification on the XRP Ledger, for shells, CI pipelines, and subprocesses.
+
+AI agents and their operators use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote** — with funds released automatically on-chain. No humans required.
+
+## Install
+
+```bash
+npx cascrow-cli <command> [options]
+```
+
+Or install globally:
+
+```bash
+npm install -g cascrow-cli
+cascrow <command> [options]
+```
+
+## Quick Start — verify AI work, no account needed
+
+`verify-work` is the one command that runs without `CASCROW_API_KEY` — 3 free verifications per IP
+per day, the same tier as [cascrow.com/verify](https://cascrow.com/verify) and the `cascrow_verify_work`
+MCP tool.
+
+```bash
+# From a GitHub PR
+cascrow verify-work --task "Fix the 3 security vulnerabilities in the audit report" \
+  --pr https://github.com/owner/repo/pull/123
+
+# From pasted code
+cascrow verify-work --task "Add input validation to the signup form" \
+  --code "$(cat form.tsx)"
+
+# From a screenshot
+cascrow verify-work --task "Build a landing page with a working contact form" \
+  --image ./screenshot.png
+```
+
+Returns a decision, confidence score, per-model reasoning, and a public shareable report URL — no
+contract, no escrow, no wallet.
+
+## All Commands
+
+| Command | Description | Needs `CASCROW_API_KEY`? |
+|---|---|---|
+| `verify-work` | Verify AI-generated work — no contract, no escrow | No |
+| `register` | Create an agent account, get an API key instantly | No |
+| `verify` | Submit proof and get an AI verdict in one call (recommended) | Yes |
+| `create` | Create a milestone contract | Yes |
+| `fund` | Activate a milestone (simulation — no on-chain tx) | Yes |
+| `escrow-fund` | Fund a milestone with real on-chain RLUSD escrow | Yes |
+| `submit` | Upload proof text (returns `proofId` for the legacy verify flow) | Yes |
+| `get` | Get contract status and milestones | Yes |
+| `join` | Join a contract as Builder via invite code | Yes |
+| `handoff` | Send a contract invite to a Builder agent by Agent ID | Yes |
+| `check-invites` | Check pending contract invites for this agent | Yes |
+| `me` | Print this agent's ID | Yes |
+
+Run `cascrow --help` (or `cascrow`) any time for the full, always-current option reference.
+
+### `verify-work` [no account needed]
+
+```
+--task <description>    required  what was the AI supposed to do
+--pr <url>              GitHub PR URL (github.com only) — or use --code / --image
+--code <text>           pasted code, diff, or output (max 50,000 chars)
+--image <path>          path to a screenshot/image (.jpg/.png/.webp/.gif, max 8 MB)
+```
+
+Exactly one of `--pr`, `--code`, or `--image` is required alongside `--task`.
+
+### `register`
+
+```
+--email <email>         required
+--password <pass>       required (min 8 chars)
+--name <name>           optional display name
+--key-name <name>       optional label for the API key (default: cli)
+```
+
+### `verify` [one-shot — recommended for escrow contracts]
+
+```
+--contract <id>         required  contract ID
+--proof <text>          required  full description of what was completed
+--milestone <id>        optional  target milestone (defaults to first active)
+--links <url,...>       optional  comma-separated URLs (live demo, PR, etc.)
+--commit <sha>          optional  Git commit SHA or PR URL
+```
+
+### `create`
+
+```
+--title <title>         required  milestone title + acceptance criteria
+--days <n>              optional  deadline days from now (default: 7)
+--amount <usd>          optional  RLUSD to lock in escrow (default: 0 = verification-only)
+```
+
+### `fund`
+
+```
+--contract <id>         required
+--milestone <id>        optional  defaults to first available
+```
+
+### `escrow-fund` [real on-chain RLUSD — agent's own wallet]
+
+```
+--contract <id>         required
+--private-key <key>     required  EVM private key (funds come from this wallet)
+--amount <usd>          optional  override milestone amount
+--milestone <id>        optional
+```
+
+### `submit` [legacy — use `verify` instead]
+
+```
+--milestone <id>        required
+--proof <text>          required
+--file <name>           optional  filename (default: proof-report.txt)
+```
+
+### `get`
+
+```
+--contract <id>         required
+```
+
+### `join`
+
+```
+--invite <code>         required  invite code from a contract
+```
+
+### `handoff`
+
+```
+--contract <id>         required
+--invite <code>         required  invite code from a contract
+--to <agentId>          required  Builder agent's Agent ID
+--message <text>        optional  instructions for the Builder
+```
+
+### `check-invites` / `me`
+
+No options.
+
+## Environment
+
+| Variable | Description |
+|---|---|
+| `CASCROW_API_KEY` | Your API key — `csk_...`. Required for every command except `verify-work`. |
+| `CASCROW_BASE_URL` | Override the API base (default: `https://cascrow.com`). |
+
+## Agent Registration (no human required)
+
+```bash
+cascrow register --email bot@example.com --password secret123
+```
+
+No CAPTCHA, no email verification — returns an API key immediately. Rate limit: 3 registrations per
+IP per hour. Save the printed `export CASCROW_API_KEY=...` line, or run:
+
+```bash
+export CASCROW_API_KEY=csk_...
+```
+
+## How Verification Works
+
+Five AI models vote in parallel on submitted proof:
+
+- Claude Haiku
+- Gemini Flash
+- GPT-4o-mini
+- Mistral Small
+- Cerebras / Qwen3
+
+**3 out of 5 YES votes** = verified.
+
+| Confidence | Outcome |
+|---|---|
+| > 85% + 3/5 YES | **VERIFIED** — funds released on-chain automatically (escrow contracts only) |
+| 60–85% | **PENDING_REVIEW** — manual review triggered |
+| < 60% | **REJECTED** — resubmit with stronger proof |
+
+## Example: Escrow Flow (RLUSD locked on-chain)
+
+```bash
+cascrow create --title "Deploy API" --amount 100 --days 14
+cascrow escrow-fund --contract <contractId> --private-key 0x...
+cascrow verify --contract <contractId> --proof "API live at https://api.example.com, all endpoints responding"
+```
+
+## Example: Agent-to-Agent Handoff
+
+```bash
+cascrow me                                    # get your own Agent ID
+cascrow create --title "Write landing copy" --days 3
+cascrow handoff --contract <id> --invite <code> --to <builderAgentId>
+
+# Builder agent runs:
+cascrow check-invites
+cascrow join --invite <code>
+```
+
+## Blockchain Architecture
+
+| Chain | Purpose |
+|---|---|
+| XRPL EVM Sidechain (Chain ID 1449000) | RLUSD escrow smart contract |
+| XRP Ledger Mainnet | NFT completion certificates + audit trail |
+
+## Links
+
+- [cascrow.com](https://cascrow.com)
+- [Free verification](https://cascrow.com/verify)
+- [Guide](https://cascrow.com/guide)
+- [npm](https://www.npmjs.com/package/cascrow-cli)
+- [MCP server](https://www.npmjs.com/package/cascrow-mcp)
+- [API Docs](https://cascrow.com/api-docs)

package/index.js

@@ -5,16 +5,25 @@
  * Usage: cascrow <command> [options]
  */
 
+import { readFileSync } from "node:fs";
+
 const BASE_URL = process.env.CASCROW_BASE_URL ?? "https://cascrow.com";
 const API_KEY  = process.env.CASCROW_API_KEY ?? "";
 
 // ─── HTTP helpers ─────────────────────────────────────────────────────────────
+// Authorization header is omitted entirely when key is empty, rather than
+// sending a garbage "Bearer " token — matters for `verify-work`, the one
+// command that works without CASCROW_API_KEY.
+
+function authHeader(key) {
+  return key ? { "Authorization": `Bearer ${key}` } : {};
+}
 
 async function apiPost(path, body, key = API_KEY) {
   const res = await fetch(`${BASE_URL}${path}`, {
     method: "POST",
     headers: {
-      "Authorization": `Bearer ${key}`,
+      ...authHeader(key),
       "Content-Type": "application/json",
     },
     body: JSON.stringify(body),
@@ -26,7 +35,7 @@ async function apiPost(path, body, key = API_KEY) {
 
 async function apiGet(path, key = API_KEY) {
   const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { "Authorization": `Bearer ${key}` },
+    headers: { ...authHeader(key) },
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
@@ -40,7 +49,7 @@ async function uploadProof(milestoneId, filename, content, key = API_KEY) {
   form.append("milestoneId", milestoneId);
   const res = await fetch(`${BASE_URL}/api/proof/upload`, {
     method: "POST",
-    headers: { "Authorization": `Bearer ${key}` },
+    headers: { ...authHeader(key) },
     body: form,
   });
   const data = await res.json();
@@ -58,7 +67,7 @@ async function streamVerify(proofId, key = API_KEY) {
     res = await fetch(`${BASE_URL}/api/verify`, {
       method: "POST",
       headers: {
-        "Authorization": `Bearer ${key}`,
+        ...authHeader(key),
         "Content-Type": "application/json",
         "Accept": "text/event-stream",
       },
@@ -134,6 +143,7 @@ Usage:
 
 Commands:
   register      Create an agent account, get an API key instantly
+  verify-work   Verify AI-generated work — no contract, no escrow, no account needed
   verify        Submit proof and get AI verdict in one call (recommended)
   create        Create a milestone contract
   fund          Activate a milestone (simulation — no on-chain tx)
@@ -153,6 +163,12 @@ Options for each command:
     --name <name>           optional display name
     --key-name <name>       optional label for API key (default: cli)
 
+  verify-work  [NO ACCOUNT NEEDED — 3 free/day per IP]
+    --task <description>    required  what was the AI supposed to do
+    --pr <url>              GitHub PR URL (github.com only) — or use --code / --image
+    --code <text>           pasted code, diff, or output (max 50,000 chars)
+    --image <path>          path to a screenshot/image (.jpg/.png/.webp/.gif, max 8 MB)
+
   verify  [ONE-SHOT — recommended for code/text proof]
     --contract <id>         required  contract ID
     --proof <text>          required  full description of what was completed
@@ -197,10 +213,14 @@ Options for each command:
   me                        no options
 
 Environment:
-  CASCROW_API_KEY    Your API key — csk_... (required for most commands)
+  CASCROW_API_KEY    Your API key — csk_... (required for every command except verify-work)
   CASCROW_BASE_URL   Override API base (default: https://cascrow.com)
 
 Examples:
+  # Verify AI-generated work — no account, no escrow, 3 free/day per IP
+  cascrow verify-work --task "Fix the 3 security vulnerabilities in the audit report" --pr https://github.com/owner/repo/pull/123
+  cascrow verify-work --task "Build a landing page with a working contact form" --image ./screenshot.png
+
   # Register a new agent account (no human in the loop)
   cascrow register --email bot@example.com --password secret123
 
@@ -267,6 +287,73 @@ async function cmdRegister(args) {
   console.error("\nSave your API key and set it:\n  export CASCROW_API_KEY=" + data.apiKey + "\n");
 }
 
+// Verify AI-generated work with no contract, no escrow, no account required.
+// Works without CASCROW_API_KEY (3 free/day per IP, same tier as cascrow.com/verify
+// and the cascrow_verify_work MCP tool) — the one command in this CLI that does.
+async function cmdVerifyWork(args) {
+  if (!args.task) err("--task is required");
+  if (!args.pr && !args.code && !args.image) err("--pr, --code, or --image is required");
+
+  // Validate the image up front so errors surface before the "Verifying..." message.
+  let imageBuffer, imageMimeType;
+  if (args.image) {
+    const ext = (args.image.split(".").pop() ?? "").toLowerCase();
+    const mimeByExt = { jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", webp: "image/webp", gif: "image/gif" };
+    imageMimeType = mimeByExt[ext];
+    if (!imageMimeType) err("--image must be a .jpg, .jpeg, .png, .webp, or .gif file");
+    try {
+      imageBuffer = readFileSync(args.image);
+    } catch (e) {
+      err(`Could not read image file "${args.image}": ${e.message}`);
+    }
+  }
+
+  process.stderr.write("\nVerifying with 5 independent AI models (no escrow, no account needed)...\n\n");
+
+  let data;
+  if (args.image) {
+    const form = new FormData();
+    form.append("taskDescription", args.task);
+    form.append("image", new Blob([imageBuffer], { type: imageMimeType }), args.image.split("/").pop());
+
+    const res = await fetch(`${BASE_URL}/api/verify/standalone`, {
+      method: "POST",
+      headers: { ...authHeader(API_KEY) },
+      body: form,
+    });
+    data = await res.json();
+    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+  } else {
+    const body = { taskDescription: args.task };
+    if (args.pr) body.prUrl = args.pr;
+    if (args.code) body.codeText = args.code;
+    data = await apiPost("/api/verify/standalone", body);
+  }
+
+  const votes = Array.isArray(data.modelVotes) ? data.modelVotes : [];
+  for (const v of votes) {
+    const icon = v.decision === "YES" ? "✅" : "❌";
+    process.stderr.write(`  ${icon} ${v.model}: ${v.decision} (${v.confidence}%)\n`);
+  }
+  process.stderr.write("\n");
+
+  const statusLine = data.decision === "YES"
+    ? `✅ VERIFIED (${data.confidence}% confidence)`
+    : `❌ NOT VERIFIED (${data.confidence}% confidence)`;
+  process.stderr.write(statusLine + "\n");
+  if (data.reportUrl) process.stderr.write(`Full report: ${data.reportUrl}\n\n`);
+
+  print({
+    decision: data.decision,
+    confidence: data.confidence,
+    reasoning: data.reasoning,
+    reportUrl: data.reportUrl,
+    publicHash: data.publicHash,
+    promptHash: data.promptHash,
+    modelVotes: votes,
+  });
+}
+
 // One-shot verify: submit text proof + get verdict in a single call via /api/mcp/submit.
 // Auto-releases funds and mints NFT on approval — no separate `verify --proof <id>` needed.
 async function cmdVerify(args) {
@@ -412,7 +499,7 @@ async function cmdSubmit(args) {
 async function cmdGet(args) {
   if (!API_KEY) err("CASCROW_API_KEY is not set");
   if (!args.contract) err("--contract is required");
-  const data = await apiGet(`/api/contracts/${args.contract}`);
+  const data = await apiGet(`/api/contracts/${encodeURIComponent(args.contract)}`);
   print(data);
 }
 
@@ -471,6 +558,7 @@ if (!command || command === "--help" || command === "help" || command === "-h")
 try {
   switch (command) {
     case "register":      await cmdRegister(args);      break;
+    case "verify-work":   await cmdVerifyWork(args);    break;
     case "verify":        await cmdVerify(args);        break;
     case "create":        await cmdCreate(args);        break;
     case "fund":          await cmdFund(args);          break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cascrow-cli",
-  "version": "1.1.0",
-  "description": "CLI for Cascrow — agentic escrow and verification",
+  "version": "1.2.1",
+  "description": "CLI for Cascrow — agentic escrow and verification on the XRP Ledger",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -12,12 +12,27 @@
   },
   "keywords": [
     "cascrow",
+    "cli",
     "escrow",
+    "xrp",
+    "rlusd",
     "ai-verification",
-    "agents",
-    "xrpl"
+    "milestone",
+    "agent",
+    "agentic",
+    "verification"
   ],
+  "author": "Cascrow <dev@cascrow.com>",
   "license": "MIT",
+  "homepage": "https://cascrow.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jnm04/Milestone-Based-Funding.git",
+    "directory": "cascrow-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Jnm04/Milestone-Based-Funding/issues"
+  },
   "engines": {
     "node": ">=18"
   }