hwpx-kit-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hwpx-kit",
   "description": "한글(HWPX/HWP) 문서 자동화 스킬 모음 — 양식 분석·채우기·백지 생성·표기 변환·공문 규약·표 계산·오피스 출력. CLI는 첫 사용 시 스킬이 설치를 안내 (Python 3.10+ 필요).",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": {
     "name": "6aneffy",
     "email": "tkdgus990809@gmail.com"

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/CLAUDE.md

@@ -26,7 +26,7 @@ skills/*/SKILL.md → Claude Code 플러그인 스킬들 (.claude-plugin/plugin.
  └─ office-export    → hwpx→docx(변환)·pptx/xlsx(재구성, officecli 선택 의존)
 
 CLI (cli.py) — JSON 봉투, 종료코드 0/1/2
- └─ commands/ (analyze·fill·fill-batch·inspect·read·validate·convert·export·render·generate·fmt·row-add·row-del·row-height·table-clear·table-set·table-copy·table-map·table-new·page-break·outline)
+ └─ commands/ (analyze·fill·fill-batch·inspect·image-add·header-footer·read·validate·convert·export·render·generate·fmt·row-add·row-del·row-height·table-clear·table-set·table-copy·table-map·table-new·page-break·outline)
      ├─ format.py ← 순수함수 (금액한글화·요일·만나이) — 엔진 임포트 금지, fmt는 파일 인수 없음(FILE_NOT_FOUND 가드 우회)
      └─ adapter/ ← 명령 계층은 어댑터 인터페이스만 사용 (엔진 직접 import 금지)
          ├─ hwpx_engine.py   → python-hwpx (hwpx 분석·채우기·검증·표 조작, 순수 Python)

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hwpx-kit-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: 한글(HWPX) 문서 자동화 CLI — Korean HWPX document automation for AI agents: analyze, fill, read, validate, table ops
 Project-URL: Homepage, https://github.com/6aneffy/hwpx-kit
 Project-URL: Repository, https://github.com/6aneffy/hwpx-kit
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/hwpx-kit-cli.svg)](https://pypi.org/project/hwpx-kit-cli/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-d97757.svg)](https://claude.com/claude-code)
-[![Tests](https://img.shields.io/badge/tests-176%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-186%20passing-brightgreen.svg)](tests/)
 
 </div>
 
@@ -154,6 +154,8 @@ hwpx-kit row-add 문서.hwpx --table 3 --like 2 --count 3 --out 결과.hwpx
 hwpx-kit row-del 문서.hwpx --table 3 --rows 5-7 --out 결과.hwpx              # 행 삭제
 hwpx-kit row-height 문서.hwpx --table 3 --like 1 --rows 2-5 --out 결과.hwpx  # 행 높이 정돈
 hwpx-kit page-break 문서.hwpx --table 5 --out 결과.hwpx                 # 쪽나눔 (새 장 시작)
+hwpx-kit image-add 문서.hwpx --image 도장.png --at-text "(인)" --width-mm 20 --out 결과.hwpx  # 직인·사진
+hwpx-kit header-footer 문서.hwpx --footer "대외비" --page-number center --out 결과.hwpx
 
 # 변환·생성
 hwpx-kit fmt --amount 12340 --json           # 금12,340원(금일만이천삼백사십원)
@@ -190,7 +192,7 @@ hwpx-kit render 문서.hwpx --out p.svg        # SVG 미리보기 (kordoc)
 ## 아키텍처
 
 ```
-Claude Code 스킬 6종 ──→  hwpx-kit CLI (23 명령, JSON 봉투)
+Claude Code 스킬 6종 ──→  hwpx-kit CLI (25 명령, JSON 봉투)
                               └─ adapter/  ← 엔진 격리 계층
                                   ├─ python-hwpx    hwpx 분석·채우기·표 조작
                                   ├─ pypdf·python-docx·openpyxl   타 포맷 읽기
@@ -206,7 +208,7 @@ templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커
 
 ## 검증
 
-- 자동 테스트 176개 (pytest)
+- 자동 테스트 186개 (pytest)
 - 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
   실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
 - 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/README.md

@@ -10,7 +10,7 @@
 [![PyPI](https://img.shields.io/pypi/v/hwpx-kit-cli.svg)](https://pypi.org/project/hwpx-kit-cli/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-d97757.svg)](https://claude.com/claude-code)
-[![Tests](https://img.shields.io/badge/tests-176%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-186%20passing-brightgreen.svg)](tests/)
 
 </div>
 
@@ -131,6 +131,8 @@ hwpx-kit row-add 문서.hwpx --table 3 --like 2 --count 3 --out 결과.hwpx
 hwpx-kit row-del 문서.hwpx --table 3 --rows 5-7 --out 결과.hwpx              # 행 삭제
 hwpx-kit row-height 문서.hwpx --table 3 --like 1 --rows 2-5 --out 결과.hwpx  # 행 높이 정돈
 hwpx-kit page-break 문서.hwpx --table 5 --out 결과.hwpx                 # 쪽나눔 (새 장 시작)
+hwpx-kit image-add 문서.hwpx --image 도장.png --at-text "(인)" --width-mm 20 --out 결과.hwpx  # 직인·사진
+hwpx-kit header-footer 문서.hwpx --footer "대외비" --page-number center --out 결과.hwpx
 
 # 변환·생성
 hwpx-kit fmt --amount 12340 --json           # 금12,340원(금일만이천삼백사십원)
@@ -167,7 +169,7 @@ hwpx-kit render 문서.hwpx --out p.svg        # SVG 미리보기 (kordoc)
 ## 아키텍처
 
 ```
-Claude Code 스킬 6종 ──→  hwpx-kit CLI (23 명령, JSON 봉투)
+Claude Code 스킬 6종 ──→  hwpx-kit CLI (25 명령, JSON 봉투)
                               └─ adapter/  ← 엔진 격리 계층
                                   ├─ python-hwpx    hwpx 분석·채우기·표 조작
                                   ├─ pypdf·python-docx·openpyxl   타 포맷 읽기
@@ -183,7 +185,7 @@ templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커
 
 ## 검증
 
-- 자동 테스트 176개 (pytest)
+- 자동 테스트 186개 (pytest)
 - 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
   실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
 - 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hwpx-kit-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "한글(HWPX) 문서 자동화 CLI — Korean HWPX document automation for AI agents: analyze, fill, read, validate, table ops"
 readme = "README.md"
 requires-python = ">=3.10"

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/skills/hwpx-form/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hwpx-kit
-description: HWPX 양식 자동화 — 한글(HWPX/HWP) 양식 분석, 내용 채우기, 본문 추출, 구조 검증, .hwp→.hwpx 변환. 사용자가 hwpx/hwp 파일을 주며 "이 양식에 채워줘", "여기에 써줘", "이 명단으로 30명분 만들어줘"(일괄 생성), "이 엑셀 표 넣어줘", "이 문서 읽어줘/요약해줘", "hwp 변환해줘" 할 때 사용. Triggers: fill this Korean form, mail merge certificates, read this hwp/hwpx file, Hangul document automation.
+description: HWPX 양식 자동화 — 한글(HWPX/HWP) 양식 분석, 내용 채우기, 본문 추출, 구조 검증, .hwp→.hwpx 변환. 사용자가 hwpx/hwp 파일을 주며 "이 양식에 채워줘", "여기에 써줘", "이 명단으로 30명분 만들어줘"(일괄 생성), "이 엑셀 표 넣어줘", "도장 찍어줘/사진 붙여줘", "쪽번호 넣어줘", "이 문서 읽어줘/요약해줘", "hwp 변환해줘" 할 때 사용. Triggers: fill this Korean form, mail merge certificates, read this hwp/hwpx file, Hangul document automation.
 ---
 
 # hwpx-kit: HWPX 양식 자동화
@@ -157,6 +157,22 @@ CLI `hwpx-kit`으로 hwpx 문서를 다룬다. 항상 `--json`을 붙여 실행
    금지문자는 `_` 치환. 원본 불변은 fill과 동일
 5. 개인정보 든 명단 파일은 사용자 문서와 동일한 기밀 취급 — 커밋·업로드 금지
 
+## 사진·직인 넣기 — "여기 도장 찍어줘", "사진 붙여줘"
+
+`hwpx-kit image-add <문서.hwpx> --image <파일.png> ... --out <결과.hwpx>`
+- **직인/서명**: 대상 문단 원문으로 — `--at-text "서명: (인)" --width-mm 20`
+  (원문은 read 출력에서 복사. 이미지 파일은 사용자에게 받는다 — 도장을 그려주지 않는다)
+- **사진 첨부 칸**(표 안): `--table N --cell R,C --width-mm 35 --height-mm 45`
+  (증명사진 규격 예시. 좌표는 table-map으로 확인)
+- 글자처럼취급으로 들어가므로 셀 크기가 이미지에 맞을수록 깔끔 — 크게 넣으면
+  행이 부푼다. 삽입 후 validate + 한글 육안 확인 안내
+- 사용자 제공 사진·도장 이미지도 문서와 동일한 기밀 취급
+
+## 머리말·꼬리말·쪽번호 — "쪽번호 넣어줘"
+
+`hwpx-kit header-footer <문서.hwpx> [--header "텍스트"] [--footer "텍스트"] [--page-number center] --out <결과.hwpx>`
+— 쪽번호 위치는 left/center/right. 문서관리번호·대외비 표기 등에 사용.
+
 ## 엑셀 표를 한글 문서에 넣기 — "이 엑셀 표 문서에 넣어줘"
 
 복붙(서식 깨짐) 대신 도구 조합으로:

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/src/hwpx_kit/adapter/hwpx_engine.py

@@ -671,6 +671,71 @@ class HwpxEngineAdapter:
             self._mark_sections_dirty()
         return len(targets)
 
+    _HWPUNIT_PER_MM = 7200 / 25.4  # 1mm ≈ 283.46 hwpunit
+
+    def insert_image(self, image_path: str, *, at_text: str | None = None,
+                     table_index: int | None = None, cell: tuple[int, int] | None = None,
+                     width_mm: float = 20.0, height_mm: float | None = None) -> dict:
+        """이미지를 문단(원문 앵커) 또는 표 셀에 글자처럼취급으로 삽입.
+
+        엔진 2단계: add_image(바이너리 등록) → paragraph.add_picture(배치).
+        height_mm 생략 시 정사각(width와 동일) — 비율 유지가 필요하면 호출자가 지정.
+        """
+        import os as _os
+
+        ext = _os.path.splitext(image_path)[1].lower().lstrip(".")
+        if ext == "jpeg":
+            ext = "jpg"
+        if ext not in ("png", "jpg", "bmp", "gif"):
+            raise ValueError(f"지원하지 않는 이미지 형식: .{ext} (png/jpg/bmp/gif)")
+        with open(image_path, "rb") as f:
+            image_data = f.read()
+
+        width = int(width_mm * self._HWPUNIT_PER_MM)
+        height = int((height_mm if height_mm is not None else width_mm) * self._HWPUNIT_PER_MM)
+
+        with quiet_engine():
+            if cell is not None:
+                if table_index is None:
+                    raise ValueError("--cell은 --table과 함께 지정하세요.")
+                from hwpx.tools import table_navigation as tn
+
+                tables = tn._collect_document_tables(self._doc)
+                if not 0 <= table_index < len(tables):
+                    raise ValueError(f"표 인덱스 범위 밖: {table_index} (표 {len(tables)}개)")
+                r, c = cell
+                paragraphs = tables[table_index].table.cell(r, c).paragraphs
+                target = list(paragraphs)[0]
+            else:
+                target = self._find_anchor_paragraph(anchor_text=at_text,
+                                                     after_table=table_index)
+            item_id = self._doc.add_image(image_data, ext)
+            target.add_picture(item_id, width=width, height=height, treat_as_char=True)
+        return {"binary_item_id": item_id, "width": width, "height": height}
+
+    def set_header_footer(self, *, header: str | None = None,
+                          footer: str | None = None,
+                          page_number: str | None = None) -> list[str]:
+        """머리말/꼬리말 텍스트·쪽번호 설정. 적용 항목 이름 목록 반환."""
+        applied: list[str] = []
+        align_map = {"left": "LEFT", "center": "CENTER", "right": "RIGHT"}
+        with quiet_engine():
+            if header is not None:
+                self._doc.set_header_text(header)
+                applied.append("header")
+            if footer is not None:
+                self._doc.set_footer_text(footer)
+                applied.append("footer")
+            if page_number is not None:
+                align = align_map.get(page_number.lower())
+                if align is None:
+                    raise ValueError(f"쪽번호 위치는 left/center/right 중 하나: {page_number}")
+                self._doc.set_page_number(align=align)
+                applied.append("page_number")
+        if not applied:
+            raise ValueError("--header/--footer/--page-number 중 하나는 지정하세요.")
+        return applied
+
     def save_copy(self, out_path: str) -> str:
         out_abs = os.path.abspath(out_path)
         if out_abs == self._source_path:

{hwpx_kit_cli-0.3.0 → hwpx_kit_cli-0.4.0}/src/hwpx_kit/cli.py

@@ -104,6 +104,25 @@ def _build_parser() -> argparse.ArgumentParser:
     pin.add_argument("--checks", help="쉼표 구분: residue,gongmun,pii (생략 시 전부)")
     pin.add_argument("--json", action="store_true")
 
+    pim = sub.add_parser("image-add", help="이미지(사진·직인) 삽입 — 문단 앵커 또는 표 셀에 글자처럼취급")
+    pim.add_argument("file")
+    pim.add_argument("--image", required=True, help="이미지 파일 (png/jpg/bmp/gif)")
+    pim.add_argument("--at-text", help="이 원문 문단에 삽입 (공백 정규화 전체 일치)")
+    pim.add_argument("--table", type=int, help="표 인덱스 (--cell과 함께)")
+    pim.add_argument("--cell", help="셀 좌표 'R,C' (0-기준)")
+    pim.add_argument("--width-mm", type=float, default=20.0, help="가로 크기 mm (기본 20)")
+    pim.add_argument("--height-mm", type=float, help="세로 크기 mm (생략 시 가로와 동일)")
+    pim.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    pim.add_argument("--json", action="store_true")
+
+    phf = sub.add_parser("header-footer", help="머리말/꼬리말 텍스트·쪽번호 설정")
+    phf.add_argument("file")
+    phf.add_argument("--header", help="머리말 텍스트")
+    phf.add_argument("--footer", help="꼬리말 텍스트")
+    phf.add_argument("--page-number", help="쪽번호 위치: left/center/right")
+    phf.add_argument("--out", required=True, help="출력 hwpx 경로 (원본 불변)")
+    phf.add_argument("--json", action="store_true")
+
     pra = sub.add_parser("row-add", help="표 행 추가 — 기준 행 서식·높이 승계, 내용은 비움 (세로 병합 걸리면 거부)")
     pra.add_argument("file")
     pra.add_argument("--table", type=int, required=True, help="표 인덱스 (0-기준)")
@@ -245,6 +264,22 @@ def main(argv: list[str] | None = None) -> int:
             )
             if not data["clean"]:
                 exit_code = 2
+        elif args.command == "image-add":
+            from hwpx_kit.commands.image_add import run_image_add
+
+            data = run_image_add(
+                args.file, image_path=args.image, at_text=args.at_text,
+                table=args.table, cell=args.cell,
+                width_mm=args.width_mm, height_mm=args.height_mm,
+                out_path=args.out,
+            )
+        elif args.command == "header-footer":
+            from hwpx_kit.commands.header_footer import run_header_footer
+
+            data = run_header_footer(
+                args.file, header=args.header, footer=args.footer,
+                page_number=args.page_number, out_path=args.out,
+            )
         elif args.command == "row-add":
             from hwpx_kit.commands.table_rows import run_row_add
 

hwpx_kit_cli-0.4.0/src/hwpx_kit/commands/header_footer.py

@@ -0,0 +1,13 @@
+"""header-footer 명령 — 머리말/꼬리말 텍스트·쪽번호 설정."""
+from __future__ import annotations
+
+from hwpx_kit.adapter.hwpx_engine import HwpxEngineAdapter
+
+
+def run_header_footer(path: str, header: str | None, footer: str | None,
+                      page_number: str | None, out_path: str) -> dict:
+    ad = HwpxEngineAdapter.open(path)
+    applied = ad.set_header_footer(header=header, footer=footer,
+                                   page_number=page_number)
+    out = ad.save_copy(out_path)
+    return {"file": path, "out": out, "applied": applied}

hwpx_kit_cli-0.4.0/src/hwpx_kit/commands/image_add.py

@@ -0,0 +1,25 @@
+"""image-add 명령 — 이미지(사진·직인)를 문단 앵커 또는 표 셀에 삽입."""
+from __future__ import annotations
+
+from hwpx_kit.adapter.hwpx_engine import HwpxEngineAdapter
+
+
+def run_image_add(path: str, image_path: str, at_text: str | None,
+                  table: int | None, cell: str | None,
+                  width_mm: float, height_mm: float | None, out_path: str) -> dict:
+    if (at_text is None) == (cell is None):
+        raise ValueError("--at-text 또는 (--table + --cell) 중 정확히 하나를 지정하세요.")
+    cell_rc = None
+    if cell is not None:
+        try:
+            r, c = cell.split(",")
+            cell_rc = (int(r), int(c))
+        except ValueError:
+            raise ValueError(f"--cell 형식은 'R,C': {cell!r}") from None
+
+    ad = HwpxEngineAdapter.open(path)
+    info = ad.insert_image(image_path, at_text=at_text, table_index=table,
+                           cell=cell_rc, width_mm=width_mm, height_mm=height_mm)
+    out = ad.save_copy(out_path)
+    return {"file": path, "out": out, "image": image_path,
+            "inserted": True, **info}

hwpx_kit_cli-0.4.0/tests/test_image_header.py

@@ -0,0 +1,152 @@
+"""image-add / header-footer — 이미지 삽입·머리말/꼬리말/쪽번호.
+
+이미지는 엔진 add_image(바이너리 등록)+add_picture(문단 배치) 2단계 —
+저장 왕복 생존과 원본 불변이 계약. mm 크기는 hwpx 단위로 환산된다.
+"""
+import json
+
+import pytest
+
+# 1x1 투명 PNG
+PNG_1PX = bytes.fromhex(
+    "89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489"
+    "0000000d4944415478da63f8ffff3f0300050001ff5cccd90000000049454e44ae426082"
+)
+
+from hwpx_kit.cli import main
+from hwpx_kit.commands.header_footer import run_header_footer
+from hwpx_kit.commands.image_add import run_image_add
+
+
+@pytest.fixture()
+def doc_with_anchor(tmp_path):
+    from hwpx.document import HwpxDocument
+
+    from hwpx_kit.output import quiet_engine
+
+    with quiet_engine():
+        doc = HwpxDocument.new()
+        doc.add_paragraph("신청서")
+        doc.add_paragraph("서명: (인)")
+        t = doc.add_table(2, 2)
+        t.set_cell_text(0, 0, "사진")
+        path = str(tmp_path / "form.hwpx")
+        doc.save_to_path(path)
+    return path
+
+
+@pytest.fixture()
+def png_file(tmp_path):
+    p = tmp_path / "stamp.png"
+    p.write_bytes(PNG_1PX)
+    return str(p)
+
+
+def _image_count(path):
+    from hwpx.document import HwpxDocument
+
+    from hwpx_kit.output import quiet_engine
+
+    with quiet_engine():
+        return len(HwpxDocument.open(path).list_images())
+
+
+def test_image_add_at_text(doc_with_anchor, png_file, tmp_path):
+    out = str(tmp_path / "o.hwpx")
+    result = run_image_add(doc_with_anchor, image_path=png_file,
+                           at_text="서명: (인)", table=None, cell=None,
+                           width_mm=20, height_mm=None, out_path=out)
+    assert result["inserted"] is True
+    assert _image_count(out) == 1
+    assert _image_count(doc_with_anchor) == 0  # 원본 불변
+
+
+def test_image_add_into_table_cell(doc_with_anchor, png_file, tmp_path):
+    out = str(tmp_path / "o.hwpx")
+    result = run_image_add(doc_with_anchor, image_path=png_file,
+                           at_text=None, table=0, cell="1,0",
+                           width_mm=25, height_mm=30, out_path=out)
+    assert result["inserted"] is True
+    assert _image_count(out) == 1
+
+
+def test_image_add_validates_roundtrip(doc_with_anchor, png_file, tmp_path):
+    from hwpx_kit.commands.validate import run_validate
+
+    out = str(tmp_path / "o.hwpx")
+    run_image_add(doc_with_anchor, image_path=png_file,
+                  at_text="서명: (인)", table=None, cell=None,
+                  width_mm=20, height_mm=None, out_path=out)
+    assert run_validate(out)["valid"] is True
+
+
+def test_image_add_rejects_missing_anchor(doc_with_anchor, png_file, tmp_path):
+    with pytest.raises(ValueError, match="문단"):
+        run_image_add(doc_with_anchor, image_path=png_file,
+                      at_text="없는 문장", table=None, cell=None,
+                      width_mm=20, height_mm=None, out_path=str(tmp_path / "o.hwpx"))
+
+
+def test_image_add_rejects_bad_format(doc_with_anchor, tmp_path):
+    bad = tmp_path / "note.txt"
+    bad.write_text("텍스트")
+    with pytest.raises(ValueError, match="형식"):
+        run_image_add(doc_with_anchor, image_path=str(bad),
+                      at_text="서명: (인)", table=None, cell=None,
+                      width_mm=20, height_mm=None, out_path=str(tmp_path / "o.hwpx"))
+
+
+def test_cli_image_add(doc_with_anchor, png_file, tmp_path, capsys):
+    out = str(tmp_path / "o.hwpx")
+    code = main(["image-add", doc_with_anchor, "--image", png_file,
+                 "--at-text", "서명: (인)", "--width-mm", "20",
+                 "--out", out, "--json"])
+    env = json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+    assert code == 0 and env["ok"] is True
+    assert _image_count(out) == 1
+
+
+# ── header-footer ─────────────────────────────────────────────
+
+def _headers_footers(path):
+    from hwpx.document import HwpxDocument
+
+    from hwpx_kit.output import quiet_engine
+
+    with quiet_engine():
+        d = HwpxDocument.open(path)
+        return d.headers
+
+
+def test_header_footer_set(doc_with_anchor, tmp_path):
+    out = str(tmp_path / "o.hwpx")
+    result = run_header_footer(doc_with_anchor, header="문서관리번호 2026-01",
+                               footer=None, page_number=None, out_path=out)
+    assert "header" in result["applied"]
+    # 재열기 후에도 구조 유효 + 헤더 존재 (증발 회귀 감지)
+    from hwpx_kit.commands.validate import run_validate
+
+    assert run_validate(out)["valid"] is True
+    assert len(_headers_footers(out)) >= 1
+
+
+def test_page_number_set(doc_with_anchor, tmp_path):
+    out = str(tmp_path / "o.hwpx")
+    result = run_header_footer(doc_with_anchor, header=None, footer=None,
+                               page_number="center", out_path=out)
+    assert "page_number" in result["applied"]
+
+
+def test_header_footer_requires_one(doc_with_anchor, tmp_path):
+    with pytest.raises(ValueError):
+        run_header_footer(doc_with_anchor, header=None, footer=None,
+                          page_number=None, out_path=str(tmp_path / "o.hwpx"))
+
+
+def test_cli_header_footer(doc_with_anchor, tmp_path, capsys):
+    out = str(tmp_path / "o.hwpx")
+    code = main(["header-footer", doc_with_anchor, "--footer", "대외비",
+                 "--page-number", "center", "--out", out, "--json"])
+    env = json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+    assert code == 0 and env["ok"] is True
+    assert set(env["data"]["applied"]) == {"footer", "page_number"}