@robin7331/papyrus-cli 0.1.1

package/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=your_api_key_here

package/README.md

@@ -0,0 +1,234 @@
+<p align="center">
+  <img src="./assets/header.png" alt="Papyrus CLI logo" width="180" />
+</p>
+
+<h1 align="center">Papyrus CLI</h1>
+
+<p align="center">Convert PDFs into Markdown or plain text with the OpenAI Agents SDK.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@robin7331/papyrus-cli"><img src="https://img.shields.io/npm/v/%40robin7331%2Fpapyrus-cli?logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@robin7331/papyrus-cli"><img src="https://img.shields.io/npm/dm/%40robin7331%2Fpapyrus-cli?logo=npm&label=downloads" alt="npm downloads"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white" alt="node >= 22">
+</p>
+
+## Installation
+
+Run directly with `npx`:
+
+```bash
+npx @robin7331/papyrus-cli --help
+```
+
+Or install globally:
+
+```bash
+npm i -g @robin7331/papyrus-cli
+papyrus --help
+```
+
+## API Key Setup
+
+Papyrus requires `OPENAI_API_KEY`.
+
+macOS/Linux (persistent):
+
+```bash
+echo 'export OPENAI_API_KEY="your_api_key_here"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+PowerShell (persistent):
+
+```powershell
+setx OPENAI_API_KEY "your_api_key_here"
+# restart PowerShell after running setx
+```
+
+One-off execution:
+
+```bash
+OPENAI_API_KEY="your_api_key_here" npx @robin7331/papyrus-cli ./path/to/input.pdf
+```
+
+Security note: Papyrus intentionally does not provide an `--api-key` flag to avoid leaking keys via shell history or process lists.
+
+## Usage
+
+Single file (auto mode):
+
+```bash
+papyrus ./path/to/input.pdf
+```
+
+Single file with explicit format/output/model:
+
+```bash
+papyrus ./path/to/input.pdf --format md --output ./out/result.md --model gpt-4o-mini
+```
+
+Auto mode with extra instructions:
+
+```bash
+papyrus ./path/to/input.pdf --instructions "Prioritize table accuracy." --format txt
+```
+
+Prompt mode (inline prompt):
+
+```bash
+papyrus ./path/to/input.pdf --mode prompt --prompt "Extract all invoice line items as bullet points." --format md
+```
+
+Prompt mode (prompt file):
+
+```bash
+papyrus ./path/to/input.pdf --mode prompt --prompt-file ./my-prompt.txt --format txt
+```
+
+Folder mode (recursive scan, asks for confirmation):
+
+```bash
+papyrus ./path/to/folder
+```
+
+Folder mode with explicit concurrency and output directory:
+
+```bash
+papyrus ./path/to/folder --concurrency 4 --output ./out
+```
+
+Folder mode without confirmation prompt:
+
+```bash
+papyrus ./path/to/folder --yes
+```
+
+`npx` alternative for any command:
+
+```bash
+npx @robin7331/papyrus-cli ./path/to/input.pdf --mode auto
+```
+
+## Arguments Reference
+
+### `<input>`
+
+Path to a single PDF file or a folder containing PDFs (processed recursively).
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf
+```
+
+### `--format <format>`
+
+Output format override:
+- `md` for GitHub-flavored Markdown
+- `txt` for plain text
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf --format md
+```
+
+### `-o, --output <path>`
+
+Output destination.
+- Single file input: output file path.
+- Folder input: output directory path (folder structure is mirrored).
+
+Example:
+
+```bash
+papyrus ./docs --output ./converted
+```
+
+### `--mode <mode>`
+
+Conversion mode:
+- `auto` (default): built-in conversion behavior.
+- `prompt`: use your own prompt via `--prompt` or `--prompt-file`.
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf --mode prompt --prompt "Extract all line items."
+```
+
+### `--instructions <text>`
+
+Additional conversion instructions in `auto` mode only.
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf --mode auto --instructions "Keep table columns aligned."
+```
+
+### `--prompt <text>`
+
+Inline prompt text for `prompt` mode. Must be non-empty. In `prompt` mode, use exactly one of `--prompt` or `--prompt-file`.
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf --mode prompt --prompt "Summarize payment terms."
+```
+
+### `--prompt-file <path>`
+
+Path to a text file containing the prompt for `prompt` mode. File must contain non-empty text. In `prompt` mode, use exactly one of `--prompt` or `--prompt-file`.
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf --mode prompt --prompt-file ./my-prompt.txt
+```
+
+### `-m, --model <model>`
+
+OpenAI model name used for conversion. Default is `gpt-4o-mini`.
+
+Example:
+
+```bash
+papyrus ./docs/invoice.pdf --model gpt-4.1-mini
+```
+
+### `--concurrency <n>`
+
+Maximum parallel workers for folder input. Must be an integer between `1` and `100`. Default is `10`.
+
+Example:
+
+```bash
+papyrus ./docs --concurrency 4
+```
+
+### `-y, --yes`
+
+Skips the interactive folder confirmation prompt.
+
+Example:
+
+```bash
+papyrus ./docs --yes
+```
+
+## Notes
+
+- In `auto` mode without `--format`, the model returns structured JSON with `format` + `content`.
+- Folder input is scanned recursively for `.pdf` files and processed in parallel.
+- In folder mode, `--output` must be a directory path and mirrored subfolders are preserved.
+- For scanned PDFs, output quality depends on OCR quality from the model.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev -- ./path/to/input.pdf
+npm test
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/cli.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { Command } from "commander";
+import { convertPdf } from "./openaiPdfToMarkdown.js";
+import { defaultOutputPath, formatDurationMs, isPdfPath, looksLikeFileOutput, parseConcurrency, parseFormat, parseMode, resolveFolderOutputPath, truncate, validateOptionCombination } from "./cliHelpers.js";
+const program = new Command();
+program
+    .name("papyrus")
+    .description("Convert PDF files to Markdown or text using the OpenAI Agents SDK")
+    .argument("<input>", "Path to input PDF file or folder")
+    .option("-o, --output <path>", "Path to output file (single input) or output directory (folder input)")
+    .option("-m, --model <model>", "OpenAI model to use", "gpt-4o-mini")
+    .option("--concurrency <n>", "Max parallel workers for folder input (default: 10)", parseConcurrency)
+    .option("-y, --yes", "Skip confirmation prompt in folder mode")
+    .option("--mode <mode>", "Conversion mode: auto or prompt", parseMode, "auto")
+    .option("--format <format>", "Output format override: md or txt", parseFormat)
+    .option("--instructions <text>", "Additional conversion instructions for auto mode")
+    .option("--prompt <text>", "Custom prompt text for prompt mode")
+    .option("--prompt-file <path>", "Path to file containing prompt text for prompt mode")
+    .action(async (input, options) => {
+    const inputPath = resolve(input);
+    const startedAt = Date.now();
+    try {
+        validateOptionCombination(options);
+        const promptText = await resolvePromptText(options);
+        const inputKind = await detectInputKind(inputPath);
+        let usageTotals = emptyUsage();
+        if (inputKind === "file") {
+            usageTotals = await processSingleFile(inputPath, options, promptText);
+        }
+        else {
+            const summary = await processFolder(inputPath, options, promptText);
+            usageTotals = summary.usage;
+            if (!summary.cancelled && summary.failed > 0) {
+                process.exitCode = 1;
+            }
+        }
+        printUsageTotals(usageTotals);
+        console.log(`Duration: ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Conversion failed: ${message}`);
+        console.error(`Duration: ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
+        process.exitCode = 1;
+    }
+});
+program.parseAsync(process.argv);
+async function processSingleFile(inputPath, options, promptText) {
+    if (!isPdfPath(inputPath)) {
+        throw new Error("Input file must have a .pdf extension.");
+    }
+    const result = await convertPdf({
+        inputPath,
+        model: options.model,
+        mode: options.mode,
+        format: options.format,
+        instructions: options.instructions,
+        promptText
+    });
+    const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, result.content, "utf8");
+    console.log(`Output (${result.format}) written to: ${outputPath}`);
+    return result.usage;
+}
+async function processFolder(inputDir, options, promptText) {
+    if (options.output && looksLikeFileOutput(options.output)) {
+        throw new Error("In folder mode, --output must be a directory path (not a .md/.txt file path).");
+    }
+    const files = await collectPdfFiles(inputDir);
+    if (files.length === 0) {
+        throw new Error(`No PDF files found in directory: ${inputDir}`);
+    }
+    const concurrency = options.concurrency ?? 10;
+    const shouldProceed = await confirmFolderProcessing(files.length, concurrency, Boolean(options.yes));
+    if (!shouldProceed) {
+        console.log("Cancelled. No files were processed.");
+        return { total: files.length, succeeded: 0, failed: 0, cancelled: true, usage: emptyUsage() };
+    }
+    const outputRoot = options.output ? resolve(options.output) : undefined;
+    let succeeded = 0;
+    let failed = 0;
+    let completed = 0;
+    const usage = emptyUsage();
+    const failures = [];
+    const workerCount = Math.min(concurrency, files.length);
+    console.log(`Found ${files.length} PDF file(s). Using concurrency: ${concurrency}`);
+    const workerDashboard = process.stdout.isTTY
+        ? new AsciiWorkerDashboard(files.length, workerCount)
+        : null;
+    workerDashboard?.setSummary(completed, failed);
+    try {
+        await runWithConcurrency(files, concurrency, async (filePath, _index, workerId) => {
+            const relativeInput = relative(inputDir, filePath);
+            const startedAt = Date.now();
+            workerDashboard?.setWorkerRunning(workerId, relativeInput);
+            try {
+                const result = await convertPdf({
+                    inputPath: filePath,
+                    model: options.model,
+                    mode: options.mode,
+                    format: options.format,
+                    instructions: options.instructions,
+                    promptText
+                });
+                const outputPath = resolveFolderOutputPath(filePath, inputDir, outputRoot, result.format);
+                await mkdir(dirname(outputPath), { recursive: true });
+                await writeFile(outputPath, result.content, "utf8");
+                succeeded += 1;
+                mergeUsage(usage, result.usage);
+                if (workerDashboard) {
+                    workerDashboard.setWorkerDone(workerId, relativeInput, `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`);
+                }
+                else {
+                    console.log(`[worker-${workerId + 1}] Done ${relativeInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`);
+                }
+            }
+            catch (error) {
+                failed += 1;
+                const message = error instanceof Error ? error.message : String(error);
+                failures.push({
+                    file: relativeInput,
+                    message
+                });
+                if (workerDashboard) {
+                    workerDashboard.setWorkerFailed(workerId, relativeInput, `${truncate(message, 42)} (${formatDurationMs(Date.now() - startedAt)})`);
+                }
+                else {
+                    console.error(`[worker-${workerId + 1}] Failed ${relativeInput}: ${message} (${formatDurationMs(Date.now() - startedAt)})`);
+                }
+            }
+            finally {
+                completed += 1;
+                workerDashboard?.setSummary(completed, failed);
+            }
+        });
+    }
+    finally {
+        workerDashboard?.stop();
+    }
+    console.log(`Summary: total=${files.length}, succeeded=${succeeded}, failed=${failed}`);
+    if (failures.length > 0) {
+        console.error("Failures:");
+        for (const failure of failures) {
+            console.error(`- ${failure.file}: ${failure.message}`);
+        }
+    }
+    return { total: files.length, succeeded, failed, cancelled: false, usage };
+}
+async function resolvePromptText(options) {
+    if (options.mode !== "prompt") {
+        return undefined;
+    }
+    if (options.prompt) {
+        const prompt = options.prompt.trim();
+        if (!prompt) {
+            throw new Error("--prompt cannot be empty.");
+        }
+        return prompt;
+    }
+    if (!options.promptFile) {
+        return undefined;
+    }
+    const promptPath = resolve(options.promptFile);
+    const promptFromFile = (await readFile(promptPath, "utf8")).trim();
+    if (!promptFromFile) {
+        throw new Error("--prompt-file must contain non-empty text.");
+    }
+    return promptFromFile;
+}
+async function detectInputKind(inputPath) {
+    const metadata = await stat(inputPath);
+    if (metadata.isFile()) {
+        return "file";
+    }
+    if (metadata.isDirectory()) {
+        return "directory";
+    }
+    throw new Error("Input path must be a PDF file or directory.");
+}
+async function collectPdfFiles(rootDir) {
+    const collected = [];
+    await walkDirectory(rootDir, collected);
+    return collected;
+}
+async function walkDirectory(currentDir, collected) {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name, "en", { sensitivity: "base" }));
+    for (const entry of entries) {
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        const fullPath = join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            await walkDirectory(fullPath, collected);
+            continue;
+        }
+        if (entry.isFile() && isPdfPath(entry.name)) {
+            collected.push(fullPath);
+        }
+    }
+}
+async function runWithConcurrency(items, concurrency, worker) {
+    const maxWorkers = Math.min(concurrency, items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: maxWorkers }, async (_, workerId) => {
+        while (true) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            if (currentIndex >= items.length) {
+                return;
+            }
+            await worker(items[currentIndex], currentIndex, workerId);
+        }
+    });
+    await Promise.all(workers);
+}
+const SPINNER_FRAMES = ["-", "\\", "|", "/"];
+class AsciiWorkerDashboard {
+    lanes;
+    total;
+    workerCount;
+    spinnerTimer;
+    completed = 0;
+    failed = 0;
+    renderedLineCount = 0;
+    constructor(total, workerCount) {
+        this.total = total;
+        this.workerCount = workerCount;
+        this.lanes = Array.from({ length: workerCount }, () => ({
+            state: "idle",
+            spinnerFrame: 0
+        }));
+        process.stdout.write("\x1b[?25l");
+        this.render();
+        this.spinnerTimer = setInterval(() => {
+            this.tickSpinners();
+            this.render();
+        }, 100);
+    }
+    setSummary(completed, failed) {
+        this.completed = completed;
+        this.failed = failed;
+        this.render();
+    }
+    setWorkerRunning(workerId, file) {
+        const lane = this.lanes[workerId];
+        if (!lane) {
+            return;
+        }
+        lane.state = "running";
+        lane.file = file;
+        lane.message = "processing";
+        this.render();
+    }
+    setWorkerDone(workerId, file, message) {
+        const lane = this.lanes[workerId];
+        if (!lane) {
+            return;
+        }
+        lane.state = "done";
+        lane.file = file;
+        lane.message = message;
+        this.render();
+    }
+    setWorkerFailed(workerId, file, message) {
+        const lane = this.lanes[workerId];
+        if (!lane) {
+            return;
+        }
+        lane.state = "failed";
+        lane.file = file;
+        lane.message = message;
+        this.render();
+    }
+    stop() {
+        clearInterval(this.spinnerTimer);
+        this.render();
+        process.stdout.write("\x1b[?25h");
+    }
+    render() {
+        const lines = this.composeLines();
+        if (this.renderedLineCount > 0) {
+            process.stdout.write(`\x1b[${this.renderedLineCount}F`);
+        }
+        for (const line of lines) {
+            process.stdout.write(`\x1b[2K${line}\n`);
+        }
+        this.renderedLineCount = lines.length;
+    }
+    composeLines() {
+        const active = this.lanes.filter((lane) => lane.state === "running").length;
+        const lines = [
+            `Progress: ${this.completed}/${this.total} complete | active ${active}/${this.workerCount} | failed ${this.failed}`
+        ];
+        for (let index = 0; index < this.lanes.length; index += 1) {
+            const lane = this.lanes[index];
+            const label = `worker-${String(index + 1).padStart(2, "0")}`;
+            const icon = this.renderIcon(lane);
+            const file = truncate(lane.file ?? "idle", 64);
+            const message = lane.message ? ` | ${lane.message}` : "";
+            lines.push(`${icon} ${label} | ${file}${message}`);
+        }
+        return lines;
+    }
+    tickSpinners() {
+        for (const lane of this.lanes) {
+            if (lane.state !== "running") {
+                continue;
+            }
+            lane.spinnerFrame = (lane.spinnerFrame + 1) % SPINNER_FRAMES.length;
+        }
+    }
+    renderIcon(lane) {
+        if (lane.state === "running") {
+            return SPINNER_FRAMES[lane.spinnerFrame];
+        }
+        if (lane.state === "done") {
+            return "OK";
+        }
+        if (lane.state === "failed") {
+            return "!!";
+        }
+        return "..";
+    }
+}
+async function confirmFolderProcessing(totalFiles, concurrency, skipPrompt) {
+    if (skipPrompt) {
+        return true;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Folder mode requires an interactive terminal confirmation. Use --yes to skip the prompt.");
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    try {
+        const answer = (await rl.question(`Process ${totalFiles} PDF file(s) with concurrency ${concurrency}? [Y/n] `)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function emptyUsage() {
+    return {
+        requests: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0
+    };
+}
+function mergeUsage(target, delta) {
+    target.requests += delta.requests;
+    target.inputTokens += delta.inputTokens;
+    target.outputTokens += delta.outputTokens;
+    target.totalTokens += delta.totalTokens;
+}
+function printUsageTotals(usage) {
+    console.log(`Token usage: input=${usage.inputTokens}, output=${usage.outputTokens}, total=${usage.totalTokens}, requests=${usage.requests}`);
+}

package/dist/cliHelpers.d.ts

@@ -0,0 +1,22 @@
+import { type ConversionMode, type OutputFormat } from "./openaiPdfToMarkdown.js";
+export type CliOptions = {
+    output?: string;
+    model: string;
+    concurrency?: number;
+    yes?: boolean;
+    mode: ConversionMode;
+    format?: OutputFormat;
+    instructions?: string;
+    prompt?: string;
+    promptFile?: string;
+};
+export declare function parseMode(value: string): ConversionMode;
+export declare function parseFormat(value: string): OutputFormat;
+export declare function parseConcurrency(value: string): number;
+export declare function validateOptionCombination(options: CliOptions): void;
+export declare function defaultOutputPath(inputPath: string, format: OutputFormat): string;
+export declare function resolveFolderOutputPath(inputPath: string, inputRoot: string, outputRoot: string | undefined, format: OutputFormat): string;
+export declare function isPdfPath(inputPath: string): boolean;
+export declare function looksLikeFileOutput(outputPath: string): boolean;
+export declare function truncate(value: string, maxLength: number): string;
+export declare function formatDurationMs(durationMs: number): string;