Resources Folder Management#

Overview#

Folders in the Resources UI are virtual constructs — not real directories on disk. When a user creates a folder via "New Folder", the server writes a single DB record (a .folder placeholder attachment) with name: '.folder' and type: 'folder' but creates no physical file or directory 1. All folder-scoped queries rely on the perfixPath column (a comma-separated path like parent,child) stored on every attachments row.

Key Files#

How Folder Records Work#

• Creation: createFolder inserts a row with path = /api/file/<parent>/<folderName>/.folder, name = '.folder', type = 'folder', and perfixPath = <comma-path>. No directory is created on disk 2.
• Listing: The list endpoint runs a raw SQL WITH combined_items query that DISTINCT ON (folder_name) using perfixPath to aggregate files into folder rows. Both note-linked and standalone attachments are included via OR [note.accountId, accountId] 3.
• Navigation: ResourceStore tracks currentFolder as a /-separated string; the server converts it to a ,-separated perfixPath internally 4.

Known Bugs (issue #1128)#

1. Rename throws ENOENT#

Root cause: The rename endpoint iterates all attachments whose perfixPath starts with the old folder path and calls FileService.moveFile(oldPath, newPath) for each one 5. The .folder placeholder has no physical file, so moveFile throws ENOENT: no such file or directory /app/.blinko/files/<name>/.folder 6.

2. Delete shows "Success" but folder persists#

Root cause: The delete endpoint queries attachments using only note.accountId (via the note relation join) 7. The .folder placeholder is stored with a direct accountId and no noteId, so the query returns zero rows. The code then hits the early return { success: true } without deleting anything from the DB 8.

3. DB records not cleaned up after deletion#

Even when actual files in a folder were found and deleted from disk, the corresponding attachments rows were never removed — leaving orphaned DB records 9.

4. UI always shows "Success" toast on failure#

PromiseCall catches errors and returns undefined rather than re-throwing. When wrapped in ToastPlugin.promise(), a resolved-undefined is treated as success, masking the backend ENOENT 6.

Fix (PR #1169)#

PR #1169 addresses all three backend bugs in server/routerTrpc/attachment.ts:

• Rename: Skip FileService.moveFile() when attachment.name === '.folder' or attachment.type === 'folder'; only update the DB record with the new path 9.
• Delete query: Change the folder findMany to OR [note.accountId, accountId] so the .folder placeholder is included 9.
• DB cleanup: Add tx.attachments.deleteMany() after physical file deletion (folder path) and tx.attachments.delete() after single-file deletion 9.
• Skip placeholder on delete: Skip FileService.deleteFile() for .folder entries to avoid ENOENT when deleting empty folders 9.

Other Gotchas#

• Missing depth field on createFolder: The endpoint does not set the depth column 10, while file uploads do. This can cause the root-level listing query (which filters depth = 0) to miss or mis-sort standalone folder placeholders 6.
• Docker permission issues: If /app/.blinko/files is owned by root but the app runs as a different user, moveFile/deleteFile also fail with ENOENT or permission errors regardless of the placeholder bug 6.
• UI state refresh: ResourceStore.refreshTicker triggers a reload via useEffect; callers must increment it after mutations or the UI will show stale data 11.