fix: handle browse install resolution and CDN diagnostics

Author: danjdewhurst

setup.sh

@@ -87,8 +87,10 @@ echo "  ✓ dist/browse ($OS-$ARCH_LABEL)"
 echo ""
 echo "[5/5] Creating symlink..."
 
-# Target: ~/.local/bin/browse
-SYMLINK_DIR="$HOME/.local/bin"
+# Target: ~/.local/bin/browse by default.
+# Override with INSTALL_DIR=/usr/local/bin ./setup.sh when a system PATH entry
+# should own the command name.
+SYMLINK_DIR="${INSTALL_DIR:-$HOME/.local/bin}"
 SYMLINK_PATH="$SYMLINK_DIR/browse"
 
 mkdir -p "$SYMLINK_DIR"
@@ -101,11 +103,25 @@ ln -s "$SCRIPT_DIR/dist/browse" "$SYMLINK_PATH"
 echo "  ✓ $SYMLINK_PATH → $SCRIPT_DIR/dist/browse"
 
 if ! echo "$PATH" | tr ':' '\n' | grep -q "$SYMLINK_DIR"; then
-  echo ""
-  echo "Note: ~/.local/bin is not on your PATH. Add it with:"
-  echo "  export PATH=\"\$HOME/.local/bin:\$PATH\""
-  echo "Add this to your shell profile (~/.zshrc or ~/.bashrc) to make it permanent."
+	echo ""
+	echo "Warning: $SYMLINK_DIR is not on your PATH. Add it with:"
+	echo "  export PATH=\"$SYMLINK_DIR:\$PATH\""
+	echo "Add this to your shell profile (~/.zshrc or ~/.bashrc) to make it permanent."
+fi
+
+RESOLVED_BROWSE="$(command -v browse || true)"
+if [ -n "$RESOLVED_BROWSE" ] && [ "$RESOLVED_BROWSE" != "$SYMLINK_PATH" ]; then
+	echo ""
+	echo "Warning: 'browse' currently resolves to:"
+	echo "  $RESOLVED_BROWSE"
+	echo "not the installed CLI:"
+	echo "  $SYMLINK_PATH"
+	echo "Run '$SYMLINK_PATH ...', move $SYMLINK_DIR earlier in PATH, or reinstall with INSTALL_DIR set to an earlier PATH directory."
+elif [ -z "$RESOLVED_BROWSE" ]; then
+	echo ""
+	echo "Warning: 'browse' is not currently resolvable from PATH."
+	echo "Run '$SYMLINK_PATH ...' or add $SYMLINK_DIR to PATH."
 fi
 
 echo ""
-echo "Setup complete. Run 'browse goto https://example.com' to get started."
+echo "Setup complete. Run '$SYMLINK_PATH goto https://example.com' to get started."

src/cli.ts

@@ -87,6 +87,10 @@ function resolveBrowserFromFlag(flag?: string): BrowserName | undefined {
 	return undefined;
 }
 
+function looksLikeUrl(value: string): boolean {
+	return /^(?:https?:\/\/|file:\/\/|about:)/i.test(value);
+}
+
 export type ParsedArgs =
 	| {
 			cmd: string;
@@ -207,7 +211,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
 	if (remaining.length === 0)
 		return { cmd: "help", args: [], timeout, session, json, config };
 
-	const [cmd, ...args] = remaining;
+	const [rawCmd, ...rawArgs] = remaining;
+	const [cmd, args] = looksLikeUrl(rawCmd)
+		? ["goto", [rawCmd, ...rawArgs]]
+		: [rawCmd, rawArgs];
 
 	return { cmd: cmd as string, args, timeout, session, json, config };
 }

src/commands/goto.ts

@@ -1,4 +1,8 @@
-import { devices, type Page } from "playwright";
+import {
+	devices,
+	type Page,
+	type Response as PlaywrightResponse,
+} from "playwright";
 import type { Response } from "../protocol.ts";
 import { handleSnapshot } from "./snapshot.ts";
 import { PRESETS, type ViewportParsedArgs } from "./viewport.ts";
@@ -102,6 +106,79 @@ function parseGotoArgs(args: string[]): {
 	return { url, viewport: null };
 }
 
+function trimSnippet(text: string): string {
+	return text.replace(/\s+/g, " ").trim().slice(0, 500);
+}
+
+function headerValue(
+	headers: Record<string, string>,
+	name: string,
+): string | undefined {
+	return headers[name] ?? headers[name.toLowerCase()];
+}
+
+async function getBodySnippet(page: Page): Promise<string> {
+	try {
+		return trimSnippet(
+			await page.locator("body").innerText({ timeout: 2_000 }),
+		);
+	} catch {
+		return "";
+	}
+}
+
+function looksLikeCdnAccessBlock(
+	status: number,
+	headers: Record<string, string>,
+	title: string,
+	bodySnippet: string,
+): boolean {
+	if (status !== 403) return false;
+
+	const server = headerValue(headers, "server")?.toLowerCase() ?? "";
+	const combined = `${title}\n${bodySnippet}`.toLowerCase();
+
+	return (
+		server.includes("akamaighost") ||
+		server.includes("akamai") ||
+		(combined.includes("access denied") &&
+			(combined.includes("edgesuite") || combined.includes("permission")))
+	);
+}
+
+async function cdnBlockDiagnostic(
+	page: Page,
+	response: PlaywrightResponse,
+	title: string,
+): Promise<string | null> {
+	const status = response.status();
+	const headers = response.headers();
+	const bodySnippet = await getBodySnippet(page);
+
+	if (!looksLikeCdnAccessBlock(status, headers, title, bodySnippet)) {
+		return null;
+	}
+
+	const server = headerValue(headers, "server") ?? "unknown";
+	const finalUrl = response.url();
+	const lines = [
+		`Navigation blocked by CDN/access controls (${status}).`,
+		`URL: ${finalUrl}`,
+		`Server: ${server}`,
+		`Title: ${title || "untitled"}`,
+	];
+
+	if (bodySnippet) {
+		lines.push(`Body: ${bodySnippet}`);
+	}
+
+	lines.push(
+		"Try a real browser session, configured proxy, or verify that the installed 'browse' binary is the project CLI with 'browse version'.",
+	);
+
+	return lines.join("\n");
+}
+
 export async function handleGoto(
 	page: Page,
 	args: string[],
@@ -126,7 +203,10 @@ export async function handleGoto(
 			});
 		}
 
-		await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+		const navigationResponse = await page.goto(url, {
+			waitUntil: "domcontentloaded",
+			timeout: 30_000,
+		});
 
 		// Inject stealth patches to fix CreepJS detection.
 		// This runs on every navigation since addInitScript only affects new pages.
@@ -169,6 +249,17 @@ export async function handleGoto(
 
 		const title = await page.title();
 
+		if (navigationResponse) {
+			const blockDiagnostic = await cdnBlockDiagnostic(
+				page,
+				navigationResponse,
+				title,
+			);
+			if (blockDiagnostic) {
+				return { ok: false, error: blockDiagnostic };
+			}
+		}
+
 		let result: string;
 		if (viewport && viewport.action === "set") {
 			const suffix = viewport.label ? ` (${viewport.label})` : "";

test/cli.test.ts

@@ -20,6 +20,17 @@ describe("parseArgs", () => {
 		});
 	});
 
+	test("treats a bare URL as goto shorthand", () => {
+		const result = parseArgs(["https://example.com", "--timeout", "60000"]);
+		expect(result).toEqual({
+			cmd: "goto",
+			args: ["https://example.com"],
+			timeout: 60000,
+			session: undefined,
+			json: false,
+		});
+	});
+
 	test("parses text command with no args", () => {
 		const result = parseArgs(["text"]);
 		expect(result).toEqual({

test/commands.test.ts

@@ -41,6 +41,39 @@ describe("handleGoto", () => {
 			expect(result.error).toContain("net::ERR_NAME_NOT_RESOLVED");
 		}
 	});
+
+	test("returns diagnostic for Akamai access denied pages", async () => {
+		const page = mockPage({
+			goto: mock(() =>
+				Promise.resolve({
+					status: () => 403,
+					headers: () => ({ server: "AkamaiGHost" }),
+					url: () => "https://www.war.gov/UFO/",
+				}),
+			),
+			title: mock(() => Promise.resolve("Access Denied")),
+			locator: mock(() => ({
+				innerText: mock(() =>
+					Promise.resolve(
+						'Access Denied You do not have permission to access "https://www.war.gov/UFO/" on this server.',
+					),
+				),
+			})),
+		});
+
+		const result = await handleGoto(page as never, [
+			"https://www.war.gov/UFO/",
+		]);
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain(
+				"Navigation blocked by CDN/access controls",
+			);
+			expect(result.error).toContain("Server: AkamaiGHost");
+			expect(result.error).toContain("browse version");
+		}
+	});
 });
 
 describe("handleText", () => {