@pyrokine/mcp-ssh 2.4.3 → 3.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,16 +2,19 @@
2
2
  * SSH File Operations - 文件操作
3
3
  */
4
4
  import { spawn } from 'child_process';
5
+ import { OpenSshError } from './openssh.js';
5
6
  import { createHash, randomBytes } from 'crypto';
6
7
  import * as fs from 'fs';
7
8
  import * as os from 'os';
8
9
  import * as path from 'path';
9
- import { StringDecoder } from 'string_decoder';
10
+ import { checkWindowsAcl, windowsAclScript } from './windows-acl.js';
10
11
  import { matchesDirectoryExclude } from './directory-verification.js';
12
+ import { extractFileMode, FILE_CREATE_MODE_MASK, formatFileMode, formatFilePermissions } from './file-mode.js';
11
13
  import { sessionManager } from './session-manager.js';
12
14
  import { SftpOperationTimeoutError, withSftpOperationTimeout } from './sftp-timeout.js';
13
15
  import { escapeShellArg, expandTilde } from './tools/utils.js';
14
- import { ensureUtf8Boundary, isUtf8ContinuationByte, utf8SafeEnd } from './utf8.js';
16
+ import { encodedPowershell, remoteDirname, remoteJoin, remoteNormalize, remotePathModule, remoteShellPath, windowsCaseSemanticsScript, } from './remote-platform.js';
17
+ import { ensureUtf8Boundary, isUtf8ContinuationByte } from './utf8.js';
15
18
  // 文件类型 mode 常量
16
19
  const S_IFMT = 0o170000; // 文件类型位掩码
17
20
  const S_IFDIR = 0o40000;
@@ -29,18 +32,38 @@ function appendLimitedOutput(current, chunk) {
29
32
  }
30
33
  return (current + chunk).slice(0, LOCAL_PROCESS_OUTPUT_LIMIT);
31
34
  }
32
- function runLocalProcess(command, args, timeout) {
35
+ function runLocalProcess(command, args, timeout, env, connection) {
33
36
  return new Promise((resolve) => {
34
37
  let stdout = '';
35
38
  let stderr = '';
36
39
  let settled = false;
37
40
  let timedOut = false;
38
41
  let killTimer;
39
- const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
42
+ connection?.assertCurrent();
43
+ const child = spawn(command, args, {
44
+ stdio: ['ignore', 'pipe', 'pipe'],
45
+ env: env ?? process.env,
46
+ windowsHide: true,
47
+ detached: connection !== undefined,
48
+ });
49
+ connection?.trackProcess(child, true);
50
+ const kill = (signal) => {
51
+ if (connection && child.pid) {
52
+ try {
53
+ process.kill(-child.pid, signal);
54
+ }
55
+ catch (error) {
56
+ if (error.code !== 'ESRCH')
57
+ console.error('Local process cleanup failed:', error);
58
+ }
59
+ }
60
+ else
61
+ child.kill(signal);
62
+ };
40
63
  const timer = setTimeout(() => {
41
64
  timedOut = true;
42
- child.kill('SIGTERM');
43
- killTimer = setTimeout(() => child.kill('SIGKILL'), 5000);
65
+ kill('SIGTERM');
66
+ killTimer = setTimeout(() => kill('SIGKILL'), 5000);
44
67
  }, timeout);
45
68
  child.stdout.on('data', (chunk) => {
46
69
  stdout = appendLimitedOutput(stdout, chunk.toString('utf-8'));
@@ -94,7 +117,11 @@ export function clearRsyncCache(alias) {
94
117
  ++rsyncGlobalGeneration;
95
118
  }
96
119
  else {
97
- rsyncCache.delete(alias);
120
+ for (const key of rsyncCache.keys()) {
121
+ if (key.startsWith(`${alias}\0`)) {
122
+ rsyncCache.delete(key);
123
+ }
124
+ }
98
125
  rsyncAliasGenerations.set(alias, (rsyncAliasGenerations.get(alias) ?? 0) + 1);
99
126
  }
100
127
  }
@@ -148,18 +175,29 @@ async function runWithConcurrency(items, limit, worker) {
148
175
  }
149
176
  const it = items[Symbol.iterator]();
150
177
  const runners = [];
178
+ let failed = false;
151
179
  for (let i = 0; i < Math.min(limit, items.length); i++) {
152
180
  runners.push((async () => {
153
- while (true) {
181
+ while (!failed) {
154
182
  const next = it.next();
155
183
  if (next.done) {
156
184
  return;
157
185
  }
158
- await worker(next.value);
186
+ try {
187
+ await worker(next.value);
188
+ }
189
+ catch (error) {
190
+ failed = true;
191
+ throw error;
192
+ }
159
193
  }
160
194
  })());
161
195
  }
162
- await Promise.all(runners);
196
+ const settled = await Promise.allSettled(runners);
197
+ const failure = settled.find((result) => result.status === 'rejected');
198
+ if (failure?.status === 'rejected') {
199
+ throw failure.reason;
200
+ }
163
201
  }
164
202
  /**
165
203
  * 校验本地路径是否在 SSH_MCP_FILE_OPS_ALLOW_DIRS 白名单内
@@ -170,8 +208,26 @@ async function runWithConcurrency(items, limit, worker) {
170
208
  * 格式:path.delimiter 分隔的绝对路径列表(POSIX `:`,Windows `;`),如 `/tmp:/home/user/work`
171
209
  * 安全性:路径会通过 fs.realpathSync 解析 symlink,防止 symlink 逃出白名单
172
210
  */
173
- function quoteRsyncSshArg(value) {
174
- return escapeShellArg(String(value));
211
+ export function convertRsyncPath(value, profile) {
212
+ if (profile === 'native-win32' || profile === 'posix') {
213
+ return value;
214
+ }
215
+ const drive = /^([a-zA-Z]):[\\/](.*)$/.exec(value);
216
+ if (drive) {
217
+ const prefix = profile === 'cygwin' ? '/cygdrive/' : '/';
218
+ return `${prefix}${drive[1].toLowerCase()}/${drive[2].replace(/\\/g, '/')}`;
219
+ }
220
+ if (value.startsWith('\\\\')) {
221
+ return `//${value.slice(2).replace(/\\/g, '/')}`;
222
+ }
223
+ return value.replace(/\\/g, '/');
224
+ }
225
+ export function quoteRsyncSshArg(value, profile = 'posix') {
226
+ const text = String(value);
227
+ if (/[\r\n\0]/.test(text)) {
228
+ throw new Error('rsync SSH argument contains a newline or NUL');
229
+ }
230
+ return profile === 'posix' ? escapeShellArg(text) : `"${text.replace(/([\\"])/g, '\\$1')}"`;
175
231
  }
176
232
  function configuredAllowDirectories() {
177
233
  const allowEnv = process.env.SSH_MCP_FILE_OPS_ALLOW_DIRS;
@@ -280,7 +336,8 @@ export function probeLocalPath(localPath, followSymlinks = false) {
280
336
  expandedPath: expanded,
281
337
  resolvedPath,
282
338
  size: stats.size,
283
- mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
339
+ mode: formatFileMode(stats.mode),
340
+ modeValue: extractFileMode(stats.mode),
284
341
  mtimeMs: Math.round(stats.mtimeMs),
285
342
  isSymlink: linkStats.isSymbolicLink(),
286
343
  isDirectory: stats.isDirectory(),
@@ -347,12 +404,16 @@ async function remoteExists(alias, remotePath) {
347
404
  sftp.end();
348
405
  }
349
406
  }
350
- export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
351
- const sftp = await getSftpWithinDeadline(alias);
407
+ export async function hashRemoteFileDigest(alias, remotePath, algorithm, timeout, limits) {
408
+ const connection = sessionManager.getOpenSshConnection(alias);
409
+ if (connection)
410
+ return connection.hashFile(remotePath, algorithm, timeout ?? 600_000, limits?.maxBytes, limits?.expectedSize);
411
+ const sftp = await getSftpWithinDeadline(alias, timeout);
352
412
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
353
413
  const hash = createHash(algorithm);
354
414
  const stream = sftp.createReadStream(remotePath);
355
415
  let settled = false;
416
+ let bytes = 0;
356
417
  const finish = (error) => {
357
418
  if (settled) {
358
419
  return;
@@ -366,10 +427,35 @@ export async function hashRemoteFileDigest(alias, remotePath, algorithm) {
366
427
  resolve(hash.digest('hex'));
367
428
  }
368
429
  };
369
- stream.on('data', (chunk) => hash.update(chunk));
430
+ stream.on('data', (chunk) => {
431
+ if (settled)
432
+ return;
433
+ bytes += chunk.length;
434
+ if (limits && (bytes > limits.maxBytes || bytes > limits.expectedSize)) {
435
+ stream.destroy();
436
+ finish(new Error('Remote file grew or exceeded the verification byte budget'));
437
+ }
438
+ else
439
+ hash.update(chunk);
440
+ });
370
441
  stream.once('error', finish);
371
- stream.once('end', () => finish());
372
- }));
442
+ stream.once('end', () => finish(limits && bytes !== limits.expectedSize
443
+ ? new Error('Remote file changed during verification')
444
+ : undefined));
445
+ }), timeout);
446
+ }
447
+ export async function atomicReplaceCapability(alias, timeout) {
448
+ const sftp = await getSftpWithinDeadline(alias, timeout);
449
+ try {
450
+ // ssh2 checks this negotiated extension before sending ext_openssh_rename.
451
+ const extensions = sftp._extensions;
452
+ return extensions?.['posix-rename@openssh.com'] === '1'
453
+ ? { atomicReplaceSupported: true }
454
+ : { atomicReplaceSupported: false, reason: 'posix-rename@openssh.com was not negotiated' };
455
+ }
456
+ finally {
457
+ sftp.end();
458
+ }
373
459
  }
374
460
  export class RemoteRenameNotStartedError extends Error {
375
461
  constructor(message) {
@@ -403,8 +489,8 @@ export async function renameRemoteFile(alias, sourcePath, targetPath, replaceExi
403
489
  }
404
490
  }), timeout);
405
491
  }
406
- export async function removeRemoteFile(alias, remotePath) {
407
- const sftp = await getSftpWithinDeadline(alias);
492
+ export async function removeRemoteFile(alias, remotePath, timeout) {
493
+ const sftp = await getSftpWithinDeadline(alias, timeout);
408
494
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
409
495
  sftp.unlink(remotePath, (error) => {
410
496
  sftp.end();
@@ -415,7 +501,7 @@ export async function removeRemoteFile(alias, remotePath) {
415
501
  resolve();
416
502
  }
417
503
  });
418
- }));
504
+ }), timeout);
419
505
  }
420
506
  /**
421
507
  * 带进度追踪的流传输
@@ -524,7 +610,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
524
610
  }
525
611
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
526
612
  const totalSize = stats.size;
527
- const safeCreateMode = (createMode ?? stats.mode) & 0o777;
613
+ const safeCreateMode = (createMode ?? stats.mode) & FILE_CREATE_MODE_MASK;
528
614
  const writeStream = sftp.createWriteStream(remotePath, { mode: safeCreateMode, flags: exclusive ? 'wx' : 'w' });
529
615
  let remoteCreated = false;
530
616
  writeStream.once('open', () => {
@@ -532,7 +618,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
532
618
  });
533
619
  try {
534
620
  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') };
621
+ return { ...result, createMode: formatFileMode(safeCreateMode) };
536
622
  }
537
623
  catch (error) {
538
624
  throw new UploadFileError(error instanceof Error ? error.message : String(error), remoteCreated, {
@@ -540,6 +626,22 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
540
626
  });
541
627
  }
542
628
  }
629
+ async function existingDownloadTargetMode(localPath) {
630
+ let stats;
631
+ try {
632
+ stats = await fs.promises.lstat(localPath);
633
+ }
634
+ catch (error) {
635
+ if (isLocalMissingError(error)) {
636
+ return undefined;
637
+ }
638
+ throw error;
639
+ }
640
+ if (!stats.isFile()) {
641
+ throw new Error(`Refusing to replace a non-regular local target: ${localPath}`);
642
+ }
643
+ return stats.mode & FILE_CREATE_MODE_MASK;
644
+ }
543
645
  async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, closeSftpOnFailure, timeout) {
544
646
  let readStream;
545
647
  try {
@@ -547,11 +649,21 @@ async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath
547
649
  if (!fs.existsSync(localDir)) {
548
650
  fs.mkdirSync(localDir, { recursive: true });
549
651
  }
652
+ if (process.platform === 'win32') {
653
+ const handle = await fs.promises.open(temporaryPath, 'wx', 0o600);
654
+ await handle.close();
655
+ if (checkWindowsAcl(temporaryPath, true) !== 'key_path_usable') {
656
+ throw new Error('privacy_not_enforced_on_windows: temporary download file ACL could not be verified');
657
+ }
658
+ }
550
659
  readStream = sftp.createReadStream(remotePath);
551
660
  return {
552
661
  totalSize,
553
662
  readStream,
554
- writeStream: fs.createWriteStream(temporaryPath, { flags: 'wx' }),
663
+ writeStream: fs.createWriteStream(temporaryPath, {
664
+ flags: process.platform === 'win32' ? 'r+' : 'wx',
665
+ mode: 0o600,
666
+ }),
555
667
  };
556
668
  }
557
669
  catch (error) {
@@ -575,12 +687,16 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
575
687
  throwIfAborted(signal);
576
688
  localPath = expandTilde(localPath);
577
689
  validateLocalPathAgainstAllowList(localPath);
690
+ const preservedMode = await existingDownloadTargetMode(localPath);
578
691
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
579
692
  const localDir = path.dirname(localPath);
580
693
  const temporaryPath = path.join(localDir, `.${path.basename(localPath)}.mcp-tmp-${process.pid}-${randomBytes(8).toString('hex')}`);
581
694
  try {
582
695
  const { totalSize, readStream, writeStream } = await prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, !sharedSftp, timeout);
583
696
  const result = await withSftpDeadline(sftp, pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), timeout);
697
+ if (process.platform !== 'win32') {
698
+ await fs.promises.chmod(temporaryPath, preservedMode ?? 0o600);
699
+ }
584
700
  await fs.promises.rename(temporaryPath, localPath);
585
701
  return { ...result, atomic: true };
586
702
  }
@@ -632,10 +748,24 @@ function validateReadFileOptions(options) {
632
748
  if (selectors.length > 1) {
633
749
  throw new Error('offset、tail、lineRange 只能同时指定一个');
634
750
  }
751
+ if (options.lineRange !== undefined) {
752
+ parseLineRange(options.lineRange);
753
+ }
754
+ if (!options.binary &&
755
+ options.offset !== undefined &&
756
+ options.encoding?.startsWith('utf16') &&
757
+ options.offset % 2 !== 0) {
758
+ throw new Error('UTF-16 offset must point to a complete code unit boundary');
759
+ }
760
+ if (!options.binary && options.encoding === 'gbk' && (options.offset !== undefined || options.tail)) {
761
+ throw new Error('GBK byte offsets cannot prove character boundaries; use lineRange or binary=true');
762
+ }
635
763
  }
636
- function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
764
+ function emptyReadResult(totalSize, sampleKind, readOffset = 0, binary = false) {
637
765
  return {
638
766
  content: '',
767
+ content_base64: binary ? '' : undefined,
768
+ encoding: binary ? 'base64' : undefined,
639
769
  size: totalSize,
640
770
  total_size: totalSize,
641
771
  read_offset: readOffset,
@@ -645,95 +775,211 @@ function emptyReadResult(totalSize, sampleKind, readOffset = 0) {
645
775
  truncated: readOffset < totalSize,
646
776
  };
647
777
  }
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) {
778
+ function detectReadEncoding(firstBytes, requested) {
779
+ if (requested !== 'auto') {
780
+ return requested;
781
+ }
782
+ if (firstBytes[0] === 0xff && firstBytes[1] === 0xfe) {
783
+ return 'utf16le';
784
+ }
785
+ if (firstBytes[0] === 0xfe && firstBytes[1] === 0xff) {
786
+ return 'utf16be';
787
+ }
788
+ return 'utf8';
789
+ }
790
+ function decodeReadBuffer(bytes, encoding, binary, budgetTruncated, atFileStart) {
791
+ if (binary) {
792
+ return { content: bytes.toString('base64'), content_base64: bytes.toString('base64'), read_bytes: bytes.length };
793
+ }
794
+ const label = encoding === 'utf8' ? 'utf-8' : encoding === 'gbk' ? 'gbk' : encoding === 'utf16le' ? 'utf-16le' : 'utf-16be';
795
+ const invalid = () => new Error(`Invalid ${encoding} sequence or offset is not a character boundary`);
796
+ const decoderOptions = { fatal: true, ignoreBOM: !atFileStart };
797
+ const decoder = new TextDecoder(label, decoderOptions);
798
+ let content;
799
+ try {
800
+ // Streaming validation rejects malformed complete characters before considering an incomplete suffix.
801
+ content = decoder.decode(bytes, { stream: true });
802
+ }
803
+ catch {
804
+ throw invalid();
805
+ }
806
+ try {
807
+ content += decoder.decode();
808
+ return { content, read_bytes: bytes.length };
809
+ }
810
+ catch {
811
+ if (!budgetTruncated) {
812
+ throw invalid();
813
+ }
814
+ }
815
+ // Only a byte-budget boundary may leave up to three bytes of an incomplete character.
816
+ for (let end = bytes.length - 1; end >= Math.max(0, bytes.length - 3); --end) {
817
+ try {
818
+ content = new TextDecoder(label, decoderOptions).decode(bytes.subarray(0, end));
819
+ }
820
+ catch {
821
+ continue;
822
+ }
823
+ if (end === 0 && bytes.length > 0) {
824
+ throw new Error(`maxBytes is too small to read the next ${encoding} character`);
825
+ }
826
+ return { content, read_bytes: end };
827
+ }
828
+ throw invalid();
829
+ }
830
+ async function readLineRange(sftp, remotePath, totalSize, maxBytes, lineRange, encoding, binary, timeout) {
677
831
  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;
832
+ let stream;
833
+ try {
834
+ stream = sftp.createReadStream(remotePath);
835
+ }
836
+ catch (error) {
837
+ sftp.end();
838
+ throw error;
839
+ }
840
+ const chunks = [];
841
+ let line = 1;
842
+ let lineStart;
843
+ let lineEnd;
844
+ let size = 0;
845
+ let consumed = 0;
846
+ let byteLimitReached = false;
847
+ let sawAfter = false;
848
+ let encodingDetected = encoding !== 'auto';
849
+ let detected = encoding === 'auto' ? 'utf8' : encoding;
850
+ let pending = Buffer.alloc(0);
851
+ try {
852
+ await withSftpDeadline(sftp, (async () => {
853
+ for await (const part of stream) {
854
+ const chunk = Buffer.from(part);
855
+ consumed += chunk.length;
856
+ if (consumed > 1024 * 1024 * 1024) {
857
+ throw new Error('lineRange scan exceeded the 1 GiB input budget');
858
+ }
859
+ // Preserve a split UTF-16 code unit across SFTP chunks.
860
+ const data = Buffer.concat([pending, chunk]);
861
+ if (!encodingDetected && data.length < 2) {
862
+ pending = data;
863
+ continue;
864
+ }
865
+ if (!encodingDetected) {
866
+ detected = detectReadEncoding(data, encoding);
867
+ encodingDetected = true;
868
+ }
869
+ const width = detected.startsWith('utf16') ? 2 : 1;
870
+ const bigEndian = detected === 'utf16be';
871
+ const available = data.length - (data.length % width);
872
+ let segmentStart = 0;
873
+ for (let index = 0; index < available; index += width) {
874
+ const newline = width === 1
875
+ ? data[index] === 10
876
+ : bigEndian
877
+ ? data[index] === 0 && data[index + 1] === 10
878
+ : data[index] === 10 && data[index + 1] === 0;
879
+ if (!newline) {
880
+ continue;
881
+ }
882
+ if (line >= start && line <= end) {
883
+ const length = index + width - segmentStart;
884
+ const remaining = maxBytes - size;
885
+ if (length > remaining) {
886
+ if (remaining > 0) {
887
+ chunks.push(data.subarray(segmentStart, segmentStart + remaining));
888
+ size += remaining;
889
+ lineStart ??= line;
890
+ }
891
+ byteLimitReached = true;
892
+ stream.destroy();
893
+ break;
894
+ }
895
+ chunks.push(data.subarray(segmentStart, index + width));
896
+ size += length;
897
+ lineStart ??= line;
898
+ }
899
+ ++line;
900
+ segmentStart = index + width;
901
+ if (line > end) {
902
+ sawAfter = segmentStart < data.length || consumed < totalSize;
903
+ break;
904
+ }
905
+ }
906
+ if (byteLimitReached || line > end) {
907
+ break;
908
+ }
909
+ if (line >= start && line <= end && available > segmentStart) {
910
+ const length = available - segmentStart;
911
+ const remaining = maxBytes - size;
912
+ const taken = Math.min(length, remaining);
913
+ if (taken > 0) {
914
+ chunks.push(data.subarray(segmentStart, segmentStart + taken));
915
+ size += taken;
916
+ lineStart ??= line;
917
+ }
918
+ if (taken < length) {
919
+ byteLimitReached = true;
920
+ stream.destroy();
921
+ break;
922
+ }
923
+ }
924
+ pending = data.subarray(available);
925
+ }
926
+ if (!byteLimitReached && line <= end && line >= start && pending.length > 0) {
927
+ const taken = Math.min(pending.length, maxBytes - size);
928
+ if (taken > 0) {
929
+ chunks.push(pending.subarray(0, taken));
930
+ lineStart ??= line;
931
+ }
932
+ byteLimitReached = taken < pending.length;
933
+ }
934
+ })(), timeout);
935
+ }
936
+ finally {
937
+ stream.destroy();
938
+ sftp.end();
939
+ }
940
+ const raw = Buffer.concat(chunks);
941
+ const decoded = decodeReadBuffer(raw, detected, binary, byteLimitReached, lineStart === 1);
942
+ if (decoded.read_bytes < raw.length) {
943
+ byteLimitReached = true;
944
+ }
945
+ // Metadata describes the decoded prefix, not the bytes scanned or discarded at the budget boundary.
946
+ let finalLineTerminated = false;
947
+ if (decoded.read_bytes > 0 && lineStart !== undefined) {
948
+ const width = detected.startsWith('utf16') ? 2 : 1;
949
+ let returnedLine = lineStart;
950
+ for (let index = 0; index < decoded.read_bytes; index += width) {
951
+ lineEnd = returnedLine;
952
+ finalLineTerminated =
953
+ width === 1
954
+ ? raw[index] === 10
955
+ : index + 1 < decoded.read_bytes &&
956
+ (detected === 'utf16be'
957
+ ? raw[index] === 0 && raw[index + 1] === 10
958
+ : raw[index] === 10 && raw[index + 1] === 0);
959
+ if (finalLineTerminated) {
960
+ ++returnedLine;
961
+ }
962
+ }
963
+ }
964
+ else {
965
+ lineStart = undefined;
966
+ }
967
+ const eof = !byteLimitReached && !sawAfter;
724
968
  return {
725
- content,
969
+ content: decoded.content,
970
+ content_base64: decoded.content_base64,
971
+ encoding: binary ? 'base64' : detected,
726
972
  size: totalSize,
727
973
  total_size: totalSize,
728
974
  read_offset: 0,
729
- read_bytes: readBytes,
975
+ read_bytes: decoded.read_bytes,
730
976
  sample_kind: 'line_range',
731
- truncated: byteLimitReached || sawAfter,
732
- line_start: actualStart || undefined,
733
- line_end: actualEnd || undefined,
977
+ truncated: byteLimitReached || !eof,
978
+ line_start: lineStart,
979
+ line_end: lineEnd,
734
980
  eof,
735
981
  byte_limit_reached: byteLimitReached,
736
- final_line_terminated: actualEnd === 0 ? undefined : finalLineTerminated,
982
+ final_line_terminated: lineEnd === undefined ? undefined : finalLineTerminated,
737
983
  };
738
984
  }
739
985
  /**
@@ -752,12 +998,11 @@ export async function readFile(alias, remotePath, options) {
752
998
  throw error;
753
999
  }
754
1000
  if (readOptions.lineRange) {
755
- sftp.end();
756
- return readLineRange(alias, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.timeout);
1001
+ return readLineRange(sftp, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.encoding ?? 'auto', readOptions.binary === true, readOptions.timeout);
757
1002
  }
758
1003
  if (actualSize === 0) {
759
1004
  sftp.end();
760
- return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full');
1005
+ return emptyReadResult(0, readOptions.tail ? 'tail' : readOptions.offset !== undefined ? 'range' : 'full', 0, readOptions.binary === true);
761
1006
  }
762
1007
  const requestedOffset = readOptions.tail
763
1008
  ? Math.max(0, actualSize - readOptions.maxBytes)
@@ -772,7 +1017,24 @@ export async function readFile(alias, remotePath, options) {
772
1017
  : 'head';
773
1018
  if (readSize === 0) {
774
1019
  sftp.end();
775
- return emptyReadResult(actualSize, sampleKind, requestedOffset);
1020
+ return emptyReadResult(actualSize, sampleKind, requestedOffset, readOptions.binary === true);
1021
+ }
1022
+ let encoding = readOptions.encoding ?? 'auto';
1023
+ if (!readOptions.binary && encoding === 'auto' && requestedOffset > 0) {
1024
+ try {
1025
+ const first = await withSftpDeadline(sftp, new Promise((resolve, reject) => {
1026
+ const stream = sftp.createReadStream(remotePath, { start: 0, end: 1 });
1027
+ const chunks = [];
1028
+ stream.on('data', (chunk) => chunks.push(chunk));
1029
+ stream.once('error', reject);
1030
+ stream.once('end', () => resolve(Buffer.concat(chunks)));
1031
+ }), readOptions.timeout);
1032
+ encoding = detectReadEncoding(first, 'auto');
1033
+ }
1034
+ catch (error) {
1035
+ sftp.end();
1036
+ throw error;
1037
+ }
776
1038
  }
777
1039
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
778
1040
  const chunks = [];
@@ -789,22 +1051,45 @@ export async function readFile(alias, remotePath, options) {
789
1051
  }
790
1052
  try {
791
1053
  const buffer = Buffer.concat(chunks);
1054
+ const detected = detectReadEncoding(buffer, encoding);
1055
+ if (!readOptions.binary &&
1056
+ detected.startsWith('utf16') &&
1057
+ !readOptions.tail &&
1058
+ requestedOffset % 2) {
1059
+ throw new Error(`Invalid ${detected} offset is not a character boundary`);
1060
+ }
792
1061
  let contentStart = 0;
793
- if (readOptions.tail) {
1062
+ if (!readOptions.binary && detected === 'utf8' && readOptions.tail && requestedOffset > 0) {
794
1063
  while (contentStart < buffer.length && isUtf8ContinuationByte(buffer[contentStart])) {
795
1064
  ++contentStart;
796
1065
  }
797
1066
  }
798
- else {
1067
+ else if (!readOptions.binary && detected === 'utf8') {
799
1068
  ensureUtf8Boundary(buffer, 0, 'offset');
800
1069
  }
801
- const contentEnd = utf8SafeEnd(buffer, contentStart, buffer.length, remotePath, requestedOffset + buffer.length < actualSize);
802
- const contentBuffer = buffer.subarray(contentStart, contentEnd);
1070
+ else if (!readOptions.binary && detected.startsWith('utf16') && readOptions.tail) {
1071
+ contentStart = requestedOffset % 2;
1072
+ if (requestedOffset > 0 && contentStart + 2 <= buffer.length) {
1073
+ const firstUnit = detected === 'utf16be'
1074
+ ? buffer.readUInt16BE(contentStart)
1075
+ : buffer.readUInt16LE(contentStart);
1076
+ if (firstUnit >= 0xdc00 && firstUnit <= 0xdfff) {
1077
+ contentStart += 2;
1078
+ }
1079
+ }
1080
+ }
1081
+ if (!readOptions.binary && buffer.length > 0 && contentStart >= buffer.length) {
1082
+ throw new Error(`maxBytes is too small to read a complete ${detected} tail character`);
1083
+ }
1084
+ const decoded = decodeReadBuffer(buffer.subarray(contentStart), detected, readOptions.binary === true, requestedOffset + buffer.length < actualSize, requestedOffset + contentStart === 0);
1085
+ const contentBuffer = buffer.subarray(contentStart, contentStart + decoded.read_bytes);
803
1086
  const actualReadOffset = requestedOffset + contentStart;
804
- const nextOffset = requestedOffset + contentEnd;
1087
+ const nextOffset = actualReadOffset + contentBuffer.length;
805
1088
  const remainingBytes = Math.max(0, actualSize - nextOffset);
806
1089
  resolve({
807
- content: contentBuffer.toString('utf-8'),
1090
+ content: decoded.content,
1091
+ content_base64: decoded.content_base64,
1092
+ encoding: readOptions.binary ? 'base64' : detected,
808
1093
  size: actualSize,
809
1094
  total_size: actualSize,
810
1095
  read_offset: actualReadOffset,
@@ -821,10 +1106,18 @@ export async function readFile(alias, remotePath, options) {
821
1106
  reject(processingError);
822
1107
  }
823
1108
  };
824
- const readStream = sftp.createReadStream(remotePath, {
825
- start: requestedOffset,
826
- end: requestedOffset + readSize - 1,
827
- });
1109
+ let readStream;
1110
+ try {
1111
+ readStream = sftp.createReadStream(remotePath, {
1112
+ start: requestedOffset,
1113
+ end: requestedOffset + readSize - 1,
1114
+ });
1115
+ }
1116
+ catch (error) {
1117
+ sftp.end();
1118
+ reject(error);
1119
+ return;
1120
+ }
828
1121
  readStream.on('data', (chunk) => {
829
1122
  chunks.push(chunk);
830
1123
  });
@@ -832,6 +1125,42 @@ export async function readFile(alias, remotePath, options) {
832
1125
  readStream.once('error', (error) => finish(error));
833
1126
  }), readOptions.timeout);
834
1127
  }
1128
+ export async function createEmptyRemoteFile(alias, remotePath, timeout) {
1129
+ const sftp = await getSftpWithinDeadline(alias, timeout);
1130
+ try {
1131
+ await withSftpDeadline(sftp, new Promise((resolve, reject) => {
1132
+ const stream = sftp.createWriteStream(remotePath, { flags: 'wx', mode: 0o600 });
1133
+ stream.once('error', reject);
1134
+ stream.once('close', resolve);
1135
+ stream.end();
1136
+ }), timeout);
1137
+ }
1138
+ finally {
1139
+ sftp.end();
1140
+ }
1141
+ }
1142
+ export async function prepareWindowsRemotePrivateFile(alias, remotePath, timeout, shellPath = remotePath) {
1143
+ await createEmptyRemoteFile(alias, remotePath, timeout);
1144
+ try {
1145
+ const acl = await sessionManager.exec(alias, encodedPowershell(windowsAclScript(shellPath, true)), {
1146
+ timeout,
1147
+ useLoginUser: true,
1148
+ maxOutputSize: 4096,
1149
+ });
1150
+ if (!acl.success || acl.stdout.trim() !== 'usable') {
1151
+ throw new Error('privacy_not_enforced_on_windows: remote temporary file ACL was not verified');
1152
+ }
1153
+ }
1154
+ catch (error) {
1155
+ try {
1156
+ await removeRemoteFile(alias, remotePath, timeout);
1157
+ }
1158
+ catch (cleanupError) {
1159
+ throw new AggregateError([error, cleanupError], 'privacy_not_enforced_on_windows: remote ACL check and cleanup failed', { cause: cleanupError });
1160
+ }
1161
+ throw error;
1162
+ }
1163
+ }
835
1164
  /**
836
1165
  * 写入远程文件
837
1166
  */
@@ -866,7 +1195,7 @@ function validateSftpEntryName(filename) {
866
1195
  /**
867
1196
  * 列出目录内容
868
1197
  */
869
- export async function listDir(alias, remotePath, showHidden = false, sharedSftp, timeout) {
1198
+ export async function listDir(alias, remotePath, showHidden = false, sharedSftp, timeout, style = 'posix') {
870
1199
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
871
1200
  const closeWhenDone = !sharedSftp;
872
1201
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
@@ -894,12 +1223,13 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp,
894
1223
  .filter((item) => showHidden || !item.filename.startsWith('.'))
895
1224
  .map((item) => ({
896
1225
  name: item.filename,
897
- path: path.posix.join(remotePath, item.filename),
1226
+ path: remoteJoin(style, remotePath, item.filename),
898
1227
  size: item.attrs.size,
899
1228
  isDirectory: (item.attrs.mode & S_IFMT) === S_IFDIR,
900
1229
  isFile: (item.attrs.mode & S_IFMT) === S_IFREG,
901
1230
  isSymlink: (item.attrs.mode & S_IFMT) === S_IFLNK,
902
- permissions: formatPermissions(item.attrs.mode),
1231
+ mode: extractFileMode(item.attrs.mode),
1232
+ permissions: formatFilePermissions(item.attrs.mode),
903
1233
  owner: item.attrs.uid,
904
1234
  group: item.attrs.gid,
905
1235
  mtime: new Date(item.attrs.mtime * 1000),
@@ -922,30 +1252,35 @@ export async function listDir(alias, remotePath, showHidden = false, sharedSftp,
922
1252
  /**
923
1253
  * 获取文件信息
924
1254
  */
925
- export async function getFileInfo(alias, remotePath, timeout) {
926
- const sftp = await getSftpWithinDeadline(alias, timeout);
927
- return withSftpDeadline(sftp, new Promise((resolve, reject) => {
928
- sftp.stat(remotePath, (err, stats) => {
1255
+ export async function getFileInfo(alias, remotePath, timeout, style = 'posix') {
1256
+ const connection = sessionManager.getOpenSshConnection(alias);
1257
+ let stats;
1258
+ if (connection) {
1259
+ stats = await connection.stat(remotePath, timeout ?? 600_000);
1260
+ }
1261
+ else {
1262
+ const sftp = await getSftpWithinDeadline(alias, timeout);
1263
+ try {
1264
+ stats = await sftpStat(sftp, remotePath, timeout);
1265
+ }
1266
+ finally {
929
1267
  sftp.end();
930
- if (err) {
931
- reject(err);
932
- return;
933
- }
934
- resolve({
935
- name: path.posix.basename(remotePath),
936
- path: remotePath,
937
- size: stats.size,
938
- isDirectory: (stats.mode & S_IFMT) === S_IFDIR,
939
- isFile: (stats.mode & S_IFMT) === S_IFREG,
940
- isSymlink: (stats.mode & S_IFMT) === S_IFLNK,
941
- permissions: formatPermissions(stats.mode),
942
- owner: stats.uid,
943
- group: stats.gid,
944
- mtime: new Date(stats.mtime * 1000),
945
- atime: new Date(stats.atime * 1000),
946
- });
947
- });
948
- }), timeout);
1268
+ }
1269
+ }
1270
+ return {
1271
+ name: remotePathModule(style).basename(remotePath),
1272
+ path: remotePath,
1273
+ size: stats.size,
1274
+ isDirectory: (stats.mode & S_IFMT) === S_IFDIR,
1275
+ isFile: (stats.mode & S_IFMT) === S_IFREG,
1276
+ isSymlink: (stats.mode & S_IFMT) === S_IFLNK,
1277
+ mode: extractFileMode(stats.mode),
1278
+ permissions: formatFilePermissions(stats.mode),
1279
+ owner: stats.uid,
1280
+ group: stats.gid,
1281
+ mtime: new Date(stats.mtime * 1000),
1282
+ atime: new Date(stats.atime * 1000),
1283
+ };
949
1284
  }
950
1285
  function sftpMkdir(sftp, remotePath, timeout) {
951
1286
  return withSftpDeadline(sftp, new Promise((resolve, reject) => {
@@ -959,8 +1294,8 @@ function sftpMkdir(sftp, remotePath, timeout) {
959
1294
  });
960
1295
  }), timeout);
961
1296
  }
962
- async function ensureSftpDirectory(sftp, remotePath, timeout) {
963
- const normalizedPath = path.posix.normalize(remotePath);
1297
+ async function ensureSftpDirectory(sftp, remotePath, timeout, style = 'posix') {
1298
+ const normalizedPath = remoteNormalize(style, remotePath);
964
1299
  if (normalizedPath === '/' || normalizedPath === '.') {
965
1300
  return;
966
1301
  }
@@ -979,9 +1314,12 @@ async function ensureSftpDirectory(sftp, remotePath, timeout) {
979
1314
  }
980
1315
  return;
981
1316
  }
982
- const parent = path.posix.dirname(normalizedPath);
1317
+ const parent = remoteDirname(style, normalizedPath);
1318
+ if (style === 'sftp-posix' && /^\/\/[^/]+\/[^/]+\/?$/.test(normalizedPath) && parent !== normalizedPath) {
1319
+ throw new Error('SFTP UNC share root does not exist; refusing to create a network host path');
1320
+ }
983
1321
  if (parent !== normalizedPath) {
984
- await ensureSftpDirectory(sftp, parent, timeout);
1322
+ await ensureSftpDirectory(sftp, parent, timeout, style);
985
1323
  }
986
1324
  try {
987
1325
  await sftpMkdir(sftp, normalizedPath, timeout);
@@ -1002,12 +1340,12 @@ async function ensureSftpDirectory(sftp, remotePath, timeout) {
1002
1340
  /**
1003
1341
  * 创建目录
1004
1342
  */
1005
- export async function mkdir(alias, remotePath, recursive = false, sharedSftp, timeout) {
1343
+ export async function mkdir(alias, remotePath, recursive = false, sharedSftp, timeout, style = 'posix') {
1006
1344
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias, timeout));
1007
1345
  return withSftpDeadline(sftp, (async () => {
1008
1346
  try {
1009
1347
  if (recursive) {
1010
- await ensureSftpDirectory(sftp, remotePath, timeout);
1348
+ await ensureSftpDirectory(sftp, remotePath, timeout, style);
1011
1349
  }
1012
1350
  else {
1013
1351
  await sftpMkdir(sftp, remotePath, timeout);
@@ -1024,15 +1362,26 @@ export async function mkdir(alias, remotePath, recursive = false, sharedSftp, ti
1024
1362
  /**
1025
1363
  * 检查远程是否安装 rsync
1026
1364
  */
1027
- export async function checkRsync(alias, timeout = 10_000) {
1365
+ export async function checkRsync(alias, timeout = 10_000, executable = 'rsync', shell = 'posix') {
1028
1366
  const generation = getRsyncGeneration(alias);
1029
- const cached = rsyncCache.get(alias);
1367
+ const cacheKey = `${alias}\0${shell}\0${executable}`;
1368
+ const cached = rsyncCache.get(cacheKey);
1030
1369
  if (cached !== undefined && cached.expiresAt > Date.now()) {
1031
1370
  return cached.value;
1032
1371
  }
1033
1372
  const startedAt = Date.now();
1034
1373
  try {
1035
- const result = await sessionManager.exec(alias, 'command -v rsync', {
1374
+ if (/[\r\n\0]/.test(executable)) {
1375
+ throw new Error('Invalid rsync executable path');
1376
+ }
1377
+ const probeCommand = shell === 'posix'
1378
+ ? executable === 'rsync'
1379
+ ? 'command -v rsync'
1380
+ : `test -x ${escapeShellArg(executable)} && printf '%s\\n' ${escapeShellArg(executable)}`
1381
+ : shell === 'powershell'
1382
+ ? `(Get-Command -ErrorAction Stop -Name '${executable.replace(/'/g, "''")}').Source`
1383
+ : `where.exe "${executable.replace(/"/g, '""')}"`;
1384
+ const result = await sessionManager.exec(alias, probeCommand, {
1036
1385
  timeout,
1037
1386
  useLoginUser: true,
1038
1387
  maxOutputSize: 4096,
@@ -1055,7 +1404,7 @@ export async function checkRsync(alias, timeout = 10_000) {
1055
1404
  retryable: false,
1056
1405
  exitCode: result.exitCode,
1057
1406
  };
1058
- rsyncCache.set(alias, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1407
+ rsyncCache.set(cacheKey, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1059
1408
  return probe;
1060
1409
  }
1061
1410
  if (result.failureKind === 'timeout' || result.timedOut) {
@@ -1088,7 +1437,7 @@ export async function checkRsync(alias, timeout = 10_000) {
1088
1437
  retryable: false,
1089
1438
  exitCode: result.exitCode,
1090
1439
  };
1091
- rsyncCache.set(alias, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1440
+ rsyncCache.set(cacheKey, { value: probe, expiresAt: Date.now() + RSYNC_CACHE_TTL_MS });
1092
1441
  return probe;
1093
1442
  }
1094
1443
  return {
@@ -1111,6 +1460,57 @@ export async function checkRsync(alias, timeout = 10_000) {
1111
1460
  };
1112
1461
  }
1113
1462
  }
1463
+ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1464
+ const candidates = [];
1465
+ const style = options.remotePathStyle ?? sessionManager.getRemotePathStyle(alias);
1466
+ await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks === true, { files: 0, directories: 0, bytes: 0 }, 0, options.signal, '', style, (parent, names) => {
1467
+ if (names.length < 2) {
1468
+ return;
1469
+ }
1470
+ // ASCII folding only screens candidates. Windows performs the authoritative comparison.
1471
+ // Any Unicode name requires remote comparison against every sibling, including ASCII names.
1472
+ const hasUnicode = names.some((name) => [...name].some((char) => char.charCodeAt(0) > 0x7f));
1473
+ if (hasUnicode || new Set(names.map((name) => name.toLowerCase())).size !== names.length) {
1474
+ candidates.push({ parent, names });
1475
+ }
1476
+ });
1477
+ const deadline = Date.now() + (options.preflightTimeout ?? 10_000);
1478
+ for (const { parent, names } of candidates) {
1479
+ let collision;
1480
+ try {
1481
+ const timeout = deadline - Date.now();
1482
+ if (timeout <= 0) {
1483
+ throw new Error('name preflight timeout was exhausted');
1484
+ }
1485
+ const result = await sessionManager.exec(alias, encodedPowershell(windowsCaseSemanticsScript(remoteShellPath(parent, style), names)), { timeout, maxOutputSize: 65_536, useLoginUser: true, loadProfile: false });
1486
+ if (!result.success ||
1487
+ result.exitCode !== 0 ||
1488
+ result.timedOut ||
1489
+ result.stdoutTruncated ||
1490
+ result.stderrTruncated) {
1491
+ throw new Error(result.stderr || 'Windows case semantics query failed or returned truncated output');
1492
+ }
1493
+ const semantics = JSON.parse(result.stdout);
1494
+ if (typeof semantics?.caseSensitive !== 'boolean' ||
1495
+ !Object.hasOwn(semantics, 'collision') ||
1496
+ (semantics.collision !== null &&
1497
+ (!Array.isArray(semantics.collision) ||
1498
+ semantics.collision.length !== 2 ||
1499
+ semantics.collision[0] === semantics.collision[1] ||
1500
+ !semantics.collision.every((name) => typeof name === 'string' && names.includes(name)))) ||
1501
+ (semantics.caseSensitive && semantics.collision !== null)) {
1502
+ throw new Error('Windows case semantics query returned incomplete fields');
1503
+ }
1504
+ collision = semantics.collision;
1505
+ }
1506
+ catch (error) {
1507
+ throw new Error(`case_semantics_unverified: ${parent}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
1508
+ }
1509
+ if (collision) {
1510
+ throw new Error(`windows_filename_collision: ${parent}: ${collision.join(' / ')}`);
1511
+ }
1512
+ }
1513
+ }
1114
1514
  /**
1115
1515
  * 智能文件同步(根据连接能力选择 rsync 或 SFTP)
1116
1516
  *
@@ -1134,17 +1534,25 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
1134
1534
  sourceIsDirectory = source.stats.isDirectory();
1135
1535
  }
1136
1536
  else {
1137
- sourceIsDirectory = (await getFileInfo(alias, remotePath)).isDirectory;
1537
+ sourceIsDirectory = (await getFileInfo(alias, remotePath, undefined, options.remotePathStyle)).isDirectory;
1138
1538
  }
1139
1539
  if (sourceIsDirectory && options.recursive === false) {
1140
1540
  throw new Error('recursive=false is not supported for directory sources; use a file source or enable recursion');
1141
1541
  }
1142
1542
  const capabilityStartedAt = Date.now();
1143
1543
  const rsyncGeneration = getRsyncGeneration(alias);
1544
+ if (direction === 'upload' && sourceIsDirectory && sessionManager.getRemotePlatform(alias) === 'windows') {
1545
+ await verifyWindowsUploadNames(alias, localPath, remotePath, options);
1546
+ assertCurrentRsyncGeneration(alias, rsyncGeneration);
1547
+ }
1144
1548
  const capability = sessionManager.getExternalTransferCapability(alias);
1145
1549
  const preflightTimeout = options.preflightTimeout ?? 10_000;
1550
+ const connection = sessionManager.getOpenSshConnection(alias);
1551
+ if (connection) {
1552
+ await connection.capture('command -v find stat head realpath >/dev/null && find --version >/dev/null && stat --version >/dev/null && head --version >/dev/null && realpath --version >/dev/null', preflightTimeout, 4096);
1553
+ }
1146
1554
  const rsyncProbe = capability.rsyncEligible
1147
- ? await checkRsync(alias, preflightTimeout)
1555
+ ? await checkRsync(alias, preflightTimeout, capability.rsyncExecutable, capability.commandShell)
1148
1556
  : {
1149
1557
  available: false,
1150
1558
  status: 'skipped',
@@ -1153,8 +1561,21 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
1153
1561
  reason: capability.decisionReason,
1154
1562
  };
1155
1563
  assertCurrentRsyncGeneration(alias, rsyncGeneration);
1156
- const resolvedOptions = { ...options, sourceIsDirectory };
1564
+ const resolvedOptions = {
1565
+ ...options,
1566
+ sourceIsDirectory,
1567
+ remotePathStyle: options.remotePathStyle ?? capability.remotePathStyle ?? 'posix',
1568
+ };
1157
1569
  const capabilityDuration = Date.now() - capabilityStartedAt;
1570
+ if (capability.backend === 'openssh' && !rsyncProbe.available) {
1571
+ throw new OpenSshError('The OpenSSH master backend requires remote rsync; no SFTP fallback is available', {
1572
+ code: 'unsupported_backend',
1573
+ backend: 'openssh',
1574
+ capability: 'rsync',
1575
+ reason: rsyncProbe.reason ?? rsyncProbe.error,
1576
+ retryable: false,
1577
+ });
1578
+ }
1158
1579
  const selectedTransport = capability.rsyncEligible && rsyncProbe?.available ? 'rsync' : 'sftp';
1159
1580
  const decisionReason = !capability.rsyncEligible
1160
1581
  ? capability.decisionReason
@@ -1201,11 +1622,22 @@ export async function syncFiles(alias, localPath, remotePath, direction, options
1201
1622
  */
1202
1623
  async function syncWithRsync(alias, localPath, remotePath, direction, options, capability, generation) {
1203
1624
  assertCurrentRsyncGeneration(alias, generation);
1625
+ const connection = sessionManager.getOpenSshConnection(alias);
1626
+ const fallbackToSftp = (reason) => {
1627
+ if (connection)
1628
+ throw new OpenSshError('OpenSSH master sync preflight failed; the selected backend was preserved', {
1629
+ code: 'openssh_sync_preflight',
1630
+ backend: 'openssh',
1631
+ reason,
1632
+ retryable: false,
1633
+ });
1634
+ return syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1635
+ };
1204
1636
  const checkCommand = os.platform() === 'win32' ? 'where' : 'which';
1205
1637
  const checkResult = await runLocalProcess(checkCommand, ['rsync'], options.preflightTimeout ?? 10_000);
1206
1638
  assertCurrentRsyncGeneration(alias, generation);
1207
1639
  if (checkResult.status !== 0) {
1208
- const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1640
+ const fallback = await fallbackToSftp(checkResult.timedOut ? 'local_rsync_preflight_timeout' : 'local_rsync_unavailable');
1209
1641
  return {
1210
1642
  ...fallback,
1211
1643
  connectStatus: 'not_applicable',
@@ -1249,29 +1681,66 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1249
1681
  // 构建 rsync argv(不用 shell=true,避免 username/host 含 shell 元字符时注入)
1250
1682
  // ProxyCommand=none 显式禁用 ssh-config 中可能定义的 ProxyCommand,防止外部命令注入
1251
1683
  const connectTimeout = options.connectTimeout ?? 30_000;
1252
- const sshOptions = [
1253
- '-p',
1254
- String(capability.port),
1255
- '-o',
1256
- 'StrictHostKeyChecking=accept-new',
1257
- '-o',
1258
- 'BatchMode=yes',
1259
- '-o',
1260
- `ConnectTimeout=${Math.max(1, Math.ceil(connectTimeout / 1000))}`,
1261
- '-o',
1262
- 'ProxyCommand=none',
1263
- ];
1684
+ const profile = capability.rsyncProfile ?? 'posix';
1685
+ const localRsyncPath = process.platform === 'win32' ? convertRsyncPath(localPath, profile) : localPath;
1686
+ const remoteRsyncPath = capability.commandShell && capability.commandShell !== 'posix'
1687
+ ? convertRsyncPath(remoteShellPath(remotePath, capability.remotePathStyle ?? 'win32'), profile).replace(/\\/g, '/')
1688
+ : remotePath;
1689
+ const childEnv = { ...process.env };
1690
+ if (capability.agent === 'none') {
1691
+ delete childEnv.SSH_AUTH_SOCK;
1692
+ }
1693
+ else if (capability.agent) {
1694
+ childEnv.SSH_AUTH_SOCK = capability.agent;
1695
+ }
1696
+ const sshOptions = connection
1697
+ ? connection.arguments().slice(0, -1)
1698
+ : [
1699
+ '-p',
1700
+ String(capability.port),
1701
+ '-o',
1702
+ 'StrictHostKeyChecking=accept-new',
1703
+ '-o',
1704
+ 'BatchMode=yes',
1705
+ '-o',
1706
+ `ConnectTimeout=${Math.max(1, Math.ceil(connectTimeout / 1000))}`,
1707
+ '-o',
1708
+ 'ProxyCommand=none',
1709
+ ];
1710
+ if (capability.agent === 'none') {
1711
+ sshOptions.push('-o', 'IdentityAgent=none');
1712
+ }
1264
1713
  if (capability.keyPath) {
1265
1714
  sshOptions.push('-i', capability.keyPath);
1266
1715
  }
1267
1716
  const destination = `${capability.username}@${capability.host}`;
1717
+ const executable = capability.rsyncExecutable;
1718
+ if (executable &&
1719
+ (/[\r\n\0]/.test(executable) || (capability.commandShell === 'cmd' && executable.includes('"')))) {
1720
+ throw new Error('Invalid remote rsync executable');
1721
+ }
1722
+ const remoteCommand = executable
1723
+ ? capability.commandShell === 'powershell'
1724
+ ? `& '${executable.replace(/'/g, "''")}'`
1725
+ : capability.commandShell === 'cmd'
1726
+ ? `"${executable}"`
1727
+ : escapeShellArg(executable)
1728
+ : 'rsync';
1268
1729
  assertCurrentRsyncGeneration(alias, generation);
1269
1730
  const connectStartedAt = Date.now();
1270
- const connectResult = await runLocalProcess('ssh', [...sshOptions, destination, 'true'], connectTimeout);
1731
+ const connectResult = await runLocalProcess('ssh', [
1732
+ ...sshOptions,
1733
+ destination,
1734
+ capability.commandShell === 'powershell'
1735
+ ? 'powershell.exe -NoProfile -Command exit 0'
1736
+ : capability.commandShell === 'cmd'
1737
+ ? 'cmd.exe /D /C exit 0'
1738
+ : 'true',
1739
+ ], connectTimeout, childEnv, connection);
1271
1740
  const connectDuration = Date.now() - connectStartedAt;
1272
1741
  assertCurrentRsyncGeneration(alias, generation);
1273
1742
  if (connectResult.error || connectResult.status !== 0) {
1274
- const fallback = await syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options);
1743
+ const fallback = await fallbackToSftp(connectResult.stderr.trim() || connectResult.error?.message || 'rsync_connect_failed');
1275
1744
  const fallbackReason = connectResult.timedOut ? 'rsync_connect_timeout' : 'rsync_connect_failed';
1276
1745
  const detail = connectResult.stderr.trim() || connectResult.error?.message;
1277
1746
  return {
@@ -1284,23 +1753,46 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1284
1753
  : fallback.output,
1285
1754
  };
1286
1755
  }
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;
1756
+ if (capability.commandShell && capability.commandShell !== 'posix') {
1757
+ const remoteProbe = await runLocalProcess('ssh', [...sshOptions, destination, `${remoteCommand} --version`], connectTimeout, childEnv);
1758
+ assertCurrentRsyncGeneration(alias, generation);
1759
+ if (remoteProbe.error || remoteProbe.status !== 0) {
1760
+ const fallback = await fallbackToSftp(remoteProbe.stderr.trim() || remoteProbe.error?.message || 'remote_rsync_unavailable');
1761
+ const reason = remoteProbe.stderr.trim() || remoteProbe.error?.message || `exit code ${remoteProbe.status}`;
1762
+ return {
1763
+ ...fallback,
1764
+ connectDuration,
1765
+ connectStatus: 'completed',
1766
+ fallbackReason: remoteProbe.timedOut
1767
+ ? 'remote_rsync_command_timeout'
1768
+ : 'remote_rsync_command_unavailable',
1769
+ output: `Remote rsync command preflight failed: ${reason}; ${fallback.output ?? ''}`.trim(),
1770
+ };
1771
+ }
1772
+ }
1773
+ const sshCmd = ['ssh', ...sshOptions].map((arg) => quoteRsyncSshArg(arg, profile)).join(' ');
1774
+ const rsyncLocalPath = options.sourceIsDirectory && direction === 'upload' && !localRsyncPath.endsWith('/')
1775
+ ? `${localRsyncPath}/`
1776
+ : localRsyncPath;
1777
+ const rsyncRemotePath = options.sourceIsDirectory && direction === 'download' && !remoteRsyncPath.endsWith('/')
1778
+ ? `${remoteRsyncPath}/`
1779
+ : remoteRsyncPath;
1294
1780
  // remoteSpec 作为单独 argv 元素,不经 shell 解析
1295
1781
  const remoteSpec = `${destination}:${rsyncRemotePath}`;
1782
+ if (executable) {
1783
+ args.push(`--rsync-path=${remoteCommand}`);
1784
+ }
1785
+ if (connection || (capability.commandShell !== 'posix' && capability.commandShell !== undefined)) {
1786
+ args.push('--protect-args');
1787
+ }
1296
1788
  // 在 path 参数前插 `--`,明确剩余为路径而非选项(双重保险)
1297
1789
  const rsyncArgs = direction === 'upload'
1298
1790
  ? [...args, '-e', sshCmd, '--', rsyncLocalPath, remoteSpec]
1299
- : [...args, '-e', sshCmd, '--', remoteSpec, localPath];
1791
+ : [...args, '-e', sshCmd, '--', remoteSpec, localRsyncPath];
1300
1792
  try {
1301
1793
  assertCurrentRsyncGeneration(alias, generation);
1302
1794
  const operationTimeout = options.operationTimeout ?? 600_000;
1303
- const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout);
1795
+ const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout, childEnv, connection);
1304
1796
  if (!isCurrentRsyncGeneration(alias, generation)) {
1305
1797
  return {
1306
1798
  success: false,
@@ -1331,15 +1823,15 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1331
1823
  output: `rsync ${reason}${stderr ? ` | stderr: ${stderr}` : ''}; remote transfer state is unknown`,
1332
1824
  };
1333
1825
  }
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
1826
  return {
1338
- ...fallback,
1827
+ success: false,
1828
+ method: 'rsync',
1339
1829
  connectDuration,
1340
1830
  connectStatus: 'completed',
1831
+ operationStatus: 'unknown',
1832
+ retryable: true,
1341
1833
  fallbackReason: 'rsync_operation_failed',
1342
- output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
1834
+ output: `rsync failed: ${reason}${stderr ? ` | stderr: ${stderr}` : ''}; remote transfer state is unknown`,
1343
1835
  };
1344
1836
  }
1345
1837
  const output = result.stdout;
@@ -1369,16 +1861,15 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1369
1861
  if (!isCurrentRsyncGeneration(alias, generation)) {
1370
1862
  throw e;
1371
1863
  }
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
1864
  return {
1377
- ...fallback,
1865
+ success: false,
1866
+ method: 'rsync',
1378
1867
  connectDuration,
1379
1868
  connectStatus: 'completed',
1869
+ operationStatus: 'unknown',
1870
+ retryable: true,
1380
1871
  fallbackReason: 'rsync_execution_error',
1381
- output: fallback.output ? `${warning}\n\n${fallback.output}` : warning,
1872
+ output: `rsync execution failed: ${e instanceof Error ? e.message : String(e)}; remote transfer state is unknown`,
1382
1873
  };
1383
1874
  }
1384
1875
  }
@@ -1415,20 +1906,6 @@ class DirectoryTransferAccumulator {
1415
1906
  addFailed() {
1416
1907
  this.result.failed++;
1417
1908
  }
1418
- merge(result) {
1419
- this.result.fileCount += result.fileCount;
1420
- this.result.totalSize += result.totalSize;
1421
- this.result.skippedSymlinks += result.skippedSymlinks;
1422
- this.result.skippedUnsupported += result.skippedUnsupported;
1423
- for (const itemPath of result.unsupportedSamples) {
1424
- if (this.result.unsupportedSamples.length < 10) {
1425
- this.result.unsupportedSamples.push(itemPath);
1426
- }
1427
- }
1428
- this.result.added += result.added;
1429
- this.result.updated += result.updated;
1430
- this.result.failed += result.failed;
1431
- }
1432
1909
  toResult() {
1433
1910
  return { ...this.result };
1434
1911
  }
@@ -1448,7 +1925,7 @@ function buildDirectorySyncResult(result, warnings) {
1448
1925
  }
1449
1926
  function buildSyncResult(fileCount, totalSize, warnings, skippedSymlinks = 0, stats) {
1450
1927
  if (skippedSymlinks > 0) {
1451
- warnings.push(`skipped ${skippedSymlinks} symlink(s) (set followSymlinks=true to traverse)`);
1928
+ warnings.push(`skipped ${skippedSymlinks} symlink(s); link targets were not transferred`);
1452
1929
  }
1453
1930
  return {
1454
1931
  success: true,
@@ -1485,13 +1962,56 @@ function parseRsyncStats(output) {
1485
1962
  }
1486
1963
  return stats;
1487
1964
  }
1488
- function hashLocalFile(filePath) {
1965
+ export function hashLocalFile(filePath, algorithm = 'sha256', timeout, limits) {
1489
1966
  return new Promise((resolve, reject) => {
1490
- const hash = createHash('sha256');
1967
+ const before = fs.statSync(filePath);
1968
+ if (!before.isFile() || (limits && (before.size > limits.maxBytes || before.size !== limits.expectedSize))) {
1969
+ reject(new Error('Local file size changed or exceeds the verification byte budget'));
1970
+ return;
1971
+ }
1972
+ const hash = createHash(algorithm);
1491
1973
  const stream = fs.createReadStream(filePath);
1492
- stream.on('data', (chunk) => hash.update(chunk));
1493
- stream.on('error', reject);
1494
- stream.on('end', () => resolve(hash.digest('hex')));
1974
+ let bytes = 0;
1975
+ let settled = false;
1976
+ const finish = (error) => {
1977
+ if (settled)
1978
+ return;
1979
+ settled = true;
1980
+ if (timer)
1981
+ clearTimeout(timer);
1982
+ if (error) {
1983
+ stream.destroy();
1984
+ reject(error);
1985
+ }
1986
+ else
1987
+ resolve(hash.digest('hex'));
1988
+ };
1989
+ const timer = timeout === undefined
1990
+ ? undefined
1991
+ : setTimeout(() => finish(new Error(`Local file hashing timed out after ${timeout}ms`)), timeout);
1992
+ stream.on('data', (chunk) => {
1993
+ bytes += Buffer.byteLength(chunk);
1994
+ if (bytes > before.size || (limits && bytes > limits.maxBytes))
1995
+ finish(new Error('Local file grew during verification'));
1996
+ else
1997
+ hash.update(chunk);
1998
+ });
1999
+ stream.on('error', finish);
2000
+ stream.on('end', () => {
2001
+ try {
2002
+ const after = fs.statSync(filePath);
2003
+ const changed = bytes !== before.size ||
2004
+ after.size !== before.size ||
2005
+ after.ino !== before.ino ||
2006
+ after.dev !== before.dev ||
2007
+ after.mtimeMs !== before.mtimeMs ||
2008
+ after.ctimeMs !== before.ctimeMs;
2009
+ finish(changed ? new Error('Local file changed during verification') : undefined);
2010
+ }
2011
+ catch (error) {
2012
+ finish(error instanceof Error ? error : new Error(String(error)));
2013
+ }
2014
+ });
1495
2015
  });
1496
2016
  }
1497
2017
  async function hashRemoteFile(alias, remotePath) {
@@ -1551,14 +2071,14 @@ async function buildSingleFileVerification(alias, localPath, remotePath, directi
1551
2071
  };
1552
2072
  }
1553
2073
  }
1554
- async function resolveSftpUploadFileTarget(alias, localPath, remotePath) {
1555
- if (remotePath.endsWith('/')) {
1556
- return path.posix.join(remotePath, path.basename(localPath));
2074
+ async function resolveSftpUploadFileTarget(alias, localPath, remotePath, style = 'posix') {
2075
+ if (remotePath.endsWith('/') || remotePath.endsWith('\\')) {
2076
+ return remoteJoin(style, remotePath, path.basename(localPath));
1557
2077
  }
1558
2078
  try {
1559
2079
  const info = await getFileInfo(alias, remotePath);
1560
2080
  if (info.isDirectory) {
1561
- return path.posix.join(remotePath, path.basename(localPath));
2081
+ return remoteJoin(style, remotePath, path.basename(localPath));
1562
2082
  }
1563
2083
  }
1564
2084
  catch (error) {
@@ -1569,28 +2089,31 @@ async function resolveSftpUploadFileTarget(alias, localPath, remotePath) {
1569
2089
  }
1570
2090
  return remotePath;
1571
2091
  }
1572
- function resolveSftpDownloadFileTarget(remotePath, localPath) {
2092
+ function resolveSftpDownloadFileTarget(remotePath, localPath, style = 'posix') {
1573
2093
  if (localPath.endsWith(path.sep)) {
1574
2094
  fs.mkdirSync(localPath, { recursive: true });
1575
- return path.join(localPath, path.posix.basename(remotePath));
2095
+ return path.join(localPath, remotePathModule(style).basename(remotePath));
1576
2096
  }
1577
2097
  if (fs.existsSync(localPath) && fs.statSync(localPath).isDirectory()) {
1578
- return path.join(localPath, path.posix.basename(remotePath));
2098
+ return path.join(localPath, remotePathModule(style).basename(remotePath));
1579
2099
  }
1580
2100
  return localPath;
1581
2101
  }
1582
2102
  async function syncWithSftpWithTimeout(alias, localPath, remotePath, direction, options) {
1583
2103
  const timeout = options.operationTimeout ?? 600_000;
1584
2104
  const controller = new AbortController();
2105
+ const accumulator = new DirectoryTransferAccumulator();
2106
+ const warnings = [];
1585
2107
  const operation = syncWithSftp(alias, localPath, remotePath, direction, {
1586
2108
  ...options,
1587
2109
  signal: controller.signal,
1588
- });
2110
+ }, accumulator, warnings);
1589
2111
  let timer;
1590
2112
  const timedOut = new Promise((resolve) => {
1591
2113
  timer = setTimeout(() => {
1592
2114
  controller.abort(new SftpOperationTimeoutError(timeout));
1593
2115
  resolve({
2116
+ ...buildDirectorySyncResult(accumulator.toResult(), [...warnings]),
1594
2117
  success: false,
1595
2118
  method: 'sftp',
1596
2119
  operationStatus: 'unknown',
@@ -1606,9 +2129,8 @@ async function syncWithSftpWithTimeout(alias, localPath, remotePath, direction,
1606
2129
  }
1607
2130
  return result;
1608
2131
  }
1609
- async function syncWithSftp(alias, localPath, remotePath, direction, options) {
2132
+ async function syncWithSftp(alias, localPath, remotePath, direction, options, accumulator, warnings) {
1610
2133
  throwIfAborted(options.signal);
1611
- const warnings = [];
1612
2134
  if (options.delete) {
1613
2135
  warnings.push('delete option is not supported in SFTP mode (requires rsync)');
1614
2136
  }
@@ -1666,10 +2188,10 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1666
2188
  };
1667
2189
  }
1668
2190
  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);
2191
+ const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal, '', options.remotePathStyle, undefined, accumulator);
1670
2192
  return buildDirectorySyncResult(result, warnings);
1671
2193
  }
1672
- const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath);
2194
+ const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath, options.remotePathStyle);
1673
2195
  const existed = await remoteExists(alias, targetRemotePath);
1674
2196
  const { size } = await uploadFile(alias, localPath, targetRemotePath, undefined, undefined, undefined, options.signal, options.followSymlinks === true);
1675
2197
  return {
@@ -1678,7 +2200,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1678
2200
  };
1679
2201
  }
1680
2202
  // download
1681
- const info = await getFileInfo(alias, remotePath);
2203
+ const info = await getFileInfo(alias, remotePath, undefined, options.remotePathStyle);
1682
2204
  if (info.isDirectory && options.recursive === false) {
1683
2205
  return {
1684
2206
  success: false,
@@ -1693,10 +2215,10 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1693
2215
  files: 0,
1694
2216
  directories: 0,
1695
2217
  bytes: 0,
1696
- }, 0, options.signal);
2218
+ }, 0, options.signal, '', options.remotePathStyle, accumulator);
1697
2219
  return buildDirectorySyncResult(result, warnings);
1698
2220
  }
1699
- const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath);
2221
+ const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath, options.remotePathStyle);
1700
2222
  const existed = fs.existsSync(targetLocalPath);
1701
2223
  const { size } = await downloadFile(alias, remotePath, targetLocalPath, undefined, undefined, options.signal);
1702
2224
  return {
@@ -1705,35 +2227,27 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options) {
1705
2227
  };
1706
2228
  }
1707
2229
  catch (err) {
1708
- if (err instanceof SftpOperationTimeoutError) {
1709
- return {
1710
- success: false,
1711
- method: 'sftp',
1712
- operationStatus: 'unknown',
1713
- timedOut: true,
1714
- retryable: true,
1715
- stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1716
- output: err.message,
1717
- };
1718
- }
2230
+ const result = buildDirectorySyncResult(accumulator.toResult(), warnings);
2231
+ const timedOut = err instanceof SftpOperationTimeoutError;
1719
2232
  return {
2233
+ ...result,
1720
2234
  success: false,
1721
- method: 'sftp',
1722
- operationStatus: 'failed',
1723
- stats: { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 1 },
1724
- output: err instanceof Error ? err.message : String(err),
2235
+ operationStatus: timedOut ? 'unknown' : 'failed',
2236
+ timedOut: timedOut || undefined,
2237
+ retryable: timedOut || undefined,
2238
+ stats: { ...result.stats, failed: Math.max(1, result.stats.failed) },
2239
+ output: [result.output, err instanceof Error ? err.message : String(err)].filter(Boolean).join('; '),
1725
2240
  };
1726
2241
  }
1727
2242
  }
1728
2243
  /**
1729
2244
  * 递归上传目录
1730
2245
  */
1731
- async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '') {
2246
+ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', inspectNames, accumulator = new DirectoryTransferAccumulator()) {
1732
2247
  throwIfAborted(signal);
1733
- const accumulator = new DirectoryTransferAccumulator();
1734
2248
  recordSftpDirectory(traversal, depth, localPath);
1735
- const ownSftp = !sharedSftp;
1736
- const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
2249
+ const ownSftp = !sharedSftp && !inspectNames;
2250
+ const sftp = inspectNames ? undefined : (sharedSftp ?? (await getSftpWithinDeadline(alias)));
1737
2251
  const activeDirectories = (traversal.activeDirectories ??= new Set());
1738
2252
  const realPath = fs.realpathSync(localPath);
1739
2253
  if (activeDirectories.has(realPath)) {
@@ -1746,7 +2260,9 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1746
2260
  activeDirectories.add(realPath);
1747
2261
  try {
1748
2262
  validateLocalPathAgainstAllowList(localPath);
1749
- await mkdir(alias, remotePath, true, sftp);
2263
+ if (!inspectNames) {
2264
+ await mkdir(alias, remotePath, true, sftp, undefined, style);
2265
+ }
1750
2266
  throwIfAborted(signal);
1751
2267
  const items = fs.readdirSync(localPath);
1752
2268
  // 先分类:目录串行(递归会自己并发文件);文件并发上传,避免单 SSH session 上 channel 过多
@@ -1760,11 +2276,17 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1760
2276
  const itemLocalPath = path.join(localPath, item);
1761
2277
  const stats = followSymlinks ? fs.statSync(itemLocalPath) : fs.lstatSync(itemLocalPath);
1762
2278
  if (!followSymlinks && stats.isSymbolicLink()) {
1763
- console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
2279
+ if (!inspectNames) {
2280
+ console.warn(`[ssh_sync] skipping symlink: ${itemLocalPath}`);
2281
+ }
1764
2282
  accumulator.addSkippedSymlink();
1765
2283
  continue;
1766
2284
  }
1767
2285
  if (stats.isDirectory()) {
2286
+ if (activeDirectories.has(fs.realpathSync(itemLocalPath))) {
2287
+ accumulator.addSkippedSymlink();
2288
+ continue;
2289
+ }
1768
2290
  subDirItems.push(item);
1769
2291
  }
1770
2292
  else if (stats.isFile()) {
@@ -1775,26 +2297,30 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1775
2297
  accumulator.addSkippedUnsupported(itemRelativePath);
1776
2298
  }
1777
2299
  }
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
- });
2300
+ if (inspectNames) {
2301
+ inspectNames(remotePath, [...subDirItems, ...fileItems.map(({ name }) => name)]);
2302
+ }
2303
+ else {
2304
+ // 文件并发上传
2305
+ await runWithConcurrency(fileItems, SFTP_PARALLEL_LIMIT, async ({ name, stats }) => {
2306
+ const itemLocalPath = path.join(localPath, name);
2307
+ const itemRemotePath = remoteJoin(style, remotePath, name);
2308
+ const existed = await sftpExists(sftp, itemRemotePath);
2309
+ try {
2310
+ await uploadFile(alias, itemLocalPath, itemRemotePath, undefined, sftp, undefined, signal, followSymlinks);
2311
+ accumulator.addFile(stats.size, existed);
2312
+ }
2313
+ catch (error) {
2314
+ accumulator.addFailed();
2315
+ throw error;
2316
+ }
2317
+ });
2318
+ }
1792
2319
  // 子目录串行递归
1793
2320
  for (const item of subDirItems) {
1794
2321
  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);
1797
- accumulator.merge(result);
2322
+ const itemRemotePath = remoteJoin(style, remotePath, item);
2323
+ await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item, style, inspectNames, accumulator);
1798
2324
  }
1799
2325
  }
1800
2326
  finally {
@@ -1808,18 +2334,41 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
1808
2334
  /**
1809
2335
  * 递归下载目录
1810
2336
  */
1811
- async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '') {
2337
+ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', accumulator = new DirectoryTransferAccumulator()) {
1812
2338
  throwIfAborted(signal);
1813
- const accumulator = new DirectoryTransferAccumulator();
1814
2339
  recordSftpDirectory(traversal, depth, remotePath);
1815
2340
  const ownSftp = !sharedSftp;
1816
2341
  const sftp = sharedSftp ?? (await getSftpWithinDeadline(alias));
1817
2342
  try {
2343
+ const items = await listDir(alias, remotePath, true, sftp, undefined, style);
2344
+ throwIfAborted(signal);
2345
+ if (process.platform === 'win32') {
2346
+ const localNames = new Map((fs.existsSync(localPath) ? fs.readdirSync(localPath) : []).map((name) => [
2347
+ name.normalize('NFC').toLowerCase(),
2348
+ name,
2349
+ ]));
2350
+ const remoteNames = new Set();
2351
+ for (const item of items) {
2352
+ const relativeName = relativeBase ? `${relativeBase}/${item.name}` : item.name;
2353
+ if (matchesDirectoryExclude(relativeName, exclude) || (!item.isDirectory && !item.isFile)) {
2354
+ continue;
2355
+ }
2356
+ if (/[<>:"/\\|?*]/.test(item.name) ||
2357
+ [...item.name].some((char) => char.charCodeAt(0) < 32) ||
2358
+ /[. ]$/.test(item.name) ||
2359
+ /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i.test(item.name)) {
2360
+ throw new Error(`Remote entry cannot be represented as a Windows filename: ${relativeName}`);
2361
+ }
2362
+ const key = item.name.normalize('NFC').toLowerCase();
2363
+ if (remoteNames.has(key) || (localNames.has(key) && localNames.get(key) !== item.name)) {
2364
+ throw new Error(`Windows local filename collision at ${relativeName}`);
2365
+ }
2366
+ remoteNames.add(key);
2367
+ }
2368
+ }
1818
2369
  if (!fs.existsSync(localPath)) {
1819
2370
  fs.mkdirSync(localPath, { recursive: true });
1820
2371
  }
1821
- const items = await listDir(alias, remotePath, true, sftp);
1822
- throwIfAborted(signal);
1823
2372
  // 分类:文件并发下载,目录串行递归
1824
2373
  const fileItems = [];
1825
2374
  const dirItems = [];
@@ -1857,8 +2406,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1857
2406
  });
1858
2407
  for (const item of dirItems) {
1859
2408
  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);
1861
- accumulator.merge(result);
2409
+ await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name, style, accumulator);
1862
2410
  }
1863
2411
  for (const item of symlinkItems) {
1864
2412
  console.warn(`[ssh_sync] skipping remote symlink: ${item.path}`);
@@ -1872,22 +2420,3 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
1872
2420
  }
1873
2421
  return accumulator.toResult();
1874
2422
  }
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
- }