feat(drive): harden inspect shortcut failures

[fangshuyu-768]

Summary

• harden drive +inspect input validation by rejecting conflicting --type values and malformed bare tokens before any API call
• add limited retry/backoff for rate-limited wiki unwrap and drive metadata fetches, and annotate typed errors with the failing inspect stage
• switch drive metadata lookup helpers onto CallAPITyped so inspect and its shared metadata path emit consistent typed errors

Testing

• go test ./shortcuts/drive ./shortcuts/common
• go test ./... (currently fails on existing cmd/schema tests with Unknown service: im on latest main; unrelated to this PR)

Notes

• supersedes feat(drive): harden inspect shortcut failures #1323, which used a temporary branch name

Summary by CodeRabbit

• Bug Fixes

  • Enhanced drive +inspect command with improved input validation for URLs and tokens, now rejecting empty inputs and detecting type conflicts early.

• Improvements

  • Added automatic retry mechanism with exponential backoff for wiki operations to handle rate limiting gracefully.
  • Enriched error messages with stage-specific context for better troubleshooting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 74c89b2c-25f9-4126-9140-cb28c4420b35

📥 Commits

Reviewing files that changed from the base of the PR and between 076f4d5 and b54abe8.

📒 Files selected for processing (4)

• shortcuts/common/drive_meta.go
• shortcuts/common/drive_meta_test.go
• shortcuts/drive/drive_inspect.go
• shortcuts/drive/drive_inspect_test.go

---

📝 Walkthrough

Walkthrough

The PR improves drive metadata retrieval and the drive +inspect shortcut by switching to typed API responses, centralizing URL/token validation with conflict detection, and adding resilient exponential backoff retry logic with stage-specific error annotation.

Changes

Drive Metadata & Inspect Robustness

Layer / File(s)	Summary
Typed API Response Integration shortcuts/common/drive_meta.go, shortcuts/common/drive_meta_test.go	FetchDriveMeta switches from runtime.CallAPI to runtime.CallAPITyped for the batch metadata query, enabling typed error inspection. Tests now validate the returned error is a typed problem and assert its error code.
URL/Token Resolution and Validation shortcuts/drive/drive_inspect.go, shortcuts/drive/drive_inspect_test.go	New driveInspectResolveRef helper centralizes --url and --type parsing and validation: trims/rejects empty URLs, normalizes type to lowercase, detects conflicts between flag and URL path type, rejects bare tokens containing protocol markers or path fragments, and requires --type for bare tokens. Integrated into Validate, DryRun, and Execute flows. Tests cover conflicting type flags and malformed bare token formats.
Retry & Error Annotation Infrastructure shortcuts/drive/drive_inspect.go, shortcuts/drive/drive_inspect_test.go	Wiki node resolve and metadata fetch now execute through exponential backoff retry wrapper with stage-aware error annotation. New helpers: driveInspectCallWithRetry (exponential backoff with configurable attempts/initial delay), driveInspectShouldRetry (detects retryable errors via typed problem codes), driveInspectWait (context-aware timer), and driveInspectAnnotateError (labels errors with execution stage and action hints). Tests assert error message prefixes and verify successful resolve after rate-limit retry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#947: Introduces the initial +inspect shortcut and meta-query logic that this PR refactors and hardens with validation, retry, and typed errors.
• larksuite/cli#992: Modifies FetchDriveMeta behavior; both PRs update the same function, one switching to typed responses while the other restructured metadata retrieval.
• larksuite/cli#1121: Overlaps on drive_inspect_test.go changes, particularly TestDriveInspectExecute_BatchQueryError and related Execute test assertions.

Suggested labels

size/L, domain/ccm

Suggested reviewers

• wittam-01

Poem

🐰 With typed errors caught and tokens tight,
Retries backoff through the night,
Wiki nodes and metadata gleam,
A robustness dream! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.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
Title check	✅ Passed	The title 'feat(drive): harden inspect shortcut failures' clearly summarizes the main change—improving error handling and input validation for the drive inspect shortcut, which aligns with the PR's primary objectives of hardening validation and annotating typed errors.
Description check	✅ Passed	The PR description provides a clear summary of changes, testing approach, and notes about superseding a prior PR. However, it deviates from the template by using a 'Testing' section instead of 'Test Plan' and lacks checkboxes for unit tests and manual verification.
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-inspect-hardening

---

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#feat/drive-inspect-hardening -y -g