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

package/README.md

@@ -11,15 +11,45 @@ Connected once, it shares by itself: a hook in Claude Code and Codex syncs after
 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".
 
+## How it works, step by step
+
+In short: connect, choose on the survey page, then share. Before the choice, only repository names leave the Mac.
+
+1. **The person pastes the line from their survey page** into Claude Code, Codex or Terminal. The code in it works
+   once, for 30 minutes; the server trades it for a token for this Mac.
+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
+   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
+   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
+   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 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.
+
 ## 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
   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. Run again on a Mac that is
-  connected, it keeps that Mac's link on the same server (the survey page still shows one Mac) and lets the person
-  choose again; a link on another server is disconnected, and its token never goes to the new one.
+  `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
+  shows one Mac) and lets the person choose again; a link on another server is disconnected, and its token never goes
+  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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-adoption-score/ai-coding-usage",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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/api.mjs

@@ -7,6 +7,22 @@ const TIMEOUT_MS = 20_000
 
 export const CLIENT_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 
+/** Plain http goes only to this Mac itself, for testing; the device token goes anywhere else over https. */
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+/** Why the add-on won't talk to `server`, or null when it will. @param {string} server */
+export function serverProblem(server) {
+  let url
+  try {
+    url = new URL(server)
+  } catch {
+    return `"${server}" isn't a web address.`
+  }
+  if (url.protocol === 'https:') return null
+  if (url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname)) return null
+  return `"${server}" isn't https. Plain http works only for this Mac's own address (localhost), for testing.`
+}
+
 /**
  * @param {string} server @param {string} path @param {unknown} body @param {string} [token]
  * @returns {Promise<{ status: number, body: any, retryAfterSeconds: number | null }>}
@@ -25,6 +41,8 @@ export async function get(server, path, token) {
 
 /** @param {string} server @param {string} path @param {'GET' | 'POST'} method @param {unknown} body @param {string} [token] */
 async function request(server, path, method, body, token) {
+  const problem = serverProblem(server)
+  if (problem) throw new Error(problem)
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
   try {

package/src/choice.mjs

@@ -19,13 +19,33 @@ export function repositoryOwner(repository) {
   return parts.length >= 3 ? `${parts[0]}/${parts[1]}`.toLowerCase() : null
 }
 
+/**
+ * The choice in the server's answer, taken only in one of the two shapes the server keeps: what the person ticked, or
+ * `{ all: true }` for links made before people could choose. Anything else shares nothing.
+ * @param {unknown} value @returns {RepositoryChoice | null}
+ */
+export function readChoice(value) {
+  if (!value || typeof value !== 'object') return null
+  const choice = /** @type {Record<string, unknown>} */ (value)
+  if ('all' in choice) return choice.all === true ? { all: true } : null
+  const names = (list) => Array.isArray(list) && list.every((name) => typeof name === 'string')
+  if (!names(choice.repositories) || !names(choice.owners)) return null
+  if (typeof choice.outsideGit !== 'boolean' || typeof choice.localFolders !== 'boolean') return null
+  return {
+    repositories: /** @type {string[]} */ (choice.repositories),
+    owners: /** @type {string[]} */ (choice.owners),
+    outsideGit: choice.outsideGit,
+    localFolders: choice.localFolders,
+  }
+}
+
 /**
  * Whether a session in `repository` (null outside any repository) is shared. Nothing is, before the person chooses.
  * @param {RepositoryChoice | null} choice @param {string | null} repository
  */
 export function isShared(choice, repository) {
   if (!choice) return false
-  if ('all' in choice) return true
+  if ('all' in choice) return choice.all === true
   if (!repository) return choice.outsideGit
   if (choice.repositories.includes(repository)) return true
   if (repository.startsWith(LOCAL_PREFIX)) return choice.localFolders
@@ -64,7 +84,7 @@ export function repositoryList(rows) {
 /** What this Mac shares, in a line for `status`. @param {RepositoryChoice | null} choice */
 export function describeChoice(choice) {
   if (!choice) return 'nothing yet: choose your repositories on your survey page'
-  if ('all' in choice) return 'every repository'
+  if ('all' in choice) return choice.all === true ? 'every repository' : 'nothing'
   const parts = [`${choice.repositories.length} ${choice.repositories.length === 1 ? 'repository' : 'repositories'}`]
   if (choice.owners.length > 0) parts.push(`new ones from ${choice.owners.join(', ')}`)
   if (choice.outsideGit) parts.push('work outside a repository')

package/src/cli.mjs

@@ -4,13 +4,13 @@ import { existsSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { CLIENT_VERSION, post } from './api.mjs'
+import { CLIENT_VERSION, post, serverProblem } from './api.mjs'
 import { runCheckIn } from './checkin.mjs'
 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 { scanUsage } from './scan.mjs'
+import { daysToRead, scanUsage } from './scan.mjs'
 import { readState } from './state.mjs'
 import { describeChoice, repositoryList } from './choice.mjs'
 import { formatSummary } from './summary.mjs'
@@ -109,11 +109,8 @@ async function connect(args) {
     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')
-  try {
-    new URL(server)
-  } catch {
-    return fail(`"${server}" isn't a web address.`)
-  }
+  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
   // count a second Mac. A token never goes to another server; that survey is told the Mac left once this one connects.
   const previous = readConfig()
@@ -131,7 +128,9 @@ async function connect(args) {
   if (response.status !== 200 || response.body?.status !== 'connected') {
     return fail(response.body?.error ?? `Couldn't connect: the server answered ${response.status}.`)
   }
-  const { token, companyName, syncIntervalSeconds, historyDays } = response.body
+  const { token, companyName, syncIntervalSeconds } = response.body
+  // However far back the survey asks for, the add-on reads 30 days at most.
+  const historyDays = daysToRead(response.body.historyDays)
   // A new connection starts with nothing sent.
   rmSync(paths().state, { force: true })
   const config = { server, token, companyName, connectedAt: new Date().toISOString(), syncIntervalSeconds, historyDays }
@@ -149,7 +148,7 @@ async function connect(args) {
   say(`  Codex: ${HOOK_WORDS[installed.codex] ?? installed.codex}`)
   say(`  Automatic ping-back: ${installed.checkIn === 'added' ? 'added, so the survey knows this Mac is still connected (no numbers)' : "couldn't add it"}`)
   // The person chooses which repositories to share before any session leaves this Mac: only the names go now.
-  const scan = await scanUsage({ days: historyDays || 30 })
+  const scan = await scanUsage({ days: historyDays })
   const list = repositoryList(scan.rows)
   const listed = await post(server, '/api/usage/repositories', list, token)
   if (listed.body?.status !== 'choosing') {

package/src/scan.mjs

@@ -5,13 +5,22 @@ import { loadDesktopConnectorNames } from './connectors.mjs'
 import { assignCommits, createGitInfo } from './git.mjs'
 import { createRowSet, finishRow, hasUse, windowStart } from './rows.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
+}
+
 /**
- * Reads this Mac's Claude Code and Codex records for the last `days` calendar days 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 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.
  * @param {{ days?: number, now?: number, env?: NodeJS.ProcessEnv }} [options]
  */
-export async function scanUsage({ days = 30, now = Date.now(), env = process.env } = {}) {
-  const since = windowStart(now, days)
+export async function scanUsage({ days = MAX_HISTORY_DAYS, now = Date.now(), env = process.env } = {}) {
+  const since = windowStart(now, daysToRead(days))
   const rows = createRowSet()
   const gitInfo = createGitInfo()
   const claudeHealth = { files: 0, lines: 0, unreadable: 0 }

package/src/sync.mjs

@@ -4,7 +4,7 @@ import { closeSync, openSync, readFileSync, rmSync, writeSync } from 'node:fs'
 import { constants, setPriority } from 'node:os'
 import { get, post, CLIENT_VERSION } from './api.mjs'
 import { reportedHookState } from './checkin.mjs'
-import { isShared } from './choice.mjs'
+import { isShared, readChoice } from './choice.mjs'
 import { isCurrentConfig, writeConfig } from './config.mjs'
 import { hookState, uninstallAll } from './install.mjs'
 import { log } from './log.mjs'
@@ -96,7 +96,7 @@ export async function askChoice(config) {
   if (response.status === 429) return { status: 'waiting', choice: null, retryAfterSeconds: response.retryAfterSeconds }
   const status = response.body?.status ?? (response.status === 401 ? 'revoked' : 'error')
   if (status === 'error') throw new Error(response.body?.error ?? `The server answered ${response.status}.`)
-  return { status, choice: response.body?.choice ?? null, retryAfterSeconds: null }
+  return { status, choice: readChoice(response.body?.choice), retryAfterSeconds: null }
 }
 
 /**
@@ -136,7 +136,7 @@ export async function syncNow(config, { background = false, reason = 'manual', e
     }
     const { choice } = asked
 
-    const scan = await scanUsage({ days: config.historyDays || 30, env })
+    const scan = await scanUsage({ days: config.historyDays, env })
     const included = 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 = {