mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-19 19:51:20 -08:00
refactor(tooling): [MOD-DEV-01] own dev server lifecycle and report port failures
This commit is contained in:
Harvey Zhao committed
1 parent
401d4cdd65
commit
772d79a671
24 files changed
+1249
-132
No files matched your search
+56
-26
@@ -2,19 +2,24 @@
|
||||
|
||||
Use Node from `.node-version` and Yarn Classic 1.22.22. The historical JS/MJS
|
||||
entrypoints remain checked compatibility shims; implementation lives in strict TS.
|
||||
No runtime/build dependency or bundler was replaced by this migration.
|
||||
Vite still owns library bundling. The dev HTTP server is repository-owned; the
|
||||
root dev dependency mrmime 2.0.1 supplies MIME names. Servor 4.0.2 remains only for
|
||||
its browser-opening helper and the isolated historical failure probe.
|
||||
|
||||
| Module | Responsibility |
|
||||
| --- | --- |
|
||||
| `projects.ts` | Deterministic workspace discovery, CLI selection, non-TTY failure, one JS/TS entry |
|
||||
| `names.ts` | Historical camelCase/PascalCase library global names |
|
||||
| `config.ts` | Vite configuration and resource/worker/output targets; typed with installed Vite declarations |
|
||||
| `banner.ts` | Version/license/notices, UMD AMD/global identity, inline-worker banner removal |
|
||||
| `production.ts` | Sequential package/format builds, checked dist cleanup, docs copy and optional analysis |
|
||||
| `analysis.ts` | Per-build module and artifact size/hash reports outside dist |
|
||||
| `development.ts` | Servor demo startup, initial IIFE build, source watcher, first-success browser opening |
|
||||
| `rebuild.ts` | One active build Promise, coalesced pending changes and later retry after rejection |
|
||||
| `vendor.d.ts` | Only the consumed prompts 2.4.2 / Servor 4.0.2 APIs; verified against installed sources |
|
||||
| Module | Responsibility |
|
||||
| ---------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `projects.ts` | Deterministic workspace discovery, CLI selection, non-TTY failure, one JS/TS entry |
|
||||
| `names.ts` | Historical camelCase/PascalCase library global names |
|
||||
| `config.ts` | Vite configuration and resource/worker/output targets; typed with installed Vite declarations |
|
||||
| `banner.ts` | Version/license/notices, UMD AMD/global identity, inline-worker banner removal |
|
||||
| `production.ts` | Sequential package/format builds, checked dist cleanup, docs copy and optional analysis |
|
||||
| `analysis.ts` | Per-build module and artifact size/hash reports outside dist |
|
||||
| `development.ts` | Session startup/close/done, IIFE build queue, source watcher and first-success browser opening |
|
||||
| `server.ts` | HTTP binding, docs watcher, request/socket ownership and shutdown |
|
||||
| `assets.ts` | Root-contained files, directory indexes, HTML injection, gzip and media ranges |
|
||||
| `reload.ts` | SSE clients, shared heartbeat and the browser reload script |
|
||||
| `rebuild.ts` | One active build Promise, coalesced pending changes and later retry after rejection |
|
||||
| `vendor.d.ts` | Only the consumed prompts 2.4.2 / Servor 4.0.2 openBrowser APIs |
|
||||
|
||||
`build.js` and `dev.js` own command execution/error reporting. `utils.js`,
|
||||
`projects.js`, `rebuild.js` and `build-analysis.mjs` keep their previous named
|
||||
@@ -33,6 +38,7 @@ yarn build --help
|
||||
yarn dev --help
|
||||
yarn typecheck:library
|
||||
yarn test:library
|
||||
yarn test:dev-server
|
||||
```
|
||||
|
||||
No-argument TTY selection uses the same prompts UI. Missing names in non-TTY mode,
|
||||
@@ -54,13 +60,13 @@ under `scripts/library/`, including additions/removals. Do not reduce that cover
|
||||
to `config.ts` alone: banners, name mapping, project discovery or analysis may also
|
||||
affect artifacts. Markdown maintenance changes are not build inputs.
|
||||
|
||||
## Development lifetime and remaining server work
|
||||
## Development lifetime
|
||||
|
||||
CLI defaults remain port 8082 and docs/index.html, with output at
|
||||
docs/uncompiled/<package>/index.js. The output directory is created before Servor
|
||||
enumerates directories for its Linux file watchers. The internal `runDevelop`
|
||||
function accepts a port only for isolated callers/tests; the CLI does not add a
|
||||
new flag. Do not stop an unrelated server occupying 8082 to run a test.
|
||||
docs/uncompiled/<package>/index.js. Optional `ARTPLAYER_DEV_PORT` accepts an integer
|
||||
0..65535; 0 atomically binds an available port for isolated callers/tests. Invalid
|
||||
values or occupied ports exit nonzero; there is no silent port fallback. Do not
|
||||
stop an unrelated server occupying 8082 to run a test.
|
||||
|
||||
Build errors are reported while keeping the source watcher alive. Changes during
|
||||
a build schedule one subsequent build rather than concurrent writes. Browser
|
||||
@@ -69,12 +75,31 @@ Only the package src tree is watched; external dependencies/configuration change
|
||||
still require restart. Tests use real automatic reload rather than racing it with
|
||||
a second manual navigation.
|
||||
|
||||
Servor still owns its HTTP server, docs watchers, reload sockets/timers and SIGINT
|
||||
handler until process exit; its API exposes no close handle. MOD-DEV-01 tracks
|
||||
replacing/adapting that lifetime and fixing its reproduced occupied-port exit code
|
||||
zero. `node refactor/scripts/servor-port-probe.mjs` reproduces that upstream defect
|
||||
in an isolated child without touching 8082. It is not a candidate-success test.
|
||||
This migration does not claim those server limitations are resolved.
|
||||
`startDevelopment` returns `{ url, close, done }`. The CLI owns SIGINT/SIGTERM
|
||||
handlers and its AbortController; importing implementation modules installs none.
|
||||
`close()` is idempotent: stop queuing builds, remove the abort handler and source
|
||||
watcher, close HTTP/docs watching/SSE, then await the active build. A late build
|
||||
cannot open a browser or reload a closed session. Aborting during asynchronous
|
||||
startup waits for and closes a late-bound server. `done` rejects on fatal watcher
|
||||
or server errors; ordinary compiler errors retain the session for correction.
|
||||
|
||||
`server.ts` owns every HTTP socket and active asset pipeline, the recursive docs
|
||||
watcher and 75ms debounce timer. Its close destroys only its own sockets and waits
|
||||
for request pipelines to settle. `reload.ts` has one 30s heartbeat while clients
|
||||
exist; the last disconnection or shutdown removes it. The browser closes its SSE
|
||||
connection on pagehide. Docs edits reload automatically; the selected output tree
|
||||
is ignored by the docs watcher and reloads only after a successful queued build.
|
||||
|
||||
`assets.ts` leaves classic JS assets intact for Monaco, injects reload into HTML,
|
||||
serves directory index.html and escaped listings, and falls back to root index.html
|
||||
for missing extensionless routes. HTTP corrections include valid directory
|
||||
redirects, fallback status200, body-free HEAD, explicit gzip;q=0, exact/suffix/open
|
||||
media ranges and 416 for malformed/unsatisfiable ranges. Realpath containment
|
||||
rejects outside symlinks/junctions. Stream pipelines dispose file/gzip resources on
|
||||
disconnect. This local docs server is not a production hosting server.
|
||||
|
||||
`node refactor/scripts/servor-port-probe.mjs` preserves the old Servor occupied-port
|
||||
exit0 reproduction. Candidate failure/cleanup checks live in test/dev-server.test.js.
|
||||
|
||||
## Evidence and regression ownership
|
||||
|
||||
@@ -86,13 +111,18 @@ This migration does not claim those server limitations are resolved.
|
||||
- `test/plugin-scaffold.test.js`: newly generated plugins use these real tools.
|
||||
- `test/browser/library-development.spec.js`: real dev server in Chromium, Firefox
|
||||
and WebKit, worker messaging, automatic reload, source edits and error recovery.
|
||||
Uses fixture ports and disposes its own child; it does not test media playback.
|
||||
The real JS CLI receives SIGTERM and must exit naturally with status0. A second
|
||||
case serves actual docs/Monaco, executes TypeScript and plays/seeks/decodes local
|
||||
MP4. Its recorded tracked core5.4.1 asset is not a newly built release candidate.
|
||||
- `test/dev-server.test.js`: real occupied-port CLI failure, HTTP/HEAD/ranges,
|
||||
repeated same-port startup/shutdown with SSE, aborted download and startup/build
|
||||
cancellation; a controlled clock separately checks heartbeat disposal.
|
||||
- `node refactor/scripts/library-build-comparison.mjs`: copy current package sources
|
||||
into a retained fixture, build all libraries with frozen pre-migration scripts
|
||||
and current scripts at the same paths, compare all artifact hashes. This is an
|
||||
explicit whole-build validation, not part of every quick unit test.
|
||||
|
||||
Remote Linux/macOS/Windows CI remains a separate release gate. The local browser
|
||||
evidence for MOD-02 is Windows; source inspection of Linux watcher registration
|
||||
does not substitute for a remote Linux run. Lerna and root installation hooks were
|
||||
evidence for MOD-02 and MOD-DEV-01 is Windows; it does not substitute for remote
|
||||
Linux/macOS runs or real device playback. Lerna and root installation hooks were
|
||||
not changed. The scaffold's separate guide remains in `scripts/plugin/README.md`.
|
||||
Reference in new issue
Block a user