Repository navigation
fix: folder and file names stay within the 255-byte filesystem limit - #473
Merged
Merged
Conversation
…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>
…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
marked this pull request as ready for review
October 27, 2026 07:48
This was referenced Oct 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #264
What changed
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.mp3or.m4bstays 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- Nand 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>.tmpcopy fits in 255. Duplicate track names in nested folders cut only the folder prefix, so-Track01.mp3stays; the(2)dedup name keeps its suffix and extension; an ebook's source name (no rename) keeps its extension..tmpsuffix 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.documentation/phase3/file-organization.md(Path Sanitization, Fixed Issues 15). Thepath-template.util.tsheader 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 withENAMETOOLONG. The import failed cleanly; no files were lost.Evidence
tests/lib/utils/path-byte-limit.test.tsruns the realsubstituteTemplateandbuildRenamedFilename: 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- Nand 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.tests/utils/file-organizer.byte-limit.test.ts: duplicate track names in long Cyrillic nested folders stay distinct, keep-Track01.mp3and fit; a(2)name at the limit keeps its suffix;CD1-Track01.mp3andChapter 1 (2).mp3are 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.tmpcopy at 255 bytes or less. With tagging off, a 250-byte title keeps its full name.Book: Titlestill givesBook Title.m4b, tagged or not.tests/lib/utils/path-component.test.tscovers 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.main'ssrc(08dc816) and this branch's tests, the 3 test files that run againstmain: 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
vitest relatedonpath-component.ts,file-organizer.tsandmetadata-tagger.ts, plus the changed test files): PASS, 105 files, 1551 passed, 1 skippedtsc --noEmitclean; ESLint on the 8 touched code and test files reports the same 30 errors and 7 warningsmainhas infile-organizer.tsand its test, none in the others)src/liband tests onlyRisk and rollback
{author}/{title}, or long titles under templates whose folders don't hold the full title, such as{author}/{asin}. Onmainthe merge failed and the book imported as separate chapter files. Now it imports as one merged.m4bwith a cut name, tagged when tagging is on.mainthe merge worked but the tagger's.tmpcopy 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.Release note
🤖 Generated with Claude Code