dsh-git-push 0.0.0-stage → 2.8.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (279) hide show
  1. package/.auditignore +30 -0
  2. package/.gitignore +39 -0
  3. package/LICENSE +21 -0
  4. package/README.md +1486 -2
  5. package/cli.mjs +360 -0
  6. package/cordis.patch.yml +14 -0
  7. package/lib/ARCHITECTURE.md +34 -0
  8. package/lib/BUGFIX-NOTES-2026-09-14.md +278 -0
  9. package/lib/app/apply.js +275 -0
  10. package/lib/app/audit-api.js +158 -0
  11. package/lib/app/command-registry.js +266 -0
  12. package/lib/app/constants.js +16 -0
  13. package/lib/app/handlers/account.js +166 -0
  14. package/lib/app/handlers/clone.js +168 -0
  15. package/lib/app/handlers/http-constants.js +9 -0
  16. package/lib/app/handlers/identity-rewrite.js +94 -0
  17. package/lib/app/handlers/meta.js +175 -0
  18. package/lib/app/handlers/npm.js +169 -0
  19. package/lib/app/handlers/repo-actions.js +143 -0
  20. package/lib/app/handlers/repos.js +231 -0
  21. package/lib/app/handlers/settings.js +62 -0
  22. package/lib/app/host-doc-checks.js +25 -0
  23. package/lib/app/http-handlers.js +131 -0
  24. package/lib/app/index.js +30 -0
  25. package/lib/app/inject-text.js +192 -0
  26. package/lib/app/scan-root.js +23 -0
  27. package/lib/app/schema.js +150 -0
  28. package/lib/app/settings-bridge.js +167 -0
  29. package/lib/app/slash-commands.js +395 -0
  30. package/lib/app/slot-stats.js +35 -0
  31. package/lib/app/tool-call.js +672 -0
  32. package/lib/app/tools.js +34 -0
  33. package/lib/ast/brace.js +105 -0
  34. package/lib/ast/callgraph.js +135 -0
  35. package/lib/ast/code-lines.js +114 -0
  36. package/lib/ast/consts.js +12 -0
  37. package/lib/ast/control-flow.js +461 -0
  38. package/lib/ast/credential.js +199 -0
  39. package/lib/ast/dataflow.js +274 -0
  40. package/lib/ast/dup-code.js +165 -0
  41. package/lib/ast/index.js +36 -0
  42. package/lib/ast/io-risk-const.js +95 -0
  43. package/lib/ast/io-risk-fn.js +208 -0
  44. package/lib/ast/io-risk-loop.js +308 -0
  45. package/lib/ast/io-risk.js +314 -0
  46. package/lib/ast/lang.js +156 -0
  47. package/lib/ast/line-count.js +52 -0
  48. package/lib/ast/magic-number.js +272 -0
  49. package/lib/ast/naming.js +284 -0
  50. package/lib/ast/perf.js +472 -0
  51. package/lib/ast/scope.js +241 -0
  52. package/lib/ast/shell.js +131 -0
  53. package/lib/ast/size.js +378 -0
  54. package/lib/ast/symbol-index.js +399 -0
  55. package/lib/ast/tokenizer.js +341 -0
  56. package/lib/audit/analysis-coverage.js +98 -0
  57. package/lib/audit/audit-file.js +182 -0
  58. package/lib/audit/checks.js +17 -0
  59. package/lib/audit/client-entry.js +93 -0
  60. package/lib/audit/collector.js +477 -0
  61. package/lib/audit/ext-runner.js +80 -0
  62. package/lib/audit/file-context.js +138 -0
  63. package/lib/audit/finding.js +50 -0
  64. package/lib/audit/gitignore-match.js +113 -0
  65. package/lib/audit/glob.js +63 -0
  66. package/lib/audit/history-report.js +100 -0
  67. package/lib/audit/history.js +126 -0
  68. package/lib/audit/ignore-blind.js +101 -0
  69. package/lib/audit/index.js +33 -0
  70. package/lib/audit/orchestrate.js +476 -0
  71. package/lib/audit/public.js +24 -0
  72. package/lib/audit/repo-level.js +30 -0
  73. package/lib/audit/report-yaml.js +86 -0
  74. package/lib/audit/slot.js +65 -0
  75. package/lib/audit-defaults.js +18 -0
  76. package/lib/audit-rules/audit-rules-comment.yml +247 -0
  77. package/lib/audit-rules/audit-rules-cpp.yml +22 -0
  78. package/lib/audit-rules/audit-rules-docs.yml +32 -0
  79. package/lib/audit-rules/audit-rules-dsh.yml +162 -0
  80. package/lib/audit-rules/audit-rules-filehealth.yml +42 -0
  81. package/lib/audit-rules/audit-rules-folder.yml +99 -0
  82. package/lib/audit-rules/audit-rules-frontend.yml +335 -0
  83. package/lib/audit-rules/audit-rules-go.yml +22 -0
  84. package/lib/audit-rules/audit-rules-i18n.yml +45 -0
  85. package/lib/audit-rules/audit-rules-java.yml +105 -0
  86. package/lib/audit-rules/audit-rules-nodejs.yml +647 -0
  87. package/lib/audit-rules/audit-rules-npm.yml +187 -0
  88. package/lib/audit-rules/audit-rules-paths.yml +92 -0
  89. package/lib/audit-rules/audit-rules-performance.yml +215 -0
  90. package/lib/audit-rules/audit-rules-php.yml +22 -0
  91. package/lib/audit-rules/audit-rules-private.yml +24 -0
  92. package/lib/audit-rules/audit-rules-python.yml +106 -0
  93. package/lib/audit-rules/audit-rules-robustness.yml +27 -0
  94. package/lib/audit-rules/audit-rules-rust.yml +22 -0
  95. package/lib/audit-rules/audit-rules-structure.yml +159 -0
  96. package/lib/audit-rules/audit-rules-swift.yml +22 -0
  97. package/lib/audit-rules/audit-rules-template.yml +108 -0
  98. package/lib/checks/button-bind.js +276 -0
  99. package/lib/checks/common.js +170 -0
  100. package/lib/checks/credential-file.js +43 -0
  101. package/lib/checks/dataflow.js +40 -0
  102. package/lib/checks/dispatch.js +112 -0
  103. package/lib/checks/dup-code.js +69 -0
  104. package/lib/checks/dup-const.js +232 -0
  105. package/lib/checks/file-health.js +150 -0
  106. package/lib/checks/filter.js +137 -0
  107. package/lib/checks/folder.js +173 -0
  108. package/lib/checks/hardcoded-path.js +98 -0
  109. package/lib/checks/index.js +46 -0
  110. package/lib/checks/io.js +66 -0
  111. package/lib/checks/magic-number.js +42 -0
  112. package/lib/checks/npm-json.js +273 -0
  113. package/lib/checks/private.js +63 -0
  114. package/lib/checks/regex.js +256 -0
  115. package/lib/checks/semantic.js +134 -0
  116. package/lib/checks/structural.js +274 -0
  117. package/lib/cli/commands-account.mjs +107 -0
  118. package/lib/cli/commands-audit.mjs +144 -0
  119. package/lib/cli/commands-doc.mjs +127 -0
  120. package/lib/cli/commands-vcs.mjs +175 -0
  121. package/lib/client/index.js +162 -0
  122. package/lib/client-parts/00-loader.js +33 -0
  123. package/lib/client-parts/01-const.js +207 -0
  124. package/lib/client-parts/02-utils.js +62 -0
  125. package/lib/client-parts/03-icons.js +12 -0
  126. package/lib/client-parts/10-account.js +83 -0
  127. package/lib/client-parts/11-browser.js +95 -0
  128. package/lib/client-parts/20-repo.js +374 -0
  129. package/lib/client-parts/21-audit.js +301 -0
  130. package/lib/client-parts/22-settings.js +146 -0
  131. package/lib/client-parts/23-npm.js +383 -0
  132. package/lib/client-parts/30-page.js +56 -0
  133. package/lib/client-parts/40-controller.js +1092 -0
  134. package/lib/client-parts/41-actions.js +279 -0
  135. package/lib/client-parts/99-apply.js +72 -0
  136. package/lib/client.js +3195 -0
  137. package/lib/commit-push.js +148 -0
  138. package/lib/context/index.js +363 -0
  139. package/lib/core/atomic-json.js +98 -0
  140. package/lib/core/config.js +40 -0
  141. package/lib/core/credentials.js +274 -0
  142. package/lib/core/endpoints.js +109 -0
  143. package/lib/core/exec.js +162 -0
  144. package/lib/exempt/index.js +292 -0
  145. package/lib/fs/edit-after-read.js +103 -0
  146. package/lib/fsx.js +87 -0
  147. package/lib/git/account-status.js +140 -0
  148. package/lib/git/account.js +233 -0
  149. package/lib/git/api.js +136 -0
  150. package/lib/git/atomic-json.js +6 -0
  151. package/lib/git/browse.js +38 -0
  152. package/lib/git/clone-download.js +397 -0
  153. package/lib/git/clone-history-mode.js +143 -0
  154. package/lib/git/clone-history.js +175 -0
  155. package/lib/git/clone-jobs.js +250 -0
  156. package/lib/git/clone-replay-io.js +172 -0
  157. package/lib/git/clone-replay.js +275 -0
  158. package/lib/git/clone.js +445 -0
  159. package/lib/git/cloud.js +46 -0
  160. package/lib/git/commit-message.js +141 -0
  161. package/lib/git/config.js +6 -0
  162. package/lib/git/cred-env.js +88 -0
  163. package/lib/git/credentials.js +6 -0
  164. package/lib/git/endpoints.js +6 -0
  165. package/lib/git/exec.js +6 -0
  166. package/lib/git/identity-rewrite.js +297 -0
  167. package/lib/git/identity.js +150 -0
  168. package/lib/git/ignore.js +69 -0
  169. package/lib/git/index.js +41 -0
  170. package/lib/git/module-splitter.js +47 -0
  171. package/lib/git/post-push.js +101 -0
  172. package/lib/git/push-diagnose.js +142 -0
  173. package/lib/git/push.js +476 -0
  174. package/lib/git/remote-resolve.js +146 -0
  175. package/lib/git/remote.js +128 -0
  176. package/lib/git/repo-index.js +512 -0
  177. package/lib/git/repos.js +235 -0
  178. package/lib/git/scan-runner.js +159 -0
  179. package/lib/git/sensitive.js +134 -0
  180. package/lib/git/transport.js +430 -0
  181. package/lib/git/visibility.js +35 -0
  182. package/lib/git/wrapped-git.js +68 -0
  183. package/lib/http/index.js +170 -0
  184. package/lib/index.js +24 -0
  185. package/lib/link-check/index.js +187 -0
  186. package/lib/npm/account.js +64 -0
  187. package/lib/npm/install.js +211 -0
  188. package/lib/npm/npmrc.js +56 -0
  189. package/lib/npm/publish.js +171 -0
  190. package/lib/npm/registry.js +168 -0
  191. package/lib/plugin/auto-detect.js +92 -0
  192. package/lib/plugin/auto-push.js +154 -0
  193. package/lib/plugin/index.js +250 -0
  194. package/lib/readme-templates/readme.yml +38 -0
  195. package/lib/rule/compilers/credential.js +62 -0
  196. package/lib/rule/compilers/dataflow.js +38 -0
  197. package/lib/rule/compilers/file-health.js +75 -0
  198. package/lib/rule/compilers/frontend.js +86 -0
  199. package/lib/rule/compilers/func.js +35 -0
  200. package/lib/rule/compilers/helpers.js +71 -0
  201. package/lib/rule/compilers/index.js +29 -0
  202. package/lib/rule/compilers/link-semantic.js +45 -0
  203. package/lib/rule/compilers/list-kinds.js +12 -0
  204. package/lib/rule/compilers/numeric-kinds.js +66 -0
  205. package/lib/rule/compilers/regex.js +78 -0
  206. package/lib/rule/compilers/structure.js +80 -0
  207. package/lib/rule/compilers.js +17 -0
  208. package/lib/rule/homoglyph.js +45 -0
  209. package/lib/rule/loader.js +270 -0
  210. package/lib/rule/registry.js +115 -0
  211. package/lib/rule/scope.js +67 -0
  212. package/lib/score/docs-score.js +166 -0
  213. package/lib/score/index.js +140 -0
  214. package/lib/self/index.js +196 -0
  215. package/lib/skip-dirs.js +64 -0
  216. package/lib/tool-probes.json +50 -0
  217. package/lib/user-requirements.json +14 -0
  218. package/lib/vendor/js-yaml/LICENSE +21 -0
  219. package/lib/vendor/js-yaml/js-yaml.mjs +3073 -0
  220. package/package.json +95 -4
  221. package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
  222. package/scripts/audit-ext/_example-readme-present.mjs +34 -0
  223. package/scripts/audit-ext/variable-min-length.mjs +102 -0
  224. package/scripts/audit-runner.mjs +35 -0
  225. package/scripts/audit-runtime-check.mjs +129 -0
  226. package/scripts/browser-page-probe.mjs +271 -0
  227. package/scripts/build-client.mjs +119 -0
  228. package/scripts/check.mjs +88 -0
  229. package/scripts/clean-date-comments.py +102 -0
  230. package/scripts/cpu-sample.mjs +188 -0
  231. package/scripts/doc-drift.mjs +200 -0
  232. package/scripts/doc-func.mjs +212 -0
  233. package/scripts/doc-tree.mjs +456 -0
  234. package/scripts/doc-version.mjs +220 -0
  235. package/scripts/frontend-preview-check.mjs +124 -0
  236. package/scripts/hot-path-probe-cjs.cjs +71 -0
  237. package/scripts/hot-path-probe-fs-shim.mjs +28 -0
  238. package/scripts/hot-path-probe-fsp-shim.mjs +31 -0
  239. package/scripts/hot-path-probe.mjs +153 -0
  240. package/scripts/module-splitter.py +800 -0
  241. package/scripts/platform-scan.mjs +168 -0
  242. package/scripts/preview-gen.mjs +489 -0
  243. package/scripts/preview-local-runner.mjs +55 -0
  244. package/scripts/preview-server-direct.mjs +116 -0
  245. package/scripts/preview-server.mjs +305 -0
  246. package/scripts/preview-slot-data.mjs +123 -0
  247. package/scripts/probe-recheck.mjs +47 -0
  248. package/scripts/readme-gen.mjs +268 -0
  249. package/scripts/rename-locator.mjs +97 -0
  250. package/scripts/rule-switch.mjs +97 -0
  251. package/scripts/rules-solo-audit.mjs +173 -0
  252. package/scripts/scan-file-io.mjs +713 -0
  253. package/scripts/scan-hardcoded-paths.mjs +125 -0
  254. package/scripts/scan-repos.mjs +167 -0
  255. package/scripts/scan-version.mjs +122 -0
  256. package/scripts/scrub-user-wording.mjs +420 -0
  257. package/scripts/symbol-index.mjs +85 -0
  258. package/scripts/sync-plugin-install.mjs +223 -0
  259. package/scripts/sync-plugin.mjs +279 -0
  260. package/scripts/verify-prestep.mjs +100 -0
  261. package/skills/dev/audit-rule-authoring.md +58 -0
  262. package/skills/dev/dsh-git-push.md +323 -0
  263. package/skills/dev/git-push-live-fix.md +45 -0
  264. package/skills/dsh-repo-index.md +35 -0
  265. package/skills/guide/guide-audit.md +167 -0
  266. package/skills/guide/guide-cli-scripts.md +104 -0
  267. package/skills/guide/guide-clone-repos.md +173 -0
  268. package/skills/guide/guide-commit-push.md +156 -0
  269. package/skills/guide/guide-inject-ui.md +166 -0
  270. package/skills/guide/guide-slash-completion.md +118 -0
  271. package/skills/workflow/README.md +21 -0
  272. package/skills/workflow/git-commit-discipline.md +68 -0
  273. package/skills/workflow/git-project-startup.md +85 -0
  274. package/skills/workflow/git-rebuild-process.md +57 -0
  275. package/skills/workflow/github-operations.md +91 -0
  276. package/skills/workflow/readme-sync-git-md.md +28 -0
  277. package/skills/workflow/task-completion-report.md +73 -0
  278. package/skills/workflow/tool-json-add-ask.md +35 -0
  279. package/skills/workflow/versioning-rule.md +211 -0
@@ -0,0 +1,275 @@
1
+ /**
2
+ * 克隆·真实历史重放:从「提交链」算出每一步要落盘/删除的文件(纯规划部分)。
3
+ *
4
+ * 【为什么要「按父提交算差异」而不是每条提交重下整棵树】
5
+ * 整树重下意味着 N 条提交 × M 个文件,等于把仓库下载 N 遍(大仓直接不可用);
6
+ * 而相邻提交之间通常只改几个文件 ⇒ 按 sha 比对后只下「新增/内容变/权限变」的,
7
+ * 其余复用工作区已有文件,删除的按名单删掉即可。
8
+ *
9
+ * 【为什么单独成模块、且与 git 执行分开】
10
+ * 「算差异」是**可单测的纯逻辑**(新增/改动/删除、权限变化、目录变文件等),
11
+ * 而「跑 git 命令」依赖仓库状态与环境 ⇒ 后者放在执行层,前者在此并单测覆盖。
12
+ *
13
+ * 【一个必须处理的真实限制】GitHub 的 `GET /git/trees/{sha}?recursive=1` 在
14
+ * 条目过多(约 10 万条 / 7MB 响应)时会回 `truncated: true` 且**只给一部分条目**——
15
+ * 此时绝不能当成完整树用(会漏文件、重放出的 tree 与远端不同 ⇒ sha 不同 ⇒ 推不回)。
16
+ * 故本模块提供 blobEntriesOf 显式回报该情况,由调用方决定中止或改走非递归逐层拉取。
17
+ */
18
+
19
+ // replayHistory 要用 clone-history 的「提交环境变量换算」(author/committer/date 回填),
20
+ // 两者分工:clone-history 负责「远端链 → 数据」,本模块负责「数据 → 本地提交」。
21
+ import { commitEnvOf } from './clone-history.js';
22
+
23
+ /**
24
+ * 从 `git/trees/{sha}` 的返回体里取 blob 条目,并显式回报「树被截断」。
25
+ *
26
+ * @param {object} treeJson API 返回体(含 tree: [{path,mode,type,sha,size}], truncated)
27
+ * @returns {{ok:boolean, entries:Array<object>, truncated:boolean, error?:string}}
28
+ */
29
+ export function blobEntriesOf(treeJson) {
30
+ const list = Array.isArray(treeJson?.tree) ? treeJson.tree : null;
31
+ if (!list) return { ok: false, entries: [], truncated: false, error: '返回体缺少 tree 数组' };
32
+ const truncated = treeJson?.truncated === true;
33
+ const entries = list
34
+ .filter((e) => e && e.type === 'blob' && e.path)
35
+ .map((e) => ({ path: String(e.path), mode: String(e.mode || ''), sha: String(e.sha || ''), size: Number(e.size) || 0 }))
36
+ .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
37
+ if (truncated) {
38
+ return { ok: false, entries, truncated: true, error: '远端树过大被截断(truncated)——不能当作完整树使用,需改走非递归逐层拉取' };
39
+ }
40
+ return { ok: true, entries, truncated: false };
41
+ }
42
+
43
+ /**
44
+ * 两次树快照的差异 → 本轮重放要下载/保留/删除的文件。
45
+ *
46
+ * 判据:**sha 不同**(内容变)或 **mode 不同**(可执行位变)都要重下;
47
+ * 路径只在旧树里出现 ⇒ 删除;两边都在且 sha/mode 相同 ⇒ 复用工作区文件(不下载)。
48
+ * 注意:目录变文件 / 文件变目录在 git 里就是「旧路径删除 + 新路径新增」,本函数天然覆盖
49
+ * (路径比对,不假设类型),但**调用方必须保证删除先于下载会破坏目录的路径**——
50
+ * 故返回体分开给出 remove 与 download,由执行层决定顺序(先删后下,见执行层注释)。
51
+ *
52
+ * @param {Array<object>} prevEntries 父提交的 blob 条目(首次提交传空数组)
53
+ * @param {Array<object>} curEntries 当前提交的 blob 条目
54
+ * @returns {{download:Array<object>,keep:Array<object>,remove:Array<string>}}
55
+ */
56
+ export function planTreeDiff(prevEntries = [], curEntries = []) {
57
+ const prev = new Map((Array.isArray(prevEntries) ? prevEntries : []).map((e) => [e.path, e]));
58
+ const cur = new Map((Array.isArray(curEntries) ? curEntries : []).map((e) => [e.path, e]));
59
+ const download = [];
60
+ const keep = [];
61
+ const remove = [];
62
+ for (const [path, e] of cur) {
63
+ const p = prev.get(path);
64
+ if (!p || p.sha !== e.sha || p.mode !== e.mode) download.push(e);
65
+ else keep.push(e);
66
+ }
67
+ for (const [path] of prev) if (!cur.has(path)) remove.push(path);
68
+ const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
69
+ download.sort(byPath);
70
+ keep.sort(byPath);
71
+ remove.sort();
72
+ return { download, keep, remove };
73
+ }
74
+
75
+ /**
76
+ * 重放进度标记:记录「已重放到哪个远端 sha」,供中断后继续(不从头再来)。
77
+ *
78
+ * 为什么需要:大仓重放要跑成百上千次 API 与 git 命令,任何一次网络抖动都会中断;
79
+ * 没有标记就只能整条链重来(实测同类问题:下载链路曾因「每轮清零分片」永远收敛不了)。
80
+ * 标记文件放在仓库的 .git 目录内(不进工作区、不会被 git 跟踪)。
81
+ *
82
+ * @param {string} gitDir 仓库的 .git 目录绝对路径
83
+ * @returns {{path:string}}
84
+ */
85
+ export function replayMarkerPath(gitDir) {
86
+ return { path: `${String(gitDir).replace(/[\\/]+$/, '')}/dsh-clone-history.json` };
87
+ }
88
+
89
+ /**
90
+ * 判断标记是否可用于续跑:分支相同**且**已记录的 sha 确实是当前链上的提交。
91
+ *
92
+ * 为什么要校验 sha 在链上:远端被 force push / 分支重建后,旧标记指向的 sha
93
+ * 可能已不在链上;直接沿用会重放出一条与远端不符的历史(sha 全错 ⇒ 推不回)。
94
+ *
95
+ * @param {object} marker 已读出的标记(可为 null)
96
+ * @param {{branch?:string, shas?:Set<string>|Array<string>}} ctx 当前分支与链上 sha 集合
97
+ * @returns {{resume:boolean, fromSha:string, reason?:string}}
98
+ */
99
+ export function canResumeFrom(marker, { branch = '', shas = [] } = {}) {
100
+ if (!marker || typeof marker !== 'object') return { resume: false, fromSha: '', reason: '无标记' };
101
+ if (String(marker.branch || '') !== String(branch || '')) return { resume: false, fromSha: '', reason: '分支不一致' };
102
+ const set = shas instanceof Set ? shas : new Set(shas || []);
103
+ const fromSha = String(marker.replayedSha || '');
104
+ if (!fromSha || !set.has(fromSha)) return { resume: false, fromSha: '', reason: '标记的 sha 不在当前链上(可能被 force push 或分支重建)' };
105
+ return { resume: true, fromSha };
106
+ }
107
+
108
+ /**
109
+ * 重放编排:按拓扑序逐条重建本地提交。**所有外部动作走 io 注入**,故本函数可离线单测。
110
+ *
111
+ * 【为什么用 write-tree + commit-tree,而不是 `git commit`】
112
+ * ① `commit-tree` **原生支持多个 -p**(合并提交直接给多个父即可),而 `git commit` 造合并
113
+ * 要依赖 HEAD/索引状态机(`-p` 并非其参数),在多父、非线性的重放里极易出错;
114
+ * ② `commit-tree` 完全由「tree + parents + env + message」决定结果 ⇒ 与我们要的
115
+ * 「sha 保真」语义一致(env 里的 author/committer/date 直接进对象);
116
+ * ③ 不依赖工作区是否干净、不触发 hooks。
117
+ * 故 io.commit 的实现应为:暂存变更 → `git write-tree` → `git commit-tree <tree> [-p …]`。
118
+ *
119
+ * @param {object} o
120
+ * @param {Array<object>} o.commits 拓扑序提交链(来自 fetchCommitChain)
121
+ * @param {string} o.branch 分支名
122
+ * @param {object} o.io 执行动作注入:
123
+ * readMarker() → marker|null|writeMarker({branch,replayedSha}) → {ok}
124
+ * fetchTreeEntries(treeSha) → {ok,entries,error}
125
+ * applyDownload(entries) → {ok,failed?,error?}
126
+ * applyRemove(paths) → {ok,error?}
127
+ * commit({env,message,parentShas}) → {ok,sha,error?}
128
+ * @returns {Promise<{ok:boolean,replayed:number,headSha:string,resumedFrom:string,error?:string}>}
129
+ */
130
+ export async function replayHistory({ commits = [], branch = '', io } = {}) {
131
+ if (!io || typeof io.commit !== 'function') return { ok: false, replayed: 0, headSha: '', resumedFrom: '', error: '缺少 io 注入' };
132
+ const list = Array.isArray(commits) ? commits : [];
133
+ if (!list.length) return { ok: false, replayed: 0, headSha: '', resumedFrom: '', error: '提交链为空' };
134
+
135
+ const shas = new Set(list.map((c) => c.sha));
136
+ const marker = typeof io.readMarker === 'function' ? await io.readMarker() : null;
137
+ const can = canResumeFrom(marker, { branch, shas });
138
+ const fromIndex = can.resume ? list.findIndex((c) => c.sha === can.fromSha) : -1;
139
+
140
+ const localShas = new Map(); // 远端 sha → 本地 sha(父映射用)
141
+ let prevEntries = [];
142
+ let start = 0;
143
+ if (fromIndex >= 0) {
144
+ // 续跑:基线用「已重放到的那个提交」的树(它的本地提交已存在),并跳过它本身
145
+ const base = await io.fetchTreeEntries(list[fromIndex].tree);
146
+ if (!base.ok) return { ok: false, replayed: 0, headSha: '', resumedFrom: can.fromSha, error: `续跑基线取树失败:${base.error}` };
147
+ prevEntries = base.entries;
148
+ start = fromIndex + 1;
149
+ }
150
+
151
+ let replayed = 0;
152
+ let headSha = '';
153
+ let resumedFrom = can.resume ? can.fromSha : '';
154
+ for (let i = start; i < list.length; i++) {
155
+ const c = list[i];
156
+ const t = await io.fetchTreeEntries(c.tree);
157
+ if (!t.ok) return { ok: false, replayed, headSha, resumedFrom, error: `取树失败(${c.sha.slice(0, 7)}):${t.error}` };
158
+ const diff = planTreeDiff(prevEntries, t.entries);
159
+ if (diff.remove.length) {
160
+ const rm = await io.applyRemove(diff.remove);
161
+ if (!rm?.ok) return { ok: false, replayed, headSha, resumedFrom, error: `删除失败(${c.sha.slice(0, 7)}):${rm?.error || '未知'}` };
162
+ }
163
+ if (diff.download.length) {
164
+ // 把「正在重放的远端提交 sha」传给下载层:GitHub 的 contents/raw 端点**接受 commit sha 作为 ref**,
165
+ // 故下载到的就是**该提交的版本**,而不是分支 HEAD 的版本。
166
+ // 为什么必须这样:下载层原本按「路径 + 分支」取文件(contentsApiUrl(...,branch)),
167
+ // 在重放里会拿到 HEAD 版本 ⇒ 与 tree 记录的 size 不符(真仓库实测 lib/index.js 期望 15983 实得 15991)
168
+ // ⇒ 长度校验失败、且即使绕过也会把中间提交写成 HEAD 的样子(sha 保真彻底失效)。
169
+ const dl = await io.applyDownload(diff.download, { remoteSha: c.sha });
170
+ if (!dl?.ok) {
171
+ // 失败处**不写标记**:标记指向「最后一个完整重放的提交」,续跑从它的下一个开始
172
+ return { ok: false, replayed, headSha, resumedFrom, error: `下载失败(${c.sha.slice(0, 7)}):${dl?.error || '未知'}` };
173
+ }
174
+ }
175
+ // 父映射:链上不存在的父(depth 截断处)不传——本地没有该对象,传了必然失败
176
+ const parentShas = (c.parents || []).map((p) => localShas.get(p)).filter(Boolean);
177
+ const r = await io.commit({ env: commitEnvOf(c), message: c.message, parentShas });
178
+ if (!r?.ok) return { ok: false, replayed, headSha, resumedFrom, error: `建提交失败(${c.sha.slice(0, 7)}):${r?.error || '未知'}` };
179
+ localShas.set(c.sha, r.sha);
180
+ headSha = r.sha;
181
+ replayed += 1;
182
+ prevEntries = t.entries;
183
+ if (typeof io.writeMarker === 'function') await io.writeMarker({ branch, replayedSha: c.sha });
184
+ }
185
+ return { ok: true, replayed, headSha, resumedFrom };
186
+ }
187
+
188
+ // ─────────────────── git 命令参数构造(纯函数:把「要跑什么」固定下来) ───────────────────
189
+ // 为什么要这一层:接线层(把 io 接到真 git)最容易出错的地方,是**命令与参数顺序**写错
190
+ // (少一个 -p、ref 名写错、配置键大小写错)。把这些固化成纯函数后:
191
+ // ① 可以单测(断言精确参数数组)② 接线层只负责「把这些参数交给 runGit」③ 命令语义集中可查。
192
+ // 核心链条(重放一条提交):addAll → writeTree → commitTree → updateRef。
193
+
194
+ /** `git init`:在目标目录建库(真实历史模式下用,快照模式也走同一条但现在已存在)。 */
195
+ export function initArgs() {
196
+ return ['init'];
197
+ }
198
+
199
+ /** `git remote add <name> <url>`:真实历史模式写真实 git URL(供标准 fetch/push)。 */
200
+ export function setRemoteArgs(name, url) {
201
+ return ['remote', 'add', String(name), String(url)];
202
+ }
203
+
204
+ /** `git config core.fileMode false`:不支持 mode 的卷(CIFS)上抑制「权限变更」噪音。 */
205
+ export function configFileModeArgs(enabled = false) {
206
+ return ['config', 'core.fileMode', enabled ? 'true' : 'false'];
207
+ }
208
+
209
+ /**
210
+ * `git add -A -f`:把工作区当前状态全部暂存(删除也一并暂存)。
211
+ *
212
+ * 为什么必须带 `-f`:重放是**逐字节重建远端树**,而 `git add -A` 会**遵守 .gitignore**——
213
+ * 远端树里存在、却被仓库 .gitignore 忽略的文件不会被暂存 ⇒ 重建出的 tree 与远端不同 ⇒ sha 不同。
214
+ * 真仓库 e2e 实测:远端 master 树 33 个 blob,本地只跟踪到 28 个(差 5 个),
215
+ * 且三条提交的 tree 条条不同 ⇒ tip sha 与远端 HEAD 不一致(正是该问题)。
216
+ */
217
+ export function addAllArgs() {
218
+ return ['add', '-A', '-f'];
219
+ }
220
+
221
+ /** `git write-tree`:把暂存区写成树对象,供 commit-tree 使用。 */
222
+ export function writeTreeArgs() {
223
+ return ['write-tree'];
224
+ }
225
+
226
+ /**
227
+ * `git commit-tree <tree> [-p <parent>…] -m <message>`:由树与父构造提交对象。
228
+ *
229
+ * 为什么不用 `git commit`:commit-tree **原生支持多个 -p**(合并提交直接给多父),
230
+ * 且结果只由 tree + parents + env + message 决定 ⇒ 与「sha 保真」语义一致。
231
+ *
232
+ * @param {{tree:string, parents?:string[], message?:string}} o
233
+ * @returns {string[]} 参数数组
234
+ */
235
+ export function commitTreeArgs({ tree = '', parents = [], message = '' } = {}) {
236
+ const args = ['commit-tree', String(tree)];
237
+ for (const p of parents || []) args.push('-p', String(p));
238
+ args.push('-m', String(message));
239
+ return args;
240
+ }
241
+
242
+ /**
243
+ * `git update-ref <ref> <sha> [<old>]`:把分支/远端跟踪引用指向重放出来的提交。
244
+ * 给了 oldValue 时是「CAS 更新」(引用不是该值则失败),用于避免覆盖并发写入。
245
+ */
246
+ export function updateRefArgs(ref, sha, { oldValue = '' } = {}) {
247
+ const args = ['update-ref', String(ref), String(sha)];
248
+ if (oldValue) args.push(String(oldValue));
249
+ return args;
250
+ }
251
+
252
+ /** `git branch --set-upstream-to=<remote>/<branch> <branch>`:让 branch -vv 显示上游。 */
253
+ export function setUpstreamArgs(branch, remote = 'origin') {
254
+ return ['branch', `--set-upstream-to=${String(remote)}/${String(branch)}`, String(branch)];
255
+ }
256
+
257
+ /** `git rev-parse <rev>`:取引用对应的 sha(接线层校验用)。 */
258
+ export function revParseArgs(rev) {
259
+ return ['rev-parse', String(rev)];
260
+ }
261
+
262
+ /** 远端跟踪引用名:`refs/remotes/<remote>/<branch>`。 */
263
+ export function remoteTrackingRef(remote, branch) {
264
+ return `refs/remotes/${String(remote)}/${String(branch)}`;
265
+ }
266
+
267
+ /** 本地分支引用名:`refs/heads/<branch>`。 */
268
+ export function localBranchRef(branch) {
269
+ return `refs/heads/${String(branch)}`;
270
+ }
271
+
272
+ /** 构造续跑标记内容(写入 .git 内的标记文件,含写入时间便于排查)。 */
273
+ export function markerJson({ branch = '', replayedSha = '', at = '' } = {}) {
274
+ return JSON.stringify({ branch: String(branch), replayedSha: String(replayedSha), at: at || new Date().toISOString() });
275
+ }