backlens 0.1.0 → 0.1.1

package/README.md

@@ -12,6 +12,10 @@ The link backlens prints carries a private token: keep it to yourself, it contro
 
 To run one exact command instead: `npx backlens -- node server.js`.
 
+To keep it in the project, install it as a dev dependency with your package manager (`npm i -D backlens`, `pnpm add -D backlens`, `yarn add -D backlens`). In a pnpm or yarn workspace, use that tool: npm cannot install into a project whose package.json uses `workspace:` versions.
+
+The dashboard uses port 7777, or the next free one if it is taken. `--port` picks one.
+
 ## What you get
 
 - **Routes**: every endpoint your app registers (fastify and nest report them at startup; express routes appear once called), with calls, p50 and p95, and how many database, Redis and outgoing HTTP calls each request makes.

package/bin/backlens.js

@@ -42,19 +42,25 @@ if (testMode) await runTests();
 else await runStudio();
 
 async function runStudio() {
-  const port = Number(flag('--port') ?? 7777);
+  const chosen = flag('--port');
+  // Without --port, a busy 7777 (another backlens, say) moves on to the next free port.
+  const ports = chosen ? [Number(chosen)] : Array.from({ length: 20 }, (_, i) => 7777 + i);
   let server;
-  try {
-    server = await startServer({
-      port,
-      root,
-      token,
-      manualArgv: command.length ? command : null,
-      mirror: (line, stream) => process.stderr.write(`${dim('app │')} ${stream === 'sys' ? dim(line) : line}\n`),
-    });
-  } catch (err) {
-    process.stderr.write(`backlens: could not open port ${port} (${err.code ?? err.message}). Try --port.\n`);
-    process.exit(1);
+  for (const port of ports) {
+    try {
+      server = await startServer({
+        port,
+        root,
+        token,
+        manualArgv: command.length ? command : null,
+        mirror: (line, stream) => process.stderr.write(`${dim('app │')} ${stream === 'sys' ? dim(line) : line}\n`),
+      });
+      break;
+    } catch (err) {
+      if (err.code === 'EADDRINUSE' && port !== ports.at(-1)) continue;
+      process.stderr.write(`backlens: could not open port ${port} (${err.code ?? err.message}). Try --port.\n`);
+      process.exit(1);
+    }
   }
   const link = `http://localhost:${server.address().port}/?t=${token}`;
   process.stderr.write(`${bold('backlens')} dashboard ${bold(link)}\n${dim('         keep this link private: it controls your app. Ctrl+C stops everything.')}\n\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlens",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Run your Node backend through backlens and see every request, every query, and what is wrong with them.",
   "license": "MIT",
   "type": "module",