# SCP Plugin Walkthrough

This walkthrough adds a bundled `scp` plugin backed by existing SSH libraries:

- `paramiko` for SSH and SFTP directory listing
- `scp` for file transfers

The implementation lives in [plugins/scp/__init__.py](plugins/scp/__init__.py).

## What The Plugin Does

The SCP plugin mirrors the FTP walkthrough, but on top of SSH:

- `search-file -plugin scp ...` lists remote files and folders over SFTP.
- plain `@N` on a folder drills into that directory.
- plain `@N` on a file runs `download-file -plugin scp -url ...`.
- `@N | add-file -store ...` downloads first, then ingests the local temp file.
- `add-file -plugin scp -path ...` uploads a local file to the configured remote path.

## Example Config

```toml
[provider.scp]
host = "ssh.example.com"
port = 22
username = "deploy"
password = "secret"
key_path = "C:/Users/Admin/.ssh/id_ed25519"
base_path = "/srv/files"
timeout = 20
search_depth = 1
allow_agent = true
look_for_keys = true
```

Notes:

- `host` and `username` are required for the plugin to validate.
- You can use password auth, key auth, or both.
- `base_path` is both the default search root and the default upload directory.

## Search Flow

List the configured base path:

```powershell
search-file -plugin scp "*"
```

Search by filename:

```powershell
search-file -plugin scp "invoice"
```

Search another subtree with deeper recursion:

```powershell
search-file -plugin scp "path:/srv/files/releases depth:2 *.zip"
```

Show only folders:

```powershell
search-file -plugin scp "path:/srv/files type:folder *"
```

## Selection Flow

Folder rows are navigation rows:

```powershell
search-file -plugin scp "*"
@2
```

File rows carry an explicit row action, so terminal selection downloads directly:

```powershell
search-file -plugin scp "report"
@1
```

That expands to the equivalent of:

```powershell
download-file -plugin scp -url scp://ssh.example.com/srv/files/report.pdf
```

## Download And Add-File Flow

Download into a local folder:

```powershell
search-file -plugin scp "report"
@1 | download-file -path C:\Downloads
```

Ingest a selected remote file into a configured store backend:

```powershell
search-file -plugin scp "report"
@1 | add-file -store tutorial
```

Why this works:

- file rows advertise `_selection_action` for `download-file`
- `add-file` selection replay inserts that provider download stage before ingest
- the plugin also implements `resolve_pipe_result_download()` for provider-owned SCP rows

## Upload Flow

Upload a local file to the configured remote `base_path`:

```powershell
add-file -plugin scp -path C:\Media\report.pdf
```

## Implementation Notes

The plugin uses SFTP for directory listing because SCP itself is a transfer protocol, not a browse/search protocol. That split keeps the provider simple:

- browse and metadata via Paramiko SFTP
- file transfer via the `scp` package

## Recommended Demo Commands

```powershell
search-file -plugin scp "*"
search-file -plugin scp "path:/srv/files depth:2 *.zip"
@1
@1 | download-file -path C:\Downloads
@1 | add-file -store tutorial
add-file -plugin scp -path C:\Media\report.pdf
```