@pyrokine/mcp-ssh 2.0.1 → 2.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/dist/file-ops.js CHANGED
@@ -2,6 +2,7 @@
2
2
  * SSH File Operations - 文件操作
3
3
  */
4
4
  import { execSync, spawnSync } from 'child_process';
5
+ import { createHash } from 'crypto';
5
6
  import * as fs from 'fs';
6
7
  import * as os from 'os';
7
8
  import * as path from 'path';
@@ -57,27 +58,17 @@ async function runWithConcurrency(items, limit, worker) {
57
58
  * 格式:path.delimiter 分隔的绝对路径列表(POSIX `:`,Windows `;`),如 `/tmp:/home/user/work`
58
59
  * 安全性:路径会通过 fs.realpathSync 解析 symlink,防止 symlink 逃出白名单
59
60
  */
60
- function validateLocalPathAgainstAllowList(localPath) {
61
+ function quoteRsyncSshArg(value) {
62
+ return escapeShellArg(String(value));
63
+ }
64
+ function getAllowListStatus(localPath) {
61
65
  const allowEnv = process.env.SSH_MCP_FILE_OPS_ALLOW_DIRS;
62
- if (!allowEnv) {
63
- return;
64
- }
65
- const allowDirs = allowEnv
66
- .split(path.delimiter)
67
- .map((p) => p.trim())
68
- .filter((p) => p.length > 0);
66
+ const allowDirs = allowEnv?.split(path.delimiter).filter((item) => item.trim().length > 0) ?? [];
69
67
  if (allowDirs.length === 0) {
70
- return;
71
- }
72
- let resolvedLocal;
73
- try {
74
- // 路径不存在时,向上找到第一个存在的祖先 realpathSync 后再拼接剩余
75
- resolvedLocal = resolvePathOrAncestor(localPath);
68
+ return { configured: false };
76
69
  }
77
- catch (e) {
78
- throw new Error(`无法解析路径 ${localPath}: ${e instanceof Error ? e.message : String(e)}`);
79
- }
80
- const inAllowList = allowDirs.some((dir) => {
70
+ const resolvedLocal = resolvePathOrAncestor(localPath);
71
+ const matched = allowDirs.some((dir) => {
81
72
  try {
82
73
  const resolvedDir = fs.realpathSync(dir);
83
74
  const rel = path.relative(resolvedDir, resolvedLocal);
@@ -87,8 +78,12 @@ function validateLocalPathAgainstAllowList(localPath) {
87
78
  return false;
88
79
  }
89
80
  });
90
- if (!inAllowList) {
91
- throw new Error(`localPath "${localPath}" 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 白名单内(白名单: ${allowDirs.join(', ')})`);
81
+ return { configured: true, matched };
82
+ }
83
+ function validateLocalPathAgainstAllowList(localPath) {
84
+ const allowList = getAllowListStatus(localPath);
85
+ if (allowList.configured && !allowList.matched) {
86
+ throw new Error('localPath 不在 SSH_MCP_FILE_OPS_ALLOW_DIRS 允许目录内');
92
87
  }
93
88
  }
94
89
  function resolvePathOrAncestor(p) {
@@ -111,6 +106,28 @@ function resolvePathOrAncestor(p) {
111
106
  return absolute;
112
107
  }
113
108
  }
109
+ export function probeLocalPath(localPath) {
110
+ const expanded = expandTilde(localPath);
111
+ const resolvedPath = resolvePathOrAncestor(expanded);
112
+ const allowList = getAllowListStatus(expanded);
113
+ if (!fs.existsSync(expanded)) {
114
+ return { exists: false, inputPath: localPath, expandedPath: expanded, resolvedPath, allowList };
115
+ }
116
+ const stats = fs.lstatSync(expanded);
117
+ return {
118
+ exists: true,
119
+ inputPath: localPath,
120
+ expandedPath: expanded,
121
+ resolvedPath,
122
+ size: stats.size,
123
+ mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
124
+ mtimeMs: Math.round(stats.mtimeMs),
125
+ isSymlink: stats.isSymbolicLink(),
126
+ isDirectory: stats.isDirectory(),
127
+ isFile: stats.isFile(),
128
+ allowList,
129
+ };
130
+ }
114
131
  /**
115
132
  * sftp.stat 的 Promise 包装
116
133
  */
@@ -126,6 +143,24 @@ function sftpStat(sftp, remotePath) {
126
143
  });
127
144
  });
128
145
  }
146
+ async function sftpExists(sftp, remotePath) {
147
+ try {
148
+ await sftpStat(sftp, remotePath);
149
+ return true;
150
+ }
151
+ catch {
152
+ return false;
153
+ }
154
+ }
155
+ async function remoteExists(alias, remotePath) {
156
+ const sftp = await sessionManager.getSftp(alias);
157
+ try {
158
+ return await sftpExists(sftp, remotePath);
159
+ }
160
+ finally {
161
+ sftp.end();
162
+ }
163
+ }
129
164
  /**
130
165
  * 带进度追踪的流传输
131
166
  */
@@ -195,13 +230,19 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
195
230
  localPath = expandTilde(localPath);
196
231
  validateLocalPathAgainstAllowList(localPath);
197
232
  if (!fs.existsSync(localPath)) {
198
- throw new Error(`Local file not found: ${localPath}`);
233
+ throw new Error('Local file not found');
199
234
  }
200
235
  // 用 lstat 拒绝顶层 symlink,与 ssh_sync 顶层 followSymlinks=false 行为一致;
201
236
  // 单文件接口不引入 followSymlinks 选项,需走 symlink 请用 ssh_sync
202
237
  const lstats = fs.lstatSync(localPath);
203
238
  if (lstats.isSymbolicLink()) {
204
- throw new Error(`Refusing to upload symlink at top level: ${localPath} (use ssh_sync with followSymlinks=true to traverse)`);
239
+ throw new Error('Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)');
240
+ }
241
+ if (lstats.isDirectory()) {
242
+ throw new Error('UPLOAD_PATH_IS_DIRECTORY: localPath is a directory, use ssh_sync for directory upload');
243
+ }
244
+ if (!lstats.isFile()) {
245
+ throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
205
246
  }
206
247
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
207
248
  const totalSize = lstats.size;
@@ -222,36 +263,138 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
222
263
  }
223
264
  return pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(localPath), sftp, totalSize, onProgress, !sharedSftp);
224
265
  }
266
+ export const DEFAULT_READ_FILE_MAX_BYTES = 1024 * 1024;
267
+ export const HARD_READ_FILE_MAX_BYTES = 16 * 1024 * 1024;
268
+ function normalizeReadFileOptions(options) {
269
+ if (typeof options === 'number') {
270
+ return { maxBytes: options };
271
+ }
272
+ return { ...options, maxBytes: options?.maxBytes ?? DEFAULT_READ_FILE_MAX_BYTES };
273
+ }
274
+ function parseLineRange(lineRange) {
275
+ const match = /^(?<start>\d+)(?:-(?<end>\d+))?$/.exec(lineRange.trim());
276
+ if (!match?.groups) {
277
+ throw new Error('lineRange 必须使用 "start-end" 或 "start" 格式,例如 "120-180"');
278
+ }
279
+ const start = Number(match.groups.start);
280
+ const end = match.groups.end ? Number(match.groups.end) : start;
281
+ if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start) {
282
+ throw new Error('lineRange 必须是从 1 开始且 end >= start 的行号范围');
283
+ }
284
+ return { start, end };
285
+ }
286
+ function validateReadFileOptions(options) {
287
+ if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) {
288
+ throw new Error('maxBytes 必须是正整数');
289
+ }
290
+ if (options.maxBytes > HARD_READ_FILE_MAX_BYTES) {
291
+ throw new Error(`maxBytes 不能超过 ${HARD_READ_FILE_MAX_BYTES},请使用 offset、tail 或 lineRange 分块读取`);
292
+ }
293
+ if (options.offset !== undefined && (!Number.isSafeInteger(options.offset) || options.offset < 0)) {
294
+ throw new Error('offset 必须是非负整数');
295
+ }
296
+ const selectors = [options.offset !== undefined, options.tail === true, options.lineRange !== undefined].filter(Boolean);
297
+ if (selectors.length > 1) {
298
+ throw new Error('offset、tail、lineRange 只能同时指定一个');
299
+ }
300
+ }
301
+ function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
302
+ return {
303
+ content: '',
304
+ size: totalSize,
305
+ total_size: totalSize,
306
+ read_offset: readOffset,
307
+ read_bytes: 0,
308
+ remaining_bytes: Math.max(0, totalSize - readOffset),
309
+ sample_kind: sampleKind,
310
+ truncated: readOffset < totalSize,
311
+ };
312
+ }
313
+ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange) {
314
+ const { start, end } = parseLineRange(lineRange);
315
+ const command = [
316
+ `awk 'NR>=${start} && NR<=${end} { print } NR>${end} { exit }'`,
317
+ escapeShellArg(remotePath),
318
+ '|',
319
+ 'head',
320
+ '-c',
321
+ String(maxBytes),
322
+ ].join(' ');
323
+ const result = await sessionManager.exec(alias, command, {
324
+ timeout: 30000,
325
+ useLoginUser: true,
326
+ maxOutputSize: maxBytes + 4096,
327
+ });
328
+ if (!result.success && result.stderr.trim().length > 0) {
329
+ throw new Error(result.stderr.trim());
330
+ }
331
+ const readBytes = Buffer.byteLength(result.stdout, 'utf-8');
332
+ return {
333
+ content: result.stdout,
334
+ size: totalSize,
335
+ total_size: totalSize,
336
+ read_offset: 0,
337
+ read_bytes: readBytes,
338
+ remaining_bytes: Math.max(0, totalSize - readBytes),
339
+ sample_kind: 'line_range',
340
+ truncated: readBytes >= maxBytes,
341
+ line_start: start,
342
+ line_end: end,
343
+ };
344
+ }
225
345
  /**
226
346
  * 读取远程文件内容
227
347
  */
228
- export async function readFile(alias, remotePath, maxBytes = 1024 * 1024 // 默认最大 1MB
229
- ) {
348
+ export async function readFile(alias, remotePath, options) {
349
+ const readOptions = normalizeReadFileOptions(options);
350
+ validateReadFileOptions(readOptions);
230
351
  const sftp = await sessionManager.getSftp(alias);
231
352
  const actualSize = (await sftpStat(sftp, remotePath)).size;
232
- const truncated = actualSize > maxBytes;
233
- // 处理空文件
353
+ if (readOptions.lineRange) {
354
+ sftp.end();
355
+ return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange);
356
+ }
234
357
  if (actualSize === 0) {
235
358
  sftp.end();
236
- return { content: '', size: 0, truncated: false };
359
+ return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full');
360
+ }
361
+ const readOffset = readOptions.tail
362
+ ? Math.max(0, actualSize - readOptions.maxBytes)
363
+ : Math.min(readOptions.offset ?? 0, actualSize);
364
+ const readSize = Math.min(actualSize - readOffset, readOptions.maxBytes);
365
+ const sampleKind = readOptions.tail
366
+ ? 'tail'
367
+ : readOptions.offset !== undefined
368
+ ? 'range'
369
+ : actualSize <= readOptions.maxBytes
370
+ ? 'full'
371
+ : 'head';
372
+ if (readSize === 0) {
373
+ sftp.end();
374
+ return emptyReadResult(actualSize, sampleKind, readOffset);
237
375
  }
238
- const readSize = Math.min(actualSize, maxBytes);
239
376
  return new Promise((resolve, reject) => {
240
377
  const chunks = [];
241
378
  const readStream = sftp.createReadStream(remotePath, {
242
- start: 0,
243
- end: readSize - 1,
379
+ start: readOffset,
380
+ end: readOffset + readSize - 1,
244
381
  });
245
382
  readStream.on('data', (chunk) => {
246
383
  chunks.push(chunk);
247
384
  });
248
385
  readStream.on('end', () => {
249
386
  sftp.end();
250
- const content = Buffer.concat(chunks).toString('utf-8');
387
+ const buffer = Buffer.concat(chunks);
388
+ const remainingBytes = Math.max(0, actualSize - readOffset - buffer.length);
251
389
  resolve({
252
- content,
390
+ content: buffer.toString('utf-8'),
253
391
  size: actualSize,
254
- truncated,
392
+ total_size: actualSize,
393
+ read_offset: readOffset,
394
+ read_bytes: buffer.length,
395
+ remaining_bytes: remainingBytes,
396
+ sample_kind: sampleKind,
397
+ truncated: readOffset > 0 || remainingBytes > 0,
255
398
  });
256
399
  });
257
400
  readStream.on('error', (err) => {
@@ -403,13 +546,20 @@ export async function checkRsync(alias) {
403
546
  * @param options 同步选项
404
547
  */
405
548
  export async function syncFiles(alias, localPath, remotePath, direction, options = {}) {
549
+ const startedAt = Date.now();
406
550
  localPath = expandTilde(localPath);
407
551
  validateLocalPathAgainstAllowList(localPath);
408
552
  const hasRsync = await checkRsync(alias);
409
- if (hasRsync) {
410
- return syncWithRsync(alias, localPath, remotePath, direction, options);
411
- }
412
- return syncWithSftp(alias, localPath, remotePath, direction, options);
553
+ const result = hasRsync
554
+ ? await syncWithRsync(alias, localPath, remotePath, direction, options)
555
+ : await syncWithSftp(alias, localPath, remotePath, direction, options);
556
+ return {
557
+ ...result,
558
+ transport: result.method,
559
+ direction,
560
+ dryRun: options.dryRun === true,
561
+ duration: Date.now() - startedAt,
562
+ };
413
563
  }
414
564
  /**
415
565
  * 使用 rsync 同步文件
@@ -436,8 +586,12 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
436
586
  if (!sessionInfo) {
437
587
  throw new Error(`Session '${alias}' not found`);
438
588
  }
589
+ // 密码认证无法透传给 rsync 的 ssh 子进程,直接走 SFTP
590
+ if (sessionInfo.authMethod === 'password') {
591
+ return syncWithSftp(alias, localPath, remotePath, direction, options);
592
+ }
439
593
  // 构建 rsync 参数
440
- const args = ['-avz', '--progress'];
594
+ const args = ['-avz', '--itemize-changes', '--stats'];
441
595
  if (options.delete) {
442
596
  args.push('--delete');
443
597
  }
@@ -459,7 +613,7 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
459
613
  }
460
614
  // path 安全校验:以 `-` 起始的路径会被 rsync 当成选项解析(即便有 `--` 兜底,也避免 OS/rsync 实现差异)
461
615
  if (localPath.startsWith('-') || remotePath.startsWith('-')) {
462
- throw new Error(`Invalid path: must not start with '-' (localPath=${localPath}, remotePath=${remotePath})`);
616
+ throw new Error('Invalid path: localPath and remotePath must not start with -');
463
617
  }
464
618
  // username/host 安全校验:拒绝 shell 元字符与 ssh 选项注入
465
619
  const sshIdentifierAllowed = /^[a-zA-Z0-9.:_-]+$/;
@@ -471,7 +625,21 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
471
625
  }
472
626
  // 构建 rsync argv(不用 shell=true,避免 username/host 含 shell 元字符时注入)
473
627
  // ProxyCommand=none 显式禁用 ssh-config 中可能定义的 ProxyCommand,防止外部命令注入
474
- const sshCmd = `ssh -p ${sessionInfo.port} -o StrictHostKeyChecking=accept-new -o BatchMode=yes -o ProxyCommand=none`;
628
+ const sshParts = [
629
+ 'ssh',
630
+ '-p',
631
+ String(sessionInfo.port),
632
+ '-o',
633
+ 'StrictHostKeyChecking=accept-new',
634
+ '-o',
635
+ 'BatchMode=yes',
636
+ '-o',
637
+ 'ProxyCommand=none',
638
+ ];
639
+ if (sessionInfo.keyPath) {
640
+ sshParts.push('-i', sessionInfo.keyPath);
641
+ }
642
+ const sshCmd = sshParts.map(quoteRsyncSshArg).join(' ');
475
643
  // remoteSpec 作为单独 argv 元素,不经 shell 解析
476
644
  const remoteSpec = `${sessionInfo.username}@${sessionInfo.host}:${remotePath}`;
477
645
  // 在 path 参数前插 `--`,明确剩余为路径而非选项(双重保险)
@@ -496,21 +664,22 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
496
664
  };
497
665
  }
498
666
  const output = result.stdout ?? '';
499
- // 解析 rsync 输出统计文件数
500
- const lines = output.split('\n');
501
- let filesTransferred = 0;
502
- for (const line of lines) {
503
- if (line.trim() &&
504
- !line.startsWith('sending') &&
505
- !line.startsWith('receiving') &&
506
- !line.startsWith('total')) {
507
- filesTransferred++;
508
- }
509
- }
667
+ const stats = parseRsyncStats(output);
668
+ const filesTransferred = stats.added + stats.updated;
510
669
  return {
511
670
  success: true,
512
671
  method: 'rsync',
513
672
  filesTransferred,
673
+ stats,
674
+ commandSummary: {
675
+ tool: 'rsync',
676
+ dryRun: options.dryRun === true,
677
+ delete: options.delete === true,
678
+ recursive: options.recursive !== false,
679
+ followSymlinks: options.followSymlinks === true,
680
+ excludeCount: options.exclude?.length ?? 0,
681
+ usedKeyPath: Boolean(sessionInfo.keyPath),
682
+ },
514
683
  output,
515
684
  };
516
685
  }
@@ -525,7 +694,51 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options) {
525
694
  };
526
695
  }
527
696
  }
528
- function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0) {
697
+ class DirectoryTransferAccumulator {
698
+ result = {
699
+ fileCount: 0,
700
+ totalSize: 0,
701
+ skippedSymlinks: 0,
702
+ added: 0,
703
+ updated: 0,
704
+ failed: 0,
705
+ };
706
+ addFile(size, existed) {
707
+ this.result.fileCount++;
708
+ this.result.totalSize += size;
709
+ if (existed) {
710
+ this.result.updated++;
711
+ }
712
+ else {
713
+ this.result.added++;
714
+ }
715
+ }
716
+ addSkippedSymlink() {
717
+ this.result.skippedSymlinks++;
718
+ }
719
+ addFailed() {
720
+ this.result.failed++;
721
+ }
722
+ merge(result) {
723
+ this.result.fileCount += result.fileCount;
724
+ this.result.totalSize += result.totalSize;
725
+ this.result.skippedSymlinks += result.skippedSymlinks;
726
+ this.result.added += result.added;
727
+ this.result.updated += result.updated;
728
+ this.result.failed += result.failed;
729
+ }
730
+ toResult() {
731
+ return { ...this.result };
732
+ }
733
+ }
734
+ function buildDirectorySyncResult(result, warnings) {
735
+ return buildSyncResult(result.fileCount, result.totalSize, warnings, result.skippedSymlinks, {
736
+ added: result.added,
737
+ updated: result.updated,
738
+ failed: result.failed,
739
+ });
740
+ }
741
+ function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0, stats) {
529
742
  if (skippedSymlinks > 0) {
530
743
  warnings.push(`skipped ${skippedSymlinks} symlink(s) (set followSymlinks=true to traverse)`);
531
744
  }
@@ -535,18 +748,106 @@ function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0) {
535
748
  filesTransferred: fileCount,
536
749
  bytesTransferred: totalSize,
537
750
  skippedSymlinks: skippedSymlinks > 0 ? skippedSymlinks : undefined,
751
+ stats: {
752
+ added: stats?.added ?? 0,
753
+ updated: stats?.updated ?? fileCount,
754
+ deleted: stats?.deleted ?? 0,
755
+ skipped: stats?.skipped ?? skippedSymlinks,
756
+ failed: stats?.failed ?? 0,
757
+ },
538
758
  output: warnings.length ? `Warning: ${warnings.join('; ')}` : undefined,
539
759
  };
540
760
  }
761
+ function parseRsyncStats(output) {
762
+ const stats = { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 0 };
763
+ for (const line of output.split('\n')) {
764
+ if (line.startsWith('*deleting')) {
765
+ stats.deleted++;
766
+ }
767
+ else if (/^>f\+{9}\s/.test(line)) {
768
+ stats.added++;
769
+ }
770
+ else if (/^>f/.test(line)) {
771
+ stats.updated++;
772
+ }
773
+ }
774
+ const transferredMatch = output.match(/Number of regular files transferred:\s*(?<count>\d+)/);
775
+ if (transferredMatch?.groups && stats.added + stats.updated === 0) {
776
+ stats.updated = Number(transferredMatch.groups.count);
777
+ }
778
+ return stats;
779
+ }
780
+ function hashLocalFile(filePath) {
781
+ return new Promise((resolve, reject) => {
782
+ const hash = createHash('sha256');
783
+ const stream = fs.createReadStream(filePath);
784
+ stream.on('data', (chunk) => hash.update(chunk));
785
+ stream.on('error', reject);
786
+ stream.on('end', () => resolve(hash.digest('hex')));
787
+ });
788
+ }
789
+ async function hashRemoteFile(alias, remotePath) {
790
+ const result = await sessionManager.exec(alias, `sha256sum ${escapeShellArg(remotePath)} | awk '{print $1}'`, {
791
+ timeout: 30000,
792
+ useLoginUser: true,
793
+ maxOutputSize: 4096,
794
+ });
795
+ if (!result.success) {
796
+ return undefined;
797
+ }
798
+ const digest = result.stdout.trim().split(/\s+/)[0];
799
+ return /^[a-fA-F0-9]{64}$/.test(digest) ? digest : undefined;
800
+ }
801
+ async function buildSingleFileVerification(alias, localPath, remotePath, direction) {
802
+ const localStats = fs.statSync(localPath);
803
+ const remoteInfo = await getFileInfo(alias, remotePath);
804
+ const [localSha256, remoteSha256] = await Promise.all([hashLocalFile(localPath), hashRemoteFile(alias, remotePath)]);
805
+ return {
806
+ kind: 'single_file',
807
+ direction,
808
+ hashAlgorithm: 'sha256',
809
+ hashMatch: remoteSha256 ? localSha256 === remoteSha256 : undefined,
810
+ local: {
811
+ size: localStats.size,
812
+ mode: (localStats.mode & 0o777).toString(8),
813
+ mtimeMs: Math.round(localStats.mtimeMs),
814
+ sha256: localSha256,
815
+ },
816
+ remote: {
817
+ size: remoteInfo.size,
818
+ permissions: remoteInfo.permissions,
819
+ owner: remoteInfo.owner,
820
+ group: remoteInfo.group,
821
+ mtime: remoteInfo.mtime,
822
+ sha256: remoteSha256,
823
+ },
824
+ };
825
+ }
541
826
  async function syncWithSftp(alias, localPath, remotePath, direction, options) {
542
827
  const warnings = [];
543
828
  if (options.delete) {
544
829
  warnings.push('delete option is not supported in SFTP mode (requires rsync)');
545
830
  }
546
831
  if (options.dryRun) {
832
+ const localExists = fs.existsSync(localPath);
833
+ const localStats = localExists ? fs.lstatSync(localPath) : undefined;
834
+ const remoteTargetExists = await remoteExists(alias, remotePath).catch(() => false);
547
835
  return {
548
836
  success: true,
549
837
  method: 'sftp',
838
+ commandSummary: {
839
+ dryRun: true,
840
+ direction,
841
+ recursive: options.recursive !== false,
842
+ followSymlinks: options.followSymlinks === true,
843
+ deleteRequested: options.delete === true,
844
+ excludeCount: options.exclude?.length ?? 0,
845
+ localExists,
846
+ localIsDirectory: localStats?.isDirectory(),
847
+ localIsSymlink: localStats?.isSymbolicLink(),
848
+ remoteTargetExists,
849
+ wouldOverwrite: direction === 'upload' ? remoteTargetExists : localExists,
850
+ },
550
851
  output: 'Dry run mode: would transfer files via SFTP' +
551
852
  (warnings.length ? `. Warning: ${warnings.join('; ')}` : ''),
552
853
  };
@@ -555,28 +856,42 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
555
856
  if (direction === 'upload') {
556
857
  const stats = options.followSymlinks ? fs.statSync(localPath) : fs.lstatSync(localPath);
557
858
  if (stats.isSymbolicLink()) {
558
- throw new Error(`Refusing to upload symlink at top level: ${localPath} (set followSymlinks=true to traverse)`);
859
+ return {
860
+ success: false,
861
+ method: 'sftp',
862
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
863
+ output: 'Refusing to upload symlink at top level (set followSymlinks=true to traverse)',
864
+ };
559
865
  }
560
866
  if (stats.isDirectory() && options.recursive !== false) {
561
- const { fileCount, totalSize, skippedSymlinks } = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false);
562
- return buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks);
867
+ const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false);
868
+ return buildDirectorySyncResult(result, warnings);
563
869
  }
870
+ const existed = await remoteExists(alias, remotePath);
564
871
  const { size } = await uploadFile(alias, localPath, remotePath);
565
- return buildSyncResult(1, size, warnings);
872
+ return {
873
+ ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
874
+ verification: await buildSingleFileVerification(alias, localPath, remotePath, 'upload'),
875
+ };
566
876
  }
567
877
  // download
568
878
  const info = await getFileInfo(alias, remotePath);
569
879
  if (info.isDirectory && options.recursive !== false) {
570
- const { fileCount, totalSize, skippedSymlinks } = await downloadDirectory(alias, remotePath, localPath, options.exclude);
571
- return buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks);
880
+ const result = await downloadDirectory(alias, remotePath, localPath, options.exclude);
881
+ return buildDirectorySyncResult(result, warnings);
572
882
  }
883
+ const existed = fs.existsSync(localPath);
573
884
  const { size } = await downloadFile(alias, remotePath, localPath);
574
- return buildSyncResult(1, size, warnings);
885
+ return {
886
+ ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
887
+ verification: await buildSingleFileVerification(alias, localPath, remotePath, 'download'),
888
+ };
575
889
  }
576
890
  catch (err) {
577
891
  return {
578
892
  success: false,
579
893
  method: 'sftp',
894
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
580
895
  output: err instanceof Error ? err.message : String(err),
581
896
  };
582
897
  }
@@ -585,9 +900,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
585
900
  * 递归上传目录
586
901
  */
587
902
  async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false) {
588
- let fileCount = 0;
589
- let totalSize = 0;
590
- let skippedSymlinks = 0;
903
+ const accumulator = new DirectoryTransferAccumulator();
591
904
  // 顶层调用时开启一个 SFTP 会话,递归调用复用
592
905
  const ownSftp = !sharedSftp;
593
906
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
@@ -606,7 +919,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
606
919
  const stats = followSymlinks ? fs.statSync(itemLocalPath) : fs.lstatSync(itemLocalPath);
607
920
  if (!followSymlinks && stats.isSymbolicLink()) {
608
921
  console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
609
- skippedSymlinks++;
922
+ accumulator.addSkippedSymlink();
610
923
  continue;
611
924
  }
612
925
  if (stats.isDirectory()) {
@@ -620,18 +933,22 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
620
933
  await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
621
934
  const itemLocalPath = path.join(localPath, name);
622
935
  const itemRemotePath = path.posix.join(remotePath, name);
623
- await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp);
624
- fileCount++;
625
- totalSize += stats.size;
936
+ const existed = await sftpExists(sftp, itemRemotePath);
937
+ try {
938
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp);
939
+ accumulator.addFile(stats.size, existed);
940
+ }
941
+ catch (error) {
942
+ accumulator.addFailed();
943
+ throw error;
944
+ }
626
945
  });
627
946
  // 子目录串行递归
628
947
  for (const item of subDirItems) {
629
948
  const itemLocalPath = path.join(localPath, item);
630
949
  const itemRemotePath = path.posix.join(remotePath, item);
631
950
  const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks);
632
- fileCount += result.fileCount;
633
- totalSize += result.totalSize;
634
- skippedSymlinks += result.skippedSymlinks;
951
+ accumulator.merge(result);
635
952
  }
636
953
  }
637
954
  finally {
@@ -639,15 +956,13 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
639
956
  sftp.end();
640
957
  }
641
958
  }
642
- return { fileCount, totalSize, skippedSymlinks };
959
+ return accumulator.toResult();
643
960
  }
644
961
  /**
645
962
  * 递归下载目录
646
963
  */
647
964
  async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp) {
648
- let fileCount = 0;
649
- let totalSize = 0;
650
- let skippedSymlinks = 0;
965
+ const accumulator = new DirectoryTransferAccumulator();
651
966
  // 顶层调用时开启一个 SFTP 会话,递归调用复用
652
967
  const ownSftp = !sharedSftp;
653
968
  const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
@@ -680,20 +995,24 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
680
995
  }
681
996
  await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async (item) => {
682
997
  const itemLocalPath = path.join(localPath, item.name);
683
- await downloadFile(alias, item.path, itemLocalPath, undefined, sftp);
684
- fileCount++;
685
- totalSize += item.size;
998
+ const existed = fs.existsSync(itemLocalPath);
999
+ try {
1000
+ await downloadFile(alias, item.path, itemLocalPath, undefined, sftp);
1001
+ accumulator.addFile(item.size, existed);
1002
+ }
1003
+ catch (error) {
1004
+ accumulator.addFailed();
1005
+ throw error;
1006
+ }
686
1007
  });
687
1008
  for (const item of dirItems) {
688
1009
  const itemLocalPath = path.join(localPath, item.name);
689
1010
  const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp);
690
- fileCount += result.fileCount;
691
- totalSize += result.totalSize;
692
- skippedSymlinks += result.skippedSymlinks;
1011
+ accumulator.merge(result);
693
1012
  }
694
1013
  for (const item of symlinkItems) {
695
1014
  console.warn(`[ssh_sync] skipping remote symlink: ${item.path}`);
696
- skippedSymlinks++;
1015
+ accumulator.addSkippedSymlink();
697
1016
  }
698
1017
  }
699
1018
  finally {
@@ -701,7 +1020,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
701
1020
  sftp.end();
702
1021
  }
703
1022
  }
704
- return { fileCount, totalSize, skippedSymlinks };
1023
+ return accumulator.toResult();
705
1024
  }
706
1025
  /**
707
1026
  * 简单的模式匹配(支持 * 和 ?)