@justlovepl/desktop-bridge 0.0.0-stage → 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Desktop Bridge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Desktop Bridge npm CLI
+
+Independent npm distribution for the Desktop Bridge **local device client**. It does not publish the upstream Desktop Commander package or cloud relay.
+
+Version 0.2.7 adds Windows Task Scheduler background management. npm remains the installation, upgrade and control entry point. **0.2.7 is currently a release candidate; public npm publication is pending the publisher account's one-time-password verification.**
+
+Requires Node.js 24 and npm. Native installers for computers without Node remain available at <https://mcp.ilovestudy.de/start.html>.
+
+```sh
+npm install -g @justlovepl/desktop-bridge
+desktop-bridge setup               # default: background, login startup enabled
+desktop-bridge setup --mode manual # explicitly choose foreground/manual operation
+desktop-bridge status
+desktop-bridge start
+desktop-bridge stop
+desktop-bridge restart
+desktop-bridge pair                # explicitly request browser approval
+desktop-bridge mode manual
+desktop-bridge mode background
+desktop-bridge repair              # repairs AND re-pairs in the browser
+desktop-bridge uninstall           # preserves credentials/results unless --purge
+```
+
+**Installing the npm CLI does not start a service.** Run `desktop-bridge setup` to install/pair the client and select background operation by default. Use `--mode manual` for foreground operation; `--no-start` also selects manual mode. The native installers still ask the user to select a mode explicitly.
+
+On Windows, background mode registers a Task Scheduler task for the current user with limited privileges, starts it independently of the terminal/SSH session, and starts it again on user login. The task has no runtime time limit, allows battery operation, and restarts on failures. This mode requires that user to be logged into Windows; running before login is the separate administrator service option. `stop` leaves the task registered but stops the client; `start` resumes it; `mode manual` and `uninstall` remove it. An update migrates the old login shortcut to the managed task while preserving pairing and the saved mode.
+
+`--administrator` requires explicit OS authorization and respects the existing protected service restrictions. `--root <directory>` selects a dedicated custom data directory. **There is no install/start action in npm postinstall**.
+
+`desktop-bridge uninstall --purge` permanently deletes local credentials and result journals. Uninstalling locally does not revoke the server token; use device management at <https://mcp.ilovestudy.de/start.html> to revoke device authorization. Existing administrator service installations require the protected service's own approved uninstall flow.
+
+Update the npm CLI and then apply the local client release:
+
+```sh
+desktop-bridge update
+```
+
+`npm update` alone does not replace an already running agent. `desktop-bridge update` upgrades the CLI and Agent while explicitly passing the existing saved mode, with credential, mode, and task journal protection. It refuses to install a CLI older than the current version. `repair` also preserves the saved mode, but deliberately requires browser re-pairing approval. A revoked device always requires explicit new pairing.
+
+## Packaging / tests
+
+The npm package lives in `npm-installer/`, distinct from the root upstream `package.json` and `bridge/client/package.json`. Packing stages files from an explicit allowlist in `bridge/client/` and `bridge/agent/`; no cloud server, installed user data or secret credentials enter the package.
+
+```sh
+cd npm-installer
+npm test
+npm pack --dry-run
+```
+
+Review the resulting npm tarball and run real setup/stop/re-pair/update/uninstall tests on Windows, macOS and Linux before first publication. **Never run npm publish from the repository root or bridge/client directory.**

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third-party components
+
+Desktop Bridge uses Desktop Commander MCP as its local tool engine. The currently deployed engine is `@wonderwhy-er/desktop-commander` version `0.3.0`, already pinned on p111. The original Remote client and official hosted backend are not used by this bridge's connection.
+
+Upstream: https://github.com/wonderwhy-er/DesktopCommanderMCP
+
+Desktop Commander MCP is MIT licensed:
+
+Copyright (c) 2024-2025 Eduard Ruzga and Desktop Commander Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The bridge also depends on the official MCP TypeScript SDK, Express, express-rate-limit, and ws. Their licenses are included in their installed npm packages and remain applicable. `package-lock.json` pins the relay dependencies.
+
+## NES.css
+
+The administration page uses [NES.css](https://github.com/nostalgic-css/NES.css), version 2.3.0, for 8-bit UI components. NES.css is distributed under the MIT License. The unmodified stylesheet and complete license text are stored at `public/vendor/nes.css/nes.min.css` and `public/vendor/nes.css/LICENSE`; there is no third-party CSS or font request at runtime.

package/bin/desktop-bridge.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/** CLI does not start a service during npm install; explicit setup is required. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {performUpdate} from './update.mjs';
+
+const packageRoot=fileURLToPath(new URL('../',import.meta.url));
+const clientRoot=path.join(packageRoot,'dist','client');
+const installer=path.join(clientRoot,'install.mjs');
+const controller=path.join(clientRoot,'control.mjs');
+const manifest=JSON.parse(fs.readFileSync(path.join(packageRoot,'package.json'),'utf8'));
+const commands=new Set(['setup','start','stop','restart','status','pair','mode','repair','uninstall','update']);
+
+export function clientDataRoot(platform=process.platform,env=process.env,home=os.homedir()){
+  return platform==='win32'?path.win32.join(env.LOCALAPPDATA??path.win32.join(home,'AppData','Local'),'DesktopBridgeClient')
+    :platform==='darwin'?path.posix.join(home,'Library','Application Support','DesktopBridge')
+      :path.posix.join(env.XDG_DATA_HOME??path.posix.join(home,'.local','share'),'desktop-bridge');
+}
+
+export function parse(argv){
+  const [command='help',...args]=argv;
+  if(['help','--help','-h'].includes(command))return {command:'help'};
+  if(['version','--version','-v'].includes(command))return {command:'version'};
+  if(!commands.has(command))throw new Error('Unknown command: '+command);
+  let customRoot;
+  const remainder=[];
+  for(let i=0;i<args.length;i++){
+    if(args[i]==='--root'){
+      const value=args[++i];
+      if(!value||value.startsWith('--')||customRoot)throw new Error('--root requires exactly one directory');
+      customRoot=path.resolve(value);
+    }else remainder.push(args[i]);
+  }
+  const control=['start','stop','status','pair','mode','restart'].includes(command);
+  if(control){
+    if(command==='mode'){
+      if(remainder.length!==1||!['manual','background'].includes(remainder[0]))throw new Error('Usage: desktop-bridge mode manual|background');
+    }else if(remainder.length)throw new Error(command+' does not accept extra arguments');
+  }else if(command==='uninstall'){
+    if(remainder.some(x=>x!=='--purge')||remainder.filter(x=>x==='--purge').length>1)throw new Error('Usage: desktop-bridge uninstall [--purge]');
+  }else if(command==='repair'||command==='update'){
+    if(remainder.length)throw new Error('Usage: desktop-bridge '+command+' [--root directory]');
+  }else{
+    for(let i=0;i<remainder.length;i++){
+      const a=remainder[i];
+      if(a==='--mode'){
+        if(!['manual','background'].includes(remainder[++i]))throw new Error('Use --mode manual or --mode background');
+      }else if(!['--administrator','--no-browser','--no-start'].includes(a))throw new Error('Unknown setup option: '+a);
+    }
+  }
+  if(command==='setup'&&!remainder.includes('--mode')&&!remainder.includes('--no-start'))remainder.push('--mode','background');
+  return {command,args:remainder,root:customRoot};
+}
+
+function usage(){
+  return 'Desktop Bridge '+manifest.version+'\n\n'+
+    'Usage: desktop-bridge <command> [options]\n\n'+
+    '  setup [--mode manual|background] [--administrator]  Install and pair (default: background)\n'+
+    '  start | stop | restart                           Manage local agent\n'+
+    '  status                                           Show local connection status\n'+
+    '  pair                                             Re-pair in your browser\n'+
+    '  mode manual|background                           Change startup mode\n'+
+    '  repair                                           Repair (re-pairs in browser)\n'+
+    '  update                                           Update npm CLI and installed Agent\n'+
+    '  uninstall [--purge]                              Remove local agent\n'+
+    '  version | help                                   Show CLI info\n\n'+
+    'All commands except help/version accept --root <directory>.\n'+
+    'No service is installed automatically by npm install.\n'+
+    'update upgrades the npm CLI and applies its client release while preserving pairing.\n'+
+    'Device unlink/revocation: https://mcp.ilovestudy.de/start.html\n';
+}
+
+async function childRun(script,args){
+  if(!fs.existsSync(script))throw new Error('Packaged client is missing. Reinstall the npm package.');
+  const child=spawn(process.execPath,[script,...args],{stdio:'inherit',windowsHide:false});
+  return await new Promise((resolve,reject)=>{
+    child.once('error',reject);
+    child.once('exit',(code,signal)=>resolve(signal?128:code??1));
+  });
+}
+
+export async function main(argv=process.argv.slice(2)){
+  const parsed=parse(argv);
+  if(parsed.command==='help'){console.log(usage());return 0;}
+  if(parsed.command==='version'){console.log(manifest.version);return 0;}
+  if(Number(process.versions.node.split('.')[0])!==24)throw new Error('Desktop Bridge needs Node.js 24. Install Node.js 24 before using this CLI.');
+  const root=parsed.root??clientDataRoot();
+  const rootArgs=parsed.root?['--root',root]:[];
+  if(parsed.command==='setup')return childRun(installer,[...parsed.args,...rootArgs]);
+  if(!fs.existsSync(path.join(root,'launch.json')))throw new Error('Client is not installed at '+root+'. Run desktop-bridge setup first.');
+  if(parsed.command==='update')return performUpdate({root,packageRoot,packageName:manifest.name});
+  if(parsed.command==='repair'){
+    console.log('Repair also requires browser re-pairing approval.');
+    const {savedMode}=await import('../dist/client/install-options.mjs');
+    const mode=savedMode(root);
+    if(!mode)throw new Error('Cannot identify saved startup mode. Run setup --mode manual|background.');
+    return childRun(installer,['--repair','--mode',mode,...rootArgs]);
+  }
+  if(parsed.command==='uninstall'){
+    const status=await childRun(installer,['--uninstall',...parsed.args,...rootArgs]);
+    if(status===0)console.log('To also remove the npm CLI: npm uninstall -g '+manifest.name);
+    return status;
+  }
+  if(parsed.command==='restart'){
+    const status=await childRun(controller,['stop',...rootArgs]);
+    return status===0?childRun(controller,['start',...rootArgs]):status;
+  }
+  return childRun(controller,[parsed.command,...parsed.args,...rootArgs]);
+}
+if(process.argv[1]&&fs.realpathSync(path.resolve(process.argv[1]))===fs.realpathSync(fileURLToPath(import.meta.url))){
+  main().then(code=>{process.exitCode=code;},error=>{
+    console.error('Desktop Bridge:',error.message);
+    process.exitCode=1;
+  });
+}

package/bin/update.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+
+/**
+ * Upgrade npm CLI first, then let the NEW package's installer update the
+ * separate per-user client runtime. Credentials stay in the user data root.
+ */
+export function findNpmCli({node=process.execPath,env=process.env}={}){
+  const bin=path.dirname(node);
+  const candidates=[
+    env.npm_execpath,
+    path.join(bin,'node_modules','npm','bin','npm-cli.js'),
+    path.resolve(bin,'../lib/node_modules/npm/bin/npm-cli.js')
+  ];
+  const found=candidates.find(p=>p&&path.basename(p)==='npm-cli.js'&&fs.existsSync(p));
+  if(!found)throw new Error('Cannot locate npm-cli.js. Install npm alongside Node.js 24 or run npm update -g manually.');
+  return found;
+}
+
+export async function runProcess(executable,args){
+  const child=spawn(executable,args,{stdio:'inherit',windowsHide:false});
+  return await new Promise((resolve,reject)=>{
+    child.once('error',reject);
+    child.once('exit',(code,signal)=>resolve(signal?128:code??1));
+  });
+}
+
+function readJson(file){
+  try{return JSON.parse(fs.readFileSync(file,'utf8'));}
+  catch{throw new Error('Cannot read valid JSON from '+path.basename(file));}
+}
+const identityFields=['deviceToken','deviceId','serverUrl','userId','accountId','ownerId','tenantId','deviceName','accountHint'];
+function getIdentity(config){
+  return Object.fromEntries(identityFields.filter(name=>Object.hasOwn(config,name)).map(name=>[name,config[name]]));
+}
+
+export async function performUpdate({
+  root,packageRoot,packageName='@justlovepl/desktop-bridge',
+  npmScript,execute=runProcess,print=message=>console.log(message)
+}){
+  const installed=path.join(root,'launch.json');
+  if(!fs.existsSync(installed))throw new Error('Local client not installed. Run desktop-bridge setup before updating.');
+  if(path.resolve(root)===path.resolve(packageRoot)||path.resolve(packageRoot).startsWith(path.resolve(root)+path.sep))
+    throw new Error('Client data directory must not contain the npm package.');
+  const configFile=path.join(root,'agent-config.json');
+  const settingsFile=path.join(root,'client-settings.json');
+  const config=readJson(configFile),settings=readJson(settingsFile);
+  if(!config.deviceId||!config.deviceToken)throw new Error('Device is not paired. Run desktop-bridge pair before updating.');
+  if(!['manual','background'].includes(settings.mode))
+    throw new Error('Cannot identify saved startup mode; refusing an update that might change it.');
+  if(fs.existsSync(path.join(root,'auth-status.json'))&&readJson(path.join(root,'auth-status.json')).authStatus==='re_pair_required')
+    throw new Error('Device authorization is revoked. Re-pair it before updating.');
+  const previousIdentity=getIdentity(config);
+  const previousMode=settings.mode;
+  const previousPrivilege=settings.privilege??'standard';
+  const journalFile=path.join(root,'journal.json');
+  const oldJournal=fs.existsSync(journalFile)?readJson(journalFile):null;
+  const installedPackage=readJson(path.join(packageRoot,'package.json'));
+  if(!/^\d+\.\d+\.\d+$/.test(installedPackage.version))throw new Error('Unsupported CLI version; refusing an unsafe update.');
+  const npmCli=npmScript??findNpmCli();
+  print('Updating npm CLI (device credentials and configuration are kept outside npm)...');
+  // A locally tested newer build must not silently downgrade to an older
+  // published client. npm resolves the newest matching stable release.
+  const npmStatus=await execute(process.execPath,[npmCli,'install','--global','--no-audit','--no-fund',packageName+'@>='+installedPackage.version]);
+  if(npmStatus!==0)throw new Error('npm package update failed; local client was not reinstalled.');
+  const packageFile=path.join(packageRoot,'package.json');
+  const current=readJson(packageFile);
+  if(current.name!==packageName)throw new Error('Updated npm package identity is unexpected. Client was not modified.');
+  const newEntry=path.join(packageRoot,'bin','desktop-bridge.mjs');
+  if(!fs.existsSync(newEntry))throw new Error('Updated CLI entry missing; local client was not modified.');
+  print('npm CLI updated to '+current.version+'. Upgrading local Agent in '+previousMode+' mode...');
+  // The new package's installer reuses an existing approved device token.
+  // --no-browser means routine upgrades must not open an unsolicited login tab.
+  const installStatus=await execute(process.execPath,[
+    newEntry,'setup','--mode',previousMode,'--no-browser','--root',root
+  ]);
+  if(installStatus!==0)throw new Error('Agent update failed; do not manually erase device data. Check status and retry or repair.');
+  const updatedConfig=readJson(configFile);
+  for(const [key,value] of Object.entries(previousIdentity)){
+    if(updatedConfig[key]!==value)
+      throw new Error('Authorization or account binding changed during upgrade ('+key+'). Do not restore revoked tokens; check account and re-pair if needed.');
+  }
+  const updatedSettings=readJson(settingsFile);
+  if(updatedSettings.mode!==previousMode||(updatedSettings.privilege??'standard')!==previousPrivilege)
+    throw new Error('Startup mode or privilege changed unexpectedly during upgrade. Inspect settings before restarting.');
+  if(oldJournal){
+    const updatedJournal=readJson(journalFile);
+    for(const [id,entry] of Object.entries(oldJournal)){
+      if(entry?.status==='completed'&&(!entry.time||Date.now()-entry.time<30*86400000)&&!Object.hasOwn(updatedJournal,id))
+        throw new Error('Recent completed task journal entry missing after upgrade: '+id);
+    }
+  }
+  print('Update complete: npm CLI '+current.version+', device identity and '+previousMode+' startup mode preserved.');
+  return 0;
+}

package/dist/client/Install.cmd

@@ -0,0 +1,3 @@
+@echo off
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" %*
+if errorlevel 1 pause

package/dist/client/Install.command

@@ -0,0 +1,3 @@
+#!/bin/sh
+SOURCE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec /bin/sh "$SOURCE/Install.sh" "$@"

package/dist/client/Install.sh

@@ -0,0 +1,137 @@
+#!/bin/sh
+set -eu
+umask 077
+fail() { echo "$*" >&2; exit 1; }
+# Validate portable options before downloading or changing the local installation.
+NEXT=''; DATA_ROOT=''; MODE=''; NO_START=0; STOP=0; UNINSTALL=0; PURGE=0
+for ARG in "$@"; do
+ if [ -n "$NEXT" ]; then
+  case "$ARG" in ''|--*) fail "$NEXT 缺少参数值。";; esac
+  if [ "$NEXT" = --root ]; then DATA_ROOT="$ARG"
+  else
+   case "$ARG" in manual|background) ;; *) fail '--mode 只能是 manual 或 background。';; esac
+   [ -z "$MODE" ] || [ "$MODE" = "$ARG" ] || fail '不能同时指定不同的 --mode。'
+   MODE="$ARG"
+  fi
+  NEXT=''
+ else
+  case "$ARG" in
+   --root|--mode) NEXT="$ARG";;
+   --no-start) NO_START=1;; --stop) STOP=1;; --uninstall) UNINSTALL=1;; --purge) PURGE=1;;
+   --repair|--no-browser) ;; *) fail "未知参数：$ARG";;
+  esac
+ fi
+done
+[ -z "$NEXT" ] || fail "$NEXT 缺少参数值。"
+[ "$NO_START:$MODE" != 1:background ] || fail '--no-start 不能与 --mode background 同时使用。'
+[ "$STOP:$UNINSTALL" != 1:1 ] || fail '--stop 不能与 --uninstall 同时使用。'
+[ "$PURGE:$UNINSTALL" != 1:0 ] || fail '--purge 必须与 --uninstall 一起使用。'
+for TOOL in uname dirname; do command -v "$TOOL" >/dev/null 2>&1 || fail "缺少基础工具 $TOOL，无法识别安装环境。"; done
+SOURCE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+case "$(uname -s)" in Darwin) PLATFORM=darwin;; Linux) PLATFORM=linux;; *) fail '支持的系统：macOS 和 Linux。';; esac
+case "$(uname -m)" in x86_64|amd64) ARCH=x64;; arm64|aarch64) ARCH=arm64;; *) fail '支持的处理器：x64 和 ARM64。';; esac
+VERSION=24.19.0
+if [ -z "$DATA_ROOT" ]; then
+ if [ "$PLATFORM" = darwin ]; then DATA_ROOT="$HOME/Library/Application Support/DesktopBridge"; else DATA_ROOT="${XDG_DATA_HOME:-$HOME/.local/share}/desktop-bridge"; fi
+fi
+LOCAL_RUNTIME="$DATA_ROOT/runtime/node-v$VERSION-$PLATFORM-$ARCH"
+LOCAL_NODE="$LOCAL_RUNTIME/bin/node"
+LOCAL_NPM="$LOCAL_RUNTIME/lib/node_modules/npm/bin/npm-cli.js"
+if [ -x "$LOCAL_NODE" ] && [ -f "$LOCAL_NPM" ]; then
+ if NODE_VERSION=$("$LOCAL_NODE" --version 2>/dev/null) && [ "$NODE_VERSION" = "v$VERSION" ] && NPM_VERSION=$("$LOCAL_NODE" "$LOCAL_NPM" --version 2>/dev/null) && [ -n "$NPM_VERSION" ]; then
+  exec "$LOCAL_NODE" "$SOURCE/install.mjs" "$@"
+ fi
+fi
+[ ! -e "$LOCAL_RUNTIME" ] || echo '私有 Node 或 npm 无法正常运行，将下载校验后的官方环境进行修复。' >&2
+# Discover every required fallback before beginning a network request.
+for TOOL in mktemp rm chmod; do command -v "$TOOL" >/dev/null 2>&1 || fail "缺少基础工具 $TOOL，无法创建和清理私有临时目录。"; done
+PYTHON=''
+if command -v python3 >/dev/null 2>&1 && python3 -c 'import sys; assert sys.version_info >= (3, 8); import urllib.request, ssl, hashlib, tarfile' >/dev/null 2>&1; then PYTHON=python3; fi
+if command -v curl >/dev/null 2>&1; then DOWNLOADER=curl
+elif command -v wget >/dev/null 2>&1; then DOWNLOADER=wget
+elif [ -n "$PYTHON" ]; then DOWNLOADER=python
+else fail '缺少可用下载环境：需要 curl、wget 或 Python 3（含 HTTPS 标准库）。'; fi
+if command -v sha256sum >/dev/null 2>&1; then HASHER=sha256sum
+elif command -v shasum >/dev/null 2>&1; then HASHER=shasum
+elif [ -n "$PYTHON" ]; then HASHER=python
+else fail '缺少 SHA-256 校验环境：需要 sha256sum、shasum 或 Python 3。'; fi
+if command -v tar >/dev/null 2>&1 && { [ "$PLATFORM" = darwin ] || command -v gzip >/dev/null 2>&1; }; then EXTRACTOR=tar
+elif [ -n "$PYTHON" ]; then EXTRACTOR=python
+else fail '缺少解压环境：需要 tar（Linux 同时需要 gzip）或 Python 3；尚未开始下载。'; fi
+case "$PLATFORM-$ARCH" in
+ darwin-x64) HASH=d1b5e999db158c62fe8f7267a4476b035d8bd93b1a605bac24a3f0dd166e3316;;
+ darwin-arm64) HASH=8294b7aa9b03997481c06babf1e8b270c859358f27da57a11509afe537ac381d;;
+ linux-x64) HASH=f625d97cd707df4ff96254916fbc5ff014f09c09effe5a1e0ca8f6d41a8789d4;;
+ linux-arm64) HASH=d28c8a5bf0a808f0ed434a1dce8c54ae98f0371c0bd86ac58abc613f73e6643f;;
+esac
+# Bootstrap only in a private directory. install.mjs owns the durable installation.
+TEMP=$(mktemp -d "${TMPDIR:-/tmp}/desktop-bridge.XXXXXXXX") || fail '无法创建私有临时目录，请检查临时目录的写入权限。'
+trap 'rm -rf "$TEMP"' 0
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+chmod 700 "$TEMP" || fail '无法保护临时目录权限。'
+FILE="node-v$VERSION-$PLATFORM-$ARCH.tar.gz"
+URL="https://nodejs.org/dist/v$VERSION/$FILE"
+echo '正在准备经过 SHA-256 校验的官方 Node 24.19.0 环境…' >&2
+case "$DOWNLOADER" in
+ curl) curl --fail --location --retry 2 --proto '=https' --proto-redir '=https' --tlsv1.2 "$URL" -o "$TEMP/runtime.tar.gz" || fail '官方环境下载失败，请检查网络、HTTPS 证书或代理设置。';;
+ wget) wget --https-only "$URL" -O "$TEMP/runtime.tar.gz" || fail '官方环境下载失败，请检查网络、HTTPS 证书或代理设置。';;
+ python) python3 - "$URL" "$TEMP/runtime.tar.gz" <<'PY' || fail '官方环境下载失败，请检查网络、HTTPS 证书或代理设置。'
+import shutil, sys, urllib.parse, urllib.request
+class HTTPSOnly(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if urllib.parse.urlparse(newurl).scheme != 'https':
+            raise ValueError('Refusing a non-HTTPS redirect')
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+with urllib.request.build_opener(HTTPSOnly()).open(sys.argv[1], timeout=30) as response, open(sys.argv[2], 'wb') as output:
+    shutil.copyfileobj(response, output)
+PY
+ ;;
+esac
+case "$HASHER" in
+ sha256sum) HASH_OUTPUT=$(sha256sum "$TEMP/runtime.tar.gz") || fail 'SHA-256 校验工具执行失败。'; ACTUAL=${HASH_OUTPUT%% *};;
+ shasum) HASH_OUTPUT=$(shasum -a 256 "$TEMP/runtime.tar.gz") || fail 'SHA-256 校验工具执行失败。'; ACTUAL=${HASH_OUTPUT%% *};;
+ python) ACTUAL=$(python3 - "$TEMP/runtime.tar.gz" <<'PY'
+import hashlib, sys
+value=hashlib.sha256()
+with open(sys.argv[1], 'rb') as source:
+    for block in iter(lambda: source.read(1024*1024), b''):
+        value.update(block)
+print(value.hexdigest())
+PY
+ ) || fail 'Python SHA-256 校验失败。';;
+esac
+[ "$ACTUAL" = "$HASH" ] || fail '官方 Node 环境校验失败（checksum mismatch），已拒绝执行。'
+if [ "$EXTRACTOR" = tar ]; then tar -xzf "$TEMP/runtime.tar.gz" -C "$TEMP" || fail '官方环境解压失败，请检查磁盘空间。'
+else python3 - "$TEMP/runtime.tar.gz" "$TEMP" <<'PY' || fail 'Python 安全解压失败，请检查压缩包和磁盘空间。'
+import os, pathlib, sys, tarfile
+root=os.path.realpath(sys.argv[2])
+def inside(value):
+    return os.path.commonpath((root, os.path.realpath(value))) == root
+with tarfile.open(sys.argv[1], 'r:gz') as archive:
+    for member in archive:
+        parts=pathlib.PurePosixPath(member.name)
+        target=os.path.join(root, member.name)
+        if parts.is_absolute() or '..' in parts.parts or not inside(target):
+            raise ValueError('Unsafe archive path')
+        if member.issym() or member.islnk():
+            link=os.path.join(os.path.dirname(target) if member.issym() else root, member.linkname)
+            if os.path.isabs(member.linkname) or not inside(link):
+                raise ValueError('Unsafe archive link')
+        elif not (member.isfile() or member.isdir()):
+            raise ValueError('Unsupported archive entry')
+        archive.extract(member, root)
+# Recheck links after extracting the complete graph; never execute an escaping link.
+for directory, folders, files in os.walk(root, followlinks=False):
+    for name in folders + files:
+        if not inside(os.path.join(directory, name)):
+            raise ValueError('Unsafe archive link graph')
+PY
+fi
+BOOT_NODE="$TEMP/node-v$VERSION-$PLATFORM-$ARCH/bin/node"
+BOOT_NPM="$TEMP/node-v$VERSION-$PLATFORM-$ARCH/lib/node_modules/npm/bin/npm-cli.js"
+[ -x "$BOOT_NODE" ] && [ -f "$BOOT_NPM" ] || fail '官方环境不完整：缺少 Node 或 npm。'
+NODE_VERSION=$("$BOOT_NODE" --version 2>/dev/null) && [ "$NODE_VERSION" = "v$VERSION" ] || fail '下载的 Node 无法运行或版本不匹配，请检查系统架构和执行权限。'
+NPM_VERSION=$("$BOOT_NODE" "$BOOT_NPM" --version 2>/dev/null) && [ -n "$NPM_VERSION" ] || fail '下载环境中的 npm 无法运行，请重新下载。'
+"$BOOT_NODE" "$SOURCE/install.mjs" "$@"

package/dist/client/Pair-again.cmd

@@ -0,0 +1,3 @@
+@echo off
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" -Repair %*
+if errorlevel 1 pause

package/dist/client/RePair.cmd

@@ -0,0 +1,9 @@
+@echo off
+setlocal DisableDelayedExpansion
+rem Manual re-authorization. The browser must confirm this device again.
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0control.ps1" -Action pair %*
+set "RESULT=%ERRORLEVEL%"
+if not "%RESULT%"=="0" echo Pairing did not finish. Check the error above and retry when ready.
+echo.
+pause
+exit /b %RESULT%

package/dist/client/Start.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal DisableDelayedExpansion
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0control.ps1" -Action start %*
+if errorlevel 1 pause

package/dist/client/Start.command

@@ -0,0 +1,3 @@
+#!/bin/sh
+SOURCE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec /bin/sh "$SOURCE/start.sh" "$@"

package/dist/client/Stop.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal DisableDelayedExpansion
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0control.ps1" -Action stop %*
+if errorlevel 1 pause

package/dist/client/Stop.command

@@ -0,0 +1,3 @@
+#!/bin/sh
+SOURCE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec /bin/sh "$SOURCE/stop.sh" "$@"

package/dist/client/Uninstall.cmd

@@ -0,0 +1,3 @@
+@echo off
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0install.ps1" -Uninstall %*
+if errorlevel 1 pause

package/dist/client/Uninstall.command

@@ -0,0 +1,3 @@
+#!/bin/sh
+SOURCE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec /bin/sh "$SOURCE/Uninstall.sh" "$@"

package/dist/client/Uninstall.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+SOURCE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec /bin/sh "$SOURCE/Install.sh" --uninstall "$@"

package/dist/client/admin-elevate.mjs

@@ -0,0 +1,48 @@
+// The only user-facing elevation helper. Never elevates without a requested action.
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {protectedRoot} from './admin-runtime.mjs';
+const folder=path.dirname(fileURLToPath(import.meta.url));
+export function psQuote(s){return "'"+String(s).replace(/'/g,"''")+"'";}
+export function elevationRequest(action,{source,mode,purge=false,root=protectedRoot(),platform=process.platform}={}) {
+  if(!['install','start','stop','status','mode','uninstall'].includes(action))throw new Error('Unknown administrator action.');
+  if(action==='install'&&(!source||!['manual','background'].includes(mode)))throw new Error('Installation needs a paired source and an explicit mode.');
+  if(action==='mode'&&!['manual','background'].includes(mode))throw new Error('Mode must be manual or background.');
+  if(purge&&action!=='uninstall')throw new Error('--purge requires uninstall.');
+  const installer=action==='install'?path.join(source,'admin-service.mjs'):path.join(root,'admin-service.mjs');
+  // The protected root is intentionally unreadable to ordinary users.
+  // Derive the known runtime path without inspecting privileged files.
+  const safeNode=action==='install'?process.execPath:path.join(root,'runtime',`node-v24.19.0-${platform}-${process.arch}`,platform==='win32'?'node.exe':'bin/node');
+  const args=[installer,action];
+  if(action==='install')args.push(source,mode);
+  if(action==='mode')args.push(mode);
+  if(purge)args.push('--purge');
+  if(platform==='win32') {
+    // Windows UAC is shown through the OS; exit code is propagated to the caller.
+    const windowsArg=x=>'"'+String(x).replace(/(\\*)"/g,'$1$1\\"').replace(/(\\+)$/,'$1$1')+'"';
+    const list=psQuote(args.map(windowsArg).join(' '));
+    const script='$ErrorActionPreference="Stop"; $p=Start-Process -FilePath '+psQuote(safeNode)+
+      ' -ArgumentList '+list+' -Verb RunAs -Wait -PassThru; exit $p.ExitCode';
+    return {command:'powershell.exe',args:['-NoProfile','-Command',script]};
+  }
+  if(!['darwin','linux'].includes(platform))throw new Error('Unsupported platform.');
+  return {command:'sudo',args:['--',safeNode,...args]};
+}
+function run(command,args) {
+ return new Promise((resolve,reject)=>{
+   const child=spawn(command,args,{stdio:'inherit'});
+   child.once('error',reject);
+   child.once('exit',(code,signal)=>code===0?resolve():reject(new Error('Administrator authorization or operation failed: '+(signal??code))));
+ });
+}
+const argv=process.argv.slice(2);
+if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url)){
+ const [action,...args]=argv;
+ const opts=action==='install'?{source:args[0],mode:args[1]}:action==='mode'?{mode:args[0]}:action==='uninstall'?{purge:args[0]==='--purge'}:{};
+ if((action==='install'&&args.length!==2)||(action==='mode'&&args.length!==1)||(action==='uninstall'&&args.length>1)||(action!=='install'&&action!=='mode'&&action!=='uninstall'&&args.length))throw new Error('Unexpected administrative arguments.');
+ const request=elevationRequest(action,opts);
+ console.log('Administrator authorization will be requested by the operating system. This does not grant Google, ChatGPT or macOS privacy permissions.');
+ await run(request.command,request.args);
+}