@pyrokine/mcp-ssh 3.2.0 → 3.3.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/README.md CHANGED
@@ -231,7 +231,10 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
231
231
  OpenSSH
232
232
  entries also include `masterReused` and `identityStatus` . Use `detail=true` for connection details or `fields=[...]`
233
233
  to
234
- select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open state, so a dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and an explicitly chosen conflicting alias returns an error.
234
+ select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open
235
+ state, so dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias
236
+ that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and
237
+ an explicitly chosen conflicting alias returns an error.
235
238
 
236
239
  ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
237
240
  Direct,
@@ -256,12 +259,22 @@ pending, a channel returned by the delayed callback is destroyed before the conn
256
259
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
257
260
  | `ssh_exec_script` | Upload and run a temporary remote script |
258
261
 
259
- `ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as `interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and retains its cmd or PowerShell script invocation.
262
+ `ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as
263
+ `interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array
264
+ preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and
265
+ retains its cmd or PowerShell script invocation.
260
266
 
261
267
  For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
262
268
  correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
263
269
  execution. POSIX scripts retain their original content.
264
270
 
271
+ Host cancellation stops subsequent batch commands and queued parallel work, including batches with `stopOnError=false`.
272
+ It also stops later script upload, permission preparation, interpreter dispatch, and password input to a late sudo
273
+ channel.
274
+ Script cleanup uses a separate timeout of at most 30000 ms and removes only this request's temporary file.
275
+ `keepScript=true` retains a script once execution has started; an upload or preparation failure still cleans it up.
276
+ Canceling a request closes its own channels and leaves other requests and any reused OpenSSH master available.
277
+
265
278
  ### Tracked operations
266
279
 
267
280
  | Tool | Description |
@@ -285,7 +298,8 @@ execution. POSIX scripts retain their original content.
285
298
  | `ssh_mkdir` | Create remote directory |
286
299
  | `ssh_sync` | Smart sync with rsync (fallback to SFTP) |
287
300
 
288
- `ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
301
+ `ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream
302
+ with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
289
303
 
290
304
  ### PTY Sessions (Persistent Interactive Terminal)
291
305
 
@@ -454,7 +468,7 @@ that command. A reported exit signal is retained as `exitSignal` and classified
454
468
  ### Basic: Connect and Execute
455
469
 
456
470
  ```
457
- ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
471
+ ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
458
472
  ssh_exec(alias="myserver", command="ls -la /home")
459
473
  ssh_disconnect(alias="myserver")
460
474
  ```
@@ -492,6 +506,11 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
492
506
  from the session that was actually published. Concurrent calls reuse an alias only when the complete session
493
507
  configuration matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout
494
508
  settings. A conflicting pending or active connection is rejected even when its `user@host:port` identity is unchanged.
509
+ Conflict errors include `details.differingFields` with configuration field names only. OpenSSH configuration preparation
510
+ registers the requested alias, `configHost`, or initial endpoint. Disconnect cancels its owned `ssh -G` process and
511
+ prevents a later connection, including the preparation-to-connect handoff. A later connection can reuse the resolved
512
+ alias when `ssh -G` changes the hostname, user, or port.
513
+
495
514
  Missing templates include available template names when they can be loaded. Missing `configHost` returns SSH config
496
515
  candidates and suggests `ssh_config_list`.
497
516
 
@@ -503,12 +522,12 @@ Connect to internal server via jump host:
503
522
  ssh_connect(
504
523
  host="<internal-host>",
505
524
  user="root",
506
- keyPath="/home/.ssh/id_rsa",
525
+ keyPath="~/.ssh/id_rsa",
507
526
  alias="internal",
508
527
  jumpHost={
509
528
  host: "bastion.example.com",
510
529
  user: "admin",
511
- keyPath: "/home/.ssh/bastion_key"
530
+ keyPath: "~/.ssh/bastion_key"
512
531
  }
513
532
  )
514
533
  ```
@@ -518,7 +537,7 @@ ssh_connect(
518
537
  Perfect for scenarios where you SSH as root but need to run commands as another user:
519
538
 
520
539
  ```
521
- 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
540
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
522
541
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
523
542
  // Output: appuser
524
543
  ```
@@ -623,11 +642,12 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
623
642
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
624
643
  ```
625
644
 
626
- This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
627
- The
628
- `ssh_exec_script.timeout` value applies while uploading the temporary script, preparing its permissions, and running
629
- it.
630
- A stalled SFTP upload therefore ends on the requested timeout instead of using the default SFTP budget.
645
+ Log querying uses the general command and file tools. `ssh_exec_script.timeout` independently limits temporary script
646
+ upload, permission preparation, and execution. Explicit values use positive integer milliseconds, up to 3600000. Cleanup
647
+ has its own timeout: the smaller of the requested value and 30000 ms, or 30000 ms when omitted. Without an explicit
648
+ timeout, commands retain their 30000 ms default and SFTP retains 600000 ms. Host request deadlines apply separately.
649
+ Use `ssh_operation_start/status/read/cancel` for long observations: a host abort of synchronous exec leaves the remote
650
+ process's stop state unknown.
631
651
 
632
652
  ### With Environment Variables
633
653
 
@@ -635,7 +655,7 @@ A stalled SFTP upload therefore ends on the requested timeout instead of using t
635
655
  ssh_connect(
636
656
  host="<server-host>",
637
657
  user="root",
638
- keyPath="/home/.ssh/id_rsa",
658
+ keyPath="~/.ssh/id_rsa",
639
659
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
640
660
  )
641
661
  ```
@@ -649,7 +669,7 @@ No need to manage connections for single commands. `ssh_quick_exec` creates a un
649
669
  ssh_quick_exec(
650
670
  host="<server-host>",
651
671
  user="root",
652
- keyPath="/home/.ssh/id_rsa",
672
+ keyPath="~/.ssh/id_rsa",
653
673
  command="uptime"
654
674
  )
655
675
  ```
@@ -720,7 +740,9 @@ tools.
720
740
 
721
741
  `ssh_upload` , `ssh_download` , `ssh_read_file` , `ssh_write_file` , `ssh_list_dir` , `ssh_file_info` , and
722
742
  `ssh_mkdir` accept
723
- `timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. Timeouts retain local and
743
+ `timeout` for one SFTP operation. Downloads use one total deadline for transfer and failure diagnostics;
744
+ when time expires or the host cancels, remote probing stops and local diagnostics remain available. It defaults to
745
+ 10 minutes and accepts up to one hour. Timeouts retain local and
724
746
  remote probe diagnostics. Uploads and writes report `operationStatus="unknown"` when an
725
747
  OPEN, WRITE, or CLOSE request was dispatched without a completion reply. Explicit server refusal returns `failed` .
726
748
  Read-only upload preflight failures also return `failed` ,
@@ -842,9 +864,18 @@ mode. Directory sources reject `recursive=false`. Relative exclude patterns are
842
864
  source root; patterns without `/` match each basename. A trailing `/` restricts a pattern to directories:
843
865
  `provider/` skips directories with that basename and their contents while retaining regular files named `provider`.
844
866
 
845
- A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or `REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation behavior. Downloads create missing local parents; an rsync parent-preparation failure returns `failureStage="local_prepare"` before the transfer process starts.
867
+ A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a
868
+ file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or
869
+ `REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation
870
+ behavior. Downloads create missing local parents; a failure during rsync parent preparation returns
871
+ `failureStage="local_prepare"` before the transfer process starts.
846
872
 
847
- Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning, with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the client's absolute request deadline remain separate from progress-driven idle-timeout resets.
873
+ Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including
874
+ recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification
875
+ sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a
876
+ token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning,
877
+ with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the
878
+ client's absolute request deadline remain separate from progress-driven idle-timeout resets.
848
879
 
849
880
  For a regular file, `verify.sha256`, `verify.owner`, `verify.mode`, and Windows `verify.aclSddl` apply to the actual
850
881
  transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a
@@ -855,7 +886,7 @@ local and remote hashing, including the SFTP transport check. `verify.count`, `v
855
886
  require a directory source and are rejected before transfer for a file. A known source file larger than the requested
856
887
  hash budget is also rejected before transfer.
857
888
 
858
- Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root
889
+ Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root
859
890
  manifest,
860
891
  owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
861
892
  `verify.deletions=true` requires `delete=true` ; it records the destination before transfer and only checks whether
@@ -897,6 +928,29 @@ hash streams and stops later checks, while preserving completed file and byte co
897
928
  result
898
929
  has `success=false` and a timed-out verification outcome.
899
930
 
931
+ `bandwidthLimitKiBps` optionally limits aggregate transfer payload to KiB/s (1 KiB = 1024 bytes), for rsync and
932
+ SFTP, in either direction. Omit it for the existing unrestricted speed. Concurrent and recursive SFTP file
933
+ transfers share one limit; metadata and explicitly requested verification reads have separate costs. For example,
934
+ `ssh_sync(..., bandwidthLimitKiBps=1024)` requests 1 MiB/s.
935
+
936
+ Canceling a running rsync request terminates and waits for its own local process group, retaining reported
937
+ itemization/deletion counts and `lastProgress`. The result is `cancelled=true`, `operationStatus="unknown"`: remote
938
+ writes or deletions already dispatched require inspection. The alias, other requests, and the reused OpenSSH master
939
+ remain available.
940
+
941
+ Directory `checks` uses `null` for unrequested checks, `true` for an executed match, and `false` for a mismatch.
942
+ Top-level `verificationStatus` distinguishes unrequested, skipped, matched, mismatched, and error outcomes.
943
+ Explicit single-file SHA-256 verification reads each endpoint once and shares its digest with
944
+ `transportVerification`; byte limits and metadata stability checks still apply.
945
+
946
+ `ssh_mkdir` uses the SFTP login identity, independently of command `runAs`. Its response includes `loginUser`,
947
+ `runAs`, `creationIdentity="sftp_login"`, and actual numeric `owner`, `group`, `mode`, and `permissions`. Directory
948
+ access follows those returned permissions; the tool preserves ownership and permission policy. Once creation is
949
+ acknowledged, a later metadata read failure returns `success=true`, `operationStatus="completed"`, `retryable=false`,
950
+ and `metadataStatus="unavailable"`. `metadataError` contains the metadata failure in the existing error format,
951
+ including any timeout details; unavailable `owner`, `group`, `mode`, and `permissions` are omitted. Use `ssh_file_info`
952
+ to read metadata again. Directory creation failures retain their original error response.
953
+
900
954
  Directory root digests sort paths by their UTF-8 bytes, independent of enumeration order or locale. Case-distinct and
901
955
  Unicode NFC/NFD-distinct names remain separate entries; file names are not normalized.
902
956
 
@@ -1073,6 +1127,11 @@ also include
1073
1127
 
1074
1128
  ### Exec Options
1075
1129
 
1130
+ `ssh_exec(..., stdin="text")` sends UTF-8 input followed by EOF through ssh2 or the reused OpenSSH channel. Empty
1131
+ input sends EOF; omitting `stdin` retains existing behavior. Input stays out of the command string and
1132
+ input-delivery errors. A canceled request closes its own channel and returns remote state `unknown`, while the
1133
+ alias and master remain available. Commands that intentionally print their input still control their own output.
1134
+
1076
1135
  | Option | Type | Default | Description |
1077
1136
  | --------------- | ------- | ------------- | ------------------------------------------ |
1078
1137
  | `timeout` | number | 30000 | Command timeout in ms |
package/README_zh.md CHANGED
@@ -401,7 +401,7 @@ channel 关闭且没有收到退出状态时,返回 `exitCode=null`、`failure
401
401
  ### 基础:连接和执行
402
402
 
403
403
  ```
404
- ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
404
+ ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
405
405
  ssh_exec(alias="myserver", command="ls -la /home")
406
406
  ssh_disconnect(alias="myserver")
407
407
  ```
@@ -438,6 +438,19 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
438
438
  host、keepalive 和 timeout;pending 或 active 连接的配置冲突时会被拒绝,即使 `user@host:port`
439
439
  identity 相同,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
440
440
 
441
+ 配置冲突通过 `details.differingFields` 返回不同的配置字段名,字段值和凭证保持私有
442
+ OpenSSH 配置准备按请求 alias、`configHost` 或初始连接地址登记,disconnect 会终止本次自有 `ssh -G` 进程
443
+ 准备结束与连接登记之间发生的取消同样生效,`ssh -G` 改变主机名、用户或端口后,后续请求仍可重新连接解析后的 alias
444
+
445
+ `ssh_exec(..., stdin="text")` 经 ssh2 或复用的 OpenSSH 通道写入 UTF-8 内容并发送 EOF,空字符串只发送 EOF,省略时保持原输入行为,输入不写入命令字符串或输入发送错误,
446
+ 请求取消会关闭本次通道并返回远端状态 `unknown`,alias 与 master 继续可用,命令主动输出输入内容时按实际命令输出返回
447
+
448
+ 宿主取消请求后,批量命令与排队中的并行任务停止派发,`stopOnError=false` 同样生效
449
+ 脚本停止后续上传、权限准备和解释器执行,迟到的 sudo 通道不再接收密码
450
+ 脚本清理使用独立期限,最长 30000 ms,仅删除本次创建的临时文件
451
+ `keepScript=true` 在开始执行后保留脚本,上传或准备失败时仍执行清理
452
+ 取消仅关闭本次通道,其他请求及复用的 OpenSSH master 继续可用
453
+
441
454
  ### 跳板机
442
455
 
443
456
  通过跳板机连接内网服务器:
@@ -446,12 +459,12 @@ identity 相同,template 缺失时返回可用模板名,`configHost` 缺失
446
459
  ssh_connect(
447
460
  host="<internal-host>",
448
461
  user="root",
449
- keyPath="/home/.ssh/id_rsa",
462
+ keyPath="~/.ssh/id_rsa",
450
463
  alias="internal",
451
464
  jumpHost={
452
465
  host: "bastion.example.com",
453
466
  user: "admin",
454
- keyPath: "/home/.ssh/bastion_key"
467
+ keyPath: "~/.ssh/bastion_key"
455
468
  }
456
469
  )
457
470
  ```
@@ -461,7 +474,7 @@ ssh_connect(
461
474
  适用于 SSH 以 root 登录,但需要以其他用户执行命令的场景:
462
475
 
463
476
  ```
464
- 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
477
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
465
478
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
466
479
  // 输出: appuser
467
480
  ```
@@ -554,8 +567,9 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
554
567
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
555
568
  ```
556
569
 
557
- 日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具;`ssh_exec_script.timeout`
558
- 同时用于临时脚本上传、权限准备和执行阶段;SFTP 上传停滞时按请求的 timeout 结束,不再使用默认 SFTP 预算
570
+ 日志查询由通用命令和文件工具组合完成;`ssh_exec_script.timeout` 分别限制临时脚本上传、权限准备和执行阶段,每阶段独立计时,显式值为正整数,最大 3600000 ms;清理阶段独立计时,使用请求值与 30000 ms 中的较小值,省略参数时为 30000 ms
571
+
572
+ 未传显式超时时,命令保持 30000 ms 默认值,SFTP 保持 600000 ms 默认值,宿主请求期限独立生效;长时间观察使用 `ssh_operation_start/status/read/cancel`,同步 exec 被宿主中止时远端进程停止状态仍为未知
559
573
 
560
574
  ### 设置环境变量
561
575
 
@@ -563,7 +577,7 @@ ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=655
563
577
  ssh_connect(
564
578
  host="<server-host>",
565
579
  user="root",
566
- keyPath="/home/.ssh/id_rsa",
580
+ keyPath="~/.ssh/id_rsa",
567
581
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
568
582
  )
569
583
  ```
@@ -577,7 +591,7 @@ ssh_connect(
577
591
  ssh_quick_exec(
578
592
  host="<server-host>",
579
593
  user="root",
580
- keyPath="/home/.ssh/id_rsa",
594
+ keyPath="~/.ssh/id_rsa",
581
595
  command="uptime"
582
596
  )
583
597
  ```
@@ -638,7 +652,8 @@ user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB
638
652
  `next_offset`;行范围读取不执行远端 shell 工具
639
653
 
640
654
  `ssh_upload`、`ssh_download`、`ssh_read_file`、`ssh_write_file`、`ssh_list_dir`、`ssh_file_info` 和 `ssh_mkdir`
641
- 支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1 小时,超时保留本地与远端探测诊断
655
+ 支持 `timeout`,默认 10 分钟,最大 1 小时,下载与失败诊断共用一次总期限
656
+ 取消或超期后停止远端探测,保留原错误与本地详情,其他文件工具仍按单个 SFTP 操作计时
642
657
  上传和写入已派发 OPEN、WRITE 或 CLOSE 且丢失完成应答时,返回 `operationStatus="unknown"`;服务端明确拒绝返回 `failed`
643
658
  上传前只读探测失败也返回 `failed`,`failureStage="preflight"`,已确认写入字节为 0
644
659
  `failureStage`、受影响路径与 `acknowledgedBytes` 保留已确认进度,`retryable=false` 表示写入不会自动重放,重写前检查路径状态
@@ -751,7 +766,8 @@ ssh_sync(..., delete=true, verify={deletions: true})
751
766
  会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
752
767
  尾部 `/` 将模式限定为目录,`provider/` 排除每一级同名目录及其内容,保留名为 `provider` 的普通文件
753
768
 
754
- 单文件上传要求远端父目录存在,已知父目录缺失或父路径为文件时,在上传前返回 `failureStage="remote_prepare"` 和 `REMOTE_PARENT_NOT_FOUND` 或 `REMOTE_PARENT_NOT_DIRECTORY`
769
+ 单文件上传要求远端父目录存在,已知父目录缺失或父路径为文件时,在上传前返回 `failureStage="remote_prepare"` 和 `REMOTE_PARENT_NOT_FOUND` 或
770
+ `REMOTE_PARENT_NOT_DIRECTORY`
755
771
  缺失目录使用 `ssh_mkdir` 创建,目录同步仍按递归创建规则执行
756
772
  下载自动创建缺失的本地父目录,rsync 的本地准备失败在传输进程启动前返回 `failureStage="local_prepare"`
757
773
 
@@ -797,6 +813,20 @@ session 不经过这项凭证选择,也不回退到 SFTP,`preflightTimeout`
797
813
  校验超期会关闭本次持有的哈希流并停止后续检查,保留已完成的文件数、字节数与 `transferSuccess`,整体返回 `success=false`
798
814
  并明确报告校验超期
799
815
 
816
+ `bandwidthLimitKiBps` 为可选总传输限速,单位 KiB/s(1 KiB = 1024 bytes),适用于双向 rsync 和 SFTP,省略时保持原不限速行为,SFTP 并发文件和递归子目录共用本次限速,
817
+ 元数据和显式校验读取单独消耗资源,例如 `ssh_sync(..., bandwidthLimitKiBps=1024)` 请求 1 MiB/s
818
+
819
+ 取消运行中的 rsync 请求时,工具终止并等待本次自有本地进程组,保留已报告的文件明细、删除计数和 `lastProgress`,返回 `cancelled=true`、`operationStatus="unknown"`,
820
+ 已派发的远端写入和删除需要检查实际状态,alias、其他请求和复用的 OpenSSH master 保持可用
821
+
822
+ 目录 `checks` 使用 `null` 表示未请求,`true` 表示已执行且匹配,`false` 表示不匹配,顶层 `verificationStatus` 区分未请求、跳过、匹配、不匹配和错误,
823
+ 显式单文件 SHA-256 校验只完整读取每端一次,并将摘要共享给 `transportVerification`,保留字节预算及元数据稳定性检查
824
+
825
+ `ssh_mkdir` 使用 SFTP 登录身份,命令 `runAs` 单独生效,响应包含 `loginUser`、`runAs`、`creationIdentity="sftp_login"` 和实际数值 `owner`、
826
+ `group`、`mode` 及 `permissions`,后续目录访问由返回的权限决定,工具保持既有属主和权限策略
827
+ 创建已确认后,后续元信息读取失败时返回 `success=true`、`operationStatus="completed"`、`retryable=false` 和 `metadataStatus="unavailable"`,
828
+ `metadataError` 按既有错误格式保留元信息读取错误及超时详情,未取得的 `owner`、`group`、`mode` 和 `permissions` 省略,使用 `ssh_file_info` 重新读取元信息,目录创建自身失败时保留原错误响应
829
+
800
830
  目录根摘要按路径的 UTF-8 字节排序,不依赖枚举顺序或 locale,大小写不同与 NFC/NFD 不同的名称保持独立,不归一化文件名
801
831
 
802
832
  rsync 模式设置
@@ -123,7 +123,7 @@ function withoutQuotedText(command, shell) {
123
123
  const bodyStart = index;
124
124
  let bodyEnd = limit;
125
125
  let afterDelimiter = limit;
126
- // Delimiters are case-sensitive; input quotes never change shell quote state.
126
+ // Delimiters are case-sensitive; quoted input leaves the command parser quote state unchanged.
127
127
  for (let lineStart = index; lineStart < limit;) {
128
128
  let lineEnd = lineStart;
129
129
  let line = '';
@@ -512,15 +512,15 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
512
512
  throw new Error('OpenSSH manifest field exceeded its byte budget');
513
513
  }
514
514
  }, remaining());
515
- if (pending.length || fields.length) {
516
- throw new Error('OpenSSH manifest ended with incomplete metadata');
517
- }
518
515
  }
519
516
  catch (error) {
520
517
  if (error !== limit) {
521
518
  throw error;
522
519
  }
523
520
  }
521
+ if (!limitReason && (pending.length || fields.length)) {
522
+ throw new Error('OpenSSH manifest ended with incomplete metadata');
523
+ }
524
524
  if (!limitReason && request.sha256) {
525
525
  let hashedBytes = 0;
526
526
  for (const entry of entries) {
@@ -658,18 +658,18 @@ export function compareDirectoryManifests(expected, actual, request, deletionBas
658
658
  }
659
659
  const checks = {
660
660
  entries: missing === 0 && typeMismatch === 0,
661
- count: request.count ? expected.count === actual.count : true,
662
- sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 : true,
663
- owner: request.owner ? ownerMismatch === 0 : true,
664
- mode: request.mode ? modeMismatch === 0 : true,
661
+ count: request.count ? expected.count === actual.count : null,
662
+ sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 : null,
663
+ owner: request.owner ? ownerMismatch === 0 : null,
664
+ mode: request.mode ? modeMismatch === 0 : null,
665
665
  deletions: request.deletions
666
666
  ? deletionBaseline !== undefined && remainingDeletionCandidates.length === 0
667
- : true,
668
- staleFiles: request.staleFiles ? stale === 0 : true,
667
+ : null,
668
+ staleFiles: request.staleFiles ? stale === 0 : null,
669
669
  };
670
670
  return {
671
671
  kind: 'directory',
672
- matched: Object.values(checks).every(Boolean),
672
+ matched: Object.values(checks).every((value) => value !== false),
673
673
  checks,
674
674
  expected: { count: expected.count, rootSha256: request.sha256 ? expected.rootSha256 : undefined },
675
675
  actual: { count: actual.count, rootSha256: request.sha256 ? actual.rootSha256 : undefined },
@@ -91,7 +91,7 @@ export declare class UploadFileError extends Error {
91
91
  /**
92
92
  * 上传文件
93
93
  */
94
- export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean, timeout?: number): Promise<{
94
+ export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean, timeout?: number, throttle?: (bytes: number) => Promise<void>): Promise<{
95
95
  success: boolean;
96
96
  size: number;
97
97
  createMode: string;
@@ -99,7 +99,7 @@ export declare function uploadFile(alias: string, localPath: string, remotePath:
99
99
  /**
100
100
  * 下载文件
101
101
  */
102
- export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal, timeout?: number): Promise<{
102
+ export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal, timeout?: number, throttle?: (bytes: number) => Promise<void>): Promise<{
103
103
  success: boolean;
104
104
  size: number;
105
105
  atomic: true;
@@ -141,12 +141,12 @@ type ReadFileResult = {
141
141
  * 读取远程文件内容
142
142
  */
143
143
  export declare function readFile(alias: string, remotePath: string, options?: number | ReadFileOptions): Promise<ReadFileResult>;
144
- export declare function createEmptyRemoteFile(alias: string, remotePath: string, timeout?: number): Promise<void>;
145
- export declare function prepareWindowsRemotePrivateFile(alias: string, remotePath: string, timeout?: number, shellPath?: string): Promise<void>;
144
+ export declare function createEmptyRemoteFile(alias: string, remotePath: string, timeout?: number, signal?: AbortSignal): Promise<void>;
145
+ export declare function prepareWindowsRemotePrivateFile(alias: string, remotePath: string, timeout?: number, shellPath?: string, signal?: AbortSignal): Promise<void>;
146
146
  /**
147
147
  * 写入远程文件
148
148
  */
149
- export declare function writeFile(alias: string, remotePath: string, content: string, append?: boolean, timeout?: number): Promise<{
149
+ export declare function writeFile(alias: string, remotePath: string, content: string, append?: boolean, timeout?: number, signal?: AbortSignal): Promise<{
150
150
  success: boolean;
151
151
  size: number;
152
152
  }>;
@@ -173,6 +173,8 @@ type SyncOptions = {
173
173
  recursive?: boolean;
174
174
  followSymlinks?: boolean;
175
175
  verifySha256?: boolean;
176
+ bandwidthLimitKiBps?: number;
177
+ throttle?: (bytes: number) => Promise<void>;
176
178
  preflightTimeout?: number;
177
179
  connectTimeout?: number;
178
180
  operationTimeout?: number;
@@ -225,6 +227,8 @@ type SyncResult = {
225
227
  connectStatus?: 'completed' | 'failed' | 'not_applicable';
226
228
  operationStatus?: 'completed' | 'failed' | 'unknown';
227
229
  failureStage?: string;
230
+ cancelled?: boolean;
231
+ lastProgress?: TransferProgress;
228
232
  timedOut?: boolean;
229
233
  retryable?: boolean;
230
234
  direction?: 'upload' | 'download';