Render focused catalog command help

[akcorca]

Summary

• Render focused help for craken <resource> <action> --help when the server catalog advertises a matching command.
• Show local option help for message cursors, workspace activity filters, and wiki recent limits.
• Render route request metadata and response examples when the server catalog includes them.
• Keep global craken --help behavior as the broad catalog view.

Validation

• MISE_TRUSTED_CONFIG_PATHS=$PWD mise exec -- go test ./...
• git diff --check

Fixes #8
Related: corca-ai/craken-agents#292

Summary by CodeRabbit

릴리스 노트

• New Features

  • 특정 명령에 대한 상세 도움말 기능 추가 - 명령어와 함께 --help 플래그를 사용할 때 해당 명령의 사용법, 옵션, 응답 예시 등을 우선 표시합니다.

• Documentation

  • 기본 도움말과 작업 도움말이 서버 카탈로그를 통해 어떻게 렌더링되는지에 대한 설명 추가

• Tests

  • 포커스된 명령어 도움말이 올바르게 렌더링되는지 검증하는 테스트 추가

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9b34be70-a9b9-488c-b27f-d1464be23a3a

📥 Commits

Reviewing files that changed from the base of the PR and between c053969 and c950a56.

📒 Files selected for processing (4)

• docs/architecture.md
• internal/craken/command.go
• internal/craken/command_test.go
• internal/craken/generic.go

📜 Recent review details

🔇 Additional comments (1)

docs/architecture.md (1)

9-9: LGTM!

---

Walkthrough

서버 카탈로그 메타데이터를 통해 특정 명령(craken <resource> <action> --help)에 대한 포커스된 도움말을 렌더링하도록 CLI 도움말 시스템을 확장했습니다. 입력 처리, 라우팅 로직, 포맷팅 함수, 테스트가 추가되었으며 구조체 필드가 메타데이터 파싱을 지원하도록 확장되었습니다.

Changes

포커스된 도움말 렌더링

Layer / File(s)	Summary
카탈로그 데이터 구조 확장 internal/craken/generic.go	route 구조체에 PathParameters, QueryParameters, BodyFields, ResponseExample 필드와 JSON 태그를 추가하고, catalogField 타입을 정의하여 서버 응답의 필드 메타데이터를 표현합니다.
도움말 입력 처리 및 라우팅 internal/craken/command.go	parseCommand에서 --help 플래그를 감지하면 Action을 "help"로 정규화하고, runHelp가 focusedHelpTarget으로 특정 명령을 카탈로그에서 검색해 포커스된 도움말을 우선 렌더링하도록 제어 흐름을 추가합니다.
포커스된 도움말 렌더링 구현 internal/craken/command.go	printFocusedCommandHelp가 Usage/설명/예제/로컬 옵션/Operation/필드 그룹(Path/Query/Body)/응답 예시를 순차적으로 출력하며, printCatalogFieldGroup, fieldDetail, printResponseExample, localCommandHelpOptions가 필드 정보와 JSON 응답을 포맷팅합니다.
포커스된 도움말 테스트 internal/craken/command_test.go	TestFocusedHelpRendersServerCommandLocalOptionsAndMetadata에서 channel messages, workspace activity, wiki recent 명령별로 포커스된 도움말에 예상 메타데이터와 옵션이 포함되고 전역 카탈로그 섹션이 제외되는지 검증합니다.
아키텍처 문서화 docs/architecture.md	기본 도움말과 작업별 도움말이 /api/client 카탈로그를 1회 조회해 서버 소유 명령 구문과 메타데이터를 렌더링하고, 특정 명령 매칭 시 로컬 옵션과 경로 정보를 보강하는 방식을 설명합니다.

Sequence Diagram

sequenceDiagram
  participant User
  participant parseCommand
  participant runHelp
  participant focusedHelpTarget
  participant printFocusedCommandHelp
  participant printCatalogHelp
  User->>parseCommand: craken channel messages --help
  parseCommand->>parseCommand: --help 감지 시 Action="help" 설정
  parseCommand->>runHelp: cmd 전달
  runHelp->>focusedHelpTarget: cmd.Resource/Action 조합 조회
  alt 특정 명령 매칭
    focusedHelpTarget-->>runHelp: cliCommand, route 반환
    runHelp->>printFocusedCommandHelp: 포커스된 도움말 렌더링
    printFocusedCommandHelp->>User: Usage/옵션/응답 예시 출력
  else 매칭 실패
    focusedHelpTarget-->>runHelp: nil 반환
    runHelp->>printCatalogHelp: 전체 카탈로그 도움말 렌더링
    printCatalogHelp->>User: 전역 도움말 출력
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• corca-ai/craken-cli#5: 메인 PR의 internal/craken/command.go와 command_test.go 변경(포커스된 help 렌더링)이 리트리브드 PR의 printCatalogHelp 및 "Server commands" 렌더링 로직과 동일한 헬프 출력 코드 경로를 함께 확장합니다.
• corca-ai/craken-cli#4: 메인 PR의 서버 카탈로그 기반 도움말 기초(internal/craken/command.go, command_test.go, internal/craken/generic.go)가 리트리브드 PR과 동일하게 /api/client를 통한 헬프 렌더링을 수정하며, 메인 PR이 이를 포커스된 작업별 도움말로 확장합니다.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 변경 사항의 핵심을 명확하게 요약합니다. '포커스된 카탈로그 명령 도움말 렌더링'은 서버 카탈로그 기반으로 특정 명령에 대한 상세 도움말을 표시하는 주요 기능을 정확히 반영합니다.
Linked Issues check	✅ Passed	PR이 연결된 이슈 #8의 모든 주요 요구사항을 충족합니다. 포커스된 도움말 렌더링, 커서 옵션 표시, 메타데이터 및 응답 예시 표시, 글로벌 --help 보존, 테스트 커버리지가 모두 구현되었습니다.
Out of Scope Changes check	✅ Passed	모든 변경 사항이 이슈 #8의 범위 내에 있습니다. docs, command.go, command_test.go, generic.go의 수정 사항들은 모두 포커스된 도움말 렌더링 기능을 구현하기 위한 것입니다.

_{✏️ 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 codex/catalog-focused-help

---

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