@walkhi/code-relax 0.1.0-beta.1

package/dist/src/service-control.mjs

@@ -0,0 +1,72 @@
+import http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+function matches(left, right) {
+  const a = Buffer.from(left || '');
+  const b = Buffer.from(right || '');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+// Separate from the LAN listener: mobile credentials never authorize lifecycle operations.
+export async function openControl({ instanceId, secret, shutdown, status = () => ({}), actions = {} }) {
+  const server = http.createServer((request, response) => {
+    if (!matches(request.headers.authorization, `Bearer ${secret}`)) {
+      response.writeHead(403).end();
+      return;
+    }
+    const action = Object.keys(actions).find(name => request.url === `/${instanceId}/${name}`);
+    if ((!action && request.url !== `/${instanceId}`) || !['GET', 'POST'].includes(request.method) || (action && request.method !== 'POST')) {
+      response.writeHead(404).end();
+      return;
+    }
+    response.setHeader('Content-Type', 'application/json');
+    response.setHeader('Connection', 'close');
+    if (action) {
+      Promise.resolve().then(() => actions[action]()).then(result => {
+        response.end(JSON.stringify({ ...result, instanceId, pid: process.pid }));
+      }).catch(error => { response.writeHead(409).end(JSON.stringify({ error: error.message })); });
+      return;
+    }
+    if (request.method === 'POST') response.once('finish', () => {
+      Promise.resolve(shutdown()).catch(error => {
+        console.error('Bridge 关闭失败：', error.message);
+        process.exitCode = 1;
+      });
+    });
+    response.end(JSON.stringify({ ...status(), instanceId, pid: process.pid }));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  return { port: server.address().port, close: () => new Promise((resolve, reject) => {
+    server.close(error => error ? reject(error) : resolve());
+  }) };
+}
+
+export function controlRequest(session, method = 'GET', action = '') {
+  return new Promise((resolve, reject) => {
+    const request = http.request({ hostname: '127.0.0.1', port: session.controlPort,
+      path: `/${session.instanceId}${action ? '/' + action : ''}`, method, agent: false,
+      headers: { Authorization: `Bearer ${session.controlSecret}` }, timeout: action ? 25000 : 2000 }, response => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', chunk => { body += chunk; });
+      response.on('error', reject);
+      response.on('end', () => {
+        try {
+          if (response.statusCode === 409) throw new Error(JSON.parse(body).error);
+          if (response.statusCode !== 200) throw new Error('Bridge 管理通道身份验证失败。');
+          const identity = JSON.parse(body);
+          if (identity.instanceId !== session.instanceId || identity.pid !== session.pid) {
+            throw new Error('Bridge 实例身份不匹配。');
+          }
+          resolve(identity);
+        } catch (error) { reject(error); }
+      });
+    });
+    request.on('timeout', () => request.destroy(new Error('Bridge 管理通道响应超时。')));
+    request.on('error', reject);
+    request.end();
+  });
+}

package/dist/src/service-doctor.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readRecord } from './service-lifecycle.mjs';
+import { inspectSkill } from './skill-install.mjs';
+import { readManagedEnvironment } from './platform/windows/user-environment.mjs';
+import { managedAppServerUrl } from './managed-app-server.mjs';
+
+export async function doctor({ paths, host, service, skillTarget }) {
+  const checks = [];
+  const add = (id, status, message) => checks.push({ id, status, message });
+  const check = async (id, task) => {
+    try { await task(); } catch (error) { add(id, 'error', error.message); }
+  };
+  await check('installation', async () => {
+    const record = readRecord(path.join(paths.serviceRoot, 'installation.json'));
+    if (!record || !fs.existsSync(path.join(paths.serviceRoot, 'dist/bin/codex-remote.mjs'))) throw Error('尚未完整部署服务，请重新安装 Code Relax。');
+    if (!record.nodeExecutable || !fs.existsSync(record.nodeExecutable)) throw Error('记录的 Node 已失效，请用可用的 Node 重新安装 Code Relax。');
+    add('installation', 'ok', `服务 ${record.version}；Node：${record.nodeExecutable}`);
+  });
+  let sharedUrl;
+  await check('shared-service', async () => {
+    sharedUrl = await host.sharedServiceUrl();
+    add('shared-service', 'ok', sharedUrl ? '完整控制连接可用。' : '当前使用基础控制。');
+  });
+  await check('desktop', async () => {
+    await host.desktopEnvironment(readRecord(path.join(paths.stateRoot, 'bridge-startup-context.json')), sharedUrl);
+    add('desktop', 'ok', 'Desktop 来源上下文和工具管道已定位；实际任务操作尚未验证。');
+  });
+  await check('network', async () => {
+    const address = await host.lanAddress();
+    if (!address) throw Error('未找到局域网 IPv4；请连接受信任的 Wi-Fi 或有线网络。');
+    add('network', 'ok', `局域网地址：${address}`);
+  });
+  await check('service', async () => {
+    const state = await service.status();
+    add('service', state.running ? 'ok' : 'warning', state.running
+      ? `本机服务正常：${state.mode}，端口 ${state.port}` : '服务未就绪；安装后执行 relax start。');
+    if (state.running) add('managed-app-server', state.managedAppServer?.state === 'ready' ? 'ok' : 'error',
+      state.managedAppServer?.state === 'ready' ? '受管 app-server 已就绪。'
+        : state.managedAppServer?.error || '受管 app-server 尚未就绪。');
+    if (state.managedAppServer?.updatePending) add('managed-app-server-update', 'warning',
+      'Codex Desktop 已提供新版 CLI；当前 app-server 会继续完成任务，并在下次进程自然重启或重新登录 Windows 后采用新版。');
+  });
+  await check('desktop-environment', async () => {
+    const environment = await readManagedEnvironment();
+    if (environment.forceCliUser === '1' || environment.forceCliMachine === '1') {
+      add('desktop-environment', 'error', 'CODEX_APP_SERVER_FORCE_CLI=1 会阻止 Desktop 使用受管 app-server。');
+    } else if (environment.userValue === managedAppServerUrl) {
+      add('desktop-environment', 'ok', `Desktop 后续启动地址：${managedAppServerUrl}`);
+    } else {
+      add('desktop-environment', 'warning', environment.userValue
+        ? `用户配置了其他 app-server 地址：${environment.userValue}`
+        : '尚未配置 Desktop 后续启动地址；请重新执行 setup。');
+    }
+  });
+  await check('skill', async () => {
+    const state = inspectSkill(skillTarget);
+    add('skill', state.managed ? 'ok' : 'warning', state.managed ? '本包管理的 Skill 已安装。'
+      : state.installed ? '存在同名自定义 Skill，本包不会覆盖。' : '可执行 relax skill-install 安装 Skill。');
+  });
+  add('firewall', 'warning', '手机连通性未验证。首次启动请允许记录的 Node 在受信任的专用网络通信；若曾拒绝，可在 Windows 安全中心的防火墙“允许应用通过防火墙”中检查该 Node。不要关闭整个防火墙。');
+  return { ready: !checks.some(item => item.status === 'error'), lanAccess: 'unverified', checks };
+}

package/dist/src/service-health.mjs

@@ -0,0 +1,33 @@
+import WebSocket from 'ws';
+
+// Use the same authenticated LAN protocol as mobile clients; never replay requests.
+export function serviceHealth(session) {
+  if (!session) return Promise.resolve(null);
+  return new Promise((resolve, reject) => {
+    const token = new URL(session.accessUrl).searchParams.get('token');
+    const socket = new WebSocket(`ws://127.0.0.1:${session.port}/api/socket`);
+    let done = false;
+    const finish = (error, value = null) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      socket.terminate();
+      if (error) reject(error); else resolve(value);
+    };
+    const timer = setTimeout(() => finish(new Error('Bridge 健康检查超时。')), 6000);
+    socket.on('open', () => socket.send(JSON.stringify({ type: 'auth', token })));
+    socket.on('message', data => {
+      try {
+        const message = JSON.parse(data.toString());
+        if (message.type === 'ready') {
+          socket.send(JSON.stringify({ type: 'request', id: 1, method: 'GET', path: '/api/health' }));
+        } else if (message.type === 'response' && message.id === 1) {
+          finish(null, message.status === 200 ? message.body : null);
+        }
+      } catch (error) { finish(error); }
+    });
+    socket.on('error', error => finish(error.code === 'ECONNREFUSED' ? null : error));
+    socket.on('close', code => finish(new Error(code === 1008
+      ? 'Bridge 健康检查鉴权失败。' : 'Bridge 健康检查连接已断开。')));
+  });
+}

package/dist/src/service-install.mjs

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { assertPlainPath } from './skill-install.mjs';
+
+const exec = promisify(execFile);
+export function packageRoot(from) {
+  let directory = path.resolve(from);
+  while (true) {
+    if (readRecord(path.join(directory, 'package.json'))?.name === '@walkhi/code-relax') return directory;
+    const parent = path.dirname(directory);
+    if (parent === directory) throw new Error('找不到 Code Relax 安装包。');
+    directory = parent;
+  }
+}
+
+export async function installService(source, target, executable, stateRoot, hooks = {}) {
+  assertPlainPath(target);
+  if (!fs.existsSync(path.join(source, 'dist/bin/codex-remote.mjs'))) throw new Error('缺少发布构建；源码目录请先执行 npm run build。');
+  if (!fs.existsSync(path.join(source, 'node_modules'))) throw new Error('缺少包依赖，请重新安装完整 npm 包。');
+  const parent = path.dirname(target);
+  const legacyUploadsRoots = readRecord(path.join(target, 'installation.json'))?.legacyUploadsRoots || [];
+  if (fs.existsSync(path.join(source, 'src/server.mjs'))) legacyUploadsRoots.push(path.join(source, 'uploads'));
+  fs.mkdirSync(parent, { recursive: true });
+  const stage = path.join(parent, `service-stage-${randomUUID()}`);
+  const backup = path.join(parent, `service-backup-${randomUUID()}`);
+  fs.mkdirSync(stage);
+  try {
+    for (const name of ['dist', 'node_modules', 'package.json', 'README.md']) {
+      fs.cpSync(path.join(source, name), path.join(stage, name), { recursive: true });
+    }
+    await exec(executable, [path.join(stage, 'dist/bin/codex-remote.mjs'), '--help'], { windowsHide: true });
+    await exec(executable, ['-e', 'const r=require("node:module").createRequire(process.argv[1]); r("sharp"); r("qrcode"); r("ws"); r("node-datachannel");', path.join(stage, 'package.json')], { windowsHide: true });
+    writeRecord(path.join(stage, 'installation.json'), { installedAt: new Date().toISOString(), source, nodeExecutable: executable, stateRoot,
+      legacyUploadsRoots: [...new Set(legacyUploadsRoots)],
+      version: readRecord(path.join(source, 'package.json')).version });
+    const previous = fs.existsSync(target);
+    let previousMoved = false, activated = false;
+    try {
+      await hooks.beforeActivate?.();
+      if (previous) { fs.renameSync(target, backup); previousMoved = true; }
+      fs.renameSync(stage, target); activated = true;
+      await hooks.verifyActivation?.({ serviceRoot: target, nodeExecutable: executable,
+        version: readRecord(path.join(target, 'package.json')).version });
+    } catch (error) {
+      try {
+        if (activated && fs.existsSync(target)) fs.rmSync(target, { recursive: true });
+        if (previousMoved) fs.renameSync(backup, target);
+        await hooks.restoreActivation?.();
+      } catch (restoreError) {
+        throw new AggregateError([error, restoreError], `服务更新失败，旧版本恢复也未完成：${restoreError.message}`);
+      }
+      throw error;
+    }
+    if (previous) {
+      if (path.dirname(backup) !== parent || !path.basename(backup).startsWith('service-backup-')) throw new Error('Invalid backup path');
+      fs.rmSync(backup, { recursive: true });
+    }
+    return { serviceRoot: target, nodeExecutable: executable, version: readRecord(path.join(target, 'package.json')).version };
+  } finally {
+    // Only this invocation's generated sibling stage may be cleaned up.
+    if (path.dirname(stage) !== parent || !path.basename(stage).startsWith('service-stage-')) throw new Error('Invalid stage path');
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+export async function uninstallService({ serviceRoot, stateRoot, uploadsRoot, credentialsRoot }, service, beforeRemove = async () => {}) {
+  const target = path.resolve(serviceRoot);
+  assertPlainPath(target);
+  if (path.basename(target) !== 'service' || path.basename(path.dirname(target)) !== 'CodexRemote') throw new Error('拒绝删除未识别的服务目录。');
+  const preserved = [stateRoot, uploadsRoot, credentialsRoot].filter(Boolean);
+  for (const data of preserved) {
+    const relative = path.relative(target, path.resolve(data));
+    if (!relative || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))) throw new Error('服务目录包含用户数据，拒绝删除。');
+  }
+  if (!fs.existsSync(target)) {
+    await service.stop();
+    await beforeRemove();
+    return { removed: false, serviceRoot: target, preserved };
+  }
+  const pkg = readRecord(path.join(target, 'package.json'));
+  const record = readRecord(path.join(target, 'installation.json'));
+  if (pkg?.name !== '@walkhi/code-relax' || !record?.installedAt || !record?.nodeExecutable) throw new Error('缺少有效安装记录，未删除服务目录。');
+  await service.stop();
+  await beforeRemove();
+  fs.rmSync(target, { recursive: true });
+  return { removed: true, serviceRoot: target, preserved };
+}

package/dist/src/service-lifecycle.mjs

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { startBackground, processAlive } from './background-process.mjs';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { controlRequest } from './service-control.mjs';
+import { serviceHealth as health } from './service-health.mjs';
+
+export function readRecord(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export function writeRecord(file, value) {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temp, JSON.stringify(value, null, 2), { mode: 0o600 });
+    fs.renameSync(temp, file);
+  } finally { fs.rmSync(temp, { force: true }); }
+}
+
+export function lifecycle({ stateRoot, host }) {
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const sessionPath = path.join(stateRoot, 'bridge-session.json');
+  const configPath = path.join(stateRoot, 'bridge-config.json');
+  const contextPath = path.join(stateRoot, 'bridge-startup-context.json');
+  const scriptPath = fileURLToPath(new URL('./server.mjs', import.meta.url));
+
+  async function alive(session) {
+    if (!session?.controlPort || !session.instanceId || !session.controlSecret) {
+      if (await health(session)) throw new Error('当前为旧版 Bridge，请先使用旧版停止入口结束服务，再启动新版。');
+      return false;
+    }
+    try { await controlRequest(session); return true; }
+    catch (error) { if (error.code === 'ECONNREFUSED') return false; throw error; }
+  }
+  async function stop() {
+    const session = readRecord(sessionPath);
+    if (!await alive(session)) return { stopped: true, message: 'Bridge 已停止。' };
+    await controlRequest(session, 'POST');
+    const deadline = Date.now() + 10000;
+    while (true) {
+      try { if (!await alive(session)) break; }
+      catch (error) {
+        // A connection accepted just before the listener closes may be reset.
+        // Verify refusal on the next connection; never resend the shutdown request.
+        if (error.code !== 'ECONNRESET') throw error;
+      }
+      if (Date.now() > deadline) throw new Error('Bridge 未在 10 秒内退出；未强杀进程。');
+      await delay(100);
+    }
+    return { stopped: true, message: 'Bridge 已正常关闭。' };
+  }
+  async function status() {
+    const session = readRecord(sessionPath);
+    const running = await alive(session);
+    const result = running ? await health(session) : null;
+    return { running: running && result?.status === 'ok', processRunning: running, pid: session?.pid,
+      port: session?.port, mode: result?.transportMode, execution: result?.execution,
+      managedAppServer: result?.managedAppServer, desktop: result?.desktop,
+      desktopRestartRecommended: result?.desktopRestartRecommended === true,
+      resident: result?.resident === true };
+  }
+  async function pair() {
+    const session = readRecord(sessionPath);
+    const connection = await alive(session) ? await health(session) : null;
+    if (connection?.status !== 'ok' || !session.lan) {
+      throw new Error('没有健康的局域网服务，请先执行 relax start。');
+    }
+    const address = await host.lanAddress();
+    const url = new URL(session.accessUrl);
+    url.hostname = address || '127.0.0.1';
+    session.accessUrl = url.href;
+    writeRecord(sessionPath, session);
+    return { pid: session.pid, port: session.port, transportMode: connection.transportMode,
+      execution: connection.execution, managedAppServer: connection.managedAppServer, desktop: connection.desktop,
+      desktopRestartRecommended: connection.desktopRestartRecommended === true, accessUrl: session.accessUrl,
+      qrPath: path.join(stateRoot, 'connection-qr.png') };
+  }
+  async function start() {
+    let session = readRecord(sessionPath);
+    if (await alive(session)) {
+      const result = await health(session);
+      if (session.scriptPath === scriptPath && session.lan && result?.status === 'ok' && result.resident) {
+        const context = readRecord(contextPath) || {};
+        const sourceThreadId = process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID || context.sourceThreadId;
+        writeRecord(contextPath, { sourceThreadId });
+        await controlRequest(session, 'POST', 'refresh-execution');
+        return pair();
+      }
+      await stop();
+    }
+    let config = readRecord(configPath);
+    if (!config && session?.lan) config = { port: session.port, token: new URL(session.accessUrl).searchParams.get('token') };
+    config ||= { port: 45831, token: randomBytes(32).toString('base64url') };
+    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535 || !/^[A-Za-z0-9_-]{20,}$/.test(config.token)) {
+      throw new Error('bridge-config.json 中端口或 Token 无效；不会自动重置凭据。');
+    }
+    const address = await host.lanAddress() || '127.0.0.1';
+    const { executable, environment } = await host.desktopEnvironment(readRecord(contextPath), '');
+    writeRecord(configPath, config);
+    writeRecord(contextPath, { sourceThreadId: environment.CODEX_THREAD_ID || environment.CODEX_SESSION_ID });
+    const instanceId = randomUUID();
+    const controlSecret = randomBytes(32).toString('base64url');
+    const readyPath = path.join(stateRoot, `bridge-ready-${instanceId}.json`);
+    const pid = await startBackground(executable, [scriptPath, '--lan', '--port', String(config.port), '--token', config.token],
+      { ...environment, CODEX_REMOTE_INSTANCE: instanceId, CODEX_REMOTE_CONTROL_SECRET: controlSecret,
+        CODEX_REMOTE_READY_PATH: readyPath }, [path.join(stateRoot, 'bridge.stdout.log'), path.join(stateRoot, 'bridge.stderr.log')]);
+    try {
+      const deadline = Date.now() + 10000;
+      let ready;
+      while (!(ready = readRecord(readyPath))) {
+        if (!processAlive(pid)) throw new Error('Bridge 启动失败，请查看 bridge.stderr.log。');
+        if (Date.now() > deadline) throw new Error('Bridge 未在 10 秒内就绪。');
+        await delay(100);
+      }
+      if (ready.instanceId !== instanceId || ready.pid !== pid) throw new Error('Bridge 启动实例不匹配。');
+      session = { ...ready, controlSecret, executablePath: executable, scriptPath, port: config.port,
+        lan: true, appServer: false, accessUrl: `http://${address}:${config.port}/?token=${config.token}`,
+        startedAt: new Date().toISOString() };
+      await controlRequest(session);
+      writeRecord(sessionPath, session);
+      return await pair();
+    } catch (error) {
+      if (processAlive(pid)) process.kill(pid);
+      throw error;
+    } finally { fs.rmSync(readyPath, { force: true }); }
+  }
+  return { start, pair, status, stop };
+}

package/dist/src/service-restart.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { startBackground } from './background-process.mjs';
+import { lifecycle, readRecord } from './service-lifecycle.mjs';
+import * as host from './platform/windows/service-host.mjs';
+
+const script = fileURLToPath(import.meta.url);
+
+export async function requestServiceRestart(stateRoot) {
+  const lock = path.join(stateRoot, 'service-restart.lock');
+  const operationId = randomUUID();
+  let handle;
+  try {
+    handle = fs.openSync(lock, 'wx', 0o600);
+    fs.writeFileSync(handle, JSON.stringify({ operationId, requestedAt: new Date().toISOString() }));
+  } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('工作站服务已在重启中。');
+    throw error;
+  } finally { if (handle !== undefined) fs.closeSync(handle); }
+  try {
+    const log = path.join(stateRoot, 'service-restart.log');
+    await startBackground(process.execPath, [script, '--worker', stateRoot, operationId], process.env, [log, log]);
+    return { operationId, status: 'scheduled', message: '工作站服务重启已安排。' };
+  } catch (error) {
+    fs.rmSync(lock, { force: true }); throw error;
+  }
+}
+
+async function run(stateRoot, operationId) {
+  const lock = path.join(stateRoot, 'service-restart.lock');
+  if (readRecord(lock)?.operationId !== operationId) throw new Error('服务重启实例已失效。');
+  const service = lifecycle({ stateRoot, host });
+  try {
+    await delay(1000);
+    await service.stop();
+    await service.start();
+  } finally {
+    if (readRecord(lock)?.operationId === operationId) fs.rmSync(lock, { force: true });
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === script && process.argv[2] === '--worker') {
+  const [stateRoot, operationId] = process.argv.slice(3);
+  run(stateRoot, operationId).catch(error => { console.error(error.message); process.exitCode = 1; });
+}