Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI 레퍼런스

hwpforge(Hammer)는 HwpForge의 명령줄 도구입니다. 이 장은 hwpforge --help와 hwpforge <명령> --help가 보여 주는 23개 명령을 정리합니다. 플래그 이름과 기본값은 clap 정의(crates/hwpforge-bindings-cli/src/main.rs)를 그대로 옮겼으므로, 버전이 올라 의심스러우면 --help가 우선입니다.

설치

hwpforge-bindings-cli는 crates.io에 배포하지 않으므로(publish = false) git 또는 로컬 경로에서 설치합니다. hwpforge-smithy-pdf(krilla) 의존 때문에 워크스페이스 MSRV(1.89)보다 높은 Rust 1.92 이상이 필요합니다(rust-version = "1.92").

cargo install --git https://github.com/ai-screams/HwpForge hwpforge-bindings-cli

# 또는 clone 후 로컬 경로에서
git clone https://github.com/ai-screams/HwpForge && cd HwpForge
cargo install --path crates/hwpforge-bindings-cli

설치되는 바이너리 이름은 hwpforge입니다([[bin]] name = "hwpforge").

전역 옵션

옵션설명
--json결과를 machine-readable JSON으로 출력합니다
-h, --help도움말
-V, --version버전

--json은 모든 명령이 받습니다. 에이전트가 결과를 파싱할 때는 이 플래그를 붙이세요.

명령 한눈에 보기

--help는 HWP5·PDF 명령을 먼저 나열하고 그 뒤에 HWPX 명령을 나열합니다. 아래 표는 용도별로 다시 묶었습니다.

용도명령
HWP5 · PDFaudit-hwp5, census-hwp5, convert-hwp5, to-pdf
만들기 · 변환convert, to-json, from-json, to-md
읽기 · 검사inspect, outline, fields, read, diff, validate
편집fill, set-cell, patch, insert-para, delete-para, stamp-plan, stamp
부가templates, schema

HWP 입력과 HWPX 출력

다음 14개 명령은 HWPX와 HWP5(.hwp) 입력을 받습니다. HWP5는 메모리에서 HWPX로 변환한 뒤 기존 연산에 전달합니다. 확장자가 아니라 내용으로 판별하며, 정상 ZIP으로 열리는 접두사 HWPX는 그대로 처리합니다.

용도명령
읽기·검사inspect, outline, read, fields, to-md, to-json, validate, diff(양쪽 입력), stamp-plan
편집fill, set-cell, insert-para, delete-para, stamp

편집 문서 결과는 **.hwpx**입니다. .hwp 저장은 지원하지 않으며, 편집 5개 명령은 .hwp 출력 확장자를 대소문자 구분 없이 INVALID_EXTENSION으로 거부합니다. 읽기 명령의 JSON·Markdown 출력 형식은 그대로입니다.

hwpforge inspect form.hwp --json
hwpforge fill form.hwp --set name=홍길동 -o form.filled.hwpx --json

변환 손실 정책

읽기 명령은 변환 경고를 보고합니다. 편집 5개 명령은 의미 손실이 있으면 쓰기 전에 HWP5_CONVERSION_LOSS로 거부합니다. 거부된 경고를 확인한 뒤 --accept-conversion-loss로 변환 손실을 명시적으로 허용합니다. 이 옵션은 편집 자체의 admission 검사나 인코드 의미 손실 거부(ENCODE_SEMANTIC_LOSS)를 해제하지 않습니다.

글꼴 분류 정보(style.font.type_info)와 메모 모양 정의(header.memo_shape_definition)의 생략은 정책상 비손실이며 경고는 남습니다. 시각적으로 차이가 없다는 보장은 아닙니다. 조판 캐시 생략도 의미 손실 거부 대상이 아닙니다. 개요 번호 모양 참조(section.outlineShapeIDRef), 변경 추적 정의, 중첩 구역 설정, 언어별 장평, 자동 간격과 미분류 경고는 손실로 취급합니다.

변환 메타데이터

HWP5_CONVERSION_LOSS의 JSON details.warnings는 거부된 경고만 담으며, 각 항목은 stage, code, message와 선택적인 location을 갖습니다. 성공 JSON은 기존 warnings의 형과 내용을 유지하고, HWP5 입력일 때만 별도 conversion: {source_format: "hwp5", warnings: [...]}를 더합니다. 변환 경고가 없어도 conversion.warnings는 빈 배열입니다.

diff는 conversion.base·conversion.revised에 변환된 입력의 메타데이터만 담습니다. diff -o 보고서 본문과 to-json·to-md의 문서 본문에는 변환 메타데이터를 섞지 않습니다. 사람용 모드는 표준 오류로 변환 사실과 경고를 알리고, --json 모드는 결과 메타데이터로 전달합니다.

HWP 원본 보호

HWP5 입력을 자동 변환한 경우, 이미 있는 출력 파일이 입력과 같은 파일이면 INVALID_OUTPUT_PATH(종료 1)로 쓰기 전에 거부합니다. 편집 5개 명령의 문서 출력과 stamp의 manifest뿐 아니라 diff -o(양쪽 입력), to-json -o, to-md의 Markdown·추출 이미지 출력에도 적용합니다. 상대·절대 경로, 심볼릭 링크, 하드 링크와 대소문자를 구분하지 않는 파일 시스템의 별칭도 파일 정체성으로 비교합니다.

아직 없는 출력은 이 비교로 거부하지 않습니다. 정체성 확인 실패는 FILE_WRITE_FAILED이며 insert-para·delete-para는 종료 2, 나머지 자동 변환 대상 명령은 종료 1입니다. HWPX 입력의 제자리 편집은 계속 허용합니다. 실행 도중 다른 프로세스가 경로를 바꾸는 경우는 보호 범위에 포함하지 않습니다.

자동 변환 제외 경로

CLI from-json --base·patch, Python from_json(base=...)·patch·restyle과 MCP의 문서 입력(restyle 포함)은 HWP5를 자동 변환하지 않으며 HWP5_INPUT으로 거부합니다. 이 경로에는 convert-hwp5 또는 Python convert_hwp5로 명시적으로 변환한 HWPX를 전달합니다. Python의 지원 연산과 저장 보호는 Python 입력 정책을 참고합니다.

자동 변환 도입은 오류 코드 계약의 breaking change입니다. 대상 명령의 HWP5 입력은 기존 HWP5_INPUT 대신 변환 결과 또는 HWP5_DECODE_FAILED, HWP5_CONVERT_FAILED, VALIDATION_FAILED, ENCODE_FAILED를 반환합니다. 변환 실패는 기존 연산의 인자 검사보다 먼저이며, 변환 손실 거부는 기존 편집 검사 다음이면서 쓰기 전입니다. 기존 코드의 명령별 종료 값은 유지합니다(set-cell의 validation/encode 오류는 1, 나머지 변환 오류는 2). .hwp 출력 거부도 기존 동작의 변경입니다.

HWP5 · PDF

convert-hwp5

HWP5(.hwp)를 HWPX로 변환합니다.

hwpforge convert-hwp5 [OPTIONS] --output <OUTPUT> <INPUT>
옵션설명
-o, --output출력 HWPX 경로(필수)
--no-layout-cacheHWP5의 조판 캐시(PARA_LINE_SEG)를 싣지 않습니다. 줄 나눔은 여는 쪽이 다시 계산합니다

기본값은 조판 캐시를 HWPX <hp:linesegarray>로 싣습니다. 그래서 결과가 원본의 줄 나눔 자리를 담고 to-pdf의 렌더 대상이 됩니다. 줄 시작 자리를 정확히 옮길 수 없는 문단(차트, 알 수 없는 컨트롤, 경계로 가를 수 없는 줄 시작)은 잘못된 데이터를 싣는 대신 LAYOUT_CACHE_DROPPED 경고와 함께 캐시를 버립니다. 예전 옵션 --carry-layout-cache는 계속 받지만 기본값과 같은 출력을 내며, --no-layout-cache와 함께 줄 수 없습니다.

to-pdf

HWPX 또는 HWP5 문서를 조판 캐시 재생 방식으로 PDF로 렌더합니다. 입력 형식은 확장자가 아니라 내용으로 판별합니다.

hwpforge to-pdf [OPTIONS] <INPUT>
옵션설명
-o, --output출력 PDF 경로(기본값: 입력 경로의 확장자를 .pdf로 바꾼 것)
--font-dir <FONT_DIRS>폰트를 찾을 디렉터리(반복 가능)
--discovery <DISCOVERY>폰트 자동 탐색: explicit(결정적, 기본값) | hancom | platform
--degraded렌더 실패를 오류 대신 경고로 낮춥니다. 없는 스타일·축 폰트는 regular로 그리고, 렌더할 수 없는 이미지는 건너뜁니다
--partial-cache-reject조판 캐시가 없는 문단이 하나라도 있으면 문서를 거부합니다(기본값: 경고 후 그 문단을 건너뜀)

조판 캐시가 있는 문서만 렌더할 수 있습니다. convert나 --base 없는 from-json이 새로 만든 문서에는 캐시가 없어 거부됩니다. from-json --base는 믿을 수 있는 바뀌지 않은 캐시만 이어받습니다.

audit-hwp5

HWP5 원본과 변환된 HWPX 결과의 구조·의미 동등성을 점검합니다. 픽셀 단위 시각·쪽 나눔 동등성은 보장하지 않으며, 후속 시각 검증용 체크리스트를 보고서에 담습니다.

hwpforge audit-hwp5 [OPTIONS] <SOURCE> <RESULT>

<SOURCE>는 원본 .hwp, <RESULT>는 변환된 .hwpx입니다.

census-hwp5

HWP5 파일(과 선택적 HWPX 짝 파일)의 원시 fixture census를 만듭니다.

hwpforge census-hwp5 [OPTIONS] <INPUT>
옵션설명
--companion <COMPANION>중첩 XML·경로 census용 HWPX 짝 fixture(선택)
-o, --outputcensus 데이터셋을 JSON으로 저장할 경로(선택)

만들기 · 변환

convert

Markdown을 HWPX로 변환합니다.

hwpforge convert [OPTIONS] --output <OUTPUT> <INPUT>
옵션설명
<INPUT>Markdown 파일. -를 주면 stdin에서 읽습니다
-o, --output출력 HWPX 경로(필수)
--preset <PRESET>스타일 프리셋 이름(기본값: default)

사용 가능한 프리셋은 templates list로 확인합니다.

to-json

HWPX 또는 HWP5를 편집 가능한 JSON으로 내보냅니다.

hwpforge to-json [OPTIONS] --output <OUTPUT> <FILE>
옵션설명
-o, --output출력 JSON 경로(필수, stdout 내보내기는 없습니다)
--section <SECTION>특정 섹션만 추출(0부터 시작하는 인덱스)
--no-styles스타일 정보를 제외합니다

--section 없이 내보낸 문서 전체 JSON은 from-json이, --section N으로 내보낸 섹션 JSON은 patch가 읽습니다. 두 JSON은 서로 다른 형식입니다.

두 JSON 모두 맨 위에 "format_version": 3 를 쓰고, 문단 여백 다섯 가지(margin_left, margin_right, indent, spacing_before, spacing_after)와 탭 위치(position)를 단위와 값으로 씁니다. hwpunit 은 1/100 pt, char 는 1/500 글자입니다.

"margin_left": { "unit": "hwpunit", "value": 2000 },
"indent": { "unit": "char", "value": -1000 }

from-json 과 patch 는 이전 판이 쓴 버전 없는 JSON 을 이렇게 다룹니다.

  • 탭 위치가 하나라도 있으면 LEGACY_JSON_TABS 로 거부합니다. 옛 JSON 에는 탭 단위가 남아 있지 않아 추측하지 않습니다.
  • 탭 위치가 없으면 문단 여백을 옛 표현에서 풀어 읽고 LEGACY_PARAGRAPH_MEASURES 경고를 냅니다. 옛 JSON 이 이미 잃은 단위는 되살리지 못합니다.
  • 명시 v2는 문단 style_id를 정의 배열 위치로 해석해 v3로 이행합니다. 그 밖의 버전 번호나 정수가 아닌 format_version 은 거부합니다.

어느 경우든 원본 HWPX 또는 HWP5 에서 새 판의 to-json 을 다시 실행하는 것이 가장 정확합니다.

스타일 글자 모양의 그림자는 0.17.0 부터 shadow 객체로 나옵니다(이전 키 shadow_type 은 종류만 담았습니다).

"shadow": { "kind": "Continuous", "color": "#123456", "offset_x": -3, "offset_y": 4 }

color 는 "#RRGGBB" 또는 "none" 입니다. 이전 판이 쓴 "shadow_type": "Drop" JSON 도 from-json 이 읽고, 이때 색·간격은 기본값 #C0C0C0·10·10 이 됩니다(이전 출력 #B2B2B2 보다 밝음).

from-json

JSON을 HWPX로 되돌립니다.

hwpforge from-json [OPTIONS] --output <OUTPUT> <INPUT>
옵션설명
-o, --output출력 HWPX 경로(필수)
--base <BASE>이미지를 물려받을 기준 HWPX(왕복 충실도용)

to-md

HWPX 또는 HWP5를 Markdown으로 변환합니다.

hwpforge to-md [OPTIONS] <INPUT>
옵션설명
-o, --output출력 디렉터리(기본값: 입력과 같은 디렉터리)
--mode <MODE>styled(기본값, 스타일을 따르고 이미지 포함) | lossy(스타일 정보 없는 읽기용) | lossless(보존 범위를 확인하는 기계용 보기. 보존 범위의 보존 목록은 보존, 거부 목록에 든 개체가 있으면 오류, 그 밖의 값은 빠질 수 있음. 프론트매터에 metadata.format: lossless 가 붙고 convert 는 이 출력을 MD_DECODE_FAILED 로 거부하므로, 왕복 편집에는 to-json/from-json 을 사용)

읽기 · 검사

inspect

HWPX 또는 HWP5 문서를 디코드한 구조를 보여 줍니다. HWP5 입력의 변환 경고는 별도로 보고합니다.

hwpforge inspect [OPTIONS] <FILE>
옵션설명
--styles스타일 상세(문자·문단 모양)를 포함합니다

outline

문서의 내비게이션 맵(제목, 표, 이름 있는 누름틀, 책갈피)을 보여 줍니다. 이름 앵커(제목 텍스트, 표 순번, 필드·책갈피 이름)가 1차 키이고 {section, para} 위치는 구조 편집 뒤에 낡을 수 있으므로, 읽기·편집 전에 한 번 받아 두는 용도입니다.

hwpforge outline [OPTIONS] <FILE>

fields

이름 있는 누름틀(click-here field)과 각각이 채울 수 있는 필드인지 나열합니다.

hwpforge fields [OPTIONS] <FILE>

read

문서 전체를 내보내지 않고 목표 하나만 텍스트로 읽습니다. 목표는 정확히 하나만 지정합니다.

hwpforge read [OPTIONS] <FILE>
옵션설명
--section <SECTION>문단을 읽을 섹션 인덱스
--paras <PARAS>닫힌 문단 범위 "A..B" 또는 단일 "N"(--section 필요)
--table <TABLE>표 순번. 논리 격자 텍스트 행렬로 읽습니다(병합 영역은 앵커에 한 번, span과 함께)
--field <FIELD>이름 있는 누름틀 하나

텍스트가 아닌 내용(표, 이미지, 컨트롤)은 조용히 버려지지 않고 명시적인 표지로 드러납니다. 읽기 전용입니다.

diff

HWPX 또는 HWP5 입력 둘을 두 채널로 비교해 편집이 실제로 무엇을 바꿨는지 확인합니다.

hwpforge diff [OPTIONS] <BASE> <REVISED>
옵션설명
-o, --output전체 JSON 보고서를 이 경로에도 씁니다

semantic 채널은 디코드한 Core 구조를 필드 값, 표 셀 텍스트 {table, row, col}, 문단 텍스트 {section, para}, 구조 개수, 상한이 있는 미분류 잔여로 분류합니다. package 채널은 ZIP 엔트리를 바이트로 비교합니다. 바뀐 엔트리 안의 wire 내용(예: hp:linesegarray 조판 캐시)은 항목별로 나열하지 않으며 보고서가 그렇게 밝힙니다. fill·set-cell·stamp·patch 뒤에 돌려 의도한 변경만 반영됐는지 확인하세요.

validate

HWPX 또는 HWP5가 디코드되고 Core의 구조 불변식(Document::validate)을 만족하는지 편집 없이 검사합니다.

hwpforge validate [OPTIONS] <FILE>

종료 코드는 --help에 다음과 같이 정의돼 있습니다.

종료 코드의미
0문서가 유효합니다
1파일을 읽을 수 없음(없거나 읽을 수 없거나 크기 상한을 넘는 파일)
2명령행 인자가 잘못됐거나 디코드·HWP5 변환에 실패합니다
3디코드는 되지만 검증에 실패합니다(오류가 아니라 판정이며, --json 출력의 errors를 보세요). 파서는 통과하고 Core 중첩 깊이가 32를 넘는 문서는 디코드에서 거부되므로 3이 아니라 DECODE_FAILED(종료 2)입니다

인자를 잘못 준 경우(필수 인자 누락, 알 수 없는 옵션)는 clap이 종료 코드 2로 끝냅니다. 아래 오류 계약은 다른 명령의 종료 정책도 함께 설명합니다.

편집

fill·set-cell·insert-para·delete-para·stamp는 HWP5 입력의 의미 손실을 기본 거부합니다. 공통 옵션 --accept-conversion-loss는 변환 손실만 허용하며 편집 문서 출력은 .hwpx입니다. 자세한 내용은 입력 정책을 참고합니다.

fill·set-cell·insert-para·delete-para·stamp·patch는 결과를 -o로 지정한 출력 경로에 씁니다(필수 옵션). stamp-plan은 파일을 쓰지 않으므로 -o가 없습니다. 편집 뒤에는 diff로 변경 범위를 확인하세요.

fill

이름 있는 누름틀을 값으로 채웁니다. 기존 한컴 미리보기가 있던 문서에서 내용을 실제로 바꾸면 미리보기(Preview)를 지우고 PREVIEW_REMOVED 경고를 냅니다. 한컴에서 다시 저장하면 미리보기가 다시 만들어집니다. 내용이 같으면 원본 파일을 돌려줍니다. 머리글 정규화·스타일 정의 변경 등 문서 재인코드가 필요하거나 이전 형식의 문서 전체 JSON을 쓰는 경우는 이 보장 밖입니다.

hwpforge fill [OPTIONS] --output <OUTPUT> <FILE>
옵션설명
--set <NAME=VALUE>채울 이름=값 쌍(반복 가능). 하나 이상 필수
-o, --output출력 HWPX 경로(필수)

요청한 값을 모두 먼저 검증(알 수 없는·중복된·채울 수 없는 이름, 빈 값)하고, 하나라도 실패하면 아무것도 쓰지 않습니다. 누름틀이 들어 있는 서식 문서에서만 동작하므로 convert로 막 만든 문서에는 필드가 없습니다. 이름은 fields로 먼저 확인하세요.

set-cell

요청한 모든 칸이 본문 직속 표의 한 문단·한 텍스트 run(빈 run 포함)이고 원문 위치와 header 보존을 확인할 수 있으면 텍스트 슬롯만 바꿉니다. 문단·표 속성과 슬롯 밖 미해석 원문은 유지합니다. 실제 값이 바뀌면 기존 Preview와 연결을 제거하고 PREVIEW_REMOVED를 알리며, 같은 값은 원본 바이트를 반환합니다. 입력 경고는 한 번 남으며 header 수선을 뜻하지 않습니다. 한 칸이라도 이 범위 밖이거나 텍스트 치환을 지원하지 않으면 파일 전체에 기존 왕복 안전성·패키지 보존 검사와 재인코드를 적용합니다. 주소 오류와 검증 실패는 오류로 끝납니다.

표 셀을 논리 격자 주소로 편집하며, batch는 전부 성공하거나 아무것도 쓰지 않습니다.

hwpforge set-cell [OPTIONS] --output <OUTPUT> <FILE>
옵션설명
--table <TABLE>표 순번(문서 순서, 0부터). 단일 편집에는 필수(--map 일괄 편집에서는 쓰지 않음)
--at <R,C>격자 좌표 "row,col"(덮인 위치는 병합 앵커로 해석)
--right-of <LABEL>유일하게 라벨된 셀의 오른쪽 셀을 대상으로 합니다
--below <LABEL>유일하게 라벨된 셀의 아래쪽 셀을 대상으로 합니다
--text <TEXT>바꿀 텍스트(빈 문자열은 셀을 비웁니다). 단일 편집에는 필수
--map <MAP_JSON>일괄 편집용 명세 맵(CellSpec JSON 배열). 위 플래그들과 함께 쓸 수 없습니다
-o, --output출력 HWPX 경로(필수)

patch

기존 HWPX의 섹션 하나를 교체합니다.

hwpforge patch [OPTIONS] --section <SECTION> --output <OUTPUT> <BASE> <SECTION_JSON>

<SECTION_JSON>은 to-json --section N으로 내보낸 섹션 JSON이며, <BASE>가 이미지와 나머지 패키지의 기준입니다. 문서 전체 JSON을 넣으면 스키마 불일치로 거부됩니다. 구조(문단 수)를 바꾸려면 insert-para·delete-para나 from-json을 쓰세요.

insert-para

기준 문단 앞이나 뒤에 새 최상위 문단을 삽입합니다. 관련 없는 내용을 유지하며, 영향을 받는 조판 캐시를 고칩니다. 한컴 저장 문서는 아래 사전 검사에서 거부됩니다.

hwpforge insert-para [OPTIONS] --section <SECTION> --anchor <ANCHOR> --text <TEXTS> --output <OUTPUT> <FILE>
옵션설명
--section <SECTION>섹션 인덱스
--anchor <ANCHOR>기준 문단 인덱스(새 문단이 이 문단의 문단·문자 모양을 그대로 물려받습니다)
--before기준 앞에 삽입합니다(기본값은 뒤)
--text <TEXTS>새 문단의 한 줄 일반 텍스트. 반복하면 연속된 블록을 한 번의 검증된 편집으로 삽입합니다
-o, --output출력 HWPX 경로(필수)

섹션의 첫 문단(secPr를 담은 문단) 앞 삽입은 거부됩니다. 왕복 안전한 입력만 편집할 수 있습니다.

delete-para

최상위 본문 문단을 인덱스로 삭제합니다. 전부 성공하거나 전부 취소됩니다. 한컴 저장 HWPX에서도 검증 가능한 최상위 본문 평문·빈 문단을 삭제할 수 있습니다. 문단 번호는 입력 문서의 위치 기준입니다. 원문 보존 경로는 한 요청에 한 문단을 받아 대상 문단만 제거하며, 생존 문단의 줄 조판 캐시·표 높이·ID와 관련 없는 부속 데이터를 유지합니다. 위치에 따라 줄 폭이 바뀔 수 있는 문서는 원래 admission 오류로 거부합니다. 기존 Preview와 관련 연결은 제거하고 PREVIEW_REMOVED를 알립니다. 한컴에서 다시 저장하면 미리보기가 만들어집니다. 검증할 수 없는 입력은 기존 오류로 거부하며 출력하지 않습니다.

CONTENT_LOST는 입력을 Core로 읽을 때 표현하지 못한 정보가 있다는 경고입니다. 원문 보존 삭제는 그 정보가 출력 원문에 보존되고 삭제 판정에 영향을 주지 않음을 별도로 확인한 경우에만 성공하며, 입력 decode 경고는 순서와 횟수 그대로 남습니다. 이는 원문 XML에 정보가 남는 일부 손실(예: 언어별 글자 값)에만 해당하며, 그 밖의 CONTENT_LOST 입력은 기존 거부를 유지합니다. 전체 재인코드 편집의 입력 손실 거부는 유지됩니다.

hwpforge delete-para [OPTIONS] --section <SECTION> --output <OUTPUT> <FILE>
옵션설명
--section <SECTION>섹션 인덱스
--index <INDICES>...삭제할 최상위 문단 인덱스(일괄 삭제는 반복). 하나 이상 필수
-o, --output출력 HWPX 경로(필수)

참조(책갈피·상호참조·각주 등)를 담은 문단, 강제 쪽·단 나눔이 있는 문단, 섹션 속성(secPr)을 담은 첫 문단, 삭제하면 섹션이 비게 되는 경우는 거부합니다(fail-closed).

stamp-plan

산문 속 자리표시자(체크박스, 괄호 빈칸, 날짜 빈칸, 단독 @, 도장 토큰) 후보를 찾아 템플릿 스탬핑 계획을 만듭니다.

hwpforge stamp-plan [OPTIONS] <FILE>

출력의 각 후보에 {"field":{"name":"…"}} 또는 "ignore" 액션을 붙여 명세 맵을 만든 뒤 stamp --map을 실행합니다. 지침 문맥의 후보(guarded)는 자동 적용되지 않습니다.

stamp

명세 맵을 적용해 자리표시자를 이름 있는 누름틀로 승격합니다. 전부 성공하거나 전부 취소되며, 스탬프된 HWPX와 매니페스트를 씁니다.

hwpforge stamp [OPTIONS] --map <MAP_JSON> --output <OUTPUT> <FILE>
옵션설명
--map <MAP_JSON>StampSpec JSON 배열(필수)
-o, --output출력 HWPX 경로(필수)
--manifest <MANIFEST>매니페스트 JSON 경로(기본값: <output>.manifest.json)

실패 시 아무것도 쓰지 않는 admission 게이트(무변경 왕복 + ZIP 닫힌 세계 검사) 뒤에서 동작하고, 결과물은 곧바로 fields·fill에 쓸 수 있습니다.

부가

templates

스타일 프리셋을 관리합니다. 하위 명령은 두 개입니다.

hwpforge templates list            # 사용 가능한 프리셋 목록
hwpforge templates show <NAME>     # 프리셋 상세

schema

문서·스타일 타입의 JSON Schema를 출력합니다.

hwpforge schema [OPTIONS] [TYPE_NAME]

TYPE_NAME은 document(기본값), exported-document, exported-section 중 하나입니다. exported-document가 to-json의 전체 JSON, exported-section이 --section JSON의 형식입니다.

다음 단계

0.18 오류 코드와 종료 상태

CLI JSON의 code, MCP 도구 오류의 code, Python HwpForgeError.code는 같은 실패 단계와 도메인 거부 사유에 같은 OpsCode 문자열을 사용합니다. 여러 결함이 있으면 실제로 먼저 실패한 검사로 분류하며, 메시지·힌트·응답 봉투까지 같다는 뜻은 아닙니다. 퇴역 별명과 옛 문자열 lookup은 제공하지 않습니다.

실패 단계·원인코드
보류 명령의 HWPX 입력에 HWP5(.hwp)를 전달HWP5_INPUT (종료 2)
HWP5 변환의 의미 손실로 편집 거부HWP5_CONVERSION_LOSS (종료 1)
편집 문서 출력이 .hwpINVALID_EXTENSION (종료 1)
편집 문서·manifest 또는 diff·to-json·to-md 출력이 HWP5 입력과 같은 파일INVALID_OUTPUT_PATH (종료 1)
입력 HWPX / Markdown / HWP5 해석DECODE_FAILED / MD_DECODE_FAILED / HWP5_DECODE_FAILED
편집 전 no-op 검증·인코드·재디코드 또는 의미 왕복 불일치INPUT_NOT_ROUNDTRIP_SAFE
입력 ZIP 엔트리 미보존INPUT_ENTRIES_NOT_CARRIED
명시적 문서 검증·메모리 문서 깊이 검사VALIDATION_FAILED
출력 생성 / 의미 손실 때문에 출력 거부ENCODE_FAILED / ENCODE_SEMANTIC_LOSS
생성 산출물 읽기·재디코드·대조SELF_VERIFY_FAILED
보호 필드 침범 / 내부 불변식 파손PROTECTED_FIELD_RANGE / INTERNAL_INVARIANT
보존 patch의 변경·metadata 거부 / fill 고유 거부PATCH_FAILED / FILL_FAILED
아직 분류하지 않은 상류 variantUPSTREAM_UNMAPPED

HWP5_INPUT이면 먼저 hwpforge convert-hwp5 <in.hwp> -o <out.hwpx>로 변환하세요. 확장자가 아닌 내용으로 판정하며, ZIP으로 열리는 접두사 HWPX는 이 코드로 재분류하지 않습니다.

전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.

INPUT_NOT_ROUNDTRIP_SAFE는 현재 코덱으로 무변경 왕복을 확인하지 못했다는 뜻입니다. 원문을 보존하는 to-json --section N → patch, 누름틀 fill, 보존 가능한 한 문단·한 Text run 칸의 set-cell 경로를 검토하세요. 입력 바이트의 깊이 초과는 DECODE_FAILED이고, Rust Draft 셀 편집의 깊이 초과는 VALIDATION_FAILED입니다.

종료 상태는 (명령, 코드)로 결정합니다. 같은 명령·코드는 오류 payload나 발생 경로에 따라 달라지지 않습니다. 0은 성공이고, validate의 3은 디코드된 문서가 유효하지 않다는 판정입니다(Core 중첩 깊이 32 초과는 디코드 거부라 DECODE_FAILED입니다). 오류의 1·2만으로 원인을 구분하지 말고 code를 확인하세요.

I/O 코드종료 상태
FILE_NOT_FOUND, FILE_READ_FAILEDto-md·convert-hwp5는 2, 나머지는 1
INPUT_TOO_LARGE일반 파일 사전 검사·FIFO 모두 1
FILE_WRITE_FAILEDdelete-para·insert-para·convert-hwp5는 2, 나머지는 1

0.18에서 바뀌는 종료 값은 다음 일곱 변경군입니다.

delete-para의 사전 validate·encode·재decode 실패도 INPUT_NOT_ROUNDTRIP_SAFE / 1입니다. 마지막 의미 왕복 비교 또는 ZIP carry 호출의 실패만 원문 보존 삭제를 시도하며, 그 시도에서 어느 검증이든 실패하면 원래 오류를 그대로 반환합니다.

명령·실패이전0.18 코드·종료
insert-para: no-op validate·encode·재decode2INPUT_NOT_ROUNDTRIP_SAFE / 1
stamp: no-op validate·encode·재decode2INPUT_NOT_ROUNDTRIP_SAFE / 1
set-cell: 입력 decode·원본 패키지 읽기1DECODE_FAILED / 2
delete-para·insert-para: 출력 decode·생성 산출물 읽기·fragment 파싱2SELF_VERIFY_FAILED / 1
to-md·convert-hwp5: 크기 한도를 넘는 FIFO 입력2INPUT_TOO_LARGE / 1
convert-hwp5: 쓰기 성공 직후 stat 실패1FILE_WRITE_FAILED / 2
validate: 파서는 통과하고 Core 중첩 깊이가 32를 넘는 HWPX3(판정)DECODE_FAILED / 2

CLI 전용 INVALID_SET·DUPLICATE_SET과 진단용 네 코드는 유지합니다. 잘못된 명령행 문법은 기존 파서의 종료 2와 사용법 텍스트를 유지합니다. PDF의 cause.code는 별도 렌더러 코드 체계입니다.

이전 코드로 분기하던 소비자는 다음 이행표를 참고하세요. 아래 왼쪽 열은 과거 이름이며 0.18 출력이나 lookup 별명이 아닙니다.

이전 코드·용도0.18 코드
DECODE_ERROR, HWPX_DECODE_FAILEDDECODE_FAILED
ENCODE_ERRORENCODE_FAILED
VALIDATION_ERROR, VALIDATE_FAILEDVALIDATION_FAILED
MD_DECODE_ERROR, JSON_PARSE_ERRORMD_DECODE_FAILED, JSON_PARSE_FAILED
SERIALIZE_ERROR, STAMP_MANIFEST_SERIALIZEJSON_SERIALIZE_FAILED
UNKNOWN_PRESETPRESET_NOT_FOUND
STYLE_STORE_ERROR, STYLE_REBIND_ERRORSTYLE_STORE_FAILED, STYLE_REBIND_FAILED
FILL_ERROR, 포괄 FILL_FAILED고유 fill 거부는 FILL_FAILED, 나머지는 실패 단계·patch·불변식 코드
PATCH_ERROR, 포괄 PATCH_FAILED보존 정책 거부는 PATCH_FAILED, 나머지는 실패 단계·보호 필드·불변식·구역 범위 코드
SET_CELL_CODEC_FAILED, STAMP_CODEC_FAILED, STRUCTURAL_CODEC해당 단계 코드, PROTECTED_FIELD_RANGE, INTERNAL_INVARIANT; 의미 손실은 ENCODE_SEMANTIC_LOSS
READ_SECTION_OUT_OF_RANGE, READ_TABLE_OUT_OF_RANGE, READ_FIELD_NOT_FOUNDSECTION_OUT_OF_RANGE, TABLE_NOT_FOUND, FIELD_NOT_FOUND
STAMP_DELTA_MISMATCH, STAMP_CELL_TARGET_DUPLICATESELF_VERIFY_FAILED, CELL_TARGET_DUPLICATE
INDEX_OUT_OF_RANGESECTION_OUT_OF_RANGE 또는 PARAGRAPH_OUT_OF_RANGE
UNCARRIED_ZIP_ENTRIESINPUT_ENTRIES_NOT_CARRIED
MCP 앞 삽입 거부의 SECTION_PROPERTIES_PARAGRAPHINSERT_BEFORE_SECTION_PROPERTIES; 원래 구역 속성 문단 보호에는 기존 코드 유지
STRUCTURAL_EDIT_FAILED정밀 도메인 코드 또는 UPSTREAM_UNMAPPED
SECTION_WORKFLOW_FAILED, SECTION_WORKFLOW_ERROR, SET_CELL_FAILED, STAMP_FAILED fallbackUPSTREAM_UNMAPPED
포괄 HWP5_CONVERT_FAILEDdecode는 HWP5_DECODE_FAILED, 직접 검증은 VALIDATION_FAILED, 출력 생성은 ENCODE_FAILED; layout replay는 기존 코드 유지
READ_ERROR, METADATA_ERROR, STDIN_READ_FAILEDFILE_READ_FAILED; 입력 부재는 FILE_NOT_FOUND
WRITE_ERROR, DIR_CREATE_ERROR, DIR_CREATE_FAILED출력 I/O는 FILE_WRITE_FAILED, 출력 경로 정책은 INVALID_OUTPUT_PATH

과거 로그의 포괄 코드는 당시 실패 단계를 모르면 새 코드 하나로 자동 변환할 수 없습니다.

MCP의 도구 필드 역직렬화 실패는 필드 경로를 메시지에 포함한 INVALID_PARAMS입니다. 경고가 있는 18개 도구는 {code, message, hint?} 객체 배열을 반환하며, 빈 경고는 생략합니다. templates에는 경고 필드가 없습니다. 전송·JSON-RPC·알 수 없는 도구·worker 실패는 기존 프로토콜 경계를 유지합니다.

Python 파일 I/O는 HwpForgeError와 OSError로 포착할 수 있고, 입력 부재는 FileNotFoundError로도 포착할 수 있습니다. 정확한 타입 비교나 PermissionError 같은 세부 포착은 달라집니다. Python 호출 규약·인자 변환의 TypeError·ValueError는 유지합니다.

스타일 참조와 JSON 이행

v3 문단의 style_ref는 문서 내부 참조입니다. styles.style_positions[ref]가 styles.styles 정의 배열의 위치를 가리킵니다. 숫자 ref 0은 wire 0과 다를 수 있으며, null은 출력에서 wire 0을 사용합니다. 대응표는 모든 정의를 정확히 한 번 포함해야 합니다. schema의 Document는 Core 구조이고 ExportedDocument/ExportedSection은 이 교환 envelope를 설명합니다.

독립 from-json은 non-null 참조가 있으면 styles를 요구합니다(base 제공 여부와 무관). styles 없는 구역 patch는 제출한 base의 참조 공간으로 해석합니다. 동일 section과 다른 header를 가진 파일의 출처 차이까지 검출하지는 않습니다. 완전 왕복에는 styles를 포함하세요. v2는 위치 참조를 단방향 이행하며, styles 없는 v2 문서 작성은 default preset을 사용합니다. 버전 없는 JSON은 기존 여백 단위 이행을 먼저 수행합니다.

MCP from-json의 문자열 인자 안 JSON도 같은 계약입니다. 별도 MCP schema 도구는 없으며 CLI schema를 사용합니다. Python의 dict 반환 타입과 callable은 그대로이고, 그 내부 데이터 계약만 v3로 바뀝니다.

v3에서 Core JSON의 style_id는 style_ref로 바뀌었으며, 교환에는 envelope를 사용하세요. to-json --no-styles로 내보낸 v3 문서는 non-null 참조에 필요한 styles가 없어 그대로 from-json에 넣으면 거절됩니다.

by Ai-Scream