dsh-session-sync 0.1.0
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.
- package/ARCHITECTURE.md +86 -0
- package/CHANGELOG.md +18 -0
- package/LICENSE +201 -0
- package/README.es.md +181 -0
- package/README.hi.md +181 -0
- package/README.md +181 -0
- package/README.pt.md +181 -0
- package/README.zh.md +181 -0
- package/SECURITY.md +39 -0
- package/THIRD_PARTY_NOTICES.md +25 -0
- package/cordis.patch.yml +41 -0
- package/index.mjs +775 -0
- package/lib/constants.mjs +109 -0
- package/lib/domain.mjs +29 -0
- package/lib/engine.mjs +289 -0
- package/lib/errors.mjs +99 -0
- package/lib/gate.mjs +152 -0
- package/lib/git.mjs +377 -0
- package/lib/merge.mjs +96 -0
- package/lib/mirror.mjs +120 -0
- package/lib/paths.mjs +107 -0
- package/lib/render.mjs +107 -0
- package/lib/sanitize.mjs +105 -0
- package/lib/status.mjs +69 -0
- package/package.json +144 -0
- package/types.d.ts +132 -0
package/lib/git.mjs
ADDED
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
// lib/git.mjs — git 命令层(零 DSH 依赖;runner 由 index.mjs 经 ctx.subprocess 注入)。
|
|
2
|
+
//
|
|
3
|
+
// 安全边界:
|
|
4
|
+
// - 动词白名单 + 参数断言(运行时强制执行,防未来改坏);
|
|
5
|
+
// - 绝不发出 force push(`-f`/`--force`/`--force-with-lease`/`+refspec` 全拒绝);
|
|
6
|
+
// - 绝不发出 reset/clean/rebase/checkout 分支切换——工作树只经 add/commit/
|
|
7
|
+
// merge(--no-commit)/checkout(--ours|--theirs 显式路径) 变更;
|
|
8
|
+
// - 错误消息嵌入前统一脱敏(remote 凭据、token 形态一律 redactText)。
|
|
9
|
+
//
|
|
10
|
+
// runner 契约(index.mjs 构造):
|
|
11
|
+
// run(args, { cwd, signal, timeoutMs, binary, maxBytes }) → { code, stdout, stderr }
|
|
12
|
+
// stdout:binary=false 时为 UTF-8 文本;binary=true 时为 Buffer(原始字节)。
|
|
13
|
+
|
|
14
|
+
import { redactText } from './sanitize.mjs'
|
|
15
|
+
import { gitFailed, pushRejected } from './errors.mjs'
|
|
16
|
+
import { LIMITS } from './constants.mjs'
|
|
17
|
+
|
|
18
|
+
/** 允许的顶层动词。 */
|
|
19
|
+
export const ALLOWED_VERBS = new Set([
|
|
20
|
+
'init',
|
|
21
|
+
'config',
|
|
22
|
+
'remote',
|
|
23
|
+
'add',
|
|
24
|
+
'commit',
|
|
25
|
+
'push',
|
|
26
|
+
'fetch',
|
|
27
|
+
'merge',
|
|
28
|
+
'merge-base',
|
|
29
|
+
'rev-parse',
|
|
30
|
+
'log',
|
|
31
|
+
'diff',
|
|
32
|
+
'cat-file',
|
|
33
|
+
'show',
|
|
34
|
+
'checkout',
|
|
35
|
+
'ls-files',
|
|
36
|
+
'status',
|
|
37
|
+
])
|
|
38
|
+
|
|
39
|
+
/** 断言命令是白名单内的安全原语。 */
|
|
40
|
+
export function assertSafe(args) {
|
|
41
|
+
const verb = args[0] ?? ''
|
|
42
|
+
if (!ALLOWED_VERBS.has(verb)) {
|
|
43
|
+
throw gitFailed('assert', `forbidden git verb ${JSON.stringify(verb)} (whitelist violation)`)
|
|
44
|
+
}
|
|
45
|
+
if (verb === 'push') {
|
|
46
|
+
for (const arg of args.slice(1)) {
|
|
47
|
+
if (arg === '-f' || arg === '--force' || arg === '--force-with-lease' || arg === '--mirror' || arg.startsWith('+')) {
|
|
48
|
+
throw gitFailed('assert', `git push argument ${JSON.stringify(arg)} is forbidden (never force-push)`)
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
if (verb === 'checkout' && !(args.includes('--ours') || args.includes('--theirs'))) {
|
|
53
|
+
throw gitFailed('assert', 'git checkout is only allowed with --ours/--theirs (no branch switching)')
|
|
54
|
+
}
|
|
55
|
+
if (verb === 'merge' && !(args.includes('--no-commit') || args.includes('--abort'))) {
|
|
56
|
+
throw gitFailed('assert', 'git merge is only allowed with --no-commit or --abort')
|
|
57
|
+
}
|
|
58
|
+
if (verb === 'commit' && args.includes('--amend')) {
|
|
59
|
+
throw gitFailed('assert', 'git commit --amend is forbidden (history is append-only)')
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* git 同步后端。所有命令串行经内部互斥链执行(每仓库一把)。
|
|
65
|
+
*/
|
|
66
|
+
export class GitBackend {
|
|
67
|
+
/** @type {(args: string[], opts?: object) => Promise<{code: number, stdout: string|Buffer, stderr: string}>} */
|
|
68
|
+
#run
|
|
69
|
+
/** @type {string} 工作树根。 */
|
|
70
|
+
#repoDir
|
|
71
|
+
/** @type {string} 远端地址(未脱敏原文,只用于 git 命令;展示一律 sanitizeRemote)。 */
|
|
72
|
+
#remote
|
|
73
|
+
/** @type {string} 分支名。 */
|
|
74
|
+
#branch
|
|
75
|
+
/** @type {string} 提交者名。 */
|
|
76
|
+
#commitName
|
|
77
|
+
/** @type {string} 提交者邮箱。 */
|
|
78
|
+
#commitEmail
|
|
79
|
+
/** @type {Promise<unknown>} 每仓库串行链。 */
|
|
80
|
+
#chain = Promise.resolve()
|
|
81
|
+
/** @type {number} 单条命令超时。 */
|
|
82
|
+
#timeoutMs
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* @param {object} deps - {repoDir, remote, branch, commitName, commitEmail, run, timeoutMs}。
|
|
86
|
+
*/
|
|
87
|
+
constructor(deps) {
|
|
88
|
+
this.#run = deps.run
|
|
89
|
+
this.#repoDir = deps.repoDir
|
|
90
|
+
this.#remote = deps.remote
|
|
91
|
+
this.#branch = deps.branch
|
|
92
|
+
this.#commitName = deps.commitName
|
|
93
|
+
this.#commitEmail = deps.commitEmail
|
|
94
|
+
this.#timeoutMs = deps.timeoutMs
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* 串行执行:同一仓库的所有操作按序排队(镜像/推/拉互不穿插)。
|
|
99
|
+
* @template T
|
|
100
|
+
* @param {() => Promise<T>} fn - 排队的操作。
|
|
101
|
+
* @returns {Promise<T>}
|
|
102
|
+
*/
|
|
103
|
+
schedule(fn) {
|
|
104
|
+
const run = this.#chain.then(fn, fn)
|
|
105
|
+
this.#chain = run.then(() => undefined, () => undefined)
|
|
106
|
+
return run
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* 执行一条 git 命令(白名单断言 → runner → 失败包装)。
|
|
111
|
+
* @param {string[]} args - git 参数(不含 gitBin)。
|
|
112
|
+
* @param {object} [opts] - {binary?: boolean, signal?: AbortSignal}。
|
|
113
|
+
* @returns {Promise<{code: number, stdout: string|Buffer, stderr: string}>}
|
|
114
|
+
*/
|
|
115
|
+
async #git(args, opts = {}) {
|
|
116
|
+
assertSafe(args)
|
|
117
|
+
try {
|
|
118
|
+
return await this.#run(args, {
|
|
119
|
+
cwd: this.#repoDir,
|
|
120
|
+
binary: opts.binary ?? false,
|
|
121
|
+
timeoutMs: this.#timeoutMs,
|
|
122
|
+
signal: opts.signal,
|
|
123
|
+
})
|
|
124
|
+
} catch (error) {
|
|
125
|
+
throw gitFailed(args[0] ?? 'git', redactText(error instanceof Error ? error.message : String(error)))
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** 必成功的 git 调用(code !== 0 → gitFailed,stderr 尾部脱敏嵌入)。 */
|
|
130
|
+
async #must(args, opts = {}) {
|
|
131
|
+
const result = await this.#git(args, opts)
|
|
132
|
+
if (result.code !== 0) {
|
|
133
|
+
const tail = redactText(String(result.stderr ?? '')).trim().split('\n').slice(-3).join(' | ') || `exit ${result.code}`
|
|
134
|
+
throw gitFailed(args[0] ?? 'git', tail)
|
|
135
|
+
}
|
|
136
|
+
return result
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** 可选成功的 git 调用(非零退出返回 null;runner/白名单错误照常抛出)。 */
|
|
140
|
+
async #maybe(args, opts = {}) {
|
|
141
|
+
const result = await this.#git(args, opts)
|
|
142
|
+
return result.code === 0 ? result : null
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** 该目录是否已是 git 仓库。 */
|
|
146
|
+
async isRepo() {
|
|
147
|
+
const out = await this.#maybe(['rev-parse', '--is-inside-work-tree'])
|
|
148
|
+
return out !== null && String(out.stdout).trim() === 'true'
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* 本地初始化(无 remote、无提交):init(如缺)→ 禁用行尾转换 → 提交者身份。
|
|
153
|
+
* 供 status 与 bootstrap 共用;repoDir 必须已由调用方(引擎)建好。
|
|
154
|
+
* @returns {Promise<void>}
|
|
155
|
+
*/
|
|
156
|
+
async ensureRepo() {
|
|
157
|
+
if (!(await this.isRepo())) {
|
|
158
|
+
await this.#must(['init', '-b', this.#branch])
|
|
159
|
+
}
|
|
160
|
+
// 字节镜像必须逐字节保真:core.autocrlf=false 关闭 checkout/checkin 的
|
|
161
|
+
// CRLF/LF 转换(否则 Windows 检出会把 LF 会话字节改成 CRLF,破坏镜像)。
|
|
162
|
+
await this.#must(['config', 'core.autocrlf', 'false'])
|
|
163
|
+
await this.#must(['config', 'user.name', this.#commitName])
|
|
164
|
+
await this.#must(['config', 'user.email', this.#commitEmail])
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* 引导仓库:本地初始化 → origin remote(增/改)→ 初始提交。
|
|
169
|
+
* 幂等:每次挂载/首次操作都走一遍,代价为几条本地命令。
|
|
170
|
+
* @returns {Promise<void>}
|
|
171
|
+
*/
|
|
172
|
+
async bootstrap() {
|
|
173
|
+
await this.ensureRepo()
|
|
174
|
+
const current = await this.#maybe(['remote', 'get-url', 'origin'])
|
|
175
|
+
if (current === null) {
|
|
176
|
+
await this.#must(['remote', 'add', 'origin', this.#remote])
|
|
177
|
+
} else if (String(current.stdout).trim() !== this.#remote.trim()) {
|
|
178
|
+
await this.#must(['remote', 'set-url', 'origin', this.#remote])
|
|
179
|
+
}
|
|
180
|
+
const head = await this.headSha()
|
|
181
|
+
if (head === undefined) {
|
|
182
|
+
await this.commitAll('dsh-session-sync: initial commit', { allowEmpty: true })
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** 当前 HEAD sha;unborn 时为 undefined。 */
|
|
187
|
+
async headSha() {
|
|
188
|
+
const out = await this.#maybe(['rev-parse', '--verify', 'HEAD'])
|
|
189
|
+
const sha = out === null ? '' : String(out.stdout).trim()
|
|
190
|
+
return sha === '' ? undefined : sha
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** 远端跟踪引用(refs/remotes/origin/<branch>)sha;未拉取过为 undefined。 */
|
|
194
|
+
async remoteHeadSha() {
|
|
195
|
+
const out = await this.#maybe(['rev-parse', '--verify', `refs/remotes/origin/${this.#branch}`])
|
|
196
|
+
const sha = out === null ? '' : String(out.stdout).trim()
|
|
197
|
+
return sha === '' ? undefined : sha
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** 两提交的合并基点 sha;无公共祖先为 undefined。 */
|
|
201
|
+
async mergeBaseOf(left, right) {
|
|
202
|
+
const out = await this.#maybe(['merge-base', left, right])
|
|
203
|
+
const sha = out === null ? '' : String(out.stdout).trim()
|
|
204
|
+
return sha === '' ? undefined : sha
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** 提交数统计(log --oneline 行数;rev-list 不进白名单)。 */
|
|
208
|
+
async countCommitsSafe(left, right) {
|
|
209
|
+
if (left === right) return 0
|
|
210
|
+
const out = await this.#maybe(['log', '--oneline', `${left}..${right}`])
|
|
211
|
+
if (out === null) return 0
|
|
212
|
+
const lines = String(out.stdout).trim()
|
|
213
|
+
return lines === '' ? 0 : lines.split('\n').length
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* 工作树全量提交(add -A → 有变更才 commit)。返回新 HEAD sha 或
|
|
218
|
+
* 无变更时的 null。
|
|
219
|
+
* @param {string} message - 提交信息(长度已截断)。
|
|
220
|
+
* @param {object} [opts] - {allowEmpty?: boolean}。
|
|
221
|
+
* @returns {Promise<string|null>}
|
|
222
|
+
*/
|
|
223
|
+
async commitAll(message, opts = {}) {
|
|
224
|
+
await this.#must(['add', '-A'])
|
|
225
|
+
const status = await this.#must(['status', '--porcelain'])
|
|
226
|
+
if (String(status.stdout).trim() === '' && !(opts.allowEmpty ?? false)) return null
|
|
227
|
+
await this.#must(['commit', '-m', message.slice(0, LIMITS.MAX_COMMIT_MESSAGE_LENGTH), ...(opts.allowEmpty === true ? ['--allow-empty'] : [])])
|
|
228
|
+
return this.headSha() ?? null
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* push 到远端(显式 refspec HEAD:refs/heads/<branch>,与本地分支名解耦)。
|
|
233
|
+
* 被拒(远端领先)→ PUSH_REJECTED;绝不重试强推。
|
|
234
|
+
* @param {object} [opts] - {signal?: AbortSignal}。
|
|
235
|
+
* @returns {Promise<void>}
|
|
236
|
+
*/
|
|
237
|
+
async push(opts = {}) {
|
|
238
|
+
const result = await this.#git(['push', 'origin', `HEAD:refs/heads/${this.#branch}`], { signal: opts.signal })
|
|
239
|
+
if (result.code !== 0) {
|
|
240
|
+
throw pushRejected(redactText(String(result.stderr ?? '')).trim().split('\n').slice(-3).join(' | ') || `exit ${result.code}`)
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/**
|
|
245
|
+
* fetch 远端分支到远端跟踪引用(+ 只影响跟踪引用,绝不触碰工作树)。
|
|
246
|
+
* 远端尚无该分支(首次 push 前)返回 false。
|
|
247
|
+
* @param {object} [opts] - {signal?: AbortSignal}。
|
|
248
|
+
* @returns {Promise<boolean>} 是否拿到远端分支。
|
|
249
|
+
*/
|
|
250
|
+
async fetch(opts = {}) {
|
|
251
|
+
const result = await this.#git(['fetch', 'origin', `+${this.#branch}:refs/remotes/origin/${this.#branch}`], { signal: opts.signal })
|
|
252
|
+
if (result.code === 0) return true
|
|
253
|
+
const stderr = String(result.stderr ?? '')
|
|
254
|
+
if (/couldn't find remote ref/i.test(stderr)) return false
|
|
255
|
+
throw gitFailed('fetch', redactText(stderr).trim().split('\n').slice(-3).join(' | ') || `exit ${result.code}`)
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* 开始合并:git merge --no-commit --allow-unrelated-histories <remoteHead>。
|
|
260
|
+
* 干净自动合并退出 0(变更已暂存,待 commit --no-edit 落合并提交);
|
|
261
|
+
* 冲突退出 1(工作树为 ours + 冲突标记,逐路径 resolve 后 add)。
|
|
262
|
+
* 已是最新退出 0 且无 MERGE_HEAD。
|
|
263
|
+
* --allow-unrelated-histories:首拉场景(本地空仓库 + 远端独立历史)必
|
|
264
|
+
* 需;两历史已相关时该旗标是无害 no-op。
|
|
265
|
+
* @param {string} remoteHead - 远端头 sha。
|
|
266
|
+
* @returns {Promise<{conflicted: boolean, inProgress: boolean}>}
|
|
267
|
+
*/
|
|
268
|
+
async beginMerge(remoteHead) {
|
|
269
|
+
const result = await this.#git(['merge', '--no-commit', '--allow-unrelated-histories', remoteHead])
|
|
270
|
+
if (result.code === 0) {
|
|
271
|
+
const stderr = String(result.stderr ?? '')
|
|
272
|
+
if (/already up to date/i.test(stderr)) return { conflicted: false, inProgress: false }
|
|
273
|
+
return { conflicted: false, inProgress: true }
|
|
274
|
+
}
|
|
275
|
+
const inProgress = await this.mergeInProgress()
|
|
276
|
+
return { conflicted: inProgress, inProgress }
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** 是否存在进行中的合并(MERGE_HEAD)。 */
|
|
280
|
+
async mergeInProgress() {
|
|
281
|
+
const out = await this.#maybe(['rev-parse', '--verify', 'MERGE_HEAD'])
|
|
282
|
+
return out !== null && String(out.stdout).trim() !== ''
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/** 放弃进行中的合并(失败路径恢复用)。 */
|
|
286
|
+
async abortMerge() {
|
|
287
|
+
if (!(await this.mergeInProgress())) return
|
|
288
|
+
await this.#must(['merge', '--abort'])
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* 冲突路径清单(ls-files -u 解析:stage 1=base、2=ours、3=theirs)。
|
|
293
|
+
* @returns {Promise<Array<{path: string, base?: string, ours?: string, theirs?: string}>>}
|
|
294
|
+
*/
|
|
295
|
+
async conflictedPaths() {
|
|
296
|
+
const out = await this.#must(['ls-files', '-u'])
|
|
297
|
+
const byPath = new Map()
|
|
298
|
+
for (const line of String(out.stdout).split('\n')) {
|
|
299
|
+
if (line.trim() === '') continue
|
|
300
|
+
// 格式:<mode> <sha> <stage>\t<path>(未合并路径的 sha 为全零时也有 stage)。
|
|
301
|
+
const [meta, ...rest] = line.split('\t')
|
|
302
|
+
const rel = rest.join('\t')
|
|
303
|
+
const stage = (meta ?? '').split(/\s+/)[2]
|
|
304
|
+
let entry = byPath.get(rel)
|
|
305
|
+
if (entry === undefined) {
|
|
306
|
+
entry = { path: rel }
|
|
307
|
+
byPath.set(rel, entry)
|
|
308
|
+
}
|
|
309
|
+
if (stage === '1') entry.base = (meta ?? '').split(/\s+/)[1]
|
|
310
|
+
else if (stage === '2') entry.ours = (meta ?? '').split(/\s+/)[1]
|
|
311
|
+
else if (stage === '3') entry.theirs = (meta ?? '').split(/\s+/)[1]
|
|
312
|
+
}
|
|
313
|
+
return [...byPath.values()]
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* 读冲突索引阶段 blob 的原始字节(cat-file blob :<stage>:<path>)。
|
|
318
|
+
* @param {string} stage - 1|2|3。
|
|
319
|
+
* @param {string} rel - 仓库相对路径。
|
|
320
|
+
* @returns {Promise<Buffer|undefined>} 内容;阶段缺失为 undefined。
|
|
321
|
+
*/
|
|
322
|
+
async readStageBlob(stage, rel) {
|
|
323
|
+
const out = await this.#maybe(['cat-file', 'blob', `:${stage}:${rel}`], { binary: true })
|
|
324
|
+
if (out === null) return undefined
|
|
325
|
+
return Buffer.isBuffer(out.stdout) ? out.stdout : Buffer.from(String(out.stdout))
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/**
|
|
329
|
+
* 从索引阶段检出单文件到工作树(仅 --ours/--theirs + 显式路径)。
|
|
330
|
+
* @param {'ours'|'theirs'} which - 检出哪一侧。
|
|
331
|
+
* @param {string} rel - 仓库相对路径。
|
|
332
|
+
* @returns {Promise<void>}
|
|
333
|
+
*/
|
|
334
|
+
async checkoutStage(which, rel) {
|
|
335
|
+
await this.#must(['checkout', `--${which}`, '--', rel])
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/** 暂存全部(冲突解决后、合并提交前)。 */
|
|
339
|
+
async addAll() {
|
|
340
|
+
await this.#must(['add', '-A'])
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/** 落合并提交(MERGE_HEAD 在时生成真正的双亲合并提交)。 */
|
|
344
|
+
async commitMerge() {
|
|
345
|
+
if (!(await this.mergeInProgress())) return null
|
|
346
|
+
await this.#must(['commit', '--no-edit'])
|
|
347
|
+
return this.headSha() ?? null
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/** 最近 N 条提交摘要(log --oneline -n)。 */
|
|
351
|
+
async recentCommits(limit) {
|
|
352
|
+
const out = await this.#maybe(['log', '--oneline', `-n${Math.max(1, Math.floor(limit))}`])
|
|
353
|
+
if (out === null) return []
|
|
354
|
+
return String(out.stdout).trim().split('\n').filter(line => line.length > 0)
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
/** 工作树脏状态(status --porcelain 原始行)。 */
|
|
358
|
+
async dirtyLines() {
|
|
359
|
+
// -uall: list every untracked FILE individually (porcelain otherwise
|
|
360
|
+
// collapses a fully-untracked directory into one '?? dir/' entry).
|
|
361
|
+
const out = await this.#must(['status', '--porcelain', '-uall'])
|
|
362
|
+
return String(out.stdout).split('\n').filter(line => line.trim() !== '')
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/** 已跟踪文件清单(ls-files)。 */
|
|
366
|
+
async lsFiles() {
|
|
367
|
+
const out = await this.#must(['ls-files'])
|
|
368
|
+
return String(out.stdout).split('\n').filter(line => line.length > 0)
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** 两提交的路径差异统计(diff --stat)。 */
|
|
372
|
+
async diffStat(left, right) {
|
|
373
|
+
const out = await this.#maybe(['diff', '--stat', left, right])
|
|
374
|
+
if (out === null) return ''
|
|
375
|
+
return String(out.stdout).trim()
|
|
376
|
+
}
|
|
377
|
+
}
|
package/lib/merge.mjs
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
// lib/merge.mjs — append-only 三分支合并语义(纯函数,零依赖)。
|
|
2
|
+
//
|
|
3
|
+
// 会话日志是 append-only:三方(合并基点 base、本地 ours、远端 theirs)
|
|
4
|
+
// 逐文件按字节比较。规则(绝不静默覆盖——ours/theirs 任一字节都会存续):
|
|
5
|
+
// - 相同(ours == theirs)→ 保留 ours;
|
|
6
|
+
// - 仅本地变(theirs == base)→ 保留 ours;
|
|
7
|
+
// - 仅远端变(ours == base)→ 采纳 theirs(本地无增量可丢,不是覆盖);
|
|
8
|
+
// - 双边纯追加(base 是 ours 与 theirs 的共同字节前缀)→ 保留 ours 在原路径,
|
|
9
|
+
// theirs 整体留存为 fork 文件(两边保留);
|
|
10
|
+
// - 其余(任一侧重写/压缩打包/删除等真实分歧)→ 同样保留 ours + fork theirs,
|
|
11
|
+
// 并响亮报告 diverged,绝不替用户取舍。
|
|
12
|
+
//
|
|
13
|
+
// 内容按 Buffer 语义比较:zstd 等二进制日志与 UTF-8 文本同一套规则。
|
|
14
|
+
|
|
15
|
+
import { MERGE_KINDS } from './constants.mjs'
|
|
16
|
+
|
|
17
|
+
/** 任意内容形态 → Buffer|undefined。 */
|
|
18
|
+
function norm(value) {
|
|
19
|
+
if (value === undefined || value === null) return undefined
|
|
20
|
+
if (Buffer.isBuffer(value)) return value
|
|
21
|
+
return Buffer.from(String(value))
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** a 是否为 b 的字节前缀(等长即相等)。 */
|
|
25
|
+
function isPrefix(prefix, whole) {
|
|
26
|
+
return prefix !== undefined && whole !== undefined
|
|
27
|
+
&& prefix.length <= whole.length
|
|
28
|
+
&& whole.subarray(0, prefix.length).equals(prefix)
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* 单路径三方分类。
|
|
33
|
+
* @param {Buffer|string|undefined} base - 合并基点内容。
|
|
34
|
+
* @param {Buffer|string|undefined} ours - 本地内容。
|
|
35
|
+
* @param {Buffer|string|undefined} theirs - 远端内容。
|
|
36
|
+
* @returns {{kind: string, keepOurs: boolean, forkTheirs: boolean}}
|
|
37
|
+
* kind ∈ MERGE_KINDS;keepOurs=false 时采纳 theirs(theirs-only)。
|
|
38
|
+
*/
|
|
39
|
+
export function classifyPath(base, ours, theirs) {
|
|
40
|
+
const b = norm(base)
|
|
41
|
+
const o = norm(ours)
|
|
42
|
+
const t = norm(theirs)
|
|
43
|
+
if (o !== undefined && t !== undefined && o.equals(t)) {
|
|
44
|
+
return { kind: MERGE_KINDS.IDENTICAL, keepOurs: true, forkTheirs: false }
|
|
45
|
+
}
|
|
46
|
+
if (o === undefined && t === undefined) {
|
|
47
|
+
return { kind: MERGE_KINDS.IDENTICAL, keepOurs: true, forkTheirs: false }
|
|
48
|
+
}
|
|
49
|
+
// 仅本地变:远端仍是基点内容。
|
|
50
|
+
if (equalsOrBothMissing(t, b)) {
|
|
51
|
+
return { kind: MERGE_KINDS.OURS_ONLY, keepOurs: true, forkTheirs: false }
|
|
52
|
+
}
|
|
53
|
+
// 仅远端变:本地仍是基点内容 → 采纳远端(本地无增量,非覆盖)。
|
|
54
|
+
if (equalsOrBothMissing(o, b)) {
|
|
55
|
+
return { kind: MERGE_KINDS.THEIRS_ONLY, keepOurs: false, forkTheirs: false }
|
|
56
|
+
}
|
|
57
|
+
// 双边纯追加:共同基点前缀 + 各自后缀 → 两边保留,远端转 fork 文件。
|
|
58
|
+
if (isPrefix(b, o) && isPrefix(b, t)) {
|
|
59
|
+
return { kind: MERGE_KINDS.APPEND_BOTH, keepOurs: true, forkTheirs: true }
|
|
60
|
+
}
|
|
61
|
+
// 真实分歧(重写/打包/单侧删除等):同样两边保留 + 响亮报告。
|
|
62
|
+
return { kind: MERGE_KINDS.DIVERGED, keepOurs: true, forkTheirs: true }
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** 两侧同时缺失或字节相等。 */
|
|
66
|
+
function equalsOrBothMissing(left, right) {
|
|
67
|
+
if (left === undefined && right === undefined) return true
|
|
68
|
+
if (left === undefined || right === undefined) return false
|
|
69
|
+
return left.equals(right)
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* 整批冲突路径的合并计划(pull 阶段对 merge 冲突路径逐一调用 classifyPath)。
|
|
74
|
+
* @param {Array<{path: string, base?: Buffer|string, ours?: Buffer|string, theirs?: Buffer|string}>} conflicts - 冲突路径。
|
|
75
|
+
* @returns {{resolutions: Array<{path: string, kind: string, adoptTheirs: boolean, forkTheirs: boolean}>, summary: {kept: number, adopted: number, appended: number, diverged: number, forkPaths: string[]}}}
|
|
76
|
+
*/
|
|
77
|
+
export function planMerge(conflicts) {
|
|
78
|
+
const resolutions = []
|
|
79
|
+
const summary = { kept: 0, adopted: 0, appended: 0, diverged: 0, forkPaths: [] }
|
|
80
|
+
for (const entry of conflicts) {
|
|
81
|
+
const verdict = classifyPath(entry.base, entry.ours, entry.theirs)
|
|
82
|
+
const resolution = {
|
|
83
|
+
path: entry.path,
|
|
84
|
+
kind: verdict.kind,
|
|
85
|
+
adoptTheirs: !verdict.keepOurs,
|
|
86
|
+
forkTheirs: verdict.forkTheirs,
|
|
87
|
+
}
|
|
88
|
+
resolutions.push(resolution)
|
|
89
|
+
if (verdict.kind === MERGE_KINDS.THEIRS_ONLY) summary.adopted += 1
|
|
90
|
+
else summary.kept += 1
|
|
91
|
+
if (verdict.kind === MERGE_KINDS.APPEND_BOTH) summary.appended += 1
|
|
92
|
+
if (verdict.kind === MERGE_KINDS.DIVERGED) summary.diverged += 1
|
|
93
|
+
if (verdict.forkTheirs) summary.forkPaths.push(entry.path)
|
|
94
|
+
}
|
|
95
|
+
return { resolutions, summary }
|
|
96
|
+
}
|
package/lib/mirror.mjs
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
// lib/mirror.mjs — 会话目录 → git 工作树的字节镜像(node:fs;零 DSH 依赖)。
|
|
2
|
+
//
|
|
3
|
+
// 会话文件一律按不透明字节复制(JSONL/zstd 等物理编码属于宿主,插件不解析)。
|
|
4
|
+
// 安全边界:
|
|
5
|
+
// - 绝不跟随符号链接(源或目标为链接一律跳过并报告,杜绝写出根外);
|
|
6
|
+
// - 删除仅限工作树内、源已不存在、且非 fork 文件的常规文件;
|
|
7
|
+
// - fork 文件(FORK_NAME_RE)永不复制、永不删除——冲突双方字节的持久载体。
|
|
8
|
+
|
|
9
|
+
import { promises as fs } from 'node:fs'
|
|
10
|
+
import path from 'node:path'
|
|
11
|
+
import { FORK_NAME_RE } from './constants.mjs'
|
|
12
|
+
|
|
13
|
+
/** 递归枚举 root 下全部常规文件(POSIX 相对路径;符号链接跳过并回报)。 */
|
|
14
|
+
async function listFiles(root) {
|
|
15
|
+
const files = []
|
|
16
|
+
const skipped = []
|
|
17
|
+
const walk = async (dir) => {
|
|
18
|
+
const entries = await fs.readdir(dir, { withFileTypes: true })
|
|
19
|
+
for (const entry of entries) {
|
|
20
|
+
const absolute = path.join(dir, entry.name)
|
|
21
|
+
if (entry.isSymbolicLink()) {
|
|
22
|
+
skipped.push(absolute)
|
|
23
|
+
continue
|
|
24
|
+
}
|
|
25
|
+
if (entry.isDirectory()) {
|
|
26
|
+
await walk(absolute)
|
|
27
|
+
continue
|
|
28
|
+
}
|
|
29
|
+
if (entry.isFile()) {
|
|
30
|
+
files.push({ absolute, rel: path.relative(root, absolute).split(path.sep).join('/') })
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
await walk(root)
|
|
35
|
+
return { files, skipped }
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** 内容一致则跳过写(返回 false),否则覆写(返回 true)。 */
|
|
39
|
+
async function writeIfDifferent(target, content) {
|
|
40
|
+
try {
|
|
41
|
+
const existing = await fs.readFile(target)
|
|
42
|
+
if (existing.equals(content)) return false
|
|
43
|
+
} catch {
|
|
44
|
+
// 目标不存在 → 照写。
|
|
45
|
+
}
|
|
46
|
+
await fs.mkdir(path.dirname(target), { recursive: true })
|
|
47
|
+
await fs.writeFile(target, content)
|
|
48
|
+
return true
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* 把 sessionRoot 镜像进 <repoDir>/<mirrorDir>/…。
|
|
53
|
+
* @param {object} deps - {sessionRoot, repoDir, mirrorDir, forkNameRe?}。
|
|
54
|
+
* @returns {Promise<{mirrored: number, unchanged: number, skippedLinks: string[], deleted: string[], forkedPreserved: string[]}>}
|
|
55
|
+
*/
|
|
56
|
+
export async function mirrorSessionRoot(deps) {
|
|
57
|
+
const forkRe = deps.forkNameRe ?? FORK_NAME_RE
|
|
58
|
+
const source = await listFiles(deps.sessionRoot)
|
|
59
|
+
const mirrorRoot = path.join(deps.repoDir, deps.mirrorDir)
|
|
60
|
+
const targets = new Set()
|
|
61
|
+
|
|
62
|
+
let mirrored = 0
|
|
63
|
+
let unchanged = 0
|
|
64
|
+
for (const file of source.files) {
|
|
65
|
+
const target = path.join(mirrorRoot, ...file.rel.split('/'))
|
|
66
|
+
targets.add(file.rel)
|
|
67
|
+
const wrote = await writeIfDifferent(target, await fs.readFile(file.absolute))
|
|
68
|
+
if (wrote) mirrored += 1
|
|
69
|
+
else unchanged += 1
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// 删除:目标树中源已不存在、且非 fork 命名的文件。
|
|
73
|
+
const deleted = []
|
|
74
|
+
const forkedPreserved = []
|
|
75
|
+
const targetFiles = []
|
|
76
|
+
try {
|
|
77
|
+
const walk = async (dir) => {
|
|
78
|
+
const entries = await fs.readdir(dir, { withFileTypes: true })
|
|
79
|
+
for (const entry of entries) {
|
|
80
|
+
const absolute = path.join(dir, entry.name)
|
|
81
|
+
if (entry.isSymbolicLink()) continue
|
|
82
|
+
if (entry.isDirectory()) {
|
|
83
|
+
await walk(absolute)
|
|
84
|
+
continue
|
|
85
|
+
}
|
|
86
|
+
if (entry.isFile()) targetFiles.push(absolute)
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
await walk(mirrorRoot)
|
|
90
|
+
} catch {
|
|
91
|
+
// 镜像根尚不存在 → 无删除可做。
|
|
92
|
+
}
|
|
93
|
+
for (const absolute of targetFiles) {
|
|
94
|
+
const rel = path.relative(mirrorRoot, absolute).split(path.sep).join('/')
|
|
95
|
+
const basename = path.posix.basename(rel)
|
|
96
|
+
if (forkRe.test(basename)) {
|
|
97
|
+
forkedPreserved.push(rel)
|
|
98
|
+
continue
|
|
99
|
+
}
|
|
100
|
+
if (!targets.has(rel)) {
|
|
101
|
+
await fs.unlink(absolute)
|
|
102
|
+
deleted.push(rel)
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
return { mirrored, unchanged, skippedLinks: source.skipped, deleted, forkedPreserved }
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* 确保设备身份文件内容为 deviceId(不同才写;返回是否写入)。
|
|
111
|
+
* @param {string} repoDir - 同步仓库根。
|
|
112
|
+
* @param {string} deviceFile - 文件名(repoDir 直下)。
|
|
113
|
+
* @param {string} deviceId - 设备 id。
|
|
114
|
+
* @returns {Promise<boolean>} 是否写入。
|
|
115
|
+
*/
|
|
116
|
+
export async function ensureDeviceFile(repoDir, deviceFile, deviceId) {
|
|
117
|
+
const target = path.join(repoDir, deviceFile)
|
|
118
|
+
const content = Buffer.from(`${deviceId}\n`)
|
|
119
|
+
return writeIfDifferent(target, content)
|
|
120
|
+
}
|