open-ready 0.1.115 → 0.2.1

package/README.md

@@ -22,7 +22,7 @@
 
 <!-- template-git-repo:badges:start -->
 <p align="center">
-    <a href="https://starterdocs.vtempest.workers.dev/docs/packages/open-when-ready"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
+    <a href="https://1computer.online/docs/packages/open-when-ready"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
     <br />
     <a href="https://github.com/OpenSourceAGI/dev-tools-starter-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/dev-tools-starter-agent" alt="GitHub Stars" /></a>
     <a href="https://www.npmjs.com/package/open-ready"><img src="https://img.shields.io/npm/dm/open-ready.svg" alt="NPM Monthly Downloads" /></a>
@@ -52,7 +52,7 @@
 
 Smart dev server launcher that watches your server's output and automatically opens the browser when ready — or opens an AI assistant with the error context when something goes wrong.
 
-Works with Next.js, Vite, and any CLI-based dev server.
+Works with Next.js, Vite, and any CLI-based dev server. When [portless](https://www.npmjs.com/package/portless) is installed, your app gets a stable named URL like `https://myapp.localhost` instead of a port number — and that's the URL that opens.
 
 ## Install
 
@@ -85,6 +85,24 @@ open-ready next dev
 | `--noAi` | `false` | Disable opening AI on error |
 | `--noOpen` | `false` | Disable opening browser when ready |
 | `--pollDelay <ms>` | `1200` | How often to poll the log for ready/error signals |
+| `--name <app>` | inferred | App name for the portless URL (`https://<app>.localhost`) |
+| `--no-portless` | `false` | Don't route through portless even if it's installed |
+| `--portless` | `false` | Use portless even without a TTY or when `CI` is set |
+
+### Named `.localhost` URLs with portless
+
+If `portless` is installed (globally, or in any `node_modules/.bin` up from the current directory), open-ready runs your command through it by default:
+
+```sh
+npm install -g portless       # Node >= 24
+
+open-ready next dev           # -> https://<package-name>.localhost
+open-ready next dev --name shop   # -> https://shop.localhost
+```
+
+The app name comes from `--name`, else the `package.json` name (scope dropped, e.g. `@acme/web` → `web`), else the directory name. open-ready starts the portless proxy in your terminal first, so the one-time sudo/CA-trust prompt happens there, then runs `portless run --name <app> <command>` and opens the URL portless prints once the dev server is ready.
+
+Without a TTY or with `CI` set, portless is skipped unless you pass `--portless` (the proxy must already be running). If portless isn't installed, or its proxy can't start, open-ready falls back to the plain `http://localhost:<port>` behaviour.
 
 ### Disable AI on error
 
@@ -105,7 +123,7 @@ open-ready npm run dev --ai-base "https://chatgpt.com/?q="
    - **Error signal** — lines matching `error`, `failed`, `exception`, `SyntaxError`, or `⨯`
    - **Ready signal** — lines matching `ready - started server` or `Ready in Xms`
 3. On **error**: extracts up to ~1000 chars of surrounding context and opens your AI assistant with a pre-filled prompt explaining the error and asking for a fix
-4. On **ready**: waits for the port to be reachable, then opens the local URL in your default browser
+4. On **ready**: waits for the port to be reachable, then opens the portless URL (when running through portless) or the local URL in your default browser
 
 For Next.js projects, the log is written to `.next/port.log`; otherwise `open-when-ready.log` in the current directory.
 

package/open-when-ready.mjs

@@ -5,23 +5,33 @@
  * output for a "ready" signal, and automatically opens the local URL in the
  * browser. If an error is detected first, it opens an AI assistant with the
  * error context for troubleshooting.
+ *
+ * When portless (npm: portless) is installed, the
+ * command is run through it by default so the app gets a stable named URL
+ * such as https://myapp.localhost, and that URL is the one opened.
  */
 
 import fsPromises from "fs/promises";
 import fs from "fs";
 import path from "path";
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
+import { fileURLToPath } from "url";
 import opener from "opener";
 import minimist from "minimist";
 import waitOn from "wait-on";
 
-const argv = minimist(process.argv.slice(2));
+const rawArgs = process.argv.slice(2);
+const argv = minimist(rawArgs, { string: ["name"], boolean: ["portless"] });
 const cmdArgs = argv._;
 const aiBase = argv["ai-base"] || "https://perplexity.ai?q=";
 const noAi = argv.noAi || argv.noai || argv.ai === false;
 const noOpen = argv.noOpen || argv.noopen || false;
 const maxErrorContextChars = 1000;
 const pollDelay = argv.pollDelay || 1200;
+// minimist defaults booleans to false, so read the explicit flags from argv.
+const noPortless =
+  argv.noPortless || argv.noportless || rawArgs.includes("--no-portless");
+const forcePortless = rawArgs.includes("--portless");
 
 const nextDir = path.join(".", ".next");
 const logPath = fs.existsSync(nextDir)
@@ -72,6 +82,138 @@ function extractUrl(log) {
   return null;
 }
 
+/**
+ * Derives a portless-safe app name (a single DNS label) from a package name or
+ * directory name: drops an npm scope, lowercases, and collapses anything that
+ * isn't a letter, digit or hyphen.
+ * @param {string} raw - Package or directory name
+ * @returns {string} Sanitized name, or empty string if nothing usable remains
+ */
+function sanitizeAppName(raw) {
+  return String(raw || "")
+    .replace(/^@[^/]+\//, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 63)
+    .replace(/-+$/, "");
+}
+
+/**
+ * Infers the app name for portless: package.json "name" in `cwd`, falling back
+ * to the directory name, then "app".
+ * @param {string} [cwd=process.cwd()] - Directory to infer from
+ * @returns {string} App name
+ */
+function inferAppName(cwd = process.cwd()) {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(cwd, "package.json"), "utf8"),
+    );
+    const fromPkg = sanitizeAppName(pkg.name);
+    if (fromPkg) return fromPkg;
+  } catch {}
+  return sanitizeAppName(path.basename(path.resolve(cwd))) || "app";
+}
+
+/**
+ * Locates the portless binary: a local node_modules/.bin (walking up from
+ * `cwd`), then the PATH.
+ * @param {string} [cwd=process.cwd()] - Directory to start searching from
+ * @param {string} [envPath=process.env.PATH] - PATH to search
+ * @returns {string|null} Absolute path to the binary, or null if not installed
+ */
+function findPortless(cwd = process.cwd(), envPath = process.env.PATH || "") {
+  const names =
+    process.platform === "win32"
+      ? ["portless.cmd", "portless.exe", "portless"]
+      : ["portless"];
+  const dirs = [];
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    dirs.push(path.join(dir, "node_modules", ".bin"));
+    if (path.dirname(dir) === dir) break;
+  }
+  dirs.push(...envPath.split(path.delimiter).filter(Boolean));
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      try {
+        if (fs.statSync(candidate).isFile()) return candidate;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+/**
+ * Builds the shell command to spawn. With a portless binary, the command is
+ * wrapped as `portless run --name <app> <command>`; otherwise it runs as-is.
+ * @param {string[]} args - The wrapped command and its arguments
+ * @param {{portlessBin?: string|null, appName?: string}} [opts]
+ * @returns {string} Shell command line
+ */
+function buildCommand(args, { portlessBin = null, appName = "" } = {}) {
+  const command = args.join(" ");
+  if (!portlessBin) return command;
+  return `"${portlessBin}" run --name ${appName} ${command}`;
+}
+
+/**
+ * Parses log output for the URL portless prints when it registers the app
+ * (a line like `-> https://myapp.localhost`).
+ * @param {string} log - Raw log output
+ * @returns {string|null} The portless URL, or null if not found
+ */
+function extractPortlessUrl(log) {
+  const clean = log.replace(/\x1b\[[0-9;]*m/g, "");
+  const match = clean.match(/^\s*->\s+(https?:\/\/\S+)/m);
+  return match ? match[1].replace(/\/+$/, "") : null;
+}
+
+/**
+ * Makes sure the portless proxy is running before the dev command is spawned.
+ * The wrapped command runs with piped, detached stdio, so portless cannot
+ * prompt for sudo (to bind 443 and trust its CA) from inside it. Starting the
+ * proxy here, attached to the terminal, lets that one-time prompt happen.
+ * @param {string} portlessBin - Path to the portless binary
+ * @returns {boolean} True if the proxy is (now) running
+ */
+function ensurePortlessProxy(portlessBin) {
+  const result = spawnSync(`"${portlessBin}" proxy start`, {
+    stdio: "inherit",
+    shell: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+/**
+ * Decides whether to run through portless and prepares it.
+ * @returns {{portlessBin: string|null, appName: string}}
+ */
+function resolvePortless() {
+  const appName = sanitizeAppName(argv.name) || inferAppName();
+  if (noPortless) return { portlessBin: null, appName };
+  const interactive = !!process.stdin.isTTY && !process.env.CI;
+  if (!interactive && !forcePortless) return { portlessBin: null, appName };
+  const portlessBin = findPortless();
+  if (!portlessBin) {
+    if (forcePortless) {
+      console.error(
+        "[open-ready] --portless given but portless is not installed (npm install -g portless). Running without it.",
+      );
+    }
+    return { portlessBin: null, appName };
+  }
+  if (interactive && !ensurePortlessProxy(portlessBin)) {
+    console.error(
+      "[open-ready] Could not start the portless proxy. Running without it.",
+    );
+    return { portlessBin: null, appName };
+  }
+  return { portlessBin, appName };
+}
+
 /**
  * Main entry point. Spawns the dev server command, pipes its output to a log
  * file, and polls the log for ready/error signals to open the browser or AI helper.
@@ -81,7 +223,8 @@ async function run() {
     await fsPromises.rm(logPath, { force: true });
   } catch {}
 
-  const proc = spawn(cmdArgs.join(" "), [], {
+  const { portlessBin, appName } = resolvePortless();
+  const proc = spawn(buildCommand(cmdArgs, { portlessBin, appName }), [], {
     stdio: ["ignore", "pipe", "pipe", "ipc"],
     shell: true,
     detached: true,
@@ -135,11 +278,16 @@ async function run() {
         opened = true;
         lastReadySeen = true;
         const url = extractUrl(currentLog);
-        if (url && !noOpen) {
-          try {
-            await waitOn(url, { timeout: 10000, http: true });
-          } catch {}
-          opener(url);
+        const portlessUrl = portlessBin ? extractPortlessUrl(currentLog) : null;
+        if ((url || portlessUrl) && !noOpen) {
+          // Wait on the app's own port; the portless URL sits behind a proxy
+          // with a locally-trusted CA that Node itself may not trust.
+          if (url) {
+            try {
+              await waitOn(url, { timeout: 10000, http: true });
+            } catch {}
+          }
+          opener(portlessUrl || url);
         }
         clearInterval(poll);
         return;
@@ -154,4 +302,25 @@ async function run() {
   });
 }
 
-run().catch(console.error);
+export {
+  sanitizeAppName,
+  inferAppName,
+  findPortless,
+  buildCommand,
+  extractPortlessUrl,
+  extractUrl,
+  getErrorContext,
+};
+
+function isMain() {
+  try {
+    return (
+      fs.realpathSync(process.argv[1]) ===
+      fs.realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) run().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-ready",
-  "version": "0.1.115",
+  "version": "0.2.1",
   "description": "Smart dev server launcher: error→AI search, success→auto-open browser. Any CLI tool.",
   "type": "module",
   "bin": {

package/test/portless.test.mjs

@@ -0,0 +1,106 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  buildCommand,
+  extractPortlessUrl,
+  extractUrl,
+  findPortless,
+  inferAppName,
+  sanitizeAppName,
+} from "../open-when-ready.mjs";
+
+let tmp;
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "open-ready-"));
+});
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("sanitizeAppName", () => {
+  it("drops the npm scope and lowercases", () => {
+    expect(sanitizeAppName("@MyOrg/Web-App")).toBe("web-app");
+  });
+  it("collapses invalid characters into single hyphens", () => {
+    expect(sanitizeAppName("my_cool..app!")).toBe("my-cool-app");
+  });
+  it("returns empty string for unusable input", () => {
+    expect(sanitizeAppName("___")).toBe("");
+    expect(sanitizeAppName(undefined)).toBe("");
+  });
+  it("caps the length at one DNS label", () => {
+    expect(sanitizeAppName("a".repeat(100))).toHaveLength(63);
+  });
+});
+
+describe("inferAppName", () => {
+  it("uses the package.json name", () => {
+    fs.writeFileSync(
+      path.join(tmp, "package.json"),
+      JSON.stringify({ name: "@acme/dashboard" }),
+    );
+    expect(inferAppName(tmp)).toBe("dashboard");
+  });
+  it("falls back to the directory name", () => {
+    const dir = path.join(tmp, "My Project");
+    fs.mkdirSync(dir);
+    expect(inferAppName(dir)).toBe("my-project");
+  });
+});
+
+describe("findPortless", () => {
+  it("finds a local node_modules/.bin binary walking up", () => {
+    const bin = path.join(tmp, "node_modules", ".bin");
+    fs.mkdirSync(bin, { recursive: true });
+    fs.writeFileSync(path.join(bin, "portless"), "");
+    const nested = path.join(tmp, "apps", "web");
+    fs.mkdirSync(nested, { recursive: true });
+    expect(findPortless(nested, "")).toBe(path.join(bin, "portless"));
+  });
+  it("falls back to PATH", () => {
+    const pathDir = path.join(tmp, "bin");
+    fs.mkdirSync(pathDir);
+    fs.writeFileSync(path.join(pathDir, "portless"), "");
+    const cwd = path.join(tmp, "app");
+    fs.mkdirSync(cwd);
+    expect(findPortless(cwd, pathDir)).toBe(path.join(pathDir, "portless"));
+  });
+  it("returns null when not installed", () => {
+    expect(findPortless(tmp, "")).toBeNull();
+  });
+});
+
+describe("buildCommand", () => {
+  it("runs the command as-is without portless", () => {
+    expect(buildCommand(["next", "dev"])).toBe("next dev");
+  });
+  it("wraps the command with portless run --name", () => {
+    expect(
+      buildCommand(["next", "dev"], {
+        portlessBin: "/usr/bin/portless",
+        appName: "myapp",
+      }),
+    ).toBe('"/usr/bin/portless" run --name myapp next dev');
+  });
+});
+
+describe("extractPortlessUrl", () => {
+  it("reads the URL portless prints", () => {
+    const log = "Starting proxy...\n\n  -> https://myapp.localhost\n\nRunning: PORT=4123 next dev\n";
+    expect(extractPortlessUrl(log)).toBe("https://myapp.localhost");
+  });
+  it("ignores ANSI color codes", () => {
+    const log = "\x1b[36m\x1b[1m\n  -> https://fix-ui.myapp.localhost:1355\n\x1b[22m\x1b[39m";
+    expect(extractPortlessUrl(log)).toBe("https://fix-ui.myapp.localhost:1355");
+  });
+  it("returns null without a portless line", () => {
+    expect(extractPortlessUrl("  - Local: http://localhost:3000")).toBeNull();
+  });
+  it("coexists with the framework's own localhost URL", () => {
+    const log = "  -> https://myapp.localhost\n  - Local: http://localhost:4123\n ✓ Ready in 900ms";
+    expect(extractPortlessUrl(log)).toBe("https://myapp.localhost");
+    expect(extractUrl(log)).toBe("http://localhost:4123");
+  });
+});