code-server-sync 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 更新日志
+
+## 0.1.0 - 2026-10-27
+
+首次发布 npm 包 `code-server-sync`，命令名是 `cs-sync`。
+
+- 本机（Windows、macOS）和云端（Linux）安装同一个包
+- 经 code-server 已登录的 `/proxy/<端口>/` 同步项目代码
+- `token` 直接打印 `cs-sync recv ...`，不必再填写云端脚本路径
+- 支持 `init`、`login`、`cookie`、`doctor`、`list`、`remove`、`token`、`to-cloud`、`to-local`、`diff-to-cloud`、`diff-to-local`、`sync`、`recv`、`self-test`
+- 整份同步、行级 diff、启动后的双向监视，以及 `--dry-run`
+- `cs-sync --version` 打印当前安装的版本

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nie Tao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# cs-sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`cs-sync` 在本机目录与运行 code-server 的云主机目录之间同步代码。
+
+通道使用 code-server 已经登录的 `/proxy/<端口>/`，不另外开放公网入口。云端用同一个命令启动接收进程 `recv`。
+
+本机可以是 Windows 或 macOS。云端接收进程运行在 Linux 上。
+
+## 适合谁
+
+适合需要在本机编辑，并把代码同步到一台已经登录的 code-server 云主机的人。
+
+它不替代编辑器、编译器或部署流水线。
+
+## 一次完整使用会经过什么
+
+1. 在本机和云端都安装 `code-server-sync`
+2. 登记本机目录、云端目录和 code-server 地址
+3. 写入 code-server 登录态
+4. 用 `token` 打印云端接收命令
+5. 把打印出的 `cs-sync recv ...` 贴到云端终端
+6. 用 `doctor` 检查通道
+7. 先 `--dry-run`，再正式同步
+
+| 步骤 | 命令 | 结果 |
+|------|------|------|
+| 登记 | `cs-sync init` | 生成项目令牌和接收端口，并打印云端启动命令 |
+| 登录 | `cs-sync login` 或 `cs-sync cookie` | 把 code-server 登录态记到本机配置 |
+| 打印命令 | `cs-sync token` | 再次打印要贴到云端的 `cs-sync recv ...` |
+| 启动接收 | 云端执行 `cs-sync recv ...` | 云端开始在该端口接收 |
+| 检查 | `cs-sync doctor` | 确认代理、令牌和路径校验 |
+| 演练 | `cs-sync to-cloud --dry-run` | 只列出将要发生的变化 |
+| 同步 | `cs-sync to-cloud` 或 `cs-sync sync` | 按所选方式写入 |
+
+在 `localRoot` 目录内运行时可以省略 `--name`。
+
+## 前提
+
+本机（Windows 或 macOS）：
+
+- Node.js 18 及以上
+- Python 3.9 及以上。Windows 上使用 `py -3` 或 `python`，macOS 上使用 `python3`
+- Git。整份同步前的暂存、行级 diff 和 `sync` 都会用到
+
+云端（Linux）：
+
+- 已安装同一个包
+- Python 3.9 及以上
+
+## 安装
+
+本机和云端都执行：
+
+```bash
+npm install -g code-server-sync
+cs-sync --help
+cs-sync --version
+```
+
+不安装到全局时：
+
+```bash
+npx code-server-sync --help
+```
+
+## 最短上手
+
+```bash
+cs-sync init \
+  --name 我的项目 \
+  --local /本机/项目目录 \
+  --remote /云端/绝对路径 \
+  --base https://code-server主机:端口
+
+cs-sync login
+
+cs-sync token --name 我的项目
+```
+
+把 `token` 打印的那一行贴到云端 code-server 终端。它的形式是：
+
+```bash
+cs-sync recv --root '/云端/绝对路径' --token '…' --port 27182
+```
+
+然后：
+
+```bash
+cs-sync doctor --name 我的项目
+cs-sync to-cloud --name 我的项目 --dry-run
+cs-sync to-cloud --name 我的项目
+cs-sync sync --name 我的项目
+```
+
+Windows 上 `--local` 使用本机路径，例如 `C:\work\demo`。`--remote` 始终是云端 Linux 绝对路径。`token` 打印的引号按云端 shell 转义，直接粘贴到云端终端。
+
+## 按意图选择命令
+
+### 我要检查通道
+
+```bash
+cs-sync doctor --name 我的项目
+```
+
+### 我要把本机整份覆盖到云端同名路径
+
+```bash
+cs-sync to-cloud --name 我的项目
+```
+
+### 我要把云端整份覆盖到本机同名路径
+
+```bash
+cs-sync to-local --name 我的项目
+```
+
+### 我只想把本机尚未提交的行级改动推上去
+
+```bash
+cs-sync diff-to-cloud --name 我的项目
+```
+
+### 我只想把云端尚未提交的行级改动拉下来
+
+```bash
+cs-sync diff-to-local --name 我的项目
+```
+
+### 我要在保存之后双向同步启动后的增量
+
+```bash
+cs-sync sync --name 我的项目
+```
+
+## 命令一览
+
+| 命令 | 作用 |
+|------|------|
+| `init` | 登记项目，生成令牌并分配端口 |
+| `list` / `remove` | 列出或删除映射，不删除目录里的代码 |
+| `login` / `cookie` | 写入 code-server 登录态，所有项目共用 |
+| `token` | 打印云端 `recv` 启动命令 |
+| `doctor` | 检查代理、令牌和路径校验 |
+| `to-cloud` | 云端先 `git add -A`，再用本机文件覆盖云端同名路径 |
+| `to-local` | 本机先 `git add -A`，再用云端文件覆盖本机同名路径 |
+| `diff-to-cloud` | 云端先暂存，再把本机 `git diff` 行级推到云端；合不上则跳过 |
+| `diff-to-local` | 本机先暂存，再把云端 `git diff` 行级拉到本机 |
+| `sync` | 记下基线后，按行级增量与三路合并双向同步之后的保存 |
+| `recv` | 只在云端 Linux 上运行，负责接收 |
+| `self-test` | 在本机临时目录检查协议，不连接真实 code-server |
+
+同步类命令都支持 `--dry-run`。全局可选 `--config /某/项目.json`。`cs-sync --version` 打印当前安装的版本。
+
+## 三种同步
+
+### 整份：`to-cloud` / `to-local`
+
+按相对路径扫描，用 SHA-256 比较内容，相同则跳过。覆盖同名文件，对端独有的文件保留。正式执行前，对即将被覆盖的一侧执行 `git add -A`，把当前改动放进 index。`--dry-run` 不会暂存。
+
+默认同步忽略 `.git`、`node_modules`、`dist`、`build`、`.agents`、常见虚拟环境目录等。扫描时跳过约 32MB 以上的单个文件。上传和下载使用同一个大小限制，超过会拒绝。
+
+### 行级：`diff-to-cloud` / `diff-to-local`
+
+收集相对 `HEAD` 的 `git diff`，没有 `HEAD` 时使用已暂存内容，并包含未跟踪的新文件。对端在临时目录用 `git apply` 试算后再写入。合不上则跳过该文件，保留对端原内容。二进制、对端已经存在的「新增」和补丁冲突记为失败或冲突。
+
+### 监视：`sync`
+
+启动时扫描本机并读取云端清单，记下基线。两边当时已经不一致的内容只记基线，启动前的差异留给 `to-*` 或 `diff-*`。之后只同步启动后的保存。
+
+本地改动按相对上次已同步内容的行级 diff 推到云端。云端改动先试行级补丁，对不上再做三路合并。真冲突时保留这一侧已有内容，并打印提示。二进制不能按行同步。
+
+| 日志 | 含义 |
+|------|------|
+| `本地改动` | 本机先改，并已同步到云端。删除时带「（删除）」 |
+| `本地写入` | 因为云端变更，本机文件被写入或删除 |
+| `云端改动` | 云端工作区先出现变更 |
+| `云端写入` | 因为本机同步，云端文件被写入或删除 |
+
+云端日志仍是旧文案时，在云端升级 `code-server-sync` 并重启 `cs-sync recv`。本机的 `sync` 也要重新启动。
+
+## `.cs-syncignore`
+
+在本机目录或云端目录放置 `.cs-syncignore`，语法与 gitignore 类似：`*`、`?`、`**`、目录尾 `/`、`#` 注释、`!` 否定。
+
+它和内置忽略取并集，命中任一即跳过。`!` 不能抵消内置忽略，例如 `!node_modules` 无效。各端读取自己目录下的这份文件。扫描、整份同步、行级同步、`sync` 和 `--dry-run` 都会用它。
+
+## `--dry-run`
+
+适用于 `to-cloud`、`to-local`、`diff-to-cloud`、`diff-to-local`、`sync`。
+
+不会执行 `git add -A`，不会调用云端暂存，不会写入或删除项目目录中的文件，不会把补丁落到工作区，也不会推送忽略规则。`sync --dry-run` 不进入持续监视，打印当前双边差异后退出。
+
+会做连通检查，并只读读取云端清单。行级预览可能只读拉取对端内容，用来判断是相同跳过还是能够合入。
+
+清单标签包括：`add`、`modify`、`delete`、`skip-same`、`conflict`、`binary`、`local-only`、`remote-only`。
+
+## 配置
+
+默认目录是 `~/.config/cs-sync/`。Windows 上是 `%USERPROFILE%\.config\cs-sync`。环境变量 `CS_SYNC_HOME` 可以改到别处。
+
+```
+~/.config/cs-sync/
+  host.json
+  projects/
+    我的项目.json
+```
+
+**host.json**
+
+| 字段 | 含义 |
+|------|------|
+| `baseUrl` | code-server 根地址 |
+| `cookie` | `code-server-session=…` |
+| `auth` | 例如 `password` 或 `none` |
+| `insecure` | 是否跳过 TLS 校验 |
+
+**projects/\*.json**
+
+| 字段 | 含义 |
+|------|------|
+| `name` | 项目简称 |
+| `localRoot` / `remoteRoot` | 本机目录 / 云端绝对路径 |
+| `port` | 云端 recv 端口，默认从 27182 递增 |
+| `token` | 项目令牌 |
+| `ignoreDirs` | 忽略的目录名 |
+
+配置文件按 `0600` 写入。Windows 上权限由系统落成它能表达的结果。项目名区分大小写。
+
+## 使用时要注意
+
+- 外网要先登录 code-server，才能到达同步接口。
+- 持有项目 `token` 才能对 `recv` 做写入。`/health` 不校验令牌。
+- `recv` 在云端监听 `0.0.0.0`，经 code-server `/proxy` 访问。端口不要对公网直接开放。
+- `host.json` 可能含登录相关字段。它不是系统钥匙串。
+- `token` 会出现在云端进程的命令行里，同机可以看见。
+- 正式同步前的暂存是 `git add -A`，会改动对应仓库的 index。`--dry-run` 不会暂存。
+- 常见初始化路径下，HTTPS 可能跳过证书校验。
+- 单个文件超过约 32MB 时，上传和下载都会拒绝。
+
+## 常见问题
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| doctor 返回网页 | Cookie 失效或未登录 | 重新 `cs-sync login` 或 `cs-sync cookie` |
+| 502 / 连接被拒绝 | 云端 `recv` 未启动或端口不对 | 再执行 `cs-sync token`，把命令贴到云端 |
+| 403 | 本机令牌与云端 `--token` 不一致 | 使用当前项目 `token` 打印出的命令 |
+| 提示接收程序过旧 | 云端的包装版本旧，缺接口 | 在云端升级 `code-server-sync` 并重启 `cs-sync recv` |
+| sync 不传启动前就改过的文件 | 只跟踪启动后的增量 | 改用 `to-*` 或 `diff-*`，或先看 `sync --dry-run` |
+| 冲突后该文件本轮不动 | 同一处行变更合不上 | 人工对齐后再保存，或改用整份 / 行级命令 |
+| 行级大量失败 | 补丁合不上或是二进制 | 改用整份同步，或先对齐内容 |
+| 端口被其他程序占用 | 不是本工具的接收进程 | 按提示检查该端口后手动处理 |
+| sync 在网络中断后继续 | 读超时被接住 | 恢复网络后会继续监视 |

package/bin/cs-sync.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const VERSION_CHECK =
+  "import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)";
+
+function candidates() {
+  if (process.platform === "win32") {
+    return [["py", "-3"], ["python"], ["python3"]];
+  }
+  return [["python3"], ["python"]];
+}
+
+function tryVersion(parts) {
+  const result = spawnSync(parts[0], parts.slice(1).concat(["-c", VERSION_CHECK]), {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error && result.error.code === "ENOENT") {
+    return "missing";
+  }
+  if (result.status === 0) {
+    return "ok";
+  }
+  return "old";
+}
+
+function fail(tried) {
+  const names = tried.map((parts) => parts.join(" ")).join("、");
+  const hint = process.platform === "win32"
+    ? "在 Windows 上安装 Python 3.9 及以上，并确认 py -3 或 python 可用。"
+    : "请安装 Python 3.9 及以上，并确认 python3 在 PATH 中。";
+  console.error("需要 Python 3.9 及以上才能运行 cs-sync。\n已尝试：" + names + "\n" + hint);
+  process.exit(1);
+}
+
+function main() {
+  const tried = [];
+  let chosen = null;
+  for (const parts of candidates()) {
+    tried.push(parts);
+    if (tryVersion(parts) === "ok") {
+      chosen = parts;
+      break;
+    }
+  }
+  if (!chosen) {
+    fail(tried);
+  }
+  const root = path.resolve(__dirname, "..");
+  const env = Object.assign({}, process.env);
+  env.PYTHONPATH = env.PYTHONPATH ? root + path.delimiter + env.PYTHONPATH : root;
+  const result = spawnSync(
+    chosen[0],
+    chosen.slice(1).concat(["-m", "cs_sync"], process.argv.slice(2)),
+    { env: env, stdio: "inherit" }
+  );
+  if (result.error) {
+    console.error("启动 Python 失败：" + result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main();

package/cs_sync/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from cs_sync.cli import main
+
+if __name__ == "__main__":
+    main()