Levandor

Entrypoint Rename Blast Radius (95 supervisor confs)

4 min read

Renaming any vuer entrypoint (server.js, cron.js, background.js, media.js, convert.js, integrationLog.js, storage.js) is a 4-repo coordinated release, not a single-repo edit. 95 supervisor conf files hard-code a command=node <entry>.js line, and only 7 of them live in the three code repos the change would touch. Two silent traps — logger.js argv sniffing and an 8th customization-only entrypoint — make a partial rename fail quietly. Mapped by FKITDEV-8387; useful for any entrypoint change, not just the TypeScript one.

For Agents

Before renaming or moving a vuer entrypoint file, assume it is spelled out by string in ~95 files across 4 repos (vuer_oss / vuer_css / portal_css + vuer_build + vuer-release + vuer_docker), plus a process.argv[1] sniff in logger.js, plus a bb/kh-only soap_server.js. A miss is a supervisord crash-loop for that partner — or worse, a silent logging / coverage regression.

Where command=node <entry>.js lives (95 files)

LocationFilesNotes
vuer_build/partner/<client>/…75across 35 partners
vuer-release/projects/<client>/components/…11Gen2 lean-format partners
vuer_docker/workspace/devtools/files/supervisor_{dev,docker}.conf2dev-box
the three code repos themselves7supervisor_vuer_oss_{dev,docker,e2e_test}.conf · supervisor_vuer_css_{dev,docker}.conf · supervisor_portal_css_{dev,docker}.conf

Any conf missed by a rename ⇒ supervisord crash-loop (exit code 2, restart every 1–2 s) for that partner. A March-2026 attempt at exactly this migration did that. Base-image Dockerfiles reference the supervisor conf filename, not the .js, so they are unaffected.

Silent trap 1: logger.js picks the log channel by process.argv[1]

vuer_oss/server/logger.js:102–114 chooses the log4js channel by sniffing the entrypoint filename:

process.argv[1].endsWith('server.js')        // → server channel
process.argv[1].endsWith('cron.js')          // → cron channel
// … background.js / media.js / convert.js / integrationLog.js

Rename an entrypoint and every one of its processes silently routes to the unknown channel. It fails quietly — no crash, just misfiled logs. This is also why the .ts-shim strategy in FKITDEV-8387 keeps process.argv[1] pointing at the original server.js shim (the shim requires server.ts).

Silent trap 2: the 8th entrypoint soap_server.js (bb/kh only)

There is an 8th entrypoint, soap_server.js, that exists only on the bb and kh vuer_oss customization branches (vuer_build/partner/{bb,kh}/vuer_oss/supervisor_vuer_oss_docker.conf:137). It is not on devel, so a rename planned from devel alone will miss it.

Silent trap 3: the soap_server.js suffix collision

The logger.js check is a suffix test, and 'soap_server.js'.endsWith('server.js') === true. So bb/kh’s SOAP entrypoint has been silently inheriting the vuer channel by accident — nobody wrote a rule for it. Renaming the main entrypoint to server.ts removes that accidental match and drops soap_server.js to the unknown channel, again with no error. Fix used in FKITDEV-8387:

process.argv[1].endsWith('server.ts') || process.argv[1].endsWith('soap_server.js')

General lesson

Suffix-matching entrypoint dispatch is fragile under rename. A suffix test matches any longer filename ending the same way, so the pre-rename behaviour may itself have been accidental — you cannot assume “it worked before, so preserving the string preserves the behaviour”. Enumerate every file whose name ends with the matched suffix before touching it.

Silent trap 4: the confs are not version-pinned to the app

Even a complete rename is not safe to merge on its own, because vuer_build partner overlay Dockerfiles COPY the supervisor conf unversioned from main on top of a version-pinned app image. Flipping the confs therefore breaks rebuilds of older release tags and breaks every partner branch that has not merged devel yet. Full write-up + mitigations: unversioned-partner-supervisor-overlays.

Implication

A literal .js → .ts (or any) entrypoint rename must land as a lockstep release of vuer_oss / vuer_css / portal_css plus vuer_build + vuer-release + vuer_docker, plus the bb/kh customization branches, plus a logger.js update.

Outcome (2026-07-22)

FKITDEV-8387 initially chose a decoupled .ts-module + one-line .js-shim approach to dodge all of this. That was reversed after review (vuer_oss PR #8059): the migration landed as a direct rename, command=node server.ts, no shims — 7 entrypoints in vuer_oss, 1 each in vuer_css/portal_css, 75 confs in vuer_build and 12 in vuer-release. So the full blast radius above was actually paid, and the remaining open risk is the release-sequencing one in unversioned-partner-supervisor-overlays.

Graph View

Backlinks