spec-board

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { SpecBoardItem, SpecBoardSnap } from '../types'
5import {
6  NEXT_ARGS,
7  PROGRESS_ARGS,
8  READ_ONLY,
9  WAITING_ARGS,
10  clean,
11  cleanBlock,
12  clockLabel,
13  cut,
14  headOf,
15  isAbsolute,
16  isPythonOk,
17  noticeOf,
18  paneSvg,
19  parseList,
20  parseNext,
21  showArgs,
22  sortWaiting,
23  summaryLines,
24  tagOf,
25} from './board'
26import { followTheme, readTheme } from './style'
27
28const PANE = 'spec-board'
29const TITLE = '仕様書'
30const DESCRIPTION = 'SpecStatus の確認待ち・途中・おすすめの仕様書をペインで見る (読むだけ)'
31/** 開いている間に読み直す間隔 */
32const POLL_MS = 5 * 60_000
33/** 一覧に出す上限。残りは「ほか N 件」 */
34const MAX_ROWS = 40
35/** 詳細に出す文字数の上限 */
36const MAX_DETAIL = 20_000
37
38const SNAP = atom({ plugin: 'spec-board', key: 'snap' } as const, { kind: 'idle' })
39const LOADING = atom({ plugin: 'spec-board', key: 'isLoading' } as const, false)
40const DETAIL = atom({ plugin: 'spec-board', key: 'detail' } as const, { kind: 'none' })
41
42type $ = EngineInterface
43
44// 設定は register で userConfig から入れる
45const cfg = { python: '', script: '' }
46// ponytail: 主の名前を持てたかはモジュール変数。リロードでも session.start が来て決め直す
47let ownsMain = false
48// 読み込みの連番。遅れて返った古い結果で新しい結果を上書きしない
49let seq = 0
50let detailSeq = 0
51
52type Ran = { ok: true; stdout: string; stderr: string } | { ok: false; message: string; head: string }
53
54/** SpecStatus を読む物だけ呼ぶ。出力は日本語なので UTF-8 にさせる */
55async function ss($: $, args: string[]): Promise<Ran> {
56  if (!READ_ONLY.has(args[0] ?? '')) return { ok: false, message: `呼ばないコマンドです: ${args[0]}`, head: '' }
57  try {
58    const r = await $.process.run([cfg.python, cfg.script, ...args], {
59      env: { PYTHONIOENCODING: 'utf-8' },
60      timeoutMs: 120_000,
61    })
62    if (r.exitCode !== 0) return { ok: false, message: `終了コード ${r.exitCode}`, head: headOf(`${r.stdout}\n${r.stderr}`) }
63    return { ok: true, stdout: r.stdout, stderr: r.stderr }
64  } catch (err) {
65    return { ok: false, message: `起動できません: ${clean(err instanceof Error ? err.message : String(err))}`, head: '' }
66  }
67}
68
69const isConfigured = () => cfg.python !== '' && cfg.script !== ''
70
71async function load($: $) {
72  const my = ++seq
73  if (!isConfigured()) {
74    await update($, SNAP, () => ({ kind: 'unset' as const }))
75    return
76  }
77  await update($, LOADING, () => true)
78  const [w, p, n] = await Promise.all([ss($, WAITING_ARGS), ss($, PROGRESS_ARGS), ss($, NEXT_ARGS)])
79  let snap: SpecBoardSnap
80  const failed = (step: string, r: Ran): SpecBoardSnap | undefined =>
81    r.ok ? undefined : { kind: 'error', step, message: r.message, head: r.head }
82  snap = failed('list --waiting', w) ?? failed('list --state', p) ?? failed('next', n) ?? { kind: 'idle' }
83  if (w.ok && p.ok && n.ok) {
84    try {
85      snap = {
86        kind: 'ok',
87        waiting: sortWaiting(parseList(w.stdout)),
88        progress: parseList(p.stdout),
89        next: parseNext(n.stdout),
90        loadedAt: await $.clock.now(),
91        notice: noticeOf(w.stderr || p.stderr || n.stderr),
92      }
93    } catch (err) {
94      const message = `JSON として読めませんでした: ${clean(err instanceof Error ? err.message : String(err))}`
95      snap = { kind: 'error', step: 'list', message, head: headOf(w.stdout) }
96    }
97  }
98  if (my !== seq) return
99  await update($, SNAP, () => snap)
100  await update($, LOADING, () => false)
101}
102
103async function showDetail($: $, name: string) {
104  const my = ++detailSeq
105  await update($, DETAIL, () => ({ kind: 'loading' as const, name }))
106  const r = await ss($, showArgs(name))
107  if (my !== detailSeq) return
108  await update($, DETAIL, () =>
109    r.ok
110      ? { kind: 'ok' as const, name, text: cleanBlock(r.stdout).trim().slice(0, MAX_DETAIL) }
111      : { kind: 'error' as const, name, message: r.message, head: r.head },
112  )
113}
114
115const isOpen = async ($: $) => (await $.ui.panes().catch(() => [])).some(p => p.id === PANE)
116
117const openPane = async ($: $) => {
118  void load($).catch(() => {})
119  await $.ui.open({ id: PANE, title: TITLE })
120  return { text: '仕様書のペインを開きました。' }
121}
122
123export const register: Register = (on, options) => {
124  const python = String(options.pythonPath ?? '').trim()
125  const script = String(options.specstatusScript ?? '').trim()
126  // 空・相対パスは未設定と同じ。空を「今のフォルダ」と読まない
127  cfg.python = isPythonOk(python) ? python : ''
128  cfg.script = isAbsolute(script) ? script : ''
129
130  followTheme(on)
131  on('session.start', async ($, e, next) => {
132    const started = await next(e)
133    await readTheme($)
134    // /specs が拒まれたら /spec-board にする
135    const got = await $.command.register({ name: 'specs', description: DESCRIPTION }).catch(() => undefined)
136    ownsMain = got?.command === 'specs'
137    if (!ownsMain) await $.command.register({ name: 'spec-board', description: DESCRIPTION }).catch(() => {})
138    $.clock.every(POLL_MS, async () => {
139      if (await isOpen($)) await load($)
140    })
141    if (await isOpen($)) void load($).catch(() => {})
142    return started
143  })
144
145  // /specs を持てなかった時は、その名前の持ち主に回す
146  on('command.run', { command: 'specs' }, ($, e, next) => (ownsMain ? openPane($) : next(e))).catch(($, e, next) => next(e))
147  on('command.run', { command: 'spec-board' }, openPane)
148
149  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
150    const t = $.ui.resolve(e)
151    const { Box, Text, Button, Code } = t
152    // terminal の表にも Svg の名前があるので、画面の種類でも分ける
153    const Svg = e.surface !== 'terminal' && 'Svg' in t ? t.Svg : undefined
154    const snap = await read($, SNAP)
155    const isLoading = await read($, LOADING)
156    const detail = await read($, DETAIL)
157    const lines = summaryLines(snap)
158
159    const section = (key: string, title: string, items: SpecBoardItem[], empty: string) => (
160      <Box key={key} flexDirection="column">
161        <Text bold>{`${title} ${items.length} 件`}</Text>
162        {items.length === 0 && <Text dimColor>{empty}</Text>}
163        {items.slice(0, MAX_ROWS).map((i, n) => (
164          <Box key={`${key}-${n}`} flexDirection="column">
165            <Button key={`${key}-b-${n}`} plain onPress={() => void showDetail($, i.name).catch(() => {})}>
166              {cut(i.name, 26)} <Text dimColor>{tagOf(i)}</Text>
167            </Button>
168            {i.note !== '' && <Text dimColor>{`  ${cut(i.note, 52)}`}</Text>}
169          </Box>
170        ))}
171        {items.length > MAX_ROWS && <Text dimColor>{`ほか ${items.length - MAX_ROWS} 件`}</Text>}
172      </Box>
173    )
174
175    return (
176      <Box flexDirection="column" gap={1}>
177        {Svg ? (
178          <Svg source={paneSvg(snap)} alt={lines.map(l => l.text).join('\n')} />
179        ) : (
180          <Box key="lines" flexDirection="column">
181            {lines.map(l => (
182              <Text color={l.color} dimColor={l.isDim} bold={l.isBold}>
183                {l.text}
184              </Text>
185            ))}
186          </Box>
187        )}
188        <Button key="reload" label={isLoading ? '読み込み中' : '読み直す'} variant="primary" onPress={() => void load($).catch(() => {})} />
189        {snap.kind === 'error' && snap.head !== '' && <Code key="err" source={snap.head} />}
190        {snap.kind === 'ok' && section('wait', '待ち', snap.waiting, '待っている仕様書はありません')}
191        {snap.kind === 'ok' && section('prog', '途中', snap.progress, '途中の仕様書はありません')}
192        {snap.kind === 'ok' && (
193          <Box key="next" flexDirection="column">
194            <Text bold>{`おすすめ ${snap.next.length} 件`}</Text>
195            {snap.next.length === 0 && <Text dimColor>おすすめはありません</Text>}
196            {snap.next.map((r, n) => (
197              <Box key={`next-${n}`} flexDirection="column">
198                <Button key={`next-b-${n}`} plain onPress={() => void showDetail($, r.name).catch(() => {})}>
199                  {`${r.score} ${cut(r.name, 24)}`} <Text dimColor>{r.state}</Text>
200                </Button>
201                {r.reasons !== '' && <Text dimColor>{`  ${cut(r.reasons, 52)}`}</Text>}
202              </Box>
203            ))}
204          </Box>
205        )}
206        {detail.kind !== 'none' && (
207          <Box key="detail" flexDirection="column">
208            <Text bold>{`詳細: ${cut(detail.name, 40)}`}</Text>
209            {detail.kind === 'loading' && <Text dimColor>読み込み中</Text>}
210            {detail.kind === 'ok' && <Code source={detail.text} />}
211            {detail.kind === 'error' && <Text color="red">{`show が失敗しました: ${detail.message}`}</Text>}
212            {detail.kind === 'error' && detail.head !== '' && <Code source={detail.head} />}
213            <Button key="close-detail" dimColor label="詳細を閉じる" onPress={() => void update($, DETAIL, () => ({ kind: 'none' as const }))} />
214          </Box>
215        )}
216        {snap.kind === 'ok' && (
217          <Text dimColor>{`読込 ${clockLabel(snap.loadedAt)}${snap.notice !== '' ? ` / ${snap.notice}` : ''}`}</Text>
218        )}
219      </Box>
220    )
221  })
222}
223

1// SpecStatus の出力を読み、ペインの SVG と terminal 用の行を組む。どれも純関数
2import type { SpecBoardItem, SpecBoardNext, SpecBoardSnap } from '../types'
3import { C, HEADER_H, countUp, frame, growBar, header } from './style'
4
5
6/** 呼んでよいサブコマンド。データを書く物 (mark・update・schedule・notify・build・gui・shortcut) は呼ばない */
7export const READ_ONLY = new Set(['list', 'next', 'show'])
8export const WAITING_ARGS = ['list', '--waiting', '--json']
9export const PROGRESS_ARGS = ['list', '--state', '着手済', '--state', '一部未実装', '--json']
10export const NEXT_ARGS = ['next']
11// 名前が - で始まっても引数として読まれないよう -- を挟む
12export const showArgs = (name: string) => ['show', '--', name]
13
14export const UNSET_HINT = '未設定。/config で spec-board の pythonPath (python の場所) と specstatusScript (specstatus.py の場所) に絶対パスを入れてください'
15
16/** 絶対パスか。C: のようなドライブだけ・相対パスは違う */
17export const isAbsolute = (p: string) => /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('/') || p.startsWith('\\\\')
18/** python の指定: 絶対パスか、区切りを含まないコマンド名 (python3 など。PATH から探す) */
19export const isPythonOk = (p: string) => isAbsolute(p) || /^[\w.-]+$/.test(p)
20
21const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g
22const CTRL = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g
23/** 1 行にする: 制御文字を落とし、タブ・改行は空白に */
24export const clean = (s: unknown) =>
25  String(s ?? '')
26    .replace(ANSI, '')
27    .replace(/[\t\r\n]+/g, ' ')
28    .replace(CTRL, '')
29    .trim()
30/** 複数行のまま制御文字を落とす (Code に出す物) */
31export const cleanBlock = (s: string) => s.replace(ANSI, '').replace(/\r\n?/g, '\n').replace(CTRL, '')
32
33/** 出力の頭 n 行 (失敗した時に見せる) */
34export function headOf(out: string, n = 12) {
35  return cleanBlock(out)
36    .split('\n')
37    .filter(l => l.trim() !== '')
38    .slice(0, n)
39    .join('\n')
40    .slice(0, 2000)
41}
42
43const wide = (ch: string) => /[⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/.test(ch)
44/** 全角 2・半角 1 の幅で max に収め、はみ出たら末尾を … にする */
45export function cut(s: string, max: number) {
46  if ([...s].reduce((n, ch) => n + (wide(ch) ? 2 : 1), 0) <= max) return s
47  let out = ''
48  let n = 1
49  for (const ch of s) {
50    n += wide(ch) ? 2 : 1
51    if (n > max) break
52    out += ch
53  }
54  return `${out}…`
55}
56
57const str = (v: unknown) => (typeof v === 'string' ? clean(v) : '')
58const int = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
59
60/** list --json の出力を読む。配列でなければ例外 */
61export function parseList(stdout: string): SpecBoardItem[] {
62  const data: unknown = JSON.parse(stdout)
63  if (!Array.isArray(data)) throw new Error('JSON の形が違います (配列ではありません)')
64  const items: SpecBoardItem[] = []
65  for (const x of data) {
66    if (typeof x !== 'object' || x === null) continue
67    const r = x as Record<string, unknown>
68    const name = str(r.name)
69    if (name === '') continue
70    const done = int(r.done_phase)
71    const last = int(r.last_phase)
72    const phase = last !== undefined ? `Phase ${done ?? 0}/${last}` : ''
73    const waiting = str(r.waiting)
74    items.push({ name, state: str(r.state), waiting: waiting === 'なし' ? '' : waiting, note: str(r.note), phase })
75  }
76  return items
77}
78
79/** 確認待ち (依頼者が動く物) を先に。ほかは元の順 */
80export const sortWaiting = (items: SpecBoardItem[]) =>
81  [...items].sort((a, b) => Number(b.waiting === '確認待ち') - Number(a.waiting === '確認待ち'))
82
83/** next の出力 (「 170  名前  (状態)  理由」の行) を読む。合わない行は飛ばす */
84export function parseNext(stdout: string): SpecBoardNext[] {
85  const out: SpecBoardNext[] = []
86  for (const line of cleanBlock(stdout).split('\n')) {
87    const m = /^\s*(-?\d+(?:\.\d+)?)\s{2,}(.+?)\s{2,}\((.+?)\)(?:\s{2,}(.*))?$/.exec(line)
88    if (!m) continue
89    out.push({ score: Number(m[1]), name: clean(m[2]), state: clean(m[3]), reasons: clean(m[4] ?? '') })
90  }
91  return out
92}
93
94/** 標準エラーの最初の行 (GitHub の回数の上限などの知らせ) */
95export const noticeOf = (stderr: string) => cut(clean(cleanBlock(stderr).split('\n').find(l => l.trim() !== '') ?? ''), 80)
96
97export const clockLabel = (ms: number) => {
98  const d = new Date(ms)
99  return [d.getHours(), d.getMinutes()].map(n => String(n).padStart(2, '0')).join(':')
100}
101
102const esc = (s: string) => clean(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
103
104// 見出しの右には時刻を入れない(読み直しのたびに source が変わると動きが最初からになる)
105/** 共通の見出し帯の下に body を置く(body は見出しを除いた座標で書く) */
106const svgDoc = (h: number, body: string, accent = C.purple) =>
107  frame(h + HEADER_H, header('仕様書', 'SpecStatus', accent) + `<g transform="translate(0 ${HEADER_H})">${body}</g>`)
108
109const count = (items: SpecBoardItem[], f: (i: SpecBoardItem) => boolean) => items.filter(f).length
110
111function tile(x: number, label: string, value: number, sub: string, color: string, isPulsing: boolean, delay: number) {
112  const pulse = isPulsing
113    ? `<circle cx="${x + 100}" cy="26" r="4" fill="${color}"><animate attributeName="opacity" values="1;0.2;1" dur="1.6s" repeatCount="indefinite"/></circle>`
114    : ''
115  return (
116    `<rect x="${x}" y="10" width="114" height="84" rx="8" fill="${C.face}" stroke="${C.line}"/>` +
117    `<rect x="${x}" y="10" width="4" height="84" rx="2" fill="${color}"/>` +
118    `<text x="${x + 14}" y="30" font-size="12" fill="${C.dim}">${label}</text>` +
119    pulse +
120    countUp(value, `x="${x + 14}" y="64" font-size="${String(value).length > 3 ? 22 : 28}" font-weight="bold" fill="${color}"`, String, delay) +
121    `<text x="${x + 14}" y="84" font-size="12" fill="${C.dim}">${esc(cut(sub, 15))}</text>`
122  )
123}
124
125/** 件数のタイル 3 枚と、おすすめの点数の棒 */
126function okSvg(snap: Extract<SpecBoardSnap, { kind: 'ok' }>) {
127  const ask = count(snap.waiting, i => i.waiting === '確認待ち')
128  const real = count(snap.waiting, i => i.waiting === '実物待ち')
129  const part = count(snap.progress, i => i.state === '一部未実装')
130  let s =
131    tile(8, '待ち', snap.waiting.length, `確認 ${ask}・実物 ${real}`, C.yellow, ask > 0, 0) +
132    tile(133, '途中', snap.progress.length, `着手 ${snap.progress.length - part}・一部 ${part}`, C.blue, false, 0.1) +
133    tile(258, '次のおすすめ', snap.next.length, snap.next[0]?.name ?? 'なし', C.green, false, 0.2)
134  const rows = snap.next.slice(0, 5)
135  if (rows.length === 0) return svgDoc(104, s, snap.waiting.length > 0 ? C.yellow : C.purple)
136  const y0 = 104
137  const h = 34 + rows.length * 34
138  s += `<rect x="8" y="${y0}" width="364" height="${h}" rx="8" fill="${C.face}" stroke="${C.line}"/>`
139  s += `<text x="20" y="${y0 + 22}" font-size="13" font-weight="bold" fill="${C.text}">おすすめ (点数の高い順)</text>`
140  const max = Math.max(1, ...rows.map(r => r.score))
141  rows.forEach((r, i) => {
142    const y = y0 + 34 + i * 34
143    const bw = Math.max(4, (Math.max(0, r.score) / max) * 250)
144    s += `<text x="20" y="${y + 12}" font-size="12" fill="${C.text}">${esc(cut(r.name, 34))}</text>`
145    s += `<text x="360" y="${y + 12}" font-size="12" fill="${C.dim}" text-anchor="end">${esc(cut(r.state, 10))}</text>`
146    s += `<rect x="20" y="${y + 18}" width="250" height="8" rx="4" fill="${C.bg}"/>`
147    s += growBar(20, y + 18, bw, 8, C.green, Number((0.2 + i * 0.08).toFixed(2)))
148    s += `<text x="280" y="${y + 26}" font-size="12" fill="${C.green}">${r.score}</text>`
149  })
150  return svgDoc(y0 + h + 8, s, snap.waiting.length > 0 ? C.yellow : C.purple)
151}
152
153/** 未設定・失敗・まだ読んでいない時の札 */
154function messageSvg(title: string, color: string, lines: string[]) {
155  const shown = lines.slice(0, 8)
156  let s = `<rect x="8" y="8" width="364" height="${52 + shown.length * 20}" rx="8" fill="${C.face}" stroke="${C.line}"/>`
157  s += `<rect x="8" y="8" width="4" height="${52 + shown.length * 20}" rx="2" fill="${color}"/>`
158  s += `<text x="24" y="38" font-size="18" font-weight="bold" fill="${color}">${esc(title)}</text>`
159  shown.forEach((l, i) => (s += `<text x="24" y="${64 + i * 20}" font-size="12" fill="${C.text}">${esc(cut(l, 54))}</text>`))
160  return svgDoc(68 + shown.length * 20, s, color)
161}
162
163/** 54 桁ずつに折る */
164function wrap(s: string, max = 54) {
165  const out: string[] = []
166  let line = ''
167  let n = 0
168  for (const ch of s) {
169    const w = wide(ch) ? 2 : 1
170    if (n + w > max) {
171      out.push(line)
172      line = ''
173      n = 0
174    }
175    line += ch
176    n += w
177  }
178  if (line !== '') out.push(line)
179  return out
180}
181
182export function paneSvg(snap: SpecBoardSnap) {
183  if (snap.kind === 'ok') return okSvg(snap)
184  if (snap.kind === 'unset') return messageSvg('未設定', C.yellow, wrap(UNSET_HINT.replace(/^未設定。/, '')))
185  if (snap.kind === 'error') return messageSvg(`${snap.step} が失敗しました`, C.red, wrap(snap.message))
186  return messageSvg('読み込み中', C.dim, ['SpecStatus を読んでいます'])
187}
188
189export type Line = { text: string; color?: string; isDim?: boolean; isBold?: boolean }
190
191/** terminal と Svg の alt に使う、上の部分の文 */
192export function summaryLines(snap: SpecBoardSnap): Line[] {
193  if (snap.kind === 'unset') return [{ text: UNSET_HINT, color: 'yellow' }]
194  if (snap.kind === 'error') return [{ text: `${snap.step} が失敗しました: ${snap.message}`, color: 'red' }]
195  if (snap.kind === 'idle') return [{ text: '読み込み中', isDim: true }]
196  const ask = count(snap.waiting, i => i.waiting === '確認待ち')
197  return [
198    { text: `待ち ${snap.waiting.length} (確認待ち ${ask}) / 途中 ${snap.progress.length} / おすすめ ${snap.next.length}`, isBold: true },
199    ...snap.next.slice(0, 5).map(r => ({ text: `${r.score} ${r.name} (${r.state})` })),
200  ]
201}
202
203/** 一覧の行の右に出す小さい文 */
204export const tagOf = (i: SpecBoardItem) => [i.state, i.waiting, i.phase].filter(Boolean).join('・')
205

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/** 仕様書 1 本 (list --json の 1 件から必要な所だけ) */
2export type SpecBoardItem = {
3  name: string
4  /** 実装完了 / 一部未実装 / 着手済 など */
5  state: string
6  /** 確認待ち / 実物待ち / なし など。無ければ空 */
7  waiting: string
8  /** メモ (制御文字を落とした物) */
9  note: string
10  /** 「Phase 2/3」の形。分からなければ空 */
11  phase: string
12}
13
14/** next の 1 行 */
15export type SpecBoardNext = { score: number; name: string; state: string; reasons: string }
16
17export type SpecBoardSnap =
18  | { kind: 'idle' }
19  /** pythonPath か specstatusScript が空・相対パス */
20  | { kind: 'unset' }
21  /** コマンドが起動できない・終了コードが 0 でない・JSON が読めない。head は出力の頭 */
22  | { kind: 'error'; step: string; message: string; head: string }
23  | {
24      kind: 'ok'
25      waiting: SpecBoardItem[]
26      progress: SpecBoardItem[]
27      next: SpecBoardNext[]
28      loadedAt: number
29      /** 標準エラーの 1 行目 (GitHub の回数の上限など)。無ければ空 */
30      notice: string
31    }
32
33export type SpecBoardDetail =
34  | { kind: 'none' }
35  | { kind: 'loading'; name: string }
36  | { kind: 'ok'; name: string; text: string }
37  | { kind: 'error'; name: string; message: string; head: string }
38
39declare module 'claude-code' {
40  interface PluginState {
41    'spec-board': {
42      snap: SpecBoardSnap
43      isLoading: boolean
44      detail: SpecBoardDetail
45    }
46  }
47}
48