feat(ai-folder-readme-generator): add AI Folder README Generator

[LukasHirt]

AI-generated · OSPO-55 · Gate: ✅ 1.00

Problem

Project spaces and shared folders in oCIS have no description layer. New collaborators must manually browse all contents to understand a folder's purpose. There is no lightweight way to create or maintain a folder README without leaving the app.

Solution

Right-clicking a folder surfaces a "Generate README" action. The extension enumerates the folder's top-level file names (via WebDAV PROPFIND), samples up to ~10 short text/markdown files for content context, and sends the list to the configured LLM. The model returns a structured folder description (purpose, key files, usage notes) that the extension writes as README.md into the folder via WebDAV PUT. If README.md already exists, the user is prompted to overwrite. Tier 1 (structured output): JSON outline → cleanly sectioned Markdown. Tier 2 (text): raw model Markdown written as-is. Tier 3 (no LLM): action is hidden from the menu.

Extension points

global.files.context-actions (action)

Why ship this now

Folder documentation is a perpetual gap in file-sharing platforms; creating a persistent artifact (not just a sidebar panel) sets this apart from the carryover ai-folder-brief-sidebar and gives teams a searchable, shareable file.

What was built

web-app-ai-folder-readme-generator adds a "Generate README" action to the folder context menu (global.files.context-actions), letting a user right-click any single folder and produce a persistent, shareable README.md describing its contents — something existing sidebar-brief style extensions don't leave behind. The extension lists the folder's top-level entries over WebDAV, samples up to 10 text/markdown files (capped at 12,000 total characters, with sampling stopping early once that budget is spent) for content context, and sends the result to the configured LLM. A structured JSON schema (headline, subheadline, purpose, key_files, usage_notes) is requested first; when the model returns valid JSON it's rendered into clean sectioned Markdown, and if parsing fails the extension falls back to writing the model's raw Markdown output as-is. If no LLM is configured, the action is hidden from the menu entirely rather than shown in a broken state.

The core logic lives in src/composables/useReadmeGenerator.ts, which owns folder listing (clientService.webdav.listFiles), file sampling, prompt construction, the JSON/raw-text rendering paths, and the final putFileContents WebDAV write; src/utils/file-support.ts provides the isFolder and isSampleableFile predicates used to filter what gets sampled. src/index.ts registers the ActionExtension itself, gating visibility on a single folder being selected and an LLM being configured, and surfaces success/error notifications via useMessages. When a README.md already exists, src/components/OverwriteDialog.vue prompts the user to confirm before it's overwritten; because this is an action-only extension with no sidebar panel host tree to inherit plugins from, the dialog is mounted standalone via Vue 3's createApp() with its own local vue3-gettext and OcButton (pulled directly from @ownclouders/design-system, added as a new dependency since @ownclouders/web-pkg doesn't re-export it).

Test coverage spans unit specs for useLLM and useReadmeGenerator (folder listing, the sampling cap, overwrite detection, LLM call shape, both rendering paths, the WebDAV write) and OverwriteDialog's emitted events, plus Playwright acceptance tests covering action visibility, a mocked-LLM generation flow asserting the WebDAV PUT and resulting file-list entry, and the overwrite-dialog confirm/cancel path. One known deviation from the original stage plan: the call-shape tests assert the extension's actual messages/maxTokens/temperature request shape rather than a responseFormat field, since this package's useLLM implementation never included that option (it exists only in a sibling template package).

Out of scope for this extension: editing an existing README in place (only generate/overwrite is supported), multi-folder batch generation, and any UI beyond the context-menu action and overwrite dialog — there is no sidebar panel or settings screen.

Gate

Check	Result
Hygiene	✅ ok
Build	✅ ok
Lint	✅ ok
Unit tests	✅ ok
E2E tests	✅ ok
Score	1.00

---

_{Effort: S · 🤖 Generated by extctl}

[kw-security]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[dj4oC]

Adds a context-menu "Generate README" action for folders that calls a same-origin ai-llm-proxy and writes a structured README.md via WebDAV PUT.

• Security: 1 finding — see inline review (CWE-116: Markdown table-cell injection via unescaped LLM output)
• Stability: no findings
• Performance: no findings
• Test coverage: unit + e2e tests present; same-origin enforcement and overwrite flow unit-tested ✅
• TODOs found: 1 — "description": "CANDIDATE" in package.json (placeholder — tracking issue to follow)
• Dependency touched: no new runtime dependencies beyond existing @ownclouders/* workspace packages ✅
• CI status: all green per Snyk ✅ (build verification not possible in cloud review environment)
• Stale review: ⚠️ This PR has been awaiting review since 2026-07-05 — exceeded 48h threshold

🤖 Automated review by Claude Code (security · stability · performance · coverage)

[dj4oC]

TODO tracking: issue #500 opened to replace the "description": "CANDIDATE" placeholder in package.json before publish.

[LukasHirt]

Rebased onto `main` (was 15 commits behind) and addressed the CWE-116 finding from the review.

The prior fix attempt (`e6bbf8eb`) applied the suggested escaping incorrectly, leaving duplicate/broken code in renderMarkdown (an unescaped loop plus a escapeMdCell function declared mid-function) and wasn't DCO-signed. Replaced it with a clean, signed commit:

• Added stripNewlines/escapeMdCell helpers and applied them consistently to all LLM-sourced fields — headline, subheadline, purpose, and the key_files table cells — not just the table, per the review's suggestion.
• Added unit tests covering pipe-escaping and newline-stripping.
• Restored pnpm-lock.yaml entries for this package that were affected by the rebase.

Verified: unit tests (48 passing), check:types, lint, and build all green locally.

The "description": "CANDIDATE" placeholder in package.json is left as-is per the tracked follow-up in #500.

[LukasHirt]

Follow-up (`2484b52b`): addressed two more things flagged in this thread.

• `package.json` `description` no longer says `"CANDIDATE"` — set to a real description matching sibling extensions' style (issue web-app-ai-folder-readme-generator: replace placeholder package description #500 can be closed once this merges).
• `@ownclouders/design-system`, `web-client`, `web-pkg` bumped `^12.3.2` → `^12.5.0`, and `extension-sdk` `12.3.2` → `^12.5.0`, matching what every other package on `main` currently depends on.

Verified again: unit tests (48 passing), `check:types`, `lint`, and `build` all green. Pushed on top of the previous fix — no force-push needed this time.