@xerg/cli 0.1.7 → 0.1.9

package/README.md

@@ -1,13 +1,16 @@
 # xerg
 
-Audit OpenClaw agent spend, waste, and before/after improvements.
+Audit OpenClaw workflows in dollars, compare fixes, and surface savings opportunities.
 
-Xerg audits OpenClaw workflows in dollars, not tokens. It reads your gateway logs and session transcripts, shows where money is leaking, classifies waste into five categories, and lets you re-run the same audit with `--compare` so you can see what changed after a fix.
+Xerg audits OpenClaw workflows in dollars, not tokens. It reads your gateway logs and session transcripts, surfaces five spend categories across confirmed waste and savings opportunities, and lets you re-run the same audit with `--compare` so you can see exactly what changed after a fix.
+
+Everything runs locally by default. No account is required for local audits. No data leaves your machine unless you explicitly `--push` results to the Xerg API for a team dashboard.
 
 ## 30-second quick start
 
 ```bash
 npx @xerg/cli doctor
+npx @xerg/cli doctor --verbose
 npx @xerg/cli audit
 npx @xerg/cli audit --compare
 ```
@@ -112,6 +115,13 @@ xerg audit --log-file /path/to/openclaw.log
 xerg audit --sessions-dir /path/to/sessions
 ```
 
+If your local machine has no OpenClaw files, inspect remote targets directly instead:
+
+```bash
+xerg doctor --remote user@host
+xerg doctor --railway
+```
+
 ## Authentication and config
 
 Push commands resolve credentials in this order:
@@ -140,7 +150,8 @@ Example `~/.xerg/config.json`:
 
 - Total spend by workflow and model, in dollars
 - Observed vs. estimated cost (always labeled)
-- Structural waste: retry, context bloat, loop, downgrade candidates, idle
+- Confirmed waste: retry, loop
+- Savings opportunities: context bloat, downgrade candidates, idle
 - Savings recommendations with suggested A/B tests
 - Before/after deltas on re-audit
 
@@ -158,6 +169,7 @@ Xerg v0 stores economic metadata and audit summaries locally. It does not store
 ## Troubleshooting
 
 - `better-sqlite3` is a native dependency. If install fails, retry on a supported Node version and make sure standard native build tooling is available for your platform.
+- `--verbose` prints progress updates to stderr for `xerg doctor` and `xerg audit`, which helps distinguish package install time from CLI runtime.
 - If `xerg audit --remote ...` fails before pulling files, verify that both `ssh` and `rsync` are installed and reachable on your `PATH`.
 - If `xerg audit --railway` fails immediately, verify that the `railway` CLI is installed, authenticated, and can access the target project.
 

package/dist/index.js

@@ -798,10 +798,17 @@ function segmentToRegExp(segment) {
   return new RegExp(`^${escaped}$`);
 }
 async function inspectOpenClawSources(options) {
+  options.onProgress?.("Checking local OpenClaw defaults...");
   const sources = await detectOpenClawSources(options);
   const notes = [];
+  options.onProgress?.(
+    sources.length > 0 ? `Detected ${sources.length} local source file${sources.length === 1 ? "" : "s"}.` : "No local OpenClaw source files were detected."
+  );
   if (sources.length === 0) {
     notes.push("No OpenClaw gateway logs or session files were detected.");
+    notes.push(
+      "Doctor checks local defaults by default. Use --remote or --railway to inspect remote targets."
+    );
     notes.push(
       "Use --log-file or --sessions-dir if your OpenClaw data lives outside the defaults."
     );
@@ -1383,6 +1390,7 @@ async function doctorOpenClaw(options) {
   return inspectOpenClawSources(options);
 }
 async function auditOpenClaw(options) {
+  options.onProgress?.("Scanning for OpenClaw source files...");
   if (options.compare && options.noDb) {
     throw new Error(
       "The --compare flag needs local snapshot history. Remove --no-db or provide --db <path>."
@@ -1390,13 +1398,19 @@ async function auditOpenClaw(options) {
   }
   const sources = await detectOpenClawSources(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."
     );
   }
+  options.onProgress?.(`Detected ${sources.length} source file${sources.length === 1 ? "" : "s"}.`);
+  options.onProgress?.("Normalizing OpenClaw source files...");
   const runs = normalizeOpenClawSources(sources, options.since);
+  options.onProgress?.(`Normalized ${runs.length} run${runs.length === 1 ? "" : "s"}.`);
+  options.onProgress?.("Computing waste and savings findings...");
   const findings = buildFindings(runs);
   const dbPath = options.noDb ? void 0 : options.dbPath ?? getDefaultDbPath();
+  options.onProgress?.("Building audit summary...");
   const summary = buildAuditSummary({
     runs,
     findings,
@@ -1406,6 +1420,7 @@ async function auditOpenClaw(options) {
     comparisonKeyOverride: options.comparisonKeyOverride
   });
   if (options.compare && dbPath) {
+    options.onProgress?.("Looking for a comparable baseline audit...");
     const baseline = readLatestComparableAuditSummary({
       dbPath,
       comparisonKey: summary.comparisonKey,
@@ -1421,6 +1436,7 @@ async function auditOpenClaw(options) {
     }
   }
   if (dbPath) {
+    options.onProgress?.(`Persisting local snapshot to ${dbPath}...`);
     persistAudit(
       {
         summary,
@@ -1429,6 +1445,9 @@ async function auditOpenClaw(options) {
       },
       dbPath
     );
+    options.onProgress?.("Local snapshot stored.");
+  } else {
+    options.onProgress?.("Skipping local snapshot persistence (--no-db).");
   }
   return summary;
 }
@@ -1639,6 +1658,14 @@ function renderCompareBlock(summary) {
   ];
 }
 function renderDoctorReport(report) {
+  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",
+    "- Remote audits still analyze locally after Xerg pulls the source files to your machine."
+  ];
   const sections = [
     "# Xerg doctor",
     "",
@@ -1652,7 +1679,8 @@ function renderDoctorReport(report) {
     ...report.sources.length > 0 ? report.sources.map((source) => `- [${source.kind}] ${source.path}`) : ["- none"],
     "",
     "## Notes",
-    ...report.notes.map((note) => `- ${note}`)
+    ...report.notes.map((note) => `- ${note}`),
+    ...nextSteps
   ];
   return sections.join("\n");
 }
@@ -1811,6 +1839,23 @@ var NoDataError = class extends Error {
   }
 };
 
+// src/log.ts
+function createCliLogger(options) {
+  return {
+    info(message) {
+      process.stderr.write(`${message}
+`);
+    },
+    verbose(message) {
+      if (!options.verbose) {
+        return;
+      }
+      process.stderr.write(`[verbose] ${message}
+`);
+    }
+  };
+}
+
 // src/push/client.ts
 async function pushAudit(payload, config) {
   const url = `${config.apiUrl}/v1/audits`;
@@ -2124,14 +2169,19 @@ function buildComparisonKeyForRemote(source) {
   return `${source.host}:${logPath}:${sessPath}`;
 }
 async function pullRemoteFiles(opts) {
-  const { source, since, keepFiles = false } = opts;
+  const { source, since, keepFiles = false, onProgress } = opts;
+  onProgress?.(`Testing SSH connectivity to ${source.host}...`);
   const connectivity = testSshConnectivity(source);
   if (!connectivity.ok) {
     throw new Error(
       `Cannot connect to ${source.host}. Check SSH config and key access.${connectivity.error ? ` (${connectivity.error})` : ""}`
     );
   }
+  onProgress?.("SSH connectivity OK.");
   const useRsync = isRsyncAvailable();
+  onProgress?.(
+    useRsync ? "Local rsync detected. Xerg will prefer rsync and fall back to tar over SSH if needed." : "Local rsync not detected. Xerg will pull files with tar over SSH."
+  );
   const localBase = resolveLocalPath(source, keepFiles);
   const gatewayDir = join5(localBase, "gateway");
   const sessionsDir = join5(localBase, "sessions");
@@ -2139,6 +2189,7 @@ async function pullRemoteFiles(opts) {
   const remoteSessionsPath = source.sessionsDir ?? DEFAULT_SESSIONS_DIR;
   const { stdout: expandedSessions } = sshExec(source, `eval echo ${remoteSessionsPath}`);
   const resolvedSessionsPath = expandedSessions || remoteSessionsPath;
+  onProgress?.("Checking remote default paths for gateway logs and sessions...");
   const { status: logPathExists } = sshExec(source, `test -e ${remoteLogPath} && echo exists`);
   const { status: sessPathExists } = sshExec(
     source,
@@ -2147,6 +2198,7 @@ async function pullRemoteFiles(opts) {
   let pulledLog = false;
   let pulledSessions = false;
   if (logPathExists === 0) {
+    onProgress?.(`Pulling gateway logs from ${remoteLogPath}...`);
     const { stdout: isFile } = sshExec(source, `test -f ${remoteLogPath} && echo file`);
     if (isFile === "file") {
       const parentDir = remoteLogPath.slice(0, remoteLogPath.lastIndexOf("/")) || "/tmp";
@@ -2171,6 +2223,7 @@ async function pullRemoteFiles(opts) {
     }
   }
   if (sessPathExists === 0) {
+    onProgress?.(`Pulling session files from ${resolvedSessionsPath}...`);
     pulledSessions = pullDirectory({
       source,
       remotePath: resolvedSessionsPath,
@@ -2194,11 +2247,13 @@ async function pullRemoteFiles(opts) {
   };
   if (pulledLog) result.logFile = gatewayDir;
   if (pulledSessions) result.sessionsDir = sessionsDir;
+  onProgress?.("Remote files pulled successfully.");
   return result;
 }
 async function runRemoteDoctor(opts) {
-  const { source } = opts;
+  const { source, onProgress } = opts;
   const notes = [];
+  onProgress?.(`Testing SSH connectivity to ${source.host}...`);
   const connectivity = testSshConnectivity(source);
   if (!connectivity.ok) {
     return {
@@ -2222,7 +2277,9 @@ async function runRemoteDoctor(opts) {
       ]
     };
   }
+  onProgress?.("SSH connectivity OK.");
   notes.push("SSH connectivity: OK");
+  onProgress?.("Checking rsync availability locally and on the remote host...");
   const rsyncLocal = isRsyncAvailable();
   const rsyncRemote = isRemoteRsyncAvailable(source);
   notes.push(`rsync available locally: ${rsyncLocal ? "yes" : "no"}`);
@@ -2246,6 +2303,7 @@ async function runRemoteDoctor(opts) {
       totalBytes: Number.parseInt(sizeOut, 10) || 0
     };
   }
+  onProgress?.("Inspecting remote default paths...");
   const gateway = checkPath(DEFAULT_GATEWAY_DIR);
   const sessions = checkPath(DEFAULT_SESSIONS_DIR);
   if (gateway.exists) {
@@ -2458,23 +2516,27 @@ function buildComparisonKeyForRailway(source) {
   return `railway-linked:${logPath}:${sessPath}`;
 }
 async function pullRemoteFilesRailway(opts) {
-  const { source, since, keepFiles = false } = opts;
+  const { source, since, keepFiles = false, onProgress } = opts;
   const target = source.railway;
+  onProgress?.("Testing Railway service connectivity...");
   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.`
     );
   }
+  onProgress?.("Railway service reachable.");
   const localBase = resolveLocalPath2(source, keepFiles);
   const gatewayDir = join6(localBase, "gateway");
   const sessionsDir = join6(localBase, "sessions");
   const remoteLogPath = source.logFile ?? DEFAULT_GATEWAY_DIR2;
+  onProgress?.("Checking Railway default paths for gateway logs and sessions...");
   const logCheck = checkRemotePath(remoteLogPath, target);
   const resolvedSessionsPath = findSessionsPath(target, source.sessionsDir);
   let pulledLog = false;
   let pulledSessions = false;
   if (logCheck.exists) {
+    onProgress?.(`Pulling gateway logs from ${remoteLogPath}...`);
     const { stdout: isFile } = railwayExec(`test -f ${remoteLogPath} && echo file`, target);
     if (isFile === "file") {
       const parentDir = remoteLogPath.slice(0, remoteLogPath.lastIndexOf("/")) || "/tmp";
@@ -2494,6 +2556,7 @@ async function pullRemoteFilesRailway(opts) {
     }
   }
   if (resolvedSessionsPath) {
+    onProgress?.(`Pulling session files from ${resolvedSessionsPath}...`);
     pulledSessions = tarRailwayPull({
       target,
       remotePath: resolvedSessionsPath,
@@ -2518,12 +2581,14 @@ async function pullRemoteFilesRailway(opts) {
   };
   if (pulledLog) result.logFile = gatewayDir;
   if (pulledSessions) result.sessionsDir = sessionsDir;
+  onProgress?.("Railway files pulled successfully.");
   return result;
 }
 async function runRailwayDoctor(opts) {
-  const { source } = opts;
+  const { source, onProgress } = opts;
   const target = source.railway;
   const notes = [];
+  onProgress?.("Checking whether the Railway CLI is installed...");
   const whichCheck = spawnSync2("which", ["railway"], { stdio: "pipe", timeout: 5e3 });
   const railwayCliInstalled = whichCheck.status === 0;
   if (!railwayCliInstalled) {
@@ -2539,6 +2604,7 @@ async function runRailwayDoctor(opts) {
     };
   }
   const railwayPath = whichCheck.stdout?.toString().trim() ?? "railway";
+  onProgress?.("Checking Railway CLI authentication...");
   const versionCheck = spawnSync2("railway", ["version"], { stdio: "pipe", timeout: 1e4 });
   const versionStr = versionCheck.status === 0 ? versionCheck.stdout?.toString().trim() : railwayPath;
   notes.push(`Railway CLI: installed (${versionStr})`);
@@ -2558,6 +2624,7 @@ async function runRailwayDoctor(opts) {
     };
   }
   notes.push(`Authenticated as: ${railwayAuthUser}`);
+  onProgress?.("Testing Railway service connectivity...");
   const { status: reachStatus } = railwayExec("echo ok", target);
   const serviceReachable = reachStatus === 0;
   if (!serviceReachable) {
@@ -2578,6 +2645,7 @@ async function runRailwayDoctor(opts) {
     };
   }
   notes.push("Service connectivity: OK");
+  onProgress?.("Inspecting Railway default paths...");
   const gateway = checkRemotePath(DEFAULT_GATEWAY_DIR2, target);
   const { stdout: expandedDefault } = railwayExec(`eval echo ${DEFAULT_SESSIONS_DIR2}`, target);
   const resolvedDefault = expandedDefault || DEFAULT_SESSIONS_DIR2;
@@ -2770,6 +2838,7 @@ async function auditOrNoData(...args) {
   }
 }
 async function runAuditCommand(options) {
+  const logger = createCliLogger({ verbose: options.verbose });
   if (options.dryRun && !options.push) {
     throw new Error("--dry-run requires --push.");
   }
@@ -2780,7 +2849,7 @@ async function runAuditCommand(options) {
     throw new Error("Use only one of --remote, --remote-config, or --railway.");
   }
   if (!options.remote && !options.remoteConfig && !options.railway) {
-    return runLocalAudit(options);
+    return runLocalAudit(options, logger);
   }
   if (options.railway) {
     const railwayTarget = buildRailwayTarget(options);
@@ -2789,14 +2858,14 @@ async function runAuditCommand(options) {
       remoteLogFile: options.remoteLogFile,
       remoteSessionsDir: options.remoteSessionsDir
     });
-    return runSingleRemoteAudit(source2, options);
+    return runSingleRemoteAudit(source2, options, logger);
   }
   if (options.remoteConfig) {
     const sources = loadRemoteConfig(options.remoteConfig);
     if (sources.length === 1) {
-      return runSingleRemoteAudit(sources[0], options);
+      return runSingleRemoteAudit(sources[0], options, logger);
     }
-    return runMultiRemoteAudit(sources, options);
+    return runMultiRemoteAudit(sources, options, logger);
   }
   const remote = options.remote;
   const source = buildSourceFromFlags({
@@ -2804,7 +2873,7 @@ async function runAuditCommand(options) {
     remoteLogFile: options.remoteLogFile,
     remoteSessionsDir: options.remoteSessionsDir
   });
-  return runSingleRemoteAudit(source, options);
+  return runSingleRemoteAudit(source, options, logger);
 }
 function buildRailwayTarget(options) {
   if (options.railwayProject && options.railwayEnvironment && options.railwayService) {
@@ -2816,14 +2885,22 @@ function buildRailwayTarget(options) {
   }
   return void 0;
 }
-async function runLocalAudit(options) {
+async function runLocalAudit(options, logger) {
+  logger.verbose("Running a local audit.");
+  if (options.logFile) {
+    logger.verbose(`Using explicit local log file: ${options.logFile}`);
+  }
+  if (options.sessionsDir) {
+    logger.verbose(`Using explicit local sessions directory: ${options.sessionsDir}`);
+  }
   const summary = await auditOrNoData({
     logFile: options.logFile,
     sessionsDir: options.sessionsDir,
     since: options.since,
     compare: options.compare,
     dbPath: options.db,
-    noDb: options.noDb
+    noDb: options.noDb,
+    onProgress: logger.verbose
   });
   renderOutput(summary, options);
   if (options.push) {
@@ -2838,11 +2915,11 @@ function getComparisonKey(source) {
   }
   return buildComparisonKeyForRemote(source);
 }
-function pullFiles(source, since, keepFiles) {
+function pullFiles(source, since, keepFiles, onProgress) {
   if (source.transport === "railway") {
-    return pullRemoteFilesRailway({ source, since, keepFiles });
+    return pullRemoteFilesRailway({ source, since, keepFiles, onProgress });
   }
-  return pullRemoteFiles({ source, since, keepFiles });
+  return pullRemoteFiles({ source, since, keepFiles, onProgress });
 }
 function describeSource(source) {
   if (source.transport === "railway") {
@@ -2853,10 +2930,15 @@ function describeSource(source) {
 function sourceEnvironment(source) {
   return source.transport === "railway" ? "railway" : "remote";
 }
-async function runSingleRemoteAudit(source, options) {
-  process.stderr.write(`Pulling files from ${describeSource(source)}...
-`);
-  const pullResult = await pullFiles(source, options.since, options.keepRemoteFiles);
+async function runSingleRemoteAudit(source, options, logger) {
+  logger.info(`Pulling files from ${describeSource(source)}...`);
+  const pullResult = await pullFiles(
+    source,
+    options.since,
+    options.keepRemoteFiles,
+    logger.verbose
+  );
+  logger.verbose(`Files staged at ${pullResult.localPath}.`);
   try {
     const comparisonKeyOverride = getComparisonKey(source);
     const summary = await auditOrNoData({
@@ -2866,7 +2948,8 @@ async function runSingleRemoteAudit(source, options) {
       compare: options.compare,
       dbPath: options.db,
       noDb: options.noDb,
-      comparisonKeyOverride
+      comparisonKeyOverride,
+      onProgress: logger.verbose
     });
     renderOutput(summary, options);
     if (options.push) {
@@ -2882,14 +2965,18 @@ async function runSingleRemoteAudit(source, options) {
     cleanupPullResult(pullResult, options.keepRemoteFiles);
   }
 }
-async function runMultiRemoteAudit(sources, options) {
+async function runMultiRemoteAudit(sources, options, logger) {
   const results = [];
   const errors = [];
   for (const source of sources) {
-    process.stderr.write(`Pulling files from ${source.name} (${describeSource(source)})...
-`);
+    logger.info(`Pulling files from ${source.name} (${describeSource(source)})...`);
     try {
-      const pullResult = await pullFiles(source, options.since, options.keepRemoteFiles);
+      const pullResult = await pullFiles(
+        source,
+        options.since,
+        options.keepRemoteFiles,
+        logger.verbose
+      );
       results.push({ source, pullResult });
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
@@ -2914,7 +3001,8 @@ ${errorMessages}`);
         compare: options.compare,
         dbPath: options.db,
         noDb: options.noDb,
-        comparisonKeyOverride
+        comparisonKeyOverride,
+        onProgress: logger.verbose
       });
       summaries.push({ name: source.name, source, summary });
     }
@@ -3058,32 +3146,43 @@ function cleanupPullResult(pullResult, keepFiles) {
 
 // src/commands/doctor.ts
 async function runDoctorCommand(options) {
+  const logger = createCliLogger({ verbose: options.verbose });
   if (options.railway) {
+    logger.verbose("Inspecting Railway audit readiness.");
     const railwayTarget = buildRailwayTarget2(options);
     const source = buildRailwaySourceFromFlags({
       railway: railwayTarget,
       remoteLogFile: options.remoteLogFile,
       remoteSessionsDir: options.remoteSessionsDir
     });
-    const report2 = await runRailwayDoctor({ source });
+    const report2 = await runRailwayDoctor({ source, onProgress: logger.verbose });
     process.stdout.write(`${renderRailwayDoctorReport(report2)}
 `);
     return;
   }
   if (options.remote) {
+    logger.verbose(`Inspecting SSH audit readiness for ${options.remote}.`);
     const source = buildSourceFromFlags({
       remote: options.remote,
       remoteLogFile: options.remoteLogFile,
       remoteSessionsDir: options.remoteSessionsDir
     });
-    const report2 = await runRemoteDoctor({ source });
+    const report2 = await runRemoteDoctor({ source, onProgress: logger.verbose });
     process.stdout.write(`${renderRemoteDoctorReport(report2)}
 `);
     return;
   }
+  logger.verbose("Inspecting local OpenClaw audit readiness.");
+  if (options.logFile) {
+    logger.verbose(`Using explicit local log file: ${options.logFile}`);
+  }
+  if (options.sessionsDir) {
+    logger.verbose(`Using explicit local sessions directory: ${options.sessionsDir}`);
+  }
   const report = await doctorOpenClaw({
     logFile: options.logFile,
-    sessionsDir: options.sessionsDir
+    sessionsDir: options.sessionsDir,
+    onProgress: logger.verbose
   });
   process.stdout.write(`${renderDoctorReport(report)}
 `);
@@ -3534,6 +3633,9 @@ function parseAuditOptions(raw) {
       case "--dry-run":
         options.dryRun = true;
         break;
+      case "--verbose":
+        options.verbose = true;
+        break;
       case "--fail-above-waste-rate":
         options.failAboveWasteRate = readFloat(arg, argv2[index + 1]);
         index += 1;
@@ -3618,6 +3720,9 @@ function parseDoctorOptions(raw) {
         options.railwayService = readValue(arg, argv2[index + 1]);
         index += 1;
         break;
+      case "--verbose":
+        options.verbose = true;
+        break;
       default:
         throw new Error(`Unknown doctor option "${arg}". Run \`xerg doctor --help\` for usage.`);
     }
@@ -3709,6 +3814,7 @@ Railway options:
 Push options:
   --push                      Push the audit summary to the Xerg API after computing it
   --dry-run                   With --push: print the payload to stdout without sending it
+  --verbose                   Print progress updates to stderr while the audit runs
 
 Threshold options:
   --fail-above-waste-rate <n> Exit with code 3 if structural waste rate exceeds threshold (e.g. 0.30)
@@ -3748,6 +3854,7 @@ Usage:
 Options:
   --log-file <path>           Explicit OpenClaw gateway log file to inspect
   --sessions-dir <path>       Explicit OpenClaw sessions directory to inspect
+  --verbose                   Print progress updates to stderr while doctor runs
 
 Remote options (SSH):
   --remote <user@host>        SSH target in user@host or user@host:port format