feat: add incremental skills sync

[zhangheng023]

Summary

This PR adds incremental official skills sync for lark-cli update and the install wizard. It replaces the legacy stamp-only flow with skills-state.json, preserving user-deleted official skills during normal updates while still auto-installing newly official skills.

Changes

• Add internal/skillscheck/state.go for skills-state.json read/write and version status lookup.
• Add internal/skillscheck/sync.go for official/local skills parsing, incremental sync planning, and best-effort sync orchestration.
• Add skills command primitives to internal/selfupdate/updater.go for listing official/global skills and installing selected skills.
• Update cmd/update/update.go to report skills sync/status in JSON and human output, support --force restore semantics, and keep --check skills-sync side-effect free.
• Update scripts/install-wizard.js to use runtime official skills discovery and write skills-state.json.
• Remove the legacy internal/skillscheck/stamp.go flow and update related tests.

Test Plan

• focused Go validation passed: go test ./internal/selfupdate ./internal/skillscheck ./cmd/update ./cmd -run 'Test(Init|ReadState|WriteState|ReadSyncedVersion|SyncSkills|Plan|ParseSkillsList|SkillsCommands|ListOfficialSkills|RunSkillsAndState|UpdateRun|UpdateNpm_Skills|UpdateAlready|UpdateManual|UpdateNpm_JSON|UpdateNpm_Human|UpdateForce|SetupNotices)' -count=1
• installer syntax check passed: node --check scripts/install-wizard.js
• validate passed: build, vet, unit test, integration test, convention guard, and security test
• local-eval passed for feature-scoped E2E: 3/3 update scenarios passed; full built-in E2E suites were blocked by unrelated sandbox scopes unsupported by the test app/user
• acceptance-reviewer passed: 4/4 cases
• manual verification: lark-cli update --check --json with isolated config dirs confirmed missing/valid/corrupt skills state behavior and no skills-state/stamp writes

Related Issues

N/A

Summary by CodeRabbit

• New Features

  • Programmatic skills management: list, install, and synchronize official/global skills
  • Install wizard now performs version-aware skills sync and persists skills state

• Refactor

  • Migrated skills tracking from a simple stamp to a structured state file
  • Update flow revamped to use state-based skills sync and make --check side-effect-free

• Tests

  • Expanded test coverage for skills parsing, sync planning, state persistence, and update behaviors

[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: a95169ef-e585-4dc8-9d4c-22cb21b8e740

📥 Commits

Reviewing files that changed from the base of the PR and between c5543b8 and 9c3a12f.

📒 Files selected for processing (4)

• cmd/update/update.go
• internal/skillscheck/check.go
• internal/skillscheck/check_test.go
• internal/skillscheck/state.go

🚧 Files skipped from review as they are similar to previous changes (3)

• internal/skillscheck/check.go
• internal/skillscheck/check_test.go
• cmd/update/update.go

---

📝 Walkthrough

Walkthrough

This PR replaces stamp-based skills version tracking with structured JSON state, adds parsing and sync orchestration, extends Updater with skills methods and an override hook, refactors the update command and reporting to use state-based flows, integrates state into skills checks, migrates the install wizard, and removes stamp artifacts.

Changes

Skills Version Tracking: Stamp→State Migration

Layer / File(s)	Summary
State persistence contract and helpers internal/skillscheck/state.go, internal/skillscheck/state_test.go	SkillsState JSON schema with schema versioning and persistence helpers (ReadState, WriteState, ReadSyncedVersion) replace the simple stamp mechanism and are validated by tests for missing/corrupt/valid state and synced-version extraction.
Skills synchronization orchestration internal/skillscheck/sync.go, internal/skillscheck/sync_test.go	ParseSkillsList, PlanSync, and SyncSkills parse lists, compute deterministic sync plans, run installs, aggregate failures and details, and persist updated SkillsState, returning a structured SyncResult.
Updater API skills operations and override hooks internal/selfupdate/updater.go, internal/selfupdate/updater_test.go	Adds SkillsCommandOverride and new methods ListOfficialSkills, ListGlobalSkills, InstallSkill to provide a runnable skills interface and enable test injection of npx behavior.
Update command refactor to state-based skills sync cmd/update/update.go, cmd/update/update_test.go	Switches from runSkillsAndStamp to runSkillsAndState, injects syncSkills for testing, skips stale-file cleanup under --check, and updates JSON/text reporting (skills_action, skills_summary, skills_warning) and tests to reflect SyncResult and SkillsState.
Skills check: state-based version reading internal/skillscheck/check.go, internal/skillscheck/check_test.go, internal/skillscheck/notice.go	Init now uses ReadSyncedVersion and normalizes versions (trim leading v/V); tests and comments now seed/read the skills-state.json state file instead of the stamp.
Install wizard: version-aware skills sync scripts/install-wizard.js	Centralizes config dir and skills-state.json, adds parsing, planning, list and install helpers, replaces one-shot installs with version-aware sync/install steps, and threads CLI version through install steps.
Integration tests and stamp deprecation cleanup cmd/root_integration_test.go	Integration tests updated to seed state via WriteState instead of WriteStamp; deprecated stamp files and tests removed.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• larksuite/cli#723: Continues related work replacing stamp-based skills tracking with state/version-based implementation and updating integration tests.
• larksuite/cli#391: Related update command skills synchronization changes and wiring of updater skills plumbing.
• larksuite/cli#801: Related skillscheck Init/notice changes and integration test updates for missing persisted markers.

Poem

"I am a rabbit, hopping light and spry,
I swapped the stamp for JSON in a blink of eye.
Skills sync hums, plans tidy and neat,
State saved with care — no more stamp’s defeat.
Hooray for order, installs now complete! 🐇"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 13.83% 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: add incremental skills sync' clearly and concisely summarizes the main change: adding incremental skills synchronization functionality.
Description check	✅ Passed	The PR description follows the template structure with a clear Summary, detailed Changes list, comprehensive Test Plan with checkmarks, and Related Issues section.
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/incremental-skills-update

---

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 83.39921% with 42 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.46%. Comparing base (898e0ee) to head (9c3a12f).
⚠️ Report is 24 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/skillscheck/sync.go	84.50%	13 Missing and 9 partials ⚠️
cmd/update/update.go	82.97%	4 Missing and 4 partials ⚠️
internal/selfupdate/updater.go	65.21%	8 Missing ⚠️
internal/skillscheck/state.go	89.18%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #965      +/-   ##
==========================================
+ Coverage   65.92%   67.46%   +1.54%     
==========================================
  Files         523      573      +50     
  Lines       49692    53866    +4174     
==========================================
+ Hits        32758    36340    +3582     
- Misses      14134    14501     +367     
- Partials     2800     3025     +225     

☔ 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@9c3a12f431c608de7a36ed49bb3f0b2100f7c7b3

🧩 Skill update

npx skills add larksuite/cli#feat/incremental-skills-update -y -g

[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 `@cmd/update/update.go`:
- Around line 397-403: The summary map in skillsSummary mixes a numeric count
("official") with slice values ("updated", "added", "skipped_deleted"); change
those slice entries to numeric counters by replacing r.Updated, r.Added, and
r.SkippedDeleted with their lengths (e.g., len(r.Updated), len(r.Added),
len(r.SkippedDeleted)) so all fields are consistently numbers in the returned
map.

In `@internal/skillscheck/check.go`:
- Around line 22-23: The comparison in internal/skillscheck/check.go currently
does raw string equality on version and currentVersion (the snippet with "if
version == currentVersion { return }"); normalize both values by trimming any
leading "v" or "V" before comparing (e.g., use strings.TrimPrefix on both
version and currentVersion) and ensure the strings package is imported, so
"v1.0.21" and "1.0.21" are treated as equal when performing the drift check.

🪄 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: 9ff33895-a0d7-4569-8a06-f121badebce4

📥 Commits

Reviewing files that changed from the base of the PR and between e6bc292 and c5543b8.

📒 Files selected for processing (15)

• cmd/root_integration_test.go
• cmd/update/update.go
• cmd/update/update_test.go
• internal/selfupdate/updater.go
• internal/selfupdate/updater_test.go
• internal/skillscheck/check.go
• internal/skillscheck/check_test.go
• internal/skillscheck/notice.go
• internal/skillscheck/stamp.go
• internal/skillscheck/stamp_test.go
• internal/skillscheck/state.go
• internal/skillscheck/state_test.go
• internal/skillscheck/sync.go
• internal/skillscheck/sync_test.go
• scripts/install-wizard.js

💤 Files with no reviewable changes (2)

• internal/skillscheck/stamp_test.go
• internal/skillscheck/stamp.go