@mearl/client 3.0.0-beta.8 → 3.0.0

package/dist/plugins/runtime/pluginPageManager.js

@@ -1,8 +1,10 @@
 import { diagnosticBinding } from './pluginDiagnostics.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { readFileSync, statSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { lstatSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { keyedDir } from '@mearl/daemon-core';
 import { capturePluginRevision } from './pluginRevision.js';
 import { findPluginRegistration } from '../sdk/plugin.js';
 import { UnifiedClient, decodeBrowserTarget } from '../../unified.js';
@@ -361,6 +363,14 @@ export class PluginPageManager {
                     throw failure('PLUGIN_PAGE_TARGET_CHANGED', 'Nested plugin must use the inherited document');
                 if (!matchesPluginPageURL(runtime.matches, target.url))
                     throw failure('PLUGIN_PAGE_URL_NOT_ALLOWED', 'Plugin page URL is outside its declared matches');
+                if (target.url.startsWith('file:')) {
+                    const file = fileURLToPath(target.url);
+                    const directory = keyedDir(join('plugin-previews', plugin));
+                    if (dirname(file) !== directory ||
+                        !lstatSync(directory, { throwIfNoEntry: false })?.isDirectory() ||
+                        !lstatSync(file, { throwIfNoEntry: false })?.isFile())
+                        throw failure('PLUGIN_PAGE_URL_NOT_ALLOWED', 'Local preview must be a regular file in the plugin preview directory');
+                }
                 const existing = [...this.instances.values()].find(item => item.value.state === 'active' &&
                     item.value.plugin === plugin &&
                     sameTarget(item.value.target, target));
@@ -781,7 +791,7 @@ export class PluginPageManager {
         try {
             await this.validate(record);
             const binding = record.runtime.events[delivery.name];
-            const started = this.start(record, binding.command, { event: { name: delivery.name, payload: delivery.payload, sequence: delivery.sequence } }, `page:${record.value.instanceId}:${delivery.sequence}`);
+            const started = this.start(record, binding.command, { event: { name: delivery.name, payload: delivery.payload, sequence: delivery.sequence } }, `page:${record.value.instanceId}:${delivery.sequence}`, undefined, binding.executionTimeoutMs);
             delivery.taskId = started.taskId;
             this.append(record, {
                 type: 'running',
@@ -813,7 +823,7 @@ export class PluginPageManager {
             });
         }
     }
-    start(record, command, input, key, parentIdentity) {
+    start(record, command, input, key, parentIdentity, executionTimeoutMs) {
         // The runtime delegates through the instance's current connection. Its identity follows
         // that connection so binding cannot replace the connection with this forwarding proxy.
         const bridge = {
@@ -838,6 +848,7 @@ export class PluginPageManager {
             environment: record.execution.environment,
             options: record.options,
             idempotencyKey: key,
+            executionTimeoutMs,
         }, bridge, {
             ...(parentIdentity?.taskId ? { parentTaskId: parentIdentity.taskId, parentIdentity } : {}),
             revision: record.revision,

package/dist/plugins/sdk/plugin.d.ts

@@ -1,3 +1,4 @@
+import type { CommandRunner } from '@mearl/daemon-core';
 import type { PluginTaskRecoveryDeclaration, PluginTaskCheckpoint, PluginCheckpointMigrationInput } from '@mearl/browser-core';
 import type { PluginStateDeclaration } from '@mearl/browser-core';
 import type { PluginModelRequest, PluginModelResult } from '@mearl/browser-core';
@@ -71,6 +72,9 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'opti
     onInvocation?: (identity: PluginInvocationIdentity | undefined) => void;
 }, pluginName?: string): Promise<{
     name: string | undefined;
+    setup: ((context: {
+        runCommand: CommandRunner;
+    }) => unknown | Promise<unknown>) | undefined;
     description: string | undefined;
     defaultCommand: string | undefined;
     toolbox: PluginToolboxContribution | undefined;
@@ -90,6 +94,9 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'opti
 }>;
 export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
+    setup: ((context: {
+        runCommand: CommandRunner;
+    }) => unknown | Promise<unknown>) | undefined;
     description: string | undefined;
     defaultCommand: string | undefined;
     toolbox: PluginToolboxContribution | undefined;

package/dist/plugins/sdk/plugin.js

@@ -153,6 +153,7 @@ export async function loadPlugin(entry, context, pluginName) {
     let taskRecovery;
     let appProfiles;
     let profileSources;
+    let setup;
     const registerCommand = (signature, handler, description = '', examples = [], toolboxOnly = false, runtimeOnly = false) => {
         if (!registering)
             throw new Error('命令只能在入口注册阶段声明');
@@ -313,6 +314,9 @@ export async function loadPlugin(entry, context, pluginName) {
             if (module.description !== undefined && typeof module.description !== 'string')
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
+            if (module.setup !== undefined && typeof module.setup !== 'function')
+                throw new Error('入口的 setup 导出必须为函数');
+            setup = module.setup;
             if (module.defaultCommand !== undefined && typeof module.defaultCommand !== 'string')
                 throw new Error('入口的 defaultCommand 导出必须为字符串');
             defaultCommand = module.defaultCommand;
@@ -535,6 +539,7 @@ export async function loadPlugin(entry, context, pluginName) {
     };
     return {
         name,
+        setup,
         description,
         defaultCommand,
         toolbox,

package/dist/plugins/sdk/pluginPageDefinition.js

@@ -37,6 +37,8 @@ export function normalizePluginPageRuntime(value) {
                 (!Number.isSafeInteger(event.maxPending) ||
                     event.maxPending < 1 ||
                     event.maxPending > 64)) ||
+            (event.executionTimeoutMs !== undefined &&
+                (!Number.isSafeInteger(event.executionTimeoutMs) || event.executionTimeoutMs < 1 || event.executionTimeoutMs > 300000)) ||
             event.schema.$async)
             throw new Error(`Invalid page event binding: ${name}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "3.0.0-beta.8",
+  "version": "3.0.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -47,6 +47,7 @@
     "mearl": "./dist/bin.js"
   },
   "files": [
+    "README.en.md",
     "dist",
     "!dist/**/*.map"
   ],
@@ -67,11 +68,11 @@
     "commander": "^14.0.3",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "3.0.0-beta.8",
-    "@mearl/cloud-types": "3.0.0-beta.8",
-    "@mearl/provider": "3.0.0-beta.8",
-    "@mearl/agent-runtime": "3.0.0-beta.8",
-    "@mearl/browser-core": "3.0.0-beta.8"
+    "@mearl/daemon-core": "3.0.0",
+    "@mearl/cloud-types": "3.0.0",
+    "@mearl/browser-core": "3.0.0",
+    "@mearl/agent-runtime": "3.0.0",
+    "@mearl/provider": "3.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",