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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hwpx-kit-cli
-Version: 0.4.0
+Version: 0.5.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-186%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-193%20passing-brightgreen.svg)](tests/)
 
 </div>
 
@@ -204,11 +204,18 @@ templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커
 설계 불변 원칙: **① 원본 절대 수정 금지 ② `--json` stdout은 봉투 한 줄만
 ③ 서식은 항상 보존** (셀을 비워도 글자모양이 유지되어 재기입 시 원래 서식을 물려받음).
 
+## 민감정보 처리 (secure 모드)
+
+주민번호·계좌 같은 값은 **AI 모델을 거치지 않고** 채울 수 있습니다:
+사용자가 값 파일을 직접 작성 → 스킬은 경로만 전달 → `fill --secure`가 CLI에서만 읽어 채움.
+`--secure`는 하나라도 못 채우면 산출물 없이 실패하고(부분 채움 방지), 출력에 값을 노출하지 않습니다.
+제출 전 `inspect`로 개인정보 잔존(주민번호·전화·이메일 패턴)도 기계 검사할 수 있습니다.
+
 > 🚧 같은 코어를 MCP 서버로 노출하는 버전도 제작 중입니다 (Claude Desktop 등 MCP 클라이언트용).
 
 ## 검증
 
-- 자동 테스트 186개 (pytest)
+- 자동 테스트 193개 (pytest)
 - 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
   실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
 - 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.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-186%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-193%20passing-brightgreen.svg)](tests/)
 
 </div>
 
@@ -181,11 +181,18 @@ templates/ 기본 계획서 템플릿 (표지·장 헤더·표 골격, 마커
 설계 불변 원칙: **① 원본 절대 수정 금지 ② `--json` stdout은 봉투 한 줄만
 ③ 서식은 항상 보존** (셀을 비워도 글자모양이 유지되어 재기입 시 원래 서식을 물려받음).
 
+## 민감정보 처리 (secure 모드)
+
+주민번호·계좌 같은 값은 **AI 모델을 거치지 않고** 채울 수 있습니다:
+사용자가 값 파일을 직접 작성 → 스킬은 경로만 전달 → `fill --secure`가 CLI에서만 읽어 채움.
+`--secure`는 하나라도 못 채우면 산출물 없이 실패하고(부분 채움 방지), 출력에 값을 노출하지 않습니다.
+제출 전 `inspect`로 개인정보 잔존(주민번호·전화·이메일 패턴)도 기계 검사할 수 있습니다.
+
 > 🚧 같은 코어를 MCP 서버로 노출하는 버전도 제작 중입니다 (Claude Desktop 등 MCP 클라이언트용).
 
 ## 검증
 
-- 자동 테스트 186개 (pytest)
+- 자동 테스트 193개 (pytest)
 - 실서식 수렴 테스트: 보도자료·신청서·계획서·회의록·공고문 5계열,
   실제 공공기관 문서 30여 종으로 analyze→fill→validate 왕복
 - 실사용 시나리오 테스트 3회 (백지 생성 12분 완주, 장·표 동적 추가, 보도자료 변환)

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

@@ -1,6 +1,6 @@
 [project]
 name = "hwpx-kit-cli"
-version = "0.4.0"
+version = "0.5.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.4.0 → hwpx_kit_cli-0.5.0}/skills/hwpx-form/SKILL.md

@@ -157,6 +157,22 @@ CLI `hwpx-kit`으로 hwpx 문서를 다룬다. 항상 `--json`을 붙여 실행
    금지문자는 `_` 치환. 원본 불변은 fill과 동일
 5. 개인정보 든 명단 파일은 사용자 문서와 동일한 기밀 취급 — 커밋·업로드 금지
 
+## 민감정보(주민번호·계좌 등) 채우기 — secure 프로토콜
+
+주민번호·계좌·급여처럼 민감한 값이 들어가는 서식은 **값이 너(Claude)를 거치지
+않게** 처리한다:
+
+1. 사용자에게 값 JSON 파일을 **직접** 만들어 달라고 안내 (메모장 등):
+   `{"table:주민등록번호": "여기에 직접 입력", ...}` — 키 목록은 네가
+   analyze 결과로 만들어주되 **값은 비워서** 건넨다
+2. 파일을 받으면 **절대 Read하지 말고 경로만** 사용:
+   `hwpx-kit fill <양식> --data <값파일> --out <결과> --secure --json`
+   - --secure = 하나라도 못 채우면 산출물 없이 실패 (반쯤 채워진 개인정보
+     문서가 남지 않음), 출력 JSON에 값 비노출
+3. 채움 확인은 값을 보지 않고 간접으로: `inspect <결과> --checks residue`
+   (빈칸·마커 잔존 없음 = 전부 채워짐)
+4. 끝나면 값 파일 삭제를 사용자에게 권한다. 값 파일·결과물 모두 커밋·업로드 금지
+
 ## 사진·직인 넣기 — "여기 도장 찍어줘", "사진 붙여줘"
 
 `hwpx-kit image-add <문서.hwpx> --image <파일.png> ... --out <결과.hwpx>`

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.0}/skills/table-calc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: table-calc
-description: 보고서 표 수치 작업 — 증감(△·▲▽·↑↓·%·%p), 비율, 순번, 세자리 콤마, 합계·역합계 계산과 공무원 관습 표기. hwpx 표에 "증감 채워줘", "비율 계산해서 넣어줘", "합계 맞춰줘", "표 계산해줘" 요청 시 사용. Triggers: calculate table totals in Korean report style.
+description: 보고서 표 수치 작업 — 증감(△·▲▽·↑↓·%·%p), 비율, 순번, 세자리 콤마, 합계·역합계 계산과 공무원 관습 표기. hwpx 표에 "증감 채워줘", "비율 계산해서 넣어줘", "합계 맞춰줘", "표 계산해줘", "천원/백만원 단위로 바꿔줘" 요청 시 사용. Triggers: calculate table totals in Korean report style.
 ---
 
 # table-calc: 표 수치 계산·표기
@@ -36,6 +36,16 @@ description: 보고서 표 수치 작업 — 증감(△·▲▽·↑↓·%·%p),
 - **검산**: 채우기 전에 합계 행이 항목 합과 일치하는지 확인, 불일치하면 채우지
   말고 사용자에게 보고
 
+## 표 단위 변환 — "이 표 천원/백만원 단위로 바꿔줘"
+
+1. `table-map`으로 대상 표의 수치 셀 수집 (원 단위 원본 값)
+2. 셀마다 `hwpx-kit fmt --scale <원값> --unit 천원` (또는 백만원) — 사사오입
+   반올림+콤마를 도구가 보장 (암산 금지). 여러 값이면 fmt를 && 체이닝
+3. `table-set --data`로 일괄 기입 + 표 위/아래에 `(단위: 천원)` 캡션이 없으면
+   text: 교체나 table-set으로 추가 (캡션 위치는 문서 관례 — 보통 표 우측 상단)
+4. **검산**: 변환 후 합계 행 = 항목 합 (반올림 누적 오차로 ±1 어긋나면
+   합계 셀은 원값 합의 변환값으로 맞추고 사용자에게 알림)
+
 ## 착지 (문서에 쓰기)
 
 계산 결과는 hwpx-form 스킬의 fill 계약으로 셀에 넣는다 — 새 방식을 만들지 말 것:

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

@@ -50,6 +50,8 @@ def _build_parser() -> argparse.ArgumentParser:
     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("--secure", action="store_true",
+                    help="엄격 모드(민감정보용) — 하나라도 못 채우면 산출물 없이 실패, 출력에 값 비노출")
     pf.add_argument("--json", action="store_true")
 
     pr = sub.add_parser("read", help="본문을 Markdown/텍스트로 추출")
@@ -196,6 +198,8 @@ def _build_parser() -> argparse.ArgumentParser:
     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("--scale", help="원 단위 금액 → --unit 단위로 환산 (반올림·콤마)")
+    pt.add_argument("--unit", default="천원", choices=["천원", "백만원"], help="--scale 대상 단위 (기본 천원)")
     pt.add_argument("--json", action="store_true")
 
     return p
@@ -227,9 +231,16 @@ def main(argv: list[str] | None = None) -> int:
         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
+            if args.secure:
+                from hwpx_kit.commands.fill import run_fill_secure
+
+                data = run_fill_secure(args.file, mapping, args.out)
+                if not data["ok"]:
+                    exit_code = 1
+            else:
+                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":
@@ -240,6 +251,7 @@ def main(argv: list[str] | None = None) -> int:
             data = run_fmt(
                 amount=args.amount, date=args.date, age=args.age,
                 base=args.base, style=args.style,
+                scale=args.scale, unit=args.unit,
             )
         elif args.command == "row-height":
             data = run_row_height(

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.0}/src/hwpx_kit/commands/fill.py

@@ -77,6 +77,31 @@ def _apply_one(ad: HwpxEngineAdapter, fill_key: str, value: str) -> str | None:
     return "알 수 없는 fill_key 형식 (clickhere:/marker:/table:/text:/delete:/bold:/underline: 중 하나여야 함)"
 
 
+def run_fill_secure(path: str, data: dict[str, str], out_path: str) -> dict:
+    """엄격 모드 — 민감정보(PII) 채우기용.
+
+    ① 하나라도 못 채우면 산출물을 남기지 않는다 (반쯤 채워진 개인정보 문서 방지)
+    ② 결과에 값을 절대 노출하지 않는다 — 키 목록·개수만.
+    값 파일은 CLI만 읽는 것이 전제 (스킬 규약: Claude는 경로만 전달).
+    """
+    import os as _os
+
+    result = run_fill(path, data, out_path)
+    if result["unmatched"]:
+        try:
+            _os.remove(result["out"])
+        except OSError:
+            pass
+        return {
+            "ok": False,
+            "out": None,
+            "applied_count": len(result["applied"]),
+            "unmatched_keys": [u["key"] for u in result["unmatched"]],
+            "reason": "일부 키를 채우지 못해 산출물을 만들지 않았습니다 (--secure 엄격 모드)",
+        }
+    return {"ok": True, "out": result["out"], "applied_count": len(result["applied"])}
+
+
 def run_fill(path: str, data: dict[str, str], out_path: str) -> dict:
     ad = HwpxEngineAdapter.open(path)
     applied: list[str] = []

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.0}/src/hwpx_kit/commands/fmt.py

@@ -4,7 +4,7 @@
 """
 from __future__ import annotations
 
-from hwpx_kit.format import format_amount, gongmun_date, korean_age
+from hwpx_kit.format import format_amount, gongmun_date, korean_age, scale_amount
 
 
 def run_fmt(
@@ -13,10 +13,20 @@ def run_fmt(
     age: str | None = None,
     base: str | None = None,
     style: str = "gongmun",
+    scale: str | None = None,
+    unit: str = "천원",
 ) -> dict:
-    targets = [k for k, v in (("amount", amount), ("date", date), ("age", age)) if v is not None]
+    targets = [k for k, v in (("amount", amount), ("date", date), ("age", age),
+                              ("scale", scale)) if v is not None]
     if len(targets) != 1:
-        raise ValueError("--amount / --date / --age 중 정확히 하나를 지정하세요.")
+        raise ValueError("--amount / --date / --age / --scale 중 정확히 하나를 지정하세요.")
+
+    if scale is not None:
+        cleaned = scale.replace(",", "").strip()
+        if not cleaned.isdigit():
+            raise ValueError(f"금액은 정수여야 합니다: {scale}")
+        return {"kind": "scale", "input": scale, "unit": unit,
+                "result": scale_amount(int(cleaned), unit)}
 
     if amount is not None:
         cleaned = amount.replace(",", "").strip()

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.0}/src/hwpx_kit/format.py

@@ -92,3 +92,21 @@ def korean_age(yymmdd: str, base: str | None = None) -> str:
     if age < 0:
         raise ValueError("기준일이 생년월일보다 앞섭니다.")
     return f"{digits}({age})"
+
+
+_SCALE_UNITS = {"천원": 1_000, "백만원": 1_000_000}
+
+
+def scale_amount(won: int, unit: str) -> str:
+    """원 단위 금액 → 천원/백만원 단위 문자열 (반올림, 세 자리 콤마).
+
+    예산표 "단위: 천원" 관습용. 반내림이 필요한 특수 규정은 호출자가 처리.
+    """
+    from decimal import ROUND_HALF_UP, Decimal
+
+    divisor = _SCALE_UNITS.get(unit)
+    if divisor is None:
+        raise ValueError(f"지원 단위: {', '.join(_SCALE_UNITS)} (받은 값: {unit})")
+    # 파이썬 round()는 은행가 반올림(0.5→0) — 행정 관습은 사사오입(0.5→1)
+    scaled = int((Decimal(won) / Decimal(divisor)).quantize(Decimal(1), rounding=ROUND_HALF_UP))
+    return f"{scaled:,}"

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.0}/tests/test_fill_batch.py

@@ -151,3 +151,52 @@ def test_cli_fill_batch(cert_form, roster_json, template_json, tmp_path, capsys)
     assert code == 0
     assert env["ok"] is True
     assert env["data"]["succeeded"] == 3
+
+
+# ── fill --secure (엄격 모드) ─────────────────────────────────
+
+def test_fill_secure_strict_no_partial(cert_form, tmp_path):
+    """--secure: 하나라도 못 채우면 산출물을 남기지 않는다 (반쯤 채워진 PII 문서 방지)."""
+    import os
+
+    from hwpx_kit.commands.fill import run_fill_secure
+
+    out = str(tmp_path / "o.hwpx")
+    result = run_fill_secure(cert_form, {"marker:성명": "김철수", "marker:없는키": "x"}, out)
+    assert result["ok"] is False
+    assert not os.path.exists(out)          # 부분 산출물 없음
+    # 실패 사유에 값이 노출되지 않는다
+    import json as _json
+
+    assert "김철수" not in _json.dumps(result, ensure_ascii=False)
+
+
+def test_fill_secure_success(cert_form, tmp_path):
+    import os
+
+    from hwpx_kit.commands.fill import run_fill_secure
+
+    out = str(tmp_path / "o.hwpx")
+    result = run_fill_secure(cert_form, {"marker:성명": "김철수", "marker:과정명": "AI"}, out)
+    assert result["ok"] is True and os.path.exists(out)
+    assert result["applied_count"] == 2
+    # 값 자체는 결과 JSON에 없음
+    import json as _json
+
+    assert "김철수" not in _json.dumps(result, ensure_ascii=False)
+
+
+def test_cli_fill_secure(cert_form, tmp_path, capsys):
+    import json as _json
+
+    from hwpx_kit.cli import main
+
+    values = tmp_path / "v.json"
+    values.write_text(_json.dumps({"marker:성명": "김철수", "marker:과정명": "AI"},
+                                  ensure_ascii=False), encoding="utf-8")
+    out = str(tmp_path / "o.hwpx")
+    code = main(["fill", cert_form, "--data", str(values), "--out", out,
+                 "--secure", "--json"])
+    captured = capsys.readouterr().out
+    assert code == 0
+    assert "김철수" not in captured          # stdout에 값 비노출

{hwpx_kit_cli-0.4.0 → hwpx_kit_cli-0.5.0}/tests/test_format.py

@@ -144,3 +144,42 @@ def test_cli_fmt_requires_exactly_one(capsys):
     env = _last_json(capsys)
     assert code == 1
     assert env["ok"] is False
+
+
+# ── 표 단위 변환 (천원/백만원) ────────────────────────────────
+
+def test_scale_amount_to_cheonwon():
+    from hwpx_kit.format import scale_amount
+
+    # 관습: 반올림, 세 자리 콤마
+    assert scale_amount(1234567, "천원") == "1,235"
+    assert scale_amount(1000, "천원") == "1"
+    assert scale_amount(37000000, "천원") == "37,000"
+
+
+def test_scale_amount_to_baekmanwon():
+    from hwpx_kit.format import scale_amount
+
+    assert scale_amount(37000000, "백만원") == "37"
+    assert scale_amount(1234567890, "백만원") == "1,235"
+    assert scale_amount(500000, "백만원") == "1"   # 반올림 올라감
+
+
+def test_scale_amount_rejects_unknown_unit():
+    import pytest as _pytest
+
+    from hwpx_kit.format import scale_amount
+
+    with _pytest.raises(ValueError):
+        scale_amount(1000, "억원")
+
+
+def test_cli_fmt_scale(capsys):
+    import json as _json
+
+    from hwpx_kit.cli import main
+
+    code = main(["fmt", "--scale", "1,234,567", "--unit", "천원", "--json"])
+    env = _json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+    assert code == 0
+    assert env["data"]["result"] == "1,235"