@pugi/cli 0.1.0-alpha.10

package/dist/core/auto-open-browser.js

@@ -0,0 +1,128 @@
+import { spawn } from 'node:child_process';
+/**
+ * Open `url` in the default browser. Returns `{ opened: true }` on a
+ * successful spawn, `{ opened: false }` on any failure. The url is not
+ * shell-escaped here; we always pass it as a single argv element to a
+ * direct spawn (no shell), so quoting is irrelevant.
+ */
+export async function autoOpenBrowser(url, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawnDetached = deps.spawnDetached ?? defaultSpawnDetached;
+    // Refuse anything that does not parse as http(s). The device-flow URL
+    // is always https — guarding here keeps a hostile server response
+    // from convincing us to spawn `open file:///etc/passwd` or worse.
+    if (!isSafeHttpUrl(url)) {
+        return { opened: false };
+    }
+    if (platform === 'darwin') {
+        return { opened: spawnDetached('open', [url]) };
+    }
+    if (platform === 'win32') {
+        // P1-3 (triple-review 2026-05-24): cmd.exe parses `&` as a command
+        // separator BEFORE Node hands argv to the child, regardless of
+        // `shell: false`. A device-flow URL like
+        // `https://app.pugi.io/devices/authorize?user_code=ABC&trace=xyz`
+        // would be truncated at the `&`, opening only the first half. We
+        // prefer PowerShell (its argv parser is sane: a single quoted URL
+        // round-trips verbatim) and fall back to a double-quoted cmd
+        // invocation when PowerShell is missing from PATH.
+        if (spawnDetached('powershell', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            'Start-Process',
+            quoteForPowerShell(url),
+        ])) {
+            return { opened: true };
+        }
+        // Fallback: `cmd /c start "" "<url>"`. The URL itself is wrapped
+        // in double quotes so cmd does not split on `&`; any embedded `"`
+        // in the URL is escaped using cmd's caret-quote convention.
+        return {
+            opened: spawnDetached('cmd', ['/c', 'start', '""', quoteForCmd(url)]),
+        };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        // Try xdg-open first (the freedesktop standard), then gio (GNOME),
+        // then a couple of well-known browsers as a last resort. Each
+        // attempt is a fresh spawn — if the binary is missing the helper
+        // returns false and we fall through.
+        for (const cmd of LINUX_OPENERS) {
+            if (spawnDetached(cmd, [url]))
+                return { opened: true };
+        }
+        return { opened: false };
+    }
+    // Unknown platform (android, aix, sunos…) — degrade gracefully.
+    return { opened: false };
+}
+const LINUX_OPENERS = ['xdg-open', 'gio', 'gnome-open', 'kde-open'];
+function isSafeHttpUrl(candidate) {
+    try {
+        const url = new URL(candidate);
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * P1-3 (triple-review 2026-05-24): wrap a URL for PowerShell's
+ * `Start-Process` invocation. PowerShell's single-quote string literal
+ * does NOT process escape sequences; the only metachar inside is the
+ * single quote itself (escaped by doubling). URLs do not contain
+ * single quotes in practice, but the helper handles them defensively
+ * so future input shapes do not break.
+ */
+function quoteForPowerShell(url) {
+    return `'${url.replace(/'/g, "''")}'`;
+}
+/**
+ * P1-3 (triple-review 2026-05-24): wrap a URL for cmd.exe's
+ * `start ""` invocation. Double quotes pin the URL as a single token
+ * so cmd does NOT split on `&`, `|`, `^`, `<`, `>`. Embedded `"` (rare
+ * in URLs but defensible) is escaped via cmd's caret-quote convention:
+ * `^"`.
+ */
+function quoteForCmd(url) {
+    return `"${url.replace(/"/g, '^"')}"`;
+}
+/**
+ * Real spawn implementation. Detaches the child so the Pugi CLI can
+ * exit (or keep polling) without inheriting the browser's lifecycle.
+ * Returns `true` only when the spawn produced a pid; any error event
+ * (ENOENT for a missing binary, EACCES for a sandboxed permission
+ * denial) flips the result to `false`.
+ */
+function defaultSpawnDetached(cmd, args) {
+    try {
+        const options = {
+            detached: true,
+            stdio: 'ignore',
+            shell: false,
+        };
+        const child = spawn(cmd, args.slice(), options);
+        // P3 polish (triple-review 2026-05-24): swallow the async `error`
+        // event (ENOENT for a missing binary, EACCES for a sandboxed
+        // permission denial). The old `errored` flag was always false at
+        // the synchronous `return !errored` point (the `error` event is
+        // delivered later in the next tick), so the flag was dead. The
+        // listener is still required: without it, Node escalates the
+        // event to an unhandled-error and crashes the host process when
+        // the binary is missing.
+        child.on('error', () => undefined);
+        if (typeof child.pid !== 'number')
+            return false;
+        // unref so the parent event loop is not held open by the browser
+        // handle. The browser process continues independently.
+        child.unref();
+        // Callers treat `true` as best-effort: the fallback "Browser
+        // didn't open?" hint is always rendered, so a silent spawn
+        // failure still leaves the user a usable path.
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=auto-open-browser.js.map