feat(inspector): let run scripts declare their Open menu URL

Helmor derives the Run tab's Open menu by regex-sniffing stdout for
`http://{localhost,127.0.0.1,0.0.0.0}:PORT` banners. That breaks under a
reverse proxy: with portless, Caddy, ngrok, or Tailscale Funnel the
services behind the proxy print ephemeral ports that are neither
reachable nor stable across boots, while the address users actually need
is a named domain nobody prints in a recognizable banner.

Run scripts can now declare it explicitly by printing a marker line:

    echo "helmor:url=https://${HELMOR_WORKSPACE_NAME}.localhost"

Declared URLs accept any host (not just the three local forms), and take
precedence over sniffed ones rather than joining them — a script that
declares its address is telling us the sniffed ports are wrong, not that
they are extra options worth offering. Repeating the marker declares
multiple URLs, which surface in the existing 2+ picker.

Detection waits for the terminating newline before committing a match,
since PTY output splits on arbitrary 4096-byte boundaries and a marker
truncated mid-URL still parses as a well-formed one.

No backend change: HELMOR_WORKSPACE_NAME is already exported into the
script environment, so per-workspace interpolation works with no schema
column and no new CLI flag.

Author: dalkommatt

.changeset/run-script-declared-url.md

@@ -0,0 +1,5 @@
+---
+"helmor": patch
+---
+
+Let run scripts declare their own URL for the Open menu by printing `helmor:url=<URL>` on a line of their own — useful for reverse-proxy dev setups (portless, Caddy, ngrok, Tailscale Funnel) where Helmor's sniffed `localhost:PORT` banners are ephemeral ports that aren't reachable through the proxy. Declared URLs accept any host and fully replace the sniffed ones.

src/features/inspector/detect-urls.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "vitest";
 import {
 	dedupUrlKey,
+	extractDeclaredUrls,
 	extractLocalUrls,
 	extractPort,
 	stripAnsi,
+	trailingPartialLine,
 } from "./detect-urls";
 
 describe("stripAnsi", () => {
@@ -169,3 +171,73 @@ describe("extractPort", () => {
 		expect(extractPort("https://localhost")).toBeNull();
 	});
 });
+
+describe("extractDeclaredUrls", () => {
+	it("extracts a marker URL with a named host and no port", () => {
+		expect(
+			extractDeclaredUrls("helmor:url=https://achernar.localhost"),
+		).toEqual(["https://achernar.localhost"]);
+	});
+
+	it("survives ANSI wrapping and CRLF line endings", () => {
+		expect(
+			extractDeclaredUrls(
+				"\x1b[32mhelmor:url=https://achernar.localhost\x1b[0m\r\nbooting…\r\n",
+			),
+		).toEqual(["https://achernar.localhost"]);
+	});
+
+	it("tolerates leading indentation", () => {
+		expect(extractDeclaredUrls("  \thelmor:url=http://app.test\n")).toEqual([
+			"http://app.test",
+		]);
+	});
+
+	it("collects multiple declarations in order", () => {
+		expect(
+			extractDeclaredUrls(
+				"helmor:url=https://web.localhost\nnoise\nhelmor:url=https://api.localhost\n",
+			),
+		).toEqual(["https://web.localhost", "https://api.localhost"]);
+	});
+
+	it("ignores markers that are not at the start of a line", () => {
+		expect(
+			extractDeclaredUrls("see helmor:url=https://evil.test for details"),
+		).toEqual([]);
+	});
+
+	it("ignores non-http schemes", () => {
+		expect(extractDeclaredUrls("helmor:url=ftp://nope.test\n")).toEqual([]);
+		expect(extractDeclaredUrls("helmor:url=nonsense\n")).toEqual([]);
+	});
+
+	it("strips trailing sentence punctuation", () => {
+		expect(extractDeclaredUrls("helmor:url=https://app.test.\n")).toEqual([
+			"https://app.test",
+		]);
+	});
+
+	it("is stateless across calls despite the shared global regex", () => {
+		const input = "helmor:url=https://app.test\n";
+		expect(extractDeclaredUrls(input)).toEqual(extractDeclaredUrls(input));
+	});
+});
+
+describe("trailingPartialLine", () => {
+	it("returns text after the last newline", () => {
+		expect(trailingPartialLine("a\nb\nhelmor:url=htt")).toBe("helmor:url=htt");
+	});
+
+	it("returns the whole input when there is no newline", () => {
+		expect(trailingPartialLine("partial")).toBe("partial");
+	});
+
+	it("returns empty when the chunk ends on a newline", () => {
+		expect(trailingPartialLine("done\n")).toBe("");
+	});
+
+	it("caps runaway single-line output", () => {
+		expect(trailingPartialLine("x".repeat(5000), 2048)).toHaveLength(2048);
+	});
+});

src/features/inspector/detect-urls.ts

@@ -31,10 +31,62 @@ const ANSI_RE = new RegExp(
 const LOCAL_URL_RE =
 	/\bhttps?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::\d+)?(?:\/[^\s"'`<>)\]]*)?/gi;
 
+// Marker a run script prints to declare the URL Helmor should offer in the
+// Open menu. Anchored to the start of a line (leading whitespace allowed) so
+// it can't be triggered by a URL appearing mid-prose. The host part is
+// deliberately unrestricted — unlike LOCAL_URL_RE this must accept named
+// domains, which is the entire point of the feature.
+const DECLARED_URL_RE = /^[ \t]*helmor:url=(https?:\/\/[^\s"'`<>]+)/gim;
+
 export function stripAnsi(input: string): string {
 	return input.replace(ANSI_RE, "");
 }
 
+/**
+ * Extract URLs a run script has explicitly declared via `helmor:url=<URL>`
+ * lines in its output.
+ *
+ * Sniffing `http://localhost:PORT` out of stdout works for plain dev servers
+ * but breaks under a reverse proxy: with portless, Caddy, ngrok, or Tailscale
+ * Funnel the services behind the proxy print ephemeral ports that are neither
+ * reachable nor stable, while the address users actually need is a named
+ * domain nobody prints in a recognizable banner. Declaring it explicitly is
+ * the escape hatch:
+ *
+ *     echo "helmor:url=https://${HELMOR_WORKSPACE_NAME}.localhost"
+ *
+ * Repeating the marker declares multiple URLs (e.g. web + api in a monorepo),
+ * which surface in the Open menu's picker. Declared URLs take precedence over
+ * sniffed ones — see the script store.
+ */
+export function extractDeclaredUrls(input: string): string[] {
+	const clean = stripAnsi(input);
+	const out: string[] = [];
+	// Shared regex object with the `g` flag carries `lastIndex` between calls.
+	DECLARED_URL_RE.lastIndex = 0;
+	let match = DECLARED_URL_RE.exec(clean);
+	while (match !== null) {
+		out.push(match[1].replace(/[.,;:!?]+$/, ""));
+		match = DECLARED_URL_RE.exec(clean);
+	}
+	return out;
+}
+
+/**
+ * Return the trailing partial line of a chunk — everything after the last
+ * newline — capped so a pathological single-line stream (a progress bar
+ * redrawing with `\r`) can't grow the carry buffer without bound.
+ *
+ * PTY output is split on arbitrary 4096-byte boundaries, so a marker line can
+ * straddle two chunks. Carrying the partial line forward and re-scanning it
+ * with the next chunk makes detection boundary-proof.
+ */
+export function trailingPartialLine(input: string, cap = 2048): string {
+	const idx = input.lastIndexOf("\n");
+	const tail = idx === -1 ? input : input.slice(idx + 1);
+	return tail.length > cap ? tail.slice(-cap) : tail;
+}
+
 /**
  * Extract normalized dev-server URLs from a chunk of shell output. Returns
  * URLs in the order they appear. Caller is responsible for deduping across

src/features/inspector/script-store.test.ts

@@ -28,8 +28,14 @@ vi.mock("@/lib/api", async (importOriginal) => {
 });
 
 // Dynamic import so vi.mock is applied before module evaluation.
-const { _resetForTesting, getScriptState, startScript, TRUNCATION_NOTICE } =
-	await import("./script-store");
+const {
+	_resetForTesting,
+	attach,
+	effectiveScriptUrls,
+	getScriptState,
+	startScript,
+	TRUNCATION_NOTICE,
+} = await import("./script-store");
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -132,3 +138,73 @@ describe("script-store ring buffer", () => {
 		expect(TRUNCATION_NOTICE).toContain("\x1b[0m");
 	});
 });
+
+describe("script-store URL detection", () => {
+	it("sniffs localhost banners when nothing is declared", () => {
+		const emit = startAndCapture();
+		emit({ type: "stdout", data: "  Local: http://localhost:5173/\n" });
+
+		const entry = getScriptState("ws1", "run");
+		expect(effectiveScriptUrls(entry!)).toEqual(["http://localhost:5173/"]);
+	});
+
+	it("lets a declared URL replace already-sniffed ephemeral ports", () => {
+		const emit = startAndCapture();
+		// A portless-style boot: proxied services announce raw ephemeral ports
+		// that are not reachable through the proxy…
+		emit({ type: "stdout", data: "web ready http://localhost:4761\n" });
+		emit({ type: "stdout", data: "api ready http://localhost:4786\n" });
+		const entry = getScriptState("ws1", "run");
+		expect(effectiveScriptUrls(entry!)).toHaveLength(2);
+
+		// …then the run script declares the address that actually works.
+		emit({ type: "stdout", data: "helmor:url=https://achernar.localhost\n" });
+
+		expect(effectiveScriptUrls(entry!)).toEqual(["https://achernar.localhost"]);
+	});
+
+	it("stops collecting sniffed URLs once one is declared", () => {
+		const emit = startAndCapture();
+		emit({ type: "stdout", data: "helmor:url=https://achernar.localhost\n" });
+		emit({ type: "stdout", data: "listening on http://localhost:4761\n" });
+
+		const entry = getScriptState("ws1", "run");
+		expect(effectiveScriptUrls(entry!)).toEqual(["https://achernar.localhost"]);
+	});
+
+	it("detects a marker split across PTY chunk boundaries", () => {
+		const emit = startAndCapture();
+		emit({ type: "stdout", data: "booting\nhelmor:url=https://ach" });
+		emit({ type: "stdout", data: "ernar.localhost\nready\n" });
+
+		const entry = getScriptState("ws1", "run");
+		expect(effectiveScriptUrls(entry!)).toEqual(["https://achernar.localhost"]);
+	});
+
+	it("keeps multiple declared URLs in first-seen order without duplicates", () => {
+		const emit = startAndCapture();
+		emit({ type: "stdout", data: "helmor:url=https://web.localhost\n" });
+		emit({ type: "stdout", data: "helmor:url=https://api.localhost\n" });
+		emit({ type: "stdout", data: "helmor:url=https://web.localhost\n" });
+
+		const entry = getScriptState("ws1", "run");
+		expect(effectiveScriptUrls(entry!)).toEqual([
+			"https://web.localhost",
+			"https://api.localhost",
+		]);
+	});
+
+	it("notifies listeners when a declaration supersedes sniffed URLs", () => {
+		const seen: string[][] = [];
+		const emit = startAndCapture();
+		attach("ws1", "run", {
+			onChunk: () => {},
+			onStatusChange: () => {},
+			onUrlsChange: (urls) => seen.push(urls),
+		});
+		emit({ type: "stdout", data: "http://localhost:4761\n" });
+		emit({ type: "stdout", data: "helmor:url=https://achernar.localhost\n" });
+
+		expect(seen.at(-1)).toEqual(["https://achernar.localhost"]);
+	});
+});

src/features/inspector/script-store.ts

@@ -5,7 +5,12 @@ import {
 	stopRepoScript,
 	writeRepoScriptStdin,
 } from "@/lib/api";
-import { dedupUrlKey, extractLocalUrls } from "./detect-urls";
+import {
+	dedupUrlKey,
+	extractDeclaredUrls,
+	extractLocalUrls,
+	trailingPartialLine,
+} from "./detect-urls";
 
 export type ScriptStatus = "idle" | "running" | "exited";
 
@@ -52,8 +57,29 @@ export type ScriptEntry = {
 	 * as new chunks arrive. Empty when the script hasn't printed any banner.
 	 */
 	urls: string[];
+	/**
+	 * URLs the script explicitly declared via `helmor:url=<URL>` lines. When
+	 * non-empty these fully replace {@link urls} in the Open menu — a script
+	 * that declares its address is telling us the sniffed localhost ports are
+	 * wrong (typically ephemeral ports behind a reverse proxy), not that they
+	 * are extra options worth offering.
+	 */
+	declaredUrls: string[];
+	/**
+	 * Trailing partial line carried over from the previous chunk, so marker
+	 * lines split across PTY chunk boundaries are still detected.
+	 */
+	tail: string;
 };
 
+/**
+ * URLs to surface in the Open menu: explicitly declared ones win over sniffed
+ * localhost banners.
+ */
+export function effectiveScriptUrls(entry: ScriptEntry): string[] {
+	return entry.declaredUrls.length > 0 ? entry.declaredUrls : entry.urls;
+}
+
 /** Append a chunk and evict from the head until under the byte cap. */
 function appendChunk(entry: ScriptEntry, data: string) {
 	entry.chunks.push(data);
@@ -110,6 +136,8 @@ export function startScript(
 		status: "running",
 		exitCode: null,
 		urls: [],
+		declaredUrls: [],
+		tail: "",
 	};
 	entries.set(k, entry);
 
@@ -137,15 +165,51 @@ export function startScript(
 					// no URL. Skip the regex work when the chunk can't possibly
 					// contain one. `event.data.includes("http")` is a plain
 					// substring scan — ~100x faster than the ANSI+URL regex
-					// combo and totally safe (any real localhost URL has "http"
-					// verbatim in bytes, even when wrapped in ANSI).
+					// combo and totally safe (any real URL, sniffed or declared,
+					// has "http" verbatim in bytes, even when wrapped in ANSI).
 					//
 					// We still run detection on every chunk until we've seen at
 					// least one URL, so the initial banner is never missed.
-					if (entry.urls.length > 0 && !event.data.includes("http")) {
+					if (
+						entry.urls.length + entry.declaredUrls.length > 0 &&
+						!event.data.includes("http")
+					) {
+						entry.tail = trailingPartialLine(entry.tail + event.data);
 						break;
 					}
 
+					// Rejoin the previous chunk's trailing partial line with the new
+					// data, then consider only the newline-terminated portion. A
+					// marker split across a PTY chunk boundary would otherwise be
+					// committed truncated — `helmor:url=https://ach` is a perfectly
+					// well-formed URL as far as the regex is concerned, so waiting
+					// for the terminating newline is the only safe signal that we
+					// have the whole thing.
+					const scan = entry.tail + event.data;
+					const lastNewline = scan.lastIndexOf("\n");
+					const completeLines =
+						lastNewline === -1 ? "" : scan.slice(0, lastNewline + 1);
+					entry.tail = trailingPartialLine(scan);
+
+					// Explicit `helmor:url=` declarations win outright: once a
+					// script has told us its address, sniffed localhost banners are
+					// noise (ephemeral ports behind a reverse proxy) and we stop
+					// collecting them entirely.
+					const declared = extractDeclaredUrls(completeLines);
+					if (declared.length > 0) {
+						let changed = false;
+						for (const url of declared) {
+							if (!entry.declaredUrls.includes(url)) {
+								entry.declaredUrls.push(url);
+								changed = true;
+							}
+						}
+						if (changed) {
+							listeners.get(k)?.onUrlsChange?.([...entry.declaredUrls]);
+						}
+					}
+					if (entry.declaredUrls.length > 0) break;
+
 					// Scan the fresh chunk for dev-server URLs. We keep a deduped,
 					// first-seen-ordered list on the entry and only fire the listener
 					// when something actually changed.

src/features/inspector/sections/run.tsx

@@ -20,6 +20,7 @@ import { TABS_EASING, TABS_HOVER_TRANSITION_MS, useTabsZoom } from "../layout";
 import {
 	attach,
 	detach,
+	effectiveScriptUrls,
 	resizeScript,
 	type ScriptStatus,
 	startScript,
@@ -182,7 +183,7 @@ export function RunTab({
 			setStatus(existing.status);
 			// Replay URLs already detected on this entry so the parent's state
 			// mirrors the store the moment the component mounts.
-			onUrlsChange?.([...existing.urls]);
+			onUrlsChange?.(effectiveScriptUrls(existing));
 			const replay = () => {
 				const t = termRef.current;
 				if (!t) return;