@fiber-pay/cli 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/cli.js

@@ -965,13 +965,13 @@ import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, wr
 import { join as join3 } from "path";
 
 // src/lib/config-templates.ts
-var TESTNET_CONFIG_TEMPLATE_V061 = `# This configuration file only contains the necessary configurations for the testnet deployment.
+var TESTNET_CONFIG_TEMPLATE_V071 = `# This configuration file only contains the necessary configurations for the testnet deployment.
 # All options' descriptions can be found via \`fnn --help\` and be overridden by command line arguments or environment variables.
 fiber:
-  listening_addr: "/ip4/127.0.0.1/tcp/8228"
+  listening_addr: "/ip4/0.0.0.0/tcp/8228"
   bootnode_addrs:
     - "/ip4/54.179.226.154/tcp/8228/p2p/Qmes1EBD4yNo9Ywkfe6eRw9tG1nVNGLDmMud1xJMsoYFKy"
-    - "/ip4/54.179.226.154/tcp/18228/p2p/QmdyQWjPtbK4NWWsvy8s69NGJaQULwgeQDT5ZpNDrTNaeV"
+    - "/ip4/16.163.7.105/tcp/8228/p2p/QmdyQWjPtbK4NWWsvy8s69NGJaQULwgeQDT5ZpNDrTNaeV"
   announce_listening_addr: true
   announced_addrs:
     # If you want to announce your fiber node public address to the network, you need to add the address here, please change the ip to your public ip accordingly.
@@ -1037,7 +1037,7 @@ services:
   - rpc
   - ckb
 `;
-var MAINNET_CONFIG_TEMPLATE_V061 = `# This configuration file only contains the necessary configurations for the mainnet deployment.
+var MAINNET_CONFIG_TEMPLATE_V071 = `# This configuration file only contains the necessary configurations for the mainnet deployment.
 # All options' descriptions can be found via \`fnn --help\` and be overridden by command line arguments or environment variables.
 fiber:
   listening_addr: "/ip4/0.0.0.0/tcp/8228"
@@ -1113,7 +1113,7 @@ services:
   - ckb
 `;
 function getConfigTemplate(network) {
-  return network === "mainnet" ? MAINNET_CONFIG_TEMPLATE_V061 : TESTNET_CONFIG_TEMPLATE_V061;
+  return network === "mainnet" ? MAINNET_CONFIG_TEMPLATE_V071 : TESTNET_CONFIG_TEMPLATE_V071;
 }
 
 // src/lib/config.ts
@@ -2032,7 +2032,7 @@ import { existsSync as existsSync6 } from "fs";
 import { Command as Command6 } from "commander";
 
 // src/lib/log-files.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { closeSync, createReadStream, existsSync as existsSync5, openSync, readSync, statSync } from "fs";
 import { join as join4 } from "path";
 function resolvePersistedLogPaths(dataDir, meta) {
   return {
@@ -2068,9 +2068,80 @@ function readLastLines(filePath, maxLines) {
   if (!existsSync5(filePath)) {
     return [];
   }
-  const content = readFileSync5(filePath, "utf-8");
-  const lines = content.split(/\r?\n/).filter((line) => line.length > 0);
-  return lines.slice(-maxLines);
+  if (!Number.isFinite(maxLines) || maxLines <= 0) {
+    return [];
+  }
+  let fd;
+  try {
+    fd = openSync(filePath, "r");
+    const size = statSync(filePath).size;
+    if (size <= 0) {
+      return [];
+    }
+    const chunkSize = 64 * 1024;
+    let position = size;
+    const chunks = [];
+    let newlineCount = 0;
+    while (position > 0 && newlineCount <= maxLines) {
+      const start = Math.max(0, position - chunkSize);
+      const bytesToRead = position - start;
+      const buffer = Buffer.alloc(bytesToRead);
+      const bytesRead = readSync(fd, buffer, 0, bytesToRead, start);
+      const chunk = buffer.toString("utf8", 0, bytesRead);
+      chunks.unshift(chunk);
+      for (let index = 0; index < chunk.length; index += 1) {
+        if (chunk.charCodeAt(index) === 10) {
+          newlineCount += 1;
+        }
+      }
+      position = start;
+    }
+    const content = chunks.join("");
+    const lines = content.split(/\r?\n/).filter((line) => line.length > 0);
+    return lines.slice(-maxLines);
+  } finally {
+    if (fd !== void 0) {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+  }
+}
+async function readAppendedLines(filePath, offset, remainder = "") {
+  if (!existsSync5(filePath)) {
+    return { lines: [], nextOffset: 0, remainder: "" };
+  }
+  const size = statSync(filePath).size;
+  const safeOffset = size < offset ? 0 : offset;
+  if (safeOffset >= size) {
+    return { lines: [], nextOffset: size, remainder };
+  }
+  const stream = createReadStream(filePath, {
+    encoding: "utf8",
+    start: safeOffset,
+    end: size - 1
+  });
+  const lines = [];
+  let pending = remainder;
+  let bytesReadTotal = 0;
+  for await (const chunk of stream) {
+    const chunkText = String(chunk);
+    bytesReadTotal += Buffer.byteLength(chunkText, "utf8");
+    const merged = `${pending}${chunkText}`;
+    const parts = merged.split(/\r?\n/);
+    pending = parts.pop() ?? "";
+    for (const line of parts) {
+      if (line.length > 0) {
+        lines.push(line);
+      }
+    }
+  }
+  return {
+    lines,
+    nextOffset: safeOffset + bytesReadTotal,
+    remainder: pending
+  };
 }
 
 // src/commands/job.ts
@@ -2388,7 +2459,7 @@ ${title}: ${filePath}`);
 }
 
 // src/commands/logs.ts
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync7, statSync as statSync2 } from "fs";
 import { formatRuntimeAlert } from "@fiber-pay/runtime";
 import { Command as Command7 } from "commander";
 var ALLOWED_SOURCES = /* @__PURE__ */ new Set([
@@ -2550,7 +2621,8 @@ Following logs (interval: ${intervalMs}ms). Press Ctrl+C to stop.`);
         {
           title: entry.title,
           path: entry.path,
-          seenLines: entry.exists ? entry.lines.length : 0
+          offset: entry.exists ? statSync2(entry.path).size : 0,
+          remainder: ""
         }
       ])
     );
@@ -2565,26 +2637,41 @@ Following logs (interval: ${intervalMs}ms). Press Ctrl+C to stop.`);
         console.log("\nStopped following logs.");
         resolve2();
       };
+      let polling = false;
       const timer = setInterval(() => {
-        for (const target of targets) {
-          const state = states.get(target.source);
-          if (!state) continue;
-          if (!existsSync7(state.path)) {
-            continue;
-          }
-          const allLines = readLastLines(state.path, Number.MAX_SAFE_INTEGER);
-          const total = allLines.length;
-          const fromIndex = total < state.seenLines ? 0 : state.seenLines;
-          const newLines = allLines.slice(fromIndex);
-          if (newLines.length === 0) {
-            continue;
-          }
-          for (const line of newLines) {
-            const output = target.source === "runtime" ? formatRuntimeAlertHuman(line) : line;
-            console.log(`[${state.title}] ${output}`);
-          }
-          state.seenLines = total;
+        if (polling) {
+          return;
         }
+        polling = true;
+        void (async () => {
+          for (const target of targets) {
+            const state = states.get(target.source);
+            if (!state) continue;
+            if (!existsSync7(state.path)) {
+              state.offset = 0;
+              state.remainder = "";
+              continue;
+            }
+            const result = await readAppendedLines(state.path, state.offset, state.remainder);
+            const newLines = result.lines;
+            if (newLines.length === 0) {
+              state.offset = result.nextOffset;
+              state.remainder = result.remainder;
+              continue;
+            }
+            for (const line of newLines) {
+              const output = target.source === "runtime" ? formatRuntimeAlertHuman(line) : line;
+              console.log(`[${state.title}] ${output}`);
+            }
+            state.offset = result.nextOffset;
+            state.remainder = result.remainder;
+          }
+        })().catch((error) => {
+          const message = error instanceof Error ? error.message : "Failed to read appended logs";
+          console.error(`Error: ${message}`);
+        }).finally(() => {
+          polling = false;
+        });
       }, intervalMs);
       process.on("SIGINT", stop);
       process.on("SIGTERM", stop);
@@ -2596,11 +2683,122 @@ Following logs (interval: ${intervalMs}ms). Press Ctrl+C to stop.`);
 import { nodeIdToPeerId as nodeIdToPeerId2, scriptToAddress as scriptToAddress2 } from "@fiber-pay/sdk";
 import { Command as Command8 } from "commander";
 
+// src/lib/node-start.ts
+import { spawn } from "child_process";
+import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
+import { join as join5 } from "path";
+import {
+  createKeyManager,
+  ensureFiberBinary,
+  getDefaultBinaryPath,
+  ProcessManager
+} from "@fiber-pay/node";
+import { startRuntimeService } from "@fiber-pay/runtime";
+
+// src/lib/bootnode.ts
+import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
+import { parse as parseYaml } from "yaml";
+function extractBootnodeAddrs(configFilePath) {
+  if (!existsSync8(configFilePath)) return [];
+  try {
+    const content = readFileSync5(configFilePath, "utf-8");
+    const doc = parseYaml(content);
+    const addrs = doc?.fiber?.bootnode_addrs;
+    if (!Array.isArray(addrs)) return [];
+    return addrs.filter((a) => typeof a === "string" && a.startsWith("/ip"));
+  } catch {
+    return [];
+  }
+}
+async function autoConnectBootnodes(rpc, bootnodes) {
+  if (bootnodes.length === 0) return;
+  console.log(`\u{1F517} Connecting to ${bootnodes.length} bootnode(s)...`);
+  for (const addr of bootnodes) {
+    const shortId = addr.match(/\/p2p\/(.+)$/)?.[1]?.slice(0, 12) || addr.slice(-12);
+    try {
+      await rpc.connectPeer({ address: addr });
+      console.log(`   \u2705 Connected to ${shortId}...`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.toLowerCase().includes("already")) {
+        console.log(`   \u2705 Already connected to ${shortId}...`);
+      } else {
+        console.error(`   \u26A0\uFE0F  Failed to connect to ${shortId}...: ${msg}`);
+      }
+    }
+  }
+}
+
+// src/lib/node-migration.ts
+import { dirname } from "path";
+import { BinaryManager, MigrationManager } from "@fiber-pay/node";
+
+// src/lib/migration-utils.ts
+function replaceRawMigrateHint(message) {
+  return message.replace(
+    /Fiber need to run some database migrations, please run `fnn-migrate[^`]*` to start migrations\.?/g,
+    "Fiber database migration is required."
+  );
+}
+function normalizeMigrationCheck(check) {
+  return {
+    ...check,
+    message: replaceRawMigrateHint(check.message)
+  };
+}
+
+// src/lib/node-migration.ts
+async function runMigrationGuard(opts) {
+  const { dataDir, binaryPath, json } = opts;
+  if (!MigrationManager.storeExists(dataDir)) {
+    return { checked: false, skippedReason: "store does not exist" };
+  }
+  const storePath = MigrationManager.resolveStorePath(dataDir);
+  const binaryDir = dirname(binaryPath);
+  const bm = new BinaryManager(binaryDir);
+  const migrateBinPath = bm.getMigrateBinaryPath();
+  let migrationCheck;
+  try {
+    const migrationManager = new MigrationManager(migrateBinPath);
+    migrationCheck = await migrationManager.check(storePath);
+  } catch {
+    return { checked: false, skippedReason: "fnn-migrate binary not available" };
+  }
+  if (migrationCheck.needed) {
+    const message = migrationCheck.valid ? "Database migration required. Run `fiber-pay node upgrade --force-migrate` before starting." : replaceRawMigrateHint(migrationCheck.message);
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_REQUIRED",
+        message,
+        recoverable: true,
+        suggestion: `Back up your store first (directory: "${storePath}"). Then run \`fiber-pay node upgrade --force-migrate\`. If migration still fails, close channels on the old fnn version, remove the store, and restart with a fresh store. If backup exists, restore it to roll back.`,
+        details: {
+          storePath,
+          migrationCheck: {
+            ...migrationCheck,
+            message
+          }
+        }
+      });
+    } else {
+      console.error(`\u274C ${message}`);
+      console.error(`   1) Back up store directory: ${storePath}`);
+      console.error("   2) Run: fiber-pay node upgrade --force-migrate");
+      console.error(
+        "   3) If it still fails, close channels on old fnn, remove store, then restart."
+      );
+      console.error("   4) If backup exists, restore it to roll back.");
+    }
+    process.exit(1);
+  }
+  return { checked: true, migrationCheck };
+}
+
 // src/lib/node-runtime-daemon.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync9 } from "fs";
 function getCustomBinaryState(binaryPath) {
-  const exists = existsSync8(binaryPath);
+  const exists = existsSync9(binaryPath);
   if (!exists) {
     return { path: binaryPath, ready: false, version: "unknown" };
   }
@@ -2690,52 +2888,6 @@ function stopRuntimeDaemonFromNode(params) {
   );
 }
 
-// src/lib/node-start.ts
-import { spawn } from "child_process";
-import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
-import { join as join5 } from "path";
-import {
-  ensureFiberBinary,
-  getDefaultBinaryPath,
-  ProcessManager
-} from "@fiber-pay/node";
-import { startRuntimeService } from "@fiber-pay/runtime";
-import { createKeyManager } from "@fiber-pay/sdk";
-
-// src/lib/bootnode.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
-import { parse as parseYaml } from "yaml";
-function extractBootnodeAddrs(configFilePath) {
-  if (!existsSync9(configFilePath)) return [];
-  try {
-    const content = readFileSync6(configFilePath, "utf-8");
-    const doc = parseYaml(content);
-    const addrs = doc?.fiber?.bootnode_addrs;
-    if (!Array.isArray(addrs)) return [];
-    return addrs.filter((a) => typeof a === "string" && a.startsWith("/ip"));
-  } catch {
-    return [];
-  }
-}
-async function autoConnectBootnodes(rpc, bootnodes) {
-  if (bootnodes.length === 0) return;
-  console.log(`\u{1F517} Connecting to ${bootnodes.length} bootnode(s)...`);
-  for (const addr of bootnodes) {
-    const shortId = addr.match(/\/p2p\/(.+)$/)?.[1]?.slice(0, 12) || addr.slice(-12);
-    try {
-      await rpc.connectPeer({ address: addr });
-      console.log(`   \u2705 Connected to ${shortId}...`);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (msg.toLowerCase().includes("already")) {
-        console.log(`   \u2705 Already connected to ${shortId}...`);
-      } else {
-        console.error(`   \u26A0\uFE0F  Failed to connect to ${shortId}...: ${msg}`);
-      }
-    }
-  }
-}
-
 // src/lib/node-start.ts
 async function runNodeStartCommand(config, options) {
   const json = Boolean(options.json);
@@ -2864,6 +3016,19 @@ async function runNodeStartCommand(config, options) {
     console.log(`\u{1F9E9} Binary: ${binaryPath}`);
     console.log(`\u{1F9E9} Version: ${binaryVersion}`);
   }
+  const guardResult = await runMigrationGuard({ dataDir: config.dataDir, binaryPath, json });
+  if (guardResult.checked) {
+    emitStage("migration_check", "ok", {
+      storePath: `${config.dataDir}/store`,
+      needed: false
+    });
+  } else {
+    emitStage("migration_check", "ok", {
+      storePath: `${config.dataDir}/store`,
+      skipped: true,
+      reason: guardResult.skippedReason
+    });
+  }
   const nodeConfig = {
     binaryPath,
     dataDir: config.dataDir,
@@ -3634,67 +3799,334 @@ async function runNodeReadyCommand(config, options) {
   }
 }
 
-// src/commands/node.ts
-function createNodeCommand(config) {
-  const node = new Command8("node").description("Node management");
-  node.command("start").option("--daemon", "Start node in detached background mode (node + runtime)").option("--runtime-proxy-listen <host:port>", "Runtime monitor proxy listen address").option("--event-stream <format>", "Event stream format for --json mode (jsonl)", "jsonl").option("--quiet-fnn", "Do not mirror fnn stdout/stderr to console; keep file persistence").option("--json").action(async (options) => {
-    await runNodeStartCommand(config, options);
-  });
-  node.command("stop").option("--json").action(async (options) => {
-    const json = Boolean(options.json);
-    const runtimeMeta = readRuntimeMeta(config.dataDir);
-    const runtimePid = readRuntimePid(config.dataDir);
-    if (runtimeMeta?.daemon && runtimePid && isProcessRunning(runtimePid)) {
-      stopRuntimeDaemonFromNode({ dataDir: config.dataDir, rpcUrl: config.rpcUrl });
+// src/lib/node-stop.ts
+async function runNodeStopCommand(config, options) {
+  const json = Boolean(options.json);
+  const runtimeMeta = readRuntimeMeta(config.dataDir);
+  const runtimePid = readRuntimePid(config.dataDir);
+  if (runtimeMeta?.daemon && runtimePid && isProcessRunning(runtimePid)) {
+    stopRuntimeDaemonFromNode({ dataDir: config.dataDir, rpcUrl: config.rpcUrl });
+  }
+  removeRuntimeFiles(config.dataDir);
+  const pid = readPidFile(config.dataDir);
+  if (!pid) {
+    if (json) {
+      printJsonError({
+        code: "NODE_NOT_RUNNING",
+        message: "No PID file found. Node may not be running.",
+        recoverable: true,
+        suggestion: "Run `fiber-pay node start` first if you intend to stop a node."
+      });
+    } else {
+      console.log("\u274C No PID file found. Node may not be running.");
     }
-    removeRuntimeFiles(config.dataDir);
-    const pid = readPidFile(config.dataDir);
-    if (!pid) {
-      if (json) {
-        printJsonError({
-          code: "NODE_NOT_RUNNING",
-          message: "No PID file found. Node may not be running.",
-          recoverable: true,
-          suggestion: "Run `fiber-pay node start` first if you intend to stop a node."
-        });
-      } else {
-        console.log("\u274C No PID file found. Node may not be running.");
-      }
-      process.exit(1);
+    process.exit(1);
+  }
+  if (!isProcessRunning(pid)) {
+    if (json) {
+      printJsonError({
+        code: "NODE_NOT_RUNNING",
+        message: `Process ${pid} is not running. Cleaning up PID file.`,
+        recoverable: true,
+        suggestion: "Start the node again if needed; stale PID has been cleaned.",
+        details: { pid, stalePidFileCleaned: true }
+      });
+    } else {
+      console.log(`\u274C Process ${pid} is not running. Cleaning up PID file.`);
     }
-    if (!isProcessRunning(pid)) {
-      if (json) {
-        printJsonError({
-          code: "NODE_NOT_RUNNING",
-          message: `Process ${pid} is not running. Cleaning up PID file.`,
-          recoverable: true,
-          suggestion: "Start the node again if needed; stale PID has been cleaned.",
-          details: { pid, stalePidFileCleaned: true }
-        });
-      } else {
-        console.log(`\u274C Process ${pid} is not running. Cleaning up PID file.`);
+    removePidFile(config.dataDir);
+    process.exit(1);
+  }
+  if (!json) {
+    console.log(`\u{1F6D1} Stopping node (PID: ${pid})...`);
+  }
+  process.kill(pid, "SIGTERM");
+  let attempts = 0;
+  while (isProcessRunning(pid) && attempts < 30) {
+    await new Promise((resolve2) => setTimeout(resolve2, 100));
+    attempts++;
+  }
+  if (isProcessRunning(pid)) {
+    process.kill(pid, "SIGKILL");
+  }
+  removePidFile(config.dataDir);
+  if (json) {
+    printJsonSuccess({ pid, stopped: true });
+  } else {
+    console.log("\u2705 Node stopped.");
+  }
+}
+
+// src/lib/node-upgrade.ts
+import { BinaryManager as BinaryManager2, MigrationManager as MigrationManager2 } from "@fiber-pay/node";
+async function runNodeUpgradeCommand(config, options) {
+  const json = Boolean(options.json);
+  const installDir = `${config.dataDir}/bin`;
+  const binaryManager = new BinaryManager2(installDir);
+  const pid = readPidFile(config.dataDir);
+  if (pid && isProcessRunning(pid)) {
+    const msg = "The Fiber node is currently running. Stop it before upgrading.";
+    if (json) {
+      printJsonError({
+        code: "NODE_RUNNING",
+        message: msg,
+        recoverable: true,
+        suggestion: "Run `fiber-pay node stop` first, then retry the upgrade."
+      });
+    } else {
+      console.error(`\u274C ${msg}`);
+      console.log("   Run: fiber-pay node stop");
+    }
+    process.exit(1);
+  }
+  let targetTag;
+  if (options.version) {
+    targetTag = binaryManager.normalizeTag(options.version);
+  } else {
+    if (!json) console.log("\u{1F50D} Resolving latest Fiber release...");
+    targetTag = await binaryManager.getLatestTag();
+  }
+  if (!json) console.log(`\u{1F4E6} Target version: ${targetTag}`);
+  const currentInfo = await binaryManager.getBinaryInfo();
+  const targetVersion = targetTag.startsWith("v") ? targetTag.slice(1) : targetTag;
+  const storePath = MigrationManager2.resolveStorePath(config.dataDir);
+  const migrateBinaryPath = binaryManager.getMigrateBinaryPath();
+  let migrationCheck = null;
+  const storeExists = MigrationManager2.storeExists(config.dataDir);
+  if (!json && storeExists) {
+    console.log("\u{1F4C2} Existing store detected.");
+  }
+  if (currentInfo.ready && currentInfo.version === targetVersion && !options.forceMigrate) {
+    if (storeExists) {
+      migrationCheck = await runMigrationAndReport({
+        migrateBinaryPath,
+        storePath,
+        json,
+        checkOnly: Boolean(options.checkOnly),
+        targetVersion,
+        backup: options.backup !== false,
+        forceMigrateAttempt: false
+      });
+    }
+    const msg = migrationCheck ? `Already installed ${targetTag}. Store compatibility checked.` : `Already installed ${targetTag}. Use --force-migrate to run migration flow anyway.`;
+    if (json) {
+      printJsonSuccess({
+        action: "none",
+        currentVersion: currentInfo.version,
+        targetVersion,
+        message: msg,
+        migration: migrationCheck
+      });
+    } else {
+      console.log(`\u2705 ${msg}`);
+    }
+    return;
+  }
+  const versionMatches = currentInfo.ready && currentInfo.version === targetVersion;
+  const shouldDownload = !versionMatches;
+  if (!json && currentInfo.ready) {
+    console.log(`   Current version: v${currentInfo.version}`);
+  }
+  if (shouldDownload) {
+    if (!json && storeExists) {
+      console.log("\u{1F4C2} Existing store detected, will check migration after download.");
+    }
+    if (!json) console.log("\u2B07\uFE0F  Downloading new binary...");
+    const showProgress2 = (progress) => {
+      if (!json) {
+        const percent = progress.percent !== void 0 ? ` (${progress.percent}%)` : "";
+        process.stdout.write(`\r   [${progress.phase}]${percent} ${progress.message}`.padEnd(80));
+        if (progress.phase === "installing") console.log();
       }
-      removePidFile(config.dataDir);
-      process.exit(1);
+    };
+    await binaryManager.download({
+      version: targetTag,
+      force: true,
+      onProgress: showProgress2
+    });
+  } else if (!json && options.forceMigrate) {
+    console.log("\u23ED\uFE0F  Skipping binary download: target version is already installed.");
+    console.log("\u{1F501} --force-migrate enabled: attempting migration flow on existing binaries.");
+  }
+  if (storeExists) {
+    migrationCheck = await runMigrationAndReport({
+      migrateBinaryPath,
+      storePath,
+      json,
+      checkOnly: Boolean(options.checkOnly),
+      targetVersion,
+      backup: options.backup !== false,
+      forceMigrateAttempt: Boolean(options.forceMigrate)
+    });
+  }
+  const newInfo = await binaryManager.getBinaryInfo();
+  if (json) {
+    printJsonSuccess({
+      action: "upgraded",
+      previousVersion: currentInfo.ready ? currentInfo.version : null,
+      currentVersion: newInfo.version,
+      binaryPath: newInfo.path,
+      migrateBinaryPath,
+      migration: migrationCheck
+    });
+  } else {
+    console.log("\n\u2705 Upgrade complete!");
+    console.log(`   Version: v${newInfo.version}`);
+    console.log(`   Binary:  ${newInfo.path}`);
+    console.log("\n   Start the node with: fiber-pay node start");
+  }
+}
+async function runMigrationAndReport(opts) {
+  const {
+    migrateBinaryPath,
+    storePath,
+    json,
+    checkOnly,
+    targetVersion,
+    backup,
+    forceMigrateAttempt
+  } = opts;
+  let migrationManager;
+  try {
+    migrationManager = new MigrationManager2(migrateBinaryPath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "fnn-migrate binary not available";
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_TOOL_MISSING",
+        message: msg,
+        recoverable: true,
+        suggestion: "Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      });
+    } else {
+      console.error(`
+\u26A0\uFE0F  ${msg}`);
+      console.log(
+        "   Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      );
     }
-    if (!json) {
-      console.log(`\u{1F6D1} Stopping node (PID: ${pid})...`);
+    process.exit(1);
+  }
+  if (!json) console.log("\u{1F50D} Checking store compatibility...");
+  let migrationCheck;
+  try {
+    migrationCheck = await migrationManager.check(storePath);
+  } catch (checkErr) {
+    const msg = checkErr instanceof Error ? checkErr.message : String(checkErr);
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_TOOL_MISSING",
+        message: `Migration check failed: ${msg}`,
+        recoverable: true,
+        suggestion: "Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      });
+    } else {
+      console.error(`
+\u26A0\uFE0F  Migration check failed: ${msg}`);
+      console.log(
+        "   Run `fiber-pay node upgrade` to reinstall binaries, then retry `fiber-pay node upgrade --force-migrate`."
+      );
     }
-    process.kill(pid, "SIGTERM");
-    let attempts = 0;
-    while (isProcessRunning(pid) && attempts < 30) {
-      await new Promise((resolve2) => setTimeout(resolve2, 100));
-      attempts++;
+    process.exit(1);
+  }
+  if (checkOnly) {
+    const normalizedCheck = normalizeMigrationCheck(migrationCheck);
+    if (json) {
+      printJsonSuccess({
+        action: "check-only",
+        targetVersion,
+        migration: normalizedCheck
+      });
+    } else {
+      console.log(`
+\u{1F4CB} Migration status: ${normalizedCheck.message}`);
     }
-    if (isProcessRunning(pid)) {
-      process.kill(pid, "SIGKILL");
+    process.exit(0);
+  }
+  if (!migrationCheck.needed) {
+    if (!json) console.log("   Store is compatible, no migration needed.");
+    return normalizeMigrationCheck(migrationCheck);
+  }
+  if (!migrationCheck.valid && !forceMigrateAttempt) {
+    const normalizedMessage = replaceRawMigrateHint(migrationCheck.message);
+    if (json) {
+      printJsonError({
+        code: "MIGRATION_INCOMPATIBLE",
+        message: normalizedMessage,
+        recoverable: false,
+        suggestion: `Back up your store first (directory: "${storePath}"). Then run \`fiber-pay node upgrade --force-migrate\`. If it still fails, close all channels with the old fnn version, remove the store, and restart with a fresh store. If you attempted migration with backup enabled, you can roll back by restoring the backup directory.`,
+        details: {
+          storePath,
+          migrationCheck: {
+            ...migrationCheck,
+            message: normalizedMessage
+          }
+        }
+      });
+    } else {
+      console.error("\n\u274C Store migration is not possible automatically.");
+      console.log(normalizedMessage);
+      console.log(`   1) Back up store directory: ${storePath}`);
+      console.log("   2) Try: fiber-pay node upgrade --force-migrate");
+      console.log(
+        "   3) If it still fails, close channels on old fnn, remove store, then restart."
+      );
+      console.log("   4) If migration created a backup, you can roll back by restoring it.");
     }
-    removePidFile(config.dataDir);
+    process.exit(1);
+  }
+  if (!migrationCheck.valid && !json) {
+    console.log("\u26A0\uFE0F  Store check reported incompatibility, but --force-migrate is set.");
+    console.log("   Attempting migration anyway with backup enabled (unless --no-backup).");
+  }
+  if (!json) console.log("\u{1F504} Running database migration...");
+  const result = await migrationManager.migrate({
+    storePath,
+    backup,
+    force: forceMigrateAttempt
+  });
+  if (!result.success) {
     if (json) {
-      printJsonSuccess({ pid, stopped: true });
+      printJsonError({
+        code: "MIGRATION_FAILED",
+        message: result.message,
+        recoverable: !!result.backupPath,
+        suggestion: result.backupPath ? `To roll back, delete the current store at "${storePath}" and restore the backup from "${result.backupPath}".` : "Re-download the previous version or start fresh.",
+        details: { output: result.output, backupPath: result.backupPath }
+      });
     } else {
-      console.log("\u2705 Node stopped.");
+      console.error("\n\u274C Migration failed.");
+      console.log(result.message);
     }
+    process.exit(1);
+  }
+  if (!json) {
+    console.log(`\u2705 ${result.message}`);
+    if (result.backupPath) {
+      console.log(`   Backup: ${result.backupPath}`);
+    }
+  }
+  try {
+    const postCheck = await migrationManager.check(storePath);
+    return normalizeMigrationCheck(postCheck);
+  } catch (err) {
+    if (!json) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("\u26A0\uFE0F  Post-migration check failed; final migration status may be stale.");
+      console.error(`   ${message}`);
+    }
+    return normalizeMigrationCheck(migrationCheck);
+  }
+}
+
+// src/commands/node.ts
+function createNodeCommand(config) {
+  const node = new Command8("node").description("Node management");
+  node.command("start").option("--daemon", "Start node in detached background mode (node + runtime)").option("--runtime-proxy-listen <host:port>", "Runtime monitor proxy listen address").option("--event-stream <format>", "Event stream format for --json mode (jsonl)", "jsonl").option("--quiet-fnn", "Do not mirror fnn stdout/stderr to console; keep file persistence").option("--json").action(async (options) => {
+    await runNodeStartCommand(config, options);
+  });
+  node.command("stop").option("--json").action(async (options) => {
+    await runNodeStopCommand(config, options);
   });
   node.command("status").option("--json").action(async (options) => {
     await runNodeStatusCommand(config, options);
@@ -3725,6 +4157,12 @@ function createNodeCommand(config) {
       printNodeInfoHuman(output);
     }
   });
+  node.command("upgrade").description("Upgrade the Fiber node binary and migrate the database if needed").option("--version <version>", "Target Fiber version (default: latest)").option("--no-backup", "Skip creating a store backup before migration").option("--check-only", "Only check if migration is needed, do not migrate").option(
+    "--force-migrate",
+    "Force migration attempt even when compatibility check reports incompatible data"
+  ).option("--json").action(async (options) => {
+    await runNodeUpgradeCommand(config, options);
+  });
   return node;
 }
 
@@ -4488,8 +4926,8 @@ function createRuntimeCommand(config) {
 import { Command as Command12 } from "commander";
 
 // src/lib/build-info.ts
-var CLI_VERSION = "0.1.0-rc.2";
-var CLI_COMMIT = "d44bf1937f40ea65c0a1e63ed3bc17d732248fb0";
+var CLI_VERSION = "0.1.0-rc.4";
+var CLI_COMMIT = "20dc82d290856d411382a4ec30f912b913b4f956";
 
 // src/commands/version.ts
 function createVersionCommand() {
@@ -4507,6 +4945,55 @@ function createVersionCommand() {
   });
 }
 
+// src/lib/argv.ts
+var GLOBAL_OPTIONS_WITH_VALUE = /* @__PURE__ */ new Set([
+  "--profile",
+  "--data-dir",
+  "--rpc-url",
+  "--network",
+  "--key-password",
+  "--binary-path"
+]);
+function isOptionToken(token) {
+  return token.startsWith("-") && token !== "-";
+}
+function hasInlineValue(token) {
+  return token.includes("=");
+}
+function getFirstPositional(argv) {
+  for (let index = 2; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === "--") {
+      return argv[index + 1];
+    }
+    if (!isOptionToken(token)) {
+      return token;
+    }
+    if (GLOBAL_OPTIONS_WITH_VALUE.has(token) && !hasInlineValue(token)) {
+      const next = argv[index + 1];
+      if (next && !isOptionToken(next)) {
+        index++;
+      }
+    }
+  }
+  return void 0;
+}
+function hasTopLevelVersionFlag(argv) {
+  for (let index = 2; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === "--") {
+      return false;
+    }
+    if (token === "--version" || token === "-v") {
+      return true;
+    }
+  }
+  return false;
+}
+function isTopLevelVersionRequest(argv) {
+  return !getFirstPositional(argv) && hasTopLevelVersionFlag(argv);
+}
+
 // src/index.ts
 function shouldOutputJson() {
   return process.argv.includes("--json");
@@ -4608,10 +5095,15 @@ function printFatal(error) {
   }
 }
 async function main() {
-  applyGlobalOverrides(process.argv);
+  const argv = process.argv;
+  if (isTopLevelVersionRequest(argv)) {
+    console.log(`${CLI_VERSION} (${CLI_COMMIT})`);
+    return;
+  }
+  applyGlobalOverrides(argv);
   const config = getEffectiveConfig(explicitFlags).config;
   const program = new Command13();
-  program.name("fiber-pay").description("AI Agent Payment SDK for CKB Lightning Network").version(`${CLI_VERSION} (${CLI_COMMIT})`, "-v, --version", "Show version and commit id").option("--profile <name>", "Use profile at ~/.fiber-pay/profiles/<name>").option("--data-dir <path>", "Override data directory for all commands").option("--rpc-url <url>", "Override RPC URL for all commands").option("--network <network>", "Override network for all commands (testnet|mainnet)").option("--key-password <password>", "Override key password for all commands").option("--binary-path <path>", "Override fiber binary path for all commands").showHelpAfterError().showSuggestionAfterError();
+  program.name("fiber-pay").description("AI Agent Payment SDK for CKB Lightning Network").option("--profile <name>", "Use profile at ~/.fiber-pay/profiles/<name>").option("--data-dir <path>", "Override data directory for all commands").option("--rpc-url <url>", "Override RPC URL for all commands").option("--network <network>", "Override network for all commands (testnet|mainnet)").option("--key-password <password>", "Override key password for all commands").option("--binary-path <path>", "Override fiber binary path for all commands").showHelpAfterError().showSuggestionAfterError();
   program.exitOverride();
   program.configureOutput({
     writeOut: (str) => process.stdout.write(str),
@@ -4633,7 +5125,7 @@ async function main() {
   program.addCommand(createConfigCommand(config));
   program.addCommand(createRuntimeCommand(config));
   program.addCommand(createVersionCommand());
-  await program.parseAsync(process.argv);
+  await program.parseAsync(argv);
 }
 main().catch((error) => {
   const commanderCode = error && typeof error === "object" && "code" in error ? String(error.code) : void 0;