bestviber 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# bestviber
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Focus timer and focus analytics for you and your AI agents.
+
+```sh
+npm install -g bestviber
+bestviber login          # approve a code in your browser
+bestviber start          # start a focus session
+bestviber stop --note "wrote the launch post"
+bestviber week           # this week: total, by day, by hour, by tag, vs last week
+bestviber insights       # peak hours, best weekday, streaks, trends
+```
+
+Every command takes `--json` for scripts and agents. `bestviber tools` lists
+every action the server offers and `bestviber run <action>` runs any of them,
+so new features work without updating the CLI.
+
+## Agents
+
+- `bestviber skill install` adds the bestviber skill for Claude Code and
+  other agents that read `~/.agents/skills`.
+- `bestviber mcp` prints how to connect any MCP client to
+  `https://www.bestviber.com/api/mcp`.
+
+Free. Same account as [bestviber.com](https://www.bestviber.com).

package/bin/bestviber.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { parse } from '../src/args.mjs'
+import { CliError } from '../src/client.mjs'
+import { commands } from '../src/commands.mjs'
+
+const pkg = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+)
+
+function help() {
+  const width = Math.max(...Object.keys(commands).map((c) => c.length))
+  const lines = Object.entries(commands).map(
+    ([name, c]) => `  ${name.padEnd(width)}  ${c.summary}`,
+  )
+  return `bestviber ${pkg.version}: focus timer and focus analytics for you and your agents
+
+Usage: bestviber <command> [options]
+
+${lines.join('\n')}
+
+Options:
+  --json     Print raw JSON (for scripts and agents)
+  --help     Show help for a command
+
+Start with \`bestviber login\`. Full docs: https://www.bestviber.com/llms.txt`
+}
+
+async function main() {
+  const [name, ...rest] = process.argv.slice(2)
+  if (!name || name === 'help' || name === '--help' || name === '-h') {
+    console.log(help())
+    return
+  }
+  if (name === '--version' || name === '-v') {
+    console.log(pkg.version)
+    return
+  }
+  const command = commands[name]
+  if (!command)
+    throw new CliError(`Unknown command "${name}". Run \`bestviber help\`.`)
+  const { flags, args } = parse(rest)
+  if (flags.help) {
+    console.log(
+      `${command.summary}\n\nUsage: bestviber ${command.usage ?? name}`,
+    )
+    return
+  }
+  const json = flags.json === true
+  delete flags.json
+  const result = await command.run({ flags, args, json })
+  if (result === undefined) return
+  console.log(
+    json && typeof result !== 'string'
+      ? JSON.stringify(result, null, 2)
+      : result,
+  )
+}
+
+main().catch((err) => {
+  if (err instanceof CliError) {
+    console.error(`bestviber: ${err.message}`)
+    process.exit(err.exitCode)
+  }
+  console.error(err)
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "bestviber",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Focus timer and focus analytics for you and your AI agents. Start, pause and finish sessions, and get daily, weekly and monthly stats from the terminal.",
+  "keywords": [
+    "focus",
+    "timer",
+    "pomodoro",
+    "deep-work",
+    "productivity",
+    "time-tracking",
+    "cli",
+    "ai-agent",
+    "mcp"
+  ],
+  "homepage": "https://www.bestviber.com",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "bestviber": "bin/bestviber.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
 }

package/src/args.mjs

@@ -0,0 +1,32 @@
+/**
+ * `--key value`, `--key=value`, `--flag`, `--no-flag` (sets both `flag:
+ * false` and `no-flag: true`); a repeated key becomes an array. Everything
+ * else is positional.
+ * @param {string[]} argv
+ */
+export function parse(argv) {
+  /** @type {Record<string, any>} */
+  const flags = {}
+  /** @type {string[]} */
+  const args = []
+  const set = (/** @type {string} */ key, /** @type {unknown} */ value) => {
+    flags[key] = key in flags ? [...[flags[key]].flat(), value] : value
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith('--')) {
+      args.push(a)
+      continue
+    }
+    const body = a.slice(2)
+    const eq = body.indexOf('=')
+    if (eq !== -1) set(body.slice(0, eq), body.slice(eq + 1))
+    else if (body.startsWith('no-')) {
+      flags[body.slice(3)] = false
+      flags[body] = true
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith('--'))
+      set(body, argv[++i])
+    else set(body, true)
+  }
+  return { flags, args }
+}

package/src/client.mjs

@@ -0,0 +1,136 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const DEFAULT_URL = 'https://www.bestviber.com'
+export const CLIENT_ID = 'bestviber-cli'
+
+export class CliError extends Error {
+  /** @param {string} message @param {number} [exitCode] */
+  constructor(message, exitCode = 1) {
+    super(message)
+    this.exitCode = exitCode
+  }
+}
+
+// ───── config ─────
+
+export function configPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  return join(base, 'bestviber', 'config.json')
+}
+
+/** @returns {Promise<{ token?: string, url?: string, email?: string }>} */
+export async function readConfig() {
+  try {
+    return JSON.parse(await readFile(configPath(), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+/** @param {{ token?: string, url?: string, email?: string }} config */
+export async function writeConfig(config) {
+  const path = configPath()
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  // The token is a bearer credential: owner-only.
+  await writeFile(path, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 })
+}
+
+export async function clearConfig() {
+  await rm(configPath(), { force: true })
+}
+
+export async function baseUrl() {
+  const config = await readConfig()
+  return (process.env.BESTVIBER_URL || config.url || DEFAULT_URL).replace(
+    /\/+$/,
+    '',
+  )
+}
+
+export async function token() {
+  return process.env.BESTVIBER_TOKEN || (await readConfig()).token
+}
+
+export function localTimeZone() {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone
+}
+
+// ───── http ─────
+
+/**
+ * @param {string} path
+ * @param {{ method?: string, body?: unknown, auth?: boolean }} [opts]
+ */
+export async function request(path, opts = {}) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Timezone': localTimeZone(),
+    'User-Agent': 'bestviber-cli',
+  }
+  if (opts.auth !== false) {
+    const t = await token()
+    if (!t) throw new CliError('Not signed in. Run `bestviber login` first.', 2)
+    headers.Authorization = `Bearer ${t}`
+  }
+  let res
+  try {
+    res = await fetch(`${await baseUrl()}${path}`, {
+      method: opts.method ?? (opts.body === undefined ? 'GET' : 'POST'),
+      headers,
+      body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    })
+  } catch (err) {
+    throw new CliError(
+      `Could not reach bestviber: ${/** @type {Error} */ (err).message}`,
+    )
+  }
+  const text = await res.text()
+  let data
+  try {
+    data = text ? JSON.parse(text) : null
+  } catch {
+    data = { error: text }
+  }
+  return { status: res.status, ok: res.ok, data }
+}
+
+/** Fetches the live action list; new server actions appear here. */
+export async function manifest() {
+  const res = await request('/api/v1/actions', { auth: false })
+  if (!res.ok)
+    throw new CliError(`Could not load actions (HTTP ${res.status}).`)
+  return /** @type {Array<{ name: string, title: string, description: string, inputSchema: any, readOnly: boolean, consequential: boolean }>} */ (
+    res.data.actions
+  )
+}
+
+/**
+ * Runs an action on the server and returns its result.
+ * @param {string} name @param {Record<string, unknown>} [input]
+ */
+export async function call(name, input = {}) {
+  const res = await request(`/api/v1/actions/${encodeURIComponent(name)}`, {
+    body: input,
+  })
+  if (res.status === 401)
+    throw new CliError(
+      'Not signed in, or the session expired. Run `bestviber login`.',
+      2,
+    )
+  if (!res.ok || !res.data?.ok) {
+    const issues = res.data?.issues
+      ? '\n' +
+        res.data.issues
+          .map(
+            (/** @type {any} */ i) =>
+              `  ${i.path?.join('.') || 'input'}: ${i.message}`,
+          )
+          .join('\n')
+      : ''
+    throw new CliError(`${res.data?.error ?? `HTTP ${res.status}`}${issues}`)
+  }
+  return res.data.result
+}

package/src/commands.mjs

@@ -0,0 +1,524 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import {
+  baseUrl,
+  call,
+  clearConfig,
+  CLIENT_ID,
+  CliError,
+  configPath,
+  localTimeZone,
+  manifest,
+  readConfig,
+  request,
+  token,
+  writeConfig,
+} from './client.mjs'
+import { clock, duration, elapsed, stats } from './format.mjs'
+
+/**
+ * @typedef {{ flags: Record<string, any>, args: string[], json: boolean }} Ctx
+ * @typedef {{
+ *   summary: string,
+ *   usage?: string,
+ *   actions: string[],
+ *   run: (ctx: Ctx) => Promise<unknown>,
+ * }} Command
+ */
+
+const sleep = (/** @type {number} */ ms) =>
+  new Promise((r) => setTimeout(r, ms))
+
+function openBrowser(/** @type {string} */ url) {
+  const cmd =
+    process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'cmd'
+        : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true })
+      .on('error', () => {})
+      .unref()
+  } catch {
+    // No browser; the URL is printed anyway.
+  }
+}
+
+/** Prints `human` normally, `data` as JSON with --json. */
+function out(
+  /** @type {Ctx} */ ctx,
+  /** @type {unknown} */ data,
+  /** @type {string} */ human,
+) {
+  return ctx.json ? data : human
+}
+
+async function tagIdsByName(/** @type {string[]} */ names) {
+  if (names.length === 0) return undefined
+  /** @type {Array<{id: string, name: string}>} */
+  const tags = await call('list_tags')
+  return names.map((name) => {
+    const t = tags.find((x) => x.name.toLowerCase() === name.toLowerCase())
+    if (!t)
+      throw new CliError(
+        `No tag "${name}". Tags: ${tags.map((x) => x.name).join(', ') || 'none'}. Create it with \`bestviber tags add ${name}\`.`,
+      )
+    return t.id
+  })
+}
+
+const asList = (/** @type {unknown} */ v) =>
+  v === undefined ? [] : Array.isArray(v) ? v : [v]
+
+/** @type {Record<string, Command>} */
+export const commands = {
+  // ───── account ─────
+  login: {
+    summary: 'Sign in by approving a code in your browser',
+    usage: 'login [--no-browser]',
+    actions: [],
+    async run(ctx) {
+      const start = await request('/api/auth/device/code', {
+        auth: false,
+        body: { client_id: CLIENT_ID },
+      })
+      if (!start.ok)
+        throw new CliError(
+          `Could not start sign-in: ${start.data?.error_description ?? start.status}`,
+        )
+      const d = start.data
+      const code = `${d.user_code.slice(0, 4)}-${d.user_code.slice(4)}`
+      process.stderr.write(
+        `\nOpen ${d.verification_uri_complete}\nand approve the code  ${code}\n\nWaiting for approval…`,
+      )
+      if (!ctx.flags['no-browser']) openBrowser(d.verification_uri_complete)
+
+      let interval = (d.interval ?? 5) * 1000
+      const deadline = Date.now() + d.expires_in * 1000
+      while (Date.now() < deadline) {
+        await sleep(interval)
+        const res = await request('/api/auth/device/token', {
+          auth: false,
+          body: {
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            device_code: d.device_code,
+            client_id: CLIENT_ID,
+          },
+        })
+        if (res.ok && res.data?.access_token) {
+          const t = res.data.access_token
+          const me = await fetch(`${await baseUrl()}/api/auth/get-session`, {
+            headers: { Authorization: `Bearer ${t}` },
+          }).then((r) => r.json())
+          await writeConfig({
+            ...(await readConfig()),
+            token: t,
+            email: me?.user?.email,
+          })
+          process.stderr.write(' approved.\n')
+          return out(
+            ctx,
+            { ok: true, email: me?.user?.email },
+            `Signed in as ${me?.user?.email ?? 'you'}.`,
+          )
+        }
+        const err = res.data?.error
+        if (err === 'authorization_pending') continue
+        if (err === 'slow_down') {
+          interval += 5000
+          continue
+        }
+        process.stderr.write('\n')
+        if (err === 'access_denied') throw new CliError('Sign-in was denied.')
+        if (err === 'expired_token')
+          throw new CliError('The code expired. Run `bestviber login` again.')
+        throw new CliError(
+          `Sign-in failed: ${res.data?.error_description ?? err ?? res.status}`,
+        )
+      }
+      throw new CliError('The code expired. Run `bestviber login` again.')
+    },
+  },
+
+  logout: {
+    summary: 'Sign out and forget the token on this machine',
+    actions: [],
+    async run(ctx) {
+      if (await token())
+        await request('/api/auth/sign-out', { body: {} }).catch(() => {})
+      await clearConfig()
+      return out(ctx, { ok: true }, 'Signed out.')
+    },
+  },
+
+  whoami: {
+    summary: 'Show the signed-in account',
+    actions: [],
+    async run(ctx) {
+      const res = await request('/api/auth/get-session')
+      const email = res.data?.user?.email
+      if (!email) throw new CliError('Not signed in. Run `bestviber login`.', 2)
+      return out(ctx, { email, server: await baseUrl() }, email)
+    },
+  },
+
+  token: {
+    summary: 'Print the API token (for MCP or scripts). Keep it secret.',
+    actions: [],
+    async run() {
+      const t = await token()
+      if (!t) throw new CliError('Not signed in. Run `bestviber login`.', 2)
+      return t
+    },
+  },
+
+  mcp: {
+    summary: 'Show how to connect an AI agent over MCP',
+    actions: [],
+    async run(ctx) {
+      const url = `${await baseUrl()}/api/mcp`
+      const config = {
+        mcpServers: {
+          bestviber: {
+            type: 'http',
+            url,
+            headers: {
+              Authorization: 'Bearer <run: bestviber token>',
+              'X-Timezone': localTimeZone(),
+            },
+          },
+        },
+      }
+      if (ctx.json) return config
+      return [
+        'Claude Code:',
+        `  claude mcp add --transport http bestviber ${url} \\`,
+        '    --header "Authorization: Bearer $(bestviber token)" \\',
+        `    --header "X-Timezone: ${localTimeZone()}"`,
+        '',
+        'Other clients (JSON config; paste the output of `bestviber token`):',
+        JSON.stringify(config, null, 2)
+          .split('\n')
+          .map((l) => `  ${l}`)
+          .join('\n'),
+      ].join('\n')
+    },
+  },
+
+  skill: {
+    summary: 'Install the bestviber skill for Claude Code and other agents',
+    usage: 'skill install [--dir <skills-folder>]',
+    actions: [],
+    async run(ctx) {
+      if (ctx.args[0] !== 'install')
+        throw new CliError('Usage: bestviber skill install [--dir <folder>]')
+      // ~/.claude/skills for Claude Code; ~/.agents/skills is the shared
+      // folder other agents read, when it exists.
+      const dirs = ctx.flags.dir
+        ? [String(ctx.flags.dir)]
+        : [
+            join(homedir(), '.claude', 'skills'),
+            ...(existsSync(join(homedir(), '.agents'))
+              ? [join(homedir(), '.agents', 'skills')]
+              : []),
+          ]
+      const files = await Promise.all(
+        ['SKILL.md', 'reference.md'].map(async (name) => {
+          const res = await fetch(`${await baseUrl()}/skill/${name}`)
+          if (!res.ok)
+            throw new CliError(
+              `Could not download ${name} (HTTP ${res.status}).`,
+            )
+          return { name, body: await res.text() }
+        }),
+      )
+      const written = []
+      for (const dir of dirs) {
+        const target = join(dir, 'bestviber')
+        await mkdir(target, { recursive: true })
+        for (const f of files) await writeFile(join(target, f.name), f.body)
+        written.push(target)
+      }
+      return out(
+        ctx,
+        { installed: written },
+        `Installed the bestviber skill to:\n${written.map((d) => `  ${d}`).join('\n')}\nRun this again any time to update it.`,
+      )
+    },
+  },
+
+  // ───── timer ─────
+  start: {
+    summary: 'Start a focus session',
+    usage: 'start [--tag <name>]... [--room <id>]',
+    actions: ['start_focus_session', 'list_tags'],
+    async run(ctx) {
+      const row = await call('start_focus_session', {
+        tagIds: await tagIdsByName(asList(ctx.flags.tag)),
+        roomId: ctx.flags.room,
+      })
+      return out(ctx, row, `Focus session started at ${clock(row.startedAt)}.`)
+    },
+  },
+
+  pause: {
+    summary: 'Pause the running session',
+    actions: ['pause_focus_session'],
+    async run(ctx) {
+      return out(ctx, await call('pause_focus_session'), 'Paused.')
+    },
+  },
+
+  resume: {
+    summary: 'Resume the paused session',
+    actions: ['resume_focus_session'],
+    async run(ctx) {
+      return out(ctx, await call('resume_focus_session'), 'Resumed.')
+    },
+  },
+
+  stop: {
+    summary: 'Finish the session and record it',
+    usage: 'stop [--note <text>]',
+    actions: ['finish_focus_session'],
+    async run(ctx) {
+      const res = await call('finish_focus_session', { notes: ctx.flags.note })
+      return out(ctx, res, `Recorded ${duration(res.durationMs)} of focus.`)
+    },
+  },
+
+  status: {
+    summary: 'Show the open session and today so far',
+    actions: ['get_active_session', 'get_focus_totals'],
+    async run(ctx) {
+      const [active, totals] = await Promise.all([
+        call('get_active_session'),
+        call('get_focus_totals'),
+      ])
+      if (ctx.json) return { active, totals }
+      const running = active ? elapsed(active) : 0
+      const lines = [
+        active
+          ? `${active.status === 'paused' ? 'Paused' : 'Focusing'}: ${duration(running)} (started ${clock(active.startedAt)})`
+          : 'No session running.',
+        `Today: ${duration(totals.today + running)}   last 7 days: ${duration(totals.week + running)}`,
+      ]
+      return lines.join('\n')
+    },
+  },
+
+  // ───── stats ─────
+  today: periodCommand('day', 'today', 'Stats for today'),
+  yesterday: periodCommand('day', 'yesterday', 'Stats for yesterday'),
+  week: periodCommand('week', 'today', 'Stats for this week (from Monday)'),
+  month: periodCommand('month', 'today', 'Stats for this month'),
+  year: periodCommand('year', 'today', 'Stats for this year'),
+
+  stats: {
+    summary: 'Stats for any period or range',
+    usage:
+      'stats [--period day|week|month|year] [--date <YYYY-MM-DD>] | [--from <date> --to <date>]',
+    actions: ['get_stats'],
+    async run(ctx) {
+      const s = await call('get_stats', {
+        period: ctx.flags.period,
+        date: ctx.flags.date,
+        from: ctx.flags.from,
+        to: ctx.flags.to,
+      })
+      return out(ctx, s, stats(s))
+    },
+  },
+
+  streak: {
+    summary: 'Current and longest streak of focus days',
+    actions: ['get_streaks'],
+    async run(ctx) {
+      const s = await call('get_streaks')
+      return out(
+        ctx,
+        s,
+        [
+          `Current streak: ${s.currentDays} day${s.currentDays === 1 ? '' : 's'}${s.currentDays && !s.focusedToday ? ' (focus today to keep it)' : ''}`,
+          `Longest: ${s.longestDays} day${s.longestDays === 1 ? '' : 's'}${s.longest ? ` (${s.longest.from} → ${s.longest.to})` : ''}`,
+          `Active days in total: ${s.totalActiveDays}`,
+        ].join('\n'),
+      )
+    },
+  },
+
+  insights: {
+    summary: 'Findings about when and how you focus',
+    actions: ['get_insights'],
+    async run(ctx) {
+      const r = await call('get_insights')
+      return out(
+        ctx,
+        r,
+        r.insights.map((/** @type {any} */ i) => `• ${i.text}`).join('\n'),
+      )
+    },
+  },
+
+  sessions: {
+    summary: 'List finished sessions for a day or range',
+    usage:
+      'sessions [--date today|yesterday|<YYYY-MM-DD>] | [--from <date> --to <date>]',
+    actions: ['list_sessions'],
+    async run(ctx) {
+      /** @type {any[]} */
+      const rows = await call('list_sessions', {
+        date: ctx.flags.date,
+        from: ctx.flags.from,
+        to: ctx.flags.to,
+      })
+      if (ctx.json) return rows
+      if (rows.length === 0) return 'No sessions.'
+      return rows
+        .map(
+          (s) =>
+            `${new Date(s.startedAt).toLocaleDateString()} ${clock(s.startedAt)}  ${duration(s.durationMs).padStart(7)}${s.notes ? `  ${s.notes}` : ''}`,
+        )
+        .join('\n')
+    },
+  },
+
+  // ───── tags & rooms ─────
+  tags: {
+    summary: 'List tags, or `tags add <name>` / `tags rm <name>`',
+    usage: 'tags [add <name> | rm <name>]',
+    actions: ['list_tags', 'create_tag', 'delete_tag'],
+    async run(ctx) {
+      const [sub, ...rest] = ctx.args
+      const name = rest.join(' ')
+      if (sub === 'add') {
+        if (!name) throw new CliError('Usage: bestviber tags add <name>')
+        return out(
+          ctx,
+          await call('create_tag', { name }),
+          `Added tag "${name}".`,
+        )
+      }
+      if (sub === 'rm' || sub === 'remove') {
+        const [id] = (await tagIdsByName([name])) ?? []
+        return out(
+          ctx,
+          await call('delete_tag', { id }),
+          `Removed tag "${name}".`,
+        )
+      }
+      if (sub) throw new CliError(`Unknown subcommand "tags ${sub}".`)
+      /** @type {any[]} */
+      const tags = await call('list_tags')
+      return out(
+        ctx,
+        tags,
+        tags.length ? tags.map((t) => t.name).join('\n') : 'No tags yet.',
+      )
+    },
+  },
+
+  rooms: {
+    summary: 'List your focus rooms',
+    actions: ['list_rooms'],
+    async run(ctx) {
+      /** @type {any[]} */
+      const rooms = await call('list_rooms')
+      return out(
+        ctx,
+        rooms,
+        rooms.length
+          ? rooms.map((r) => `${r.id}  ${r.name}`).join('\n')
+          : 'No rooms yet.',
+      )
+    },
+  },
+
+  // ───── everything else ─────
+  tools: {
+    summary: 'List every action the server offers (always up to date)',
+    actions: [],
+    async run(ctx) {
+      const list = await manifest()
+      if (ctx.json) return list
+      const width = Math.max(...list.map((a) => a.name.length))
+      return list
+        .map((a) => `${a.name.padEnd(width)}  ${a.title}`)
+        .join('\n')
+        .concat(
+          '\n\nRun one with: bestviber run <name> [--key value]... or --input <json>',
+        )
+    },
+  },
+
+  run: {
+    summary: 'Run any action by name',
+    usage:
+      'run <action> [--key value]... | run <action> --input \'{"json":true}\'',
+    actions: [],
+    async run(ctx) {
+      const [name] = ctx.args
+      if (!name)
+        throw new CliError(
+          'Usage: bestviber run <action>. See `bestviber tools`.',
+        )
+      const { input: raw, ...rest } = ctx.flags
+      let input = {}
+      if (raw) {
+        try {
+          input = JSON.parse(raw)
+        } catch {
+          throw new CliError('--input must be JSON.')
+        }
+      } else {
+        const action = (await manifest()).find((a) => a.name === name)
+        if (!action)
+          throw new CliError(
+            `Unknown action "${name}". See \`bestviber tools\`.`,
+          )
+        input = coerce(rest, action.inputSchema)
+      }
+      const result = await call(name, input)
+      return ctx.json ? result : JSON.stringify(result, null, 2)
+    },
+  },
+}
+
+/** Turns `--key value` strings into the types the JSON Schema asks for. */
+function coerce(
+  /** @type {Record<string, any>} */ flags,
+  /** @type {any} */ schema,
+) {
+  /** @type {Record<string, unknown>} */
+  const input = {}
+  for (const [key, value] of Object.entries(flags)) {
+    const type = schema?.properties?.[key]?.type
+    if (type === 'number' || type === 'integer') input[key] = Number(value)
+    else if (type === 'boolean') input[key] = value === true || value === 'true'
+    else if (type === 'array') input[key] = asList(value)
+    else input[key] = value
+  }
+  return input
+}
+
+function periodCommand(
+  /** @type {string} */ period,
+  /** @type {string} */ date,
+  /** @type {string} */ summary,
+) {
+  return /** @type {Command} */ ({
+    summary,
+    actions: ['get_stats'],
+    async run(ctx) {
+      const s = await call('get_stats', { period, date })
+      return out(ctx, s, stats(s))
+    },
+  })
+}
+
+export { configPath }

package/src/format.mjs

@@ -0,0 +1,87 @@
+// 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)}`)
+  }
+  return lines.join('\n')
+}