dsh-config-manager 0.2.3 → 0.3.0

package/lib/sync/gc-skip.js

@@ -0,0 +1,57 @@
+/**
+ * 本轮 blob GC 的放弃码（SYN-04）。**机器可判定**，文案由上层按码翻译（字典键由 Lead 统一加）：
+ * 通道没有 logger，`delete()` 还会吞掉 GC 抛出的异常，所以「本轮为什么没回收」只能靠这个码如实外露。
+ * 三态同义：拿不到引用者内容 = 无法证明「没人引用」⇒ 本轮整轮放弃，绝不按残集删除。
+ *
+ * 单一来源：webdav / s3 两个通道都从这里导入（此前各写一份同名常量，改一侧不炸另一侧 =
+ * 静默漂移；本模块不 import 任何 transport，所以不存在环）。
+ */
+export const GC_SKIP_REFERENCE_MISSING = 'gc-skip-reference-missing';
+export const GC_SKIP_REFERENCE_UNREADABLE = 'gc-skip-reference-unreadable';
+export const GC_SKIP_SNAPSHOT_UNPARSABLE = 'gc-skip-snapshot-unparsable';
+/**
+ * SYN-04b：通道「本轮 GC 放弃码」的读取与冒泡（从 sync-engine.ts 下沉，行为逐字不变）。
+ *
+ * 为什么放在独立模块：SYN-04 之后 webdav/s3 遇到「引用快照 404 / 读不出」会**放弃本轮 blob GC**
+ * （绝不在「证明不了没人引用」时删 blob），而通道层没有 logger、delete() 又把 GC 异常吃掉
+ * ⇒ 放弃只能靠 transport 的只读字段外露。字段形态是 getter（见 webdav/s3 transport 的
+ * `get lastGcSkip()`），这里按 unknown 读、只接受非空字符串，getter 抛错也不影响 push。
+ *
+ * 判据（缺一不可，全部当「没有放弃码」）：字段缺失 / null / 非字符串 / 空串 / getter 抛错。
+ * 读不到 ≠ 没有放弃：通道没这个能力时本来就不该冒泡告警，所以两者在调用侧合并处理。
+ */
+export function readGcSkipCode(transport) {
+    try {
+        const raw = transport?.lastGcSkip;
+        return typeof raw === 'string' && raw !== '' ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * SYN-04b：放弃码 → 一条 warning 文本。
+ *
+ * 码必须同时以**明文**出现：core 目录的翻译器对未知键回退键名本身（{code} 插值随之丢失），
+ * 而文案键由上层统一补字典 —— 在补键之前，只发出裸键名等于「报了但看不出来」，日志也无法 grep。
+ */
+export function gcSkipWarning(msg, code) {
+    const text = msg('sync.gcSkipped', { code });
+    return text.includes(code) ? text : text + ': ' + code;
+}
+/**
+ * SYN-04b：把通道的 GC 放弃码冒泡成一条 warning（`state` 保证同一轮只报一次）。
+ *
+ * 语义边界：放弃 GC **不是** push 失败 —— 快照本身已上传/已删除，只是这一轮的孤儿 blob
+ * 没被回收（磁盘/远端会多留几份文件）。所以它进 warnings、不进 ok，与 prune 既有语义一致。
+ */
+export function reportGcSkipOnce(transport, msg, warnings, state) {
+    if (state.done)
+        return;
+    const code = readGcSkipCode(transport);
+    if (code === null)
+        return;
+    state.done = true;
+    warnings.push(gcSkipWarning(msg, code));
+}
+//# sourceMappingURL=gc-skip.js.map

package/lib/sync/git/git-transport.d.ts

@@ -7,7 +7,7 @@ export interface GitExecResult {
     stderr: string;
     code: number;
 }
-/** 可注入的 git 执行器（测试 mock 用）；默认实现 = child_process.execFile promise 封装 */
+/** 可注入的 git 执行器（测试 mock 用）；默认实现 = child_process.spawn promise 封装（超时杀进程树） */
 export type GitExecFn = (cmd: string, args: string[], opts: {
     cwd?: string;
     timeoutMs?: number;
@@ -59,7 +59,7 @@ export interface GitTransportOptions {
     timeoutMs?: number;
     /** 幂等读操作（list/download 的 clone/pull）的网络重试参数；缺省 attempts=3、250ms 起指数退避 */
     retry?: SyncRetryOptions;
-    /** 注入 exec（测试 mock 用）；缺省 = execFile 封装 */
+    /** 注入 exec（测试 mock 用）；缺省 = spawn 封装（超时杀进程树） */
     exec?: GitExecFn;
     /** 提交作者（写入远端历史），默认 DSH Config Sync <sync@dsh.local> */
     author?: GitAuthor;
@@ -75,11 +75,26 @@ export interface GitTransportOptions {
 export declare class GitTransportError extends SyncTransportError {
     constructor(message: string, opts?: SyncTransportErrorOptions);
 }
+/**
+ * 默认 git 执行器：spawn + **进程树** kill（issue #122）。
+ *
+ * 为什么不再用 execFile：它的 timeout 只对 git.exe 自己发 SIGTERM，而真正在下包的是 git.exe 的子进程
+ * （git-remote-https / git index-pack）。父进程被杀、孙进程继续写 tmp_pack_*，管道不关闭 ⇒ execFile 的
+ * promise 连超时错误都可能不返回 ⇒ 上层「正在检查远端变更...」永久挂起，下一轮重试再起一份，最终 N 份
+ * 并发下载同一个 pack。
+ * 这里改为：POSIX 上 detached 起独立进程组，超时对**整组**发 SIGKILL；Windows 上 `taskkill /T /F`；
+ * 无论 kill 是否成功，宽限期到点都带着已收集输出收尾 —— 绝不把「管道没关」变成上层无限等待。
+ *
+ * 导出仅供测试直接验证「超时 + 进程树 kill + 有界收尾」（issue #122 的验收面）。
+ */
+export declare const defaultGitExec: GitExecFn;
 /** 实现 SyncTransport 的 git 通道。所有操作前 ensureRepo() 保证工作副本就绪，网络命令带凭据。 */
 export declare class GitTransport implements SyncTransport {
     readonly type = "git";
     private readonly o;
     private repoReady;
+    /** 该工作副本是否 partial clone（remote.origin.promisor）；null = 尚未判定（issue #122） */
+    private partialClone;
     /**
      * 工作副本锁的可重入深度：list/upload/download/delete 都会经 ensureRepo → reconcileOrigin，
      * rebuildWorkDir → adoptRemoteHistory 也各自嵌套；外层入口持锁，内层直接跑。
@@ -94,6 +109,8 @@ export declare class GitTransport implements SyncTransport {
      */
     private readErrors;
     private readonly msg;
+    /** repoUrl 是否为网络地址（本地目录仓库 == false）：决定要不要额外禁 file 传输（SEC-12）。 */
+    private readonly networkRepo;
     constructor(options: GitTransportOptions);
     /** 最近一次 checkIsPrivate() 的结果；null = 尚未检查 */
     get isPrivateHint(): boolean | null;
@@ -151,6 +168,30 @@ export declare class GitTransport implements SyncTransport {
      */
     private withWorkdir;
     private ensureRepo;
+    /**
+     * 首次 clone（issue #122）：partial clone + sparse-checkout，只落地同步内容。
+     *
+     * 为什么：同步仓库可能比同步内容大几个数量级（报告者现场 1.8 GB 仓库 / 6 MB 内容）。此前 `git clone`
+     * 全量落地，之后每次 fetch 还要拉完整对象图 ⇒ 一次「检查远端变更」就下几百 MB。
+     * `--filter=blob:none` 只取 commit+tree，`--no-checkout` 先不落地任何文件，
+     * `sparse-checkout set --cone <三个目录>` 之后 checkout 只 materialize 这三个目录的 blob。
+     *
+     * 老 git 不认这些选项（unknown option）时回落全量 clone —— 行为与修复前完全一致，绝不因优化失败。
+     */
+    private cloneIntoWorkDir;
+    /**
+     * 该工作副本是不是 partial clone（`remote.origin.promisor=true`）。
+     *
+     * 只有 partial clone 才能给 fetch 加 `--filter=blob:none`：对普通全量副本加过滤会让后续 checkout
+     * 拿到缺失的 blob。存量副本（1.8 GB 那种）因此只受益于 ls-remote 短路与 `--no-tags`，不会被改坏。
+     */
+    private isPartialClone;
+    /** 拉取姿态：partial clone 保持 blob 过滤；同步仓库不需要 tag（issue #122） */
+    private fetchOptionFlags;
+    /** 远端分支当前的 sha（ls-remote 只取一行 refs）；读不到 → null（短路是优化，失败一律回落正常 fetch） */
+    private lsRemoteBranchSha;
+    /** 解析引用指向的 sha；读不到 / 不是 sha → null */
+    private revParseSha;
     /**
      * 让工作副本的 origin 与配置的 repoUrl 保持一致（issue #79）。
      *
@@ -229,6 +270,11 @@ export declare class GitTransport implements SyncTransport {
      * 还会在本地留下一个已提交却推不上去的快照。
      */
     private runGit;
+    /**
+     * 把「git 退出非零」归一成可操作错误（runGit 与 clone 回落共用同一套文案与分类）。
+     * token 只用于脱敏，绝不进 message。
+     */
+    private raiseGitFailure;
     /**
      * 为网络命令构造 credential helper 参数：
      * 仅 http(s) 远端需要 token；本地路径 / ssh 走 git 原生认证（密钥），不调用 provider。
@@ -239,6 +285,14 @@ export declare class GitTransport implements SyncTransport {
     private repoHost;
     /** 读取一次 token（错误消息脱敏用）；非 http(s) 场景返回空 */
     private readTokenOnce;
+    /**
+     * 回传体里的地址（工作副本自检的 origin / pushUrl）脱敏：只剥「凭据段」，其余原样保留。
+     *
+     * 为什么不整串换占位符：状态面板要显示「工作副本现在指向哪个远端」，用户靠 host/path 判断是否
+     * 已跟随配置。为什么不一律剥 userinfo：`ssh://git@host` 里的 `git` 是 ssh 登录名（标准写法），
+     * 剥掉会让用户认不出自己的远端 —— 与 validateRepoUrl 的口径保持一致（只有 password 位是凭据）。
+     */
+    private bareUrl;
     /** 错误/日志脱敏：token（原文与 URL 编码两种形态）与 repoUrl 一律替换 */
     private mask;
     /**