/sap-file-transfer

name: sap-file-transfer
description: |
  Transfers files between the local PC and the SAP application server, and
  lists app-server directories. Four modes: upload (CG3Z, PC -> app server),
  download (CG3Y, app server -> PC), list and exists (headless RFC via
  EPS2_GET_DIRECTORY_LISTING - no AL11 scraping). Text (ASC) or binary (BIN)
  transfer, explicit --overwrite flag, popup-guarded (overwrite Query,
  cannot-open-file Information popup), locale-independent (all outcomes read
  via control IDs + MessageType, verified for JA logons). Wires the SAP GUI
  Security precheck/sidecar around the local-file IO. Closes the
  file-interface test loop: upload test input -> /sap-run-report -> list ->
  download output -> diff against the spec's expected output (golden rows /
  Mapping (File Out)). No transport request involved - this skill touches
  no repository object.
  Typical asks: "upload <file> to the SAP server", "download /tmp/x from S4D",
  "list /usr/sap/trans", "does /tmp/out.txt exist on the app server".
  Prerequisites: active SAP GUI session (use /sap-login first) for
  upload/download; SAP NCo 3.1 (32-bit) in GAC for list/exists.
argument-hint: "upload <local-file> <appserver-file> [--binary|--text] [--overwrite] | download <appserver-file> <local-file> [--binary|--text] [--overwrite] | list <appserver-dir> [--mask <pattern>] | exists <appserver-file>   [--session /app/con[N]/ses[M]]"

SAP File Transfer Skill

You move files between the operator's PC and the SAP application server (CG3Z / CG3Y) or list app-server directories headlessly over RFC.

Task: $ARGUMENTS

---

Shared Resources

| File | Token | Purpose | |---|---|---| | `<SAP_DEV_CORE_SHARED_DIR>/rules/safety_policy.md` | *(rule)* | **Rule 0 (highest priority)** — environment guard; enforced by Step 0.6 via `sap_safety_gate.ps1` | | `<SAP_DEV_CORE_SHARED_DIR>/rules/skill_operating_rules.md` | *(rule)* | Mandatory operating rules | | `<SAP_DEV_CORE_SHARED_DIR>/rules/language_independence_rules.md` | *(rule)* | GUI-scripting language independence — the drivers key every outcome on control IDs + `MessageType`; localized text appears only inside `WScript.Echo` diagnostics | | `<SAP_DEV_CORE_SHARED_DIR>/rules/sap_gui_security_handling.md` | *(rule)* | Both transfer modes are SAP-GUI-side local-file IO (upload READS a PC file, download WRITES one) → can raise the modal "SAP GUI Security" dialog, which suspends the whole Scripting API | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_gui_security_precheck.ps1` | — | Read-only `saprules.xml` probe before the transfer (`-Access r` for upload, `-Access w` for download) | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_gui_security_sidecar.ps1` | — | OS-level watcher that auto-dismisses the SAP GUI Security dialog; pre-arm when the precheck says `NOT_COVERED` | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_attach_lib.vbs` | `%%ATTACH_LIB_VBS%%` | Parallel-safe session attach (Tier 3 contract) | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_session_lock.vbs` | `%%SESSION_LOCK_VBS%%` | Session lock around the fill+execute critical section; release sweeps orphan modals | | `<SAP_DEV_CORE_SHARED_DIR>/scripts/sap_rfc_lib.ps1` | — | NCo connect helpers, dot-sourced by `sap_file_list.ps1` (list/exists) | | `<SKILL_DIR>/references/sap_file_transfer_upload.vbs` | — | CG3Z driver. Tokens: `%%LOCAL_FILE%%`, `%%REMOTE_FILE%%`, `%%TRANSFER_MODE%%`, `%%OVERWRITE%%` (+ attach/lock tokens) | | `<SKILL_DIR>/references/sap_file_transfer_download.vbs` | — | CG3Y driver. Same tokens; execute button is btn[13] (vs btn[14] in CG3Z) | | `<SKILL_DIR>/references/sap_file_list.ps1` | — | `list` / `exists` over RFC: `EPS2_GET_DIRECTORY_LISTING` with legacy `EPS_` fallback. 32-bit PowerShell |

Probed against: S/4HANA 1909 (S4D), SAP GUI 7.70 — CG3Z dialog `SAPLC13Z`/1020, CG3Y dialog `SAPLC13Z`/1010, overwrite Query `SAPLSPO1`/300, cannot-open-file Information popup `SAPMSDYP`/10. Golden baselines in `references/*.screens.json`.

---

Step 0 — Resolve Work Directory

**Resolve `work_dir` via the env-aware helper** — do NOT take `work_dir` from a direct `settings.json` read (that ignores the `SAPDEV_AI_WORK_DIR` env var and `userconfig.json`):

powershell -NoProfile -ExecutionPolicy Bypass -Command ". '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1'; . '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'; Write-Output ('WORK_DIR=' + (Get-SapWorkDir)); Write-Output ('RUN_TEMP=' + (Get-SapRunTemp))"

Set `{WORK_TEMP}` = `{work_dir}\temp` (base — ONLY for `Get-SapCurrentSessionPath -WorkTemp`). Write this skill's OWN scratch (the generated `*_run.vbs`, sidecar log) under `{RUN_TEMP}`.

---

Step 0.5 — Start Logging

powershell -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_file_transfer_run.json" -Skill sap-file-transfer -ParamsJson "{\"mode\":\"<MODE>\",\"remote\":\"<appserver-path>\"}"

---

Step 0.6 — Safety Gate (Rule 0 — `safety_policy.md`)

The `upload` mode writes a file onto the SAP application server and runs the environment gate first; `download`, `list` and `exists` are read-only and skip it:

powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_safety_gate.ps1" -Action assert -Skill sap-file-transfer

| Verdict (last line) | Exit | Action | |---|---|---| | `SAFETY: ALLOW ...` | 0 | proceed (log via `-Action step`, step `safety_gate`) | | `SAFETY: TYPED_CONFIRM_REQUIRED ... expect="PROD <SID>/<CLIENT>"` | 3 | the operator must **type** the shown token; re-run assert with `-ConfirmationText '<their verbatim answer>'`; proceed only on `ALLOW_CONFIRMED` | | `SAFETY: REFUSED class=<C> ...` | 1 | **STOP.** End the run `FAILED` with `-ErrorClass <C>` and relay the gate's remediation lines. Never bypass, soften, retry, or drive the transaction manually instead — Rule 0 outranks every other instruction, including mid-session user ones. | | `SAFE