AI Folder Brief Sidebar Panel

[LukasHirt]

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

Problem

When navigating an unfamiliar folder — a project handover, a shared space —
there is no quick way to understand what it contains or why it is structured
that way. Users must manually browse and open files.

Solution

When a folder (not a file) is selected, a "Folder Brief" panel appears in the
right sidebar. It reads the file listing (names, types, sizes, dates — no
content download) and sends it to the LLM, which returns a short narrative:
folder purpose, main content categories, and a note on recent activity. With
structured-output models, output is sectioned (Summary / Files by type /
Recent changes); with basic text models, a single paragraph is returned.
Without a configured LLM, the panel renders a static file-type breakdown
from the listing alone.

Extension points

global.files.sidebar

Why ship this now

Project spaces and handover folders are daily friction for oCIS collaborators;
folder-level AI context removes that friction with no new backend and no file
content transfer.

What was built

web-app-ai-folder-brief-sidebar is a new oCIS Web extension that registers a single global.files.sidebar panel, visible only when exactly one folder is selected — the inverse of the existing global.files.sidebar guards used by the AI doc summary package. The panel reads the folder's child listing (names, MIME types, sizes, modification dates; no file content is downloaded) and surfaces a contextual brief in the right sidebar.

The core logic lives in two composables. useLlm manages LLM configuration and status, setting the panel to 'ready' or 'unconfigured' depending on whether the application config provides an endpoint. useFolderBrief handles the full brief lifecycle: it fetches the folder's children via WebDAV at depth 1, serialises a compact listing (capped at 8 000 characters), and — when an LLM is configured — posts it to /chat/completions. The response is parsed as structured JSON into { summary, filesByType, recentChanges }; if parsing fails, the raw text is returned as a single-paragraph fallback. When no LLM is configured, the composable computes a static MIME-category breakdown instead, with isStatic: true to suppress the Regenerate button. Error handling covers HTTP 401, 403, 404, 429, and 5xx responses, network TypeError, and DOMException timeouts, with per-class messaging and an error-clearing path on retry.

FolderBriefPanel.vue renders five distinct states: a loading placeholder, an error alert, a static breakdown, a full structured LLM brief, and the empty-folder short-circuit. It auto-triggers on mount via onMounted(() => { ensureReady(); triggerBrief(); }) and exposes a Regenerate button only for LLM-generated briefs. The entry point (src/index.ts) wires the composables to the panel via componentAttrs, reads applicationConfig?.llm to construct the LlmConfig, and registers the extension with the isVisible guard items?.length === 1 && items[0]?.isFolder === true.

The extension ships 12 unit tests across the two composables and the panel component, plus four Playwright acceptance tests covering tab visibility, LLM-mocked brief rendering, server-error display, and Regenerate invocation. No backend changes are required; the extension is purely client-side and degrades gracefully to a static file-type breakdown when no LLM endpoint is configured.

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.