@pyrokine/mcp-ssh 2.4.1 → 2.4.3

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
@@ -9,7 +9,9 @@ import * as path from 'path';
9
9
  import { StringDecoder } from 'string_decoder';
10
10
  import { matchesDirectoryExclude } from './directory-verification.js';
11
11
  import { sessionManager } from './session-manager.js';
12
+ import { SftpOperationTimeoutError, withSftpOperationTimeout } from './sftp-timeout.js';
12
13
  import { escapeShellArg, expandTilde } from './tools/utils.js';
14
+ import { ensureUtf8Boundary, isUtf8ContinuationByte, utf8SafeEnd } from './utf8.js';
13
15
  // 文件类型 mode 常量
14
16
  const S_IFMT = 0o170000; // 文件类型位掩码
15
17
  const S_IFDIR = 0o40000;
@@ -106,14 +108,6 @@ const SFTP_SYNC_MAX_FILES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_FILES', 10_000)
106
108
  const SFTP_SYNC_MAX_DIRECTORIES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DIRECTORIES', 2_000);
107
109
  const SFTP_SYNC_MAX_DEPTH = positiveIntegerEnv('SSH_MCP_SFTP_MAX_DEPTH', 64);
108
110
  const SFTP_SYNC_MAX_BYTES = positiveIntegerEnv('SSH_MCP_SFTP_MAX_BYTES', 10 * 1024 * 1024 * 1024);
109
- class SftpOperationTimeoutError extends Error {
110
- timeout;
111
- constructor(timeout) {
112
- super(`SFTP operation timed out after ${timeout}ms; remote transfer state is unknown`);
113
- this.timeout = timeout;
114
- this.name = 'SftpOperationTimeoutError';
115
- }
116
- }
117
111
  function abortError(signal) {
118
112
  return signal.reason instanceof Error ? signal.reason : new Error('SFTP operation aborted');
119
113
  }
@@ -249,7 +243,8 @@ function validateLocalUploadSource(localPath, followSymlinks, symlinkError) {
249
243
  throw new Error(symlinkError);
250
244
  }
251
245
  if (followSymlinks && getAllowListStatus(expandedPath).configured) {
252
- throw new Error('followSymlinks=true cannot be combined with SSH_MCP_FILE_OPS_ALLOW_DIRS because symlink targets can change during transfer');
246
+ throw new Error('followSymlinks=true cannot be combined with SSH_MCP_FILE_OPS_ALLOW_DIRS because ' +
247
+ 'symlink targets can change during transfer');
253
248
  }
254
249
  return {
255
250
  expandedPath,
@@ -267,7 +262,7 @@ export function validateUploadFileSource(localPath) {
267
262
  }
268
263
  return source;
269
264
  }
270
- export function validateSyncUploadSource(localPath, followSymlinks = false, _exclude) {
265
+ export function validateSyncUploadSource(localPath, followSymlinks = false) {
271
266
  return validateLocalUploadSource(localPath, followSymlinks, 'Refusing to sync a top-level symlink; set followSymlinks=true to traverse its target');
272
267
  }
273
268
  export function probeLocalPath(localPath, followSymlinks = false) {
@@ -296,8 +291,17 @@ export function probeLocalPath(localPath, followSymlinks = false) {
296
291
  /**
297
292
  * sftp.stat 的 Promise 包装
298
293
  */
299
- function sftpStat(sftp, remotePath) {
300
- return new Promise((resolve, reject) => {
294
+ async function getSftpWithinDeadline(alias, timeout) {
295
+ const request = sessionManager.getSftp(alias);
296
+ return withSftpOperationTimeout(request, timeout, () => {
297
+ void request.then((sftp) => sftp.end(), () => undefined);
298
+ });
299
+ }
300
+ function withSftpDeadline(sftp, operation, timeout) {
301
+ return withSftpOperationTimeout(operation, timeout, () => sftp.end());
302
+ }
303
+ function sftpStat(sftp, remotePath, timeout) {
304
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
301
305
  sftp.stat(remotePath, (err, stats) => {
302
306
  if (err) {
303
307
  reject(err);
@@ -306,7 +310,7 @@ function sftpStat(sftp, remotePath) {
306
310
  resolve(stats);
307
311
  }
308
312
  });
309
- });
313
+ }), timeout);
310
314
  }
311
315
  function isSftpMissingError(error) {
312
316
  if (!error || typeof error !== 'object') {
@@ -335,7 +339,7 @@ async function sftpExists(sftp, remotePath) {
335
339
  }
336
340
  }
337
341
  async function remoteExists(alias, remotePath) {
338
- const sftp = await sessionManager.getSftp(alias);
342
+ const sftp = await getSftpWithinDeadline(alias);
339
343
  try {
340
344
  return await sftpExists(sftp, remotePath);
341
345
  }
@@ -344,8 +348,8 @@ async function remoteExists(alias, remotePath) {
344
348
  }
345
349
  }
346
350
  export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
347
- const sftp = await sessionManager.getSftp(alias);
348
- return new Promise((resolve, reject) => {
351
+ const sftp = await getSftpWithinDeadline(alias);
352
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
349
353
  const hash = createHash(algorithm);
350
354
  const stream = sftp.createReadStream(remotePath);
351
355
  let settled = false;
@@ -365,7 +369,7 @@ export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
365
369
  stream.on('data', (chunk) => hash.update(chunk));
366
370
  stream.once('error', finish);
367
371
  stream.once('end', () => finish());
368
- });
372
+ }));
369
373
  }
370
374
  export class RemoteRenameNotStartedError extends Error {
371
375
  constructor(message) {
@@ -373,9 +377,9 @@ export class RemoteRenameNotStartedError extends Error {
373
377
  this.name = 'RemoteRenameNotStartedError';
374
378
  }
375
379
  }
376
- export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExisting = false) {
377
- const sftp = await sessionManager.getSftp(alias);
378
- return new Promise((resolve, reject) => {
380
+ export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExisting = false, timeout) {
381
+ const sftp = await getSftpWithinDeadline(alias, timeout);
382
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
379
383
  const callback = (error) => {
380
384
  sftp.end();
381
385
  if (error) {
@@ -397,11 +401,11 @@ export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExi
397
401
  sftp.end();
398
402
  reject(new RemoteRenameNotStartedError(`SFTP rename request was not sent: ${error instanceof Error ? error.message : String(error)}`));
399
403
  }
400
- });
404
+ }), timeout);
401
405
  }
402
406
  export async function removeRemoteFile(alias, remotePath) {
403
- const sftp = await sessionManager.getSftp(alias);
404
- return new Promise((resolve, reject) => {
407
+ const sftp = await getSftpWithinDeadline(alias);
408
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
405
409
  sftp.unlink(remotePath, (error) => {
406
410
  sftp.end();
407
411
  if (error && !isSftpMissingError(error)) {
@@ -411,7 +415,7 @@ export async function removeRemoteFile(alias, remotePath) {
411
415
  resolve();
412
416
  }
413
417
  });
414
- });
418
+ }));
415
419
  }
416
420
  /**
417
421
  * 带进度追踪的流传输
@@ -491,16 +495,21 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
491
495
  }
492
496
  export class UploadFileError extends Error {
493
497
  remoteCreated;
498
+ details;
494
499
  constructor(message, remoteCreated, options) {
495
500
  super(message, options);
496
501
  this.remoteCreated = remoteCreated;
497
502
  this.name = 'UploadFileError';
503
+ const cause = options?.cause;
504
+ if (cause && typeof cause === 'object' && 'details' in cause) {
505
+ this.details = cause.details;
506
+ }
498
507
  }
499
508
  }
500
509
  /**
501
510
  * 上传文件
502
511
  */
503
- export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal, followSymlinks = false, exclusive = false) {
512
+ export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal, followSymlinks = false, exclusive = false, timeout) {
504
513
  throwIfAborted(signal);
505
514
  const source = followSymlinks
506
515
  ? validateLocalUploadSource(localPath, true, 'Refusing to upload symlink at top level (use ssh_sync with followSymlinks=true to traverse)')
@@ -513,7 +522,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
513
522
  if (!stats.isFile()) {
514
523
  throw new Error('UPLOAD_PATH_IS_NOT_FILE: localPath is not a regular file');
515
524
  }
516
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
525
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
517
526
  const totalSize = stats.size;
518
527
  const safeCreateMode = (createMode ?? stats.mode) & 0o777;
519
528
  const writeStream = sftp.createWriteStream(remotePath, { mode: safeCreateMode, flags: exclusive ? 'wx' : 'w' });
@@ -522,7 +531,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
522
531
  remoteCreated = true;
523
532
  });
524
533
  try {
525
- const result = await pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal);
534
+ const result = await withSftpDeadline(sftp, pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
526
535
  return { ...result, createMode: safeCreateMode.toString(8).padStart(4, '0') };
527
536
  }
528
537
  catch (error) {
@@ -531,31 +540,51 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
531
540
  });
532
541
  }
533
542
  }
543
+ async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, closeSftpOnFailure, timeout) {
544
+ let readStream;
545
+ try {
546
+ const totalSize = (await sftpStat(sftp, remotePath, timeout)).size;
547
+ if (!fs.existsSync(localDir)) {
548
+ fs.mkdirSync(localDir, { recursive: true });
549
+ }
550
+ readStream = sftp.createReadStream(remotePath);
551
+ return {
552
+ totalSize,
553
+ readStream,
554
+ writeStream: fs.createWriteStream(temporaryPath, { flags: 'wx' }),
555
+ };
556
+ }
557
+ catch (error) {
558
+ try {
559
+ ;
560
+ readStream?.destroy?.();
561
+ }
562
+ catch {
563
+ /* ignore cleanup errors while preserving the transfer setup error */
564
+ }
565
+ if (closeSftpOnFailure) {
566
+ sftp.end();
567
+ }
568
+ throw error;
569
+ }
570
+ }
534
571
  /**
535
572
  * 下载文件
536
573
  */
537
- export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal) {
574
+ export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal, timeout) {
538
575
  throwIfAborted(signal);
539
576
  localPath = expandTilde(localPath);
540
577
  validateLocalPathAgainstAllowList(localPath);
541
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
578
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
542
579
  const localDir = path.dirname(localPath);
543
580
  const temporaryPath = path.join(localDir, `.${path.basename(localPath)}.mcp-tmp-${process.pid}-${randomBytes(8).toString('hex')}`);
544
- let transferStarted = false;
545
581
  try {
546
- const totalSize = (await sftpStat(sftp, remotePath)).size;
547
- if (!fs.existsSync(localDir)) {
548
- fs.mkdirSync(localDir, { recursive: true });
549
- }
550
- transferStarted = true;
551
- const result = await pipeWithProgress(sftp.createReadStream(remotePath), fs.createWriteStream(temporaryPath, { flags: 'wx' }), sftp, totalSize, onProgress, !sharedSftp, signal);
582
+ const { totalSize, readStream, writeStream } = await prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, !sharedSftp, timeout);
583
+ const result = await withSftpDeadline(sftp, pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
552
584
  await fs.promises.rename(temporaryPath, localPath);
553
585
  return { ...result, atomic: true };
554
586
  }
555
587
  catch (error) {
556
- if (!sharedSftp && !transferStarted) {
557
- sftp.end();
558
- }
559
588
  try {
560
589
  await fs.promises.unlink(temporaryPath);
561
590
  }
@@ -639,24 +668,26 @@ export function buildLineRangeAwkProgram(start, end) {
639
668
  `NR > ${end} { if (full_body) { byte_limit = 1 } saw_after = 1; exit }`,
640
669
  'END {',
641
670
  ' if (full_body && final_terminated) { byte_limit = 1 }',
642
- ' printf "__MCP_LINE_META__%d:%d:%d:%d:%d\\n", actual_start, actual_end, written, byte_limit, saw_after > "/dev/stderr"',
671
+ ' printf "__MCP_LINE_META__%d:%d:%d:%d:%d\\n",' +
672
+ ' actual_start, actual_end, written, byte_limit, saw_after > "/dev/stderr"',
643
673
  '}',
644
674
  ].join('\n');
645
675
  }
646
- async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange) {
676
+ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange, timeout) {
647
677
  const { start, end } = parseLineRange(lineRange);
648
678
  const awkProgram = buildLineRangeAwkProgram(start, end);
649
679
  const escapedPath = escapeShellArg(remotePath);
650
680
  const command = [
651
681
  `last_byte=$(tail -c 1 -- ${escapedPath} 2>/dev/null | od -An -tu1 | tr -d ' ')`,
652
682
  'if [ "$last_byte" = "10" ]; then terminated=1; else terminated=0; fi',
653
- `LC_ALL=C awk -v max=${maxBytes} -v final_terminated="$terminated" ${escapeShellArg(awkProgram)} ${escapedPath} | base64 | tr -d '\\n'`,
683
+ `LC_ALL=C awk -v max=${maxBytes} -v final_terminated="$terminated" ` +
684
+ `${escapeShellArg(awkProgram)} ${escapedPath} | base64 | tr -d '\\n'`,
654
685
  'status=${PIPESTATUS[0]}',
655
686
  'printf "__MCP_LINE_END__%s\\n" "$terminated" >&2',
656
687
  'exit "$status"',
657
688
  ].join('; ');
658
689
  const result = await sessionManager.exec(alias, `bash -c ${escapeShellArg(command)}`, {
659
- timeout: 30000,
690
+ timeout: timeout ?? 30000,
660
691
  useLoginUser: true,
661
692
  maxOutputSize: Math.ceil(maxBytes / 3) * 4 + 4096,
662
693
  });
@@ -711,10 +742,10 @@ async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange)
711
742
  export async function readFile(alias, remotePath, options) {
712
743
  const readOptions = normalizeReadFileOptions(options);
713
744
  validateReadFileOptions(readOptions);
714
- const sftp = await sessionManager.getSftp(alias);
745
+ const sftp = await getSftpWithinDeadline(alias, readOptions.timeout);
715
746
  let actualSize;
716
747
  try {
717
- actualSize = (await sftpStat(sftp, remotePath)).size;
748
+ actualSize = (await sftpStat(sftp, remotePath, readOptions.timeout)).size;
718
749
  }
719
750
  catch (error) {
720
751
  sftp.end();
@@ -722,16 +753,16 @@ export async function readFile(alias, remotePath, options) {
722
753
  }
723
754
  if (readOptions.lineRange) {
724
755
  sftp.end();
725
- return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange);
756
+ return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.timeout);
726
757
  }
727
758
  if (actualSize === 0) {
728
759
  sftp.end();
729
760
  return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full');
730
761
  }
731
- const readOffset = readOptions.tail
762
+ const requestedOffset = readOptions.tail
732
763
  ? Math.max(0, actualSize - readOptions.maxBytes)
733
764
  : Math.min(readOptions.offset ?? 0, actualSize);
734
- const readSize = Math.min(actualSize - readOffset, readOptions.maxBytes);
765
+ const readSize = Math.min(actualSize - requestedOffset, readOptions.maxBytes);
735
766
  const sampleKind = readOptions.tail
736
767
  ? 'tail'
737
768
  : readOptions.offset !== undefined
@@ -741,46 +772,74 @@ export async function readFile(alias, remotePath, options) {
741
772
  : 'head';
742
773
  if (readSize === 0) {
743
774
  sftp.end();
744
- return emptyReadResult(actualSize, sampleKind, readOffset);
775
+ return emptyReadResult(actualSize, sampleKind, requestedOffset);
745
776
  }
746
- return new Promise((resolve, reject) => {
777
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
747
778
  const chunks = [];
779
+ let settled = false;
780
+ const finish = (error) => {
781
+ if (settled) {
782
+ return;
783
+ }
784
+ settled = true;
785
+ sftp.end();
786
+ if (error) {
787
+ reject(error);
788
+ return;
789
+ }
790
+ try {
791
+ const buffer = Buffer.concat(chunks);
792
+ let contentStart = 0;
793
+ if (readOptions.tail) {
794
+ while (contentStart < buffer.length && isUtf8ContinuationByte(buffer[contentStart])) {
795
+ ++contentStart;
796
+ }
797
+ }
798
+ else {
799
+ ensureUtf8Boundary(buffer, 0, 'offset');
800
+ }
801
+ const contentEnd = utf8SafeEnd(buffer, contentStart, buffer.length, remotePath, requestedOffset + buffer.length < actualSize);
802
+ const contentBuffer = buffer.subarray(contentStart, contentEnd);
803
+ const actualReadOffset = requestedOffset + contentStart;
804
+ const nextOffset = requestedOffset + contentEnd;
805
+ const remainingBytes = Math.max(0, actualSize - nextOffset);
806
+ resolve({
807
+ content: contentBuffer.toString('utf-8'),
808
+ size: actualSize,
809
+ total_size: actualSize,
810
+ read_offset: actualReadOffset,
811
+ requested_offset: requestedOffset,
812
+ read_bytes: contentBuffer.length,
813
+ read_end: nextOffset,
814
+ next_offset: nextOffset,
815
+ remaining_bytes: remainingBytes,
816
+ sample_kind: sampleKind,
817
+ truncated: actualReadOffset > 0 || remainingBytes > 0,
818
+ });
819
+ }
820
+ catch (processingError) {
821
+ reject(processingError);
822
+ }
823
+ };
748
824
  const readStream = sftp.createReadStream(remotePath, {
749
- start: readOffset,
750
- end: readOffset + readSize - 1,
825
+ start: requestedOffset,
826
+ end: requestedOffset + readSize - 1,
751
827
  });
752
828
  readStream.on('data', (chunk) => {
753
829
  chunks.push(chunk);
754
830
  });
755
- readStream.on('end', () => {
756
- sftp.end();
757
- const buffer = Buffer.concat(chunks);
758
- const remainingBytes = Math.max(0, actualSize - readOffset - buffer.length);
759
- resolve({
760
- content: buffer.toString('utf-8'),
761
- size: actualSize,
762
- total_size: actualSize,
763
- read_offset: readOffset,
764
- read_bytes: buffer.length,
765
- remaining_bytes: remainingBytes,
766
- sample_kind: sampleKind,
767
- truncated: readOffset > 0 || remainingBytes > 0,
768
- });
769
- });
770
- readStream.on('error', (err) => {
771
- sftp.end();
772
- reject(err);
773
- });
774
- });
831
+ readStream.once('end', () => finish());
832
+ readStream.once('error', (error) => finish(error));
833
+ }), readOptions.timeout);
775
834
  }
776
835
  /**
777
836
  * 写入远程文件
778
837
  */
779
- export async function writeFile(alias, remotePath, content, append = false) {
780
- const sftp = await sessionManager.getSftp(alias);
838
+ export async function writeFile(alias, remotePath, content, append = false, timeout) {
839
+ const sftp = await getSftpWithinDeadline(alias, timeout);
781
840
  const flags = append ? 'a' : 'w';
782
841
  const contentBuffer = Buffer.from(content, 'utf-8');
783
- return new Promise((resolve, reject) => {
842
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
784
843
  const writeStream = sftp.createWriteStream(remotePath, { flags });
785
844
  writeStream.on('close', () => {
786
845
  sftp.end();
@@ -792,7 +851,7 @@ export async function writeFile(alias, remotePath, content, append = false) {
792
851
  });
793
852
  writeStream.write(contentBuffer);
794
853
  writeStream.end();
795
- });
854
+ }), timeout);
796
855
  }
797
856
  function validateSftpEntryName(filename) {
798
857
  if (filename.length === 0 ||
@@ -807,10 +866,10 @@ function validateSftpEntryName(filename) {
807
866
  /**
808
867
  * 列出目录内容
809
868
  */
810
- export async function listDir(alias, remotePath, showHidden = false, sharedSftp) {
811
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
869
+ export async function listDir(alias, remotePath, showHidden = false, sharedSftp, timeout) {
870
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
812
871
  const closeWhenDone = !sharedSftp;
813
- return new Promise((resolve, reject) => {
872
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
814
873
  sftp.readdir(remotePath, (err, list) => {
815
874
  if (err) {
816
875
  if (closeWhenDone) {
@@ -858,14 +917,14 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp)
858
917
  }
859
918
  resolve(files);
860
919
  });
861
- });
920
+ }), timeout);
862
921
  }
863
922
  /**
864
923
  * 获取文件信息
865
924
  */
866
- export async function getFileInfo(alias, remotePath) {
867
- const sftp = await sessionManager.getSftp(alias);
868
- return new Promise((resolve, reject) => {
925
+ export async function getFileInfo(alias, remotePath, timeout) {
926
+ const sftp = await getSftpWithinDeadline(alias, timeout);
927
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
869
928
  sftp.stat(remotePath, (err, stats) => {
870
929
  sftp.end();
871
930
  if (err) {
@@ -886,10 +945,10 @@ export async function getFileInfo(alias, remotePath) {
886
945
  atime: new Date(stats.atime * 1000),
887
946
  });
888
947
  });
889
- });
948
+ }), timeout);
890
949
  }
891
- function sftpMkdir(sftp, remotePath) {
892
- return new Promise((resolve, reject) => {
950
+ function sftpMkdir(sftp, remotePath, timeout) {
951
+ return withSftpDeadline(sftp, new Promise((resolve, reject) => {
893
952
  sftp.mkdir(remotePath, (error) => {
894
953
  if (error) {
895
954
  reject(error);
@@ -898,35 +957,38 @@ function sftpMkdir(sftp, remotePath) {
898
957
  resolve();
899
958
  }
900
959
  });
901
- });
960
+ }), timeout);
902
961
  }
903
- async function ensureSftpDirectory(sftp, remotePath) {
962
+ async function ensureSftpDirectory(sftp, remotePath, timeout) {
904
963
  const normalizedPath = path.posix.normalize(remotePath);
905
964
  if (normalizedPath === '/' || normalizedPath === '.') {
906
965
  return;
907
966
  }
967
+ let existingMode;
908
968
  try {
909
- const stats = await sftpStat(sftp, normalizedPath);
910
- if ((stats.mode & S_IFMT) !== S_IFDIR) {
911
- throw new Error(`Remote path exists and is not a directory: ${normalizedPath}`);
912
- }
913
- return;
969
+ existingMode = (await sftpStat(sftp, normalizedPath, timeout)).mode;
914
970
  }
915
971
  catch (error) {
916
972
  if (!isSftpMissingError(error)) {
917
973
  throw error;
918
974
  }
919
975
  }
976
+ if (existingMode !== undefined) {
977
+ if ((existingMode & S_IFMT) !== S_IFDIR) {
978
+ throw new Error(`Remote path exists and is not a directory: ${normalizedPath}`);
979
+ }
980
+ return;
981
+ }
920
982
  const parent = path.posix.dirname(normalizedPath);
921
983
  if (parent !== normalizedPath) {
922
- await ensureSftpDirectory(sftp, parent);
984
+ await ensureSftpDirectory(sftp, parent, timeout);
923
985
  }
924
986
  try {
925
- await sftpMkdir(sftp, normalizedPath);
987
+ await sftpMkdir(sftp, normalizedPath, timeout);
926
988
  }
927
989
  catch (error) {
928
990
  try {
929
- const stats = await sftpStat(sftp, normalizedPath);
991
+ const stats = await sftpStat(sftp, normalizedPath, timeout);
930
992
  if ((stats.mode & S_IFMT) === S_IFDIR) {
931
993
  return;
932
994
  }
@@ -940,22 +1002,24 @@ async function ensureSftpDirectory(sftp, remotePath) {
940
1002
  /**
941
1003
  * 创建目录
942
1004
  */
943
- export async function mkdir(alias, remotePath, recursive = false, sharedSftp) {
944
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
945
- try {
946
- if (recursive) {
947
- await ensureSftpDirectory(sftp, remotePath);
948
- }
949
- else {
950
- await sftpMkdir(sftp, remotePath);
1005
+ export async function mkdir(alias, remotePath, recursive = false, sharedSftp, timeout) {
1006
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
1007
+ return withSftpDeadline(sftp, (async () => {
1008
+ try {
1009
+ if (recursive) {
1010
+ await ensureSftpDirectory(sftp, remotePath, timeout);
1011
+ }
1012
+ else {
1013
+ await sftpMkdir(sftp, remotePath, timeout);
1014
+ }
1015
+ return true;
951
1016
  }
952
- return true;
953
- }
954
- finally {
955
- if (!sharedSftp) {
956
- sftp.end();
1017
+ finally {
1018
+ if (!sharedSftp) {
1019
+ sftp.end();
1020
+ }
957
1021
  }
958
- }
1022
+ })(), timeout);
959
1023
  }
960
1024
  /**
961
1025
  * 检查远程是否安装 rsync
@@ -1065,7 +1129,7 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
1065
1129
  }
1066
1130
  let sourceIsDirectory;
1067
1131
  if (direction === 'upload') {
1068
- const source = validateSyncUploadSource(localPath, options.followSymlinks === true, options.exclude);
1132
+ const source = validateSyncUploadSource(localPath, options.followSymlinks === true);
1069
1133
  localPath = source.expandedPath;
1070
1134
  sourceIsDirectory = source.stats.isDirectory();
1071
1135
  }
@@ -1593,7 +1657,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1593
1657
  };
1594
1658
  }
1595
1659
  if (stats.isDirectory() && options.recursive === false) {
1596
- throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1660
+ return {
1661
+ success: false,
1662
+ method: 'sftp',
1663
+ operationStatus: 'failed',
1664
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1665
+ output: 'recursive=false does not support directories; use a file source or enable recursion',
1666
+ };
1597
1667
  }
1598
1668
  if (stats.isDirectory()) {
1599
1669
  const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal);
@@ -1610,7 +1680,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1610
1680
  // download
1611
1681
  const info = await getFileInfo(alias, remotePath);
1612
1682
  if (info.isDirectory && options.recursive === false) {
1613
- throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1683
+ return {
1684
+ success: false,
1685
+ method: 'sftp',
1686
+ operationStatus: 'failed',
1687
+ stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1688
+ output: 'recursive=false is not supported for directory sources; use a file source or enable recursion',
1689
+ };
1614
1690
  }
1615
1691
  if (info.isDirectory) {
1616
1692
  const result = await downloadDirectory(alias, remotePath, localPath, options.exclude, undefined, {
@@ -1657,7 +1733,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1657
1733
  const accumulator = new DirectoryTransferAccumulator();
1658
1734
  recordSftpDirectory(traversal, depth, localPath);
1659
1735
  const ownSftp = !sharedSftp;
1660
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
1736
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
1661
1737
  const activeDirectories = (traversal.activeDirectories ??= new Set());
1662
1738
  const realPath = fs.realpathSync(localPath);
1663
1739
  if (activeDirectories.has(realPath)) {
@@ -1737,7 +1813,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1737
1813
  const accumulator = new DirectoryTransferAccumulator();
1738
1814
  recordSftpDirectory(traversal, depth, remotePath);
1739
1815
  const ownSftp = !sharedSftp;
1740
- const sftp = sharedSftp ?? (await sessionManager.getSftp(alias));
1816
+ const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
1741
1817
  try {
1742
1818
  if (!fs.existsSync(localPath)) {
1743
1819
  fs.mkdirSync(localPath, { recursive: true });
@@ -23,7 +23,8 @@ export class ForwardManager {
23
23
  existing.type === 'local' &&
24
24
  existing.lifecycle === 'closing' &&
25
25
  existing.pendingChannelOpens > 0) {
26
- throw new Error(`Alias '${alias}' still has an unresolved SSH channel open; retry closing the existing forward or disconnect the alias`);
26
+ throw new Error(`Alias '${alias}' still has an unresolved SSH channel open; ` +
27
+ 'retry closing the existing forward or disconnect the alias');
27
28
  }
28
29
  }
29
30
  const client = deps.getClient(alias);
@@ -58,7 +59,8 @@ export class ForwardManager {
58
59
  return;
59
60
  }
60
61
  if (this.pendingChannelOpensForAlias(alias) >= MAX_PENDING_CHANNEL_OPENS_PER_ALIAS) {
61
- console.warn(`Local forward ${session.id} rejected a connection because alias '${alias}' already has ${MAX_PENDING_CHANNEL_OPENS_PER_ALIAS} pending SSH channel opens`);
62
+ console.warn(`Local forward ${session.id} rejected a connection because alias '${alias}' already has ` +
63
+ `${MAX_PENDING_CHANNEL_OPENS_PER_ALIAS} pending SSH channel opens`);
62
64
  socket.destroy();
63
65
  return;
64
66
  }
@@ -278,6 +280,7 @@ export class ForwardManager {
278
280
  }
279
281
  });
280
282
  }
283
+ // noinspection ES6MissingAwait — Promise 与 listener close 并发,随后由 Promise.all 等待
281
284
  const channelOpenDrain = fwd.type === 'local' ? this.waitForChannelOpenDrain(fwd) : Promise.resolve();
282
285
  const closeCompletion = mode === 'force'
283
286
  ? Promise.all([fwd.closePromise, this.waitForConnectionDrain(fwd), channelOpenDrain]).then(() => undefined)
@@ -379,6 +382,8 @@ export class ForwardManager {
379
382
  remotePort: fwd.remotePort,
380
383
  createdAt: fwd.createdAt,
381
384
  active: fwd.active,
385
+ lifecycle: fwd.lifecycle,
386
+ acceptingConnections: fwd.active && fwd.lifecycle === 'active',
382
387
  });
383
388
  }
384
389
  return result;
@@ -560,7 +565,8 @@ export class ForwardManager {
560
565
  });
561
566
  }
562
567
  catch (error) {
563
- console.warn(`Cancelled remote forward ${fwd.id} cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
568
+ const message = error instanceof Error ? error.message : String(error);
569
+ console.warn(`Canceled remote forward ${fwd.id} cleanup failed: ${message}`);
564
570
  }
565
571
  }
566
572
  withTimeout(promise, timeoutMs) {
@@ -56,9 +56,4 @@ export declare class OperationManager {
56
56
  private normalizeRetentionMs;
57
57
  private normalizeStartTimeoutMs;
58
58
  private normalizeOffset;
59
- private ensureUtf8Boundary;
60
- private utf8SafeEnd;
61
- private trimIncompleteUtf8Sequence;
62
- private utf8SequenceLength;
63
- private isUtf8ContinuationByte;
64
59
  }