@youdie006/prodex 0.8.3 → 0.9.1

package/README.md

@@ -29,11 +29,13 @@ The most common way to use `prodex` is standalone — get a ChatGPT Pro answer o
 ```bash
 npm install -g @youdie006/prodex          # needs Node 20+, git, ripgrep
 
-prodex pro browser login                  # opens a dedicated Chrome; log in to ChatGPT there
-prodex pro browser ask --file src/auth.ts "Review this for security holes"
+prodex pro browser login                  # opens a dedicated Chrome and waits until your ChatGPT login is READY
+prodex ask --file src/auth.ts "Review this for security holes"
 ```
 
-The answer prints to your terminal and is saved under `.bridge/` for later. `prodex` drives the picker you can see and deliberately will not send into a window you cannot watch — but a dedicated Chrome window left non-minimized (even behind your editor) counts as watchable, so it sends quietly in the background without stealing focus. Just don't minimize it or switch that window to another tab. Add `--pro-mode 확장` for extended reasoning, or `--file` more than once to attach several files. See [First Pro Login](#first-pro-login) for the full flow, and the [FAQ](#faq) if a send stops.
+`prodex ask` is the short form of `prodex pro browser ask`; the full form and every flag work identically. In an interactive terminal, `login` keeps watching the opened window and tells you exactly which manual step is still missing (log in, clear a check, open a chat) until it reports READY. While ChatGPT thinks, `prodex` prints progress to stderr (connecting, prompt sent, elapsed seconds while generating), so a multi-minute Pro answer never looks frozen.
+
+The answer prints to your terminal and is saved under `.bridge/` for later (`prodex pro latest` re-prints it). `prodex` drives the picker you can see and deliberately will not send into a window you cannot watch — but a dedicated Chrome window left non-minimized (even behind your editor) counts as watchable, so it sends quietly in the background without stealing focus. Just don't minimize it or switch that window to another tab. Add `--pro-mode 확장` for extended reasoning, or `--file` more than once to attach several files. See [First Pro Login](#first-pro-login) for the full flow, and the [FAQ](#faq) if a send stops.
 
 ## Core Shape
 
@@ -97,9 +99,11 @@ Not implemented:
 - Shell execution tools.
 - Automatic public tunnel setup.
 
-## Quick Start
+## Agent Bridge Quick Start
+
+This section connects coding agents (Claude, Codex, ChatGPT Projects) to the bridge over MCP. It is not required for the standalone terminal flow above — if you only want Pro answers in your terminal, the [Quickstart](#quickstart-a-pro-second-opinion-from-your-terminal) is complete on its own.
 
-Requires Node.js 20 or newer, `git`, and `ripgrep` (`rg`) on PATH. The optional visible-browser adapter also needs a Chromium-family browser (`google-chrome`, `chromium`, `chromium-browser`, `microsoft-edge`, `brave-browser`) or `PRODEX_CHROME=/path/to/browser`.
+Requires Node.js 20 or newer, `git`, and `ripgrep` (`rg`) on PATH. The optional visible-browser adapter needs a Chromium-family browser: PATH binaries (`google-chrome`, `chromium`, `chromium-browser`, `microsoft-edge`, `brave-browser`), standard macOS app bundles, Windows Program Files/LOCALAPPDATA installs, and Windows-host browsers under WSL are all probed automatically; anything else via `PRODEX_CHROME=/path/to/browser`.
 
 Install from npm — **note the scope**. The unscoped `prodex` on npm is an unrelated third-party package; do **not** install it. Use the scoped name:
 
@@ -153,7 +157,7 @@ prodex pro browser check
 prodex pro browser smoke --cwd /absolute/path/to/your/repo
 ```
 
-If you use a non-default debug port or Chrome profile, pass it to `login`; the printed follow-up `check` and `smoke` commands keep the matching `--port`. If you launch from outside the repo you want to inspect, pass `--cwd /absolute/path/to/your/repo` to `login`, `check`, or `smoke` so the command targets the same bridge. On slower first launches, add `--launch-timeout-ms 12000`.
+If you use a non-default debug port or Chrome profile, pass it to `login`; the printed follow-up `check` and `smoke` commands keep the matching `--port`. To stop repeating `--port` on every command, export `PRODEX_CDP_PORT=<port>` once — explicit `--port` still wins. If you launch from outside the repo you want to inspect, pass `--cwd /absolute/path/to/your/repo` to `login`, `check`, or `smoke` so the command targets the same bridge. On slower first launches, add `--launch-timeout-ms 12000`.
 
 For a source checkout, keep the follow-up commands in source-checkout form too:
 
@@ -170,7 +174,7 @@ node "$SOURCE_CLI" pro browser smoke --source-cli "$SOURCE_CLI" --cwd /absolute/
 What happens:
 
 - `login --dry-run` prints the dedicated Chrome profile, debug URL, and next commands without opening a browser.
-- `login` opens that dedicated Chrome profile at ChatGPT.
+- `login` opens that dedicated Chrome profile at ChatGPT. In an interactive terminal it then waits (default 5 minutes; `--no-wait` skips, `--wait-timeout-ms` tunes) and narrates which manual step is still missing until it reports READY; scripts and agents get the immediate return unless they pass `--wait`.
 - You log in manually in the visible browser.
 - If ChatGPT asks for captcha, Cloudflare/human verification, permission, or account verification, handle it in that browser.
 - If ChatGPT shows a usage limit, message limit, model limit, or rate limit, wait for the reset or choose an available model in the browser.
@@ -184,11 +188,11 @@ What happens:
 
 You can close that Chrome window after check/smoke or when you are done. The next time you need it, run `pro browser login` or `pro browser check` again. `check` will tell you what to do if the browser is closed.
 
-Actual explicit visible-browser consult:
+Actual explicit visible-browser consult (`prodex ask` is the short form of `prodex pro browser ask`):
 
 ```bash
 cd /absolute/path/to/your/repo
-prodex pro browser ask --cwd /absolute/path/to/your/repo --file README.md "Review the project positioning"
+prodex ask --file README.md "Review the project positioning"
 prodex pro latest
 prodex results show latest
 prodex results artifact latest

package/dist/chatgpt-browser.d.ts

@@ -40,6 +40,29 @@ export type ChatGptProMode = "기본" | "확장";
 export declare function parseReasoningEffort(raw: string): ChatGptReasoningEffort;
 /** Normalize a CLI Pro sub-mode value onto the exact ChatGPT menu label. */
 export declare function parseProMode(raw: string): ChatGptProMode;
+export declare const DEFAULT_CDP_PORT = 9333;
+/**
+ * Stability policy for the answer poll loop. Returns true once the observed
+ * (answer, generating) stream should be accepted as final:
+ * - normal answers: two consecutive identical, non-generating polls;
+ * - answers whose tail looks like the streaming caret: six additional
+ *   confirmations (~6s at the 1s poll cadence), so a lingering caret gets
+ *   dropped by ChatGPT's finalization re-render first, while an answer that
+ *   genuinely ends with an underscore is still accepted after the extra wait.
+ */
+export declare function createChatGptAnswerStabilityTracker(): (answer: string, generating: boolean) => boolean;
+/**
+ * Resolve the Chrome DevTools port: explicit flag > PRODEX_CDP_PORT env >
+ * default 9333. The env var exists so a non-default port picked at login does
+ * not have to be repeated as --port on every later command.
+ */
+export declare function resolveCdpPort(explicit?: number): number;
+export type SendChatGptProgressPhase = "connecting" | "tab_ready" | "selecting" | "sent" | "waiting" | "answered";
+export interface SendChatGptProgressEvent {
+    phase: SendChatGptProgressPhase;
+    elapsedMs: number;
+    detail?: string;
+}
 export interface SendChatGptPromptOptions {
     port?: number;
     prompt: string;
@@ -55,6 +78,8 @@ export interface SendChatGptPromptOptions {
     proMode?: ChatGptProMode;
     /** Reasoning effort, used for non-Pro models. */
     effort?: ChatGptReasoningEffort;
+    /** Progress callback so long sends can report phase + elapsed instead of staying silent. */
+    onProgress?: (event: SendChatGptProgressEvent) => void;
 }
 export interface SendChatGptPromptResult {
     url: string;
@@ -132,6 +157,13 @@ export declare function assertChatGptTargetTabAvailable(targetUrl: string): void
 export declare function assertChatGptPageAvailable(): never;
 export declare function assertChatGptReadyForPrompt(loggedInLikely: boolean, hasComposer: boolean): void;
 export declare function chatGptVisibilityBlocker(visibilityState: string | undefined, url: string | undefined): ChatGptBrowserStatus["blocker"] | undefined;
+/**
+ * Environment for the browser spawn. On Linux shells without DISPLAY or
+ * WAYLAND_DISPLAY (common in WSL where a non-login shell does not export
+ * them), a present WSLg X socket means a desktop is actually available -
+ * inject DISPLAY=:0 so Chrome does not exit immediately with code 1.
+ */
+export declare function browserLaunchEnv(platform?: NodeJS.Platform, env?: Record<string, string | undefined>, hasX0Socket?: () => boolean): Record<string, string | undefined>;
 export declare function openChatGptBrowser(options?: ChatGptBrowserOptions): ChatGptBrowserLaunch;
 export declare function getChatGptBrowserStatus(options?: {
     port?: number;
@@ -169,4 +201,13 @@ export declare function statusExpression(): string;
 export declare function prepareComposerExpression(): string;
 export declare function composerTextStateExpression(): string;
 export declare function submitExpression(): string;
+/**
+ * Ordered browser candidates for the current platform: PATH binary names
+ * first, then well-known absolute install locations (macOS app bundles,
+ * Windows Program Files/LOCALAPPDATA, and Windows-host browsers under WSL).
+ * WSL detection cannot rely on WSL_DISTRO_NAME alone: non-login shells
+ * (measured live) may not carry it, so WSL_INTEROP and the kernel string are
+ * probed too.
+ */
+export declare function chromeCommandCandidates(platform?: NodeJS.Platform, env?: Record<string, string | undefined>, isWsl?: () => boolean): string[];
 export {};

package/dist/chatgpt-browser.js

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { accessSync, constants, statSync } from "node:fs";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 export class ChatGptBrowserBlockerError extends Error {
@@ -60,6 +60,62 @@ export function parseProMode(raw) {
         return alias;
     throw new Error(`--pro-mode must be one of ${PRO_MODES.join(", ")}`);
 }
+export const DEFAULT_CDP_PORT = 9333;
+// The ChatGPT streaming caret renders as a literal text character at the end
+// of the growing assistant message (a plain "_" in the current UI; "▍" and
+// friends historically). Measured live 2026-07-06: the caret can stay in
+// innerText for a beat AFTER the stop button disappears, so a short answer can
+// look stable and non-generating while still carrying the caret.
+const TRAILING_CARET_SUSPECT = /[_▍▌█▊▋]$/;
+/**
+ * Stability policy for the answer poll loop. Returns true once the observed
+ * (answer, generating) stream should be accepted as final:
+ * - normal answers: two consecutive identical, non-generating polls;
+ * - answers whose tail looks like the streaming caret: six additional
+ *   confirmations (~6s at the 1s poll cadence), so a lingering caret gets
+ *   dropped by ChatGPT's finalization re-render first, while an answer that
+ *   genuinely ends with an underscore is still accepted after the extra wait.
+ */
+export function createChatGptAnswerStabilityTracker() {
+    let stableAnswer;
+    let confirmations = 0;
+    return (answer, generating) => {
+        if (generating) {
+            // A generating poll invalidates any baseline: the text may still grow.
+            stableAnswer = undefined;
+            confirmations = 0;
+            return false;
+        }
+        if (answer !== stableAnswer) {
+            stableAnswer = answer;
+            confirmations = 0;
+            return false;
+        }
+        confirmations += 1;
+        // Trim before the caret check: the caller trims the returned answer, so a
+        // caret followed by trailing whitespace must count as suspect too.
+        const required = TRAILING_CARET_SUSPECT.test(answer.trimEnd()) ? 8 : 2;
+        return confirmations >= required;
+    };
+}
+/**
+ * Resolve the Chrome DevTools port: explicit flag > PRODEX_CDP_PORT env >
+ * default 9333. The env var exists so a non-default port picked at login does
+ * not have to be repeated as --port on every later command.
+ */
+export function resolveCdpPort(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const fromEnv = process.env.PRODEX_CDP_PORT;
+    if (fromEnv !== undefined && fromEnv !== "") {
+        const parsed = Number(fromEnv);
+        if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65_535) {
+            throw new Error(`PRODEX_CDP_PORT must be an integer between 1 and 65535, got: ${fromEnv}`);
+        }
+        return parsed;
+    }
+    return DEFAULT_CDP_PORT;
+}
 export const CHATGPT_RUNTIME_BLOCKER_TEXT_EXCLUDED_ANCESTORS = '[data-message-author-role],script,style,noscript,[aria-hidden="true"],div[role="textbox"],textarea,[contenteditable="true"]';
 export const CHATGPT_COMPOSER_CANDIDATE_EXCLUDED_ANCESTORS = '[data-message-author-role],script,style,noscript,[aria-hidden="true"]';
 export const PRODEX_ACTIVE_COMPOSER_ATTRIBUTE = "data-prodex-active-composer";
@@ -398,16 +454,36 @@ export function chatGptVisibilityBlocker(visibilityState, url) {
         next_step: `Select ${url ?? "the ChatGPT tab"} in the dedicated browser, then retry.`
     };
 }
+/**
+ * Environment for the browser spawn. On Linux shells without DISPLAY or
+ * WAYLAND_DISPLAY (common in WSL where a non-login shell does not export
+ * them), a present WSLg X socket means a desktop is actually available -
+ * inject DISPLAY=:0 so Chrome does not exit immediately with code 1.
+ */
+export function browserLaunchEnv(platform = process.platform, env = process.env, hasX0Socket = () => {
+    try {
+        statSync("/tmp/.X11-unix/X0");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}) {
+    if (platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY && hasX0Socket()) {
+        return { ...env, DISPLAY: ":0" };
+    }
+    return env;
+}
 export function openChatGptBrowser(options = {}) {
     const command = resolveChromeCommand();
-    const port = options.port ?? 9333;
+    const port = resolveCdpPort(options.port);
     const profileDir = options.profileDir ?? defaultChatGptProfileDir();
     const args = buildChromeLaunchArgs({
         port,
         profileDir,
         url: options.url ?? "https://chatgpt.com/"
     });
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    const child = spawn(command, args, { detached: true, stdio: "ignore", env: browserLaunchEnv() });
     let earlyExit;
     const earlyExitWaiters = new Set();
     const recordEarlyExit = (exit) => {
@@ -444,7 +520,7 @@ export function openChatGptBrowser(options = {}) {
     };
 }
 export async function getChatGptBrowserStatus(options = {}) {
-    const port = options.port ?? 9333;
+    const port = resolveCdpPort(options.port);
     const page = await findChatGptPage(port, options.timeoutMs ?? 1500);
     if (!page.ok) {
         return {
@@ -846,8 +922,20 @@ async function selectProject(cdp, options) {
     }
 }
 export async function sendChatGptPrompt(options) {
-    const port = options.port ?? 9333;
+    const port = resolveCdpPort(options.port);
     const timeoutMs = options.timeoutMs ?? 90_000;
+    const sendStartedAt = Date.now();
+    const emitProgress = (phase, detail) => {
+        if (!options.onProgress)
+            return;
+        try {
+            options.onProgress({ phase, elapsedMs: Date.now() - sendStartedAt, ...(detail !== undefined ? { detail } : {}) });
+        }
+        catch {
+            // Progress reporting must never break the send itself.
+        }
+    };
+    emitProgress("connecting", `port ${port}`);
     const normalizedTargetUrl = options.targetUrl ? normalizeChatGptTargetUrl(options.targetUrl) : undefined;
     const pageResult = await findChatGptPage(port, computePageDiscoveryTimeout(timeoutMs), normalizedTargetUrl);
     if (!pageResult.ok) {
@@ -877,6 +965,19 @@ export async function sendChatGptPrompt(options) {
     if (busyBlocker) {
         throw new ChatGptBrowserBlockerError(busyBlocker);
     }
+    emitProgress("tab_ready");
+    // Progress details deliberately avoid project names (receipts redact them too).
+    const selectionSummary = [
+        options.model !== undefined ? `model=${options.model}` : undefined,
+        options.proMode !== undefined ? `pro_mode=${options.proMode}` : undefined,
+        options.effort !== undefined ? `effort=${options.effort}` : undefined,
+        options.project !== undefined ? "project=set" : undefined,
+        options.projectNew !== undefined ? "project_new=set" : undefined
+    ]
+        .filter((part) => part !== undefined)
+        .join(" ");
+    if (selectionSummary)
+        emitProgress("selecting", selectionSummary);
     let beforeSubmit;
     let submitButtonFound = false;
     const cdp = await connectCdp(page.webSocketDebuggerUrl);
@@ -905,6 +1006,7 @@ export async function sendChatGptPrompt(options) {
     finally {
         cdp.close();
     }
+    emitProgress("sent", `timeout ${Math.round(timeoutMs / 1000)}s`);
     const started = Date.now();
     const acceptDeadline = computePromptAcceptanceDeadline(timeoutMs, started);
     let accepted = false;
@@ -919,6 +1021,7 @@ export async function sendChatGptPrompt(options) {
             accepted = true;
             break;
         }
+        emitProgress("waiting", "prompt posting");
     }
     if (!accepted) {
         // A successful submit clears the composer, so text still sitting there means
@@ -933,34 +1036,26 @@ export async function sendChatGptPrompt(options) {
         }
         throw acceptanceTimeoutError({ timeoutMs, composerStillHasText, submitButtonFound });
     }
-    let stableAnswer;
-    let stableConfirmations = 0;
+    const answerIsStable = createChatGptAnswerStabilityTracker();
     while (Date.now() - started < timeoutMs) {
         await sleep(1000);
         finalState = await evaluateOnPage(page, answerExpression());
         const runtimeBlocker = chatGptBlockerFromAnswerState(finalState);
         if (runtimeBlocker)
             throw new ChatGptBrowserBlockerError(runtimeBlocker);
+        emitProgress("waiting", finalState.generating ? "generating" : "stabilizing");
         if (!hasFreshChatGptAnswer(beforeSubmit.assistantMessageCount, finalState))
             continue;
-        // A "fresh" answer must also be stable: ChatGPT can momentarily look done mid-stream, so accept
-        // it only once the text stops changing across polls. Otherwise trailing tokens (e.g. the final
-        // "_OK" of the smoke token) get dropped.
-        if (finalState.answer === stableAnswer && !finalState.generating) {
-            stableConfirmations += 1;
-            // Require two consecutive stable, non-generating polls so a mid-stream
-            // pause (identical text across one interval while more tokens are still
-            // coming) is not mistaken for completion.
-            if (stableConfirmations >= 2)
-                break;
-        }
-        else {
-            stableAnswer = finalState.answer;
-            stableConfirmations = 0;
-        }
+        // A "fresh" answer must also be stable: ChatGPT can momentarily look done
+        // mid-stream, and the streaming caret renders as a literal trailing
+        // character that can outlive the stop button. The tracker requires extra
+        // confirmations for caret-suspect tails (see its doc comment).
+        if (answerIsStable(finalState.answer, finalState.generating))
+            break;
     }
     const completed = finalState;
     if (completed && hasFreshChatGptAnswer(beforeSubmit.assistantMessageCount, completed)) {
+        emitProgress("answered");
         return {
             url: completed.url,
             title: completed.title,
@@ -973,6 +1068,7 @@ export async function sendChatGptPrompt(options) {
     // (a truncated-but-real Pro answer is far more useful than losing it) and
     // flag it so the caller records the incompleteness and the retry hint.
     if (completed && hasPartialChatGptAnswer(beforeSubmit.assistantMessageCount, completed)) {
+        emitProgress("answered", "partial");
         return {
             url: completed.url,
             title: completed.title,
@@ -1002,7 +1098,7 @@ export function modelMenuOptionsExpression() {
 // and press Escape. Nothing is clicked inside the menu, so the user's model
 // selection is never changed.
 export async function listChatGptModelOptions(input = {}) {
-    const port = input.port ?? 9333;
+    const port = resolveCdpPort(input.port);
     const timeoutMs = input.timeoutMs ?? 15_000;
     const pageResult = await findChatGptPage(port, computePageDiscoveryTimeout(timeoutMs), undefined);
     if (!pageResult.ok) {
@@ -1424,13 +1520,74 @@ function answerExpression() {
 function enterKeyEvent(type) {
     return { type, key: "Enter", code: "Enter", windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 };
 }
+const CHROME_PATH_BINARY_NAMES = ["google-chrome", "chromium", "chromium-browser", "microsoft-edge", "brave-browser"];
+const DARWIN_CHROME_PATHS = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+];
+function win32ChromePaths(env) {
+    return [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        ...(env.LOCALAPPDATA ? [`${env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`] : []),
+        "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
+    ];
+}
+const WSL_WINDOWS_CHROME_PATHS = [
+    "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe",
+    "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+    "/mnt/c/Program Files/Microsoft/Edge/Application/msedge.exe",
+    "/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
+];
+function kernelLooksLikeWsl() {
+    try {
+        return /microsoft/i.test(readFileSync("/proc/version", "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ordered browser candidates for the current platform: PATH binary names
+ * first, then well-known absolute install locations (macOS app bundles,
+ * Windows Program Files/LOCALAPPDATA, and Windows-host browsers under WSL).
+ * WSL detection cannot rely on WSL_DISTRO_NAME alone: non-login shells
+ * (measured live) may not carry it, so WSL_INTEROP and the kernel string are
+ * probed too.
+ */
+export function chromeCommandCandidates(platform = process.platform, env = process.env, isWsl = kernelLooksLikeWsl) {
+    const candidates = [...CHROME_PATH_BINARY_NAMES];
+    if (platform === "darwin")
+        candidates.push(...DARWIN_CHROME_PATHS);
+    if (platform === "win32")
+        candidates.push(...win32ChromePaths(env));
+    if (platform === "linux" && (env.WSL_DISTRO_NAME || env.WSL_INTEROP || isWsl())) {
+        candidates.push(...WSL_WINDOWS_CHROME_PATHS);
+    }
+    return candidates;
+}
 function resolveChromeCommand() {
     const fromEnv = process.env.PRODEX_CHROME;
     if (fromEnv) {
         assertChromeCommandAvailable(fromEnv, "PRODEX_CHROME");
         return fromEnv;
     }
-    for (const command of ["google-chrome", "chromium", "chromium-browser", "microsoft-edge", "brave-browser"]) {
+    for (const command of chromeCommandCandidates()) {
+        if (isPathLikeCommand(command)) {
+            try {
+                if (!statSync(command).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (hasChromeLikeVersion(command))
+                return command;
+            continue;
+        }
         if (isCommandOnPath(command) && hasChromeLikeVersion(command))
             return command;
     }