@justlovepl/desktop-bridge 0.0.0-stage → 0.2.6

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,46 @@
-# 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.
+
+**Status: development branch, not yet published or production validated.**
+
+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               # must type 1 or 2; blank Enter prompts again
+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
+```
+
+**The CLI installation itself never prompts or starts a service.** Each interactive `desktop-bridge setup` or reinstall must explicitly select `1` (manual) or `2` (background); pressing Enter without a choice repeats the prompt. For non-interactive setup, a startup mode is mandatory. No existing credential, Agent, or login startup configuration may change before the choice is validated.\n\nUse `desktop-bridge setup --mode manual` or `--mode background` in automated shells. `--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
+npm update -g @justlovepl/desktop-bridge
+desktop-bridge setup
+```
+
+`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; routine update is not an interactive re-install. A new pairing still requires an explicit browser login and approval if the existing device authorization was revoked.
+
+## 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,114 @@
+#!/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);
+    }
+  }
+  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\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.');
+    return childRun(installer,['--repair',...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,92 @@
+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 npmCli=npmScript??findNpmCli();
+  print('Updating npm CLI (device credentials and configuration are kept outside npm)...');
+  const npmStatus=await execute(process.execPath,[npmCli,'install','--global','--no-audit','--no-fund',packageName+'@latest']);
+  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);
+}