@jsenv/core 41.4.10 → 41.4.12

package/dist/start_build_server/start_build_server.js

@@ -1,4 +1,6 @@
-import { startServer, createFileSystemFetch, serverPluginCORS, jsenvAccessControlAllowedHeaders, serverPluginErrorHandler } from "@jsenv/server";
+import { createFileSystemFetch, startServer, serverPluginCORS, jsenvAccessControlAllowedHeaders, serverPluginErrorHandler } from "@jsenv/server";
+import { parseHtml, injectJsenvScript, stringifyHtmlAst } from "@jsenv/ast";
+import { readFileSync } from "node:fs";
 import { createLogger, Abort, raceProcessTeardownEvents, createTaskLog } from "./jsenv_core_packages.js";
 import "./jsenv_core_node_modules.js";
 import "node:process";
@@ -6,6 +8,43 @@ import "node:os";
 import "node:tty";
 import "node:util";
 
+/*
+ * Inject the ribbon into an html string, inlining the client code.
+ *
+ * Used when serving files that must not be modified on the filesystem (the build
+ * directory served by startBuildServer): the ribbon exists only in what the
+ * server sends, never in the artifact that gets deployed.
+ */
+
+
+const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
+let ribbonClientFileContent;
+
+const injectRibbonIntoHtml = (
+  html,
+  { text = "BUILD", color, textColor, href, target, position } = {},
+) => {
+  if (ribbonClientFileContent === undefined) {
+    ribbonClientFileContent = String(
+      readFileSync(new URL(ribbonClientFileUrl)),
+    );
+  }
+  const htmlAst = parseHtml({ html, url: "file:///ribbon.html" });
+  const params = { text, color, textColor, href, target, position };
+  for (const key of Object.keys(params)) {
+    if (params[key] === undefined) {
+      delete params[key];
+    }
+  }
+  injectJsenvScript(htmlAst, {
+    type: "module",
+    content: `${ribbonClientFileContent}
+injectRibbon(${JSON.stringify(params)});`,
+    pluginName: "jsenv:ribbon",
+  });
+  return stringifyHtmlAst(htmlAst);
+};
+
 /*
  * startBuildServer is mean to interact with the build files;
  * files that will be deployed to production server(s).
@@ -26,11 +65,16 @@ import "node:util";
  * Start a server for build files.
  * @param {Object} buildServerParameters
  * @param {string|url} buildServerParameters.buildDirectoryUrl Directory where build files are written
+ * @param {boolean|object} [buildServerParameters.ribbon=false] Inject a ribbon in the html responses,
+ *        marking the page as non-production. The build directory itself is left untouched.
+ *        As an object: `text`, `color`, `textColor`, `href`, `target`, `position`
+ *        (see startDevServer "ribbon" param).
  * @return {Object} A build server object
  */
 const startBuildServer = async ({
   buildDirectoryUrl,
   buildDirectoryMainFileRelativeUrl = "index.html",
+  ribbon = false,
   port = 9779,
   routes = [],
   serverPlugins = [],
@@ -46,6 +90,9 @@ const startBuildServer = async ({
   keepProcessAlive = true,
 }) => {
   const logger = createLogger({ logLevel });
+  if (ribbon === true) {
+    ribbon = {};
+  }
   const operation = Abort.startOperation();
   operation.addAbortSignal(signal);
   if (handleSIGINT) {
@@ -58,6 +105,9 @@ const startBuildServer = async ({
     });
   }
 
+  const fileSystemFetch = createFileSystemFetch(buildDirectoryUrl, {
+    mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
+  });
   const startBuildServerTask = createTaskLog("start build server", {
     disabled: !logger.levels.info,
   });
@@ -96,9 +146,9 @@ const startBuildServer = async ({
       {
         endpoint: "GET /",
         description: "Serve build files",
-        fetch: createFileSystemFetch(buildDirectoryUrl, {
-          mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
-        }),
+        fetch: ribbon
+          ? withRibbonInjectedInHtml(fileSystemFetch, ribbon)
+          : fileSystemFetch,
       },
     ],
   });
@@ -120,4 +170,44 @@ const startBuildServer = async ({
   };
 };
 
+const withRibbonInjectedInHtml = (fetch, ribbon) => {
+  return async (request, helpers) => {
+    const response = await fetch(request, helpers);
+    if (!response || response.status !== 200) {
+      return response;
+    }
+    const contentType = response.headers?.["content-type"];
+    if (!contentType || !contentType.startsWith("text/html")) {
+      return response;
+    }
+    const html = await readResponseBodyAsString(response.body);
+    const htmlWithRibbon = injectRibbonIntoHtml(html, ribbon);
+    const bodyBuffer = Buffer.from(htmlWithRibbon);
+    const headers = {
+      ...response.headers,
+      "content-length": bodyBuffer.length,
+    };
+    // the body is generated per request; what the file on disk hashes to or when
+    // it was modified does not describe it
+    delete headers.etag;
+    delete headers["last-modified"];
+    return {
+      ...response,
+      headers,
+      body: bodyBuffer,
+    };
+  };
+};
+
+const readResponseBodyAsString = async (body) => {
+  if (typeof body === "string" || Buffer.isBuffer(body)) {
+    return String(body);
+  }
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return String(Buffer.concat(chunks));
+};
+
 export { startBuildServer };

package/dist/start_dev_server/start_dev_server.js

@@ -1,6 +1,6 @@
 import { WebSocketResponse, pickContentType, ServerEvents, serverPluginErrorHandler, composeTwoResponses, fetchDirectory, serverPluginCORS, jsenvAccessControlAllowedHeaders, startServer } from "@jsenv/server";
 import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from "node:fs";
-import { registerFileLifecycle, lookupPackageDirectory, readPackageAtOrNull, generateContentFrame, urlToRelativeUrl, errorToHTML, DATA_URL, CONTENT_TYPE, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, urlToExtension, urlToBasename, applyNodeEsmResolution, URL_META, readCustomConditionsFromProcessArgs, urlIsOrIsInsideOf, collectFiles, registerDirectoryLifecycle, asUrlWithoutSearch, readEntryStatSync, ensurePathnameTrailingSlash, compareFileUrls, urlToFilename, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, createDetailedMessage, stringifyUrlSite, injectQueryParamsIntoSpecifier, isSpecifierForNodeBuiltin, injectQueryParams, urlToFileSystemPath, writeFileSync, moveUrl, ensureWindowsDriveLetter, validateResponseIntegrity, setUrlFilename, getCallerPosition, asSpecifierWithoutSearch, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, createLogger, normalizeUrl, ANSI, RUNTIME_COMPAT, formatError, assertAndNormalizeDirectoryUrl, createTaskLog } from "./jsenv_core_packages.js";
+import { urlToRelativeUrl, registerFileLifecycle, lookupPackageDirectory, readPackageAtOrNull, generateContentFrame, errorToHTML, DATA_URL, CONTENT_TYPE, normalizeImportMap, composeTwoImportMaps, resolveImport, JS_QUOTES, urlToExtension, urlToBasename, applyNodeEsmResolution, URL_META, readCustomConditionsFromProcessArgs, urlIsOrIsInsideOf, collectFiles, registerDirectoryLifecycle, asUrlWithoutSearch, readEntryStatSync, ensurePathnameTrailingSlash, compareFileUrls, urlToFilename, applyFileSystemMagicResolution, getExtensionsToTry, setUrlExtension, createDetailedMessage, stringifyUrlSite, injectQueryParamsIntoSpecifier, isSpecifierForNodeBuiltin, injectQueryParams, urlToFileSystemPath, writeFileSync, moveUrl, ensureWindowsDriveLetter, validateResponseIntegrity, setUrlFilename, getCallerPosition, asSpecifierWithoutSearch, bufferToEtag, isFileSystemPath, urlToPathname, setUrlBasename, createLogger, normalizeUrl, ANSI, RUNTIME_COMPAT, formatError, assertAndNormalizeDirectoryUrl, createTaskLog } from "./jsenv_core_packages.js";
 import { createPluginsController } from "@jsenv/server/src/plugins_controller.js";
 import { parseHtml, injectJsenvScript, stringifyHtmlAst, parseCssUrls, getHtmlNodeAttribute, getHtmlNodePosition, getHtmlNodeAttributePosition, setHtmlNodeAttributes, parseSrcSet, getUrlForContentInsideHtml, removeHtmlNodeText, setHtmlNodeText, getHtmlNodeText, analyzeScriptNode, visitHtmlNodes, parseJsUrls, getUrlForContentInsideJs, applyBabelPlugins, analyzeLinkNode, injectHtmlNodeAsEarlyAsPossible, createHtmlNode, generateUrlForInlineContent, parseJsWithAcorn } from "@jsenv/ast";
 import { jsenvPluginSupervisor } from "@jsenv/plugin-supervisor";
@@ -144,12 +144,21 @@ const createStatus = (
     declaredVersion,
     declaredBy,
     installedVersion: null,
+    // the file telling this dependency apart; it is what an install rewrites and
+    // what the dev server looks at to know the dependency became the declared one
+    watchedPath: null,
     state: "missing",
   };
   const installedDirectoryUrl = findInstalledDirectoryUrl(
     declaringDirectoryUrl,
     packageName,
   );
+  status.watchedPath = watchedPathFromDirectoryUrl(
+    packageDirectory,
+    // not installed yet: name the place where it is expected to appear
+    installedDirectoryUrl ||
+      `${declaringDirectoryUrl}node_modules/${packageName}/`,
+  );
   if (!installedDirectoryUrl) {
     return status;
   }
@@ -168,6 +177,14 @@ const createStatus = (
   return status;
 };
 
+const watchedPathFromDirectoryUrl = (packageDirectory, directoryUrl) => {
+  const packageJsonUrl = `${directoryUrl}package.json`;
+  if (!packageDirectory.url) {
+    return packageJsonUrl;
+  }
+  return urlToRelativeUrl(packageJsonUrl, packageDirectory.url);
+};
+
 const findInstalledDirectoryUrl = (declaringDirectoryUrl, packageName) => {
   let directoryUrl = declaringDirectoryUrl;
   while (directoryUrl) {
@@ -232,8 +249,13 @@ const watchDependencies = (
   { onProblem, onInstalled, onChange, pollInterval = POLL_INTERVAL },
 ) => {
   let problemMap = new Map();
+  // every path given to the browser is relative to the package directory, the
+  // one holding the package.json being watched
+  const packageJsonPath = "package.json";
   const watcher = {
     getProblems: () => Array.from(problemMap.values()),
+    // what the browser needs to display the watching in progress
+    getWatchInfo: () => ({ packageJsonPath, pollInterval }),
     stop: () => {},
   };
   if (!packageDirectory.url) {
@@ -7122,6 +7144,7 @@ const clientFileUrl = import.meta.resolve("../js/dependency_status.js");
 const jsenvPluginDependencyStatus = ({
   dependencyProblemEventEmitter,
   getDependencyProblems,
+  getDependencyWatchInfo = () => ({}),
 }) => {
   return {
     name: "jsenv:dependency_status",
@@ -7158,7 +7181,10 @@ const jsenvPluginDependencyStatus = ({
           src: clientReference.generatedSpecifier,
           initCall: {
             callee: "initDependencyStatus",
-            params: { problems: getDependencyProblems() },
+            params: {
+              problems: getDependencyProblems(),
+              watchInfo: getDependencyWatchInfo(),
+            },
           },
           pluginName: "jsenv:dependency_status",
         });
@@ -7232,6 +7258,12 @@ const jsenvPluginCustomElementsRedefine = () => {
 const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
+  text,
+  color,
+  textColor,
+  href,
+  target,
+  position,
 }) => {
   const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
   const associations = URL_META.resolveAssociations(
@@ -7244,7 +7276,7 @@ const jsenvPluginRibbon = ({
   );
   return {
     name: "jsenv:ribbon",
-    appliesDuring: "dev",
+    appliesDuring: "*",
     transformUrlContent: {
       html: (urlInfo) => {
         const jsenvToolbarHtmlClientFileUrl = urlInfo.context.getPluginMeta(
@@ -7279,9 +7311,19 @@ const jsenvPluginRibbon = ({
           src: ribbonClientFileReference.generatedSpecifier,
           initCall: {
             callee: "injectRibbon",
-            params: {
-              text: urlInfo.context.dev ? "DEV" : "BUILD",
-            },
+            params: withoutUndefinedValues({
+              text:
+                text === undefined
+                  ? urlInfo.context.dev
+                    ? "DEV"
+                    : "BUILD"
+                  : text,
+              color,
+              textColor,
+              href,
+              target,
+              position,
+            }),
           },
           pluginName: "jsenv:ribbon",
         });
@@ -7291,6 +7333,16 @@ const jsenvPluginRibbon = ({
   };
 };
 
+const withoutUndefinedValues = (object) => {
+  const objectWithoutUndefinedValues = {};
+  for (const key of Object.keys(object)) {
+    if (object[key] !== undefined) {
+      objectWithoutUndefinedValues[key] = object[key];
+    }
+  }
+  return objectWithoutUndefinedValues;
+};
+
 /**
  * HTML page server by jsenv dev server will listen for drop events
  * and redirect the browser to the dropped file location.
@@ -11666,7 +11718,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {Array} [params.serverPlugins=[]] - `@jsenv/server`-level plugins.
  * @param {boolean|object} [params.clientAutoreload=true] - Live reload; also gates the server-events channel.
  * @param {boolean|object} [params.serverTiming={ minDuration: 0.5 }] - server-timing response headers; `minDuration` (ms) drops entries that took less (0 when run by the test plan, so tests see every entry).
- * @param {boolean} [params.ribbon=true] - The dev "ribbon" overlay.
+ * @param {boolean|object} [params.ribbon=true] - The "ribbon" overlay marking the page as non-production. As an object: `text` (defaults to `"DEV"`), `color` (background, defaults to `"orange"`), `textColor` (defaults to dark or light depending on `color`), `href` (turns the ribbon into a link; only then does it capture clicks), `target` (defaults to `"_blank"`), `position` (`"top-right"` (default), `"top-left"`, `"bottom-right"`, `"bottom-left"` draw a diagonal corner ribbon; `"top"`, `"bottom"` draw a full width band), `htmlInclude` (defaults to `"/**\/*.html"`).
  * @param {boolean} [params.supervisor=true] - Script supervisor (better error reporting).
  * @param {boolean|object} [params.directoryListing=true] - Directory listing pages.
  * @param {object} [params.injections] - Values to inject into files, as `{ urlPattern: getInjections }`. Keys are url patterns relative to sourceDirectoryUrl (`"./index.html"`, `"**\/*.js"`), values are functions receiving `urlInfo` and returning (or resolving to) an object of placeholders to replace, named `__LIKE_THIS__` by convention. In JS the value is injected as a JS literal (a string brings its own quotes), everywhere else as-is so it can be concatenated: `href="__BACKEND_URL__/users/me"`. An html url pattern also covers what is inlined in that html, so `<script>window.backendUrl = __BACKEND_URL__;</script>` shares the value with every js file of the page. See `INJECTIONS.optional` and `INJECTIONS.global`.
@@ -11882,6 +11934,7 @@ const startDevServer = async ({
       dependencyStatus: {
         dependencyProblemEventEmitter,
         getDependencyProblems: dependencyWatcher.getProblems,
+        getDependencyWatchInfo: dependencyWatcher.getWatchInfo,
       },
       cacheControl,
       ribbon,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "41.4.10",
+  "version": "41.4.12",
   "type": "module",
   "description": "Tool to develop, test and build js projects",
   "repository": {
@@ -72,12 +72,12 @@
     "test:snapshot_clear": "npx @jsenv/filesystem clear **/tests/**/side_effects/"
   },
   "dependencies": {
-    "@jsenv/ast": "6.8.5",
-    "@jsenv/js-module-fallback": "1.4.38",
+    "@jsenv/ast": "6.9.0",
+    "@jsenv/js-module-fallback": "1.4.39",
     "@jsenv/plugin-bundling": "2.10.16",
-    "@jsenv/plugin-minification": "1.7.6",
-    "@jsenv/plugin-supervisor": "1.8.9",
-    "@jsenv/plugin-transpilation": "1.5.79",
+    "@jsenv/plugin-minification": "1.7.7",
+    "@jsenv/plugin-supervisor": "1.8.10",
+    "@jsenv/plugin-transpilation": "1.5.80",
     "@jsenv/server": "17.6.0",
     "@jsenv/sourcemap": "1.4.2",
     "react-table": "7.8.0"

package/src/build/build.js

@@ -134,6 +134,18 @@ import { jsenvPluginMappings } from "./jsenv_plugin_mappings.js";
  *        How URLs are versioned for this entry point (defaults to "search_param")
  * @param {('none'|'inline'|'file'|'programmatic')} [entryPoint.sourcemaps]
  *        Sourcemap generation strategy for this entry point (defaults to "none")
+ * @param {boolean|object} [entryPoint.ribbon=false]
+ *        Inject a ribbon marking the page as non-production. Disabled by default
+ *        because the ribbon ends up inside the build directory: enable it on the
+ *        builds meant for a preview/review app, not on the production build.
+ *
+ *          ribbon: {
+ *            text: "preview",
+ *            color: "#7c3aed",
+ *            href: "https://github.com/org/repo/pull/42",
+ *          }
+ *
+ *        See startDevServer "ribbon" param for the full list of options.
  * @param {object} [entryPoint.injections]
  *        Values to inject into files, as { urlPattern: getInjections }.
  *        Keys are url patterns relative to sourceDirectoryUrl ("./index.html", "**\/*.js"),
@@ -953,6 +965,7 @@ const entryPointDefaultParams = {
   magicDirectoryIndex: undefined,
   directoryReferenceEffect: undefined,
   scenarioPlaceholders: undefined,
+  ribbon: false,
   injections: undefined,
   transpilation: {},
   preserveComments: undefined,
@@ -1007,6 +1020,7 @@ const prepareEntryPointBuild = async (
     magicDirectoryIndex,
     directoryReferenceEffect,
     scenarioPlaceholders,
+    ribbon,
     injections,
     transpilation,
     preserveComments,
@@ -1183,6 +1197,7 @@ const prepareEntryPointBuild = async (
       inlining: false,
       http,
       scenarioPlaceholders,
+      ribbon,
       packageSideEffects,
     }),
   ]);

package/src/build/start_build_server.js

@@ -23,15 +23,22 @@ import {
   startServer,
 } from "@jsenv/server";
 
+import { injectRibbonIntoHtml } from "../plugins/ribbon/ribbon_html_injection.js";
+
 /**
  * Start a server for build files.
  * @param {Object} buildServerParameters
  * @param {string|url} buildServerParameters.buildDirectoryUrl Directory where build files are written
+ * @param {boolean|object} [buildServerParameters.ribbon=false] Inject a ribbon in the html responses,
+ *        marking the page as non-production. The build directory itself is left untouched.
+ *        As an object: `text`, `color`, `textColor`, `href`, `target`, `position`
+ *        (see startDevServer "ribbon" param).
  * @return {Object} A build server object
  */
 export const startBuildServer = async ({
   buildDirectoryUrl,
   buildDirectoryMainFileRelativeUrl = "index.html",
+  ribbon = false,
   port = 9779,
   routes = [],
   serverPlugins = [],
@@ -47,6 +54,9 @@ export const startBuildServer = async ({
   keepProcessAlive = true,
 }) => {
   const logger = createLogger({ logLevel });
+  if (ribbon === true) {
+    ribbon = {};
+  }
   const operation = Abort.startOperation();
   operation.addAbortSignal(signal);
   if (handleSIGINT) {
@@ -60,6 +70,9 @@ export const startBuildServer = async ({
     });
   }
 
+  const fileSystemFetch = createFileSystemFetch(buildDirectoryUrl, {
+    mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
+  });
   const startBuildServerTask = createTaskLog("start build server", {
     disabled: !logger.levels.info,
   });
@@ -98,9 +111,9 @@ export const startBuildServer = async ({
       {
         endpoint: "GET /",
         description: "Serve build files",
-        fetch: createFileSystemFetch(buildDirectoryUrl, {
-          mainFileRelativeUrl: buildDirectoryMainFileRelativeUrl,
-        }),
+        fetch: ribbon
+          ? withRibbonInjectedInHtml(fileSystemFetch, ribbon)
+          : fileSystemFetch,
       },
     ],
   });
@@ -121,3 +134,43 @@ export const startBuildServer = async ({
     },
   };
 };
+
+const withRibbonInjectedInHtml = (fetch, ribbon) => {
+  return async (request, helpers) => {
+    const response = await fetch(request, helpers);
+    if (!response || response.status !== 200) {
+      return response;
+    }
+    const contentType = response.headers?.["content-type"];
+    if (!contentType || !contentType.startsWith("text/html")) {
+      return response;
+    }
+    const html = await readResponseBodyAsString(response.body);
+    const htmlWithRibbon = injectRibbonIntoHtml(html, ribbon);
+    const bodyBuffer = Buffer.from(htmlWithRibbon);
+    const headers = {
+      ...response.headers,
+      "content-length": bodyBuffer.length,
+    };
+    // the body is generated per request; what the file on disk hashes to or when
+    // it was modified does not describe it
+    delete headers.etag;
+    delete headers["last-modified"];
+    return {
+      ...response,
+      headers,
+      body: bodyBuffer,
+    };
+  };
+};
+
+const readResponseBodyAsString = async (body) => {
+  if (typeof body === "string" || Buffer.isBuffer(body)) {
+    return String(body);
+  }
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return String(Buffer.concat(chunks));
+};

package/src/dev/start_dev_server.js

@@ -48,7 +48,7 @@ const EXECUTED_BY_TEST_PLAN = process.argv.includes("--jsenv-test");
  * @param {Array} [params.serverPlugins=[]] - `@jsenv/server`-level plugins.
  * @param {boolean|object} [params.clientAutoreload=true] - Live reload; also gates the server-events channel.
  * @param {boolean|object} [params.serverTiming={ minDuration: 0.5 }] - server-timing response headers; `minDuration` (ms) drops entries that took less (0 when run by the test plan, so tests see every entry).
- * @param {boolean} [params.ribbon=true] - The dev "ribbon" overlay.
+ * @param {boolean|object} [params.ribbon=true] - The "ribbon" overlay marking the page as non-production. As an object: `text` (defaults to `"DEV"`), `color` (background, defaults to `"orange"`), `textColor` (defaults to dark or light depending on `color`), `href` (turns the ribbon into a link; only then does it capture clicks), `target` (defaults to `"_blank"`), `position` (`"top-right"` (default), `"top-left"`, `"bottom-right"`, `"bottom-left"` draw a diagonal corner ribbon; `"top"`, `"bottom"` draw a full width band), `htmlInclude` (defaults to `"/**\/*.html"`).
  * @param {boolean} [params.supervisor=true] - Script supervisor (better error reporting).
  * @param {boolean|object} [params.directoryListing=true] - Directory listing pages.
  * @param {object} [params.injections] - Values to inject into files, as `{ urlPattern: getInjections }`. Keys are url patterns relative to sourceDirectoryUrl (`"./index.html"`, `"**\/*.js"`), values are functions receiving `urlInfo` and returning (or resolving to) an object of placeholders to replace, named `__LIKE_THIS__` by convention. In JS the value is injected as a JS literal (a string brings its own quotes), everywhere else as-is so it can be concatenated: `href="__BACKEND_URL__/users/me"`. An html url pattern also covers what is inlined in that html, so `<script>window.backendUrl = __BACKEND_URL__;</script>` shares the value with every js file of the page. See `INJECTIONS.optional` and `INJECTIONS.global`.
@@ -265,6 +265,7 @@ export const startDevServer = async ({
       dependencyStatus: {
         dependencyProblemEventEmitter,
         getDependencyProblems: dependencyWatcher.getProblems,
+        getDependencyWatchInfo: dependencyWatcher.getWatchInfo,
       },
       cacheControl,
       ribbon,

package/src/helpers/watch_dependencies.js

@@ -23,8 +23,13 @@ export const watchDependencies = (
   { onProblem, onInstalled, onChange, pollInterval = POLL_INTERVAL },
 ) => {
   let problemMap = new Map();
+  // every path given to the browser is relative to the package directory, the
+  // one holding the package.json being watched
+  const packageJsonPath = "package.json";
   const watcher = {
     getProblems: () => Array.from(problemMap.values()),
+    // what the browser needs to display the watching in progress
+    getWatchInfo: () => ({ packageJsonPath, pollInterval }),
     stop: () => {},
   };
   if (!packageDirectory.url) {

package/src/kitchen/package_dependencies.js

@@ -12,6 +12,7 @@
  * would pick, which is way beyond what is needed here.
  */
 
+import { urlToRelativeUrl } from "@jsenv/urls";
 import { existsSync } from "node:fs";
 
 const DEPENDENCY_FIELDS = [
@@ -93,12 +94,21 @@ const createStatus = (
     declaredVersion,
     declaredBy,
     installedVersion: null,
+    // the file telling this dependency apart; it is what an install rewrites and
+    // what the dev server looks at to know the dependency became the declared one
+    watchedPath: null,
     state: "missing",
   };
   const installedDirectoryUrl = findInstalledDirectoryUrl(
     declaringDirectoryUrl,
     packageName,
   );
+  status.watchedPath = watchedPathFromDirectoryUrl(
+    packageDirectory,
+    // not installed yet: name the place where it is expected to appear
+    installedDirectoryUrl ||
+      `${declaringDirectoryUrl}node_modules/${packageName}/`,
+  );
   if (!installedDirectoryUrl) {
     return status;
   }
@@ -117,6 +127,14 @@ const createStatus = (
   return status;
 };
 
+const watchedPathFromDirectoryUrl = (packageDirectory, directoryUrl) => {
+  const packageJsonUrl = `${directoryUrl}package.json`;
+  if (!packageDirectory.url) {
+    return packageJsonUrl;
+  }
+  return urlToRelativeUrl(packageJsonUrl, packageDirectory.url);
+};
+
 const findInstalledDirectoryUrl = (declaringDirectoryUrl, packageName) => {
   let directoryUrl = declaringDirectoryUrl;
   while (directoryUrl) {