feat(quark): add Quark Drive adapter (#858)

* feat(quark): add Quark Drive adapter (ls, mkdir, mv, rename, rm, save, share-tree)

Browser-based adapter for Quark Cloud Drive (pan.quark.cn) using cookie
strategy. Supports file browsing, folder management, and saving shared
files with task polling for async operations.

* fix(quark): address review feedback on adapter correctness and docs

- ls: fix depth off-by-one (default 0 now lists target folder only)
- save/mv: report success only after pollTask confirms completion; throw on timeout
- save/mv: reject combining --to and --to-fid instead of silently preferring --to-fid
- utils: check content-type before calling r.json() to handle non-JSON responses gracefully
- tests: add quark graceful auth-failure E2E cases for all 7 commands
- docs: add Browser Bridge extension to prerequisites; fix mkdir --parent example; expand command table with positional args; add Notes section explaining stoken flow

* fix(quark): map auth failures and cover utils

* fix(quark): reuse auth mapping for share-tree

---------

Co-authored-by: xzy <xzy@mbp-m5.local>
Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: 3 people

README.md

@@ -141,6 +141,7 @@ git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && n
 | **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` |
 | **xianyu** | `search` `item` `chat` |
 | **xiaoe** | `courses` `detail` `catalog` `play-url` `content` |
+| **quark** | `ls` `mkdir` `mv` `rename` `rm` `save` `share-tree` |
 
 79+ adapters in total — **[→ see all supported sites & commands](./docs/adapters/index.md)**
 

README.zh-CN.md

@@ -147,6 +147,7 @@ npx skills add jackwener/opencli --skill opencli-oneshot     # 快速命令参
 | **chatgpt** | `status` `new` `send` `read` `ask` `model` | 桌面端 |
 | **xiaohongshu** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | 浏览器 |
 | **xiaoe** | `courses` `detail` `catalog` `play-url` `content` | 浏览器 |
+| **quark** | `ls` `mkdir` `mv` `rename` `rm` `save` `share-tree` | 浏览器 |
 | **apple-podcasts** | `search` `episodes` `top` | 公开 |
 | **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 公开 |
 | **zhihu** | `hot` `search` `question` `download` `follow` `like` `favorite` `comment` `answer` | 浏览器 |

clis/quark/ls.ts

@@ -0,0 +1,94 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import type { IPage } from '@jackwener/opencli/types';
+import {
+  findFolder,
+  formatSize,
+  listMyDrive,
+} from './utils.js';
+
+interface DriveNode {
+  name: string;
+  fid: string;
+  is_dir: boolean;
+  size: string;
+  path: string;
+  children?: DriveNode[];
+}
+
+async function buildTree(
+  page: IPage,
+  pdirFid: string,
+  parentPath: string,
+  depth: number,
+  maxDepth: number,
+  dirsOnly: boolean,
+): Promise<DriveNode[]> {
+  if (depth > maxDepth) return [];
+
+  const files = await listMyDrive(page, pdirFid);
+  const nodes: DriveNode[] = [];
+
+  for (const file of files) {
+    if (dirsOnly && !file.dir) continue;
+
+    const path = parentPath ? `${parentPath}/${file.file_name}` : file.file_name;
+    const node: DriveNode = {
+      name: file.file_name,
+      fid: file.fid,
+      is_dir: file.dir,
+      size: formatSize(file.size),
+      path,
+    };
+
+    if (file.dir && depth < maxDepth) {
+      node.children = await buildTree(page, file.fid, path, depth + 1, maxDepth, dirsOnly);
+    }
+
+    nodes.push(node);
+  }
+
+  return nodes;
+}
+
+function flattenTree(nodes: DriveNode[], level = 0): Record<string, unknown>[] {
+  const result: Record<string, unknown>[] = [];
+  const indent = '  '.repeat(level);
+
+  for (const node of nodes) {
+    result.push({
+      name: `${indent}${node.name}`,
+      fid: node.fid,
+      is_dir: node.is_dir,
+      size: node.size,
+      path: node.path,
+    });
+    if (node.children) {
+      result.push(...flattenTree(node.children, level + 1));
+    }
+  }
+
+  return result;
+}
+
+cli({
+  site: 'quark',
+  name: 'ls',
+  description: 'List files in your Quark Drive',
+  domain: 'pan.quark.cn',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'path', positional: true, default: '', help: 'Folder path to list (empty for root)' },
+    { name: 'depth', type: 'int', default: 0, help: 'Max depth to traverse' },
+    { name: 'dirs-only', type: 'boolean', default: false, help: 'Show directories only' },
+  ],
+  columns: ['name', 'is_dir', 'size', 'fid', 'path'],
+  func: async (page, kwargs) => {
+    const path = (kwargs.path as string) ?? '';
+    const depth = Math.max(0, (kwargs.depth as number) ?? 0);
+    const dirsOnly = (kwargs['dirs-only'] as boolean) ?? false;
+
+    const rootFid = path ? await findFolder(page, path) : '0';
+    const tree = await buildTree(page, rootFid, path, 0, depth, dirsOnly);
+    return flattenTree(tree);
+  },
+});

clis/quark/mkdir.ts

@@ -0,0 +1,47 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import type { IPage } from '@jackwener/opencli/types';
+import { DRIVE_API, apiPost, findFolder } from './utils.js';
+
+interface MkdirResult {
+  status: string;
+  fid: string;
+  name: string;
+}
+
+cli({
+  site: 'quark',
+  name: 'mkdir',
+  description: 'Create a folder in your Quark Drive',
+  domain: 'pan.quark.cn',
+  strategy: Strategy.COOKIE,
+  defaultFormat: 'json',
+  args: [
+    { name: 'name', required: true, positional: true, help: 'Folder name' },
+    { name: 'parent', help: 'Parent folder path (resolved by name)' },
+    { name: 'parent-fid', help: 'Parent folder fid (use directly)' },
+  ],
+  func: async (page: IPage, kwargs: Record<string, unknown>): Promise<MkdirResult> => {
+    const name = kwargs.name as string;
+    if (!name.trim()) throw new ArgumentError('Folder name cannot be empty');
+
+    if (kwargs.parent && kwargs['parent-fid']) {
+      throw new ArgumentError('Cannot use both --parent and --parent-fid');
+    }
+
+    const parentFid = kwargs['parent-fid']
+      ? (kwargs['parent-fid'] as string)
+      : kwargs.parent
+        ? await findFolder(page, kwargs.parent as string)
+        : '0';
+
+    const data = await apiPost<{ fid: string }>(page, `${DRIVE_API}?pr=ucpro&fr=pc`, {
+      pdir_fid: parentFid,
+      file_name: name,
+      dir_path: '',
+      dir_init_lock: false,
+    });
+
+    return { status: 'ok', fid: data.fid, name };
+  },
+});

clis/quark/mv.ts

@@ -0,0 +1,62 @@
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import type { IPage } from '@jackwener/opencli/types';
+import { DRIVE_API, apiPost, findFolder, pollTask } from './utils.js';
+
+interface MoveResult {
+  status: string;
+  count: number;
+  destination: string;
+  task_id: string;
+  completed: boolean;
+}
+
+cli({
+  site: 'quark',
+  name: 'mv',
+  description: 'Move files to a folder in your Quark Drive',
+  domain: 'pan.quark.cn',
+  strategy: Strategy.COOKIE,
+  defaultFormat: 'json',
+  timeoutSeconds: 120,
+  args: [
+    { name: 'fids', required: true, positional: true, help: 'File IDs to move (comma-separated)' },
+    { name: 'to', default: '', help: 'Destination folder path (required unless --to-fid is set)' },
+    { name: 'to-fid', default: '', help: 'Destination folder ID (overrides --to)' },
+  ],
+  func: async (page: IPage, kwargs: Record<string, unknown>): Promise<MoveResult> => {
+    const to = kwargs.to as string;
+    const toFid = kwargs['to-fid'] as string;
+    const fids = kwargs.fids as string;
+    const fidList = [...new Set(fids.split(',').map(id => id.trim()).filter(Boolean))];
+    if (fidList.length === 0) throw new ArgumentError('No fids provided');
+    if (!to && !toFid) throw new ArgumentError('Either --to or --to-fid is required');
+    if (to && toFid) throw new ArgumentError('Cannot use both --to and --to-fid');
+
+    const targetFid = toFid || await findFolder(page, to);
+    const data = await apiPost<{ task_id: string }>(page, `${DRIVE_API}/move?pr=ucpro&fr=pc`, {
+      filelist: fidList,
+      to_pdir_fid: targetFid,
+    });
+
+    const result: MoveResult = {
+      status: 'pending',
+      count: fidList.length,
+      destination: to || toFid,
+      task_id: data.task_id,
+      completed: false,
+    };
+
+    if (data.task_id) {
+      const completed = await pollTask(page, data.task_id);
+      result.completed = completed;
+      result.status = completed ? 'ok' : 'error';
+      if (!completed) throw new CommandExecutionError('quark: Move task timed out');
+    } else {
+      result.status = 'ok';
+      result.completed = true;
+    }
+
+    return result;
+  },
+});

clis/quark/rename.ts

@@ -0,0 +1,35 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import type { IPage } from '@jackwener/opencli/types';
+import { DRIVE_API, apiPost } from './utils.js';
+
+interface RenameResult {
+  status: string;
+  fid: string;
+  new_name: string;
+}
+
+cli({
+  site: 'quark',
+  name: 'rename',
+  description: 'Rename a file in your Quark Drive',
+  domain: 'pan.quark.cn',
+  strategy: Strategy.COOKIE,
+  defaultFormat: 'json',
+  args: [
+    { name: 'fid', required: true, positional: true, help: 'File ID to rename' },
+    { name: 'name', required: true, help: 'New file name' },
+  ],
+  func: async (page: IPage, kwargs: Record<string, unknown>): Promise<RenameResult> => {
+    const fid = kwargs.fid as string;
+    const name = kwargs.name as string;
+    if (!name.trim()) throw new ArgumentError('New name cannot be empty');
+
+    await apiPost(page, `${DRIVE_API}/rename?pr=ucpro&fr=pc`, {
+      fid,
+      file_name: name,
+    });
+
+    return { status: 'ok', fid, new_name: name };
+  },
+});

clis/quark/rm.ts

@@ -0,0 +1,33 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import type { IPage } from '@jackwener/opencli/types';
+import { DRIVE_API, apiPost } from './utils.js';
+
+interface DeleteResult {
+  status: string;
+  count: number;
+  deleted_fids: string[];
+}
+
+cli({
+  site: 'quark',
+  name: 'rm',
+  description: 'Delete files from your Quark Drive',
+  domain: 'pan.quark.cn',
+  strategy: Strategy.COOKIE,
+  defaultFormat: 'json',
+  args: [
+    { name: 'fids', required: true, positional: true, help: 'File IDs to delete (comma-separated)' },
+  ],
+  func: async (page: IPage, kwargs: Record<string, unknown>): Promise<DeleteResult> => {
+    const fids = kwargs.fids as string;
+    const fidList = [...new Set(fids.split(',').map(id => id.trim()).filter(Boolean))];
+    if (fidList.length === 0) throw new ArgumentError('No fids provided');
+
+    await apiPost(page, `${DRIVE_API}/delete?pr=ucpro&fr=pc`, {
+      filelist: fidList,
+    });
+
+    return { status: 'ok', count: fidList.length, deleted_fids: fidList };
+  },
+});