code-server-sync 0.0.0-stage → 0.1.0

package/cs_sync/cli.py

@@ -0,0 +1,650 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import posixpath
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from cs_sync.client import Client, check_ready, explain_http, origin_of, ssl_context
+from cs_sync.config import (
+    compose,
+    ensure_config,
+    load_host,
+    load_json,
+    next_port,
+    project_filename,
+    project_files,
+    project_paths,
+    projects_dir,
+    save_config,
+    save_host,
+    valid_name,
+)
+from cs_sync.files import file_mode, remove_file, write_file
+from cs_sync.git import StageError, collect_changes, stage_changes, transfer_line_changes
+from cs_sync.ignore import DEFAULT_IGNORE_DIRS, ignore_dirs, load_path_ignore, should_skip
+from cs_sync.protocol import DEFAULT_PORT, eprint
+from cs_sync.server import serve
+from cs_sync.sync import (
+    copy_cloud_to_local,
+    copy_local_to_cloud,
+    is_dry_run,
+    load_remote_base,
+    preview_copy_cloud_to_local,
+    preview_copy_local_to_cloud,
+    preview_line_changes,
+    preview_sync_divergence,
+    print_dry_run_banner,
+    watch,
+)
+
+def command_text(config: dict, command: str) -> str:
+    text = "cs-sync %s" % command
+    if config.get("name"):
+        text += " --name %s" % config["name"]
+    return text
+
+
+def shell_quote(value: str) -> str:
+    return "'" + str(value).replace("'", "'\"'\"'") + "'"
+
+
+def normalize_remote_path(path: str) -> str:
+    text = str(path or "").strip().replace("\\", "/")
+    if not text.startswith("/") or text.startswith("//"):
+        raise SystemExit("云端路径必须是绝对路径。")
+    text = posixpath.normpath(text)
+    if not text.startswith("/"):
+        raise SystemExit("云端路径必须是绝对路径。")
+    return text
+
+
+def recv_command(config: dict) -> str:
+    return "cs-sync recv --root %s --token %s --port %d" % (
+        shell_quote(config["remoteRoot"]),
+        shell_quote(config["token"]),
+        int(config["port"]),
+    )
+
+
+def ensure_host_base(base: str = "") -> dict:
+    host = load_host()
+    if base:
+        parts = urllib.parse.urlsplit(base)
+        if parts.scheme not in ("http", "https") or not parts.netloc:
+            raise SystemExit("--base 需要写成 https://主机:端口")
+        host["baseUrl"] = urllib.parse.urlunsplit((parts.scheme, parts.netloc, "", "", ""))
+        host["insecure"] = host.get("insecure", parts.scheme == "https")
+        save_host(host)
+        return host
+    if host.get("baseUrl"):
+        return host
+    for path in project_files().values():
+        endpoint = str(load_json(path).get("endpoint") or "")
+        if not endpoint:
+            continue
+        host["baseUrl"] = origin_of(endpoint)
+        host["insecure"] = endpoint.startswith("https://")
+        save_host(host)
+        return host
+    raise SystemExit("还没有 code-server 地址。加上 --base https://主机:端口")
+
+
+def selected(args: argparse.Namespace) -> dict:
+    return ensure_config(getattr(args, "name", "") or "", getattr(args, "config", "") or "")
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    import secrets
+
+    if not args.local or not args.remote:
+        raise SystemExit("需要 --local 本地目录 和 --remote 云端绝对路径")
+    local = os.path.abspath(os.path.expanduser(args.local))
+    if not os.path.isdir(local):
+        raise SystemExit("本地目录不存在: %s" % local)
+    remote = normalize_remote_path(args.remote)
+    name = args.name or os.path.basename(local.rstrip(os.sep))
+    if not valid_name(name):
+        raise SystemExit("项目名只能包含字母、数字、点、下划线和中划线，并用 --name 指定")
+    files = project_files()
+    if name in files and not args.force:
+        raise SystemExit("项目 %s 已存在。换一个 --name，或加上 --force 覆盖" % name)
+    ensure_host_base(args.base or "")
+    port = args.port or next_port()
+    project = {
+        "name": name,
+        "localRoot": local,
+        "remoteRoot": remote,
+        "port": port,
+        "token": secrets.token_urlsafe(32),
+        "ignoreDirs": sorted(DEFAULT_IGNORE_DIRS),
+    }
+    path = os.path.join(projects_dir(), project_filename(name))
+    save_config(path, project)
+    if args.force:
+        for old in project_paths().get(name, []):
+            if os.path.abspath(old) != os.path.abspath(path):
+                os.remove(old)
+    config = compose(load_host(), project)
+    print("已添加项目 %s" % name)
+    print("本地: %s" % local)
+    print("云端: %s" % remote)
+    print("在云主机的 code-server 终端执行:")
+    print(recv_command(config))
+
+
+def cmd_remove(args: argparse.Namespace) -> None:
+    name = args.name
+    if not name:
+        raise SystemExit("请用 --name 指定要删除的项目。先运行 list 查看名称。")
+    paths = project_paths()
+    if name not in paths:
+        known = "、".join(sorted(paths)) or "（无）"
+        raise SystemExit("没有名为 %s 的项目。已有: %s" % (name, known))
+    for path in paths[name]:
+        os.remove(path)
+        print("已删除映射 %s" % path)
+    print("项目 %s 已从列表移除。本地目录和云端代码都还在。" % name)
+
+
+def cmd_list(_args: argparse.Namespace) -> None:
+    files = project_files()
+    if not files:
+        print("还没有项目。")
+        return
+    host = load_host()
+    base = host.get("baseUrl") or ""
+    if not base:
+        for path in files.values():
+            endpoint = str(load_json(path).get("endpoint") or "")
+            if endpoint:
+                base = origin_of(endpoint)
+                break
+    print("code-server: %s" % (base or "（未设置）"))
+    print("登录: %s" % ("这台 code-server 不校验登录" if host.get("auth") == "none" else ("已保存" if host.get("cookie") else "未登录")))
+    for name in sorted(files):
+        config = compose(host, load_json(files[name]))
+        print("%s  端口 %s  本地 %s  云端 %s" % (name, config.get("port"), config.get("localRoot"), config.get("remoteRoot")))
+
+
+def cmd_token(args: argparse.Namespace) -> None:
+    config = selected(args)
+    if not config.get("token"):
+        raise SystemExit("token 为空")
+    print(recv_command(config))
+
+
+def cmd_login(args: argparse.Namespace) -> None:
+    import getpass
+    import http.cookiejar
+
+    host = ensure_host_base(getattr(args, "base", "") or "")
+    password = str(host.get("password") or "")
+    if password:
+        print("使用已保存的密码登录。")
+    else:
+        password = getpass.getpass("code-server 登录密码: ")
+    origin = host["baseUrl"].rstrip("/")
+    data = urllib.parse.urlencode({"password": password, "base": ""}).encode()
+    request = urllib.request.Request(origin + "/login", data=data, method="POST")
+    jar = http.cookiejar.CookieJar()
+    context = ssl_context(bool(host.get("insecure", True)))
+    handlers = [
+        urllib.request.HTTPCookieProcessor(jar),
+        urllib.request.HTTPSHandler(context=context),
+    ]
+    opener = urllib.request.build_opener(*handlers)
+    try:
+        with opener.open(request, timeout=30) as response:
+            body = response.read()
+            final_status = response.status
+    except urllib.error.HTTPError as exc:
+        body = exc.read()
+        final_status = exc.code
+    except urllib.error.URLError as exc:
+        raise SystemExit("连不上 code-server：%s" % exc.reason)
+    session = ""
+    for cookie in jar:
+        if cookie.name == "code-server-session":
+            session = "code-server-session=%s" % cookie.value
+            break
+    if session:
+        host["cookie"] = session
+        host["auth"] = "password"
+        save_host(host)
+        print("登录凭证已保存，之后每个项目共用。")
+        return
+    try:
+        with urllib.request.urlopen(urllib.request.Request(origin + "/"), context=context, timeout=30) as response:
+            page = response.read(4000)
+            open_status = response.status
+    except urllib.error.URLError as exc:
+        raise SystemExit("连不上 code-server：%s" % exc.reason)
+    if open_status == 200 and b"vscode-workbench-web-configuration" in page:
+        host["auth"] = "none"
+        host["cookie"] = ""
+        save_host(host)
+        print("这台 code-server 不校验登录，直接运行 doctor 或 sync 即可。")
+        return
+    preview = body.decode("utf-8", errors="replace")[:160].replace("\n", " ")
+    raise SystemExit("登录没有拿到 code-server-session（状态 %d）。%s" % (final_status, preview))
+
+
+def cmd_cookie(args: argparse.Namespace) -> None:
+    host = ensure_host_base(getattr(args, "base", "") or "")
+    value = args.value.strip()
+    if not value.startswith("code-server-session="):
+        value = "code-server-session=" + value
+    host["cookie"] = value
+    save_host(host)
+    print("登录凭证已保存，之后每个项目共用。")
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    config = selected(args)
+    client = Client(config)
+    label = config.get("name") or config.get("localRoot")
+    print("项目: %s" % label)
+    print("端点: %s" % client.endpoint)
+    print("cookie: %s" % ("已填写" if client.cookie else "空"))
+    check_ready(client)
+    print("通道和令牌都可用。")
+
+
+def report_copy(action: str, done: int, skipped: int, failed: int, leftover: str) -> None:
+    print("完成：%s %d 个，相同跳过 %d 个。" % (action, done, skipped), flush=True)
+    print(leftover, flush=True)
+    if failed:
+        raise SystemExit("有 %d 个文件没有同步过去。" % failed)
+
+
+def stage_local_side(local_root: str, ignored: set) -> None:
+    try:
+        stage_changes(local_root, ignored)
+    except StageError as exc:
+        raise SystemExit(str(exc))
+
+
+def stage_cloud_side(client: Client, config: dict, command: str) -> None:
+    stage_status, stage_info = client.stage()
+    if stage_status == 404:
+        raise SystemExit("云端接收程序不支持暂存。请在云端升级 code-server-sync 并重启 cs-sync recv，然后再运行 %s。" % command_text(config, command))
+    if stage_status != 200 or not stage_info:
+        raise SystemExit("云端暂存失败：%s" % explain_http(stage_status, b""))
+    staged = [str(item) for item in stage_info.get("staged") or []]
+    if not stage_info.get("repos"):
+        print("云端项目里没有 git 仓库，跳过暂存。", flush=True)
+    elif staged:
+        for rel in staged:
+            print("云端暂存 %s" % rel, flush=True)
+    else:
+        print("云端没有需要暂存的修改。", flush=True)
+
+
+def cmd_to_cloud(args: argparse.Namespace) -> None:
+    config = selected(args)
+    label = config.get("name") or config.get("localRoot")
+    dry = is_dry_run(args)
+    if dry:
+        print_dry_run_banner("to-cloud")
+    print("把本地内容同步到云主机：%s" % label, flush=True)
+    local_root = config["localRoot"]
+    if not os.path.isdir(local_root):
+        raise SystemExit("本地目录不存在: %s" % local_root)
+    client = Client(config)
+    check_ready(client)
+    ignored = ignore_dirs(config)
+    path_ignore = load_path_ignore(local_root)
+    print("已连上 %s" % client.endpoint, flush=True)
+    if dry:
+        ignore_status = 200
+        print("演练模式跳过：推送忽略规则、云端暂存。", flush=True)
+    else:
+        ignore_status, _ignore_body = client.push_ignore(ignored)
+        stage_cloud_side(client, config, "to-cloud")
+    remote, enabled = load_remote_base(client, ignored, ignore_status, path_ignore)
+    if not enabled:
+        print("云端还是旧的接收程序，将把全部未忽略文件同步到云端。", flush=True)
+    if dry:
+        uploaded, skipped, failed = preview_copy_local_to_cloud(local_root, ignored, remote if enabled else None)
+        if failed:
+            raise SystemExit("演练发现 %d 个无法处理的文件。" % failed)
+        return
+    uploaded, skipped, failed = copy_local_to_cloud(client, local_root, ignored, remote if enabled else None)
+    report_copy("本地改动", uploaded, skipped, failed, "只在云端、本地没有的文件保持原样。")
+
+
+def cmd_to_local(args: argparse.Namespace) -> None:
+    config = selected(args)
+    label = config.get("name") or config.get("localRoot")
+    dry = is_dry_run(args)
+    if dry:
+        print_dry_run_banner("to-local")
+    print("把云主机内容同步到本地：%s" % label, flush=True)
+    local_root = config["localRoot"]
+    if not os.path.isdir(local_root):
+        raise SystemExit("本地目录不存在: %s" % local_root)
+    client = Client(config)
+    check_ready(client)
+    ignored = ignore_dirs(config)
+    path_ignore = load_path_ignore(local_root)
+    print("已连上 %s" % client.endpoint, flush=True)
+    if dry:
+        ignore_status = 200
+        print("演练模式跳过：推送忽略规则、本地暂存。", flush=True)
+    else:
+        ignore_status, _ignore_body = client.push_ignore(ignored)
+    remote, enabled = load_remote_base(client, ignored, ignore_status, path_ignore)
+    if not enabled:
+        raise SystemExit("云端接收程序不支持拉取。请在云端升级 code-server-sync 并重启 cs-sync recv，然后再运行 %s。" % command_text(config, "to-local"))
+    if dry:
+        downloaded, skipped, failed = preview_copy_cloud_to_local(local_root, remote)
+        if failed:
+            raise SystemExit("演练发现 %d 个无法处理的文件。" % failed)
+        return
+    stage_local_side(local_root, ignored)
+    downloaded, skipped, failed = copy_cloud_to_local(client, local_root, remote)
+    report_copy("本地写入", downloaded, skipped, failed, "只在本地、云端没有的文件保持原样。")
+
+
+def report_lines(applied: int, failed: int) -> None:
+    print("完成：已同步 %d 处 git diff，未应用 %d 处。" % (applied, failed), flush=True)
+    if failed:
+        raise SystemExit("有 %d 处 git diff 没有同步过去。" % failed)
+
+
+def local_change_reader(local_root: str):
+    def read_dest(rel: str):
+        full = os.path.join(local_root, *rel.split("/"))
+        if os.path.islink(full) or not os.path.isfile(full):
+            return False, None, "644"
+        with open(full, "rb") as handle:
+            return True, handle.read(), file_mode(full)
+    return read_dest
+
+
+def local_change_writer(local_root: str):
+    def write_dest(rel: str, payload: bytes, mode: str) -> bool:
+        try:
+            write_file(local_root, rel, payload, 0o755 if mode == "755" else 0o644)
+        except (ValueError, OSError) as exc:
+            eprint("本地写入失败 %s ：%s" % (rel, exc))
+            return False
+        return True
+    return write_dest
+
+
+def local_change_deleter(local_root: str):
+    def delete_dest(rel: str) -> bool:
+        try:
+            remove_file(local_root, rel)
+        except (ValueError, OSError) as exc:
+            eprint("本地写入（删除）失败 %s ：%s" % (rel, exc))
+            return False
+        return True
+    return delete_dest
+
+
+def cloud_change_reader(client: Client):
+    def read_dest(rel: str):
+        status, payload, mode = client.pull_file(rel)
+        if status != 200:
+            return False, None, "644"
+        return True, payload, "755" if mode == 0o755 else "644"
+    return read_dest
+
+
+def cloud_change_writer(client: Client):
+    def write_dest(rel: str, payload: bytes, mode: str) -> bool:
+        status, body = client.put_file(rel, payload, mode)
+        if status != 200 or body.strip() != b"ok":
+            eprint("未同步到云端 %s ：%s" % (rel, explain_http(status, body)))
+            return False
+        return True
+    return write_dest
+
+
+def cloud_change_deleter(client: Client):
+    def delete_dest(rel: str) -> bool:
+        status, body = client.delete_file(rel)
+        if status != 200 or body.strip() != b"ok":
+            eprint("未同步到云端（删除） %s ：%s" % (rel, explain_http(status, body)))
+            return False
+        return True
+    return delete_dest
+
+
+def cmd_diff_to_cloud(args: argparse.Namespace) -> None:
+    config = selected(args)
+    label = config.get("name") or config.get("localRoot")
+    dry = is_dry_run(args)
+    if dry:
+        print_dry_run_banner("diff-to-cloud")
+    print("把本次 git diff 同步到云主机：%s" % label, flush=True)
+    local_root = config["localRoot"]
+    if not os.path.isdir(local_root):
+        raise SystemExit("本地目录不存在: %s" % local_root)
+    client = Client(config)
+    check_ready(client)
+    ignored = ignore_dirs(config)
+    path_ignore = load_path_ignore(local_root)
+    print("已连上 %s" % client.endpoint, flush=True)
+    if dry:
+        print("演练模式跳过：推送忽略规则、云端暂存。", flush=True)
+    else:
+        client.push_ignore(ignored)
+        stage_cloud_side(client, config, "diff-to-cloud")
+    try:
+        changes, repo_count = collect_changes(local_root, ignored)
+    except StageError as exc:
+        raise SystemExit(str(exc))
+    if repo_count == 0:
+        print("项目里没有 git 仓库，没有可同步的 git diff。", flush=True)
+        return
+    if not changes:
+        print("没有需要同步的 git diff。", flush=True)
+        return
+    if dry:
+        would, failed = preview_line_changes(changes, cloud_change_reader(client))
+        if failed:
+            raise SystemExit("演练发现 %d 处 git diff 不能直接应用。" % failed)
+        print("去掉 --dry-run 才会真正同步这 %d 处。" % would, flush=True)
+        return
+    applied, failed = transfer_line_changes(
+        changes,
+        cloud_change_reader(client),
+        cloud_change_writer(client),
+        cloud_change_deleter(client),
+        success_verb="本地改动",
+    )
+    report_lines(applied, failed)
+
+
+def cmd_diff_to_local(args: argparse.Namespace) -> None:
+    config = selected(args)
+    label = config.get("name") or config.get("localRoot")
+    dry = is_dry_run(args)
+    if dry:
+        print_dry_run_banner("diff-to-local")
+    print("把云端本次 git diff 同步到本地：%s" % label, flush=True)
+    local_root = config["localRoot"]
+    if not os.path.isdir(local_root):
+        raise SystemExit("本地目录不存在: %s" % local_root)
+    client = Client(config)
+    check_ready(client)
+    ignored = ignore_dirs(config)
+    path_ignore = load_path_ignore(local_root)
+    print("已连上 %s" % client.endpoint, flush=True)
+    if dry:
+        print("演练模式跳过：推送忽略规则、本地暂存。", flush=True)
+    else:
+        client.push_ignore(ignored)
+    status, info = client.changes()
+    if status == 404:
+        raise SystemExit("云端接收程序不支持读取 git diff。请在云端升级 code-server-sync 并重启 cs-sync recv，然后再运行 %s。" % command_text(config, "diff-to-local"))
+    if status != 200 or not info:
+        raise SystemExit("读取云端 git diff 失败：%s" % explain_http(status, b""))
+    if not dry:
+        stage_local_side(local_root, ignored)
+    if not info.get("repos"):
+        print("云端项目里没有 git 仓库，没有可同步的 git diff。", flush=True)
+        return
+    changes = info.get("changes") or []
+    if not changes:
+        print("云端没有需要同步的 git diff。", flush=True)
+        return
+    try:
+        filtered = [change for change in changes if not should_skip(str(change.get("path") or ""), ignored, path_ignore)]
+    except TypeError:
+        filtered = list(changes)
+    if dry:
+        would, failed = preview_line_changes(filtered, local_change_reader(local_root))
+        if failed:
+            raise SystemExit("演练发现 %d 处 git diff 不能直接应用。" % failed)
+        print("去掉 --dry-run 才会真正同步这 %d 处。" % would, flush=True)
+        return
+    applied, failed = transfer_line_changes(
+        filtered,
+        local_change_reader(local_root),
+        local_change_writer(local_root),
+        local_change_deleter(local_root),
+        success_verb="本地写入",
+    )
+    report_lines(applied, failed)
+
+
+def cmd_sync(args: argparse.Namespace) -> None:
+    config = selected(args)
+    label = config.get("name") or config.get("localRoot")
+    dry = is_dry_run(args)
+    if dry:
+        print_dry_run_banner("sync")
+        print("同步项目 %s（仅预览当前差异，不进入监视）" % label, flush=True)
+        local_root = config["localRoot"]
+        if not os.path.isdir(local_root):
+            raise SystemExit("本地目录不存在: %s" % local_root)
+        client = Client(config)
+        check_ready(client)
+        ignored = ignore_dirs(config)
+        path_ignore = load_path_ignore(local_root)
+        print("已连上 %s" % client.endpoint, flush=True)
+        print("演练模式跳过：推送忽略规则。", flush=True)
+        remote, pull_enabled = load_remote_base(client, ignored, 200, path_ignore)
+        if not pull_enabled:
+            print("云端还是旧的接收程序，差异预览只能看到本地侧扫描结果与有限清单。", flush=True)
+            remote = {}
+        preview_sync_divergence(local_root, ignored, remote, pull_enabled)
+        return
+    print("同步项目 %s" % label, flush=True)
+    try:
+        watch(config)
+    except KeyboardInterrupt:
+        print("\n已停止监视")
+
+
+def cmd_recv(args: argparse.Namespace) -> None:
+    if not args.root or not args.token:
+        raise SystemExit("用法: cs-sync recv --root 云端绝对路径 --token 令牌 [--port %d]" % DEFAULT_PORT)
+    serve(args.root, args.token, args.port or DEFAULT_PORT)
+
+
+def cmd_self_test_entry(_args) -> None:
+    from cs_sync.self_test import cmd_self_test
+    cmd_self_test(_args)
+
+
+def package_version() -> str:
+    path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "package.json")
+    with open(path, encoding="utf-8") as handle:
+        return json.load(handle)["version"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cs-sync",
+        description="经 code-server 已登录通道，在本机与云主机之间同步项目代码",
+    )
+    parser.add_argument("--version", action="version", version="cs-sync %s" % package_version())
+    parser.add_argument("--config", default="", help="直接指定某个项目配置文件")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="登记一个项目")
+    init.add_argument("--name", default="", help="项目简称；省略时用本地目录名")
+    init.add_argument("--local", required=True, help="本机项目目录")
+    init.add_argument("--remote", required=True, help="云主机上的绝对路径")
+    init.add_argument("--base", default="", help="code-server 地址，例如 https://10.248.148.67:18888")
+    init.add_argument("--port", type=int, default=0, help="云端接收端口，省略时自动递增")
+    init.add_argument("--force", action="store_true", help="覆盖同名项目")
+    init.set_defaults(func=cmd_init)
+
+    listing = sub.add_parser("list", help="列出已登记的项目")
+    listing.set_defaults(func=cmd_list)
+
+    remove = sub.add_parser("remove", help="删除一个项目映射，不删除代码")
+    remove.add_argument("--name", required=True, help="要删除的项目简称")
+    remove.set_defaults(func=cmd_remove)
+
+    token = sub.add_parser("token", help="打印这个项目在云端的启动命令")
+    token.add_argument("--name", default="")
+    token.set_defaults(func=cmd_token)
+
+    login = sub.add_parser("login", help="用 code-server 密码登录，所有项目共用")
+    login.add_argument("--base", default="")
+    login.set_defaults(func=cmd_login)
+
+    cookie = sub.add_parser("cookie", help="写入浏览器里的 code-server-session，所有项目共用")
+    cookie.add_argument("value")
+    cookie.add_argument("--base", default="")
+    cookie.set_defaults(func=cmd_cookie)
+
+    doctor = sub.add_parser("doctor", help="检查某个项目的代理和接收程序")
+    doctor.add_argument("--name", default="")
+    doctor.set_defaults(func=cmd_doctor)
+
+    to_cloud = sub.add_parser("to-cloud", help="先暂存云端已有修改，再把本地内容同步到云主机，覆盖云端同名文件")
+    to_cloud.add_argument("--name", default="", help="项目简称；在该项目目录内可省略")
+    to_cloud.add_argument("--dry-run", action="store_true", help="只列出将本地改动/跳过的文件，不暂存、不写入")
+    to_cloud.set_defaults(func=cmd_to_cloud)
+
+    to_local = sub.add_parser("to-local", help="先暂存本地已有修改，再把云主机内容同步到本地，覆盖本地同名文件")
+    to_local.add_argument("--name", default="", help="项目简称；在该项目目录内可省略")
+    to_local.add_argument("--dry-run", action="store_true", help="只列出将本地写入/跳过的文件，不暂存、不写入")
+    to_local.set_defaults(func=cmd_to_local)
+
+    diff_to_cloud = sub.add_parser("diff-to-cloud", help="先暂存云端已有修改，再只把本地本次 git diff 同步到云主机")
+    diff_to_cloud.add_argument("--name", default="", help="项目简称；在该项目目录内可省略")
+    diff_to_cloud.add_argument("--dry-run", action="store_true", help="只列出将应用的 git diff，不暂存、不写入")
+    diff_to_cloud.set_defaults(func=cmd_diff_to_cloud)
+
+    diff_to_local = sub.add_parser("diff-to-local", help="先暂存本地已有修改，再只把云端本次 git diff 同步到本地")
+    diff_to_local.add_argument("--name", default="", help="项目简称；在该项目目录内可省略")
+    diff_to_local.add_argument("--dry-run", action="store_true", help="只列出将应用的 git diff，不暂存、不写入")
+    diff_to_local.set_defaults(func=cmd_diff_to_local)
+
+    sync_cmd = sub.add_parser("sync", help="双向监视：启动后的保存按 git 行级 diff 同步")
+    sync_cmd.add_argument("--name", default="", help="项目简称；在该项目目录内可省略")
+    sync_cmd.add_argument("--dry-run", action="store_true", help="只预览当前本地/云端差异，不进入监视、不写入")
+    sync_cmd.set_defaults(func=cmd_sync)
+
+    recv = sub.add_parser("recv", help="在云主机上接收文件，监听 0.0.0.0")
+    recv.add_argument("--root", default="")
+    recv.add_argument("--token", default="")
+    recv.add_argument("--port", type=int, default=0)
+    recv.set_defaults(func=cmd_recv)
+
+    test = sub.add_parser("self-test", help="在本机临时目录跑一遍协议")
+    test.set_defaults(func=cmd_self_test_entry)
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()