Repository navigation
Expand file tree
/
Copy pathdev-web.ts
More file actions
440 lines (411 loc) · 19.2 KB
/
Copy pathdev-web.ts
File metadata and controls
440 lines (411 loc) · 19.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
/**
* The Web development loop: build once, serve through `dsh web`, and keep every
* browser-side artifact rebuilt on source edits, in one terminal.
*
* Stages, in order: `pnpm run build:artifacts` (skipped by `--skip-build`), three
* long-lived watchers, then `dsh web` (skipped by `--no-serve`). The watchers
* exist because the compile shell links built lib products rather than
* sources: `tsc -b tsconfig.client.json --watch` emits `lib/types` (the tsdown
* lib entries are that emit, not `src`), tsdown watch bundles `lib/index.js`
* and `lib/client.js`, and `vite build --watch` rewrites `apps/web/dist`, which
* `dsh web` serves. A missing watcher does not fail — it silently shows the
* previous artifact, so an edit appears to do nothing; any stage exiting on its
* own therefore stops the loop with exit code 1.
*
* Reload signaling is not this script's business — the host webserver
* stat-polls the bundles it serves and broadcasts `rebuilt` frames itself, so
* any process that rewrites `lib/client.js` files triggers reloads.
*
* MUST NOT run beside `pnpm run build` or `build:artifacts`: they write the same `lib/` and
* `apps/web/dist/` trees. The build stage here finishes before any watcher starts.
*
* Usage: `pnpm run dev:web [--skip-build] [--no-serve] [--poll[=ms]] [dsh web arguments]`.
* `--skip-build` requires the artifact tree from a prior `build` or `build:artifacts`: every
* watcher is incremental over the previous stage's output and none of them
* bootstraps a missing tree. `--no-serve` keeps only the watchers, for a
* `dsh web` started elsewhere. `--poll` switches the source watchers to polling
* (default 500ms): network mounts (weka) deliver no inotify events, so native
* watching sees the initial build only and never a source change. Polling has
* to reach tsc too — a native-watching tsc never re-emits `lib/types`, which
* strands the other two stages on stale input.
*
* Shutdown: Ctrl+C reaches every stage through the terminal's process group, so
* the script only waits for them and escalates survivors; SIGTERM is addressed
* to this process alone and is forwarded once. The exit code is 130 after
* SIGINT, 0 after SIGTERM, and 1 when a stage exited on its own.
*
* Each package keeps its own tsdown.config.ts untouched: this script layers
* `watch` through API-level inline config (tsdown workspace mode fills inline
* keys under each package's file config, and no package config defines it).
*/
import { globSync, readFileSync } from 'node:fs'
import { dirname, join, resolve, sep } from 'node:path'
import { fileURLToPath, pathToFileURL } from 'node:url'
import { execa } from 'execa'
import { build } from 'tsdown'
import type { TsdownBundle } from 'tsdown'
import {
CLIENT_BUILD_PROFILE_SELECTOR,
clientBuildProcessEnvironment,
repositoryClientBuildEnvironment,
} from './client-build-environment.ts'
import { pnpmInvocation } from './pnpm-invocation.ts'
const repoRoot = fileURLToPath(new URL('..', import.meta.url))
/** Client-face type emit feeding every tsdown lib entry in the watch set. */
const CLIENT_TYPE_PROGRAM = 'tsconfig.client.json'
/** Compile-shell workspace whose dist `dsh web` serves. */
const SHELL_PACKAGE = '@deepseek-ai/dsh-web-frontend'
/**
* Test infrastructure builds through the client preset but never enters the
* shell's module graph, so it is not a dev-loop artifact.
*/
const TEST_INFRASTRUCTURE_PREFIX = 'packages/test-support/'
/**
* Sample one local public environment for every long-lived watcher stage.
* @param root - repository root supplying version and Git metadata.
* @param environment - watcher launch environment supplying public extensions.
* @returns process environment shared by tsdown and spawned watcher stages.
*/
export function devWebBuildEnvironment(
root: string,
environment: NodeJS.ProcessEnv = process.env,
): NodeJS.ProcessEnv {
return clientBuildProcessEnvironment(environment, repositoryClientBuildEnvironment(root, environment))
}
/** Resolved `dev-web` command line: the script's own flags plus the arguments forwarded to `dsh web`. */
export interface DevWebArguments {
/** Skip the `pnpm run build:artifacts` that otherwise precedes the watchers. */
readonly skipBuild: boolean
/** Start `dsh web`; false keeps only the rebuild watchers beside an already running server. */
readonly serve: boolean
/** Source-watcher polling interval in milliseconds; undefined selects native watching. */
readonly pollInterval: number | undefined
/** Arguments forwarded verbatim to `dsh web`, in order. */
readonly appArgs: readonly string[]
}
/** Polling interval selected by a bare `--poll`. */
const DEFAULT_POLL_INTERVAL = 500
/**
* Parse the script's command line. `--skip-build`, `--no-serve`, and `--poll[=ms]`
* belong to this script; a bare `--` is dropped; every other token is forwarded
* to `dsh web`.
* @param argv - arguments after the script path.
* @returns the resolved flags and forwarded arguments.
* @throws Error when `--poll` carries a non-positive or non-integer interval, or
* when `--no-serve` leaves forwarded arguments without a `dsh web` process.
*/
export function parseDevWebArguments(argv: readonly string[]): DevWebArguments {
let skipBuild = false
let serve = true
let pollInterval: number | undefined
const appArgs: string[] = []
for (const arg of argv) {
// `pnpm run` forwards a `--` separator verbatim; it carries no meaning here.
if (arg === '--') continue
if (arg === '--skip-build') skipBuild = true
else if (arg === '--no-serve') serve = false
else if (arg === '--poll' || arg.startsWith('--poll=')) {
pollInterval = arg === '--poll' ? DEFAULT_POLL_INTERVAL : Number(arg.slice('--poll='.length))
if (!Number.isInteger(pollInterval) || pollInterval <= 0) throw new Error(`dev-web: invalid --poll interval "${arg}"`)
} else appArgs.push(arg)
}
if (!serve && appArgs.length > 0) {
throw new Error(`dev-web: --no-serve leaves no dsh web process for ${appArgs[0] ?? ''}`)
}
return { skipBuild, serve, pollInterval, appArgs }
}
/**
* Discover the watch workspace by declaration: every packages/<group>/<name>
* whose package.json carries `dsh.client` with platform "web" is a client
* plugin bundle emitter. Scanned once at startup — a package added while
* watching means restarting this script.
* @param root - repository root containing the grouped package directories.
* @returns workspace-relative plugin package directories.
*/
export function discoverPluginDirs(root = repoRoot): string[] {
const dirs: string[] = []
for (const manifestPath of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as {
dsh?: { client?: { platform?: unknown } }
}
if (manifest.dsh?.client?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/'))
}
return dirs
}
/**
* Discover the statically linked library packages: the other half of the same
* partition {@link discoverPluginDirs} takes. A package that builds through the
* client preset without declaring `dsh.client` has no loader-delivered browser
* half, so the compile shell links its `lib/index.js` instead — and an edit to
* its source reaches the browser only once that bundle is rewritten. Deriving
* the set from the build preset rather than a hand list keeps it correct when
* dependency sections move around; deriving it from `dependencies` would not,
* because client packages declare their build inputs as devDependencies.
* @param root - repository root containing the grouped package directories.
* @returns workspace-relative library package directories.
*/
export function discoverLibraryDirs(root = repoRoot): string[] {
const dirs: string[] = []
for (const configPath of globSync('packages/*/*/tsdown.config.ts', { cwd: root }).sort()) {
const dir = dirname(configPath).split(sep).join('/')
if (dir.startsWith(TEST_INFRASTRUCTURE_PREFIX)) continue
if (!readFileSync(join(root, configPath), 'utf8').includes('tsdown.client.ts')) continue
const manifest = JSON.parse(readFileSync(join(root, dir, 'package.json'), 'utf8')) as {
dsh?: { client?: unknown }
}
if (manifest.dsh?.client === undefined) dirs.push(dir)
}
return dirs
}
/**
* Start the tsdown watch build used by `pnpm run dev:web`.
* @param root - repository or fixture root passed to tsdown.
* @param pluginDirs - workspace-relative package directories to watch.
* @param pollInterval - optional source-watcher polling interval in milliseconds.
* @returns live bundles after every watcher has completed its initial build and package-owned post-build hooks.
*/
export async function watchClientPlugins(
root: string,
pluginDirs: readonly string[],
pollInterval?: number,
): Promise<TsdownBundle[]> {
let resolveInitialBuilds: (() => void) | undefined
const initialBuilds = new Promise<void>((resolve) => { resolveInitialBuilds = resolve })
const initialized = new WeakSet<object>()
const readiness: { expectedBuilds?: number; initializedBuilds: number } = { initializedBuilds: 0 }
const bundles = await build({
cwd: root,
workspace: [...pluginDirs],
configLoader: 'native',
watch: true,
// Workspace hooks override inline hooks; onSuccess runs after each package's build:done work.
onSuccess: (options) => {
if (initialized.has(options)) return
initialized.add(options)
readiness.initializedBuilds += 1
if (
readiness.expectedBuilds !== undefined
&& readiness.initializedBuilds >= readiness.expectedBuilds
) resolveInitialBuilds?.()
},
...pollInterval !== undefined
? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
: {},
})
readiness.expectedBuilds = bundles.length
if (readiness.initializedBuilds >= readiness.expectedBuilds) resolveInitialBuilds?.()
await initialBuilds
return bundles
}
/** One long-lived stage process as the supervisor observes it. */
export interface StageHandle {
/** Command label used in diagnostics. */
readonly name: string
/** Settles with the exit code, or null when a signal ended the stage. */
readonly exited: Promise<number | null>
/**
* Deliver one signal; a no-op once the stage has exited.
* @param signal - the signal to send.
*/
kill(signal: NodeJS.Signals): void
}
/** How a requested stop reaches the stages. */
export interface StageStop {
/** Signal sent to every live stage first; omitted when the terminal already delivered SIGINT to them. */
readonly signal?: NodeJS.Signals | undefined
/** Milliseconds to wait for exits before escalating to SIGTERM, and again before SIGKILL. */
readonly graceMs: number
}
/**
* Own the live stages: report a stage that exits before a stop was requested,
* and on a requested stop signal, wait, and escalate until every stage has exited.
*/
export class StageSupervisor {
private readonly live = new Set<StageHandle>()
private stopping = false
/**
* @param onStale - receives the stage name and exit code when a stage exits before a stop was requested.
*/
constructor(private readonly onStale: (stage: string, code: number | null) => void) {}
/**
* Track one started stage until it exits.
* @param stage - the stage to supervise.
*/
add(stage: StageHandle): void {
this.live.add(stage)
void stage.exited.then((code) => {
this.live.delete(stage)
if (!this.stopping) this.onStale(stage.name, code)
})
}
/**
* Stop every live stage and resolve once all of them have exited.
* @param stop - initial signal and the grace period between escalation steps.
*/
async stop(stop: StageStop): Promise<void> {
this.stopping = true
const escalation: (NodeJS.Signals | undefined)[] = [stop.signal]
if (stop.signal !== 'SIGTERM') escalation.push('SIGTERM')
for (const signal of escalation) {
if (this.live.size === 0) return
if (signal !== undefined) for (const stage of this.live) stage.kill(signal)
await this.settled(stop.graceMs)
}
for (const stage of this.live) stage.kill('SIGKILL')
await Promise.all([...this.live].map(stage => stage.exited))
}
private async settled(graceMs: number): Promise<void> {
let timer: NodeJS.Timeout | undefined
await Promise.race([
Promise.all([...this.live].map(stage => stage.exited)),
new Promise<void>((resolve) => { timer = setTimeout(resolve, graceMs) }),
])
clearTimeout(timer)
}
}
/**
* Grace period per escalation step. `dsh web` gives its plugin tree five seconds
* to dispose after the first signal; escalating earlier would turn the graceful
* drain into a forced exit.
*/
const STOP_GRACE_MS = 6_000
/**
* Spawn one long-lived stage with inherited stdio and hand it to the supervisor.
* @param supervisor - owner that reports an unexpected exit and stops the stage on shutdown.
* @param name - command label used in diagnostics.
* @param command - executable, resolved from the workspace bins when `local` is set.
* @param args - command arguments.
* @param local - whether to resolve `command` from the workspace's installed bins.
*/
function spawnStage(
supervisor: StageSupervisor,
name: string,
command: string,
args: readonly string[],
local: boolean,
): void {
const child = execa(command, [...args], {
cwd: repoRoot,
stdio: 'inherit',
preferLocal: local,
reject: false,
})
supervisor.add({
name,
exited: child.then(result => result.exitCode ?? null),
kill(signal) { child.kill(signal) },
})
}
/**
* Build every repository artifact, without the aggregate test and script
* typechecks, with the launch environment untouched:
* `scripts/build.ts` samples the public client values itself.
* @returns the build's exit code, or null when a signal ended it.
*/
async function runBuild(): Promise<number | null> {
const invocation = pnpmInvocation(['run', 'build:artifacts'])
const result = await execa(invocation.command, invocation.args, { cwd: repoRoot, stdio: 'inherit', reject: false })
return result.exitCode ?? null
}
const invokedPath = process.argv[1]
const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
if (isMain) {
let options: DevWebArguments
try {
options = parseDevWebArguments(process.argv.slice(2))
} catch (error) {
console.error(error instanceof Error ? error.message : error)
console.error('dev-web: usage: pnpm run dev:web [--skip-build] [--no-serve] [--poll[=ms]] [dsh web arguments]')
process.exit(1)
}
// Shutdown is requested once, by a terminal signal or by a stage exiting on
// its own; `signal` stays unset for SIGINT because the terminal's process
// group already delivered it to every stage.
const shutdown = Promise.withResolvers<number>()
const requested: { code?: number; signal?: NodeJS.Signals } = {}
const shutdownRequested = (): boolean => requested.code !== undefined
const requestShutdown = (code: number, signal: NodeJS.Signals | undefined): void => {
if (shutdownRequested()) return
requested.code = code
if (signal !== undefined) requested.signal = signal
shutdown.resolve(code)
}
const supervisor = new StageSupervisor((stage, code) => {
console.error(`dev-web: ${stage} exited (code ${String(code)}); stopping the other stages`)
requestShutdown(1, 'SIGTERM')
})
// Persistent listeners, not `once`: the tsdown watchers bundle signal-exit,
// which re-raises a signal whenever it finds no other listener left and would
// terminate this process in the middle of the teardown below.
process.on('SIGINT', () => { requestShutdown(130, undefined) })
process.on('SIGTERM', () => { requestShutdown(0, 'SIGTERM') })
const buildExit = options.skipBuild ? 0 : await runBuild()
if (shutdownRequested()) process.exit(await shutdown.promise)
if (buildExit !== 0) {
console.error(`dev-web: pnpm run build:artifacts exited (code ${String(buildExit)})`)
process.exit(1)
}
const buildEnvironment = devWebBuildEnvironment(repoRoot, process.env)
for (const name of Object.keys(process.env)) {
if (name === CLIENT_BUILD_PROFILE_SELECTOR || name.startsWith('DSH_CLIENT_')) {
Reflect.deleteProperty(process.env, name)
}
}
for (const [name, value] of Object.entries(buildEnvironment)) {
if (name.startsWith('DSH_CLIENT_') && value !== undefined) process.env[name] = value
}
const pluginDirs = discoverPluginDirs()
const libraryDirs = discoverLibraryDirs()
if (pluginDirs.length === 0) {
console.error('dev-web: no dsh.client (platform "web") packages found under packages/')
process.exit(1)
}
if (libraryDirs.length === 0) {
console.error('dev-web: no client-preset library packages found under packages/ — the compile shell links their lib products, so an empty set means the discovery predicate is stale')
process.exit(1)
}
// tsc has no polling interval flag, so `--poll` selects its fixed-interval
// watchers rather than an interval. Dropping that translation leaves tsc
// natively watching on a network mount where inotify never fires: it stops
// re-emitting lib/types, and the two later stages then rebuild forever from
// stale input without printing anything.
spawnStage(supervisor, `tsc -b ${CLIENT_TYPE_PROGRAM} --watch`, 'tsc', [
'-b', CLIENT_TYPE_PROGRAM, '--watch', '--preserveWatchOutput',
...options.pollInterval !== undefined
? ['--watchFile', 'fixedPollingInterval', '--watchDirectory', 'fixedPollingInterval']
: [],
], true)
// tsdown's initial builds are awaited before the dist watcher starts so vite's
// first build reads current lib bundles rather than whatever the last full
// build left. Its own watch then covers later lib rewrites — those files are
// in its module graph.
const bundles = await watchClientPlugins(repoRoot, [...pluginDirs, ...libraryDirs], options.pollInterval)
if (!shutdownRequested()) {
// Through the shell's own `watch` script rather than vite's API: vite is not a
// repository-root dependency, and more importantly the vite root is its
// working directory — `resolve.dedupe` resolves react from that root, so
// running vite from anywhere but apps/web silently switches which react copy
// the bundle gets.
spawnStage(supervisor, 'vite build --watch', 'pnpm', ['--filter', SHELL_PACKAGE, 'run', 'watch'], false)
// The same launch vector as the root `dsh` script, so the served Host runs
// from source exactly as `pnpm dsh web` would.
if (options.serve) {
spawnStage(supervisor, 'dsh web', process.execPath, [
'--import', 'tsx/esm', 'apps/cli/src/bin.ts', 'web', ...options.appArgs,
], false)
}
console.log(
`dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
+ ` and ${String(libraryDirs.length)} statically linked library packages`
+ (options.pollInterval !== undefined ? ` (polling ${String(options.pollInterval)}ms)` : '')
+ `, plus tsc -b ${CLIENT_TYPE_PROGRAM} and the ${SHELL_PACKAGE} dist build`
+ (options.serve ? ', serving through dsh web' : '')
+ ':\n '
+ [...pluginDirs, ...libraryDirs].join('\n '),
)
}
const exitCode = await shutdown.promise
await supervisor.stop({ signal: requested.signal, graceMs: STOP_GRACE_MS })
for (const bundle of bundles) await bundle[Symbol.asyncDispose]()
process.exit(exitCode)
}