cajupdf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julio Cesar Ody
+
+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,135 @@
+# cajupdf 🥜
+
+**Crack open a PDF, get clean markdown and its pictures.**
+
+`caju` is the cashew — that funny little nut that grows _outside_ its fruit, in
+plain sight. `cajupdf` does the same trick to your PDFs: it cracks the shell and
+hands you the good stuff — readable markdown, plus every embedded image, laid out
+where you can actually use them.
+
+---
+
+## What it does
+
+Three stages, one command:
+
+1. **Text** — pulled with [`unpdf`](https://github.com/unjs/unpdf) (PDF.js under
+   the hood). Scanned/image-only PDFs fall back to the macOS **Vision framework
+   OCR** automatically — no setup, no API keys.
+2. **Images / figures / sigils** — extracted at full fidelity with Poppler's
+   `pdfimages` (JPEGs stay JPEGs, PNGs stay PNGs).
+3. **Markdown** — assembled with YAML front matter (title, author, page & image
+   counts) and one `## Page N` section per page, images linked inline.
+
+---
+
+## Requirements
+
+- **macOS** — cajupdf leans on the system Vision framework for OCR, so it's
+  macOS-only for now.
+- **Node ≥ 22**
+- **`pdfimages`** (Poppler) — only needed when extracting images:
+  `brew install poppler`. Skip it entirely with `--no-images`.
+
+---
+
+## Install
+
+```bash
+npm i -g cajupdf
+# or
+pnpm add -g cajupdf
+```
+
+Then:
+
+```bash
+cajupdf some.pdf
+```
+
+Or run it from a clone:
+
+```bash
+pnpm install
+pnpm build
+node dist/cli.js some.pdf
+```
+
+---
+
+## Usage
+
+```
+cajupdf <pdf> [<pdf> ...] [options]
+
+Options:
+  --no-images        Skip image extraction (images are extracted by default).
+  --url-friendly     Slugify output names to kebab-case (default: verbatim).
+  --out-dir <dir>    Where to write outputs (default: current directory).
+  -h, --help         Show help.
+  -v, --version      Show version.
+```
+
+Pass as many PDFs as you like — each is processed independently, and one bad file
+won't sink the rest (the run just exits non-zero if any failed).
+
+---
+
+## Output layout
+
+The markdown is `<name>.md`, and its images sit in a sibling `<name>-images/`
+directory.
+
+**Default (verbatim names):**
+
+```
+My Book.pdf  →  My Book.md
+                My Book-images/
+                  img-002-000.jpg
+                  ...
+```
+
+Verbatim names can contain spaces, so image links are percent-encoded and
+angle-bracket-wrapped to stay valid markdown:
+`![](<My Book-images/img-002-000.jpg>)`.
+
+**`--url-friendly` (kebab-case):**
+
+```
+My Book.pdf  →  my-book.md
+                my-book-images/
+                  img-002-000.jpg
+                  ...
+```
+
+---
+
+## Programmatic API
+
+`cajupdf` is also a library. The one-call workhorse:
+
+```ts
+import { extractPdf } from 'cajupdf'
+
+const result = await extractPdf('My Book.pdf', {
+  images: true, // extract images (default)
+  urlFriendly: false, // keep names verbatim (default)
+  outDir: './out', // default: cwd
+  onProgress: p => console.log(p.stage, p.current, p.total),
+})
+
+// → { mdPath, imageDir, pageCount, imageCount }
+```
+
+Or reach for the individual stages — `parsePDF`, `extractImages`, `toMarkdown`,
+`slugify`, `resolveOutputNames` — all exported with full types.
+
+---
+
+## License
+
+MIT
+
+---
+
+_Built to be cracked open. Mind the shell._ 🥜🐘

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { t as e } from "./extract-pdf-Bnge6uHj.js";
+import t from "node:fs";
+import n from "node:path";
+import { fileURLToPath as r } from "node:url";
+import i from "chalk";
+//#region src/lib/spinner.ts
+var a = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+], o = 80;
+function s(e, t, n) {
+	let r = process.stdout.columns ?? 80, i = Math.max(10, r - t - n - 1);
+	return e.length <= i ? e : e.slice(0, Math.max(1, i - 1)) + "…";
+}
+function c(e, t, n = 15) {
+	let r = t > 0 ? Math.min(e / t, 1) : 0, a = Math.round(r * n), o = n - a, s = i.cyan("█".repeat(a)) + i.dim("░".repeat(o)), c = `${Math.round(r * 100)}%`.padStart(4);
+	return `[${s}] ${i.dim(c)}`;
+}
+function l(e) {
+	let t = 0, n = e, r = 0, l = 0, u = null, d = () => {
+		let e = i.cyan(a[t]), o = l > 0 ? ` ${c(r, l)}` : "", u = s(n, 2, l > 0 ? 23 : 0);
+		process.stdout.write(`\r${e} ${i.dim(u)}${o}\x1b[K`), t = (t + 1) % a.length;
+	};
+	return u = setInterval(d, o), d(), {
+		update(e) {
+			n = e;
+		},
+		setProgress(e, t) {
+			r = e, l = t;
+		},
+		stop(e) {
+			u &&= (clearInterval(u), null), e ? process.stdout.write(`\r${i.dim(e)}\x1b[K\n`) : process.stdout.write("\r\x1B[K");
+		},
+		succeed(e) {
+			u &&= (clearInterval(u), null), process.stdout.write(`\r${i.green("✓")} ${i.dim(e)}\x1b[K\n`);
+		},
+		fail(e) {
+			u &&= (clearInterval(u), null), process.stdout.write(`\r${i.red("✗")} ${i.dim(e)}\x1b[K\n`);
+		}
+	};
+}
+//#endregion
+//#region src/cli.ts
+function u() {
+	console.error("cajupdf — crack open a PDF, get clean markdown and its pictures. 🥜"), console.error(""), console.error("Usage: cajupdf <pdf> [<pdf> ...] [options]"), console.error(""), console.error("Options:"), console.error("  --no-images        Skip image extraction (images are extracted by default)."), console.error("  --url-friendly     Slugify output names to kebab-case (default: verbatim)."), console.error("  --out-dir <dir>    Where to write outputs (default: current directory)."), console.error("  -h, --help         Show this help."), console.error("  -v, --version      Show version.");
+}
+function d() {
+	let e = n.dirname(r(import.meta.url));
+	return JSON.parse(t.readFileSync(n.join(e, "..", "package.json"), "utf-8")).version;
+}
+function f(e) {
+	let t = [], n = !0, r = !1, i;
+	for (let a = 0; a < e.length; a++) {
+		let o = e[a];
+		switch (o) {
+			case "--no-images":
+				n = !1;
+				break;
+			case "--url-friendly":
+				r = !0;
+				break;
+			case "--out-dir": {
+				let t = e[++a];
+				if (!t) return null;
+				i = t;
+				break;
+			}
+			default:
+				if (o && o.startsWith("-")) return null;
+				o && t.push(o);
+		}
+	}
+	return t.length === 0 ? null : {
+		pdfs: t,
+		images: n,
+		urlFriendly: r,
+		outDir: i
+	};
+}
+async function p(r, i) {
+	let a = n.resolve(r), o = n.basename(a);
+	if (!t.existsSync(a)) return console.error(`✗ File not found: ${r}`), !1;
+	if (n.extname(a).toLowerCase() !== ".pdf") return console.error(`✗ Not a PDF: ${r}`), !1;
+	let s = l(`Extracting ${o}`), c = (e) => {
+		switch (e.stage) {
+			case "loading":
+				s.update(`Loading ${o}`);
+				break;
+			case "parsing":
+				s.update(`Parsing text ${o}`), s.setProgress(e.current, e.total);
+				break;
+			case "ocr":
+				s.update(`OCR (Vision) ${o}`), s.setProgress(e.current, e.total);
+				break;
+			case "images":
+				s.update(`Extracting images ${o}`), e.total > 0 && s.setProgress(e.current, e.total);
+				break;
+			case "done": break;
+		}
+	};
+	try {
+		let t = await e(a, {
+			...i,
+			onProgress: c
+		}), r = n.basename(t.mdPath);
+		return s.succeed(`${o} → ${r} (${t.pageCount} pages, ${t.imageCount} images)`), !0;
+	} catch (e) {
+		return s.fail(`Failed: ${o}`), console.error(e instanceof Error ? e.message : e), !1;
+	}
+}
+async function m() {
+	let e = process.argv.slice(2);
+	(e[0] === "-h" || e[0] === "--help") && (u(), process.exit(0)), (e[0] === "-v" || e[0] === "--version") && (console.log(d()), process.exit(0));
+	let t = f(e);
+	t || (u(), process.exit(2));
+	let n = {
+		images: t.images,
+		urlFriendly: t.urlFriendly,
+		outDir: t.outDir
+	}, r = !1;
+	for (let e of t.pdfs) await p(e, n) || (r = !0);
+	process.exit(+!!r);
+}
+m().catch((e) => {
+	console.error(e), process.exit(1);
+});
+//#endregion

package/dist/extract-pdf-Bnge6uHj.js

@@ -0,0 +1,192 @@
+import e from "node:fs";
+import t from "node:path";
+import { execFile as n } from "node:child_process";
+import { extractText as r, getDocumentProxy as i } from "unpdf";
+import { promisify as a } from "node:util";
+//#region src/lib/text.ts
+var o = () => new Promise((e) => setTimeout(e, 10));
+async function s(n, a) {
+	let s = e.readFileSync(n);
+	a?.({
+		stage: "loading",
+		current: 0,
+		total: 0
+	}), await o();
+	let c = await i(new Uint8Array(s)), u = c.numPages, d, f;
+	try {
+		let e = (await c.getMetadata())?.info;
+		d = e?.Title, f = e?.Author;
+	} catch {}
+	a?.({
+		stage: "parsing",
+		current: 0,
+		total: u
+	}), await o();
+	let { text: p } = await r(c, { mergePages: !1 });
+	for (let e = 0; e < p.length; e++) e % 10 == 0 && (a?.({
+		stage: "parsing",
+		current: e + 1,
+		total: u
+	}), await o());
+	let m = p.map((e) => e.trim());
+	return !m.some((e) => e.length > 0) && process.platform === "darwin" && (a?.({
+		stage: "ocr",
+		current: 0,
+		total: u
+	}), await o(), m = await l(n, u, a)), a?.({
+		stage: "done",
+		current: u,
+		total: u
+	}), {
+		text: m.join("\n\n"),
+		pageCount: u,
+		pages: m,
+		metadata: {
+			title: d || t.basename(n, ".pdf"),
+			author: f
+		}
+	};
+}
+var c = "\nimport Foundation\nimport PDFKit\nimport Vision\n\nguard CommandLine.arguments.count > 1 else {\n  fputs(\"Usage: ocr-pdf <path>\\n\", stderr)\n  exit(1)\n}\n\nlet pdfPath = CommandLine.arguments[1]\nguard let doc = PDFDocument(url: URL(fileURLWithPath: pdfPath)) else {\n  fputs(\"Failed to open PDF\\n\", stderr)\n  exit(1)\n}\n\nvar result: [[String: Any]] = []\n\nfor i in 0..<doc.pageCount {\n  guard let page = doc.page(at: i) else {\n    result.append([\"page\": i + 1, \"text\": \"\"])\n    continue\n  }\n\n  // Render page to CGImage for Vision OCR\n  let bounds = page.bounds(for: .mediaBox)\n  let scale: CGFloat = 2.0  // 2x for better OCR accuracy\n  let width = Int(bounds.width * scale)\n  let height = Int(bounds.height * scale)\n\n  guard let ctx = CGContext(\n    data: nil,\n    width: width,\n    height: height,\n    bitsPerComponent: 8,\n    bytesPerRow: 0,\n    space: CGColorSpaceCreateDeviceRGB(),\n    bitmapInfo: CGImageAlphaInfo.premultipliedFirst.rawValue\n  ) else {\n    result.append([\"page\": i + 1, \"text\": \"\"])\n    continue\n  }\n\n  ctx.setFillColor(CGColor.white)\n  ctx.fill(CGRect(x: 0, y: 0, width: width, height: height))\n  ctx.scaleBy(x: scale, y: scale)\n\n  // PDFKit renders in a flipped coordinate space\n  NSGraphicsContext.saveGraphicsState()\n  let nsCtx = NSGraphicsContext(cgContext: ctx, flipped: false)\n  NSGraphicsContext.current = nsCtx\n  page.draw(with: .mediaBox, to: ctx)\n  NSGraphicsContext.restoreGraphicsState()\n\n  guard let cgImage = ctx.makeImage() else {\n    result.append([\"page\": i + 1, \"text\": \"\"])\n    continue\n  }\n\n  let semaphore = DispatchSemaphore(value: 0)\n  var pageText = \"\"\n\n  let request = VNRecognizeTextRequest { request, error in\n    if let observations = request.results as? [VNRecognizedTextObservation] {\n      pageText = observations\n        .compactMap { $0.topCandidates(1).first?.string }\n        .joined(separator: \"\\n\")\n    }\n    semaphore.signal()\n  }\n  request.recognitionLevel = .accurate\n  request.usesLanguageCorrection = true\n\n  let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])\n  try? handler.perform([request])\n  semaphore.wait()\n\n  result.append([\"page\": i + 1, \"text\": pageText])\n\n  // Progress: write page number to stderr so the caller can track it\n  fputs(\"PAGE:\\(i + 1)\\n\", stderr)\n}\n\nlet jsonData = try! JSONSerialization.data(withJSONObject: result)\nprint(String(data: jsonData, encoding: .utf8)!)\n";
+async function l(r, i, a) {
+	let o = process.env.TMPDIR || "/tmp", s = t.join(o, ".ocr-script-" + process.pid + ".swift");
+	try {
+		return e.writeFileSync(s, c), await new Promise((e, t) => {
+			n("/usr/bin/swift", [s, r], {
+				maxBuffer: 100 * 1024 * 1024,
+				timeout: 600 * 1e3
+			}, (n, r) => {
+				if (n) {
+					t(/* @__PURE__ */ Error(`OCR failed: ${n.message}`));
+					return;
+				}
+				try {
+					e(JSON.parse(r).map((e) => e.text.trim()));
+				} catch (e) {
+					t(/* @__PURE__ */ Error(`Failed to parse OCR output: ${e}`));
+				}
+			}).stderr?.on("data", (e) => {
+				let t = e.toString().split("\n");
+				for (let e of t) {
+					let t = e.match(/^PAGE:(\d+)$/);
+					if (t?.[1]) {
+						let e = parseInt(t[1], 10);
+						a?.({
+							stage: "ocr",
+							current: e,
+							total: i
+						});
+					}
+				}
+			});
+		});
+	} finally {
+		try {
+			e.unlinkSync(s);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/lib/images.ts
+var u = a(n);
+async function d(n, r, i = "img", a) {
+	try {
+		await u("pdfimages", ["-v"]);
+	} catch (e) {
+		if (e.code === "ENOENT") throw Error("pdfimages not found on PATH. Install Poppler: `brew install poppler` (macOS) or your distro equivalent.");
+	}
+	e.mkdirSync(r, { recursive: !0 }), a?.({
+		stage: "images",
+		current: 0,
+		total: 0
+	}), await u("pdfimages", [
+		"-p",
+		"-all",
+		n,
+		t.join(r, i)
+	], { maxBuffer: 100 * 1024 * 1024 });
+	let o = RegExp(`^${f(i)}-(\\d+)-(\\d+)\\.([A-Za-z0-9]+)$`), s = e.readdirSync(r), c = [];
+	for (let e of s) {
+		let n = e.match(o);
+		!n?.[1] || !n[2] || c.push({
+			page: parseInt(n[1], 10),
+			index: parseInt(n[2], 10),
+			filename: e,
+			path: t.join(r, e)
+		});
+	}
+	return c.sort((e, t) => e.page - t.page || e.index - t.index), a?.({
+		stage: "images",
+		current: c.length,
+		total: c.length
+	}), c;
+}
+function f(e) {
+	return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/lib/markdown.ts
+function p(e, t, n) {
+	let r = n.title ?? e.metadata.title ?? "Untitled", i = e.metadata.author, a = /* @__PURE__ */ new Map();
+	for (let e of t) {
+		let t = a.get(e.page) ?? [];
+		t.push(e), a.set(e.page, t);
+	}
+	let o = [];
+	o.push("---"), o.push(`title: ${h(r)}`), i && o.push(`author: ${h(i)}`), o.push(`pages: ${e.pageCount}`), o.push(`images: ${t.length}`), o.push("---"), o.push("");
+	for (let t = 0; t < e.pages.length; t++) {
+		let r = t + 1, i = e.pages[t]?.trim() ?? "", s = a.get(r) ?? [];
+		if (!(!i && s.length === 0)) {
+			o.push(`## Page ${r}`), o.push(""), i && (o.push(i), o.push(""));
+			for (let e of s) o.push(`![](${m(n.imageDir, e.filename)})`);
+			s.length > 0 && o.push("");
+		}
+	}
+	return o.join("\n");
+}
+function m(e, t) {
+	let n = `${e}/${t}`, r = encodeURI(n);
+	return r === n && !/[()]/.test(n) ? n : `<${r}>`;
+}
+function h(e) {
+	return /[:#\n"'\\]/.test(e) ? JSON.stringify(e) : e;
+}
+//#endregion
+//#region src/lib/slugify.ts
+function g(e, t = 60) {
+	let n = e.normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/['‘’`´]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	if (n.length <= t) return n || "untitled";
+	let r = n.slice(0, t), i = r.lastIndexOf("-");
+	return (i > t / 2 ? r.slice(0, i) : r).replace(/-+$/, "");
+}
+//#endregion
+//#region src/lib/resolve-output-names.ts
+function _(e, n = {}) {
+	let r = t.resolve(n.outDir ?? process.cwd()), i = t.basename(e, t.extname(e)), a = n.urlFriendly ? g(i) : i, o = `${a}-images`;
+	return {
+		baseName: a,
+		mdPath: t.join(r, `${a}.md`),
+		imageDir: t.join(r, o),
+		imageDirName: o
+	};
+}
+//#endregion
+//#region src/lib/extract-pdf.ts
+async function v(t, n = {}) {
+	let { images: r = !0, urlFriendly: i = !1, outDir: a, onProgress: o } = n, c = _(t, {
+		urlFriendly: i,
+		outDir: a
+	}), l = await s(t, o), u = [];
+	if (r && (u = await d(t, c.imageDir, "img", o), u.length === 0)) try {
+		e.rmdirSync(c.imageDir);
+	} catch {}
+	let f = p(l, u, { imageDir: c.imageDirName });
+	return e.writeFileSync(c.mdPath, f, "utf-8"), {
+		mdPath: c.mdPath,
+		imageDir: u.length > 0 ? c.imageDir : null,
+		pageCount: l.pageCount,
+		imageCount: u.length
+	};
+}
+//#endregion
+export { d as a, p as i, _ as n, s as o, g as r, v as t };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { extractPdf } from './lib/extract-pdf';
+export { parsePDF } from './lib/text';
+export { extractImages } from './lib/images';
+export { toMarkdown } from './lib/markdown';
+export { slugify } from './lib/slugify';
+export { resolveOutputNames } from './lib/resolve-output-names';
+export type { ExtractPdfOptions, ExtractPdfResult } from './lib/extract-pdf';
+export type { ParsedPDF, ParseProgress, ProgressCallback } from './lib/text';
+export type { ExtractedImage } from './lib/images';
+export type { ToMarkdownOptions } from './lib/markdown';
+export type { OutputNames, ResolveOutputNamesOptions } from './lib/resolve-output-names';

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, o as r, r as i, t as a } from "./extract-pdf-Bnge6uHj.js";
+export { e as extractImages, a as extractPdf, r as parsePDF, n as resolveOutputNames, i as slugify, t as toMarkdown };

package/dist/lib/extract-pdf.d.ts

@@ -0,0 +1,25 @@
+import { ProgressCallback } from './text';
+export interface ExtractPdfOptions {
+    /** Extract embedded images via Poppler. Default: true. */
+    images?: boolean;
+    /** Slugify output names to kebab-case. Default: false (verbatim). */
+    urlFriendly?: boolean;
+    /** Directory to write outputs in. Default: current working directory. */
+    outDir?: string;
+    /** Progress callback for spinner/UI wiring. */
+    onProgress?: ProgressCallback;
+}
+export interface ExtractPdfResult {
+    /** Absolute path of the markdown file written. */
+    mdPath: string;
+    /** Absolute path of the image directory, or null when images were skipped/empty. */
+    imageDir: string | null;
+    pageCount: number;
+    imageCount: number;
+}
+/**
+ * Run the full PDF → markdown pipeline for a single file: parse text (with macOS
+ * OCR fallback), optionally extract images, assemble markdown, and write it to
+ * disk. Returns where things landed.
+ */
+export declare function extractPdf(pdfPath: string, options?: ExtractPdfOptions): Promise<ExtractPdfResult>;

package/dist/lib/images.d.ts

@@ -0,0 +1,17 @@
+import { ProgressCallback } from './text';
+export interface ExtractedImage {
+    page: number;
+    index: number;
+    filename: string;
+    path: string;
+}
+/**
+ * Extract embedded images from a PDF using Poppler's `pdfimages`.
+ *
+ * Requires `pdfimages` on PATH (install via `brew install poppler` on macOS).
+ *
+ * Files are written as `<outDir>/<prefix>-<page>-<n>.<ext>` where the page
+ * number is zero-padded by pdfimages. `-all` preserves original encodings
+ * (JPEGs stay JPEGs, etc.) for highest fidelity.
+ */
+export declare function extractImages(pdfPath: string, outDir: string, prefix?: string, onProgress?: ProgressCallback): Promise<ExtractedImage[]>;

package/dist/lib/markdown.d.ts

@@ -0,0 +1,9 @@
+import { ParsedPDF } from './text';
+import { ExtractedImage } from './images';
+export interface ToMarkdownOptions {
+    /** Directory (relative to the .md file) where images live. e.g. "My Book" */
+    imageDir: string;
+    /** Optional title override; defaults to parsed metadata title. */
+    title?: string;
+}
+export declare function toMarkdown(parsed: ParsedPDF, images: ExtractedImage[], options: ToMarkdownOptions): string;

package/dist/lib/resolve-output-names.d.ts

@@ -0,0 +1,22 @@
+export interface OutputNames {
+    /** Markdown stem (source filename without extension; slugified if url-friendly). */
+    baseName: string;
+    /** Absolute path of the markdown file to write. */
+    mdPath: string;
+    /** Absolute path of the image directory (`<baseName>-images`). */
+    imageDir: string;
+    /** Image directory name relative to the markdown file, for use in image links. */
+    imageDirName: string;
+}
+export interface ResolveOutputNamesOptions {
+    /** Slugify names to kebab-case instead of keeping them verbatim. */
+    urlFriendly?: boolean;
+    /** Directory to place outputs in. Defaults to the current working directory. */
+    outDir?: string;
+}
+/**
+ * Decide where a PDF's outputs land. The markdown is `<baseName>.md` and its
+ * images go in a sibling `<baseName>-images/` directory. Default keeps the
+ * source filename verbatim; `--url-friendly` slugifies it.
+ */
+export declare function resolveOutputNames(pdfPath: string, options?: ResolveOutputNamesOptions): OutputNames;

package/dist/lib/slugify.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Turn an arbitrary string into a url-friendly kebab-case slug: lowercased,
+ * diacritics stripped, apostrophes dropped, runs of other characters collapsed
+ * to single hyphens, and truncated at a word boundary within `maxLength`.
+ */
+export declare function slugify(input: string, maxLength?: number): string;

package/dist/lib/spinner.d.ts

@@ -0,0 +1,11 @@
+export interface Spinner {
+    update(text: string): void;
+    stop(finalText?: string): void;
+    succeed(text: string): void;
+    fail(text: string): void;
+}
+export interface ProgressSpinner extends Spinner {
+    setProgress(current: number, total: number): void;
+}
+export declare function createSpinner(initialText: string): Spinner;
+export declare function createProgressSpinner(initialText: string): ProgressSpinner;

package/dist/lib/text.d.ts

@@ -0,0 +1,16 @@
+export interface ParsedPDF {
+    text: string;
+    pageCount: number;
+    pages: string[];
+    metadata: {
+        title?: string;
+        author?: string;
+    };
+}
+export interface ParseProgress {
+    stage: 'loading' | 'parsing' | 'ocr' | 'images' | 'done';
+    current: number;
+    total: number;
+}
+export type ProgressCallback = (progress: ParseProgress) => void;
+export declare function parsePDF(filePath: string, onProgress?: ProgressCallback): Promise<ParsedPDF>;

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "cajupdf",
+  "version": "0.1.0",
+  "description": "Turn PDFs into clean markdown + extracted images (macOS)",
+  "type": "module",
+  "bin": {
+    "cajupdf": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin"
+  ],
+  "keywords": [
+    "pdf",
+    "markdown",
+    "ocr",
+    "vision",
+    "poppler",
+    "pdfimages",
+    "extract",
+    "cli",
+    "macos"
+  ],
+  "license": "MIT",
+  "author": "Julio Cesar Ody",
+  "homepage": "https://github.com/juliocesar/cajupdf#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juliocesar/cajupdf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/juliocesar/cajupdf/issues"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write \"**/*.{ts,js,mjs,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,mjs,json,md}\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "unpdf": "^1.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-only-warn": "^1.2.1",
+    "eslint-plugin-prettier": "^5.5.6",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.60.1",
+    "vite": "^8.0.14",
+    "vite-plugin-dts": "^4",
+    "vitest": "^4.1.7"
+  }
+}