hwp2md 1.0.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Jaechan Kim<kjc0210@gmail.com>
+
+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,174 @@
+# hwp2md
+
+Node.js 및 브라우저용 HWP/HWPX to Markdown 변환기.
+
+한글(HWP 5.0 및 HWPX) 파일을 LLM에 최적화된 깔끔한 Markdown으로 변환합니다.
+
+## 주요 기능
+
+- ✅ HWP 5.0 및 HWPX 파일에서 텍스트 추출
+- ✅ HWPX (ZIP+XML) 형식 지원 (확장자 자동 감지)
+- ✅ 표를 Markdown 형식으로 변환
+- ✅ 문서 구조 보존
+- ✅ 셀 병합 처리 (LLM 최적화를 위한 내용 반복)
+- ✅ Node.js 및 브라우저 환경 지원
+- ✅ TypeScript 타입 정의 포함
+
+## 설치
+
+```bash
+npm install hwp2md
+# 또는
+pnpm add hwp2md
+# 또는
+yarn add hwp2md
+```
+
+## 사용법
+
+### Node.js
+
+```typescript
+import { convert } from "hwp2md";
+
+// HWP 또는 HWPX 변환 (확장자로 자동 감지)
+const markdown = await convert("document.hwp");
+const markdown2 = await convert("document.hwpx");
+console.log(markdown);
+
+// 옵션 지정
+const markdown3 = await convert("document.hwp", {
+  tableLineBreakStyle: "space", // 또는 'br'
+});
+```
+
+### 브라우저
+
+```typescript
+import { convertFromFile } from "hwp2md/browser";
+
+const fileInput = document.getElementById("file") as HTMLInputElement;
+fileInput.addEventListener("change", async (e) => {
+  const file = (e.target as HTMLInputElement).files?.[0];
+  if (file) {
+    const markdown = await convertFromFile(file);
+    console.log(markdown);
+  }
+});
+```
+
+### CLI
+
+```bash
+# 전역 설치
+npm install -g hwp2md
+
+# 파일 정보 표시
+hwp2md info document.hwp
+hwp2md info document.hwpx
+
+# Markdown으로 변환
+hwp2md convert document.hwp output.md
+
+# HWPX 파일 변환 (자동 감지)
+hwp2md convert document.hwpx output.md
+
+# 옵션 지정
+hwp2md convert document.hwp output.md --table-line-breaks br
+```
+
+## API
+
+### `convert(input, options?)`
+
+HWP/HWPX 파일을 Markdown으로 변환합니다 (확장자로 자동 감지).
+
+**파라미터:**
+
+- `input`: 파일 경로 (Node.js, `.hwp` 또는 `.hwpx`), ArrayBuffer, 또는 Uint8Array
+- `options`: 변환 옵션
+  - `tableLineBreakStyle`: `'space'` (기본값) 또는 `'br'`
+
+**반환값:** `Promise<string>` - Markdown 내용
+
+### `convertFromFile(file, options?)` (브라우저 전용)
+
+브라우저 File 객체에서 HWP를 변환합니다.
+
+**파라미터:**
+
+- `file`: input 엘리먼트의 File 객체
+- `options`: 변환 옵션
+
+**반환값:** `Promise<string>` - Markdown 내용
+
+### `HWPFile`
+
+HWP 파일 파싱을 위한 저수준 API입니다.
+
+```typescript
+import { HWPFile } from "hwp2md";
+
+const hwp = await HWPFile.fromFile("document.hwp");
+hwp.open();
+
+console.log(hwp.fileHeader);
+console.log(hwp.getSectionCount());
+
+const sectionData = hwp.readSection(0);
+hwp.close();
+```
+
+### `HWPXFile`
+
+HWPX 파일 파싱을 위한 저수준 API입니다.
+
+```typescript
+import { HWPXFile, convertHwpxToMarkdown } from "hwp2md";
+
+const hwpx = await HWPXFile.fromFile("document.hwpx");
+hwpx.open();
+
+console.log(hwpx.getSectionCount());
+const markdown = convertHwpxToMarkdown(hwpx);
+
+hwpx.close();
+```
+
+## 옵션
+
+### `tableLineBreakStyle`
+
+표 셀 내 줄바꿈 처리 방식:
+
+- `'space'` (기본값): 공백으로 연결 - LLM 처리에 최적화
+- `'br'`: `<br>` 태그 사용 - 가독성 우선
+
+## 제한사항
+
+- **HWP 5.0 및 HWPX 지원** - 이전 HWP 형식(HWP 3.0, HWP 97, HWP 2002 등)은 지원하지 않음
+  - 레거시 HWP 파일은 한컴오피스에서 HWP 5.0 또는 HWPX로 변환 가능
+  - 레거시 형식 감지 시 오류 발생
+- **텍스트 & 표** - 현재 텍스트와 표만 추출하며, 이미지 및 복잡한 개체는 건너뜀
+- **한국어 중심** - 한국어 문서에 최적화 (UTF-16LE 인코딩)
+- **기본 서식만** - 글꼴, 색상, 고급 스타일은 보존하지 않음
+
+## 개발
+
+```bash
+# 의존성 설치
+pnpm install
+
+# 빌드
+pnpm build
+
+# 테스트
+pnpm test
+
+# 타입 체크
+pnpm typecheck
+```
+
+## 라이선스
+
+MIT

package/dist/browser.d.mts

@@ -0,0 +1,179 @@
+//#region src/types.d.ts
+/**
+ * HWP File Header Information
+ */
+interface FileHeader {
+  signature: string;
+  version: string;
+  isCompressed: boolean;
+  isEncrypted: boolean;
+  rawProperties: number;
+}
+/**
+ * Binary Record Structure
+ */
+interface Record$1 {
+  tagId: number;
+  level: number;
+  data: Uint8Array;
+  size: number;
+}
+/**
+ * Paragraph Header Information
+ */
+interface ParagraphHeader {
+  textCount: number;
+  controlMask: number;
+  paraShapeId: number;
+  styleId: number;
+  columnType: number;
+  charShapeCount: number;
+}
+/**
+ * Parsed Paragraph
+ */
+interface Paragraph {
+  text: string;
+  header: ParagraphHeader;
+}
+/**
+ * Table Cell
+ */
+interface Cell {
+  row: number;
+  col: number;
+  rowspan: number;
+  colspan: number;
+  text: string;
+}
+/**
+ * Parsed Table
+ */
+interface Table {
+  rows: number;
+  cols: number;
+  cells: Cell[];
+}
+/**
+ * Conversion Options
+ */
+interface ConvertOptions {
+  tableLineBreakStyle?: "space" | "br";
+}
+/**
+ * Merge Strategy for Table Cells
+ */
+type MergeStrategy = "repeat" | "blank";
+//#endregion
+//#region src/parser.d.ts
+/**
+ * HWP File Parser
+ * Reads and parses HWP 5.0 files using OLE Compound File format
+ */
+declare class HWPFile {
+  private data;
+  private cfb;
+  private _fileHeader;
+  private _isCompressed;
+  /**
+   * Create HWPFile from raw data
+   * @param data - Raw HWP file data
+   */
+  constructor(data: Uint8Array | ArrayBuffer);
+  /**
+   * Create HWPFile from file path (Node.js only)
+   * @param path - Path to HWP file
+   */
+  static fromFile(path: string): Promise<HWPFile>;
+  /**
+   * Create HWPFile from ArrayBuffer
+   * @param data - ArrayBuffer data
+   */
+  static fromArrayBuffer(data: ArrayBuffer): HWPFile;
+  /**
+   * Create HWPFile from Uint8Array
+   * @param data - Uint8Array data
+   */
+  static fromUint8Array(data: Uint8Array): HWPFile;
+  /**
+   * Open and parse HWP file
+   */
+  open(): void;
+  /**
+   * Close HWP file and release resources
+   */
+  close(): void;
+  /**
+   * Get file header information
+   */
+  get fileHeader(): FileHeader | null;
+  /**
+   * Check if file is compressed
+   */
+  get isCompressed(): boolean;
+  /**
+   * Parse FileHeader stream (256 bytes fixed)
+   */
+  private parseFileHeader;
+  /**
+   * Read and decompress stream
+   * @param streamPath - Stream path (e.g., 'DocInfo', 'BodyText/Section0')
+   * @returns Decompressed data or null if stream doesn't exist
+   */
+  readStream(streamPath: string): Uint8Array | null;
+  /**
+   * List all streams in HWP file
+   * @returns Array of stream paths
+   */
+  listStreams(): string[][];
+  /**
+   * Get file information
+   */
+  getFileInfo(): Record<string, unknown>;
+  /**
+   * Get number of sections in BodyText
+   */
+  getSectionCount(): number;
+  /**
+   * Read section data
+   * @param sectionIndex - Section index (0-based)
+   * @returns Decompressed section data
+   */
+  readSection(sectionIndex: number): Uint8Array | null;
+}
+//#endregion
+//#region src/converter.d.ts
+/**
+ * Convert HWP file to Markdown
+ * @param hwp - Opened HWP file
+ * @param options - Conversion options
+ * @returns Markdown content
+ */
+declare function convertHwpToMarkdown(hwp: HWPFile, options?: ConvertOptions): string;
+/**
+ * High-level API: Convert HWP/HWPX file to Markdown
+ * Auto-detects format based on file extension or magic bytes.
+ * @param input - File path (Node.js), ArrayBuffer, or Uint8Array
+ * @param options - Conversion options
+ * @returns Markdown content
+ */
+declare function convert(input: string | ArrayBuffer | Uint8Array, options?: ConvertOptions): Promise<string>;
+//#endregion
+//#region src/browser.d.ts
+/**
+ * Convert HWP from Blob (browser File API)
+ * @param blob - Blob or File object
+ * @param options - Conversion options
+ * @returns Markdown content
+ */
+declare function convertFromBlob(blob: Blob, options?: ConvertOptions): Promise<string>;
+/**
+ * Convert HWP from File input (browser)
+ * @param file - File object from input element
+ * @param options - Conversion options
+ * @returns Markdown content
+ */
+declare function convertFromFile(file: File, options?: ConvertOptions): Promise<string>;
+//#endregion
+export { Cell, ConvertOptions, FileHeader, HWPFile, MergeStrategy, Paragraph, ParagraphHeader, Record$1 as Record, Table, convert, convertFromBlob, convertFromFile, convertHwpToMarkdown };
+//# sourceMappingURL=browser.d.mts.map

package/dist/browser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/types.ts","../src/parser.ts","../src/converter.ts","../src/browser.ts"],"sourcesContent":[],"mappings":";;AAGA;AAWA;AAUiB,UArBA,UAAA,CAqBe;EAYf,SAAA,EAAA,MAAS;EAQT,OAAI,EAAA,MAAA;EAWJ,YAAK,EAAA,OAGb;EAMQ,WAAA,EAAA,OAAc;EAOnB,aAAA,EAAA,MAAa;;;;AC1DzB;AAS4B,UDRX,QAAA,CCQW;EAAa,KAAA,EAAA,MAAA;EAMM,KAAA,EAAA,MAAA;EAAR,IAAA,EDX/B,UCW+B;EAUR,IAAA,EAAA,MAAA;;;;;AAmIG,UDjJjB,eAAA,CCiJiB;EAmDjB,SAAA,EAAA,MAAA;EAuCoB,WAAA,EAAA,MAAA;EAAU,WAAA,EAAA,MAAA;;;;AC/M/C;AAiEA;;;AAEY,UFnFK,SAAA,CEmFL;EACT,IAAA,EAAA,MAAA;EAAO,MAAA,EFlFA,eEkFA;;;;ACxGV;AACQ,UH2BS,IAAA,CG3BT;EAAI,GAAA,EAAA,MAAA;EAET,GAAA,EAAA,MAAA;EAAO,OAAA,EAAA,MAAA;EAYY,OAAA,EAAA,MAAA;EACd,IAAA,EAAA,MAAA;;;;;UHuBS,KAAA;;;SAGR;;;;;UAMQ,cAAA;;;;;;KAOL,aAAA;;;AA3BZ;AAWA;AASA;AAOA;cC1Da,OAAA;;;EAAA,QAAA,WAAO;EASQ,QAAA,aAAA;EAAa;;;;EAgBI,WAAA,CAAA,IAAA,EAhBjB,UAgBiB,GAhBJ,WAgBI;EAQf;;;;EA8Kb,OAAA,QAAA,CAAA,IAAA,EAAA,MAAA,CAAA,EAhMsB,OAgMtB,CAhM8B,OAgM9B,CAAA;EAuCoB;;;;+BA7NN,cAAc;ECc7B;AAiEhB;;;EAEY,OAAA,cAAA,CAAA,IAAA,EDzEkB,UCyElB,CAAA,EDzE+B,OCyE/B;EACT;;;;;ACxGH;;EACY,KAAA,CAAA,CAAA,EAAA,IAAA;EAET;;AAYH;EACQ,IAAA,UAAA,CAAA,CAAA,EFuEY,UEvEZ,GAAA,IAAA;EAAI;;;;;;;;;;;;;kCFyIsB;;;;;;;;;iBAmDjB;;;;;;;;;;qCAuCoB;;;;;;;;;;AArNP,iBCMd,oBAAA,CDNc,GAAA,ECOvB,ODPuB,EAAA,OAAA,CAAA,ECQnB,cDRmB,CAAA,EAAA,MAAA;;;ACM9B;AAiEA;;;;AAGG,iBAHmB,OAAA,CAGnB,KAAA,EAAA,MAAA,GAFe,WAEf,GAF6B,UAE7B,EAAA,OAAA,CAAA,EADS,cACT,CAAA,EAAA,OAAA,CAAA,MAAA,CAAA;;;AFxDH;AAOA;;;;AC1DA;AAS4B,iBENN,eAAA,CFMM,IAAA,EELpB,IFKoB,EAAA,OAAA,CAAA,EELhB,cFKgB,CAAA,EEHzB,OFGyB,CAAA,MAAA,CAAA;;;;;;;AAwBe,iBEfrB,eAAA,CFeqB,IAAA,EEdnC,IFcmC,EAAA,OAAA,CAAA,EEd/B,cFc+B,CAAA,EEZxC,OFYwC,CAAA,MAAA,CAAA"}

package/dist/browser.mjs

@@ -0,0 +1,27 @@
+import { a as HWPFile, n as convertHwpToMarkdown, t as convert } from "./converter-D6LrZNSL.mjs";
+
+//#region src/browser.ts
+/**
+* Convert HWP from Blob (browser File API)
+* @param blob - Blob or File object
+* @param options - Conversion options
+* @returns Markdown content
+*/
+async function convertFromBlob(blob, options) {
+	const arrayBuffer = await blob.arrayBuffer();
+	const { convert: convert$1 } = await import("./converter-C0C25ssg.mjs");
+	return convert$1(arrayBuffer, options);
+}
+/**
+* Convert HWP from File input (browser)
+* @param file - File object from input element
+* @param options - Conversion options
+* @returns Markdown content
+*/
+async function convertFromFile(file, options) {
+	return convertFromBlob(file, options);
+}
+
+//#endregion
+export { HWPFile, convert, convertFromBlob, convertFromFile, convertHwpToMarkdown };
+//# sourceMappingURL=browser.mjs.map

package/dist/browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.mjs","names":["convert"],"sources":["../src/browser.ts"],"sourcesContent":["/**\n * HWP2MD - Browser Entry Point\n * Browser-specific entry point (no Node.js dependencies)\n */\n\n// Core exports for browser\nexport { HWPFile } from \"./parser\";\nexport { convert, convertHwpToMarkdown } from \"./converter\";\nexport type * from \"./types\";\n\n/**\n * Convert HWP from Blob (browser File API)\n * @param blob - Blob or File object\n * @param options - Conversion options\n * @returns Markdown content\n */\nexport async function convertFromBlob(\n  blob: Blob,\n  options?: import(\"./types\").ConvertOptions,\n): Promise<string> {\n  const arrayBuffer = await blob.arrayBuffer();\n  const { convert } = await import(\"./converter\");\n  return convert(arrayBuffer, options);\n}\n\n/**\n * Convert HWP from File input (browser)\n * @param file - File object from input element\n * @param options - Conversion options\n * @returns Markdown content\n */\nexport async function convertFromFile(\n  file: File,\n  options?: import(\"./types\").ConvertOptions,\n): Promise<string> {\n  return convertFromBlob(file, options);\n}\n"],"mappings":";;;;;;;;;AAgBA,eAAsB,gBACpB,MACA,SACiB;CACjB,MAAM,cAAc,MAAM,KAAK,aAAa;CAC5C,MAAM,EAAE,uBAAY,MAAM,OAAO;AACjC,QAAOA,UAAQ,aAAa,QAAQ;;;;;;;;AAStC,eAAsB,gBACpB,MACA,SACiB;AACjB,QAAO,gBAAgB,MAAM,QAAQ"}

package/dist/cli/index.d.mts

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