/sap-compare

name: sap-compare
description: |
  Compare the SAME ABAP object across two SAP systems — the pinned connection
  (LEFT) and a second saved profile selected with --against <hint> (RIGHT).
  DDIC objects (table / structure / data element / domain / table type) are
  compared field-by-field over RFC on BOTH sides (DDIF_FIELDINFO_GET). Programs
  / includes / function modules are compared by source over RFC via
  RPY_PROGRAM_READ (sap_rfc_read_source.ps1). Emits a structured field diff
  (diff.json), a unified source diff, and an AI summary that annotates each
  difference with the likely cause — including release skew using each system's
  saved release marker. Read-only: never modifies either system.
  Prerequisites: BOTH systems saved via /sap-login (RFC password required, same
  Windows user — DPAPI is CurrentUser-scoped). Class source compare is limited
  (RFC class source unsupported until ADT mode).
argument-hint: "<OBJECT_NAME> --against <profile-hint> [--type ...] [--ddic|--source]"

SAP Compare Skill

Diffs one repository object between two systems and explains the differences. Use it for landscape drift ("works in QAS, fails in DEV"), pre-transport sanity checks, and confirming an import landed. Pure read-only on both systems (observes `shared/rules/skill_operating_rules.md`).

Shared Resources

| File | Path | Purpose | |---|---|---| | `sap_settings_lib.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_settings_lib.ps1` | `Get-SapSettingValue` | | `sap_connection_lib.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1` | `Get-SapWorkDir`, `Resolve-SapProfileHint`, `Get-SapCurrentConnectionProfile` | | `sap_dpapi.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_dpapi.ps1` | decrypt RIGHT password (`-Action unprotect`; invoked as a subprocess) | | `sap_rfc_lib.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_rfc_lib.ps1` | `Connect-SapRfc`, `Disconnect-SapRfc`, `New-RfcReadTable` | | `sap_rfc_read_source.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_rfc_read_source.ps1` | `Read-SapAbapSource` (cross-system source) | | `sap_compare_ddic.ps1` | `<SKILL_DIR>\references\sap_compare_ddic.ps1` | dual-connect DDIC fetch + structured field diff -> `diff.json` | | `sap_compare_diff.ps1` | `<SKILL_DIR>\references\sap_compare_diff.ps1` | normalize + text diff (source mode) | | `sap_log_helper.ps1` | `<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1` | structured logging |

Step 0 — Resolve Work Directory

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))"

| Setting | Default if blank | |---|---| | `work_dir` | `C:\sap_dev_work` |

Parse `WORK_DIR=` and `RUN_TEMP=` from stdout.

Set `{WORK_TEMP}` = `{work_dir}\temp` and `{RUN_TEMP}` = the `RUN_TEMP=` value (`Get-SapRunTemp` mints + creates `{work_dir}\temp\run_<id>`). Set `{OUT}` = `{RUN_TEMP}\compare\{OBJECT}` — per-run private scratch, so concurrent `/sap-compare` runs never clobber each other's `left.def`/`right.def`/`diff.json`. Ensure `{OUT}` exists:

cmd /c if not exist "{OUT}" mkdir "{OUT}"

Step 0.5 — Start Logging (best-effort)

powershell -NoProfile -ExecutionPolicy Bypass -File "<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_log_helper.ps1" -Action start -StateFile "{RUN_TEMP}\sap_compare_run.json" -Skill sap-compare -ParamsJson "{\"args\":\"{RAW_ARGS}\"}"

Step 1 — Parse Arguments

• `{OBJECT}` = first positional, uppercased.
• `--against <hint>` -> `{AGAINST}` (**required**). Uses `Resolve-SapProfileHint`

grammar: UUID, `last`, `default`, `<SID>`, `<SID>/<CLIENT>/<USER>`, or a description substring.

• `--type` -> `{TYPE}` (default `auto`).
• `--ddic` / `--source` -> force `{MODE}` (otherwise derived in Step 3).

Step 2 — Resolve & Connect BOTH Systems

The reference scripts own the dual connection. For source mode, the SKILL can also drive it directly. Resolution refuses on ambiguity (mirrors the broker "ambiguous = refuse loudly" rule):

. '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_connection_lib.ps1'
. '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_rfc_lib.ps1'

# LEFT = pinned (empty params => Connect-SapRfc falls back to the pinned profile)
$left = Connect-SapRfc -DestName "CMP_LEFT"
if (-not $left) { Write-Output "ERROR: LEFT not connected (run /sap-login)"; exit 2 }

# RIGHT = --against profile, explicit creds
$cands = @(Resolve-SapProfileHint -Hint '{AGAINST}')
if ($cands.Count -eq 0) { Write-Output "ERROR: profile '{AGAINST}' not found"; exit 2 }
if ($cands.Count -gt 1) { Write-Output "ERROR: '{AGAINST}' is ambiguous — qualify as <SID>/<CLIENT>/<USER>"; exit 2 }
$t  = $cands[0]
$pw = (& '<SAP_DEV_CORE_SHARED_DIR>\scripts\sap_dpapi.ps1' -Action unprotect -Value "$($t.password_dpapi)" 2>$null) -as [string]
$right = Connect-SapRfc -Server $t.application_server -Sysnr $t.system_number `
          -MessageServer $t.message_server -LogonGroup $t.logon_group -SystemID $t.system_id `
          -Client $t.client -User $t.user -Password $pw -Language $t.language -DestName "CMP_RIGHT"
if (-not $right) { Write-Output "ERROR: RIGHT '{AGAINST}' not connected (RFC creds / DPAPI / reachability)"; exit 2 }

Record `{LEFT_SID}` / `{RIGHT_SID}` and each profile's `server_release_marker` for the Step 5 annotation.

> Note: `Connect-SapRfc` publishes `$g_*` caller-scope vars (last call wins) and > `Disconnect-SapRfc` cleans up the *last* config. Keep `$left`/`$right` and let > the reference scripts own lifecycle; don't rely on `$g_*` after the 2nd connect.

Step 3 — Detect Type (on LEFT, RFC) & Pick Mode

If `{TYPE}=auto`, probe LEFT via `New-RfcReadTable` (same table set as `/sap-explain-object` Step 3: `TRDIR`/`TFDIR`/`SEOCLASS`/`DD02L`/`DD04L`/`DD01L`/`DD40L`).

| Detected type | `{MODE}` | |---|---| | table, structure, data element, domain, table type | `d