feat: implement promote file to book and split book functionality

artifacts/2026-02-20/promote_file_to_book.md

@@ -0,0 +1,42 @@
+# Promote File to Book Specification
+
+## Overview
+This feature allows users to "promote" files from an existing book into a standalone book in the library. This is useful when a single library item incorrectly groups multiple separate books or files together. The feature has two mechanisms: a quick single-file context action, and a bulk "Split Book" Wizard.
+
+## UI Requirements
+
+### 1. Single-File Promotion (Quick Action)
+- Added to the "Library Files" table (`LibraryFilesTableRow.vue`).
+- A new context menu item "Promote to book" is available for active files.
+- Selecting it opens a confirmation prompt.
+
+### 2. Multi-File Book Split (Wizard)
+- A "Split Book" button added to the header of the "Library Files" table (`LibraryFilesTable.vue`).
+- Opens `SplitBookModal.vue`, passing the current library item files.
+- Displays a table of audio/ebook files with an input binding for "Book Number" (Default 1).
+- Includes an "Assign 1 to N" quick action for automatically splitting every single file into its own standalone book.
+- Submits an array of file assignments containing the target Book Number.
+
+## Backend Requirements
+
+### 1. Single-File Promotion
+- **Endpoint**: `POST /api/items/:id/file/:fileid/promote`
+- **Logic**:
+  1. Determine a new folder name based on the target filename.
+  2. Create the target destination folder.
+  3. Move the specified file.
+  4. Detach record from the current database entry.
+  5. Trigger `LibraryScanner.scan(library)` to generate the standalone library item.
+
+### 2. Multi-file Book Split
+- **Endpoint**: `POST /api/items/:id/split`
+- **Request Body**: `{ assignments: [{ ino: string, bookNumber: number }] }`
+- **Logic**:
+  1. Group payload assignments by `bookNumber` (ignoring `1` since that designates the current book).
+  2. Iterate through groups. For each group `[Book 2, Book 3, etc]`:
+     a. Compute target folder path based on original directory + `- Book [N]`.
+     b. Ensure custom directory is created.
+     c. Iterate through `ino` targets and migrate target resources.
+  3. Detach file payload records from existing library item.
+  4. Emit completion via `SocketAuthority.libraryItemEmitter`.
+  5. Call `LibraryScanner.scan(library)` to construct the new entities sequentially.

client/components/modals/item/SplitBookModal.vue

@@ -0,0 +1,120 @@
+<template>
+  <modals-modal ref="modal" v-model="show" name="split-book" :width="600" :height="'unset'" :processing="processing">
+    <template #outer>
+      <div class="absolute top-0 left-0 p-5 w-2/3 overflow-hidden">
+        <p class="text-3xl text-white truncate">{{ $strings.HeaderSplitBook || 'Split Book' }}</p>
+      </div>
+    </template>
+    <div class="px-6 py-4 w-full h-full text-sm bg-bg rounded-lg shadow-lg border border-black-300">
+      <p class="text-sm text-gray-300 mb-4">{{ $strings.MessageSplitBookDescription || 'Assign each file to a new book number to split them into separate library items.' }}</p>
+      
+      <div class="flex justify-end mb-2">
+        <ui-btn small @click="autoAssignSequence">{{ $strings.ButtonAutoAssignSequence || 'Assign 1 to N' }}</ui-btn>
+      </div>
+
+      <div class="max-h-96 overflow-y-auto">
+        <table class="w-full text-sm">
+          <thead>
+            <tr>
+              <th class="text-left py-2 px-2">{{ $strings.LabelFilename || 'Filename' }}</th>
+              <th class="text-center w-32 px-2 border-l border-primary">{{ $strings.LabelBookGroup || 'Book Number' }}</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="file in filesWithAssignment" :key="file.ino" class="border-t border-primary">
+              <td class="py-2 px-2 truncate" :title="file.metadata.filename">{{ file.metadata.filename }}</td>
+              <td class="text-center px-2 border-l border-primary">
+                <input type="number" min="1" v-model.number="file.bookNumber" class="w-16 bg-primary text-center px-1 py-1 rounded outline-none w-full" />
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      <div class="mt-4 flex justify-end">
+        <ui-btn @click="show = false" class="mr-2">{{ $strings.ButtonCancel }}</ui-btn>
+        <ui-btn color="success" :loading="processing" @click="submit">{{ $strings.ButtonSubmit }}</ui-btn>
+      </div>
+    </div>
+  </modals-modal>
+</template>
+
+<script>
+export default {
+  props: {
+    value: Boolean,
+    libraryItem: {
+      type: Object,
+      default: () => {}
+    }
+  },
+  data() {
+    return {
+      processing: false,
+      filesWithAssignment: []
+    }
+  },
+  computed: {
+    show: {
+      get() {
+        return this.value
+      },
+      set(val) {
+        this.$emit('input', val)
+      }
+    }
+  },
+  watch: {
+    show: {
+      handler(newVal) {
+        if (newVal) {
+          this.init()
+        }
+      }
+    }
+  },
+  methods: {
+    init() {
+      const audioAndEbooks = (this.libraryItem.libraryFiles || []).filter(f => f.fileType === 'audio' || f.fileType === 'ebook')
+      this.filesWithAssignment = audioAndEbooks.map(file => {
+        return {
+          ...file,
+          bookNumber: 1
+        }
+      })
+    },
+    autoAssignSequence() {
+      this.filesWithAssignment.forEach((file, ind) => {
+        file.bookNumber = ind + 1
+      })
+    },
+    async submit() {
+      this.processing = true
+      
+      const assignments = this.filesWithAssignment.map(f => ({
+        ino: f.ino,
+        bookNumber: f.bookNumber
+      })).filter(a => a.bookNumber > 1) // Only send ones being detached/split
+
+      if (!assignments.length) {
+        this.$toast.warning('No files assigned to new books.')
+        this.processing = false
+        return
+      }
+
+      try {
+        await this.$axios.$post(`/api/items/${this.libraryItem.id}/split`, {
+          assignments
+        })
+        this.$toast.success('Successfully split files into new books')
+        this.show = false
+      } catch (error) {
+        console.error('Failed to split book', error)
+        this.$toast.error('Failed to split book: ' + (error.response?.data || error.message))
+      } finally {
+        this.processing = false
+      }
+    }
+  }
+}
+</script>

client/components/tables/LibraryFilesTable.vue

@@ -7,6 +7,7 @@
       </div>
       <div class="grow" />
       <ui-btn v-if="userIsAdmin" small :color="showFullPath ? 'bg-gray-600' : 'bg-primary'" class="mr-2 hidden md:block" @click.stop="toggleFullPath">{{ $strings.ButtonFullPath }}</ui-btn>
+      <ui-btn v-if="userCanDelete" small color="bg-primary" class="mr-2" @click.stop="showSplitBookModal = true">{{ $strings.ButtonSplitBook || 'Split Book' }}</ui-btn>
       <div class="cursor-pointer h-10 w-10 rounded-full hover:bg-black-400 flex justify-center items-center duration-500" :class="showFiles ? 'transform rotate-180' : ''">
         <span class="material-symbols text-4xl">&#xe313;</span>
       </div>
@@ -28,6 +29,7 @@
     </transition>
 
     <modals-audio-file-data-modal v-model="showAudioFileDataModal" :library-item-id="libraryItemId" :audio-file="selectedAudioFile" />
+    <modals-item-split-book-modal v-model="showSplitBookModal" :library-item="libraryItem" />
   </div>
 </template>
 
@@ -46,6 +48,7 @@ export default {
       showFiles: false,
       showFullPath: false,
       showAudioFileDataModal: false,
+      showSplitBookModal: false,
       selectedAudioFile: null
     }
   },

client/components/tables/LibraryFilesTableRow.vue

@@ -55,6 +55,12 @@ export default {
           action: 'download'
         })
       }
+      if (this.userCanDelete && (this.file.audioFile || this.file.isEBookFile)) {
+        items.push({
+          text: this.$strings.LabelPromoteToBook || 'Promote to book',
+          action: 'promote'
+        })
+      }
       if (this.userCanDelete) {
         items.push({
           text: this.$strings.ButtonDelete,
@@ -77,6 +83,8 @@ export default {
         this.deleteLibraryFile()
       } else if (action === 'download') {
         this.downloadLibraryFile()
+      } else if (action === 'promote') {
+        this.promoteLibraryFile()
       } else if (action === 'more') {
         this.$emit('showMore', this.file.audioFile)
       }
@@ -103,6 +111,27 @@ export default {
     },
     downloadLibraryFile() {
       this.$downloadFile(this.downloadUrl, this.file.metadata.filename)
+    },
+    promoteLibraryFile() {
+      const payload = {
+        message: this.$strings.MessageConfirmPromoteFile || 'Are you sure you want to promote this file to a new book?',
+        callback: (confirmed) => {
+          if (confirmed) {
+            this.$axios
+              .$post(`/api/items/${this.libraryItemId}/file/${this.file.ino}/promote`)
+              .then(() => {
+                this.$toast.success(this.$strings.ToastPromoteFileSuccess || 'File successfully promoted to new book')
+              })
+              .catch((error) => {
+                console.error('Failed to promote file', error)
+                const errorMsg = error.response?.data || 'Unknown error'
+                this.$toast.error(this.$strings.ToastPromoteFileFailed || `Failed to promote file: ${errorMsg}`)
+              })
+          }
+        },
+        type: 'yesNo'
+      }
+      this.$store.commit('globals/setConfirmPrompt', payload)
     }
   },
   mounted() {}

server/controllers/LibraryItemController.js

@@ -13,6 +13,7 @@ const { getAudioMimeTypeFromExtname, encodeUriPath, sanitizeFilename } = require
 const LibraryItemScanner = require('../scanner/LibraryItemScanner')
 const AudioFileScanner = require('../scanner/AudioFileScanner')
 const Scanner = require('../scanner/Scanner')
+const LibraryScanner = require('../scanner/LibraryScanner')
 const Watcher = require('../Watcher')
 
 const libraryItemsBookFilters = require('../utils/queries/libraryItemsBookFilters')
@@ -1477,6 +1478,176 @@ class LibraryItemController {
     res.sendStatus(200)
   }
 
+  /**
+   * POST api/items/:id/file/:fileid/promote
+   *
+   * @param {LibraryItemControllerRequestWithFile} req
+   * @param {Response} res
+   */
+  async promoteLibraryFile(req, res) {
+    if (!req.user.canDelete) {
+      Logger.warn(`[LibraryItemController] User "${req.user.username}" attempted to promote file without permission`)
+      return res.sendStatus(403)
+    }
+
+    if (!req.libraryItem.isBook) {
+      return res.status(400).send('Promote only available for books')
+    }
+
+    const libraryFile = req.libraryFile
+
+    // Determine new folder name based on file name without extension
+    const ext = Path.extname(libraryFile.metadata.path)
+    const baseName = Path.basename(libraryFile.metadata.path, ext)
+    const sanitizedFolderName = Database.libraryItemModel.getConsolidatedFolderName('Unknown Author', baseName)
+
+    const library = await Database.libraryModel.findByIdWithFolders(req.libraryItem.libraryId)
+    // Find the library folder that currently contains this item
+    const targetFolder = library.libraryFolders.find((f) => req.libraryItem.path.startsWith(f.path)) || library.libraryFolders[0]
+
+    const targetPath = Path.join(targetFolder.path, sanitizedFolderName)
+
+    if (await fs.pathExists(targetPath)) {
+      return res.status(409).send('Destination folder already exists')
+    }
+
+    try {
+      await fs.ensureDir(targetPath)
+
+      const newFilePath = Path.join(targetPath, Path.basename(libraryFile.metadata.path))
+      await fs.move(libraryFile.metadata.path, newFilePath)
+
+      // Remove the file from the original library item
+      req.libraryItem.libraryFiles = req.libraryItem.libraryFiles.filter((lf) => lf.ino !== req.params.fileid)
+      req.libraryItem.changed('libraryFiles', true)
+
+      if (req.libraryItem.media.audioFiles.some((af) => af.ino === req.params.fileid)) {
+        req.libraryItem.media.audioFiles = req.libraryItem.media.audioFiles.filter((af) => af.ino !== req.params.fileid)
+        req.libraryItem.media.changed('audioFiles', true)
+      } else if (req.libraryItem.media.ebookFile?.ino === req.params.fileid) {
+        req.libraryItem.media.ebookFile = null
+        req.libraryItem.media.changed('ebookFile', true)
+      }
+
+      if (!req.libraryItem.media.hasMediaFiles) {
+        req.libraryItem.isMissing = true
+      }
+
+      if (req.libraryItem.media.changed()) {
+        await req.libraryItem.media.save()
+      }
+
+      await req.libraryItem.save()
+
+      SocketAuthority.libraryItemEmitter('item_updated', req.libraryItem)
+
+      // Trigger scan on the library to pick up the new folder
+      LibraryScanner.scan(library)
+
+      res.json({
+        success: true
+      })
+    } catch (error) {
+      Logger.error(`[LibraryItemController] Failed to promote file`, error)
+      return res.status(500).send(error.message || 'Failed to promote file')
+    }
+  }
+
+  /**
+   * POST api/items/:id/split
+   *
+   * @param {LibraryItemControllerRequest} req
+   * @param {Response} res
+   */
+  async splitLibraryItem(req, res) {
+    if (!req.user.canDelete) {
+      Logger.warn(`[LibraryItemController] User "${req.user.username}" attempted to split book without permission`)
+      return res.sendStatus(403)
+    }
+
+    if (!req.libraryItem.isBook) {
+      return res.status(400).send('Split only available for books')
+    }
+
+    const assignments = req.body.assignments || []
+    if (!assignments.length) {
+      return res.status(400).send('No file assignments provided')
+    }
+
+    const library = await Database.libraryModel.findByIdWithFolders(req.libraryItem.libraryId)
+    const targetFolder = library.libraryFolders.find((f) => req.libraryItem.path.startsWith(f.path)) || library.libraryFolders[0]
+
+    // Group files by bookNumber
+    const groups = {}
+    assignments.forEach(({ ino, bookNumber }) => {
+      // Only care about split files (bookNumber > 1)
+      if (bookNumber > 1) {
+        if (!groups[bookNumber]) groups[bookNumber] = []
+        groups[bookNumber].push(ino)
+      }
+    })
+
+    if (Object.keys(groups).length === 0) {
+      return res.status(400).send('No files were assigned to new books')
+    }
+
+    // Process each group
+    try {
+      const originalPathBase = Path.basename(req.libraryItem.path)
+      let filesRemoved = 0
+
+      for (const [bookNumber, inos] of Object.entries(groups)) {
+        const newFolderName = `${originalPathBase} - Book ${bookNumber}`
+        const targetPath = Path.join(targetFolder.path, newFolderName)
+
+        await fs.ensureDir(targetPath)
+
+        for (const ino of inos) {
+          const libraryFile = req.libraryItem.getLibraryFileWithIno(ino)
+          if (!libraryFile) continue
+
+          const newFilePath = Path.join(targetPath, Path.basename(libraryFile.metadata.path))
+          await fs.move(libraryFile.metadata.path, newFilePath)
+
+          // Remove the file from original library item
+          req.libraryItem.libraryFiles = req.libraryItem.libraryFiles.filter((lf) => lf.ino !== ino)
+          
+          if (req.libraryItem.media.audioFiles.some((af) => af.ino === ino)) {
+            req.libraryItem.media.audioFiles = req.libraryItem.media.audioFiles.filter((af) => af.ino !== ino)
+          } else if (req.libraryItem.media.ebookFile?.ino === ino) {
+            req.libraryItem.media.ebookFile = null
+          }
+          filesRemoved++
+        }
+      }
+
+      if (filesRemoved > 0) {
+        req.libraryItem.changed('libraryFiles', true)
+        req.libraryItem.media.changed('audioFiles', true)
+        req.libraryItem.media.changed('ebookFile', true)
+
+        if (!req.libraryItem.media.hasMediaFiles) {
+          req.libraryItem.isMissing = true
+        }
+
+        if (req.libraryItem.media.changed()) {
+          await req.libraryItem.media.save()
+        }
+
+        await req.libraryItem.save()
+        SocketAuthority.libraryItemEmitter('item_updated', req.libraryItem)
+
+        // Trigger scan on the library to pick up the new folders
+        LibraryScanner.scan(library)
+      }
+
+      res.json({ success: true, filesMoved: filesRemoved })
+    } catch (error) {
+      Logger.error(`[LibraryItemController] Failed to split book`, error)
+      return res.status(500).send(error.message || 'Failed to split book')
+    }
+  }
+
   /**
    * GET api/items/:id/file/:fileid/download
    * Same as GET api/items/:id/file/:fileid but allows logging and restricting downloads

server/routers/ApiRouter.js

@@ -131,9 +131,11 @@ class ApiRouter {
     this.router.get('/items/:id/ffprobe/:fileid', LibraryItemController.middleware.bind(this), LibraryItemController.getFFprobeData.bind(this))
     this.router.get('/items/:id/file/:fileid', LibraryItemController.middleware.bind(this), LibraryItemController.getLibraryFile.bind(this))
     this.router.delete('/items/:id/file/:fileid', LibraryItemController.middleware.bind(this), LibraryItemController.deleteLibraryFile.bind(this))
+    this.router.post('/items/:id/file/:fileid/promote', LibraryItemController.middleware.bind(this), LibraryItemController.promoteLibraryFile.bind(this))
     this.router.get('/items/:id/file/:fileid/download', LibraryItemController.middleware.bind(this), LibraryItemController.downloadLibraryFile.bind(this))
     this.router.get('/items/:id/ebook/:fileid?', LibraryItemController.middleware.bind(this), LibraryItemController.getEBookFile.bind(this))
     this.router.patch('/items/:id/ebook/:fileid/status', LibraryItemController.middleware.bind(this), LibraryItemController.updateEbookFileStatus.bind(this))
+    this.router.post('/items/:id/split', LibraryItemController.middleware.bind(this), LibraryItemController.splitLibraryItem.bind(this))
     this.router.post('/items/:id/move', LibraryItemController.middleware.bind(this), LibraryItemController.move.bind(this))
     this.router.post('/items/:id/consolidate', LibraryItemController.middleware.bind(this), LibraryItemController.consolidate.bind(this))