@antelopejs/dms-frontend 0.9.3 → 0.10.1

package/templates/vue/server/backend-request.mjs

@@ -0,0 +1,61 @@
+import { CLIENT_HEADERS, relayedHeaders } from "./auth/backend.mjs";
+import { forwardedHeaders } from "./auth/client-ip.mjs";
+import { readSession } from "./auth/session.mjs";
+import { backendResponseError } from "./backend-response.mjs";
+import { serverReads } from "./in-place-render.mjs";
+
+/**
+ * The headers of a backend request: the relayed client headers, the client's
+ * Origin and Referer as received, the `X-Forwarded-*` headers (set last, so no
+ * caller writes them), and the session's access token unless the request goes
+ * anonymously.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {{ anonymous: boolean, headers: readonly string[] }} [access]
+ * @returns {Record<string, string>}
+ */
+export function backendHeaders(
+  request,
+  access = { anonymous: false, headers: [] },
+) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    ...relayedHeaders(request, [
+      "accept",
+      "content-type",
+      "if-match",
+      "origin",
+      "referer",
+      ...CLIENT_HEADERS,
+      ...access.headers,
+    ]),
+    ...forwardedHeaders(request),
+  };
+  const session = access.anonymous ? undefined : readSession(request);
+  if (session?.accessToken)
+    headers.authorization = `Bearer ${session.accessToken}`;
+  return headers;
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {import("./in-place-render.mjs").ServerReads}
+ */
+export function serverComponentFetch(request) {
+  return serverReads(() => backendHeaders(request));
+}
+
+/**
+ * @param {string} path
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {Promise<unknown>}
+ */
+export async function backendJson(path, request) {
+  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
+    headers: backendHeaders(request),
+  });
+  if (!response.ok) {
+    throw await backendResponseError(response);
+  }
+  return response.json();
+}

package/templates/vue/server/backend-response.mjs

@@ -1,5 +1,6 @@
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
+import { isObjectLike, isString } from "./type-guards.mjs";
 
 /**
  * What a JSON caller gets when the backend fails: the generic i18n key of
@@ -18,6 +19,10 @@ const FORBIDDEN = 403;
 const FRONTEND_ORIGIN = "http://frontend.local";
 
 export class BackendResponseError extends Error {
+  /**
+   * @param {number} status
+   * @param {string | undefined} code The typed refusal code of the answer
+   */
   constructor(status, code) {
     super(`DMS backend returned ${status}`);
     this.status = status;
@@ -28,21 +33,28 @@ export class BackendResponseError extends Error {
 /**
  * The refusal code in a backend answer: the string or the `message` of its
  * JSON body, or the body itself when it is not JSON (a bare code).
+ *
+ * @param {Response} response
+ * @returns {Promise<string | undefined>}
  */
 async function refusalCode(response) {
   const text = (await response.text().catch(() => "")).trim();
   if (text.length > REFUSAL_CODE_MAX_LENGTH) return undefined;
+  /** @type {unknown} */
   let value = text;
   try {
+    /** @type {unknown} */
     const data = JSON.parse(text);
-    value = typeof data === "string" ? data : data?.message;
+    value = isObjectLike(data) ? data.message : data;
   } catch {}
-  return typeof value === "string" && REFUSAL_CODE.test(value)
-    ? value
-    : undefined;
+  return isString(value) && REFUSAL_CODE.test(value) ? value : undefined;
 }
 
-/** The error for a failed backend response, with its typed code if any. */
+/**
+ * The error for a failed backend response, with its typed code if any.
+ *
+ * @param {Response} response
+ */
 export async function backendResponseError(response) {
   return new BackendResponseError(response.status, await refusalCode(response));
 }
@@ -54,7 +66,11 @@ export async function backendResponseError(response) {
  * `loadRenderer` resolves. Only a same-origin path other than the refused one
  * qualifies: a refused destination sent to itself again would loop.
  *
- * @returns Whether the visit was redirected
+ * @param {unknown} error What the request failed with
+ * @param {import("./request-target.mjs").ServerRequest} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {() => Promise<typeof import("../ssr-renderer.ts")>} loadRenderer
+ * @returns {Promise<boolean>} Whether the visit was redirected
  */
 export async function redirectAccessRefusal(
   error,
@@ -69,6 +85,7 @@ export async function redirectAccessRefusal(
     !error.code
   )
     return false;
+  /** @type {string | undefined} */
   let location;
   try {
     location = (await loadRenderer()).accessRedirect?.(error.code);

package/templates/vue/server/built-files.mjs

@@ -14,6 +14,9 @@ const PUBLIC_DOT_DIRECTORY = ".well-known";
  * source path of every module file), and a module's `public/` may hold dot
  * files too. `/.well-known/`, which RFC 8615 reserves for files meant to be
  * public, stays served.
+ *
+ * @param {string} relativePath
+ * @returns {boolean}
  */
 export function isPublicBuildPath(relativePath) {
   return relativePath
@@ -33,6 +36,10 @@ export function isPublicBuildPath(relativePath) {
  *
  * The prefix uses the native separator: `resolve` answers with backslashes on
  * Windows.
+ *
+ * @param {string} root
+ * @param {string} pathname
+ * @returns {string | undefined}
  */
 export function publicBuildFile(root, pathname) {
   let decoded;

package/templates/vue/server/cli-report.mjs

@@ -1,12 +1,23 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { stripVTControlCharacters } from "node:util";
+import { isNumber, isObjectLike, isRecord, isString } from "./type-guards.mjs";
 
 const WILDCARD_ADDRESSES = ["0.0.0.0", "::"];
 
+/**
+ * @param {import("node:child_process").Serializable} message
+ * @param {string} line
+ * @param {(line: string) => void} write
+ * @returns {Promise<void>}
+ */
 async function report(message, line, write) {
   if (!process.send) return write(line);
-  await new Promise((sent) => process.send(message, () => sent()));
+  /** @type {Promise<void>} */
+  const sent = new Promise((resolve) =>
+    process.send?.(message, () => resolve()),
+  );
+  await sent;
 }
 
 /**
@@ -15,6 +26,10 @@ async function report(message, line, write) {
  * What the server tells whoever started it. Started by `ajs dms dev` or `ajs
  * dms start`, it reports over IPC and the CLI words what the user reads.
  * Started on its own, it prints the line itself.
+ *
+ * @param {string} address
+ * @param {number} port
+ * @returns {Promise<void>}
  */
 export async function reportReady(address, port) {
   const host = WILDCARD_ADDRESSES.includes(address)
@@ -29,10 +44,32 @@ export async function reportReady(address, port) {
   );
 }
 
+/** The `ANTELOPEJS_QUIET` values that leave a run verbose, as `@antelopejs/core` reads them. */
+const DISABLED_FLAG_VALUES = ["0", "false"];
+
+/**
+ * Prints the routing summary, unless the run is quiet: `-q` given to `ajs` or
+ * `ajs dms` reaches the server as `ANTELOPEJS_QUIET`, and a quiet ready server
+ * prints only its `Local` url.
+ *
+ * @param {readonly string[]} lines What `routingReport` returned
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function reportRouting(lines, env = process.env) {
+  const quiet = env.ANTELOPEJS_QUIET;
+  if (quiet && !DISABLED_FLAG_VALUES.includes(quiet.toLowerCase())) return;
+  for (const line of lines) console.log(line);
+}
+
 /**
  * The server cannot listen: a port taken by another process, an address this
  * host does not have. Reported instead of Node's unhandled-error dump, then
  * the server exits.
+ *
+ * @param {NodeJS.ErrnoException} error
+ * @param {string} host
+ * @param {number} port
+ * @returns {Promise<void>}
  */
 export async function reportListenError(error, host, port) {
   await report(
@@ -52,31 +89,46 @@ export async function reportListenError(error, host, port) {
 /** The `[PARSE_ERROR] ` Rolldown puts in front of what it says. */
 const RULE_PREFIX = /^\[[A-Z_]+\]\s*/;
 
-/** The first problem Rolldown reports when it cannot bundle a config. */
+/**
+ * The first problem Rolldown reports when it cannot bundle a config.
+ *
+ * @param {unknown} error What the startup threw
+ */
 function bundlerError(error) {
-  const first = error?.errors?.[0];
-  return first && typeof first === "object" ? first : undefined;
+  const errors = isObjectLike(error) ? error.errors : undefined;
+  const first = isObjectLike(errors) ? errors[0] : undefined;
+  return isRecord(first) ? first : undefined;
 }
 
 /**
  * Where a startup error points, when it says: Rolldown's location for a config
  * it could not bundle (the line is read back from the file, which Rolldown
  * only draws in a colored frame), Rollup's for a plugin that failed on a file.
+ *
+ * @param {unknown} error What the startup threw
  */
 function errorLocation(error) {
-  const source = bundlerError(error) ?? error;
-  const file = source?.loc?.file ?? source?.id;
-  if (typeof file !== "string") return undefined;
-  const { line, column } = source.loc ?? {};
+  const source =
+    bundlerError(error) ?? (isObjectLike(error) ? error : undefined);
+  const loc = isObjectLike(source?.loc) ? source.loc : undefined;
+  const file = loc?.file ?? source?.id;
+  if (!isString(file)) return undefined;
+  const line = isNumber(loc?.line) ? loc.line : undefined;
   return {
     file: resolve(file),
     line,
-    column,
+    column: isNumber(loc?.column) ? loc.column : undefined,
     lineText: line === undefined ? undefined : readLine(file, line),
   };
 }
 
-/** Line `line` (1-based) of `file`, `undefined` when it cannot be read. */
+/**
+ * Line `line` (1-based) of `file`, `undefined` when it cannot be read.
+ *
+ * @param {string} file
+ * @param {number} line
+ * @returns {string | undefined}
+ */
 function readLine(file, line) {
   try {
     return readFileSync(file, "utf8").split(/\r?\n/)[line - 1];
@@ -85,7 +137,11 @@ function readLine(file, line) {
   }
 }
 
-/** The first line of what went wrong, without Rolldown's rule and frame. */
+/**
+ * The first line of what went wrong, without Rolldown's rule and frame.
+ *
+ * @param {unknown} error What the startup threw
+ */
 function errorText(error) {
   const reported = bundlerError(error);
   const message = reported
@@ -101,6 +157,8 @@ function errorText(error) {
 /**
  * Vite could not start, so no page can be served: the error and where it
  * points instead of a stack trace, then the server exits.
+ *
+ * @param {unknown} error What the startup threw
  */
 export async function reportStartError(error) {
   const message = errorText(error);
@@ -109,7 +167,12 @@ export async function reportStartError(error) {
     ? `${location.file}${location.line ? `:${location.line}:${location.column ?? 0}` : ""}: `
     : "";
   await report(
-    { type: "dms:start-error", message, code: error?.code, location },
+    {
+      type: "dms:start-error",
+      message,
+      code: isObjectLike(error) ? error.code : undefined,
+      location,
+    },
     `DMS development server failed to start: ${where}${message}`,
     console.error,
   );

package/templates/vue/server/client-error.mjs

@@ -11,6 +11,7 @@ const HEADER_OVERFLOW_HINT_INTERVAL_MS = 60_000;
 
 let lastHeaderOverflowHint = -Infinity;
 
+/** @param {number} maxHeaderSize */
 function warnHeaderOverflow(maxHeaderSize) {
   const now = Date.now();
   if (now - lastHeaderOverflowHint < HEADER_OVERFLOW_HINT_INTERVAL_MS) return;
@@ -32,6 +33,10 @@ function warnHeaderOverflow(maxHeaderSize) {
  *
  * Once a response went out on this connection, a status line would land in the
  * middle of it.
+ *
+ * @param {NodeJS.ErrnoException} error
+ * @param {import("node:stream").Duplex & { bytesWritten?: number }} socket
+ * @param {number} maxHeaderSize
  */
 export function handleClientError(error, socket, maxHeaderSize) {
   let response = BAD_REQUEST_RESPONSE;

package/templates/vue/server/client-manifest.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { viteManifestOf } from "./generated-files.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../", import.meta.url));
 const BUILT_TEMPLATE_PATH = join(PROJECT_ROOT, "dist/client/index.html");
@@ -14,7 +15,9 @@ const SOURCE_TEMPLATE_PATH = join(PROJECT_ROOT, "index.html");
  * Read once and kept: both files are build output and cannot change while
  * the server is up.
  */
+/** @type {import("vite").Manifest | undefined} */
 let clientManifest;
+/** @type {string | undefined} */
 let productionTemplate;
 
 /**
@@ -31,13 +34,22 @@ export function productionHtmlTemplate() {
   return productionTemplate;
 }
 
+/** @returns {import("vite").Manifest | undefined} */
 function productionClientManifest() {
   if (clientManifest) return clientManifest;
   if (!existsSync(CLIENT_MANIFEST_PATH)) return undefined;
-  clientManifest = JSON.parse(readFileSync(CLIENT_MANIFEST_PATH, "utf8"));
+  clientManifest = viteManifestOf(
+    JSON.parse(readFileSync(CLIENT_MANIFEST_PATH, "utf8")),
+  );
   return clientManifest;
 }
 
+/**
+ * @param {import("vite").Manifest} manifest
+ * @param {string} key
+ * @param {Set<string>} styles
+ * @param {Set<string>} visited
+ */
 function collectManifestStyles(manifest, key, styles, visited) {
   if (visited.has(key)) return;
   visited.add(key);
@@ -56,11 +68,16 @@ function collectManifestStyles(manifest, key, styles, visited) {
  * component, so the lookup needs no guessing from names. A component bundled
  * into another chunk is no key of its own: its stylesheet comes with that
  * chunk's, reached through the `imports` of the component that loaded it.
+ *
+ * @param {Iterable<string>} [modules]
+ * @returns {Set<string>}
  */
 function renderedModuleStyles(modules = []) {
   const manifest = productionClientManifest();
+  /** @type {Set<string>} */
   const styles = new Set();
   if (!manifest) return styles;
+  /** @type {Set<string>} */
   const visited = new Set();
   for (const id of modules)
     collectManifestStyles(manifest, id, styles, visited);
@@ -72,6 +89,9 @@ function renderedModuleStyles(modules = []) {
  * template does not link already, so that none of them waits for its chunk's
  * JavaScript to arrive: the HTML would otherwise paint unstyled and shift once
  * it does. A component the render did not reach gets no link.
+ *
+ * @param {Iterable<string> | undefined} modules
+ * @param {string} template
  */
 export function renderedModuleStyleTags(modules, template) {
   return [...renderedModuleStyles(modules)]
@@ -85,6 +105,8 @@ export function renderedModuleStyleTags(modules, template) {
  * rendered with: the browser fetches it next to the entry rather than once the
  * entry runs and asks for it, which would put a round trip before hydration.
  * Nothing without a production build (Vite serves the sources in development).
+ *
+ * @param {string | undefined} locale
  */
 export function localeCatalogPreloadTag(locale) {
   const manifest = productionClientManifest();

package/templates/vue/server/content.mjs

@@ -11,15 +11,16 @@ export const MINIMUM_COMPRESSION_BYTES = 1_024;
 const DYNAMIC_BROTLI_QUALITY = 4;
 
 /**
- * A compressor for a body generated or relayed now, in the encoding the client
- * accepts (Brotli first), or `undefined` when it accepts neither. `streaming`
- * flushes what each write gives at once, for a body written over time: the
- * client gets each part when it is written, not when a block fills.
+ * The codings among `br` and `gzip` the client accepts, most wanted first
+ * (Brotli on a tie). Empty when it accepts neither, or ranks identity above
+ * both: implicit identity is a fallback, not a preference over compression.
  *
- * Implicit identity is a fallback, not a preference over compression.
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {("br" | "gzip")[]}
  */
-export function acceptedEncoder(request, { streaming = false } = {}) {
+export function acceptedCodings(request) {
   const accepted = request.headers["accept-encoding"] ?? "";
+  /** @type {Map<string, number>} */
   const qualities = new Map();
   for (const entry of accepted.split(",")) {
     const [token, ...parameters] = entry.trim().toLowerCase().split(";");
@@ -37,12 +38,29 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
       Math.min(qualities.get(token.trim()) ?? 1, quality),
     );
   }
+  /** @param {string} token */
   const quality = (token) => qualities.get(token) ?? qualities.get("*") ?? 0;
   const br = quality("br");
   const gzip = quality("gzip");
   const identity = qualities.get("identity") ?? 0;
-  if (identity > Math.max(br, gzip)) return undefined;
-  if (br > 0 && br >= gzip)
+  if (identity > Math.max(br, gzip)) return [];
+  /** @type {("br" | "gzip")[]} */
+  const ranked = gzip > br ? ["gzip", "br"] : ["br", "gzip"];
+  return ranked.filter((coding) => quality(coding) > 0);
+}
+
+/**
+ * A compressor for a body generated or relayed now, in the encoding the client
+ * wants most (see `acceptedCodings`), or `undefined` when it accepts neither.
+ * `streaming` flushes what each write gives at once, for a body written over
+ * time: the client gets each part when it is written, not when a block fills.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {{ streaming?: boolean }} [options]
+ */
+export function acceptedEncoder(request, { streaming = false } = {}) {
+  const [coding] = acceptedCodings(request);
+  if (coding === "br")
     return {
       encoding: "br",
       stream: createBrotliCompress({
@@ -52,7 +70,7 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
         },
       }),
     };
-  if (gzip > 0)
+  if (coding === "gzip")
     return {
       encoding: "gzip",
       stream: createGzip(
@@ -61,12 +79,24 @@ export function acceptedEncoder(request, { streaming = false } = {}) {
     };
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string | Buffer} content
+ */
 function responseEncoder(request, content) {
   if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
   return acceptedEncoder(request);
 }
 
-/** Send a generated body, compressed when the client accepts it. */
+/**
+ * Send a generated body, compressed when the client accepts it.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {number} status
+ * @param {import("node:http").OutgoingHttpHeaders} headers
+ * @param {string | Buffer} content
+ */
 export async function writeContent(
   request,
   response,

package/templates/vue/server/dev-private-files.mjs

@@ -28,6 +28,10 @@ export const DEV_FS_DENY = [
  * file, a module's server entry, or a file under a `server/` directory of a
  * module materialized under `root`. Compared without case, as a
  * case-insensitive file system would serve them.
+ *
+ * @param {string} file
+ * @param {string} root
+ * @returns {boolean}
  */
 export function isPrivateFile(file, root) {
   const name = (resolve(file).split(/[\\/]/).at(-1) ?? "").toLowerCase();
@@ -39,12 +43,22 @@ export function isPrivateFile(file, root) {
   );
 }
 
+/**
+ * @param {string} id
+ * @returns {string}
+ */
 function stripQuery(id) {
   const query = id.search(/[?#]/);
   return query === -1 ? id : id.slice(0, query);
 }
 
-/** The file a request URL names under `root`, `undefined` when it names none. */
+/**
+ * The file a request URL names under `root`, `undefined` when it names none.
+ *
+ * @param {string | undefined} url
+ * @param {string} root
+ * @returns {string | undefined}
+ */
 function requestedFile(url, root) {
   let pathname;
   try {
@@ -74,6 +88,8 @@ function requestedFile(url, root) {
  *
  * The middleware is registered directly, not returned: it runs before Vite's
  * middlewares.
+ *
+ * @returns {import("vite").Plugin}
  */
 export function denyPrivateFiles() {
   let root = process.cwd();

package/templates/vue/server/dev-styles.mjs

@@ -8,6 +8,13 @@ const SFC_STYLE = /[?&]vue&type=style/;
 const STYLE_EXTENSION =
   /\.(?:css|less|pcss|postcss|sass|scss|styl|stylus)(?:$|\?)/;
 
+/**
+ * A stylesheet module of the development server's graph: its URL, and the id
+ * its tag is matched by.
+ *
+ * @typedef {{ url: string, id: string }} StyleModule
+ */
+
 /**
  * The workspace's generated entry stylesheet. `main.ts` is its only importer,
  * so it never enters the SSR module graph, yet it carries Tailwind, Nuxt UI and
@@ -25,6 +32,16 @@ const ENTRY_STYLESHEET_ID = join(PROJECT_ROOT, "dms-main.css")
   .split(sep)
   .join("/");
 
+/**
+ * @typedef {{ urlToModuleMap: ReadonlyMap<string, { id: string | null } | undefined> }} StyleGraph
+ * @typedef {{
+ *   environments?: { ssr?: { moduleGraph?: StyleGraph } },
+ *   moduleGraph?: StyleGraph,
+ *   transformRequest(url: string): Promise<{ code: string } | null>,
+ * }} StyleServer
+ */
+
+/** @param {StyleServer} devServer */
 function ssrModuleGraph(devServer) {
   return devServer.environments?.ssr?.moduleGraph ?? devServer.moduleGraph;
 }
@@ -39,6 +56,10 @@ function ssrModuleGraph(devServer) {
  */
 const TRAILING_LANG = /&(lang\.[^&?]*)$/;
 
+/**
+ * @param {string} url
+ * @returns {string}
+ */
 function directUrl(url) {
   if (SFC_STYLE.test(url) && TRAILING_LANG.test(url)) {
     return url.replace(TRAILING_LANG, "&direct&$1");
@@ -46,6 +67,10 @@ function directUrl(url) {
   return `${url}${url.includes("?") ? "&" : "?"}direct`;
 }
 
+/**
+ * @param {StyleServer} devServer
+ * @returns {StyleModule[]}
+ */
 function styleModules(devServer) {
   const graph = ssrModuleGraph(devServer);
   if (!graph) return [];
@@ -54,6 +79,7 @@ function styleModules(devServer) {
     .map(([url, module]) => ({ url, id: module?.id ?? url }));
 }
 
+/** @param {StyleModule} module */
 function linkTag({ url, id }) {
   return `<link rel="stylesheet" ${STYLE_ATTRIBUTE}="${id}" href="${directUrl(url)}">`;
 }
@@ -64,6 +90,10 @@ function linkTag({ url, id }) {
  * stylesheet. They are small; inline them instead. A block that could close its
  * own tag is dropped rather than escaped — CSS has no escape that is valid in
  * every position, and a scoped component rule is not worth the risk.
+ *
+ * @param {StyleServer} devServer
+ * @param {StyleModule} module
+ * @returns {Promise<string>}
  */
 async function inlineTag(devServer, { url, id }) {
   const result = await devServer
@@ -87,6 +117,9 @@ async function inlineTag(devServer, { url, id }) {
  * stylesheet, which is why this module is development-only and lives beside
  * client-manifest.mjs rather than inside server.mjs, whose size the linter
  * caps.
+ *
+ * @param {StyleServer} devServer
+ * @returns {Promise<string>}
  */
 export async function developmentStyleTags(devServer) {
   const modules = styleModules(devServer);
@@ -106,6 +139,11 @@ export async function developmentStyleTags(devServer) {
  * The style tags a document needs, whichever server is answering it: collected
  * from the live module graph in development, read from the build manifest for
  * the components the render created (`modules`) in production.
+ *
+ * @param {import("vite").ViteDevServer | undefined} devServer
+ * @param {Iterable<string> | undefined} modules
+ * @param {string} template
+ * @returns {Promise<string>}
  */
 export async function documentStyleTags(devServer, modules, template) {
   return devServer

package/templates/vue/server/email-bundle-watch.mjs

@@ -1,13 +1,15 @@
 import { fileURLToPath } from "node:url";
 import { build } from "vite";
+import { isObjectLike } from "./type-guards.mjs";
 
 const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
 process.on("disconnect", () => process.exit(0));
 
+/** @type {(() => void) | undefined} */
 let startBuild;
 process.on("message", (message) => {
-  if (message?.state !== "build") return;
+  if (!isObjectLike(message) || message.state !== "build") return;
   startBuild?.();
   startBuild = undefined;
 });
@@ -17,10 +19,12 @@ const serverHandoff = {
   name: "dms-email-bundle-handoff",
   buildStart() {
     if (!process.send) return;
-    return new Promise((start) => {
+    /** @type {Promise<void>} */
+    const held = new Promise((start) => {
       startBuild = start;
-      process.send({ state: "building" });
+      process.send?.({ state: "building" });
     });
+    return held;
   },
 };
 
@@ -34,6 +38,8 @@ const watcher = await build({
   build: { watch: {} },
 });
 
+if (!("on" in watcher))
+  throw new TypeError("The email bundle build did not start a watcher");
 watcher.on("event", (event) => {
   if (event.code === "END") process.send?.({ state: "ready" });
   else if (event.code === "ERROR") process.send?.({ state: "failed" });