extension 4.0.19 → 4.0.20

package/dist/browsers.cjs

@@ -1260,6 +1260,18 @@ var __webpack_modules__ = {
                 node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
             } catch  {}
         }
+        function stampReadyBrowserLaunch(extensionOutputPath, details) {
+            try {
+                if (!extensionOutputPath) return;
+                const readyPath = readyPathFor(extensionOutputPath);
+                if (!node_fs__rspack_import_0.existsSync(readyPath)) return;
+                const ready = JSON.parse(node_fs__rspack_import_0.readFileSync(readyPath, 'utf-8'));
+                const profilePath = String(details?.profilePath || '').trim();
+                if (profilePath) ready.profilePath = profilePath;
+                if ('number' == typeof details?.browserPid && Number.isFinite(details.browserPid)) ready.browserPid = details.browserPid;
+                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+            } catch  {}
+        }
         function stampReadyExtensionLoadRefused(extensionOutputPath, reason) {
             try {
                 if (!extensionOutputPath) return;
@@ -1306,6 +1318,7 @@ var __webpack_modules__ = {
             } catch  {}
         }
         __webpack_require__.d(__webpack_exports__, {
+            M: ()=>stampReadyBrowserLaunch,
             Wi: ()=>stampReadyBrowserExited,
             __: ()=>stampReadyRdpPort,
             iD: ()=>stampReadyProfileLocked,
@@ -3066,6 +3079,10 @@ var __webpack_modules__ = {
                     extensionOutputPath: (0, extension_output_path.W)(compilation, chromiumConfig.find((flag)=>flag.startsWith('--load-extension='))) || void 0
                 };
                 const child = await this.launchWithDirectSpawn(browserBinaryLocation, chromiumConfig, usePipe);
+                (0, ready_stamp.M)(this.closeHandlerContext?.extensionOutputPath, {
+                    profilePath: chromiumConfig.find((flag)=>flag.startsWith('--user-data-dir='))?.slice('--user-data-dir='.length).replace(/^"|"$/g, ''),
+                    browserPid: child?.pid
+                });
                 const pipeStreams = usePipe && child?.stdio?.[3] && child?.stdio?.[4] ? {
                     input: child.stdio[4],
                     output: child.stdio[3]
@@ -4835,6 +4852,10 @@ var __webpack_modules__ = {
                     const profilePath = profileMatch[1];
                     const { binary, args } = FirefoxBinaryDetector.generateFirefoxArgs(binaryPath, profilePath, debugPort, firefoxArgs, isFirefoxHeadlessRequested());
                     this.child = await this.spawnFirefoxChild(binary, args, wslFallbackBinary);
+                    (0, ready_stamp.M)(this.extensionOutputPath, {
+                        profilePath,
+                        browserPid: this.child?.pid
+                    });
                     this.child.on('close', ()=>{
                         (0, shared_utils.sW)(profilePath);
                     });
@@ -4883,6 +4904,9 @@ var __webpack_modules__ = {
                         ...firefoxArgs
                     ];
                     this.child = await this.spawnFirefoxChild(binaryPath, args, wslFallbackBinary);
+                    (0, ready_stamp.M)(this.extensionOutputPath, {
+                        browserPid: this.child?.pid
+                    });
                     this.wireChildLifecycle();
                     if (debugPort > 0) (0, ready_stamp.__)(this.extensionOutputPath, debugPort);
                     this.scheduleWatchTimeout();

package/dist/cli.cjs

@@ -1261,6 +1261,18 @@ var __webpack_modules__ = {
                 node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
             } catch  {}
         }
+        function stampReadyBrowserLaunch(extensionOutputPath, details) {
+            try {
+                if (!extensionOutputPath) return;
+                const readyPath = readyPathFor(extensionOutputPath);
+                if (!node_fs__rspack_import_0.existsSync(readyPath)) return;
+                const ready = JSON.parse(node_fs__rspack_import_0.readFileSync(readyPath, 'utf-8'));
+                const profilePath = String(details?.profilePath || '').trim();
+                if (profilePath) ready.profilePath = profilePath;
+                if ('number' == typeof details?.browserPid && Number.isFinite(details.browserPid)) ready.browserPid = details.browserPid;
+                node_fs__rspack_import_0.writeFileSync(readyPath, JSON.stringify(ready, null, 2));
+            } catch  {}
+        }
         function stampReadyExtensionLoadRefused(extensionOutputPath, reason) {
             try {
                 if (!extensionOutputPath) return;
@@ -1307,6 +1319,7 @@ var __webpack_modules__ = {
             } catch  {}
         }
         __webpack_require__.d(__webpack_exports__, {
+            M: ()=>stampReadyBrowserLaunch,
             Wi: ()=>stampReadyBrowserExited,
             __: ()=>stampReadyRdpPort,
             iD: ()=>stampReadyProfileLocked,
@@ -3056,6 +3069,10 @@ var __webpack_modules__ = {
                     extensionOutputPath: (0, extension_output_path.W)(compilation, chromiumConfig.find((flag)=>flag.startsWith('--load-extension='))) || void 0
                 };
                 const child = await this.launchWithDirectSpawn(browserBinaryLocation, chromiumConfig, usePipe);
+                (0, ready_stamp.M)(this.closeHandlerContext?.extensionOutputPath, {
+                    profilePath: chromiumConfig.find((flag)=>flag.startsWith('--user-data-dir='))?.slice('--user-data-dir='.length).replace(/^"|"$/g, ''),
+                    browserPid: child?.pid
+                });
                 const pipeStreams = usePipe && child?.stdio?.[3] && child?.stdio?.[4] ? {
                     input: child.stdio[4],
                     output: child.stdio[3]
@@ -4825,6 +4842,10 @@ var __webpack_modules__ = {
                     const profilePath = profileMatch[1];
                     const { binary, args } = FirefoxBinaryDetector.generateFirefoxArgs(binaryPath, profilePath, debugPort, firefoxArgs, isFirefoxHeadlessRequested());
                     this.child = await this.spawnFirefoxChild(binary, args, wslFallbackBinary);
+                    (0, ready_stamp.M)(this.extensionOutputPath, {
+                        profilePath,
+                        browserPid: this.child?.pid
+                    });
                     this.child.on('close', ()=>{
                         (0, shared_utils.sW)(profilePath);
                     });
@@ -4873,6 +4894,9 @@ var __webpack_modules__ = {
                         ...firefoxArgs
                     ];
                     this.child = await this.spawnFirefoxChild(binaryPath, args, wslFallbackBinary);
+                    (0, ready_stamp.M)(this.extensionOutputPath, {
+                        browserPid: this.child?.pid
+                    });
                     this.wireChildLifecycle();
                     if (debugPort > 0) (0, ready_stamp.__)(this.extensionOutputPath, debugPort);
                     this.scheduleWatchTimeout();
@@ -5754,6 +5778,8 @@ var __webpack_modules__ = {
             E_SESSION_NOT_FOUND: 'E_SESSION_NOT_FOUND',
             E_EVAL_REFUSED: 'E_EVAL_REFUSED',
             E_TARGET_NOT_FOUND: 'E_TARGET_NOT_FOUND',
+            E_HEADED_WINDOW_REQUIRED: 'E_HEADED_WINDOW_REQUIRED',
+            E_USER_GESTURE_REQUIRED: 'E_USER_GESTURE_REQUIRED',
             E_TIMEOUT: 'E_TIMEOUT',
             E_PUBLISH_REJECTED: 'E_PUBLISH_REJECTED',
             E_AUTH_REQUIRED: 'E_AUTH_REQUIRED',
@@ -6296,6 +6322,12 @@ var __webpack_modules__ = {
                 ],
                 description: 'Diagnose a dev session: ready contract, control channel, token, executor, browser',
                 supportsSourceInspection: false
+            },
+            {
+                name: 'capabilities',
+                positionals: [],
+                description: 'Print the engine version, contract versions, and json-capable commands',
+                supportsSourceInspection: false
             }
         ];
         const COMMANDS = COMMAND_TABLE.map((entry)=>({
@@ -6746,12 +6778,21 @@ Cross-Browser Compatibility
             }
             return out.slice(Math.max(0, out.length - limit));
         }
-        function codeForBridgeError(name, message) {
+        const REFUSAL_TO_CODE = {
+            needs_headed_window: messaging.Lp.E_HEADED_WINDOW_REQUIRED,
+            needs_user_gesture: messaging.Lp.E_USER_GESTURE_REQUIRED,
+            surface_not_open: messaging.Lp.E_TARGET_NOT_FOUND,
+            api_unavailable: messaging.Lp.E_NOT_IMPLEMENTED
+        };
+        function codeForBridgeError(name, message, refusal) {
+            if (refusal && refusal in REFUSAL_TO_CODE) return REFUSAL_TO_CODE[refusal];
             if ('Timeout' === name) return messaging.Lp.E_TIMEOUT;
             if ('Unavailable' === name) return messaging.Lp.E_CONTROL_UNAVAILABLE;
-            if ('Forbidden' === name) return /token missing/i.test(message) ? messaging.Lp.E_TOKEN_MISSING : messaging.Lp.E_EVAL_REFUSED;
+            if ('EvalTokenMissing' === name) return messaging.Lp.E_TOKEN_MISSING;
+            if ('EvalDisabled' === name || 'EvalTokenMismatch' === name || 'Forbidden' === name) return messaging.Lp.E_EVAL_REFUSED;
+            if ('TargetNotFound' === name) return messaging.Lp.E_TARGET_NOT_FOUND;
             if ('BadRequest' === name) return messaging.Lp.E_ARGS;
-            if ('Unsupported' === name) return /needs a --tab id|no injectable frame|is not open/i.test(message) ? messaging.Lp.E_TARGET_NOT_FOUND : messaging.Lp.E_NOT_IMPLEMENTED;
+            if ('Unsupported' === name) return /needs a --tab id|is not open/i.test(message) ? messaging.Lp.E_TARGET_NOT_FOUND : messaging.Lp.E_NOT_IMPLEMENTED;
             if ('EvalError' === name) return messaging.Lp.E_EVAL;
             if ('InspectError' === name) return messaging.Lp.E_INSPECT;
             if ('StorageError' === name) return messaging.Lp.E_STORAGE;
@@ -6776,14 +6817,19 @@ Cross-Browser Compatibility
             const raw = error || {};
             const name = 'string' == typeof raw.name ? raw.name : 'Error';
             const message = 'string' == typeof raw.message ? raw.message : 'command failed';
-            const code = codeForBridgeError(name, message);
+            const refusal = 'string' == typeof raw.code ? raw.code : void 0;
+            const code = codeForBridgeError(name, message, refusal);
+            const hint = 'string' == typeof raw.hint ? raw.hint : code === messaging.Lp.E_EVAL ? 'The expression threw inside the page. Check the expression itself.' : void 0;
             return {
                 ...extras,
                 ...messaging.Pr.fail(command, statusForCode(code), {
                     ...raw,
                     code,
                     message,
-                    name
+                    name,
+                    ...hint ? {
+                        hint
+                    } : {}
                 }, {
                     truncated: wasTruncated
                 })
@@ -7193,7 +7239,7 @@ Cross-Browser Compatibility
                 if (asJson) console.log(JSON.stringify(messaging.Pr.ok('build', 'built', {
                     projectPath: pathOrRemoteUrl,
                     browsers: built,
-                    mode,
+                    mode: mode ?? 'production',
                     summaries
                 })));
             });
@@ -7213,6 +7259,43 @@ Cross-Browser Compatibility
             }
             throw new Error('Extension.js CLI package.json not found.');
         }
+        const READY_CONTRACT_SCHEMA_VERSION = 2;
+        function collectOutputJsonCommands(program) {
+            const names = new Set();
+            for (const command of program.commands){
+                const accepts = (command.options || []).some((option)=>'--output' === option.long && String(option.flags || '').includes('json'));
+                if (accepts) names.add(command.name());
+            }
+            return Array.from(names).sort();
+        }
+        function buildEngineCapabilities(program) {
+            const cliPackageJson = getCliPackageJson();
+            return {
+                name: String(cliPackageJson.name || 'extension'),
+                version: String(cliPackageJson.version || ''),
+                envelopeSchema: 1,
+                readySchemaVersion: READY_CONTRACT_SCHEMA_VERSION,
+                outputJsonCommands: collectOutputJsonCommands(program)
+            };
+        }
+        function registerCapabilitiesCommand(program) {
+            program.command('capabilities').description(commandDescriptions.capabilities).option('--output <pretty|json>', 'result format. This command defaults to json').action(async (opts = {})=>{
+                const format = 'pretty' === String(opts.output ?? 'json').trim().toLowerCase() ? 'pretty' : 'json';
+                const value = buildEngineCapabilities(program);
+                if ('json' === format) {
+                    console.log(JSON.stringify(messaging.Pr.ok('capabilities', 'ok', value)));
+                    await exitAfterDrain(0);
+                    return;
+                }
+                console.log([
+                    `${value.name} ${value.version}`,
+                    `envelope schema: ${value.envelopeSchema}`,
+                    `ready contract schemaVersion: ${value.readySchemaVersion}`,
+                    `commands that accept --output json: ${value.outputJsonCommands.join(', ')}`
+                ].join('\n'));
+                await exitAfterDrain(0);
+            });
+        }
         const create_require = (0, external_node_module_.createRequire)(__rslib_import_meta_url__);
         const CREATE_ERROR_NEEDLES = {
             E_DESTINATION_NOT_EMPTY: 'already contains files that would be overwritten',
@@ -7274,6 +7357,95 @@ Cross-Browser Compatibility
             });
         }
         var browsers = __webpack_require__("./browsers/index.ts");
+        const FRAMED_FLAG = 'extensionEnvelopePrinted';
+        function markErrorFramed(err) {
+            if (err && 'object' == typeof err) try {
+                err[FRAMED_FLAG] = true;
+            } catch  {}
+        }
+        function isErrorFramed(err) {
+            return Boolean(err && 'object' == typeof err && true === err[FRAMED_FLAG]);
+        }
+        function wantsJsonOutput(argv) {
+            const equalArg = argv.find((arg)=>arg.startsWith('--output='));
+            if (equalArg) return 'json' === equalArg.slice(9).trim().toLowerCase();
+            const flagIndex = argv.indexOf('--output');
+            if (flagIndex >= 0) return 'json' === String(argv[flagIndex + 1] || '').trim().toLowerCase();
+            return false;
+        }
+        function isCommanderError(err) {
+            return Boolean(err && 'object' == typeof err && 'string' == typeof err.code && String(err.code).startsWith('commander.'));
+        }
+        function commanderExitCode(err) {
+            const exitCode = Number(err.exitCode);
+            return Number.isFinite(exitCode) ? exitCode : 1;
+        }
+        function firstQuoted(message, pattern) {
+            const match = pattern.exec(message);
+            return match?.[1];
+        }
+        function refsFromMessage(code, message) {
+            if ('commander.unknownOption' === code) {
+                const flag = firstQuoted(message, /'(-[^']*)'/);
+                return flag ? {
+                    flag
+                } : void 0;
+            }
+            if ('commander.unknownCommand' === code) {
+                const command = firstQuoted(message, /'([^']+)'/);
+                return command ? {
+                    command
+                } : void 0;
+            }
+            if ('commander.invalidArgument' === code || 'commander.optionMissingArgument' === code) {
+                const option = firstQuoted(message, /option '([^']+)'/);
+                const flag = option?.split(/\s+/)[0];
+                return flag?.startsWith('-') ? {
+                    flag
+                } : void 0;
+            }
+        }
+        function codeForCommanderError(code) {
+            if ('commander.unknownCommand' === code) return messaging.Lp.E_UNKNOWN_COMMAND;
+            if ('commander.unknownOption' === code) return messaging.Lp.E_FLAG_NOT_SUPPORTED_HERE;
+            if ('commander.invalidArgument' === code || 'commander.optionMissingArgument' === code) return messaging.Lp.E_FLAG_VALUE_INVALID;
+            return messaging.Lp.E_ARGS;
+        }
+        function commanderErrorEnvelope(err, command) {
+            const commanderCode = String(err.code);
+            const message = String(err.message || 'the command line could not be parsed').replace(/^error:\s*/i, '').trim();
+            const error = {
+                code: codeForCommanderError(commanderCode),
+                message,
+                name: 'CliError'
+            };
+            const refs = refsFromMessage(commanderCode, message);
+            if (refs) error.refs = refs;
+            return messaging.Pr.fail(command, 'usage', error);
+        }
+        function internalErrorEnvelope(err, command) {
+            return messaging.Pr.fail(command, 'failed', {
+                code: messaging.Lp.E_INTERNAL,
+                message: err instanceof Error ? err.message : String(err),
+                name: err instanceof Error ? err.name : 'Error'
+            });
+        }
+        function earlyExitEnvelope(command, code, message, refs) {
+            const error = {
+                code,
+                message,
+                name: 'CliError'
+            };
+            if (refs) error.refs = refs;
+            return messaging.Pr.fail(command, 'usage', error);
+        }
+        function writeStdoutFrame(frame) {
+            try {
+                external_node_fs_.writeSync(1, `${JSON.stringify(frame)}\n`);
+            } catch  {
+                console.log(JSON.stringify(frame));
+            }
+        }
         let warnedDeprecatedAlias = false;
         function warnDeprecatedOutputAlias(flag) {
             if (warnedDeprecatedAlias) return;
@@ -7602,6 +7774,7 @@ Cross-Browser Compatibility
                             }, {
                                 hint: failure.hint
                             }));
+                            markErrorFramed(error);
                         }
                         throw error;
                     }
@@ -8426,6 +8599,7 @@ Cross-Browser Compatibility
                             }, {
                                 hint: failure.hint
                             }));
+                            markErrorFramed(error);
                         }
                         throw error;
                     }
@@ -8964,9 +9138,9 @@ Cross-Browser Compatibility
             }
             return null;
         }
-        const cliPackageJson = getCliPackageJson();
+        const index_cliPackageJson = getCliPackageJson();
         function developVersion() {
-            return resolveExtensionDevelopVersion(__dirname, cliPackageJson.version);
+            return resolveExtensionDevelopVersion(__dirname, index_cliPackageJson.version);
         }
         process.env.EXTENSION_DEVELOP_VERSION = developVersion();
         function scanArgvValue(argv, flag) {
@@ -8991,19 +9165,23 @@ Cross-Browser Compatibility
                 if (!arg.startsWith('-')) return arg;
             }
         }
+        function failBeforeParse(argv, humanMessage, code, plainMessage, flag) {
+            console.error(humanMessage);
+            if (wantsJsonOutput(argv)) writeStdoutFrame(earlyExitEnvelope(resolveCommandFromArgv(argv) || 'extension', code, plainMessage, {
+                flag
+            }));
+            process.exit(1);
+        }
         function applyNoBrowserArgvShim(argv) {
             const hasNoRunner = argv.includes('--no-runner');
-            if (hasNoRunner) {
-                console.error(removedNoRunnerFlag());
-                process.exit(1);
-            }
+            if (hasNoRunner) failBeforeParse(argv, removedNoRunnerFlag(), messaging.Lp.E_REMOVED_FLAG, '--no-runner was removed. Use --no-browser instead.', '--no-runner');
             let nextArgv = argv;
             const hasNoReload = nextArgv.includes('--no-reload');
             if (hasNoReload) {
                 const command = resolveCommandFromArgv(nextArgv);
                 if ('dev' !== command) {
-                    console.error(`--no-reload is only supported on \`extension dev\` (got: ${command || 'no command'}).`);
-                    process.exit(1);
+                    const message = `--no-reload is only supported on \`extension dev\` (got: ${command || 'no command'}).`;
+                    failBeforeParse(nextArgv, message, messaging.Lp.E_FLAG_NOT_SUPPORTED_HERE, message, '--no-reload');
                 }
                 process.env.EXTENSION_NO_RELOAD = 'true';
                 nextArgv = nextArgv.filter((arg)=>'--no-reload' !== arg);
@@ -9012,10 +9190,7 @@ Cross-Browser Compatibility
             if (!hasNoBrowser) return nextArgv;
             const command = resolveCommandFromArgv(nextArgv);
             const supportsNoBrowser = 'dev' === command || 'start' === command || 'preview' === command;
-            if (!supportsNoBrowser) {
-                console.error(noBrowserNotSupportedForCommand(command));
-                process.exit(1);
-            }
+            if (!supportsNoBrowser) failBeforeParse(nextArgv, noBrowserNotSupportedForCommand(command), messaging.Lp.E_FLAG_NOT_SUPPORTED_HERE, command ? `--no-browser is not supported on \`extension ${command}\`.` : '--no-browser needs a command that launches a browser.', '--no-browser');
             process.env.EXTENSION_CLI_NO_BROWSER = '1';
             return nextArgv.filter((arg)=>'--no-browser' !== arg);
         }
@@ -9025,7 +9200,7 @@ Cross-Browser Compatibility
             process.env.EXTENSION_CLI_UPDATE_SUFFIX = updateMessage.suffix;
         });
         const extensionJs = external_commander_namespaceObject.program;
-        extensionJs.name(String(cliPackageJson.name)).description(String(cliPackageJson.description)).version(String(cliPackageJson.version)).option('--no-telemetry', 'disable anonymous telemetry for this run').option('--ai-help', 'show AI-assistant oriented help and tips').addOption(new external_commander_namespaceObject.Option('--format <pretty|json>').hideHelp()).addHelpText('after', programUserHelp()).showHelpAfterError(true).showSuggestionAfterError(true);
+        extensionJs.name(String(index_cliPackageJson.name)).description(String(index_cliPackageJson.description)).version(String(index_cliPackageJson.version)).option('--no-telemetry', 'disable anonymous telemetry for this run').option('--ai-help', 'show AI-assistant oriented help and tips').addOption(new external_commander_namespaceObject.Option('--format <pretty|json>').hideHelp()).addHelpText('after', programUserHelp()).showHelpAfterError(true).showSuggestionAfterError(true).exitOverride();
         registerCreateCommand(extensionJs);
         registerDevCommand(extensionJs);
         registerStartCommand(extensionJs);
@@ -9037,10 +9212,11 @@ Cross-Browser Compatibility
         registerInstallCommand(extensionJs);
         registerTelemetryCommand(extensionJs);
         registerDoctorCommand(extensionJs);
+        registerCapabilitiesCommand(extensionJs);
         function runAIHelp() {
             const format = resolveAIHelpFormatFromArgv(process.argv).trim().toLowerCase();
             if ('json' === format) {
-                console.log(JSON.stringify(programAIHelpJSON(String(cliPackageJson.version)), null, 2));
+                console.log(JSON.stringify(programAIHelpJSON(String(index_cliPackageJson.version)), null, 2));
                 exitAfterDrain(0);
                 return;
             }
@@ -9059,13 +9235,26 @@ Cross-Browser Compatibility
         if (process.argv.includes('--ai-help')) runAIHelp();
         else {
             const argv = applyNoBrowserArgvShim(process.argv);
-            extensionJs.parseAsync(argv).then(()=>{
-                markCommandSuccess();
-            }).catch((err)=>{
-                markCommandFailure();
-                console.error(unhandledError(err));
-                process.exit(1);
-            });
+            const asJson = wantsJsonOutput(argv);
+            const commandName = resolveCommandFromArgv(argv) || 'extension';
+            (async ()=>{
+                try {
+                    await extensionJs.parseAsync(argv);
+                    markCommandSuccess();
+                } catch (err) {
+                    if (isCommanderError(err)) {
+                        const exitCode = commanderExitCode(err);
+                        if (0 === exitCode) process.exit(0);
+                        markCommandFailure();
+                        if (asJson) writeStdoutFrame(commanderErrorEnvelope(err, commandName));
+                        process.exit(exitCode);
+                    }
+                    markCommandFailure();
+                    console.error(unhandledError(err));
+                    if (asJson && !isErrorFramed(err)) writeStdoutFrame(internalErrorEnvelope(err, commandName));
+                    process.exit(1);
+                }
+            })();
         }
     },
     "chrome-location2" (module) {

package/dist/extension/browsers/browsers-lib/ready-stamp.d.ts

@@ -1,4 +1,8 @@
 export declare function stampReadyRdpPort(extensionOutputPath: string | undefined, rdpPort: number): void;
+export declare function stampReadyBrowserLaunch(extensionOutputPath: string | undefined, details: {
+    profilePath?: string;
+    browserPid?: number;
+}): void;
 export declare function stampReadyExtensionLoadRefused(extensionOutputPath: string | undefined, reason: string): void;
 export declare function stampReadyProfileLocked(extensionOutputPath: string | undefined, details: {
     message?: string;

package/dist/extension/commands/act.d.ts

@@ -11,6 +11,7 @@ interface ActResultLike {
         name?: unknown;
         message?: unknown;
         engine?: unknown;
+        code?: unknown;
     };
 }
 /**

package/dist/extension/commands/capabilities.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+export declare const READY_CONTRACT_SCHEMA_VERSION = 2;
+export declare function collectOutputJsonCommands(program: Command): string[];
+export interface EngineCapabilities {
+    name: string;
+    version: string;
+    envelopeSchema: number;
+    readySchemaVersion: number;
+    outputJsonCommands: string[];
+}
+export declare function buildEngineCapabilities(program: Command): EngineCapabilities;
+export declare function registerCapabilitiesCommand(program: Command): void;

package/dist/extension/helpers/cli-failure.d.ts

@@ -0,0 +1,16 @@
+import { ENVELOPE, type EnvelopeErrorRefs, type ErrorCode } from './messaging';
+export declare function markErrorFramed(err: unknown): void;
+export declare function isErrorFramed(err: unknown): boolean;
+export declare function wantsJsonOutput(argv: string[]): boolean;
+interface CommanderErrorLike {
+    code?: unknown;
+    exitCode?: unknown;
+    message?: unknown;
+}
+export declare function isCommanderError(err: unknown): err is CommanderErrorLike;
+export declare function commanderExitCode(err: CommanderErrorLike): number;
+export declare function commanderErrorEnvelope(err: CommanderErrorLike, command: string): ReturnType<typeof ENVELOPE.fail>;
+export declare function internalErrorEnvelope(err: unknown, command: string): ReturnType<typeof ENVELOPE.fail>;
+export declare function earlyExitEnvelope(command: string, code: ErrorCode, message: string, refs?: EnvelopeErrorRefs): ReturnType<typeof ENVELOPE.fail>;
+export declare function writeStdoutFrame(frame: unknown): void;
+export {};

package/dist/extension/helpers/messages.d.ts

@@ -177,6 +177,11 @@ declare const COMMAND_TABLE: readonly [{
     }];
     readonly description: 'Diagnose a dev session: ready contract, control channel, token, executor, browser';
     readonly supportsSourceInspection: false;
+}, {
+    readonly name: 'capabilities';
+    readonly positionals: readonly [];
+    readonly description: 'Print the engine version, contract versions, and json-capable commands';
+    readonly supportsSourceInspection: false;
 }];
 export type CommandName = (typeof COMMAND_TABLE)[number]['name'];
 export interface CommandSpec extends CommandTableEntry {

package/dist/extension/helpers/messaging.d.ts

@@ -54,6 +54,8 @@ export declare const CODES: {
     readonly E_SESSION_NOT_FOUND: 'E_SESSION_NOT_FOUND';
     readonly E_EVAL_REFUSED: 'E_EVAL_REFUSED';
     readonly E_TARGET_NOT_FOUND: 'E_TARGET_NOT_FOUND';
+    readonly E_HEADED_WINDOW_REQUIRED: 'E_HEADED_WINDOW_REQUIRED';
+    readonly E_USER_GESTURE_REQUIRED: 'E_USER_GESTURE_REQUIRED';
     readonly E_TIMEOUT: 'E_TIMEOUT';
     readonly E_PUBLISH_REJECTED: 'E_PUBLISH_REJECTED';
     readonly E_AUTH_REQUIRED: 'E_AUTH_REQUIRED';
@@ -149,12 +151,19 @@ export declare const CODES: {
     readonly E_UNINSTALL_NOOP: 'E_UNINSTALL_NOOP';
 };
 export type ErrorCode = (typeof CODES)[keyof typeof CODES];
+export interface EnvelopeErrorRefs {
+    flag?: string;
+    command?: string;
+    path?: string;
+    version?: string;
+}
 export interface EnvelopeError {
     code: ErrorCode;
     message: string;
     name?: string;
     engine?: string;
     hint?: string;
+    refs?: EnvelopeErrorRefs;
 }
 export interface Envelope<T = unknown> {
     schema: typeof ENVELOPE_SCHEMA;

package/package.json

@@ -38,7 +38,7 @@
     "extension": "./bin/extension.cjs"
   },
   "name": "extension",
-  "version": "4.0.19",
+  "version": "4.0.20",
   "description": "The cross-browser extension framework. Build Chrome, Edge, Firefox, and Safari extensions with no build configuration.",
   "homepage": "https://extension.js.org/",
   "bugs": {
@@ -106,9 +106,9 @@
     "vivaldi-location2": "2.1.0",
     "waterfox-location": "2.1.0",
     "yandex-location": "2.1.0",
-    "extension-create": "4.0.19",
-    "extension-develop": "4.0.19",
-    "extension-install": "4.0.19",
+    "extension-create": "4.0.20",
+    "extension-develop": "4.0.20",
+    "extension-install": "4.0.20",
     "commander": "^15.0.0",
     "pintor": "0.3.0",
     "semver": "^7.7.3",