@pyrokine/mcp-ssh 2.3.2 → 2.4.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.
@@ -0,0 +1,485 @@
1
+ import { createHash } from 'crypto';
2
+ import * as fs from 'fs';
3
+ import * as path from 'path';
4
+ import { escapeShellArg } from './tools/utils.js';
5
+ export const DIRECTORY_VERIFY_MAX_ENTRIES = 50_000;
6
+ export const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
7
+ export const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES = 256 * 1024 * 1024;
8
+ export const DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
9
+ export const DIRECTORY_VERIFY_MAX_FILE_BYTES = 4 * 1024 * 1024 * 1024;
10
+ export const DIRECTORY_VERIFY_MAX_TOTAL_BYTES = 16 * 1024 * 1024 * 1024;
11
+ function rootHash(entries) {
12
+ const hash = createHash('sha256');
13
+ for (const entry of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
14
+ hash.update(JSON.stringify({
15
+ path: entry.path,
16
+ type: entry.type,
17
+ size: entry.size,
18
+ sha256: entry.sha256,
19
+ }));
20
+ hash.update('\n');
21
+ }
22
+ return hash.digest('hex');
23
+ }
24
+ async function hashFile(filePath) {
25
+ const hash = createHash('sha256');
26
+ await new Promise((resolve, reject) => {
27
+ const stream = fs.createReadStream(filePath);
28
+ stream.on('data', (chunk) => hash.update(chunk));
29
+ stream.on('error', reject);
30
+ stream.on('end', resolve);
31
+ });
32
+ return hash.digest('hex');
33
+ }
34
+ function globPatternToRegExp(pattern) {
35
+ let expression = '';
36
+ for (let index = 0; index < pattern.length; ++index) {
37
+ const character = pattern[index];
38
+ if (character === '*' && pattern[index + 1] === '*') {
39
+ expression += '.*';
40
+ ++index;
41
+ }
42
+ else if (character === '*') {
43
+ expression += '[^/]*';
44
+ }
45
+ else if (character === '?') {
46
+ expression += '[^/]';
47
+ }
48
+ else {
49
+ expression += character.replace(/[.+^${}()|[\]\\]/g, '\\$&');
50
+ }
51
+ }
52
+ return new RegExp(`^${expression}$`);
53
+ }
54
+ const excludePatternCache = new Map();
55
+ export function matchesDirectoryExclude(relativePath, patterns) {
56
+ const normalizedPath = relativePath.replace(/^\.\//, '').replace(/^\//, '');
57
+ const basename = path.posix.basename(normalizedPath);
58
+ return Boolean(patterns?.some((pattern) => {
59
+ const normalizedPattern = pattern.replace(/^\//, '');
60
+ let regex = excludePatternCache.get(normalizedPattern);
61
+ if (!regex) {
62
+ regex = globPatternToRegExp(normalizedPattern);
63
+ excludePatternCache.set(normalizedPattern, regex);
64
+ }
65
+ return regex.test(normalizedPattern.includes('/') ? normalizedPath : basename);
66
+ }));
67
+ }
68
+ export async function createLocalDirectoryManifest(rootPath, request, exclude, followSymlinks = false) {
69
+ const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
70
+ const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
71
+ const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
72
+ const rootStats = await fs.promises.stat(rootPath);
73
+ if (!rootStats.isDirectory()) {
74
+ throw new Error(`directory verification root is not a directory: ${rootPath}`);
75
+ }
76
+ const entries = [
77
+ {
78
+ path: '.',
79
+ type: 'directory',
80
+ size: 0,
81
+ mode: (rootStats.mode & 0o777).toString(8).padStart(4, '0'),
82
+ owner: String(rootStats.uid),
83
+ },
84
+ ];
85
+ const activeDirectories = new Set();
86
+ let hashedBytes = 0;
87
+ let skippedSymlinks = 0;
88
+ let skippedUnsupported = 0;
89
+ const unsupportedSamples = [];
90
+ let limitReason;
91
+ const visit = async (currentPath, relativeBase) => {
92
+ const realPath = await fs.promises.realpath(currentPath);
93
+ if (activeDirectories.has(realPath)) {
94
+ skippedSymlinks++;
95
+ return;
96
+ }
97
+ activeDirectories.add(realPath);
98
+ try {
99
+ for (const name of await fs.promises.readdir(currentPath)) {
100
+ const relativePath = relativeBase ? `${relativeBase}/${name}` : name;
101
+ if (matchesDirectoryExclude(relativePath, exclude)) {
102
+ continue;
103
+ }
104
+ if (entries.length >= maxEntries) {
105
+ limitReason = 'entries';
106
+ return;
107
+ }
108
+ const fullPath = path.join(currentPath, name);
109
+ const linkStats = await fs.promises.lstat(fullPath);
110
+ if (linkStats.isSymbolicLink() && !followSymlinks) {
111
+ skippedSymlinks++;
112
+ continue;
113
+ }
114
+ const stats = linkStats.isSymbolicLink() ? await fs.promises.stat(fullPath) : linkStats;
115
+ if (stats.isDirectory()) {
116
+ entries.push({
117
+ path: relativePath,
118
+ type: 'directory',
119
+ size: 0,
120
+ mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
121
+ owner: String(stats.uid),
122
+ });
123
+ await visit(fullPath, relativePath);
124
+ if (limitReason) {
125
+ return;
126
+ }
127
+ }
128
+ else if (stats.isFile()) {
129
+ let sha256;
130
+ if (request.sha256) {
131
+ if (stats.size > maxFileBytes) {
132
+ limitReason = 'file_bytes';
133
+ return;
134
+ }
135
+ if (hashedBytes + stats.size > maxTotalBytes) {
136
+ limitReason = 'total_bytes';
137
+ return;
138
+ }
139
+ hashedBytes += stats.size;
140
+ sha256 = await hashFile(fullPath);
141
+ }
142
+ entries.push({
143
+ path: relativePath,
144
+ type: 'file',
145
+ size: stats.size,
146
+ mode: (stats.mode & 0o777).toString(8).padStart(4, '0'),
147
+ owner: String(stats.uid),
148
+ sha256,
149
+ });
150
+ }
151
+ else {
152
+ ++skippedUnsupported;
153
+ if (unsupportedSamples.length < 10) {
154
+ unsupportedSamples.push(relativePath);
155
+ }
156
+ }
157
+ }
158
+ }
159
+ finally {
160
+ activeDirectories.delete(realPath);
161
+ }
162
+ };
163
+ await visit(rootPath, '');
164
+ return {
165
+ entries,
166
+ count: entries.length,
167
+ rootSha256: rootHash(entries),
168
+ limited: limitReason !== undefined,
169
+ limitReason,
170
+ skippedSymlinks,
171
+ skippedUnsupported,
172
+ unsupportedSamples,
173
+ };
174
+ }
175
+ export function createEmptyDirectoryManifest() {
176
+ const entries = [];
177
+ return {
178
+ entries,
179
+ count: 0,
180
+ rootSha256: rootHash(entries),
181
+ limited: false,
182
+ skippedSymlinks: 0,
183
+ skippedUnsupported: 0,
184
+ unsupportedSamples: [],
185
+ };
186
+ }
187
+ function buildExcludeRegexes(exclude) {
188
+ const pathPatterns = [];
189
+ const basenamePatterns = [];
190
+ for (const pattern of exclude ?? []) {
191
+ const normalized = pattern.replace(/^\//, '');
192
+ const expression = globPatternToRegExp(normalized).source.replace(/^\^|\$$/g, '');
193
+ if (normalized.includes('/')) {
194
+ pathPatterns.push(expression);
195
+ }
196
+ else {
197
+ basenamePatterns.push(expression);
198
+ }
199
+ }
200
+ return {
201
+ path: pathPatterns.length > 0 ? `^(${pathPatterns.join('|')})$` : undefined,
202
+ basename: basenamePatterns.length > 0 ? `^(${basenamePatterns.join('|')})$` : undefined,
203
+ };
204
+ }
205
+ export function buildRemoteDirectoryManifestCommand(rootPath, request, exclude, followSymlinks = false) {
206
+ const maxEntries = Math.min(request.maxEntries ?? 10_000, DIRECTORY_VERIFY_MAX_ENTRIES);
207
+ const maxFileBytes = Math.min(request.maxFileBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES, DIRECTORY_VERIFY_MAX_FILE_BYTES);
208
+ const maxTotalBytes = Math.min(request.maxTotalBytes ?? DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES, DIRECTORY_VERIFY_MAX_TOTAL_BYTES);
209
+ const normalizedRoot = rootPath.replace(/\/+$/, '') || '/';
210
+ const root = escapeShellArg(normalizedRoot);
211
+ const includeHash = request.sha256 === true;
212
+ const excludeRegexes = buildExcludeRegexes(exclude);
213
+ const pathExcludeRegex = excludeRegexes.path ? escapeShellArg(excludeRegexes.path) : undefined;
214
+ const basenameExcludeRegex = excludeRegexes.basename ? escapeShellArg(excludeRegexes.basename) : undefined;
215
+ const findFollow = followSymlinks ? '-L' : '-H';
216
+ const script = [
217
+ 'set -euo pipefail',
218
+ 'export LC_ALL=C',
219
+ `root=${root}`,
220
+ '[ -d "$root" ] || { printf "remote directory does not exist\\n" >&2; exit 3; }',
221
+ 'count=0',
222
+ 'hashed_bytes=0',
223
+ 'skipped_symlinks=0',
224
+ 'skipped_unsupported=0',
225
+ 'unsupported_samples=()',
226
+ 'excluded_dirs=()',
227
+ 'while IFS= read -r -d "" item; do',
228
+ ' if [ "$item" = "__MCP_FIND_ERROR__" ]; then exit 4; fi',
229
+ ' if [ "$item" = "$root" ]; then rel=.; elif [ "$root" = / ]; then rel=${item#/}; else rel=${item#"$root"/}; fi',
230
+ ' for excluded_dir in "${excluded_dirs[@]}"; do case "$rel" in "$excluded_dir"/*) continue 2;; esac; done',
231
+ pathExcludeRegex
232
+ ? ` if [ "$rel" != . ] && printf %s "$rel" | grep -Eq -- ${pathExcludeRegex}; then [ -d "$item" ] && excluded_dirs+=("$rel"); continue; fi`
233
+ : ' :',
234
+ basenameExcludeRegex
235
+ ? ` base=${'${rel##*/}'}; if [ "$rel" != . ] && printf %s "$base" | grep -Eq -- ${basenameExcludeRegex}; then [ -d "$item" ] && excluded_dirs+=("$rel"); continue; fi`
236
+ : ' :',
237
+ followSymlinks
238
+ ? ' :'
239
+ : ' if [ "$rel" != . ] && [ -L "$item" ]; then skipped_symlinks=$((skipped_symlinks + 1)); continue; fi',
240
+ ' if [ -d "$item" ]; then type=directory; size=0; elif [ -f "$item" ]; then type=file; size=$(stat -c %s -- "$item"); else skipped_unsupported=$((skipped_unsupported + 1)); if [ "${#unsupported_samples[@]}" -lt 10 ]; then unsupported_samples+=("$(printf %s "$rel" | base64 | tr -d "\\n")"); fi; continue; fi',
241
+ ' count=$((count + 1))',
242
+ ` if [ "$count" -gt ${maxEntries} ]; then printf '__MCP_LIMIT__\\tentries\\n'; break; fi`,
243
+ ' raw_mode=$(stat -c %a -- "$item")',
244
+ ' mode=$(printf \'%04o\' "$((8#$raw_mode & 0777))")',
245
+ ' owner=$(stat -c %u -- "$item")',
246
+ includeHash
247
+ ? ` if [ "$type" = file ]; then
248
+ if [ "$size" -gt ${maxFileBytes} ]; then printf '__MCP_LIMIT__\\tfile_bytes\\n'; break; fi
249
+ next_hashed_bytes=$((hashed_bytes + size))
250
+ if [ "$next_hashed_bytes" -gt ${maxTotalBytes} ]; then printf '__MCP_LIMIT__\\ttotal_bytes\\n'; break; fi
251
+ hashed_bytes=$next_hashed_bytes
252
+ digest=$(sha256sum -- "$item" | cut -d " " -f 1)
253
+ else digest=; fi`
254
+ : ' digest=',
255
+ ' encoded=$(printf %s "$rel" | base64 | tr -d "\\n")',
256
+ ' printf "%s\\t%s\\t%s\\t%s\\t%s\\t%s\\n" "$encoded" "$type" "$size" "$mode" "$owner" "$digest"',
257
+ `done < <({ find ${findFollow} "$root" -print0 || printf '%s\\0' '__MCP_FIND_ERROR__'; })`,
258
+ 'printf "__MCP_SKIPPED_SYMLINKS__\\t%s\\n" "$skipped_symlinks"',
259
+ 'printf "__MCP_SKIPPED_UNSUPPORTED__\\t%s\\n" "$skipped_unsupported"',
260
+ 'for sample in "${unsupported_samples[@]}"; do printf "__MCP_UNSUPPORTED_SAMPLE__\\t%s\\n" "$sample"; done',
261
+ ].join('\n');
262
+ return `bash -c ${escapeShellArg(script)}`;
263
+ }
264
+ function decodeManifestPath(encodedPath) {
265
+ const decodedPath = Buffer.from(encodedPath, 'base64').toString('utf-8');
266
+ if (!encodedPath ||
267
+ !/^[A-Za-z0-9+/]+={0,2}$/.test(encodedPath) ||
268
+ encodedPath.length % 4 !== 0 ||
269
+ !decodedPath ||
270
+ decodedPath.length > 4096 ||
271
+ decodedPath.includes('\0') ||
272
+ path.posix.isAbsolute(decodedPath) ||
273
+ decodedPath.split('/').includes('..')) {
274
+ throw new Error('remote directory verification returned malformed manifest path');
275
+ }
276
+ return decodedPath;
277
+ }
278
+ export function parseRemoteDirectoryManifest(output) {
279
+ const entries = [];
280
+ const paths = new Set();
281
+ let skippedSymlinks = 0;
282
+ let skippedUnsupported = 0;
283
+ const unsupportedSamples = [];
284
+ let limitReason;
285
+ for (const line of output.split('\n')) {
286
+ if (!line) {
287
+ continue;
288
+ }
289
+ if (line.startsWith('__MCP_LIMIT__\t')) {
290
+ const reason = line.slice('__MCP_LIMIT__\t'.length);
291
+ if (reason === 'entries' || reason === 'file_bytes' || reason === 'total_bytes') {
292
+ limitReason = reason;
293
+ continue;
294
+ }
295
+ throw new Error('remote directory verification returned an unknown limit reason');
296
+ }
297
+ if (line.startsWith('__MCP_SKIPPED_SYMLINKS__\t')) {
298
+ const count = Number(line.slice('__MCP_SKIPPED_SYMLINKS__\t'.length));
299
+ if (!Number.isSafeInteger(count) || count < 0) {
300
+ throw new Error('remote directory verification returned an invalid symlink count');
301
+ }
302
+ skippedSymlinks = count;
303
+ continue;
304
+ }
305
+ if (line.startsWith('__MCP_SKIPPED_UNSUPPORTED__\t')) {
306
+ const count = Number(line.slice('__MCP_SKIPPED_UNSUPPORTED__\t'.length));
307
+ if (!Number.isSafeInteger(count) || count < 0) {
308
+ throw new Error('remote directory verification returned an invalid unsupported entry count');
309
+ }
310
+ skippedUnsupported = count;
311
+ continue;
312
+ }
313
+ if (line.startsWith('__MCP_UNSUPPORTED_SAMPLE__\t')) {
314
+ const encodedPath = line.slice('__MCP_UNSUPPORTED_SAMPLE__\t'.length);
315
+ const samplePath = decodeManifestPath(encodedPath);
316
+ if (unsupportedSamples.length >= 10) {
317
+ throw new Error('remote directory verification returned too many unsupported entry samples');
318
+ }
319
+ unsupportedSamples.push(samplePath);
320
+ continue;
321
+ }
322
+ const fields = line.split('\t');
323
+ if (fields.length !== 6) {
324
+ throw new Error('remote directory verification returned malformed manifest data');
325
+ }
326
+ const [encodedPath, type, sizeText, mode, owner, sha256] = fields;
327
+ const size = Number(sizeText);
328
+ const entryPath = decodeManifestPath(encodedPath);
329
+ if (paths.has(entryPath) ||
330
+ (type !== 'file' && type !== 'directory') ||
331
+ !Number.isSafeInteger(size) ||
332
+ size < 0 ||
333
+ !/^0[0-7]{3}$/.test(mode) ||
334
+ !/^\d+$/.test(owner) ||
335
+ (sha256 !== undefined && sha256 !== '' && !/^[a-f0-9]{64}$/.test(sha256))) {
336
+ throw new Error('remote directory verification returned malformed manifest data');
337
+ }
338
+ paths.add(entryPath);
339
+ entries.push({
340
+ path: entryPath,
341
+ type,
342
+ size,
343
+ mode,
344
+ owner,
345
+ sha256: sha256 || undefined,
346
+ });
347
+ }
348
+ return {
349
+ entries,
350
+ count: entries.length,
351
+ rootSha256: rootHash(entries),
352
+ limited: limitReason !== undefined,
353
+ limitReason,
354
+ skippedSymlinks,
355
+ skippedUnsupported,
356
+ unsupportedSamples,
357
+ };
358
+ }
359
+ export function compareDirectoryManifests(expected, actual, request, deletionBaseline) {
360
+ if (expected.limited || actual.limited || (request.deletions && deletionBaseline?.limited)) {
361
+ return {
362
+ kind: 'directory',
363
+ skipped: true,
364
+ reason: 'directory verification resource limit reached',
365
+ expectedCount: expected.count,
366
+ actualCount: actual.count,
367
+ expectedLimitReason: expected.limitReason,
368
+ actualLimitReason: actual.limitReason,
369
+ deletionBaselineLimitReason: deletionBaseline?.limitReason,
370
+ };
371
+ }
372
+ if (expected.skippedSymlinks > 0 ||
373
+ actual.skippedSymlinks > 0 ||
374
+ (request.deletions && (deletionBaseline?.skippedSymlinks ?? 0) > 0)) {
375
+ return {
376
+ kind: 'directory',
377
+ skipped: true,
378
+ reason: 'directory verification skipped symbolic links; set followSymlinks=true to verify link targets',
379
+ expectedSkippedSymlinks: expected.skippedSymlinks,
380
+ actualSkippedSymlinks: actual.skippedSymlinks,
381
+ deletionBaselineSkippedSymlinks: deletionBaseline?.skippedSymlinks,
382
+ };
383
+ }
384
+ if (expected.skippedUnsupported > 0 ||
385
+ actual.skippedUnsupported > 0 ||
386
+ (request.deletions && (deletionBaseline?.skippedUnsupported ?? 0) > 0)) {
387
+ return {
388
+ kind: 'directory',
389
+ skipped: true,
390
+ reason: 'directory verification skipped unsupported filesystem entries',
391
+ expectedSkippedUnsupported: expected.skippedUnsupported,
392
+ actualSkippedUnsupported: actual.skippedUnsupported,
393
+ deletionBaselineSkippedUnsupported: deletionBaseline?.skippedUnsupported,
394
+ expectedUnsupportedSamples: expected.unsupportedSamples,
395
+ actualUnsupportedSamples: actual.unsupportedSamples,
396
+ deletionBaselineUnsupportedSamples: deletionBaseline?.unsupportedSamples,
397
+ };
398
+ }
399
+ const expectedByPath = new Map(expected.entries.map((entry) => [entry.path, entry]));
400
+ const actualByPath = new Map(actual.entries.map((entry) => [entry.path, entry]));
401
+ const mismatches = [];
402
+ let missing = 0;
403
+ let stale = 0;
404
+ let typeMismatch = 0;
405
+ let ownerMismatch = 0;
406
+ let modeMismatch = 0;
407
+ let contentMismatch = 0;
408
+ const addMismatch = (value) => {
409
+ if (mismatches.length < DIRECTORY_VERIFY_MAX_MISMATCHES) {
410
+ mismatches.push(value);
411
+ }
412
+ };
413
+ for (const [entryPath, expectedEntry] of expectedByPath) {
414
+ const actualEntry = actualByPath.get(entryPath);
415
+ if (!actualEntry) {
416
+ missing++;
417
+ addMismatch({ path: entryPath, kind: 'missing' });
418
+ continue;
419
+ }
420
+ if (expectedEntry.type !== actualEntry.type) {
421
+ typeMismatch++;
422
+ addMismatch({ path: entryPath, kind: 'type', expected: expectedEntry.type, actual: actualEntry.type });
423
+ continue;
424
+ }
425
+ if (request.owner && expectedEntry.owner !== actualEntry.owner) {
426
+ ownerMismatch++;
427
+ addMismatch({ path: entryPath, kind: 'owner', expected: expectedEntry.owner, actual: actualEntry.owner });
428
+ }
429
+ if (request.mode && expectedEntry.mode !== actualEntry.mode) {
430
+ modeMismatch++;
431
+ addMismatch({ path: entryPath, kind: 'mode', expected: expectedEntry.mode, actual: actualEntry.mode });
432
+ }
433
+ if (request.sha256 && expectedEntry.sha256 !== actualEntry.sha256) {
434
+ contentMismatch++;
435
+ addMismatch({ path: entryPath, kind: 'sha256' });
436
+ }
437
+ }
438
+ for (const entryPath of actualByPath.keys()) {
439
+ if (!expectedByPath.has(entryPath)) {
440
+ stale++;
441
+ addMismatch({ path: entryPath, kind: 'stale' });
442
+ }
443
+ }
444
+ const deletionCandidates = deletionBaseline
445
+ ? deletionBaseline.entries
446
+ .map((entry) => entry.path)
447
+ .filter((entryPath) => entryPath !== '.' && !expectedByPath.has(entryPath))
448
+ : [];
449
+ const remainingDeletionCandidates = deletionCandidates.filter((entryPath) => actualByPath.has(entryPath));
450
+ for (const entryPath of remainingDeletionCandidates) {
451
+ addMismatch({ path: entryPath, kind: 'deletion_remaining' });
452
+ }
453
+ const checks = {
454
+ entries: missing === 0 && typeMismatch === 0,
455
+ count: request.count ? expected.count === actual.count : true,
456
+ sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 : true,
457
+ owner: request.owner ? ownerMismatch === 0 : true,
458
+ mode: request.mode ? modeMismatch === 0 : true,
459
+ deletions: request.deletions
460
+ ? deletionBaseline !== undefined && remainingDeletionCandidates.length === 0
461
+ : true,
462
+ staleFiles: request.staleFiles ? stale === 0 : true,
463
+ };
464
+ return {
465
+ kind: 'directory',
466
+ matched: Object.values(checks).every(Boolean),
467
+ checks,
468
+ expected: { count: expected.count, rootSha256: request.sha256 ? expected.rootSha256 : undefined },
469
+ actual: { count: actual.count, rootSha256: request.sha256 ? actual.rootSha256 : undefined },
470
+ summary: {
471
+ missing,
472
+ stale,
473
+ typeMismatch,
474
+ ownerMismatch,
475
+ modeMismatch,
476
+ contentMismatch,
477
+ deletionCandidates: deletionCandidates.length,
478
+ deletedEntries: deletionCandidates.length - remainingDeletionCandidates.length,
479
+ remainingDeletionCandidates: remainingDeletionCandidates.length,
480
+ },
481
+ deletionBaselineCaptured: deletionBaseline !== undefined,
482
+ mismatchSamples: mismatches,
483
+ mismatchSampleLimit: DIRECTORY_VERIFY_MAX_MISMATCHES,
484
+ };
485
+ }
@@ -3,9 +3,19 @@
3
3
  */
4
4
  import { SFTPWrapper } from 'ssh2';
5
5
  import { FileInfo, TransferProgress } from './types.js';
6
+ type RsyncProbeResult = {
7
+ available: boolean;
8
+ status: 'available' | 'unavailable' | 'timeout' | 'error' | 'skipped';
9
+ duration: number;
10
+ retryable: boolean;
11
+ exitCode?: number;
12
+ failureKind?: string;
13
+ error?: string;
14
+ reason?: string;
15
+ };
6
16
  /** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
7
17
  export declare function clearRsyncCache(alias?: string): void;
8
- export declare function probeLocalPath(localPath: string): {
18
+ export declare function probeLocalPath(localPath: string, followSymlinks?: boolean): {
9
19
  exists: boolean;
10
20
  inputPath: string;
11
21
  expandedPath: string;
@@ -39,14 +49,15 @@ export declare function probeLocalPath(localPath: string): {
39
49
  /**
40
50
  * 上传文件
41
51
  */
42
- export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper): Promise<{
52
+ export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal): Promise<{
43
53
  success: boolean;
44
54
  size: number;
55
+ createMode: string;
45
56
  }>;
46
57
  /**
47
58
  * 下载文件
48
59
  */
49
- export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper): Promise<{
60
+ export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal): Promise<{
50
61
  success: boolean;
51
62
  size: number;
52
63
  }>;
@@ -65,12 +76,16 @@ type ReadFileResult = {
65
76
  total_size: number;
66
77
  read_offset: number;
67
78
  read_bytes: number;
68
- remaining_bytes: number;
79
+ remaining_bytes?: number;
69
80
  sample_kind: ReadFileSampleKind;
70
81
  truncated: boolean;
71
82
  line_start?: number;
72
83
  line_end?: number;
84
+ eof?: boolean;
85
+ byte_limit_reached?: boolean;
86
+ final_line_terminated?: boolean;
73
87
  };
88
+ export declare function buildLineRangeAwkProgram(start: number, end: number): string;
74
89
  /**
75
90
  * 读取远程文件内容
76
91
  */
@@ -97,9 +112,21 @@ export declare function mkdir(alias: string, remotePath: string, recursive?: boo
97
112
  /**
98
113
  * 检查远程是否安装 rsync
99
114
  */
100
- export declare function checkRsync(alias: string): Promise<boolean>;
115
+ export declare function checkRsync(alias: string, timeout?: number): Promise<RsyncProbeResult>;
116
+ type SyncOptions = {
117
+ delete?: boolean;
118
+ dryRun?: boolean;
119
+ exclude?: string[];
120
+ recursive?: boolean;
121
+ followSymlinks?: boolean;
122
+ preflightTimeout?: number;
123
+ connectTimeout?: number;
124
+ operationTimeout?: number;
125
+ sourceIsDirectory?: boolean;
126
+ signal?: AbortSignal;
127
+ };
101
128
  /**
102
- * 智能文件同步(优先使用 rsync)
129
+ * 智能文件同步(根据连接能力选择 rsync 或 SFTP)
103
130
  *
104
131
  * @param alias SSH 连接别名
105
132
  * @param localPath 本地路径
@@ -107,13 +134,7 @@ export declare function checkRsync(alias: string): Promise<boolean>;
107
134
  * @param direction 同步方向:'upload' 或 'download'
108
135
  * @param options 同步选项
109
136
  */
110
- export declare function syncFiles(alias: string, localPath: string, remotePath: string, direction: 'upload' | 'download', options?: {
111
- delete?: boolean;
112
- dryRun?: boolean;
113
- exclude?: string[];
114
- recursive?: boolean;
115
- followSymlinks?: boolean;
116
- }): Promise<SyncResult>;
137
+ export declare function syncFiles(alias: string, localPath: string, remotePath: string, direction: 'upload' | 'download', options?: SyncOptions): Promise<SyncResult>;
117
138
  /**
118
139
  * 使用 SFTP 同步文件
119
140
  */
@@ -128,12 +149,34 @@ type SyncResult = {
128
149
  success: boolean;
129
150
  method: 'rsync' | 'sftp';
130
151
  transport?: 'rsync' | 'sftp';
152
+ selectedTransport?: 'rsync' | 'sftp';
153
+ decisionReason?: string;
154
+ rsyncProbe?: RsyncProbeResult;
155
+ fallbackReason?: string;
156
+ phaseDurations?: {
157
+ capabilityPreflight: number;
158
+ connect?: number;
159
+ operation: number;
160
+ total: number;
161
+ };
162
+ phaseStatus?: {
163
+ capabilityPreflight: 'completed' | 'failed';
164
+ connect: 'completed' | 'failed' | 'not_applicable';
165
+ operation: 'completed' | 'failed' | 'unknown';
166
+ };
167
+ connectDuration?: number;
168
+ connectStatus?: 'completed' | 'failed' | 'not_applicable';
169
+ operationStatus?: 'completed' | 'failed' | 'unknown';
170
+ timedOut?: boolean;
171
+ retryable?: boolean;
131
172
  direction?: 'upload' | 'download';
132
173
  dryRun?: boolean;
133
174
  duration?: number;
134
175
  filesTransferred?: number;
135
176
  bytesTransferred?: number;
136
177
  skippedSymlinks?: number;
178
+ skippedUnsupported?: number;
179
+ unsupportedSamples?: string[];
137
180
  stats?: SyncStats;
138
181
  verification?: Record<string, unknown>;
139
182
  commandSummary?: Record<string, unknown>;