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

package/dist/src/scripts/live-smoke/scenarios.js

@@ -2,6 +2,7 @@ import { mkdtemp, readFile, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { attachAskRead, attachFiles, askMessage, bootstrap, composeMessage, createChatGPT, copyResponse, downloadLatestAttachment, newThread, openThread, readLatest, runSequence, searchThreads, selectTool, setMode, submitMessage, twoTurnExchange, waitAndRead, waitForMessage } from "../../index.js";
+import { readAssistantGenerationState } from "../../dom/generation-state.js";
 import { contextEnvFlag, contextEnvText } from "./harness.js";
 export const requiredScenarios = [
     scenario("bootstrap-new-tab", true, () => true, async (context, meta) => {
@@ -447,6 +448,54 @@ export const requiredScenarios = [
     })
 ];
 export const optionalScenarios = [
+    scenario("long-response-partial-short-timeout", false, context => contextEnvFlag(context, "CHATGPT_E2E_LONG_PARTIAL"), async (context, meta) => {
+        const env = await bootNewThread(context, meta);
+        if ("status" in env)
+            return env;
+        const result = await askMessage(env, {
+            text: [
+                "Live capture stress test. Write exactly 180 numbered items.",
+                "Each item should be a complete sentence. Continue until item 180."
+            ].join("\n"),
+            wait: { timeoutMs: 30000, stableMs: 2000, pollMs: 750 },
+            read: { format: "markdown" }
+        });
+        const output = result.output_text ?? "";
+        const details = partialCaptureDetails(result, output);
+        return !result.ok && result.status === "partial" && result.data?.complete === false
+            ? pass(meta, result, details)
+            : fail(meta, result, details);
+    }),
+    scenario("stop-control-detection", false, context => contextEnvFlag(context, "CHATGPT_E2E_STOP_CONTROL"), async (context, meta) => {
+        const env = await bootNewThread(context, meta);
+        if ("status" in env)
+            return env;
+        const asked = await askMessage(env, {
+            text: [
+                "Live stop-control stress test. Write exactly 400 numbered items.",
+                "Each item should be a complete sentence. Continue until item 400."
+            ].join("\n"),
+            wait: false,
+            read: false
+        });
+        if (!asked.ok)
+            return fail(meta, asked);
+        const generation = await waitForGenerationSignal(env, 30000);
+        const waited = await waitForMessage(env, { timeoutMs: 1000, stableMs: 0, pollMs: 250 });
+        await stopGenerationIfVisible(env);
+        const output = waited.output_text ?? "";
+        const details = {
+            generationActive: generation.active,
+            generationStopped: generation.stopped,
+            generationSignals: generation.signals,
+            waitStatus: waited.status,
+            outputChars: output.length,
+            outputHash: hashPreview(output)
+        };
+        return generation.active && !(waited.ok && waited.data?.complete === true)
+            ? pass(meta, waited, details)
+            : fail(meta, waited, details);
+    }),
     scenario("download-generated-file", false, context => contextEnvFlag(context, "CHATGPT_E2E_DOWNLOAD"), async (context, meta) => {
         const env = await bootNewThread(context, meta);
         if ("status" in env)
@@ -640,6 +689,41 @@ function responseCommand(response) {
         context: { timestamp: new Date(response.created_at * 1000).toISOString() }
     };
 }
+function partialCaptureDetails(result, output) {
+    return {
+        resultStatus: result.status,
+        complete: result.data?.complete,
+        outputChars: output.length,
+        outputHash: hashPreview(output)
+    };
+}
+async function waitForGenerationSignal(env, timeoutMs) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        if (env.page !== undefined) {
+            const state = await readAssistantGenerationState(env.page).catch(() => ({ active: false, stopped: false, signals: [] }));
+            if (state.active || state.stopped) {
+                return state;
+            }
+        }
+        await env.page?.waitForTimeout?.(500);
+    }
+    return { active: false, stopped: false, signals: [] };
+}
+async function stopGenerationIfVisible(env) {
+    const stop = env.page?.getByRole?.("button", { name: /Stop answering|Stop generating|Stop streaming|Cancel/i });
+    const clicked = stop?.click?.({ timeoutMs: 5000 });
+    if (clicked !== undefined) {
+        await clicked.catch(() => undefined);
+    }
+}
+function hashPreview(text) {
+    let hash = 0;
+    for (const char of text) {
+        hash = ((hash << 5) - hash + char.charCodeAt(0)) | 0;
+    }
+    return Math.abs(hash).toString(16);
+}
 async function tempFile(name, body) {
     const dir = await mkdtemp(join(tmpdir(), "chatgpt-live-smoke-"));
     const file = join(dir, name);

package/dist/src/scripts/locale-capture/language-coverage.d.ts

@@ -0,0 +1,10 @@
+export type CoverageLanguage = {
+    language: string;
+    nativeName: string;
+    bcp47: string;
+    speakers: string;
+    status: string;
+};
+export declare function parseLanguageCoverageMarkdown(markdown: string): CoverageLanguage[];
+export declare function readLanguageCoverage(path: string): Promise<CoverageLanguage[]>;
+export declare function nonEnglishLanguages(languages: readonly CoverageLanguage[]): CoverageLanguage[];

package/dist/src/scripts/locale-capture/language-coverage.js

@@ -0,0 +1,39 @@
+import { readFile } from "node:fs/promises";
+const TABLE_ROW_PATTERNS = [
+    /^\|\s*[^|]+?\s*\|\s*(?<language>[^|]+?)\s*\|\s*(?<native>[^|]+?)\s*\|\s*`(?<bcp47>[^`]+)`\s*\|\s*(?<speakers>[^|]+?)\s*\|\s*(?<status>[^|]+?)\s*\|/,
+    /^\|\s*(?<language>[^|]+?)\s*\|\s*(?<native>[^|]+?)\s*\|\s*`(?<bcp47>[^`]+)`\s*\|\s*(?<speakers>[^|]+?)\s*\|\s*(?<status>[^|]+?)\s*\|/,
+];
+export function parseLanguageCoverageMarkdown(markdown) {
+    const seen = new Set();
+    const languages = [];
+    for (const line of markdown.split(/\r?\n/)) {
+        const match = TABLE_ROW_PATTERNS.map(pattern => pattern.exec(line)).find(Boolean);
+        const groups = match?.groups;
+        if (groups === undefined)
+            continue;
+        const bcp47 = groups.bcp47?.trim();
+        if (bcp47 === undefined || bcp47.length === 0 || seen.has(bcp47))
+            continue;
+        const language = groups.language?.trim();
+        const nativeName = groups.native?.trim();
+        const speakers = groups.speakers?.trim();
+        const status = groups.status?.trim();
+        if (language === undefined
+            || nativeName === undefined
+            || speakers === undefined
+            || status === undefined
+            || language.length === 0
+            || nativeName.length === 0) {
+            continue;
+        }
+        seen.add(bcp47);
+        languages.push({ language, nativeName, bcp47, speakers, status });
+    }
+    return languages;
+}
+export async function readLanguageCoverage(path) {
+    return parseLanguageCoverageMarkdown(await readFile(path, "utf8"));
+}
+export function nonEnglishLanguages(languages) {
+    return languages.filter(language => !/^en(?:-|$)/i.test(language.bcp47));
+}

package/dist/src/testing/surface-drift.d.ts

@@ -0,0 +1,66 @@
+import { type CommandDescriptor } from "../commands/registry.js";
+type DatedExemption = {
+    date: string;
+    reason: string;
+};
+type CommandExemption = DatedExemption & {
+    command: string;
+};
+type DescriptorExemption = DatedExemption & {
+    descriptor: string;
+};
+type DocAnchor = {
+    id: string;
+    paths: string[];
+    terms: string[];
+};
+type SurfaceDriftPolicy = {
+    schemaVersion: string;
+    backendCommandDescriptorExemptions: CommandExemption[];
+    descriptorBackendCommandExemptions: DescriptorExemption[];
+    backendDispatchExemptions: CommandExemption[];
+    pythonFacadeExemptions: CommandExemption[];
+    generatedBlockerDocs: string[];
+    docAnchors: DocAnchor[];
+};
+export type SurfaceCommandDescriptor = Pick<CommandDescriptor, "name" | "blockers">;
+export type SurfaceBlockerExplanation = {
+    kind: string;
+    title: string;
+    category: string;
+    severity: string;
+    userActionRequired: boolean;
+    nextCommands: string[];
+};
+export type SurfaceDriftModel = {
+    backendCommands: string[];
+    backendCapabilityCommands: string[];
+    backendDispatchCommands: string[];
+    commandDescriptors: SurfaceCommandDescriptor[];
+    commandDescriptorFixtureNames: string[];
+    paritySuiteCommands: string[];
+    pythonCommands: string[];
+    blockerKinds: string[];
+    blockerExplanationFixtureKinds: string[];
+    blockerExplanations: SurfaceBlockerExplanation[];
+    docs: Record<string, string>;
+    policy: SurfaceDriftPolicy;
+};
+export type SurfaceDriftReport = {
+    commandCount: number;
+    descriptorCount: number;
+    blockerKindCount: number;
+    pythonCommandCount: number;
+    generatedDocsChecked: number;
+    docAnchorsChecked: number;
+};
+export type SurfaceDriftValidationResult = {
+    ok: boolean;
+    errors: string[];
+    report: SurfaceDriftReport;
+};
+export declare function validateSurfaceDrift(packageRootInput?: URL | string): SurfaceDriftReport;
+export declare function collectSurfaceDriftModel(packageRootInput?: URL | string): SurfaceDriftModel;
+export declare function validateSurfaceDriftModel(model: SurfaceDriftModel): SurfaceDriftValidationResult;
+export declare function generatedBlockerCoverageSection(explanations: SurfaceBlockerExplanation[]): string;
+export {};

package/dist/src/testing/surface-drift.js

@@ -0,0 +1,363 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { backendCommands } from "../backend/protocol.js";
+import { commandDescriptors } from "../commands/registry.js";
+import { explainCommandBlocker } from "../diagnostics/blockers.js";
+const POLICY_SCHEMA_VERSION = "chatgpt.browser_control.surface_drift_policy.v1";
+const GENERATED_BLOCKERS_START = "<!-- surface-drift:blocker-kind-coverage:start -->";
+const GENERATED_BLOCKERS_END = "<!-- surface-drift:blocker-kind-coverage:end -->";
+export function validateSurfaceDrift(packageRootInput = defaultPackageRoot()) {
+    const result = validateSurfaceDriftModel(collectSurfaceDriftModel(packageRootInput));
+    if (!result.ok) {
+        throw new Error(`Surface drift validation failed:\n- ${result.errors.join("\n- ")}`);
+    }
+    return result.report;
+}
+export function collectSurfaceDriftModel(packageRootInput = defaultPackageRoot()) {
+    const packageRoot = toPath(packageRootInput);
+    const contractRoot = join(packageRoot, "contracts", "v1");
+    const policy = readJson(join(contractRoot, "surface-drift-policy.json"));
+    const repoRoot = resolve(packageRoot, "..", "..");
+    const pythonRoot = resolvePythonRoot(packageRoot);
+    const blockerKinds = readBlockerKinds(join(packageRoot, "src", "types.ts"));
+    const descriptorFixture = readJson(join(contractRoot, "fixtures", "command-descriptors.json"));
+    const capabilitiesFixture = readJson(join(contractRoot, "fixtures", "backend-capabilities.json"));
+    const blockerProfilesFixture = readJson(join(contractRoot, "fixtures", "blocker-explanation-profiles.json"));
+    const paritySuite = readJson(join(contractRoot, "parity-suite.json"));
+    const docs = collectDocs(packageRoot, policy, pythonRoot);
+    return {
+        backendCommands: [...backendCommands],
+        backendCapabilityCommands: capabilitiesFixture.commands ?? capabilitiesFixture.result?.commands ?? [],
+        backendDispatchCommands: readBackendDispatchCommands(join(packageRoot, "src", "backend", "session.ts")),
+        commandDescriptors: commandDescriptors().map(descriptor => ({ name: descriptor.name, blockers: [...descriptor.blockers] })),
+        commandDescriptorFixtureNames: (descriptorFixture.result ?? []).map(descriptor => descriptor.name),
+        paritySuiteCommands: Object.keys(paritySuite.backendCommands ?? {}),
+        pythonCommands: pythonRoot === undefined ? [] : readPythonCommands(pythonRoot, backendCommands),
+        blockerKinds,
+        blockerExplanationFixtureKinds: (blockerProfilesFixture.result?.profiles ?? []).map(profile => profile.kind),
+        blockerExplanations: blockerKinds.map(kind => {
+            const explanation = explainCommandBlocker({ kind: kind, message: `Synthetic ${kind} blocker for surface drift validation.` });
+            return {
+                kind,
+                title: explanation.title,
+                category: explanation.category,
+                severity: explanation.severity,
+                userActionRequired: explanation.userActionRequired,
+                nextCommands: [...explanation.nextCommands]
+            };
+        }),
+        docs,
+        policy: normalizePolicyForLayout(policy, repoRoot)
+    };
+}
+export function validateSurfaceDriftModel(model) {
+    const errors = [];
+    const backendCommandsSet = new Set(model.backendCommands);
+    const descriptorNames = sortedUnique(model.commandDescriptors.map(descriptor => descriptor.name));
+    const descriptorNameSet = new Set(descriptorNames);
+    const blockerKindSet = new Set(model.blockerKinds);
+    const backendDescriptorExemptions = new Set(model.policy.backendCommandDescriptorExemptions.map(exemption => exemption.command));
+    const descriptorBackendExemptions = new Set(model.policy.descriptorBackendCommandExemptions.map(exemption => exemption.descriptor));
+    const backendDispatchExemptions = new Set(model.policy.backendDispatchExemptions.map(exemption => exemption.command));
+    const pythonFacadeExemptions = new Set(model.policy.pythonFacadeExemptions.map(exemption => exemption.command));
+    validatePolicy(model, errors);
+    compareSets("backend capabilities fixture commands", model.backendCapabilityCommands, model.backendCommands, errors);
+    compareSets("command descriptor fixture names", model.commandDescriptorFixtureNames, descriptorNames, errors);
+    compareSets("parity-suite backend command coverage", model.paritySuiteCommands, model.backendCommands, errors);
+    compareSets("blocker explanation profile fixture kinds", model.blockerExplanationFixtureKinds, model.blockerKinds, errors);
+    for (const command of model.backendCommands) {
+        if (!descriptorNameSet.has(command) && !backendDescriptorExemptions.has(command)) {
+            errors.push(`backend command ${command} is missing from command descriptors and has no exemption`);
+        }
+        if (!model.backendDispatchCommands.includes(command) && !backendDispatchExemptions.has(command)) {
+            errors.push(`backend command ${command} is missing from backend dispatch and has no exemption`);
+        }
+        if (!model.pythonCommands.includes(command) && !pythonFacadeExemptions.has(command)) {
+            errors.push(`backend command ${command} is missing from Python facade coverage and has no exemption`);
+        }
+    }
+    for (const descriptor of model.commandDescriptors) {
+        if (!backendCommandsSet.has(descriptor.name) && !descriptorBackendExemptions.has(descriptor.name)) {
+            errors.push(`command descriptor ${descriptor.name} is not a backend command and has no exemption`);
+        }
+        for (const blocker of descriptor.blockers) {
+            if (!blockerKindSet.has(blocker)) {
+                errors.push(`command descriptor ${descriptor.name} references unknown blocker ${blocker}`);
+            }
+        }
+    }
+    for (const explanation of model.blockerExplanations) {
+        if (!blockerKindSet.has(explanation.kind)) {
+            errors.push(`blocker explanation references unknown kind ${explanation.kind}`);
+        }
+        if (explanation.kind !== "unknown" && explanation.title === "Unknown blocker") {
+            errors.push(`blocker kind ${explanation.kind} falls back to the unknown blocker explanation`);
+        }
+        for (const nextCommand of explanation.nextCommands) {
+            if (!backendCommandsSet.has(nextCommand) && !descriptorNameSet.has(nextCommand)) {
+                errors.push(`blocker kind ${explanation.kind} references unknown next command ${nextCommand}`);
+            }
+        }
+    }
+    const expectedBlockerSection = generatedBlockerCoverageSection(model.blockerExplanations);
+    let generatedDocsChecked = 0;
+    for (const docPath of model.policy.generatedBlockerDocs) {
+        const text = model.docs[docPath];
+        if (text === undefined)
+            continue;
+        generatedDocsChecked += 1;
+        if (normalizeLineEndings(extractGeneratedBlockerCoverage(text)) !== expectedBlockerSection) {
+            errors.push(`generated blocker coverage section is stale in ${docPath}`);
+        }
+    }
+    if (generatedDocsChecked === 0) {
+        errors.push("no generated blocker coverage docs were found");
+    }
+    let docAnchorsChecked = 0;
+    for (const anchor of model.policy.docAnchors) {
+        const existingPaths = anchor.paths.filter(path => model.docs[path] !== undefined);
+        if (existingPaths.length === 0) {
+            errors.push(`doc anchor ${anchor.id} has no existing checked paths`);
+            continue;
+        }
+        for (const docPath of existingPaths) {
+            const text = model.docs[docPath];
+            if (text === undefined)
+                continue;
+            docAnchorsChecked += anchor.terms.length;
+            for (const term of anchor.terms) {
+                if (!text.includes(term)) {
+                    errors.push(`doc anchor ${anchor.id} missing ${term} in ${docPath}`);
+                }
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        report: {
+            commandCount: model.backendCommands.length,
+            descriptorCount: descriptorNames.length,
+            blockerKindCount: model.blockerKinds.length,
+            pythonCommandCount: model.pythonCommands.length,
+            generatedDocsChecked,
+            docAnchorsChecked
+        }
+    };
+}
+export function generatedBlockerCoverageSection(explanations) {
+    return [
+        GENERATED_BLOCKERS_START,
+        "## Blocker Kind Coverage",
+        "",
+        "This section is checked by `npm run docs:drift`. Keep it aligned with `BlockerKind`, `explainCommandBlocker(...)`, command descriptors, and public troubleshooting coverage.",
+        "",
+        ...explanations.map(explanation => `- \`${explanation.kind}\`: ${explanation.title} (category: \`${explanation.category}\`, severity: \`${explanation.severity}\`, user action: ${explanation.userActionRequired ? "yes" : "no"})`),
+        GENERATED_BLOCKERS_END
+    ].join("\n");
+}
+function collectDocs(packageRoot, policy, pythonRoot) {
+    const paths = new Set([
+        ...policy.generatedBlockerDocs,
+        ...policy.docAnchors.flatMap(anchor => anchor.paths)
+    ]);
+    const docs = {};
+    for (const docPath of paths) {
+        const absolutePath = resolveDocPath(packageRoot, docPath, pythonRoot);
+        if (absolutePath === undefined)
+            continue;
+        if (existsSync(absolutePath) && statSync(absolutePath).isFile()) {
+            docs[docPath] = readFileSync(absolutePath, "utf8");
+        }
+    }
+    return docs;
+}
+function resolveDocPath(packageRoot, docPath, pythonRoot) {
+    const pythonPrefix = "$pythonRoot/";
+    if (docPath.startsWith(pythonPrefix)) {
+        if (pythonRoot === undefined)
+            return undefined;
+        return join(pythonRoot, docPath.slice(pythonPrefix.length));
+    }
+    return resolve(packageRoot, docPath);
+}
+function extractGeneratedBlockerCoverage(text) {
+    const start = text.indexOf(GENERATED_BLOCKERS_START);
+    const end = text.indexOf(GENERATED_BLOCKERS_END);
+    if (start < 0 || end < start)
+        return undefined;
+    return text.slice(start, end + GENERATED_BLOCKERS_END.length);
+}
+function normalizeLineEndings(text) {
+    return text?.replace(/\r\n?/g, "\n");
+}
+function validatePolicy(model, errors) {
+    const policy = model.policy;
+    if (policy.schemaVersion !== POLICY_SCHEMA_VERSION) {
+        errors.push(`surface-drift-policy.json has unsupported schemaVersion ${String(policy.schemaVersion)}`);
+    }
+    const backendCommandsSet = new Set(model.backendCommands);
+    const descriptorNames = new Set(model.commandDescriptors.map(descriptor => descriptor.name));
+    const commandExemptionGroups = [
+        ["backendCommandDescriptorExemptions", policy.backendCommandDescriptorExemptions, backendCommandsSet],
+        ["backendDispatchExemptions", policy.backendDispatchExemptions, backendCommandsSet],
+        ["pythonFacadeExemptions", policy.pythonFacadeExemptions, backendCommandsSet]
+    ];
+    for (const [group, exemptions, allowedCommands] of commandExemptionGroups) {
+        validateUniqueExemptions(group, exemptions.map(exemption => exemption.command), errors);
+        for (const exemption of exemptions) {
+            validateDatedExemption(`${group}.${exemption.command}`, exemption, errors);
+            if (!allowedCommands.has(exemption.command)) {
+                errors.push(`${group}.${exemption.command} does not reference a backend command`);
+            }
+        }
+    }
+    validateUniqueExemptions("descriptorBackendCommandExemptions", policy.descriptorBackendCommandExemptions.map(exemption => exemption.descriptor), errors);
+    for (const exemption of policy.descriptorBackendCommandExemptions) {
+        validateDatedExemption(`descriptorBackendCommandExemptions.${exemption.descriptor}`, exemption, errors);
+        if (!descriptorNames.has(exemption.descriptor)) {
+            errors.push(`descriptorBackendCommandExemptions.${exemption.descriptor} does not reference a command descriptor`);
+        }
+    }
+    const docAnchorIds = policy.docAnchors.map(anchor => anchor.id);
+    validateUniqueExemptions("docAnchors", docAnchorIds, errors);
+    for (const anchor of policy.docAnchors) {
+        if (anchor.paths.length === 0)
+            errors.push(`doc anchor ${anchor.id} must include at least one path`);
+        if (anchor.terms.length === 0)
+            errors.push(`doc anchor ${anchor.id} must include at least one term`);
+    }
+}
+function validateDatedExemption(label, exemption, errors) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(exemption.date)) {
+        errors.push(`${label} must include a YYYY-MM-DD date`);
+    }
+    if (exemption.reason.trim().length < 12) {
+        errors.push(`${label} must include a concrete reason`);
+    }
+}
+function validateUniqueExemptions(label, values, errors) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            errors.push(`${label} contains duplicate entry ${value}`);
+        seen.add(value);
+    }
+}
+function compareSets(label, actual, expected, errors) {
+    const actualSorted = sortedUnique(actual);
+    const expectedSorted = sortedUnique(expected);
+    const actualSet = new Set(actualSorted);
+    const expectedSet = new Set(expectedSorted);
+    const missing = expectedSorted.filter(item => !actualSet.has(item));
+    const extra = actualSorted.filter(item => !expectedSet.has(item));
+    if (missing.length > 0)
+        errors.push(`${label} missing: ${missing.join(", ")}`);
+    if (extra.length > 0)
+        errors.push(`${label} extra: ${extra.join(", ")}`);
+}
+function normalizePolicyForLayout(policy, repoRoot) {
+    if (existsSync(join(repoRoot, "packages", "node")) && !existsSync(join(repoRoot, "tools", "public-export"))) {
+        return {
+            ...policy,
+            generatedBlockerDocs: policy.generatedBlockerDocs.filter(path => !path.includes("tools/public-export")),
+            docAnchors: policy.docAnchors.map(anchor => ({
+                ...anchor,
+                paths: anchor.paths.filter(path => !path.includes("tools/public-export"))
+            }))
+        };
+    }
+    return policy;
+}
+function readBlockerKinds(typesPath) {
+    const text = readFileSync(typesPath, "utf8");
+    const match = text.match(/export type BlockerKind =([\s\S]*?);/);
+    if (match === null || match[1] === undefined) {
+        throw new Error("Unable to find BlockerKind union in src/types.ts.");
+    }
+    return [...match[1].matchAll(/"([^"]+)"/g)].map(item => {
+        const kind = item[1];
+        if (kind === undefined)
+            throw new Error("Unable to parse BlockerKind literal.");
+        return kind;
+    });
+}
+function readBackendDispatchCommands(sessionPath) {
+    const text = readFileSync(sessionPath, "utf8");
+    const match = text.match(/switch \(request\.command\) \{([\s\S]*?)\n  \}/);
+    if (match === null || match[1] === undefined) {
+        throw new Error("Unable to find backend command dispatch switch.");
+    }
+    return sortedUnique([...match[1].matchAll(/case "([^"]+)":/g)].map(item => {
+        const command = item[1];
+        if (command === undefined)
+            throw new Error("Unable to parse backend dispatch command.");
+        return command;
+    }));
+}
+function readPythonCommands(pythonRoot, knownBackendCommands) {
+    const known = new Set(knownBackendCommands);
+    const commands = new Set();
+    for (const path of pythonFiles(pythonRoot)) {
+        const text = readFileSync(path, "utf8");
+        for (const pattern of [
+            /command_result\([^,\n]+,\s*"([^"]+)"/g,
+            /request_backend\([^,\n]+,\s*"([^"]+)"/g,
+            /async_request_backend\([^,\n]+,\s*"([^"]+)"/g,
+            /self\.request\("([^"]+)"/g,
+            /self\.stream\("([^"]+)"/g,
+            /"([^"]+)"\s*:\s*"([^"]+)"/g
+        ]) {
+            for (const match of text.matchAll(pattern)) {
+                const command = match[2] ?? match[1];
+                if (command !== undefined && known.has(command)) {
+                    commands.add(command);
+                }
+            }
+        }
+    }
+    return sortedUnique([...commands]);
+}
+function pythonFiles(root) {
+    const result = [];
+    const visit = (path) => {
+        for (const entry of readdirSync(path, { withFileTypes: true })) {
+            const entryPath = join(path, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "__pycache__" || entry.name.endsWith(".egg-info"))
+                    continue;
+                visit(entryPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".py")) {
+                result.push(entryPath);
+            }
+        }
+    };
+    visit(root);
+    return result;
+}
+function resolvePythonRoot(packageRoot) {
+    const repoRoot = resolve(packageRoot, "..", "..");
+    const candidates = [
+        join(repoRoot, "packages", "python"),
+        resolve(packageRoot, "..", "python"),
+        join(repoRoot, "packages", "python"),
+        resolve(packageRoot, "..", "python")
+    ];
+    return candidates.find(path => existsSync(path) && statSync(path).isDirectory());
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function toPath(input) {
+    if (input instanceof URL)
+        return fileURLToPath(input);
+    return input;
+}
+function defaultPackageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}