usage-history

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { DayRec, Days, HistoryMetric, HistoryRange, HistoryRestore, HistoryWeekDay } from '../types'
5import { addDay, asDays, asHeat, busiest, chartSvg, dayKey, dayLabel, EMPTY_DAY, fmtNum, heatSvg, lastDays, mergeDays, mergeHeat, slot, SLOTS, summarize, UNIT, weekOf, withUnknown } from './history'
6import { backupDaily, followTheme, jstDay, listBackups, mayWrite, readTheme, rememberVersion } from './style'
7
8type $ = EngineInterface
9
10const PANE = 'usage-history'
11const TITLE = '使い方の記録'
12const DESCRIPTION = '日ごとのターン数やトークンの記録をグラフで見る'
13
14const CLOSED: HistoryRestore = { days: null, pick: null }
15
16const DAYS = atom({ plugin: 'usage-history', key: 'days' } as const, {} as Days)
17const HEAT = atom({ plugin: 'usage-history', key: 'heat' } as const, [] as number[])
18const WEEK = atom({ plugin: 'usage-history', key: 'week' } as const, [] as HistoryWeekDay[])
19const RANGE = atom({ plugin: 'usage-history', key: 'range' } as const, 7 as HistoryRange)
20const METRIC = atom({ plugin: 'usage-history', key: 'metric' } as const, 'turns' as HistoryMetric)
21const RESTORE = atom({ plugin: 'usage-history', key: 'restore' } as const, CLOSED)
22const NOTE = atom({ plugin: 'usage-history', key: 'note' } as const, '')
23
24const OLD_VERSION = '新しい版が入りました。VS Code を開き直すまで記録は書きません'
25const DATE_RE = /^\d{4}-\d{2}-\d{2}$/
26
27// /history を自分で取れたか (取れなければ /usage-history にして、/history は横取りしない)
28let ownsMain = false
29
30/** 設定の backupDir (絶対パスでなければ空 = 控えない)。register で入れる */
31let backupDir = ''
32/** 控えを書いた (書かなくてよいと分かった) JST の日。同じ日は fs を読みに行かない */
33let backedDay = ''
34
35// 絶対パス (/x、\x、C:\x、C:/x) だけを受け付ける。相対パスや「C:」は今のフォルダから読まれてしまう
36const folderOption = (value: unknown) => {
37  const raw = String(value ?? '').trim()
38  return /^(?:[\\/]|[A-Za-z]:[\\/])/.test(raw) ? raw : ''
39}
40
41/** その日はじめての時だけ、store の生の値 (知らない欄ごと) を days と heat の 2 つの控えに書く */
42async function backup($: $, rawDays: unknown, rawHeat: unknown, now: number) {
43  if (backupDir === '' || rawDays === undefined || backedDay === jstDay(now)) return
44  try {
45    await backupDaily($, backupDir, 'days', rawDays, now)
46    if (rawHeat !== undefined) await backupDaily($, backupDir, 'heat', rawHeat, now)
47    backedDay = jstDay(now)
48  } catch {
49    // 書けなければ次のターンの終わりにもう一度
50  }
51}
52
53/** 日ごとの記録と、そこから作る直近 7 日 (他の mod が読む) を一緒に置き換える */
54async function putDays($: $, days: Days, now: number) {
55  await update($, DAYS, () => days)
56  await update($, WEEK, () => weekOf(days, now))
57}
58
59// まだ store に書いていない差分。メインのターンの終わりにまとめて 1 回書く
60let pendingDays: Days = {}
61let pendingHeat: number[] = []
62const bump = (key: string, d: Partial<DayRec>) => {
63  pendingDays[key] = addDay(pendingDays[key] ?? EMPTY_DAY, d)
64}
65
66// store への書き込みは 1 本ずつ
67let chain: Promise<unknown> = Promise.resolve()
68const serial = <T,>(f: () => Promise<T>) => {
69  const p = chain.then(f, f)
70  chain = p.catch(() => {})
71  return p
72}
73
74/** 書けなかった差分を、溜めている差分に戻す (次のターンの終わりにもう一度書く) */
75function putBack(days: Days, heat: number[]) {
76  for (const [k, d] of Object.entries(days)) bump(k, d)
77  if (heat.length > 0) pendingHeat = mergeHeat(pendingHeat, heat)
78}
79
80const BROKEN = '記録を読めなかったので、まだ書いていません。次のターンの終わりにもう一度読みます'
81const UNSAVED = '記録を書けませんでした。次のターンの終わりにもう一度書きます'
82
83/** store の key を読む。無ければ { v: undefined }、読めなければ (reject) undefined */
84const readKey = ($: $, key: 'days' | 'heat') =>
85  $.store.get(key).then(
86    v => ({ v }),
87    () => undefined,
88  )
89
90// 書く直前に読み直し、差分だけを足す (他のセッションが足した分を消さない)
91const flush = ($: $) =>
92  serial(async () => {
93    if (Object.keys(pendingDays).length === 0 && pendingHeat.length === 0) return
94    const now = await $.clock.now()
95    // 古い版のまま動いている時は書かない (新しい版の欄を消さないように。差分は溜めたまま)
96    if (!(await mayWrite($, now))) return
97    const gotDays = await readKey($, 'days')
98    const gotHeat = await readKey($, 'heat')
99    // 読めない時 (reject・形が違う) は書かない。差分は溜めたまま次に回す
100    const savedDays = gotDays === undefined ? undefined : gotDays.v === undefined ? {} : asDays(gotDays.v)
101    if (gotDays === undefined || savedDays === undefined) {
102      await update($, NOTE, () => BROKEN)
103      return
104    }
105    // heat は 168 枠でなければ上書きしない (heat の差分だけ溜めたまま)
106    const savedHeat = gotHeat === undefined ? undefined : gotHeat.v === undefined ? [] : asHeat(gotHeat.v)
107    const days = pendingDays
108    const heat = savedHeat === undefined ? [] : pendingHeat
109    pendingDays = {}
110    if (savedHeat !== undefined) pendingHeat = []
111    await backup($, gotDays.v, gotHeat?.v, now)
112    const nextDays = mergeDays(savedDays, days)
113    await putDays($, nextDays, now)
114    // この版の知らない欄 (新しい版が足した物) は読んだまま残す
115    const isDays = await $.store.set('days', withUnknown(gotDays.v, nextDays)).then(
116      () => true,
117      () => false,
118    )
119    let isHeat = true
120    if (savedHeat !== undefined && heat.length > 0) {
121      const nextHeat = mergeHeat(savedHeat, heat)
122      await update($, HEAT, () => nextHeat)
123      isHeat = await $.store.set('heat', nextHeat).then(
124        () => true,
125        () => false,
126      )
127    }
128    putBack(isDays ? {} : days, isHeat ? [] : heat)
129    const note = await read($, NOTE)
130    if (!isDays || !isHeat) await update($, NOTE, () => UNSAVED)
131    else if (savedHeat === undefined) await update($, NOTE, () => BROKEN)
132    else if (note === BROKEN || note === UNSAVED) await update($, NOTE, () => '')
133  })
134
135// ---------------------------------------------------------------- 控えから戻す
136
137async function openRestore($: $) {
138  // 日付はファイルから来るので、形の合う物だけ (画面の文字に制御文字を入れない)
139  const days = (await listBackups($, backupDir, 'days').catch(() => [])).map(b => b.day).filter(d => DATE_RE.test(d))
140  await update($, RESTORE, () => ({ days, pick: null }))
141}
142
143/** 控えの日の記録に戻す。store の days と heat を控えの値にして、画面の記録も読み直す */
144const restore = ($: $, day: string) =>
145  serial(async () => {
146    const now = await $.clock.now()
147    if (!(await mayWrite($, now))) {
148      await update($, NOTE, () => OLD_VERSION)
149      return
150    }
151    const b = (await listBackups($, backupDir, 'days').catch(() => [])).find(x => x.day === day)
152    const days = asDays(b?.value)
153    if (!b || !days) {
154      await update($, NOTE, () => 'この控えは読めない形でした')
155      return
156    }
157    const h = (await listBackups($, backupDir, 'heat').catch(() => [])).find(x => x.day === day)
158    const heat = asHeat(h?.value)
159    const isSaved = await (async () => {
160      await $.store.set('days', b.value)
161      if (heat) await $.store.set('heat', heat)
162    })().then(
163      () => true,
164      () => false,
165    )
166    if (!isSaved) {
167      await update($, NOTE, () => '記録を書けませんでした')
168      return
169    }
170    await putDays($, days, now)
171    if (heat) await update($, HEAT, () => heat)
172    await update($, RESTORE, () => CLOSED)
173    // heat の控えが無い (読めない) 日は、曜日と時間帯の記録を今のまま残す。混ざったことを言っておく
174    await update($, NOTE, () => (heat ? `${day} の記録に戻しました` : `${day} の日ごとの記録に戻しました (曜日と時間帯の記録は控えが無いので今のまま)`))
175  })
176
177const openPane = async ($: $) => {
178  await $.ui.open({ id: PANE, title: TITLE })
179  return { text: '使い方の記録を開きました。' }
180}
181
182export const register: Register = (on, options) => {
183  backupDir = folderOption(options.backupDir)
184  followTheme(on)
185
186  on('session.start', async ($, e, next) => {
187    const started = await next(e)
188    await rememberVersion($)
189    const got = await $.command.register({ name: 'history', description: DESCRIPTION }).catch(() => undefined)
190    ownsMain = got?.command === 'history'
191    if (!ownsMain) await $.command.register({ name: 'usage-history', description: DESCRIPTION }).catch(() => {})
192    await readTheme($)
193    const now = await $.clock.now()
194    const rawDays = await $.store.get('days').catch(() => undefined)
195    const rawHeat = await $.store.get('heat').catch(() => undefined)
196    await backup($, rawDays, rawHeat, now)
197    await putDays($, asDays(rawDays) ?? (await read($, DAYS)), now)
198    const heat = asHeat(rawHeat)
199    if (heat) await update($, HEAT, () => heat)
200    return started
201  })
202
203  on('session.end', async ($, e, next) => {
204    await flush($).catch(() => {})
205    return next(e)
206  })
207
208  // 数えるだけ。結果を待たず、落ちても呼び出しは止めない
209  on('tool.call', async ($, e, next) => {
210    bump(dayKey(await $.clock.now()), { tools: 1 })
211    return next(e)
212  }).catch(($, e, next) => next(e))
213
214  on('turn.complete', async ($, e, next) => {
215    const at = await $.clock.now()
216    const isMain = e.agentId === undefined
217    const isTurn = isMain && e.reason === 'answer'
218    const u = e.usage
219    bump(dayKey(at), {
220      turns: isTurn ? 1 : 0,
221      subTurns: isMain ? 0 : 1,
222      durationMs: isMain ? e.durationMs : 0,
223      inputTokens: u?.input_tokens ?? 0,
224      outputTokens: u?.output_tokens ?? 0,
225      cacheRead: u?.cache_read_input_tokens ?? 0,
226    })
227    if (isTurn) {
228      if (pendingHeat.length === 0) pendingHeat = new Array<number>(SLOTS).fill(0)
229      pendingHeat[slot(at)] = (pendingHeat[slot(at)] ?? 0) + 1
230    }
231    // サブエージェントの分は溜めておき、メインのターンの終わりに 1 回書く
232    if (isMain) void flush($).catch(() => {})
233    return next(e)
234  }).catch(($, e, next) => next(e))
235
236  on('command.run', { command: 'history' }, ($, e, next) => (ownsMain ? openPane($) : next(e))).catch(($, e, next) => next(e))
237  on('command.run', { command: 'usage-history' }, openPane)
238
239  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
240    const t = $.ui.resolve(e)
241    const { Box, Text, Button } = t
242    const Svg = e.surface !== 'terminal' && 'Svg' in t ? t.Svg : undefined
243    const now = await $.clock.now()
244    const days = await read($, DAYS)
245    const heat = await read($, HEAT)
246    const range = await read($, RANGE)
247    const metric = await read($, METRIC)
248    const restoring = await read($, RESTORE)
249    const note = await read($, NOTE)
250    const { total, top, value, average } = summarize(lastDays(days, now, range), metric)
251    const unit = UNIT[metric]
252    const peak = busiest(heat)
253    const line = `直近 ${range} 日 ${unit} 合計 ${fmtNum(value)} / 1 日平均 ${fmtNum(average)}`
254    const topLine = top ? `いちばん多かった日 ${dayLabel(top.key)} ${fmtNum(top.value)} ${unit}` : `直近 ${range} 日はまだ記録がありません`
255
256    return (
257      <Box flexDirection="column" gap={1}>
258        <Box flexDirection="row" flexWrap="wrap" columnGap={1}>
259          {([7, 30] as const).map(n => (
260            <Button key={`range-${n}`} dimColor={range !== n} label={`${n} 日`} variant={range === n ? 'primary' : undefined} onPress={() => update($, RANGE, () => n)} />
261          ))}
262          <Button
263            key="metric" dimColor
264            label={metric === 'turns' ? '出力トークンで見る' : 'ターン数で見る'}
265            onPress={() => update($, METRIC, m => (m === 'turns' ? 'output' : 'turns'))}
266          />
267        </Box>
268        {Svg ? (
269          <Box flexDirection="column" gap={1}>
270            <Svg key="chart" source={chartSvg(days, now, range, metric)} alt={line} />
271            <Svg key="heat" source={heatSvg(heat)} alt={peak ? `いちばん多い時間帯 ${peak.week}曜 ${peak.hour} 時台` : '曜日と時間帯のヒートマップ'} />
272          </Box>
273        ) : (
274          <Box flexDirection="column">
275            <Text bold>{line}</Text>
276            <Text dimColor>{`ツール ${fmtNum(total.tools)} 回 / サブエージェント ${fmtNum(total.subTurns)} ターン`}</Text>
277            <Text dimColor>{`入力 ${fmtNum(total.inputTokens)} / 出力 ${fmtNum(total.outputTokens)} / キャッシュ読み ${fmtNum(total.cacheRead)}`}</Text>
278            <Text>{topLine}</Text>
279            {peak && <Text>{`よく使う時間帯 ${peak.week}曜 ${peak.hour} 時台(${peak.turns} ターン)`}</Text>}
280          </Box>
281        )}
282        {restoring.days !== null && (
283          <Box key="restore-box" flexDirection="column" borderStyle="round" borderColor="yellow" paddingX={1} paddingY={1}>
284            <Text color="yellow" bold>
285              控えから戻す
286            </Text>
287            {backupDir === '' ? (
288              <Text dimColor>設定の backupDir を入れると控えが取れます</Text>
289            ) : restoring.days.length === 0 ? (
290              <Text dimColor>まだ控えがありません (毎日はじめて記録を書く時に取ります)</Text>
291            ) : restoring.pick === null ? (
292              restoring.days.map(d => (
293                <Button key={`restore:${d}`} label={`${d} の記録`} dimColor onPress={() => void update($, RESTORE, r => ({ ...r, pick: d }))} />
294              ))
295            ) : (
296              <Box key="restore-ask" flexDirection="column">
297                <Text>{`${restoring.pick} の記録に戻しますか。今の記録は上書きされます`}</Text>
298                <Button key="restore:yes" label="戻す" variant="primary" onPress={() => void restore($, restoring.pick ?? '')} />
299                <Button key="restore:no" label="やめる" dimColor onPress={() => void update($, RESTORE, r => ({ ...r, pick: null }))} />
300              </Box>
301            )}
302            <Button key="restore:close" label="閉じる" dimColor onPress={() => void update($, RESTORE, () => CLOSED)} />
303          </Box>
304        )}
305        {note !== '' && <Text color="yellow">{note}</Text>}
306        <Button key="restore" label="控えから戻す" dimColor onPress={() => void (restoring.days === null ? openRestore($) : update($, RESTORE, () => CLOSED))} />
307      </Box>
308    )
309  })
310}
311

1// 日ごとの使い方の純関数(日付・足し方・刈り込み・集計・SVG)
2import type { DayRec, Days, HistoryMetric, HistoryRange, HistoryWeekDay } from '../types'
3import { C, HEADER_H, W, countUp, esc, fadeIn, frame, growColumn, header, panel } from './style'
4
5/** 残す日数 */
6export const KEEP_DAYS = 400
7export const SLOTS = 7 * 24
8export const EMPTY_DAY: DayRec = { turns: 0, tools: 0, inputTokens: 0, outputTokens: 0, cacheRead: 0, durationMs: 0, subTurns: 0 }
9const FIELDS = Object.keys(EMPTY_DAY) as (keyof DayRec)[]
10const WEEK = ['日', '月', '火', '水', '木', '金', '土']
11/** ヒートマップの行(月曜始まり) */
12const ROWS = ['月', '火', '水', '木', '金', '土', '日']
13
14const jst = (ms: number) => new Date(ms + 9 * 3600_000)
15
16/** 日本時間の 'YYYY-MM-DD' */
17export const dayKey = (ms: number) => jst(ms).toISOString().slice(0, 10)
18
19/** 曜日(月=0)×時刻のます目の番号 */
20export function slot(ms: number) {
21  const d = jst(ms)
22  return ((d.getUTCDay() + 6) % 7) * 24 + d.getUTCHours()
23}
24
25/** 'YYYY-MM-DD' → '10/18(土)' */
26export function dayLabel(key: string, withWeek = true) {
27  const d = new Date(`${key}T00:00:00Z`)
28  return `${d.getUTCMonth() + 1}/${d.getUTCDate()}${withWeek ? `(${WEEK[d.getUTCDay()]})` : ''}`
29}
30
31export const addDay = (a: DayRec, b: Partial<DayRec>): DayRec =>
32  Object.fromEntries(FIELDS.map(k => [k, a[k] + (b[k] ?? 0)])) as DayRec
33
34const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0)
35
36/** store から読んだ値を確かめる。形の合わない日は捨てる。オブジェクトでなければ undefined */
37export function asDays(v: unknown): Days | undefined {
38  if (typeof v !== 'object' || v === null || Array.isArray(v)) return undefined
39  const out: Days = {}
40  for (const [k, rec] of Object.entries(v)) {
41    if (!/^\d{4}-\d{2}-\d{2}$/.test(k) || typeof rec !== 'object' || rec === null) continue
42    out[k] = Object.fromEntries(FIELDS.map(f => [f, num((rec as Record<string, unknown>)[f])])) as DayRec
43  }
44  return out
45}
46
47export const asHeat = (v: unknown): number[] | undefined =>
48  Array.isArray(v) && v.length === SLOTS ? v.map(num) : undefined
49
50const DATE_RE = /^\d{4}-\d{2}-\d{2}$/
51
52/**
53 * store に書く形。書く直前に読んだ raw のうち、この版の知らない欄 (日付でないキー・日ごとの知らない数) を残して days を重ねる。
54 * 古い版のまま動いているセッションが、新しい版の記録を消さないように。刈り込んだ古い日は戻さない
55 */
56export function withUnknown(raw: unknown, days: Days): Record<string, unknown> {
57  const o = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {}
58  const out: Record<string, unknown> = Object.fromEntries(Object.entries(o).filter(([k]) => !DATE_RE.test(k)))
59  for (const [k, d] of Object.entries(days)) {
60    const was = o[k]
61    const extra = typeof was === 'object' && was !== null && !Array.isArray(was) ? Object.entries(was).filter(([f]) => !(FIELDS as string[]).includes(f)) : []
62    out[k] = { ...Object.fromEntries(extra), ...d }
63  }
64  return out
65}
66
67/** 保存済みの日々に、このセッションで溜めた差分を足し、新しい KEEP_DAYS 日だけ残す */
68export function mergeDays(saved: Days, delta: Days): Days {
69  const out: Days = { ...saved }
70  for (const [k, d] of Object.entries(delta)) out[k] = addDay(out[k] ?? EMPTY_DAY, d)
71  return Object.fromEntries(
72    Object.keys(out)
73      .sort()
74      .slice(-KEEP_DAYS)
75      .map(k => [k, out[k] as DayRec]),
76  )
77}
78
79export const mergeHeat = (saved: readonly number[], delta: readonly number[]) => Array.from({ length: SLOTS }, (_, k) => (saved[k] ?? 0) + (delta[k] ?? 0))
80
81/** 今日で終わる n 日(古い順)。記録の無い日は 0 */
82export function lastDays(days: Days, now: number, n: number) {
83  return Array.from({ length: n }, (_, k) => {
84    const key = dayKey(now - (n - 1 - k) * 86_400_000)
85    return { key, rec: days[key] ?? EMPTY_DAY }
86  })
87}
88
89/** 直近 7 日の日ごとの数 (state の week。他の mod が読む形) */
90export const weekOf = (days: Days, now: number): HistoryWeekDay[] =>
91  lastDays(days, now, 7).map(({ key, rec }) => ({
92    day: key,
93    turns: rec.turns,
94    tools: rec.tools,
95    inputTokens: rec.inputTokens,
96    outputTokens: rec.outputTokens,
97    minutes: Math.round(rec.durationMs / 60_000),
98  }))
99
100export const metricOf =(rec: DayRec, metric: HistoryMetric) => (metric === 'turns' ? rec.turns : rec.outputTokens)
101
102export function summarize(list: readonly { key: string; rec: DayRec }[], metric: HistoryMetric) {
103  const total = list.reduce((a, d) => addDay(a, d.rec), EMPTY_DAY)
104  let top: { key: string; value: number } | undefined
105  for (const d of list) {
106    const value = metricOf(d.rec, metric)
107    if (value > 0 && (top === undefined || value >= top.value)) top = { key: d.key, value }
108  }
109  return { total, top, value: metricOf(total, metric), average: metricOf(total, metric) / Math.max(1, list.length) }
110}
111
112/** 1 万を超えたら「万」、1 億を超えたら「億」で 1 桁 */
113export function fmtNum(n: number) {
114  if (n >= 1e8) return `${(n / 1e8).toFixed(1)}億`
115  if (n >= 1e4) return `${(n / 1e4).toFixed(1)}万`
116  return Number.isInteger(n) || n >= 100 ? String(Math.round(n)) : n.toFixed(1)
117}
118
119export const UNIT: Record<HistoryMetric, string> = { turns: 'ターン', output: '出力トークン' }
120
121/** いちばん多い時間帯(ターン数)。記録が無ければ undefined */
122export function busiest(heat: readonly number[]) {
123  let best = -1
124  let max = 0
125  heat.forEach((v, k) => {
126    if (v > max) {
127      max = v
128      best = k
129    }
130  })
131  return best < 0 ? undefined : { week: ROWS[Math.floor(best / 24)] ?? '', hour: best % 24, turns: max }
132}
133
134/** 見出し・合計と 1 日平均・日ごとの縦棒・いちばん多かった日 */
135export function chartSvg(days: Days, now: number, range: HistoryRange, metric: HistoryMetric) {
136  const list = lastDays(days, now, range)
137  const { total, top, value, average } = summarize(list, metric)
138  const unit = UNIT[metric]
139  const parts: string[] = [header('日ごとの使い方', `直近 ${range} 日の${unit}`, C.green)]
140
141  // 合計と 1 日平均の 2 枚
142  const tileY = HEADER_H + 10
143  const tileW = (W - 14 * 2 - 10) / 2
144  for (const [k, [label, n]] of ([
145    ['合計', value],
146    ['1 日平均', average],
147  ] as const).entries()) {
148    const x = 14 + k * (tileW + 10)
149    parts.push(panel(x, tileY, tileW, 58))
150    parts.push(`<text x="${x + 12}" y="${tileY + 20}" font-size="12" fill="${C.dim}">${esc(`${label}(${unit})`)}</text>`)
151    parts.push(countUp(n, `x="${x + 12}" y="${tileY + 46}" font-size="22" font-weight="bold" fill="${C.text}"`, fmtNum, k * 0.1))
152  }
153  const subY = tileY + 58 + 18
154  parts.push(`<text x="14" y="${subY}" font-size="12" fill="${C.dim}">${esc(`ツール ${fmtNum(total.tools)} 回 / サブエージェント ${fmtNum(total.subTurns)} ターン`)}</text>`)
155  parts.push(`<text x="14" y="${subY + 16}" font-size="12" fill="${C.dim}">${esc(`入力 ${fmtNum(total.inputTokens)} / 出力 ${fmtNum(total.outputTokens)} / キャッシュ読み ${fmtNum(total.cacheRead)}`)}</text>`)
156
157  // 日ごとの縦棒。いちばん多かった日は黄色、今日は青、ほかは緑
158  const chartTop = subY + 34
159  const chartH = 110
160  const bottom = chartTop + chartH
161  const left = 14
162  const gap = range === 7 ? 10 : 3
163  const colW = (W - left * 2 - gap * (range - 1)) / range
164  const max = Math.max(1, ...list.map(d => metricOf(d.rec, metric)))
165  parts.push(`<line x1="${left}" y1="${bottom}" x2="${W - left}" y2="${bottom}" stroke="${C.line}"/>`)
166  list.forEach((d, k) => {
167    const v = metricOf(d.rec, metric)
168    const x = left + k * (colW + gap)
169    const h = v === 0 ? 0 : Math.max(2, ((chartH - 16) * v) / max)
170    const fill = top?.key === d.key ? C.yellow : k === list.length - 1 ? C.blue : C.green
171    parts.push(growColumn(x, bottom, colW, h, fill, k * (range === 7 ? 0.05 : 0.015)))
172    if (range === 7 && v > 0) parts.push(fadeIn(`<text x="${x + colW / 2}" y="${bottom - h - 4}" font-size="12" fill="${C.text}" text-anchor="middle">${esc(fmtNum(v))}</text>`, 0.5))
173    const isLabeled = range === 7 || (list.length - 1 - k) % 7 === 0
174    if (isLabeled) parts.push(`<text x="${x + colW / 2}" y="${bottom + 16}" font-size="12" fill="${C.dim}" text-anchor="middle">${esc(dayLabel(d.key, false))}</text>`)
175  })
176
177  const topY = bottom + 40
178  parts.push(
179    `<text x="14" y="${topY}" font-size="13" fill="${C.text}">${esc(
180      top ? `いちばん多かった日 ${dayLabel(top.key)} ${fmtNum(top.value)} ${unit}` : `直近 ${range} 日はまだ記録がありません`,
181    )}</text>`,
182  )
183  return frame(topY + 14, parts.join(''))
184}
185
186/** 曜日×時間帯のヒートマップ(濃さ = これまでのメインのターン数) */
187export function heatSvg(heat: readonly number[]) {
188  const left = 40
189  const top = 34
190  const cw = (W - left - 14) / 24
191  const ch = 18
192  const max = Math.max(1, ...heat)
193  const parts: string[] = [`<text x="14" y="22" font-size="13" font-weight="bold" fill="${C.text}">曜日と時間帯ごとのターン数(これまで)</text>`]
194  ROWS.forEach((label, r) => {
195    const y = top + r * ch
196    parts.push(`<text x="14" y="${y + 13}" font-size="12" fill="${C.dim}">${label}</text>`)
197    for (let h = 0; h < 24; h++) {
198      const v = heat[r * 24 + h] ?? 0
199      const x = left + h * cw
200      parts.push(
201        v === 0
202          ? `<rect x="${x.toFixed(1)}" y="${y}" width="${(cw - 2).toFixed(1)}" height="${ch - 2}" rx="2" fill="${C.face}"/>`
203          : `<rect x="${x.toFixed(1)}" y="${y}" width="${(cw - 2).toFixed(1)}" height="${ch - 2}" rx="2" fill="${C.green}" opacity="${(0.2 + (0.8 * v) / max).toFixed(2)}"/>`,
204      )
205    }
206  })
207  const labelY = top + 7 * ch + 14
208  for (const h of [0, 6, 12, 18, 23]) parts.push(`<text x="${(left + h * cw + cw / 2).toFixed(1)}" y="${labelY}" font-size="12" fill="${C.dim}" text-anchor="middle">${h}</text>`)
209  const b = busiest(heat)
210  parts.push(
211    `<text x="14" y="${labelY + 22}" font-size="12" fill="${C.dim}">${esc(b ? `いちばん多いのは ${b.week}曜 ${b.hour} 時台(${b.turns} ターン)` : 'まだ記録がありません')}</text>`,
212  )
213  return frame(labelY + 32, fadeIn(parts.join('')))
214}
215

1// 全 mod で共通の見た目(色・見出し・動き)と小物。
2// 正本は shared/style.ts。各 mod の hooks/style.ts はその写しなので、直すのは正本だけにして
3// `node tools/copy_shared.mts` で写す(`--check` で写しのずれを見つける)。
4import type { EngineInterface, On } from 'claude-code'
5
6export type Palette = {
7  bg: string
8  face: string
9  line: string
10  text: string
11  dim: string
12  weak: string
13  blue: string
14  green: string
15  yellow: string
16  red: string
17  purple: string
18  orange: string
19}
20
21/** GitHub Dark 系(docs/mod-guide.md の 7 節) */
22export const DARK: Palette = {
23  bg: '#0d1117',
24  face: '#161b22',
25  line: '#30363d',
26  text: '#c9d1d9',
27  dim: '#8b949e',
28  weak: '#8b949e',
29  blue: '#58a6ff',
30  green: '#3fb950',
31  yellow: '#d29922',
32  red: '#f85149',
33  purple: '#bc8cff',
34  orange: '#f78166',
35}
36
37/** GitHub Light 系 */
38export const LIGHT: Palette = {
39  bg: '#ffffff',
40  face: '#f6f8fa',
41  line: '#d0d7de',
42  text: '#1f2328',
43  dim: '#656d76',
44  weak: '#656d76',
45  blue: '#0969da',
46  green: '#1a7f37',
47  yellow: '#9a6700',
48  red: '#cf222e',
49  purple: '#8250df',
50  orange: '#bc4c00',
51}
52
53// ponytail: 今の色はモジュールの変数 1 個(この mod の中だけ)。SVG を作る関数は C.bg などを呼ぶたびに読むので、
54// 引数を増やさずにテーマが変わる。描く途中で切り替わることは無い(JS は 1 本で走る)
55/** 今の色。setTheme で中身が入れ替わる(同じ物を指し続けるので、import した C のままでよい) */
56export const C: Palette = { ...DARK }
57let isLightNow = false
58
59export const isLight = () => isLightNow
60
61/** /config の theme の値が明るい系か('light'・'light-daltonized'・'light-ansi' など) */
62export const isLightTheme = (value: unknown) => typeof value === 'string' && value.startsWith('light')
63
64export function setTheme(light: boolean) {
65  isLightNow = light
66  Object.assign(C, light ? LIGHT : DARK)
67}
68
69/**
70 * 今の /config の theme を読んで色を合わせる。mod 自身の session.start の中で呼ぶ
71 * (同じイベントに matcher 無しのフックを 2 つ置くと読み込みを拒まれるので、ここでは on しない)。
72 * VS Code の配色は mod から読めないので、Claude Code の theme が light 系の時だけ明るくなる
73 */
74export async function readTheme($: EngineInterface) {
75  const rows = await $.config.list().catch(() => [])
76  setTheme(isLightTheme(rows.find(r => r.key === 'theme')?.value))
77}
78
79/** /config で theme が変わったら色を替えて描き直す。register の中で 1 回呼ぶ */
80export function followTheme(on: On) {
81  on('config.set', { key: 'theme' }, async ($, e, next) => {
82    const r = await next(e)
83    if (r.deny === undefined) {
84      setTheme(isLightTheme(r.value))
85      $.ui.invalidate('ui.render')
86    }
87    return r
88  })
89}
90
91// ---- 小物 ----
92
93/** 外から来る文字列の制御文字を落とす。エンジンは制御文字を含む Text の子や alt を拒み、ペインが閉じる */
94export const clean = (s: string) => s.replace(/[\t\n\r]+/g, ' ').replace(/[\x00-\x1f\x7f-\x9f]/g, '').trim()
95
96/** SVG の文字に入れる前のエスケープ(制御文字も落とす) */
97export const esc = (s: string) =>
98  clean(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
99
100// ---- 時間帯と季節 (日本時間 JST = UTC+9 固定。動いている環境のタイムゾーンには頼らない) ----
101
102export type DayPart = '朝' | '昼' | '夕' | '夜'
103export type Season = '春' | '夏' | '秋' | '冬'
104
105const jstDate = (now: number) => new Date(now + 9 * 3_600_000)
106
107/** 時間帯。朝 5-10 時 / 昼 10-16 時 / 夕 16-19 時 / 夜 19-5 時 */
108export const dayPart = (now: number): DayPart => {
109  const h = jstDate(now).getUTCHours()
110  return h >= 5 && h < 10 ? '朝' : h >= 10 && h < 16 ? '昼' : h >= 16 && h < 19 ? '夕' : '夜'
111}
112
113/** 季節。春 3-5 月 / 夏 6-8 月 / 秋 9-11 月 / 冬 12-2 月 */
114export const season = (now: number): Season => {
115  const m = jstDate(now).getUTCMonth() + 1
116  return m >= 3 && m <= 5 ? '春' : m >= 6 && m <= 8 ? '夏' : m >= 9 && m <= 11 ? '秋' : '冬'
117}
118
119/** n 文字を超えたら … で切る */
120export const short = (s: string, n: number) => (s.length > n ? `${s.slice(0, Math.max(0, n - 1))}…` : s)
121
122// ---- 記録を守る(docs/mod-guide.md の 9 節) ----
123
124/** JST の YYYY-MM-DD */
125export const jstDay = (now: number) => jstDate(now).toISOString().slice(0, 10)
126
127export type Backup = { day: string; value: unknown }
128
129// ponytail: $.fs に消す手が無いので、曜日ごとの 7 つの枠を上書きして 7 日分だけ残す。もっと残すなら枠を日付にして process で消す
130const backupPath = (dir: string, plugin: string, key: string, wd: number) => `${dir.replace(/[\\/]+$/, '')}/${plugin}/${key}-${wd}.json`
131
132/**
133 * $.store の key の値を、その日はじめて呼ばれた時だけ dir に控える(曜日ごとの枠で 7 日分)。
134 * dir が空なら何もしない(公開の既定は空。入れた人が backupDir を設定する)。書いたら true
135 */
136export async function backupDaily($: EngineInterface, dir: string, key: string, value: unknown, now: number): Promise<boolean> {
137  if (!dir.trim() || value === undefined) return false
138  const day = jstDay(now)
139  const path = backupPath(dir, $.plugin.name, key, jstDate(now).getUTCDay())
140  // 壊れた枠(途中まで・null)は無いのと同じに扱って上書きする
141  const old = await $.fs.read(path).then(t => parseBackup(t)?.day ?? '', () => '')
142  if (old === day) return false
143  await $.fs.write(path, JSON.stringify({ day, value } satisfies Backup))
144  return true
145}
146
147/** 控えの 1 枠を読む。壊れていれば undefined */
148export function parseBackup(text: string): Backup | undefined {
149  try {
150    const b = JSON.parse(text) as Partial<Backup> | null
151    return b && typeof b.day === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(b.day) && b.value !== undefined ? (b as Backup) : undefined
152  } catch {
153    return undefined
154  }
155}
156
157/** 控えの一覧。新しい日から順。読めない枠・壊れた枠は飛ばす */
158export async function listBackups($: EngineInterface, dir: string, key: string): Promise<Backup[]> {
159  if (!dir.trim()) return []
160  const all = await Promise.all(
161    [0, 1, 2, 3, 4, 5, 6].map(wd =>
162      $.fs.read(backupPath(dir, $.plugin.name, key, wd)).then(parseBackup, () => undefined),
163    ),
164  )
165  return all.filter((b): b is Backup => b !== undefined).sort((a, b) => b.day.localeCompare(a.day))
166}
167
168let loadedPrint: string | undefined
169let staleAt = 0
170let isStaleNow = false
171let toldStale = false
172
173const normPath = (p: string) => p.replace(/[\\/]+/g, '/').replace(/\/$/, '').toLowerCase()
174
175/** FNV-1a 32bit。中身が変わったかを見るだけ */
176function fnv(s: string) {
177  let h = 0x811c9dc5
178  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)
179  return (h >>> 0).toString(16)
180}
181
182/**
183 * 今ディスクにある、この mod の指紋。plugin.json と hooks の .ts / .tsx の中身から作る
184 * (版の数字を上げずに中身だけ変えた時も変わる)。plugin.json が読めなければ undefined
185 */
186async function diskPrint($: EngineInterface): Promise<string | undefined> {
187  const root = $.plugin.root
188  let manifest: string | undefined
189  for (const p of [`${root}/.claude-plugin/plugin.json`, `${root}/plugin.json`]) {
190    manifest = await $.fs.read(p).then(t => t, () => undefined)
191    if (manifest !== undefined) break
192  }
193  if (manifest === undefined) return undefined
194  const names = await $.fs.list(`${root}/hooks`).then(
195    es => es.filter(e => e.kind === 'file' && /\.tsx?$/.test(e.name)).map(e => e.name).sort(),
196    () => [] as string[],
197  )
198  const parts = await Promise.all(names.map(n => $.fs.read(`${root}/hooks/${n}`).then(t => `${n}\n${t}`, () => n)))
199  return fnv([manifest, ...parts].join('\0'))
200}
201
202/**
203 * マーケットプレイスから入れた形(<plugins>/cache/<market>/<name>/<版>)なら、installed_plugins.json に
204 * 今入っている場所が自分と違うか。違えば新しい版が入っている。分からなければ false
205 */
206async function replacedInCache($: EngineInterface): Promise<boolean> {
207  const root = normPath($.plugin.root)
208  const at = root.lastIndexOf('/plugins/cache/')
209  if (at < 0) return false
210  const raw = await $.fs.read(`${$.plugin.root.slice(0, at + '/plugins'.length)}/installed_plugins.json`).then(t => t, () => '')
211  try {
212    const plugins = (JSON.parse(raw) as { plugins?: Record<string, { installPath?: unknown }[]> }).plugins ?? {}
213    const mine = Object.entries(plugins)
214      .filter(([k]) => k.startsWith(`${$.plugin.name}@`))
215      .flatMap(([, v]) => (Array.isArray(v) ? v : []))
216      .map(e => (typeof e.installPath === 'string' ? normPath(e.installPath) : ''))
217    return mine.length > 0 && !mine.includes(root)
218  } catch {
219    return false
220  }
221}
222
223/** 読み込んだ時の指紋を覚える。mod の session.start で 1 回呼ぶ */
224export async function rememberVersion($: EngineInterface) {
225  loadedPrint ??= await diskPrint($)
226}
227
228/**
229 * 新しい版が入ったのに、このセッションはまだ古い版で動いているか。
230 * フォルダから読ませている時は中身の指紋が読み込んだ時と違えば、マーケットプレイスから入れた時は
231 * 入っている場所が自分でなくなれば true。読み直すのは 60 秒に 1 回まで。分からない時は false
232 */
233export async function isStale($: EngineInterface, now: number): Promise<boolean> {
234  if (isStaleNow || now - staleAt < 60_000) return isStaleNow
235  staleAt = now
236  if (await replacedInCache($)) return (isStaleNow = true)
237  if (loadedPrint === undefined) return false
238  const p = await diskPrint($)
239  isStaleNow = p !== undefined && p !== loadedPrint
240  return isStaleNow
241}
242
243/**
244 * $.store に書いてよいか。古い版のままなら書かず、1 回だけトーストで開き直しを頼む
245 * (古い版は新しい版の欄を知らないので、書くと消してしまう)
246 */
247export async function mayWrite($: EngineInterface, now: number): Promise<boolean> {
248  if (!(await isStale($, now))) return true
249  if (!toldStale) {
250    toldStale = true
251    $.ui.toast(`${$.plugin.name}: 新しい版が入りました。VS Code を開き直すまで記録は書きません`)
252  }
253  return false
254}
255
256// ---- SVG の部品 ----
257
258export const W = 380
259export const HEADER_H = 44
260
261/** SVG 全体の枠。地を塗って body を入れる。幅は W にそろえる */
262export const frame = (h: number, body: string, w = W) =>
263  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" font-family="sans-serif">` +
264  `<rect width="${w}" height="${h}" rx="10" fill="${C.bg}"/>${body}</svg>`
265
266/** 面(カード)。角丸 8、線 1 */
267export const panel = (x: number, y: number, w: number, h: number, fill = C.face) =>
268  `<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="8" fill="${fill}" stroke="${C.line}"/>`
269
270/**
271 * 共通の見出し帯(高さ HEADER_H)。左に色の縦線、左に題、右に添え書き。
272 * 下の細い線が左から伸びる
273 */
274export function header(title: string, sub = '', accent = C.blue, y = 0, w = W) {
275  const pad = 14
276  return [
277    `<rect x="0" y="${y}" width="${w}" height="${HEADER_H}" rx="10" fill="${C.face}"/>`,
278    `<rect x="0" y="${y + 8}" width="4" height="${HEADER_H - 16}" rx="2" fill="${accent}"/>`,
279    `<text x="${pad}" y="${y + 28}" font-size="16" font-weight="bold" fill="${C.text}">${esc(title)}</text>`,
280    sub === '' ? '' : `<text x="${w - pad}" y="${y + 28}" font-size="12" fill="${C.dim}" text-anchor="end">${esc(sub)}</text>`,
281    growBar(pad, y + HEADER_H - 3, w - pad * 2, 2, accent, 0, 0.35),
282  ].join('')
283}
284
285/** 横に伸びる棒。幅 0 から w まで伸びて止まる(shots.mts は終わりの値で撮る) */
286export const growBar = (x: number, y: number, w: number, h: number, fill: string, delay = 0, opacity = 1) =>
287  `<rect x="${x}" y="${y}" width="${Math.max(0, w)}" height="${h}" rx="${Math.min(3, h / 2)}" fill="${fill}"${opacity === 1 ? '' : ` opacity="${opacity}"`}>` +
288  `<animate attributeName="width" from="0" to="${Math.max(0, w)}" begin="${delay}s" dur="0.6s" fill="freeze"/></rect>`
289
290/** 下から伸びる縦の棒(下端 bottom・高さ h) */
291export const growColumn = (x: number, bottom: number, w: number, h: number, fill: string, delay = 0) =>
292  `<rect x="${x}" y="${bottom - h}" width="${w}" height="${Math.max(0, h)}" rx="${Math.min(3, w / 2)}" fill="${fill}">` +
293  `<animate attributeName="y" from="${bottom}" to="${bottom - h}" begin="${delay}s" dur="0.6s" fill="freeze"/>` +
294  `<animate attributeName="height" from="0" to="${Math.max(0, h)}" begin="${delay}s" dur="0.6s" fill="freeze"/></rect>`
295
296/** ふわっと出る。中身は SVG の断片 */
297export const fadeIn = (body: string, delay = 0) =>
298  `<g opacity="1"><animate attributeName="opacity" from="0" to="1" begin="${delay}s" dur="0.4s" fill="freeze"/>${body}</g>`
299
300/**
301 * 0 から value まで数字が増えて止まる。コマ送りの文字を重ね、最後のコマだけが残る。
302 * attrs は <text> に付ける属性(x・y・font-size・fill など)。format で桁区切りや単位を付ける
303 */
304export function countUp(value: number, attrs: string, format: (n: number) => string = n => String(n), delay = 0) {
305  const STEPS = 8
306  const d = 0.08
307  const last = `<text ${attrs} opacity="0">${esc(format(value))}<animate attributeName="opacity" from="0" to="1" begin="${(delay + (STEPS - 1) * d).toFixed(2)}s" dur="0.01s" fill="freeze"/></text>`
308  if (!Number.isFinite(value) || value === 0) return `<text ${attrs}>${esc(format(value))}</text>`
309  const frames = Array.from({ length: STEPS - 1 }, (_, k) => {
310    const n = Number.isInteger(value) ? Math.round((value * k) / (STEPS - 1)) : (value * k) / (STEPS - 1)
311    return `<text ${attrs} opacity="0">${esc(format(n))}<animate attributeName="opacity" values="1;1" begin="${(delay + k * d).toFixed(2)}s" dur="${d}s"/></text>`
312  })
313  return frames.join('') + last
314}
315

1// usage-history の $.state の契約
2
3/** 1 日分(日本時間の日付ごと)の足し上げ */
4export type DayRec = {
5  /** メインのターン数(reason が answer で agentId が無い物) */
6  turns: number
7  /** tool.call の数(サブエージェントの分も含む) */
8  tools: number
9  /** 以下 4 つはメインとサブエージェントの合計 */
10  inputTokens: number
11  outputTokens: number
12  cacheRead: number
13  /** メインのターンの所要時間の合計 */
14  durationMs: number
15  /** サブエージェントのターン数 */
16  subTurns: number
17}
18
19/** 'YYYY-MM-DD'(日本時間) → その日の記録 */
20export type Days = Record<string, DayRec>
21
22export type HistoryRange = 7 | 30
23export type HistoryMetric = 'turns' | 'output'
24
25/** 直近 7 日の 1 日分(他の mod が読む形。week-card など) */
26export type HistoryWeekDay = {
27  /** 日本時間の 'YYYY-MM-DD' */
28  day: string
29  /** メインのターン数 */
30  turns: number
31  /** ツールの回数(サブエージェントの分も含む) */
32  tools: number
33  /** 入力・出力トークン(メインとサブエージェントの合計) */
34  inputTokens: number
35  outputTokens: number
36  /** メインのターンの所要時間の合計(分、四捨五入) */
37  minutes: number
38}
39
40/** 「控えから戻す」の欄。days が null なら閉じている。days は控えのある日 (新しい順)、pick は確かめ中の日 */
41export type HistoryRestore = { days: string[] | null; pick: string | null }
42
43declare module 'claude-code' {
44  interface PluginState {
45    'usage-history': {
46      /** 最大 400 日。$.store の 'days' にも残す */
47      days: Days
48      /** 曜日(月=0)×時刻(0-23 時)のメインのターン数、長さ 168。$.store の 'heat' にも残す */
49      heat: number[]
50      /**
51       * 今日で終わる直近 7 日(古い順、7 要素。記録の無い日は 0)。他の mod が読んでよい(書くのは usage-history)。
52       * セッションの始まりとメインのターンの終わりに置き換わる。usage-history が入っていない・読み込む前は undefined
53       */
54      week: HistoryWeekDay[]
55      range: HistoryRange
56      metric: HistoryMetric
57      restore: HistoryRestore
58      /** ボタンの結果などの一言。空なら出さない */
59      note: string
60    }
61  }
62}
63