feat(drive): add modified-time smart sync mode

[fangshuyu-768]

Summary

This PR implements the first roadmap feature point for Drive sync efficiency by adding a new smart mode for the existing --if-exists policy.

--if-exists=smart is a best-effort incremental optimization based on modified_time, not a content-hash equality check. It skips redundant transfers when timestamps already show the target side is up to date, and falls back to the safe transfer path when the metadata cannot be trusted.

Changes

• Add smart as a new --if-exists mode for drive +push and skip uploads when Drive modified_time already matches or is newer than the local file mtime.
• Add smart as a new --if-exists mode for drive +pull and skip downloads when the local file mtime already matches or is newer than Drive modified_time.
• Preserve the remote modified_time on downloaded local files so repeated drive +pull --if-exists=smart runs stay stable.
• Add shared Drive epoch parsing and comparison helpers so second-, millisecond-, and microsecond-based timestamps behave consistently.
• Remove size-based smart-mode checks after verifying that the Drive listing metadata used by this flow does not provide a trustworthy size field for this purpose.
• Extend unit tests for push and pull smart-mode skip and transfer behavior, plus timestamp parsing edge cases and metadata fallback coverage.
• Add dry-run end-to-end coverage to ensure smart is accepted by both drive +push and drive +pull.
• Update shortcut docs and skill references to describe the final modified-time-based smart sync semantics.

Design Notes

• smart is intentionally a best-effort optimization, not a strict content-equality guarantee.
• On pull, the CLI preserves the remote modified_time on downloaded local files to keep repeated smart syncs stable.
• On push, the remote modified_time remains server-controlled, so the CLI can only compare against it, not rewrite it.

Test Plan

• Unit tests pass
• Manual local verification confirms the CLI commands work as expected
• go test ./shortcuts/drive
• go test ./tests/cli_e2e/drive
• go vet ./...
• make unit-test
• go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main

Related Issues

• None

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a smart mode for Drive --if-exists in push and pull that uses remote epoch parsing and resolution-aware modified-time comparison (plus optional size checks) to decide skip vs transfer; includes helpers, unit and e2e tests, and documentation updates.

Changes

Smart --if-exists implementation for Drive push/pull

Layer / File(s)	Summary
Timestamp parsing and comparison helpers shortcuts/drive/list_remote.go, shortcuts/drive/drive_duplicate_remote_test.go	Added parseDriveEpoch to parse Drive epoch strings (inferring seconds/milliseconds/microseconds) and compareDriveRemoteModifiedToLocal to compare remote vs local times with resolution truncation. Unit tests validate epoch handling and invalid inputs.
Drive pull smart mode shortcuts/drive/drive_pull.go, shortcuts/drive/drive_pull_test.go	Added smart to --if-exists, extended drivePullTarget to carry ModifiedTime, populated remote metadata in remote-view paths, and implemented drivePullShouldSkipSmart which resolves local path, stats local ModTime, requires remote ModifiedTime, and skips only when local is at least as new under remote resolution. Added tests for skip, download, and fallback cases.
Drive push smart mode shortcuts/drive/drive_push.go, shortcuts/drive/drive_push_test.go	Added smart to --if-exists, recorded local ModTime during file walk, and routed skip decisions through drivePushShouldSkipExisting/drivePushShouldSkipSmart which call compareDriveRemoteModifiedToLocal; smart falls back to upload on parse/stat failures. Added tests for skip, overwrite, and fallback behavior.
End-to-end dry-run tests tests/cli_e2e/drive/drive_pull_dryrun_test.go, tests/cli_e2e/drive/drive_push_dryrun_test.go	Added dry-run tests verifying --if-exists smart is accepted and generates expected dry-run envelopes (HTTP method GET and the expected folder token).
Documentation updates skills/lark-drive/*, skills/lark-drive/references/*	Rewrote SKILL and reference docs to document --if-exists=smart semantics, summary.skipped behavior, examples, and performance guidance for push/pull.

Sequence Diagram(s)

The diagrams embedded in the hidden review stack artifact visualize the timestamp parsing flow and the smart skip decision sequences for pull and push.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#709: Related work on drive +push and --if-exists behavior that also touches skip/overwrite decisions.
• larksuite/cli#803: Related changes around Drive epoch timestamp handling and duplicate-remote tests.
• larksuite/cli#696: Previous drive +pull work extended by this PR to add smart mtime-based comparisons.

Suggested reviewers

• wittam-01
• zhouyue-bytedance

🐰 I nibbled timestamps, tiny and grand,
Smart mode now checks time with careful hand.
If local time is equal or a tad more new,
Skip the transfer — no needless chew.
Hop — syncs are clever, light, and true.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.67% 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
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.
Title check	✅ Passed	The title 'feat(drive): add modified-time smart sync mode' directly and clearly describes the main change: introducing a smart sync mode based on modified-time comparison for Drive operations.
Description check	✅ Passed	The description is comprehensive and well-structured. It includes a clear summary, detailed changes covering both push and pull implementations, design notes explaining the best-effort approach, and a completed test plan with all checkboxes marked.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/drive-push-smart-if-exists

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 93.67089% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.95%. Comparing base (62ff3d6) to head (82b41b4).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/drive/drive_pull.go	94.28%	1 Missing and 1 partial ⚠️
shortcuts/drive/list_remote.go	92.85%	2 Missing ⚠️
shortcuts/drive/drive_push.go	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #859      +/-   ##
==========================================
+ Coverage   65.87%   65.95%   +0.07%     
==========================================
  Files         518      518              
  Lines       48814    48901      +87     
==========================================
+ Hits        32157    32252      +95     
+ Misses      13890    13881       -9     
- Partials     2767     2768       +1     

☔ 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.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@82b41b41fc04d13c3ccde374ea17ab9b966a6b15

🧩 Skill update

npx skills add larksuite/cli#feat/drive-push-smart-if-exists -y -g