vibeusage 0.2.11 → 0.2.13

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# 🟢 VIBESCORE
+# 🟢 VIBEUSAGE
 
 **QUANTIFY YOUR AI OUTPUT**  
 _Real-time AI Analytics for Codex CLI_
@@ -81,6 +81,19 @@ npx --yes vibeusage sync
 npx --yes vibeusage status
 ````
 
+### Doctor
+
+```bash
+# Run health checks
+npx --yes vibeusage doctor
+
+# Emit JSON report (and write to file)
+npx --yes vibeusage doctor --json --out doctor.json
+
+# Override base URL (diagnostics only)
+npx --yes vibeusage doctor --base-url https://example.invalid
+```
+
 ### Sources
 
 - Codex CLI logs: `~/.codex/sessions/**/rollout-*.jsonl` (override with `CODEX_HOME`)
@@ -89,10 +102,9 @@ npx --yes vibeusage status
 
 ## 🔧 Environment Variables
 
-- `VIBESCORE_HTTP_TIMEOUT_MS`: CLI HTTP timeout in ms (default `20000`, `0` disables, clamped to `1000..120000`).
-- `VITE_VIBESCORE_HTTP_TIMEOUT_MS`: Dashboard request timeout in ms (default `15000`, `0` disables, clamped to `1000..30000`).
+- `VIBEUSAGE_HTTP_TIMEOUT_MS`: CLI HTTP timeout in ms (default `20000`, `0` disables, clamped to `1000..120000`).
+- `VITE_VIBEUSAGE_HTTP_TIMEOUT_MS`: Dashboard request timeout in ms (default `15000`, `0` disables, clamped to `1000..30000`).
 - `VIBEUSAGE_ROLLUP_ENABLED`: Currently ignored; rollup aggregation is disabled in code until the daily rollup table is deployed.
-- `VIBESCORE_ROLLUP_ENABLED`: Legacy alias for `VIBEUSAGE_ROLLUP_ENABLED` (ignored).
 - `GEMINI_HOME`: Override Gemini CLI home (defaults to `~/.gemini`).
 
 ## 🧰 Troubleshooting

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# 🟢 VIBESCORE
+# 🟢 VIBEUSAGE
 
 **量化你的 AI 产出**  
 _Codex CLI 实时 AI 分析工具_
@@ -81,6 +81,19 @@ npx --yes vibeusage sync
 npx --yes vibeusage status
 ````
 
+### Doctor
+
+```bash
+# 运行健康检查
+npx --yes vibeusage doctor
+
+# 输出 JSON 报告（同时写文件）
+npx --yes vibeusage doctor --json --out doctor.json
+
+# 覆盖 base URL（仅诊断）
+npx --yes vibeusage doctor --base-url https://example.invalid
+```
+
 ### 日志来源
 
 - Codex CLI 日志：`~/.codex/sessions/**/rollout-*.jsonl`（可用 `CODEX_HOME` 覆盖）
@@ -89,10 +102,9 @@ npx --yes vibeusage status
 
 ## 🔧 环境变量
 
-- `VIBESCORE_HTTP_TIMEOUT_MS`：CLI 请求超时（毫秒，默认 `20000`，`0` 表示关闭，范围 `1000..120000`）。
-- `VITE_VIBESCORE_HTTP_TIMEOUT_MS`：Dashboard 请求超时（毫秒，默认 `15000`，`0` 表示关闭，范围 `1000..30000`）。
+- `VIBEUSAGE_HTTP_TIMEOUT_MS`：CLI 请求超时（毫秒，默认 `20000`，`0` 表示关闭，范围 `1000..120000`）。
+- `VITE_VIBEUSAGE_HTTP_TIMEOUT_MS`：Dashboard 请求超时（毫秒，默认 `15000`，`0` 表示关闭，范围 `1000..30000`）。
 - `VIBEUSAGE_ROLLUP_ENABLED`：当前被忽略，rollup 聚合在代码层禁用，等待 rollup 表部署完成后再恢复。
-- `VIBESCORE_ROLLUP_ENABLED`：`VIBEUSAGE_ROLLUP_ENABLED` 的兼容别名（同样无效）。
 - `GEMINI_HOME`：覆盖 Gemini CLI 的 home（默认 `~/.gemini`）。
 
 ## 🧰 常见问题

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "publishConfig": {
@@ -27,8 +27,7 @@
   "bin": {
     "tracker": "bin/tracker.js",
     "vibeusage": "bin/tracker.js",
-    "vibeusage-tracker": "bin/tracker.js",
-    "vibescore-tracker": "bin/tracker.js"
+    "vibeusage-tracker": "bin/tracker.js"
   },
   "files": [
     "bin/",

package/src/cli.js

@@ -2,6 +2,7 @@ const { cmdInit } = require('./commands/init');
 const { cmdSync } = require('./commands/sync');
 const { cmdStatus } = require('./commands/status');
 const { cmdDiagnostics } = require('./commands/diagnostics');
+const { cmdDoctor } = require('./commands/doctor');
 const { cmdUninstall } = require('./commands/uninstall');
 
 async function run(argv) {
@@ -25,6 +26,9 @@ async function run(argv) {
     case 'diagnostics':
       await cmdDiagnostics(rest);
       return;
+    case 'doctor':
+      await cmdDoctor(rest);
+      return;
     case 'uninstall':
       await cmdUninstall(rest);
       return;
@@ -44,6 +48,7 @@ function printHelp() {
       '  npx vibeusage [--debug] sync [--auto] [--drain]',
       '  npx vibeusage [--debug] status',
       '  npx vibeusage [--debug] diagnostics [--out diagnostics.json]',
+      '  npx vibeusage [--debug] doctor [--json] [--out doctor.json] [--base-url <url>]',
       '  npx vibeusage [--debug] uninstall [--purge]',
       '',
       'Notes:',

package/src/commands/doctor.js

@@ -0,0 +1,91 @@
+const os = require('node:os');
+const path = require('node:path');
+
+const { readJsonStrict, writeFileAtomic, chmod600IfPossible } = require('../lib/fs');
+const { resolveTrackerPaths } = require('../lib/tracker-paths');
+const { collectTrackerDiagnostics } = require('../lib/diagnostics');
+const { resolveRuntimeConfig } = require('../lib/runtime-config');
+const { buildDoctorReport } = require('../lib/doctor');
+
+async function cmdDoctor(argv = []) {
+  const opts = parseArgs(argv);
+  const home = os.homedir();
+  const { trackerDir } = await resolveTrackerPaths({ home });
+  const configPath = path.join(trackerDir, 'config.json');
+
+  const configStatus = await readJsonStrict(configPath);
+  const config = configStatus.status === 'ok' && isPlainObject(configStatus.value) ? configStatus.value : {};
+  const runtime = resolveRuntimeConfig({ cli: { baseUrl: opts.baseUrl }, config, env: process.env });
+  const diagnostics = await collectTrackerDiagnostics({ home });
+  const cliPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
+
+  const report = await buildDoctorReport({
+    runtime,
+    diagnostics,
+    fetch: globalThis.fetch,
+    paths: {
+      trackerDir,
+      configPath,
+      cliPath
+    }
+  });
+
+  const jsonOutput = opts.json || Boolean(opts.out);
+  const payload = JSON.stringify(report, null, jsonOutput ? 2 : 0) + '\n';
+
+  if (opts.out) {
+    const outPath = path.resolve(process.cwd(), opts.out);
+    await writeFileAtomic(outPath, payload);
+    await chmod600IfPossible(outPath);
+    process.stderr.write(`Wrote doctor report to: ${outPath}\n`);
+  }
+
+  if (jsonOutput) {
+    process.stdout.write(payload);
+  } else {
+    process.stdout.write(renderHumanReport(report));
+  }
+
+  if (report.summary.critical > 0) {
+    process.exitCode = 1;
+  }
+}
+
+function parseArgs(argv) {
+  const out = { json: false, out: null, baseUrl: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') out.json = true;
+    else if (arg === '--out') out.out = argv[++i] || null;
+    else if (arg === '--base-url') out.baseUrl = argv[++i] || null;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  return out;
+}
+
+function renderHumanReport(report) {
+  const lines = [];
+  lines.push('Doctor report');
+  lines.push('');
+  for (const check of report.checks || []) {
+    lines.push(formatCheckLine(check));
+  }
+  lines.push('');
+  lines.push(
+    `Summary: ok ${report.summary.ok} | warn ${report.summary.warn} | fail ${report.summary.fail} | critical ${report.summary.critical}`
+  );
+  lines.push('');
+  return lines.join('\n');
+}
+
+function formatCheckLine(check = {}) {
+  const status = String(check.status || 'unknown').toUpperCase();
+  const detail = check.detail ? ` - ${check.detail}` : '';
+  return `- [${status}] ${check.id || 'unknown'}${detail}`;
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+module.exports = { cmdDoctor };

package/src/commands/init.js

@@ -29,6 +29,7 @@ const {
   issueDeviceTokenWithLinkCode
 } = require('../lib/insforge');
 const { resolveTrackerPaths } = require('../lib/tracker-paths');
+const { resolveRuntimeConfig } = require('../lib/runtime-config');
 const {
   BOLD,
   DIM,
@@ -51,25 +52,26 @@ const ASCII_LOGO = [
 ].join('\n');
 
 const DIVIDER = '----------------------------------------------';
+const DEFAULT_DASHBOARD_URL = 'https://www.vibeusage.cc';
 
 async function cmdInit(argv) {
   const opts = parseArgs(argv);
   const home = os.homedir();
 
-  const { rootDir, trackerDir, binDir } = await resolveTrackerPaths({ home, migrate: true });
+  const { rootDir, trackerDir, binDir } = await resolveTrackerPaths({ home });
 
   const configPath = path.join(trackerDir, 'config.json');
   const notifyOriginalPath = path.join(trackerDir, 'codex_notify_original.json');
   const linkCodeStatePath = path.join(trackerDir, 'link_code_state.json');
 
-  const baseUrl = opts.baseUrl ||
-    process.env.VIBEUSAGE_INSFORGE_BASE_URL ||
-    process.env.VIBESCORE_INSFORGE_BASE_URL ||
-    'https://5tmappuk.us-east.insforge.app';
-  let dashboardUrl = opts.dashboardUrl ||
-    process.env.VIBEUSAGE_DASHBOARD_URL ||
-    process.env.VIBESCORE_DASHBOARD_URL ||
-    null;
+  const existingConfig = await readJson(configPath);
+  const runtime = resolveRuntimeConfig({
+    cli: { baseUrl: opts.baseUrl, dashboardUrl: opts.dashboardUrl },
+    config: existingConfig || {},
+    env: process.env
+  });
+  const baseUrl = runtime.baseUrl;
+  let dashboardUrl = runtime.dashboardUrl || DEFAULT_DASHBOARD_URL;
   const notifyPath = path.join(binDir, 'notify.cjs');
   const appDir = path.join(trackerDir, 'app');
   const trackerBinPath = path.join(appDir, 'bin', 'tracker.js');
@@ -98,8 +100,8 @@ async function cmdInit(argv) {
       opts,
       home,
       trackerDir,
-      configPath,
-      notifyPath
+      notifyPath,
+      runtime
     });
     renderLocalReport({ summary: preview.summary, isDryRun: true });
     if (preview.pendingBrowserAuth) {
@@ -125,7 +127,9 @@ async function cmdInit(argv) {
       linkCodeStatePath,
       notifyPath,
       appDir,
-      trackerBinPath
+      trackerBinPath,
+      runtime,
+      existingConfig
     });
   } catch (err) {
     spinner.stop();
@@ -140,7 +144,6 @@ async function cmdInit(argv) {
 
   if (setup.pendingBrowserAuth) {
     const deviceName = opts.deviceName || os.hostname();
-    if (!dashboardUrl) dashboardUrl = await detectLocalDashboardUrl();
     const flow = await beginBrowserAuth({ baseUrl, dashboardUrl, timeoutMs: 10 * 60_000, open: false });
     const canAutoOpen = !opts.noOpen;
     renderAuthTransition({ authUrl: flow.authUrl, canAutoOpen });
@@ -157,7 +160,6 @@ async function cmdInit(argv) {
     const resolvedDashboardUrl = dashboardUrl || null;
     renderSuccessBox({ configPath, dashboardUrl: resolvedDashboardUrl });
   } else if (deviceToken) {
-    if (!dashboardUrl) dashboardUrl = await detectLocalDashboardUrl();
     const resolvedDashboardUrl = dashboardUrl || null;
     renderSuccessBox({ configPath, dashboardUrl: resolvedDashboardUrl });
   } else {
@@ -209,10 +211,8 @@ function shouldUseBrowserAuth({ deviceToken, opts }) {
   return true;
 }
 
-async function buildDryRunSummary({ opts, home, trackerDir, configPath, notifyPath }) {
-  const existingConfig = await readJson(configPath);
-  const deviceTokenFromEnv = process.env.VIBEUSAGE_DEVICE_TOKEN || process.env.VIBESCORE_DEVICE_TOKEN || null;
-  const deviceToken = deviceTokenFromEnv || existingConfig?.deviceToken || null;
+async function buildDryRunSummary({ opts, home, trackerDir, notifyPath, runtime }) {
+  const deviceToken = runtime?.deviceToken || null;
   const pendingBrowserAuth = shouldUseBrowserAuth({ deviceToken, opts });
   const context = buildIntegrationTargets({ home, trackerDir, notifyPath });
   const summary = await previewIntegrations({ context });
@@ -230,15 +230,13 @@ async function runSetup({
   linkCodeStatePath,
   notifyPath,
   appDir,
-  trackerBinPath
+  trackerBinPath,
+  runtime,
+  existingConfig
 }) {
   await ensureDir(trackerDir);
   await ensureDir(binDir);
-
-  const existingConfig = await readJson(configPath);
-  const deviceTokenFromEnv = process.env.VIBEUSAGE_DEVICE_TOKEN || process.env.VIBESCORE_DEVICE_TOKEN || null;
-
-  let deviceToken = deviceTokenFromEnv || existingConfig?.deviceToken || null;
+  let deviceToken = runtime?.deviceToken || null;
   let deviceId = existingConfig?.deviceId || null;
   const installedAt = existingConfig?.installedAt || new Date().toISOString();
   let pendingBrowserAuth = false;
@@ -611,7 +609,7 @@ try {
 // Throttle spawn: at most once per 20 seconds.
 try {
     const throttlePath = path.join(trackerDir, 'sync.throttle');
-    let deviceToken = process.env.VIBEUSAGE_DEVICE_TOKEN || process.env.VIBESCORE_DEVICE_TOKEN || null;
+    let deviceToken = process.env.VIBEUSAGE_DEVICE_TOKEN || null;
     if (!deviceToken) {
       try {
         const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
@@ -686,35 +684,6 @@ function isSelfNotify(cmd) {
 
 module.exports = { cmdInit };
 
-async function detectLocalDashboardUrl() {
-  // Dev-only convenience: prefer a local dashboard (if running) so the user sees our own UI first.
-  // Vite defaults to 5173, but may auto-increment if the port is taken.
-  const hosts = ['127.0.0.1', 'localhost'];
-  const ports = [5173, 5174, 5175, 5176, 5177];
-
-  for (const port of ports) {
-    for (const host of hosts) {
-      const base = `http://${host}:${port}`;
-      const ok = await checkUrlReachable(base);
-      if (ok) return base;
-    }
-  }
-  return null;
-}
-
-async function checkUrlReachable(url) {
-  const timeoutMs = 250;
-  try {
-    const controller = new AbortController();
-    const t = setTimeout(() => controller.abort(), timeoutMs);
-    const res = await fetch(url, { method: 'GET', signal: controller.signal });
-    clearTimeout(t);
-    return Boolean(res && res.ok);
-  } catch (_e) {
-    return false;
-  }
-}
-
 async function probeFile(p) {
   try {
     const st = await fs.stat(p);
@@ -794,5 +763,5 @@ async function copyRuntimeDependencies({ from, to }) {
 }
 
 function isDebugEnabled() {
-  return process.env.VIBEUSAGE_DEBUG === '1' || process.env.VIBESCORE_DEBUG === '1';
+  return process.env.VIBEUSAGE_DEBUG === '1';
 }

package/src/commands/status.js

@@ -25,7 +25,7 @@ async function cmdStatus(argv = []) {
   }
 
   const home = os.homedir();
-  const { trackerDir, binDir } = await resolveTrackerPaths({ home, migrate: true });
+  const { trackerDir, binDir } = await resolveTrackerPaths({ home });
   const configPath = path.join(trackerDir, 'config.json');
   const queuePath = path.join(trackerDir, 'queue.jsonl');
   const queueStatePath = path.join(trackerDir, 'queue.state.json');

package/src/commands/sync.js

@@ -16,7 +16,7 @@ const {
 } = require('../lib/rollout');
 const { drainQueueToCloud } = require('../lib/uploader');
 const { createProgress, renderBar, formatNumber, formatBytes } = require('../lib/progress');
-const { syncHeartbeat } = require('../lib/vibescore-api');
+const { syncHeartbeat } = require('../lib/vibeusage-api');
 const {
   DEFAULTS: UPLOAD_DEFAULTS,
   normalizeState: normalizeUploadState,
@@ -25,11 +25,12 @@ const {
   recordUploadFailure
 } = require('../lib/upload-throttle');
 const { resolveTrackerPaths } = require('../lib/tracker-paths');
+const { resolveRuntimeConfig } = require('../lib/runtime-config');
 
 async function cmdSync(argv) {
   const opts = parseArgs(argv);
   const home = os.homedir();
-  const { trackerDir } = await resolveTrackerPaths({ home, migrate: true });
+  const { trackerDir } = await resolveTrackerPaths({ home });
 
   await ensureDir(trackerDir);
 
@@ -169,11 +170,9 @@ async function cmdSync(argv) {
 
     progress?.stop();
 
-    const deviceToken = config?.deviceToken || process.env.VIBEUSAGE_DEVICE_TOKEN || process.env.VIBESCORE_DEVICE_TOKEN || null;
-    const baseUrl = config?.baseUrl ||
-      process.env.VIBEUSAGE_INSFORGE_BASE_URL ||
-      process.env.VIBESCORE_INSFORGE_BASE_URL ||
-      'https://5tmappuk.us-east.insforge.app';
+    const runtime = resolveRuntimeConfig({ config: config || {}, env: process.env });
+    const deviceToken = runtime.deviceToken;
+    const baseUrl = runtime.baseUrl;
 
     let uploadResult = null;
     let uploadAttempted = false;
@@ -202,7 +201,8 @@ async function cmdSync(argv) {
             retryAtMs: autoDecision.blockedUntilMs,
             reason,
             pendingBytes,
-            source: 'auto-throttled'
+            source: 'auto-throttled',
+            autoRetryNoSpawn: runtime.autoRetryNoSpawn
           });
         }
       }
@@ -251,7 +251,8 @@ async function cmdSync(argv) {
                 retryAtMs,
                 reason: 'backoff',
                 pendingBytes,
-                source: 'auto-error'
+                source: 'auto-error',
+                autoRetryNoSpawn: runtime.autoRetryNoSpawn
               });
             }
           }
@@ -278,7 +279,8 @@ async function cmdSync(argv) {
           retryAtMs,
           reason: 'backlog',
           pendingBytes,
-          source: 'auto-backlog'
+          source: 'auto-backlog',
+          autoRetryNoSpawn: runtime.autoRetryNoSpawn
         });
       }
     }
@@ -385,7 +387,7 @@ function deriveAutoSkipReason({ decision, state }) {
   return 'throttled';
 }
 
-async function scheduleAutoRetry({ trackerDir, retryAtMs, reason, pendingBytes, source }) {
+async function scheduleAutoRetry({ trackerDir, retryAtMs, reason, pendingBytes, source, autoRetryNoSpawn }) {
   const retryMs = coerceRetryMs(retryAtMs);
   if (!retryMs) return { scheduled: false, retryAtMs: 0 };
 
@@ -411,7 +413,7 @@ async function scheduleAutoRetry({ trackerDir, retryAtMs, reason, pendingBytes,
 
   const delayMs = Math.min(AUTO_RETRY_MAX_DELAY_MS, Math.max(0, retryMs - nowMs));
   if (delayMs <= 0) return { scheduled: false, retryAtMs: retryMs };
-  if (process.env.VIBEUSAGE_AUTO_RETRY_NO_SPAWN === '1' || process.env.VIBESCORE_AUTO_RETRY_NO_SPAWN === '1') {
+  if (autoRetryNoSpawn) {
     return { scheduled: false, retryAtMs: retryMs };
   }
 

package/src/commands/uninstall.js

@@ -16,10 +16,7 @@ const { resolveTrackerPaths } = require('../lib/tracker-paths');
 async function cmdUninstall(argv) {
   const opts = parseArgs(argv);
   const home = os.homedir();
-  const { trackerDir, binDir, legacyRootDir } = await resolveTrackerPaths({
-    home,
-    migrate: false
-  });
+  const { trackerDir, binDir } = await resolveTrackerPaths({ home });
   const codexHome = process.env.CODEX_HOME || path.join(home, '.codex');
   const codexConfigPath = path.join(codexHome, 'config.toml');
   const codeHome = process.env.CODE_HOME || path.join(home, '.code');
@@ -73,7 +70,6 @@ async function cmdUninstall(argv) {
 
   if (opts.purge) {
     await fs.rm(path.join(home, '.vibeusage'), { recursive: true, force: true }).catch(() => {});
-    await fs.rm(legacyRootDir, { recursive: true, force: true }).catch(() => {});
   }
 
   process.stdout.write(

package/src/lib/browser-auth.js

@@ -6,7 +6,7 @@ const DEFAULT_BASE_URL = 'https://5tmappuk.us-east.insforge.app';
 
 async function beginBrowserAuth({ baseUrl, dashboardUrl, timeoutMs, open }) {
   const nonce = crypto.randomBytes(16).toString('hex');
-  const callbackPath = `/vibescore/callback/${nonce}`;
+  const callbackPath = `/vibeusage/callback/${nonce}`;
   const authUrl = dashboardUrl ? new URL('/', dashboardUrl) : new URL('/auth/sign-up', baseUrl);
   const postAuthRedirect = resolvePostAuthRedirect({ dashboardUrl, authUrl });
   const { callbackUrl, waitForCallback } = await startLocalCallbackServer({

package/src/lib/debug-flags.js

@@ -1,8 +1,6 @@
 function stripDebugFlag(argv, env = process.env) {
   const filtered = Array.isArray(argv) ? argv.filter((arg) => arg !== '--debug') : [];
-  const debugEnv =
-    String(env?.VIBEUSAGE_DEBUG || '') === '1' ||
-    String(env?.VIBESCORE_DEBUG || '') === '1';
+  const debugEnv = String(env?.VIBEUSAGE_DEBUG || '') === '1';
   return { argv: filtered, debug: filtered.length !== (argv || []).length || debugEnv };
 }
 

package/src/lib/diagnostics.js

@@ -20,7 +20,7 @@ async function collectTrackerDiagnostics({
   codexHome = process.env.CODEX_HOME || path.join(home, '.codex'),
   codeHome = process.env.CODE_HOME || path.join(home, '.code')
 } = {}) {
-  const { trackerDir, binDir } = await resolveTrackerPaths({ home, migrate: true });
+  const { trackerDir, binDir } = await resolveTrackerPaths({ home });
   const configPath = path.join(trackerDir, 'config.json');
   const queuePath = path.join(trackerDir, 'queue.jsonl');
   const queueStatePath = path.join(trackerDir, 'queue.state.json');

package/src/lib/doctor.js

@@ -0,0 +1,343 @@
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+
+const { readJsonStrict } = require('./fs');
+
+async function buildDoctorReport({
+  runtime = {},
+  diagnostics = null,
+  fetch = globalThis.fetch,
+  now = () => new Date(),
+  paths = {}
+} = {}) {
+  const checks = [];
+
+  checks.push(...buildRuntimeChecks(runtime));
+
+  if (paths.trackerDir) {
+    checks.push(await checkTrackerDir(paths.trackerDir));
+  }
+  if (paths.configPath) {
+    checks.push(await checkConfigJson(paths.configPath));
+  }
+  if (paths.cliPath) {
+    checks.push(await checkCliEntrypoint(paths.cliPath));
+  }
+
+  checks.push(await checkNetwork({ baseUrl: runtime?.baseUrl || null, fetch }));
+
+  if (diagnostics) {
+    checks.push(...buildDiagnosticsChecks(diagnostics));
+  }
+
+  const summary = summarizeChecks(checks);
+
+  return {
+    version: 1,
+    generated_at: now().toISOString(),
+    ok: summary.critical === 0,
+    summary,
+    checks,
+    diagnostics
+  };
+}
+
+function buildRuntimeChecks(runtime = {}) {
+  const checks = [];
+  const baseUrl = typeof runtime.baseUrl === 'string' && runtime.baseUrl.trim() ? runtime.baseUrl.trim() : null;
+  const deviceToken = typeof runtime.deviceToken === 'string' && runtime.deviceToken.trim() ? 'set' : 'unset';
+  const dashboardUrl =
+    typeof runtime.dashboardUrl === 'string' && runtime.dashboardUrl.trim() ? runtime.dashboardUrl.trim() : null;
+  const httpTimeoutMs = Number.isFinite(Number(runtime.httpTimeoutMs)) ? Number(runtime.httpTimeoutMs) : null;
+  const debug = Boolean(runtime.debug);
+  const insforgeAnonKey = typeof runtime.insforgeAnonKey === 'string' && runtime.insforgeAnonKey.trim() ? 'set' : 'unset';
+  const autoRetryNoSpawn = Boolean(runtime.autoRetryNoSpawn);
+
+  checks.push({
+    id: 'runtime.base_url',
+    status: baseUrl ? 'ok' : 'fail',
+    detail: baseUrl ? 'base_url set' : 'base_url missing',
+    critical: false,
+    meta: {
+      base_url: baseUrl,
+      source: runtime?.sources?.baseUrl || null
+    }
+  });
+
+  checks.push({
+    id: 'runtime.device_token',
+    status: deviceToken === 'set' ? 'ok' : 'warn',
+    detail: deviceToken === 'set' ? 'device token set' : 'device token missing',
+    critical: false,
+    meta: {
+      device_token: deviceToken,
+      source: runtime?.sources?.deviceToken || null
+    }
+  });
+
+  checks.push({
+    id: 'runtime.dashboard_url',
+    status: 'ok',
+    detail: dashboardUrl ? 'dashboard_url set' : 'dashboard_url unset',
+    critical: false,
+    meta: {
+      dashboard_url: dashboardUrl,
+      source: runtime?.sources?.dashboardUrl || null
+    }
+  });
+
+  checks.push({
+    id: 'runtime.http_timeout_ms',
+    status: 'ok',
+    detail: 'http timeout resolved',
+    critical: false,
+    meta: {
+      http_timeout_ms: httpTimeoutMs,
+      source: runtime?.sources?.httpTimeoutMs || null
+    }
+  });
+
+  checks.push({
+    id: 'runtime.debug',
+    status: 'ok',
+    detail: debug ? 'debug enabled' : 'debug disabled',
+    critical: false,
+    meta: {
+      debug,
+      source: runtime?.sources?.debug || null
+    }
+  });
+
+  checks.push({
+    id: 'runtime.insforge_anon_key',
+    status: 'ok',
+    detail: insforgeAnonKey === 'set' ? 'anon key set' : 'anon key unset',
+    critical: false,
+    meta: {
+      anon_key: insforgeAnonKey,
+      source: runtime?.sources?.insforgeAnonKey || null
+    }
+  });
+
+  checks.push({
+    id: 'runtime.auto_retry_no_spawn',
+    status: 'ok',
+    detail: autoRetryNoSpawn ? 'auto retry spawn disabled' : 'auto retry spawn enabled',
+    critical: false,
+    meta: {
+      auto_retry_no_spawn: autoRetryNoSpawn,
+      source: runtime?.sources?.autoRetryNoSpawn || null
+    }
+  });
+
+  return checks;
+}
+
+async function checkTrackerDir(trackerDir) {
+  try {
+    const st = await fs.stat(trackerDir);
+    if (!st.isDirectory()) {
+      return {
+        id: 'fs.tracker_dir',
+        status: 'fail',
+        detail: 'tracker dir is not a directory',
+        critical: true,
+        meta: { path: trackerDir }
+      };
+    }
+    await fs.access(trackerDir, constants.R_OK);
+    return {
+      id: 'fs.tracker_dir',
+      status: 'ok',
+      detail: 'tracker dir readable',
+      critical: false,
+      meta: { path: trackerDir }
+    };
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return {
+        id: 'fs.tracker_dir',
+        status: 'warn',
+        detail: 'tracker dir missing',
+        critical: false,
+        meta: { path: trackerDir }
+      };
+    }
+    if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+      return {
+        id: 'fs.tracker_dir',
+        status: 'fail',
+        detail: 'tracker dir permission denied',
+        critical: true,
+        meta: { path: trackerDir, code: err.code }
+      };
+    }
+    return {
+      id: 'fs.tracker_dir',
+      status: 'fail',
+      detail: 'tracker dir error',
+      critical: true,
+      meta: { path: trackerDir, code: err?.code || 'error' }
+    };
+  }
+}
+
+async function checkConfigJson(configPath) {
+  const res = await readJsonStrict(configPath);
+  if (res.status === 'ok') {
+    return {
+      id: 'fs.config_json',
+      status: 'ok',
+      detail: 'config.json readable',
+      critical: false,
+      meta: { path: configPath }
+    };
+  }
+  if (res.status === 'missing') {
+    return {
+      id: 'fs.config_json',
+      status: 'warn',
+      detail: 'config.json missing',
+      critical: false,
+      meta: { path: configPath }
+    };
+  }
+  if (res.status === 'invalid') {
+    return {
+      id: 'fs.config_json',
+      status: 'fail',
+      detail: 'config.json invalid',
+      critical: true,
+      meta: { path: configPath }
+    };
+  }
+  return {
+    id: 'fs.config_json',
+    status: 'fail',
+    detail: 'config.json read error',
+    critical: true,
+    meta: { path: configPath }
+  };
+}
+
+async function checkCliEntrypoint(cliPath) {
+  try {
+    const st = await fs.stat(cliPath);
+    if (!st.isFile()) {
+      return {
+        id: 'cli.entrypoint',
+        status: 'fail',
+        detail: 'cli entrypoint is not a file',
+        critical: false,
+        meta: { path: cliPath }
+      };
+    }
+    await fs.access(cliPath, constants.R_OK);
+    if (process.platform !== 'win32') {
+      await fs.access(cliPath, constants.X_OK);
+    }
+    return {
+      id: 'cli.entrypoint',
+      status: 'ok',
+      detail: 'cli entrypoint readable',
+      critical: false,
+      meta: { path: cliPath }
+    };
+  } catch (err) {
+    return {
+      id: 'cli.entrypoint',
+      status: 'fail',
+      detail: 'cli entrypoint not accessible',
+      critical: false,
+      meta: { path: cliPath, code: err?.code || 'error' }
+    };
+  }
+}
+
+async function checkNetwork({ baseUrl, fetch }) {
+  if (!baseUrl) {
+    return {
+      id: 'network.base_url',
+      status: 'warn',
+      detail: 'base_url missing (skipped)',
+      critical: false,
+      meta: { base_url: null }
+    };
+  }
+
+  const start = Date.now();
+  try {
+    if (typeof fetch !== 'function') throw new Error('Missing fetch');
+    const res = await fetch(baseUrl, { method: 'GET' });
+    const latency = Date.now() - start;
+    return {
+      id: 'network.base_url',
+      status: 'ok',
+      detail: `HTTP ${res.status} (reachable)`,
+      critical: false,
+      meta: {
+        status_code: res.status,
+        latency_ms: latency,
+        base_url: baseUrl
+      }
+    };
+  } catch (err) {
+    const latency = Date.now() - start;
+    return {
+      id: 'network.base_url',
+      status: 'fail',
+      detail: 'Network error',
+      critical: false,
+      meta: {
+        error: err?.message || String(err),
+        latency_ms: latency,
+        base_url: baseUrl
+      }
+    };
+  }
+}
+
+function buildDiagnosticsChecks(diagnostics) {
+  const checks = [];
+  const notify = diagnostics?.notify || {};
+  const notifyConfigured = Boolean(
+    notify.codex_notify_configured ||
+      notify.every_code_notify_configured ||
+      notify.claude_hook_configured ||
+      notify.gemini_hook_configured ||
+      notify.opencode_plugin_configured
+  );
+
+  checks.push({
+    id: 'notify.configured',
+    status: notifyConfigured ? 'ok' : 'warn',
+    detail: notifyConfigured ? 'notify configured' : 'notify not configured',
+    critical: false,
+    meta: { configured: notifyConfigured }
+  });
+
+  const uploadError = diagnostics?.upload?.last_error || null;
+  checks.push({
+    id: 'upload.last_error',
+    status: uploadError ? 'warn' : 'ok',
+    detail: uploadError ? 'last upload error present' : 'no upload errors',
+    critical: false,
+    meta: { last_error: uploadError ? uploadError.message || null : null }
+  });
+
+  return checks;
+}
+
+function summarizeChecks(checks = []) {
+  const summary = { ok: 0, warn: 0, fail: 0, critical: 0 };
+  for (const check of checks) {
+    if (!check || typeof check.status !== 'string') continue;
+    if (check.status === 'ok') summary.ok += 1;
+    else if (check.status === 'warn') summary.warn += 1;
+    else if (check.status === 'fail') summary.fail += 1;
+    if (check.status === 'fail' && check.critical) summary.critical += 1;
+  }
+  return summary;
+}
+
+module.exports = { buildDoctorReport };

package/src/lib/fs.js

@@ -22,6 +22,21 @@ async function readJson(filePath) {
   }
 }
 
+async function readJsonStrict(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return { status: 'ok', value: JSON.parse(raw), error: null };
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return { status: 'missing', value: null, error: err };
+    }
+    if (err && err.name === 'SyntaxError') {
+      return { status: 'invalid', value: null, error: err };
+    }
+    return { status: 'error', value: null, error: err };
+  }
+}
+
 async function writeJson(filePath, obj) {
   await writeFileAtomic(filePath, JSON.stringify(obj, null, 2) + '\n');
 }
@@ -55,8 +70,8 @@ module.exports = {
   ensureDir,
   writeFileAtomic,
   readJson,
+  readJsonStrict,
   writeJson,
   chmod600IfPossible,
   openLock
 };
-

package/src/lib/insforge-client.js

@@ -11,16 +11,11 @@ function loadInsforgeSdk() {
 }
 
 function getAnonKey({ env = process.env } = {}) {
-  return (
-    env.VIBEUSAGE_INSFORGE_ANON_KEY ||
-    env.VIBESCORE_INSFORGE_ANON_KEY ||
-    env.INSFORGE_ANON_KEY ||
-    ''
-  );
+  return env.VIBEUSAGE_INSFORGE_ANON_KEY || '';
 }
 
 function getHttpTimeoutMs({ env = process.env } = {}) {
-  const raw = readEnvValue(env, ['VIBEUSAGE_HTTP_TIMEOUT_MS', 'VIBESCORE_HTTP_TIMEOUT_MS']);
+  const raw = readEnvValue(env, ['VIBEUSAGE_HTTP_TIMEOUT_MS']);
   if (raw == null || raw === '') return 20_000;
   const n = Number(raw);
   if (!Number.isFinite(n)) return 20_000;

package/src/lib/insforge.js

@@ -1,4 +1,4 @@
-const { exchangeLinkCode, issueDeviceToken, signInWithPassword } = require('./vibescore-api');
+const { exchangeLinkCode, issueDeviceToken, signInWithPassword } = require('./vibeusage-api');
 
 async function issueDeviceTokenWithPassword({ baseUrl, email, password, deviceName }) {
   const accessToken = await signInWithPassword({ baseUrl, email, password });

package/src/lib/runtime-config.js

@@ -0,0 +1,120 @@
+const DEFAULT_BASE_URL = 'https://5tmappuk.us-east.insforge.app';
+const DEFAULT_DASHBOARD_URL = 'https://www.vibeusage.cc';
+const DEFAULT_HTTP_TIMEOUT_MS = 20_000;
+
+function resolveRuntimeConfig({ cli = {}, config = {}, env = process.env, defaults = {} } = {}) {
+  const baseUrl = pickString(cli.baseUrl, config.baseUrl, env?.VIBEUSAGE_INSFORGE_BASE_URL, defaults.baseUrl, DEFAULT_BASE_URL);
+  const dashboardUrl = pickString(
+    cli.dashboardUrl,
+    config.dashboardUrl,
+    env?.VIBEUSAGE_DASHBOARD_URL,
+    defaults.dashboardUrl,
+    DEFAULT_DASHBOARD_URL
+  );
+  const deviceToken = pickString(cli.deviceToken, config.deviceToken, env?.VIBEUSAGE_DEVICE_TOKEN, defaults.deviceToken, null);
+  const httpTimeoutMs = pickHttpTimeoutMs(
+    cli.httpTimeoutMs,
+    config.httpTimeoutMs,
+    env?.VIBEUSAGE_HTTP_TIMEOUT_MS,
+    defaults.httpTimeoutMs,
+    DEFAULT_HTTP_TIMEOUT_MS
+  );
+  const debug = pickBoolean(cli.debug, config.debug, env?.VIBEUSAGE_DEBUG, defaults.debug, false);
+  const insforgeAnonKey = pickString(
+    cli.insforgeAnonKey,
+    config.insforgeAnonKey,
+    env?.VIBEUSAGE_INSFORGE_ANON_KEY,
+    defaults.insforgeAnonKey,
+    ''
+  );
+  if (insforgeAnonKey.value == null) insforgeAnonKey.value = '';
+  const autoRetryNoSpawn = pickBoolean(
+    cli.autoRetryNoSpawn,
+    config.autoRetryNoSpawn,
+    env?.VIBEUSAGE_AUTO_RETRY_NO_SPAWN,
+    defaults.autoRetryNoSpawn,
+    false
+  );
+
+  return {
+    baseUrl: baseUrl.value,
+    dashboardUrl: dashboardUrl.value,
+    deviceToken: deviceToken.value,
+    httpTimeoutMs: httpTimeoutMs.value,
+    debug: debug.value,
+    insforgeAnonKey: insforgeAnonKey.value,
+    autoRetryNoSpawn: autoRetryNoSpawn.value,
+    sources: {
+      baseUrl: baseUrl.source,
+      dashboardUrl: dashboardUrl.source,
+      deviceToken: deviceToken.source,
+      httpTimeoutMs: httpTimeoutMs.source,
+      debug: debug.source,
+      insforgeAnonKey: insforgeAnonKey.source,
+      autoRetryNoSpawn: autoRetryNoSpawn.source
+    }
+  };
+}
+
+function pickString(...candidates) {
+  return pickValue(candidates, normalizeString);
+}
+
+function pickBoolean(...candidates) {
+  return pickValue(candidates, normalizeBoolean);
+}
+
+function pickHttpTimeoutMs(...candidates) {
+  return pickValue(candidates, normalizeHttpTimeoutMs);
+}
+
+function pickValue(candidates, normalize) {
+  const labels = ['cli', 'config', 'env', 'default', 'default'];
+  for (let i = 0; i < candidates.length; i += 1) {
+    const value = normalize(candidates[i]);
+    if (value !== undefined) {
+      return { value, source: labels[i] || 'default' };
+    }
+  }
+  return { value: null, source: 'default' };
+}
+
+function normalizeString(value) {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  return trimmed;
+}
+
+function normalizeBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value !== 0;
+  if (typeof value === 'string') {
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed) return undefined;
+    if (trimmed === '1' || trimmed === 'true') return true;
+    if (trimmed === '0' || trimmed === 'false') return false;
+  }
+  return undefined;
+}
+
+function normalizeHttpTimeoutMs(value) {
+  if (value == null || value === '') return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return undefined;
+  if (n <= 0) return 0;
+  return clampInt(n, 1000, 120_000);
+}
+
+function clampInt(value, min, max) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return min;
+  return Math.min(max, Math.max(min, Math.floor(n)));
+}
+
+module.exports = {
+  DEFAULT_BASE_URL,
+  DEFAULT_DASHBOARD_URL,
+  DEFAULT_HTTP_TIMEOUT_MS,
+  resolveRuntimeConfig
+};

package/src/lib/tracker-paths.js

@@ -1,66 +1,15 @@
 const os = require('node:os');
 const path = require('node:path');
-const fs = require('node:fs/promises');
 
-async function resolveTrackerPaths({ home = os.homedir(), migrate = true } = {}) {
-  const legacyRootDir = path.join(home, '.vibescore');
+async function resolveTrackerPaths({ home = os.homedir() } = {}) {
   const rootDir = path.join(home, '.vibeusage');
-  const legacyTrackerDir = path.join(legacyRootDir, 'tracker');
-  const legacyBinDir = path.join(legacyRootDir, 'bin');
-  const trackerDir = path.join(rootDir, 'tracker');
-  const binDir = path.join(rootDir, 'bin');
-
-  const legacyExists = await pathExists(legacyRootDir);
-  const newExists = await pathExists(rootDir);
-
-  let usingLegacy = false;
-  let migrated = false;
-
-  if (migrate && legacyExists && !newExists) {
-    const result = await migrateLegacyRoot({ legacyRootDir, rootDir });
-    usingLegacy = result.usingLegacy;
-    migrated = result.migrated;
-  } else if (!newExists && legacyExists) {
-    usingLegacy = true;
-  }
-
-  const activeRootDir = usingLegacy ? legacyRootDir : rootDir;
   return {
-    rootDir: activeRootDir,
-    trackerDir: path.join(activeRootDir, 'tracker'),
-    binDir: path.join(activeRootDir, 'bin'),
-    legacyRootDir,
-    legacyTrackerDir,
-    legacyBinDir,
-    migrated,
-    usingLegacy
+    rootDir,
+    trackerDir: path.join(rootDir, 'tracker'),
+    binDir: path.join(rootDir, 'bin')
   };
 }
 
-async function migrateLegacyRoot({ legacyRootDir, rootDir }) {
-  try {
-    await fs.rename(legacyRootDir, rootDir);
-    return { migrated: true, usingLegacy: false };
-  } catch (err) {
-    try {
-      await fs.cp(legacyRootDir, rootDir, { recursive: true });
-      return { migrated: true, usingLegacy: false };
-    } catch (copyErr) {
-      return { migrated: false, usingLegacy: true, error: copyErr };
-    }
-  }
-}
-
-async function pathExists(target) {
-  try {
-    await fs.stat(target);
-    return true;
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return false;
-    throw err;
-  }
-}
-
 module.exports = {
   resolveTrackerPaths
 };

package/src/lib/uploader.js

@@ -3,7 +3,7 @@ const fssync = require('node:fs');
 const readline = require('node:readline');
 
 const { ensureDir, readJson, writeJson } = require('./fs');
-const { ingestHourly } = require('./vibescore-api');
+const { ingestHourly } = require('./vibeusage-api');
 
 const DEFAULT_SOURCE = 'codex';
 const DEFAULT_MODEL = 'unknown';

package/src/lib/{vibescore-api.js → vibeusage-api.js}

@@ -19,7 +19,7 @@ async function issueDeviceToken({ baseUrl, accessToken, deviceName, platform = '
   const data = await invokeFunction({
     baseUrl,
     accessToken,
-    slug: 'vibescore-device-token-issue',
+    slug: 'vibeusage-device-token-issue',
     method: 'POST',
     body: { device_name: deviceName, platform },
     errorPrefix: 'Device token issue failed'
@@ -39,7 +39,7 @@ async function exchangeLinkCode({ baseUrl, linkCode, requestId, deviceName, plat
   const data = await invokeFunction({
     baseUrl,
     accessToken: null,
-    slug: 'vibescore-link-code-exchange',
+    slug: 'vibeusage-link-code-exchange',
     method: 'POST',
     body: {
       link_code: linkCode,
@@ -66,7 +66,7 @@ async function ingestHourly({ baseUrl, deviceToken, hourly }) {
   const data = await invokeFunctionWithRetry({
     baseUrl,
     accessToken: deviceToken,
-    slug: 'vibescore-ingest',
+    slug: 'vibeusage-ingest',
     method: 'POST',
     body: { hourly },
     errorPrefix: 'Ingest failed',
@@ -83,7 +83,7 @@ async function syncHeartbeat({ baseUrl, deviceToken }) {
   const data = await invokeFunction({
     baseUrl,
     accessToken: deviceToken,
-    slug: 'vibescore-sync-ping',
+    slug: 'vibeusage-sync-ping',
     method: 'POST',
     body: {},
     errorPrefix: 'Sync heartbeat failed'