dsh-session-sync 0.1.4 → 0.2.1

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/index.mjs CHANGED
@@ -45,6 +45,9 @@ import {
45
45
  import { assertNestingSafe, resolveRepoDir, resolveSessionRoot } from './lib/paths.mjs'
46
46
  import { GitBackend } from './lib/git.mjs'
47
47
  import { SyncEngine } from './lib/engine.mjs'
48
+ import { EncryptedBackend, encryptTree, decryptTree, mergeTrees } from './lib/encrypted.mjs'
49
+ import { selectEncryptionMode } from './lib/backend.mjs'
50
+ import { detectAge, ageEncrypt, ageDecrypt } from './lib/age.mjs'
48
51
  import { collectStatus } from './lib/status.mjs'
49
52
  import { renderDiff, renderPull, renderPush, renderStatus, errorValue } from './lib/render.mjs'
50
53
  import { confirmSync, hasOpenTurn, makeEventGate, maybeAppendSessionEvent } from './lib/gate.mjs'
@@ -92,6 +95,9 @@ export function probeIgnorableAppend() {
92
95
  * @property {string} [remote] 远端地址(自定义 remote;pull/push 前必须非空,status/diff 不需要)。
93
96
  * @property {string} [branch] 远端分支名(默认 main)。
94
97
  * @property {string} [gitBin] git 可执行路径(默认 'git')。
98
+ * @property {string} [ageBin] age 可执行路径(默认 'age';backend: encrypted 时探测,缺失降级明文)。
99
+ * @property {string} [ageRecipient] age 收件人(公钥/身份串;空 = 无法加密,降级明文)。
100
+ * @property {string} [ageIdentity] age 身份文件路径(无口令私钥;空 = 无法解密,降级明文)。
95
101
  * @property {boolean} [autoPullOnStart] 挂载时自动拉取一次(配置即授权,不再确认)。
96
102
  * @property {boolean} [autoPushOnTurnEnd] 每个 turn/end 后自动推送(配置即授权)。
97
103
  * @property {number} [pullIntervalMinutes] 周期自动拉取间隔分钟(0 = 关闭)。
@@ -112,6 +118,9 @@ export const Config = Schema.object({
112
118
  remote: Schema.string().default(DEFAULTS.REMOTE),
113
119
  branch: Schema.string().default(DEFAULTS.BRANCH),
114
120
  gitBin: Schema.string().default(DEFAULTS.GIT_BIN),
121
+ ageBin: Schema.string().default(DEFAULTS.AGE_BIN),
122
+ ageRecipient: Schema.string().default(DEFAULTS.AGE_RECIPIENT),
123
+ ageIdentity: Schema.string().default(DEFAULTS.AGE_IDENTITY),
115
124
  autoPullOnStart: Schema.boolean().default(DEFAULTS.AUTO_PULL_ON_START),
116
125
  autoPushOnTurnEnd: Schema.boolean().default(DEFAULTS.AUTO_PUSH_ON_TURN_END),
117
126
  pullIntervalMinutes: Schema.number().default(DEFAULTS.PULL_INTERVAL_MINUTES),
@@ -139,6 +148,9 @@ export function resolveConfig(config = {}) {
139
148
  remote: config.remote ?? DEFAULTS.REMOTE,
140
149
  branch: config.branch ?? DEFAULTS.BRANCH,
141
150
  gitBin: config.gitBin ?? DEFAULTS.GIT_BIN,
151
+ ageBin: config.ageBin ?? DEFAULTS.AGE_BIN,
152
+ ageRecipient: config.ageRecipient ?? DEFAULTS.AGE_RECIPIENT,
153
+ ageIdentity: config.ageIdentity ?? DEFAULTS.AGE_IDENTITY,
142
154
  autoPullOnStart: config.autoPullOnStart ?? DEFAULTS.AUTO_PULL_ON_START,
143
155
  autoPushOnTurnEnd: config.autoPushOnTurnEnd ?? DEFAULTS.AUTO_PUSH_ON_TURN_END,
144
156
  pullIntervalMinutes: config.pullIntervalMinutes ?? DEFAULTS.PULL_INTERVAL_MINUTES,
@@ -161,6 +173,15 @@ export function resolveConfig(config = {}) {
161
173
  if (typeof resolved.gitBin !== 'string' || resolved.gitBin.length === 0) {
162
174
  throw badConfig('gitBin must be a non-empty string')
163
175
  }
176
+ if (typeof resolved.ageBin !== 'string' || resolved.ageBin.length === 0) {
177
+ throw badConfig('ageBin must be a non-empty string')
178
+ }
179
+ if (typeof resolved.ageRecipient !== 'string') {
180
+ throw badConfig('ageRecipient must be a string')
181
+ }
182
+ if (typeof resolved.ageIdentity !== 'string') {
183
+ throw badConfig('ageIdentity must be a string')
184
+ }
164
185
  if (typeof resolved.branch !== 'string' || resolved.branch.length === 0 || !/^[A-Za-z0-9._/-]+$/u.test(resolved.branch)) {
165
186
  throw badConfig('branch must be a non-empty ref-safe string')
166
187
  }
@@ -254,6 +275,60 @@ export function makeRunGit(subprocess, opts) {
254
275
  }
255
276
  }
256
277
 
278
+ /**
279
+ * age runner:ctx.subprocess 上的 collect 封装(与 makeRunGit 同构)。
280
+ * args 为「含可执行路径的完整 argv」(lib/age.mjs 的 runner 契约),只做文本
281
+ * 输出收集与退出码/超时/取消语义;age 加解密经文件入参(-o out in),无需 stdin。
282
+ * @param {import('@deepseek-ai/dsh-subprocess').SubprocessRuntime} subprocess - 宿主子进程服务。
283
+ * @param {object} opts - {graceMs, commandTimeoutMs, maxOutputBytes}。
284
+ * @returns {(args: string[], runOpts?: object) => Promise<{code: number, stdout: string, stderr: string}>}
285
+ */
286
+ export function makeRunAge(subprocess, opts) {
287
+ return async (args, runOpts = {}) => {
288
+ const controller = new AbortController()
289
+ let timedOut = false
290
+ const timer = setTimeout(() => {
291
+ timedOut = true
292
+ controller.abort(new Error(`age ${args[0] ?? ''} timed out after ${opts.commandTimeoutMs}ms`))
293
+ }, opts.commandTimeoutMs)
294
+ const onAbort = () => {
295
+ controller.abort(runOpts.signal?.reason instanceof Error ? runOpts.signal.reason : new Error('sync operation aborted'))
296
+ }
297
+ if (runOpts.signal !== undefined) {
298
+ runOpts.signal.addEventListener('abort', onAbort, { once: true })
299
+ }
300
+ try {
301
+ const executable = await subprocess.resolveExecutable(args[0], undefined, controller.signal)
302
+ const handle = subprocess.spawn({
303
+ argv: [executable, ...args.slice(1)],
304
+ cwd: runOpts.cwd,
305
+ stdio: {
306
+ stdin: 'ignore',
307
+ stdout: { maxBytes: opts.maxOutputBytes },
308
+ stderr: { maxBytes: opts.maxOutputBytes },
309
+ },
310
+ graceMs: opts.graceMs,
311
+ signal: controller.signal,
312
+ })
313
+ const outcome = await handle.done
314
+ if (timedOut) {
315
+ throw new Error(`age ${args[0] ?? ''} timed out after ${opts.commandTimeoutMs}ms`)
316
+ }
317
+ if (runOpts.signal?.aborted === true) {
318
+ throw runOpts.signal.reason instanceof Error ? runOpts.signal.reason : new Error('sync operation aborted')
319
+ }
320
+ const stdout = handle.collected.stdout.readFrom(0).text
321
+ const stderr = handle.collected.stderr.readFrom(0).text
322
+ return { code: outcome.exitCode ?? (outcome.signal !== null ? 128 : 0), stdout, stderr }
323
+ } finally {
324
+ clearTimeout(timer)
325
+ if (runOpts.signal !== undefined) {
326
+ runOpts.signal.removeEventListener('abort', onAbort)
327
+ }
328
+ }
329
+ }
330
+ }
331
+
257
332
  /**
258
333
  * 工具参数/输出描述(双语)。
259
334
  */
@@ -266,13 +341,13 @@ const TOOL_TEXT = {
266
341
  }
267
342
 
268
343
  /** sync_status 工具规范结果(与工具 schema 同构)。 */
269
- /** @typedef {{ok: boolean, branch: string, remote: string, head?: string, remoteHead?: string, ahead: number, behind: number, dirty: string[], forks: string[], diffStat: string, mergeInProgress: boolean, lastCommits: string[], lastPullAt?: number, lastPushAt?: number, lastError?: string, error?: string}} StatusValue */
270
- /** @typedef {{ok: boolean, pulled?: boolean, merged?: boolean, adopted?: number, appended?: number, diverged?: number, forks?: string[], head?: string, error?: string}} PullValue */
271
- /** @typedef {{ok: boolean, pushed?: boolean, head?: string, mirrored?: number, deleted?: number, remote?: string, error?: string}} PushValue */
344
+ /** @typedef {{ok: boolean, branch: string, remote: string, head?: string, remoteHead?: string, ahead: number, behind: number, dirty: string[], forks: string[], diffStat: string, mergeInProgress: boolean, lastCommits: string[], lastPullAt?: number, lastPushAt?: number, lastError?: string, error?: string, warnings?: string[]}} StatusValue */
345
+ /** @typedef {{ok: boolean, pulled?: boolean, merged?: boolean, adopted?: number, appended?: number, diverged?: number, forks?: string[], head?: string, error?: string, warnings?: string[]}} PullValue */
346
+ /** @typedef {{ok: boolean, pushed?: boolean, head?: string, mirrored?: number, deleted?: number, remote?: string, error?: string, warnings?: string[]}} PushValue */
272
347
 
273
348
  /**
274
349
  * sync_status 工具定义(read-only:不确认、不触网)。
275
- * @param {SyncEngine} engine - 同步引擎。
350
+ * @param {{status: () => Promise<object>}} engine - 同步引擎(git 或 encrypted 后端同一 surface)。
276
351
  * @param {() => Promise<object>} readMeta - 元数据读取。
277
352
  * @returns {object} 工具定义。
278
353
  */
@@ -302,6 +377,7 @@ export function makeSyncStatusTool(engine, readMeta) {
302
377
  lastPushAt: { type: 'integer' },
303
378
  lastError: { type: 'string' },
304
379
  error: { type: 'string' },
380
+ warnings: { type: 'array', items: { type: 'string' } },
305
381
  },
306
382
  },
307
383
  render(_args, value) {
@@ -345,6 +421,7 @@ export function makeSyncPullTool(deps) {
345
421
  forks: { type: 'array', items: { type: 'string' } },
346
422
  head: { type: 'string' },
347
423
  error: { type: 'string' },
424
+ warnings: { type: 'array', items: { type: 'string' } },
348
425
  },
349
426
  },
350
427
  render(_args, value) {
@@ -403,6 +480,7 @@ export function makeSyncPushTool(deps) {
403
480
  deleted: { type: 'integer' },
404
481
  remote: { type: 'string' },
405
482
  error: { type: 'string' },
483
+ warnings: { type: 'array', items: { type: 'string' } },
406
484
  },
407
485
  },
408
486
  render(_args, value) {
@@ -530,7 +608,7 @@ export function apply(ctx, config = {}) {
530
608
  reportMeta({ lastError: message.slice(0, 500) })
531
609
  }
532
610
 
533
- // --- git 后端 + 引擎。
611
+ // --- git 后端 + 引擎(backend seam:git = 明文,encrypted = age 加密的 git)。
534
612
  const git = new GitBackend({
535
613
  repoDir,
536
614
  remote: resolved.remote,
@@ -546,7 +624,7 @@ export function apply(ctx, config = {}) {
546
624
  timeoutMs: resolved.commandTimeoutMs,
547
625
  })
548
626
 
549
- const engine = new SyncEngine({
627
+ const engineDeps = {
550
628
  git,
551
629
  sessionRoot,
552
630
  repoDir,
@@ -557,7 +635,21 @@ export function apply(ctx, config = {}) {
557
635
  reportError,
558
636
  logger,
559
637
  onForks: (forkPaths) => handleForks(forkPaths),
560
- })
638
+ }
639
+ const engine = resolved.backend === BACKENDS.ENCRYPTED
640
+ ? new EncryptedBackend({
641
+ ...engineDeps,
642
+ run: makeRunAge(ctx.subprocess, {
643
+ graceMs: resolved.graceMs,
644
+ commandTimeoutMs: resolved.commandTimeoutMs,
645
+ maxOutputBytes: resolved.maxOutputBytes,
646
+ }),
647
+ ageBin: resolved.ageBin,
648
+ ageRecipient: resolved.ageRecipient,
649
+ ageIdentity: resolved.ageIdentity,
650
+ timeoutMs: resolved.commandTimeoutMs,
651
+ })
652
+ : new SyncEngine(engineDeps)
561
653
  // 设备 id 来自元数据领域;在领域就绪后补齐(fork 命名/设备文件用)。
562
654
  void ensureMeta().then((meta) => {
563
655
  engine.deviceId = meta.deviceId
@@ -759,6 +851,14 @@ export {
759
851
  // 复用/测试面:引擎、后端、纯函数与词汇。
760
852
  GitBackend,
761
853
  SyncEngine,
854
+ EncryptedBackend,
855
+ selectEncryptionMode,
856
+ detectAge,
857
+ ageEncrypt,
858
+ ageDecrypt,
859
+ encryptTree,
860
+ decryptTree,
861
+ mergeTrees,
762
862
  collectStatus,
763
863
  renderStatus,
764
864
  renderDiff,
package/lib/age.mjs ADDED
@@ -0,0 +1,77 @@
1
+ // lib/age.mjs — age 二进制探测与加解密(零 DSH 依赖)。
2
+ //
3
+ // age 是「探测 → 使用 → 优雅降级」的可选外部二进制:encrypted 后端在 resolve
4
+ // 期探测其是否存在,缺 age/缺 recipient/identity 时降级为明文 git 并显式警告,
5
+ // 绝不硬依赖 age。操作期(encrypted 模式下)加解密失败一律 fail closed
6
+ // (AGE_FAILED),绝不静默回退成明文传输。
7
+ //
8
+ // runner 契约(与 git 一致,但 args 为「含可执行路径的完整 argv」):
9
+ // run(args, { cwd, timeoutMs, signal, binary, maxBytes }) → { code, stdout, stderr }
10
+ // args[0] 为 age 可执行路径,其余为 age 参数。
11
+
12
+ import { redactText } from './sanitize.mjs'
13
+ import { ageFailed } from './errors.mjs'
14
+
15
+ /**
16
+ * 探测 age:`age --version` 退出 0 → 返回配置的二进制路径;否则(含 runner
17
+ * 抛错)返回 null。纯探测,不抛错——调用方据此降级。
18
+ * @param {(args: string[], opts?: object) => Promise<{code: number, stdout: string|Buffer, stderr: string}>} run - 子进程 runner。
19
+ * @param {string} [ageBin] - age 可执行路径(默认 'age')。
20
+ * @param {{timeoutMs?: number, cwd?: string}} [opts] - 探测参数。
21
+ * @returns {Promise<string|null>} 二进制路径或 null。
22
+ */
23
+ export async function detectAge(run, ageBin = 'age', opts = {}) {
24
+ if (typeof ageBin !== 'string' || ageBin.length === 0) return null
25
+ try {
26
+ const result = await run([ageBin, '--version'], { timeoutMs: opts.timeoutMs, cwd: opts.cwd })
27
+ return result.code === 0 ? ageBin : null
28
+ } catch {
29
+ return null
30
+ }
31
+ }
32
+
33
+ /**
34
+ * 执行一条 age 命令并把失败包成 AGE_FAILED(stderr 尾部脱敏嵌入)。
35
+ * @param {(args: string[], opts?: object) => Promise<{code: number, stdout: string|Buffer, stderr: string}>} run - 子进程 runner。
36
+ * @param {string[]} args - 完整 argv(含可执行路径)。
37
+ * @param {{cwd?: string, timeoutMs?: number}} [opts] - 命令参数。
38
+ * @returns {Promise<{code: number, stdout: string|Buffer, stderr: string}>}
39
+ */
40
+ async function runAge(run, args, opts = {}) {
41
+ let result
42
+ try {
43
+ result = await run(args, { cwd: opts.cwd, timeoutMs: opts.timeoutMs })
44
+ } catch (error) {
45
+ throw ageFailed(args[0] ?? 'age', redactText(error instanceof Error ? error.message : String(error)))
46
+ }
47
+ if (result.code !== 0) {
48
+ const tail = redactText(String(result.stderr ?? '')).trim().split('\n').slice(-3).join(' | ') || `exit ${result.code}`
49
+ throw ageFailed(args[0] ?? 'age', tail)
50
+ }
51
+ return result
52
+ }
53
+
54
+ /**
55
+ * age 加密单个明文文件 → 密文文件:`age -r <recipient> -o <out> <in>`。
56
+ * 文件入参(非 stdin)避免写管道的宿主限制;身份文件无需、不触网。
57
+ * @param {(args: string[], opts?: object) => Promise<{code: number, stdout: string|Buffer, stderr: string}>} run - 子进程 runner。
58
+ * @param {object} deps - {ageBin, recipient, inPath, outPath, timeoutMs?, cwd?}。
59
+ * @returns {Promise<string>} 密文输出路径。
60
+ */
61
+ export async function ageEncrypt(run, deps) {
62
+ await runAge(run, [deps.ageBin, '-r', deps.recipient, '-o', deps.outPath, deps.inPath], deps)
63
+ return deps.outPath
64
+ }
65
+
66
+ /**
67
+ * age 解密密文文件 → 明文文件:`age -d -i <identity> -o <out> <in>`。
68
+ * 身份文件必须是「无口令」的 age 私钥(有口令会走 TTY 提示;stdin 已 ignore,
69
+ * 将立即失败——这是 fail-closed 的预期行为,用户需用无口令身份文件)。
70
+ * @param {(args: string[], opts?: object) => Promise<{code: number, stdout: string|Buffer, stderr: string}>} run - 子进程 runner。
71
+ * @param {object} deps - {ageBin, identity, inPath, outPath, timeoutMs?, cwd?}。
72
+ * @returns {Promise<string>} 明文输出路径。
73
+ */
74
+ export async function ageDecrypt(run, deps) {
75
+ await runAge(run, [deps.ageBin, '-d', '-i', deps.identity, '-o', deps.outPath, deps.inPath], deps)
76
+ return deps.outPath
77
+ }
@@ -0,0 +1,57 @@
1
+ // lib/backend.mjs — 传输后端 seam(零依赖)。
2
+ //
3
+ // Backend 契约(三类传输后端共享同一 surface;本次落地 git 与 encrypted,
4
+ // 对象存储 object-storage 为接口占位,配置即 resolveConfig 响亮失败):
5
+ //
6
+ // kind : 'git' | 'encrypted' | 'object-storage' —— 语义后端
7
+ // mode : 'plaintext' | 'encrypted' —— 实际生效的传输模式
8
+ // warnings : string[] —— 降级/边界警告(进入
9
+ // status/push/pull 结果)
10
+ // status() -> StatusValue
11
+ // push(opts) -> PushValue
12
+ // pull(opts) -> PullValue
13
+ //
14
+ // git(GitBackend + SyncEngine)为明文内置实现;encrypted(lib/encrypted.mjs)
15
+ // 为 age 包装的 git 传输(镜像内容加密后再推、解密后再合并);object-storage
16
+ // 无实现——只有契约与常量占位。
17
+
18
+ import { BACKENDS } from './constants.mjs'
19
+
20
+ /** 传输模式词汇。 */
21
+ export const BACKEND_MODES = Object.freeze({
22
+ PLAINTEXT: 'plaintext',
23
+ ENCRYPTED: 'encrypted',
24
+ })
25
+
26
+ /**
27
+ * 选择 encrypted 后端实际生效的传输模式(纯函数;探测结果经参数注入,便于测试)。
28
+ *
29
+ * 降级规则(任一不满足即回退明文 git 并给出显式警告,绝不静默降级):
30
+ * - backend !== 'encrypted' → 明文(无警告);
31
+ * - age 二进制不可用 → 明文 + 警告;
32
+ * - ageRecipient 为空 → 明文 + 警告(无法加密);
33
+ * - ageIdentity 为空 → 明文 + 警告(无法解密)。
34
+ *
35
+ * @param {object} deps - {backend, ageAvailable, ageRecipient, ageIdentity}。
36
+ * @param {string} deps.backend - BACKENDS 之一。
37
+ * @param {boolean} deps.ageAvailable - detectAge 是否探测到 age 二进制。
38
+ * @param {string} deps.ageRecipient - age 收件人(公钥/身份串)。
39
+ * @param {string} deps.ageIdentity - age 身份文件路径(解密私钥)。
40
+ * @returns {{mode: 'plaintext'|'encrypted', warnings: string[]}}
41
+ */
42
+ export function selectEncryptionMode({ backend, ageAvailable, ageRecipient, ageIdentity }) {
43
+ if (backend !== BACKENDS.ENCRYPTED) return { mode: BACKEND_MODES.PLAINTEXT, warnings: [] }
44
+ const warnings = []
45
+ if (ageAvailable !== true) {
46
+ warnings.push('age binary not found (probed `age --version`); mirror content will be pushed unencrypted')
47
+ } else {
48
+ if (typeof ageRecipient !== 'string' || ageRecipient.trim() === '') {
49
+ warnings.push('ageRecipient is empty; mirror content will be pushed unencrypted')
50
+ }
51
+ if (typeof ageIdentity !== 'string' || ageIdentity.trim() === '') {
52
+ warnings.push('ageIdentity is empty; mirror content will be pushed unencrypted')
53
+ }
54
+ }
55
+ const mode = warnings.length === 0 ? BACKEND_MODES.ENCRYPTED : BACKEND_MODES.PLAINTEXT
56
+ return { mode, warnings }
57
+ }
package/lib/constants.mjs CHANGED
@@ -20,11 +20,24 @@ export const DEVICE_FILE = 'device.txt'
20
20
  // 存储领域 state 表的单例键。
21
21
  export const STATE_KEY = 'singleton'
22
22
 
23
- // 后端词汇:git 是唯一实现;其余为端到端加密后端预留(加载期响亮失败)。
23
+ // 后端词汇:git 为明文传输,encrypted 为 age 加密的 git 传输(镜像内容
24
+ // 加密后再推,见 lib/backend.mjs 的 seam 契约与 lib/encrypted.mjs)。
24
25
  export const BACKENDS = Object.freeze({
25
26
  GIT: 'git',
27
+ ENCRYPTED: 'encrypted',
26
28
  })
27
29
 
30
+ // 预留后端(接口占位,尚未实现):配置即加载期响亮失败(backendUnsupported)。
31
+ // 与 git/encrypted 共享同一 seam(status/push/pull 三方法),只是传输介质不同。
32
+ export const RESERVED_BACKENDS = Object.freeze({
33
+ OBJECT_STORAGE: 'object-storage',
34
+ })
35
+
36
+ // encrypted 后端在 git 工作树内放置密文镜像的目录名与单个密文文件后缀
37
+ // (每会话文件一个 .age 密文;明文镜像 sessions/ 只存在于本地、绝不提交)。
38
+ export const ENC_DIR = 'encrypted'
39
+ export const ENC_EXT = '.age'
40
+
28
41
  // Config.confirmVia 的取值。
29
42
  export const CONFIRM_CHANNELS = Object.freeze({
30
43
  AUTO: 'auto',
@@ -58,6 +71,7 @@ export const ERROR_CODES = Object.freeze({
58
71
  PUSH_REJECTED: 'PUSH_REJECTED',
59
72
  SYNC_DENIED: 'SYNC_DENIED',
60
73
  PATH_UNSAFE: 'PATH_UNSAFE',
74
+ AGE_FAILED: 'AGE_FAILED',
61
75
  })
62
76
 
63
77
  // fork 文件名模式:<basename>.remote-fork-<UTC 时间戳>-<设备短 id>;镜像与
@@ -73,6 +87,9 @@ export const DEFAULTS = Object.freeze({
73
87
  REMOTE: '',
74
88
  BRANCH: 'main',
75
89
  GIT_BIN: 'git',
90
+ AGE_BIN: 'age',
91
+ AGE_RECIPIENT: '',
92
+ AGE_IDENTITY: '',
76
93
  AUTO_PULL_ON_START: false,
77
94
  AUTO_PUSH_ON_TURN_END: false,
78
95
  PULL_INTERVAL_MINUTES: 0,