codex-usage-dashboard 0.1.0 → 0.1.2

package/README.md

@@ -7,7 +7,7 @@ Multi-user Codex usage tracking with a Vercel-hosted dashboard, Supabase Auth, a
 - Vite + TanStack Router + React Query
 - Supabase Auth + Postgres
 - Vercel Functions for pairing and sync ingest
-- Local Codex access through `codex app-server`
+- Local Codex access through a bundled `@openai/codex` `app-server`
 
 ## What changed
 
@@ -47,12 +47,20 @@ The Vite dev server now serves the local pairing and sync API routes under `/api
 
 ## Direct connect flow
 
-Run this on any machine that already has Codex installed:
+Run this on any machine:
 
 ```bash
 npx codex-usage-dashboard@latest connect --site "https://your-site.vercel.app"
 ```
 
+The package now brings a compatible `@openai/codex` CLI dependency with it, so `connect`, `pair`, and `sync` do not require a separate global Codex install.
+
+If the machine has never logged into Codex before, authenticate once with:
+
+```bash
+npx @openai/codex@latest login
+```
+
 That command:
 
 - starts a local `codex app-server`
@@ -68,7 +76,7 @@ If the same machine is already connected, rerun the same command to reopen the d
 
 1. Sign in on the website.
 2. Click `Create pairing command`.
-3. Run the generated command on the machine that already has Codex installed.
+3. Run the generated command on the machine you want to pair.
 
 The generated command looks like:
 

package/bin/codex-usage.js

@@ -3,19 +3,28 @@
 import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import os from 'node:os'
 import path from 'node:path'
 import process from 'node:process'
 
 const DEFAULT_POLL_MS = 60_000
+const CODEX_HELP_TIMEOUT_MS = 15_000
 const CONFIG_FILE_NAME = 'codex-usage-sync.json'
 const NPX_COMMAND = 'npx codex-usage-dashboard@latest'
 
+const require = createRequire(import.meta.url)
+
+let codexAppServerSupportPromise = null
+let resolvedCodexExecutable = null
+
 class StdioCodexClient {
   constructor({ codexHome }) {
     this.codexHome = codexHome
     this.child = null
     this.buffer = ''
+    this.isClosing = false
+    this.lastStderrMessage = ''
     this.pending = new Map()
     this.requestId = 0
     this.notificationHandler = null
@@ -26,17 +35,9 @@ class StdioCodexClient {
       return
     }
 
+    this.buffer = ''
+    this.lastStderrMessage = ''
     this.child = await this.spawnAppServer()
-    this.child.stdout.setEncoding('utf8')
-    this.child.stdout.on('data', (chunk) => {
-      this.consumeStdout(chunk)
-    })
-    this.child.stderr.on('data', (chunk) => {
-      const message = chunk.toString().trim()
-      if (message) {
-        console.error(`[codex] ${message}`)
-      }
-    })
 
     await this.request('initialize', {
       capabilities: {},
@@ -54,13 +55,12 @@ class StdioCodexClient {
       return
     }
 
-    this.child.kill('SIGTERM')
+    const child = this.child
     this.child = null
+    this.isClosing = true
+    child.kill('SIGTERM')
 
-    for (const pending of this.pending.values()) {
-      pending.reject(new Error('Codex app-server closed.'))
-    }
-    this.pending.clear()
+    this.rejectPending(new Error('Codex app-server closed.'))
   }
 
   onNotification(handler) {
@@ -73,17 +73,25 @@ class StdioCodexClient {
     }
 
     const id = ++this.requestId
-    this.child.stdin.write(
-      `${JSON.stringify({
-        id,
-        jsonrpc: '2.0',
-        method,
-        ...(params ? { params } : {}),
-      })}\n`,
-    )
-
     return new Promise((resolve, reject) => {
       this.pending.set(id, { reject, resolve })
+
+      this.child.stdin.write(
+        `${JSON.stringify({
+          id,
+          jsonrpc: '2.0',
+          method,
+          ...(params ? { params } : {}),
+        })}\n`,
+        (error) => {
+          if (!error) {
+            return
+          }
+
+          this.pending.delete(id)
+          reject(error)
+        },
+      )
     })
   }
 
@@ -151,32 +159,78 @@ class StdioCodexClient {
     }
   }
 
-  spawnAppServer() {
+  rejectPending(error) {
+    for (const pending of this.pending.values()) {
+      pending.reject(error)
+    }
+
+    this.pending.clear()
+  }
+
+  async spawnAppServer() {
+    await ensureCodexAppServerSupport()
+    const codexExecutable = resolveCodexExecutable()
+
     return new Promise((resolve, reject) => {
-      const child = spawn('codex', ['app-server', '--listen', 'stdio://'], {
-        env: {
-          ...process.env,
-          ...(this.codexHome ? { CODEX_HOME: this.codexHome } : {}),
+      const child = spawn(
+        codexExecutable.command,
+        [...codexExecutable.argsPrefix, 'app-server', '--listen', 'stdio://'],
+        {
+          env: {
+            ...process.env,
+            ...(this.codexHome ? { CODEX_HOME: this.codexHome } : {}),
+          },
+          stdio: ['pipe', 'pipe', 'pipe'],
         },
-        stdio: ['pipe', 'pipe', 'pipe'],
+      )
+
+      child.stdout.setEncoding('utf8')
+      child.stdout.on('data', (chunk) => {
+        this.consumeStdout(chunk)
+      })
+
+      child.stderr.on('data', (chunk) => {
+        const message = chunk.toString().trim()
+        if (!message) {
+          return
+        }
+
+        const lines = message.split(/\r?\n/)
+        this.lastStderrMessage = lines[lines.length - 1] ?? message
+        console.error(`[codex] ${message}`)
       })
 
       child.once('error', (error) => {
         reject(
           new Error(
             error.code === 'ENOENT'
-              ? 'The `codex` command is not installed on this machine.'
+              ? 'Codex CLI is not available. Reinstall `codex-usage-dashboard` or install it globally with `npm install -g @openai/codex`.'
               : error.message,
           ),
         )
       })
 
+      child.once('exit', (code, signal) => {
+        if (this.child === child) {
+          this.child = null
+        }
+
+        const expectedShutdown = this.isClosing
+        this.isClosing = false
+
+        if (expectedShutdown) {
+          return
+        }
+
+        const error = buildCodexAppServerExitError(
+          code,
+          signal,
+          this.lastStderrMessage,
+        )
+        this.rejectPending(error)
+      })
+
       child.once('spawn', () => {
-        child.on('exit', (code) => {
-          if (code !== 0 && code !== null) {
-            console.error(`[codex] app-server exited with code ${code}`)
-          }
-        })
         resolve(child)
       })
     })
@@ -236,20 +290,20 @@ async function runPairCommand(args) {
       }),
     })
 
-    const payload = await parseJsonResponse(response)
+    const payload = await parseResponseBody(response)
     if (!response.ok) {
-      throw new Error(payload.error ?? 'Pairing failed.')
+      throw new Error(buildHttpErrorMessage(response, payload, 'Pairing failed.'))
     }
 
     const config = {
       authMode: 'website-paired',
       codexHome,
-      deviceId: payload.deviceId,
-      deviceToken: payload.deviceToken,
+      deviceId: payload.data.deviceId,
+      deviceToken: payload.data.deviceToken,
       dashboardOrigin: new URL(pairUrl).origin,
       label: device.label,
-      pollMs: payload.pollMs ?? DEFAULT_POLL_MS,
-      syncUrl: payload.syncUrl,
+      pollMs: payload.data.pollMs ?? DEFAULT_POLL_MS,
+      syncUrl: payload.data.syncUrl,
     }
 
     await writeConfig(codexHome, config)
@@ -313,24 +367,26 @@ async function runConnectCommand(args) {
       }),
     })
 
-    const payload = await parseJsonResponse(response)
+    const payload = await parseResponseBody(response)
     if (!response.ok) {
-      throw new Error(payload.error ?? 'Unable to connect this machine.')
+      throw new Error(
+        buildHttpErrorMessage(response, payload, 'Unable to connect this machine.'),
+      )
     }
 
     const config = {
       authMode: 'guest-link',
       codexHome,
       dashboardOrigin: siteOrigin,
-      deviceId: payload.deviceId,
-      deviceToken: payload.deviceToken,
+      deviceId: payload.data.deviceId,
+      deviceToken: payload.data.deviceToken,
       label: device.label,
-      pollMs: payload.pollMs ?? DEFAULT_POLL_MS,
-      syncUrl: payload.syncUrl,
+      pollMs: payload.data.pollMs ?? DEFAULT_POLL_MS,
+      syncUrl: payload.data.syncUrl,
     }
 
     await writeConfig(codexHome, config)
-    await openDashboard(payload.dashboardUrl)
+    await openDashboard(payload.data.dashboardUrl)
     console.log('Dashboard opened.')
     console.log(`Config saved to ${resolveConfigPath(codexHome)}`)
     console.log(
@@ -447,9 +503,9 @@ async function syncOnce(client, config, args) {
     }),
   })
 
-  const payload = await parseJsonResponse(response)
+  const payload = await parseResponseBody(response)
   if (!response.ok) {
-    throw new Error(payload.error ?? 'Sync failed.')
+    throw new Error(buildHttpErrorMessage(response, payload, 'Sync failed.'))
   }
 }
 
@@ -465,12 +521,14 @@ async function resolveExistingDashboardUrl(config, args) {
       }),
     })
 
-    const payload = await parseJsonResponse(response)
+    const payload = await parseResponseBody(response)
     if (!response.ok) {
-      throw new Error(payload.error ?? 'Unable to open the dashboard.')
+      throw new Error(
+        buildHttpErrorMessage(response, payload, 'Unable to open the dashboard.'),
+      )
     }
 
-    return payload.dashboardUrl ?? null
+    return payload.data.dashboardUrl ?? null
   }
 
   const siteOrigin =
@@ -489,7 +547,7 @@ async function readSnapshot(client, failWhenLoggedOut) {
   if (!accountState.account) {
     if (failWhenLoggedOut) {
       throw new Error(
-        'No logged-in Codex account was found. Run `codex login` and try again.',
+        'No logged-in Codex account was found. Run `npx @openai/codex@latest login` (or `codex login` if installed globally) and try again.',
       )
     }
 
@@ -598,6 +656,161 @@ function openInBrowser(url) {
   })
 }
 
+async function ensureCodexAppServerSupport() {
+  if (!codexAppServerSupportPromise) {
+    codexAppServerSupportPromise = inspectCodexCliForAppServer().catch(
+      (error) => {
+        codexAppServerSupportPromise = null
+        throw error
+      },
+    )
+  }
+
+  await codexAppServerSupportPromise
+}
+
+async function inspectCodexCliForAppServer() {
+  const codexExecutable = resolveCodexExecutable()
+  const help = await runCommandCapture(
+    codexExecutable.command,
+    [...codexExecutable.argsPrefix, '--help'],
+    { timeoutMs: CODEX_HELP_TIMEOUT_MS },
+  )
+
+  const helpText = `${help.stdout}\n${help.stderr}`
+  if (help.code === 0 && /\bapp-server\b/.test(helpText)) {
+    return
+  }
+
+  const version = await runCommandCapture(
+    codexExecutable.command,
+    [...codexExecutable.argsPrefix, '--version'],
+    { timeoutMs: CODEX_HELP_TIMEOUT_MS },
+  )
+  const versionText = normalizeCodexVersion(version.stdout || version.stderr)
+  throw new Error(
+    `Resolved Codex CLI ${versionText} (${codexExecutable.label}) does not support \`codex app-server\`. Reinstall \`codex-usage-dashboard\` or update Codex with \`npm install -g @openai/codex\`, then rerun this command.`,
+  )
+}
+
+function resolveCodexExecutable() {
+  if (resolvedCodexExecutable) {
+    return resolvedCodexExecutable
+  }
+
+  const bundledBinPath = resolveBundledCodexBin()
+  if (bundledBinPath) {
+    resolvedCodexExecutable = {
+      argsPrefix: [bundledBinPath],
+      command: process.execPath,
+      label: 'bundled @openai/codex',
+    }
+    return resolvedCodexExecutable
+  }
+
+  resolvedCodexExecutable = {
+    argsPrefix: [],
+    command: 'codex',
+    label: 'global codex',
+  }
+  return resolvedCodexExecutable
+}
+
+function resolveBundledCodexBin() {
+  try {
+    return require.resolve('@openai/codex/bin/codex.js')
+  } catch {
+    return null
+  }
+}
+
+function runCommandCapture(command, args, { timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+
+    const child = spawn(command, args, {
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return
+      }
+
+      settled = true
+      child.kill('SIGTERM')
+      reject(
+        new Error(
+          `Timed out while probing \`${command} ${args.join(' ')}\`.`,
+        ),
+      )
+    }, timeoutMs)
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString()
+    })
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString()
+    })
+
+    child.once('error', (error) => {
+      if (settled) {
+        return
+      }
+
+      settled = true
+      clearTimeout(timeout)
+      reject(
+        new Error(
+          error.code === 'ENOENT'
+            ? 'The `codex` command is not installed on this machine.'
+            : error.message,
+        ),
+      )
+    })
+
+    child.once('close', (code, signal) => {
+      if (settled) {
+        return
+      }
+
+      settled = true
+      clearTimeout(timeout)
+      resolve({
+        code,
+        signal,
+        stderr: stderr.trim(),
+        stdout: stdout.trim(),
+      })
+    })
+  })
+}
+
+function normalizeCodexVersion(versionText) {
+  const normalized = versionText.trim().replace(/^codex-cli\s+/i, '')
+  return normalized || 'unknown'
+}
+
+function buildCodexAppServerExitError(code, signal, stderrMessage) {
+  const exitDetail =
+    typeof code === 'number'
+      ? `exit code ${code}`
+      : signal
+        ? `signal ${signal}`
+        : 'no exit code'
+
+  const message = [`Codex app-server exited unexpectedly (${exitDetail}).`]
+  if (stderrMessage) {
+    message.push(stderrMessage)
+  }
+
+  return new Error(message.join(' '))
+}
+
 async function writeConfig(codexHome, config) {
   await mkdir(codexHome, { recursive: true })
   await writeFile(
@@ -616,13 +829,81 @@ async function readConfig(codexHome) {
   return JSON.parse(await readFile(configPath, 'utf8'))
 }
 
-async function parseJsonResponse(response) {
-  const payload = await response.json().catch(() => null)
-  if (!payload || typeof payload !== 'object') {
-    return {}
+async function parseResponseBody(response) {
+  const text = (await response.text().catch(() => '')).trim()
+  if (!text) {
+    return { data: {}, text: '' }
+  }
+
+  try {
+    const parsed = JSON.parse(text)
+    if (parsed && typeof parsed === 'object') {
+      return { data: parsed, text }
+    }
+  } catch {
+    // Fall back to the raw text when the response body is not JSON.
+  }
+
+  return { data: {}, text }
+}
+
+function buildHttpErrorMessage(response, payload, fallbackMessage) {
+  const bodyError =
+    typeof payload.data?.error === 'string' && payload.data.error.trim()
+      ? payload.data.error.trim()
+      : null
+  const plainText =
+    payload.text && !looksLikeHtml(payload.text)
+      ? payload.text.replace(/\s+/g, ' ').trim()
+      : ''
+  const statusLabel = `${response.status}${response.statusText ? ` ${response.statusText}` : ''}`
+  const vercelError = response.headers.get('x-vercel-error')
+  const vercelId = response.headers.get('x-vercel-id')
+
+  const detail = bodyError ?? truncateText(plainText, 240)
+  let message = detail
+    ? `${fallbackMessage} ${detail}`
+    : `${fallbackMessage} HTTP ${statusLabel}.`
+
+  if (!detail) {
+    return appendHttpContext(message, vercelError, vercelId)
+  }
+
+  if (!bodyError) {
+    message = `${message} (HTTP ${statusLabel})`
+  }
+
+  return appendHttpContext(message, vercelError, vercelId)
+}
+
+function appendHttpContext(message, vercelError, vercelId) {
+  const context = []
+
+  if (vercelError) {
+    context.push(`Vercel error: ${vercelError}`)
+  }
+
+  if (vercelId) {
+    context.push(`request id: ${vercelId}`)
+  }
+
+  if (!context.length) {
+    return message
+  }
+
+  return `${message} [${context.join('; ')}]`
+}
+
+function looksLikeHtml(text) {
+  return /^<!doctype html>|^<html[\s>]/i.test(text)
+}
+
+function truncateText(text, maxLength) {
+  if (text.length <= maxLength) {
+    return text
   }
 
-  return payload
+  return `${text.slice(0, maxLength - 1)}…`
 }
 
 function waitForTermination(cleanup) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-usage-dashboard",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.1.2",
   "files": [
     "README.md",
     "bin"
@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5.2.8",
+    "@openai/codex": "^0.118.0",
     "@radix-ui/react-slot": "^1.2.4",
     "@supabase/supabase-js": "^2.101.1",
     "@tanstack/react-query": "^5.96.2",