mark-epub-down 0.1.0

package/dist/utils/epub-path.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEpubPath = normalizeEpubPath;
+exports.splitEpubHref = splitEpubHref;
+exports.buildTargetKey = buildTargetKey;
+exports.resolveEpubHref = resolveEpubHref;
+const node_path_1 = __importDefault(require("node:path"));
+function normalizeEpubPath(value) {
+    const normalized = value.replace(/\\/g, "/");
+    return node_path_1.default.posix.normalize(normalized).replace(/^\.\//, "");
+}
+function splitEpubHref(href) {
+    const [pathPart, fragment] = href.split("#", 2);
+    return {
+        pathPart,
+        fragment: fragment && fragment.length > 0 ? fragment : undefined,
+    };
+}
+function buildTargetKey(resourcePath, fragment) {
+    return fragment ? `${normalizeEpubPath(resourcePath)}#${fragment}` : normalizeEpubPath(resourcePath);
+}
+function resolveEpubHref(baseDocumentPath, href) {
+    const trimmedHref = href.trim();
+    if (isExternalHref(trimmedHref)) {
+        return {
+            kind: "external",
+            href: trimmedHref,
+        };
+    }
+    if (trimmedHref.startsWith("#")) {
+        const fragment = trimmedHref.slice(1);
+        return {
+            kind: "internal",
+            href: trimmedHref,
+            resourcePath: normalizeEpubPath(baseDocumentPath),
+            fragment,
+            targetKey: buildTargetKey(baseDocumentPath, fragment),
+        };
+    }
+    const { pathPart, fragment } = splitEpubHref(trimmedHref);
+    const resourcePath = normalizeEpubPath(node_path_1.default.posix.join(node_path_1.default.posix.dirname(normalizeEpubPath(baseDocumentPath)), pathPart));
+    return {
+        kind: "internal",
+        href: trimmedHref,
+        resourcePath,
+        fragment,
+        targetKey: buildTargetKey(resourcePath, fragment),
+    };
+}
+function isExternalHref(href) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//");
+}
+//# sourceMappingURL=epub-path.js.map

package/dist/utils/epub-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epub-path.js","sourceRoot":"","sources":["../../src/utils/epub-path.ts"],"names":[],"mappings":";;;;;AAUA,8CAGC;AAED,sCASC;AAED,wCAEC;AAED,0CAiCC;AA/DD,0DAA6B;AAU7B,SAAgB,iBAAiB,CAAC,KAAa;IAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7C,OAAO,mBAAI,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,SAAgB,aAAa,CAAC,IAAY;IAIxC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAChD,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;KACjE,CAAC;AACJ,CAAC;AAED,SAAgB,cAAc,CAAC,YAAoB,EAAE,QAAiB;IACpE,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,YAAY,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;AACvG,CAAC;AAED,SAAgB,eAAe,CAAC,gBAAwB,EAAE,IAAY;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAEhC,IAAI,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,WAAW;SAClB,CAAC;IACJ,CAAC;IAED,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACtC,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,WAAW;YACjB,YAAY,EAAE,iBAAiB,CAAC,gBAAgB,CAAC;YACjD,QAAQ;YACR,SAAS,EAAE,cAAc,CAAC,gBAAgB,EAAE,QAAQ,CAAC;SACtD,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,iBAAiB,CACpC,mBAAI,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAI,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC,EAAE,QAAQ,CAAC,CACnF,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,WAAW;QACjB,YAAY;QACZ,QAAQ;QACR,SAAS,EAAE,cAAc,CAAC,YAAY,EAAE,QAAQ,CAAC;KAClD,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC"}

package/dist/utils/path.d.ts

@@ -0,0 +1,2 @@
+export declare function deriveOutputPath(inputPath: string, outputPath: string | undefined, cwd: string): string;
+export declare function ensureOutputPathAvailable(outputPath: string, overwrite?: boolean): Promise<void>;

package/dist/utils/path.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveOutputPath = deriveOutputPath;
+exports.ensureOutputPathAvailable = ensureOutputPathAvailable;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../domain/errors");
+function deriveOutputPath(inputPath, outputPath, cwd) {
+    if (outputPath) {
+        return node_path_1.default.resolve(cwd, outputPath);
+    }
+    const parsed = node_path_1.default.parse(inputPath);
+    return node_path_1.default.join(parsed.dir, `${parsed.name}.md`);
+}
+async function ensureOutputPathAvailable(outputPath, overwrite = false) {
+    try {
+        await (0, promises_1.access)(outputPath);
+    }
+    catch (error) {
+        if (error instanceof errors_1.ConversionError) {
+            throw error;
+        }
+        return;
+    }
+    if (overwrite) {
+        return;
+    }
+    throw errors_1.ConversionError.fatal("OUTPUT_EXISTS", `output file already exists and overwrite is disabled: ${outputPath}`);
+}
+//# sourceMappingURL=path.js.map

package/dist/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":";;;;;AAKA,4CAOC;AAED,8DAsBC;AApCD,+CAA0C;AAC1C,0DAA6B;AAE7B,6CAAmD;AAEnD,SAAgB,gBAAgB,CAAC,SAAiB,EAAE,UAA8B,EAAE,GAAW;IAC7F,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,mBAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,MAAM,GAAG,mBAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,mBAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC;AACpD,CAAC;AAEM,KAAK,UAAU,yBAAyB,CAC7C,UAAkB,EAClB,SAAS,GAAG,KAAK;IAEjB,IAAI,CAAC;QACH,MAAM,IAAA,iBAAM,EAAC,UAAU,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,wBAAe,EAAE,CAAC;YACrC,MAAM,KAAK,CAAC;QACd,CAAC;QAED,OAAO;IACT,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IAED,MAAM,wBAAe,CAAC,KAAK,CACzB,eAAe,EACf,yDAAyD,UAAU,EAAE,CACtE,CAAC;AACJ,CAAC"}

package/docs/epub-to-md-v1-public-spec.md

@@ -0,0 +1,176 @@
+# EPUB to Markdown v1 Public Spec
+
+## Overview
+
+`mark-epub-down` is a Node.js CLI and package that converts a single EPUB into a single Markdown document.
+
+The v1 output is intended as source material for LLM knowledge bases, wikis, and related ingestion pipelines. The project prioritizes semantic preservation, source correctness, and low-risk transformation over reader-oriented Markdown polish.
+
+## Scope
+
+- Input: one `.epub` file
+- Output: one `.md` file
+- Supported runtime targets: Node.js `20`, `22`, and `24`
+- Implementation language: TypeScript
+- Distribution shape: npm package with CLI and programmatic Node API
+
+## Goals
+
+- Preserve meaningful document structure and content semantics.
+- Keep source order aligned with the EPUB spine.
+- Include EPUB-native table-of-contents information in the output.
+- Prefer conservative transformations over aggressive normalization.
+- Produce Markdown that works well as downstream ingestion source.
+
+## Non-goals
+
+- Perfect visual reproduction of EPUB layout or CSS presentation
+- Viewer-specific Markdown tuning as the primary goal
+- Heuristic reconstruction of missing structure
+- Chapter-splitting output in the v1 baseline
+
+## CLI
+
+The v1 CLI keeps a small surface:
+
+```text
+epub2llm <input.epub>
+epub2llm <input.epub> -o <output.md>
+epub2llm -h
+epub2llm --help
+epub2llm -V
+epub2llm --version
+```
+
+- The input EPUB is a positional argument.
+- `-o` and `--output` select an explicit output path.
+- If no output path is provided, the tool derives one from the input filename with a `.md` extension.
+- Existing output files are not overwritten silently.
+- In interactive terminal use, the CLI may prompt for explicit overwrite confirmation with a default `No` answer.
+
+## Node API
+
+The package exposes a programmatic `convertEpub()` function for Node.js use.
+
+The stable v1 options are:
+
+- `inputPath`
+- `outputPath`
+- `cwd`
+- `overwrite`
+
+`convertEpub()` writes the Markdown file and returns structured conversion results, including warnings. It does not prompt for overwrite confirmation or print terminal output. If the output target already exists and `overwrite` is not enabled, the function fails conservatively with `OUTPUT_EXISTS`.
+
+## Output Structure
+
+The generated Markdown document uses this high-level structure:
+
+1. minimal YAML front matter
+2. top-level book title
+3. dedicated `## TOC` section
+4. merged body content in spine order
+
+The front matter stays minimal and only includes values available from EPUB package metadata:
+
+- `title`
+- `creator`
+- `language`
+- `identifier`
+- `publisher`
+- `published`
+
+Missing metadata fields are omitted rather than guessed.
+
+`published` is mapped from EPUB `dc:date`. Full dates and date-times are normalized to `YYYY-MM-DD`. Partial dates such as `YYYY` or `YYYY-MM` are preserved as-is rather than padded with guessed precision.
+
+## Conversion Rules
+
+### Table of contents
+
+- The EPUB-native TOC is the authoritative TOC source.
+- The TOC is rendered as a hierarchical Markdown list under `## TOC`.
+- Entries become Markdown links only when the target can be mapped confidently.
+- Unresolved TOC items remain plain text.
+
+### Document structure
+
+- Source heading levels are preserved.
+- Source headings are not globally shifted to compensate for the inserted book title.
+- The merged body follows the source document's own heading structure.
+
+### Links, anchors, and notes
+
+- Internal targets are rewritten into collision-safe identifiers for merged single-file output.
+- TOC targets, internal links, and note-related links are rewritten conservatively.
+- When a link target cannot be rewritten safely, the output degrades conservatively instead of guessing.
+- Footnote and note structure is preserved as close to the original topology as possible.
+
+### Content cleanup
+
+- Cleanup is based on DOM/XHTML elements, not page-type inference.
+- The strategy is conservative blacklist removal.
+- Only high-confidence non-text elements are removed by default.
+- Empty containers may be removed only when they carry no visible text, no preserved children, and no necessary structure.
+
+The default removable set includes:
+
+- `script`
+- `style`
+- `img`
+- `svg`
+- `canvas`
+- `audio`
+- `video`
+- `source`
+- `track`
+- `iframe`
+- `object`
+- `embed`
+- `form`
+- `input`
+- `button`
+- `select`
+- `option`
+- `textarea`
+
+Containers such as `figure`, `figcaption`, `aside`, `section`, `nav`, `div`, and `span` are not removed purely by tag name.
+
+### Core element mapping
+
+- `h1` to `h6` map to Markdown headings
+- `p` maps to paragraphs
+- `blockquote` maps to Markdown blockquotes
+- `hr` maps to `---`
+- `em` and `i` map to emphasis
+- `strong` and `b` map to strong emphasis
+- `code` maps to inline code
+- safe `a[href]` targets map to Markdown links
+
+Definition lists are degraded into Markdown list structures instead of being dropped.
+
+## Errors and Warnings
+
+Fatal errors stop conversion and return a non-zero exit code. Typical fatal cases include:
+
+- missing input file
+- invalid or unreadable EPUB container
+- missing or unreadable OPF/package document
+- unreadable spine content required for conversion
+- unwritable output path
+- output target already exists and overwrite is not confirmed
+
+Warnings still allow output generation and keep a success exit code. Typical warning cases include:
+
+- missing TOC
+- unresolved TOC targets
+- links that cannot be safely rewritten
+- dropped elements caused by cleanup rules
+- incomplete metadata
+- source structures that cannot be represented perfectly in Markdown
+
+Warnings may be summarized in CLI output, and some low-signal warnings may be retained only in structured results rather than shown in the terminal.
+
+## Validation Boundary
+
+- Fixed Layout EPUB (FXL) is out of scope for v1.
+- Validation should cover nested TOCs, footnotes, CJK ruby content, tables, image-heavy EPUBs, degraded TOC metadata, incomplete metadata, and RTL samples.

package/docs/v1-technical-selection.md

@@ -0,0 +1,106 @@
+# EPUB to Markdown v1 Technical Selection
+
+This document records the implementation choices made strictly from `epub-to-md-v1-spec.md`.
+
+## Runtime and language
+
+- Supported runtime targets: Node.js `20`, `22`, and `24`
+- Language: TypeScript
+- Module output: CommonJS for a simple Node CLI and library distribution path
+
+## Package choices
+
+| Concern | Package | Why this fits the spec |
+| --- | --- | --- |
+| CLI parsing | `commander` | Mature, minimal, standard `-h/-V/-o` surface |
+| EPUB unzip to temp dir | `extract-zip` | Small, established, matches the "unpack into temporary working area" pipeline |
+| XML parsing | `fast-xml-parser` | Mature, fast, good fit for `container.xml`, OPF, and NCX |
+| XHTML/DOM handling | `jsdom@26.1.0` | Stable DOM API and compatible with the supported Node.js runtimes |
+| HTML to Markdown | `turndown` | Widely used baseline converter for conservative Markdown generation |
+| GFM table support | `turndown-plugin-gfm` | Provides a starting point for simple-table conversion without inventing a custom renderer too early |
+
+## Project skeleton
+
+The codebase is split by the pipeline described in the spec:
+
+- `src/cli.ts`
+  - CLI surface and exit handling
+- `src/cli/`
+  - CLI-only overwrite confirmation, reporting, and command orchestration
+- `src/application/convert-epub.ts`
+  - public file-writing API for Node consumers
+- `src/application/convert-epub-document.ts`
+  - internal conversion core that returns Markdown plus warnings
+- `src/epub/`
+  - archive extraction, `container.xml`, OPF parsing, TOC parsing, spine indexing, spine content loading
+- `src/transform/`
+  - DOM cleanup, anchor rewriting, internal-link rewriting, Markdown conversion primitives
+- `src/output/`
+  - front matter, title, and TOC rendering
+- `src/domain/`
+  - spec constants, shared types, warnings, and fatal error model
+- `src/utils/`
+  - path derivation and conservative output handling
+
+## Current MVP coverage
+
+The current implementation now covers the minimum viable pipeline:
+
+1. input/output path validation
+2. temp-dir creation and EPUB extraction
+3. `container.xml` parsing
+4. OPF metadata/manifest/spine parsing
+5. TOC source detection and parsing
+6. spine index construction
+7. spine XHTML loading
+8. conservative DOM cleanup
+9. internal target collection from `id` / `name` / `xml:id`, with merged-document anchor generation
+10. low-risk internal link, TOC target, and explicit footnote/backlink rewriting
+11. XHTML-to-Markdown conversion
+12. front matter, book title, TOC, and merged body rendering
+13. final Markdown file emission
+14. stderr warning emission
+
+## Still intentionally deferred
+
+The following spec areas are still intentionally partial rather than fully complete:
+
+1. deeper footnote edge cases beyond explicit source anchors and note/backlink semantics
+2. richer table strategy, especially complex-table HTML fallback detection
+3. broader malformed-EPUB tolerance and regression coverage
+
+## Regression Harness
+
+The repo now includes a small regression suite using Node's built-in `node:test` runner:
+
+- run with `npm test`
+- tests generate temporary EPUB fixtures on the fly
+- current coverage includes:
+  - output skeleton generation
+  - warning suppression for expected dropped elements
+  - `<br>` rendered as plain newline for downstream Markdown tool compatibility
+  - ruby converted to explicit text fallback
+  - RTL text preserved in TOC and body content
+  - degraded-but-readable TOC with unresolved targets downgraded to plain text plus warning
+  - explicit footnote/backlink preservation
+  - role-based endnotes stored as list items without losing ordered-list semantics
+  - image-heavy low-text content preserving surviving text while dropping media
+  - row-header tables preserved as Markdown tables without unnecessary HTML fallback
+  - simple vs complex table handling
+  - inconsistent package navigation metadata downgraded to warning instead of fatal failure
+  - invalid nav downgraded to warning instead of fatal failure
+  - NCX fallback when nav parsing fails
+  - unreadable NCX downgraded to warning instead of fatal failure
+  - invalid NCX downgraded to warning instead of fatal failure
+  - missing-TOC warning behavior
+  - impact-oriented warning wording and explicit CLI visibility policy
+  - conservative output-file overwrite failure
+  - interactive overwrite confirmation accept path
+  - interactive overwrite confirmation decline / EOF path
+
+## Known Divergences
+
+The current implementation intentionally diverges from one point in the draft spec:
+
+- `<br>` currently renders as a plain newline, not trailing `\`
+  - reason: downstream tools in actual use, including Obsidian/MarkEdit in this workflow, do not reliably interpret the trailing-backslash hard-break form

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "mark-epub-down",
+  "version": "0.1.0",
+  "description": "EPUB to Markdown source generator for LLM knowledge bases, wikis, and related ingestion pipelines",
+  "license": "MIT",
+  "keywords": [
+    "epub",
+    "markdown",
+    "cli",
+    "node",
+    "llm",
+    "ingestion"
+  ],
+  "homepage": "https://github.com/thomson1973/mark-epub-down#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomson1973/mark-epub-down.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thomson1973/mark-epub-down/issues"
+  },
+  "bin": {
+    "epub2llm": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "engines": {
+    "node": "^20.14.0 || ^22.0.0 || ^24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "extract-zip": "^2.0.1",
+    "fast-xml-parser": "^5.5.11",
+    "jsdom": "^26.1.0",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^28.0.1",
+    "@types/node": "^20.19.39",
+    "@types/turndown": "^5.0.6",
+    "typescript": "^5.5.3"
+  }
+}