On-behalf-of: SAP <matthias.bruns@sap.com>
Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

On-behalf-of: SAP <matthias.bruns@sap.com>
Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

# Conflicts:
#	cli/cmd/transfer/component-version/cmd.go

#### What this PR does / why we need it

Adds a `--transfer-spec` flag to `ocm transfer component-version` that
enables a two-step transfer workflow:

1. **Generate** the transfer spec via `--dry-run -o yaml` and save it to
a file
2. **Edit** the spec (e.g., change the target registry, remove
transformations)
3. **Execute** the modified spec via `--transfer-spec <file>`

This gives users full control over the TransformationGraphDefinition
before execution.

**Changes:**
- New `--transfer-spec` flag accepting a file path (or `-` for stdin)
- Custom argument validator: 0 args when `--transfer-spec` is set,
exactly 2 otherwise (source, destination)
- `loadTransferSpec()` function for reading and deserializing YAML/JSON
specs
- `buildGraphDefinitionFromArgs()` extracted for cleaner code structure
- Updated command description and examples documenting the workflow

#### Which issue(s) this PR fixes

Contributes
open-component-model/ocm-project#930

#### Testing

##### How to test the changes

```bash
# Step 1: Generate a transfer spec
ocm transfer cv --dry-run -o yaml ctf::./my-archive//ocm.software/mycomponent:1.0.0 ghcr.io/my-org/ocm > spec.yaml

# Step 2: Edit spec.yaml (e.g. change target registry)

# Step 3: Execute the modified spec
ocm transfer cv --transfer-spec spec.yaml
```

##### Verification

- [x] I have tested the changes locally by running `ocm`

```bash
#!/bin/zsh
#
# Test script for the --transfer-spec feature (issue #930).
# Demonstrates the two-step transfer workflow:
#   1. Generate a transfer spec via --dry-run
#   2. Edit the spec (change target registry)
#   3. Execute the modified spec via --transfer-spec
#
# Prerequisites:
#   - Authenticated to both REGISTRY and REGISTRY2 (e.g. via docker login / gh auth)
#   - Go installed (uses go run)

set -euo pipefail

alias OCM='go run ../../main.go'
REGISTRY="ghcr.io/matthiasbruns/ocm-tutorials"
REGISTRY2="ghcr.io/matthiasbruns/ocm-tutorials-2"

pause() {
  echo "\n>>> Next: $1"
  echo "--- Press Enter to continue ---"
  read
}

# ── Step 1: Create a source CTF archive ──────────────────────────────────────

cat <<EOF > constructor.yaml
components:
- name: ocm.software/transfer-spec-test
  version: 1.0.0
  provider:
    name: ocm.software
  resources:
  - name: test-resource
    version: 1.0.0
    type: plainText
    input:
      type: utf8
      text: "Hello from transfer-spec test!"
EOF

CTF_DIR=$(mktemp -d)
echo "Using temporary directory for CTF: $CTF_DIR"

OCM add cv --repository ctf::$CTF_DIR --constructor constructor.yaml

SOURCE_REF="ctf::$CTF_DIR//ocm.software/transfer-spec-test:1.0.0"

pause "Generate transfer spec via --dry-run (targeting $REGISTRY)"

# ── Step 2: Generate transfer spec targeting REGISTRY ────────────────────────

SPEC_FILE=$(mktemp).yaml
echo "Writing transfer spec to: $SPEC_FILE"

OCM transfer component-version $SOURCE_REF $REGISTRY \
  --dry-run -o yaml \
  --copy-resources \
  > $SPEC_FILE

echo "\n=== Generated Transfer Spec ==="
cat $SPEC_FILE
echo "=== End of Transfer Spec ===\n"

pause "Modify the spec to target $REGISTRY2 instead of $REGISTRY"

# ── Step 3: Edit the spec to change the target registry ──────────────────────

MODIFIED_SPEC_FILE=$(mktemp).yaml
sed "s|${REGISTRY}|${REGISTRY2}|g" $SPEC_FILE > $MODIFIED_SPEC_FILE

echo "\n=== Modified Transfer Spec (diff) ==="
diff $SPEC_FILE $MODIFIED_SPEC_FILE || true
echo "=== End of Diff ===\n"

pause "Execute the modified spec (transfer to $REGISTRY2)"

# ── Step 4: Execute the modified transfer spec ───────────────────────────────

OCM transfer component-version --transfer-spec $MODIFIED_SPEC_FILE --loglevel debug

echo "\nTransfer completed successfully!"

pause "Verify: describe component in $REGISTRY2"

# ── Step 5: Verify the component was transferred to REGISTRY2 ────────────────

OCM describe component-version https://$REGISTRY2//ocm.software/transfer-spec-test:1.0.0

# ── Cleanup ──────────────────────────────────────────────────────────────────

rm -rf $CTF_DIR constructor.yaml $SPEC_FILE $MODIFIED_SPEC_FILE

echo "\nAll done! The component was transferred to $REGISTRY2 using a modified transfer spec."

```

---------

Signed-off-by: Matthias Bruns <git@matthiasbruns.com>