path-band

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Head } from '../types'
5import { fit, gitdirOf, headOf, locationOf, parentOf, sepOf } from './where'
6
7const where = atom({ plugin: 'path-band', key: 'where' } as const, null)
8
9/** Blank cells at the line's left and right, as usage-band keeps, so the bands share their edges. */
10const LEFT = 2
11const RIGHT = 1
12/** A checkout made outside the session (another terminal) shows within this. */
13const TICK_MS = 30_000
14/** Inside the hook of the call that ran a `cd`, the session's directory still reads the old one; it is read again this much later. */
15const SETTLE_MS = 1_000
16
17// The folder the line was last worked out for, and the working tree found above it.
18let dirSeen: string | null = null
19let top: string | null = null
20let headPath: string | null = null
21// HEAD's modification time when last read, so an unchanged HEAD is not read again.
22let headSeen = -1
23let head: Head | null = null
24let home: string | null | undefined
25
26const statOf = ($: EngineInterface, path: string) => $.fs.stat(path).catch(() => null)
27
28// The working tree holding `dir`: the nearest folder above it with a `.git`, a folder in a
29// repository's own tree, a file naming the gitdir in a worktree.
30const findTop = async ($: EngineInterface, dir: string): Promise<{ top: string; gitdir: string } | null> => {
31  for (let d: string | null = dir; d !== null; d = parentOf(d as string)) {
32    const dotGit = `${d.replace(/[\\/]+$/, '')}${sepOf(d)}.git`
33    const st = await statOf($, dotGit)
34    if (st === null) continue
35    if (st.kind === 'dir') return { top: d, gitdir: dotGit }
36    const text = await $.fs.read(dotGit).catch(() => '')
37    const gitdir = gitdirOf(text, d)
38    return gitdir === null ? null : { top: d, gitdir }
39  }
40  return null
41}
42
43// Works the line out again when the folder or HEAD has changed since it was last drawn.
44const check = async ($: EngineInterface) => {
45  // The session's directory follows a shell `cd`, /cd and worktree moves; its root does not
46  // follow a shell `cd`, and CwdChanged does not fire for one (ADR-0081).
47  const dir = await $.session.cwd()
48  if (home === undefined) home = (await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME')) ?? null
49  if (dir !== dirSeen) {
50    dirSeen = dir
51    const found = await findTop($, dir)
52    top = found?.top ?? null
53    headPath = found === null ? null : `${found.gitdir}${sepOf(found.gitdir)}HEAD`
54    headSeen = -1
55    head = null
56  }
57  if (headPath !== null) {
58    const st = await statOf($, headPath)
59    const mtime = st?.mtimeMs ?? -1
60    if (mtime !== headSeen) {
61      headSeen = mtime
62      head = st === null ? null : headOf(await $.fs.read(headPath).catch(() => ''))
63    }
64  }
65  const next = { path: locationOf(dir, top, home), head }
66  await update($, where, w => (w !== null && w.path === next.path && w.head?.branch === head?.branch && w.head?.sha === head?.sha ? w : next))
67}
68
69export const register: Register = on => {
70  on('session.start', async ($, e, next) => {
71    const result = await next(e)
72    await check($)
73    $.clock.every(TICK_MS, () => void check($).catch(() => undefined))
74    return result
75  })
76
77  // /clear, /resume and /branch start $.state over without a session.start.
78  on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {
79    const result = await next(e)
80    dirSeen = null
81    await check($)
82    return result
83  }).catch(($, e, next) => next(e))
84
85  // A checkout, a worktree entered, a `cd`: each happens under a tool call.
86  on('tool.call', async ($, e, next) => {
87    const result = await next(e)
88    if (e.agentId === undefined) {
89      await check($)
90      $.clock.after(SETTLE_MS, () => void check($).catch(() => undefined))
91    }
92    return result
93  }).catch(($, e, next) => next(e))
94
95  // One line over whatever the other bands draw: the working location and its branch, two chips.
96  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
97    const below = await next(e)
98    const w = await read($, where)
99    if (w === null || e.props.hasSurvey) return below
100
101    const { Box, Text } = $.ui.resolve(e)
102    const shown = fit(w, e.props.bodyColumns - LEFT - RIGHT)
103    const isDetached = w.head !== null && w.head.branch === null
104    const line = (
105      <Box flexDirection="row" paddingLeft={LEFT} paddingRight={RIGHT}>
106        <Text wrap="truncate-end">
107          <Text backgroundColor="suggestion" color="inverseText">{` ${shown.path} `}</Text>
108          {shown.branch !== null && <Text> </Text>}
109          {shown.branch !== null && (
110            <Text backgroundColor="subtle" color={isDetached ? 'warning' : 'text'}>{` ${shown.branch} `}</Text>
111          )}
112          {isDetached && <Text dimColor> detached</Text>}
113        </Text>
114      </Box>
115    )
116    return (
117      <Box flexDirection="column">
118        {line}
119        {below}
120      </Box>
121    )
122  })
123}
124

1import type { Head, Where } from '../types'
2
3/** The longest a branch chip's name runs before it is cut (thegraph-panel's run-name limit). */
4export const BRANCH_MAX = 40
5
6// Hangul, CJK and full-width forms take two cells in a terminal.
7const isWide = (c: string) => /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/.test(c)
8
9export const cells = (s: string) => [...s].reduce((n, c) => n + (isWide(c) ? 2 : 1), 0)
10
11/** `s` cut at its end to `w` cells, the last of them `…`. */
12export const cutEnd = (s: string, w: number): string => {
13  if (cells(s) <= w) return s
14  if (w <= 0) return ''
15  let out = ''
16  let n = 0
17  for (const c of s) {
18    const k = isWide(c) ? 2 : 1
19    if (n + k > w - 1) break
20    out += c
21    n += k
22  }
23  return `${out}…`
24}
25
26/** `s` cut at its start to `w` cells, the first of them `…`: a path keeps the folder it ends in. */
27export const cutStart = (s: string, w: number): string => {
28  if (cells(s) <= w) return s
29  if (w <= 0) return ''
30  const cs = [...s]
31  let out = ''
32  let n = 0
33  for (let i = cs.length - 1; i >= 0; i--) {
34    const c = cs[i] ?? ''
35    const k = isWide(c) ? 2 : 1
36    if (n + k > w - 1) break
37    out = c + out
38    n += k
39  }
40  return `…${out}`
41}
42
43export const sepOf = (path: string) => (path.includes('\\') ? '\\' : '/')
44
45const trimSep = (path: string) => (/^([A-Za-z]:)?[\\/]$/.test(path) ? path : path.replace(/[\\/]+$/, ''))
46
47/** The folder holding `path`, or null at a root. */
48export const parentOf = (path: string): string | null => {
49  const p = trimSep(path)
50  const cut = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'))
51  if (cut < 0) return null
52  const parent = p.slice(0, cut) || p.slice(0, 1)
53  const root = /^[A-Za-z]:$/.test(parent) ? `${parent}${sepOf(p)}` : parent
54  return root === p ? null : root
55}
56
57export const baseName = (path: string) => trimSep(path).split(/[\\/]/).at(-1) ?? path
58
59const isAbsolute = (path: string) => /^([A-Za-z]:)?[\\/]/.test(path)
60
61// Windows paths compare without regard to case.
62const sameStart = (path: string, top: string) => {
63  const fold = (s: string) => (sepOf(s) === '\\' ? s.toLowerCase() : s)
64  const p = fold(trimSep(path))
65  const t = fold(trimSep(top))
66  return p === t || p.startsWith(t + sepOf(top)) || p.startsWith(`${t}/`)
67}
68
69/** Where a `.git` file's `gitdir:` line points, resolved against the folder holding it; null if it has none. */
70export const gitdirOf = (text: string, dir: string): string | null => {
71  const m = /^gitdir:\s*(.+?)\s*$/m.exec(text)
72  const target = m?.[1]
73  if (target === undefined) return null
74  return isAbsolute(target) ? target : `${trimSep(dir)}${sepOf(dir)}${target}`
75}
76
77/** What `HEAD` names: a branch, or a commit when detached; null when it is neither. */
78export const headOf = (text: string): Head | null => {
79  const t = text.trim()
80  const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(t)
81  if (ref?.[1] !== undefined) return { branch: ref[1], sha: null }
82  if (/^[0-9a-f]{40,64}$/.test(t)) return { branch: null, sha: t.slice(0, 7) }
83  return null
84}
85
86/**
87 * The working location (GLOSSARY): the working tree's folder name and the path
88 * beneath it; outside any working tree, the path with `home` shortened to `~`.
89 */
90export const locationOf = (dir: string, top: string | null, home: string | null): string => {
91  const slash = (s: string) => s.replace(/\\/g, '/')
92  if (top !== null && sameStart(dir, top)) {
93    const rel = slash(trimSep(dir).slice(trimSep(top).length)).replace(/^\/+/, '')
94    return rel === '' ? baseName(top) : `${baseName(top)}/${rel}`
95  }
96  if (home !== null && sameStart(dir, home)) {
97    const rel = slash(trimSep(dir).slice(trimSep(home).length)).replace(/^\/+/, '')
98    return rel === '' ? '~' : `~/${rel}`
99  }
100  return slash(dir)
101}
102
103/** The text in each chip at `width` cells: the branch whole up to BRANCH_MAX, the path cut at its start. */
104export const fit = (where: Where, width: number): { path: string; branch: string | null } => {
105  const head = where.head
106  const name = head === null ? null : cutEnd(head.branch ?? head.sha ?? '', BRANCH_MAX)
107  // A chip is its text with a space either side; a detached head adds ` detached` after its chip.
108  const branchCells = name === null ? 0 : 1 + cells(name) + 2 + (head?.branch === null ? cells(' detached') : 0)
109  const path = cutStart(where.path, Math.max(1, width - branchCells - 2))
110  return { path, branch: name }
111}
112

1/** What `HEAD` names: a branch, or the short SHA of a detached commit. */
2export type Head = { branch: string; sha: null } | { branch: null; sha: string }
3
4/** What the line draws: the working location, and its head when it is inside a working tree. */
5export type Where = { path: string; head: Head | null }
6
7declare module 'claude-code' {
8  interface PluginState {
9    'path-band': {
10      where: Where | null
11    }
12  }
13}
14