codex-usage-dashboard 0.1.1 → 0.1.3

package/README.md

@@ -50,7 +50,13 @@ The Vite dev server now serves the local pairing and sync API routes under `/api
 Run this on any machine:
 
 ```bash
-npx codex-usage-dashboard@latest connect --site "https://your-site.vercel.app"
+npx codex-usage-dashboard@latest connect --site "https://codex-use-age.vercel.app"
+```
+
+For local development in this repo, use:
+
+```bash
+npm run connect -- --site "http://localhost:5173"
 ```
 
 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.
@@ -81,7 +87,7 @@ If the same machine is already connected, rerun the same command to reopen the d
 The generated command looks like:
 
 ```bash
-npx codex-usage-dashboard@latest pair "https://your-site.vercel.app/api/pair/complete?token=..."
+npx codex-usage-dashboard@latest pair "https://codex-use-age.vercel.app/api/pair/complete?token=..."
 ```
 
 ## Live sync after pairing
@@ -101,6 +107,14 @@ The saved device token is read from the same Codex home that the CLI uses.
 - `npm run sync -- --watch`: local version of the hosted sync command
 - `npm run collector`: legacy single-operator collector script
 
+## Publishing
+
+1. Run `npm version patch` (or `minor` / `major`) before every new publish.
+2. Run `npm run release:check` to verify the tarball contents and confirm the version is still unpublished.
+3. Run `npm publish`.
+
+`npm publish` cannot overwrite an existing version on npm, so repeating a publish for the same version will fail with `E403`.
+
 ## Tario-specific Git workflow for Codex
 
 If the current machine or user context indicates Tario is the operator, treat that as a master-by-default environment.

package/bin/codex-usage.js

@@ -290,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)
@@ -325,71 +325,71 @@ async function runConnectCommand(args) {
   const codexHome = resolveCodexHome(args.options['codex-home'])
   const existingConfig = await readConfig(codexHome)
   const client = new StdioCodexClient({ codexHome })
+  const siteOriginFromArgs = resolveSiteOrigin(args.options.site)
 
   try {
     await client.connect()
 
     if (existingConfig) {
-      const dashboardUrl = await resolveExistingDashboardUrl(existingConfig, args)
+      try {
+        const dashboardUrl = await resolveExistingDashboardUrl(existingConfig, args)
+        let dashboardOpenState = null
 
-      if (dashboardUrl) {
-        await openDashboard(dashboardUrl)
-      }
+        if (dashboardUrl) {
+          dashboardOpenState = await openDashboard(dashboardUrl)
+        }
 
-      await syncOnce(client, existingConfig, args)
-      console.log('Dashboard opened.')
+        await syncOnce(client, existingConfig, args)
+        logDashboardOpenState(dashboardOpenState)
 
-      if (args.options.watch) {
-        await runWatchLoop(client, existingConfig, args)
-      }
+        if (args.options.watch) {
+          await runWatchLoop(client, existingConfig, args)
+        }
 
-      return
+        return
+      } catch (error) {
+        if (!isRevokedDeviceError(error)) {
+          throw error
+        }
+
+        const siteOrigin =
+          siteOriginFromArgs ??
+          existingConfig.dashboardOrigin ??
+          deriveOriginFromUrl(existingConfig.syncUrl)
+
+        if (!siteOrigin) {
+          throw new Error(
+            `This device was unlinked from the dashboard. Rerun \`${NPX_COMMAND} connect --site "https://codex-use-age.vercel.app"\` to create a new connection.`,
+          )
+        }
+
+        console.log(
+          'This device was unlinked from the dashboard. Creating a new connection...',
+        )
+
+        const refreshedConfig = await startConnectFlow(
+          client,
+          args,
+          codexHome,
+          siteOrigin,
+        )
+
+        if (args.options.watch) {
+          await runWatchLoop(client, refreshedConfig, args)
+        }
+
+        return
+      }
     }
 
-    const siteOrigin = resolveSiteOrigin(args.options.site)
+    const siteOrigin = siteOriginFromArgs
     if (!siteOrigin) {
       throw new Error(
         'Pass --site <url> the first time you run connect, or set CODEX_USAGE_SITE_URL.',
       )
     }
 
-    const snapshot = await readSnapshot(client, true)
-    const device = buildDevicePayload(args, codexHome)
-    const response = await fetch(new URL('/api/connect/start', siteOrigin), {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        accountState: snapshot.accountState,
-        device,
-        rateLimits: snapshot.rateLimits,
-      }),
-    })
-
-    const payload = await parseJsonResponse(response)
-    if (!response.ok) {
-      throw new Error(payload.error ?? 'Unable to connect this machine.')
-    }
-
-    const config = {
-      authMode: 'guest-link',
-      codexHome,
-      dashboardOrigin: siteOrigin,
-      deviceId: payload.deviceId,
-      deviceToken: payload.deviceToken,
-      label: device.label,
-      pollMs: payload.pollMs ?? DEFAULT_POLL_MS,
-      syncUrl: payload.syncUrl,
-    }
-
-    await writeConfig(codexHome, config)
-    await openDashboard(payload.dashboardUrl)
-    console.log('Dashboard opened.')
-    console.log(`Config saved to ${resolveConfigPath(codexHome)}`)
-    console.log(
-      `Next: rerun \`${NPX_COMMAND} connect --site "${siteOrigin}"\` to reopen this dashboard, or \`${NPX_COMMAND} sync --watch\` for live updates only.`,
-    )
+    const config = await startConnectFlow(client, args, codexHome, siteOrigin)
 
     if (args.options.watch) {
       await runWatchLoop(client, config, args)
@@ -399,6 +399,50 @@ async function runConnectCommand(args) {
   }
 }
 
+async function startConnectFlow(client, args, codexHome, siteOrigin) {
+  const snapshot = await readSnapshot(client, true)
+  const device = buildDevicePayload(args, codexHome)
+  const response = await fetch(new URL('/api/connect/start', siteOrigin), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      accountState: snapshot.accountState,
+      device,
+      rateLimits: snapshot.rateLimits,
+    }),
+  })
+
+  const payload = await parseResponseBody(response)
+  if (!response.ok) {
+    throw new Error(
+      buildHttpErrorMessage(response, payload, 'Unable to connect this machine.'),
+    )
+  }
+
+  const config = {
+    authMode: 'guest-link',
+    codexHome,
+    dashboardOrigin: siteOrigin,
+    deviceId: payload.data.deviceId,
+    deviceToken: payload.data.deviceToken,
+    label: device.label,
+    pollMs: payload.data.pollMs ?? DEFAULT_POLL_MS,
+    syncUrl: payload.data.syncUrl,
+  }
+
+  await writeConfig(codexHome, config)
+  const dashboardOpenState = await openDashboard(payload.data.dashboardUrl)
+  logDashboardOpenState(dashboardOpenState)
+  console.log(`Config saved to ${resolveConfigPath(codexHome)}`)
+  console.log(
+    `Next: rerun \`${NPX_COMMAND} connect --site "${siteOrigin}"\` to reopen this dashboard, or \`${NPX_COMMAND} sync --watch\` for live updates only.`,
+  )
+
+  return config
+}
+
 async function runSyncCommand(args) {
   const codexHome = resolveCodexHome(args.options['codex-home'])
   const config = await readConfig(codexHome)
@@ -501,9 +545,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.'))
   }
 }
 
@@ -519,12 +563,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 =
@@ -571,8 +617,21 @@ function buildDevicePayload(args, codexHome, fallbackLabel) {
 async function openDashboard(url) {
   try {
     await openInBrowser(url)
+    return 'browser'
   } catch {
     console.log(`Open this URL in your browser: ${url}`)
+    return 'manual'
+  }
+}
+
+function logDashboardOpenState(state) {
+  if (state === 'browser') {
+    console.log('Dashboard URL sent to your browser.')
+    return
+  }
+
+  if (state === 'manual') {
+    console.log('Dashboard URL ready.')
   }
 }
 
@@ -616,6 +675,18 @@ function resolveSiteOrigin(configuredValue) {
   return new URL(value).origin
 }
 
+function deriveOriginFromUrl(value) {
+  if (typeof value !== 'string' || !value) {
+    return null
+  }
+
+  try {
+    return new URL(value).origin
+  } catch {
+    return null
+  }
+}
+
 function resolveCodexHome(configuredValue) {
   const home = configuredValue ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex')
 
@@ -822,16 +893,136 @@ async function readConfig(codexHome) {
     return null
   }
 
-  return JSON.parse(await readFile(configPath, 'utf8'))
+  const rawConfig = JSON.parse(await readFile(configPath, 'utf8'))
+  const normalizedConfig = normalizeConfig(rawConfig)
+
+  if (JSON.stringify(normalizedConfig) !== JSON.stringify(rawConfig)) {
+    await writeConfig(codexHome, normalizedConfig)
+  }
+
+  return normalizedConfig
+}
+
+function normalizeConfig(config) {
+  if (!config || typeof config !== 'object') {
+    return config
+  }
+
+  const normalizedConfig = { ...config }
+
+  if (
+    !normalizedConfig.dashboardOrigin &&
+    typeof normalizedConfig.syncUrl === 'string'
+  ) {
+    try {
+      normalizedConfig.dashboardOrigin = new URL(
+        normalizedConfig.syncUrl,
+      ).origin
+    } catch {
+      // Leave the saved origin untouched when the sync URL is malformed.
+    }
+  }
+
+  if (looksLikeLegacyGuestLinkConfig(config)) {
+    normalizedConfig.authMode = 'guest-link'
+  }
+
+  return normalizedConfig
+}
+
+function looksLikeLegacyGuestLinkConfig(config) {
+  return (
+    !config.authMode &&
+    !config.dashboardOrigin &&
+    typeof config.deviceToken === 'string' &&
+    config.deviceToken.length > 0 &&
+    typeof config.syncUrl === 'string' &&
+    config.syncUrl.length > 0
+  )
+}
+
+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 isRevokedDeviceError(error) {
+  return (
+    error instanceof Error &&
+    error.message.includes('This device is no longer authorized.')
+  )
+}
+
+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)
 }
 
-async function parseJsonResponse(response) {
-  const payload = await response.json().catch(() => null)
-  if (!payload || typeof payload !== 'object') {
-    return {}
+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,15 +1,15 @@
 {
   "name": "codex-usage-dashboard",
   "private": false,
-  "version": "0.1.1",
+  "version": "0.1.3",
   "files": [
     "README.md",
     "bin"
   ],
   "type": "module",
   "bin": {
-    "codex-usage": "./bin/codex-usage.js",
-    "codex-usage-dashboard": "./bin/codex-usage.js"
+    "codex-usage": "bin/codex-usage.js",
+    "codex-usage-dashboard": "bin/codex-usage.js"
   },
   "scripts": {
     "dev": "vite",
@@ -23,45 +23,47 @@
     "setup:hosted": "tsx scripts/setup-hosted.ts",
     "setup:local": "tsx scripts/setup-local.ts",
     "collector": "tsx scripts/codex-collector.ts",
-    "collector:once": "tsx scripts/codex-collector.ts --once"
+    "collector:once": "tsx scripts/codex-collector.ts --once",
+    "release:check": "node ./scripts/check-publish.mjs",
+    "prepublishOnly": "npm run release:check"
   },
   "dependencies": {
+    "@openai/codex": "^0.118.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@fontsource-variable/geist": "^5.2.8",
-    "@openai/codex": "^0.118.0",
     "@radix-ui/react-slot": "^1.2.4",
+    "@tailwindcss/vite": "^4.2.2",
     "@supabase/supabase-js": "^2.101.1",
     "@tanstack/react-query": "^5.96.2",
     "@tanstack/react-query-devtools": "^5.96.2",
     "@tanstack/react-router": "^1.168.10",
+    "@tanstack/router-plugin": "^1.167.12",
     "@tanstack/router-devtools": "^1.166.11",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "dotenv": "^17.4.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
     "lucide-react": "^1.7.0",
     "radix-ui": "^1.4.3",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "shadcn": "^4.1.2",
+    "tailwindcss": "^4.2.2",
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.4",
-    "@tailwindcss/vite": "^4.2.2",
-    "@tanstack/router-plugin": "^1.167.12",
-    "@types/node": "^24.12.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.1",
-    "eslint": "^9.39.4",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.5.2",
-    "globals": "^17.4.0",
-    "tailwindcss": "^4.2.2",
     "tsx": "^4.21.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.57.0",
-    "vite": "^8.0.1"
+    "vite": "^8.0.1",
+    "zod": "^4.3.6"
   }
 }