feat: add pdf-to-docx-swift converter Closes #18

Co-Authored-By: kiki830621 <kiki830621@gmail.com>

Author: PsychQuantClaw

.gitignore

@@ -5,6 +5,7 @@ DerivedData/
 
 # Package resolved (optional - can include or exclude)
 # Package.resolved
+packages/*/Package.resolved
 
 # Xcode
 *.xcodeproj
@@ -18,7 +19,7 @@ xcuserdata/
 *.code-workspace
 
 # Local packages & MCP (separate git repos)
-packages/
+packages/*
 !packages/srt-to-html-swift/
 !packages/srt-to-html-swift/Package.swift
 !packages/srt-to-html-swift/Sources/
@@ -43,6 +44,15 @@ packages/
 !packages/html-to-md-swift/Tests/
 !packages/html-to-md-swift/Tests/HTMLToMDSwiftTests/
 !packages/html-to-md-swift/Tests/HTMLToMDSwiftTests/HTMLConverterTests.swift
+!packages/pdf-to-docx-swift/
+!packages/pdf-to-docx-swift/Package.swift
+!packages/pdf-to-docx-swift/README.md
+!packages/pdf-to-docx-swift/Sources/
+!packages/pdf-to-docx-swift/Sources/PDFToDOCXSwift/
+!packages/pdf-to-docx-swift/Sources/PDFToDOCXSwift/PDFToDOCXConverter.swift
+!packages/pdf-to-docx-swift/Tests/
+!packages/pdf-to-docx-swift/Tests/PDFToDOCXSwiftTests/
+!packages/pdf-to-docx-swift/Tests/PDFToDOCXSwiftTests/PDFToDOCXConverterTests.swift
 mcp/
 
 # Temp files

CONVERSIONS.md

@@ -17,7 +17,7 @@
 | **Markdown** | — | ✅ `md-to-html` | 🔬 `md-to-word` | · | · | · | · |
 | **HTML** | ✅ `html-to-md` | — | 📋 `html-to-word` | · | · | · | · |
 | **Word (.docx)** | ✅ `word-to-md` | 📋 `word-to-html` | — | · | · | · | · |
-| **PDF** | 📋 `pdf-to-md` | · | · | ✅ `pdf-to-latex` | · | — | · |
+| **PDF** | 📋 `pdf-to-md` | · | 🔄 `pdf-to-docx` | ✅ `pdf-to-latex` | · | — | · |
 | **BibLaTeX (.bib)** | ✅ `bib-apa-to-md` | ✅ `bib-apa-to-html` | · | · | ✅ `bib-apa-to-json` | · | · |
 | **SRT** | · | ✅ `srt-to-html` | · | · | · | · | — |
 
@@ -34,6 +34,7 @@
 | BibLaTeX → APA Markdown | `bib-apa-to-md-swift` | ✅ implemented | style-aware renderer |
 | BibLaTeX → APA JSON | `bib-apa-to-json-swift` | ✅ implemented | pre-rendered HTML + anchors |
 | PDF → Markdown | `pdf-to-md-swift` | 📋 planned | direct path, avoid hub loss through LaTeX |
+| PDF → Word (.docx) | `pdf-to-docx-swift` | 🔄 active | direct editable export with headings / lists / tables / page breaks |
 | Word → HTML | `word-to-html-swift` | 📋 planned | direct path preserves Word semantics |
 | HTML → Word | `html-to-word-swift` | 📋 planned | reverse path after word-to-html |
 | Markdown → Word | `md-to-word-swift` | 🔬 research | binary target + protocol shape need design |
@@ -43,6 +44,7 @@
 | Priority | Converter | Status | Why now |
 |---------:|-----------|--------|---------|
 | P1 | `pdf-to-md-swift` | 📋 planned | direct markdown export is a natural companion to existing PDF parsing stack |
+| P1 | `pdf-to-docx-swift` | 🔄 active | editable Word output is now architecturally straightforward via OOXML writer path |
 | P1 | `word-to-html-swift` | 📋 planned | direct conversion avoids Markdown hub loss for rich Word semantics |
 | P2 | `html-to-word-swift` | 📋 planned | reverse path once Word↔HTML design stabilizes |
 | P3 | `md-to-word-swift` | 🔬 research | requires target-binary converter story beyond current text-streaming protocol |

Package.swift

@@ -15,6 +15,7 @@ let package = Package(
         .package(url: "https://github.com/PsychQuant/markdown-swift.git", from: "0.1.0"),
         .package(url: "https://github.com/PsychQuant/marker-swift.git", from: "0.1.0"),
         .package(name: "pdf-to-latex-swift", path: "packages/pdf-to-latex-swift"),
+        .package(name: "PDFToDOCXSwift", path: "packages/pdf-to-docx-swift"),
         .package(name: "HTMLToMDSwift", path: "packages/html-to-md-swift"),
         .package(name: "MDToHTMLSwift", path: "packages/md-to-html-swift"),
         .package(name: "SRTToHTMLSwift", path: "packages/srt-to-html-swift"),
@@ -41,6 +42,7 @@ let package = Package(
                 .product(name: "MDToHTMLSwift", package: "MDToHTMLSwift"),
                 .product(name: "SRTToHTMLSwift", package: "SRTToHTMLSwift"),
                 "MarkerWordConverter",
+                .product(name: "PDFToDOCXSwift", package: "PDFToDOCXSwift"),
                 .product(name: "PDFToLaTeXCore", package: "pdf-to-latex-swift"),
                 .product(name: "BibAPAToHTML", package: "BibAPAToHTML"),
                 .product(name: "BibAPAToJSON", package: "BibAPAToJSON"),

Sources/MacDocCLI/MacDoc+PDF.swift

@@ -9,8 +9,9 @@ extension MacDoc {
     struct PDF: AsyncParsableCommand {
         static let configuration = CommandConfiguration(
             commandName: "pdf",
-            abstract: "PDF 轉 LaTeX 工具（多步驟 pipeline）",
+            abstract: "PDF 工具（直接轉 DOCX + PDF→LaTeX pipeline）",
             subcommands: [
+                ToDOCX.self,
                 Init.self,
                 Segment.self,
                 Render.self,

Sources/MacDocCLI/MacDoc+PDFToDOCX.swift

@@ -0,0 +1,44 @@
+import ArgumentParser
+import Foundation
+import CommonConverterSwift
+import PDFToDOCXSwift
+
+// MARK: - pdf to-docx
+extension MacDoc.PDF {
+    struct ToDOCX: AsyncParsableCommand {
+        static let configuration = CommandConfiguration(
+            commandName: "to-docx",
+            abstract: "將 PDF (.pdf) 直接轉換為 Word (.docx)"
+        )
+
+        @Argument(help: "輸入 .pdf 檔案路徑")
+        var input: String
+
+        @Option(name: [.short, .long], help: "輸出 .docx 檔案路徑（預設為與輸入同名）")
+        var output: String?
+
+        @Flag(name: .long, help: "保留 PDF 段內換行為 Word line break")
+        var hardBreaks: Bool = false
+
+        mutating func run() async throws {
+            let inputURL = URL(fileURLWithPath: input)
+            guard FileManager.default.fileExists(atPath: inputURL.path) else {
+                throw ValidationError("找不到輸入檔案: \(input)")
+            }
+
+            var options = ConversionOptions.default
+            options.hardLineBreaks = hardBreaks
+
+            let outputURL = resolvedOutputURL(for: inputURL)
+            try PDFToDOCXConverter().convertToFile(input: inputURL, output: outputURL, options: options)
+            print("已寫入: \(outputURL.path)")
+        }
+
+        private func resolvedOutputURL(for inputURL: URL) -> URL {
+            if let output {
+                return URL(fileURLWithPath: output)
+            }
+            return inputURL.deletingPathExtension().appendingPathExtension("docx")
+        }
+    }
+}

packages/pdf-to-docx-swift/Package.swift

@@ -0,0 +1,30 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "PDFToDOCXSwift",
+    platforms: [.macOS(.v14)],
+    products: [
+        .library(name: "PDFToDOCXSwift", targets: ["PDFToDOCXSwift"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/PsychQuant/doc-converter-swift.git", from: "0.4.0"),
+        .package(url: "https://github.com/PsychQuant/ooxml-swift.git", from: "0.5.3"),
+    ],
+    targets: [
+        .target(
+            name: "PDFToDOCXSwift",
+            dependencies: [
+                .product(name: "CommonConverterSwift", package: "doc-converter-swift"),
+                .product(name: "OOXMLSwift", package: "ooxml-swift"),
+            ]
+        ),
+        .testTarget(
+            name: "PDFToDOCXSwiftTests",
+            dependencies: [
+                "PDFToDOCXSwift",
+                .product(name: "OOXMLSwift", package: "ooxml-swift"),
+            ]
+        ),
+    ]
+)

packages/pdf-to-docx-swift/README.md

@@ -0,0 +1,53 @@
+# pdf-to-docx-swift
+
+Direct PDF → Word (`.docx`) converter for macdoc.
+
+## What it does
+
+- reads PDF files with `PDFKit`
+- maps detected structure into `OOXMLSwift` `WordDocument`
+- writes full `.docx` archives via `DocxWriter`
+- exposes a streaming `DocumentConverter` surface that emits `word/document.xml`
+
+## Current structure detection
+
+- document metadata (`Title`, `Author`, `Subject`, `Keywords`, creation/modification date)
+- headings (first-page title + short heading-like lines)
+- paragraphs
+- bullet / ordered lists
+- simple tables detected from tabs / multi-space aligned columns / pipe rows
+- page breaks between PDF pages
+
+## Usage
+
+```swift
+import PDFToDOCXSwift
+
+let converter = PDFToDOCXConverter()
+try converter.convertToFile(
+    input: URL(fileURLWithPath: "paper.pdf"),
+    output: URL(fileURLWithPath: "paper.docx")
+)
+```
+
+## CLI
+
+After wiring into `macdoc`:
+
+```bash
+macdoc pdf to-docx input.pdf -o output.docx
+# or let macdoc choose input.docx next to the source PDF
+macdoc pdf to-docx input.pdf
+```
+
+## Testing
+
+```bash
+cd packages/pdf-to-docx-swift
+swift build
+swift test
+```
+
+## Notes
+
+This package prioritizes editable Word output from native PDF text extraction. It does not yet reconstruct embedded images or advanced PDF layout semantics.