epub-optimizer 0.0.0-stage → 3.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1434 -2
  3. package/dist/src/batch.d.ts +34 -0
  4. package/dist/src/batch.js +137 -0
  5. package/dist/src/cli.d.ts +7 -0
  6. package/dist/src/cli.js +275 -0
  7. package/dist/src/index.d.ts +23 -0
  8. package/dist/src/index.js +24 -0
  9. package/dist/src/optimization.d.ts +7 -0
  10. package/dist/src/optimization.js +207 -0
  11. package/dist/src/pipeline.d.ts +2 -0
  12. package/dist/src/pipeline.js +48 -0
  13. package/dist/src/processors/archive-processor.d.ts +26 -0
  14. package/dist/src/processors/archive-processor.js +170 -0
  15. package/dist/src/processors/epub-processor.d.ts +17 -0
  16. package/dist/src/processors/epub-processor.js +133 -0
  17. package/dist/src/processors/font-characters.d.ts +2 -0
  18. package/dist/src/processors/font-characters.js +227 -0
  19. package/dist/src/processors/font-engine.d.ts +6 -0
  20. package/dist/src/processors/font-engine.js +101 -0
  21. package/dist/src/processors/font-limits.d.ts +3 -0
  22. package/dist/src/processors/font-limits.js +3 -0
  23. package/dist/src/processors/font-processor.d.ts +4 -0
  24. package/dist/src/processors/font-processor.js +121 -0
  25. package/dist/src/processors/font-runner.d.ts +8 -0
  26. package/dist/src/processors/font-runner.js +94 -0
  27. package/dist/src/processors/font-worker.d.ts +1 -0
  28. package/dist/src/processors/font-worker.js +12 -0
  29. package/dist/src/processors/html-processor.d.ts +22 -0
  30. package/dist/src/processors/html-processor.js +190 -0
  31. package/dist/src/processors/image-converter.d.ts +14 -0
  32. package/dist/src/processors/image-converter.js +481 -0
  33. package/dist/src/processors/image-processor.d.ts +24 -0
  34. package/dist/src/processors/image-processor.js +165 -0
  35. package/dist/src/processors/js-processor.d.ts +7 -0
  36. package/dist/src/processors/js-processor.js +59 -0
  37. package/dist/src/processors/lazy-img.d.ts +5 -0
  38. package/dist/src/processors/lazy-img.js +48 -0
  39. package/dist/src/processors/svg-optimizer.d.ts +5 -0
  40. package/dist/src/processors/svg-optimizer.js +49 -0
  41. package/dist/src/scripts/create-epub.d.ts +2 -0
  42. package/dist/src/scripts/create-epub.js +29 -0
  43. package/dist/src/scripts/fix/fix-span-tags.d.ts +2 -0
  44. package/dist/src/scripts/fix/fix-span-tags.js +36 -0
  45. package/dist/src/scripts/fix/fix-xml.d.ts +3 -0
  46. package/dist/src/scripts/fix/fix-xml.js +59 -0
  47. package/dist/src/scripts/fix/index.d.ts +5 -0
  48. package/dist/src/scripts/fix/index.js +20 -0
  49. package/dist/src/scripts/fix/remove-empty-styles.d.ts +10 -0
  50. package/dist/src/scripts/fix/remove-empty-styles.js +53 -0
  51. package/dist/src/scripts/fix/xhtml-files.d.ts +2 -0
  52. package/dist/src/scripts/fix/xhtml-files.js +34 -0
  53. package/dist/src/scripts/ops/add-chapter-sections-to-toc.d.ts +5 -0
  54. package/dist/src/scripts/ops/add-chapter-sections-to-toc.js +242 -0
  55. package/dist/src/scripts/ops/add-cover-image-property.d.ts +2 -0
  56. package/dist/src/scripts/ops/add-cover-image-property.js +27 -0
  57. package/dist/src/scripts/ops/ncx.d.ts +6 -0
  58. package/dist/src/scripts/ops/ncx.js +19 -0
  59. package/dist/src/scripts/ops/update-cover-linear.d.ts +11 -0
  60. package/dist/src/scripts/ops/update-cover-linear.js +45 -0
  61. package/dist/src/scripts/ops/update-structure.d.ts +5 -0
  62. package/dist/src/scripts/ops/update-structure.js +22 -0
  63. package/dist/src/scripts/ops/update-summary-page.d.ts +2 -0
  64. package/dist/src/scripts/ops/update-summary-page.js +53 -0
  65. package/dist/src/scripts/ops/update-toc-with-cover.d.ts +2 -0
  66. package/dist/src/scripts/ops/update-toc-with-cover.js +140 -0
  67. package/dist/src/scripts/utils.d.ts +53 -0
  68. package/dist/src/scripts/utils.js +92 -0
  69. package/dist/src/scripts/validate-epub.d.ts +12 -0
  70. package/dist/src/scripts/validate-epub.js +185 -0
  71. package/dist/src/storage.d.ts +30 -0
  72. package/dist/src/storage.js +286 -0
  73. package/dist/src/types.d.ts +51 -0
  74. package/dist/src/types.js +1 -0
  75. package/dist/src/utils/author-workflow-config.d.ts +17 -0
  76. package/dist/src/utils/author-workflow-config.js +95 -0
  77. package/dist/src/utils/buffered-process.d.ts +8 -0
  78. package/dist/src/utils/buffered-process.js +36 -0
  79. package/dist/src/utils/cli-config.d.ts +4 -0
  80. package/dist/src/utils/cli-config.js +84 -0
  81. package/dist/src/utils/config.d.ts +49 -0
  82. package/dist/src/utils/config.js +58 -0
  83. package/dist/src/utils/diagnostics.d.ts +11 -0
  84. package/dist/src/utils/diagnostics.js +38 -0
  85. package/dist/src/utils/epub-doctor.d.ts +78 -0
  86. package/dist/src/utils/epub-doctor.js +301 -0
  87. package/dist/src/utils/epub-features.d.ts +20 -0
  88. package/dist/src/utils/epub-features.js +105 -0
  89. package/dist/src/utils/epub-integrity.d.ts +25 -0
  90. package/dist/src/utils/epub-integrity.js +197 -0
  91. package/dist/src/utils/epub-text.d.ts +13 -0
  92. package/dist/src/utils/epub-text.js +106 -0
  93. package/dist/src/utils/epub-utils.d.ts +79 -0
  94. package/dist/src/utils/epub-utils.js +207 -0
  95. package/dist/src/utils/epubcheck-report.d.ts +35 -0
  96. package/dist/src/utils/epubcheck-report.js +68 -0
  97. package/dist/src/utils/file-size.d.ts +13 -0
  98. package/dist/src/utils/file-size.js +40 -0
  99. package/dist/src/utils/files.d.ts +14 -0
  100. package/dist/src/utils/files.js +39 -0
  101. package/dist/src/utils/html-report.d.ts +17 -0
  102. package/dist/src/utils/html-report.js +95 -0
  103. package/dist/src/utils/i18n.d.ts +5 -0
  104. package/dist/src/utils/i18n.js +9 -0
  105. package/dist/src/utils/output-transaction.d.ts +8 -0
  106. package/dist/src/utils/output-transaction.js +146 -0
  107. package/dist/src/utils/package-root.d.ts +2 -0
  108. package/dist/src/utils/package-root.js +15 -0
  109. package/dist/src/utils/path-safety.d.ts +2 -0
  110. package/dist/src/utils/path-safety.js +30 -0
  111. package/dist/src/utils/pipeline-options.d.ts +34 -0
  112. package/dist/src/utils/pipeline-options.js +49 -0
  113. package/dist/src/utils/png-animation.d.ts +7 -0
  114. package/dist/src/utils/png-animation.js +44 -0
  115. package/dist/src/utils/run-report.d.ts +49 -0
  116. package/dist/src/utils/run-report.js +71 -0
  117. package/dist/src/utils/temp-dir.d.ts +11 -0
  118. package/dist/src/utils/temp-dir.js +80 -0
  119. package/dist/src/utils/watch-lock.d.ts +8 -0
  120. package/dist/src/utils/watch-lock.js +100 -0
  121. package/dist/src/utils/watch-summary.d.ts +13 -0
  122. package/dist/src/utils/watch-summary.js +130 -0
  123. package/dist/src/utils/xhtml-structure.d.ts +7 -0
  124. package/dist/src/utils/xhtml-structure.js +53 -0
  125. package/dist/src/utils/xhtml.d.ts +27 -0
  126. package/dist/src/utils/xhtml.js +205 -0
  127. package/dist/src/utils/xml-dtd.d.ts +6 -0
  128. package/dist/src/utils/xml-dtd.js +133 -0
  129. package/dist/src/watch.d.ts +21 -0
  130. package/dist/src/watch.js +328 -0
  131. package/package.json +99 -3
  132. package/scripts/install-epubcheck.sh +44 -0
@@ -0,0 +1,207 @@
1
+ #!/usr/bin/env node
2
+ import { reportError, reportInfo } from "./utils/diagnostics.js";
3
+ import fs from "fs-extra";
4
+ import { snapshotResources, compareResources, writeHtmlReport } from "./utils/html-report.js";
5
+ import { processEpubContent } from "./processors/epub-processor.js";
6
+ import { reportFileSizeComparison } from "./utils/file-size.js";
7
+ import { runFixes } from "./scripts/fix/index.js";
8
+ import { runStructureUpdates } from "./scripts/ops/update-structure.js";
9
+ import { run as createEPUBFile } from "./scripts/create-epub.js";
10
+ import { runAsync as validateEPUB } from "./scripts/validate-epub.js";
11
+ import { removeTempDir } from "./utils/temp-dir.js";
12
+ import { assertDistinctInputOutput, assertSafeOutputTarget, assertSafeReportPath, commitCandidateOutput, createCandidateOutputPath, discardCandidateOutput, } from "./utils/output-transaction.js";
13
+ import { completePipelineReport, createPipelineReport, printProfile, recordSkippedStep, runReportedStep, writePipelineReport, } from "./utils/run-report.js";
14
+ import { assertEpubContentIntegrity, collectEpubContentMetrics, compareEpubContentMetrics, } from "./utils/epub-integrity.js";
15
+ import { assertEpubTextPreserved, collectEpubTextSnapshot, } from "./utils/epub-text.js";
16
+ import { loadAuthorWorkflowConfig } from "./utils/author-workflow-config.js";
17
+ import { runDoctor } from "./utils/epub-doctor.js";
18
+ import { resolvePngBackground } from "./utils/pipeline-options.js";
19
+ export async function runOptimization(args, processingOptions = {}) {
20
+ resolvePngBackground(args);
21
+ if (args.reportHtml) {
22
+ assertSafeReportPath(args.reportHtml, args.input, args.output);
23
+ if (args.reportJson)
24
+ assertDistinctInputOutput(args.reportJson, args.reportHtml);
25
+ if (args.doctor || args.inspect)
26
+ throw new Error("HTML reports are available for optimization runs only.");
27
+ }
28
+ if (args.doctor || args.inspect) {
29
+ if (args.reportJson) {
30
+ assertSafeReportPath(args.reportJson, args.input, args.output);
31
+ }
32
+ await runDoctor({ input: args.input, reportJson: args.reportJson });
33
+ return;
34
+ }
35
+ assertDistinctInputOutput(args.input, args.output);
36
+ await assertSafeOutputTarget(args.output);
37
+ if (args.reportJson) {
38
+ assertSafeReportPath(args.reportJson, args.input, args.output);
39
+ }
40
+ const report = createPipelineReport({
41
+ input: args.input,
42
+ output: args.output,
43
+ preset: args.preset,
44
+ strict: args.strict,
45
+ });
46
+ let candidateOutput;
47
+ let reportWriteError;
48
+ let textBefore;
49
+ let resourcesBefore;
50
+ try {
51
+ candidateOutput = await createCandidateOutputPath(args.output);
52
+ // Step 1: Extract + run every content processor. Skip packaging —
53
+ // repair/author steps still need the temp dir, and the candidate archive
54
+ // is created only once after every transformation is complete.
55
+ reportInfo("\n=== Optimize EPUB ===");
56
+ await processEpubContent(args, {
57
+ runStep: (name, operation) => runReportedStep(report, name, args.strict, () => processingOptions.runStep ? processingOptions.runStep(name, operation) : operation()),
58
+ skipStep: (name, reason) => {
59
+ recordSkippedStep(report, name, reason);
60
+ processingOptions.skipStep?.(name, reason);
61
+ },
62
+ afterExtract: async (tempDir) => {
63
+ report.content = {
64
+ before: await collectEpubContentMetrics(tempDir),
65
+ };
66
+ textBefore = await collectEpubTextSnapshot(tempDir);
67
+ if (args.reportHtml)
68
+ resourcesBefore = await snapshotResources(tempDir);
69
+ await processingOptions.afterExtract?.(tempDir);
70
+ },
71
+ });
72
+ // Step 2: Explicit XHTML repair passes. The author workflow implies repair,
73
+ // while the generic optimizer remains conservative by default.
74
+ if (args.repair) {
75
+ reportInfo("\n=== XHTML Repair Passes ===");
76
+ await runReportedStep(report, "Repair XHTML", args.strict, () => runFixes({ tempDir: args.temp, strict: args.strict }));
77
+ }
78
+ else {
79
+ recordSkippedStep(report, "Repair XHTML", "Enable with --repair or the author preset.");
80
+ }
81
+ // The optimizing and repair passes must not change what the reader sees.
82
+ // Checked before the author workflow, which edits navigation text on purpose.
83
+ reportInfo("\n=== Validate Text Preservation ===");
84
+ await runReportedStep(report, "Validate text preservation", args.strict, async () => {
85
+ if (!textBefore) {
86
+ throw new Error("Input text was not collected after extraction.");
87
+ }
88
+ assertEpubTextPreserved(textBefore, await collectEpubTextSnapshot(args.temp));
89
+ reportInfo("Document text is unchanged after optimization.");
90
+ });
91
+ // Step 3: Optional author workflow structure updates. These are tailored to
92
+ // this project's Pages/manual-summary publishing flow.
93
+ if (args.authorWorkflow) {
94
+ reportInfo("\n=== Author Workflow Structure Updates ===");
95
+ await runReportedStep(report, "Author workflow", args.strict, async () => {
96
+ const authorConfig = await loadAuthorWorkflowConfig(args.authorConfig);
97
+ await runStructureUpdates({
98
+ tempDir: args.temp,
99
+ lang: args.lang,
100
+ strict: args.strict,
101
+ authorConfig,
102
+ });
103
+ });
104
+ }
105
+ else {
106
+ recordSkippedStep(report, "Author workflow", "Enable with --author-workflow or --preset author.");
107
+ }
108
+ reportInfo("\n=== Validate Content Integrity ===");
109
+ await runReportedStep(report, "Validate content integrity", args.strict, async () => {
110
+ const before = report.content?.before;
111
+ if (!before) {
112
+ throw new Error("Input content metrics were not collected after extraction.");
113
+ }
114
+ const after = await collectEpubContentMetrics(args.temp);
115
+ const integrity = compareEpubContentMetrics(before, after);
116
+ report.content = { before, after, integrity };
117
+ assertEpubContentIntegrity(integrity);
118
+ reportInfo("Content counts and internal references passed before/after validation.");
119
+ });
120
+ if (resourcesBefore)
121
+ report.resources = compareResources(resourcesBefore, await snapshotResources(args.temp));
122
+ // Step 4: Build and validate a candidate. The requested output is not
123
+ // touched until EPUBCheck has accepted the candidate.
124
+ reportInfo("\n=== Create Candidate EPUB ===");
125
+ await runReportedStep(report, "Create candidate EPUB", args.strict, () => createEPUBFile({ tempDir: args.temp, output: candidateOutput }));
126
+ reportInfo("\n=== Validate Candidate EPUB ===");
127
+ await runReportedStep(report, "Validate candidate EPUB", args.strict, () => validateEPUB({
128
+ output: candidateOutput,
129
+ strict: args.strict,
130
+ timeoutMs: args.validationTimeout,
131
+ onReport: (validation) => {
132
+ report.validation = validation;
133
+ },
134
+ }));
135
+ reportInfo("\n=== Publish Validated EPUB ===");
136
+ await runReportedStep(report, "Publish validated EPUB", args.strict, () => commitCandidateOutput(candidateOutput, args.output));
137
+ candidateOutput = undefined;
138
+ // Step 5: Cleanup only after the validated output is safely published.
139
+ if (args.clean) {
140
+ reportInfo("\n=== Cleanup ===");
141
+ const removedTempDir = await runReportedStep(report, "Cleanup", args.strict, () => removeTempDir(args.temp, {
142
+ inputPath: args.input,
143
+ outputPath: args.output,
144
+ }));
145
+ reportInfo(`Removed temporary directory: ${removedTempDir}`);
146
+ }
147
+ else {
148
+ recordSkippedStep(report, "Cleanup", "Temporary files kept for inspection.");
149
+ }
150
+ if (await fs.pathExists(args.output)) {
151
+ await reportFileSizeComparison(args.input, args.output);
152
+ const [inputStats, outputStats] = await Promise.all([
153
+ fs.stat(args.input),
154
+ fs.stat(args.output),
155
+ ]);
156
+ const savedBytes = inputStats.size - outputStats.size;
157
+ report.sizes = {
158
+ inputBytes: inputStats.size,
159
+ outputBytes: outputStats.size,
160
+ savedBytes,
161
+ reductionPercent: (savedBytes / inputStats.size) * 100,
162
+ };
163
+ }
164
+ completePipelineReport(report);
165
+ if (args.clean) {
166
+ reportInfo("All done!\n");
167
+ }
168
+ else {
169
+ reportInfo(`\nBuild completed successfully!\nNote: Temporary files have been kept in '${args.temp}'. Use --clean to remove them.\n`);
170
+ }
171
+ }
172
+ catch (error) {
173
+ await discardCandidateOutput(candidateOutput);
174
+ completePipelineReport(report, error);
175
+ reportError(error instanceof Error ? error.message : error);
176
+ reportError(`Temporary files were kept in '${args.temp}' for inspection.`);
177
+ throw error;
178
+ }
179
+ finally {
180
+ report.tempDir = args.temp;
181
+ if (args.reportJson) {
182
+ try {
183
+ await writePipelineReport(report, args.reportJson);
184
+ }
185
+ catch (error) {
186
+ reportError(`Failed to write JSON report: ${error instanceof Error ? error.message : String(error)}`);
187
+ reportWriteError = error;
188
+ }
189
+ }
190
+ if (args.reportHtml) {
191
+ try {
192
+ await writeHtmlReport(report, args.reportHtml);
193
+ }
194
+ catch (error) {
195
+ reportError(`Failed to write HTML report: ${error instanceof Error ? error.message : String(error)}`);
196
+ reportWriteError ??= error;
197
+ }
198
+ }
199
+ processingOptions.onReport?.(report);
200
+ if (args.profile) {
201
+ printProfile(report);
202
+ }
203
+ }
204
+ if (reportWriteError !== undefined) {
205
+ throw reportWriteError;
206
+ }
207
+ }
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export declare function main(): Promise<void>;
@@ -0,0 +1,48 @@
1
+ #!/usr/bin/env node
2
+ import { reportError } from "./utils/diagnostics.js";
3
+ import { planStorage, saveStoragePlan, applyStoragePlan } from "./storage.js";
4
+ import { runWatch } from "./watch.js";
5
+ import { runBatch } from "./batch.js";
6
+ import { parseArguments } from "./cli.js";
7
+ import { runOptimization } from "./optimization.js";
8
+ import { isEntryPoint } from "./scripts/utils.js";
9
+ export async function main() {
10
+ const args = await parseArguments();
11
+ if (args.applyStoragePlan) {
12
+ process.stdout.write(JSON.stringify(await applyStoragePlan(args.applyStoragePlan), null, 2) + "\n");
13
+ }
14
+ else if (args.storage) {
15
+ const plan = await planStorage(args.storage, args.keepRevisions);
16
+ if (args.storagePlan)
17
+ await saveStoragePlan(plan, args.storagePlan);
18
+ process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
19
+ }
20
+ else if (args.watch) {
21
+ const controller = new AbortController();
22
+ const stop = () => controller.abort();
23
+ process.on("SIGINT", stop);
24
+ process.on("SIGTERM", stop);
25
+ try {
26
+ const report = await runWatch(args, { signal: controller.signal });
27
+ if (report.failed)
28
+ process.exitCode = 1;
29
+ }
30
+ finally {
31
+ process.off("SIGINT", stop);
32
+ process.off("SIGTERM", stop);
33
+ }
34
+ }
35
+ else if (args.batch) {
36
+ const report = await runBatch(args);
37
+ if (!report.success)
38
+ process.exitCode = 1;
39
+ }
40
+ else
41
+ await runOptimization(args);
42
+ }
43
+ if (isEntryPoint(import.meta.url)) {
44
+ main().catch((err) => {
45
+ reportError(err instanceof Error ? err.message : err);
46
+ process.exit(1);
47
+ });
48
+ }
@@ -0,0 +1,26 @@
1
+ export interface ArchiveLimits {
2
+ maxEntries: number;
3
+ maxEntryBytes: number;
4
+ maxTotalBytes: number;
5
+ maxCompressionRatio: number;
6
+ }
7
+ /**
8
+ * Extract EPUB file contents to a temporary directory.
9
+ * Validates each entry against zip-slip: any entry whose resolved target
10
+ * escapes `extractDir` aborts the extraction.
11
+ * @throws Error if extraction fails or an entry tries to escape extractDir
12
+ */
13
+ declare function extractEPUB(epubPath: string, extractDir: string, limits?: ArchiveLimits): Promise<void>;
14
+ /**
15
+ * Recompress directory contents into an EPUB file (Apple Books compatible)
16
+ * EPUB requires specific compression:
17
+ * 1. mimetype file must be first, uncompressed, with no extra fields
18
+ * 2. All other files should be compressed normally
19
+ *
20
+ * @param outputPath Path for output EPUB file
21
+ * @param sourceDir Directory containing EPUB contents
22
+ * @returns True if compression succeeded
23
+ * @throws Error if compression fails
24
+ */
25
+ declare function compressEPUB(outputPath: string, sourceDir: string): Promise<boolean>;
26
+ export { extractEPUB, compressEPUB };
@@ -0,0 +1,170 @@
1
+ import fs from "fs-extra";
2
+ import path from "node:path";
3
+ import unzipper from "unzipper";
4
+ import yazl from "yazl";
5
+ import { Transform } from "node:stream";
6
+ import { pipeline } from "node:stream/promises";
7
+ import config from "../utils/config.js";
8
+ import { createManagedTempDir, TEMP_DIR_MARKER } from "../utils/temp-dir.js";
9
+ function isZipSymlink(externalFileAttributes) {
10
+ const unixMode = externalFileAttributes >>> 16;
11
+ return (unixMode & 0o170000) === 0o120000;
12
+ }
13
+ function validateArchiveMetadata(files, limits) {
14
+ if (files.length > limits.maxEntries) {
15
+ throw new Error(`Archive contains ${files.length} entries; limit is ${limits.maxEntries}.`);
16
+ }
17
+ let declaredTotal = 0;
18
+ for (const entry of files) {
19
+ if (isZipSymlink(entry.externalFileAttributes)) {
20
+ throw new Error(`Archive entry ${entry.path} is a symbolic link.`);
21
+ }
22
+ if (entry.type === "Directory")
23
+ continue;
24
+ if (entry.uncompressedSize > limits.maxEntryBytes) {
25
+ throw new Error(`Archive entry ${entry.path} is ${entry.uncompressedSize} bytes; per-file limit is ${limits.maxEntryBytes}.`);
26
+ }
27
+ declaredTotal += entry.uncompressedSize;
28
+ if (declaredTotal > limits.maxTotalBytes) {
29
+ throw new Error(`Archive expands beyond the ${limits.maxTotalBytes} byte total limit.`);
30
+ }
31
+ const ratio = entry.compressedSize === 0
32
+ ? entry.uncompressedSize === 0
33
+ ? 1
34
+ : Number.POSITIVE_INFINITY
35
+ : entry.uncompressedSize / entry.compressedSize;
36
+ if (ratio > limits.maxCompressionRatio) {
37
+ throw new Error(`Archive entry ${entry.path} has suspicious compression ratio ${ratio.toFixed(0)}:1.`);
38
+ }
39
+ }
40
+ }
41
+ /**
42
+ * Extract EPUB file contents to a temporary directory.
43
+ * Validates each entry against zip-slip: any entry whose resolved target
44
+ * escapes `extractDir` aborts the extraction.
45
+ * @throws Error if extraction fails or an entry tries to escape extractDir
46
+ */
47
+ async function extractEPUB(epubPath, extractDir, limits = config.archiveLimits) {
48
+ try {
49
+ const absExtract = path.resolve(extractDir);
50
+ const directory = await unzipper.Open.file(epubPath);
51
+ validateArchiveMetadata(directory.files, limits);
52
+ await createManagedTempDir(extractDir, epubPath);
53
+ let extractedTotal = 0;
54
+ for (const entry of directory.files) {
55
+ const normalizedEntryPath = entry.path.replace(/\\/g, "/");
56
+ if (!normalizedEntryPath ||
57
+ normalizedEntryPath.startsWith("/") ||
58
+ normalizedEntryPath.includes("\0") ||
59
+ /^[a-z]:/i.test(normalizedEntryPath)) {
60
+ throw new Error(`Refusing unsafe archive entry: ${entry.path}`);
61
+ }
62
+ const target = path.resolve(absExtract, normalizedEntryPath);
63
+ if (target === path.join(absExtract, TEMP_DIR_MARKER)) {
64
+ throw new Error(`Refusing reserved archive entry: ${entry.path}`);
65
+ }
66
+ const rel = path.relative(absExtract, target);
67
+ if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
68
+ throw new Error(`Refusing entry outside extract dir: ${entry.path}`);
69
+ }
70
+ if (entry.type === "Directory") {
71
+ await fs.ensureDir(target);
72
+ continue;
73
+ }
74
+ await fs.ensureDir(path.dirname(target));
75
+ let entryBytes = 0;
76
+ const limiter = new Transform({
77
+ transform(chunk, _encoding, callback) {
78
+ entryBytes += chunk.length;
79
+ extractedTotal += chunk.length;
80
+ if (entryBytes > limits.maxEntryBytes) {
81
+ callback(new Error(`Archive entry ${entry.path} exceeded the per-file size limit.`));
82
+ return;
83
+ }
84
+ if (extractedTotal > limits.maxTotalBytes) {
85
+ callback(new Error("Archive exceeded the total extracted size limit."));
86
+ return;
87
+ }
88
+ callback(null, chunk);
89
+ },
90
+ });
91
+ await pipeline(entry.stream(), limiter, fs.createWriteStream(target, { flags: "wx" }));
92
+ }
93
+ }
94
+ catch (error) {
95
+ throw new Error(`Failed to extract EPUB: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
96
+ }
97
+ }
98
+ /**
99
+ * Helper function to recursively add directory contents to zip file
100
+ * @param zipFile The yazl ZipFile instance
101
+ * @param dirPath Full path to directory to add
102
+ * @param zipPath Relative path within zip file
103
+ * @param exclude Array of file/directory names to exclude
104
+ */
105
+ async function addDirectoryRecursive(zipFile, dirPath, zipPath, exclude = []) {
106
+ const items = await fs.readdir(dirPath);
107
+ for (const item of items) {
108
+ if (exclude.includes(item))
109
+ continue;
110
+ const fullPath = path.join(dirPath, item);
111
+ const zipItemPath = zipPath ? `${zipPath}/${item}` : item;
112
+ const stats = await fs.stat(fullPath);
113
+ if (stats.isDirectory()) {
114
+ await addDirectoryRecursive(zipFile, fullPath, zipItemPath, exclude);
115
+ }
116
+ else {
117
+ // Add file with compression (equivalent to zip -r9)
118
+ zipFile.addFile(fullPath, zipItemPath, {
119
+ compress: true,
120
+ compressionLevel: 9,
121
+ });
122
+ }
123
+ }
124
+ }
125
+ /**
126
+ * Recompress directory contents into an EPUB file (Apple Books compatible)
127
+ * EPUB requires specific compression:
128
+ * 1. mimetype file must be first, uncompressed, with no extra fields
129
+ * 2. All other files should be compressed normally
130
+ *
131
+ * @param outputPath Path for output EPUB file
132
+ * @param sourceDir Directory containing EPUB contents
133
+ * @returns True if compression succeeded
134
+ * @throws Error if compression fails
135
+ */
136
+ async function compressEPUB(outputPath, sourceDir) {
137
+ try {
138
+ const absOutput = path.resolve(outputPath);
139
+ const absSource = path.resolve(sourceDir);
140
+ // Ensure mimetype exists and is correct
141
+ const mimetypePath = path.join(absSource, "mimetype");
142
+ await fs.writeFile(mimetypePath, "application/epub+zip");
143
+ // Remove output if exists
144
+ if (await fs.pathExists(absOutput))
145
+ await fs.unlink(absOutput);
146
+ return new Promise((resolve, reject) => {
147
+ const zipFile = new yazl.ZipFile();
148
+ // Step 1: Add mimetype first, uncompressed, no extra fields
149
+ zipFile.addFile(mimetypePath, "mimetype", {
150
+ compress: false, // No compression (store only)
151
+ forceZip64Format: false,
152
+ });
153
+ // Step 2: Add everything else, compressed, excluding mimetype
154
+ addDirectoryRecursive(zipFile, absSource, "", ["mimetype", TEMP_DIR_MARKER])
155
+ .then(() => {
156
+ // Write the zip file to disk
157
+ zipFile.outputStream
158
+ .pipe(fs.createWriteStream(absOutput))
159
+ .on("close", () => resolve(true))
160
+ .on("error", reject);
161
+ zipFile.end();
162
+ })
163
+ .catch(reject);
164
+ });
165
+ }
166
+ catch (error) {
167
+ throw new Error(`Failed to compress EPUB: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
168
+ }
169
+ }
170
+ export { extractEPUB, compressEPUB };
@@ -0,0 +1,17 @@
1
+ import type { Args } from "../types.js";
2
+ export interface ContentProcessingOptions {
3
+ runStep?: <T>(name: string, operation: () => Promise<T> | T) => Promise<T>;
4
+ skipStep?: (name: string, reason: string) => void;
5
+ afterExtract?: (tempDir: string) => Promise<void> | void;
6
+ }
7
+ /**
8
+ * Extract the EPUB and run its content processors without publishing an output.
9
+ * The shared optimization pipeline validates and publishes the resulting candidate.
10
+ * @param args Resolved optimization options.
11
+ * @returns Metadata about the run.
12
+ */
13
+ export declare function processEpubContent(args: Args, options?: ContentProcessingOptions): Promise<{
14
+ success: boolean;
15
+ input: string;
16
+ output: string;
17
+ }>;
@@ -0,0 +1,133 @@
1
+ import { reportError, reportInfo, reportWarning } from "../utils/diagnostics.js";
2
+ import fs from "fs-extra";
3
+ import { extractEPUB } from "./archive-processor.js";
4
+ import { processHTML } from "./html-processor.js";
5
+ import { optimizeImages } from "./image-processor.js";
6
+ import { subsetFonts } from "./font-processor.js";
7
+ import { convertPngToJpeg } from "./image-converter.js";
8
+ import { minifyJavaScript } from "./js-processor.js";
9
+ import { optimizeSVGs } from "./svg-optimizer.js";
10
+ import { addLazyLoadingToImages } from "./lazy-img.js";
11
+ import { assertSafeTempDir } from "../utils/temp-dir.js";
12
+ import path from "node:path";
13
+ import { assertDistinctInputOutput, assertSafeOutputTarget } from "../utils/output-transaction.js";
14
+ import { detectEpubFeatures } from "../utils/epub-features.js";
15
+ import { assertNoInternalDtdSubsets } from "../utils/xml-dtd.js";
16
+ import { resolvePngBackground } from "../utils/pipeline-options.js";
17
+ /**
18
+ * Extract the EPUB and run its content processors without publishing an output.
19
+ * The shared optimization pipeline validates and publishes the resulting candidate.
20
+ * @param args Resolved optimization options.
21
+ * @returns Metadata about the run.
22
+ */
23
+ export async function processEpubContent(args, options = {}) {
24
+ const resolvedArgs = args;
25
+ const pngBackground = resolvePngBackground(resolvedArgs);
26
+ const runStep = options.runStep ?? (async (_name, operation) => operation());
27
+ const skipStep = options.skipStep ?? (() => { });
28
+ try {
29
+ // Validate inputs
30
+ if (!(await fs.pathExists(resolvedArgs.input))) {
31
+ throw new Error(`Input file not found: ${resolvedArgs.input}`);
32
+ }
33
+ if (!(await fs.stat(resolvedArgs.input)).isFile()) {
34
+ throw new Error(`Input path must point to a regular file: ${resolvedArgs.input}`);
35
+ }
36
+ assertDistinctInputOutput(resolvedArgs.input, resolvedArgs.output);
37
+ await assertSafeOutputTarget(resolvedArgs.output);
38
+ resolvedArgs.temp = assertSafeTempDir(resolvedArgs.temp, {
39
+ inputPath: resolvedArgs.input,
40
+ outputPath: resolvedArgs.output,
41
+ });
42
+ // Create parent directory for output if it doesn't exist
43
+ const outputDir = path.dirname(path.resolve(resolvedArgs.output));
44
+ if (outputDir !== path.parse(outputDir).root) {
45
+ await fs.ensureDir(outputDir);
46
+ }
47
+ // 1. Extract EPUB file
48
+ await runStep("Extract EPUB", () => extractEPUB(resolvedArgs.input, resolvedArgs.temp));
49
+ reportInfo(`📦 Extracted ${resolvedArgs.input} to ${resolvedArgs.temp}`);
50
+ // 1b. Detect special EPUB shapes early so we degrade gracefully instead of
51
+ // silently corrupting them: refuse DRM-encrypted books, leave obfuscated
52
+ // fonts untouched, and keep fixed-layout page images at their native size.
53
+ await runStep("Analyze EPUB structure", async () => {
54
+ await assertNoInternalDtdSubsets(resolvedArgs.temp);
55
+ const features = await detectEpubFeatures(resolvedArgs.temp);
56
+ if (features.encryptionKind === "drm") {
57
+ throw new Error("EPUB contains encrypted/DRM-protected resources (META-INF/encryption.xml). " +
58
+ "Optimizing would corrupt the protected content, so the operation was refused.");
59
+ }
60
+ if (features.encryptionKind === "obfuscation") {
61
+ reportWarning("⚠️ Obfuscated embedded fonts detected (META-INF/encryption.xml); optimizing " +
62
+ "everything else and leaving the fonts untouched.");
63
+ resolvedArgs.fonts = false;
64
+ }
65
+ if (features.fixedLayout && resolvedArgs.maxImageDim > 0) {
66
+ reportWarning("⚠️ Fixed-layout (pre-paginated) EPUB detected; disabling image downscaling " +
67
+ "to keep page images aligned with the declared viewport.");
68
+ resolvedArgs.maxImageDim = 0;
69
+ }
70
+ });
71
+ if (options.afterExtract) {
72
+ await runStep("Analyze input content", () => options.afterExtract?.(resolvedArgs.temp));
73
+ }
74
+ // 2. Process HTML and CSS files
75
+ await runStep("Optimize HTML/CSS", () => processHTML(resolvedArgs.temp));
76
+ reportInfo("🔄 Optimized HTML/CSS files");
77
+ // 3. Minify JavaScript
78
+ await runStep("Minify JavaScript", () => minifyJavaScript(resolvedArgs.temp));
79
+ reportInfo("🔄 Minified JavaScript files");
80
+ // 4. Convert eligible PNGs to JPEG; alpha needs an explicit background.
81
+ // Resize is chained into the same
82
+ // sharp pass so converted JPEGs don't need a follow-up downscale — step
83
+ // 5 skips them to avoid a double recompression.
84
+ const maxImageDim = resolvedArgs.maxImageDim > 0 ? resolvedArgs.maxImageDim : undefined;
85
+ let convertedJpegs = new Set();
86
+ if (resolvedArgs.convertPng && !resolvedArgs.lossless) {
87
+ convertedJpegs = await runStep("Convert PNG to JPEG", () => convertPngToJpeg(resolvedArgs.temp, resolvedArgs.jpgQuality, resolvedArgs.imageConcurrency, maxImageDim, pngBackground));
88
+ reportInfo("🖼️ Converted PNG to JPEG");
89
+ }
90
+ else {
91
+ skipStep("Convert PNG to JPEG", resolvedArgs.lossless ? "Disabled by lossless preset." : "Disabled by CLI option.");
92
+ }
93
+ // 5. Single-pass image optimization: resize + re-encode in one sharp
94
+ // pipeline (replaces the old downscale + optimize split).
95
+ if (!resolvedArgs.lossless) {
96
+ await runStep("Optimize images", () => optimizeImages(resolvedArgs.temp, {
97
+ jpegQuality: resolvedArgs.jpgQuality,
98
+ pngQuality: resolvedArgs.pngQuality,
99
+ maxDim: maxImageDim,
100
+ skip: convertedJpegs,
101
+ concurrency: resolvedArgs.imageConcurrency,
102
+ }));
103
+ reportInfo("🖼️ Optimized image files");
104
+ }
105
+ else {
106
+ skipStep("Optimize images", "Disabled by lossless preset.");
107
+ }
108
+ // 6. Optimize SVGs
109
+ await runStep("Optimize SVG", () => optimizeSVGs(resolvedArgs.temp));
110
+ reportInfo("🖼️ Optimized SVG files");
111
+ // 7. Add lazy loading to images
112
+ if (resolvedArgs.lazyLoading) {
113
+ await runStep("Add lazy loading", () => addLazyLoadingToImages(resolvedArgs.temp));
114
+ reportInfo("🖼️ Added lazy loading to images");
115
+ }
116
+ else {
117
+ skipStep("Add lazy loading", "Disabled by preset/CLI option.");
118
+ }
119
+ // 8. Optional font subsetting in resource-monitored child processes.
120
+ await runStep("Process fonts", () => subsetFonts(resolvedArgs.temp, { enabled: resolvedArgs.fonts }));
121
+ reportInfo("🔤 Font processing complete");
122
+ return { success: true, input: resolvedArgs.input, output: resolvedArgs.output };
123
+ }
124
+ catch (error) {
125
+ if (error instanceof Error) {
126
+ reportError(`❌ Error: ${error.message}`);
127
+ }
128
+ else {
129
+ reportError("❌ Unknown error", error);
130
+ }
131
+ throw error;
132
+ }
133
+ }
@@ -0,0 +1,2 @@
1
+ /** Deliberately over-collects literal text; refuses content whose glyphs are not statically known. */
2
+ export declare function collectFontCharacters(root: string): Promise<string>;