feat: add background_tasks + list_snapshots tools (v0.3.4)

- background_tasks: SYNO.FileStation.BackgroundTask::list (v3) — paginated
  table of active/recent copy/move/delete/extract/compress tasks
- list_snapshots: SYNO.FileStation.Snapshot::list (v2) — Btrfs snapshots
  per share; maps error 400 to a clear Btrfs-required message
- 20 new tests (107 total)
- SPEC.md and CLAUDE.md updated (26 tools)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-04-14 21:54:03 +02:00
parent b88677a20c
commit 4c6de3bfc7
6 changed files with 456 additions and 13 deletions
+107 -1
View File
@@ -97,7 +97,7 @@ regardless of service state.
---
## Tools (v0.2.10 — 20 tools)
## Tools (v0.3.4 — 26 tools)
### Read-only
@@ -134,6 +134,22 @@ regardless of service state.
| `list_sharing_links` | List all sharing links (paginated table) |
| `delete_sharing_link` | Delete a sharing link by ID |
### Thumbnail & Favorites
| Tool | Description |
|------|-------------|
| `get_thumbnail` | Fetch a thumbnail for an image/video file as base64 |
| `list_favorites` | List all FileStation user favorites |
| `add_favorite` | Add a path to FileStation favorites |
| `delete_favorite` | Remove a path from FileStation favorites |
### Background Tasks & Snapshots
| Tool | Description |
|------|-------------|
| `background_tasks` | List FileStation background tasks (copy, move, delete, etc.) |
| `list_snapshots` | List Btrfs snapshots for a shared folder (requires Btrfs volume) |
---
### Tool details
@@ -439,6 +455,96 @@ pagination hint when more results are available.
---
#### `get_thumbnail`
**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `path` | str | yes | — | Share-relative path to the image or video file |
| `size` | str | no | `large` | `small`, `medium`, `large`, or `original` |
**Returns:** JSON `{filename, size_bytes, content_base64}` (JPEG bytes encoded as base64).
**DSM call:** `SYNO.FileStation.Thumb::get` (POST, v2)
> DSM returns image bytes directly when the file has a thumbnail. Non-image content-type
> indicates a DSM error envelope — the tool parses and surfaces the error code.
---
#### `list_favorites`
**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `offset` | int | no | 0 | Pagination offset |
| `limit` | int | no | 200 | Max items to return |
**Returns:** Table with name, path, type, status, real path, modified time.
**DSM call:** `SYNO.FileStation.Favorite::list` (v2, `additional=["real_path","size","time"]`)
---
#### `add_favorite`
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | str | yes | Share-relative path to pin |
| `name` | str | yes | Display label for the favorite |
**Returns:** `"Added favorite '{name}' → {path}"` or error.
**DSM call:** `SYNO.FileStation.Favorite::add` (v2, `index=-1`)
---
#### `delete_favorite`
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `path` | str | yes | Share-relative path of the favorite to remove |
**Returns:** `"Deleted favorite for {path}"` or error.
**DSM call:** `SYNO.FileStation.Favorite::delete` (v2)
---
#### `background_tasks`
**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `offset` | int | no | 0 | Pagination offset |
| `limit` | int | no | 100 | Max tasks to return (capped at 200) |
**Returns:** Table with task ID, type, status, path, and file progress. Includes total count
and a pagination hint when more results are available.
**DSM call:** `SYNO.FileStation.BackgroundTask::list` (v3)
> Only the `list` method is available on this NAS — tasks cannot be stopped or cleared
> via this API.
---
#### `list_snapshots`
**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `share_path` | str | yes | — | Share-relative root path (e.g. `/docker`) |
| `offset` | int | no | 0 | Pagination offset |
| `limit` | int | no | 100 | Max snapshots to return (capped at 500) |
**Returns:** Table with snapshot ID, creation time, description, and locked flag. Includes
total count and a pagination hint when more results are available.
**DSM call:** `SYNO.FileStation.Snapshot::list` (v2, `folder_path={share_path}`)
> **Btrfs required:** DSM returns error 400 when the share is not on a Btrfs volume.
> The tool maps this to a clear message: *"Snapshots not available — requires Btrfs-formatted
> volume."*
---
## Error Handling Strategy
### Principles