link-check

1// Link Check: checks the external links Claude adds to pages, posts and templates.
2// Only links new in an edit are asked for; each URL once per session. Broken ones go back to Claude with the
3// edit's result, so it can fix them, and stay above the prompt until they're gone from the file.
4import { atom, read, update } from 'claude-code'
5import type { EngineInterface, Register } from 'claude-code'
6
7import type { Line, Problem } from '../types'
8
9const CONTENT_FILE = /\.(md|mdx|markdown|astro|html?|tsx|jsx|vue|svelte|php|njk|liquid|twig)$/i
10const EDIT_TOOLS = new Set(['Write', 'Edit', 'MultiEdit'])
11const WAIT_MS = 6_000 // how long an edit may wait for its links; later answers come as a toast
12const FILE_WAIT_MS = 20_000 // /links <file> waits longer: you asked for it
13const PER_EDIT = 25 // links checked per edit at most
14const PER_FILE = 100
15const PARALLEL = 6
16const BRAND = '#60a5fa'
17const AGENT = 'Mozilla/5.0 (compatible; link-check; +https://github.com/krysmalskipl/claude-code-mods)'
18// Hosts that are never real pages: local servers, examples and reserved names.
19const SKIP_HOST = /^(localhost|127\.\d+\.\d+\.\d+|0\.0\.0\.0|\[::1\]|([\w-]+\.)*(example\.(com|org|net)|local|test|invalid|localhost))$/i
20const EMPTY: Line = { problems: [], checked: 0 }
21
22type Result = { kind: 'ok' | 'redirect' | 'blocked' | 'broken' | 'unreachable'; status: number | null }
23
24// Held by the host, so the band survives a hot reload of this file.
25const line = atom({ plugin: 'link-check', key: 'line' } as const, EMPTY)
26
27const cache = new Map<string, Promise<Result>>() // url → its answer, once per session
28let running = 0
29const queue: (() => void)[] = []
30
31export const register: Register = on => {
32  on('session.start', async ($, e, next) => {
33    const result = await next(e)
34    await $.command
35      .register({ name: 'links', description: 'Broken links Claude added, or check every link in a file', argumentHint: '[file]' })
36      .catch(() => {}) // a name Claude Code already has is refused: start anyway
37    return result
38  })
39
40  on('tool.call', async ($, e, next) => {
41    const path = (e as unknown as { file_path?: unknown }).file_path
42    if (!EDIT_TOOLS.has(e.tool) || typeof path !== 'string' || !CONTENT_FILE.test(path)) return next(e)
43    const before = e.tool === 'Write' ? await $.fs.read(path).then(String, () => '') : ''
44    const ran = await next(e)
45    if (ran.deny !== undefined || ran.isError === true) return ran
46
47    const added = newLinks(e as unknown as Record<string, unknown>, before).slice(0, PER_EDIT)
48    if (added.length === 0) return ran
49    const checks = added.map(url => ({ url, answer: check($, url) }))
50    const timeUp = $.clock.sleep(WAIT_MS).then(() => null)
51    const inTime = await Promise.all(checks.map(c => Promise.race([c.answer, timeUp]).then(r => ({ url: c.url, r }))))
52    await refresh($, path, added.length)
53
54    const bad = inTime.filter(x => x.r && isProblem(x.r))
55    const late = checks.filter((_, i) => !inTime[i].r)
56    if (late.length > 0) void reportLate($, path, late) // in the background: the edit doesn't wait for slow hosts
57    if (bad.length === 0) return ran
58    const list = bad.map(x => `${x.url} (${label(x.r!)})`).join(', ')
59    const note = `link-check: ${bad.length === 1 ? 'a link' : `${bad.length} links`} just added to ${basename(path)} ${bad.length === 1 ? "doesn't" : "don't"} work: ${list}. Fix or remove ${bad.length === 1 ? 'it' : 'them'} if wrong.`
60    return { ...ran, context: [...(ran.context ?? []), note] }
61  }).catch(($, e, next) => next(e)) // a hook that failed never holds up the edit
62
63  on('command.run', { command: 'links' }, async ($, e) => {
64    const arg = e.args.trim()
65    if (!arg) {
66      const now = await read($, line)
67      if (now.problems.length === 0) return { text: `No broken links. ${now.checked} checked this session.` }
68      return { text: ['## Links that don\'t work', '', ...now.problems.map(p => `- ${p.url} (${label(p)}) in \`${basename(p.file)}\``)].join('\n') }
69    }
70    let text: string
71    try {
72      text = String(await $.fs.read(arg))
73    } catch (err) {
74      return { text: `Couldn't read ${arg}: ${err instanceof Error ? err.message : String(err)}` }
75    }
76    const urls = links(text).slice(0, PER_FILE)
77    if (urls.length === 0) return { text: `No external links in ${basename(arg)}.` }
78    const timeUp = $.clock.sleep(FILE_WAIT_MS).then(() => null)
79    const answers = await Promise.all(urls.map(url => Promise.race([check($, url), timeUp]).then(r => ({ url, r }))))
80    await refresh($, arg, urls.length)
81    const rows = answers.map(({ url, r }) => `- ${r ? icon(r) : '…'} ${url}${r && r.kind !== 'ok' ? ` (${label(r)})` : r ? '' : ' (still waiting)'}`)
82    const bad = answers.filter(a => a.r && isProblem(a.r)).length
83    return { text: [`## Links in ${basename(arg)}: ${urls.length} checked, ${bad} not working`, '', ...rows].join('\n') }
84  })
85
86  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
87    const rest = await next(e) // what other mods and Claude Code draw here stays
88    const now = { ...EMPTY, ...(await read($, line)) }
89    if (e.props.hasSurvey || now.problems.length === 0) return rest
90
91    const { Box, Text } = $.ui.resolve(e)
92    const first = now.problems[0]
93    const n = now.problems.length
94    return (
95      <Box flexDirection="column">
96        <Box paddingX={1}>
97          <Text wrap="truncate-end">
98            <Text color={BRAND} bold>{'◆ Links  '}</Text>
99            <Text color="red" bold>{`${n} not working`}</Text>
100            <Text dimColor>{` · ${first.url} (${label(first)}) in ${basename(first.file)}`}</Text>
101            {n > 1 && <Text dimColor>{` and ${n - 1} more`}</Text>}
102            <Text dimColor>{' · /links'}</Text>
103          </Text>
104        </Box>
105        {rest}
106      </Box>
107    )
108  })
109}
110
111// The file's problems are the known-bad links still in it, so a link Claude fixed drops off the band.
112async function refresh($: EngineInterface, path: string, checkedNow: number) {
113  const text = await $.fs.read(path).then(String, () => '')
114  const inFile = new Set(links(text))
115  const mine: Problem[] = []
116  for (const url of inFile) {
117    const r = await settled(url)
118    if (r && isProblem(r)) mine.push({ url, file: path, kind: r.kind as Problem['kind'], status: r.status })
119  }
120  await update($, line, l => ({ checked: l.checked + checkedNow, problems: [...l.problems.filter(p => p.file !== path), ...mine] }))
121}
122
123async function reportLate($: EngineInterface, path: string, late: { url: string; answer: Promise<Result> }[]) {
124  const answers = await Promise.all(late.map(c => c.answer.then(r => ({ url: c.url, r }))))
125  await refresh($, path, 0)
126  const bad = answers.filter(a => isProblem(a.r))
127  if (bad.length > 0) $.ui.toast(`link-check: ${bad.map(a => `${a.url} (${label(a.r)})`).join(', ')} in ${basename(path)}`)
128}
129
130// Links in what the edit wrote that weren't in what it replaced.
131export function newLinks(input: Record<string, unknown>, before: string) {
132  const pairs: [string, string][] = []
133  if (typeof input.content === 'string') pairs.push([input.content, before])
134  if (typeof input.new_string === 'string') pairs.push([input.new_string, String(input.old_string ?? '')])
135  if (Array.isArray(input.edits)) for (const x of input.edits as Record<string, unknown>[]) pairs.push([String(x.new_string ?? ''), String(x.old_string ?? '')])
136  const out = new Set<string>()
137  for (const [now, was] of pairs) {
138    const old = new Set(links(was))
139    for (const url of links(now)) if (!old.has(url)) out.add(url)
140  }
141  return [...out]
142}
143
144// Every external http(s) link in a text, once, without trailing punctuation and template placeholders.
145export function links(text: string) {
146  const out = new Set<string>()
147  for (const m of text.match(/https?:\/\/[^\s<>"'`)\]}|\\]+/g) ?? []) {
148    const url = m.replace(/[.,;:!?*_~]+$/, '')
149    if (/\$\{|\{\{|\.\.\.|…/.test(url)) continue
150    let host: string
151    try {
152      host = new URL(url).hostname
153    } catch {
154      continue
155    }
156    if (!host.includes('.') || SKIP_HOST.test(host)) continue
157    out.add(url)
158  }
159  return [...out]
160}
161
162// HEAD first; a host that refuses HEAD gets a GET. Each URL is asked once per session.
163function check($: EngineInterface, url: string): Promise<Result> {
164  let answer = cache.get(url)
165  if (!answer) {
166    answer = slot(async () => {
167      const ask = (method: string) => $.http.fetch(url, { method, headers: { 'user-agent': AGENT } })
168      let res = await ask('HEAD').catch(() => null)
169      if (!res || [403, 405, 501].includes(res.status)) res = (await ask('GET').catch(() => null)) ?? res
170      return classify(res?.status ?? null)
171    })
172    cache.set(url, answer)
173  }
174  return answer
175}
176
177// An answer that already came, without waiting for one that hasn't.
178async function settled(url: string) {
179  const answer = cache.get(url)
180  if (!answer) return null
181  return Promise.race([answer, Promise.resolve(null)])
182}
183
184// At most PARALLEL requests at once, so a page with many links doesn't flood anyone.
185async function slot<T>(job: () => Promise<T>): Promise<T> {
186  if (running >= PARALLEL) await new Promise<void>(go => queue.push(go))
187  running++
188  try {
189    return await job()
190  } finally {
191    running--
192    queue.shift()?.()
193  }
194}
195
196// 401, 403 and 429 are bot walls and rate limits: the page likely works in a browser, so they don't count.
197export const classify = (status: number | null): Result =>
198  status === null
199    ? { kind: 'unreachable', status }
200    : status < 300
201      ? { kind: 'ok', status }
202      : status < 400
203        ? { kind: 'redirect', status }
204        : [401, 403, 429, 999].includes(status)
205          ? { kind: 'blocked', status }
206          : { kind: 'broken', status }
207
208const isProblem = (r: Result) => r.kind === 'broken' || r.kind === 'unreachable'
209const label = (r: { kind: string; status: number | null }) =>
210  r.kind === 'unreachable' ? 'no answer' : r.kind === 'blocked' ? `${r.status}, blocks bots` : String(r.status)
211const icon = (r: Result) => (r.kind === 'ok' ? '✓' : r.kind === 'redirect' ? '↪' : r.kind === 'blocked' ? '~' : '✗')
212const basename = (p: string) => p.split('/').pop() ?? p
213

1// One external link that didn't answer as it should.
2export type Problem = {
3  url: string
4  file: string // the file it's in, as Claude edited it
5  kind: 'broken' | 'unreachable' // 4xx/5xx, or no answer at all
6  status: number | null
7}
8
9// What the band above the prompt draws.
10export type Line = {
11  problems: Problem[] // links still in their files that don't work
12  checked: number // links checked this session
13}
14
15declare module 'claude-code' {
16  interface PluginState {
17    'link-check': { line: Line }
18  }
19}
20