dev-server

1import { atom, read, update } from 'claude-code'
2import type { Engine, Register } from 'claude-code'
3
4import type { DevState } from '../types'
5
6const PANE = 'dev-server'
7const LOG_LINES = 200
8const STOP_WAIT_MS = 4000
9
10const state = atom({ plugin: 'dev-server', key: 'state' } as const, 'stopped')
11const port = atom({ plugin: 'dev-server', key: 'port' } as const, null)
12const log = atom({ plugin: 'dev-server', key: 'log' } as const, [])
13
14// The dev server this mod started. Only that one can be stopped from here.
15let child: AsyncGenerator<unknown> | null = null
16let startedPort: number | null = null
17
18// The port a project's `dev` script serves on: `-p 9002`, `--port=9002`, `PORT=9002` and the like.
19export function parsePort(script: unknown): number | null {
20  if (typeof script !== 'string') return null
21  const m = /(?:--port[= ]|-p[= ]?|\bPORT=)(\d{2,5})\b/.exec(script)
22  const value = m ? Number(m[1]) : NaN
23  return value > 0 && value < 65536 ? value : null
24}
25
26export function isWindowsPath(cwd: string): boolean {
27  return /^[A-Za-z]:[\\/]/.test(cwd) || cwd.startsWith('\\\\')
28}
29
30// npm is a .cmd script on Windows, which cannot be started without a shell.
31export function devArgv(cwd: string): string[] {
32  return [isWindowsPath(cwd) ? 'npm.cmd' : 'npm', 'run', 'dev']
33}
34
35// The process listening on `port`, from `netstat -ano -p tcp` output (Windows) or `lsof -ti` output.
36export function listeningPid(output: string, listenPort: number, isWindows: boolean): number | null {
37  if (!isWindows) {
38    const pid = Number(output.trim().split('\n')[0])
39    return Number.isInteger(pid) && pid > 0 ? pid : null
40  }
41  for (const line of output.split('\n')) {
42    const cols = line.trim().split(/\s+/)
43    if (cols.length >= 5 && cols[3] === 'LISTENING' && cols[1].endsWith(`:${listenPort}`)) {
44      const pid = Number(cols[4])
45      if (Number.isInteger(pid) && pid > 0) return pid
46    }
47  }
48  return null
49}
50
51async function isUp($: Engine, cwd: string, devPort: number): Promise<boolean> {
52  try {
53    const r = await $.process.run(['curl', '-s', '-I', '-m', '2', '-w', '\n%{http_code}', `http://localhost:${devPort}`], { cwd, timeoutMs: 5000 })
54    return r.exitCode === 0 && r.stdout.trim().split('\n').pop()?.trim() !== '000'
55  } catch {
56    return false
57  }
58}
59
60// `npm run dev` leaves children behind it, so after the child is closed, stop what still listens on the port.
61async function stopListener($: Engine, cwd: string, devPort: number): Promise<void> {
62  const isWindows = isWindowsPath(cwd)
63  try {
64    const found = isWindows
65      ? await $.process.run(['netstat', '-ano', '-p', 'tcp'], { cwd, timeoutMs: 5000 })
66      : await $.process.run(['lsof', '-ti', `tcp:${devPort}`, '-sTCP:LISTEN'], { cwd, timeoutMs: 5000 })
67    const pid = listeningPid(found.stdout, devPort, isWindows)
68    if (pid === null) return
69    await $.process.run(isWindows ? ['taskkill', '/PID', String(pid), '/T', '/F'] : ['kill', String(pid)], { cwd, timeoutMs: 5000 })
70  } catch {
71    // nothing was listening, or the tool is missing
72  }
73}
74
75async function say($: Engine, text: string): Promise<void> {
76  const lines = text.split(/\r?\n/).filter(l => l.trim() !== '')
77  if (lines.length > 0) await update($, log, old => [...old, ...lines].slice(-LOG_LINES))
78}
79
80async function start($: Engine): Promise<string> {
81  if (child !== null) return `The dev server is already ${await read($, state)} on :${startedPort}.`
82  const cwd = await $.session.cwd()
83  let script: unknown
84  try {
85    script = JSON.parse(await $.fs.read(`${cwd.replace(/[\\/]+$/, '')}/package.json`)).scripts?.dev
86  } catch {
87    return 'No package.json found in this folder.'
88  }
89  if (typeof script !== 'string') return 'package.json has no "dev" script.'
90  const devPort = parsePort(script)
91  if (devPort !== null && (await isUp($, cwd, devPort))) return `Something is already serving on :${devPort}; stop it first.`
92
93  startedPort = devPort
94  await update($, port, () => devPort)
95  await update($, log, () => [])
96  await update($, state, () => 'starting' as DevState)
97  const run = $.process.spawn({ argv: devArgv(cwd), cwd })
98  child = run
99  void (async () => {
100    try {
101      for await (const piece of run) {
102        const chunk = piece as { text?: string }
103        if (chunk.text !== undefined) {
104          await say($, chunk.text)
105          if ((await read($, state)) === 'starting') await update($, state, () => 'running' as DevState)
106        }
107      }
108    } catch (err) {
109      await say($, `The dev server stopped: ${String(err).slice(0, 200)}`)
110    } finally {
111      if (child === run) {
112        child = null
113        await update($, state, () => 'stopped' as DevState)
114      }
115    }
116  })()
117  return devPort !== null ? `Starting the dev server on :${devPort}.` : 'Starting the dev server.'
118}
119
120async function stop($: Engine): Promise<string> {
121  const run = child
122  if (run === null) return 'No dev server started from here is running. One started in a terminal has to be stopped there.'
123  const cwd = await $.session.cwd()
124  child = null
125  try {
126    await Promise.race([run.return(undefined), new Promise(r => setTimeout(r, STOP_WAIT_MS))])
127  } catch {
128    // already gone
129  }
130  if (startedPort !== null) await stopListener($, cwd, startedPort)
131  await update($, state, () => 'stopped' as DevState)
132  return 'Dev server stopped.'
133}
134
135async function dispatch($: Engine, args: string): Promise<string> {
136  const word = args.trim().split(/\s+/)[0] ?? ''
137  const current = await read($, state)
138  if (word === 'start') return start($)
139  if (word === 'stop') return stop($)
140  if (word === 'restart') {
141    if (child !== null) await stop($)
142    return start($)
143  }
144  if (word === '' || word === 'toggle') return current === 'stopped' ? start($) : stop($)
145  if (word === 'status') return current === 'stopped' ? 'The dev server is not running from here.' : `The dev server is ${current} on :${startedPort}.`
146  return 'Use /dev start, stop, restart or status.'
147}
148
149export const register: Register = on => {
150  on('session.start', async ($, e, next) => {
151    await $.command.register({ name: 'dev', description: 'Start, stop or restart the dev server (start | stop | restart | status)' })
152    return next(e)
153  })
154
155  on('command.run', { command: 'dev' }, async ($, e) => {
156    try {
157      const text = await dispatch($, String(e.args ?? ''))
158      if (String(e.args ?? '').trim() === '') await $.ui.open({ id: PANE, title: 'Dev server' })
159      return { text }
160    } catch {
161      return { text: 'The dev server command could not do that.' }
162    }
163  })
164
165  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
166    const { Box, Text, Button } = $.ui.resolve(e)
167    const current = await read($, state)
168    const devPort = await read($, port)
169    const lines = await read($, log)
170    const run = (args: string) => () => void $.command.run({ command: 'dev', args })
171
172    return (
173      <Box flexDirection="column">
174        <Box flexDirection="row" gap={1}>
175          {current === 'stopped' ? <Button onPress={run('start')}>Start</Button> : <Button onPress={run('stop')}>Stop</Button>}
176          {current !== 'stopped' && <Button onPress={run('restart')}>Restart</Button>}
177          <Text dimColor>{current === 'stopped' ? 'stopped' : `${current}${devPort !== null ? ` on :${devPort}` : ''}`}</Text>
178        </Box>
179        {lines.slice(-30).map((line, i) => (
180          <Text key={String(i)} wrap="truncate">{line}</Text>
181        ))}
182      </Box>
183    )
184  })
185}
186

1export type DevState = 'stopped' | 'starting' | 'running'
2
3declare module 'claude-code' {
4  interface PluginState {
5    'dev-server': {
6      state: DevState
7      port: number | null
8      log: string[]
9    }
10  }
11}
12