bestviber 0.0.0-stage → 0.2.0

package/src/format.mjs

@@ -0,0 +1,97 @@
+// Human-readable output. `--json` bypasses all of this.
+
+/** @param {number} ms */
+export function duration(ms) {
+  const totalMin = Math.round(ms / 60000)
+  if (ms > 0 && totalMin === 0) return `${Math.round(ms / 1000)}s`
+  const h = Math.floor(totalMin / 60)
+  const m = totalMin % 60
+  if (h === 0) return `${m}m`
+  return m ? `${h}h ${m}m` : `${h}h`
+}
+
+/** Elapsed focus on an open session, pauses removed. */
+export function elapsed(/** @type {any} */ s, now = Date.now()) {
+  const start = Date.parse(s.startedAt)
+  const openPause = s.pausedAt ? now - Date.parse(s.pausedAt) : 0
+  return Math.max(0, now - start - s.pausedMs - openPause)
+}
+
+/** @param {string} iso */
+export function clock(iso) {
+  return new Date(iso).toLocaleTimeString([], {
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+}
+
+/** @param {number} value @param {number} max @param {number} width */
+function bar(value, max, width = 24) {
+  if (max <= 0) return ''
+  const n = Math.round((value / max) * width)
+  return '█'.repeat(n) + '·'.repeat(width - n)
+}
+
+/** @param {any} stats */
+export function stats(stats) {
+  const { range } = stats
+  const lines = []
+  const title =
+    range.from === range.to ? range.from : `${range.from} → ${range.to}`
+  lines.push(`${title}  (${range.tz})`)
+  lines.push('')
+  lines.push(`  focused     ${duration(stats.totalMs)}`)
+  lines.push(`  sessions    ${stats.sessionCount}`)
+  if (stats.sessionCount) {
+    lines.push(`  average     ${duration(stats.averageSessionMs)}`)
+    lines.push(`  longest     ${duration(stats.longestSession.durationMs)}`)
+  }
+  const change = stats.changeVsPrevious
+  if (change.percent !== null)
+    lines.push(
+      `  vs previous ${change.percent >= 0 ? '+' : ''}${change.percent}% (${duration(stats.previous.totalMs)} before)`,
+    )
+  if (stats.byDay.length > 1) {
+    lines.push(`  active days ${stats.activeDays}/${stats.byDay.length}`)
+    if (stats.bestDay)
+      lines.push(
+        `  best day    ${stats.bestDay.date} (${duration(stats.bestDay.ms)})`,
+      )
+  }
+
+  if (stats.byDay.length > 1 && stats.byDay.length <= 31) {
+    const max = Math.max(...stats.byDay.map((/** @type {any} */ d) => d.ms))
+    lines.push('', '  by day')
+    for (const d of stats.byDay)
+      lines.push(
+        `  ${d.date.slice(5)}  ${bar(d.ms, max)}  ${d.ms ? duration(d.ms) : ''}`,
+      )
+  }
+
+  const hours = stats.byHour.filter((/** @type {any} */ h) => h.ms > 0)
+  if (hours.length > 1) {
+    const max = Math.max(...hours.map((/** @type {any} */ h) => h.ms))
+    lines.push('', '  by hour')
+    for (const h of hours)
+      lines.push(
+        `  ${String(h.hour).padStart(2, '0')}:00  ${bar(h.ms, max)}  ${duration(h.ms)}`,
+      )
+  }
+
+  if (stats.byTag.length > 1 || stats.byTag[0]?.tag !== 'untagged') {
+    lines.push('', '  by tag')
+    for (const t of stats.byTag)
+      lines.push(`  ${t.tag.padEnd(16)} ${duration(t.ms)}`)
+  }
+
+  if (stats.byProject?.length) {
+    lines.push('', '  by project')
+    const width = Math.max(
+      16,
+      ...stats.byProject.map((/** @type {any} */ p) => p.project.length),
+    )
+    for (const p of stats.byProject)
+      lines.push(`  ${p.project.padEnd(width)} ${duration(p.ms)}`)
+  }
+  return lines.join('\n')
+}

package/src/hooks.mjs

@@ -0,0 +1,306 @@
+// Claude Code hooks: install them, and run them.
+//
+// Claude Code runs `bestviber hook` on SessionStart, UserPromptSubmit, Stop
+// and SessionEnd. That command must be instant and silent (stdout on
+// SessionStart and UserPromptSubmit is added to Claude's context, and
+// SessionEnd gets about 1.5 s before exit), so it only hands the event to a
+// detached worker and exits. The worker talks to the server.
+
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import {
+  appendFile,
+  copyFile,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { call, configPath, token } from './client.mjs'
+import { EMPTY_STATE, decide, projectName } from './tracker.mjs'
+
+const BIN = fileURLToPath(new URL('../bin/bestviber.mjs', import.meta.url))
+const stateDir = () => dirname(configPath())
+const statePath = () => join(stateDir(), 'tracking.json')
+const logPath = () => join(stateDir(), 'hook.log')
+const lockPath = () => join(stateDir(), 'tracking.lock')
+
+// ───── the hook command ─────
+
+/** Read the event from stdin and hand it to a detached worker. Never prints. */
+export async function launchHook() {
+  const payload = await readStdin(2000)
+  try {
+    spawn(process.execPath, [BIN, 'hook', '--run'], {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, BESTVIBER_HOOK_EVENT: payload },
+    }).unref()
+  } catch {
+    // Tracking is best-effort; never get in the way of Claude Code.
+  }
+}
+
+function readStdin(/** @type {number} */ ms) {
+  return new Promise((resolve) => {
+    let data = ''
+    const done = () => resolve(data)
+    const timer = setTimeout(done, ms)
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (c) => (data += c))
+    process.stdin.on('end', () => {
+      clearTimeout(timer)
+      done()
+    })
+    process.stdin.on('error', done)
+  })
+}
+
+/** Map a Claude Code hook event to a tracker event, or null to ignore it. */
+function trackerEvent(/** @type {any} */ e) {
+  switch (e?.hook_event_name) {
+    case 'SessionStart':
+      return 'start'
+    case 'UserPromptSubmit':
+      return 'prompt'
+    case 'Stop':
+      return 'reply'
+    case 'SessionEnd':
+      // /clear and /resume also end a session id, but the work goes on.
+      return ['prompt_input_exit', 'logout', 'other'].includes(e.reason)
+        ? 'end'
+        : null
+    default:
+      return null
+  }
+}
+
+// ───── the worker ─────
+
+export async function runHookWorker() {
+  try {
+    const e = JSON.parse(process.env.BESTVIBER_HOOK_EVENT || '{}')
+    const event = trackerEvent(e)
+    if (!event || !(await token())) return
+    await withLock(async () => {
+      const state = await readState()
+      const project = detectProject(e.cwd || process.cwd())
+      const open =
+        event === 'reply'
+          ? state.sessionId
+            ? { id: state.sessionId, status: 'active', project: state.project }
+            : null
+          : await call('get_active_session')
+      const result = decide({ state, open, event, now: new Date(), project })
+      const next = { ...result.state }
+      for (const c of result.calls) {
+        const res = await call(c.name, c.input)
+        if (c.name === 'start_focus_session') next.sessionId = res?.id ?? null
+      }
+      await writeState(next)
+    })
+  } catch (err) {
+    await log(String(/** @type {Error} */ (err)?.stack ?? err))
+  }
+}
+
+function detectProject(/** @type {string} */ cwd) {
+  const git = (/** @type {string[]} */ args) => {
+    try {
+      return (
+        execFileSync('git', ['-C', cwd, ...args], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 1500,
+        }).trim() || null
+      )
+    } catch {
+      return null
+    }
+  }
+  return projectName({
+    remote: git(['remote', 'get-url', 'origin']),
+    toplevel: git(['rev-parse', '--show-toplevel']),
+    cwd,
+  })
+}
+
+async function readState() {
+  try {
+    return {
+      ...EMPTY_STATE,
+      ...JSON.parse(await readFile(statePath(), 'utf8')),
+    }
+  } catch {
+    return EMPTY_STATE
+  }
+}
+
+async function writeState(/** @type {object} */ state) {
+  await mkdir(stateDir(), { recursive: true, mode: 0o700 })
+  await writeFile(statePath(), JSON.stringify(state) + '\n', { mode: 0o600 })
+}
+
+export async function clearTrackingState() {
+  await rm(statePath(), { force: true })
+}
+
+/** One worker at a time: a prompt and a reply can land together. */
+async function withLock(/** @type {() => Promise<void>} */ fn) {
+  await mkdir(stateDir(), { recursive: true, mode: 0o700 })
+  const deadline = Date.now() + 8000
+  for (;;) {
+    try {
+      await mkdir(lockPath())
+      break
+    } catch {
+      // A lock older than 30 s belongs to a worker that died.
+      const age = await stat(lockPath())
+        .then((s) => Date.now() - s.mtimeMs)
+        .catch(() => 0)
+      if (age > 30_000) await rm(lockPath(), { recursive: true, force: true })
+      else if (Date.now() > deadline) return
+      else await new Promise((r) => setTimeout(r, 150))
+    }
+  }
+  try {
+    await fn()
+  } finally {
+    await rm(lockPath(), { recursive: true, force: true })
+  }
+}
+
+async function log(/** @type {string} */ line) {
+  try {
+    const size = await stat(logPath())
+      .then((s) => s.size)
+      .catch(() => 0)
+    if (size > 100_000) await rm(logPath(), { force: true })
+    await appendFile(logPath(), `${new Date().toISOString()} ${line}\n`)
+  } catch {
+    // Nowhere left to report to.
+  }
+}
+
+// ───── installing into Claude Code ─────
+
+const claudeDir = () =>
+  process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')
+const settingsPath = () => join(claudeDir(), 'settings.json')
+
+/** Whether Claude Code is set up on this machine. */
+export const hasClaudeCode = () => existsSync(claudeDir())
+
+/** The command Claude Code runs, with an absolute path (hooks may not share the shell's PATH). */
+function hookCommand() {
+  const q = (/** @type {string} */ s) => `"${s.replace(/(["\\$`])/g, '\\$1')}"`
+  let onPath = null
+  try {
+    onPath = execFileSync('sh', ['-c', 'command -v bestviber'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    // Not on PATH (for example run through pnpm dlx).
+  }
+  return onPath ? `${q(onPath)} hook` : `${q(process.execPath)} ${q(BIN)} hook`
+}
+
+const isOurs = (/** @type {any} */ h) =>
+  typeof h?.command === 'string' &&
+  /bestviber(\.mjs)?"?\s+hook$/.test(h.command)
+
+/** Remove our hook entries from every event, keeping everything else. */
+function withoutOurs(/** @type {Record<string, any>} */ hooks) {
+  /** @type {Record<string, any>} */
+  const cleaned = {}
+  for (const [event, groups] of Object.entries(hooks ?? {})) {
+    if (!Array.isArray(groups)) {
+      cleaned[event] = groups
+      continue
+    }
+    const kept = groups
+      .map((g) => ({
+        ...g,
+        hooks: Array.isArray(g?.hooks)
+          ? g.hooks.filter((h) => !isOurs(h))
+          : g?.hooks,
+      }))
+      .filter((g) => !Array.isArray(g.hooks) || g.hooks.length > 0)
+    if (kept.length) cleaned[event] = kept
+  }
+  return cleaned
+}
+
+async function readSettings() {
+  try {
+    return JSON.parse(await readFile(settingsPath(), 'utf8'))
+  } catch (err) {
+    if (/** @type {any} */ (err).code === 'ENOENT') return {}
+    throw new Error(
+      `Could not read ${settingsPath()} (${/** @type {Error} */ (err).message}). Left it unchanged.`,
+    )
+  }
+}
+
+async function writeSettings(/** @type {object} */ settings) {
+  const path = settingsPath()
+  await mkdir(dirname(path), { recursive: true })
+  if (existsSync(path) && !existsSync(`${path}.bestviber-backup`))
+    await copyFile(path, `${path}.bestviber-backup`)
+  const tmp = `${path}.bestviber-tmp`
+  await writeFile(tmp, JSON.stringify(settings, null, 2) + '\n')
+  await rename(tmp, path)
+}
+
+export async function installHooks() {
+  const settings = await readSettings()
+  const command = hookCommand()
+  const entry = { type: 'command', command, timeout: 10 }
+  const hooks = withoutOurs(settings.hooks)
+  /** @type {Array<[string, string | undefined]>} */
+  const events = [
+    ['SessionStart', undefined],
+    ['UserPromptSubmit', undefined],
+    ['Stop', undefined],
+    ['SessionEnd', 'prompt_input_exit|logout|other'],
+  ]
+  for (const [event, matcher] of events)
+    hooks[event] = [
+      ...(hooks[event] ?? []),
+      matcher ? { matcher, hooks: [entry] } : { hooks: [entry] },
+    ]
+  await writeSettings({ ...settings, hooks })
+  return { settings: settingsPath(), command }
+}
+
+export async function uninstallHooks() {
+  if (!existsSync(settingsPath())) return false
+  const settings = await readSettings()
+  const hooks = withoutOurs(settings.hooks)
+  const changed = JSON.stringify(hooks) !== JSON.stringify(settings.hooks ?? {})
+  if (!changed) return false
+  const next = { ...settings, hooks }
+  if (Object.keys(hooks).length === 0) delete next.hooks
+  await writeSettings(next)
+  return true
+}
+
+export async function hooksInstalled() {
+  try {
+    const hooks = (await readSettings()).hooks ?? {}
+    return Object.values(hooks).some(
+      (groups) =>
+        Array.isArray(groups) && groups.some((g) => g?.hooks?.some?.(isOurs)),
+    )
+  } catch {
+    return false
+  }
+}
+
+export const __test = { withoutOurs, isOurs, trackerEvent }

package/src/hooks.test.mjs

@@ -0,0 +1,101 @@
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, test } from 'vite-plus/test'
+import {
+  __test,
+  hooksInstalled,
+  installHooks,
+  uninstallHooks,
+} from './hooks.mjs'
+
+const { trackerEvent } = __test
+
+describe('which Claude Code events count', () => {
+  test.each([
+    [{ hook_event_name: 'SessionStart', source: 'startup' }, 'start'],
+    [{ hook_event_name: 'UserPromptSubmit', prompt: 'hi' }, 'prompt'],
+    [{ hook_event_name: 'Stop' }, 'reply'],
+    [{ hook_event_name: 'SessionEnd', reason: 'prompt_input_exit' }, 'end'],
+    [{ hook_event_name: 'SessionEnd', reason: 'logout' }, 'end'],
+    // /clear and /resume end a session id but not the work
+    [{ hook_event_name: 'SessionEnd', reason: 'clear' }, null],
+    [{ hook_event_name: 'SessionEnd', reason: 'resume' }, null],
+    [{ hook_event_name: 'PreToolUse' }, null],
+  ])('%j', (event, expected) => {
+    expect(trackerEvent(event)).toBe(expected)
+  })
+})
+
+describe('installing into ~/.claude/settings.json', () => {
+  let dir = ''
+  const saved = process.env.CLAUDE_CONFIG_DIR
+  const settings = async () =>
+    JSON.parse(await readFile(join(dir, 'settings.json'), 'utf8'))
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'bv-claude-'))
+    process.env.CLAUDE_CONFIG_DIR = dir
+  })
+  afterEach(() => {
+    if (saved === undefined) delete process.env.CLAUDE_CONFIG_DIR
+    else process.env.CLAUDE_CONFIG_DIR = saved
+  })
+
+  const theirs = {
+    theme: 'dark',
+    hooks: {
+      Stop: [{ hooks: [{ type: 'command', command: 'notify-send done' }] }],
+      PreToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [{ type: 'command', command: './guard.sh' }],
+        },
+      ],
+    },
+  }
+
+  test('adds our four hooks and keeps everything else', async () => {
+    await writeFile(join(dir, 'settings.json'), JSON.stringify(theirs))
+    await installHooks()
+    const s = await settings()
+    expect(s.theme).toBe('dark')
+    expect(s.hooks.PreToolUse).toEqual(theirs.hooks.PreToolUse)
+    expect(s.hooks.Stop[0]).toEqual(theirs.hooks.Stop[0])
+    for (const event of [
+      'SessionStart',
+      'UserPromptSubmit',
+      'Stop',
+      'SessionEnd',
+    ])
+      expect(JSON.stringify(s.hooks[event])).toMatch(/bestviber.*hook/)
+    expect(s.hooks.SessionEnd.at(-1).matcher).toBe(
+      'prompt_input_exit|logout|other',
+    )
+    expect(await hooksInstalled()).toBe(true)
+  })
+
+  test('installing twice does not duplicate', async () => {
+    await installHooks()
+    await installHooks()
+    const s = await settings()
+    expect(s.hooks.UserPromptSubmit).toHaveLength(1)
+  })
+
+  test('uninstall removes only ours', async () => {
+    await writeFile(join(dir, 'settings.json'), JSON.stringify(theirs))
+    await installHooks()
+    expect(await uninstallHooks()).toBe(true)
+    const s = await settings()
+    expect(s).toEqual(theirs)
+    expect(await hooksInstalled()).toBe(false)
+  })
+
+  test('a settings file that is not valid JSON is left alone', async () => {
+    await writeFile(join(dir, 'settings.json'), '{ not json')
+    await expect(installHooks()).rejects.toThrow(/Left it unchanged/)
+    expect(await readFile(join(dir, 'settings.json'), 'utf8')).toBe(
+      '{ not json',
+    )
+  })
+})

package/src/tracker.mjs

@@ -0,0 +1,108 @@
+// Automatic tracking for Claude Code: what to do when a hook fires.
+//
+// Pure: given the saved state, the session the server says is open, the
+// event and the time, return the API calls to make and the next state. The
+// hook runner (hooks.mjs) does the I/O; the tests drive this directly.
+//
+// Rules (agreed with the product owner):
+// - A prompt, or Claude Code starting, makes sure a session is running for
+//   the current project. A different project's session is closed first.
+// - Claude finishing a reply counts as activity; no API call is needed.
+// - Quiet under GRACE (reading a reply) still counts as focus.
+// - Quiet from GRACE up to FINISH is recorded as a pause in the same session.
+// - Quiet of FINISH or more ends the session when the quiet began; the next
+//   prompt starts a new one.
+// - A session someone started by hand (CLI, app, agent) is left alone.
+
+export const GRACE_MS = 2 * 60_000
+export const FINISH_MS = 10 * 60_000
+
+/**
+ * @typedef {{ sessionId: string | null, project: string | null, lastActivity: string | null }} TrackerState
+ * @typedef {{ id: string, status: string, project?: string | null } | null} OpenSession
+ * @typedef {'start' | 'prompt' | 'reply' | 'end'} TrackerEvent
+ * @typedef {{ name: string, input: Record<string, unknown> }} Call
+ */
+
+/** @type {TrackerState} */
+export const EMPTY_STATE = {
+  sessionId: null,
+  project: null,
+  lastActivity: null,
+}
+
+/**
+ * @param {{ state: TrackerState, open: OpenSession, event: TrackerEvent, now: Date, project: string }} input
+ * @returns {{ calls: Array<Call>, state: TrackerState }}
+ */
+export function decide({ state, open, event, now, project }) {
+  const nowIso = now.toISOString()
+  const last = state.lastActivity ? new Date(state.lastActivity) : null
+  const gap = last ? now.getTime() - last.getTime() : 0
+  const ours = open !== null && open.id === state.sessionId
+  /** When the work in the open session really stopped. */
+  const endedAt = last && gap >= GRACE_MS ? state.lastActivity : nowIso
+
+  // Someone else's session is open: stay out of its way.
+  if (open && !ours)
+    return {
+      calls: [],
+      state: { sessionId: null, project: null, lastActivity: nowIso },
+    }
+
+  if (event === 'reply')
+    return { calls: [], state: { ...state, lastActivity: nowIso } }
+
+  if (event === 'end') {
+    if (!ours) return { calls: [], state: EMPTY_STATE }
+    return {
+      calls: [{ name: 'finish_focus_session', input: { at: endedAt } }],
+      state: EMPTY_STATE,
+    }
+  }
+
+  // 'start' or 'prompt': make sure this project's session is running.
+  /** @type {Array<Call>} */
+  const calls = []
+  const start = { name: 'start_focus_session', input: { project } }
+
+  if (!ours) calls.push(start)
+  else if (open.project !== project || gap >= FINISH_MS) {
+    calls.push({ name: 'finish_focus_session', input: { at: endedAt } }, start)
+  } else if (gap >= GRACE_MS) {
+    calls.push(
+      { name: 'pause_focus_session', input: { at: state.lastActivity } },
+      { name: 'resume_focus_session', input: {} },
+    )
+  }
+
+  return {
+    calls,
+    // A new session's id comes back from start_focus_session; the runner
+    // fills it in.
+    state: {
+      sessionId: calls.includes(start) ? null : state.sessionId,
+      project,
+      lastActivity: nowIso,
+    },
+  }
+}
+
+/**
+ * The project for a working directory: "owner/repo" from the git remote,
+ * else the repository folder name, else the folder name.
+ *
+ * @param {{ remote: string | null, toplevel: string | null, cwd: string }} where
+ */
+export function projectName({ remote, toplevel, cwd }) {
+  if (remote) {
+    // git@github.com:owner/repo.git, https://host/owner/repo(.git), ssh://…
+    const m = remote
+      .trim()
+      .replace(/\.git$/, '')
+      .match(/[:/]([^/:]+\/[^/:]+)$/)
+    if (m?.[1]) return m[1]
+  }
+  const dir = (toplevel || cwd).replace(/\/+$/, '')
+  return dir.slice(dir.lastIndexOf('/') + 1) || dir
+}