@clawpilot-app/link 0.1.0

package/src/i18n.js

@@ -0,0 +1,182 @@
+export const SUPPORTED_LANGUAGES = Object.freeze(["en", "zh-Hans"]);
+
+const copy = {
+  en: {
+    pairingCreated: "ClawPilot Link pairing session created.",
+    scanPrompt: "Scan this QR with ClawPilot App:",
+    manualCode: "Manual code",
+    waitingForScan: "Waiting for someone to scan the code...",
+    pairingSuccess: "ClawPilot Link is now paired.",
+    pairingExpired: "This pairing session expired. Run clawlink pair again.",
+    startDaemonAfterPair: "Starting the Link service in the background...",
+    daemonStarted: "ClawPilot Link is running in the background.",
+    daemonAlreadyRunning: "ClawPilot Link is already running.",
+    daemonStopped: "ClawPilot Link has been stopped.",
+    restartDone: "ClawPilot Link has been restarted.",
+    notPaired: "This computer is not paired yet. Run clawlink pair first.",
+    backendMissing: "OpenClaw was not found on this computer.",
+    backendUnsupported: "Your current OpenClaw setup is not supported yet.",
+    backendReachableOnPort: "OpenClaw is reachable on port {{port}}.",
+    localAccessReadyOnPort: "Local access is ready on port {{port}}.",
+    localAccessDaemonOffline: "Local access is off because ClawPilot Link is not running.",
+    localAccessPortInUse:
+      "Local access could not start because port {{port}} is already being used by another app on this computer. Close that app, then run clawlink restart.",
+    localAccessPermissionDenied:
+      "Local access could not start because this computer denied permission to open port {{port}}. Check your system settings or security software, then run clawlink restart.",
+    localAccessUnavailable:
+      "Local access is not available right now. Run clawlink doctor to see what needs attention.",
+    localAccessNeedsAttention:
+      "ClawPilot Link can still use Relay, but local network direct connection is not ready yet. Run clawlink doctor for help.",
+    doctorSummaryOk: "Everything looks good.",
+    doctorSummaryFix: "Something needs attention before Link can stay online.",
+    statusTitle: "ClawPilot Link status",
+    statusLinkIdLabel: "Link ID",
+    statusStateLabel: "Status",
+    statusDaemonLabel: "Daemon",
+    statusOpenClawLabel: "OpenClaw",
+    statusLocalAccessLabel: "Local access",
+    statusLastErrorLabel: "Last error",
+    statusBackendUrlLabel: "Backend URL",
+    statusNotPairedValue: "Not paired",
+    statusUnknownValue: "Unknown",
+    statusDaemonOnlineValue: "online",
+    statusDaemonOfflineValue: "offline",
+    qrJoinReady: "A new join QR code is ready.",
+    qrNeedsPair: "This computer is not paired yet, so we cannot create a join QR code.",
+    connectForeground: "Running ClawPilot Link in the foreground. Press Ctrl+C to stop.",
+    connectBackground: "ClawPilot Link has been started in the background.",
+    pairedOk: "Link is paired.",
+    daemonRunning: "Daemon is running.",
+    daemonNotRunning: "Daemon is not running.",
+    linkCredentialsMissing: "Link needs to be paired again on this computer.",
+    linkCredentialsExpired: "This computer's Link sign-in expired. Run clawlink pair again.",
+    linkRevoked: "This computer's Link access was removed. Run clawlink pair again to reconnect.",
+    relayConfigSecure: "Relay address uses HTTPS.",
+    relayConfigInsecure:
+      "The Relay address must start with https://. Open {{configFile}} and update relayBaseUrl.",
+    relayReachable: "Relay is reachable.",
+    relayUnreachable: "Relay is not reachable right now.",
+    relayCheckSkipped:
+      "Relay health was not checked because the Relay address is not using https://.",
+    apiReachable: "API server is reachable.",
+    apiUnreachable: "API server is not reachable right now.",
+    skillInstalled: "Skill file is installed.",
+    skillMissing: "Skill file is missing.",
+    unpairConfirm: "Run clawlink unpair --yes if you really want to clear this computer's Link credentials.",
+    startDaemonFailed: "ClawPilot Link did not start in time.",
+    restartFailed: "ClawPilot Link did not restart in time.",
+    unknownCommand: "Unknown command",
+    availableCommands: "Available commands: pair, qr, connect, status, doctor, restart, unpair",
+  },
+  "zh-Hans": {
+    pairingCreated: "已创建 ClawPilot Link 配对会话。",
+    scanPrompt: "请用 ClawPilot App 扫描下面的二维码：",
+    manualCode: "手动输入码",
+    waitingForScan: "正在等待有人扫码...",
+    pairingSuccess: "ClawPilot Link 已完成配对。",
+    pairingExpired: "这次配对已经过期，请重新执行 clawlink pair。",
+    startDaemonAfterPair: "正在后台启动 Link 服务...",
+    daemonStarted: "ClawPilot Link 已在后台运行。",
+    daemonAlreadyRunning: "ClawPilot Link 已经在运行。",
+    daemonStopped: "ClawPilot Link 已停止。",
+    restartDone: "ClawPilot Link 已重新启动。",
+    notPaired: "这台电脑还没有配对，请先执行 clawlink pair。",
+    backendMissing: "这台电脑上没有找到 OpenClaw。",
+    backendUnsupported: "当前 OpenClaw 配置暂时还不支持 Link。",
+    backendReachableOnPort: "已经在 {{port}} 端口找到 OpenClaw。",
+    localAccessReadyOnPort: "局域网直连已经在 {{port}} 端口就绪。",
+    localAccessDaemonOffline: "由于 ClawPilot Link 没有运行，局域网直连当前不可用。",
+    localAccessPortInUse:
+      "{{port}} 端口已经被这台电脑上的其他程序占用，所以局域网直连没能启动。先关闭占用它的程序，再执行 clawlink restart。",
+    localAccessPermissionDenied:
+      "这台电脑没有允许 ClawPilot Link 打开 {{port}} 端口，所以局域网直连没能启动。请检查系统设置或安全软件，然后再执行 clawlink restart。",
+    localAccessUnavailable: "局域网直连暂时还不可用。你可以执行 clawlink doctor 看看哪里需要处理。",
+    localAccessNeedsAttention:
+      "现在仍然可以走 Relay，但局域网直连还没有准备好。你可以执行 clawlink doctor 查看提示。",
+    doctorSummaryOk: "当前看起来一切正常。",
+    doctorSummaryFix: "还有问题需要先处理，Link 才能稳定在线。",
+    statusTitle: "ClawPilot Link 状态",
+    statusLinkIdLabel: "Link ID",
+    statusStateLabel: "当前状态",
+    statusDaemonLabel: "后台服务",
+    statusOpenClawLabel: "OpenClaw",
+    statusLocalAccessLabel: "局域网直连",
+    statusLastErrorLabel: "上次错误",
+    statusBackendUrlLabel: "本地地址",
+    statusNotPairedValue: "还没有配对",
+    statusUnknownValue: "未知",
+    statusDaemonOnlineValue: "在线",
+    statusDaemonOfflineValue: "离线",
+    qrJoinReady: "新的加入二维码已经生成。",
+    qrNeedsPair: "这台电脑还没有完成配对，所以现在不能生成加入二维码。",
+    connectForeground: "ClawPilot Link 正在前台运行。按 Ctrl+C 可停止。",
+    connectBackground: "ClawPilot Link 已在后台启动。",
+    pairedOk: "这台电脑已经完成 Link 配对。",
+    daemonRunning: "后台服务正在运行。",
+    daemonNotRunning: "后台服务还没有运行。",
+    linkCredentialsMissing: "这台电脑需要重新配对 Link。",
+    linkCredentialsExpired: "这台电脑上的 Link 登录已经失效，请重新执行 clawlink pair。",
+    linkRevoked: "这台电脑的 Link 访问权限已被移除，请重新执行 clawlink pair。",
+    relayConfigSecure: "Relay 地址已使用 HTTPS。",
+    relayConfigInsecure:
+      "Relay 地址必须以 https:// 开头。请打开 {{configFile}}，把 relayBaseUrl 改成 https:// 地址。",
+    relayReachable: "Relay 服务可以连通。",
+    relayUnreachable: "现在还连不上 Relay 服务。",
+    relayCheckSkipped: "由于 Relay 地址不是 https://，所以这次没有继续检测 Relay 连通性。",
+    apiReachable: "API 服务可以连通。",
+    apiUnreachable: "现在还连不上 API 服务。",
+    skillInstalled: "SKILL 文件已经安装。",
+    skillMissing: "还没有找到 SKILL 文件。",
+    unpairConfirm: "如果你确定要清掉这台电脑上的 Link 凭据，请执行 clawlink unpair --yes。",
+    startDaemonFailed: "ClawPilot Link 没有在预期时间内启动。",
+    restartFailed: "ClawPilot Link 没有在预期时间内重新启动。",
+    unknownCommand: "不支持这个命令",
+    availableCommands: "可用命令：pair、qr、connect、status、doctor、restart、unpair",
+  },
+};
+
+export function detectLanguage() {
+  const envCandidates = [
+    process.env.CLAWPILOT_LINK_LANG,
+    process.env.LC_ALL,
+    process.env.LC_MESSAGES,
+    process.env.LANG,
+  ]
+    .filter((value) => typeof value === "string" && value.trim())
+    .map((value) => value.toLowerCase());
+
+  for (const candidate of envCandidates) {
+    if (candidate.includes("zh")) {
+      return "zh-Hans";
+    }
+    if (candidate.includes("en")) {
+      return "en";
+    }
+  }
+
+  return "en";
+}
+
+export function resolveLanguage(configLanguage) {
+  if (configLanguage === "zh-Hans" || configLanguage === "en") {
+    return configLanguage;
+  }
+  return detectLanguage();
+}
+
+export function createTranslator(language) {
+  const resolvedLanguage = language === "zh-Hans" ? "zh-Hans" : "en";
+  return {
+    language: resolvedLanguage,
+    t(key, vars = undefined) {
+      const template = copy[resolvedLanguage][key] ?? copy.en[key] ?? key;
+      if (!vars || typeof vars !== "object") {
+        return template;
+      }
+      return template.replace(/\{\{(\w+)\}\}/g, (_, name) => {
+        const value = vars[name];
+        return value === undefined || value === null ? "" : String(value);
+      });
+    },
+  };
+}

package/src/network.js

@@ -0,0 +1,71 @@
+import os from "node:os";
+
+export const LINK_DIRECT_PORT = 52378;
+
+const VIRTUAL_INTERFACE_NAME_PATTERN =
+  /(docker|veth|vmnet|vbox|tailscale|utun|virbr|hyper-v|vethernet|loopback|\blo\b|^br-|^zt|^tun|^tap)/i;
+
+function normalizeHost(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim();
+  return normalized || null;
+}
+
+function isPrivateIpv4(address) {
+  if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(address)) {
+    return false;
+  }
+
+  const segments = address.split(".").map((segment) => Number.parseInt(segment, 10));
+  if (segments.some((segment) => Number.isNaN(segment) || segment < 0 || segment > 255)) {
+    return false;
+  }
+
+  const [first, second] = segments;
+  if (first === 10) {
+    return true;
+  }
+  if (first === 192 && second === 168) {
+    return true;
+  }
+  return first === 172 && second >= 16 && second <= 31;
+}
+
+function shouldIgnoreInterface(name) {
+  const normalized = normalizeHost(name);
+  if (!normalized) {
+    return true;
+  }
+  return VIRTUAL_INTERFACE_NAME_PATTERN.test(normalized);
+}
+
+export function listLanIpv4Addresses() {
+  const interfaces = os.networkInterfaces();
+  const addresses = [];
+  const seen = new Set();
+
+  for (const [name, entries] of Object.entries(interfaces)) {
+    if (shouldIgnoreInterface(name) || !Array.isArray(entries)) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry || entry.internal) {
+        continue;
+      }
+      if (entry.family !== "IPv4") {
+        continue;
+      }
+      const address = normalizeHost(entry.address);
+      if (!address || !isPrivateIpv4(address) || seen.has(address)) {
+        continue;
+      }
+      seen.add(address);
+      addresses.push(address);
+    }
+  }
+
+  return addresses.sort((left, right) => left.localeCompare(right));
+}

package/src/openclaw.js

@@ -0,0 +1,297 @@
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import JSON5 from "json5";
+import {
+  fileExists,
+  normalizeNonEmptyString,
+  runtimePaths,
+} from "./runtime.js";
+
+const DEFAULT_GATEWAY_PORT = 18789;
+const FALLBACK_PORTS = [18789, 3400];
+
+function resolveConfigPath() {
+  if (normalizeNonEmptyString(process.env.OPENCLAW_CONFIG_PATH)) {
+    return process.env.OPENCLAW_CONFIG_PATH.trim();
+  }
+  if (normalizeNonEmptyString(process.env.OPENCLAW_STATE_DIR)) {
+    return path.join(process.env.OPENCLAW_STATE_DIR.trim(), "openclaw.json");
+  }
+  return path.join(os.homedir(), ".openclaw", "openclaw.json");
+}
+
+export async function readOpenClawConfig() {
+  const configPath = resolveConfigPath();
+  if (!fileExists(configPath)) {
+    return {
+      exists: false,
+      configPath,
+      config: null,
+    };
+  }
+
+  const raw = await fsp.readFile(configPath, "utf8");
+  return {
+    exists: true,
+    configPath,
+    config: JSON5.parse(raw),
+  };
+}
+
+function resolveGatewayAuth(config) {
+  const gateway = config?.gateway ?? {};
+  const auth = gateway?.auth ?? {};
+  const mode = normalizeNonEmptyString(auth.mode);
+  const token = normalizeNonEmptyString(auth.token);
+  const password = normalizeNonEmptyString(auth.password);
+
+  if (mode === "token" || (!mode && token)) {
+    return token
+      ? {
+          authType: "token",
+          secret: token,
+          supported: true,
+          message: null,
+        }
+      : {
+          authType: "token",
+          secret: null,
+          supported: false,
+          message: "gateway.auth.token is missing.",
+        };
+  }
+
+  if (mode === "password" || (!mode && password)) {
+    return password
+      ? {
+          authType: "password",
+          secret: password,
+          supported: true,
+          message: null,
+        }
+      : {
+          authType: "password",
+          secret: null,
+          supported: false,
+          message: "gateway.auth.password is missing.",
+        };
+  }
+
+  return {
+    authType: mode ?? null,
+    secret: null,
+    supported: false,
+    message: "Link currently needs OpenClaw shared-secret auth (token or password).",
+  };
+}
+
+function buildLocalAuthHeaders(authType, secret) {
+  const normalizedSecret = normalizeNonEmptyString(secret);
+  if (!normalizedSecret) {
+    return {};
+  }
+
+  if (authType === "password") {
+    const basicValue = Buffer.from(`:${normalizedSecret}`, "utf8").toString("base64");
+    return {
+      authorization: `Basic ${basicValue}`,
+      "x-openclaw-password": normalizedSecret,
+    };
+  }
+
+  return {
+    authorization: `Bearer ${normalizedSecret}`,
+  };
+}
+
+async function probeHttpBaseUrl(candidate) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, 4_000);
+
+  try {
+    const response = await fetch(`${candidate.httpBaseUrl}/v1/responses`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-openclaw-scopes": "operator.write",
+        ...buildLocalAuthHeaders(candidate.authType, candidate.secret),
+      },
+      body: JSON.stringify({}),
+      signal: controller.signal,
+    });
+
+    return {
+      reachable:
+        response.ok ||
+        [400, 401, 403, 404, 405, 422, 501].includes(response.status),
+      status: response.status,
+      message: `HTTP ${response.status}`,
+    };
+  } catch (error) {
+    return {
+      reachable: false,
+      status: 0,
+      message: error instanceof Error ? error.message : "probe_failed",
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export async function detectOpenClawBackend() {
+  const configResult = await readOpenClawConfig();
+  const candidates = [];
+  if (configResult.exists && configResult.config) {
+    const gateway = configResult.config.gateway ?? {};
+    const rawPort = Number(gateway.port ?? DEFAULT_GATEWAY_PORT);
+    const port = Number.isInteger(rawPort) && rawPort > 0 ? rawPort : DEFAULT_GATEWAY_PORT;
+    const auth = resolveGatewayAuth(configResult.config);
+    candidates.push({
+      source: "config",
+      configPath: configResult.configPath,
+      port,
+      httpBaseUrl: `http://127.0.0.1:${port}`,
+      wsEndpoint: `ws://127.0.0.1:${port}`,
+      authType: auth.authType,
+      secret: auth.secret,
+      supported: auth.supported,
+      supportMessage: auth.message,
+    });
+  }
+
+  for (const port of FALLBACK_PORTS) {
+    if (candidates.some((candidate) => candidate.port === port)) {
+      continue;
+    }
+    candidates.push({
+      source: "probe",
+      configPath: configResult.configPath,
+      port,
+      httpBaseUrl: `http://127.0.0.1:${port}`,
+      wsEndpoint: `ws://127.0.0.1:${port}`,
+      authType: null,
+      secret: null,
+      supported: false,
+      supportMessage: "OpenClaw config was not found, so Link cannot read gateway auth.",
+    });
+  }
+
+  for (const candidate of candidates) {
+    const probe = await probeHttpBaseUrl(candidate);
+    if (!probe.reachable) {
+      continue;
+    }
+
+    return {
+      detected: true,
+      healthy: candidate.supported,
+      supported: candidate.supported,
+      message:
+        candidate.supported
+          ? `OpenClaw is reachable on port ${candidate.port}.`
+          : candidate.supportMessage,
+      configPath: candidate.configPath,
+      httpBaseUrl: candidate.httpBaseUrl,
+      wsEndpoint: candidate.wsEndpoint,
+      authType: candidate.authType,
+      secret: candidate.secret,
+      source: candidate.source,
+      port: candidate.port,
+      checkedAt: new Date().toISOString(),
+    };
+  }
+
+  return {
+    detected: false,
+    healthy: false,
+    supported: false,
+    message: "OpenClaw is not reachable on this computer.",
+    configPath: configResult.configPath,
+    httpBaseUrl: null,
+    wsEndpoint: null,
+    authType: null,
+    secret: null,
+    source: null,
+    port: null,
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+export async function writeBackendCache(backend) {
+  await fsp.writeFile(
+    path.join(runtimePaths.cacheDir, "openclaw.json"),
+    `${JSON.stringify(backend, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+function buildSkillContent(language) {
+  if (language === "zh-Hans") {
+    return `# ClawPilot Link
+
+这台电脑已经安装了 ClawPilot Link。
+
+你可以优先使用这些命令：
+
+- \`clawlink status --json\`
+- \`clawlink doctor --json\`
+- \`clawlink qr\`
+- \`clawlink restart\`
+
+高风险命令必须先征求用户确认：
+
+- \`clawlink unpair\`
+
+如果用户只是说“连不上”或“掉线了”，先运行：
+
+1. \`clawlink status --json\`
+2. \`clawlink doctor --json\`
+
+然后把发生了什么和建议怎么修复，用普通人能看懂的话告诉用户。
+`;
+  }
+
+  return `# ClawPilot Link
+
+ClawPilot Link is installed on this computer.
+
+Start with these commands:
+
+- \`clawlink status --json\`
+- \`clawlink doctor --json\`
+- \`clawlink qr\`
+- \`clawlink restart\`
+
+Ask for confirmation before running anything risky:
+
+- \`clawlink unpair\`
+
+If the user says Link is offline or not connecting, check:
+
+1. \`clawlink status --json\`
+2. \`clawlink doctor --json\`
+
+Then explain what happened in plain language and tell the user what to do next.
+`;
+}
+
+export async function installSkill(language) {
+  const configPath = resolveConfigPath();
+  const stateDir = path.dirname(configPath);
+  const skillDir = path.join(stateDir, "skills", "clawpilot-link");
+  await fsp.mkdir(skillDir, { recursive: true });
+  const skillPath = path.join(skillDir, "SKILL.md");
+  await fsp.writeFile(skillPath, buildSkillContent(language), "utf8");
+  return {
+    skillPath,
+  };
+}
+
+export function buildLocalGatewayRequestHeaders(backend) {
+  return {
+    ...buildLocalAuthHeaders(backend.authType, backend.secret),
+  };
+}