feat(deck): add card discovery and card comment tools

Extend the Deck tool module with one discovery tool and four comment
tools, together addressing a gap where the agent could not target
existing cards by name or interact with card discussions.

Card discovery (1 tool):
- list_board_cards: list all cards in a board with metadata (stack,
  labels, assignees, due date, archived status, done, comments count).
  Optional stack_id filter limits to a single stack. Fills the gap
  raised in nextcloud#127 where add_card, add_card_label, assign_card_to_user,
  and delete_card all require a card_id the agent otherwise cannot
  discover (the unified search tool works for keyword lookups but does
  not enumerate and does not return structured metadata).

Card comments (4 tools):
- list_card_comments: list all comments on a card with pagination
- add_card_comment: create a comment, with optional threaded reply support
- update_card_comment: edit an existing comment (author-only)
- delete_card_comment: remove a comment (author-only)

list_board_cards uses the existing /boards/{boardId}/stacks REST
endpoint via the adapter pattern consistent with the other Deck
tools, and flattens the nested stack-cards shape for agent use while
stripping internal fields (ETag, lastModified, order, etc.).

Comments use the Deck OCS API via nc.ocs(), consistent with how
shares.py and other OCS-based tools work. The existing board/card
tools (REST API) are unchanged except for docstring corrections
pointing card_id lookups at list_board_cards instead of list_boards
(which does not return cards).

Tested against Nextcloud 32.0.8 with Deck 1.16.4.

Signed-off-by: Pavlinchen <paulm.schmidt@icloud.com>

Author: Pavlinchen

ex_app/lib/all_tools/deck.py

@@ -25,7 +25,57 @@ async def list_boards():
 
 		return json.dumps(response.json())
 
-	
+	@tool
+	@safe_tool
+	async def list_board_cards(board_id: int, stack_id: Optional[int] = None):
+		"""
+		List all cards in a Deck board with their metadata.
+		Each card includes its id (needed for add_card_comment, add_card_label, assign_card_to_user, delete_card),
+		title, description, stack, labels, assignees, due date, archived status, and done status.
+		Use this tool to find cards when the agent only knows a card by name or context, not by id.
+		:param board_id: the id of the board (obtainable with list_boards)
+		:param stack_id: optional - filter to cards in this specific stack only (obtainable with list_boards)
+		:return: list of cards with id, title, description, stack_id, stack_title, labels, assignees, due_date, archived, done, comments_count
+		"""
+		response = await nc._session._create_adapter().request('GET', f"{nc.app_cfg.endpoint}/index.php/apps/deck/api/v1.0/boards/{board_id}/stacks", headers={
+			"Content-Type": "application/json",
+			"OCS-APIREQUEST": "true",
+		})
+		stacks = response.json()
+
+		cards = []
+		for stack in stacks:
+			if stack_id is not None and stack['id'] != stack_id:
+				continue
+			for card in stack.get('cards', []):
+				labels = []
+				for label in card.get('labels', []):
+					labels.append({
+						'id': label['id'],
+						'title': label['title'],
+						'color': label['color'],
+					})
+				assignees = []
+				for assignment in card.get('assignedUsers', []):
+					participant = assignment.get('participant', {})
+					assignees.append({
+						'uid': participant.get('uid'),
+						'displayname': participant.get('displayname'),
+					})
+				cards.append({
+					'id': card['id'],
+					'title': card['title'],
+					'description': card.get('description', ''),
+					'stack_id': stack['id'],
+					'stack_title': stack['title'],
+					'labels': labels,
+					'assignees': assignees,
+					'due_date': card.get('duedate'),
+					'archived': card.get('archived', False),
+					'done': card.get('done'),
+					'comments_count': card.get('commentsCount', 0),
+				})
+		return json.dumps(cards)
 
 	@tool
 	@dangerous_tool
@@ -65,7 +115,7 @@ async def add_card_label(board_id: int, stack_id: int, card_id: int, label_id: i
 		Add a label to a card
 		:param board_id: the id of the board (obtainable with list_boards)
 		:param stack_id: the id of the stack (obtainable with list_boards)
-		:param card_id: the id of the card (obtainable with list_boards)
+		:param card_id: the id of the card (obtainable with list_board_cards)
 		:param label_id: the id of the label to add (obtainable with list_boards - labels are listed in board details)
 		:return: success confirmation
 		"""
@@ -85,7 +135,7 @@ async def assign_card_to_user(board_id: int, stack_id: int, card_id: int, user_i
 		Assign a card to a user
 		:param board_id: the id of the board (obtainable with list_boards)
 		:param stack_id: the id of the stack (obtainable with list_boards)
-		:param card_id: the id of the card (obtainable with list_boards)
+		:param card_id: the id of the card (obtainable with list_board_cards)
 		:param user_id: the user id to assign the card to
 		:return: success confirmation
 		"""
@@ -105,7 +155,7 @@ async def delete_card(board_id: int, stack_id: int, card_id: int):
 		Delete a card from a board
 		:param board_id: the id of the board (obtainable with list_boards)
 		:param stack_id: the id of the stack (obtainable with list_boards)
-		:param card_id: the id of the card to delete (obtainable with list_boards)
+		:param card_id: the id of the card to delete (obtainable with list_board_cards)
 		:return: success confirmation
 		"""
 		response = await nc._session._create_adapter().request('DELETE', f"{nc.app_cfg.endpoint}/index.php/apps/deck/api/v1.0/boards/{board_id}/stacks/{stack_id}/cards/{card_id}", headers={
@@ -115,16 +165,78 @@ async def delete_card(board_id: int, stack_id: int, card_id: int):
 
 		return json.dumps(response.json())
 
+	# --- Card Comments (OCS API) ---
+
+	@tool
+	@safe_tool
+	async def list_card_comments(card_id: int, limit: int = 20, offset: int = 0):
+		"""
+		List all comments on a Deck card
+		:param card_id: the id of the card (obtainable with list_board_cards)
+		:param limit: maximum number of comments to return (default 20)
+		:param offset: pagination offset (default 0)
+		:return: list of comments with id, message, author, and creation date
+		"""
+		return await nc.ocs('GET', f'/ocs/v2.php/apps/deck/api/v1.0/cards/{card_id}/comments', params={
+			'limit': limit,
+			'offset': offset,
+		})
+
+	@tool
+	@dangerous_tool
+	async def add_card_comment(card_id: int, message: str, parent_id: Optional[int] = None):
+		"""
+		Add a comment to a Deck card
+		:param card_id: the id of the card (obtainable with list_board_cards)
+		:param message: the comment text (max 1000 characters)
+		:param parent_id: optional id of a parent comment for threaded replies (obtainable with list_card_comments)
+		:return: the created comment
+		"""
+		payload = {'message': message}
+		if parent_id is not None:
+			payload['parentId'] = parent_id
+		return await nc.ocs('POST', f'/ocs/v2.php/apps/deck/api/v1.0/cards/{card_id}/comments', json=payload)
+
+	@tool
+	@dangerous_tool
+	async def update_card_comment(card_id: int, comment_id: int, message: str):
+		"""
+		Update an existing comment on a Deck card. Only the comment author can update their own comments.
+		:param card_id: the id of the card (obtainable with list_board_cards)
+		:param comment_id: the id of the comment to update (obtainable with list_card_comments)
+		:param message: the new comment text (max 1000 characters)
+		:return: the updated comment
+		"""
+		return await nc.ocs('PUT', f'/ocs/v2.php/apps/deck/api/v1.0/cards/{card_id}/comments/{comment_id}', json={
+			'message': message,
+		})
+
+	@tool
+	@dangerous_tool
+	async def delete_card_comment(card_id: int, comment_id: int):
+		"""
+		Delete a comment from a Deck card. Only the comment author can delete their own comments.
+		:param card_id: the id of the card (obtainable with list_board_cards)
+		:param comment_id: the id of the comment to delete (obtainable with list_card_comments)
+		:return: confirmation of deletion
+		"""
+		return await nc.ocs('DELETE', f'/ocs/v2.php/apps/deck/api/v1.0/cards/{card_id}/comments/{comment_id}')
+
 	return [
 		list_boards,
+		list_board_cards,
 		add_card,
 		add_card_label,
 		assign_card_to_user,
-		delete_card
+		delete_card,
+		list_card_comments,
+		add_card_comment,
+		update_card_comment,
+		delete_card_comment,
 	]
 
 def get_category_name():
 	return "Deck"
 
 async def is_available(nc: AsyncNextcloudApp):
-	return 'deck' in await nc.capabilities
+	return 'deck' in await nc.capabilities