phase-tracker

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { PhaseId } from '../types'
5import { formatBadge, nextPhase, parsePhaseArgs } from './phases'
6
7const isEnabledRef = atom({ plugin: 'phase-tracker', key: 'isEnabled' } as const, true)
8const currentRef = atom({ plugin: 'phase-tracker', key: 'current' } as const, 'idle' as PhaseId)
9const taskRef = atom({ plugin: 'phase-tracker', key: 'task' } as const, null as string | null)
10
11/** Store key of a project's phase: the store is global, so each folder gets its own. */
12export const phaseKey = (cwd: string) => `phase:${cwd.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()}`
13
14// Set at session.start (which re-fires on reload); saves go to the project the phase was loaded from, even after a /cd.
15// ponytail: keyed by the start folder, a session opened in a subfolder is a separate project; walk up to the git root if that bites.
16let projectKey = phaseKey('')
17
18// $.state is per session: phase and task are mirrored to the store and restored at session.start.
19async function savePhase($: EngineInterface) {
20  await $.store.set(projectKey, { current: await read($, currentRef), task: await read($, taskRef) })
21}
22
23export const register: Register = on => {
24  on('session.start', async ($, e, next) => {
25    const saved = await $.store.get('isEnabled').catch(() => undefined)
26    await update($, isEnabledRef, () => (typeof saved === 'boolean' ? saved : isEnabledRef.initial))
27    projectKey = phaseKey(e.cwd)
28    const phase = (await $.store.get(projectKey).catch(() => undefined)) as { current?: PhaseId; task?: string | null } | undefined
29    await update($, currentRef, () => phase?.current ?? 'idle')
30    await update($, taskRef, () => phase?.task ?? null)
31    await $.command.register({
32      name: 'fase',
33      description: 'Acompanha e gerencia a fase da tarefa atual (spec, test, code, verify, done, next, reset)',
34      argumentHint: '<fase|next|reset|on|off> [descricao]',
35    })
36    return next(e)
37  })
38
39  on('command.run', { command: 'fase' }, async ($, e) => {
40    const parsed = parsePhaseArgs(e.args)
41    if (parsed.error) return { text: parsed.error }
42
43    if (parsed.action === 'on' || parsed.action === 'off') {
44      const isEnabled = parsed.action === 'on'
45      await update($, isEnabledRef, () => isEnabled)
46      await $.store.set('isEnabled', isEnabled) // $.state is per session; the store survives a restart
47      return { text: `phase-tracker ${isEnabled ? 'ativado' : 'desativado'}.` }
48    }
49
50    if (parsed.action === 'reset') {
51      await update($, currentRef, () => 'idle')
52      await update($, taskRef, () => null)
53      await savePhase($)
54      return { text: 'Fase resetada para idle.' }
55    }
56
57    if (parsed.action === 'next') {
58      const curr = await read($, currentRef)
59      const next = nextPhase(curr)
60      await update($, currentRef, () => next)
61      await savePhase($)
62      const task = await read($, taskRef)
63      return { text: `Avançado para a fase: ${formatBadge(next, task)}` }
64    }
65
66    if (parsed.phase) {
67      await update($, currentRef, () => parsed.phase!)
68      await update($, taskRef, () => parsed.task ?? null)
69      await savePhase($)
70      return { text: `Fase definida: ${formatBadge(parsed.phase, parsed.task ?? null)}` }
71    }
72
73    const curr = await read($, currentRef)
74    const task = await read($, taskRef)
75    return { text: `Fase atual: ${formatBadge(curr, task) || 'idle'}` }
76  })
77
78  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
79    if (e.props.hasSurvey) return next(e)
80    const isEnabled = await read($, isEnabledRef)
81    if (!isEnabled) return next(e)
82
83    const current = await read($, currentRef)
84    const task = await read($, taskRef)
85    const badge = formatBadge(current, task)
86    if (!badge) return next(e)
87
88    const { Box, Text } = $.ui.resolve(e)
89    const below = await next(e)
90
91    const mine = (
92      <Box width={e.props.bodyColumns} flexDirection="row">
93        <Text color="#4aa3df" bold>
94          {badge}
95        </Text>
96      </Box>
97    )
98
99    return below.type === 'engine' ? mine : (
100      <Box flexDirection="column">
101        {below}
102        {mine}
103      </Box>
104    )
105  })
106}
107

1import type { PhaseId } from '../types'
2
3const ORDER: PhaseId[] = ['idle', 'spec', 'test', 'code', 'verify', 'done']
4
5export function nextPhase(current: PhaseId): PhaseId {
6  const idx = ORDER.indexOf(current)
7  if (idx === -1 || idx === ORDER.length - 1) return 'idle'
8  return ORDER[idx + 1]!
9}
10
11export type ParsedPhase = {
12  phase?: PhaseId
13  task?: string
14  action?: 'next' | 'reset' | 'off' | 'on'
15  error?: string
16}
17
18const PHASES: Record<string, PhaseId> = {
19  spec: 'spec',
20  test: 'test',
21  code: 'code',
22  verify: 'verify',
23  done: 'done',
24}
25
26export function parsePhaseArgs(input: string): ParsedPhase {
27  const trimmed = input.trim()
28  if (!trimmed) return { error: 'Fase ou ação desconhecida: comando vazio' }
29
30  const parts = trimmed.split(/\s+/)
31  const head = parts[0]!.toLowerCase()
32  const task = parts.slice(1).join(' ').trim() || undefined
33
34  if (head === 'next' || head === 'reset' || head === 'off' || head === 'on') {
35    return { action: head }
36  }
37
38  if (head in PHASES) {
39    return { phase: PHASES[head], task }
40  }
41
42  return { error: `Fase ou ação desconhecida: ${head}` }
43}
44
45const LABELS: Record<PhaseId, string> = {
46  idle: '',
47  spec: '[1/4 Spec]',
48  test: '[2/4 Test]',
49  code: '[3/4 Code]',
50  verify: '[4/4 Verify]',
51  done: '[✓ Concluído]',
52}
53
54export function formatBadge(phase: PhaseId, task: string | null): string {
55  if (phase === 'idle') return ''
56  const prefix = LABELS[phase]
57  return task ? `${prefix} ${task}` : prefix
58}
59

1export type PhaseId = 'idle' | 'spec' | 'test' | 'code' | 'verify' | 'done'
2
3// The validator wants each key named here, not behind an alias.
4declare module 'claude-code' {
5  interface PluginState {
6    'phase-tracker': {
7      isEnabled: boolean
8      current: PhaseId
9      task: string | null
10    }
11  }
12}
13