feat(drive): add drive preview and cover shortcuts and document quota details

[zhoujunteng-max]

Summary

This PR adds drive +preview and drive +cover shortcuts for Drive file preview artifact and cover downloads, and updates the lark-drive skill metadata to expose quota detail capability and the new shortcuts to AI agents.

Changes

• add drive +preview to list and download available preview artifacts
• add drive +cover to list and download built-in cover presets
• normalize preview result wrapping and cover parameter mapping based on backend validation rules
• add unit tests, dry-run E2E tests, and live workflow E2E tests for preview/cover flows
• update skills/lark-drive/SKILL.md and add preview/cover references
• document quota_details.get in skills/lark-drive/SKILL.md

Test Plan

• Unit tests pass
• Manual local verification confirms the lark-cli drive +preview and lark-cli drive +cover commands work as expected

Additional verification:

• make unit-test
• go test ./shortcuts/drive -run 'TestDrivePreview|TestDriveCover|TestShortcutsIncludesExpectedCommands'
• go test ./tests/cli_e2e/drive -run 'TestDrive(Preview|Cover)DryRun'
• go test ./tests/cli_e2e/drive -run 'TestDrive_PreviewAndCoverWorkflow'

Related Issues

• None

Summary by CodeRabbit

Release Notes

• New Features

  • Added drive +preview shortcut for listing and downloading Drive preview artifacts in multiple formats (PDF, text, HTML).
  • Added drive +cover shortcut for listing and downloading stable Drive cover presets.
  • Added quota_details API resource for retrieving user capacity and quota information.

• Documentation

  • Updated Drive skill documentation with new shortcut guidance and API references.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces two new Drive CLI shortcuts—+preview and +cover—that enable users to list and download Drive preview artifacts and stable cover presets. Both shortcuts share common infrastructure for candidate fetching, parameter validation, artifact download, and output path conflict resolution with automatic extension inference.

Changes

Drive Preview and Cover Shortcuts

Layer / File(s)	Summary
Shared preview and cover infrastructure shortcuts/drive/drive_preview.go, shortcuts/drive/drive_preview_common.go	Core data structures, constants for preview types/statuses/cover specs, MIME-to-extension mappings, validation helpers, candidate fetching/normalization, download with output-path conflict handling (error/overwrite/rename), and extension inference from Content-Type/Content-Disposition headers and fallback rules.
Drive Preview shortcut definition and execution shortcuts/drive/drive_preview.go	DrivePreview shortcut validates file token and preview mode, builds dry-run API calls for candidate listing or download, fetches candidates, selects by requested type, resolves version (user-provided or from candidates), downloads artifact with conflict policy, and annotates output with mode and selected type.
Drive Cover shortcut definition and execution shortcuts/drive/drive_cover.go	DriveCover shortcut validates file token and cover spec, builds dry-run HTTP GET requests to preview_download endpoint with spec-derived parameters, lists built-in cover specs on --list-only, or resolves spec and downloads with conflict policy and result annotation.
Shortcut registration and unit tests shortcuts/drive/shortcuts.go, shortcuts/drive/shortcuts_test.go, shortcuts/drive/drive_preview_test.go	Registers DrivePreview and DriveCover in the shortcuts registry; validates presence in test expectations; provides five unit tests covering preview/cover list-only output normalization, download with rename conflict policy, unavailable type error handling, and cover spec parameter mapping.
Dry-run end-to-end tests tests/cli_e2e/drive/drive_preview_dryrun_test.go	Validates dry-run API request construction for preview list-only and download, and cover download, asserting endpoint URLs, request parameters (version, type, output, crop settings like width/height/policy), and HTTP methods.
Workflow end-to-end tests tests/cli_e2e/drive/drive_preview_workflow_test.go	Tests complete preview/cover workflows using real Drive uploads: fixture creation/upload, preview/cover list-only with retry logic until candidates become downloadable, artifact download with output path and extension validation, content/image verification, and resource cleanup.
Reference documentation and user guidance skills/lark-drive/SKILL.md, skills/lark-drive/references/lark-drive-preview.md, skills/lark-drive/references/lark-drive-cover.md	Adds SKILL.md guidance for +preview and +cover shortcuts and a new quota_details.get API resource; comprehensive reference docs covering prerequisites, command examples, CLI parameters (--file-token, --type/--spec, --output, --version, --list-only, --if-exists), response contracts, candidate/spec fields, operational constraints, and error handling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#588: Modifies shortcuts/drive/shortcuts.go to add new Drive shortcuts; both PRs directly update the Shortcuts() registry function.

Suggested labels

size/L, domain/ccm

Suggested reviewers

• fangshuyu-768
• wittam-01

Poem

🐰 With preview and cover so bright,
Drive artifacts now in sight!
List or download, your choice to make,
Extensions inferred—no path at stake!
Stable specs and fixtures all the way,
Lark's CLI grows with every day! 📸

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes all major changes: adding drive preview and cover shortcuts and documenting quota details.
Description check	✅ Passed	The description includes all required sections with sufficient detail: summary, changes list, test plan with checkboxes and verification commands, and related issues.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/drive-preview-cover-and-quota

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/drive/drive_preview_common.go`:
- Around line 304-311: When matching aliases (using previewAliasesForCandidate)
against requested, don't return the first match blindly; collect all
drivePreviewCandidate matches and if any match is downloadable (e.g.,
candidate.Downloadable or candidate.IsDownloadable), return a downloadable
candidate first, otherwise return the first matched candidate; update the loop
over candidates/requested to gather matches and prefer a downloadable
drivePreviewCandidate before falling back to the first match.

In `@tests/cli_e2e/drive/drive_preview_workflow_test.go`:
- Around line 136-139: The retry predicate currently only inspects result.Stderr
for transient 404/no-artifact signals; update the predicate to concatenate
result.Stdout and result.Stderr (e.g., combined := result.Stdout +
result.Stderr) and run the existing checks against that combined string (use
strings.Contains(combined, ...) and strings.Contains(strings.ToLower(combined),
"no artifact")). Modify the three occurrences that call
strings.Contains(result.Stderr, ...) to use the combined variable so transient
errors surfaced in stdout are also caught for retries.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 733352de-f5fd-49c5-95e5-20a40b2445ed

📥 Commits

Reviewing files that changed from the base of the PR and between b3fcf55 and fa89798.

📒 Files selected for processing (11)

• shortcuts/drive/drive_cover.go
• shortcuts/drive/drive_preview.go
• shortcuts/drive/drive_preview_common.go
• shortcuts/drive/drive_preview_test.go
• shortcuts/drive/shortcuts.go
• shortcuts/drive/shortcuts_test.go
• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-cover.md
• skills/lark-drive/references/lark-drive-preview.md
• tests/cli_e2e/drive/drive_preview_dryrun_test.go
• tests/cli_e2e/drive/drive_preview_workflow_test.go

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@9090fe9065f24d16bcafa91a784b606bd3126e0f

🧩 Skill update

npx skills add larksuite/cli#feat/drive-preview-cover-and-quota -y -g

[codecov]

Codecov Report

❌ Patch coverage is 77.61807% with 109 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.70%. Comparing base (b3fcf55) to head (9090fe9).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/drive/drive_preview_common.go	76.45%	58 Missing and 31 partials ⚠️
shortcuts/drive/drive_cover.go	80.00%	5 Missing and 5 partials ⚠️
shortcuts/drive/drive_preview.go	82.45%	5 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1254      +/-   ##
==========================================
- Coverage   69.90%   69.70%   -0.21%     
==========================================
  Files         645      669      +24     
  Lines       60233    64900    +4667     
==========================================
+ Hits        42108    45239    +3131     
- Misses      14823    16011    +1188     
- Partials     3302     3650     +348     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.