proton-drive-mcp 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.3.0 — 2026-09-30
+
+Proton Drive has no search, and its end-to-end encryption rules out server-side indexing. This release adds the client-side layer: find things, understand what uses your space, and clean up safely. 4 builders worked in parallel, then 3 verifiers (live on a real account, an independent security review, packaging/CI) and a re-check of every fix. Review findings fixed before release include two ReDoS vectors in search and a local-path guard gap.
+
+### Added
+- **`drive_tree`** and **`drive_search`** (also in the `core` tier): a bounded, parallel walk of the drive (8 concurrent calls, `.git` and `node_modules` skipped, call cap, cancellable) with a 5-minute in-memory cache that the server's own writes invalidate. Search by name, glob (relative to the search folder when it contains `/`), extension, media type, size and date, with stable pagination. The first walk of a large drive takes minutes (about 25 s per 1,200 files); later calls are instant.
+- **`drive_usage`**: largest files and folders, breakdown by type, old files and trash stats (sums of file sizes, not the account quota).
+- **`drive_find_duplicates`**: groups by the uploader-claimed sha1 or by size; `verify` downloads and hashes candidates within a size and total budget. It never deletes.
+- **`drive_sharing_audit`**: public links (role, expiry, password; the URL is never printed), invitees, pending invitations and risk flags.
+- **`drive_sync_plan`**: compares a local folder with a Drive folder (plan only).
+- **`drive_bulk_move`** and **`drive_bulk_trash`**: up to 200 items in one batched call. Always two steps: without `confirmed` you get a plan and any problems; `confirmed:true` applies only if there are none. Trash stays reversible.
+- **MCP prompts** (`organise-folder`, `find-files`, `storage-audit`, `sharing-audit`), listed only when the tools they need are in the active tier; also declared in the MCPB manifest.
+- **Human confirmation through elicitation** for clients that support it (Claude Code CLI; Claude Desktop is unverified): gated calls and bulk applies ask the person instead of only failing. Clients without it behave as before. It does not protect against a model that passes `confirmed:true` itself.
+- `drive_list` and `drive_info` now return `mtime`, `uploadedAt` and `sha1` (claimed, often absent); `drive_list` takes a `type` filter; `drive_share_status` adds `shareUrlRole`.
+- Tool titles on every tool, corrected annotations (for example `drive_trash` is not destructive), `maxResultSizeChars` hints on the large-result tools.
+
+### Changed
+- The full tool list is now 46 tools (about 39 KB, was 29.5 KB); `core` is 18 tools (16.8 KB). Use `PROTON_DRIVE_TOOL_TIER=core` to keep the token cost down.
+- Folder uploads and `drive_sync_plan` refuse a local folder that contains protected locations (home directory, `/`, `~/.ssh`, ...); scans skip secret-named files and report `protectedSkipped`. Downloads into your home folder still work. Note that for uploads the CLI does the recursion, so a `.env` inside an uploaded subfolder is not filtered.
+- `.gitignore` covers `node_modules` as a symlink too.
+
+### Known limitations
+- Windows is not supported. The CLI has no search, version history, quota or change notifications, so none of those are offered.
+- The walk cache does not see changes made by other clients until it expires or `refresh:true`.
+- `drive_share_leave`, `drive_invitation_accept` and `drive_invitation_reject` have never been tested live (no second Proton account). Elicitation and prompts are verified with the official SDK client and Claude Code semantics, not with Claude Desktop.
+
 ## 1.2.0 — 2026-09-28
 
 Setup, packaging and reliability round. Five features were built in parallel on separate branches, merged, then verified live (real account, 3 concurrent servers), on Node 22/24 and on the new Ubuntu + macOS CI matrix, plus an independent code review. Review and CI findings were fixed before release.

package/README.md

@@ -30,8 +30,8 @@ Give Claude Desktop (or any MCP client) full access to your Proton Drive and Pro
 
 - **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
 - **Proton Photos album management** — list albums, create/delete albums, add and remove photos
-- **Full CLI** — same 38 operations, scriptable and pipeable, works in cron and shell scripts
-- **100% CLI coverage** — every scriptable Proton Drive CLI command has a matching tool (verified against the CLI's own source; `auth login` is the one command excluded, since it's an interactive browser flow)
+- **Companion CLI** — 44 of the 46 operations, scriptable and pipeable, works in cron and shell scripts (the two sync-folder tools, `drive_read_file` and `drive_write_file`, are MCP-only)
+- **Full Proton Drive CLI coverage** — every scriptable Proton Drive CLI command has a matching tool (verified against the CLI's own source; `auth login` is the one command excluded, since it's an interactive browser flow)
 - **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
 - **Shell injection safe** — all CLI calls use `execFile` with discrete argument arrays, never string interpolation
 - **Privacy-native** — end-to-end encryption is handled by Proton's own CLI; this server is just a thin MCP wrapper
@@ -229,6 +229,28 @@ proton-drive-cli restore /my-files/old-draft.pdf       # restore from trash
 proton-drive-cli trash empty --confirm                  # permanently delete all trashed items
 ```
 
+### Search, analytics and cleanup
+`drive_search` · `drive_tree` · `drive_usage` · `drive_find_duplicates` · `drive_sharing_audit` · `drive_sync_plan` · `drive_bulk_move` · `drive_bulk_trash`
+
+```bash
+proton-drive-cli tree /my-files --depth 2
+proton-drive-cli search /my-files --ext pdf --min-size 1000000
+proton-drive-cli usage /my-files --top 20 --older-than 365
+proton-drive-cli duplicates /my-files --min-size 1000000 [--verify]
+proton-drive-cli share audit /my-files
+proton-drive-cli sync-plan ./local /my-files/backup --direction up
+proton-drive-cli bulk-move /my-files/Archive /my-files/a.pdf /my-files/b.pdf          # plan only
+proton-drive-cli bulk-trash /my-files/old1.txt /my-files/old2.txt --confirm           # apply
+```
+
+- The first walk of a large drive can take minutes (measured ~25 s per 1,200 files at concurrency 8). Later calls reuse a 5-minute cache; `refresh` bypasses it.
+- Walks skip `.git` and `node_modules` by default.
+- Read-only tools (`drive_search`, `drive_tree`, `drive_usage`, `drive_find_duplicates`, `drive_sharing_audit`, `drive_sync_plan`) change nothing. `drive_bulk_move` and `drive_bulk_trash` are two-step: call without `confirmed` for the plan, then with `confirmed: true` to apply. Bulk trash is reversible with `drive_restore`.
+- Duplicate detection uses the sha1 the uploader claimed, which is unverified. `verify: true` downloads the candidates and hashes them.
+- The sharing audit flags an invitee as external when the address is outside Proton domains, so Proton users on a custom domain are over-flagged.
+- Sizes are sums of file sizes, not your account quota.
+- `drive_usage` trash stats always make one uncached `/trash` listing (~2.5 s), even when the walk is cached.
+
 ### Photos
 
 ```bash
@@ -260,13 +282,19 @@ proton-drive-cli share status /my-files/Projects
 
 ---
 
+## Prompts
+
+The server offers four MCP prompts (also declared in the MCPB manifest): `organise-folder` (`path`), `find-files` (`description`), `storage-audit` and `sharing-audit`. In Claude Code they are listed as `/servername:promptname (MCP)`, and `/mcp__servername__promptname` also runs them. Other clients show them as prompts. A prompt is hidden when a tool it needs is outside the active tool tier: with `PROTON_DRIVE_TOOL_TIER=core` only `find-files` is offered.
+
+---
+
 ## Tool surface
 
 ### Auth
 `drive_auth_status` · `drive_auth_logout` · `drive_version`
 
 ### Filesystem
-`drive_list` · `drive_info` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
+`drive_list` · `drive_info` · `drive_tree` · `drive_search` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
 
 ### Sharing
 `drive_share_status` · `drive_share_invite` · `drive_share_revoke` · `drive_share_remove_all` · `drive_share_set_url` · `drive_share_remove_url`
@@ -280,6 +308,9 @@ proton-drive-cli share status /my-files/Projects
 ### Copy
 `drive_copy`
 
+### Plan & bulk
+`drive_sync_plan` · `drive_bulk_move` · `drive_bulk_trash`
+
 ### Invitations
 `drive_list_invitations` · `drive_invitation_accept` · `drive_invitation_reject` · `drive_share_leave`
 
@@ -297,6 +328,8 @@ proton-drive-cli share status /my-files/Projects
 | `drive_version` | CLI and SDK version info | — |
 | `drive_list` | List files and folders at a path (paginated, default 200; `/` lists the roots) | `path`, `limit?`, `offset?` |
 | `drive_info` | Get metadata for one file/folder, including revision details (noise trimmed) | `path`, `verbose?` (raw CLI node) |
+| `drive_tree` | Folder overview: per-folder file counts and size totals (largest first), depth-limited, cached 5 min | `path?`, `depth?` (default 2, max 10), `limit?`, `foldersOnly?`, `refresh?` |
+| `drive_search` | Find files/folders under a path in one cached walk: name (substring/glob; a glob containing `/` matches the path relative to `path`), type, extension, MIME prefix, size, modified date; sortable, paginated. Reports `walk.complete` — false means the walk was cut short and matches may be missing | `query?`, `glob?`, `path?`, `type?`, `mediaType?`, `extensions?`, `minSize?`, `maxSize?`, `modifiedAfter?`, `modifiedBefore?`, `sort?`, `limit?` (default 50, max 500), `offset?`, `refresh?` |
 | `drive_mkdir` | Create a new empty folder | `path` |
 | `drive_upload` | Upload local file or folder | `localPath`, `remotePath`, `fileConflictStrategy?` (skip/create-new-revision/rename/replace), `folderConflictStrategy?` (skip/merge/rename/replace), `confirmed?` (**required for `replace`** — it trashes the existing remote item) |
 | `drive_download` | Download to local path | `remotePath`, `localPath`, `fileConflictStrategy?` (skip/rename/remove), `folderConflictStrategy?` (skip/merge/rename/remove), `confirmed?` (**required for `remove`** — it deletes the existing local item) |
@@ -306,12 +339,18 @@ proton-drive-cli share status /my-files/Projects
 | `drive_delete` | Permanently delete an item already in trash ⚠️ | `path`, `confirmed: true` |
 | `drive_list_trash` | List items currently in trash (paginated, default 100; includes `uid` — names are not unique in trash) | `limit?`, `offset?` |
 | `drive_share_status` | Get sharing members and URL | `path` |
+| `drive_usage` | Storage analytics for a subtree: totals, largest files/folders, extension and media-type breakdown, old files, trash stats (sum of file sizes, not the account quota) | `path?`, `top?`, `olderThanDays?`, `refresh?` |
+| `drive_find_duplicates` | Likely duplicate groups (claimed sha1 / same size; `verify` downloads and sha256s candidates), wasted bytes, suggested keeper — never deletes | `path?`, `minSize?`, `verify?`, `maxVerifyBytes?`, `maxVerifyTotalBytes?` (default 500 MB, max 2 GB), `limit?`, `refresh?` |
+| `drive_sharing_audit` | Public links (no URL), invitees, pending invitations and risk flags for shared items (max 100) | `path?`, `refresh?` |
 | `drive_share_invite` | Invite a user (sends an email) ⚠️ | `path`, `email`, `role` (viewer/editor/admin), `message?`, `confirmed: true` |
 | `drive_share_revoke` | Revoke one person's access (fails if not a member) ⚠️ | `path`, `email`, `confirmed: true` |
 | `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path`, `confirmed: true` |
 | `drive_share_set_url` | Create/replace a public share link ⚠️ (re-running without `password`/`expiration` removes them; expiry max ~90 days) | `path`, `role?` (viewer/editor), `password?`, `expiration?`, `confirmed: true` |
 | `drive_share_remove_url` | Remove the public share link ⚠️ | `path`, `confirmed: true` |
 | `drive_trash` | Move to trash | `path` |
+| `drive_sync_plan` | Read-only diff of a local folder vs a Drive folder (nothing transferred) | `localPath`, `drivePath`, `direction?` (up/down/both), `ignore?`, `compare?` (size-mtime/sha1), `limit?` |
+| `drive_bulk_move` | Move up to 200 items into an existing folder; without `confirmed` returns the plan and problems only | `sources`, `destinationFolder`, `confirmed?` (**required to apply**) |
+| `drive_bulk_trash` | Trash up to 200 items (recoverable); without `confirmed` returns the plan and problems only | `paths`, `confirmed?` (**required to apply**) |
 | `drive_restore` | Restore from trash | `path` |
 | `drive_empty_trash` | Permanently delete all trash ⚠️ | `confirmed: true` |
 | `drive_read_file` | Read text file from local sync folder | `path` |
@@ -356,15 +395,17 @@ proton-drive-cli share status /my-files/Projects
 - Error messages come from the CLI's own output; the command line (and therefore any `--password`) is never echoed back.
 - `drive_move` accepts a full destination path (parent + new name) for a familiar interface, but the underlying CLI only has separate `move` (change parent) and `rename` (change name) commands — this MCP translates automatically, issuing one or both as needed.
 - `drive_delete` only works on items already in `/trash` or `/photos-trash` — the CLI rejects live paths. Trash an item first with `drive_trash`, or use `drive_empty_trash` to clear everything at once.
+- If the client declares MCP elicitation (form mode), a refused `confirmed` gate is put to the human instead, and `drive_bulk_move` / `drive_bulk_trash` ask before applying a `confirmed: true` call. Only an explicit approval runs the call; decline, cancel, timeout or error keep the refusal, and after 5 declined prompts in a minute the server stops prompting. This only upgrades refusals and bulk applies: a compromised model that supplies `confirmed: true` on any other tool is **not** stopped by it. Clients without elicitation behave as before. Confirmation prompts need a client that supports elicitation (Claude Code CLI today; Claude Desktop is unverified).
+- Walk-based tools (`drive_tree`, `drive_search`, `drive_usage`, `drive_find_duplicates`) read from a cache up to 5 minutes old; changes made by other clients or processes are not seen until it expires or you pass `refresh: true`. The first walk of a large drive can take minutes (measured about 25 s per 1200 files at concurrency 8).
 - `drive_auth_status` has no native CLI equivalent — it probes by resolving `/my-files` and reports authenticated based on whether that succeeds.
 - Paths are always Drive-absolute: `/my-files/folder/file.pdf`. Relative paths are not supported.
 - All calls include `--json` automatically, except `drive_version`, whose underlying CLI command ignores `--json` and always prints plain text — this MCP parses it directly.
 
 ### Token cost
 
-`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 29.5 KB (38 tools; 39.5 KB before description trimming), `core` 13.3 KB (16 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
+`tools/list` is sent to the model in every session. Measured payload (JSON bytes): `full` 39.0 KB (46 tools), `core` 16.8 KB (18 tools). Set `PROTON_DRIVE_TOOL_TIER=core` to load only:
 
-`drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_list_trash`, `drive_mkdir`, `drive_upload`, `drive_download`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_share_status`, `photos_list_timeline`, `photos_download`.
+`drive_auth_status`, `drive_version`, `drive_list`, `drive_info`, `drive_list_trash`, `drive_search`, `drive_tree`, `drive_mkdir`, `drive_upload`, `drive_download`, `drive_rename`, `drive_move`, `drive_copy`, `drive_trash`, `drive_restore`, `drive_share_status`, `photos_list_timeline`, `photos_download`.
 
 Left out of `core` (use `full`): permanent deletion (`drive_delete`, `drive_empty_trash`), `drive_auth_logout`, public links, invitations and invites, album management, `photos_upload` and the sync-file tools. A call to a hidden tool returns an error asking for `PROTON_DRIVE_TOOL_TIER=full`; no CLI command runs.
 
@@ -386,7 +427,7 @@ These come from the upstream `proton-drive` CLI (v0.8.0), not from this server:
 
 ## Platform support
 
-Developed and live-tested on **macOS**. CI runs the test suite on Ubuntu and macOS (Node 22 and 24). **Windows is not supported yet**: the test suite has never passed there (CI runs it only as a non-blocking probe), and the Windows paths in `doctor` / `setup-claude-desktop` (`%APPDATA%`, `PATHEXT` lookup) are untested. The system-PATH warning in `doctor` only knows POSIX directories. Linux is covered by CI with the fake CLI but has not been live-tested against a real Proton account.
+Developed and live-tested on **macOS**. CI runs the test suite on Ubuntu and macOS (Node 22 and 24). **Windows is not supported yet**: the test suite has never passed there and CI does not run it, and the Windows paths in `doctor` / `setup-claude-desktop` (`%APPDATA%`, `PATHEXT` lookup) are untested. The system-PATH warning in `doctor` only knows POSIX directories. Linux is covered by CI with the fake CLI but has not been live-tested against a real Proton account.
 
 ## Testing status
 
@@ -404,7 +445,8 @@ Every tool group was live-tested on 2026-09-28 against a real Proton account, **
 | `PROTON_DRIVE_ALLOW_SENSITIVE_PATHS` | Optional | Set to `1` to disable the built-in credential-location denylist (not recommended). |
 | `CLAUDE_DESKTOP_CONFIG` | Optional | Path of the Claude Desktop config that `doctor` and `setup-claude-desktop` read/write instead of the per-OS default. |
 | `PROTON_DRIVE_RETRY_BASE_MS` | Optional | Test hook: base backoff in ms for retrying read-only calls (default 250). |
-| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 38 tools) or `core` (16 everyday tools; see [Token cost](#token-cost)). Tools outside the active tier are hidden from `tools/list` and refused at call time. Read once at startup; an unknown value falls back to `full` with a warning on stderr. |
+| `PROTON_DRIVE_WALK_TTL_MS` | Optional | How long `drive_tree`/`drive_search` reuse a cached folder walk, in ms (default 300000; 0 disables the cache). Results can be up to this old, and changes made by other clients or processes are not seen until it expires or `refresh: true`. The first walk of a large drive can take minutes. The cache is dropped for any path this server writes to. |
+| `PROTON_DRIVE_TOOL_TIER` | Optional | `full` (default, all 46 tools) or `core` (18 everyday tools; see [Token cost](#token-cost)). Tools outside the active tier are hidden from `tools/list` and refused at call time. Read once at startup; an unknown value falls back to `full` with a warning on stderr. |
 
 ---
 

package/dist/cli.js

@@ -11,8 +11,12 @@ import { DriveCliError, DriveCliNotFoundError, DriveNotAuthenticatedError, Drive
 import { checkCliAvailable } from "./utils/subprocess.js";
 import { runDoctor, formatDoctor } from "./utils/doctor.js";
 import { buildEntry, defaultConfigPath, isDirectory, resolveDriveCli, writeEntry, SERVER_KEY } from "./utils/claudeConfig.js";
+import { syncPlan, planBulkMove, planBulkTrash, loadListing, foldersToList } from "./services/plan.js";
+import { invalidatePath } from "./services/walk.js";
 import { resolve } from "node:path";
-import { validateRemotePath, validateLocalPath, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
+import { driveSearch, driveTree } from "./services/find.js";
+import { driveUsage, driveFindDuplicates, driveSharingAudit } from "./services/analytics.js";
+import { validateRemotePath, validateRemotePathList, validateLocalPath, validateEmail, validateMessage, validateName, validateFlagValue } from "./utils/validation.js";
 const drive = new DriveService();
 const args = process.argv.slice(2);
 const jsonMode = args.includes("--json");
@@ -26,6 +30,12 @@ Commands:
   version                                  Show CLI/SDK version
   list <path>                              List files at path
   info <path> [--verbose]                  Show node metadata (--verbose = raw CLI node)
+  tree [path] [--depth N] [--limit N] [--folders-only] [--refresh]
+                                           Folder overview with per-folder counts and sizes (default /my-files, depth 2)
+  search [path] [--query S] [--glob G] [--type file|folder] [--media-type P] [--ext pdf,docx]
+         [--min-size B] [--max-size B] [--after DATE] [--before DATE] [--sort name|size|mtime]
+         [--limit N] [--offset N] [--refresh]
+                                           Find files/folders under path (default /my-files) in one walk
   mkdir <path>                             Create a new folder
   upload <local> <remote> [--file-conflict X] [--folder-conflict X] [--confirm]
                                            Upload file/folder (files: skip/create-new-revision/rename/replace; folders: skip/merge/rename/replace;
@@ -37,6 +47,7 @@ Commands:
   move <src> <dst>                         Move and/or rename
   delete <path>|--uid <uid> --confirm      Delete a file/folder already in trash, permanently
   share status <path>                      Show sharing info
+  share audit [path] [--refresh]           Audit public links, invitees and risk flags under a path (default /my-files)
   share invite <path> <email> <role>       Invite user (viewer/editor/admin)
   share revoke <path> <email>              Revoke one user's access
   share remove-all <path> --confirm        Remove everyone's access + pending invitations
@@ -45,7 +56,15 @@ Commands:
   share leave <path>                       Leave a folder shared with you
   copy <src> <dst-parent-folder> [--name N]  Copy file/folder into a folder (optionally under a new name)
   trash <path>                             Move to trash
+  sync-plan <local> <remote> [--direction up|down|both] [--compare size-mtime|sha1] [--ignore g1,g2] [--limit N]
+                                           Read-only diff of a local folder vs a Drive folder (nothing transferred)
+  bulk-move <dst-folder> <src>... [--confirm]  Move many items into an existing folder; without --confirm prints the plan only
+  bulk-trash <path>... [--confirm]         Trash many items; without --confirm prints the plan only
   trash list                               List trash contents
+  usage [path] [--top N] [--older-than DAYS] [--refresh]
+                                           Storage analytics: totals, largest files/folders, breakdowns, trash (sum of file sizes, not the quota)
+  duplicates [path] [--min-size B] [--verify] [--max-verify-bytes B] [--max-verify-total-bytes B] [--limit N] [--refresh]
+                                           Likely duplicate files; --verify downloads and hashes candidates. Never deletes.
   trash empty --confirm                    Permanently delete all trash
   restore <path>|--uid <uid>               Restore from trash (uid from 'trash list')
   invitation list                          List pending invitations
@@ -86,6 +105,19 @@ function requirePath(value, usage) {
     }
     return ""; // unreachable; process.exit(1) above always terminates
 }
+function pathOrRoot(value) {
+    return value && !value.startsWith("--") ? requirePath(value, "<command> [path]") : "/my-files";
+}
+function intFlag(flag) {
+    const v = getFlag(flag);
+    if (v === undefined)
+        return undefined;
+    if (!/^\d+$/.test(v)) {
+        console.error(`${flag} must be a non-negative integer`);
+        process.exit(1);
+    }
+    return Number(v);
+}
 function requireEmail(value) {
     try {
         return validateEmail(value);
@@ -106,6 +138,19 @@ function getFlag(flag) {
     }
     return args[idx + 1];
 }
+function numFlag(flag) {
+    const v = getFlag(flag);
+    if (v === undefined)
+        return undefined;
+    if (!/^\d+$/.test(v)) {
+        console.error(`${flag} must be a non-negative integer`);
+        process.exit(1);
+    }
+    return Number(v);
+}
+function numFlags(...names) {
+    return Object.fromEntries(names.map((n) => [n, numFlag(`--${n}`)]));
+}
 function print(data) {
     console.log(jsonMode ? JSON.stringify(data) : JSON.stringify(data, null, 2));
 }
@@ -184,6 +229,21 @@ async function run() {
         case "list":
             print(await drive.list(requirePath(sub, "list <path>")));
             break;
+        case "tree":
+            print(await driveTree(drive, { path: sub && !sub.startsWith("--") ? sub : undefined, ...numFlags("depth", "limit"), foldersOnly: args.includes("--folders-only") || undefined, refresh: args.includes("--refresh") || undefined }));
+            break;
+        case "search":
+            print(await driveSearch(drive, {
+                path: sub && !sub.startsWith("--") ? sub : undefined,
+                query: getFlag("--query"), glob: getFlag("--glob"),
+                type: getFlag("--type"), mediaType: getFlag("--media-type"),
+                extensions: getFlag("--ext")?.split(","),
+                ...numFlags("limit", "offset"),
+                minSize: numFlag("--min-size"), maxSize: numFlag("--max-size"),
+                modifiedAfter: getFlag("--after"), modifiedBefore: getFlag("--before"),
+                sort: getFlag("--sort"), refresh: args.includes("--refresh") || undefined,
+            }));
+            break;
         case "info":
             print(await drive.info(requirePath(sub, "info <path> [--verbose]"), args.includes("--verbose")));
             break;
@@ -195,7 +255,7 @@ async function run() {
             }
             let local;
             try {
-                local = validateLocalPath(rawLocal);
+                local = validateLocalPath(rawLocal, { scan: true });
             }
             catch (e) {
                 console.error(e instanceof Error ? e.message : String(e));
@@ -297,6 +357,9 @@ async function run() {
             if (sub === "status") {
                 print(await drive.shareStatus(requirePath(rest[0], "share status <path>")));
             }
+            else if (sub === "audit") {
+                print(await driveSharingAudit(drive, { path: pathOrRoot(rest[0]), refresh: args.includes("--refresh") }));
+            }
             else if (sub === "invite") {
                 const [rawPath, rawEmail, role] = rest;
                 if (!rawPath || !rawEmail || !role) {
@@ -365,6 +428,25 @@ async function run() {
                 process.exit(1);
             }
             break;
+        case "usage":
+            print(await driveUsage(drive, {
+                path: pathOrRoot(sub),
+                top: intFlag("--top"),
+                olderThanDays: intFlag("--older-than"),
+                refresh: args.includes("--refresh"),
+            }));
+            break;
+        case "duplicates":
+            print(await driveFindDuplicates(drive, {
+                path: pathOrRoot(sub),
+                minSize: intFlag("--min-size"),
+                verify: args.includes("--verify"),
+                maxVerifyBytes: intFlag("--max-verify-bytes"),
+                maxVerifyTotalBytes: intFlag("--max-verify-total-bytes"),
+                limit: intFlag("--limit"),
+                refresh: args.includes("--refresh"),
+            }));
+            break;
         case "trash":
             if (sub === "empty") {
                 if (!args.includes("--confirm")) {
@@ -386,6 +468,66 @@ async function run() {
                 process.exit(1);
             }
             break;
+        case "sync-plan": {
+            const direction = getFlag("--direction"), compare = getFlag("--compare"), ignore = getFlag("--ignore"), limit = getFlag("--limit");
+            if (direction !== undefined && !["up", "down", "both"].includes(direction)) {
+                console.error("--direction must be up, down or both");
+                process.exit(1);
+            }
+            if (compare !== undefined && !["size-mtime", "sha1"].includes(compare)) {
+                console.error("--compare must be size-mtime or sha1");
+                process.exit(1);
+            }
+            if (!sub || !rest[0]) {
+                console.error("Usage: sync-plan <local> <remote> [--direction X] [--compare X] [--ignore g1,g2] [--limit N]");
+                process.exit(1);
+            }
+            print(await syncPlan(drive, {
+                localPath: sub, drivePath: rest[0], direction: direction, compare: compare,
+                ignore: ignore?.split(","), limit: limit !== undefined ? Number(limit) : undefined,
+            }));
+            break;
+        }
+        case "bulk-move": {
+            const dst = requirePath(sub, "bulk-move <dst-folder> <src>... [--confirm]");
+            const srcs = validateRemotePathList(rest.filter((r) => !r.startsWith("--")), "sources");
+            const plan = planBulkMove(srcs, dst, await loadListing(drive, foldersToList(srcs, dst)));
+            if (!args.includes("--confirm") || plan.problems.length) {
+                print({ applied: false, ...plan });
+                if (plan.problems.length)
+                    process.exit(1);
+                console.error("Plan only. Pass --confirm to apply.");
+                break;
+            }
+            try {
+                await drive.bulkMove(srcs, dst);
+            }
+            finally {
+                invalidatePath(dst);
+                srcs.forEach(invalidatePath);
+            }
+            console.log(`Moved ${srcs.length} item(s) to ${dst}.`);
+            break;
+        }
+        case "bulk-trash": {
+            const paths = validateRemotePathList([sub, ...rest].filter((r) => r !== undefined && !r.startsWith("--")), "paths");
+            const plan = planBulkTrash(paths, await loadListing(drive, foldersToList(paths)));
+            if (!args.includes("--confirm") || plan.problems.length) {
+                print({ applied: false, ...plan });
+                if (plan.problems.length)
+                    process.exit(1);
+                console.error("Plan only. Pass --confirm to apply.");
+                break;
+            }
+            try {
+                await drive.bulkTrash(paths);
+            }
+            finally {
+                paths.forEach(invalidatePath);
+            }
+            console.log(`Moved ${paths.length} item(s) to trash.`);
+            break;
+        }
         case "restore": {
             const restoreUid = getFlag("--uid");
             const restorePath = restoreUid && (!sub || sub.startsWith("--")) ? undefined : requirePath(sub, "restore <path>|--uid <uid>");
@@ -577,7 +719,7 @@ async function run() {
                 const localPaths = [];
                 for (const p of positionals) {
                     try {
-                        localPaths.push(validateLocalPath(p));
+                        localPaths.push(validateLocalPath(p, { scan: true }));
                     }
                     catch (e) {
                         console.error(e instanceof Error ? e.message : String(e));