@ai-adoption-score/ai-coding-usage 1.0.1 → 1.2.0

package/README.md

@@ -5,11 +5,12 @@ Score. It counts how a person uses Claude Code and Codex on their Mac and, once
 company's survey. Prompts, the AI's answers, code, file names, command text and session titles never leave the Mac.
 
 You don't install it yourself: your survey page shows one line with a code,
-`npx @ai-adoption-score/ai-coding-usage@1 connect <code>`, to paste into Claude Code, Codex or Terminal.
+`npx @ai-adoption-score/ai-coding-usage@latest connect <code>`, to paste into Claude Code, Codex or Terminal.
 
 Connected once, it shares by itself: a hook in Claude Code and Codex syncs after a session's replies, at most every 5
 minutes and always when a session ends, and an automatic ping-back, once an hour and without any numbers, tells the
-report "no AI use today" from "no signal".
+report "no AI use today" from "no signal". Once a day the ping-back also looks for a newer version on npm and puts it
+in place, so nobody runs the line again to get it.
 
 ## How it works, step by step
 
@@ -20,22 +21,31 @@ In short: connect, choose on the survey page, then share. Before the choice, onl
 2. **The add-on puts its hooks and the ping-back in place** and copies itself to `~/.ai-adoption-score`. Why: the
    survey gets the numbers after every session without anyone running a command again, and a hook can't run from
    npx's temporary folder. The ping-back carries no numbers; it lets the report tell "no AI use today" from "no signal".
-3. **It sends the names of the repositories used in the last 30 days, and nothing else.** Why: the person chooses on
+3. **It sends the names of the repositories used in the last 90 days, and nothing else.** Why: the person chooses on
    their survey page, and the page needs the names to list them. The choice isn't asked in the terminal, because the
    line usually runs inside Claude Code or Codex, where the add-on can't ask questions. The server keeps the list for
    an hour at most.
 4. **The person ticks what to share** on their survey page; everything is ticked to start with. When they press
    Share, the list is deleted, and with it the names they didn't tick.
-5. **Only then do numbers leave the Mac:** the last 30 days of what they ticked, then the new numbers after each
+5. **Only then do numbers leave the Mac:** the last 90 days of what they ticked, then the new numbers after each
    session. Before every sync the add-on asks what they chose and keeps everything else on the Mac; the server checks
-   the same rule again.
-6. **It removes itself** when the Mac is disconnected on the survey page or the survey closes. `disconnect` does the
+   the same rule again. After that first sync, each sync reads the last 30 days only, where rows can still change.
+   Why 90: the survey's report can show three months. Claude Code deletes its own records after 30 days unless its
+   `cleanupPeriodDays` setting says otherwise, so the older days hold what is left of them; Codex keeps its records.
+   A Mac connected with an earlier version, which sent 30 days, sends the 60 before them once, after it updates
+   itself and the server says it takes 90.
+6. **It keeps itself up to date.** Once a day the ping-back asks npm for the latest version. A newer one is
+   downloaded, checked against the checksum npm lists for it, started once to see that it runs on this Mac's Node, and
+   put in place of the add-on's copy; the hooks, the ping-back and the settings stay as they are. Why: a fix or a new
+   number reaches every Mac without anyone running the line again. It never goes back to an older version, skips a
+   version npm marks as withdrawn, and keeps the copy that works when anything fails.
+7. **It removes itself** when the Mac is disconnected on the survey page or the survey closes. `disconnect` does the
    same from the Mac.
 
 The person makes their choice on the survey page, so the survey's server keeps it and the add-on follows the server's
 answer. It still checks what it's told:
 
-- It reads 30 days back at most, whatever the server asks for.
+- It reads 90 days back at most, whatever the server asks for, and 30 when the server names no number.
 - It shares nothing when the choice isn't one of the two kinds the server keeps: what the person ticked, or
   `{ "all": true }` for links made before people could choose.
 - It sends the token over https only. Plain http works only for this Mac's own address (`localhost`), for testing.
@@ -43,8 +53,8 @@ answer. It still checks what it's told:
 ## Commands
 
 - `connect <code> [--server <url>]`: links this Mac to the survey with the code from the survey page and puts the
-  hooks and the ping-back in place. Then it sends the names of the repositories used in the last 30 days, and nothing
-  else, so the person can choose on their survey page which to share; a background wait shares the last 30 days of
+  hooks and the ping-back in place. Then it sends the names of the repositories used in the last 90 days, and nothing
+  else, so the person can choose on their survey page which to share; a background wait shares the last 90 days of
   those once they press Share. The server defaults to `https://app.ai-adoption-score.app`;
   `AI_ADOPTION_SCORE_SERVER` or `--server http://localhost:3000` point it at a local app; any other server has to be
   https. Run again on a Mac that is connected, it keeps that Mac's link on the same server (the survey page still
@@ -52,8 +62,8 @@ answer. It still checks what it's told:
   to the new one.
 - `sync`: shares now instead of after the next session. It counts the window again and sends the rows that changed
   since the server last accepted them; the server replaces what it had, so nothing counts twice.
-- `status`: which survey this Mac shares with, what the person chose, the hooks and when they last ran, and when it
-  last shared.
+- `status`: which survey this Mac shares with, what the person chose, the hooks and when they last ran, when it last
+  shared, and the add-on's version and when it last looked for a newer one.
 - `disconnect`: stops sharing from this Mac and removes everything it put in place.
 - `preview [--days 30] [--company github.com/acme] [--json]`: what would be shared, without sending.
 
@@ -88,14 +98,15 @@ nothing, and `disconnect` still takes them away.
 
 For testing, `AI_ADOPTION_SCORE_HOME`, `AI_ADOPTION_SCORE_CLAUDE_SETTINGS`, `AI_ADOPTION_SCORE_CODEX_HOOKS` and
 `AI_ADOPTION_SCORE_LAUNCH_AGENTS` move each of these elsewhere, and `AI_ADOPTION_SCORE_SKIP_LAUNCHCTL=1` leaves launchd
-alone. `AI_ADOPTION_SCORE_NODE` names a Node for `run.sh` to try.
+alone. `AI_ADOPTION_SCORE_NODE` names a Node for `run.sh` to try. `AI_ADOPTION_SCORE_REGISTRY` points the daily update
+at another npm registry; like the server, it has to be https, or http on this Mac itself.
 
 ## Try it
 
 Count this Mac's last 30 days and see what would be shared, without connecting and without sending anything:
 
 ```bash
-npx @ai-adoption-score/ai-coding-usage@1 preview
+npx @ai-adoption-score/ai-coding-usage@latest preview
 ```
 
 Add `--json` to see the exact rows, or `--days 7` for a shorter window. It needs Node.js 18.17 or newer and git, and
@@ -132,10 +143,10 @@ again and ticks it. Work outside any repository is one more box.
 ## What a row holds
 
 One row per session, day, repository and branch: the tool, a hash of the session id, the day and the first and last
-moment, the repository and branch and whether the branch is pushed, active minutes, prompts, stops, rejected actions,
-commands, file edits, lines added and removed, connector calls by name, skills, helper agents, commits and pushed
-commits, and per model its replies and tokens. `npx @ai-adoption-score/ai-coding-usage@1 preview --json` prints the exact rows this Mac
-would send.
+moment, the repository and branch and whether the branch is pushed, active minutes and the same time by hour, prompts,
+stops, rejected actions, commands, file edits, lines added and removed, connector calls by name, skills, helper agents,
+commits and pushed commits, and per model its replies and tokens. `npx @ai-adoption-score/ai-coding-usage@latest
+preview --json` prints the exact rows this Mac would send.
 
 Never shared: prompts, AI answers, code, file names and paths, command text, session titles.
 
@@ -155,3 +166,7 @@ Never shared: prompts, AI answers, code, file names and paths, command text, ses
   lines as added. A failed or turned-down edit, or a scratch file elsewhere, doesn't count.
 - Active minutes add up the gaps under five minutes. A commit counts for the session whose window holds it, from its
   first moment to an hour after its last; each commit counts once.
+- Time by hour (`minutesByHour`, from 1.1) is the same active time cut at the hours (UTC). A minute when several
+  sessions were active at once is split between them, so a person's rows add up to the time they really spent: on one
+  Mac with sessions side by side, 30 days of active minutes came to 185 hours and their time by hour to the 92 really
+  spent. Only the rows that are shared take part, so a session that stays on the Mac takes no share.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-adoption-score/ai-coding-usage",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Shares how you use Claude Code and Codex with your company's AI Adoption Score survey. Never prompts, AI answers, code or file names.",
   "homepage": "https://ai-adoption-score.app/product/ai-coding-usage",
   "repository": {

package/src/checkin.mjs

@@ -2,17 +2,18 @@
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { CLIENT_VERSION, post } from './api.mjs'
-import { isCurrentConfig, readConfig } from './config.mjs'
+import { isCurrentConfig, readConfig, takeHistoryDays } from './config.mjs'
 import { hookState, uninstallAll } from './install.mjs'
 import { log } from './log.mjs'
 import { paths } from './paths.mjs'
 import { localDay } from './rows.mjs'
 import { readState, updateState } from './state.mjs'
+import { updateIfDue } from './update.mjs'
 
 /**
  * The hourly check-in (a launchd agent): tells the survey this Mac is there, and whether each tool's hook is still in
  * place and running. It sends no usage numbers. A day with a check-in and no use is a real zero in the report; a day
- * without one is a gap.
+ * without one is a gap. Once a day it also looks for a newer add-on (update.mjs).
  */
 
 const NOT_APPROVED_GRACE_MS = 15 * 60_000
@@ -88,9 +89,17 @@ export async function runCheckIn(env = process.env) {
     updateState((current) => {
       current.lastCheckInAt = new Date().toISOString()
     }, env)
+    // A server that now takes more days back than these settings say: the next sync sends the days in between once.
+    if (status === 'active') takeHistoryDays(config, response.body, env)
     log(`check-in: ${response.status} ${status ?? ''} claude=${checkIn.claudeHook} codex=${checkIn.codexHook}`, env)
   } catch (error) {
     log(`check-in failed: ${error instanceof Error ? error.message : String(error)}`, env)
+    return 0
+  }
+  try {
+    await updateIfDue(env)
+  } catch (error) {
+    log(`update failed: ${error instanceof Error ? error.message : String(error)}`, env)
   }
   return 0
 }

package/src/cli.mjs

@@ -10,7 +10,8 @@ import { DEFAULT_SERVER, readConfig, writeConfig } from './config.mjs'
 import { runHook } from './hook.mjs'
 import { hookState, installAll, uninstallAll } from './install.mjs'
 import { paths } from './paths.mjs'
-import { daysToRead, scanUsage } from './scan.mjs'
+import { MAX_HISTORY_DAYS, daysToRead, scanUsage } from './scan.mjs'
+import { timeByHour } from './rows.mjs'
 import { readState } from './state.mjs'
 import { describeChoice, repositoryList } from './choice.mjs'
 import { formatSummary } from './summary.mjs'
@@ -27,14 +28,15 @@ Usage
   ai-coding-usage preview [--days 30] [--company github.com/acme] [--json]
 
   connect     Link this Mac to your survey with the code from your survey page. It adds a hook to Claude Code and
-              Codex and an automatic ping-back, and sends the names of the repositories you used in the last 30 days, so
-              you can choose on your survey page which to share. Then it shares the last 30 days of those, and after
-              that, after each session. Run it again to change your choice.
-  status      Show which survey this Mac shares with, what you chose, its hooks, and when it last shared.
+              Codex and an automatic ping-back, and sends the names of the repositories you used in the last 90 days, so
+              you can choose on your survey page which to share. Then it shares the last 90 days of those, and after
+              that, after each session. Run it again to change your choice. Once a day the ping-back looks for a
+              newer version of the add-on and puts it in place.
+  status      Show which survey this Mac shares with, what you chose, its hooks, when it last shared, and its version.
   sync        Share now, instead of after the next session.
   disconnect  Stop sharing from this Mac: removes the hooks, the ping-back and the add-on's settings.
   preview     Count this Mac's last 30 days and show what would be shared. Nothing is sent.
-  --days      How many days back, 1 to 30.
+  --days      How many days back, 1 to 90.
   --company   An account whose repositories are your company's, to mark them. Repeat for more.
   --json      Print the exact rows instead of the summary.
 `
@@ -108,7 +110,7 @@ async function connect(args) {
     else if (!code) code = args[index]
     else return fail(`Unknown option "${args[index]}".`)
   }
-  if (!code) return fail('Add the code from your survey page: npx @ai-adoption-score/ai-coding-usage@1 connect K7Q2-9M4X')
+  if (!code) return fail('Add the code from your survey page: npx @ai-adoption-score/ai-coding-usage@latest connect K7Q2-9M4X')
   const problem = serverProblem(server)
   if (problem) return fail(problem)
   // Run again on a Mac that is connected: the same server carries the link on with the new token, so it doesn't
@@ -129,7 +131,7 @@ async function connect(args) {
     return fail(response.body?.error ?? `Couldn't connect: the server answered ${response.status}.`)
   }
   const { token, companyName, syncIntervalSeconds } = response.body
-  // However far back the survey asks for, the add-on reads 30 days at most.
+  // However far back the survey asks for, the add-on reads 90 days at most (config.mjs).
   const historyDays = daysToRead(response.body.historyDays)
   // A new connection starts with nothing sent.
   rmSync(paths().state, { force: true })
@@ -157,7 +159,7 @@ async function connect(args) {
   const found = list.repositories.length
   say(`Found ${found} ${found === 1 ? 'repository' : 'repositories'}${list.outsideGit ? ', and work outside a repository' : ''}, in the last ${historyDays} days.`)
   say('Now choose on your survey page which to share. Nothing from your sessions is sent until you do.')
-  say('Then the last 30 days of what you chose are shared, and after that, your numbers after each session.')
+  say(`Then the last ${historyDays} days of what you chose are shared, and after that, your numbers after each session.`)
   // Waits in the background, so this line returns at once in Claude Code or Codex too.
   const waiter = spawn(process.execPath, [paths().appBin, 'sync', '--background', '--wait-for-choice'], {
     detached: true,
@@ -226,6 +228,7 @@ async function status() {
   say(`Codex hook: ${hookState('codex')}${state.hookRuns.codex ? `, last ran ${state.hookRuns.codex}` : ''}`)
   say(state.lastSyncAt ? `Last shared: ${state.lastSyncAt}.` : 'Nothing shared yet.')
   if (state.lastCheckInAt) say(`Last ping-back: ${state.lastCheckInAt}.`)
+  say(`Add-on ${CLIENT_VERSION}; it looks for a newer version once a day${state.lastUpdateCheckAt ? `, last on ${state.lastUpdateCheckAt}` : ''}.`)
   if (state.lastError) say(`Last problem: ${state.lastError}`)
   return 0
 }
@@ -256,7 +259,7 @@ async function preview(rest) {
     if (option === '--json') json = true
     else if (option === '--days') {
       days = Number(rest[++index])
-      if (!Number.isInteger(days) || days < 1 || days > 30) return fail('--days needs a whole number from 1 to 30.')
+      if (!Number.isInteger(days) || days < 1 || days > MAX_HISTORY_DAYS) return fail(`--days needs a whole number from 1 to ${MAX_HISTORY_DAYS}.`)
     } else if (option === '--company') {
       const account = rest[++index]
       if (!account) return fail('--company needs an account, like github.com/acme.')
@@ -265,6 +268,6 @@ async function preview(rest) {
   }
   if (process.platform !== 'darwin') return fail('AI Coding Usage works on a Mac for now. Nothing was read.')
   const scan = await scanUsage({ days })
-  process.stdout.write(json ? `${JSON.stringify({ since: scan.since, until: scan.until, rows: scan.rows }, null, 2)}\n` : `${formatSummary(scan, { companyAccounts })}\n`)
+  process.stdout.write(json ? `${JSON.stringify({ since: scan.since, until: scan.until, rows: timeByHour(scan.rows) }, null, 2)}\n` : `${formatSummary(scan, { companyAccounts })}\n`)
   return 0
 }

package/src/config.mjs

@@ -7,12 +7,44 @@ import { join } from 'node:path'
  * The add-on's own folder, `~/.ai-adoption-score`: the connection's settings and its device token. Only the person's
  * own account can read it. `AI_ADOPTION_SCORE_HOME` points it elsewhere, for testing.
  *
+ * `historyDays` is how many days back the server takes, and `historyDaysSent` how many of them went out in one sync:
+ * fewer, and the next sync reads them all once (`sync.mjs`).
+ *
  * @typedef {{ server: string, token: string, companyName: string, connectedAt: string, syncIntervalSeconds: number,
- *   historyDays: number, lastSyncAt?: string, initialSyncDone?: boolean }} UsageConfig
+ *   historyDays: number, historyDaysSent?: number, lastSyncAt?: string, initialSyncDone?: boolean }} UsageConfig
  */
 
 export const DEFAULT_SERVER = 'https://app.ai-adoption-score.app'
 
+/** The add-on never reads further back than this, whatever the server asks for. */
+export const MAX_HISTORY_DAYS = 90
+/** What a server that names no number takes: every server before add-on 1.2 took 30 days. */
+const DEFAULT_HISTORY_DAYS = 30
+
+/** How many days to read: a whole number from 1 to 90, and 30 when `days` isn't one. @param {unknown} days */
+export function daysToRead(days) {
+  const whole = Math.trunc(Number(days))
+  return Number.isFinite(whole) && whole >= 1 ? Math.min(whole, MAX_HISTORY_DAYS) : DEFAULT_HISTORY_DAYS
+}
+
+/**
+ * A server's answer to a sync or a check-in that takes more days than this Mac's settings say (`historyDays`: 30 before,
+ * 90 since add-on 1.2): the settings take the new number, so the next sync sends the days in between once. Never fewer,
+ * so a Mac never sends a day its server would refuse. Returns the settings as they are now.
+ * @param {UsageConfig} config
+ * @param {unknown} answer
+ * @returns {UsageConfig}
+ */
+export function takeHistoryDays(config, answer, env = process.env) {
+  const named = answer && typeof answer === 'object' && 'historyDays' in answer ? answer.historyDays : undefined
+  if (named === undefined) return config
+  const offered = daysToRead(named)
+  if (offered <= (config.historyDays ?? 0) || !isCurrentConfig(config, env)) return config
+  const next = { ...(readConfig(env) ?? config), historyDays: offered }
+  writeConfig(next, env)
+  return next
+}
+
 export function configDir(env = process.env) {
   return env.AI_ADOPTION_SCORE_HOME || join(homedir(), '.ai-adoption-score')
 }

package/src/rows.mjs

@@ -12,7 +12,8 @@ import { createHash } from 'node:crypto'
  *   repository: string | null, branch: string | null, branchPushed: boolean, activeMinutes: number,
  *   prompts: number, interrupts: number, rejectedActions: number, commands: number, fileEdits: number,
  *   linesAdded: number, linesRemoved: number, connectors: Record<string, number>, skills: number,
- *   helperAgents: number, commits: number, commitsPushed: number, models: Record<string, ModelTokens>
+ *   helperAgents: number, commits: number, commitsPushed: number, models: Record<string, ModelTokens>,
+ *   minutesByHour?: Record<string, number>
  * }} UsageRow
  *
  * What a row collects before it is finished; `gitTop` and `times` never leave the Mac.
@@ -111,6 +112,57 @@ export function changedLines(before, after) {
   return { added: newEnd - start, removed: oldEnd - start }
 }
 
+/** Each finished row's moments, kept here so they never leave the Mac: `timeByHour` needs them. */
+const momentsOf = new WeakMap()
+const HOUR_MS = 3_600_000
+
+/**
+ * Time with AI by hour (owner, 2026-10-30): each row's active stretches, the gaps under five minutes between its
+ * moments, cut at the hours (UTC, `YYYY-MM-DDTHH`), with a stretch when several of `rows` were active at once shared
+ * evenly between them. So the rows of a day add up to the time the person really spent with AI, however many sessions
+ * ran side by side, where active minutes count each session's own. Only the rows given take part, so a session that
+ * isn't shared changes nothing in the ones that are.
+ * @param {UsageRow[]} rows @returns {UsageRow[]}
+ */
+export function timeByHour(rows) {
+  /** @type {Array<[number, number, number]>} */
+  const points = []
+  rows.forEach((row, index) => {
+    const times = momentsOf.get(row) ?? []
+    for (let at = 1; at < times.length; at += 1) {
+      if (times[at] > times[at - 1] && times[at] - times[at - 1] < ACTIVE_GAP_MS) points.push([times[at - 1], 1, index], [times[at], -1, index])
+    }
+  })
+  // At the same moment, a stretch ends before the next begins.
+  points.sort((left, right) => left[0] - right[0] || left[1] - right[1])
+  /** @type {Map<string, number>[]} */
+  const shares = rows.map(() => new Map())
+  /** @type {Map<number, number>} the rows active now, and how many of their stretches */
+  const open = new Map()
+  let previous = 0
+  for (const [time, step, index] of points) {
+    for (let from = previous; open.size > 0 && from < time; ) {
+      const to = Math.min((Math.floor(from / HOUR_MS) + 1) * HOUR_MS, time)
+      const hour = new Date(from).toISOString().slice(0, 13)
+      for (const active of open.keys()) shares[active].set(hour, (shares[active].get(hour) ?? 0) + (to - from) / open.size)
+      from = to
+    }
+    const count = (open.get(index) ?? 0) + step
+    if (count > 0) open.set(index, count)
+    else open.delete(index)
+    previous = time
+  }
+  return rows.map((row, index) => {
+    /** @type {Record<string, number>} */
+    const minutesByHour = {}
+    for (const [hour, ms] of shares[index]) {
+      const minutes = Math.round(ms / 6_000) / 10
+      if (minutes > 0) minutesByHour[hour] = minutes
+    }
+    return { ...row, minutesByHour }
+  })
+}
+
 /** Working time: the gaps between a row's moments that are shorter than five minutes, added up. */
 function activeMinutes(times) {
   if (times.length === 0) return 0
@@ -130,7 +182,7 @@ function activeMinutes(times) {
 export function finishRow(draft, isPushed) {
   const times = [...draft.times].sort((left, right) => left - right)
   const { sessionId, gitTop, times: _times, ...rest } = draft
-  return {
+  const row = {
     ...rest,
     sessionKey: createHash('sha256').update(`${draft.tool}:${sessionId}`).digest('hex').slice(0, 32),
     firstEventAt: new Date(times[0]).toISOString(),
@@ -138,6 +190,8 @@ export function finishRow(draft, isPushed) {
     branchPushed: isPushed(gitTop, draft.branch),
     activeMinutes: activeMinutes(times),
   }
+  momentsOf.set(row, times)
+  return row
 }
 
 /** Whether a row has anything worth sending: a reply from the AI or a prompt from the person. */

package/src/scan.mjs

@@ -4,22 +4,18 @@ import { readCodex } from './codex.mjs'
 import { loadDesktopConnectorNames } from './connectors.mjs'
 import { assignCommits, createGitInfo } from './git.mjs'
 import { createRowSet, finishRow, hasUse, windowStart } from './rows.mjs'
+import { daysToRead } from './config.mjs'
 
-/** The add-on never reads further back than this, whatever the server asks for. */
-export const MAX_HISTORY_DAYS = 30
-
-/** How many days to read: a whole number from 1 to 30, and 30 when `days` isn't one. @param {unknown} days */
-export function daysToRead(days) {
-  const whole = Math.trunc(Number(days))
-  return Number.isFinite(whole) && whole >= 1 ? Math.min(whole, MAX_HISTORY_DAYS) : MAX_HISTORY_DAYS
-}
+export { MAX_HISTORY_DAYS, daysToRead } from './config.mjs'
 
 /**
- * Reads this Mac's Claude Code and Codex records for the last `days` calendar days, 30 at most, and returns the rows
- * that would be sent, with how much of the records could be read. Nothing is written and nothing leaves the Mac.
+ * Reads this Mac's Claude Code and Codex records for the last `days` calendar days (30 unless asked, 90 at most) and
+ * returns the rows that would be sent, with how much of the records could be read. Nothing is written and nothing leaves
+ * the Mac. Claude Code deletes its own records after 30 days unless its `cleanupPeriodDays` says otherwise, so older days
+ * hold what is left of them; Codex keeps its records.
  * @param {{ days?: number, now?: number, env?: NodeJS.ProcessEnv }} [options]
  */
-export async function scanUsage({ days = MAX_HISTORY_DAYS, now = Date.now(), env = process.env } = {}) {
+export async function scanUsage({ days = 30, now = Date.now(), env = process.env } = {}) {
   const since = windowStart(now, daysToRead(days))
   const rows = createRowSet()
   const gitInfo = createGitInfo()

package/src/state.mjs

@@ -5,13 +5,14 @@ import { paths } from './paths.mjs'
 
 /**
  * What the add-on remembers between runs, beside its settings: which rows the server accepted (by a hash of each), when
- * it last synced, when each tool's hook last ran, and how long the server asked it to wait. Only names and numbers.
+ * it last synced, when each tool's hook last ran, how long the server asked it to wait, and when it last looked for a
+ * newer version. Only names and numbers.
  *
  * @typedef {{
  *   sent: Record<string, string>,
  *   lastSyncStartedAt?: string, lastSyncAt?: string, notBefore?: string,
  *   hookRuns: Partial<Record<'claude-code' | 'codex', string>>,
- *   lastCheckInAt?: string, lastError?: string
+ *   lastCheckInAt?: string, lastError?: string, lastUpdateCheckAt?: string
  * }} UsageState
  */
 

package/src/sync.mjs

@@ -5,11 +5,11 @@ import { constants, setPriority } from 'node:os'
 import { get, post, CLIENT_VERSION } from './api.mjs'
 import { reportedHookState } from './checkin.mjs'
 import { isShared, readChoice } from './choice.mjs'
-import { isCurrentConfig, writeConfig } from './config.mjs'
+import { isCurrentConfig, readConfig, takeHistoryDays, writeConfig } from './config.mjs'
 import { hookState, uninstallAll } from './install.mjs'
 import { log } from './log.mjs'
 import { paths } from './paths.mjs'
-import { localDay } from './rows.mjs'
+import { localDay, timeByHour } from './rows.mjs'
 import { scanUsage } from './scan.mjs'
 import { readState, updateState } from './state.mjs'
 
@@ -18,6 +18,12 @@ const MAX_ROWS = 400
 const MAX_BYTES = 200 * 1024
 /** A sync that started this long ago and still holds the lock has died. */
 const STALE_LOCK_MS = 15 * 60_000
+/**
+ * The days every sync reads once all the days the server takes went out: the rows that can still change (today's, a
+ * branch pushed later, a commit made after a session) are in them, and reading more would only take longer (about 20
+ * seconds for 30 days on a busy Mac).
+ */
+export const SYNC_DAYS = 30
 
 /** @param {import('./rows.mjs').UsageRow[]} rows */
 export function batches(rows) {
@@ -136,8 +142,13 @@ export async function syncNow(config, { background = false, reason = 'manual', e
     }
     const { choice } = asked
 
-    const scan = await scanUsage({ days: config.historyDays, env })
-    const included = scan.rows.filter((row) => sendsTool(row.tool, config, state, env) && isShared(choice, row.repository))
+    // All the days the server takes go out in one sync: the first one, and once more when the server comes to take
+    // more than before (90 instead of 30 since add-on 1.2). Every other sync reads the last 30 days.
+    const wholeWindow = (config.historyDaysSent ?? 0) < config.historyDays
+    const days = wholeWindow ? config.historyDays : Math.min(config.historyDays, SYNC_DAYS)
+    const scan = await scanUsage({ days, env })
+    // Time by hour among the rows that go out only, so a session that stays on the Mac takes no share of it.
+    const included = timeByHour(scan.rows.filter((row) => sendsTool(row.tool, config, state, env) && isShared(choice, row.repository)))
     const changed = included.filter((row) => state.sent[rowKey(row)] !== rowHash(row))
     const checkIn = {
       day: localDay(Date.now()),
@@ -147,9 +158,12 @@ export async function syncNow(config, { background = false, reason = 'manual', e
     const groups = changed.length > 0 ? batches(changed) : [[]]
     let accepted = 0
     let status = asked.status === 'revoked' || asked.status === 'closed' ? asked.status : 'active'
+    /** @type {unknown} */
+    let answer = null
     for (const [index, rows] of status === 'active' ? groups.entries() : []) {
       const body = { schemaVersion: 1, clientVersion: CLIENT_VERSION, rows, ...(index === 0 ? { checkIn } : {}) }
       const response = await post(config.server, '/api/usage/sync', body, config.token)
+      answer = response.body
       status = response.body?.status ?? (response.status === 401 ? 'revoked' : 'error')
       if (response.status === 429 || status === 'paused') {
         const wait = (response.retryAfterSeconds ?? response.body?.nextSyncAfterSeconds ?? 600) * 1000
@@ -182,9 +196,19 @@ export async function syncNow(config, { background = false, reason = 'manual', e
       updateState((current) => {
         current.sent = Object.fromEntries(Object.entries(current.sent).filter(([key]) => keep.has(key)))
       }, env)
-      // The first sync is the one with the person's choice: it sends the last 30 days of every tool.
-      if (choice && !config.initialSyncDone && isCurrentConfig(config, env)) writeConfig({ ...config, initialSyncDone: true, lastSyncAt: new Date().toISOString() }, env)
-      log(`sync (${reason}): sent ${accepted} of ${included.length} rows`, env)
+      // The first sync is the one with the person's choice: it sends every tool's days. Once all the days the server takes
+      // went out, the next syncs read the last 30.
+      if (choice && (!config.initialSyncDone || wholeWindow) && isCurrentConfig(config, env)) {
+        const current = readConfig(env) ?? config
+        writeConfig({
+          ...current,
+          ...(config.initialSyncDone ? {} : { initialSyncDone: true, lastSyncAt: new Date().toISOString() }),
+          ...(wholeWindow ? { historyDaysSent: days } : {}),
+        }, env)
+      }
+      // A server that takes more days than these settings say: the next sync sends the days in between.
+      takeHistoryDays(config, answer, env)
+      log(`sync (${reason}): sent ${accepted} of ${included.length} rows${wholeWindow ? `, reading ${days} days` : ''}`, env)
     } else {
       log(`sync (${reason}): ${status}`, env)
     }
@@ -204,9 +228,9 @@ export async function syncNow(config, { background = false, reason = 'manual', e
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
 /**
- * Right after connecting, in the background: waits while the person chooses on their survey page, then sends the last
- * 30 days of what they chose. It gives up when the list on their page expires (an hour); the next sync after they
- * choose sends them all the same.
+ * Right after connecting, in the background: waits while the person chooses on their survey page, then sends the days
+ * the server takes (90) of what they chose. It gives up when the list on their page expires (an hour); the next sync
+ * after they choose sends them all the same.
  * @param {import('./config.mjs').UsageConfig} config
  * @param {{ env?: NodeJS.ProcessEnv, timeoutMs?: number }} [options]
  */

package/src/update.mjs

@@ -0,0 +1,173 @@
+// @ts-check
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { CLIENT_VERSION, serverProblem } from './api.mjs'
+import { log } from './log.mjs'
+import { paths } from './paths.mjs'
+import { readState, updateState } from './state.mjs'
+
+/**
+ * The add-on keeps itself up to date (owner, 2026-10-30): once a day the ping-back asks npm for the latest version.
+ * When there is a newer one, it downloads it, checks it is byte for byte the file npm lists for that version, checks
+ * that it starts on this Mac's Node, and puts it in place of its own copy; the next hook or ping-back runs it. Nothing
+ * is sent to npm but the request itself. The hooks, the ping-back and the settings stay as they are, and anything that
+ * goes wrong leaves the copy that works.
+ */
+
+const PACKAGE = '@ai-adoption-score/ai-coding-usage'
+const REGISTRY = 'https://registry.npmjs.org'
+const CHECK_EVERY_MS = 24 * 60 * 60_000
+const TIMEOUT_MS = 30_000
+const MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024
+
+/** "1.2.3" as numbers; null for anything else, such as a pre-release. @param {unknown} version */
+function versionParts(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version))
+  return match ? match.slice(1).map(Number) : null
+}
+
+/** Whether `candidate` is a later release than `current`; never a step back. @param {unknown} candidate @param {unknown} current */
+export function isNewer(candidate, current) {
+  const next = versionParts(candidate)
+  const now = versionParts(current)
+  if (!next || !now) return false
+  for (let index = 0; index < 3; index += 1) if (next[index] !== now[index]) return next[index] > now[index]
+  return false
+}
+
+/** Whether this Node is new enough for `engines.node` written as ">=18.17"; any other form is left to the start check. */
+function nodeFits(engines, running = process.versions.node) {
+  const wanted = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(String(engines?.node ?? '').trim())
+  if (!wanted) return true
+  const need = wanted.slice(1).map((part) => Number(part ?? 0))
+  const have = running.split('.').map(Number)
+  for (let index = 0; index < 3; index += 1) if ((have[index] ?? 0) !== need[index]) return (have[index] ?? 0) > need[index]
+  return true
+}
+
+/** @param {string} url @param {Record<string, string>} headers */
+async function download(url, headers = {}) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    const response = await fetch(url, { headers: { 'user-agent': `ai-coding-usage/${CLIENT_VERSION}`, ...headers }, signal: controller.signal })
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`)
+    const body = Buffer.from(await response.arrayBuffer())
+    if (body.length > MAX_DOWNLOAD_BYTES) throw new Error(`${url} is larger than expected`)
+    return body
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * The files of an npm package: a gzipped tar with every entry under `package/`. Only plain files whose path stays
+ * inside the package are read; links and anything else are left out.
+ * @param {Buffer} tarball @returns {Map<string, { data: Buffer, mode: number }>}
+ */
+export function readPackage(tarball) {
+  const archive = gunzipSync(tarball)
+  const files = new Map()
+  /** @type {string | null} */
+  let paxPath = null
+  for (let offset = 0; offset + 512 <= archive.length; ) {
+    const header = archive.subarray(offset, offset + 512)
+    if (header.every((byte) => byte === 0)) break
+    const field = (start, length) => header.subarray(start, start + length).toString('utf8').replace(/\0[\s\S]*$/, '')
+    const size = parseInt(field(124, 12).trim() || '0', 8)
+    const type = field(156, 1) || '0'
+    const prefix = field(257, 5) === 'ustar' ? field(345, 155) : ''
+    const name = paxPath ?? (prefix ? `${prefix}/${field(0, 100)}` : field(0, 100))
+    paxPath = null
+    const body = archive.subarray(offset + 512, offset + 512 + size)
+    offset += 512 + Math.ceil(size / 512) * 512
+    if (type === 'x') {
+      // An extended header: its `path` names the next entry.
+      paxPath = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8'))?.[1] ?? null
+      continue
+    }
+    if (type !== '0') continue
+    const parts = name.split('/')
+    if (parts[0] !== 'package' || parts.length < 2 || parts.some((part) => part === '' || part === '.' || part === '..')) continue
+    files.set(parts.slice(1).join('/'), { data: Buffer.from(body), mode: parseInt(field(100, 8).trim() || '644', 8) & 0o755 })
+  }
+  return files
+}
+
+/**
+ * Puts `version` in place of the add-on's copy, when it is the one npm lists and it starts here.
+ * @param {{ version: string, dist?: { tarball?: string, integrity?: string } }} manifest @param {string} registry
+ */
+async function install(manifest, registry, env) {
+  const where = paths(env)
+  const tarball = manifest.dist?.tarball
+  const integrity = /^sha512-(.+)$/.exec(manifest.dist?.integrity ?? '')?.[1]
+  if (!tarball || !integrity || new URL(tarball).origin !== new URL(registry).origin) throw new Error(`npm lists no file for ${manifest.version} that can be checked`)
+  const archive = await download(tarball)
+  if (createHash('sha512').update(archive).digest('base64') !== integrity) throw new Error(`the file for ${manifest.version} isn't the one npm lists`)
+  const files = readPackage(archive)
+  const listed = JSON.parse(files.get('package.json')?.data.toString('utf8') ?? '{}')
+  if (listed.name !== PACKAGE || listed.version !== manifest.version || !files.has('bin/ai-coding-usage.mjs')) throw new Error(`the file for ${manifest.version} isn't this add-on`)
+
+  // The new copy beside the old one, as connecting puts it: its program and its package.json, nothing else.
+  const fresh = `${where.app}.update`
+  const previous = `${where.app}.previous`
+  rmSync(fresh, { recursive: true, force: true })
+  try {
+    for (const [path, file] of files) {
+      if (path !== 'package.json' && !path.startsWith('bin/') && !path.startsWith('src/')) continue
+      mkdirSync(dirname(join(fresh, path)), { recursive: true })
+      writeFileSync(join(fresh, path), file.data, { mode: file.mode })
+    }
+    try {
+      // It has to start on this Node before it replaces the copy that works: its help loads all of it and exits.
+      execFileSync(process.execPath, [join(fresh, 'bin', 'ai-coding-usage.mjs'), 'help'], { stdio: 'ignore', timeout: TIMEOUT_MS, env })
+    } catch {
+      throw new Error(`${manifest.version} doesn't start on Node ${process.versions.node}`)
+    }
+    rmSync(previous, { recursive: true, force: true })
+    renameSync(where.app, previous)
+    try {
+      renameSync(fresh, where.app)
+    } catch (error) {
+      renameSync(previous, where.app)
+      throw error
+    }
+    rmSync(previous, { recursive: true, force: true })
+  } finally {
+    rmSync(fresh, { recursive: true, force: true })
+  }
+}
+
+/**
+ * The ping-back's daily look at npm. `AI_ADOPTION_SCORE_REGISTRY` points it at another registry, for testing; like the
+ * survey's server, it has to be https, or http on this Mac itself.
+ * @returns {Promise<'not-due' | 'up-to-date' | 'updated' | 'skipped'>}
+ */
+export async function updateIfDue(env = process.env, now = Date.now()) {
+  const last = readState(env).lastUpdateCheckAt
+  if (last && now - Date.parse(last) < CHECK_EVERY_MS) return 'not-due'
+  const registry = env.AI_ADOPTION_SCORE_REGISTRY || REGISTRY
+  const problem = serverProblem(registry)
+  if (problem) throw new Error(problem)
+  const document = JSON.parse(
+    (await download(`${registry.replace(/\/+$/, '')}/${PACKAGE.replace('/', '%2f')}`, { accept: 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8' })).toString('utf8')
+  )
+  // npm answered: the next look is tomorrow, whatever happens next.
+  updateState((current) => {
+    current.lastUpdateCheckAt = new Date(now).toISOString()
+  }, env)
+  const latest = document?.['dist-tags']?.latest
+  const manifest = document?.versions?.[latest]
+  if (!isNewer(latest, CLIENT_VERSION) || !manifest) return 'up-to-date'
+  if (manifest.deprecated || !nodeFits(manifest.engines)) {
+    log(`update: ${latest} is out, but ${manifest.deprecated ? 'it was withdrawn' : `it needs Node ${manifest.engines.node}`}; staying on ${CLIENT_VERSION}`, env)
+    return 'skipped'
+  }
+  await install(manifest, registry, env)
+  log(`update: ${CLIENT_VERSION} → ${latest}`, env)
+  return 'updated'
+}