@pyrokine/mcp-ssh 2.4.2 → 3.0.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
@@ -6,12 +6,14 @@ import { createHash, randomBytes } from 'crypto';
6
6
  import * as fs from 'fs';
7
7
  import * as os from 'os';
8
8
  import * as path from 'path';
9
- import { StringDecoder } from 'string_decoder';
9
+ import { checkWindowsAcl, windowsAclScript } from './windows-acl.js';
10
10
  import { matchesDirectoryExclude } from './directory-verification.js';
11
+ import { extractFileMode, FILE_CREATE_MODE_MASK, formatFileMode, formatFilePermissions } from './file-mode.js';
11
12
  import { sessionManager } from './session-manager.js';
12
13
  import { SftpOperationTimeoutError, withSftpOperationTimeout } from './sftp-timeout.js';
13
14
  import { escapeShellArg, expandTilde } from './tools/utils.js';
14
- import { ensureUtf8Boundary, isUtf8ContinuationByte, utf8SafeEnd } from './utf8.js';
15
+ import { encodedPowershell, remoteDirname, remoteJoin, remoteNormalize, remotePathModule, remoteShellPath, windowsCaseSemanticsScript, } from './remote-platform.js';
16
+ import { ensureUtf8Boundary, isUtf8ContinuationByte } from './utf8.js';
15
17
  // 文件类型 mode 常量
16
18
  const S_IFMT = 0o170000; // 文件类型位掩码
17
19
  const S_IFDIR = 0o40000;
@@ -29,14 +31,18 @@ function appendLimitedOutput(current, chunk) {
29
31
  }
30
32
  return (current + chunk).slice(0, LOCAL_PROCESS_OUTPUT_LIMIT);
31
33
  }
32
- function runLocalProcess(command, args, timeout) {
34
+ function runLocalProcess(command, args, timeout, env) {
33
35
  return new Promise((resolve) => {
34
36
  let stdout = '';
35
37
  let stderr = '';
36
38
  let settled = false;
37
39
  let timedOut = false;
38
40
  let killTimer;
39
- const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
41
+ const child = spawn(command, args, {
42
+ stdio: ['ignore', 'pipe', 'pipe'],
43
+ env: env ?? process.env,
44
+ windowsHide: true,
45
+ });
40
46
  const timer = setTimeout(() => {
41
47
  timedOut = true;
42
48
  child.kill('SIGTERM');
@@ -94,7 +100,11 @@ export function clearRsyncCache(alias) {
94
100
  ++rsyncGlobalGeneration;
95
101
  }
96
102
  else {
97
- rsyncCache.delete(alias);
103
+ for (const key of rsyncCache.keys()) {
104
+ if (key.startsWith(`${alias}\0`)) {
105
+ rsyncCache.delete(key);
106
+ }
107
+ }
98
108
  rsyncAliasGenerations.set(alias, (rsyncAliasGenerations.get(alias) ?? 0) + 1);
99
109
  }
100
110
  }
@@ -170,8 +180,26 @@ async function runWithConcurrency(items, limit, worker) {
170
180
  * 格式:path.delimiter 分隔的绝对路径列表(POSIX `:`,Windows `;`),如 `/tmp:/home/user/work`
171
181
  * 安全性:路径会通过 fs.realpathSync 解析 symlink,防止 symlink 逃出白名单
172
182
  */
173
- function quoteRsyncSshArg(value) {
174
- return escapeShellArg(String(value));
183
+ export function convertRsyncPath(value, profile) {
184
+ if (profile === 'native-win32' || profile === 'posix') {
185
+ return value;
186
+ }
187
+ const drive = /^([a-zA-Z]):[\\/](.*)$/.exec(value);
188
+ if (drive) {
189
+ const prefix = profile === 'cygwin' ? '/cygdrive/' : '/';
190
+ return `${prefix}${drive[1].toLowerCase()}/${drive[2].replace(/\\/g, '/')}`;
191
+ }
192
+ if (value.startsWith('\\\\')) {
193
+ return `//${value.slice(2).replace(/\\/g, '/')}`;
194
+ }
195
+ return value.replace(/\\/g, '/');
196
+ }
197
+ export function quoteRsyncSshArg(value, profile = 'posix') {
198
+ const text = String(value);
199
+ if (/[\r\n\0]/.test(text)) {
200
+ throw new Error('rsync SSH argument contains a newline or NUL');
201
+ }
202
+ return profile === 'posix' ? escapeShellArg(text) : `"${text.replace(/([\\"])/g, '\\$1')}"`;
175
203
  }
176
204
  function configuredAllowDirectories() {
177
205
  const allowEnv = process.env.SSH_MCP_FILE_OPS_ALLOW_DIRS;
@@ -280,7 +308,8 @@ export function probeLocalPath(localPath, followSymlinks = false) {
280
308
  expandedPath: expanded,
281
309
  resolvedPath,
282
310
  size: stats.size,
283
- mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
311
+ mode: formatFileMode(stats.mode),
312
+ modeValue: extractFileMode(stats.mode),
284
313
  mtimeMs: Math.round(stats.mtimeMs),
285
314
  isSymlink: linkStats.isSymbolicLink(),
286
315
  isDirectory: stats.isDirectory(),
@@ -371,6 +400,19 @@ export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
371
400
  stream.once('end', () => finish());
372
401
  }));
373
402
  }
403
+ export async function atomicReplaceCapability(alias, timeout) {
404
+ const sftp = await getSftpWithinDeadline(alias, timeout);
405
+ try {
406
+ // ssh2 checks this negotiated extension before sending ext_openssh_rename.
407
+ const extensions = sftp._extensions;
408
+ return extensions?.['posix-rename@openssh.com'] === '1'
409
+ ? { atomicReplaceSupported: true }
410
+ : { atomicReplaceSupported: false, reason: 'posix-rename@openssh.com was not negotiated' };
411
+ }
412
+ finally {
413
+ sftp.end();
414
+ }
415
+ }
374
416
  export class RemoteRenameNotStartedError extends Error {
375
417
  constructor(message) {
376
418
  super(message);
@@ -403,8 +445,8 @@ export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExi
403
445
  }
404
446
  }), timeout);
405
447
  }
406
- export async function removeRemoteFile(alias, remotePath) {
407
- const sftp = await getSftpWithinDeadline(alias);
448
+ export async function removeRemoteFile(alias, remotePath, timeout) {
449
+ const sftp = await getSftpWithinDeadline(alias, timeout);
408
450
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
409
451
  sftp.unlink(remotePath, (error) => {
410
452
  sftp.end();
@@ -415,7 +457,7 @@ export async function removeRemoteFile(alias, remotePath) {
415
457
  resolve();
416
458
  }
417
459
  });
418
- }));
460
+ }), timeout);
419
461
  }
420
462
  /**
421
463
  * 带进度追踪的流传输
@@ -524,7 +566,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
524
566
  }
525
567
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
526
568
  const totalSize = stats.size;
527
- const safeCreateMode = (createMode ?? stats.mode) & 0o777;
569
+ const safeCreateMode = (createMode ?? stats.mode) & FILE_CREATE_MODE_MASK;
528
570
  const writeStream = sftp.createWriteStream(remotePath, { mode: safeCreateMode, flags: exclusive ? 'wx' : 'w' });
529
571
  let remoteCreated = false;
530
572
  writeStream.once('open', () => {
@@ -532,7 +574,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
532
574
  });
533
575
  try {
534
576
  const result = await withSftpDeadline(sftp, pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
535
- return { ...result, createMode: safeCreateMode.toString(8).padStart(4, '0') };
577
+ return { ...result, createMode: formatFileMode(safeCreateMode) };
536
578
  }
537
579
  catch (error) {
538
580
  throw new UploadFileError(error instanceof Error ? error.message : String(error), remoteCreated, {
@@ -540,6 +582,22 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
540
582
  });
541
583
  }
542
584
  }
585
+ async function existingDownloadTargetMode(localPath) {
586
+ let stats;
587
+ try {
588
+ stats = await fs.promises.lstat(localPath);
589
+ }
590
+ catch (error) {
591
+ if (isLocalMissingError(error)) {
592
+ return undefined;
593
+ }
594
+ throw error;
595
+ }
596
+ if (!stats.isFile()) {
597
+ throw new Error(`Refusing to replace a non-regular local target: ${localPath}`);
598
+ }
599
+ return stats.mode & FILE_CREATE_MODE_MASK;
600
+ }
543
601
  async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, closeSftpOnFailure, timeout) {
544
602
  let readStream;
545
603
  try {
@@ -547,11 +605,21 @@ async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath
547
605
  if (!fs.existsSync(localDir)) {
548
606
  fs.mkdirSync(localDir, { recursive: true });
549
607
  }
608
+ if (process.platform === 'win32') {
609
+ const handle = await fs.promises.open(temporaryPath, 'wx', 0o600);
610
+ await handle.close();
611
+ if (checkWindowsAcl(temporaryPath, true) !== 'key_path_usable') {
612
+ throw new Error('privacy_not_enforced_on_windows: temporary download file ACL could not be verified');
613
+ }
614
+ }
550
615
  readStream = sftp.createReadStream(remotePath);
551
616
  return {
552
617
  totalSize,
553
618
  readStream,
554
- writeStream: fs.createWriteStream(temporaryPath, { flags: 'wx' }),
619
+ writeStream: fs.createWriteStream(temporaryPath, {
620
+ flags: process.platform === 'win32' ? 'r+' : 'wx',
621
+ mode: 0o600,
622
+ }),
555
623
  };
556
624
  }
557
625
  catch (error) {
@@ -575,12 +643,16 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
575
643
  throwIfAborted(signal);
576
644
  localPath = expandTilde(localPath);
577
645
  validateLocalPathAgainstAllowList(localPath);
646
+ const preservedMode = await existingDownloadTargetMode(localPath);
578
647
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
579
648
  const localDir = path.dirname(localPath);
580
649
  const temporaryPath = path.join(localDir, `.${path.basename(localPath)}.mcp-tmp-${process.pid}-${randomBytes(8).toString('hex')}`);
581
650
  try {
582
651
  const { totalSize, readStream, writeStream } = await prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, !sharedSftp, timeout);
583
652
  const result = await withSftpDeadline(sftp, pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
653
+ if (process.platform !== 'win32') {
654
+ await fs.promises.chmod(temporaryPath, preservedMode ?? 0o600);
655
+ }
584
656
  await fs.promises.rename(temporaryPath, localPath);
585
657
  return { ...result, atomic: true };
586
658
  }
@@ -632,10 +704,24 @@ function validateReadFileOptions(options) {
632
704
  if (selectors.length > 1) {
633
705
  throw new Error('offset、tail、lineRange 只能同时指定一个');
634
706
  }
707
+ if (options.lineRange !== undefined) {
708
+ parseLineRange(options.lineRange);
709
+ }
710
+ if (!options.binary &&
711
+ options.offset !== undefined &&
712
+ options.encoding?.startsWith('utf16') &&
713
+ options.offset % 2 !== 0) {
714
+ throw new Error('UTF-16 offset must point to a complete code unit boundary');
715
+ }
716
+ if (!options.binary && options.encoding === 'gbk' && (options.offset !== undefined || options.tail)) {
717
+ throw new Error('GBK byte offsets cannot prove character boundaries; use lineRange or binary=true');
718
+ }
635
719
  }
636
- function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
720
+ function emptyReadResult(totalSize, sampleKind, readOffset = 0, binary = false) {
637
721
  return {
638
722
  content: '',
723
+ content_base64: binary ? '' : undefined,
724
+ encoding: binary ? 'base64' : undefined,
639
725
  size: totalSize,
640
726
  total_size: totalSize,
641
727
  read_offset: readOffset,
@@ -645,95 +731,210 @@ function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
645
731
  truncated: readOffset < totalSize,
646
732
  };
647
733
  }
648
- export function buildLineRangeAwkProgram(start, end) {
649
- return [
650
- 'BEGIN { written = 0; actual_start = 0; actual_end = 0; byte_limit = 0; saw_after = 0; full_body = 0 }',
651
- `NR >= ${start} && NR <= ${end} {`,
652
- ' if (actual_start == 0) { actual_start = NR }',
653
- ' actual_end = NR',
654
- ' remaining = max - written',
655
- ' if (remaining <= 0) { byte_limit = 1; exit }',
656
- ' body_length = length($0)',
657
- ' if (body_length >= remaining) {',
658
- ' printf "%s", substr($0, 1, remaining)',
659
- ' written += remaining',
660
- ' if (body_length > remaining) { byte_limit = 1; exit }',
661
- ' full_body = 1',
662
- ' next',
663
- ' }',
664
- ' printf "%s\\n", $0',
665
- ' written += body_length + 1',
666
- ' full_body = 0',
667
- '}',
668
- `NR > ${end} { if (full_body) { byte_limit = 1 } saw_after = 1; exit }`,
669
- 'END {',
670
- ' if (full_body && final_terminated) { byte_limit = 1 }',
671
- ' printf "__MCP_LINE_META__%d:%d:%d:%d:%d\\n",' +
672
- ' actual_start, actual_end, written, byte_limit, saw_after > "/dev/stderr"',
673
- '}',
674
- ].join('\n');
675
- }
676
- async function readLineRange(alias, remotePath, totalSize, maxBytes, lineRange, timeout) {
734
+ function detectReadEncoding(firstBytes, requested) {
735
+ if (requested !== 'auto') {
736
+ return requested;
737
+ }
738
+ if (firstBytes[0] === 0xff && firstBytes[1] === 0xfe) {
739
+ return 'utf16le';
740
+ }
741
+ if (firstBytes[0] === 0xfe && firstBytes[1] === 0xff) {
742
+ return 'utf16be';
743
+ }
744
+ return 'utf8';
745
+ }
746
+ function decodeReadBuffer(bytes, encoding, binary, budgetTruncated) {
747
+ if (binary) {
748
+ return { content: bytes.toString('base64'), content_base64: bytes.toString('base64'), read_bytes: bytes.length };
749
+ }
750
+ const label = encoding === 'utf8' ? 'utf-8' : encoding === 'gbk' ? 'gbk' : encoding === 'utf16le' ? 'utf-16le' : 'utf-16be';
751
+ const invalid = () => new Error(`Invalid ${encoding} sequence or offset is not a character boundary`);
752
+ const decoder = new TextDecoder(label, { fatal: true });
753
+ let content;
754
+ try {
755
+ // Streaming validation rejects malformed complete characters before considering an incomplete suffix.
756
+ content = decoder.decode(bytes, { stream: true });
757
+ }
758
+ catch {
759
+ throw invalid();
760
+ }
761
+ try {
762
+ content += decoder.decode();
763
+ return { content, read_bytes: bytes.length };
764
+ }
765
+ catch {
766
+ if (!budgetTruncated) {
767
+ throw invalid();
768
+ }
769
+ }
770
+ // Only a byte-budget boundary may leave up to three bytes of an incomplete character.
771
+ for (let end = bytes.length - 1; end >= Math.max(0, bytes.length - 3); --end) {
772
+ try {
773
+ content = new TextDecoder(label, { fatal: true }).decode(bytes.subarray(0, end));
774
+ }
775
+ catch {
776
+ continue;
777
+ }
778
+ if (end === 0 && bytes.length > 0) {
779
+ throw new Error(`maxBytes is too small to read the next ${encoding} character`);
780
+ }
781
+ return { content, read_bytes: end };
782
+ }
783
+ throw invalid();
784
+ }
785
+ async function readLineRange(sftp, remotePath, totalSize, maxBytes, lineRange, encoding, binary, timeout) {
677
786
  const { start, end } = parseLineRange(lineRange);
678
- const awkProgram = buildLineRangeAwkProgram(start, end);
679
- const escapedPath = escapeShellArg(remotePath);
680
- const command = [
681
- `last_byte=$(tail -c 1 -- ${escapedPath} 2>/dev/null | od -An -tu1 | tr -d ' ')`,
682
- 'if [ "$last_byte" = "10" ]; then terminated=1; else terminated=0; fi',
683
- `LC_ALL=C awk -v max=${maxBytes} -v final_terminated="$terminated" ` +
684
- `${escapeShellArg(awkProgram)} ${escapedPath} | base64 | tr -d '\\n'`,
685
- 'status=${PIPESTATUS[0]}',
686
- 'printf "__MCP_LINE_END__%s\\n" "$terminated" >&2',
687
- 'exit "$status"',
688
- ].join('; ');
689
- const result = await sessionManager.exec(alias, `bash -c ${escapeShellArg(command)}`, {
690
- timeout: timeout ?? 30000,
691
- useLoginUser: true,
692
- maxOutputSize: Math.ceil(maxBytes / 3) * 4 + 4096,
693
- });
694
- if (!result.success) {
695
- const message = result.stderr.trim() ||
696
- result.stdout.trim() ||
697
- `remote lineRange command failed with exit code ${result.exitCode}`;
698
- throw new Error(message);
699
- }
700
- const metadataMatch = result.stderr.match(/__MCP_LINE_META__(\d+):(\d+):(\d+):([01]):([01])/);
701
- const terminatedMatch = result.stderr.match(/__MCP_LINE_END__([01])/);
702
- if (!metadataMatch || !terminatedMatch) {
703
- throw new Error('remote lineRange command returned incomplete metadata');
704
- }
705
- const actualStart = Number(metadataMatch[1]);
706
- const actualEnd = Number(metadataMatch[2]);
707
- const encoded = result.stdout.trim();
708
- if (encoded && (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 !== 0)) {
709
- throw new Error('remote lineRange command returned malformed base64 content');
710
- }
711
- let rawContent = Buffer.from(encoded, 'base64');
712
- const metadataByteLimitReached = metadataMatch[4] === '1';
713
- const sawAfter = metadataMatch[5] === '1';
714
- const finalLineTerminated = terminatedMatch[1] === '1';
715
- if (!sawAfter && !metadataByteLimitReached && !finalLineTerminated && rawContent.at(-1) === 0x0a) {
716
- rawContent = rawContent.subarray(0, -1);
717
- }
718
- const decoder = new StringDecoder('utf8');
719
- const content = decoder.write(rawContent);
720
- const incompleteUtf8 = decoder.end().length > 0;
721
- const readBytes = Buffer.byteLength(content, 'utf8');
722
- const byteLimitReached = metadataByteLimitReached || incompleteUtf8;
723
- const eof = !sawAfter && !byteLimitReached;
787
+ let stream;
788
+ try {
789
+ stream = sftp.createReadStream(remotePath);
790
+ }
791
+ catch (error) {
792
+ sftp.end();
793
+ throw error;
794
+ }
795
+ const chunks = [];
796
+ let line = 1;
797
+ let lineStart;
798
+ let lineEnd;
799
+ let size = 0;
800
+ let consumed = 0;
801
+ let byteLimitReached = false;
802
+ let sawAfter = false;
803
+ let encodingDetected = encoding !== 'auto';
804
+ let detected = encoding === 'auto' ? 'utf8' : encoding;
805
+ let pending = Buffer.alloc(0);
806
+ try {
807
+ await withSftpDeadline(sftp, (async () => {
808
+ for await (const part of stream) {
809
+ const chunk = Buffer.from(part);
810
+ consumed += chunk.length;
811
+ if (consumed > 1024 * 1024 * 1024) {
812
+ throw new Error('lineRange scan exceeded the 1 GiB input budget');
813
+ }
814
+ // Preserve a split UTF-16 code unit across SFTP chunks.
815
+ const data = Buffer.concat([pending, chunk]);
816
+ if (!encodingDetected && data.length < 2) {
817
+ pending = data;
818
+ continue;
819
+ }
820
+ if (!encodingDetected) {
821
+ detected = detectReadEncoding(data, encoding);
822
+ encodingDetected = true;
823
+ }
824
+ const width = detected.startsWith('utf16') ? 2 : 1;
825
+ const bigEndian = detected === 'utf16be';
826
+ const available = data.length - (data.length % width);
827
+ let segmentStart = 0;
828
+ for (let index = 0; index < available; index += width) {
829
+ const newline = width === 1
830
+ ? data[index] === 10
831
+ : bigEndian
832
+ ? data[index] === 0 && data[index + 1] === 10
833
+ : data[index] === 10 && data[index + 1] === 0;
834
+ if (!newline) {
835
+ continue;
836
+ }
837
+ if (line >= start && line <= end) {
838
+ const length = index + width - segmentStart;
839
+ const remaining = maxBytes - size;
840
+ if (length > remaining) {
841
+ if (remaining > 0) {
842
+ chunks.push(data.subarray(segmentStart, segmentStart + remaining));
843
+ size += remaining;
844
+ lineStart ??= line;
845
+ }
846
+ byteLimitReached = true;
847
+ stream.destroy();
848
+ break;
849
+ }
850
+ chunks.push(data.subarray(segmentStart, index + width));
851
+ size += length;
852
+ lineStart ??= line;
853
+ }
854
+ ++line;
855
+ segmentStart = index + width;
856
+ if (line > end) {
857
+ sawAfter = segmentStart < data.length || consumed < totalSize;
858
+ break;
859
+ }
860
+ }
861
+ if (byteLimitReached || line > end) {
862
+ break;
863
+ }
864
+ if (line >= start && line <= end && available > segmentStart) {
865
+ const length = available - segmentStart;
866
+ const remaining = maxBytes - size;
867
+ const taken = Math.min(length, remaining);
868
+ if (taken > 0) {
869
+ chunks.push(data.subarray(segmentStart, segmentStart + taken));
870
+ size += taken;
871
+ lineStart ??= line;
872
+ }
873
+ if (taken < length) {
874
+ byteLimitReached = true;
875
+ stream.destroy();
876
+ break;
877
+ }
878
+ }
879
+ pending = data.subarray(available);
880
+ }
881
+ if (!byteLimitReached && line <= end && line >= start && pending.length > 0) {
882
+ const taken = Math.min(pending.length, maxBytes - size);
883
+ if (taken > 0) {
884
+ chunks.push(pending.subarray(0, taken));
885
+ lineStart ??= line;
886
+ }
887
+ byteLimitReached = taken < pending.length;
888
+ }
889
+ })(), timeout);
890
+ }
891
+ finally {
892
+ stream.destroy();
893
+ sftp.end();
894
+ }
895
+ const raw = Buffer.concat(chunks);
896
+ const decoded = decodeReadBuffer(raw, detected, binary, byteLimitReached);
897
+ if (decoded.read_bytes < raw.length) {
898
+ byteLimitReached = true;
899
+ }
900
+ // Metadata describes the decoded prefix, not the bytes scanned or discarded at the budget boundary.
901
+ let finalLineTerminated = false;
902
+ if (decoded.read_bytes > 0 && lineStart !== undefined) {
903
+ const width = detected.startsWith('utf16') ? 2 : 1;
904
+ let returnedLine = lineStart;
905
+ for (let index = 0; index < decoded.read_bytes; index += width) {
906
+ lineEnd = returnedLine;
907
+ finalLineTerminated =
908
+ width === 1
909
+ ? raw[index] === 10
910
+ : index + 1 < decoded.read_bytes &&
911
+ (detected === 'utf16be'
912
+ ? raw[index] === 0 && raw[index + 1] === 10
913
+ : raw[index] === 10 && raw[index + 1] === 0);
914
+ if (finalLineTerminated) {
915
+ ++returnedLine;
916
+ }
917
+ }
918
+ }
919
+ else {
920
+ lineStart = undefined;
921
+ }
922
+ const eof = !byteLimitReached && !sawAfter;
724
923
  return {
725
- content,
924
+ content: decoded.content,
925
+ content_base64: decoded.content_base64,
926
+ encoding: binary ? 'base64' : detected,
726
927
  size: totalSize,
727
928
  total_size: totalSize,
728
929
  read_offset: 0,
729
- read_bytes: readBytes,
930
+ read_bytes: decoded.read_bytes,
730
931
  sample_kind: 'line_range',
731
- truncated: byteLimitReached || sawAfter,
732
- line_start: actualStart || undefined,
733
- line_end: actualEnd || undefined,
932
+ truncated: byteLimitReached || !eof,
933
+ line_start: lineStart,
934
+ line_end: lineEnd,
734
935
  eof,
735
936
  byte_limit_reached: byteLimitReached,
736
- final_line_terminated: actualEnd === 0 ? undefined : finalLineTerminated,
937
+ final_line_terminated: lineEnd === undefined ? undefined : finalLineTerminated,
737
938
  };
738
939
  }
739
940
  /**
@@ -752,12 +953,11 @@ export async function readFile(alias, remotePath, options) {
752
953
  throw error;
753
954
  }
754
955
  if (readOptions.lineRange) {
755
- sftp.end();
756
- return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.timeout);
956
+ return readLineRange(sftp, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.encoding ?? 'auto', readOptions.binary === true, readOptions.timeout);
757
957
  }
758
958
  if (actualSize === 0) {
759
959
  sftp.end();
760
- return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full');
960
+ return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full', 0, readOptions.binary === true);
761
961
  }
762
962
  const requestedOffset = readOptions.tail
763
963
  ? Math.max(0, actualSize - readOptions.maxBytes)
@@ -772,7 +972,7 @@ export async function readFile(alias, remotePath, options) {
772
972
  : 'head';
773
973
  if (readSize === 0) {
774
974
  sftp.end();
775
- return emptyReadResult(actualSize, sampleKind, requestedOffset);
975
+ return emptyReadResult(actualSize, sampleKind, requestedOffset, readOptions.binary === true);
776
976
  }
777
977
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
778
978
  const chunks = [];
@@ -789,22 +989,39 @@ export async function readFile(alias, remotePath, options) {
789
989
  }
790
990
  try {
791
991
  const buffer = Buffer.concat(chunks);
992
+ const detected = detectReadEncoding(buffer, readOptions.encoding ?? 'auto');
792
993
  let contentStart = 0;
793
- if (readOptions.tail) {
994
+ if (!readOptions.binary && detected === 'utf8' && readOptions.tail && requestedOffset > 0) {
794
995
  while (contentStart < buffer.length && isUtf8ContinuationByte(buffer[contentStart])) {
795
996
  ++contentStart;
796
997
  }
797
998
  }
798
- else {
999
+ else if (!readOptions.binary && detected === 'utf8') {
799
1000
  ensureUtf8Boundary(buffer, 0, 'offset');
800
1001
  }
801
- const contentEnd = utf8SafeEnd(buffer, contentStart, buffer.length, remotePath, requestedOffset + buffer.length < actualSize);
802
- const contentBuffer = buffer.subarray(contentStart, contentEnd);
1002
+ else if (!readOptions.binary && detected.startsWith('utf16') && readOptions.tail) {
1003
+ contentStart = requestedOffset % 2;
1004
+ if (requestedOffset > 0 && contentStart + 2 <= buffer.length) {
1005
+ const firstUnit = detected === 'utf16be'
1006
+ ? buffer.readUInt16BE(contentStart)
1007
+ : buffer.readUInt16LE(contentStart);
1008
+ if (firstUnit >= 0xdc00 && firstUnit <= 0xdfff) {
1009
+ contentStart += 2;
1010
+ }
1011
+ }
1012
+ }
1013
+ if (!readOptions.binary && buffer.length > 0 && contentStart >= buffer.length) {
1014
+ throw new Error(`maxBytes is too small to read a complete ${detected} tail character`);
1015
+ }
1016
+ const decoded = decodeReadBuffer(buffer.subarray(contentStart), detected, readOptions.binary === true, requestedOffset + buffer.length < actualSize);
1017
+ const contentBuffer = buffer.subarray(contentStart, contentStart + decoded.read_bytes);
803
1018
  const actualReadOffset = requestedOffset + contentStart;
804
- const nextOffset = requestedOffset + contentEnd;
1019
+ const nextOffset = actualReadOffset + contentBuffer.length;
805
1020
  const remainingBytes = Math.max(0, actualSize - nextOffset);
806
1021
  resolve({
807
- content: contentBuffer.toString('utf-8'),
1022
+ content: decoded.content,
1023
+ content_base64: decoded.content_base64,
1024
+ encoding: readOptions.binary ? 'base64' : detected,
808
1025
  size: actualSize,
809
1026
  total_size: actualSize,
810
1027
  read_offset: actualReadOffset,
@@ -821,10 +1038,18 @@ export async function readFile(alias, remotePath, options) {
821
1038
  reject(processingError);
822
1039
  }
823
1040
  };
824
- const readStream = sftp.createReadStream(remotePath, {
825
- start: requestedOffset,
826
- end: requestedOffset + readSize - 1,
827
- });
1041
+ let readStream;
1042
+ try {
1043
+ readStream = sftp.createReadStream(remotePath, {
1044
+ start: requestedOffset,
1045
+ end: requestedOffset + readSize - 1,
1046
+ });
1047
+ }
1048
+ catch (error) {
1049
+ sftp.end();
1050
+ reject(error);
1051
+ return;
1052
+ }
828
1053
  readStream.on('data', (chunk) => {
829
1054
  chunks.push(chunk);
830
1055
  });
@@ -832,6 +1057,42 @@ export async function readFile(alias, remotePath, options) {
832
1057
  readStream.once('error', (error) => finish(error));
833
1058
  }), readOptions.timeout);
834
1059
  }
1060
+ export async function createEmptyRemoteFile(alias, remotePath, timeout) {
1061
+ const sftp = await getSftpWithinDeadline(alias, timeout);
1062
+ try {
1063
+ await withSftpDeadline(sftp, new Promise((resolve, reject) => {
1064
+ const stream = sftp.createWriteStream(remotePath, { flags: 'wx', mode: 0o600 });
1065
+ stream.once('error', reject);
1066
+ stream.once('close', resolve);
1067
+ stream.end();
1068
+ }), timeout);
1069
+ }
1070
+ finally {
1071
+ sftp.end();
1072
+ }
1073
+ }
1074
+ export async function prepareWindowsRemotePrivateFile(alias, remotePath, timeout, shellPath = remotePath) {
1075
+ await createEmptyRemoteFile(alias, remotePath, timeout);
1076
+ try {
1077
+ const acl = await sessionManager.exec(alias, encodedPowershell(windowsAclScript(shellPath, true)), {
1078
+ timeout,
1079
+ useLoginUser: true,
1080
+ maxOutputSize: 4096,
1081
+ });
1082
+ if (!acl.success || acl.stdout.trim() !== 'usable') {
1083
+ throw new Error('privacy_not_enforced_on_windows: remote temporary file ACL was not verified');
1084
+ }
1085
+ }
1086
+ catch (error) {
1087
+ try {
1088
+ await removeRemoteFile(alias, remotePath, timeout);
1089
+ }
1090
+ catch (cleanupError) {
1091
+ throw new AggregateError([error, cleanupError], 'privacy_not_enforced_on_windows: remote ACL check and cleanup failed', { cause: cleanupError });
1092
+ }
1093
+ throw error;
1094
+ }
1095
+ }
835
1096
  /**
836
1097
  * 写入远程文件
837
1098
  */
@@ -866,7 +1127,7 @@ function validateSftpEntryName(filename) {
866
1127
  /**
867
1128
  * 列出目录内容
868
1129
  */
869
- export async function listDir(alias, remotePath, showHidden = false, sharedSftp, timeout) {
1130
+ export async function listDir(alias, remotePath, showHidden = false, sharedSftp, timeout, style = 'posix') {
870
1131
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
871
1132
  const closeWhenDone = !sharedSftp;
872
1133
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
@@ -894,12 +1155,13 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp,
894
1155
  .filter((item) => showHidden || !item.filename.startsWith('.'))
895
1156
  .map((item) => ({
896
1157
  name: item.filename,
897
- path: path.posix.join(remotePath, item.filename),
1158
+ path: remoteJoin(style, remotePath, item.filename),
898
1159
  size: item.attrs.size,
899
1160
  isDirectory: (item.attrs.mode & S_IFMT) === S_IFDIR,
900
1161
  isFile: (item.attrs.mode & S_IFMT) === S_IFREG,
901
1162
  isSymlink: (item.attrs.mode & S_IFMT) === S_IFLNK,
902
- permissions: formatPermissions(item.attrs.mode),
1163
+ mode: extractFileMode(item.attrs.mode),
1164
+ permissions: formatFilePermissions(item.attrs.mode),
903
1165
  owner: item.attrs.uid,
904
1166
  group: item.attrs.gid,
905
1167
  mtime: new Date(item.attrs.mtime * 1000),
@@ -922,7 +1184,7 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp,
922
1184
  /**
923
1185
  * 获取文件信息
924
1186
  */
925
- export async function getFileInfo(alias, remotePath, timeout) {
1187
+ export async function getFileInfo(alias, remotePath, timeout, style = 'posix') {
926
1188
  const sftp = await getSftpWithinDeadline(alias, timeout);
927
1189
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
928
1190
  sftp.stat(remotePath, (err, stats) => {
@@ -932,13 +1194,14 @@ export async function getFileInfo(alias, remotePath, timeout) {
932
1194
  return;
933
1195
  }
934
1196
  resolve({
935
- name: path.posix.basename(remotePath),
1197
+ name: remotePathModule(style).basename(remotePath),
936
1198
  path: remotePath,
937
1199
  size: stats.size,
938
1200
  isDirectory: (stats.mode & S_IFMT) === S_IFDIR,
939
1201
  isFile: (stats.mode & S_IFMT) === S_IFREG,
940
1202
  isSymlink: (stats.mode & S_IFMT) === S_IFLNK,
941
- permissions: formatPermissions(stats.mode),
1203
+ mode: extractFileMode(stats.mode),
1204
+ permissions: formatFilePermissions(stats.mode),
942
1205
  owner: stats.uid,
943
1206
  group: stats.gid,
944
1207
  mtime: new Date(stats.mtime * 1000),
@@ -959,8 +1222,8 @@ function sftpMkdir(sftp, remotePath, timeout) {
959
1222
  });
960
1223
  }), timeout);
961
1224
  }
962
- async function ensureSftpDirectory(sftp, remotePath, timeout) {
963
- const normalizedPath = path.posix.normalize(remotePath);
1225
+ async function ensureSftpDirectory(sftp, remotePath, timeout, style = 'posix') {
1226
+ const normalizedPath = remoteNormalize(style, remotePath);
964
1227
  if (normalizedPath === '/' || normalizedPath === '.') {
965
1228
  return;
966
1229
  }
@@ -979,9 +1242,12 @@ async function ensureSftpDirectory(sftp, remotePath, timeout) {
979
1242
  }
980
1243
  return;
981
1244
  }
982
- const parent = path.posix.dirname(normalizedPath);
1245
+ const parent = remoteDirname(style, normalizedPath);
1246
+ if (style === 'sftp-posix' && /^\/\/[^/]+\/[^/]+\/?$/.test(normalizedPath) && parent !== normalizedPath) {
1247
+ throw new Error('SFTP UNC share root does not exist; refusing to create a network host path');
1248
+ }
983
1249
  if (parent !== normalizedPath) {
984
- await ensureSftpDirectory(sftp, parent, timeout);
1250
+ await ensureSftpDirectory(sftp, parent, timeout, style);
985
1251
  }
986
1252
  try {
987
1253
  await sftpMkdir(sftp, normalizedPath, timeout);
@@ -1002,12 +1268,12 @@ async function ensureSftpDirectory(sftp, remotePath, timeout) {
1002
1268
  /**
1003
1269
  * 创建目录
1004
1270
  */
1005
- export async function mkdir(alias, remotePath, recursive = false, sharedSftp, timeout) {
1271
+ export async function mkdir(alias, remotePath, recursive = false, sharedSftp, timeout, style = 'posix') {
1006
1272
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
1007
1273
  return withSftpDeadline(sftp, (async () => {
1008
1274
  try {
1009
1275
  if (recursive) {
1010
- await ensureSftpDirectory(sftp, remotePath, timeout);
1276
+ await ensureSftpDirectory(sftp, remotePath, timeout, style);
1011
1277
  }
1012
1278
  else {
1013
1279
  await sftpMkdir(sftp, remotePath, timeout);
@@ -1024,15 +1290,26 @@ export async function mkdir(alias, remotePath, recursive = false, sharedSftp, ti
1024
1290
  /**
1025
1291
  * 检查远程是否安装 rsync
1026
1292
  */
1027
- export async function checkRsync(alias, timeout = 10_000) {
1293
+ export async function checkRsync(alias, timeout = 10_000, executable = 'rsync', shell = 'posix') {
1028
1294
  const generation = getRsyncGeneration(alias);
1029
- const cached = rsyncCache.get(alias);
1295
+ const cacheKey = `${alias}\0${shell}\0${executable}`;
1296
+ const cached = rsyncCache.get(cacheKey);
1030
1297
  if (cached !== undefined && cached.expiresAt > Date.now()) {
1031
1298
  return cached.value;
1032
1299
  }
1033
1300
  const startedAt = Date.now();
1034
1301
  try {
1035
- const result = await sessionManager.exec(alias, 'command -v rsync', {
1302
+ if (/[\r\n\0]/.test(executable)) {
1303
+ throw new Error('Invalid rsync executable path');
1304
+ }
1305
+ const probeCommand = shell === 'posix'
1306
+ ? executable === 'rsync'
1307
+ ? 'command -v rsync'
1308
+ : `test -x ${escapeShellArg(executable)} && printf '%s\\n' ${escapeShellArg(executable)}`
1309
+ : shell === 'powershell'
1310
+ ? `(Get-Command -ErrorAction Stop -Name '${executable.replace(/'/g, "''")}').Source`
1311
+ : `where.exe "${executable.replace(/"/g, '""')}"`;
1312
+ const result = await sessionManager.exec(alias, probeCommand, {
1036
1313
  timeout,
1037
1314
  useLoginUser: true,
1038
1315
  maxOutputSize: 4096,
@@ -1055,7 +1332,7 @@ export async function checkRsync(alias, timeout = 10_000) {
1055
1332
  retryable: false,
1056
1333
  exitCode: result.exitCode,
1057
1334
  };
1058
- rsyncCache.set(alias, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1335
+ rsyncCache.set(cacheKey, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1059
1336
  return probe;
1060
1337
  }
1061
1338
  if (result.failureKind === 'timeout' || result.timedOut) {
@@ -1088,7 +1365,7 @@ export async function checkRsync(alias, timeout = 10_000) {
1088
1365
  retryable: false,
1089
1366
  exitCode: result.exitCode,
1090
1367
  };
1091
- rsyncCache.set(alias, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1368
+ rsyncCache.set(cacheKey, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1092
1369
  return probe;
1093
1370
  }
1094
1371
  return {
@@ -1111,6 +1388,57 @@ export async function checkRsync(alias, timeout = 10_000) {
1111
1388
  };
1112
1389
  }
1113
1390
  }
1391
+ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1392
+ const candidates = [];
1393
+ const style = options.remotePathStyle ?? sessionManager.getRemotePathStyle(alias);
1394
+ await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks === true, { files: 0, directories: 0, bytes: 0 }, 0, options.signal, '', style, (parent, names) => {
1395
+ if (names.length < 2) {
1396
+ return;
1397
+ }
1398
+ // ASCII folding only screens candidates. Windows performs the authoritative comparison.
1399
+ // Any Unicode name requires remote comparison against every sibling, including ASCII names.
1400
+ const hasUnicode = names.some((name) => [...name].some((char) => char.charCodeAt(0) > 0x7f));
1401
+ if (hasUnicode || new Set(names.map((name) => name.toLowerCase())).size !== names.length) {
1402
+ candidates.push({ parent, names });
1403
+ }
1404
+ });
1405
+ const deadline = Date.now() + (options.preflightTimeout ?? 10_000);
1406
+ for (const { parent, names } of candidates) {
1407
+ let collision;
1408
+ try {
1409
+ const timeout = deadline - Date.now();
1410
+ if (timeout <= 0) {
1411
+ throw new Error('name preflight timeout was exhausted');
1412
+ }
1413
+ const result = await sessionManager.exec(alias, encodedPowershell(windowsCaseSemanticsScript(remoteShellPath(parent, style), names)), { timeout, maxOutputSize: 65_536, useLoginUser: true, loadProfile: false });
1414
+ if (!result.success ||
1415
+ result.exitCode !== 0 ||
1416
+ result.timedOut ||
1417
+ result.stdoutTruncated ||
1418
+ result.stderrTruncated) {
1419
+ throw new Error(result.stderr || 'Windows case semantics query failed or returned truncated output');
1420
+ }
1421
+ const semantics = JSON.parse(result.stdout);
1422
+ if (typeof semantics?.caseSensitive !== 'boolean' ||
1423
+ !Object.hasOwn(semantics, 'collision') ||
1424
+ (semantics.collision !== null &&
1425
+ (!Array.isArray(semantics.collision) ||
1426
+ semantics.collision.length !== 2 ||
1427
+ semantics.collision[0] === semantics.collision[1] ||
1428
+ !semantics.collision.every((name) => typeof name === 'string' && names.includes(name)))) ||
1429
+ (semantics.caseSensitive && semantics.collision !== null)) {
1430
+ throw new Error('Windows case semantics query returned incomplete fields');
1431
+ }
1432
+ collision = semantics.collision;
1433
+ }
1434
+ catch (error) {
1435
+ throw new Error(`case_semantics_unverified: ${parent}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
1436
+ }
1437
+ if (collision) {
1438
+ throw new Error(`windows_filename_collision: ${parent}: ${collision.join(' / ')}`);
1439
+ }
1440
+ }
1441
+ }
1114
1442
  /**
1115
1443
  * 智能文件同步(根据连接能力选择 rsync 或 SFTP)
1116
1444
  *
@@ -1134,17 +1462,21 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
1134
1462
  sourceIsDirectory = source.stats.isDirectory();
1135
1463
  }
1136
1464
  else {
1137
- sourceIsDirectory = (await getFileInfo(alias, remotePath)).isDirectory;
1465
+ sourceIsDirectory = (await getFileInfo(alias, remotePath, undefined, options.remotePathStyle)).isDirectory;
1138
1466
  }
1139
1467
  if (sourceIsDirectory && options.recursive === false) {
1140
1468
  throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1141
1469
  }
1142
1470
  const capabilityStartedAt = Date.now();
1143
1471
  const rsyncGeneration = getRsyncGeneration(alias);
1472
+ if (direction === 'upload' && sourceIsDirectory && sessionManager.getRemotePlatform(alias) === 'windows') {
1473
+ await verifyWindowsUploadNames(alias, localPath, remotePath, options);
1474
+ assertCurrentRsyncGeneration(alias, rsyncGeneration);
1475
+ }
1144
1476
  const capability = sessionManager.getExternalTransferCapability(alias);
1145
1477
  const preflightTimeout = options.preflightTimeout ?? 10_000;
1146
1478
  const rsyncProbe = capability.rsyncEligible
1147
- ? await checkRsync(alias, preflightTimeout)
1479
+ ? await checkRsync(alias, preflightTimeout, capability.rsyncExecutable, capability.commandShell)
1148
1480
  : {
1149
1481
  available: false,
1150
1482
  status: 'skipped',
@@ -1153,7 +1485,11 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
1153
1485
  reason: capability.decisionReason,
1154
1486
  };
1155
1487
  assertCurrentRsyncGeneration(alias, rsyncGeneration);
1156
- const resolvedOptions = { ...options, sourceIsDirectory };
1488
+ const resolvedOptions = {
1489
+ ...options,
1490
+ sourceIsDirectory,
1491
+ remotePathStyle: options.remotePathStyle ?? capability.remotePathStyle ?? 'posix',
1492
+ };
1157
1493
  const capabilityDuration = Date.now() - capabilityStartedAt;
1158
1494
  const selectedTransport = capability.rsyncEligible && rsyncProbe?.available ? 'rsync' : 'sftp';
1159
1495
  const decisionReason = !capability.rsyncEligible
@@ -1249,6 +1585,18 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1249
1585
  // 构建 rsync argv(不用 shell=true,避免 username/host 含 shell 元字符时注入)
1250
1586
  // ProxyCommand=none 显式禁用 ssh-config 中可能定义的 ProxyCommand,防止外部命令注入
1251
1587
  const connectTimeout = options.connectTimeout ?? 30_000;
1588
+ const profile = capability.rsyncProfile ?? 'posix';
1589
+ const localRsyncPath = process.platform === 'win32' ? convertRsyncPath(localPath, profile) : localPath;
1590
+ const remoteRsyncPath = capability.commandShell && capability.commandShell !== 'posix'
1591
+ ? convertRsyncPath(remoteShellPath(remotePath, capability.remotePathStyle ?? 'win32'), profile).replace(/\\/g, '/')
1592
+ : remotePath;
1593
+ const childEnv = { ...process.env };
1594
+ if (capability.agent === 'none') {
1595
+ delete childEnv.SSH_AUTH_SOCK;
1596
+ }
1597
+ else if (capability.agent) {
1598
+ childEnv.SSH_AUTH_SOCK = capability.agent;
1599
+ }
1252
1600
  const sshOptions = [
1253
1601
  '-p',
1254
1602
  String(capability.port),
@@ -1261,13 +1609,36 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1261
1609
  '-o',
1262
1610
  'ProxyCommand=none',
1263
1611
  ];
1612
+ if (capability.agent === 'none') {
1613
+ sshOptions.push('-o', 'IdentityAgent=none');
1614
+ }
1264
1615
  if (capability.keyPath) {
1265
1616
  sshOptions.push('-i', capability.keyPath);
1266
1617
  }
1267
1618
  const destination = `${capability.username}@${capability.host}`;
1619
+ const executable = capability.rsyncExecutable;
1620
+ if (executable &&
1621
+ (/[\r\n\0]/.test(executable) || (capability.commandShell === 'cmd' && executable.includes('"')))) {
1622
+ throw new Error('Invalid remote rsync executable');
1623
+ }
1624
+ const remoteCommand = executable
1625
+ ? capability.commandShell === 'powershell'
1626
+ ? `& '${executable.replace(/'/g, "''")}'`
1627
+ : capability.commandShell === 'cmd'
1628
+ ? `"${executable}"`
1629
+ : escapeShellArg(executable)
1630
+ : 'rsync';
1268
1631
  assertCurrentRsyncGeneration(alias, generation);
1269
1632
  const connectStartedAt = Date.now();
1270
- const connectResult = await runLocalProcess('ssh', [...sshOptions, destination, 'true'], connectTimeout);
1633
+ const connectResult = await runLocalProcess('ssh', [
1634
+ ...sshOptions,
1635
+ destination,
1636
+ capability.commandShell === 'powershell'
1637
+ ? 'powershell.exe -NoProfile -Command exit 0'
1638
+ : capability.commandShell === 'cmd'
1639
+ ? 'cmd.exe /D /C exit 0'
1640
+ : 'true',
1641
+ ], connectTimeout, childEnv);
1271
1642
  const connectDuration = Date.now() - connectStartedAt;
1272
1643
  assertCurrentRsyncGeneration(alias, generation);
1273
1644
  if (connectResult.error || connectResult.status !== 0) {
@@ -1284,23 +1655,46 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1284
1655
  : fallback.output,
1285
1656
  };
1286
1657
  }
1287
- const sshCmd = ['ssh', ...sshOptions].map(quoteRsyncSshArg).join(' ');
1288
- const rsyncLocalPath = options.sourceIsDirectory && direction === 'upload' && !localPath.endsWith(path.sep)
1289
- ? `${localPath}${path.sep}`
1290
- : localPath;
1291
- const rsyncRemotePath = options.sourceIsDirectory && direction === 'download' && !remotePath.endsWith('/')
1292
- ? `${remotePath}/`
1293
- : remotePath;
1658
+ if (capability.commandShell && capability.commandShell !== 'posix') {
1659
+ const remoteProbe = await runLocalProcess('ssh', [...sshOptions, destination, `${remoteCommand} --version`], connectTimeout, childEnv);
1660
+ assertCurrentRsyncGeneration(alias, generation);
1661
+ if (remoteProbe.error || remoteProbe.status !== 0) {
1662
+ const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1663
+ const reason = remoteProbe.stderr.trim() || remoteProbe.error?.message || `exit code ${remoteProbe.status}`;
1664
+ return {
1665
+ ...fallback,
1666
+ connectDuration,
1667
+ connectStatus: 'completed',
1668
+ fallbackReason: remoteProbe.timedOut
1669
+ ? 'remote_rsync_command_timeout'
1670
+ : 'remote_rsync_command_unavailable',
1671
+ output: `Remote rsync command preflight failed: ${reason}; ${fallback.output ?? ''}`.trim(),
1672
+ };
1673
+ }
1674
+ }
1675
+ const sshCmd = ['ssh', ...sshOptions].map((arg) => quoteRsyncSshArg(arg, profile)).join(' ');
1676
+ const rsyncLocalPath = options.sourceIsDirectory && direction === 'upload' && !localRsyncPath.endsWith('/')
1677
+ ? `${localRsyncPath}/`
1678
+ : localRsyncPath;
1679
+ const rsyncRemotePath = options.sourceIsDirectory && direction === 'download' && !remoteRsyncPath.endsWith('/')
1680
+ ? `${remoteRsyncPath}/`
1681
+ : remoteRsyncPath;
1294
1682
  // remoteSpec 作为单独 argv 元素,不经 shell 解析
1295
1683
  const remoteSpec = `${destination}:${rsyncRemotePath}`;
1684
+ if (executable) {
1685
+ args.push(`--rsync-path=${remoteCommand}`);
1686
+ }
1687
+ if (capability.commandShell !== 'posix' && capability.commandShell !== undefined) {
1688
+ args.push('--protect-args');
1689
+ }
1296
1690
  // 在 path 参数前插 `--`,明确剩余为路径而非选项(双重保险)
1297
1691
  const rsyncArgs = direction === 'upload'
1298
1692
  ? [...args, '-e', sshCmd, '--', rsyncLocalPath, remoteSpec]
1299
- : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
1693
+ : [...args, '-e', sshCmd, '--', remoteSpec, localRsyncPath];
1300
1694
  try {
1301
1695
  assertCurrentRsyncGeneration(alias, generation);
1302
1696
  const operationTimeout = options.operationTimeout ?? 600_000;
1303
- const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout);
1697
+ const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout, childEnv);
1304
1698
  if (!isCurrentRsyncGeneration(alias, generation)) {
1305
1699
  return {
1306
1700
  success: false,
@@ -1331,15 +1725,15 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1331
1725
  output: `rsync ${reason}${stderr ? ` | stderr: ${stderr}` : ''}; remote transfer state is unknown`,
1332
1726
  };
1333
1727
  }
1334
- const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1335
- const warning = `rsync 失败原因: ${reason}${stderr ? ` | stderr: ${stderr}` : ''} | 已 fallback 到 SFTP(性能可能较差)`;
1336
- console.warn(`[mcp-ssh] ${warning}`);
1337
1728
  return {
1338
- ...fallback,
1729
+ success: false,
1730
+ method: 'rsync',
1339
1731
  connectDuration,
1340
1732
  connectStatus: 'completed',
1733
+ operationStatus: 'unknown',
1734
+ retryable: true,
1341
1735
  fallbackReason: 'rsync_operation_failed',
1342
- output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
1736
+ output: `rsync failed: ${reason}${stderr ? ` | stderr: ${stderr}` : ''}; remote transfer state is unknown`,
1343
1737
  };
1344
1738
  }
1345
1739
  const output = result.stdout;
@@ -1369,16 +1763,15 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1369
1763
  if (!isCurrentRsyncGeneration(alias, generation)) {
1370
1764
  throw e;
1371
1765
  }
1372
- // rsync 启动异常发生在传输进程建立前,可安全改用 SFTP
1373
- const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1374
- const warning = `rsync 异常: ${e instanceof Error ? e.message : String(e)} | 已 fallback 到 SFTP(性能可能较差)`;
1375
- console.warn(`[mcp-ssh] ${warning}`);
1376
1766
  return {
1377
- ...fallback,
1767
+ success: false,
1768
+ method: 'rsync',
1378
1769
  connectDuration,
1379
1770
  connectStatus: 'completed',
1771
+ operationStatus: 'unknown',
1772
+ retryable: true,
1380
1773
  fallbackReason: 'rsync_execution_error',
1381
- output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
1774
+ output: `rsync execution failed: ${e instanceof Error ? e.message : String(e)}; remote transfer state is unknown`,
1382
1775
  };
1383
1776
  }
1384
1777
  }
@@ -1551,14 +1944,14 @@ async function buildSingleFileVerification(alias, localPath, remotePath, directi
1551
1944
  };
1552
1945
  }
1553
1946
  }
1554
- async function resolveSftpUploadFileTarget(alias, localPath, remotePath) {
1555
- if (remotePath.endsWith('/')) {
1556
- return path.posix.join(remotePath, path.basename(localPath));
1947
+ async function resolveSftpUploadFileTarget(alias, localPath, remotePath, style = 'posix') {
1948
+ if (remotePath.endsWith('/') || remotePath.endsWith('\\')) {
1949
+ return remoteJoin(style, remotePath, path.basename(localPath));
1557
1950
  }
1558
1951
  try {
1559
1952
  const info = await getFileInfo(alias, remotePath);
1560
1953
  if (info.isDirectory) {
1561
- return path.posix.join(remotePath, path.basename(localPath));
1954
+ return remoteJoin(style, remotePath, path.basename(localPath));
1562
1955
  }
1563
1956
  }
1564
1957
  catch (error) {
@@ -1569,13 +1962,13 @@ async function resolveSftpUploadFileTarget(alias, localPath, remotePath) {
1569
1962
  }
1570
1963
  return remotePath;
1571
1964
  }
1572
- function resolveSftpDownloadFileTarget(remotePath, localPath) {
1965
+ function resolveSftpDownloadFileTarget(remotePath, localPath, style = 'posix') {
1573
1966
  if (localPath.endsWith(path.sep)) {
1574
1967
  fs.mkdirSync(localPath, { recursive: true });
1575
- return path.join(localPath, path.posix.basename(remotePath));
1968
+ return path.join(localPath, remotePathModule(style).basename(remotePath));
1576
1969
  }
1577
1970
  if (fs.existsSync(localPath) && fs.statSync(localPath).isDirectory()) {
1578
- return path.join(localPath, path.posix.basename(remotePath));
1971
+ return path.join(localPath, remotePathModule(style).basename(remotePath));
1579
1972
  }
1580
1973
  return localPath;
1581
1974
  }
@@ -1666,10 +2059,10 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1666
2059
  };
1667
2060
  }
1668
2061
  if (stats.isDirectory()) {
1669
- const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal);
2062
+ const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal, '', options.remotePathStyle);
1670
2063
  return buildDirectorySyncResult(result, warnings);
1671
2064
  }
1672
- const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath);
2065
+ const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath, options.remotePathStyle);
1673
2066
  const existed = await remoteExists(alias, targetRemotePath);
1674
2067
  const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal, options.followSymlinks === true);
1675
2068
  return {
@@ -1678,7 +2071,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1678
2071
  };
1679
2072
  }
1680
2073
  // download
1681
- const info = await getFileInfo(alias, remotePath);
2074
+ const info = await getFileInfo(alias, remotePath, undefined, options.remotePathStyle);
1682
2075
  if (info.isDirectory && options.recursive === false) {
1683
2076
  return {
1684
2077
  success: false,
@@ -1693,10 +2086,10 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1693
2086
  files: 0,
1694
2087
  directories: 0,
1695
2088
  bytes: 0,
1696
- }, 0, options.signal);
2089
+ }, 0, options.signal, '', options.remotePathStyle);
1697
2090
  return buildDirectorySyncResult(result, warnings);
1698
2091
  }
1699
- const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath);
2092
+ const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath, options.remotePathStyle);
1700
2093
  const existed = fs.existsSync(targetLocalPath);
1701
2094
  const { size } = await downloadFile(alias, remotePath, targetLocalPath, undefined, undefined, options.signal);
1702
2095
  return {
@@ -1728,12 +2121,12 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1728
2121
  /**
1729
2122
  * 递归上传目录
1730
2123
  */
1731
- async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '') {
2124
+ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', inspectNames) {
1732
2125
  throwIfAborted(signal);
1733
2126
  const accumulator = new DirectoryTransferAccumulator();
1734
2127
  recordSftpDirectory(traversal, depth, localPath);
1735
- const ownSftp = !sharedSftp;
1736
- const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
2128
+ const ownSftp = !sharedSftp && !inspectNames;
2129
+ const sftp = inspectNames ? undefined : (sharedSftp ?? (await getSftpWithinDeadline(alias)));
1737
2130
  const activeDirectories = (traversal.activeDirectories ??= new Set());
1738
2131
  const realPath = fs.realpathSync(localPath);
1739
2132
  if (activeDirectories.has(realPath)) {
@@ -1746,7 +2139,9 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1746
2139
  activeDirectories.add(realPath);
1747
2140
  try {
1748
2141
  validateLocalPathAgainstAllowList(localPath);
1749
- await mkdir(alias, remotePath, true, sftp);
2142
+ if (!inspectNames) {
2143
+ await mkdir(alias, remotePath, true, sftp, undefined, style);
2144
+ }
1750
2145
  throwIfAborted(signal);
1751
2146
  const items = fs.readdirSync(localPath);
1752
2147
  // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
@@ -1760,11 +2155,17 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1760
2155
  const itemLocalPath = path.join(localPath, item);
1761
2156
  const stats = followSymlinks ? fs.statSync(itemLocalPath) : fs.lstatSync(itemLocalPath);
1762
2157
  if (!followSymlinks && stats.isSymbolicLink()) {
1763
- console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
2158
+ if (!inspectNames) {
2159
+ console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
2160
+ }
1764
2161
  accumulator.addSkippedSymlink();
1765
2162
  continue;
1766
2163
  }
1767
2164
  if (stats.isDirectory()) {
2165
+ if (activeDirectories.has(fs.realpathSync(itemLocalPath))) {
2166
+ accumulator.addSkippedSymlink();
2167
+ continue;
2168
+ }
1768
2169
  subDirItems.push(item);
1769
2170
  }
1770
2171
  else if (stats.isFile()) {
@@ -1775,25 +2176,30 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1775
2176
  accumulator.addSkippedUnsupported(itemRelativePath);
1776
2177
  }
1777
2178
  }
1778
- // 文件并发上传
1779
- await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
1780
- const itemLocalPath = path.join(localPath, name);
1781
- const itemRemotePath = path.posix.join(remotePath, name);
1782
- const existed = await sftpExists(sftp, itemRemotePath);
1783
- try {
1784
- await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal, followSymlinks);
1785
- accumulator.addFile(stats.size, existed);
1786
- }
1787
- catch (error) {
1788
- accumulator.addFailed();
1789
- throw error;
1790
- }
1791
- });
2179
+ if (inspectNames) {
2180
+ inspectNames(remotePath, [...subDirItems, ...fileItems.map(({ name }) => name)]);
2181
+ }
2182
+ else {
2183
+ // 文件并发上传
2184
+ await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
2185
+ const itemLocalPath = path.join(localPath, name);
2186
+ const itemRemotePath = remoteJoin(style, remotePath, name);
2187
+ const existed = await sftpExists(sftp, itemRemotePath);
2188
+ try {
2189
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal, followSymlinks);
2190
+ accumulator.addFile(stats.size, existed);
2191
+ }
2192
+ catch (error) {
2193
+ accumulator.addFailed();
2194
+ throw error;
2195
+ }
2196
+ });
2197
+ }
1792
2198
  // 子目录串行递归
1793
2199
  for (const item of subDirItems) {
1794
2200
  const itemLocalPath = path.join(localPath, item);
1795
- const itemRemotePath = path.posix.join(remotePath, item);
1796
- const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item);
2201
+ const itemRemotePath = remoteJoin(style, remotePath, item);
2202
+ const result = await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item, style, inspectNames);
1797
2203
  accumulator.merge(result);
1798
2204
  }
1799
2205
  }
@@ -1808,18 +2214,42 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1808
2214
  /**
1809
2215
  * 递归下载目录
1810
2216
  */
1811
- async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '') {
2217
+ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix') {
1812
2218
  throwIfAborted(signal);
1813
2219
  const accumulator = new DirectoryTransferAccumulator();
1814
2220
  recordSftpDirectory(traversal, depth, remotePath);
1815
2221
  const ownSftp = !sharedSftp;
1816
2222
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
1817
2223
  try {
2224
+ const items = await listDir(alias, remotePath, true, sftp, undefined, style);
2225
+ throwIfAborted(signal);
2226
+ if (process.platform === 'win32') {
2227
+ const localNames = new Map((fs.existsSync(localPath) ? fs.readdirSync(localPath) : []).map((name) => [
2228
+ name.normalize('NFC').toLowerCase(),
2229
+ name,
2230
+ ]));
2231
+ const remoteNames = new Set();
2232
+ for (const item of items) {
2233
+ const relativeName = relativeBase ? `${relativeBase}/${item.name}` : item.name;
2234
+ if (matchesDirectoryExclude(relativeName, exclude) || (!item.isDirectory && !item.isFile)) {
2235
+ continue;
2236
+ }
2237
+ if (/[<>:"/\\|?*]/.test(item.name) ||
2238
+ [...item.name].some((char) => char.charCodeAt(0) < 32) ||
2239
+ /[. ]$/.test(item.name) ||
2240
+ /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i.test(item.name)) {
2241
+ throw new Error(`Remote entry cannot be represented as a Windows filename: ${relativeName}`);
2242
+ }
2243
+ const key = item.name.normalize('NFC').toLowerCase();
2244
+ if (remoteNames.has(key) || (localNames.has(key) && localNames.get(key) !== item.name)) {
2245
+ throw new Error(`Windows local filename collision at ${relativeName}`);
2246
+ }
2247
+ remoteNames.add(key);
2248
+ }
2249
+ }
1818
2250
  if (!fs.existsSync(localPath)) {
1819
2251
  fs.mkdirSync(localPath, { recursive: true });
1820
2252
  }
1821
- const items = await listDir(alias, remotePath, true, sftp);
1822
- throwIfAborted(signal);
1823
2253
  // 分类:文件并发下载,目录串行递归
1824
2254
  const fileItems = [];
1825
2255
  const dirItems = [];
@@ -1857,7 +2287,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1857
2287
  });
1858
2288
  for (const item of dirItems) {
1859
2289
  const itemLocalPath = path.join(localPath, item.name);
1860
- const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name);
2290
+ const result = await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name, style);
1861
2291
  accumulator.merge(result);
1862
2292
  }
1863
2293
  for (const item of symlinkItems) {
@@ -1872,22 +2302,3 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1872
2302
  }
1873
2303
  return accumulator.toResult();
1874
2304
  }
1875
- /**
1876
- * 格式化权限字符串
1877
- */
1878
- function formatPermissions(mode) {
1879
- const fileType = mode & S_IFMT;
1880
- const type = fileType === S_IFDIR ? 'd' : fileType === S_IFLNK ? 'l' : fileType === S_IFREG ? '-' : '?';
1881
- const perms = [
1882
- mode & 0o400 ? 'r' : '-',
1883
- mode & 0o200 ? 'w' : '-',
1884
- mode & 0o100 ? 'x' : '-',
1885
- mode & 0o040 ? 'r' : '-',
1886
- mode & 0o020 ? 'w' : '-',
1887
- mode & 0o010 ? 'x' : '-',
1888
- mode & 0o004 ? 'r' : '-',
1889
- mode & 0o002 ? 'w' : '-',
1890
- mode & 0o001 ? 'x' : '-',
1891
- ];
1892
- return type + perms.join('');
1893
- }