@justprove/mobilevc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) MobileVC 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

@@ -0,0 +1,342 @@
+---
+
+# 📱 MobileVC — 手机就是你的 Claude Code 控制台
+
+<p align="center">
+  <img src="mobile_vc/lib/logo-2.png" alt="MobileVC logo" width="220" />
+</p>
+
+<p align="center">
+  <strong>摆脱键盘和鼠标的束缚，用手机随时接管电脑上的 Claude Code。</strong>
+</p>
+
+<p align="center">
+  <em>MobileVC 把 Claude Code 的等待、审批、审核和继续执行，变成一套专为移动端设计的操作闭环。</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Go-1.21-blue" />
+  <img src="https://img.shields.io/badge/Flutter-3.13-blue" />
+  <img src="https://img.shields.io/badge/License-MIT-green" />
+</p>
+
+---
+
+## 这是什么
+
+MobileVC 不是桌面终端的镜像，也不是远程桌面的替代品。
+
+它做的是一件更直接的事：**把电脑上的 Claude Code 变成可以被手机完整操控的工作台。**
+
+你不在电脑前，也能继续把任务推进下去：
+
+- 继续跟 Claude 对话
+- 批准或拒绝权限请求
+- 接住 Plan Mode 的多轮计划交互
+- 审核 diff、接受或回滚修改
+- 浏览文件、日志和运行状态
+- 恢复历史会话
+- 管理 Skill / Memory / Session Context
+- 在 Claude 需要你时收到提醒
+
+MobileVC 解决的不是“怎么远程看见电脑”，而是：
+
+> **怎么让你只靠手机，就能完成电脑上的几乎全部 Claude Code 工作流。**
+
+---
+
+## 核心价值
+
+### 1. 为手机重写 Claude Code 的交互
+
+手机上的操作不该依赖键盘盲输。MobileVC 把 Claude Code 的关键等待态拆出来，做成更适合触摸屏的一键动作和可视化面板：
+
+- 普通输入
+- 权限确认
+- Plan Mode 继续/推进
+- 代码审查
+- 会话恢复
+- 技能 / 记忆管理
+
+### 2. 让你离开电脑也不掉线
+
+你不需要守在桌面前，也不需要回到键盘旁。
+
+- 出门在外也能继续推进任务
+- 电脑不在身边也能批准修改
+- Claude 正在等待你时，手机能立即介入
+- 复杂工作流不会因为离开键盘而中断
+
+### 3. 把工作流做成“点一下就能继续”的手机体验
+
+MobileVC 不是为了展示“能远程看见什么”，而是为了让你真正把事做完，而且做得更快、更直观：
+
+- 看得见：skill 胶囊、memory 卡片、diff 组、日志和运行状态一目了然
+- 点得快：启用 / 停用、允许 / 拒绝、接受 / 回滚都能直接点选
+- 一键化：一键同步 skill / memory，一句话生成 skill，一句话修改 memory
+- 自动化：Claude 生成结果可自动回写 catalog，并刷新管理面板
+- 可视化：当前会话启用项、同步状态、最近同步时间都清楚展示
+
+这是一套为手机设计的 Claude Code 控制台。
+---
+
+## 主要功能
+
+### 1. 手机直接接管 Claude Code
+
+- 在手机上连接本机 Claude Code 会话
+- 继续当前任务，而不是重新开始
+- 支持创建、切换、加载、删除会话
+
+### 2. 权限确认与 Plan Mode
+
+- 支持权限请求的允许 / 拒绝
+- 支持 Claude 进入 Plan Mode 后的多轮计划交互
+- 计划、权限、普通输入分流处理
+- 移动端用按钮推进流程，不再依赖 CLI 盲输
+
+### 3. 多文件 Diff 审核
+
+- 按修改组查看待审内容
+- 在同一组内切换多个文件
+- 查看文件内容或 diff
+- 支持 accept / revert / revise
+- 支持一键接受全部待审核 diff
+
+### 4. 文件、日志与运行状态查看
+
+- 浏览项目文件树
+- 读取文件内容
+- 通过 HTTP 下载文件
+- 查看终端执行日志
+- 在不同 execution 间切换 stdout / stderr
+- 查看 runtime info 和 session 历史
+
+### 5. Skill / Memory / Session Context 管理
+
+- Skill 以“胶囊”形式展示，轻点即可执行，长按即可查看详情和修改入口
+- Memory 以“卡片”形式展示，内容、启用状态、来源和同步状态一眼可见
+- 支持一键同步 skill / memory，和本机 Claude 目录保持一致
+- 支持一句话生成 skill、一句话修改 skill / memory
+- 结果可自动回写 catalog，并立即刷新管理面板
+
+### 6. 后台提醒
+
+- 当 Claude 需要你操作时发送提醒
+- 覆盖继续输入、权限确认、Plan Mode、代码审核
+- 通过 action-needed 信号去重，避免重复打扰
+
+### 7. 可选 TTS
+
+- 支持把 Claude 的关键信息转成语音
+- 更适合移动中、通勤中或不方便盯屏的场景
+
+---
+
+## 系统架构
+
+```text
+Mobile browser / Flutter app
+         │
+         ▼
+  MobileVC Go server
+         │
+         ├─ WebSocket event stream
+         ├─ Claude Code runtime / PTY runner
+         ├─ session + projection store
+         └─ Python ChatTTS sidecar (optional)
+```
+
+### Go 后端
+
+- 入口：`cmd/server/main.go`
+- 负责 `/ws`、`/healthz`、`/download`、`/api/tts/synthesize`
+- 通过 WebSocket 驱动完整会话状态流
+- 管理 PTY runner、session store、Skill / Memory、文件系统与 TTS
+
+### Flutter 客户端
+
+- 入口：`mobile_vc/lib/main.dart` -> `mobile_vc/lib/app/app.dart`
+- 根状态由 `SessionController` 驱动
+- 首页是 `SessionHomePage`
+- 负责把后端事件变成手机上可操作的 UI 状态
+
+### 后端协议
+
+Go 后端通过结构化事件流向前端推送状态，例如：
+
+- `runtime_phase`
+- `interaction_request`
+- `session_history`
+- `skill_catalog_result`
+- `memory_list_result`
+- `file_diff`
+- `prompt_request`
+- `agent_state`
+
+---
+
+## 工作原理
+
+1. Flutter 连接 Go 后端 WebSocket
+2. Go 后端启动或恢复 Claude Code 的 PTY 会话
+3. Claude 在执行中发出等待态、权限态、计划态等结构化信号
+4. Flutter 将这些信号渲染成适合手机的操作界面
+5. 用户在手机上批准、继续、回退、审核或输入
+6. 决策再回灌给 Claude，形成完整闭环
+
+这套设计的核心不是“远程操作一台电脑”，而是：
+
+> **让手机成为你操控电脑上 Claude Code 的主入口。**
+
+---
+
+## 快速开始
+
+### 1. 安装 Node 启动器
+
+在仓库根目录执行：
+
+```bash
+npm i
+```
+
+安装后可以直接使用 `mobilevc` 命令。
+
+### 2. 首次启动并配置
+
+第一次运行会提示你输入后端端口和 `AUTH_TOKEN`：
+
+```bash
+mobilevc
+```
+
+也可以随时重新配置：
+
+```bash
+mobilevc setup
+```
+
+### 3. 启动 Go 服务
+
+```bash
+mobilevc start
+```
+
+### 4. 查看状态 / 日志 / 停止
+
+```bash
+mobilevc status
+mobilevc logs
+mobilevc logs --follow
+mobilevc stop
+```
+
+### 5. 健康检查
+
+```bash
+curl http://127.0.0.1:8001/healthz
+```
+
+Smoke test：`AUTH_TOKEN=test ./scripts/test_smoke_flow.sh`，可快速验证后端、WebSocket 与会话主链路是否正常。
+
+### 6. 打开 Web 工作台
+
+```text
+http://127.0.0.1:8001/
+```
+
+### 7. 启动 Claude 会话
+
+```text
+claude
+```
+
+### 仍然支持直接启动 Go 后端
+
+如果你想绕过 Node 启动器，原来的方式仍然可用：
+
+```bash
+AUTH_TOKEN=test go run ./cmd/server
+```
+
+---
+
+## Flutter 客户端
+
+```bash
+cd mobile_vc
+flutter pub get
+flutter run
+```
+
+> 确保 host / port / token 配置正确。
+
+---
+
+## 测试
+
+### Smoke test
+
+Smoke test：`AUTH_TOKEN=test ./scripts/test_smoke_flow.sh`，用于快速验证后端、WebSocket 和会话流是否可用。
+它会连接本地服务并跑一轮最小端到端流程，帮助你确认环境是否正常。
+建议在启动 Go 服务后先跑一次，快速确认 WebSocket、会话流和鉴权都可用。
+
+```bash
+AUTH_TOKEN=test ./scripts/test_smoke_flow.sh
+```
+
+### Go
+
+```bash
+go test ./...
+```
+
+### Flutter
+
+```bash
+cd mobile_vc
+flutter test
+```
+
+---
+
+## 项目结构
+
+```text
+cmd/server/        # Go 服务入口
+internal/          # 后端编排、运行时、协议、存储
+web/               # 浏览器工作台
+mobile_vc/         # Flutter 客户端
+sidecar/chattts/   # 可选 TTS 侧车
+```
+
+---
+
+## English Summary
+
+MobileVC turns your phone into the control center for Claude Code running on your computer.
+
+It is built for the moments when you are away from the keyboard but still need to keep shipping: approve permissions, handle Plan Mode, review diffs, inspect files and logs, resume sessions, and keep the workflow moving.
+
+### What it gives you
+
+- Mobile Claude Code control
+- Permission confirmations
+- Plan Mode handling
+- Multi-file diff review
+- File / log / runtime inspection
+- Session resume and history
+- Skill capsules and memory cards
+- One-tap sync and AI-assisted authoring
+- Skill / Memory / Context management
+- Optional TTS notifications
+
+### The idea
+
+Not a terminal mirror.
+Not a desktop clone.
+
+**A phone-first workflow that lets you operate Claude Code on your computer almost entirely from mobile.**
+
+---

package/bin/mobilevc.js

@@ -0,0 +1,827 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+const { spawn, spawnSync } = require('child_process');
+const http = require('http');
+const net = require('net');
+const qrcode = require('qrcode-terminal');
+
+const PACKAGE_NAME = 'mobilevc';
+const SERVER_BINARY_NAME = process.platform === 'win32' ? 'mobilevc-server.exe' : 'mobilevc-server';
+const STATE_DIR = path.join(os.homedir(), '.mobilevc', 'launcher');
+const LOG_DIR = path.join(os.homedir(), '.mobilevc', 'logs');
+const CONFIG_PATH = path.join(STATE_DIR, 'config.json');
+const STATE_PATH = path.join(STATE_DIR, 'state.json');
+const DEFAULT_PORT = '8001';
+const DEFAULT_LANGUAGE = 'zh';
+
+const PLATFORM_PACKAGES = {
+  'darwin-arm64': '@mobilevc/server-darwin-arm64',
+  'darwin-x64': '@mobilevc/server-darwin-x64',
+  'linux-arm64': '@mobilevc/server-linux-arm64',
+  'linux-x64': '@mobilevc/server-linux-x64',
+  'win32-x64': '@mobilevc/server-win32-x64',
+};
+
+const MESSAGES = {
+  zh: {
+    helpTitle: '🐱 MobileVC 启动器',
+    help: [
+      '用法：',
+      '  mobilevc start     启动 MobileVC 后端（默认）',
+      '  mobilevc restart   重启 MobileVC 后端',
+      '  mobilevc stop      停止已保存的后端进程',
+      '  mobilevc status    查看保存的状态和健康检查',
+      '  mobilevc config    重新配置端口、AUTH_TOKEN 和语言',
+      '  mobilevc logs      打印后端日志（加 --follow 跟随）',
+      '  mobilevc help      显示帮助',
+    ],
+    selectLanguage: '选择语言 / Language [1=中文, 2=English]: ',
+    backendPort: (current) => `后端端口 [${current}]: `,
+    authToken: (current) => current ? 'AUTH_TOKEN [已保存]: ' : 'AUTH_TOKEN: ',
+    savedConfig: (filePath) => `🐈 已保存启动器配置到 ${filePath}`,
+    launcherStateNotFound: '🐱 未找到启动器状态',
+    noSavedBackendProcess: '🐈 没有已保存的后端进程',
+    noLogsFound: '🐱 没有找到日志',
+    invalidPort: '🐱 端口无效',
+    authRequired: '🐈 AUTH_TOKEN 是必填项',
+    startingBackend: (port) => `🐱 正在启动 MobileVC 后端，端口 ${port}`,
+    logFile: (filePath) => `🐈 日志文件：${filePath}`,
+    pid: (pid) => `PID: ${pid}`,
+    alreadyRunning: (pid, port) => `MobileVC 已在运行（pid ${pid}，端口 ${port}）`,
+    backendNotRunning: '后端进程未运行',
+    stoppedBackend: '已停止 MobileVC 后端',
+    statusPid: 'pid',
+    statusPort: '端口',
+    statusAlive: '存活',
+    statusHealthz: '健康检查',
+    statusStartedAt: '启动时间',
+    statusLogPath: '日志路径',
+    statusBinaryPath: 'binaryPath',
+    statusPlatformTarget: 'platformTarget',
+    statusServerVersion: 'serverVersion',
+    statusClaudeAvailable: 'Claude CLI 可用',
+    statusHomeWritable: 'HOME 可写',
+    statusPreflight: 'preflight',
+    qrTitle: '扫码连接局域网地址',
+    qrHint: '手机扫一扫，直接读取当前局域网地址和端口',
+    localAccess: '本机访问',
+    lanAccess: '局域网访问',
+    qrUnavailable: '未检测到可用的局域网 IPv4 地址，暂时无法生成二维码',
+    preflightTitle: '启动前检查',
+    preflightBlocking: '阻塞项',
+    preflightWarnings: '提示项',
+    preflightOk: '无',
+    missingBinaryForPlatform: (target) => `当前平台 ${target} 没有可用的预编译 server 包`,
+    binaryMissing: (filePath) => `未找到 server binary：${filePath}`,
+    binaryNotExecutable: (filePath) => `server binary 不可执行：${filePath}`,
+    homeNotWritable: (homePath) => `HOME 不可写：${homePath}`,
+    authTokenMissing: '未配置 AUTH_TOKEN，请先运行 mobilevc config',
+    claudeMissing: '未检测到 Claude CLI；后端仍可启动，但无法执行 Claude 会话',
+    portInUse: (port) => `端口 ${port} 已被其他进程占用`,
+    startupFailed: '启动失败，请检查日志和 preflight 提示',
+    statusUnavailable: '未知',
+  },
+  en: {
+    helpTitle: '🐱 MobileVC launcher',
+    help: [
+      'Usage:',
+      '  mobilevc start     Start the MobileVC backend (default)',
+      '  mobilevc restart   Restart the MobileVC backend',
+      '  mobilevc stop      Stop the saved backend process',
+      '  mobilevc status    Show saved launcher state and health',
+      '  mobilevc config    Reconfigure the backend port, AUTH_TOKEN, and language',
+      '  mobilevc logs      Print backend logs (use --follow to tail)',
+      '  mobilevc help      Show this help',
+    ],
+    selectLanguage: 'Select language / Language [1=中文, 2=English]: ',
+    backendPort: (current) => `Backend port [${current}]: `,
+    authToken: (current) => current ? 'AUTH_TOKEN [saved]: ' : 'AUTH_TOKEN: ',
+    savedConfig: (filePath) => `🐈 Saved launcher config to ${filePath}`,
+    launcherStateNotFound: '🐱 Launcher state not found',
+    noSavedBackendProcess: '🐈 No saved backend process',
+    noLogsFound: '🐱 No logs found',
+    invalidPort: '🐱 Invalid port',
+    authRequired: '🐈 AUTH_TOKEN is required',
+    startingBackend: (port) => `🐱 Starting MobileVC backend on port ${port}`,
+    logFile: (filePath) => `🐈 Log file: ${filePath}`,
+    pid: (pid) => `PID: ${pid}`,
+    alreadyRunning: (pid, port) => `MobileVC is already running (pid ${pid} on port ${port})`,
+    backendNotRunning: 'Backend process is not running',
+    stoppedBackend: 'Stopped MobileVC backend',
+    statusPid: 'pid',
+    statusPort: 'port',
+    statusAlive: 'alive',
+    statusHealthz: 'healthz',
+    statusStartedAt: 'startedAt',
+    statusLogPath: 'logPath',
+    statusBinaryPath: 'binaryPath',
+    statusPlatformTarget: 'platformTarget',
+    statusServerVersion: 'serverVersion',
+    statusClaudeAvailable: 'Claude CLI available',
+    statusHomeWritable: 'HOME writable',
+    statusPreflight: 'preflight',
+    qrTitle: 'Scan to open over LAN',
+    qrHint: 'Scan with your phone to open the current LAN IP and port',
+    localAccess: 'Local access',
+    lanAccess: 'LAN access',
+    qrUnavailable: 'No available LAN IPv4 address was detected, so no QR code was generated',
+    preflightTitle: 'Preflight',
+    preflightBlocking: 'Blocking',
+    preflightWarnings: 'Warnings',
+    preflightOk: 'none',
+    missingBinaryForPlatform: (target) => `No precompiled server package is available for ${target}`,
+    binaryMissing: (filePath) => `Server binary not found: ${filePath}`,
+    binaryNotExecutable: (filePath) => `Server binary is not executable: ${filePath}`,
+    homeNotWritable: (homePath) => `HOME is not writable: ${homePath}`,
+    authTokenMissing: 'AUTH_TOKEN is missing. Run mobilevc config first.',
+    claudeMissing: 'Claude CLI was not found. The backend can start, but Claude sessions will not run.',
+    portInUse: (port) => `Port ${port} is already in use`,
+    startupFailed: 'Startup failed. Check the log and preflight output.',
+    statusUnavailable: 'unknown',
+  },
+};
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] && !args[0].startsWith('-') ? args[0] : 'start';
+  const options = parseOptions(args.slice(args[0] && args[0].startsWith('-') ? 0 : 1));
+
+  if (options.help || command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'setup' || command === 'config') {
+    runSetup(true).catch(exitWithError);
+    return;
+  }
+
+  if (command === 'status') {
+    runStatus().catch(exitWithError);
+    return;
+  }
+
+  if (command === 'stop') {
+    runStop().catch(exitWithError);
+    return;
+  }
+
+  if (command === 'restart') {
+    runRestart(options).catch(exitWithError);
+    return;
+  }
+
+  if (command === 'logs') {
+    runLogs(options).catch(exitWithError);
+    return;
+  }
+
+  if (command === 'start') {
+    runStart(options).catch(exitWithError);
+    return;
+  }
+
+  printHelp();
+}
+
+function parseOptions(args) {
+  const options = { help: false, follow: false };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--follow' || arg === '-f') options.follow = true;
+  }
+  return options;
+}
+
+function printHelp() {
+  const language = readJson(CONFIG_PATH, null)?.language || DEFAULT_LANGUAGE;
+  const bundle = MESSAGES[language] || MESSAGES[DEFAULT_LANGUAGE];
+  console.log(bundle.helpTitle);
+  console.log('');
+  console.log(bundle.help.join('\n'));
+}
+
+async function runSetup(forcePrompt) {
+  ensureDir(STATE_DIR, 0o700);
+  ensureDir(LOG_DIR, 0o700);
+
+  const current = readJson(CONFIG_PATH, null);
+  const currentLanguage = current?.language || DEFAULT_LANGUAGE;
+  const language = await askLanguage(forcePrompt || !current, currentLanguage);
+  const port = await askPort(language, forcePrompt || !current);
+  const authToken = await askToken(language, forcePrompt || !current);
+
+  writeJson(CONFIG_PATH, { language, port, authToken });
+  console.log(message(language, 'savedConfig', CONFIG_PATH));
+}
+
+async function runStart(_options) {
+  ensureDir(STATE_DIR, 0o700);
+  ensureDir(LOG_DIR, 0o700);
+
+  let config = readJson(CONFIG_PATH, null);
+  if (!config) {
+    await runSetup(false);
+    config = readJson(CONFIG_PATH, null);
+  }
+
+  const language = config?.language || DEFAULT_LANGUAGE;
+  const existingState = readJson(STATE_PATH, null);
+  if (existingState?.pid && isPidAlive(existingState.pid)) {
+    console.log(message(language, 'alreadyRunning', existingState.pid, existingState.port));
+    return;
+  }
+
+  const platformTarget = getPlatformTarget();
+  const binaryInfo = resolveBinaryInfo(platformTarget);
+  const preflight = await runPreflightChecks({ config, language, platformTarget, binaryInfo });
+  printPreflight(language, preflight);
+
+  if (preflight.blocking.length > 0) {
+    const state = buildStateSkeleton(config, language, binaryInfo, platformTarget, preflight, null);
+    writeJson(STATE_PATH, state);
+    throw new Error(preflight.blocking[0]);
+  }
+
+  const logPath = path.join(LOG_DIR, `mobilevc-${timestampForFile()}.log`);
+  fs.writeFileSync(logPath, '', { mode: 0o600 });
+  try {
+    fs.chmodSync(logPath, 0o600);
+  } catch (_) {}
+
+  const env = {
+    ...process.env,
+    PORT: String(config.port),
+    AUTH_TOKEN: String(config.authToken),
+  };
+
+  fs.appendFileSync(logPath, `launcher starting binary=${binaryInfo.binaryPath} target=${platformTarget}\n`);
+  const child = spawn(binaryInfo.binaryPath, [], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+
+  if (child.stdout) {
+    child.stdout.pipe(fs.createWriteStream(logPath, { flags: 'a', mode: 0o600 }));
+  }
+  if (child.stderr) {
+    child.stderr.pipe(fs.createWriteStream(logPath, { flags: 'a', mode: 0o600 }));
+  }
+
+  child.on('error', (err) => {
+    fs.appendFileSync(logPath, `launcher error: ${err.stack || err.message}\n`);
+  });
+
+  const versionInfo = await waitForServerVersion(config.port, 10000);
+  const state = {
+    ...buildStateSkeleton(config, language, binaryInfo, platformTarget, preflight, logPath),
+    pid: child.pid,
+    startedAt: new Date().toISOString(),
+    serverVersion: formatVersionInfo(versionInfo),
+    serverVersionRaw: versionInfo,
+  };
+  writeJson(STATE_PATH, state);
+
+  child.unref();
+  console.log(message(language, 'startingBackend', state.port));
+  console.log(message(language, 'logFile', logPath));
+  console.log(message(language, 'pid', child.pid));
+  if (!await checkHealth(state.port)) {
+    throw new Error(message(language, 'startupFailed'));
+  }
+  await printLanQr(language, state.port, state.authToken);
+}
+
+async function runStatus() {
+  const state = readJson(STATE_PATH, null);
+  const config = readJson(CONFIG_PATH, null);
+  const language = state?.language || config?.language || DEFAULT_LANGUAGE;
+  if (!state) {
+    console.log(message(language, 'launcherStateNotFound'));
+    return;
+  }
+
+  const platformTarget = state.platformTarget || getPlatformTarget();
+  const binaryInfo = resolveBinaryInfo(platformTarget);
+  const alive = state.pid ? isPidAlive(state.pid) : false;
+  const healthy = alive ? await checkHealth(state.port) : false;
+  const versionInfo = healthy ? await fetchServerVersion(state.port) : null;
+  const claudeAvailable = detectClaudeAvailability();
+  const homeWritable = isHomeWritable();
+
+  console.log(`${message(language, 'statusPid')}: ${state.pid || '-'}`);
+  console.log(`${message(language, 'statusPort')}: ${state.port || '-'}`);
+  console.log(`${message(language, 'statusAlive')}: ${alive}`);
+  console.log(`${message(language, 'statusHealthz')}: ${healthy}`);
+  console.log(`${message(language, 'statusStartedAt')}: ${state.startedAt || '-'}`);
+  console.log(`${message(language, 'statusLogPath')}: ${state.logPath || '-'}`);
+  console.log(`${message(language, 'statusBinaryPath')}: ${state.binaryPath || binaryInfo.binaryPath || '-'}`);
+  console.log(`${message(language, 'statusPlatformTarget')}: ${platformTarget}`);
+  console.log(`${message(language, 'statusServerVersion')}: ${formatVersionInfo(versionInfo) || state.serverVersion || '-'}`);
+  console.log(`${message(language, 'statusClaudeAvailable')}: ${claudeAvailable}`);
+  console.log(`${message(language, 'statusHomeWritable')}: ${homeWritable}`);
+  console.log(`${message(language, 'statusPreflight')}: ${summarizePreflight(state.preflight, language)}`);
+}
+
+async function runStop(options = {}) {
+  const state = readJson(STATE_PATH, null);
+  const language = options.language || state?.language || DEFAULT_LANGUAGE;
+  if (!state?.pid) {
+    if (!options.silent) {
+      console.log(message(language, 'noSavedBackendProcess'));
+    }
+    return false;
+  }
+
+  if (!isPidAlive(state.pid)) {
+    clearState();
+    if (!options.silent) {
+      console.log(message(language, 'backendNotRunning'));
+    }
+    return false;
+  }
+
+  killProcessGroup(state.pid, 'SIGTERM');
+
+  await waitForExit(state.pid, 4000);
+  if (isPidAlive(state.pid)) {
+    killProcessGroup(state.pid, 'SIGKILL');
+    await waitForExit(state.pid, 2000);
+  }
+
+  clearState();
+  if (!options.silent) {
+    console.log(message(language, 'stoppedBackend'));
+  }
+  return true;
+}
+
+async function runRestart(options) {
+  const state = readJson(STATE_PATH, null);
+  const language = state?.language || readJson(CONFIG_PATH, null)?.language || DEFAULT_LANGUAGE;
+  await runStop({ silent: true, language });
+  await runStart(options);
+}
+
+async function runLogs(options) {
+  ensureDir(LOG_DIR, 0o700);
+  const files = fs.readdirSync(LOG_DIR)
+    .filter((file) => file.endsWith('.log'))
+    .map((file) => path.join(LOG_DIR, file))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+
+  const state = readJson(STATE_PATH, null);
+  const language = state?.language || DEFAULT_LANGUAGE;
+  if (files.length === 0) {
+    console.log(message(language, 'noLogsFound'));
+    return;
+  }
+
+  const latest = files[0];
+  if (options.follow) {
+    followFile(latest);
+    return;
+  }
+
+  process.stdout.write(fs.readFileSync(latest, 'utf8'));
+}
+
+function resolveBinaryInfo(platformTarget) {
+  const packageName = PLATFORM_PACKAGES[platformTarget] || null;
+  const packageRoot = packageName ? resolveInstalledPackageRoot(packageName) : null;
+  const binaryPath = packageRoot ? path.join(packageRoot, 'bin', SERVER_BINARY_NAME) : null;
+  return { packageName, packageRoot, binaryPath };
+}
+
+function resolveInstalledPackageRoot(packageName) {
+  try {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`, { paths: [__dirname] });
+    return path.dirname(packageJsonPath);
+  } catch (_) {
+    return null;
+  }
+}
+
+function getPlatformTarget() {
+  return `${process.platform}-${process.arch}`;
+}
+
+async function runPreflightChecks({ config, language, platformTarget, binaryInfo }) {
+  const blocking = [];
+  const warnings = [];
+
+  if (!binaryInfo.packageName) {
+    blocking.push(message(language, 'missingBinaryForPlatform', platformTarget));
+  } else if (!binaryInfo.binaryPath || !fs.existsSync(binaryInfo.binaryPath)) {
+    blocking.push(message(language, 'binaryMissing', binaryInfo.binaryPath || `${binaryInfo.packageName}/bin/${SERVER_BINARY_NAME}`));
+  } else if (!isBinaryExecutable(binaryInfo.binaryPath)) {
+    blocking.push(message(language, 'binaryNotExecutable', binaryInfo.binaryPath));
+  }
+
+  if (!String(config?.authToken || '').trim()) {
+    blocking.push(message(language, 'authTokenMissing'));
+  }
+
+  if (!isHomeWritable()) {
+    blocking.push(message(language, 'homeNotWritable', os.homedir()));
+  }
+
+  if (await isPortOccupied(String(config?.port || DEFAULT_PORT))) {
+    blocking.push(message(language, 'portInUse', String(config?.port || DEFAULT_PORT)));
+  }
+
+  if (!detectClaudeAvailability()) {
+    warnings.push(message(language, 'claudeMissing'));
+  }
+
+  return { blocking, warnings };
+}
+
+function printPreflight(language, preflight) {
+  console.log(`${message(language, 'preflightTitle')}:`);
+  console.log(`  ${message(language, 'preflightBlocking')}: ${formatList(preflight.blocking, language)}`);
+  console.log(`  ${message(language, 'preflightWarnings')}: ${formatList(preflight.warnings, language)}`);
+}
+
+function formatList(items, language) {
+  if (!items || items.length === 0) {
+    return message(language, 'preflightOk');
+  }
+  return items.join(' | ');
+}
+
+function buildStateSkeleton(config, language, binaryInfo, platformTarget, preflight, logPath) {
+  return {
+    pid: null,
+    port: String(config.port),
+    authToken: String(config.authToken),
+    language,
+    startedAt: null,
+    logPath,
+    binaryPath: binaryInfo.binaryPath,
+    platformTarget,
+    serverVersion: null,
+    preflight,
+  };
+}
+
+function detectClaudeAvailability() {
+  const result = spawnSync('claude', ['--version'], { stdio: 'ignore' });
+  return result.status === 0 || result.error == null;
+}
+
+function isHomeWritable() {
+  try {
+    fs.accessSync(os.homedir(), fs.constants.W_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function isBinaryExecutable(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch (_) {
+    return process.platform === 'win32' && fs.existsSync(filePath);
+  }
+}
+
+function isPortOccupied(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err && err.code === 'EADDRINUSE') {
+        resolve(true);
+        return;
+      }
+      resolve(false);
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(false));
+    });
+    server.listen(Number(port), '127.0.0.1');
+  });
+}
+
+function waitForServerVersion(port, timeoutMs) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const timer = setInterval(async () => {
+      if (Date.now() - started >= timeoutMs) {
+        clearInterval(timer);
+        resolve(null);
+        return;
+      }
+      const info = await fetchServerVersion(port);
+      if (info) {
+        clearInterval(timer);
+        resolve(info);
+      }
+    }, 500);
+  });
+}
+
+function fetchServerVersion(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ hostname: '127.0.0.1', port: Number(port), path: '/version', timeout: 1500 }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          resolve(null);
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (_) {
+          resolve(null);
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.on('error', () => resolve(null));
+  });
+}
+
+function formatVersionInfo(info) {
+  if (!info || !info.version) {
+    return null;
+  }
+  const extras = [];
+  if (info.commit && info.commit !== 'unknown') extras.push(info.commit);
+  if (info.buildDate && info.buildDate !== 'unknown') extras.push(info.buildDate);
+  return extras.length > 0 ? `${info.version} (${extras.join(', ')})` : info.version;
+}
+
+function summarizePreflight(preflight, language) {
+  if (!preflight) {
+    return message(language, 'statusUnavailable');
+  }
+  return `blocking=${preflight.blocking?.length || 0}, warnings=${preflight.warnings?.length || 0}`;
+}
+
+function followFile(filePath) {
+  let lastSize = 0;
+  process.stdout.write(fs.readFileSync(filePath, 'utf8'));
+  lastSize = fs.statSync(filePath).size;
+  const timer = setInterval(() => {
+    if (!fs.existsSync(filePath)) return;
+    const stat = fs.statSync(filePath);
+    if (stat.size > lastSize) {
+      const stream = fs.createReadStream(filePath, { start: lastSize, end: stat.size });
+      stream.pipe(process.stdout, { end: false });
+      lastSize = stat.size;
+    }
+  }, 1000);
+
+  process.on('SIGINT', () => {
+    clearInterval(timer);
+    process.exit(0);
+  });
+}
+
+async function askLanguage(force, currentLanguage) {
+  if (!force && currentLanguage) {
+    return currentLanguage;
+  }
+  const selection = await promptInput(message(DEFAULT_LANGUAGE, 'selectLanguage'));
+  const normalized = String(selection || '').trim().toLowerCase();
+  if (normalized === '2' || normalized === 'en' || normalized === 'english') {
+    return 'en';
+  }
+  return 'zh';
+}
+
+async function askPort(language, force) {
+  const current = !force ? readJson(CONFIG_PATH, null)?.port : null;
+  const prompt = current ? message(language, 'backendPort', current) : message(language, 'backendPort', DEFAULT_PORT);
+  const value = await promptInput(prompt);
+  const port = String((value || current || DEFAULT_PORT).trim());
+  if (!/^\d+$/.test(port) || Number(port) <= 0 || Number(port) > 65535) {
+    throw new Error(message(language, 'invalidPort'));
+  }
+  return port;
+}
+
+async function askToken(language, force) {
+  const current = !force ? readJson(CONFIG_PATH, null)?.authToken : null;
+  const prompt = current ? message(language, 'authToken', true) : message(language, 'authToken', false);
+  const value = await promptInput(prompt, true);
+  const token = String((value || current || '').trim());
+  if (!token) {
+    throw new Error(message(language, 'authRequired'));
+  }
+  return token;
+}
+
+function message(language, key, ...args) {
+  const bundle = MESSAGES[language] || MESSAGES[DEFAULT_LANGUAGE];
+  const value = bundle[key];
+  return typeof value === 'function' ? value(...args) : value;
+}
+
+async function printLanQr(language, port, authToken = '') {
+  const host = await detectLanHost();
+  const localUrl = buildLaunchUrl('127.0.0.1', port, authToken);
+  console.log('');
+  console.log(`${message(language, 'localAccess')}: ${localUrl}`);
+
+  if (!host) {
+    console.log(message(language, 'qrUnavailable'));
+    return;
+  }
+
+  const url = buildLaunchUrl(host, port, authToken);
+  console.log(`${message(language, 'lanAccess')}: ${url}`);
+  console.log('');
+  console.log(message(language, 'qrTitle'));
+  renderTerminalQr(url);
+  console.log(message(language, 'qrHint'));
+}
+
+function renderTerminalQr(text) {
+  qrcode.generate(text, { small: true }, (qr) => {
+    const output = String(qr || '').replace(/\s+$/, '');
+    const lines = output.split('\n');
+    const widenedLines = lines.map((line) => widenQrLine(line));
+    const indent = '';
+    console.log(widenedLines.map((line) => `${indent}${line}`).join('\n'));
+  });
+}
+
+function widenQrLine(line) {
+  return Array.from(String(line || '')).map((char) => char.repeat(2)).join('');
+}
+
+function buildLaunchUrl(host, port, authToken = '') {
+  const url = new URL(`http://${host}:${port}/`);
+  if (authToken) {
+    url.searchParams.set('token', authToken);
+  }
+  return url.toString();
+}
+
+async function detectLanHost() {
+  const interfaces = os.networkInterfaces();
+  const wifi = [];
+  const wired = [];
+  const other = [];
+
+  for (const [name, entries] of Object.entries(interfaces)) {
+    if (!entries) continue;
+    for (const entry of entries) {
+      if (!entry || entry.family !== 'IPv4' || entry.internal) {
+        continue;
+      }
+      if (isLinkLocalIpv4(entry.address)) {
+        continue;
+      }
+
+      const lowered = name.toLowerCase();
+      if (/^(en0|wl|wlan|wifi|wi-?fi)/.test(lowered)) {
+        wifi.push(entry.address);
+      } else if (/^(en|eth)/.test(lowered)) {
+        wired.push(entry.address);
+      } else {
+        other.push(entry.address);
+      }
+    }
+  }
+
+  return wifi[0] || wired[0] || other[0] || null;
+}
+
+function isLinkLocalIpv4(address) {
+  return /^169\.254\./.test(address);
+}
+
+function promptInput(question, silent = false) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+    });
+    if (silent) {
+      rl.stdoutMuted = true;
+      rl._writeToOutput = function _writeToOutput(stringToWrite) {
+        if (!rl.stdoutMuted) {
+          rl.output.write(stringToWrite);
+          return;
+        }
+        const text = String(stringToWrite || '');
+        if (!text) return;
+        if (/\r?\n$/.test(text) || /:\s*$/.test(text) || /\]\s*$/.test(text)) {
+          rl.output.write(text);
+        }
+      };
+    }
+    rl.question(question, (answer) => {
+      rl.close();
+      process.stdout.write('\n');
+      resolve(answer);
+    });
+  });
+}
+
+function ensureDir(dir, mode) {
+  fs.mkdirSync(dir, { recursive: true, mode });
+  try {
+    fs.chmodSync(dir, mode);
+  } catch (_) {}
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch (_) {}
+}
+
+function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    return fallback;
+  }
+}
+
+function clearState() {
+  try {
+    fs.unlinkSync(STATE_PATH);
+  } catch (_) {}
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code !== 'ESRCH';
+  }
+}
+
+function killProcessGroup(pid, signal) {
+  const targets = process.platform === 'win32' ? [pid] : [-pid, pid];
+  for (const target of targets) {
+    try {
+      process.kill(target, signal);
+      return;
+    } catch (err) {
+      if (err.code !== 'ESRCH' && err.code !== 'EINVAL') {
+        throw err;
+      }
+    }
+  }
+}
+
+function waitForExit(pid, timeoutMs) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const timer = setInterval(() => {
+      if (!isPidAlive(pid) || Date.now() - started >= timeoutMs) {
+        clearInterval(timer);
+        resolve();
+      }
+    }, 250);
+  });
+}
+
+function checkHealth(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ hostname: '127.0.0.1', port: Number(port), path: '/healthz', timeout: 1500 }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve(res.statusCode === 200 && body.trim() === 'ok'));
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on('error', () => resolve(false));
+  });
+}
+
+function timestampForFile() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function exitWithError(err) {
+  console.error(err.message || err);
+  process.exit(1);
+}
+
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@justprove/mobilevc",
+  "version": "0.1.0",
+  "description": "Claude Code mobile workspace launcher with precompiled MobileVC backend binaries.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "mobilevc": "bin/mobilevc.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node ./bin/mobilevc.js",
+    "install:cmd": "npm install -g .",
+    "remove:cmd": "npm uninstall -g mobilevc",
+    "link:cmd": "npm link",
+    "unlink:cmd": "npm unlink -g mobilevc",
+    "sync:web": "node ./scripts/sync-embedded-web.js",
+    "build:binaries": "node ./scripts/build-npm-binaries.js"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
+  "optionalDependencies": {
+    "@mobilevc/server-darwin-arm64": "0.1.0",
+    "@mobilevc/server-darwin-x64": "0.1.0",
+    "@mobilevc/server-linux-arm64": "0.1.0",
+    "@mobilevc/server-linux-x64": "0.1.0",
+    "@mobilevc/server-win32-x64": "0.1.0"
+  }
+}