hwpx-kit-cli 0.1.1__py3-none-any.whl

hwpx_kit/adapter/office_readers.py

@@ -0,0 +1,46 @@
+"""PDF·DOCX·XLSX 텍스트 추출 — 순수 파이썬 (kordoc 흡수, 2026-07-10).
+
+Node/kordoc 의존을 '한글 없는 환경의 구형 .hwp' 하나로 좁히기 위한 자체 리더.
+출력은 read 명령의 content로 그대로 나가는 Markdown 유사 텍스트.
+"""
+from __future__ import annotations
+
+
+def read_pdf(path: str) -> str:
+    from pypdf import PdfReader
+
+    reader = PdfReader(path)
+    pages = []
+    for i, page in enumerate(reader.pages):
+        text = (page.extract_text() or "").strip()
+        pages.append(f"## p.{i + 1}\n\n{text}" if len(reader.pages) > 1 else text)
+    return "\n\n".join(pages)
+
+
+def read_docx(path: str) -> str:
+    import docx
+
+    doc = docx.Document(path)
+    parts: list[str] = []
+    for para in doc.paragraphs:
+        if para.text.strip():
+            parts.append(para.text)
+    for table in doc.tables:
+        for row in table.rows:
+            cells = [cell.text.strip().replace("\n", " ") for cell in row.cells]
+            parts.append("| " + " | ".join(cells) + " |")
+    return "\n".join(parts)
+
+
+def read_xlsx(path: str) -> str:
+    import openpyxl
+
+    wb = openpyxl.load_workbook(path, data_only=True, read_only=True)
+    parts: list[str] = []
+    for ws in wb.worksheets:
+        parts.append(f"## {ws.title}")
+        for row in ws.iter_rows(values_only=True):
+            if any(v is not None for v in row):
+                parts.append("| " + " | ".join("" if v is None else str(v) for v in row) + " |")
+    wb.close()
+    return "\n".join(parts)

hwpx_kit/cli.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from hwpx_kit.commands.analyze import run_analyze
+from hwpx_kit.commands.convert import run_convert
+from hwpx_kit.commands.export import run_export
+from hwpx_kit.commands.fill import run_fill
+from hwpx_kit.commands.fmt import run_fmt
+from hwpx_kit.commands.generate import run_generate
+from hwpx_kit.commands.outline import run_outline
+from hwpx_kit.commands.page_break import run_page_break
+from hwpx_kit.commands.read import run_read
+from hwpx_kit.commands.render import run_render
+from hwpx_kit.commands.row_height import parse_rows_spec, run_row_height
+from hwpx_kit.commands.table_clear import run_table_clear
+from hwpx_kit.commands.table_copy import run_table_copy
+from hwpx_kit.commands.table_map_cmd import run_table_map
+from hwpx_kit.commands.table_new import run_table_new
+from hwpx_kit.commands.table_set import parse_assignments, run_table_set
+from hwpx_kit.commands.validate import run_validate
+from hwpx_kit.output import envelope, print_result
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    from importlib.metadata import version
+
+    p = argparse.ArgumentParser(prog="hwpx-kit", description="HWPX 양식 자동화 CLI")
+    p.add_argument("--version", action="version", version=f"hwpx-kit {version('hwpx-kit')}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    pa = sub.add_parser("analyze", help="양식에서 채울 수 있는 필드 탐지")
+    pa.add_argument("file")
+    pa.add_argument("--json", action="store_true")
+
+    pf = sub.add_parser("fill", help="필드에 값 채워 사본 저장 (원본 불변)")
+    pf.add_argument("file")
+    pf.add_argument("--data", required=True, help="fill_key: 값 매핑 JSON 파일")
+    pf.add_argument("--out", required=True, help="출력 hwpx 경로")
+    pf.add_argument("--json", action="store_true")
+
+    pr = sub.add_parser("read", help="본문을 Markdown/텍스트로 추출")
+    pr.add_argument("file")
+    pr.add_argument("--format", default="md", choices=["md", "text"])
+    pr.add_argument("--json", action="store_true")
+
+    pv = sub.add_parser("validate", help="hwpx 구조 검증")
+    pv.add_argument("file")
+    pv.add_argument("--json", action="store_true")
+
+    pc = sub.add_parser("convert", help=".hwp를 .hwpx로 변환 (Windows + 한글 필요)")
+    pc.add_argument("file")
+    pc.add_argument("--out", help="출력 hwpx 경로 (기본: 같은 이름 .hwpx)")
+    pc.add_argument("--json", action="store_true")
+
+    px = sub.add_parser("export", help=".hwpx를 다른 형식으로 내보내기 — 워드(docx) (Windows + 한글 필요)")
+    px.add_argument("file")
+    px.add_argument("--to", default="docx", choices=["docx"], help="출력 형식 (기본 docx)")
+    px.add_argument("--out", help="출력 경로 (기본: 같은 이름에 형식 확장자)")
+    px.add_argument("--json", action="store_true")
+
+    pn = sub.add_parser("render", help="레이아웃 보존 SVG 렌더 — 브라우저로 결과 확인 (kordoc 필요)")
+    pn.add_argument("file")
+    pn.add_argument("--out", help="출력 SVG 경로 (기본: 같은 이름 .svg)")
+    pn.add_argument("--json", action="store_true")
+
+    pg = sub.add_parser("generate", help="Markdown → 공문서 HWPX 생성 (kordoc 필요)")
+    pg.add_argument("file", help="입력 Markdown 파일")
+    pg.add_argument("--out", required=True, help="출력 hwpx 경로")
+    pg.add_argument("--preset", help="kordoc 공문서 프리셋 (예: 보고서)")
+    pg.add_argument("--json", action="store_true")
+
+    ph = sub.add_parser("row-height", help="표 기준 행 높이를 지정 행들에 복사 (행 추가 후 높이 정돈)")
+    ph.add_argument("file")
+    ph.add_argument("--table", type=int, required=True, help="표 인덱스 (analyze의 table_index, 0-기준)")
+    ph.add_argument("--like", type=int, required=True, help="기준 행 (0-기준)")
+    ph.add_argument("--rows", required=True, help="대상 행: '3-7' 범위 / '3,5' 나열 / 혼합")
+    ph.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    ph.add_argument("--json", action="store_true")
+
+    pcl = sub.add_parser("table-clear", help="표의 지정 행 셀 내용 비우기 (구조는 유지 — 잔존 내용 정리용)")
+    pcl.add_argument("file")
+    pcl.add_argument("--table", type=int, required=True, help="표 인덱스 (0-기준)")
+    pcl.add_argument("--rows", help="대상 행 '1-20'/'1,3' (생략 시 표 전체)")
+    pcl.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pcl.add_argument("--json", action="store_true")
+
+    pb = sub.add_parser("page-break", help="문단(또는 표) 앞 쪽나눔 — 끼워넣은 장을 새 쪽에서 시작시킴")
+    pb.add_argument("file")
+    pb.add_argument("--at-text", help="대상 문단 원문 (공백 정규화 전체 일치)")
+    pb.add_argument("--table", type=int, help="이 표가 든 문단에 적용 (0-기준)")
+    pb.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pb.add_argument("--json", action="store_true")
+
+    pm = sub.add_parser("table-map", help="표 셀 상태 덤프 — 좌표·텍스트·병합 anchor (검사용)")
+    pm.add_argument("file")
+    pm.add_argument("--table", type=int, help="특정 표만 (0-기준, 생략 시 전체)")
+    pm.add_argument("--json", action="store_true")
+
+    pnw = sub.add_parser("table-new", help="임의 R×C 새 표 생성 (--like-table로 기존 표 서식 차용)")
+    pnw.add_argument("file")
+    pnw.add_argument("--rows", type=int, required=True)
+    pnw.add_argument("--cols", type=int, required=True)
+    pnw.add_argument("--after-text", help="삽입 위치 문단 원문")
+    pnw.add_argument("--after-table", type=int, help="이 표 뒤(같은 문단)에 삽입")
+    pnw.add_argument("--like-table", type=int, help="테두리 서식을 빌릴 기존 표 인덱스")
+    pnw.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pnw.add_argument("--json", action="store_true")
+
+    po = sub.add_parser("outline", help="문단·표 배치 지도 (앵커 탐색용, 읽기 전용)")
+    po.add_argument("file")
+    po.add_argument("--json", action="store_true")
+
+    pcp = sub.add_parser("table-copy", help="표 통째 복제를 지정 문단에 삽입 (장 헤더 박스 늘리기 등)")
+    pcp.add_argument("file")
+    pcp.add_argument("--table", type=int, required=True, help="복제할 표 인덱스 (0-기준)")
+    pcp.add_argument("--after-text", help="삽입 위치 문단의 원문 (read 출력에서 복사)")
+    pcp.add_argument("--after-table", type=int, help="이 표 뒤(같은 문단)에 삽입 — 표 사이에 문단이 없을 때")
+    pcp.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pcp.add_argument("--json", action="store_true")
+
+    pts = sub.add_parser("table-set", help="표 셀 좌표 지정 쓰기 (table-clear로 비운 셀에 새 항목 기입)")
+    pts.add_argument("file")
+    pts.add_argument("--table", type=int, required=True, help="표 인덱스 (0-기준)")
+    pts.add_argument("--set", action="append", metavar="R,C=값",
+                     help="셀 기입 (반복 지정 가능, 0-기준 좌표) — 5개 이하 소량용")
+    pts.add_argument("--data", help='셀 기입 JSON 파일 {"R,C": "값"} — 대량 기입은 이쪽 (명령 길이 한계 회피)')
+    pts.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pts.add_argument("--json", action="store_true")
+
+    pt = sub.add_parser("fmt", help="공문 표기 변환 — 금액 한글화·날짜(요일)·만나이 (파일 불필요)")
+    pt.add_argument("--amount", help="금액 (정수, 콤마 허용)")
+    pt.add_argument("--style", default="gongmun", choices=["gongmun", "ilgeum"],
+                    help="금액 표기: gongmun=법정 공문(기본) / ilgeum=민간 관습(일금…원정)")
+    pt.add_argument("--date", help="날짜 YYYYMMDD → YYYY.M.D.(요일)")
+    pt.add_argument("--age", help="생년월일 YYMMDD → YYMMDD(만나이)")
+    pt.add_argument("--base", help="만나이 기준일 YYYYMMDD (기본 오늘)")
+    pt.add_argument("--json", action="store_true")
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    # 파이프/리다이렉트 시 Windows 기본이 cp949 — JSON 소비자를 위해 UTF-8 고정.
+    # stderr(엔진 한글 경고)도 동일 — 로그 리다이렉트 시 깨짐 방지
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    args = _build_parser().parse_args(argv)
+    as_json = args.json
+
+    # fmt는 파일 입력이 없다 — 파일 가드는 파일 위치인수가 있는 명령에만
+    if args.command != "fmt" and not os.path.exists(args.file):
+        env = envelope(
+            args.command, ok=False,
+            error={"code": "FILE_NOT_FOUND", "message": f"파일이 없습니다: {args.file}"},
+        )
+        print_result(env, as_json)
+        return 1
+
+    try:
+        exit_code = 0
+        if args.command == "analyze":
+            data = run_analyze(args.file)
+        elif args.command == "fill":
+            with open(args.data, encoding="utf-8") as fh:
+                mapping = json.load(fh)
+            data = run_fill(args.file, mapping, args.out)
+            if data["unmatched"]:
+                exit_code = 2
+        elif args.command == "read":
+            data = run_read(args.file, fmt=args.format)
+        elif args.command == "convert":
+            data = run_convert(args.file, out_path=args.out)
+        elif args.command == "export":
+            data = run_export(args.file, to=args.to, out_path=args.out)
+        elif args.command == "fmt":
+            data = run_fmt(
+                amount=args.amount, date=args.date, age=args.age,
+                base=args.base, style=args.style,
+            )
+        elif args.command == "row-height":
+            data = run_row_height(
+                args.file, table=args.table, like=args.like,
+                rows=parse_rows_spec(args.rows), out_path=args.out,
+            )
+        elif args.command == "table-clear":
+            data = run_table_clear(
+                args.file, table=args.table,
+                rows=parse_rows_spec(args.rows) if args.rows else None,
+                out_path=args.out,
+            )
+        elif args.command == "table-set":
+            assignments = []
+            if args.set:
+                assignments += parse_assignments(args.set)
+            if args.data:
+                from hwpx_kit.commands.table_set import load_assignments_file
+
+                assignments += load_assignments_file(args.data)
+            if not assignments:
+                raise ValueError("--set 또는 --data 중 하나는 지정해야 합니다.")
+            data = run_table_set(
+                args.file, table=args.table,
+                assignments=assignments, out_path=args.out,
+            )
+        elif args.command == "table-copy":
+            data = run_table_copy(
+                args.file, table=args.table,
+                after_text=args.after_text, out_path=args.out,
+                after_table=args.after_table,
+            )
+        elif args.command == "outline":
+            data = run_outline(args.file)
+        elif args.command == "page-break":
+            data = run_page_break(
+                args.file, at_text=args.at_text, table=args.table, out_path=args.out,
+            )
+        elif args.command == "table-map":
+            data = run_table_map(args.file, table=args.table)
+        elif args.command == "table-new":
+            data = run_table_new(
+                args.file, rows=args.rows, cols=args.cols,
+                after_text=args.after_text, like_table=args.like_table,
+                out_path=args.out, after_table=args.after_table,
+            )
+        elif args.command == "render":
+            data = run_render(args.file, out_path=args.out)
+        elif args.command == "generate":
+            data = run_generate(args.file, args.out, preset=args.preset)
+        else:
+            data = run_validate(args.file)
+            if not data["valid"]:
+                exit_code = 2
+    except Exception as exc:
+        env = envelope(
+            args.command, ok=False,
+            error={"code": "COMMAND_FAILED", "message": str(exc)},
+        )
+        print_result(env, as_json)
+        return 1
+
+    env = envelope(args.command, ok=True, data=data)
+    if as_json:
+        print_result(env, as_json=True)
+    else:
+        if args.command == "read":
+            print(data["content"])
+        else:
+            print_result(env, as_json=False)
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hwpx_kit/commands/analyze.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import os
+import re
+from collections import Counter
+
+from hwpx_kit.adapter.hwpx_engine import HwpxEngineAdapter
+
+# 라벨은 단어 문자(한글/영숫자)를 포함해야 함 — 구두점 단독 셀 배제
+_WORD_RE = re.compile(r"\w", re.UNICODE)
+_WS_RE = re.compile(r"\s+")
+_MAX_LABEL_LEN = 20
+
+
+def _normalize_label(text: str) -> str:
+    """엔진(fill_by_path)과 같은 공백 정규화 — 개행 든 라벨('담당 부서\\n<총괄>')도
+    한 줄 라벨로 취급해 fill_key가 엔진 매칭을 그대로 통과하게 한다."""
+    return _WS_RE.sub(" ", text).strip()
+
+
+def _is_label_text(text: str) -> bool:
+    if not text:
+        return False
+    if len(text) > _MAX_LABEL_LEN:
+        return False
+    return bool(_WORD_RE.search(text))
+
+
+def find_label_candidates(table_map: dict) -> list[dict]:
+    """라벨 후보: 텍스트가 있고 바로 오른쪽 셀이 비어 있는 셀."""
+    candidates = []
+    for table in table_map.get("tables", []):
+        cells = {(c["row"], c["col"]): c for c in table.get("cells", [])}
+        for (row, col), cell in cells.items():
+            if cell.get("is_anchor") is False:
+                # 병합 셀의 격자 복제 — 논리 셀은 anchor 좌표 하나뿐
+                continue
+            text = _normalize_label(cell.get("text") or "")
+            if not _is_label_text(text):
+                continue
+            right = cells.get((row, col + 1))
+            if right is None:
+                continue
+            right_text = (right.get("text") or "").strip()
+            if _normalize_label(right_text) == text:
+                # 병합 셀은 같은 텍스트가 격자 전체에 복제되어 나타남
+                continue
+            candidates.append(
+                {
+                    "table_index": table.get("table_index", 0),
+                    "label": text,
+                    "row": row,
+                    "col": col,
+                    "fill_key": f"table:{text}",
+                    "prefilled": bool(right_text),
+                    "current": right_text,
+                    "ambiguous": False,
+                }
+            )
+    counts = Counter(c["label"] for c in candidates)
+    for c in candidates:
+        c["ambiguous"] = counts[c["label"]] > 1
+    return candidates
+
+
+def _assign_nth_keys(ad: HwpxEngineAdapter, candidates: list[dict]) -> None:
+    """중복 라벨 후보의 fill_key에 #N 접미사 부여.
+
+    중복 판정·번호 모두 fill과 같은 열거(label_positions_map, anchor 셀
+    전체) 기준 — analyze 후보로는 유일해 보여도(두 번째 출현에 오른쪽 칸이
+    없는 경우 등) fill이 ambiguous로 거부할 수 있어, fill 관점의 출현 수로
+    판정해야 'analyze 키 그대로 fill' 계약이 지켜진다.
+    """
+    if not candidates:
+        return
+    posmap = ad.label_positions_map()
+    for c in candidates:
+        matches = posmap.get(ad.normalize_label(c["label"]), [])
+        if len(matches) < 2:
+            continue
+        c["ambiguous"] = True
+        for i, m in enumerate(matches):
+            if (m["table_index"], m["row"], m["col"]) == (c["table_index"], c["row"], c["col"]):
+                c["fill_key"] = f"table:{c['label']}#{i + 1}"
+                break
+
+
+def run_analyze(path: str) -> dict:
+    ad = HwpxEngineAdapter.open(path)
+    fields: list[dict] = []
+
+    for ff in ad.form_fields():
+        fields.append(
+            {
+                "type": "clickhere",
+                "fill_key": f"clickhere:{ff.name or ff.index}",
+                "name": ff.name,
+                "index": ff.index,
+                "current": ff.current,
+            }
+        )
+
+    for m in ad.markers():
+        fields.append(
+            {
+                "type": "marker",
+                "fill_key": f"marker:{m.key}",
+                "key": m.key,
+                "paragraph_index": m.paragraph_index,
+                "context": m.context,
+            }
+        )
+
+    table_map = ad.table_map()
+    candidates = find_label_candidates(table_map)
+    _assign_nth_keys(ad, candidates)
+    for cand in candidates:
+        fields.append({"type": "table_label", **cand})
+
+    paragraph_count = len(ad.export_text().splitlines())
+    return {
+        "file": os.path.abspath(path),
+        "fields": fields,
+        "tables": {"count": len(table_map.get("tables", []))},
+        "structure": {"paragraphs": paragraph_count},
+    }

hwpx_kit/commands/convert.py

@@ -0,0 +1,52 @@
+"""구형 .hwp → .hwpx 변환.
+
+Windows + 한글(한컴오피스) 설치 환경에서만 동작 — 한글을 COM으로 백그라운드
+구동해 다른 형식으로 저장한다. 서버/타 OS에서는 명확한 에러를 낸다.
+"""
+from __future__ import annotations
+
+import os
+
+from hwpx_kit.output import quiet_engine
+
+# visible=False 팝업 무한대기 방지 — 자동응답: 확인(0x1) / 확인·취소→확인(0x10)
+# / 종료·재시도·무시→무시(0x400) / 예·아니오·취소→예(0x1000) / 예·아니오→예(0x10000)
+# / 재시도·취소→취소(0x200000)
+AUTO_ANSWER_MODE = 0x1 | 0x10 | 0x400 | 0x1000 | 0x10000 | 0x200000
+
+
+def _load_hwp_com():
+    """pyhwpx.Hwp 클래스를 반환. 불가 환경이면 RuntimeError."""
+    try:
+        from pyhwpx import Hwp
+    except ImportError as exc:
+        raise RuntimeError(
+            "hwp 변환에는 Windows + 한글(한컴오피스) + pyhwpx가 필요합니다. "
+            "설치: pip install pyhwpx"
+        ) from exc
+    return Hwp
+
+
+def run_convert(path: str, out_path: str | None = None) -> dict:
+    if not path.lower().endswith(".hwp"):
+        raise ValueError("convert 입력은 .hwp 파일이어야 합니다 (.hwpx는 변환 불필요)")
+    src = os.path.abspath(path)
+    out = os.path.abspath(out_path) if out_path else src[: -len(".hwp")] + ".hwpx"
+    if out == src:
+        raise ValueError("출력 경로가 원본과 같습니다.")
+
+    # pyhwpx는 RegisterModule 실패 등을 print()로 stdout에 씀 —
+    # --json 봉투 오염 방지 (절대 규칙: JSON 모드 stdout은 봉투 한 줄만)
+    with quiet_engine():
+        hwp_cls = _load_hwp_com()
+        hwp = hwp_cls(visible=False)
+        try:
+            if hasattr(hwp, "set_message_box_mode"):
+                hwp.set_message_box_mode(AUTO_ANSWER_MODE)
+            if not hwp.open(src):
+                raise RuntimeError(f"한글이 파일을 열지 못했습니다: {src}")
+            if not hwp.save_as(out, format="HWPX"):
+                raise RuntimeError(f"HWPX 저장에 실패했습니다: {out}")
+        finally:
+            hwp.quit()
+    return {"file": src, "out": out}

hwpx_kit/commands/export.py

@@ -0,0 +1,44 @@
+"""hwpx → 타 형식 내보내기 (현재 docx).
+
+Windows + 한글(한컴오피스) COM 경유 — convert와 같은 제약.
+한글 SaveAs의 워드 형식 문자열은 "OOXML"이다 ("DOCX"/"MSWORD"는 조용히
+실패 — 2026-07-10 실탐침). 다른 형식 저장 시 경고 팝업이 뜰 수 있는데
+visible=False라 보이지 않아 무한대기가 됨 — 메시지박스 자동응답 필수.
+"""
+from __future__ import annotations
+
+import os
+
+from hwpx_kit.commands import convert as _convert
+from hwpx_kit.commands.convert import AUTO_ANSWER_MODE
+from hwpx_kit.output import quiet_engine
+
+# to → (한글 SaveAs format 문자열, 확장자)
+_FORMATS = {"docx": ("OOXML", ".docx")}
+
+
+def run_export(path: str, to: str = "docx", out_path: str | None = None) -> dict:
+    if not path.lower().endswith(".hwpx"):
+        raise ValueError("export 입력은 .hwpx 파일이어야 합니다 (.hwp는 먼저 convert)")
+    if to not in _FORMATS:
+        raise ValueError(f"지원 형식: {', '.join(_FORMATS)} (요청: {to})")
+    save_format, ext = _FORMATS[to]
+
+    src = os.path.abspath(path)
+    out = os.path.abspath(out_path) if out_path else src[: -len(".hwpx")] + ext
+    if out == src:
+        raise ValueError("출력 경로가 원본과 같습니다.")
+
+    with quiet_engine():
+        hwp_cls = _convert._load_hwp_com()
+        hwp = hwp_cls(visible=False)
+        try:
+            if hasattr(hwp, "set_message_box_mode"):
+                hwp.set_message_box_mode(AUTO_ANSWER_MODE)
+            if not hwp.open(src):
+                raise RuntimeError(f"한글이 파일을 열지 못했습니다: {src}")
+            if not hwp.save_as(out, format=save_format):
+                raise RuntimeError(f"{to} 저장에 실패했습니다: {out}")
+        finally:
+            hwp.quit()
+    return {"file": src, "out": out, "format": to}

hwpx_kit/commands/fill.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import re
+
+from hwpx_kit.adapter.hwpx_engine import HwpxEngineAdapter
+
+# 라벨 끝의 출현 인덱스: "부서#2" → ("부서", 2). 중복 라벨 구분용
+_NTH_RE = re.compile(r"^(.+?)\s*#(\d+)$")
+
+_DIRECTIONS = {"left", "right", "up", "down"}
+
+
+def _parse_table_spec(spec: str) -> tuple[str, list[str], int | None]:
+    """"라벨#N > 방향..." 분해. 방향 토큰은 끝에서부터 유효한 것만 소비 —
+    라벨 자체에 '>'가 들어가도('담당 부서 <총괄>') 잘리지 않는다."""
+    parts = spec.split(">")
+    directions: list[str] = []
+    while len(parts) > 1 and parts[-1].strip().casefold() in _DIRECTIONS:
+        directions.insert(0, parts.pop().strip().casefold())
+    label = ">".join(parts).strip()
+    if not directions:
+        directions = ["right"]
+    nth = None
+    nth_match = _NTH_RE.match(label)
+    if nth_match:
+        label, nth = nth_match.group(1), int(nth_match.group(2))
+    return label, directions, nth
+
+
+def _apply_one(ad: HwpxEngineAdapter, fill_key: str, value: str) -> str | None:
+    """성공 시 None, 실패 시 사유 문자열 반환."""
+    if fill_key.startswith("clickhere:"):
+        name = fill_key[len("clickhere:"):]
+        try:
+            ad.fill_form_field(name, value)
+            return None
+        except Exception as exc:  # 엔진이 없는 필드에 던지는 예외를 사유로 변환
+            return f"누름틀 채우기 실패: {exc}"
+
+    if fill_key.startswith("marker:"):
+        key = fill_key[len("marker:"):]
+        count = ad.replace_marker(key, value)
+        return None if count > 0 else "문서에서 마커를 찾지 못함"
+
+    if fill_key.startswith("text:"):
+        search = fill_key[len("text:"):]
+        count = ad.replace_text(search, value)
+        if count == 0:
+            # 런이 쪼개진 긴 문장 — 문단 전체 일치로 폴백
+            count = ad.replace_paragraph_text(search, value)
+        return None if count > 0 else "문서에서 해당 문구를 찾지 못함"
+
+    if fill_key.startswith("delete:"):
+        search = fill_key[len("delete:"):]
+        count = ad.delete_paragraph_text(search)
+        return None if count > 0 else "문서에서 해당 문단을 찾지 못함"
+
+    if fill_key.startswith("bold:"):
+        count = ad.apply_run_format(fill_key[len("bold:"):], bold=True)
+        return None if count > 0 else "문서에서 해당 문구를 찾지 못함"
+
+    if fill_key.startswith("underline:"):
+        count = ad.apply_run_format(fill_key[len("underline:"):], underline=True)
+        return None if count > 0 else "문서에서 해당 문구를 찾지 못함"
+
+    if fill_key.startswith("table:"):
+        label, directions, nth = _parse_table_spec(fill_key[len("table:"):])
+        result = ad.fill_at_label(label, directions, value, nth=nth)
+        if result.get("applied_count", 0) > 0:
+            return None
+        failed = result.get("failed") or [{}]
+        reason = failed[0].get("reason", "라벨 없음")
+        if "ambiguous" in str(reason):
+            reason = f"{reason} — 같은 라벨이 여러 곳. analyze의 table:라벨#N 키로 지정"
+        return f"표 채우기 실패: {reason}"
+
+    return "알 수 없는 fill_key 형식 (clickhere:/marker:/table:/text:/delete:/bold:/underline: 중 하나여야 함)"
+
+
+def run_fill(path: str, data: dict[str, str], out_path: str) -> dict:
+    ad = HwpxEngineAdapter.open(path)
+    applied: list[str] = []
+    unmatched: list[dict] = []
+    for fill_key, value in data.items():
+        reason = _apply_one(ad, fill_key, str(value))
+        if reason is None:
+            applied.append(fill_key)
+        else:
+            unmatched.append({"key": fill_key, "reason": reason})
+    saved = ad.save_copy(out_path)
+    return {"out": saved, "applied": applied, "unmatched": unmatched}

hwpx_kit/commands/fmt.py

@@ -0,0 +1,29 @@
+"""fmt 명령 — 결정론 표기 변환 (파일 입력 없음).
+
+정확히 하나의 변환 대상(amount/date/age)을 받아 envelope로 반환.
+"""
+from __future__ import annotations
+
+from hwpx_kit.format import format_amount, gongmun_date, korean_age
+
+
+def run_fmt(
+    amount: str | None = None,
+    date: str | None = None,
+    age: str | None = None,
+    base: str | None = None,
+    style: str = "gongmun",
+) -> dict:
+    targets = [k for k, v in (("amount", amount), ("date", date), ("age", age)) if v is not None]
+    if len(targets) != 1:
+        raise ValueError("--amount / --date / --age 중 정확히 하나를 지정하세요.")
+
+    if amount is not None:
+        cleaned = amount.replace(",", "").strip()
+        if not cleaned.isdigit():
+            raise ValueError(f"금액은 정수여야 합니다: {amount}")
+        result = format_amount(int(cleaned), style=style)
+        return {"kind": "amount", "input": amount, "style": style, "result": result}
+    if date is not None:
+        return {"kind": "date", "input": date, "result": gongmun_date(date)}
+    return {"kind": "age", "input": age, "base": base, "result": korean_age(age, base=base)}

hwpx_kit/commands/generate.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import os
+
+from hwpx_kit.adapter.kordoc_engine import KordocAdapter
+
+
+def run_generate(markdown_path: str, out_path: str, preset: str | None = None) -> dict:
+    if not markdown_path.lower().endswith((".md", ".markdown")):
+        raise ValueError("generate 입력은 Markdown 파일이어야 합니다.")
+    saved = KordocAdapter.generate_hwpx(markdown_path, out_path, preset=preset)
+    return {"file": os.path.abspath(markdown_path), "out": saved, "preset": preset}