feat(doc): add --omit-title flag to docs +fetch for round-trip safety

[herbertliu]

Summary

Addresses Case 13 in the lark-cli pitfall list: `docs +fetch --format=pretty` prepends `# <title>` for human readability, but Lark stores the document title as an independent field and `docs +update --mode=overwrite` only rewrites the body. Piping pretty output through overwrite therefore accumulates a duplicate H1 block on every round-trip — observed in practice as 6+ duplicate H1s on the PR-tracker doc before anyone noticed.

Add `--omit-title` (off by default) so round-trip callers get a clean body.

Changes

• `shortcuts/doc/docs_fetch.go`: new `--omit-title` bool flag; extract `renderFetchPretty` from the Execute closure for testability.
• `shortcuts/doc/docs_fetch_test.go` (new): 6-case table-driven coverage + a dedicated round-trip-safety assertion.
• `skills/lark-doc/references/lark-doc-fetch.md`: document the flag and the round-trip use case.

Scope notes

• Default behavior unchanged — human readers still see the H1 title up top.
• Only `--format=pretty` is affected; `json` / `ndjson` / `csv` / `table` never carried the synthetic prefix.
• This is the Option 2 resolution from the Case 13 brief (additive flag). Option 1 (change default) was rejected on breaking-change risk; Option 3 (auto-strip on overwrite) needs either an extra API call to learn the title or a fragile heuristic.

Test Plan

• `go test ./shortcuts/doc/...` passes
• `go vet ./...` clean
• `gofmt -l` clean
• Manual smoke: run a fetch → overwrite cycle with and without the flag and confirm no H1 accumulates in the latter

Summary by CodeRabbit

• New Features

  • Added --omit-title flag to docs +fetch command for --format=pretty output, allowing users to exclude the initial title line from rendered markdown.

• Documentation

  • Updated documentation with new --omit-title flag examples and parameter descriptions.

[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: 9853fbf7-0ddb-497b-b45d-884b3ca2d7e7

📥 Commits

Reviewing files that changed from the base of the PR and between 81d22c6 and a82dc3e.

📒 Files selected for processing (3)

• shortcuts/doc/docs_fetch.go
• shortcuts/doc/docs_fetch_test.go
• skills/lark-doc/references/lark-doc-fetch.md

---

📝 Walkthrough

Walkthrough

The PR adds a --omit-title flag to the docs +fetch command that suppresses the H1 title prefix in pretty-format output, enabling round-trip safety when content is fetched, modified, and re-imported. The rendering logic is refactored into a helper function with comprehensive unit test coverage and documentation.

Changes

Cohort / File(s)	Summary
Core Implementation shortcuts/doc/docs_fetch.go	Introduces --omit-title flag for --format=pretty output. Pretty rendering logic refactored into renderFetchPretty helper that conditionally prints H1 title based on omitTitle flag, includes markdown content, and appends pagination hint when has_more is true.
Test Coverage shortcuts/doc/docs_fetch_test.go	Adds comprehensive unit tests validating title inclusion/omission, markdown content preservation, pagination hints, and round-trip safety to prevent title duplication on re-import.
Documentation skills/lark-doc/references/lark-doc-fetch.md	Documents the new --omit-title flag parameter and its use case for preventing title duplication in round-trip workflows.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• fix(doc): post-process docs +fetch output to improve round-trip fidelity #214: Modifies shortcuts/doc/docs_fetch.go to add markdown post-processing pipeline before output, related to how fetched content is rendered and prepared.

Suggested labels

size/M, domain/ccm

Suggested reviewers

• fangshuyu-768
• SunPeiYang996

Poem

🐰 A flag to skip the title line so grand,
When fetching docs across the land,
No duplication shall we see,
Round-trip safe and clean and free!
✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% 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 clearly and specifically summarizes the main change: adding a --omit-title flag to the docs +fetch command to address round-trip safety.
Description check	✅ Passed	The description comprehensively covers all required template sections: Summary, Changes, Test Plan, and Related Issues, with detailed context and scope notes.
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/docs-fetch-omit-title

---

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 80.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.07%. Comparing base (81d22c6) to head (a82dc3e).

Files with missing lines	Patch %	Lines
shortcuts/doc/docs_fetch.go	80.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #625      +/-   ##
==========================================
+ Coverage   60.20%   62.07%   +1.87%     
==========================================
  Files         407      407              
  Lines       43340    35804    -7536     
==========================================
- Hits        26091    22225    -3866     
+ Misses      15221    11551    -3670     
  Partials     2028     2028              

☔ 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@a82dc3e08676a352f4ce08858d8af0c602f9b441

🧩 Skill update

npx skills add larksuite/cli#feat/docs-fetch-omit-title -y -g