docs(importing): BookDrop bulk tools + managing book files (bookshelf-eseay.13/.20) #1366

Merged

zombor merged 2 commits from bd-bookshelf-eseay.13 into main 2026-08-06 20:12:15 +00:00

Conversation 2 Commits 2 Files changed 3 +279

zombor commented 2026-08-06 16:01:40 +00:00

Owner

Copy link

Summary

• New page BookDrop Bulk Tools (bookdrop-bulk-tools.md): full coverage of Extract Pattern (placeholder list, date formats, common patterns, preview/apply flow, wildcard tips) and Bulk Edit (available fields, apply behaviour, combine-with-pattern tip). All labels, placeholder names, and button text verified against bookdrop_index.html.

• New page Managing Book Files (managing-book-files.md): covers the Files sub-tab on the book detail page — viewing files, uploading (accepted formats, 2 GB limit), replacing, detaching (removes link, not disk file), deleting, and attaching to a different book. Verified against books_show.html and book_upload_modal_controller.js.

• Updated importing/_index.md with cards for both new pages.

All content is end-user framing with no source/route/internal references.

Test plan

• Hugo builds without error (make docs or hugo in docs/)
• Both new pages render at /docs/importing/bookdrop-bulk-tools/ and /docs/importing/managing-book-files/
• Cards appear in the Importing section index
• All cross-links resolve

Closes bead bookshelf-eseay.13 on merge.
Closes bead bookshelf-eseay.20 on merge.

## Summary - New page **BookDrop Bulk Tools** (`bookdrop-bulk-tools.md`): full coverage of Extract Pattern (placeholder list, date formats, common patterns, preview/apply flow, wildcard tips) and Bulk Edit (available fields, apply behaviour, combine-with-pattern tip). All labels, placeholder names, and button text verified against `bookdrop_index.html`. - New page **Managing Book Files** (`managing-book-files.md`): covers the Files sub-tab on the book detail page — viewing files, uploading (accepted formats, 2 GB limit), replacing, detaching (removes link, not disk file), deleting, and attaching to a different book. Verified against `books_show.html` and `book_upload_modal_controller.js`. - Updated `importing/_index.md` with cards for both new pages. All content is end-user framing with no source/route/internal references. ## Test plan - [ ] Hugo builds without error (`make docs` or `hugo` in `docs/`) - [ ] Both new pages render at `/docs/importing/bookdrop-bulk-tools/` and `/docs/importing/managing-book-files/` - [ ] Cards appear in the Importing section index - [ ] All cross-links resolve Closes bead bookshelf-eseay.13 on merge. Closes bead bookshelf-eseay.20 on merge.

zombor added 1 commit 2026-08-06 16:01:41 +00:00

docs(importing): BookDrop bulk tools + managing book files (bookshelf-eseay.13/.20) ... 2f3227bfcf

Add two new end-user docs pages under docs/content/docs/importing/:

- bookdrop-bulk-tools.md: covers Extract Pattern (placeholders, date
  formats, common patterns, preview/apply flow, tips) and Bulk Edit
  (available fields, one-step apply, tip on combining with Extract Pattern).
  Verified against bookdrop_index.html template — exact button labels,
  placeholder list, and common-pattern chips match the UI.

- managing-book-files.md: covers the Files sub-tab on the book detail page —
  viewing attached files, uploading a new file (accepted formats, 2 GB limit),
  replacing an existing file, detaching (removes link but not disk file),
  deleting permanently, and attaching files to a different book via the ⋮
  menu or bulk selection. Verified against books_show.html and
  book_upload_modal_controller.js.

Update importing/_index.md with cards for both new pages.

Closes bead bookshelf-eseay.13 on merge.
Closes bead bookshelf-eseay.20 on merge.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

zombor commented 2026-08-06 16:16:06 +00:00

Author

Owner

Copy link

Security review — PR #1366 (bd-bookshelf-eseay.13)

Scope confirmation: diff is 3 documentation Markdown files only (docs/content/docs/importing/_index.md, bookdrop-bulk-tools.md, managing-book-files.md). No Go code, no templates, no configuration, no secrets, no credentials were introduced or modified.

Security surface check:

• File upload guidance (managing-book-files.md): the 2 GB maximum file size quoted in the docs matches the real server-enforced cap introduced for book content uploads (the PUT /books/{id}/content middleware exemption from the 1 MB MaxBytes cap — PR #1246). The accepted format list (EPUB, PDF, CBZ, CBR, CB7, CBT, MOBI, AZW3, FB2, M4B, MP3) matches the formats the application actually supports. No guidance tells users to bypass, circumvent, or work around a size or type restriction.
• Permission framing: the docs describe file management actions (upload, replace, detach, delete, bulk edit) as features a logged-in user performs on their own books. No claim is made that these actions are available to unauthenticated users or that any gate can be skipped. The docs do not describe admin-only vs. user-level distinctions (none exist in the documented surfaces), so there is no mismatch to flag.
• Bulk edit / extract pattern guidance: describes client-side field selection and metadata writes only. No path traversal, no URL construction, no server-side file path guidance is present.
• Detach behaviour note: the docs correctly warn that a detached file remains on disk and may be re-discovered on the next scan — an accurate and user-safety-appropriate disclosure (no data silently deleted).
• Secrets/PII: none present.
• No inline style= attributes or other CSP-relevant content.
• No internal symbols, source paths, or implementation details exposed (consistent with the docs-are-end-user-facing policy).

No security findings.

REVIEW VERDICT: 0 blocker, 0 major, 0 minor

Security review — PR #1366 (`bd-bookshelf-eseay.13`) **Scope confirmation:** diff is 3 documentation Markdown files only (`docs/content/docs/importing/_index.md`, `bookdrop-bulk-tools.md`, `managing-book-files.md`). No Go code, no templates, no configuration, no secrets, no credentials were introduced or modified. **Security surface check:** - **File upload guidance** (`managing-book-files.md`): the 2 GB maximum file size quoted in the docs matches the real server-enforced cap introduced for book content uploads (the `PUT /books/{id}/content` middleware exemption from the 1 MB `MaxBytes` cap — PR #1246). The accepted format list (EPUB, PDF, CBZ, CBR, CB7, CBT, MOBI, AZW3, FB2, M4B, MP3) matches the formats the application actually supports. No guidance tells users to bypass, circumvent, or work around a size or type restriction. - **Permission framing**: the docs describe file management actions (upload, replace, detach, delete, bulk edit) as features a logged-in user performs on their own books. No claim is made that these actions are available to unauthenticated users or that any gate can be skipped. The docs do not describe admin-only vs. user-level distinctions (none exist in the documented surfaces), so there is no mismatch to flag. - **Bulk edit / extract pattern guidance**: describes client-side field selection and metadata writes only. No path traversal, no URL construction, no server-side file path guidance is present. - **Detach behaviour note**: the docs correctly warn that a detached file remains on disk and may be re-discovered on the next scan — an accurate and user-safety-appropriate disclosure (no data silently deleted). - **Secrets/PII**: none present. - **No inline `style=` attributes** or other CSP-relevant content. - **No internal symbols, source paths, or implementation details** exposed (consistent with the docs-are-end-user-facing policy). No security findings. REVIEW VERDICT: 0 blocker, 0 major, 0 minor

zombor commented 2026-08-06 16:19:12 +00:00

Author

Owner

Copy link

Code Review — bookshelf-eseay.13/.20 (docs only)

Reviewed the diff against the live source: bookdrop_index.html, bookdrop_extract_pattern_controller.js, bookdrop_bulk_edit_controller.js, books_show.html, book_upload_modal_controller.js, and book_file_replace_controller.js.

---

[MAJOR] docs/content/docs/importing/bookdrop-bulk-tools.md:131 — "Only filled fields are written" contradicts actual implementation
The Tips section states: "Only filled fields are written. If you type a publisher name but leave the language field blank, only the publisher is updated across all selected files. The language field on each file is left exactly as it was." This is factually incorrect. The controller's _buildPatch() (bookdrop_bulk_edit_controller.js) always sends all form fields — blank or not — in the POST body, and the server unconditionally overwrites every received field. A blank language field WILL clear the language on every selected proposal. The controller's own comment (line 16) confirms: "all fields are always included for simplicity (the server overwrites whatever is sent)." This misleads users into thinking a blank field is safe when it will actively erase existing data.
Fix: change the tip to say "Blank fields clear that field on all selected proposals. Fill in only the fields you want to set or overwrite."

[MINOR] docs/content/docs/importing/managing-book-files.md:44 — "Confirm to upload" misnames the Replace dialog's submit button
Step 4 of the Replace section says "Confirm to upload." The Replace modal's submit button (book_file_replace_controller.js line 127) is labeled "Replace", not "Confirm" or "upload". Users following these instructions looking for a "Confirm" button will not find one.
Fix: change "Confirm to upload." to "Click Replace to upload the replacement file."

---

Everything else verified correctly against source:

• Extract Pattern dialog title ("Extract Metadata from Filenames"), button labels ("Preview", "Extract and Apply"), placeholder chips (all 13 match), and common-pattern chips (all 6 match).
• Bulk Edit dialog title ("Bulk Edit Metadata"), button label ("Apply to Selected"), available fields (all present in template).
• Upload File dialog: accepted formats and 2 GB limit match book_upload_modal_controller.js line 111 and accept attribute.
• Primary file star (★ = ★) matches template line 558.
• Detach/Delete disabled-when-only-one-file constraint matches template lines 575–583.
• "Delete Book & All Files" label matches template line 413.
• "Attach to Another Book" in the ⋮ menu matches template line 361.
• Bulk Attach from the book list via the selection toolbar matches books_select_toolbar.html lines 214–219; toolbar is fixed at the bottom per CSS.
• _index.md card additions are consistent in style with existing cards.

REVIEW VERDICT: 0 blocker, 1 major, 1 minor

## Code Review — bookshelf-eseay.13/.20 (docs only) Reviewed the diff against the live source: `bookdrop_index.html`, `bookdrop_extract_pattern_controller.js`, `bookdrop_bulk_edit_controller.js`, `books_show.html`, `book_upload_modal_controller.js`, and `book_file_replace_controller.js`. --- [MAJOR] docs/content/docs/importing/bookdrop-bulk-tools.md:131 — "Only filled fields are written" contradicts actual implementation The Tips section states: "Only filled fields are written. If you type a publisher name but leave the language field blank, only the publisher is updated across all selected files. The language field on each file is left exactly as it was." This is factually incorrect. The controller's `_buildPatch()` (bookdrop_bulk_edit_controller.js) always sends all form fields — blank or not — in the POST body, and the server unconditionally overwrites every received field. A blank language field WILL clear the language on every selected proposal. The controller's own comment (line 16) confirms: "all fields are always included for simplicity (the server overwrites whatever is sent)." This misleads users into thinking a blank field is safe when it will actively erase existing data. Fix: change the tip to say "Blank fields clear that field on all selected proposals. Fill in only the fields you want to set or overwrite." [MINOR] docs/content/docs/importing/managing-book-files.md:44 — "Confirm to upload" misnames the Replace dialog's submit button Step 4 of the Replace section says "Confirm to upload." The Replace modal's submit button (book_file_replace_controller.js line 127) is labeled **"Replace"**, not "Confirm" or "upload". Users following these instructions looking for a "Confirm" button will not find one. Fix: change "Confirm to upload." to "Click **Replace** to upload the replacement file." --- Everything else verified correctly against source: - Extract Pattern dialog title ("Extract Metadata from Filenames"), button labels ("Preview", "Extract and Apply"), placeholder chips (all 13 match), and common-pattern chips (all 6 match). - Bulk Edit dialog title ("Bulk Edit Metadata"), button label ("Apply to Selected"), available fields (all present in template). - Upload File dialog: accepted formats and 2 GB limit match `book_upload_modal_controller.js` line 111 and accept attribute. - Primary file star (★ = ★) matches template line 558. - Detach/Delete disabled-when-only-one-file constraint matches template lines 575–583. - "Delete Book & All Files" label matches template line 413. - "Attach to Another Book" in the ⋮ menu matches template line 361. - Bulk Attach from the book list via the selection toolbar matches `books_select_toolbar.html` lines 214–219; toolbar is fixed at the bottom per CSS. - _index.md card additions are consistent in style with existing cards. REVIEW VERDICT: 0 blocker, 1 major, 1 minor

zombor force-pushed bd-bookshelf-eseay.13 from 2f3227bfcf to 3798eca614 2026-08-06 16:20:59 +00:00 Compare

zombor force-pushed bd-bookshelf-eseay.13 from 3798eca614 to 93190d711a 2026-08-06 18:44:55 +00:00 Compare

zombor force-pushed bd-bookshelf-eseay.13 from 93190d711a to d07333018a 2026-08-06 20:03:57 +00:00 Compare

zombor merged commit 9b4b0b3965 into main 2026-08-06 20:12:15 +00:00

zombor referenced this pull request from a commit 2026-08-06 20:12:21 +00:00

Merge pull request 'docs(importing): BookDrop bulk tools + managing book files (bookshelf-eseay.13/.20)' (#1366) from bd-bookshelf-eseay.13 into main

zombor referenced this pull request from a commit 2026-08-07 01:34:10 +00:00

fix(bookdrop): bulk edit skip-blank fields — blank = leave unchanged (bookshelf-alw8k)

zombor referenced this pull request from a commit 2026-08-07 01:57:05 +00:00

fix(bookdrop): bulk edit skip-blank fields — blank = leave unchanged (bookshelf-alw8k)

zombor referenced this pull request from a commit 2026-08-07 12:56:22 +00:00

fix(bookdrop): bulk edit skip-blank fields — blank = leave unchanged (bookshelf-alw8k)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

zombor/pergamum!1366

No description provided.