@vibescore/tracker 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 victor-wu.eth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @vibescore/tracker
+
+Codex CLI token usage tracker (macOS-first, notify-driven).
+
+## Quick Start
+
+```bash
+npx --yes @vibescore/tracker init
+npx --yes @vibescore/tracker sync
+npx --yes @vibescore/tracker status
+npx --yes @vibescore/tracker uninstall
+```
+
+## Requirements
+
+- Node.js >= 18
+- macOS (current supported platform)
+
+## Notes
+
+- `init` installs a Codex CLI notify hook and issues a device token.
+- `sync` parses `~/.codex/sessions/**/rollout-*.jsonl` and uploads token_count deltas.
+
+## License
+
+MIT

package/bin/tracker.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const { run } = require('../src/cli');
+
+const { argv, debug } = stripDebugFlag(process.argv.slice(2));
+if (debug) process.env.VIBESCORE_DEBUG = '1';
+
+run(argv).catch((err) => {
+  console.error(err?.stack || String(err));
+  if (debug) {
+    const original = err?.originalMessage;
+    if (original && original !== err?.message) {
+      console.error(`Original error: ${original}`);
+    }
+  }
+  process.exitCode = 1;
+});
+
+function stripDebugFlag(argv) {
+  const filtered = argv.filter((arg) => arg !== '--debug');
+  return { argv: filtered, debug: filtered.length !== argv.length || process.env.VIBESCORE_DEBUG === '1' };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vibescore/tracker",
+  "version": "0.0.1",
+  "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "smoke": "node scripts/smoke/insforge-smoke.cjs",
+    "build:insforge": "node scripts/build-insforge-functions.cjs",
+    "build:insforge:check": "node scripts/build-insforge-functions.cjs --check",
+    "dashboard:dev": "npm --prefix dashboard run dev",
+    "dashboard:build": "npm --prefix dashboard run build",
+    "dashboard:preview": "npm --prefix dashboard run preview",
+    "dev:shim": "node scripts/dev-bin-shim.cjs",
+    "validate:copy": "node scripts/validate-copy-registry.cjs",
+    "copy:pull": "node scripts/copy-sync.cjs pull",
+    "copy:push": "node scripts/copy-sync.cjs push"
+  },
+  "bin": {
+    "tracker": "bin/tracker.js",
+    "vibescore-tracker": "bin/tracker.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "0.27.2"
+  },
+  "dependencies": {
+    "@insforge/sdk": "^1.0.4"
+  }
+}

package/src/cli.js

@@ -0,0 +1,59 @@
+const { cmdInit } = require('./commands/init');
+const { cmdSync } = require('./commands/sync');
+const { cmdStatus } = require('./commands/status');
+const { cmdDiagnostics } = require('./commands/diagnostics');
+const { cmdUninstall } = require('./commands/uninstall');
+
+async function run(argv) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === '-h' || command === '--help') {
+    printHelp();
+    return;
+  }
+
+  switch (command) {
+    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 'uninstall':
+      await cmdUninstall(rest);
+      return;
+    default:
+      throw new Error(`Unknown command: ${command}`);
+  }
+}
+
+function printHelp() {
+  // Keep this short; npx users want quick guidance.
+  process.stdout.write(
+    [
+      '@vibescore/tracker',
+      '',
+      'Usage:',
+      '  npx @vibescore/tracker [--debug] init',
+      '  npx @vibescore/tracker [--debug] sync [--auto] [--drain]',
+      '  npx @vibescore/tracker [--debug] status',
+      '  npx @vibescore/tracker [--debug] diagnostics [--out diagnostics.json]',
+      '  npx @vibescore/tracker [--debug] uninstall [--purge]',
+      '',
+      'Notes:',
+      '  - init installs a Codex notify hook and issues a device token (default: browser sign in/up).',
+      '  - optional: set VIBESCORE_DASHBOARD_URL (or --dashboard-url) to use a hosted /connect page.',
+      '  - sync parses ~/.codex/sessions/**/rollout-*.jsonl and uploads token_count deltas.',
+      '  - --debug prints original backend errors when they are normalized.',
+      ''
+    ].join('\n')
+  );
+}
+
+module.exports = { run };

package/src/commands/diagnostics.js

@@ -0,0 +1,39 @@
+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/init.js

@@ -0,0 +1,256 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+
+const { ensureDir, writeFileAtomic, readJson, writeJson, chmod600IfPossible } = require('../lib/fs');
+const { prompt, promptHidden } = require('../lib/prompt');
+const { upsertCodexNotify, loadCodexNotifyOriginal } = require('../lib/codex-config');
+const { beginBrowserAuth } = require('../lib/browser-auth');
+const { issueDeviceTokenWithPassword, issueDeviceTokenWithAccessToken } = require('../lib/insforge');
+
+async function cmdInit(argv) {
+  const opts = parseArgs(argv);
+  const home = os.homedir();
+
+  const rootDir = path.join(home, '.vibescore');
+  const trackerDir = path.join(rootDir, 'tracker');
+  const binDir = path.join(rootDir, 'bin');
+
+  await ensureDir(trackerDir);
+  await ensureDir(binDir);
+
+  const configPath = path.join(trackerDir, 'config.json');
+  const notifyOriginalPath = path.join(trackerDir, 'codex_notify_original.json');
+
+  const baseUrl = opts.baseUrl || process.env.VIBESCORE_INSFORGE_BASE_URL || 'https://5tmappuk.us-east.insforge.app';
+  let dashboardUrl = opts.dashboardUrl || process.env.VIBESCORE_DASHBOARD_URL || null;
+  const notifyPath = path.join(binDir, 'notify.cjs');
+  const appDir = path.join(trackerDir, 'app');
+  const trackerBinPath = path.join(appDir, 'bin', 'tracker.js');
+
+  const existingConfig = await readJson(configPath);
+  const deviceTokenFromEnv = process.env.VIBESCORE_DEVICE_TOKEN || null;
+
+  let deviceToken = deviceTokenFromEnv || existingConfig?.deviceToken || null;
+  let deviceId = existingConfig?.deviceId || null;
+
+  await installLocalTrackerApp({ appDir });
+
+  if (!deviceToken && !opts.noAuth) {
+    const deviceName = opts.deviceName || os.hostname();
+
+    if (opts.email || opts.password) {
+      const email = opts.email || (await prompt('Email: '));
+      const password = opts.password || (await promptHidden('Password: '));
+      const issued = await issueDeviceTokenWithPassword({ baseUrl, email, password, deviceName });
+      deviceToken = issued.token;
+      deviceId = issued.deviceId;
+    } else {
+      if (!dashboardUrl) dashboardUrl = await detectLocalDashboardUrl();
+      const flow = await beginBrowserAuth({ baseUrl, dashboardUrl, timeoutMs: 10 * 60_000, open: !opts.noOpen });
+      process.stdout.write(
+        [
+          '',
+          'Connect your account:',
+          `- Open: ${flow.authUrl}`,
+          '- Finish sign in/up in your browser, then come back here.',
+          ''
+        ].join('\n')
+      );
+      const callback = await flow.waitForCallback();
+      const issued = await issueDeviceTokenWithAccessToken({ baseUrl, accessToken: callback.accessToken, deviceName });
+      deviceToken = issued.token;
+      deviceId = issued.deviceId;
+    }
+  }
+
+  const config = {
+    baseUrl,
+    deviceToken,
+    deviceId,
+    installedAt: existingConfig?.installedAt || new Date().toISOString()
+  };
+
+  await writeJson(configPath, config);
+  await chmod600IfPossible(configPath);
+
+  // Install notify handler (non-blocking; chains the previous notify if present).
+  await writeFileAtomic(
+    notifyPath,
+    buildNotifyHandler({ trackerDir, trackerBinPath, packageName: '@vibescore/tracker' })
+  );
+  await fs.chmod(notifyPath, 0o755).catch(() => {});
+
+  // Configure Codex notify hook.
+  const codexConfigPath = path.join(home, '.codex', 'config.toml');
+  const notifyCmd = ['/usr/bin/env', 'node', notifyPath];
+  const result = await upsertCodexNotify({
+    codexConfigPath,
+    notifyCmd,
+    notifyOriginalPath
+  });
+
+  const chained = await loadCodexNotifyOriginal(notifyOriginalPath);
+
+  process.stdout.write(
+    [
+      'Installed:',
+      `- Tracker config: ${configPath}`,
+      `- Notify handler: ${notifyPath}`,
+      `- Codex config: ${codexConfigPath}`,
+      result.changed ? '- Codex notify: updated' : '- Codex notify: already set',
+      chained ? '- Codex notify: chained (original preserved)' : '- Codex notify: no original',
+      deviceToken ? `- Device token: stored (${maskSecret(deviceToken)})` : '- Device token: not configured (set VIBESCORE_DEVICE_TOKEN and re-run init)',
+      ''
+    ].join('\n')
+  );
+}
+
+function parseArgs(argv) {
+  const out = {
+    baseUrl: null,
+    dashboardUrl: null,
+    email: null,
+    password: null,
+    deviceName: null,
+    noAuth: false,
+    noOpen: false
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--base-url') out.baseUrl = argv[++i] || null;
+    else if (a === '--dashboard-url') out.dashboardUrl = argv[++i] || null;
+    else if (a === '--email') out.email = argv[++i] || null;
+    else if (a === '--password') out.password = argv[++i] || null;
+    else if (a === '--device-name') out.deviceName = argv[++i] || null;
+    else if (a === '--no-auth') out.noAuth = true;
+    else if (a === '--no-open') out.noOpen = true;
+    else throw new Error(`Unknown option: ${a}`);
+  }
+  return out;
+}
+
+function maskSecret(s) {
+  if (typeof s !== 'string' || s.length < 8) return '***';
+  return `${s.slice(0, 4)}…${s.slice(-4)}`;
+}
+
+function buildNotifyHandler({ trackerDir, packageName }) {
+  // Keep this file dependency-free: Node built-ins only.
+  // It must never block Codex; it spawns sync in the background and exits 0.
+  const queueSignalPath = path.join(trackerDir, 'notify.signal');
+  const originalPath = path.join(trackerDir, 'codex_notify_original.json');
+  const fallbackPkg = packageName || '@vibescore/tracker';
+  const trackerBinPath = path.join(trackerDir, 'app', 'bin', 'tracker.js');
+
+  return `#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const payload = process.argv[2] || '';
+const trackerDir = ${JSON.stringify(trackerDir)};
+const signalPath = ${JSON.stringify(queueSignalPath)};
+const originalPath = ${JSON.stringify(originalPath)};
+const trackerBinPath = ${JSON.stringify(trackerBinPath)};
+const fallbackPkg = ${JSON.stringify(fallbackPkg)};
+
+try {
+  fs.mkdirSync(trackerDir, { recursive: true });
+  fs.writeFileSync(signalPath, new Date().toISOString(), { encoding: 'utf8' });
+} catch (_) {}
+
+// Throttle spawn: at most once per 20 seconds.
+try {
+  const throttlePath = path.join(trackerDir, 'sync.throttle');
+  const now = Date.now();
+  let last = 0;
+  try { last = Number(fs.readFileSync(throttlePath, 'utf8')) || 0; } catch (_) {}
+  if (now - last > 20_000) {
+    try { fs.writeFileSync(throttlePath, String(now), 'utf8'); } catch (_) {}
+    if (fs.existsSync(trackerBinPath)) {
+      spawnDetached([process.execPath, trackerBinPath, 'sync', '--auto', '--from-notify']);
+    } else {
+      spawnDetached(['npx', '--yes', fallbackPkg, 'sync', '--auto', '--from-notify']);
+    }
+  }
+} catch (_) {}
+
+// Chain the original Codex notify if present.
+try {
+  const original = JSON.parse(fs.readFileSync(originalPath, 'utf8'));
+  const cmd = Array.isArray(original?.notify) ? original.notify : null;
+  if (cmd && cmd.length > 0) {
+    const args = cmd.slice(1);
+    args.push(payload);
+    spawnDetached([cmd[0], ...args]);
+  }
+} catch (_) {}
+
+process.exit(0);
+
+function spawnDetached(argv) {
+  try {
+    const child = cp.spawn(argv[0], argv.slice(1), {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env
+    });
+    child.unref();
+  } catch (_) {}
+}
+`;
+}
+
+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 installLocalTrackerApp({ appDir }) {
+  // Copy the current package's runtime (bin + src) into ~/.vibescore so notify can run sync without npx.
+  const packageRoot = path.resolve(__dirname, '../..');
+  const srcFrom = path.join(packageRoot, 'src');
+  const binFrom = path.join(packageRoot, 'bin', 'tracker.js');
+
+  const srcTo = path.join(appDir, 'src');
+  const binToDir = path.join(appDir, 'bin');
+  const binTo = path.join(binToDir, 'tracker.js');
+
+  await fs.rm(appDir, { recursive: true, force: true }).catch(() => {});
+  await ensureDir(appDir);
+  await fs.cp(srcFrom, srcTo, { recursive: true });
+  await ensureDir(binToDir);
+  await fs.copyFile(binFrom, binTo);
+  await fs.chmod(binTo, 0o755).catch(() => {});
+}

package/src/commands/status.js

@@ -0,0 +1,113 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+
+const { readJson } = require('../lib/fs');
+const { readCodexNotify } = require('../lib/codex-config');
+const { normalizeState: normalizeUploadState } = require('../lib/upload-throttle');
+const { collectTrackerDiagnostics } = require('../lib/diagnostics');
+
+async function cmdStatus(argv = []) {
+  const opts = parseArgs(argv);
+  if (opts.diagnostics) {
+    const diagnostics = await collectTrackerDiagnostics();
+    process.stdout.write(JSON.stringify(diagnostics, null, 2) + '\n');
+    return;
+  }
+
+  const home = os.homedir();
+  const trackerDir = path.join(home, '.vibescore', 'tracker');
+  const configPath = path.join(trackerDir, 'config.json');
+  const queuePath = path.join(trackerDir, 'queue.jsonl');
+  const queueStatePath = path.join(trackerDir, 'queue.state.json');
+  const cursorsPath = path.join(trackerDir, 'cursors.json');
+  const notifySignalPath = path.join(trackerDir, 'notify.signal');
+  const throttlePath = path.join(trackerDir, 'sync.throttle');
+  const uploadThrottlePath = path.join(trackerDir, 'upload.throttle.json');
+  const codexHome = process.env.CODEX_HOME || path.join(home, '.codex');
+  const codexConfigPath = path.join(codexHome, 'config.toml');
+
+  const config = await readJson(configPath);
+  const cursors = await readJson(cursorsPath);
+  const queueState = (await readJson(queueStatePath)) || { offset: 0 };
+  const uploadThrottle = normalizeUploadState(await readJson(uploadThrottlePath));
+
+  const queueSize = await safeStatSize(queuePath);
+  const pendingBytes = Math.max(0, queueSize - (queueState.offset || 0));
+
+  const lastNotify = (await safeReadText(notifySignalPath))?.trim() || null;
+  const lastNotifySpawn = parseEpochMsToIso((await safeReadText(throttlePath))?.trim() || null);
+
+  const codexNotify = await readCodexNotify(codexConfigPath);
+  const notifyConfigured = Array.isArray(codexNotify) && codexNotify.length > 0;
+
+  const lastUpload = uploadThrottle.lastSuccessMs
+    ? parseEpochMsToIso(uploadThrottle.lastSuccessMs)
+    : typeof queueState.updatedAt === 'string'
+      ? queueState.updatedAt
+      : null;
+  const nextUpload = parseEpochMsToIso(uploadThrottle.nextAllowedAtMs || null);
+  const backoffUntil = parseEpochMsToIso(uploadThrottle.backoffUntilMs || null);
+  const lastUploadError = uploadThrottle.lastError
+    ? `${uploadThrottle.lastErrorAt || 'unknown'} ${uploadThrottle.lastError}`
+    : null;
+
+  process.stdout.write(
+    [
+      'Status:',
+      `- Base URL: ${config?.baseUrl || 'unset'}`,
+      `- Device token: ${config?.deviceToken ? 'set' : 'unset'}`,
+      `- Queue: ${pendingBytes} bytes pending`,
+      `- Last parse: ${cursors?.updatedAt || 'never'}`,
+      `- Last notify: ${lastNotify || 'never'}`,
+      `- Last notify-triggered sync: ${lastNotifySpawn || 'never'}`,
+      `- Last upload: ${lastUpload || 'never'}`,
+      `- Next upload after: ${nextUpload || 'never'}`,
+      `- Backoff until: ${backoffUntil || 'never'}`,
+      lastUploadError ? `- Last upload error: ${lastUploadError}` : null,
+      `- Codex notify: ${notifyConfigured ? JSON.stringify(codexNotify) : 'unset'}`,
+      ''
+    ]
+      .filter(Boolean)
+      .join('\n')
+  );
+}
+
+function parseArgs(argv) {
+  const out = { diagnostics: false };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--diagnostics' || a === '--json') out.diagnostics = true;
+    else throw new Error(`Unknown option: ${a}`);
+  }
+
+  return out;
+}
+
+async function safeStatSize(p) {
+  try {
+    const st = await fs.stat(p);
+    return st.size || 0;
+  } catch (_e) {
+    return 0;
+  }
+}
+
+async function safeReadText(p) {
+  try {
+    return await fs.readFile(p, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+function parseEpochMsToIso(v) {
+  const ms = Number(v);
+  if (!Number.isFinite(ms) || ms <= 0) return null;
+  const d = new Date(ms);
+  if (Number.isNaN(d.getTime())) return null;
+  return d.toISOString();
+}
+
+module.exports = { cmdStatus };