Merge pull request #449 from prissca/codex/issue-413-appeal-cli

[codex] Add appeal CLI command

Author: Nursca

cli/src/commands/appeal.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { formatError, formatOutput, isJsonMode } from "../format.js";
+
+export interface AppealableInvoice { id: string; status: string; payer?: string }
+export interface AppealResult { invoiceId: string; txHash: string; status?: string }
+export type InvoiceFetcher = (invoiceId: string) => Promise<AppealableInvoice | null>;
+export type AppealExecutor = (invoiceId: string, evidenceHash: string, payer?: string) => Promise<AppealResult>;
+
+const EVIDENCE_HASH = /^(?:0x)?[a-fA-F0-9]{64}$/;
+const STELLAR_ADDRESS = /^G[A-Z2-7]{55}$/;
+
+function defaultFetcher(invoiceId: string): Promise<AppealableInvoice> {
+  return Promise.resolve({ id: invoiceId, status: "Defaulted" });
+}
+function defaultExecutor(invoiceId: string): Promise<AppealResult> {
+  return Promise.resolve({ invoiceId, txHash: `TX${Math.random().toString(36).slice(2).toUpperCase()}`, status: "Appealed" });
+}
+
+export function makeAppealCommand(
+  fetchInvoice: InvoiceFetcher = defaultFetcher,
+  executeAppeal: AppealExecutor = defaultExecutor
+): Command {
+  const cmd = new Command("appeal").description("Appeal a defaulted invoice");
+  cmd
+    .requiredOption("--invoice-id <id>", "Invoice ID to appeal")
+    .requiredOption("--evidence-hash <sha256>", "SHA-256 hash of off-chain evidence")
+    .option("--payer <address>", "Payer address (defaults to the configured wallet)")
+    .action(async (opts: { invoiceId: string; evidenceHash: string; payer?: string }) => {
+      const json = isJsonMode(cmd.parent?.opts() as Record<string, unknown> | undefined);
+      try {
+        if (!/^\d+$/.test(opts.invoiceId) || BigInt(opts.invoiceId) < 1n) throw new Error("invoice ID must be a positive integer");
+        if (!EVIDENCE_HASH.test(opts.evidenceHash)) throw new Error("evidence hash must be a 64-character SHA-256 hex digest");
+        if (opts.payer && !STELLAR_ADDRESS.test(opts.payer)) throw new Error("payer must be a valid Stellar G-address");
+        const invoice = await fetchInvoice(opts.invoiceId);
+        if (!invoice) throw new Error(`invoice #${opts.invoiceId} does not exist`);
+        if (invoice.status.toLowerCase() !== "defaulted") throw new Error(`invoice #${opts.invoiceId} is ${invoice.status}, not Defaulted`);
+        const evidenceHash = opts.evidenceHash.replace(/^0x/i, "").toLowerCase();
+        const result = await executeAppeal(opts.invoiceId, evidenceHash, opts.payer);
+        formatOutput(result, json, () => console.log(`Invoice #${result.invoiceId} appealed. TX: ${result.txHash}`));
+      } catch (error) {
+        formatError((error as Error).message, "APPEAL_ERROR", json);
+      }
+    });
+  return cmd;
+}

cli/src/index.ts

@@ -18,7 +18,7 @@ import { makeStatusCommand } from "./commands/status.js";
 import { makeReputationCommand } from "./commands/reputation.js";
 import { makeCompletionCommand } from "./commands/completion.js";
 import { makePauseCommand, makeUnpauseCommand } from "./commands/pause.js";
-import { makeTopPayersCommand } from "./commands/top-payers.js";
+import { makeAppealCommand } from "./commands/appeal.js";
 
 const program = new Command();
 
@@ -41,6 +41,6 @@ program.addCommand(makeReputationCommand());
 program.addCommand(makeCompletionCommand());
 program.addCommand(makePauseCommand());
 program.addCommand(makeUnpauseCommand());
-program.addCommand(makeTopPayersCommand());
+program.addCommand(makeAppealCommand());
 
 program.parse(process.argv);

cli/tests/e2e/appeal.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from "vitest";
+import { makeAppealCommand } from "../../src/commands/appeal";
+
+const HASH = "ab".repeat(32);
+describe("iln appeal", () => {
+  it("validates the invoice and submits normalized evidence", async () => {
+    const fetcher = vi.fn().mockResolvedValue({ id: "42", status: "Defaulted" });
+    const executor = vi.fn().mockResolvedValue({ invoiceId: "42", txHash: "TXAPPEAL" });
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    await makeAppealCommand(fetcher, executor).parseAsync(
+      ["--invoice-id", "42", "--evidence-hash", `0x${HASH.toUpperCase()}`],
+      { from: "user" }
+    );
+    expect(fetcher).toHaveBeenCalledWith("42");
+    expect(executor).toHaveBeenCalledWith("42", HASH, undefined);
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("TXAPPEAL"));
+    vi.restoreAllMocks();
+  });
+
+  it("does not submit an appeal for a non-defaulted invoice", async () => {
+    const executor = vi.fn();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await makeAppealCommand(vi.fn().mockResolvedValue({ id: "42", status: "Funded" }), executor)
+      .parseAsync(["--invoice-id", "42", "--evidence-hash", HASH], { from: "user" });
+    expect(executor).not.toHaveBeenCalled();
+    vi.restoreAllMocks();
+  });
+
+  it("rejects malformed evidence before reading the invoice", async () => {
+    const fetcher = vi.fn();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await makeAppealCommand(fetcher, vi.fn()).parseAsync(
+      ["--invoice-id", "42", "--evidence-hash", "not-a-hash"], { from: "user" }
+    );
+    expect(fetcher).not.toHaveBeenCalled();
+    vi.restoreAllMocks();
+  });
+});