Summary
scripts/register-selfhost.mjs's own header comment claims it is used as the Docker entrypoint via node --import ./scripts/register-selfhost.mjs dist/server.mjs, but the actual Dockerfile CMD (Dockerfile:68) is CMD ["node", "dist/server.mjs"] with no --import flag, and no script/test/package.json entry/CI workflow step invokes it that way. This looks like a runtime-hook approach that was superseded by build-time stubbing and never had its stale comment (or itself) cleaned up.
Part of #1667.
Context
Found during a 2026-07-04 audit. The functionality the script claims to provide — stubbing cloudflare:* specifiers at runtime via Node's module hooks — is already handled at build time by scripts/build-selfhost.mjs's esbuild plugin (onResolve for cloudflare:workers, @cloudflare/puppeteer, agents/mcp, around lines 47-49), which bakes Node-safe stubs directly into dist/server.mjs. The script's only other repo reference is a path filter in .github/workflows/selfhost.yml (lines 16, 29) that triggers the workflow when the file changes — not an actual runtime use.
Requirements
- Confirm, before removing anything: (a) no external/undocumented deploy path (any maintainer runbook,
docs/self-hosting-release-checklist-style doc, or a partner/customer's own launch script referenced from repo docs) still expects --import ./scripts/register-selfhost.mjs, and (b) the build-time esbuild stub plugin actually covers every specifier this runtime hook covered — it currently stubs 3 named specifiers vs. this hook's blanket cloudflare:* prefix match. Grep the full dependency graph (including any newly-added dependency since the audit) for any other cloudflare:* import that only the runtime hook was catching.
- If confirmed fully redundant: remove
scripts/register-selfhost.mjs, update .github/workflows/selfhost.yml's path filter accordingly, and check for any other reference (docs, comments) claiming this is the entrypoint.
- If NOT confirmed redundant (i.e., some specifier really does need the blanket runtime hook): keep the script, but fix its stale header comment to describe how it's actually invoked today, and file a follow-up to either wire it into the Dockerfile CMD for real or migrate the missing specifier(s) into the build-time stub list.
Deliverables
- A PR that either deletes the script + its stale workflow reference (with the verification above documented in the PR description), or corrects the script's documentation and wires it in for real.
- If removed, a smoke-test run (
npm run smoke-selfhost or equivalent) confirming the Docker image still boots cleanly without it.
Expected outcome
scripts/register-selfhost.mjs either has a real, correct, exercised runtime role, or it's gone — no script sits in the repo describing a Docker entrypoint wiring that doesn't actually exist.
Summary
scripts/register-selfhost.mjs's own header comment claims it is used as the Docker entrypoint vianode --import ./scripts/register-selfhost.mjs dist/server.mjs, but the actualDockerfileCMD (Dockerfile:68) isCMD ["node", "dist/server.mjs"]with no--importflag, and no script/test/package.json entry/CI workflow step invokes it that way. This looks like a runtime-hook approach that was superseded by build-time stubbing and never had its stale comment (or itself) cleaned up.Part of #1667.
Context
Found during a 2026-07-04 audit. The functionality the script claims to provide — stubbing
cloudflare:*specifiers at runtime via Node's module hooks — is already handled at build time byscripts/build-selfhost.mjs's esbuild plugin (onResolveforcloudflare:workers,@cloudflare/puppeteer,agents/mcp, around lines 47-49), which bakes Node-safe stubs directly intodist/server.mjs. The script's only other repo reference is a path filter in.github/workflows/selfhost.yml(lines 16, 29) that triggers the workflow when the file changes — not an actual runtime use.Requirements
docs/self-hosting-release-checklist-style doc, or a partner/customer's own launch script referenced from repo docs) still expects--import ./scripts/register-selfhost.mjs, and (b) the build-time esbuild stub plugin actually covers every specifier this runtime hook covered — it currently stubs 3 named specifiers vs. this hook's blanketcloudflare:*prefix match. Grep the full dependency graph (including any newly-added dependency since the audit) for any othercloudflare:*import that only the runtime hook was catching.scripts/register-selfhost.mjs, update.github/workflows/selfhost.yml's path filter accordingly, and check for any other reference (docs, comments) claiming this is the entrypoint.Deliverables
npm run smoke-selfhostor equivalent) confirming the Docker image still boots cleanly without it.Expected outcome
scripts/register-selfhost.mjseither has a real, correct, exercised runtime role, or it's gone — no script sits in the repo describing a Docker entrypoint wiring that doesn't actually exist.