Skip to content

fix: folder and file names stay within the 255-byte filesystem limit - #473

Merged
kikootwo merged 3 commits into
mainfrom
fix/264-path-byte-limit
Oct 27, 2026
Merged

kikootwo merged 3 commits into
mainfrom
fix/264-path-byte-limit

Conversation

@kikootwo

@kikootwo kikootwo commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Closes #264

What changed

  • New src/lib/utils/path-component.ts: capComponentBytes() cuts a folder or file name to 255 UTF-8 bytes between grapheme clusters (Intl.Segmenter), so a multi-byte character, a surrogate pair, an accented letter, a flag or a joined emoji is never split, and trims trailing spaces and dots from the cut. capFilenameBytes(stem, suffix) cuts only the stem, so a suffix such as - 3.mp3 or .m4b stays whole. capPathComponents() applies the cap to each part of a /-separated path. A name that already fits comes back unchanged.
  • substituteTemplate() (src/lib/utils/path-template.util.ts) caps each folder of the finished path, after escaped braces are resolved, so \{ counts as the one byte it becomes.
  • buildRenamedFilename() keeps - N and the extension whole and cuts only the name.
  • FileOrganizer (src/lib/utils/file-organizer.ts): the chapter-merge output name keeps .m4b, and when metadata tagging is on it is capped at 251 bytes, so the tagger's <name>.tmp copy fits in 255. Duplicate track names in nested folders cut only the folder prefix, so -Track01.mp3 stays; the (2) dedup name keeps its suffix and extension; an ebook's source name (no rename) keeps its extension.
  • The tagger's .tmp suffix is now one constant (TAG_TEMP_SUFFIX) shared by the tagger and the merge name. No other step writes a suffix next to a name RMAB creates: the merger's concat and chapter lists, the copy and the ASIN step use their own short names.
  • The 200-character cap per variable is unchanged.
  • Docs: documentation/phase3/file-organization.md (Path Sanitization, Fixed Issues 15). The path-template.util.ts header now points at that doc; its old target did not exist.

Why

A path component is limited to 255 bytes, but the cap counted characters. In UTF-8 Cyrillic takes 2 bytes per letter, CJK 3 and emoji 4, so a 200-character title could reach 400 or 600 bytes. The cap was also per variable, so {title} - {series} could pass 255 bytes in plain ASCII. Nothing capped the joined component, and the organize failed with ENAMETOOLONG. The import failed cleanly; no files were lost.

Evidence

  • New tests/lib/utils/path-byte-limit.test.ts runs the real substituteTemplate and buildRenamedFilename: long Cyrillic, CJK and emoji titles give components of at most 255 bytes that round-trip as UTF-8, are a prefix of the title and keep - N and the extension. Two 200-character ASCII variables in one folder are cut to 255 bytes. Short names, names of exactly 254 and 255 bytes, the 200-character ASCII cap and escaped braces give today's output, byte for byte.
  • New tests/utils/file-organizer.byte-limit.test.ts: duplicate track names in long Cyrillic nested folders stay distinct, keep -Track01.mp3 and fit; a (2) name at the limit keeps its suffix; CD1-Track01.mp3 and Chapter 1 (2).mp3 are unchanged.
  • tests/utils/file-organizer.test.ts: the chapter-merge output name for long Cyrillic titles fits and keeps .m4b. With tagging on, a 200-letter and a 252-byte Cyrillic title leave the .tmp copy at 255 bytes or less. With tagging off, a 250-byte title keeps its full name. Book: Title still gives Book Title.m4b, tagged or not.
  • New tests/lib/utils/path-component.test.ts covers the helper: cut points for 2-, 3- and 4-byte characters; a joined family emoji, a flag and an e with a combining accent at the cut are dropped whole, never split; the trailing trim; the suffix kept; empty parts dropped.
  • With main's src (08dc816) and this branch's tests, the 3 test files that run against main: 13 failed, 72 passed, all on an assertion (byte counts of 256 to 604). On this branch the 4 test files pass 100/100.

Checks

  • Unit tests for the changed code (vitest related on path-component.ts, file-organizer.ts and metadata-tagger.ts, plus the changed test files): PASS, 105 files, 1551 passed, 1 skipped
  • Type check and lint: PASS (tsc --noEmit clean; ESLint on the 8 touched code and test files reports the same 30 errors and 7 warnings main has in file-organizer.ts and its test, none in the others)
  • No image build or E2E run: the change is in src/lib and tests only
  • Full unit suite: PR Tests (CI)

Risk and rollback

  • Folder names and renamed file names change only when a component is over 255 bytes. No existing library folder is renamed.
  • Some books that import today import differently, all with chapter merging on:
    • The folder fit but the merged name did not: titles of 252 to 255 bytes under {author}/{title}, or long titles under templates whose folders don't hold the full title, such as {author}/{asin}. On main the merge failed and the book imported as separate chapter files. Now it imports as one merged .m4b with a cut name, tagged when tagging is on.
    • With tagging on, merged names of 252 to 255 bytes: on main the merge worked but the tagger's .tmp copy was too long, so the file was placed without the tagger's tags and the job recorded a tagging warning. Now the name loses a character or two and the file is tagged.
    • With file renaming on, the placed name comes from the rename template, so only the separate-files case above changes.
  • On a filesystem that counts UTF-16 units rather than bytes, such as NTFS through a Docker Desktop bind mount, a name over 255 bytes but within 255 characters used to import whole; new imports now get the cut name.
  • A cut name can collide with another book's cut name only if both share their first 255 bytes; in that case they share a folder, as two books with the same title and author would today. Placement never overwrites a file.
  • Rollback: revert this PR. No stored data is changed.

Release note

🤖 Generated with Claude Code

…mport

The 200-character cap per template variable counts characters, but a folder
or file name is limited to 255 bytes. Cyrillic, CJK and emoji titles passed it
and failed the import with ENAMETOOLONG, and two variables in one component
could pass it in ASCII. A shared helper (path-component.ts) now cuts every
finished component to 255 UTF-8 bytes between code points: template folders,
renamed files (" - N" and the extension kept), the chapter-merge output name,
source-aware names (only the folder prefix cut), " (N)" dedup names and ebook
source names. A component that already fits is unchanged.

Closes #264.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kikootwo and others added 2 commits October 27, 2026 03:30
…names between grapheme clusters

When tagging is on, the chapter-merge name is capped at 251 bytes so the
tagger's <name>.tmp copy fits in 255. The cut now falls between grapheme
clusters, so a joined emoji, a flag or an accented letter stays whole.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo marked this pull request as ready for review October 27, 2026 07:48
@kikootwo
kikootwo merged commit b37b9eb into main Oct 27, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/264-path-byte-limit branch October 27, 2026 07:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Path template length cap counts characters, not bytes, so non-Latin titles can exceed the filesystem limit

1 participant