codex-chatgpt-control 0.1.0-alpha.1 → 0.3.0-alpha.1

package/dist/src/commands/conversation.js

@@ -0,0 +1,44 @@
+import { parseConversationId } from "../browser/page-state.js";
+import { countPageMessages, readLatestMessageText } from "../dom/messages.js";
+const CHATGPT_HOME = "https://chatgpt.com/";
+export async function ensureConversationTarget(page, target, options) {
+    const targetUrl = absoluteConversationUrl(target);
+    const expectedConversationId = parseConversationId(targetUrl);
+    const currentUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
+    if (expectedConversationId !== undefined
+        && parseConversationId(typeof currentUrl === "string" ? currentUrl : "") === expectedConversationId) {
+        await waitForConversationHydrated(page, options.timeoutMs, expectedConversationId);
+        return ensureResult(false, targetUrl, expectedConversationId);
+    }
+    await page.goto?.(targetUrl, { waitUntil: "domcontentloaded", timeout: options.timeoutMs });
+    await waitForConversationHydrated(page, options.timeoutMs, expectedConversationId);
+    return ensureResult(true, targetUrl, expectedConversationId);
+}
+export async function waitForConversationHydrated(page, timeoutMs, expectedConversationId) {
+    const started = Date.now();
+    do {
+        const url = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
+        const urlMatches = expectedConversationId === undefined || parseConversationId(typeof url === "string" ? url : "") === expectedConversationId;
+        const count = await countPageMessages(page).catch(() => 0);
+        const latestAssistantText = await readLatestMessageText(page, "assistant").catch(() => undefined);
+        const title = typeof page.title === "function" ? await page.title().catch(() => "") : "";
+        if (urlMatches && ((latestAssistantText?.trim().length ?? 0) > 0 || (count > 0 && title.length > 0 && title !== "ChatGPT"))) {
+            await page.waitForTimeout?.(250);
+            return;
+        }
+        await page.waitForTimeout?.(500);
+    } while (Date.now() - started < timeoutMs);
+}
+function absoluteConversationUrl(target) {
+    if (target.href !== undefined && target.href.startsWith("/")) {
+        return new URL(target.href, CHATGPT_HOME).toString();
+    }
+    return target.href ?? target.url;
+}
+function ensureResult(navigated, targetUrl, expectedConversationId) {
+    const result = { navigated, targetUrl };
+    if (expectedConversationId !== undefined) {
+        result.expectedConversationId = expectedConversationId;
+    }
+    return result;
+}

package/dist/src/commands/deadline.d.ts

@@ -0,0 +1,8 @@
+export type Deadline = {
+    startedAtMs: number;
+    timeoutMs: number;
+    expiresAtMs: number;
+};
+export declare function createDeadline(timeoutMs: number, startedAtMs?: number): Deadline;
+export declare function remainingMs(deadline: Deadline, nowMs?: number): number;
+export declare function childTimeoutMs(deadline: Deadline, capMs: number, nowMs?: number): number;

package/dist/src/commands/deadline.js

@@ -0,0 +1,14 @@
+export function createDeadline(timeoutMs, startedAtMs = Date.now()) {
+    const safeTimeoutMs = Math.max(0, timeoutMs);
+    return {
+        startedAtMs,
+        timeoutMs: safeTimeoutMs,
+        expiresAtMs: startedAtMs + safeTimeoutMs,
+    };
+}
+export function remainingMs(deadline, nowMs = Date.now()) {
+    return Math.max(0, deadline.expiresAtMs - nowMs);
+}
+export function childTimeoutMs(deadline, capMs, nowMs = Date.now()) {
+    return Math.max(0, Math.min(Math.max(0, capMs), remainingMs(deadline, nowMs)));
+}

package/dist/src/commands/doctor.d.ts

@@ -1,13 +1,21 @@
-import type { CommandResult, RuntimeEnv } from "../types.js";
-export type DoctorCheckName = "bridge" | "login" | "upload" | "download" | "clipboard" | "modes" | "tools" | "selectors";
+import type { BootstrapArgs, CommandResult, RuntimeEnv } from "../types.js";
+import type { RunReportOptions } from "./reports.js";
+export type DoctorCheckName = "bridge" | "login" | "upload" | "download" | "clipboard" | "modes" | "tools" | "selectors" | "existing_tab" | "artifacts" | "file_preflight" | "localization" | "reports";
 export type CapabilityStatus = "ok" | "blocked" | "unsupported" | "unknown";
 export type CapabilityCheck = {
     status: CapabilityStatus;
     message: string;
     remediation?: string[];
+    code?: string;
+    blockerKind?: string;
+    nextCommand?: string;
+    details?: Record<string, unknown>;
 };
 export type DoctorArgs = {
     check?: DoctorCheckName[];
+    existingTab?: BootstrapArgs["existingTab"];
+    files?: string[];
+    report?: RunReportOptions;
 };
 export type DoctorReport = {
     ready: boolean;

package/dist/src/commands/doctor.js

@@ -1,21 +1,51 @@
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
 import { readSystemClipboard } from "../browser/clipboard.js";
 import { readPageState } from "../browser/page-state.js";
+import { localeLabels } from "../dom/locale-labels.js";
 import { BROWSER_BRIDGE_REMEDIATION, resultOk } from "../errors.js";
+import { explainCommandBlocker } from "../diagnostics/blockers.js";
+import { preflightFiles } from "./files.js";
 import { contextFromPage } from "./context.js";
 import { bootstrap } from "./session.js";
 const DEFAULT_CHECKS = ["bridge", "login", "upload", "download", "clipboard", "modes", "tools", "selectors"];
+const BOOTSTRAP_CHECKS = new Set(["bridge", "login", "upload", "download", "modes", "tools", "selectors"]);
 const UPLOAD_REMEDIATION = [
     "Codex Settings > Computer Use > Chrome > Permissions > Uploads: set to Always allow, or add chatgpt.com to the allowed upload domains.",
     "Chrome chrome://extensions > Codex extension > Details: enable Allow access to file URLs."
 ];
+const REQUIRED_LOCALE_KEYS = [
+    "composerTextbox",
+    "sendButton",
+    "searchChatsButton",
+    "searchChatsPlaceholder",
+    "newChat",
+    "addFilesButton",
+    "addPhotosFilesMenuItem",
+    "copyResponse",
+    "download",
+    "modeLabels",
+    "signedInMarkers",
+    "loginBlocker",
+    "captchaBlocker",
+    "rateLimitBlocker"
+];
+const REQUIRED_TOOL_IDS = ["web_search", "deep_research", "create_image"];
+const REQUIRED_MODE_OPTION_IDS = ["latest", "instant", "thinking", "extended", "medium", "high", "extraHigh", "pro"];
 export async function doctor(env, args = {}) {
     const wanted = args.check ?? DEFAULT_CHECKS;
     const checks = {};
-    const boot = await bootstrap(env, { preferExistingTab: true, timeoutMs: 30000 });
+    const wantsExistingTab = wanted.includes("existing_tab");
+    const existingTab = wantsExistingTab ? normalizeDoctorExistingTab(args.existingTab) : undefined;
+    const boot = wantsExistingTab || wanted.some(check => BOOTSTRAP_CHECKS.has(check))
+        ? await bootstrap(env, existingTab === undefined
+            ? { preferExistingTab: true, timeoutMs: 30000 }
+            : { existingTab, preferExistingTab: false, timeoutMs: 30000 })
+        : undefined;
     for (const check of wanted) {
         switch (check) {
             case "bridge":
-                checks.bridge = boot.ok
+                checks.bridge = boot?.ok
                     ? ok("Chrome bridge is available.")
                     : bridgeCheck(boot);
                 break;
@@ -40,14 +70,34 @@ export async function doctor(env, args = {}) {
             case "selectors":
                 checks.selectors = selectorCheck(env, "Basic page selectors are available.");
                 break;
+            case "existing_tab":
+                checks.existing_tab = existingTab === undefined || boot === undefined
+                    ? blocked("Existing-tab readiness was requested, but bootstrap was not initialized.")
+                    : existingTabCheck(existingTab, boot);
+                break;
+            case "artifacts":
+                checks.artifacts = artifactsCheck(env);
+                break;
+            case "file_preflight":
+                checks.file_preflight = await filePreflightCheck(env, args);
+                break;
+            case "localization":
+                checks.localization = localizationCheck(env);
+                break;
+            case "reports":
+                checks.reports = await reportsCheck(args.report);
+                break;
         }
     }
     const ready = Object.values(checks).every(check => check?.status === "ok" || check?.status === "unknown");
     return resultOk({ ready, checks }, await contextFromPage(env.page));
 }
 function bridgeCheck(boot) {
+    if (boot === undefined) {
+        return unknown("Bridge readiness was not requested.");
+    }
     if (boot.blocker?.kind === "browser_bridge_unavailable") {
-        return blocked(boot.blocker.message, bridgeRemediation(boot));
+        return withBlockerDetails(blocked(boot.blocker.message, bridgeRemediation(boot)), boot, "session.bootstrap");
     }
     if (boot.blocker?.kind === "login_required") {
         return ok("Chrome bridge is available; ChatGPT login is required before browser-control commands can continue.");
@@ -58,11 +108,11 @@ function bridgeCheck(boot) {
     return blocked(boot.error?.message ?? "Chrome bridge is unavailable.");
 }
 async function loginCheck(env, boot) {
-    if (!boot.ok && boot.blocker?.kind === "login_required") {
-        return blocked("ChatGPT login is required.", ["Ask the user to sign in to ChatGPT in Chrome, then retry."]);
+    if (boot !== undefined && !boot.ok && boot.blocker?.kind === "login_required") {
+        return withBlockerDetails(blocked("ChatGPT login is required.", ["Ask the user to sign in to ChatGPT in Chrome, then retry."]), boot, "session.bootstrap");
     }
     if (env.page === undefined) {
-        return boot.ok ? ok("Bootstrap completed; login appears usable.") : blocked("Cannot determine login because bootstrap failed.");
+        return boot?.ok ? ok("Bootstrap completed; login appears usable.") : blocked("Cannot determine login because bootstrap failed.");
     }
     const state = await readPageState(env.page).catch(() => undefined);
     if (state?.blocker?.kind === "login_required") {
@@ -102,19 +152,204 @@ function selectorCheck(env, message) {
         ? ok(message)
         : unsupported("The active page object does not expose locator or role selector helpers.");
 }
+function existingTabCheck(existingTab, boot) {
+    if (boot.ok) {
+        return ok("Existing ChatGPT tab target can be claimed.", {
+            target: existingTab.target,
+            tabId: boot.context.tabId,
+            url: boot.context.url,
+            conversationId: boot.context.conversationId
+        });
+    }
+    return withBlockerDetails(blocked(boot.blocker?.message ?? boot.error?.message ?? "Existing ChatGPT tab target could not be claimed."), boot, "session.bootstrap");
+}
+function normalizeDoctorExistingTab(existingTab) {
+    if (existingTab !== undefined && existingTab !== true && existingTab !== false) {
+        return {
+            requireChatGPT: true,
+            ifMissing: "block",
+            ifMultiple: existingTab.target?.type === "selected" ? "first" : "block",
+            ...existingTab
+        };
+    }
+    return {
+        target: { type: "selected", host: "chatgpt" },
+        ifMissing: "block",
+        ifMultiple: "block",
+        requireChatGPT: true
+    };
+}
+function artifactsCheck(env) {
+    const page = env.page;
+    if (page === undefined) {
+        return unknown("Artifact readiness requires an already bootstrapped ChatGPT page.", undefined, {
+            pageAvailable: false
+        }, "session.bootstrap");
+    }
+    const selectorsAvailable = typeof page.locator === "function" || typeof page.getByRole === "function";
+    const downloadEventsAvailable = typeof page.waitForEvent === "function";
+    const domEvaluateAvailable = typeof page.evaluate === "function";
+    const pageAssetsAvailable = typeof page.capabilities?.get === "function";
+    const details = {
+        pageAvailable: true,
+        selectorsAvailable,
+        downloadEventsAvailable,
+        domEvaluateAvailable,
+        pageAssetsAvailable
+    };
+    if (selectorsAvailable && (downloadEventsAvailable || domEvaluateAvailable || pageAssetsAvailable)) {
+        return ok("Artifact primitives can inspect the current page without requesting generation.", details);
+    }
+    return unknown("Artifact primitives need selector support plus download, DOM, or page-assets support to prove readiness.", undefined, details);
+}
+async function filePreflightCheck(env, args) {
+    const paths = args.files ?? [];
+    const result = await preflightFiles(env, { paths });
+    const pathCount = paths.length;
+    if (result.ok && result.data !== undefined) {
+        return ok(pathCount === 0
+            ? "No file paths were supplied; file preflight has no local files to validate."
+            : "File preflight completed without blocking local file issues.", {
+            pathCount,
+            totalBytes: result.data.totalBytes,
+            warnings: result.warnings,
+            files: result.data.files.map(file => ({
+                name: file.name,
+                bytes: file.bytes,
+                extension: file.extension,
+                mimeType: file.mimeType,
+                category: file.category
+            }))
+        });
+    }
+    return withBlockerDetails(blocked(result.blocker?.message ?? result.error?.message ?? "File preflight failed.", result.blocker?.remediation?.map(step => `${step.label}: ${step.instruction}`), {
+        pathCount,
+        warnings: result.warnings
+    }), result, "files.preflight");
+}
+function localizationCheck(env) {
+    const requiredKeysMissing = REQUIRED_LOCALE_KEYS.filter(key => localeLabels[key].length === 0);
+    const missingToolIds = REQUIRED_TOOL_IDS.filter(id => (localeLabels.tools[id]?.length ?? 0) === 0);
+    const missingModeOptionIds = REQUIRED_MODE_OPTION_IDS.filter(id => (localeLabels.modeOptions[id]?.length ?? 0) === 0);
+    const toolIds = Object.keys(localeLabels.tools);
+    const modeOptionIds = Object.keys(localeLabels.modeOptions);
+    const englishCanonicalPresent = localeLabels.composerTextbox[0] === "Chat with ChatGPT"
+        && localeLabels.sendButton[0] === "Send prompt"
+        && localeLabels.modeLabels.includes("Thinking")
+        && localeLabels.modeOptions.pro?.[0] === "Pro"
+        && localeLabels.tools.web_search?.[0] === "Web search";
+    const labelCandidateCount = REQUIRED_LOCALE_KEYS.reduce((total, key) => total + localeLabels[key].length, 0)
+        + Object.values(localeLabels.tools).reduce((total, values) => total + values.length, 0)
+        + Object.values(localeLabels.modeOptions).reduce((total, values) => total + values.length, 0);
+    const details = {
+        englishCanonicalPresent,
+        requiredKeysMissing,
+        missingToolIds,
+        missingModeOptionIds,
+        toolIds,
+        modeOptionIds,
+        labelCandidateCount,
+        pageAvailable: env.page !== undefined,
+        runtimeSelectorCoverage: "registry_only_stage_2"
+    };
+    if (englishCanonicalPresent && requiredKeysMissing.length === 0 && missingToolIds.length === 0 && missingModeOptionIds.length === 0) {
+        return unknown("The locale registry is loaded; localized runtime selector coverage is registry-only in Stage 2 and not fully proven.", undefined, details);
+    }
+    return blocked("The locale registry is missing canonical labels required for selector fallback.", ["Update src/dom/locale-labels.ts or src/dom/locale/* with verified visible labels before relying on localized controls."], details, "selector_drift");
+}
+async function reportsCheck(options) {
+    const destDir = options?.destDir ?? "reports/runs";
+    const includeContent = options?.includeContent === true;
+    const details = {
+        destDir,
+        includeContent,
+        redactionDefault: !includeContent,
+        maxPreviewChars: options?.maxPreviewChars ?? 240
+    };
+    try {
+        const current = await stat(destDir);
+        if (!current.isDirectory()) {
+            return unsupported("Report destination exists but is not a directory.", undefined, details);
+        }
+        await access(destDir, constants.W_OK);
+        return ok(includeContent
+            ? "Report destination is writable; raw content persistence is enabled by request."
+            : "Report destination is writable and redaction is enabled by default.", details);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return unknown("Report destination does not exist yet; createReport will create it when a report is written.", undefined, {
+                ...details,
+                exists: false
+            }, "createReport");
+        }
+        if (isNodeError(error) && (error.code === "EACCES" || error.code === "EPERM")) {
+            return blocked("Report destination is not writable.", ["Choose a writable report destDir or update filesystem permissions."], details, "permission");
+        }
+        return unknown(`Report destination writability could not be proven: ${error instanceof Error ? error.message : String(error)}`, undefined, details);
+    }
+}
 function bridgeRemediation(boot) {
     const remediation = boot.blocker?.remediation ?? BROWSER_BRIDGE_REMEDIATION;
     return remediation.map(step => `${step.label}: ${step.instruction}`);
 }
-function ok(message) {
-    return { status: "ok", message };
+function withBlockerDetails(check, result, command) {
+    if (result.blocker === undefined) {
+        return check;
+    }
+    const explanation = explainCommandBlocker(result, { command });
+    const details = {
+        severity: explanation.severity,
+        category: explanation.category,
+        userActionRequired: explanation.userActionRequired
+    };
+    if (explanation.diagnostics?.existingTab !== undefined) {
+        details.existingTab = explanation.diagnostics.existingTab;
+    }
+    if (explanation.candidates !== undefined) {
+        details.candidates = explanation.candidates;
+    }
+    const nextCommand = explanation.nextCommands[0];
+    const enriched = {
+        ...check,
+        blockerKind: explanation.kind,
+        details
+    };
+    if (result.blocker.code !== undefined)
+        enriched.code = result.blocker.code;
+    if (check.remediation === undefined && explanation.remediation.length > 0) {
+        enriched.remediation = explanation.remediation.map(step => `${step.label}: ${step.instruction}`);
+    }
+    if (nextCommand !== undefined)
+        enriched.nextCommand = nextCommand;
+    return enriched;
+}
+function ok(message, details) {
+    return details === undefined ? { status: "ok", message } : { status: "ok", message, details };
+}
+function blocked(message, remediation, details, blockerKind, code) {
+    return capability("blocked", message, remediation, details, undefined, blockerKind, code);
+}
+function unsupported(message, remediation, details, nextCommand, code) {
+    return capability("unsupported", message, remediation, details, nextCommand, undefined, code);
 }
-function blocked(message, remediation) {
-    return remediation === undefined ? { status: "blocked", message } : { status: "blocked", message, remediation };
+function unknown(message, remediation, details, nextCommand) {
+    return capability("unknown", message, remediation, details, nextCommand);
 }
-function unsupported(message, remediation) {
-    return remediation === undefined ? { status: "unsupported", message } : { status: "unsupported", message, remediation };
+function capability(status, message, remediation, details, nextCommand, blockerKind, code) {
+    const check = { status, message };
+    if (remediation !== undefined)
+        check.remediation = remediation;
+    if (details !== undefined)
+        check.details = details;
+    if (nextCommand !== undefined)
+        check.nextCommand = nextCommand;
+    if (blockerKind !== undefined)
+        check.blockerKind = blockerKind;
+    if (code !== undefined)
+        check.code = code;
+    return check;
 }
-function unknown(message, remediation) {
-    return remediation === undefined ? { status: "unknown", message } : { status: "unknown", message, remediation };
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
 }

package/dist/src/commands/files.d.ts

@@ -1,4 +1,5 @@
-import type { AttachedFile, AttachFilesArgs, AttachFilesData, CommandResult, DownloadedFile, DownloadLatestArgs, RuntimeEnv } from "../types.js";
+import type { AttachedFile, AttachFilesArgs, AttachFilesData, CommandResult, DownloadedFile, DownloadLatestArgs, FilePreflightArgs, FilePreflightData, RuntimeEnv } from "../types.js";
 export declare function validateAttachPaths(paths: string[]): Promise<AttachedFile[]>;
+export declare function preflightFiles(env: RuntimeEnv, args: FilePreflightArgs): Promise<CommandResult<FilePreflightData>>;
 export declare function attachFiles(env: RuntimeEnv, args: AttachFilesArgs): Promise<CommandResult<AttachFilesData>>;
 export declare function downloadLatestFile(env: RuntimeEnv, args: DownloadLatestArgs): Promise<CommandResult<DownloadedFile>>;