@mearl/setup 2.6.0 → 2.7.0

package/README.md

@@ -17,6 +17,10 @@ npx @mearl/setup agentbay
 无交互环境可使用 `--stdin` 或 `--key-file <path>`。为避免 Key 进入 shell history 和
 进程参数，不接受把 Key 直接写在命令行中。
 
+Qoder Cloud Agent 仅在常规云连接失败、Mearl Skill 进入 Qoder 异常接管分支时使用
+`npx @mearl/setup qoder --yes` 生成一次性配对指令。它不安装额外隧道，也不会把 Qoder
+PAT 写入配对 URL；正常安装和连接流程无需执行该命令。
+
 ## 行为
 
 - `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
@@ -33,6 +37,8 @@ npx @mearl/setup agentbay
 - local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
 - 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
 - local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。
+- 安装始终通过 `ali-skills add` 写入最新的全局 mearl skill，并关联当前检测到的 Agent；
+  可用 `--skip-skill` 跳过。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
 
@@ -67,13 +73,13 @@ npx @mearl/setup
 npx @mearl/setup install
 
 # Agent / CI 无交互安装
-npx @mearl/setup install --yes
+npx @mearl/setup --yes
 
 # 安装云端 Agent 环境
-npx @mearl/setup install --cloud
+npx @mearl/setup --cloud
 
 # 同一台机器同时作为本地浏览器宿主和云端 Agent
-npx @mearl/setup install --local --cloud
+npx @mearl/setup --local --cloud
 
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
 npx @mearl/setup update

package/dist/aliSkills.js

@@ -163,15 +163,7 @@ export async function runGlobalMearlSkillOperation(operation, options = {}) {
             return null;
         }
     };
-    const paths = await listMearlPaths();
-    if (!paths)
-        return false;
     if (operation === 'install') {
-        if (paths.length > 0) {
-            writeLine('Skill: already installed:');
-            paths.forEach(skillPath => writeLine(`  ${skillPath}`));
-            return true;
-        }
         const installed = await run(['add', 'trip/mearl', '--skill', 'mearl', '--global', ...(options.yes ? ['--yes'] : [])], false);
         if (!installed)
             return false;
@@ -187,6 +179,9 @@ export async function runGlobalMearlSkillOperation(operation, options = {}) {
         writeLine('Skill: installed.');
         return true;
     }
+    const paths = await listMearlPaths();
+    if (!paths)
+        return false;
     if (paths.length === 0) {
         writeLine('Skill: no tracked global mearl skill found; skipped.');
         return true;

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+process.exitCode = await main();

package/dist/cli.d.ts

@@ -2,12 +2,13 @@
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin } from './agentBay.js';
 import { type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
+import { createQoderPairingInfo } from './qoder.js';
 export declare const SETUP_VERSION: string;
 interface ParsedArgs {
     agentBayKeyFile?: string;
     agentBayReadStdin: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation | 'agentbay';
+    operation?: MearlLifecycleOperation | 'agentbay' | 'qoder';
     profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
@@ -19,6 +20,7 @@ export interface SetupCliDependencies {
     promptAgentBayKey?: typeof promptAgentBayApiKey;
     readAgentBayKeyFile?: typeof readAgentBayApiKeyFile;
     readAgentBayKeyStdin?: typeof readAgentBayApiKeyStdin;
+    createQoderPairing?: typeof createQoderPairingInfo;
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;
 export declare function main(argv?: string[], interactiveTerminal?: boolean, dependencies?: SetupCliDependencies): Promise<number>;

package/dist/cli.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-import path from 'node:path';
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 import { runMearlLifecycle } from './lifecycle.js';
+import { createQoderPairingInfo, formatQoderPairingOutput } from './qoder.js';
 import { isMearlReleaseLine } from './version.js';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
@@ -54,6 +53,20 @@ export function parseSetupArgs(argv) {
         }
         throw new Error('Usage: npx @mearl/setup agentbay [--stdin | --key-file <path>]. API keys are not accepted as command-line arguments.');
     }
+    if (operation === 'qoder') {
+        const options = argv.slice(1);
+        const allowed = new Set(['--yes', '-y', '--non-interactive']);
+        if (options.some(option => !allowed.has(option))) {
+            throw new Error('Usage: npx @mearl/setup qoder [--yes]');
+        }
+        return {
+            agentBayReadStdin: false,
+            help: false,
+            operation,
+            skipSkill: false,
+            yes: options.length > 0,
+        };
+    }
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
@@ -112,12 +125,14 @@ Usage:
   npx @mearl/setup [install] [--local] [--cloud] [--mcp] [--yes]
   npx @mearl/setup <update|uninstall> [--local] [--cloud] [--mcp] [--yes]
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
+  npx @mearl/setup qoder [--yes]
 
 Behavior:
   install      Default command; defaults to --local when no environment is specified
   update       Auto-detects installed environments from the current PATH
   uninstall    Auto-detects installed environments and asks for confirmation
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
+  qoder        Create a Qoder client-side tool pairing request for troubleshooting
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
@@ -139,11 +154,11 @@ Examples:
   npx @mearl/setup
   npx @mearl/setup --yes
   npx @mearl/setup install
-  npx @mearl/setup install --yes
-  npx @mearl/setup install --cloud
-  npx @mearl/setup install --local --cloud
+  npx @mearl/setup --cloud
+  npx @mearl/setup --local --cloud
   npx @mearl/setup update
   npx @mearl/setup agentbay
+  npx @mearl/setup qoder --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
   npx @mearl/setup uninstall --local`;
     if (toError)
@@ -194,6 +209,17 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             return 1;
         }
     }
+    if (parsed.operation === 'qoder') {
+        try {
+            const pairing = (dependencies.createQoderPairing ?? createQoderPairingInfo)();
+            console.log(formatQoderPairingOutput(pairing));
+            return 0;
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     if (!interactiveTerminal && !parsed.yes && parsed.operation !== 'update') {
         console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');
         return 2;
@@ -213,7 +239,3 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         return 1;
     }
 }
-const currentFile = fileURLToPath(import.meta.url);
-if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) {
-    process.exitCode = await main();
-}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 export type { AgentBayConfigurationOptions, AgentBayConfigurationResult, AgentBaySecretInput, AgentBaySecretOutput, } from './agentBay.js';
+export { createQoderPairingInfo, formatQoderPairingOutput } from './qoder.js';
+export type { QoderPairingInfo, QoderPairingOptions } from './qoder.js';
 export type { DetectedGlobalPackage, GlobalPackageCommand, GlobalPackageManager, PackageManagerInstallation, PackageOperation, PackageDetectionOptions, } from './packageManager.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export type { MearlLifecycleDependencies, MearlLifecycleOperation, MearlLifecycleOptions, } from './lifecycle.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
+export { createQoderPairingInfo, formatQoderPairingOutput } from './qoder.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';

package/dist/lifecycle.js

@@ -150,7 +150,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         writeLine('No installed Mearl environment was detected on the current PATH.');
         if (options.operation === 'uninstall')
             return true;
-        writeLine('Run: npx @mearl/setup install');
+        writeLine('Run: npx @mearl/setup');
         return false;
     }
     if (options.operation === 'update') {

package/dist/qoder.d.ts

@@ -0,0 +1,18 @@
+export interface QoderPairingInfo {
+    pairingCode: string;
+    createdAt: number;
+    connectorUrl: string;
+    toolInput: {
+        action: 'pair';
+        payload: {
+            code: string;
+        };
+    };
+}
+export interface QoderPairingOptions {
+    now?: () => number;
+    createCode?: () => string;
+}
+/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
+export declare function createQoderPairingInfo(options?: QoderPairingOptions): QoderPairingInfo;
+export declare function formatQoderPairingOutput(info: QoderPairingInfo): string;

package/dist/qoder.js

@@ -0,0 +1,32 @@
+import { randomBytes } from 'node:crypto';
+/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
+export function createQoderPairingInfo(options = {}) {
+    const pairingCode = (options.createCode ?? (() => randomBytes(24).toString('base64url')))();
+    if (!/^[A-Za-z0-9_-]{16,128}$/.test(pairingCode)) {
+        throw new Error('Qoder pairing code must be 16-128 URL-safe characters');
+    }
+    const createdAt = (options.now ?? Date.now)();
+    if (!Number.isSafeInteger(createdAt) ||
+        createdAt < 1_000_000_000_000 ||
+        createdAt > 9_999_999_999_999) {
+        throw new Error('Qoder pairing timestamp must be a 13-digit epoch millisecond value');
+    }
+    return {
+        pairingCode,
+        createdAt,
+        connectorUrl: `qoder://pair/${pairingCode}?created=${createdAt}`,
+        toolInput: { action: 'pair', payload: { code: pairingCode } },
+    };
+}
+export function formatQoderPairingOutput(info) {
+    const connectorCommand = `npx @mearl/cloud-connector "${info.connectorUrl}"`;
+    return `[Qoder] Mearl local-browser pairing is ready.
+
+Show the user this command and ask them to run it on the computer that owns the browser:
+  ${connectorCommand}
+
+Then immediately invoke the Qoder client-side custom tool named "mearl" with this input:
+  ${JSON.stringify(info.toolInput)}
+
+The connector reads QODER_PERSONAL_ACCESS_TOKEN from the local environment. Never add the PAT to the pairing URL.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -30,13 +30,17 @@
       "types": "./dist/agentBay.d.ts",
       "import": "./dist/agentBay.js"
     },
+    "./qoder": {
+      "types": "./dist/qoder.d.ts",
+      "import": "./dist/qoder.js"
+    },
     "./version": {
       "types": "./dist/version.d.ts",
       "import": "./dist/version.js"
     }
   },
   "bin": {
-    "mearl-setup": "./dist/cli.js"
+    "mearl-setup": "./dist/bin.js"
   },
   "files": [
     "dist",
@@ -58,7 +62,7 @@
     "typescript": "^5.8.3"
   },
   "scripts": {
-    "build": "rm -rf dist/ && tsc && chmod +x dist/cli.js",
+    "build": "rm -rf dist/ && tsc && chmod +x dist/bin.js",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"