@xerg/cli 0.1.9 → 0.1.10

package/dist/index.js

@@ -4,6 +4,112 @@
 import { readFileSync as readFileSync7 } from "fs";
 import { styleText as styleText2 } from "util";
 
+// src/command-display.ts
+var PACKAGE_NAME = "@xerg/cli";
+var DEFAULT_COMMAND_PREFIX = "xerg";
+function resolveCommandDisplay(context) {
+  const runner = detectPackageExecutor(context);
+  if (!runner) {
+    return {
+      prefix: DEFAULT_COMMAND_PREFIX,
+      name: DEFAULT_COMMAND_PREFIX
+    };
+  }
+  return {
+    prefix: `${runner} ${PACKAGE_NAME}`,
+    name: PACKAGE_NAME
+  };
+}
+function formatCommand(command2, commandPrefix = resolveCommandDisplay().prefix) {
+  const suffix = Array.isArray(command2) ? command2.join(" ") : command2;
+  return suffix ? `${commandPrefix} ${suffix}` : commandPrefix;
+}
+function detectPackageExecutor(context) {
+  const env = context?.env ?? process.env;
+  const argv2 = context?.argv ?? process.argv;
+  const userAgent = normalizeSignal(env.npm_config_user_agent);
+  const execPath = normalizeSignal(env.npm_execpath);
+  const argvPath = normalizeSignal(argv2[1]);
+  const fromArgvPath = detectRunnerFromArgvPath(argvPath);
+  if (fromArgvPath) {
+    return fromArgvPath;
+  }
+  if (looksLikeInstalledCli(argvPath)) {
+    return null;
+  }
+  const fromUserAgent = detectRunnerFromSignal(userAgent);
+  if (fromUserAgent) {
+    return fromUserAgent;
+  }
+  const fromExecPath = detectRunnerFromSignal(execPath);
+  if (fromExecPath) {
+    return fromExecPath;
+  }
+  if (argvPath.includes("/_npx/") || argvPath.includes("\\_npx\\")) {
+    return "npx";
+  }
+  if (argvPath.includes("/.yarn/") && argvPath.includes("/dlx/")) {
+    return "yarn dlx";
+  }
+  if (argvPath.includes("/bunx/") || argvPath.includes("\\bunx\\")) {
+    return "bunx";
+  }
+  if (argvPath.includes("/dlx-") || argvPath.includes("\\dlx-")) {
+    return "pnpm dlx";
+  }
+  if (userAgent || execPath) {
+    return "npx";
+  }
+  return null;
+}
+function detectRunnerFromArgvPath(argvPath) {
+  if (!argvPath) {
+    return null;
+  }
+  if (argvPath.includes("/_npx/") || argvPath.includes("\\_npx\\")) {
+    return "npx";
+  }
+  if (argvPath.includes("/.yarn/") && argvPath.includes("/dlx/")) {
+    return "yarn dlx";
+  }
+  if (argvPath.includes("/bunx/") || argvPath.includes("\\bunx\\")) {
+    return "bunx";
+  }
+  if (argvPath.includes("/dlx-") || argvPath.includes("\\dlx-")) {
+    return "pnpm dlx";
+  }
+  return null;
+}
+function looksLikeInstalledCli(argvPath) {
+  if (!argvPath) {
+    return false;
+  }
+  const normalized = argvPath.replaceAll("\\", "/");
+  return normalized.endsWith("/node_modules/.bin/xerg") || normalized.includes("/node_modules/@xerg/cli/dist/index.js") || normalized.endsWith("/bin/xerg");
+}
+function detectRunnerFromSignal(signal) {
+  if (!signal) {
+    return null;
+  }
+  const tokens = signal.split(/[^a-z0-9]+/).filter(Boolean);
+  if (tokens.includes("pnpm")) {
+    return "pnpm dlx";
+  }
+  if (tokens.includes("yarn")) {
+    return "yarn dlx";
+  }
+  if (tokens.includes("bun")) {
+    return "bunx";
+  }
+  if (tokens.includes("npm")) {
+    return "npx";
+  }
+  return null;
+}
+function normalizeSignal(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+
 // src/commands/audit.ts
 import { readFileSync as readFileSync5 } from "fs";
 import { rmSync as rmSync4 } from "fs";
@@ -1400,7 +1506,7 @@ async function auditOpenClaw(options) {
   if (sources.length === 0) {
     options.onProgress?.("No OpenClaw source files were detected.");
     throw new Error(
-      "No OpenClaw sources were detected. Run `xerg doctor` or provide --log-file / --sessions-dir."
+      `No OpenClaw sources were detected. Run \`${options.commandPrefix ?? "xerg"} doctor\` or provide --log-file / --sessions-dir.`
     );
   }
   options.onProgress?.(`Detected ${sources.length} source file${sources.length === 1 ? "" : "s"}.`);
@@ -1657,13 +1763,14 @@ function renderCompareBlock(summary) {
     ...findingChanges.length > 0 ? findingChanges : ["- High-confidence waste changes: none"]
   ];
 }
-function renderDoctorReport(report) {
+function renderDoctorReport(report, options) {
+  const commandPrefix = options?.commandPrefix ?? "xerg";
   const nextSteps = report.canAudit ? [] : [
     "",
     "## Next steps",
-    "- Try explicit local paths: xerg doctor --log-file /path/to/openclaw.log --sessions-dir /path/to/sessions",
-    "- Inspect an SSH host: xerg doctor --remote user@host",
-    "- Inspect a Railway service: xerg doctor --railway",
+    `- Try explicit local paths: ${commandPrefix} doctor --log-file /path/to/openclaw.log --sessions-dir /path/to/sessions`,
+    `- Inspect an SSH host: ${commandPrefix} doctor --remote user@host`,
+    `- Inspect a Railway service: ${commandPrefix} doctor --railway`,
     "- Remote audits still analyze locally after Xerg pulls the source files to your machine."
   ];
   const sections = [
@@ -1961,7 +2068,7 @@ function loadPushConfig() {
     };
   }
   throw new Error(
-    `No API key configured. Set XERG_API_KEY, add "apiKey" to ${CONFIG_PATH}, or run \`xerg login\`.
+    `No API key configured. Set XERG_API_KEY, add "apiKey" to ${CONFIG_PATH}, or run \`${formatCommand("login")}\`.
 Get your key at https://xerg.ai/dashboard/settings`
   );
 }
@@ -2522,7 +2629,7 @@ async function pullRemoteFilesRailway(opts) {
   const { status } = railwayExec("echo ok", target);
   if (status !== 0) {
     throw new Error(
-      `Cannot reach Railway service${target ? ` (project: ${target.projectId})` : " (linked project)"}. Check railway CLI auth and service configuration.`
+      target ? `Cannot reach Railway service ${target.serviceId} (project: ${target.projectId}). Check the provided --project / --environment / --service values and confirm the Railway CLI can reach that service.` : "Cannot reach the Railway service linked to this directory. Run `railway link` here and choose the OpenClaw app service, or pass --project / --environment / --service explicitly."
     );
   }
   onProgress?.("Railway service reachable.");
@@ -2535,7 +2642,7 @@ async function pullRemoteFilesRailway(opts) {
   const resolvedSessionsPath = findSessionsPath(target, source.sessionsDir);
   let pulledLog = false;
   let pulledSessions = false;
-  if (logCheck.exists) {
+  if (logCheck.fileCount > 0) {
     onProgress?.(`Pulling gateway logs from ${remoteLogPath}...`);
     const { stdout: isFile } = railwayExec(`test -f ${remoteLogPath} && echo file`, target);
     if (isFile === "file") {
@@ -2571,8 +2678,9 @@ async function pullRemoteFilesRailway(opts) {
     const checkedPaths = [remoteLogPath, DEFAULT_SESSIONS_DIR2, ...ALTERNATE_SESSION_PATHS].join(
       ", "
     );
+    const wrongServiceHint = target ? " Verify that the selected service is the OpenClaw app, or use --remote-log-file / --remote-sessions-dir for custom paths." : " If this directory is linked to a database or sidecar instead of the OpenClaw app, run `railway link` again and choose the app service.";
     throw new Error(
-      `No OpenClaw data found on Railway service. Checked: ${checkedPaths}. Use --remote-log-file or --remote-sessions-dir to specify custom paths.`
+      `No OpenClaw data found on Railway service. Checked: ${checkedPaths}. Use --remote-log-file or --remote-sessions-dir to specify custom paths.${wrongServiceHint}`
     );
   }
   const result = {
@@ -2635,12 +2743,12 @@ async function runRailwayDoctor(opts) {
       railwayAuthenticated: true,
       railwayAuthUser,
       serviceReachable: false,
-      serviceError: target ? `Cannot reach service ${target.serviceId}` : "Cannot reach linked service. Run: railway link",
+      serviceError: target ? `Cannot reach service ${target.serviceId} in project ${target.projectId}` : "Current directory is not linked to a reachable Railway service. Run `railway link` here and choose the OpenClaw app service, or pass --project / --environment / --service.",
       defaultPaths: emptyDefaultPaths(),
       alternateSessionPaths: [],
       notes: [
         ...notes,
-        target ? `Service unreachable (project: ${target.projectId}, service: ${target.serviceId})` : "Service unreachable. Ensure a project is linked with: railway link"
+        target ? `Service unreachable (project: ${target.projectId}, service: ${target.serviceId}). Verify the provided Railway IDs point at the OpenClaw app service.` : "Service unreachable for the current directory. Run `railway link` here and choose the OpenClaw app service, or pass explicit Railway IDs."
       ]
     };
   }
@@ -2700,9 +2808,11 @@ async function runRailwayDoctor(opts) {
     alternateSessionPaths,
     notes
   };
+  let logCheck = null;
+  let sessCheck = null;
   if (source.logFile || source.sessionsDir) {
-    const logCheck = source.logFile ? checkRemotePath(source.logFile, target) : null;
-    const sessCheck = source.sessionsDir ? checkRemotePath(source.sessionsDir, target) : null;
+    logCheck = source.logFile ? checkRemotePath(source.logFile, target) : null;
+    sessCheck = source.sessionsDir ? checkRemotePath(source.sessionsDir, target) : null;
     report.customPaths = {
       logFileExists: logCheck?.exists ?? false,
       logFilePath: source.logFile ?? "",
@@ -2725,6 +2835,12 @@ async function runRailwayDoctor(opts) {
       notes.push(`Custom sessions path ${source.sessionsDir}: not found`);
     }
   }
+  const foundOpenClawData = gateway.fileCount > 0 || sessions.fileCount > 0 || alternateSessionPaths.some((path) => path.fileCount > 0) || (logCheck?.fileCount ?? 0) > 0 || (sessCheck?.fileCount ?? 0) > 0;
+  if (!foundOpenClawData) {
+    notes.push(
+      target ? "No OpenClaw data was found on this Railway service. Verify that the selected service is the OpenClaw app, or use --remote-log-file / --remote-sessions-dir for custom paths." : "No OpenClaw data was found on the linked Railway service. If this directory is linked to a database or sidecar instead of the OpenClaw app, run `railway link` again and choose the app service."
+    );
+  }
   return report;
 }
 function emptyDefaultPaths() {
@@ -2900,6 +3016,7 @@ async function runLocalAudit(options, logger) {
     compare: options.compare,
     dbPath: options.db,
     noDb: options.noDb,
+    commandPrefix: options.commandPrefix,
     onProgress: logger.verbose
   });
   renderOutput(summary, options);
@@ -2949,6 +3066,7 @@ async function runSingleRemoteAudit(source, options, logger) {
       dbPath: options.db,
       noDb: options.noDb,
       comparisonKeyOverride,
+      commandPrefix: options.commandPrefix,
       onProgress: logger.verbose
     });
     renderOutput(summary, options);
@@ -3002,6 +3120,7 @@ ${errorMessages}`);
         dbPath: options.db,
         noDb: options.noDb,
         comparisonKeyOverride,
+        commandPrefix: options.commandPrefix,
         onProgress: logger.verbose
       });
       summaries.push({ name: source.name, source, summary });
@@ -3184,7 +3303,7 @@ async function runDoctorCommand(options) {
     sessionsDir: options.sessionsDir,
     onProgress: logger.verbose
   });
-  process.stdout.write(`${renderDoctorReport(report)}
+  process.stdout.write(`${renderDoctorReport(report, { commandPrefix: options.commandPrefix })}
 `);
 }
 function buildRailwayTarget2(options) {
@@ -3308,7 +3427,7 @@ async function runLoginCommand() {
   if (existing) {
     process.stderr.write(
       `Already logged in. Credentials stored at ${getCredentialsPath()}.
-Run ${colorBold("xerg logout")} first to re-authenticate.
+Run ${colorBold(formatCommand("logout"))} first to re-authenticate.
 `
     );
     return;
@@ -3374,7 +3493,7 @@ Credentials saved to ${getCredentialsPath()}.
         continue;
       }
       if (res.status === 410) {
-        throw new Error("Device code expired. Please run `xerg login` again.");
+        throw new Error(`Device code expired. Please run \`${formatCommand("login")}\` again.`);
       }
       const body = await res.json().catch(() => ({}));
       throw new Error(body.error || `Unexpected response: HTTP ${res.status}`);
@@ -3384,7 +3503,7 @@ Credentials saved to ${getCredentialsPath()}.
       }
     }
   }
-  throw new Error("Authentication timed out. Please run `xerg login` again.");
+  throw new Error(`Authentication timed out. Please run \`${formatCommand("login")}\` again.`);
 }
 async function openBrowser(url) {
   const { exec } = await import("child_process");
@@ -3472,12 +3591,12 @@ function loadPayloadFromCache() {
     summaries = listStoredAuditSummaries(dbPath);
   } catch {
     throw new NoDataError(
-      "No local audit database found. Run `xerg audit` first, or use `xerg push --file <path>`."
+      `No local audit database found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
     );
   }
   if (summaries.length === 0) {
     throw new NoDataError(
-      "No cached audit snapshots found. Run `xerg audit` first, or use `xerg push --file <path>`."
+      `No cached audit snapshots found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
     );
   }
   const latest = summaries[0];
@@ -3509,9 +3628,10 @@ function buildMeta2() {
 // src/index.ts
 var VERSION = readVersion();
 var argv = process.argv.slice(2);
+var commandDisplay = resolveCommandDisplay();
 var command = argv[0];
 if (!command || command === "--help" || command === "-h" || command === "help") {
-  process.stdout.write(renderRootHelp());
+  process.stdout.write(renderRootHelp(commandDisplay));
   process.exit(0);
 }
 if (command === "--version" || command === "-v" || command === "version") {
@@ -3521,7 +3641,7 @@ if (command === "--version" || command === "-v" || command === "version") {
 }
 run().catch((error) => {
   const message = error instanceof Error ? error.message : "Unknown error";
-  process.stderr.write(`${colorError(`xerg failed: ${message}`)}
+  process.stderr.write(`${colorError(`${commandDisplay.name} failed: ${message}`)}
 `);
   process.exitCode = error instanceof NoDataError ? 2 : 1;
 });
@@ -3531,12 +3651,18 @@ async function run() {
     if (options.json && options.markdown) {
       throw new Error("Use either --json or --markdown, not both.");
     }
-    await runAuditCommand(options);
+    await runAuditCommand({
+      ...options,
+      commandPrefix: commandDisplay.prefix
+    });
     return;
   }
   if (command === "doctor") {
     const options = parseDoctorOptions(argv.slice(1));
-    await runDoctorCommand(options);
+    await runDoctorCommand({
+      ...options,
+      commandPrefix: commandDisplay.prefix
+    });
     return;
   }
   if (command === "push") {
@@ -3552,7 +3678,9 @@ async function run() {
     runLogoutCommand();
     return;
   }
-  throw new Error(`Unknown command "${command}". Run \`xerg --help\` to see available commands.`);
+  throw new Error(
+    `Unknown command "${command}". Run \`${formatCommand("--help", commandDisplay.prefix)}\` to see available commands.`
+  );
 }
 function parseAuditOptions(raw) {
   const argv2 = expandEqualsArgs(raw);
@@ -3562,7 +3690,7 @@ function parseAuditOptions(raw) {
     switch (arg) {
       case "--help":
       case "-h":
-        process.stdout.write(renderAuditHelp());
+        process.stdout.write(renderAuditHelp(commandDisplay.prefix));
         process.exit(0);
         break;
       case "--log-file":
@@ -3645,7 +3773,9 @@ function parseAuditOptions(raw) {
         index += 1;
         break;
       default:
-        throw new Error(`Unknown audit option "${arg}". Run \`xerg audit --help\` for usage.`);
+        throw new Error(
+          `Unknown audit option "${arg}". Run \`${formatCommand(["audit", "--help"], commandDisplay.prefix)}\` for usage.`
+        );
     }
   }
   return options;
@@ -3658,7 +3788,7 @@ function parsePushOptions(raw) {
     switch (arg) {
       case "--help":
       case "-h":
-        process.stdout.write(renderPushHelp());
+        process.stdout.write(renderPushHelp(commandDisplay.prefix));
         process.exit(0);
         break;
       case "--file":
@@ -3669,7 +3799,9 @@ function parsePushOptions(raw) {
         options.dryRun = true;
         break;
       default:
-        throw new Error(`Unknown push option "${arg}". Run \`xerg push --help\` for usage.`);
+        throw new Error(
+          `Unknown push option "${arg}". Run \`${formatCommand(["push", "--help"], commandDisplay.prefix)}\` for usage.`
+        );
     }
   }
   return options;
@@ -3682,7 +3814,7 @@ function parseDoctorOptions(raw) {
     switch (arg) {
       case "--help":
       case "-h":
-        process.stdout.write(renderDoctorHelp());
+        process.stdout.write(renderDoctorHelp(commandDisplay.prefix));
         process.exit(0);
         break;
       case "--log-file":
@@ -3724,7 +3856,9 @@ function parseDoctorOptions(raw) {
         options.verbose = true;
         break;
       default:
-        throw new Error(`Unknown doctor option "${arg}". Run \`xerg doctor --help\` for usage.`);
+        throw new Error(
+          `Unknown doctor option "${arg}". Run \`${formatCommand(["doctor", "--help"], commandDisplay.prefix)}\` for usage.`
+        );
     }
   }
   return options;
@@ -3755,13 +3889,13 @@ function readFloat(flag, value) {
   }
   return num;
 }
-function renderRootHelp() {
-  return `xerg ${VERSION}
+function renderRootHelp(display = commandDisplay) {
+  return `${display.name} ${VERSION}
 
 Waste intelligence for OpenClaw workflows.
 
 Usage:
-  xerg <command> [options]
+  ${formatCommand("<command> [options]", display.prefix)}
 
 Commands:
   audit    Analyze OpenClaw logs and produce a waste intelligence report.
@@ -3775,13 +3909,13 @@ Global options:
   -v, --version  Show version
 `;
 }
-function renderAuditHelp() {
-  return `xerg audit
+function renderAuditHelp(commandPrefix = commandDisplay.prefix) {
+  return `${formatCommand("audit", commandPrefix)}
 
 Analyze OpenClaw logs and produce a waste intelligence report.
 
 Usage:
-  xerg audit [options]
+  ${formatCommand("audit [options]", commandPrefix)}
 
 Options:
   --log-file <path>           Explicit OpenClaw gateway log file to analyze
@@ -3823,13 +3957,13 @@ Threshold options:
   -h, --help                  Show help
 `;
 }
-function renderPushHelp() {
-  return `xerg push
+function renderPushHelp(commandPrefix = commandDisplay.prefix) {
+  return `${formatCommand("push", commandPrefix)}
 
 Push a cached audit snapshot to the Xerg API.
 
 Usage:
-  xerg push [options]
+  ${formatCommand("push [options]", commandPrefix)}
 
 Options:
   --file <path>               Push a specific snapshot file instead of the most recent cached audit
@@ -3839,17 +3973,17 @@ Options:
 
 Authentication:
   Set XERG_API_KEY in your environment, add "apiKey" to ~/.xerg/config.json,
-  or run \`xerg login\` to authenticate via browser.
+  or run \`${formatCommand("login", commandPrefix)}\` to authenticate via browser.
   Browser login stores a token at ~/.config/xerg/credentials.json by default.
 `;
 }
-function renderDoctorHelp() {
-  return `xerg doctor
+function renderDoctorHelp(commandPrefix = commandDisplay.prefix) {
+  return `${formatCommand("doctor", commandPrefix)}
 
 Inspect your machine for OpenClaw sources and audit readiness.
 
 Usage:
-  xerg doctor [options]
+  ${formatCommand("doctor [options]", commandPrefix)}
 
 Options:
   --log-file <path>           Explicit OpenClaw gateway log file to inspect