@jsenv/core 40.0.7 → 40.0.9

package/dist/{plugins.js → start_dev_server/start_dev_server.js}

@@ -1,13 +1,21 @@
-import { lookupPackageDirectory, registerDirectoryLifecycle, urlToRelativeUrl, createDetailedMessage, stringifyUrlSite, generateContentFrame, validateResponseIntegrity, urlIsInsideOf, ensureWindowsDriveLetter, setUrlFilename, moveUrl, getCallerPosition, urlToBasename, urlToExtension, asSpecifierWithoutSearch, asUrlWithoutSearch, injectQueryParamsIntoSpecifier, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, urlToFileSystemPath, writeFileSync, createLogger, URL_META, normalizeUrl, ANSI, CONTENT_TYPE, DATA_URL, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, readCustomConditionsFromProcessArgs, applyNodeEsmResolution, defaultLookupPackageScope, defaultReadPackageJson, readEntryStatSync, urlToFilename, ensurePathnameTrailingSlash, comparePathnames, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, jsenvPluginTranspilation } from "./jsenv_core_packages.js";
+import { lookupPackageDirectory, registerDirectoryLifecycle, urlToRelativeUrl, moveUrl, urlIsInsideOf, ensureWindowsDriveLetter, createDetailedMessage, stringifyUrlSite, generateContentFrame, validateResponseIntegrity, setUrlFilename, getCallerPosition, urlToBasename, urlToExtension, asSpecifierWithoutSearch, asUrlWithoutSearch, injectQueryParamsIntoSpecifier, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, urlToFileSystemPath, writeFileSync, createLogger, URL_META, applyNodeEsmResolution, normalizeUrl, ANSI, CONTENT_TYPE, DATA_URL, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, readCustomConditionsFromProcessArgs, defaultLookupPackageScope, defaultReadPackageJson, readEntryStatSync, urlToFilename, ensurePathnameTrailingSlash, comparePathnames, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, jsenvPluginTranspilation, memoizeByFirstArgument, assertAndNormalizeDirectoryUrl, createTaskLog } from "../jsenv_core_packages.js";
+import { WebSocketResponse, pickContentType, ServerEvents, jsenvServiceCORS, jsenvAccessControlAllowedHeaders, composeTwoResponses, serveDirectory, jsenvServiceErrorHandler, startServer } from "@jsenv/server";
+import { convertFileSystemErrorToResponseProperties } from "@jsenv/server/src/internal/convertFileSystemErrorToResponseProperties.js";
+import { readFileSync, existsSync, readdirSync, lstatSync, realpathSync } from "node:fs";
 import { RUNTIME_COMPAT } from "@jsenv/runtime-compat";
+import { pathToFileURL } from "node:url";
 import { generateSourcemapFileUrl, createMagicSource, composeTwoSourcemaps, generateSourcemapDataUrl, SOURCEMAP } from "@jsenv/sourcemap";
 import { parseHtml, injectHtmlNodeAsEarlyAsPossible, createHtmlNode, stringifyHtmlAst, applyBabelPlugins, generateUrlForInlineContent, parseJsWithAcorn, parseCssUrls, getHtmlNodeAttribute, getHtmlNodePosition, getHtmlNodeAttributePosition, setHtmlNodeAttributes, parseSrcSet, getUrlForContentInsideHtml, removeHtmlNodeText, setHtmlNodeText, getHtmlNodeText, analyzeScriptNode, visitHtmlNodes, parseJsUrls, getUrlForContentInsideJs, analyzeLinkNode, injectJsenvScript } from "@jsenv/ast";
-import { pathToFileURL } from "node:url";
 import { performance } from "node:perf_hooks";
-import { readFileSync, existsSync, readdirSync, lstatSync, realpathSync } from "node:fs";
 import { jsenvPluginSupervisor } from "@jsenv/plugin-supervisor";
-import { WebSocketResponse, pickContentType } from "@jsenv/server";
-import { replacePlaceholders as replacePlaceholders$1, INJECTIONS, jsenvPluginInjections } from "./main.js";
+import { createRequire } from "node:module";
+import "string-width";
+import "node:process";
+import "node:os";
+import "node:tty";
+import "node:path";
+import "node:crypto";
+import "@jsenv/js-module-fallback";
 
 // default runtimeCompat corresponds to
 // "we can keep <script type="module"> intact":
@@ -22,13 +30,6 @@ const defaultRuntimeCompat = {
   safari: "11.3",
   samsung: "9.2",
 };
-const logsDefault = {
-  level: "info",
-  disabled: false,
-  animation: true,
-};
-const getDefaultBase = (runtimeCompat) =>
-  runtimeCompat.node ? "./" : "/";
 
 const createEventEmitter = () => {
   const callbackSet = new Set();
@@ -162,7 +163,33 @@ const watchSourceFiles = (
   return watch();
 };
 
-const jsenvCoreDirectoryUrl = new URL("./", import.meta.url);
+const WEB_URL_CONVERTER = {
+  asWebUrl: (fileUrl, webServer) => {
+    if (urlIsInsideOf(fileUrl, webServer.rootDirectoryUrl)) {
+      return moveUrl({
+        url: fileUrl,
+        from: webServer.rootDirectoryUrl,
+        to: `${webServer.origin}/`,
+      });
+    }
+    const fsRootUrl = ensureWindowsDriveLetter("file:///", fileUrl);
+    return `${webServer.origin}/@fs/${fileUrl.slice(fsRootUrl.length)}`;
+  },
+  asFileUrl: (webUrl, webServer) => {
+    const { pathname, search } = new URL(webUrl);
+    if (pathname.startsWith("/@fs/")) {
+      const fsRootRelativeUrl = pathname.slice("/@fs/".length);
+      return `file:///${fsRootRelativeUrl}${search}`;
+    }
+    return moveUrl({
+      url: webUrl,
+      from: `${webServer.origin}/`,
+      to: webServer.rootDirectoryUrl,
+    });
+  },
+};
+
+const jsenvCoreDirectoryUrl = new URL("../", import.meta.url);
 
 const createResolveUrlError = ({
   pluginController,
@@ -568,6 +595,7 @@ const determineSourcemapFileUrl = (urlInfo) => {
   generatedUrlObject.searchParams.delete("as_json_module");
   generatedUrlObject.searchParams.delete("as_text_module");
   generatedUrlObject.searchParams.delete("dynamic_import");
+  generatedUrlObject.searchParams.delete("dynamic_import_id");
   generatedUrlObject.searchParams.delete("cjs_as_js_module");
   const urlForSourcemap = generatedUrlObject.href;
   return generateSourcemapFileUrl(urlForSourcemap);
@@ -2637,7 +2665,7 @@ const shouldHandleSourcemap = (urlInfo) => {
 };
 
 const inlineContentClientFileUrl = new URL(
-  "./client/inline_content/inline_content.js",
+  "../client/inline_content/inline_content.js",
   import.meta.url,
 ).href;
 
@@ -2668,6 +2696,9 @@ const createKitchen = ({
 }) => {
   const logger = createLogger({ logLevel });
 
+  const nodeRuntimeEnabled = Object.keys(runtimeCompat).includes("node");
+  const packageConditions = [nodeRuntimeEnabled ? "node" : "browser", "import"];
+
   const kitchen = {
     context: {
       ...initialContext,
@@ -2687,6 +2718,14 @@ const createKitchen = ({
       sourcemaps,
       outDirectoryUrl,
     },
+    resolve: (specifier, importer) => {
+      const { url, packageDirectoryUrl, packageJson } = applyNodeEsmResolution({
+        conditions: packageConditions,
+        parentUrl: importer,
+        specifier,
+      });
+      return { url, packageDirectoryUrl, packageJson };
+    },
     graph: null,
     urlInfoTransformer: null,
     pluginController: null,
@@ -3339,7 +3378,7 @@ const inferUrlInfoType = (urlInfo) => {
 
 const jsenvPluginHtmlSyntaxErrorFallback = () => {
   const htmlSyntaxErrorFileUrl = import.meta.resolve(
-    "./client/html_syntax_error/html_syntax_error.html",
+    "../client/html_syntax_error/html_syntax_error.html",
   );
 
   return {
@@ -3406,7 +3445,7 @@ const generateHtmlForSyntaxError = (
     errorLinkText: `${htmlRelativeUrl}:${line}:${column}`,
     syntaxError: escapeHtml(htmlErrorContentFrame),
   };
-  const html = replacePlaceholders(htmlForSyntaxError, replacers);
+  const html = replacePlaceholders$1(htmlForSyntaxError, replacers);
   return html;
 };
 const escapeHtml = (string) => {
@@ -3417,7 +3456,7 @@ const escapeHtml = (string) => {
     .replace(/"/g, "&quot;")
     .replace(/'/g, "&#039;");
 };
-const replacePlaceholders = (html, replacers) => {
+const replacePlaceholders$1 = (html, replacers) => {
   return html.replace(/\$\{(\w+)\}/g, (match, name) => {
     const replacer = replacers[name];
     if (replacer === undefined) {
@@ -4330,7 +4369,12 @@ const jsenvPluginHtmlReferenceAnalysis = ({
                   });
                 } else {
                   setHtmlNodeText(node, inlineUrlInfo.content, {
-                    indentation: false, // indentation would decrease stack trace precision
+                    indentation:
+                      inlineUrlInfo.type === "js_classic" ||
+                      inlineUrlInfo.type === "js_module"
+                        ? // indentation would mess with stack trace and sourcemap
+                          false
+                        : "auto",
                   });
                   setHtmlNodeAttributes(node, {
                     "jsenv-cooked-by": "jsenv:html_inline_content_analysis",
@@ -5425,6 +5469,103 @@ const FILE_AND_SERVER_URLS_CONVERTER = {
   },
 };
 
+const jsenvPluginInjections = (rawAssociations) => {
+  let resolvedAssociations;
+
+  return {
+    name: "jsenv:injections",
+    appliesDuring: "*",
+    init: (context) => {
+      resolvedAssociations = URL_META.resolveAssociations(
+        { injectionsGetter: rawAssociations },
+        context.rootDirectoryUrl,
+      );
+    },
+    transformUrlContent: async (urlInfo) => {
+      const { injectionsGetter } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations,
+      });
+      if (!injectionsGetter) {
+        return null;
+      }
+      if (typeof injectionsGetter !== "function") {
+        throw new TypeError("injectionsGetter must be a function");
+      }
+      const injections = await injectionsGetter(urlInfo);
+      if (!injections) {
+        return null;
+      }
+      const keys = Object.keys(injections);
+      if (keys.length === 0) {
+        return null;
+      }
+      return replacePlaceholders(urlInfo.content, injections, urlInfo);
+    },
+  };
+};
+
+const injectionSymbol = Symbol.for("jsenv_injection");
+const INJECTIONS = {
+  optional: (value) => {
+    return { [injectionSymbol]: "optional", value };
+  },
+};
+
+// we export this because it is imported by jsenv_plugin_placeholder.js and unit test
+const replacePlaceholders = (content, replacements, urlInfo) => {
+  const magicSource = createMagicSource(content);
+  for (const key of Object.keys(replacements)) {
+    let index = content.indexOf(key);
+    const replacement = replacements[key];
+    let isOptional;
+    let value;
+    if (replacement && replacement[injectionSymbol]) {
+      const valueBehindSymbol = replacement[injectionSymbol];
+      isOptional = valueBehindSymbol === "optional";
+      value = replacement.value;
+    } else {
+      value = replacement;
+    }
+    if (index === -1) {
+      if (!isOptional) {
+        urlInfo.context.logger.warn(
+          `placeholder "${key}" not found in ${urlInfo.url}.
+--- suggestion a ---
+Add "${key}" in that file.
+--- suggestion b ---
+Fix eventual typo in "${key}"?
+--- suggestion c ---
+Mark injection as optional using INJECTIONS.optional():
+import { INJECTIONS } from "@jsenv/core";
+
+return {
+  "${key}": INJECTIONS.optional(${JSON.stringify(value)}),
+};`,
+        );
+      }
+      continue;
+    }
+
+    while (index !== -1) {
+      const start = index;
+      const end = index + key.length;
+      magicSource.replace({
+        start,
+        end,
+        replacement:
+          urlInfo.type === "js_classic" ||
+          urlInfo.type === "js_module" ||
+          urlInfo.type === "html"
+            ? JSON.stringify(value, null, "  ")
+            : value,
+      });
+      index = content.indexOf(key, end);
+    }
+  }
+  return magicSource.toContentAndSourcemap();
+};
+
 /*
  * NICE TO HAVE:
  * 
@@ -5451,7 +5592,7 @@ const FILE_AND_SERVER_URLS_CONVERTER = {
 
 
 const htmlFileUrlForDirectory = import.meta.resolve(
-  "./client/directory_listing/directory_listing.html",
+  "../client/directory_listing/directory_listing.html",
 );
 
 const jsenvPluginDirectoryListing = ({
@@ -5533,7 +5674,7 @@ const jsenvPluginDirectoryListing = ({
         }
         const request = urlInfo.context.request;
         const { rootDirectoryUrl, mainFilePath } = urlInfo.context;
-        return replacePlaceholders$1(
+        return replacePlaceholders(
           urlInfo.content,
           {
             ...generateDirectoryListingInjection(requestedUrl, {
@@ -6143,6 +6284,12 @@ const jsenvPluginProtocolHttp = ({ include }) => {
     //   }
     //   return null;
     // },
+    init: (context) => {
+      const outDirectoryUrl = context.outDirectoryUrl;
+      if (!outDirectoryUrl) {
+        throw new Error(`need outDirectoryUrl to write http files`);
+      }
+    },
     redirectReference: (reference) => {
       if (!reference.url.startsWith("http")) {
         return null;
@@ -6847,7 +6994,7 @@ const babelPluginMetadataImportMetaScenarios = () => {
 
 const jsenvPluginGlobalScenarios = () => {
   const transformIfNeeded = (urlInfo) => {
-    return replacePlaceholders$1(
+    return replacePlaceholders(
       urlInfo.content,
       {
         __DEV__: INJECTIONS.optional(urlInfo.context.dev),
@@ -7128,7 +7275,7 @@ const htmlNodeCanHotReload = (node) => {
 
 const jsenvPluginImportMetaHot = () => {
   const importMetaHotClientFileUrl = import.meta.resolve(
-    "./client/import_meta_hot/import_meta_hot.js",
+    "../client/import_meta_hot/import_meta_hot.js",
   );
 
   return {
@@ -7240,7 +7387,7 @@ import.meta.hot = createImportMetaHot(import.meta.url);
 };
 
 const jsenvPluginAutoreloadClient = () => {
-  const autoreloadClientFileUrl = import.meta.resolve("./client/autoreload/autoreload.js");
+  const autoreloadClientFileUrl = import.meta.resolve("../client/autoreload/autoreload.js");
 
   return {
     name: "jsenv:autoreload_client",
@@ -7759,7 +7906,7 @@ const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
 }) => {
-  const ribbonClientFileUrl = import.meta.resolve("./client/ribbon/ribbon.js");
+  const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
   const associations = URL_META.resolveAssociations(
     {
       ribbon: {
@@ -7941,4 +8088,796 @@ const getCorePlugins = ({
   ];
 };
 
-export { GRAPH_VISITOR, createEventEmitter, createKitchen, createPluginController, createPluginStore, defaultRuntimeCompat, getCorePlugins, getDefaultBase, isWebWorkerUrlInfo, jsenvPluginDirectoryReferenceEffect, jsenvPluginInlining, jsenvPluginReferenceAnalysis, logsDefault, prependContent, watchSourceFiles };
+/*
+ * This plugin is very special because it is here
+ * to provide "serverEvents" used by other plugins
+ */
+
+
+const serverEventsClientFileUrl = new URL(
+  "../client/server_events_client/server_events_client.js",
+  import.meta.url,
+).href;
+
+const jsenvPluginServerEvents = ({ clientAutoreload }) => {
+  let serverEvents = new ServerEvents({
+    actionOnClientLimitReached: "kick-oldest",
+  });
+  const { clientServerEventsConfig } = clientAutoreload;
+  const { logs = true } = clientServerEventsConfig;
+
+  return {
+    name: "jsenv:server_events",
+    appliesDuring: "dev",
+    effect: ({ kitchenContext, otherPlugins }) => {
+      const allServerEvents = {};
+      for (const otherPlugin of otherPlugins) {
+        const { serverEvents } = otherPlugin;
+        if (!serverEvents) {
+          continue;
+        }
+        for (const serverEventName of Object.keys(serverEvents)) {
+          // we could throw on serverEvent name conflict
+          // we could throw if serverEvents[serverEventName] is not a function
+          allServerEvents[serverEventName] = serverEvents[serverEventName];
+        }
+      }
+      const serverEventNames = Object.keys(allServerEvents);
+      if (serverEventNames.length === 0) {
+        return false;
+      }
+
+      const onabort = () => {
+        serverEvents.close();
+      };
+      kitchenContext.signal.addEventListener("abort", onabort);
+      for (const serverEventName of Object.keys(allServerEvents)) {
+        const serverEventInfo = {
+          ...kitchenContext,
+          // serverEventsDispatcher variable is safe, we can disable esling warning
+          // eslint-disable-next-line no-loop-func
+          sendServerEvent: (data) => {
+            if (!serverEvents) {
+              // this can happen if a plugin wants to send a server event but
+              // server is closing or the plugin got destroyed but still wants to do things
+              // if plugin code is correctly written it is never supposed to happen
+              // because it means a plugin is still trying to do stuff after being destroyed
+              return;
+            }
+            serverEvents.sendEventToAllClients({
+              type: serverEventName,
+              data,
+            });
+          },
+        };
+        const serverEventInit = allServerEvents[serverEventName];
+        serverEventInit(serverEventInfo);
+      }
+      return () => {
+        kitchenContext.signal.removeEventListener("abort", onabort);
+        serverEvents.close();
+        serverEvents = undefined;
+      };
+    },
+    transformUrlContent: {
+      html: (urlInfo) => {
+        const htmlAst = parseHtml({
+          html: urlInfo.content,
+          url: urlInfo.url,
+        });
+        injectJsenvScript(htmlAst, {
+          src: serverEventsClientFileUrl,
+          initCall: {
+            callee: "window.__server_events__.setup",
+            params: {
+              logs,
+            },
+          },
+          pluginName: "jsenv:server_events",
+        });
+        return stringifyHtmlAst(htmlAst);
+      },
+    },
+    devServerRoutes: [
+      {
+        endpoint: "GET /.internal/events.websocket",
+        description: `Jsenv dev server emit server events on this endpoint. When a file is saved the "reload" event is sent here.`,
+        fetch: serverEvents.fetch,
+        declarationSource: import.meta.url,
+      },
+    ],
+  };
+};
+
+const requireFromJsenv = createRequire(import.meta.url);
+
+const parseUserAgentHeader = memoizeByFirstArgument((userAgent) => {
+  if (userAgent.includes("node-fetch/")) {
+    // it's not really node and conceptually we can't assume the node version
+    // but good enough for now
+    return {
+      runtimeName: "node",
+      runtimeVersion: process.version.slice(1),
+    };
+  }
+  const UA = requireFromJsenv("@financial-times/polyfill-useragent-normaliser");
+  const { ua } = new UA(userAgent);
+  const { family, major, minor, patch } = ua;
+  return {
+    runtimeName: family.toLowerCase(),
+    runtimeVersion:
+      family === "Other" ? "unknown" : `${major}.${minor}${patch}`,
+  };
+});
+
+const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
+
+/**
+ * Starts the development server.
+ *
+ * @param {Object} [params={}] - Configuration params for the dev server.
+ * @param {number} [params.port=3456] - Port number the server should listen on.
+ * @param {string} [params.hostname="localhost"] - Hostname to bind the server to.
+ * @param {boolean} [params.https=false] - Whether to use HTTPS.
+ *
+ * @returns {Promise<Object>} A promise that resolves to the server instance.
+ * @throws {Error} Will throw an error if the server fails to start or is called with unexpected params.
+ *
+ * @example
+ * // Start a basic dev server
+ * const server = await startDevServer();
+ * console.log(`Server started at ${server.origin}`);
+ *
+ * @example
+ * // Start a server with custom params
+ * const server = await startDevServer({
+ *   port: 8080,
+ * });
+ */
+const startDevServer = async ({
+  sourceDirectoryUrl,
+  sourceMainFilePath = "./index.html",
+  ignore,
+  port = 3456,
+  hostname,
+  acceptAnyIp,
+  https,
+  // it's better to use http1 by default because it allows to get statusText in devtools
+  // which gives valuable information when there is errors
+  http2 = false,
+  logLevel = EXECUTED_BY_TEST_PLAN ? "warn" : "info",
+  serverLogLevel = "warn",
+  services = [],
+
+  signal = new AbortController().signal,
+  handleSIGINT = true,
+  keepProcessAlive = true,
+  onStop = () => {},
+
+  sourceFilesConfig = {},
+  clientAutoreload = true,
+
+  // runtimeCompat is the runtimeCompat for the build
+  // when specified, dev server use it to warn in case
+  // code would be supported during dev but not after build
+  runtimeCompat = defaultRuntimeCompat,
+  plugins = [],
+  referenceAnalysis = {},
+  nodeEsmResolution,
+  supervisor = true,
+  magicExtensions,
+  magicDirectoryIndex,
+  directoryListing,
+  injections,
+  transpilation,
+  cacheControl = true,
+  ribbon = true,
+  // toolbar = false,
+  onKitchenCreated = () => {},
+
+  sourcemaps = "inline",
+  sourcemapsSourcesContent,
+  outDirectoryUrl,
+  ...rest
+}) => {
+  // params type checking
+  {
+    const unexpectedParamNames = Object.keys(rest);
+    if (unexpectedParamNames.length > 0) {
+      throw new TypeError(
+        `${unexpectedParamNames.join(",")}: there is no such param`,
+      );
+    }
+    sourceDirectoryUrl = assertAndNormalizeDirectoryUrl(
+      sourceDirectoryUrl,
+      "sourceDirectoryUrl",
+    );
+    if (!existsSync(new URL(sourceDirectoryUrl))) {
+      throw new Error(`ENOENT on sourceDirectoryUrl at ${sourceDirectoryUrl}`);
+    }
+    if (typeof sourceMainFilePath !== "string") {
+      throw new TypeError(
+        `sourceMainFilePath must be a string, got ${sourceMainFilePath}`,
+      );
+    }
+    sourceMainFilePath = urlToRelativeUrl(
+      new URL(sourceMainFilePath, sourceDirectoryUrl),
+      sourceDirectoryUrl,
+    );
+    if (outDirectoryUrl === undefined) {
+      if (
+        process.env.CAPTURING_SIDE_EFFECTS ||
+        (false)
+      ) {
+        outDirectoryUrl = new URL("../.jsenv/", sourceDirectoryUrl);
+      } else {
+        const packageDirectoryUrl = lookupPackageDirectory(sourceDirectoryUrl);
+        if (packageDirectoryUrl) {
+          outDirectoryUrl = `${packageDirectoryUrl}.jsenv/`;
+        }
+      }
+    } else if (outDirectoryUrl !== null && outDirectoryUrl !== false) {
+      outDirectoryUrl = assertAndNormalizeDirectoryUrl(
+        outDirectoryUrl,
+        "outDirectoryUrl",
+      );
+    }
+  }
+
+  // params normalization
+  {
+    if (clientAutoreload === true) {
+      clientAutoreload = {};
+    }
+    if (clientAutoreload === false) {
+      clientAutoreload = { enabled: false };
+    }
+  }
+
+  const logger = createLogger({ logLevel });
+  const startDevServerTask = createTaskLog("start dev server", {
+    disabled: !logger.levels.info,
+  });
+
+  const serverStopCallbackSet = new Set();
+  const serverStopAbortController = new AbortController();
+  serverStopCallbackSet.add(() => {
+    serverStopAbortController.abort();
+  });
+  const serverStopAbortSignal = serverStopAbortController.signal;
+  const kitchenCache = new Map();
+
+  const finalServices = [];
+  // x-server-inspect service
+  {
+    finalServices.push({
+      name: "jsenv:server_header",
+      routes: [
+        {
+          endpoint: "GET /.internal/server.json",
+          description: "Get information about jsenv dev server",
+          availableMediaTypes: ["application/json"],
+          declarationSource: import.meta.url,
+          fetch: () =>
+            Response.json({
+              server: "jsenv_dev_server/1",
+              sourceDirectoryUrl,
+            }),
+        },
+      ],
+      injectResponseProperties: () => {
+        return {
+          headers: {
+            server: "jsenv_dev_server/1",
+          },
+        };
+      },
+    });
+  }
+  // cors service
+  {
+    finalServices.push(
+      jsenvServiceCORS({
+        accessControlAllowRequestOrigin: true,
+        accessControlAllowRequestMethod: true,
+        accessControlAllowRequestHeaders: true,
+        accessControlAllowedRequestHeaders: [
+          ...jsenvAccessControlAllowedHeaders,
+          "x-jsenv-execution-id",
+        ],
+        accessControlAllowCredentials: true,
+        timingAllowOrigin: true,
+      }),
+    );
+  }
+  // custom services
+  {
+    finalServices.push(...services);
+  }
+  // file_service
+  {
+    const clientFileChangeEventEmitter = createEventEmitter();
+    const clientFileDereferencedEventEmitter = createEventEmitter();
+    clientAutoreload = {
+      enabled: true,
+      clientServerEventsConfig: {},
+      clientFileChangeEventEmitter,
+      clientFileDereferencedEventEmitter,
+      ...clientAutoreload,
+    };
+    const stopWatchingSourceFiles = watchSourceFiles(
+      sourceDirectoryUrl,
+      (fileInfo) => {
+        clientFileChangeEventEmitter.emit(fileInfo);
+      },
+      {
+        sourceFilesConfig,
+        keepProcessAlive: false,
+        cooldownBetweenFileEvents: clientAutoreload.cooldownBetweenFileEvents,
+      },
+    );
+    serverStopCallbackSet.add(stopWatchingSourceFiles);
+
+    const devServerPluginStore = createPluginStore([
+      jsenvPluginServerEvents({ clientAutoreload }),
+      ...plugins,
+      ...getCorePlugins({
+        rootDirectoryUrl: sourceDirectoryUrl,
+        mainFilePath: sourceMainFilePath,
+        runtimeCompat,
+        sourceFilesConfig,
+
+        referenceAnalysis,
+        nodeEsmResolution,
+        magicExtensions,
+        magicDirectoryIndex,
+        directoryListing,
+        supervisor,
+        injections,
+        transpilation,
+
+        clientAutoreload,
+        cacheControl,
+        ribbon,
+      }),
+    ]);
+    const getOrCreateKitchen = (request) => {
+      const { runtimeName, runtimeVersion } = parseUserAgentHeader(
+        request.headers["user-agent"] || "",
+      );
+      const runtimeId = `${runtimeName}@${runtimeVersion}`;
+      const existing = kitchenCache.get(runtimeId);
+      if (existing) {
+        return existing;
+      }
+      const watchAssociations = URL_META.resolveAssociations(
+        { watch: stopWatchingSourceFiles.watchPatterns },
+        sourceDirectoryUrl,
+      );
+      let kitchen;
+      clientFileChangeEventEmitter.on(({ url, event }) => {
+        const urlInfo = kitchen.graph.getUrlInfo(url);
+        if (urlInfo) {
+          if (event === "removed") {
+            urlInfo.onRemoved();
+          } else {
+            urlInfo.onModified();
+          }
+        }
+      });
+      const clientRuntimeCompat = { [runtimeName]: runtimeVersion };
+
+      kitchen = createKitchen({
+        name: runtimeId,
+        signal: serverStopAbortSignal,
+        logLevel,
+        rootDirectoryUrl: sourceDirectoryUrl,
+        mainFilePath: sourceMainFilePath,
+        ignore,
+        dev: true,
+        runtimeCompat,
+        clientRuntimeCompat,
+        supervisor,
+        sourcemaps,
+        sourcemapsSourcesContent,
+        outDirectoryUrl: outDirectoryUrl
+          ? new URL(`${runtimeName}@${runtimeVersion}/`, outDirectoryUrl)
+          : undefined,
+      });
+      kitchen.graph.urlInfoCreatedEventEmitter.on((urlInfoCreated) => {
+        const { watch } = URL_META.applyAssociations({
+          url: urlInfoCreated.url,
+          associations: watchAssociations,
+        });
+        urlInfoCreated.isWatched = watch;
+        // when an url depends on many others, we check all these (like package.json)
+        urlInfoCreated.isValid = () => {
+          if (!urlInfoCreated.url.startsWith("file:")) {
+            return false;
+          }
+          if (urlInfoCreated.content === undefined) {
+            // urlInfo content is undefined when:
+            // - url info content never fetched
+            // - it is considered as modified because undelying file is watched and got saved
+            // - it is considered as modified because underlying file content
+            //   was compared using etag and it has changed
+            return false;
+          }
+          if (!watch) {
+            // file is not watched, check the filesystem
+            let fileContentAsBuffer;
+            try {
+              fileContentAsBuffer = readFileSync(new URL(urlInfoCreated.url));
+            } catch (e) {
+              if (e.code === "ENOENT") {
+                urlInfoCreated.onModified();
+                return false;
+              }
+              return false;
+            }
+            const fileContentEtag = bufferToEtag(fileContentAsBuffer);
+            if (fileContentEtag !== urlInfoCreated.originalContentEtag) {
+              urlInfoCreated.onModified();
+              // restore content to be able to compare it again later
+              urlInfoCreated.kitchen.urlInfoTransformer.setContent(
+                urlInfoCreated,
+                String(fileContentAsBuffer),
+                {
+                  contentEtag: fileContentEtag,
+                },
+              );
+              return false;
+            }
+          }
+          for (const implicitUrl of urlInfoCreated.implicitUrlSet) {
+            const implicitUrlInfo =
+              urlInfoCreated.graph.getUrlInfo(implicitUrl);
+            if (!implicitUrlInfo) {
+              continue;
+            }
+            if (implicitUrlInfo.content === undefined) {
+              // happens when we explicitely load an url with a search param
+              // - it creates an implicit url info to the url without params
+              // - we never explicitely request the url without search param so it has no content
+              // in that case the underlying urlInfo cannot be invalidate by the implicit
+              // we use modifiedTimestamp to detect if the url was loaded once
+              // or is just here to be used later
+              if (implicitUrlInfo.modifiedTimestamp) {
+                return false;
+              }
+              continue;
+            }
+            if (!implicitUrlInfo.isValid()) {
+              return false;
+            }
+          }
+          return true;
+        };
+      });
+      kitchen.graph.urlInfoDereferencedEventEmitter.on(
+        (urlInfoDereferenced, lastReferenceFromOther) => {
+          clientFileDereferencedEventEmitter.emit(
+            urlInfoDereferenced,
+            lastReferenceFromOther,
+          );
+        },
+      );
+      const devServerPluginController = createPluginController(
+        devServerPluginStore,
+        kitchen,
+      );
+      kitchen.setPluginController(devServerPluginController);
+
+      serverStopCallbackSet.add(() => {
+        devServerPluginController.callHooks("destroy", kitchen.context);
+      });
+      kitchenCache.set(runtimeId, kitchen);
+      onKitchenCreated(kitchen);
+      return kitchen;
+    };
+
+    finalServices.push({
+      name: "jsenv:dev_server_routes",
+      augmentRouteFetchSecondArg: (request) => {
+        const kitchen = getOrCreateKitchen(request);
+        return { kitchen };
+      },
+      routes: [
+        ...devServerPluginStore.allDevServerRoutes,
+        {
+          endpoint: "GET *",
+          description: "Serve project files.",
+          declarationSource: import.meta.url,
+          fetch: async (request, { kitchen }) => {
+            const { rootDirectoryUrl, mainFilePath } = kitchen.context;
+            let requestResource = request.resource;
+            let requestedUrl;
+            if (requestResource.startsWith("/@fs/")) {
+              const fsRootRelativeUrl = requestResource.slice("/@fs/".length);
+              requestedUrl = `file:///${fsRootRelativeUrl}`;
+            } else {
+              const requestedUrlObject = new URL(
+                requestResource === "/"
+                  ? mainFilePath
+                  : requestResource.slice(1),
+                rootDirectoryUrl,
+              );
+              requestedUrlObject.searchParams.delete("hot");
+              requestedUrl = requestedUrlObject.href;
+            }
+            const { referer } = request.headers;
+            const parentUrl = referer
+              ? WEB_URL_CONVERTER.asFileUrl(referer, {
+                  origin: request.origin,
+                  rootDirectoryUrl: sourceDirectoryUrl,
+                })
+              : sourceDirectoryUrl;
+            let reference = kitchen.graph.inferReference(
+              request.resource,
+              parentUrl,
+            );
+            if (reference) {
+              reference.urlInfo.context.request = request;
+              reference.urlInfo.context.requestedUrl = requestedUrl;
+            } else {
+              const rootUrlInfo = kitchen.graph.rootUrlInfo;
+              rootUrlInfo.context.request = request;
+              rootUrlInfo.context.requestedUrl = requestedUrl;
+              reference = rootUrlInfo.dependencies.createResolveAndFinalize({
+                trace: { message: parentUrl },
+                type: "http_request",
+                specifier: request.resource,
+              });
+              rootUrlInfo.context.request = null;
+              rootUrlInfo.context.requestedUrl = null;
+            }
+            const urlInfo = reference.urlInfo;
+            const ifNoneMatch = request.headers["if-none-match"];
+            const urlInfoTargetedByCache =
+              urlInfo.findParentIfInline() || urlInfo;
+
+            try {
+              if (!urlInfo.error && ifNoneMatch) {
+                const [clientOriginalContentEtag, clientContentEtag] =
+                  ifNoneMatch.split("_");
+                if (
+                  urlInfoTargetedByCache.originalContentEtag ===
+                    clientOriginalContentEtag &&
+                  urlInfoTargetedByCache.contentEtag === clientContentEtag &&
+                  urlInfoTargetedByCache.isValid()
+                ) {
+                  const headers = {
+                    "cache-control": `private,max-age=0,must-revalidate`,
+                  };
+                  Object.keys(urlInfo.headers).forEach((key) => {
+                    if (key !== "content-length") {
+                      headers[key] = urlInfo.headers[key];
+                    }
+                  });
+                  return {
+                    status: 304,
+                    headers,
+                  };
+                }
+              }
+              await urlInfo.cook({ request, reference });
+              let { response } = urlInfo;
+              if (response) {
+                return response;
+              }
+              response = {
+                url: reference.url,
+                status: 200,
+                headers: {
+                  // when we send eTag to the client the next request to the server
+                  // will send etag in request headers.
+                  // If they match jsenv bypass cooking and returns 304
+                  // This must not happen when a plugin uses "no-store" or "no-cache" as it means
+                  // plugin logic wants to happens for every request to this url
+                  ...(cacheIsDisabledInResponseHeader(urlInfoTargetedByCache)
+                    ? {
+                        "cache-control": "no-store", // for inline file we force no-store when parent is no-store
+                      }
+                    : {
+                        "cache-control": `private,max-age=0,must-revalidate`,
+                        // it's safe to use "_" separator because etag is encoded with base64 (see https://stackoverflow.com/a/13195197)
+                        "eTag": `${urlInfoTargetedByCache.originalContentEtag}_${urlInfoTargetedByCache.contentEtag}`,
+                      }),
+                  ...urlInfo.headers,
+                  "content-type": urlInfo.contentType,
+                  "content-length": urlInfo.contentLength,
+                },
+                body: urlInfo.content,
+                timing: urlInfo.timing, // TODO: use something else
+              };
+              const augmentResponseInfo = {
+                ...kitchen.context,
+                reference,
+                urlInfo,
+              };
+              kitchen.pluginController.callHooks(
+                "augmentResponse",
+                augmentResponseInfo,
+                (returnValue) => {
+                  response = composeTwoResponses(response, returnValue);
+                },
+              );
+              return response;
+            } catch (error) {
+              const originalError = error ? error.cause || error : error;
+              if (originalError.asResponse) {
+                return originalError.asResponse();
+              }
+              const code = originalError.code;
+              if (code === "PARSE_ERROR") {
+                // when possible let browser re-throw the syntax error
+                // it's not possible to do that when url info content is not available
+                // (happens for js_module_fallback for instance)
+                if (urlInfo.content !== undefined) {
+                  kitchen.context.logger
+                    .error(`Error while handling ${request.url}:
+  ${originalError.reasonCode || originalError.code}
+  ${error.trace?.message}`);
+                  return {
+                    url: reference.url,
+                    status: 200,
+                    // reason becomes the http response statusText, it must not contain invalid chars
+                    // https://github.com/nodejs/node/blob/0c27ca4bc9782d658afeaebcec85ec7b28f1cc35/lib/_http_common.js#L221
+                    statusText: error.reason,
+                    statusMessage: originalError.message,
+                    headers: {
+                      "content-type": urlInfo.contentType,
+                      "content-length": urlInfo.contentLength,
+                      "cache-control": "no-store",
+                    },
+                    body: urlInfo.content,
+                  };
+                }
+                return {
+                  url: reference.url,
+                  status: 500,
+                  statusText: error.reason,
+                  statusMessage: originalError.message,
+                  headers: {
+                    "cache-control": "no-store",
+                  },
+                  body: urlInfo.content,
+                };
+              }
+              if (code === "DIRECTORY_REFERENCE_NOT_ALLOWED") {
+                return serveDirectory(reference.url, {
+                  headers: {
+                    accept: "text/html",
+                  },
+                  canReadDirectory: true,
+                  rootDirectoryUrl: sourceDirectoryUrl,
+                });
+              }
+              if (code === "NOT_ALLOWED") {
+                return {
+                  url: reference.url,
+                  status: 403,
+                  statusText: originalError.reason,
+                };
+              }
+              if (code === "NOT_FOUND") {
+                return {
+                  url: reference.url,
+                  status: 404,
+                  statusText: originalError.reason,
+                  statusMessage: originalError.message,
+                };
+              }
+              return {
+                url: reference.url,
+                status: 500,
+                statusText: error.reason,
+                statusMessage: error.stack,
+                headers: {
+                  "cache-control": "no-store",
+                },
+              };
+            }
+          },
+        },
+      ],
+    });
+  }
+  // jsenv error handler service
+  {
+    finalServices.push({
+      name: "jsenv:omega_error_handler",
+      handleError: (error) => {
+        const getResponseForError = () => {
+          if (error && error.asResponse) {
+            return error.asResponse();
+          }
+          if (error && error.statusText === "Unexpected directory operation") {
+            return {
+              status: 403,
+            };
+          }
+          return convertFileSystemErrorToResponseProperties(error);
+        };
+        const response = getResponseForError();
+        if (!response) {
+          return null;
+        }
+        const body = JSON.stringify({
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+          body: response.body,
+        });
+        return {
+          status: 200,
+          headers: {
+            "content-type": "application/json",
+            "content-length": Buffer.byteLength(body),
+          },
+          body,
+        };
+      },
+    });
+  }
+  // default error handler
+  {
+    finalServices.push(
+      jsenvServiceErrorHandler({
+        sendErrorDetails: true,
+      }),
+    );
+  }
+
+  const server = await startServer({
+    signal,
+    stopOnExit: false,
+    stopOnSIGINT: handleSIGINT,
+    stopOnInternalError: false,
+    keepProcessAlive,
+    logLevel: serverLogLevel,
+    startLog: false,
+
+    https,
+    http2,
+    acceptAnyIp,
+    hostname,
+    port,
+    requestWaitingMs: 60_000,
+    services: finalServices,
+  });
+  server.stoppedPromise.then((reason) => {
+    onStop();
+    for (const serverStopCallback of serverStopCallbackSet) {
+      serverStopCallback(reason);
+    }
+    serverStopCallbackSet.clear();
+  });
+  startDevServerTask.done();
+  if (hostname) {
+    delete server.origins.localip;
+    delete server.origins.externalip;
+  }
+  logger.info(``);
+  Object.keys(server.origins).forEach((key) => {
+    logger.info(`- ${server.origins[key]}`);
+  });
+  logger.info(``);
+  return {
+    origin: server.origin,
+    sourceDirectoryUrl,
+    stop: () => {
+      server.stop();
+    },
+    kitchenCache,
+  };
+};
+
+const cacheIsDisabledInResponseHeader = (urlInfo) => {
+  return (
+    urlInfo.headers["cache-control"] === "no-store" ||
+    urlInfo.headers["cache-control"] === "no-cache"
+  );
+};
+
+export { startDevServer };