feat: move Notes assets to managed storage (#873)

* feat(notes): add managed asset storage runtime

* feat(notes): store inserted images in managed assets

* fix(notes): retry images after cloud hydration

* feat(notes): migrate referenced legacy assets

* fix(notes): retry asset migration after cloud hydration

* refactor(notes): extract asset reference parsing

* feat(storage): audit notes assets in vault doctor

* feat(storage): explain notes asset doctor warnings

* test(storage): cover managed assets in vault moves

* docs(notes): document managed image storage

Author: antonreshetov

docs/website/documentation/notes/images.md

@@ -7,7 +7,7 @@ description: "Embed images in massCode Notes with standard markdown syntax, past
 
 Use images when a screenshot, diagram, or visual reference belongs next to the note text.
 
-Images are rendered directly inside your note from standard markdown image syntax. For local images, paste an image from the clipboard or drag an image file into the editor. massCode saves the file to `notes/assets` in your vault and inserts the markdown for you.
+Images are rendered directly inside your note from standard markdown image syntax. For local images, paste an image from the clipboard or drag an image file into the editor. massCode saves new files to `notes/.masscode/assets` in your vault and inserts the markdown for you.
 
 ```md
 ![image-name](masscode://notes-asset/generated-file-name.png)
@@ -19,7 +19,11 @@ You can also use a remote image URL:
 ![Remote screenshot](https://example.com/screenshot.png)
 ```
 
+The `masscode://notes-asset/` URL is resolved by massCode. Other Markdown apps may not display these local images directly. When you copy or synchronize Notes between devices, include the whole vault, including the hidden `notes/.masscode` directory. Copying only Markdown files leaves their local images behind.
+
+Vaults with images in the managed `notes/.masscode/assets` path require a massCode version that supports this layout. Older versions may not display these images.
+
 - Paste or drag images in **Editor** and **Live Preview** modes.
 - View images in **Live Preview** or **Preview** mode.
 - Click an image block in editable modes to reveal and edit its markdown source.
-- Supported pasted and dropped formats: `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`, and `bmp`.
+- New pasted and dropped images can use `png`, `jpg`, or `jpeg`.

src/main/i18n/locales/en_US/preferences.json

@@ -45,6 +45,24 @@
         "invalid-frontmatter": "Invalid frontmatter",
         "conflicted-copy": "Conflicted copy"
       },
+      "assetWarnings": {
+        "NOTES_LEGACY_ASSET": {
+          "message": "{{assetName}} is still stored in the legacy Notes assets folder.",
+          "recommendation": "Keep the whole vault synchronized and scan again after migration completes."
+        },
+        "NOTES_ASSET_MIGRATION_PENDING": {
+          "message": "{{assetName}} is not available locally for migration inspection.",
+          "recommendation": "Make the asset available locally, then scan the vault again."
+        },
+        "NOTES_ASSET_DESTINATION_CONFLICT": {
+          "message": "{{assetName}} differs between the legacy and current Notes assets folders.",
+          "recommendation": "Compare both files and keep the correct copy before removing either one."
+        },
+        "NOTES_ASSET_MISSING": {
+          "message": "{{assetName}} is missing from both Notes assets folders.",
+          "recommendation": "Restore the asset to the vault or remove its reference from the note."
+        }
+      },
       "moreWarnings": "+{{count}} more warnings",
       "warnings": "Warnings"
     }

src/main/i18n/locales/ru_RU/preferences.json

@@ -43,6 +43,24 @@
         "invalid-frontmatter": "Битый frontmatter",
         "conflicted-copy": "Конфликтная копия"
       },
+      "assetWarnings": {
+        "NOTES_LEGACY_ASSET": {
+          "message": "{{assetName}} всё ещё хранится в старой папке изображений Notes.",
+          "recommendation": "Синхронизируйте vault целиком и повторите проверку после завершения миграции."
+        },
+        "NOTES_ASSET_MIGRATION_PENDING": {
+          "message": "{{assetName}} недоступен локально для проверки миграции.",
+          "recommendation": "Сделайте файл доступным локально и повторно проверьте vault."
+        },
+        "NOTES_ASSET_DESTINATION_CONFLICT": {
+          "message": "{{assetName}} отличается в старой и текущей папках изображений Notes.",
+          "recommendation": "Сравните оба файла и сохраните правильную копию, прежде чем удалять любой из них."
+        },
+        "NOTES_ASSET_MISSING": {
+          "message": "{{assetName}} отсутствует в обеих папках изображений Notes.",
+          "recommendation": "Восстановите файл в vault или удалите ссылку на него из заметки."
+        }
+      },
       "moreWarnings": "+{{count}} предупреждений",
       "warnings": "Предупреждения"
     }

src/main/index.ts

@@ -1,5 +1,4 @@
 /* eslint-disable node/prefer-global/process */
-import { readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import { app, BrowserWindow, ipcMain, Menu, protocol, screen } from 'electron'
@@ -10,7 +9,16 @@ import { startThemeWatcher, stopThemeWatcher } from './ipc/handlers/theme'
 import { validateStoredLicense } from './license'
 import { createMainMenu } from './menu/main'
 import { isQuitting, setQuitting } from './quitState'
-import { startMarkdownWatcher, stopMarkdownWatcher } from './storage'
+import {
+  prepareMarkdownWatcher,
+  startMarkdownWatcher,
+  stopMarkdownWatcher,
+} from './storage'
+import {
+  getNotesPaths,
+  resolveNotesAsset,
+} from './storage/providers/markdown/notes/runtime'
+import { getVaultPath } from './storage/providers/markdown/runtime/paths'
 import { ensureFlatSpacesLayout } from './storage/providers/markdown/runtime/spaces'
 import { store } from './store'
 import { startTasksCleanupScheduler, stopTasksCleanupScheduler } from './tasks'
@@ -146,37 +154,8 @@ else {
       const url = new URL(request.url)
 
       if (url.hostname === 'notes-asset') {
-        const fileName = url.pathname.replace(/^\//, '')
-        const vaultPath
-          = (store.preferences.get('storage.vaultPath') as string | null)
-            || path.join(
-              store.preferences.get('storage.rootPath') as string,
-              'markdown-vault',
-            )
-        ensureFlatSpacesLayout(vaultPath)
-        const filePath = path.join(vaultPath, 'notes', 'assets', fileName)
-
-        try {
-          const data = await readFile(filePath)
-          const ext = path.extname(fileName).toLowerCase()
-          const mimeTypes: Record<string, string> = {
-            '.png': 'image/png',
-            '.jpg': 'image/jpeg',
-            '.jpeg': 'image/jpeg',
-            '.gif': 'image/gif',
-            '.webp': 'image/webp',
-            '.svg': 'image/svg+xml',
-            '.bmp': 'image/bmp',
-          }
-          return new Response(data, {
-            headers: {
-              'Content-Type': mimeTypes[ext] || 'application/octet-stream',
-            },
-          })
-        }
-        catch {
-          return new Response('Not found', { status: 404 })
-        }
+        const paths = getNotesPaths(getVaultPath())
+        return resolveNotesAsset(url.pathname.replace(/^\//, ''), paths)
       }
 
       return new Response('Not found', { status: 404 })
@@ -251,6 +230,13 @@ else {
       log('Error registering IPC', error)
     }
 
+    try {
+      prepareMarkdownWatcher()
+    }
+    catch (error) {
+      log('Error preparing markdown watcher', error)
+    }
+
     try {
       validateStoredLicense()
     }

src/main/ipc/handlers/fs.ts

@@ -12,6 +12,11 @@ import {
   writeFileSync,
 } from 'fs-extra'
 import slash from 'slash'
+import {
+  getNotesPaths,
+  parseNotesAssetWritePayload,
+  writeNotesAsset,
+} from '../../storage/providers/markdown/notes/runtime'
 import { ensureFlatSpacesLayout } from '../../storage/providers/markdown/runtime/spaces'
 import { store } from '../../store'
 
@@ -118,30 +123,25 @@ export function registerFsHandlers() {
     })
   })
 
-  ipcMain.handle('fs:notes-asset', (event, { buffer, ext }) => {
+  ipcMain.handle('fs:notes-asset', async (event, payload: unknown) => {
+    const parsedPayload = parseNotesAssetWritePayload(payload)
+    if (!parsedPayload) {
+      throw new TypeError('Invalid Notes asset payload')
+    }
+
     const vaultPath
       = (store.preferences.get('storage.vaultPath') as string | null)
         || join(
           store.preferences.get('storage.rootPath') as string,
           'markdown-vault',
         )
 
-    return new Promise((resolve, reject) => {
-      try {
-        ensureFlatSpacesLayout(vaultPath)
-        const assetsPath = join(vaultPath, 'notes', 'assets')
-        const name = `${generateAssetId()}${ext}`
-        const dest = join(assetsPath, name)
-
-        ensureDirSync(assetsPath)
-        writeFileSync(dest, Buffer.from(buffer))
-
-        resolve(`masscode://notes-asset/${name}`)
-      }
-      catch (error) {
-        reject(error)
-      }
-    })
+    ensureFlatSpacesLayout(vaultPath)
+    return writeNotesAsset(
+      getNotesPaths(vaultPath),
+      parsedPayload.buffer,
+      parsedPayload.ext,
+    )
   })
 
   ipcMain.handle('fs:import-markdown-folder', async () => {

src/main/storage/index.ts

@@ -5,6 +5,7 @@ import type {
 } from './contracts'
 import {
   createMarkdownStorageProvider,
+  prepareMarkdownWatcher,
   startMarkdownWatcher,
   stopMarkdownWatcher,
 } from './providers/markdown'
@@ -27,4 +28,4 @@ export function useHttpStorage(): HttpStorageProvider {
   return httpStorageProvider
 }
 
-export { startMarkdownWatcher, stopMarkdownWatcher }
+export { prepareMarkdownWatcher, startMarkdownWatcher, stopMarkdownWatcher }