ado-link-bar

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Links, WorkItemDetails } from '../types'
5import { cut, findMentions, parseWorkItem, remember, textOf, transcriptTexts, workItemRef } from './links'
6
7const links = atom({ plugin: 'ado-link-bar', key: 'links' } as const, { prs: [], workItems: [] })
8const details = atom({ plugin: 'ado-link-bar', key: 'details' } as const, {} as WorkItemDetails)
9
10const EMPTY: Links = { prs: [], workItems: [] }
11// How much of a resumed transcript to read back: the recent end only.
12const TAIL_CHARS = 4 * 1024 * 1024
13// A transcript larger than this is not read back at all.
14const MAX_READ_BYTES = 64 * 1024 * 1024
15
16// Module variables start over on a reload; register sets them again from the settings.
17const cfg = { organization: '', prs: 5, workItems: 5 }
18// Work items whose title was already asked for, so each is fetched once.
19const requested = new Set<string>()
20
21// az.cmd only starts through a shell, so Windows goes through cmd. Piped, az writes JSON in the
22// console code page (cp932 on Japanese Windows), so PYTHONUTF8=1 pins it to UTF-8 for the titles.
23async function az($: EngineInterface, args: string[]) {
24  const isWindows = (await $.env.get('OS')) === 'Windows_NT'
25  const argv = isWindows ? ['cmd', '/d', '/c', 'set', 'PYTHONUTF8=1&&', 'az', ...args] : ['az', ...args]
26  return $.process.run(argv, { timeoutMs: 30_000 })
27}
28
29// Looks up a work item's title and state; on failure the link keeps its bare #id.
30async function fetchDetails($: EngineInterface, url: string) {
31  const ref = workItemRef(url)
32  if (!ref) return
33  const ran = await az($, ['boards', 'work-item', 'show', '--id', ref.id, '--org', ref.orgUrl, '--fields', 'System.Title,System.State', '--expand', 'none', '-o', 'json'])
34  const info = ran.exitCode === 0 ? parseWorkItem(ran.stdout) : null
35  if (!info) {
36    await $.ui.log(`ado-link-bar: no title for ${url}: ${ran.stderr.trim().split('\n')[0] ?? `az exited ${ran.exitCode}`}`, { to: 'debug' })
37    return
38  }
39  await update($, details, prev => ({ ...(prev ?? {}), [url]: info }))
40}
41
42// Asks for the titles not asked for yet. They arrive later; the row redraws when they land.
43function requestDetails($: EngineInterface, urls: readonly string[]) {
44  for (const url of urls) {
45    if (requested.has(url)) continue
46    requested.add(url)
47    fetchDetails($, url).catch(error => $.ui.log(`ado-link-bar: ${String(error)}`, { to: 'debug' }))
48  }
49}
50
51// Adds what one message mentions to the front of the lists.
52async function note($: EngineInterface, text: string) {
53  const found = findMentions(text, cfg.organization)
54  if (found.length === 0) return
55  await update($, links, prev => {
56    const cur = prev ?? EMPTY
57    return {
58      prs: remember(cur.prs, found.filter(f => f.kind === 'pr'), cfg.prs),
59      workItems: remember(cur.workItems, found.filter(f => f.kind === 'workItem'), cfg.workItems),
60    }
61  })
62  requestDetails($, found.filter(f => f.kind === 'workItem').map(f => f.url))
63}
64
65export const register: Register = (on, options) => {
66  if (options.enabled === false) return
67
68  cfg.organization = String(options.organization ?? '').trim()
69  cfg.prs = Math.max(0, Math.floor(Number(options.pullRequests ?? 5)))
70  cfg.workItems = Math.max(0, Math.floor(Number(options.workItems ?? 5)))
71
72  // The lists outlive a reload; their titles are asked for again.
73  on('session.start', async ($, e, next) => {
74    const started = await next(e)
75    const l = (await read($, links)) ?? EMPTY
76    const known = (await read($, details)) ?? {}
77    requestDetails($, l.workItems.map(m => m.url).filter(url => !(url in known)))
78    return started
79  })
80
81  // The person's prompts and the model's replies count as mentions; tool
82  // output, reminders and subagents' rows do not.
83  on('session.append', async ($, e, next) => {
84    const isMention =
85      e.agentId === undefined && !e.message.isMeta && (e.door === 'prompt' || e.door === 'response')
86    if (isMention) await note($, textOf(e.message.content))
87    return next(e)
88  })
89
90  // A resumed session's rows are loaded, not appended: read them back from
91  // the transcript. /clear starts the lists over.
92  on('classic.SessionStart', async ($, e, next) => {
93    const result = await next(e)
94    if (e.source === 'clear') {
95      await update($, links, () => EMPTY)
96    } else if (e.source === 'resume' || e.source === 'fork') {
97      const stat = await $.fs.stat(e.transcript_path).catch(() => null)
98      if (stat?.kind === 'file' && stat.size <= MAX_READ_BYTES) {
99        const text = await $.fs.read(e.transcript_path).catch(() => '')
100        if (typeof text === 'string') await note($, transcriptTexts(text.slice(-TAIL_CHARS)).join('\n'))
101      }
102    }
103    return result
104  })
105
106  // The band above the prompt: one row of links. The hint line under the
107  // prompt keeps a single row on the terminal, so a second row there never shows.
108  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
109    if (e.props.hasSurvey) return next(e)
110    const l = (await read($, links)) ?? EMPTY
111    if (l.prs.length === 0 && l.workItems.length === 0) return next(e)
112    const info = (await read($, details)) ?? {}
113
114    const { Box, Text, Link } = $.ui.resolve(e)
115    const group = (title: string, items: Links['prs']) => [
116      <Text dimColor>{`${title} `}</Text>,
117      ...items.flatMap((m, i) => {
118        const wi = info[m.url]
119        return [
120          ...(i > 0 ? [<Text dimColor>{' · '}</Text>] : []),
121          <Link href={m.url}>{m.label}</Link>,
122          ...(wi ? [<Text>{` ${cut(wi.title)}`}</Text>] : []),
123          ...(wi?.state ? [<Text dimColor>{` ${wi.state}`}</Text>] : []),
124        ]
125      }),
126    ]
127    const groups = [
128      ...(l.prs.length ? [group('PRs', l.prs)] : []),
129      ...(l.workItems.length ? [group('WIs', l.workItems)] : []),
130    ]
131    const row = groups.flatMap((g, i) => [...(i > 0 ? [<Text dimColor>{'   '}</Text>] : []), ...g])
132
133    return (
134      <Box flexDirection="row" paddingLeft={2}>
135        {row}
136      </Box>
137    )
138  })
139}
140

1import type { Mention, WorkItemInfo } from '../types'
2
3export type Kind = 'pr' | 'workItem'
4
5export type Found = Mention & { kind: Kind }
6
7// dev.azure.com/<org> or the older <org>.visualstudio.com
8const HOST = String.raw`https:\/\/(?:dev\.azure\.com\/([^\/\s]+)|([\w-]+)\.visualstudio\.com(?:\/DefaultCollection)?)`
9const PR = new RegExp(String.raw`^${HOST}\/([^\/\s]+)\/_git\/([^\/\s?#]+)\/pullrequest\/(\d+)`, 'i')
10const WORK_ITEM = new RegExp(String.raw`^${HOST}(?:\/[^\/\s]+)?\/_workitems\/edit\/(\d+)`, 'i')
11const URL_RE = /https:\/\/[^\s<>()[\]{}"'`|\\]+/g
12// AB#1234: Azure Boards' own notation for a work item.
13const AB_RE = /\bAB#(\d+)\b/g
14
15// What a URL is, its canonical form and its label: `repo!12` for a pull
16// request (Azure DevOps' own notation), `#1234` for a work item.
17export const classify = (url: string): Found | null => {
18  const pr = PR.exec(url)
19  if (pr) return { kind: 'pr', url: pr[0], label: `${decodeURIComponent(pr[4] ?? '')}!${pr[5]}` }
20  const wi = WORK_ITEM.exec(url)
21  if (wi) {
22    // One URL per work item, whichever project path the mention carried.
23    const base = wi[1] ? `https://dev.azure.com/${wi[1]}` : `https://${wi[2]}.visualstudio.com`
24    return { kind: 'workItem', url: `${base}/_workitems/edit/${wi[3]}`, label: `#${wi[3]}` }
25  }
26  return null
27}
28
29// Every pull request and work item in a message, in the order written.
30// AB#1234 counts only when `organization` is set.
31export const findMentions = (text: string, organization = ''): Found[] => {
32  const hits: { at: number; found: Found }[] = []
33  for (const m of text.matchAll(URL_RE)) {
34    const found = classify(m[0])
35    if (found) hits.push({ at: m.index ?? 0, found })
36  }
37  if (organization) {
38    for (const m of text.matchAll(AB_RE)) {
39      const url = `https://dev.azure.com/${organization}/_workitems/edit/${m[1]}`
40      hits.push({ at: m.index ?? 0, found: { kind: 'workItem', url, label: `#${m[1]}` } })
41    }
42  }
43  return hits.sort((a, b) => a.at - b.at).map(h => h.found)
44}
45
46// The organization URL and id `az boards work-item show` needs for a work
47// item link as `classify` writes it.
48export const workItemRef = (url: string): { orgUrl: string; id: string } | null => {
49  const m = /^https:\/\/(?:dev\.azure\.com\/([^\/]+)|([\w-]+)\.visualstudio\.com)\/_workitems\/edit\/(\d+)$/.exec(url)
50  if (!m || !m[3]) return null
51  return { orgUrl: `https://dev.azure.com/${m[1] ?? m[2]}`, id: m[3] }
52}
53
54// The title and state in `az boards work-item show -o json` output.
55export const parseWorkItem = (json: string): WorkItemInfo | null => {
56  try {
57    const fields = (JSON.parse(json) as { fields?: Record<string, unknown> }).fields ?? {}
58    const title = fields['System.Title']
59    const state = fields['System.State']
60    return typeof title === 'string' ? { title, state: typeof state === 'string' ? state : '' } : null
61  } catch {
62    return null
63  }
64}
65
66// Shortens a title to fit the band.
67export const cut = (s: string, max = 20) => {
68  const t = s.replace(/\s+/g, ' ').trim()
69  return t.length <= max ? t : `${t.slice(0, max - 1).trimEnd()}…`
70}
71
72// Moves each found link to the front, the last one written ending up first,
73// and keeps `max`.
74export const remember = (list: readonly Mention[], found: readonly Found[], max: number): Mention[] => {
75  let next = [...list]
76  for (const f of found) next = [{ url: f.url, label: f.label }, ...next.filter(m => m.url !== f.url)]
77  return next.slice(0, Math.max(0, max))
78}
79
80// The text a transcript row carries: a string, or its text blocks.
81export const textOf = (content: unknown): string => {
82  if (typeof content === 'string') return content
83  if (!Array.isArray(content)) return ''
84  return content
85    .map(b => (b && typeof b === 'object' && (b as { type?: unknown }).type === 'text' ? String((b as { text?: unknown }).text ?? '') : ''))
86    .join('\n')
87}
88
89// The person's prompts and the model's replies in a transcript file's JSONL,
90// oldest first; meta rows, tool results and subagent rows are left out.
91export const transcriptTexts = (jsonl: string): string[] => {
92  const out: string[] = []
93  for (const line of jsonl.split('\n')) {
94    if (!line.startsWith('{')) continue
95    let row: { type?: string; isMeta?: boolean; isSidechain?: boolean; message?: { content?: unknown } }
96    try {
97      row = JSON.parse(line)
98    } catch {
99      continue
100    }
101    if ((row.type !== 'user' && row.type !== 'assistant') || row.isMeta || row.isSidechain) continue
102    const text = textOf(row.message?.content)
103    if (text) out.push(text)
104  }
105  return out
106}
107

1// One link in the bar: where it goes and the short text drawn for it.
2export type Mention = { url: string; label: string }
3
4// Newest first, each list already cut to its setting.
5export type Links = { prs: Mention[]; workItems: Mention[] }
6
7// A work item's title and state as Azure Boards reports them, keyed by its URL.
8export type WorkItemInfo = { title: string; state: string }
9export type WorkItemDetails = Record<string, WorkItemInfo>
10
11declare module 'claude-code' {
12  interface PluginState {
13    'ado-link-bar': { links: Links; details: WorkItemDetails }
14  }
15}
16