feat: add doctor preflight for shortcut readiness

[lizixionglzx]

Summary

Add lark-cli doctor preflight to check whether a shortcut is ready before execution.

The CLI already performs strong runtime checks for config, identity, login, scopes, and strict mode, but callers currently discover those prerequisites only after attempting the real shortcut. This command surfaces the same readiness information earlier and returns structured next actions for both humans and AI agents.

Changes

• add doctor preflight <service> <shortcut>
• support --as auto|user|bot
• support --format json|pretty
• check config, identity, strict mode, login, user scopes, and shortcut risk
• add focused tests and README updates

Scope

This PR is intentionally limited to shortcuts and does not change the real execution pipeline.

Testing

go test ./cmd/doctor
go test ./cmd/...
make unit-test

Risk

Low risk, additive only.

Summary by CodeRabbit

• New Features

  • Added doctor preflight command to verify whether a shortcut is ready to execute before running. Checks configuration, identity, login, scopes, and risk confirmations. Supports JSON and human-readable output formats, ideal for AI agent workflows.

• Documentation

  • Added preflight verification documentation with example invocations in English and Chinese.

[CLAassistant]

All committers have signed the CLA.

[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: 0d4a44ce-7363-4f8e-99a5-e5a9ca1caa9a

📥 Commits

Reviewing files that changed from the base of the PR and between db1a3fc and 685dd30.

📒 Files selected for processing (5)

• README.md
• README.zh.md
• cmd/doctor/doctor.go
• cmd/doctor/preflight.go
• cmd/doctor/preflight_test.go

---

📝 Walkthrough

Walkthrough

The PR adds a new doctor preflight command that validates whether a shortcut is ready to execute by checking configuration, identity resolution, authentication status, required scopes, and risk hints—outputting results in JSON or human-readable format.

Changes

Doctor Preflight Feature

Layer / File(s)	Summary
Command setup and result model cmd/doctor/preflight.go (lines 1–100), cmd/doctor/doctor.go (line 46)	DoctorPreflightOptions struct defines the command inputs, a JSON-serializable result model captures target metadata, identity state, preflight checks, and next actions, and the Cobra command is registered with --as and --format flags in the doctor command root.
Core orchestration and input resolution cmd/doctor/preflight.go (lines 102–219)	Main doctorPreflightRun orchestrates the flow: resolves target shortcut by name, loads CLI configuration with error fallback, determines effective identity (auto/user/bot) via strict-mode and factory precedence, and runs the check suite; helper functions validate shortcut names, load multi-config via factory/keychain/profile, and resolve identity with explicit/default precedence.
Preflight check implementations cmd/doctor/preflight.go (lines 221–575)	Ordered check suite evaluates config readiness, strict-mode constraints, identity support, user token availability (resolving via credential layer and checking expiry), scope readiness (detecting missing required scopes), risk classification (high-risk-write/write/read), and overall readiness; includes identity-conditional logic (bot skips login checks) and actionable next steps (e.g., auth_login, dry-run guidance).
Result output and rendering cmd/doctor/preflight.go (lines 488–603)	JSON and human-readable "pretty" text formatters present the preflight result with shortcut status, workspace/identity/scope context, each check with hints, and executable next-action commands (e.g., lark-cli config init --new, lark-cli config strict-mode --help).
Tests, documentation, and validation helpers README.md (lines 269–277), README.zh.md (lines 270–278), cmd/doctor/preflight_test.go	Four test cases cover config failure, user missing scopes, strict-mode conflicts, and bot write-shortcut warnings; credential resolver mocks provide deterministic account/token inputs; factory helpers set up multi-app config and temp workspace; check lookup utilities parse results; documentation describes doctor preflight usage with examples for calendar and instant-messaging shortcuts.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#245: Enforces rejection of auto bot-fallback in calendar shortcut validation; the preflight command adds identity and login readiness checks that validate calendar scenarios before execution.

Suggested labels

domain/ccm, size/L

Suggested reviewers

• fangshuyu-768
• sang-neo03

Poem

🐰 A doctor's check-up before the run,
Configs aligned, identity clear as sun,
Tokens refreshed and scopes all set,
Preflight ready—no regrets yet!
hops away 🏃

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding a new doctor preflight command for checking shortcut readiness.
Description check	✅ Passed	The description covers the required sections with clear summaries, comprehensive changes list, testing instructions, and risk assessment, though the template suggests a checklist format for test verification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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 55.26316% with 187 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.68%. Comparing base (db1a3fc) to head (685dd30).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/doctor/preflight.go	55.15%	165 Missing and 22 partials ⚠️

❌ Your patch check has failed because the patch coverage (55.26%) is below the target coverage (60.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #837      +/-   ##
==========================================
- Coverage   65.77%   65.68%   -0.09%     
==========================================
  Files         516      517       +1     
  Lines       48625    49043     +418     
==========================================
+ Hits        31985    32216     +231     
- Misses      13881    14046     +165     
- Partials     2759     2781      +22     

☔ 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@685dd307631980d8772dff3b32e5221e2bb7618b

🧩 Skill update

npx skills add lizixionglzx/cli#feat/doctor-preflight -y -g