136 lines
3.1 KiB
Markdown
136 lines
3.1 KiB
Markdown
|
# 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
|
||
|
|
```
|