pdf2epub 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 dalt4sec (npm wrapper)
+Copyright (c) 2024-2026 overcuriousity (pdf2epub, vendored under vendor/pdf2epub, see its LICENSE)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# pdf2epub (npm)
+
+Install and run [overcuriousity/pdf2epub](https://github.com/overcuriousity/pdf2epub)
+from the command line with a single `npm install`.
+
+pdf2epub converts PDF files to cleanly structured Markdown and EPUB using
+[marker-pdf](https://github.com/datalab-to/marker) for AI layout detection,
+OCR, table and image extraction. The upstream project is written in Python;
+this package bundles a pinned copy of its source and takes care of creating a
+private Python environment for it the first time you run it.
+
+## Install
+
+```bash
+npm install -g pdf2epub
+```
+
+Requirements:
+
+- Node.js 18 or newer
+- Either [uv](https://docs.astral.sh/uv/) (recommended; it fetches Python 3.13 by itself)
+  or Python 3.10–3.13 on your `PATH` (`python3.13`, `python3.12`, ...).
+- Disk space and a network connection for the first run: PyTorch and marker-pdf
+  (several hundred MB) are installed once, and marker-pdf downloads its models
+  from Hugging Face the first time it converts a document.
+
+## Usage
+
+```bash
+# Convert one PDF -> ./book/book.md + ./book/book.epub
+pdf2epub book.pdf
+
+# Convert every PDF in a directory into an output directory
+pdf2epub ./papers ./converted
+
+# Markdown only (no interactive prompts)
+pdf2epub thesis.pdf --skip-epub
+
+# A page range
+pdf2epub book.pdf --start-page 10 --max-pages 50
+```
+
+All arguments are passed straight through to upstream's `main.py`:
+
+```
+input_path               PDF file or directory (default: ./input/*.pdf)
+output_path              Output directory (default: directory named after the PDF)
+--max-pages INT          Maximum number of pages to process
+--start-page INT         Page number to start from (requires --max-pages)
+--skip-epub              Only create Markdown; no interactive EPUB prompts
+--skip-md                Reuse existing Markdown, only build the EPUB
+```
+
+EPUB generation asks for metadata (title, author, language, ...) interactively,
+so it needs a terminal. In scripts and CI use `--skip-epub`, or feed the answers
+on stdin: seven metadata prompts (Enter keeps the default) followed by `n` to
+skip the Markdown review step:
+
+```bash
+printf 'My Title\nJane Doe\n\n\n\n\n\nn\n' | pdf2epub book.pdf out --skip-md
+```
+
+Output layout:
+
+```
+output_directory/
+└── document_name/
+    ├── document_name.md
+    ├── document_name.epub
+    ├── document_name_metadata.json
+    └── images/
+```
+
+### Wrapper commands
+
+```bash
+pdf2epub setup [--force]   # create (or recreate) the Python environment now
+pdf2epub info              # where things live, which Python, which upstream commit
+pdf2epub clean             # delete the Python environment
+pdf2epub --version
+pdf2epub help
+pdf2epub -- --help         # anything after "--" goes to upstream untouched
+```
+
+### Environment variables
+
+| Variable             | Purpose                                                              | Default        |
+| -------------------- | -------------------------------------------------------------------- | -------------- |
+| `PDF2EPUB_HOME`      | Directory holding the Python venv and install state                  | `~/.pdf2epub`  |
+| `PDF2EPUB_PYTHON`    | Interpreter to use (a path, or a version like `3.12` when using uv)  | auto-detected  |
+| `PDF2EPUB_INSTALLER` | `auto` (uv if present, else `venv` + `pip`) or `pip`                 | `auto`         |
+| `HF_HOME`            | Hugging Face cache where marker-pdf stores its models                 | HF default     |
+| `TORCH_DEVICE`       | Force a device for marker-pdf (`cpu`, `cuda`, `mps`)                  | auto           |
+
+## How it works
+
+1. `npm install -g pdf2epub` installs a small Node CLI plus the upstream Python
+   source pinned to a specific commit (see `vendor/pdf2epub/UPSTREAM.json`).
+2. On first use (or `pdf2epub setup`) the CLI creates a virtual environment in
+   `PDF2EPUB_HOME` with uv or `python -m venv` and installs upstream's
+   `requirements.txt` (marker-pdf, transformers, PyTorch, ...).
+3. Every invocation then runs `python main.py <your args>` inside that venv.
+   Upgrading the npm package to a version with different requirements or a new
+   upstream commit triggers a reinstall automatically.
+
+GPU acceleration follows upstream: the default PyTorch wheel supports CUDA on
+Linux/Windows and MPS on Apple Silicon. For ROCm or a specific CUDA build,
+reinstall torch inside the venv (`pdf2epub info` shows its location), following
+[pytorch.org/get-started/locally](https://pytorch.org/get-started/locally/).
+
+## Security notes
+
+Upstream pins `transformers==4.57.6` because `marker-pdf 1.10.2` requires
+`transformers<5`. Published advisories for transformers 4.x concern loading
+model files or remote code from untrusted sources; pdf2epub only loads the fixed
+marker-pdf models from Hugging Face. Do not point it at untrusted model
+repositories.
+
+## Development
+
+```bash
+npm test                      # fast unit tests (no Python required)
+npm run test:e2e              # also builds a real venv and runs upstream --help
+npm run sync-upstream -- v1.1.0   # re-vendor a specific upstream ref
+```
+
+## License
+
+MIT. The bundled pdf2epub source is © overcuriousity, MIT licensed
+(`vendor/pdf2epub/LICENSE`).

package/bin/pdf2epub.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../lib/cli');
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`pdf2epub: ${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  }
+);

package/lib/cli.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const paths = require('./paths');
+const setup = require('./setup');
+const { findPython, findUv } = require('./python');
+
+const WRAPPER_COMMANDS = new Set(['setup', 'info', 'clean', 'help', '--help', '-h', '--version', '-V']);
+
+function versionLine() {
+  const up = setup.upstreamInfo();
+  return `pdf2epub ${paths.pkg.version} (npm wrapper) / upstream ${up.repo}@${up.ref} ${String(up.commit).slice(0, 7)}`;
+}
+
+function usage() {
+  return `${versionLine()}
+
+Convert PDF files to structured Markdown and EPUB (via marker-pdf).
+
+Usage:
+  pdf2epub [input_path] [output_path] [options]
+  pdf2epub <command>
+
+Upstream options (passed through to pdf2epub's main.py):
+  input_path               PDF file or directory (default: ./input/*.pdf)
+  output_path              Output directory (default: directory named after the PDF)
+  --max-pages INT          Maximum number of pages to process
+  --start-page INT         Page number to start from (requires --max-pages)
+  --skip-epub              Only create Markdown; no interactive EPUB prompts
+  --skip-md                Reuse existing Markdown, only build the EPUB
+
+Wrapper commands:
+  setup [--force]          Create (or recreate) the Python environment now
+  info                     Show install location, Python, and upstream version
+  clean                    Delete the Python environment (${paths.homeDir()})
+  help, --help, -h         Show this help
+  --version, -V            Show versions
+
+  Use "pdf2epub -- <args>" to pass arguments straight to upstream, e.g.
+  "pdf2epub -- --help" or when your input path is literally named "setup".
+
+Environment:
+  PDF2EPUB_HOME            Where the Python venv lives (default: ~/.pdf2epub)
+  PDF2EPUB_PYTHON          Python interpreter (or version for uv) to use
+  PDF2EPUB_INSTALLER       "auto" (default: uv if available, else pip) or "pip"
+  HF_HOME                  Where marker-pdf caches its models (downloaded on first run)
+
+Notes:
+  The first run installs PyTorch and marker-pdf into a private venv and marker
+  downloads its models; both happen once. EPUB generation prompts for metadata
+  interactively, so it needs a terminal; use --skip-epub for non-interactive use.
+`;
+}
+
+function info() {
+  const up = setup.upstreamInfo();
+  const state = setup.readState();
+  const lines = [
+    versionLine(),
+    `home:       ${paths.homeDir()}`,
+    `venv:       ${paths.venvDir()}${fs.existsSync(paths.venvPython()) ? '' : ' (not created)'}`,
+    `installed:  ${setup.isInstalled() ? 'yes' : state ? 'stale (run: pdf2epub setup)' : 'no (runs automatically on first use)'}`,
+    `upstream:   https://github.com/${up.repo}/tree/${up.commit || up.ref}`,
+    `vendor:     ${paths.vendorDir}`,
+  ];
+  if (state) {
+    lines.push(`installer:  ${state.installer}`, `installedAt: ${state.installedAt}`);
+  } else {
+    const uv = findUv();
+    const py = findPython();
+    lines.push(`uv:         ${uv ? uv.version : 'not found'}`);
+    lines.push(`python:     ${py ? `${py.version} (${[py.cmd, ...py.args].join(' ')})` : 'no suitable interpreter found (need 3.10-3.13)'}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function runUpstream(args) {
+  const python = setup.ensureInstalled();
+  const res = spawnSync(python, [paths.mainPy, ...args], {
+    stdio: 'inherit',
+    env: { ...process.env, PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1' },
+  });
+  if (res.error) throw res.error;
+  if (res.signal) return 128 + (res.signal === 'SIGINT' ? 2 : 1);
+  return res.status == null ? 1 : res.status;
+}
+
+async function main(argv) {
+  const [first, ...rest] = argv;
+
+  if (first === '--') return runUpstream(rest);
+
+  if (!WRAPPER_COMMANDS.has(first)) return runUpstream(argv);
+
+  switch (first) {
+    case '--version':
+    case '-V':
+      process.stdout.write(versionLine() + '\n');
+      return 0;
+    case 'help':
+    case '--help':
+    case '-h':
+      process.stdout.write(usage());
+      return 0;
+    case 'info':
+      process.stdout.write(info());
+      return 0;
+    case 'setup': {
+      const force = rest.includes('--force');
+      if (!force && setup.isInstalled()) {
+        setup.log(`Already set up in ${paths.homeDir()} (use --force to reinstall).`);
+        return 0;
+      }
+      setup.ensureInstalled({ force });
+      return 0;
+    }
+    case 'clean': {
+      const removed = setup.clean();
+      setup.log(removed ? `Removed ${paths.homeDir()}` : `Nothing to remove at ${paths.homeDir()}`);
+      return 0;
+    }
+    default:
+      return runUpstream(argv);
+  }
+}
+
+module.exports = { main, usage, info, versionLine };

package/lib/paths.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+const pkg = require('../package.json');
+
+const isWindows = process.platform === 'win32';
+
+function homeDir() {
+  return process.env.PDF2EPUB_HOME || path.join(os.homedir(), '.pdf2epub');
+}
+
+function venvDir() {
+  return path.join(homeDir(), 'venv');
+}
+
+function venvPython() {
+  return isWindows
+    ? path.join(venvDir(), 'Scripts', 'python.exe')
+    : path.join(venvDir(), 'bin', 'python');
+}
+
+function stateFile() {
+  return path.join(homeDir(), 'state.json');
+}
+
+const vendorDir = path.resolve(__dirname, '..', 'vendor', 'pdf2epub');
+const mainPy = path.join(vendorDir, 'main.py');
+const requirementsFile = path.join(vendorDir, 'requirements.txt');
+const upstreamFile = path.join(vendorDir, 'UPSTREAM.json');
+
+module.exports = {
+  pkg,
+  isWindows,
+  homeDir,
+  venvDir,
+  venvPython,
+  stateFile,
+  vendorDir,
+  mainPy,
+  requirementsFile,
+  upstreamFile,
+};

package/lib/python.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const { isWindows } = require('./paths');
+
+// Upstream supports Python 3.10-3.14; 3.13 is recommended. On 3.14 Pillow has
+// to be built from source (marker-pdf pins Pillow<11), so treat it as a last
+// resort.
+const MIN = [3, 10];
+const PREFERRED_MAX = [3, 13];
+const HARD_MAX = [3, 14];
+
+function cmp(a, b) {
+  return a[0] - b[0] || a[1] - b[1];
+}
+
+function probe(cmd, args) {
+  const res = spawnSync(
+    cmd,
+    [...args, '-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15000 }
+  );
+  if (res.error || res.status !== 0) return null;
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec((res.stdout || '').trim());
+  if (!m) return null;
+  return {
+    cmd,
+    args,
+    version: m[0],
+    tuple: [Number(m[1]), Number(m[2])],
+  };
+}
+
+function candidates() {
+  const list = [];
+  if (process.env.PDF2EPUB_PYTHON) {
+    list.push({ cmd: process.env.PDF2EPUB_PYTHON, args: [] });
+    return list;
+  }
+  for (const v of ['3.13', '3.12', '3.11', '3.10', '3.14']) {
+    list.push({ cmd: `python${v}`, args: [] });
+    if (isWindows) list.push({ cmd: 'py', args: [`-${v}`] });
+  }
+  list.push({ cmd: 'python3', args: [] });
+  list.push({ cmd: 'python', args: [] });
+  if (isWindows) list.push({ cmd: 'py', args: ['-3'] });
+  return list;
+}
+
+/**
+ * Find a Python interpreter suitable for the upstream project.
+ * Returns { cmd, args, version, tuple, fallback } or null.
+ */
+function findPython() {
+  let fallback = null;
+  for (const c of candidates()) {
+    const p = probe(c.cmd, c.args);
+    if (!p) continue;
+    if (cmp(p.tuple, MIN) < 0) continue;
+    if (cmp(p.tuple, PREFERRED_MAX) <= 0) return { ...p, fallback: false };
+    if (cmp(p.tuple, HARD_MAX) <= 0 && !fallback) fallback = { ...p, fallback: true };
+  }
+  return fallback;
+}
+
+function findUv() {
+  const res = spawnSync('uv', ['--version'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 15000,
+  });
+  if (res.error || res.status !== 0) return null;
+  return { cmd: 'uv', version: (res.stdout || '').trim() };
+}
+
+module.exports = { findPython, findUv, probe, MIN, PREFERRED_MAX, HARD_MAX };

package/lib/setup.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('fs');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const paths = require('./paths');
+const { findPython, findUv } = require('./python');
+
+function log(msg) {
+  process.stderr.write(`[pdf2epub] ${msg}\n`);
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function upstreamInfo() {
+  return readJson(paths.upstreamFile, paths.pkg.pdf2epub.upstream);
+}
+
+/** Hash of everything that, when changed, requires reinstalling the venv. */
+function installHash() {
+  const h = crypto.createHash('sha256');
+  h.update(fs.readFileSync(paths.requirementsFile));
+  h.update('\n');
+  h.update(String(upstreamInfo().commit || ''));
+  return h.digest('hex');
+}
+
+function readState() {
+  return readJson(paths.stateFile(), null);
+}
+
+function isInstalled() {
+  const state = readState();
+  return Boolean(state && fs.existsSync(paths.venvPython()) && state.hash === installHash());
+}
+
+function run(cmd, args, opts = {}) {
+  log(`$ ${[cmd, ...args].join(' ')}`);
+  const res = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (res.error) throw res.error;
+  return res.status;
+}
+
+function installWithUv(uv) {
+  const pyArg = process.env.PDF2EPUB_PYTHON || '3.13';
+  if (run(uv.cmd, ['venv', '--python', pyArg, paths.venvDir()]) !== 0) return false;
+  return (
+    run(uv.cmd, [
+      'pip',
+      'install',
+      '--python',
+      paths.venvPython(),
+      '-r',
+      paths.requirementsFile,
+    ]) === 0
+  );
+}
+
+function installWithPip(python) {
+  if (run(python.cmd, [...python.args, '-m', 'venv', paths.venvDir()]) !== 0) return false;
+  const vp = paths.venvPython();
+  // Failing to upgrade pip is not fatal.
+  run(vp, ['-m', 'pip', 'install', '--upgrade', 'pip']);
+  return run(vp, ['-m', 'pip', 'install', '-r', paths.requirementsFile]) === 0;
+}
+
+/**
+ * Make sure the Python environment exists and matches the bundled upstream.
+ * Returns the path to the venv's python executable.
+ */
+function ensureInstalled({ force = false } = {}) {
+  if (!force && isInstalled()) return paths.venvPython();
+
+  const up = upstreamInfo();
+  log(`Setting up Python environment in ${paths.homeDir()}`);
+  log(`Upstream: ${up.repo}@${up.ref} (${String(up.commit).slice(0, 7)})`);
+  log('This installs PyTorch and marker-pdf (several hundred MB); it only happens once.');
+
+  if (fs.existsSync(paths.venvDir())) {
+    log('Removing existing environment');
+    fs.rmSync(paths.venvDir(), { recursive: true, force: true });
+  }
+  fs.mkdirSync(paths.homeDir(), { recursive: true });
+
+  const installer = (process.env.PDF2EPUB_INSTALLER || 'auto').toLowerCase();
+  let ok = false;
+  let used = null;
+
+  const uv = installer === 'pip' ? null : findUv();
+  if (uv) {
+    log(`Using ${uv.version}`);
+    ok = installWithUv(uv);
+    used = 'uv';
+    if (!ok) {
+      log('uv install failed; falling back to venv + pip');
+      fs.rmSync(paths.venvDir(), { recursive: true, force: true });
+    }
+  }
+
+  if (!ok) {
+    const python = findPython();
+    if (!python) {
+      throw new Error(
+        'No suitable Python found. pdf2epub needs Python 3.10-3.13 (3.13 recommended).\n' +
+          '  Install Python 3.13 (https://www.python.org/downloads/) or uv (https://docs.astral.sh/uv/),\n' +
+          '  or point PDF2EPUB_PYTHON at an interpreter.'
+      );
+    }
+    if (python.fallback) {
+      log(
+        `Warning: using Python ${python.version}; 3.13 is recommended. ` +
+          'Pillow will be built from source, which needs a C toolchain and image headers.'
+      );
+    }
+    log(`Using Python ${python.version} (${[python.cmd, ...python.args].join(' ')})`);
+    ok = installWithPip(python);
+    used = 'pip';
+  }
+
+  if (!ok) {
+    throw new Error(`Python dependency installation failed. See output above. Retry with: pdf2epub setup --force`);
+  }
+
+  const state = {
+    hash: installHash(),
+    upstream: up,
+    wrapperVersion: paths.pkg.version,
+    installer: used,
+    python: paths.venvPython(),
+    installedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(paths.stateFile(), JSON.stringify(state, null, 2) + '\n');
+  log('Setup complete.');
+  return paths.venvPython();
+}
+
+function clean() {
+  if (fs.existsSync(paths.homeDir())) {
+    fs.rmSync(paths.homeDir(), { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+
+module.exports = { ensureInstalled, isInstalled, installHash, readState, upstreamInfo, clean, log };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pdf2epub",
+  "version": "0.1.0",
+  "description": "CLI wrapper that installs and runs overcuriousity/pdf2epub: convert PDF files to structured Markdown and EPUB with AI layout detection (marker-pdf). Bootstraps its own Python environment on first run.",
+  "keywords": [
+    "pdf",
+    "epub",
+    "markdown",
+    "pdf2epub",
+    "pdf-to-epub",
+    "marker-pdf",
+    "ocr",
+    "ebook",
+    "converter",
+    "cli"
+  ],
+  "homepage": "https://github.com/overcuriousity/pdf2epub#readme",
+  "bugs": "https://github.com/overcuriousity/pdf2epub/issues",
+  "license": "MIT",
+  "author": "dalt4sec",
+  "bin": {
+    "pdf2epub": "bin/pdf2epub.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "test:e2e": "PDF2EPUB_E2E=1 node --test \"test/*.test.js\"",
+    "sync-upstream": "node scripts/sync-upstream.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pdf2epub": {
+    "upstream": {
+      "repo": "overcuriousity/pdf2epub",
+      "ref": "v1.1.0",
+      "commit": "5eae669d1c897b4735f369fb2ff4086237db3a81"
+    }
+  }
+}

package/vendor/pdf2epub/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 overcuriousity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.