@ipv9/tokentracker-cli 0.39.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ipv9/tokentracker-cli",
+  "version": "0.39.0",
+  "description": "Token usage tracker for AI agent CLIs (Claude Code, Codex, Cursor, Gemini, Kiro, OpenCode, OpenClaw, Every Code, Hermes, GitHub Copilot, Kimi Code, CodeBuddy, Grok Build, oh-my-pi, pi, Craft Agents, Kilo CLI, Kilo Code, Roo Code, Zed Agent, Goose)",
+  "main": "src/cli.js",
+  "bin": {
+    "tokentracker-cli": "bin/tracker.js",
+    "tracker": "bin/tracker.js",
+    "tokentracker": "bin/tracker.js",
+    "tokentracker-tracker": "bin/tracker.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "dashboard/dist/",
+    "scripts/install-local-service.sh",
+    "scripts/uninstall-local-service.sh",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "ci:local": "npm test && npm run validate:copy && npm run validate:ui-hardcode && npm run validate:guardrails && node --test test/architecture-guardrails.test.js && npm --prefix dashboard run build",
+    "copy:pull": "node scripts/copy-sync.cjs pull",
+    "copy:push": "node scripts/copy-sync.cjs push",
+    "dashboard:build": "npm --prefix dashboard run build",
+    "dashboard:dev": "npm --prefix dashboard run dev",
+    "dashboard:open": "bash scripts/open-dashboard.sh",
+    "dashboard:preview": "npm --prefix dashboard run preview",
+    "dev:shim": "node scripts/dev-bin-shim.cjs",
+    "audit:tokens": "node scripts/audit-token-correctness.cjs",
+    "graph:auto-index": "node scripts/graph/auto-index.cjs",
+    "graph:scip": "node scripts/graph/generate-scip.cjs",
+    "pricing:build-seed": "node scripts/build-pricing-seed.cjs",
+    "prepublishOnly": "node scripts/build-pricing-seed.cjs",
+    "test": "node --test test/*.test.js",
+    "validate:copy": "node scripts/validate-copy-registry.cjs",
+    "validate:guardrails": "node scripts/validate-architecture-guardrails.cjs",
+    "validate:retros": "node scripts/validate-retros.cjs",
+    "validate:ui-hardcode": "node scripts/ops/validate-ui-hardcode.cjs"
+  },
+  "dependencies": {
+    "@mongodb-js/zstd": "^2.0.1",
+    "undici": "^8.2.0"
+  },
+  "devDependencies": {
+    "@sourcegraph/scip-typescript": "^0.3.6",
+    "esbuild": "0.27.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pitimon/TokenTracker.git"
+  },
+  "homepage": "https://github.com/pitimon/TokenTracker#readme",
+  "bugs": {
+    "url": "https://github.com/pitimon/TokenTracker/issues"
+  },
+  "keywords": [
+    "token",
+    "tracker",
+    "ai",
+    "claude",
+    "codex",
+    "cursor",
+    "gemini",
+    "kiro",
+    "opencode",
+    "usage",
+    "cost"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/install-local-service.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PORT="${TOKENTRACKER_DASHBOARD_PORT:-7680}"
+PACKAGE_NAME="${TOKENTRACKER_NPM_PACKAGE:-@ipv9/tokentracker-cli}"
+TRACKER_HOME="${TOKENTRACKER_HOME:-$HOME/.tokentracker}"
+SERVICE_PATH="${TOKENTRACKER_SERVICE_PATH:-/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin}"
+LOG_DIR="$TRACKER_HOME/tracker/logs"
+BIN_DIR="$TRACKER_HOME/bin"
+AGENTS_DIR="$HOME/Library/LaunchAgents"
+DASHBOARD_LABEL="com.pitimon.tokentracker.dashboard"
+LOCAL_SYNC_LABEL="com.pitimon.tokentracker.local-sync"
+DASHBOARD_PLIST="$AGENTS_DIR/$DASHBOARD_LABEL.plist"
+LOCAL_SYNC_PLIST="$AGENTS_DIR/$LOCAL_SYNC_LABEL.plist"
+LOCAL_SYNC_WRAPPER="$BIN_DIR/tokentracker-local-sync-service.sh"
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "TokenTracker local service installer currently supports macOS launchd only." >&2
+  exit 1
+fi
+
+mkdir -p "$LOG_DIR" "$BIN_DIR" "$AGENTS_DIR"
+
+cat > "$LOCAL_SYNC_WRAPPER" <<'WRAPPER'
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONFIG_PATH="${TOKENTRACKER_CONFIG_PATH:-$HOME/.tokentracker/tracker/config.json}"
+PACKAGE_NAME="${TOKENTRACKER_NPM_PACKAGE:-@ipv9/tokentracker-cli}"
+export PATH="${TOKENTRACKER_SERVICE_PATH:-/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin}"
+
+if [[ -n "${TOKENTRACKER_DEVICE_TOKEN:-}" ]]; then
+  echo "TokenTracker local-sync skipped: TOKENTRACKER_DEVICE_TOKEN is configured."
+  exit 0
+fi
+
+if [[ -f "$CONFIG_PATH" ]]; then
+  HAS_DEVICE_TOKEN="$(node -e '
+const fs = require("node:fs");
+const p = process.argv[1];
+try {
+  const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+  process.stdout.write(typeof cfg.deviceToken === "string" && cfg.deviceToken.trim() ? "1" : "0");
+} catch {
+  process.stdout.write("0");
+}
+' "$CONFIG_PATH")"
+  if [[ "$HAS_DEVICE_TOKEN" == "1" ]]; then
+    echo "TokenTracker local-sync skipped: deviceToken is configured."
+    exit 0
+  fi
+fi
+
+exec npx --yes "$PACKAGE_NAME" sync --auto
+WRAPPER
+chmod 0755 "$LOCAL_SYNC_WRAPPER"
+
+launchctl bootout "gui/$(id -u)" "$DASHBOARD_PLIST" >/dev/null 2>&1 || true
+launchctl bootout "gui/$(id -u)" "$LOCAL_SYNC_PLIST" >/dev/null 2>&1 || true
+
+cat > "$DASHBOARD_PLIST" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>$DASHBOARD_LABEL</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/env</string>
+    <string>npx</string>
+    <string>--yes</string>
+    <string>$PACKAGE_NAME</string>
+    <string>serve</string>
+    <string>--no-open</string>
+    <string>--port</string>
+    <string>$PORT</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>$SERVICE_PATH</string>
+    <key>TOKENTRACKER_NPM_PACKAGE</key>
+    <string>$PACKAGE_NAME</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>$LOG_DIR/dashboard.log</string>
+  <key>StandardErrorPath</key>
+  <string>$LOG_DIR/dashboard.err.log</string>
+  <key>WorkingDirectory</key>
+  <string>$HOME</string>
+</dict>
+</plist>
+PLIST
+
+cat > "$LOCAL_SYNC_PLIST" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>$LOCAL_SYNC_LABEL</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$LOCAL_SYNC_WRAPPER</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StartInterval</key>
+  <integer>300</integer>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>$SERVICE_PATH</string>
+    <key>TOKENTRACKER_NPM_PACKAGE</key>
+    <string>$PACKAGE_NAME</string>
+    <key>TOKENTRACKER_SERVICE_PATH</key>
+    <string>$SERVICE_PATH</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>$LOG_DIR/local-sync.log</string>
+  <key>StandardErrorPath</key>
+  <string>$LOG_DIR/local-sync.err.log</string>
+  <key>WorkingDirectory</key>
+  <string>$HOME</string>
+</dict>
+</plist>
+PLIST
+
+launchctl bootstrap "gui/$(id -u)" "$DASHBOARD_PLIST"
+launchctl bootstrap "gui/$(id -u)" "$LOCAL_SYNC_PLIST"
+
+echo "Installed TokenTracker local services:"
+echo "  $DASHBOARD_LABEL -> http://127.0.0.1:$PORT/dashboard"
+echo "  $LOCAL_SYNC_LABEL -> local sync every 5 minutes, skips when deviceToken is configured"
+echo "Logs: $LOG_DIR"

package/scripts/uninstall-local-service.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENTS_DIR="$HOME/Library/LaunchAgents"
+DASHBOARD_LABEL="com.pitimon.tokentracker.dashboard"
+LOCAL_SYNC_LABEL="com.pitimon.tokentracker.local-sync"
+DASHBOARD_PLIST="$AGENTS_DIR/$DASHBOARD_LABEL.plist"
+LOCAL_SYNC_PLIST="$AGENTS_DIR/$LOCAL_SYNC_LABEL.plist"
+LOCAL_SYNC_WRAPPER="${TOKENTRACKER_HOME:-$HOME/.tokentracker}/bin/tokentracker-local-sync-service.sh"
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "TokenTracker local service uninstaller currently supports macOS launchd only." >&2
+  exit 1
+fi
+
+launchctl bootout "gui/$(id -u)" "$DASHBOARD_PLIST" >/dev/null 2>&1 || true
+launchctl bootout "gui/$(id -u)" "$LOCAL_SYNC_PLIST" >/dev/null 2>&1 || true
+
+rm -f "$DASHBOARD_PLIST" "$LOCAL_SYNC_PLIST" "$LOCAL_SYNC_WRAPPER"
+
+echo "Uninstalled TokenTracker local services."

package/src/cli.js

@@ -0,0 +1,95 @@
+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");
+const { cmdServe } = require("./commands/serve");
+const { cmdDeviceLogin } = require("./commands/device-login");
+const { cmdWrapped } = require("./commands/wrapped");
+
+async function run(argv) {
+  const [command, ...rest] = argv;
+
+  // No args → launch dashboard
+  if (!command) {
+    await cmdServe(argv);
+    return;
+  }
+
+  if (command === "-h" || command === "--help") {
+    printHelp();
+    return;
+  }
+
+  switch (command) {
+    case "serve":
+      await cmdServe(rest);
+      return;
+    case "init":
+      await cmdInit(rest);
+      return;
+    case "sync":
+      await cmdSync(rest);
+      return;
+    case "status":
+      await cmdStatus(rest);
+      return;
+    case "diagnostics":
+      await cmdDiagnostics(rest);
+      return;
+    case "doctor":
+      await cmdDoctor(rest);
+      return;
+    case "uninstall":
+      await cmdUninstall(rest);
+      return;
+    case "device-login":
+      await cmdDeviceLogin(rest);
+      return;
+    case "wrapped":
+      await cmdWrapped(rest);
+      return;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+function printHelp() {
+  // Keep this short; npx users want quick guidance.
+  process.stdout.write(
+    [
+      "tokentracker",
+      "",
+      "Usage:",
+      "  npx --yes @ipv9/tokentracker-cli                                         Open local dashboard",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] serve [--port 7680] [--no-open] [--sync]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] init [--yes] [--dry-run] [--no-open] [--link-code <code>]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] sync [--auto] [--drain] [--from-openclaw]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] status [--probe-keychain] [--probe-keychain-details]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] diagnostics [--out diagnostics.json]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] doctor [--json] [--out doctor.json] [--base-url <url>]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] uninstall [--purge]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] device-login [--json] [--base-url <url>]",
+      "  npx --yes @ipv9/tokentracker-cli [--debug] wrapped [--year 2026] [--json]",
+      "",
+      "Notes:",
+      "  - init: consent first, local setup next, browser sign-in last.",
+      "  - --yes skips the consent menu (non-interactive safe).",
+      "  - --dry-run previews changes without writing files.",
+      "  - optional: --link-code <code> skips browser login when provided by Dashboard.",
+      "  - Every Code notify installs when ~/.code/config.toml exists.",
+      "  - OpenClaw hook auto-links when OpenClaw is installed (requires gateway restart).",
+      "  - auto sync waits for a device token.",
+      "  - optional: --dashboard-url for hosted landing.",
+      "  - serve opens the local dashboard without syncing; pass --sync to parse local logs first.",
+      "  - sync parses ~/.codex/sessions/**/rollout-*.jsonl and ~/.code/sessions/**/rollout-*.jsonl, then uploads token deltas only when cloud credentials are configured.",
+      "  - --from-openclaw marks sync runs triggered by OpenClaw hooks.",
+      "  - --debug shows original backend errors.",
+      "  - device-login pairs a headless CLI / SSH session with a browser sign-in (15-min code).",
+      "",
+    ].join("\n"),
+  );
+}
+
+module.exports = { run };

package/src/commands/device-login.js

@@ -0,0 +1,161 @@
+"use strict";
+
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+
+const { readJson, writeJson } = require("../lib/fs");
+const { resolveTrackerPaths } = require("../lib/tracker-paths");
+
+const DEFAULT_BASE_URL = "https://srctyff5.us-east.insforge.app";
+const POLL_INTERVAL_MS = 5_000;
+const ABSOLUTE_TIMEOUT_MS = 16 * 60 * 1000; // matches the 15-min server window with a small buffer
+
+function readBaseUrl(config) {
+  return (
+    process.env.TOKENTRACKER_BASE_URL ||
+    process.env.TOKENTRACKER_API_URL ||
+    config?.baseUrl ||
+    DEFAULT_BASE_URL
+  );
+}
+
+async function authorize({ baseUrl, clientInfo }) {
+  const res = await fetch(`${baseUrl}/functions/tokentracker-device-flow-authorize`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ client_info: clientInfo }),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`authorize failed (HTTP ${res.status}): ${text.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+async function pollOnce({ baseUrl, deviceCode }) {
+  const res = await fetch(`${baseUrl}/functions/tokentracker-device-flow-poll`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ device_code: deviceCode }),
+  });
+  const data = await res.json().catch(() => ({}));
+  // 404 = unknown, 410 = expired, 200 = {status, user_id?, device_token?}.
+  // Anything else (502 from a misconfigured edge, 5xx during deploy, …) must
+  // bubble up as a network-style error — masking it as "unknown" would tell
+  // the user their device_code was evicted when it wasn't.
+  if (!res.ok && res.status !== 404 && res.status !== 410) {
+    throw new Error(`poll HTTP ${res.status}: ${(data?.error ?? "").toString().slice(0, 200)}`);
+  }
+  return {
+    status: data.status ?? "unknown",
+    user_id: data.user_id ?? null,
+    deviceToken: data.device_token ?? data.deviceToken ?? null,
+    deviceId: data.device_id ?? data.deviceId ?? null,
+    httpStatus: res.status,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function cmdDeviceLogin(argv = [], options = {}) {
+  const opts = parseArgs(argv);
+  const home = options.home || os.homedir();
+  const sleepFn = options.sleep || sleep;
+  const { trackerDir } = await resolveTrackerPaths({ home });
+  const configPath = path.join(trackerDir, "config.json");
+  const config = (await readJson(configPath)) || {};
+  const baseUrl = opts.baseUrl || readBaseUrl(config);
+
+  const clientInfo = `${os.platform()}-${os.arch()} ${os.hostname()}`;
+  process.stdout.write(`Requesting device code from ${baseUrl}...\n`);
+  const authResp = await authorize({ baseUrl, clientInfo });
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(authResp, null, 2) + "\n");
+  } else {
+    process.stdout.write(
+      [
+        "",
+        "  Sign in from a browser:",
+        `    ${authResp.verification_uri_complete || authResp.verification_uri}`,
+        "",
+        `  Or visit ${authResp.verification_uri} and enter the code:`,
+        "",
+        `      ${authResp.user_code}`,
+        "",
+        `  This code expires in ${Math.round(authResp.expires_in / 60)} minutes.`,
+        "  Polling every 5 seconds until you approve…",
+        "",
+      ].join("\n"),
+    );
+  }
+
+  const startedAt = Date.now();
+  let consecutiveErrors = 0;
+  const MAX_BACKOFF_MS = 30_000;
+  while (Date.now() - startedAt < ABSOLUTE_TIMEOUT_MS) {
+    // Exponential backoff on consecutive network failures (capped at 30s) so
+    // a flaky network doesn't hammer the server at the full 5s cadence for
+    // the entire 15-minute window. ±20% jitter on retries prevents
+    // thundering-herd reconnects when many CLIs lose connectivity at once.
+    let wait =
+      consecutiveErrors === 0
+        ? POLL_INTERVAL_MS
+        : Math.min(POLL_INTERVAL_MS * Math.pow(2, consecutiveErrors - 1), MAX_BACKOFF_MS);
+    if (consecutiveErrors > 0) {
+      const jitter = wait * 0.2 * (Math.random() * 2 - 1);
+      wait = Math.max(POLL_INTERVAL_MS, wait + jitter);
+    }
+    await sleepFn(wait);
+    let result;
+    try {
+      result = await pollOnce({ baseUrl, deviceCode: authResp.device_code });
+      consecutiveErrors = 0;
+    } catch (e) {
+      consecutiveErrors++;
+      process.stderr.write(`poll error (retry ${consecutiveErrors}): ${e?.message || e}\n`);
+      continue;
+    }
+    if (result.status === "approved" && result.user_id) {
+      if (!result.deviceToken) {
+        throw new Error("device login approved but server did not return a device token");
+      }
+      const next = {
+        ...config,
+        baseUrl,
+        user_id: result.user_id,
+        deviceToken: result.deviceToken,
+        deviceId: result.deviceId || config.deviceId,
+        device_login_at: new Date().toISOString(),
+      };
+      await writeJson(configPath, next);
+      process.stdout.write(`\n✓ Approved. device token written to ${configPath}\n`);
+      return;
+    }
+    if (result.status === "expired") {
+      throw new Error("device_code expired — re-run `tracker device-login`");
+    }
+    if (result.status === "unknown") {
+      throw new Error("device_code is unknown — server may have evicted it");
+    }
+    // status === "pending" → just keep polling silently
+  }
+  throw new Error("device-login timed out without approval");
+}
+
+function parseArgs(argv) {
+  const out = { json: false, baseUrl: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--base-url") {
+      out.baseUrl = argv[++i] || null;
+    } else throw new Error(`Unknown option: ${a}`);
+  }
+  return out;
+}
+
+module.exports = { cmdDeviceLogin, authorize, pollOnce };

package/src/commands/diagnostics.js

@@ -0,0 +1,38 @@
+const path = require("node:path");
+
+const { writeFileAtomic, chmod600IfPossible } = require("../lib/fs");
+const { collectTrackerDiagnostics } = require("../lib/diagnostics");
+
+async function cmdDiagnostics(argv = []) {
+  const opts = parseArgs(argv);
+  const diagnostics = await collectTrackerDiagnostics();
+  const json = JSON.stringify(diagnostics, null, opts.compact ? 0 : 2) + "\n";
+
+  if (opts.out) {
+    const outPath = path.resolve(process.cwd(), opts.out);
+    await writeFileAtomic(outPath, json);
+    await chmod600IfPossible(outPath);
+    process.stderr.write(`Wrote diagnostics to: ${outPath}\n`);
+  }
+
+  process.stdout.write(json);
+}
+
+function parseArgs(argv) {
+  const out = {
+    out: null,
+    compact: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--out") out.out = argv[++i] || null;
+    else if (a === "--compact") out.compact = true;
+    else if (a === "--pretty") out.compact = false;
+    else throw new Error(`Unknown option: ${a}`);
+  }
+
+  return out;
+}
+
+module.exports = { cmdDiagnostics };

package/src/commands/doctor.js

@@ -0,0 +1,96 @@
+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 };