routstrd 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "routstrd",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "module": "src/index.ts",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -35,6 +35,13 @@ import {
 } from "./daemon/wallet/coco-client";
 import { migrateLegacyWallet } from "./daemon/wallet/migration";
 import {
+  diagnoseWallets,
+  renderWalletDoctor,
+  summarizeWalletDirectory,
+  WalletMigrationConflictError,
+} from "./daemon/wallet/diagnostics";
+import {
+  legacyCocodDir,
   legacyCocodPidPath,
   legacyCocodSocketPath,
   walletDir as defaultWalletDir,
@@ -242,27 +249,19 @@ async function initDaemon(): Promise<void> {
   console.log(`Database will be stored at: ${DB_PATH}`);
   await stopLegacyCocod();
 
-  let migrationLockOwner: number | undefined;
   const migration = await migrateLegacyWallet({
     assertLegacyStopped: () =>
       assertLegacyCocodNotRunning({
         socketPath: legacyCocodSocketPath(),
-        pidFilePath: legacyCocodPidPath(),
-        ignorePid: migrationLockOwner,
       }),
     acquireLegacyLock: () => {
       mkdirSync(dirname(legacyCocodPidPath()), {
         recursive: true,
         mode: 0o700,
       });
-      const release = claimLegacyCocodPidFile({
+      return claimLegacyCocodPidFile({
         pidFilePath: legacyCocodPidPath(),
       });
-      migrationLockOwner = process.pid;
-      return () => {
-        migrationLockOwner = undefined;
-        release();
-      };
     },
   });
   if (migration.status === "migrated") {
@@ -349,7 +348,7 @@ program
   .description("Refund pending tokens and API keys to a specified mint")
   .option(
     "-m, --mint-url <mintUrl>",
-    "Mint URL to refund to (defaults to first mint in wallet)",
+    "Mint URL to refund to (defaults to active wallet mint)",
   )
   .option("-y, --yes", "Skip confirmation prompt", false)
   .option("--xcashu", "Refund xcashu tokens only (uses refundXcashuTokens)", false)
@@ -363,18 +362,19 @@ program
         console.log(balanceResult.error);
         process.exit(1);
       }
-      const balances = (
-        balanceResult.output as
-          | {
-              balances?: Record<string, number>;
-            }
-          | undefined
-      )?.balances;
-      if (!balances || Object.keys(balances).length === 0) {
+      const output = balanceResult.output as
+        | {
+            balances?: Record<string, number>;
+            activeMint?: string;
+          }
+        | undefined;
+      mintUrl =
+        output?.activeMint ??
+        (output?.balances ? Object.keys(output.balances)[0] : undefined);
+      if (!mintUrl) {
         console.log("No mint URLs found in wallet balance");
         process.exit(1);
       }
-      mintUrl = Object.keys(balances)[0];
       console.log(`Using mint URL: ${mintUrl}`);
     }
 
@@ -578,7 +578,17 @@ program
   )
   .action(async () => {
     await requireLocalDaemon();
-    await initDaemon();
+    try {
+      await initDaemon();
+    } catch (error) {
+      // An expected, user-actionable refusal — print the structured message
+      // without Bun's unhandled-rejection source snippet and stack trace.
+      if (error instanceof WalletMigrationConflictError) {
+        console.error(error.message);
+        process.exit(1);
+      }
+      throw error;
+    }
   });
 
 // Start - start the background daemon
@@ -592,11 +602,18 @@ program
     await requireLocalDaemon();
     const config = await loadConfig();
     await stopLegacyCocod();
-    await startDaemon({
-      port: options.port || String(config.port || 8008),
-      host: options.host || config.host || undefined,
-      provider: options.provider,
-    });
+    try {
+      await startDaemon({
+        port: options.port || String(config.port || 8008),
+        host: options.host || config.host || undefined,
+        provider: options.provider,
+      });
+    } catch (error) {
+      // startDaemon embeds the failed daemon's own output in the message
+      // (including the wallet-conflict report), so print it without a stack.
+      console.error(error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
   });
 
 // Status - check daemon status
@@ -641,7 +658,7 @@ program
   )
   .option(
     "--mint-url <url>",
-    "Mint URL to refund the deleted API key balance to (defaults to first mint in wallet)",
+    "Mint URL to refund the deleted API key balance to (defaults to active wallet mint)",
   )
   .action(async (options: { apiKeys: boolean; deleteApiKeys?: string; mintUrl?: string }) => {
     await ensureDaemonRunning();
@@ -1531,6 +1548,16 @@ walletCmd
     await handleDaemonCommand("/wallet/status");
   });
 
+walletCmd
+  .command("doctor")
+  .description("Diagnose conflicting wallets (current routstrd wallet vs legacy cocod)")
+  .action(async () => {
+    const target = summarizeWalletDirectory(defaultWalletDir(), "canonical");
+    const source = summarizeWalletDirectory(legacyCocodDir(), "legacy");
+    console.log(renderWalletDoctor(target, source));
+    if (diagnoseWallets(target, source).conflict) process.exit(1);
+  });
+
 walletCmd
   .command("unlock <passphrase>")
   .description("Unlock the wallet")
@@ -1548,6 +1575,113 @@ walletCmd
     await handleDaemonCommand("/wallet/balance");
   });
 
+walletCmd
+  .command("cleanup")
+  .description("Clear stuck pending/in-flight wallet operations")
+  .option("--mint-url <url>", "Only clean up operations for this mint URL")
+  .option(
+    "--min-age <hours>",
+    "Minimum age for reclaiming sends/cancelling melts, in hours (default: 168, one week; expired mint quotes are always failed)",
+    "168",
+  )
+  .option("--dry-run", "Report what would be cleaned without applying changes", false)
+  .option("-y, --yes", "Skip confirmation prompt", false)
+  .action(
+    async (options: {
+      mintUrl?: string;
+      minAge: string;
+      dryRun: boolean;
+      yes: boolean;
+    }) => {
+      const minAgeHours = Number.parseFloat(options.minAge);
+      if (!Number.isFinite(minAgeHours) || minAgeHours < 0) {
+        console.error(`Invalid --min-age value: ${options.minAge}`);
+        process.exit(1);
+      }
+
+      if (!options.dryRun && !options.yes) {
+        const rl = require("readline").createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        });
+        const answer = await new Promise<string>((resolve) => {
+          rl.question(
+            "This will fail expired mint quotes, reclaim old pending sends, and cancel prepared melts. Continue? [y/N] ",
+            (value: string) => {
+              rl.close();
+              resolve(value.trim().toLowerCase());
+            },
+          );
+        });
+        if (answer !== "y" && answer !== "yes") {
+          console.log("Aborted.");
+          return;
+        }
+      }
+
+      try {
+        await ensureDaemonRunning();
+
+        const result = await callDaemon("/wallet/cleanup", {
+          method: "POST",
+          body: {
+            mintUrl: options.mintUrl,
+            minAgeMs: Math.round(minAgeHours * 60 * 60 * 1000),
+            dryRun: options.dryRun === true,
+          },
+        });
+
+        if (result.error) {
+          console.log(result.error);
+          process.exit(1);
+        }
+
+        const output = result.output as
+          | {
+              dryRun?: boolean;
+              failedMintQuotes?: number;
+              reclaimedSends?: number;
+              cancelledMelts?: number;
+              skipped?: number;
+              errors?: Array<{ operationId: string; error: string }>;
+            }
+          | undefined;
+
+        if (output) {
+          const prefix = output.dryRun ? "Would clean up:" : "Cleaned up:";
+          console.log(prefix);
+          console.log(
+            `  Expired mint quotes failed: ${output.failedMintQuotes ?? 0}`,
+          );
+          console.log(`  Pending sends reclaimed: ${output.reclaimedSends ?? 0}`);
+          console.log(
+            `  Prepared melts cancelled: ${output.cancelledMelts ?? 0}`,
+          );
+          console.log(
+            `  Skipped (still recent or already terminal): ${output.skipped ?? 0}`,
+          );
+          if (output.errors && output.errors.length > 0) {
+            console.log("\nErrors:");
+            for (const e of output.errors) {
+              console.log(`  - ${e.operationId}: ${e.error}`);
+            }
+          }
+        }
+      } catch (error) {
+        const message = (error as Error).message;
+        if (
+          message?.includes("fetch failed") ||
+          message?.includes("Connection refused")
+        ) {
+          console.error("Daemon is not running");
+          process.exit(1);
+        }
+        console.error(message);
+        process.exit(1);
+      }
+    },
+  );
+
 const walletReceiveCmd = walletCmd
   .command("receive")
   .description("Wallet receive operations");

package/src/daemon/fatal-error.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { unlinkSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { exitOnUncaughtException } from "./fatal-error";
+
+const fatalErrorModule = JSON.stringify(join(import.meta.dir, "fatal-error.ts"));
+
+const fixturePaths: string[] = [];
+
+afterEach(() => {
+  while (fixturePaths.length > 0) {
+    try {
+      unlinkSync(fixturePaths.pop()!);
+    } catch {
+      // Best effort cleanup of temp fixtures.
+    }
+  }
+});
+
+/** Run a fixture script in a real subprocess so process.exit is for real. */
+async function runFixture(source: string): Promise<{
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}> {
+  const scriptPath = join(
+    tmpdir(),
+    `routstrd-fatal-error-fixture-${crypto.randomUUID()}.ts`,
+  );
+  fixturePaths.push(scriptPath);
+  await Bun.write(scriptPath, source);
+  const proc = Bun.spawn(["bun", scriptPath], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  return { exitCode, stdout, stderr };
+}
+
+describe("exitOnUncaughtException", () => {
+  test("reports the error and exits with code 1", () => {
+    let exitCode: number | undefined;
+    const stderrLines: string[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      stderrLines.push(args.map(String).join(" "));
+    };
+    try {
+      exitOnUncaughtException(new Error("boom"), (code) => {
+        exitCode = code;
+      });
+    } finally {
+      console.error = originalConsoleError;
+    }
+    expect(exitCode).toBe(1);
+    expect(stderrLines.join("\n")).toContain("boom");
+  });
+
+  test("handles non-Error thrown values", () => {
+    let exitCode: number | undefined;
+    const originalConsoleError = console.error;
+    console.error = () => {};
+    try {
+      exitOnUncaughtException("string failure", (code) => {
+        exitCode = code;
+      });
+    } finally {
+      console.error = originalConsoleError;
+    }
+    expect(exitCode).toBe(1);
+  });
+});
+
+describe("installGlobalErrorHandlers (subprocess)", () => {
+  test("an uncaught exception exits the process with code 1", async () => {
+    const { exitCode, stderr } = await runFixture(`
+      import { installGlobalErrorHandlers } from ${fatalErrorModule};
+      installGlobalErrorHandlers();
+      setTimeout(() => {
+        throw new Error("boom-uncaught");
+      }, 10);
+    `);
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("boom-uncaught");
+  });
+
+  test("an unhandled rejection is logged without exiting", async () => {
+    const { exitCode, stdout } = await runFixture(`
+      import { installGlobalErrorHandlers } from ${fatalErrorModule};
+      installGlobalErrorHandlers();
+      Promise.reject(new Error("boom-rejection"));
+      setTimeout(() => {
+        console.log("STILL-ALIVE");
+      }, 50);
+    `);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("STILL-ALIVE");
+  });
+});

package/src/daemon/fatal-error.ts

@@ -0,0 +1,48 @@
+import { logger } from "../utils/logger";
+
+/**
+ * Report an unrecoverable error, then exit.
+ *
+ * The daemon runs detached under a supervisor (pm2 via `routstrd service
+ * install`, or the spawning CLI). An uncaught exception means the call stack
+ * unwound unexpectedly mid-operation and process state can no longer be
+ * trusted. Swallowing it once left a daemon alive with nothing listening
+ * while it held both wallet PID locks, so every later start failed on the
+ * lock and liveness-only supervisors never restarted it. Exiting lets the
+ * supervisor bring up a healthy process instead.
+ *
+ * The file logger writes synchronously, so the record survives the exit.
+ * The error is mirrored to stderr because the daemon's stdout/stderr are
+ * redirected to debug.log, which is what the CLI surfaces when the daemon
+ * exits early and what pm2 captures. process.exit() runs the synchronous
+ * PID-lock exit hooks registered by claimPidFile, releasing the wallet
+ * locks on the way out.
+ *
+ * `exit` is injectable for tests.
+ */
+export function exitOnUncaughtException(
+  error: unknown,
+  exit: (code: number) => void = (code) => process.exit(code),
+): void {
+  logger.error("UNCAUGHT EXCEPTION:", error);
+  // Full error object (not just .message): this path means a bug, so the
+  // stack is the most useful thing to have in debug.log.
+  console.error("UNCAUGHT EXCEPTION:", error);
+  exit(1);
+}
+
+/**
+ * Install the process-level error handlers. Called once at daemon module
+ * load, before main() runs.
+ *
+ * Only uncaught exceptions are fatal. An unhandled rejection means a
+ * promise's failure went unobserved; the stack was not unwound and the
+ * process is still in a consistent state, so it is logged and the daemon
+ * keeps serving.
+ */
+export function installGlobalErrorHandlers(): void {
+  process.on("uncaughtException", (error) => exitOnUncaughtException(error));
+  process.on("unhandledRejection", (reason) => {
+    logger.error("UNHANDLED REJECTION:", reason);
+  });
+}

package/src/daemon/wallet/auto-refill.ts

@@ -66,8 +66,6 @@ export function startAutoRefillLoop(
       return;
     }
 
-    checkInProgress = true;
-
     // If we've been failing too much, back off rather than retrying at full speed.
     // This prevents tight loops on transient errors.
     const backoffInterval = Math.min(
@@ -78,6 +76,8 @@ export function startAutoRefillLoop(
       return;
     }
 
+    checkInProgress = true;
+
     try {
       const balances = await cocod.getBalances();
       const totalBalance = Object.values(balances).reduce<number>(
@@ -94,11 +94,9 @@ export function startAutoRefillLoop(
         `[auto-refill] Balance ${totalBalance} sats < threshold ${config.threshold}. Refilling ${config.amount} sats...`,
       );
 
-      // Get active mint
-      const mints = await cocod.listMints();
-      const mintUrl = mints[0];
+      const mintUrl = await cocod.getDefaultMint();
       if (!mintUrl) {
-        logger.error("[auto-refill] No active mint configured");
+        logger.error("[auto-refill] No default mint configured");
         return;
       }
 

package/src/daemon/wallet/cleanup.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "bun:test";
+import { selectCleanupOperations } from "./cleanup";
+
+const NOW_MS = 1_800_000_000_000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function mint(overrides: Record<string, unknown>) {
+  return {
+    id: "mint-1",
+    state: "pending",
+    expiry: NOW_MS / 1000 - 1000, // expired
+    updatedAt: NOW_MS - 2 * DAY_MS,
+    lastObservedRemoteState: undefined,
+    ...overrides,
+  };
+}
+
+function send(overrides: Record<string, unknown>) {
+  return {
+    id: "send-1",
+    state: "pending",
+    updatedAt: NOW_MS - 2 * DAY_MS,
+    ...overrides,
+  };
+}
+
+function melt(overrides: Record<string, unknown>) {
+  return {
+    id: "melt-1",
+    state: "prepared",
+    updatedAt: NOW_MS - 2 * DAY_MS,
+    ...overrides,
+  };
+}
+
+describe("selectCleanupOperations", () => {
+  it("selects expired pending mint quotes that are old enough", () => {
+    const result = selectCleanupOperations({
+      mints: [mint({ id: "a" })],
+      sends: [],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.mintsToFail.map((op) => op.id)).toEqual(["a"]);
+  });
+
+  it("ignores mint quotes that have not expired", () => {
+    const result = selectCleanupOperations({
+      mints: [mint({ id: "a", expiry: NOW_MS / 1000 + 1000 })],
+      sends: [],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.mintsToFail).toEqual([]);
+  });
+
+  it("ignores expired mint quotes already observed as PAID", () => {
+    const result = selectCleanupOperations({
+      mints: [mint({ id: "a", lastObservedRemoteState: "PAID" })],
+      sends: [],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.mintsToFail).toEqual([]);
+  });
+
+  it("ignores expired mint quotes already observed as ISSUED", () => {
+    const result = selectCleanupOperations({
+      mints: [mint({ id: "a", lastObservedRemoteState: "ISSUED" })],
+      sends: [],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.mintsToFail).toEqual([]);
+  });
+
+  it("ignores mint quotes without an expiry", () => {
+    const result = selectCleanupOperations({
+      mints: [mint({ id: "a", expiry: 0 })],
+      sends: [],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.mintsToFail).toEqual([]);
+  });
+
+  it("selects expired mint quotes even when the watcher recently touched them", () => {
+    const result = selectCleanupOperations({
+      mints: [mint({ id: "a", updatedAt: NOW_MS - 60_000 })],
+      sends: [],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.mintsToFail.map((op) => op.id)).toEqual(["a"]);
+  });
+
+  it("selects stale pending sends for reclaim", () => {
+    const result = selectCleanupOperations({
+      mints: [],
+      sends: [send({ id: "s" })],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.sendsToReclaim.map((op) => op.id)).toEqual(["s"]);
+  });
+
+  it("ignores recent pending sends", () => {
+    const result = selectCleanupOperations({
+      mints: [],
+      sends: [send({ id: "s", updatedAt: NOW_MS - 60_000 })],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.sendsToReclaim).toEqual([]);
+  });
+
+  it("ignores non-pending sends even when old", () => {
+    const result = selectCleanupOperations({
+      mints: [],
+      sends: [send({ id: "s", state: "executing" })],
+      melts: [],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.sendsToReclaim).toEqual([]);
+  });
+
+  it("selects stale prepared melts for cancellation", () => {
+    const result = selectCleanupOperations({
+      mints: [],
+      sends: [],
+      melts: [melt({ id: "m" })],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.meltsToCancel.map((op) => op.id)).toEqual(["m"]);
+  });
+
+  it("ignores non-prepared melts", () => {
+    const result = selectCleanupOperations({
+      mints: [],
+      sends: [],
+      melts: [melt({ id: "m", state: "pending" })],
+      nowMs: NOW_MS,
+      minAgeMs: DAY_MS,
+    });
+
+    expect(result.meltsToCancel).toEqual([]);
+  });
+});