feat(apps): add cache debug commands (+cache-get/-delete/-clear)

[chenxingyang1019]

What

Adds three Miaoda app runtime cache debug commands to the apps domain, mirroring the db/file command family conventions:

Command	Risk	Scope	Behavior
+cache-get	read	spark:app:read	Read a single key's value + metadata
+cache-delete	write	spark:app:write	Delete a single key (idempotent)
+cache-clear	high-risk-write	spark:app:write	Clear all keys for the app/env (requires --yes)

• Routes: GET/DELETE /apps/{app_id}/cache, POST /apps/{app_id}/cache/clear.
• Environment via --environment dev|online; omit to let the server auto-select the branch (multi-env app → dev, single-env → online). Env goes in query for get/delete, in body for clear.
• +cache-get output: on hit {key, environment, exists, ttl_ms, value_size_bytes, value}; on miss exists:false with ttl_ms/value_size_bytes null and no value. value_size_bytes is computed CLI-side; value is raw passthrough under --format json and deserialized/indented under --format pretty (raw fallback for non-JSON).
• Numeric output fields (ttl_ms, deleted_key_count) are normalized to a stable JSON number/null so the output type does not drift with the server's wire form.

Testing

• Unit tests for all three commands: hit/miss, idempotent delete, confirmation gate, dry-run method/path/params/body, env omit/explicit, pretty rendering (JSON deserialize + non-JSON fallback), exists-as-string tolerance, and numeric string-wire → JSON number normalization.
• BOE end-to-end suite: 151 field-level assertions, all green — cross-app isolation (same key names don't bleed, clear counts accurate 3/5), dev/online isolation, auto-select on omitted env, multibyte value sizing, input edges (empty/too-long/missing key), and the high-risk confirmation gate.

Notes

• Reviewed with the pr-review and security-cli-audit skills: no exploitable vulnerabilities; path/query inputs are properly encoded (no injection); risk grading and scope split verified.

Summary by CodeRabbit

• New Features

  • Added commands to view, delete, and clear application runtime cache entries.
  • Cache lookup supports readable or raw output, including existence, size, and TTL details.
  • Cache deletion is safe to repeat and treats already-missing entries as successful.
  • Cache clearing requires confirmation and supports dry-run previews and environment selection.

• Documentation

  • Added usage guidance and command references for application cache management.

• Tests

  • Added coverage for cache retrieval, deletion, clearing, formatting, validation, and dry-run behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds +cache-get, +cache-delete, and +cache-clear app shortcuts with shared environment handling, typed cache API calls, normalized output, dry-run support, tests, registration, and operational documentation.

Changes

Application runtime cache

Layer / File(s)	Summary
Shared cache routing and normalization shortcuts/apps/cache_common.go	Adds cache endpoint builders, environment selection, response normalization, TTL formatting, and JSON-aware value rendering helpers.
Cache get command shortcuts/apps/apps_cache_get.go, shortcuts/apps/apps_cache_test.go	Adds +cache-get with hit/miss handling, JSON and pretty output, dry-run behavior, validation, and normalization tests.
Cache delete and clear commands shortcuts/apps/apps_cache_delete.go, shortcuts/apps/apps_cache_clear.go, shortcuts/apps/apps_cache_test.go	Adds idempotent single-key deletion and confirmation-gated cache clearing with structured output, pretty renderers, and dry-run tests.
Shortcut registration and operational reference shortcuts/apps/shortcuts.go, shortcuts/apps/shortcuts_test.go, skills/lark-apps/SKILL.md, skills/lark-apps/references/lark-apps-cache.md	Registers the three commands, updates the shortcut count, and documents cache command usage and rules.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant CacheShortcut
  participant CacheAPI
  participant Renderer
  CLI->>CacheShortcut: invoke cache command
  CacheShortcut->>CacheAPI: read, delete, or clear cache
  CacheAPI-->>CacheShortcut: cache result
  CacheShortcut->>Renderer: format normalized output
  Renderer-->>CLI: JSON or pretty result

Loading

Suggested labels: feature

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding three cache debug commands to the apps domain.
Description check	✅ Passed	The description covers the scope, changes, and testing, though it doesn't use the repo's exact template headings.
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.

✨ 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/apps-cache-cli

---

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

[coderabbitai]

🧹 Nitpick comments (1)

shortcuts/apps/apps_cache_test.go (1)

217-223: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Error-path tests only check err != nil, no typed metadata assertion.

Both tests exercise error paths (required --key, missing --yes confirmation) but only assert that an error occurred, not its typed classification. As per coding guidelines, **/*_test.go error-path tests must assert typed metadata via errs.ProblemOf (category/subtype/param) and cause preservation, not just error presence.

• shortcuts/apps/apps_cache_test.go#L217-L223: in TestAppsCacheGet_RequiresKey, assert errs.ProblemOf(err) category/subtype (e.g. validation/invalid-argument) in addition to the non-nil check.
• shortcuts/apps/apps_cache_test.go#L311-L317: in TestAppsCacheClear_RequiresConfirmation, assert the confirmation-gate error's typed category/subtype similarly.

Note: if the required-flag/confirmation-gate errors at this layer are raw framework errors rather than errs.* typed problems, this guideline may not cleanly apply here — worth confirming the actual error type returned by the flag/confirmation middleware before making this change.

🤖 Prompt for 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.

In `@shortcuts/apps/apps_cache_test.go` around lines 217 - 223, Update
TestAppsCacheGet_RequiresKey in shortcuts/apps/apps_cache_test.go:217-223 and
TestAppsCacheClear_RequiresConfirmation in
shortcuts/apps/apps_cache_test.go:311-317 to assert errs.ProblemOf(err) typed
category/subtype and preserved cause in addition to checking err is non-nil.
First confirm the flag/confirmation middleware returns an errs.* problem; if it
returns a raw framework error, use the appropriate typed assertion or adjust
only as needed to preserve the actual error contract.

Source: Coding guidelines

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

Nitpick comments:
In `@shortcuts/apps/apps_cache_test.go`:
- Around line 217-223: Update TestAppsCacheGet_RequiresKey in
shortcuts/apps/apps_cache_test.go:217-223 and
TestAppsCacheClear_RequiresConfirmation in
shortcuts/apps/apps_cache_test.go:311-317 to assert errs.ProblemOf(err) typed
category/subtype and preserved cause in addition to checking err is non-nil.
First confirm the flag/confirmation middleware returns an errs.* problem; if it
returns a raw framework error, use the appropriate typed assertion or adjust
only as needed to preserve the actual error contract.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 324e8e91-08b2-41af-a15d-4bf25b9bbf38

📥 Commits

Reviewing files that changed from the base of the PR and between e9dabb2 and 881ab63.

📒 Files selected for processing (9)

• shortcuts/apps/apps_cache_clear.go
• shortcuts/apps/apps_cache_delete.go
• shortcuts/apps/apps_cache_get.go
• shortcuts/apps/apps_cache_test.go
• shortcuts/apps/cache_common.go
• shortcuts/apps/shortcuts.go
• shortcuts/apps/shortcuts_test.go
• skills/lark-apps/SKILL.md
• skills/lark-apps/references/lark-apps-cache.md