feat(collectives): Add Collectives support (13 tools for page management)

[Pavlinchen]

Summary

• Adds a new collectives.py tool module wrapping the Collectives OCS API plus WebDAV for page markdown I/O
• 13 tools covering the full page lifecycle: list, read, create, write, rename, move, emoji, trash, restore, permanent delete
• No tool for keyword search — search.py already auto-generates 3 Collectives search tools from the existing search providers (collectives, collectives-pages, collectives-page-content)

Motivation

The Context Agent currently has no interaction with Collectives, Nextcloud's wiki-style knowledge base app. This prevents the agent from reading, creating, or editing user knowledge bases — a core collaboration use case. The existing unified search tools can find Collectives pages, but not enumerate, create, or modify them.

Implementation Details

Disclaimer

Implementation from a technical perspective was done mainly by a LLM (Claude Opus 4.7 max effort).
Every tool and endpoint response shape was validated end-to-end against Nextcloud 32.0.8 + Collectives 3.6.1, with a full lifecycle smoke test completed before opening the PR.

Endpoints used

All OCS endpoints are under /ocs/v2.php/apps/collectives/api/v1.0/. Markdown I/O uses WebDAV at /remote.php/dav/files/{user}/{collectivePath}/{filePath}/{fileName}, with the path components coming from the page's own metadata.

Tool	Method	Path
list_collectives	GET	/collectives
list_collective_pages	GET	/collectives/{cid}/pages
get_page	GET	/collectives/{cid}/pages/{pid}
get_page_content	GET	WebDAV at page's file
list_page_trash	GET	/collectives/{cid}/pages/trash
create_page	POST	/collectives/{cid}/pages/{parentId}
update_page_content	PUT	WebDAV at page's file
rename_page	PUT	/collectives/{cid}/pages/{pid} (body {title})
move_page	PUT	/collectives/{cid}/pages/{pid} (body {parentId})
set_page_emoji	PUT	/collectives/{cid}/pages/{pid}/emoji
trash_page	DELETE	/collectives/{cid}/pages/{pid}
restore_page	PATCH	/collectives/{cid}/pages/trash/{pid}
delete_page_permanently	DELETE	/collectives/{cid}/pages/trash/{pid}

Patterns followed

• OCS calls use nc.ocs() (matches circles.py, shares.py)
• WebDAV I/O uses nc._session._create_adapter(True).request(...) (matches files.py)
• is_available() probes the OCS endpoint and returns False on exception (matches mail.py, since Collectives does not register an OCS capability)
• WebDAV paths are URL-encoded via urllib.parse.quote to handle spaces and special characters in collective/page names

Design decisions

1. No AI disclaimer is appended to content writes. Unlike chat messages or card descriptions (where modules like talk.py/deck.py append a note), wiki page content is the user's authored source material. Auto-appending "Edited by Nextcloud AI Assistant." to every page edit would pollute the wiki with notes that can't be cleanly removed later. If a user wants such a disclaimer, they can ask the agent to include it in the content itself.

2. get_page_content returns an empty string on 404. Pages typically materialize their .md file on creation, but under transient conditions the file may not yet exist — the empty string gives the agent a consistent contract.

3. No standalone search tool. search.py already generates search_collectives, search_collectives_pages, and search_collectives_page_content via unified search providers. Adding a scoped search would be redundant.

4. No Collective-level create/delete tools. Creating a Collective also provisions a backing Circle/Team, which is tied to membership management. Better addressed in a separate PR if desired.

5. No tag tools in this PR. Tags (Collectives 3.1.0+) are a small, well-contained sub-feature that can be added in a follow-up PR without affecting the page tools.

Test Plan

Tested against Nextcloud 32.0.8 + Collectives 3.6.1 with a full-lifecycle smoke test:

• list_collectives returns all user's collectives with level, canEdit, canShare
• list_collective_pages returns flat list with parentId and subpageOrder for tree reconstruction
• get_page returns single-page metadata
• get_page_content fetches markdown via WebDAV for a top-level page (landing)
• get_page_content fetches markdown via WebDAV for a nested page in a collective whose name contains spaces
• list_page_trash returns empty when no trashed pages
• create_page creates a child under the specified parent
• update_page_content writes markdown; subsequent get_page_content returns the written content
• rename_page updates title and the fileName on disk
• move_page updates parentId and the resulting filePath
• set_page_emoji round-trips UTF-8 emoji characters
• trash_page sets trashTimestamp; page appears in list_page_trash
• restore_page clears trashTimestamp
• delete_page_permanently removes the trashed page (HTTP 200)
• Integration test with Context Agent MCP server (requires running ExApp)

[marcelklehr]

Tested and confirmed working.

[Pavlinchen]

Likely open to do: add AI disclaimer (like for PR #155)? @marcelklehr What do you think?
Initial descision see above, but I'm not 100% sure on the way forward with this...

[marcelklehr]

not sure either, will discuss internally :)

[Pavlinchen]

To avoid this entirely, perhaps we can replace the update_page_content with more of a "surgical" insert?
E.g. "insert XYZ into page "Documentation" after ABC"
--> action would then be to insert the users note verbatim as a new line/block of text after a specified point (e.g. heading/previous paragraph)

[marcelklehr]

How about, we add to the tool description to make sure there is a note at the bottom of the article that says it was edited with the help of AI? Then the agent can make sure the note is always there and we don't have the problem of adding or removing it superfluously

[github-actions]

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)