@getmonoceros/workbench 1.36.3 → 1.36.4

package/dist/bin.js

@@ -2132,52 +2132,90 @@ async function preflightHostPort(hostPort, opts = {}) {
   const probe = opts.portProbe ?? realPortProbe;
   const result = await probe(hostPort);
   if (result.ok) return;
-  throw new Error(
-    formatHostPortHeldError(hostPort, result.code, result.message)
-  );
-}
-function formatHostPortHeldError(hostPort, code, systemMessage) {
-  const isInUse = code === "EADDRINUSE";
-  const lines = [];
-  if (isInUse) {
-    lines.push(`Host port ${hostPort} is already in use by another process.`);
-    lines.push("");
-    lines.push(`Monoceros needs that port for its Traefik proxy (the thing`);
-    lines.push(`that routes <name>.localhost / <name>-<port>.localhost to`);
-    lines.push(`your dev-container). Two ways out:`);
-    lines.push("");
-    lines.push("  1) Recommended: free the port.");
-    lines.push("     Identify the process holding it:");
-    lines.push(`        sudo lsof -iTCP:${hostPort} -sTCP:LISTEN -n -P`);
-    lines.push(`        # or:   sudo ss -tlnp | grep ":${hostPort}\\b"`);
-    lines.push("     Then stop or reconfigure that service.");
-    lines.push("");
-    lines.push("  2) Move Monoceros off port 80. Edit (or create)");
-    lines.push("     ~/.monoceros/monoceros-config.yml and add:");
-    lines.push("");
-    lines.push("        schemaVersion: 1");
-    lines.push("        routing:");
-    lines.push("          hostPort: 8080      # any free port");
-    lines.push("");
-    lines.push("     URLs will become http://<name>.localhost:8080/.");
-    lines.push("");
-    lines.push(`Aborting \u2014 re-run after the conflict is resolved.`);
-  } else {
-    lines.push(`Cannot reach host port ${hostPort}: ${systemMessage}`);
-    lines.push("");
-    lines.push(`This is not the typical "port already in use" case \u2014`);
-    lines.push(`Monoceros's pre-flight uses a TCP-connect probe (not a`);
-    lines.push(`bind), so EACCES / privileged-port errors normally don't`);
-    lines.push(`appear here. Most likely something on your host network`);
-    lines.push(`stack (firewall, network namespace, \u2026) is interfering with`);
-    lines.push(`loopback connects.`);
-    lines.push("");
-    lines.push("Workaround: move Monoceros off this port by setting");
-    lines.push("`routing.hostPort` in ~/.monoceros/monoceros-config.yml.");
-    lines.push("");
-    lines.push(`Aborting \u2014 re-run after the issue is resolved.`);
+  if (result.code !== "EADDRINUSE") {
+    throw new Error(
+      formatHostPortHeldError(hostPort, result.code, result.message)
+    );
   }
-  return lines.join("\n");
+  const live = await containersPublishing(docker, hostPort);
+  if (live.length > 0) {
+    throw new Error(formatLiveContainerError(hostPort, live));
+  }
+  throw new Error(formatLeftoverHolderError(hostPort));
+}
+async function containersPublishing(docker, hostPort) {
+  const ps = await docker([
+    "ps",
+    "--filter",
+    `publish=${hostPort}`,
+    "--format",
+    "{{.Names}} ({{.Image}})"
+  ]);
+  if (ps.exitCode !== 0) return [];
+  return ps.stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+}
+function formatLiveContainerError(hostPort, containers) {
+  const firstName = containers[0].split(" ")[0];
+  return [
+    `Host port ${hostPort} is in use: it is published by a running container.`,
+    "",
+    `Monoceros needs that port for its Traefik proxy. The container(s) holding it:`,
+    ...containers.map((c) => `  - ${c}`),
+    "",
+    `Stop or re-map it, then re-run, e.g.:`,
+    "",
+    `    docker stop ${firstName}`,
+    "",
+    `Or move Monoceros off the port: set \`routing.hostPort\` in`,
+    `~/.monoceros/monoceros-config.yml.`,
+    "",
+    `Aborting. Re-run after the conflict is resolved.`
+  ].join("\n");
+}
+function formatLeftoverHolderError(hostPort) {
+  return [
+    `Host port ${hostPort} is in use, but no Docker container in the active`,
+    `engine publishes it.`,
+    "",
+    `This is almost always a leftover Docker port-forwarder (docker-proxy)`,
+    `whose container is already gone. It is left behind when a native Docker`,
+    `daemon is restarted while a container held the port, which is common with`,
+    `dockerd-via-systemd inside WSL (WSL restarts it on every shutdown). The`,
+    `forwarder keeps the port bound with nothing behind it. Two ways out:`,
+    "",
+    `  1) Recommended: reap the leftover by restarting the Docker daemon`,
+    `     (harmless, it just clears stale forwarders):`,
+    `        WSL / native dockerd:  sudo systemctl restart docker`,
+    `        Docker Desktop:        restart it from its menu`,
+    `     Then re-run.`,
+    "",
+    `  2) Or move Monoceros off port ${hostPort}. Edit (or create)`,
+    `     ~/.monoceros/monoceros-config.yml and add:`,
+    "",
+    `        schemaVersion: 1`,
+    `        routing:`,
+    `          hostPort: 8080      # any free port`,
+    "",
+    `     URLs then become http://<name>.localhost:8080/.`,
+    "",
+    `Aborting. Re-run after the conflict is resolved.`
+  ].join("\n");
+}
+function formatHostPortHeldError(hostPort, _code, systemMessage) {
+  return [
+    `Cannot reach host port ${hostPort}: ${systemMessage}`,
+    "",
+    `This is not the typical "port already in use" case.`,
+    `Monoceros's pre-flight uses a TCP-connect probe (not a bind), so`,
+    `EACCES / privileged-port errors normally don't appear here. Most`,
+    `likely something on your host network stack (firewall, network`,
+    `namespace, \u2026) is interfering with loopback connects.`,
+    "",
+    "Workaround: move Monoceros off this port by setting",
+    "`routing.hostPort` in ~/.monoceros/monoceros-config.yml.",
+    "",
+    `Aborting. Re-run after the issue is resolved.`
+  ].join("\n");
 }
 var CONNECT_TIMEOUT_MS, realPortProbe;
 var init_port_check = __esm({
@@ -4308,6 +4346,8 @@ var init_transform = __esm({
 // src/briefing/agents-md.ts
 function generateAgentsMd(input) {
   const lines = [];
+  const hostPort = input.hostPort ?? 80;
+  const portSuffix = hostPort === 80 ? "" : `:${hostPort}`;
   lines.push("# Monoceros Container \u2014 Stack Briefing");
   lines.push("");
   lines.push(
@@ -4435,18 +4475,18 @@ function generateAgentsMd(input) {
       const port = input.ports[i];
       if (i === 0) {
         lines.push(
-          `- ${port} (default route) \u2192 http://${input.containerName}.localhost`
+          `- ${port} (default route) \u2192 http://${input.containerName}.localhost${portSuffix}`
         );
       } else {
         lines.push(
-          `- ${port} \u2192 http://${input.containerName}-${port}.localhost`
+          `- ${port} \u2192 http://${input.containerName}-${port}.localhost${portSuffix}`
         );
       }
     }
     lines.push("");
     lines.push(
       "To show the user a running app, open it in their host browser with",
-      `\`xdg-open http://${input.containerName}.localhost\` \u2014 Monoceros relays`,
+      `\`xdg-open http://${input.containerName}.localhost${portSuffix}\` \u2014 Monoceros relays`,
       "browser-opens from the container to the host machine. Also tell the user",
       "the URL, so they can open it themselves if no bridge is active."
     );
@@ -4466,7 +4506,7 @@ function generateAgentsMd(input) {
       "  Angular `--allowed-hosts`, CRA `DANGEROUSLY_DISABLE_HOST_CHECK`;",
       "- it does **not pin the HMR/live-reload socket** to a fixed host or port",
       "  \u2014 let it follow the page URL (e.g. for Vite, do not set",
-      "  `server.hmr.clientPort`), so HMR works on `<name>.localhost` and over",
+      `  \`server.hmr.clientPort\`), so HMR works on \`<name>.localhost${portSuffix}\` and over`,
       "  the LAN alike;",
       "- the **backend is reached via the dev-server proxy** under a relative",
       "  path (Vite `server.proxy`, Angular `proxy.conf.json`, CRA",
@@ -4551,7 +4591,7 @@ function generateAgentsMd(input) {
       "When you build something that serves on a port (a web app, an API),",
       "it must keep running after this session ends. A plain `npm start` (or",
       "any foreground start) dies the moment the user exits you or closes the",
-      `terminal, and then \`${input.containerName}.localhost\` returns 502 Bad Gateway.`
+      `terminal, and then \`${input.containerName}.localhost${portSuffix}\` returns 502 Bad Gateway.`
     );
     lines.push("");
     lines.push(
@@ -4643,7 +4683,7 @@ function formatServiceLine(svc) {
   }
   return `- **${svc.name}** (custom image \`${svc.image}\`) \u2014 reachable at \`${reach}\``;
 }
-function agentsMdInputFromCreateOptions(opts, featureDisplayMap2, manifestLoader) {
+function agentsMdInputFromCreateOptions(opts, featureDisplayMap2, manifestLoader, hostPort = 80) {
   const features = [];
   for (const [ref, userOptions] of Object.entries(opts.features ?? {})) {
     const manifest = manifestLoader?.(ref);
@@ -4663,7 +4703,8 @@ function agentsMdInputFromCreateOptions(opts, featureDisplayMap2, manifestLoader
     services: opts.services,
     features,
     repos: opts.repos ?? [],
-    ports: opts.ports ?? []
+    ports: opts.ports ?? [],
+    hostPort
   };
 }
 function resolveFeatureLines(ref, userOptions, manifest, featureDisplayMap2) {
@@ -4929,7 +4970,8 @@ async function writeBriefing(input) {
     agentsMdInputFromCreateOptions(
       input.createOpts,
       featureDisplayMap(input.components),
-      manifestLoader
+      manifestLoader,
+      input.hostPort ?? 80
     )
   );
   const claudeBody = generateClaudeMd();
@@ -8317,7 +8359,12 @@ Fix the value in the env file (or the yml).`
   }
   try {
     const components = await loadComponentCatalog();
-    await writeBriefing({ targetDir, createOpts, components });
+    await writeBriefing({
+      targetDir,
+      createOpts,
+      components,
+      hostPort: proxyHostPort(globalConfig)
+    });
   } catch (err) {
     const msg = `briefing files not written: ${err instanceof Error ? err.message : String(err)}`;
     (logger.warn ?? logger.info)(msg);
@@ -8810,7 +8857,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "1.36.3" : "dev";
+    CLI_VERSION = true ? "1.36.4" : "dev";
   }
 });