opencode-froggy 0.7.2 → 0.8.0

package/README.md

@@ -7,7 +7,7 @@
   <a href="https://www.npmjs.com/package/opencode-froggy"><img src="https://badge.fury.io/js/opencode-froggy.svg" alt="npm version"></a>
 </p>
 
-OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubber-duck, partner, code-reviewer, code-simplifier), skills (code-release), and tools (gitingest, blockchain queries, agent-promote).
+OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubber-duck, partner, code-reviewer, code-simplifier), skills (code-release), and tools (gitingest, pdf-to-markdown, blockchain queries, agent-promote).
 
 ---
 
@@ -22,6 +22,7 @@ OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubb
   - [gitingest](#gitingest)
   - [prompt-session](#prompt-session)
   - [list-child-sessions](#list-child-sessions)
+  - [pdf-to-markdown](#pdf-to-markdown)
   - [agent-promote](#agent-promote)
   - [Blockchain](#blockchain)
     - [Configuration](#configuration)
@@ -245,6 +246,37 @@ Child sessions (2):
 
 ---
 
+### pdf-to-markdown
+
+Convert a text-based PDF into enriched Markdown (headings, paragraphs, lists). Returns Markdown as plain text.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `filePath` | `string` | Yes | - | Absolute path to the PDF file to convert |
+| `maxPages` | `number` | No | All pages | Maximum number of pages to convert (positive integer) |
+
+#### Usage Examples
+
+```typescript
+// Convert an entire PDF
+pdfToMarkdown({ filePath: "/path/to/file.pdf" })
+
+// Convert the first 3 pages
+pdfToMarkdown({
+  filePath: "/path/to/file.pdf",
+  maxPages: 3
+})
+```
+
+#### Notes
+
+- The conversion extracts text content; image-only PDFs may return empty output.
+- `maxPages` is capped at the document's total page count.
+
+---
+
 ### agent-promote
 
 Promote an agent to primary (default) or specify a grade.

package/command/doc-changes.md

@@ -26,7 +26,6 @@ Automatically detect documentation files in the project:
 - Look for `README.md` at project root
 - Look for `docs/` or `documentation/` directories
 - Look for other `.md` files that describe usage, API, or features
-- Check if `CHANGELOG.md` exists (do NOT create it if missing)
 
 ## Update Phase
 

package/dist/index.js

@@ -5,7 +5,7 @@ import { getGlobalHookDir, getProjectHookDir } from "./config-paths";
 import { hasCodeExtension } from "./code-files";
 import { log } from "./logger";
 import { executeBashAction, DEFAULT_BASH_TIMEOUT, } from "./bash-executor";
-import { gitingestTool, createPromptSessionTool, createListChildSessionsTool, createAgentPromoteTool, createSkillTool, getPromotedAgents, ethTransactionTool, ethAddressTxsTool, ethAddressBalanceTool, ethTokenTransfersTool, } from "./tools";
+import { gitingestTool, pdfToMarkdownTool, createPromptSessionTool, createListChildSessionsTool, createAgentPromoteTool, createSkillTool, getPromotedAgents, ethTransactionTool, ethAddressTxsTool, ethAddressBalanceTool, ethTokenTransfersTool, } from "./tools";
 export { parseFrontmatter, loadAgents, loadCommands } from "./loaders";
 export { buildSkillActivationBlock } from "./skill-activation";
 import { buildSkillActivationBlock } from "./skill-activation";
@@ -46,6 +46,7 @@ const SmartfrogPlugin = async (ctx) => {
         hooks: Array.from(hooks.keys()),
         tools: [
             "gitingest",
+            "pdf-to-markdown",
             "skill",
             "agent-promote",
             "eth-transaction",
@@ -204,6 +205,7 @@ const SmartfrogPlugin = async (ctx) => {
         },
         tool: {
             gitingest: gitingestTool,
+            "pdf-to-markdown": pdfToMarkdownTool,
             skill: skillTool,
             "prompt-session": createPromptSessionTool(ctx.client),
             "list-child-sessions": createListChildSessionsTool(ctx.client),

package/dist/tools/index.d.ts

@@ -1,4 +1,6 @@
 export { gitingestTool, fetchGitingest, type GitingestArgs } from "./gitingest";
+export { convertPdfToMarkdown, type PdfToMarkdownArgs } from "./pdf-to-markdown-core";
+export { pdfToMarkdownTool } from "./pdf-to-markdown";
 export { createPromptSessionTool, type PromptSessionArgs } from "./prompt-session";
 export { createListChildSessionsTool } from "./list-child-sessions";
 export { createAgentPromoteTool, getPromotedAgents, type AgentPromoteArgs } from "./agent-promote";

package/dist/tools/index.js

@@ -1,4 +1,6 @@
 export { gitingestTool, fetchGitingest } from "./gitingest";
+export { convertPdfToMarkdown } from "./pdf-to-markdown-core";
+export { pdfToMarkdownTool } from "./pdf-to-markdown";
 export { createPromptSessionTool } from "./prompt-session";
 export { createListChildSessionsTool } from "./list-child-sessions";
 export { createAgentPromoteTool, getPromotedAgents } from "./agent-promote";

package/dist/tools/pdf-to-markdown-core.d.ts

@@ -0,0 +1,9 @@
+export interface PdfToMarkdownArgs {
+    filePath: string;
+    maxPages?: number;
+}
+interface MarkdownOptions {
+    maxPages?: number;
+}
+export declare function convertPdfToMarkdown(filePath: string, options?: MarkdownOptions): Promise<string>;
+export {};

package/dist/tools/pdf-to-markdown-core.js

@@ -0,0 +1,179 @@
+import { readFile } from "node:fs/promises";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+function isTextItem(item) {
+    return "str" in item;
+}
+function getFontSize(item) {
+    if (typeof item.height === "number" && item.height > 0) {
+        return item.height;
+    }
+    const [a, b] = item.transform;
+    const size = Math.hypot(a, b);
+    return size > 0 ? size : 0;
+}
+function mergeLineText(previous, next) {
+    if (previous.endsWith("-") && !previous.endsWith(" -")) {
+        return `${previous.slice(0, -1)}${next}`;
+    }
+    if (/[\s-]$/.test(previous) || /^[,.;:!?)]/.test(next)) {
+        return `${previous}${next}`;
+    }
+    return `${previous} ${next}`;
+}
+function groupTextLines(items) {
+    const sorted = [...items].sort((a, b) => {
+        const yDiff = b.transform[5] - a.transform[5];
+        if (Math.abs(yDiff) > 0.1)
+            return yDiff;
+        return a.transform[4] - b.transform[4];
+    });
+    const lines = [];
+    for (const item of sorted) {
+        const text = item.str.trim();
+        if (!text)
+            continue;
+        const y = item.transform[5];
+        const x = item.transform[4];
+        const fontSize = getFontSize(item);
+        const lastLine = lines[lines.length - 1];
+        if (lastLine) {
+            const tolerance = Math.max(2, Math.min(lastLine.fontSize, fontSize) * 0.5);
+            if (Math.abs(lastLine.y - y) <= tolerance) {
+                lastLine.text = mergeLineText(lastLine.text, text);
+                lastLine.fontSize = Math.max(lastLine.fontSize, fontSize);
+                continue;
+            }
+        }
+        lines.push({ text, y, x, fontSize });
+    }
+    return lines;
+}
+function getHeadingLevel(fontSize, maxFontSize, bodyFontSize) {
+    if (maxFontSize === 0)
+        return null;
+    if (fontSize < bodyFontSize * 1.2)
+        return null;
+    const ratio = fontSize / maxFontSize;
+    if (ratio >= 0.85)
+        return 1;
+    if (ratio >= 0.7)
+        return 2;
+    if (ratio >= 0.6)
+        return 3;
+    return null;
+}
+function getBodyFontSize(lines) {
+    const counts = new Map();
+    for (const line of lines) {
+        const rounded = Math.round(line.fontSize * 10) / 10;
+        counts.set(rounded, (counts.get(rounded) ?? 0) + 1);
+    }
+    let bestSize = 0;
+    let bestCount = 0;
+    for (const [size, count] of counts) {
+        if (count > bestCount || (count === bestCount && size < bestSize)) {
+            bestSize = size;
+            bestCount = count;
+        }
+    }
+    return bestSize || Math.max(...lines.map(line => line.fontSize));
+}
+function formatListItem(text) {
+    const trimmed = text.trim();
+    const match = /^([*\-]|\u2022|\d+\.)\s+(.*)$/.exec(trimmed);
+    if (!match)
+        return null;
+    return `- ${match[2].trim()}`;
+}
+function shouldMergeLines(previous, next) {
+    if (next.y > previous.y)
+        return false;
+    const gap = previous.y - next.y;
+    const fontSize = previous.fontSize || next.fontSize;
+    const gapThreshold = Math.max(4, fontSize * 1.6);
+    const fontDelta = Math.abs(previous.fontSize - next.fontSize);
+    if (fontDelta > fontSize * 0.4)
+        return false;
+    return gap <= gapThreshold;
+}
+function linesToMarkdown(lines) {
+    if (lines.length === 0)
+        return [];
+    const maxFontSize = Math.max(...lines.map(line => line.fontSize));
+    const bodyFontSize = getBodyFontSize(lines);
+    const output = [];
+    let currentParagraph = null;
+    let lastLine = null;
+    const flushParagraph = () => {
+        if (currentParagraph) {
+            output.push(currentParagraph, "");
+            currentParagraph = null;
+        }
+    };
+    for (const line of lines) {
+        const text = line.text.replace(/\s+/g, " ").trim();
+        if (!text)
+            continue;
+        const headingLevel = getHeadingLevel(line.fontSize, maxFontSize, bodyFontSize);
+        const listItem = formatListItem(text);
+        if (headingLevel) {
+            flushParagraph();
+            output.push(`${"#".repeat(headingLevel)} ${text}`, "");
+            lastLine = line;
+            continue;
+        }
+        if (listItem) {
+            flushParagraph();
+            output.push(listItem, "");
+            lastLine = line;
+            continue;
+        }
+        if (currentParagraph && lastLine && shouldMergeLines(lastLine, line)) {
+            currentParagraph = `${currentParagraph} ${text}`;
+        }
+        else {
+            flushParagraph();
+            currentParagraph = text;
+        }
+        lastLine = line;
+    }
+    flushParagraph();
+    while (output.length > 0 && output[output.length - 1].trim() === "") {
+        output.pop();
+    }
+    return output;
+}
+export async function convertPdfToMarkdown(filePath, options = {}) {
+    let data;
+    try {
+        const buffer = await readFile(filePath);
+        data = new Uint8Array(buffer);
+    }
+    catch (error) {
+        throw new Error(`Failed to read PDF at ${filePath}: ${String(error)}`);
+    }
+    const loadingTask = getDocument({ data });
+    const pdf = await loadingTask.promise;
+    const totalPages = pdf.numPages;
+    const maxPages = options.maxPages && options.maxPages > 0
+        ? Math.min(options.maxPages, totalPages)
+        : totalPages;
+    const markdownLines = [];
+    for (let pageNumber = 1; pageNumber <= maxPages; pageNumber += 1) {
+        const page = await pdf.getPage(pageNumber);
+        const textContent = await page.getTextContent({ normalizeWhitespace: true });
+        const items = textContent.items.filter(isTextItem);
+        const lines = groupTextLines(items);
+        const pageMarkdown = linesToMarkdown(lines);
+        if (pageMarkdown.length > 0) {
+            if (markdownLines.length > 0) {
+                markdownLines.push("");
+            }
+            markdownLines.push(...pageMarkdown);
+        }
+    }
+    while (markdownLines.length > 0 && markdownLines[markdownLines.length - 1].trim() === "") {
+        markdownLines.pop();
+    }
+    return markdownLines.join("\n");
+}

package/dist/tools/pdf-to-markdown.d.ts

@@ -0,0 +1,12 @@
+import { type ToolContext } from "@opencode-ai/plugin";
+export declare const pdfToMarkdownTool: {
+    description: string;
+    args: {
+        filePath: import("zod").ZodString;
+        maxPages: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        filePath: string;
+        maxPages?: number | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/pdf-to-markdown.js

@@ -0,0 +1,17 @@
+import { tool } from "@opencode-ai/plugin";
+import { convertPdfToMarkdown } from "./pdf-to-markdown-core";
+export const pdfToMarkdownTool = tool({
+    description: "Convert a text-based PDF into enriched Markdown (headings, paragraphs, lists). Returns Markdown as plain text.",
+    args: {
+        filePath: tool.schema.string().describe("Absolute path to the PDF file to convert"),
+        maxPages: tool.schema
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Limit the number of pages to convert"),
+    },
+    async execute(args, _context) {
+        return convertPdfToMarkdown(args.filePath, { maxPages: args.maxPages });
+    },
+});

package/dist/tools/pdf-to-markdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/pdf-to-markdown.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { convertPdfToMarkdown } from "./pdf-to-markdown-core";
+function escapePdfText(text) {
+    return text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+}
+function buildPdf(lines) {
+    const header = "%PDF-1.4\n%\xFF\xFF\xFF\xFF\n";
+    const objects = [];
+    objects.push("1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
+    objects.push("2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n");
+    objects.push("3 0 obj\n" +
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] " +
+        "/Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>\n" +
+        "endobj\n");
+    objects.push("4 0 obj\n<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>\nendobj\n");
+    const textCommands = lines
+        .map(line => {
+        const escaped = escapePdfText(line.text);
+        return `/F1 ${line.fontSize} Tf 1 0 0 1 ${line.x} ${line.y} Tm (${escaped}) Tj`;
+    })
+        .join("\n");
+    const stream = `BT\n${textCommands}\nET`;
+    const streamLength = Buffer.byteLength(stream, "utf-8");
+    objects.push(`5 0 obj\n<< /Length ${streamLength} >>\nstream\n${stream}\nendstream\nendobj\n`);
+    const offsets = [0];
+    let currentOffset = Buffer.byteLength(header, "utf-8");
+    for (const obj of objects) {
+        offsets.push(currentOffset);
+        currentOffset += Buffer.byteLength(obj, "utf-8");
+    }
+    const xrefOffset = currentOffset;
+    const xrefLines = ["xref", `0 ${objects.length + 1}`, "0000000000 65535 f "];
+    for (let i = 1; i < offsets.length; i += 1) {
+        xrefLines.push(`${String(offsets[i]).padStart(10, "0")} 00000 n `);
+    }
+    const xref = `${xrefLines.join("\n")}\n`;
+    const trailer = "trailer\n" +
+        `<< /Size ${objects.length + 1} /Root 1 0 R >>\n` +
+        "startxref\n" +
+        `${xrefOffset}\n` +
+        "%%EOF\n";
+    const pdfContent = [header, ...objects, xref, trailer].join("");
+    return Buffer.from(pdfContent, "binary");
+}
+async function withTempPdf(lines, run) {
+    const dir = await mkdtemp(join(tmpdir(), "pdf-md-"));
+    const filePath = join(dir, "sample.pdf");
+    try {
+        await writeFile(filePath, buildPdf(lines));
+        await run(filePath);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+describe("pdf-to-markdown", () => {
+    it("renders headings based on font size", async () => {
+        await withTempPdf([
+            { text: "Title", fontSize: 24, x: 100, y: 700 },
+            { text: "Body text", fontSize: 12, x: 100, y: 660 },
+        ], async (filePath) => {
+            const markdown = await convertPdfToMarkdown(filePath);
+            expect(markdown).toContain("# Title");
+        });
+    });
+    it("merges nearby lines into a paragraph", async () => {
+        await withTempPdf([
+            { text: "First line", fontSize: 12, x: 100, y: 700 },
+            { text: "Second line", fontSize: 12, x: 100, y: 684 },
+        ], async (filePath) => {
+            const markdown = await convertPdfToMarkdown(filePath);
+            expect(markdown).toContain("First line Second line");
+        });
+    });
+    it("formats bullet markers as list items", async () => {
+        await withTempPdf([{ text: "- Bullet item", fontSize: 12, x: 100, y: 700 }], async (filePath) => {
+            const markdown = await convertPdfToMarkdown(filePath);
+            expect(markdown).toContain("- Bullet item");
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-froggy",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "OpenCode plugin with a hook layer (tool.before.*, session.idle...), agents (code-reviewer, doc-writer), and commands (/review-pr, /commit)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,12 +39,14 @@
   },
   "dependencies": {
     "js-yaml": "^4.1.0",
+    "pdfjs-dist": "^4.8.69",
     "viem": "^2.44.1"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "latest",
     "@types/bun": "latest",
     "@types/js-yaml": "^4.0.9",
+    "@vitest/coverage-v8": "^4.0.17",
     "typescript": "^5.7.0",
     "vitest": "^4.0.16"
   },