deel-local-cli 1.16.0 → 1.17.2

package/src/tools/hwpxwrite.js

@@ -0,0 +1,302 @@
+/**
+ * hwpx 만들기 — 글 → 한글 문서.
+ *
+ * ── 왜 만드나 ───────────────────────────────────────────────────────────
+ *
+ * 읽기(tools/docs.js)를 넣고 나서 남은 말이 늘 같았다. 「읽어 주는 건 알겠는데,
+ * 결과를 그 서식으로 주면 안 되나요.」
+ *
+ * 사내에서 오가는 것은 md 가 아니다. 주간보고도 회의록도 검토 의견도 한글
+ * 문서다. 지금까지는 deel 이 md 를 내놓고 사람이 그걸 한글에 붙여 넣어 서식을
+ * 다시 잡았다. 그 붙여넣기가 하루에 몇 번씩이다.
+ *
+ * ── 고치기는 여전히 안 한다 ────────────────────────────────────────────
+ *
+ * docs.js 가 「문서는 못 고침」 이라고 못 박은 것은 그대로다. 서식·그림·양식이
+ * 든 문서를 글로 왕복시키면 반드시 뭔가 잃고, 잃은 채로 저장된 문서는 겉보기에
+ * 멀쩡해서 알아차렸을 때는 원본이 없다.
+ *
+ * **새로 만드는 것은 다르다.** 잃을 원본이 없다. 그래서 여기서 하는 일은 하나뿐
+ * 이다 — 빈 종이에 글을 적어 hwpx 로 내놓는다. 있는 파일을 덮어쓰지도 않는다.
+ *
+ * ── 무엇을 옮기고 무엇을 안 옮기나 ─────────────────────────────────────
+ *
+ *   옮긴다    제목 세 단계(#·##·###) · 문단 · 글머리표(-·*·1.) · 빈 줄
+ *   안 옮긴다 표 · 그림 · 굵게·기울임 · 링크
+ *
+ * 표를 안 넣는 것은 **못 해서가 아니라 확인할 수 없어서**다. OWPML 의 표는 칸
+ * 크기·여백·병합을 다 적어야 하고, 그 중 하나가 틀리면 한글이 **파일 전체**를
+ * 안 연다. 이 자리에는 한글이 없어서 「열린다」 를 잴 방법이 없다. 문단만 있는
+ * 문서는 구조가 단순해 어긋날 자리가 거의 없고, 표는 그 반대다. 표는 줄 글로
+ * 적어 내보내고 **그렇게 했다고 말한다** — 조용히 빼면 사람은 표가 사라진 것을
+ * 나중에야 안다.
+ *
+ * ── 규격에 대해 ────────────────────────────────────────────────────────
+ *
+ * hwpx 는 ZIP + XML 이다(한컴 공개 규격 OWPML). 우리 zip 쓰개(pack/zip.js)와
+ * 글자 이어붙이기면 되고, 새로 들이는 것이 없다 — 읽기와 같은 자세다.
+ *
+ * `mimetype` 은 **맨 앞에, 안 눌러서** 담는다. ZIP 을 안 풀고도 앞머리만 보고
+ * 무슨 파일인지 알게 하려는 규약이다. pack/zip.js 는 눌러서 커지면 그냥 담으므로
+ * (20바이트짜리는 늘 그렇다) 차례만 맞추면 된다.
+ */
+import { makeZip } from '../pack/zip.js';
+
+/** 1pt = 100 HWPUNIT. 규격이 그렇다. */
+const PT = 100;
+/** 한 문단이 이보다 길면 자른다. 모델이 통째로 쏟아붓는 것을 막는다. */
+export const 문단최대 = 20000;
+/** 문단 수 상한. 넘으면 자르고 **잘랐다고 말한다.** */
+export const 문단수최대 = 5000;
+
+const 갈래 = { 제목1: 1, 제목2: 2, 제목3: 3, 본문: 0, 글머리: 0 };
+
+const esc = (s) => String(s ?? '')
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;')
+  /*
+   * XML 1.0 이 아예 못 담는 제어문자를 걷어낸다.
+   *
+   * 모델이 낸 글에 이런 것이 섞이는 일이 실제로 있다 — 터미널 출력을 그대로
+   * 옮겨 적으면 ESC(0x1B)가 딸려 온다. 남겨 두면 한글이 **파일 전체**를 안 여는데,
+   * 화면에는 「손상된 문서」 한 줄만 뜼다. 글자 몇 개를 잃는 쪽이 문서를 통째로
+   * 잃는 쪽보다 낫다.
+   */
+  .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+
+/**
+ * 글을 문단 목록으로 읽는다.
+ *
+ * 마크다운을 다 아는 척하지 않는다. 우리가 내놓는 글에 실제로 들어 있는 것만
+ * 본다 — 제목, 글머리표, 문단. 굵게·링크 같은 것은 **글자 그대로** 남긴다.
+ * 지우면 `**중요**` 가 `중요` 가 되어 강조가 사라지고, 옮기려 들면 서식 조합이
+ * 폭발한다. 남기면 적어도 사람이 무엇을 뜻했는지 읽을 수 있다.
+ *
+ * @returns {{문단들: Array<{갈래:string, 글:string}>, 잘림: number, 표몇개: number}}
+ */
+export function 글읽기(글) {
+  const 줄들 = String(글 ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const 문단들 = [];
+  let 표몇개 = 0;
+  let 이어붙일것 = null;
+
+  const 닫기 = () => {
+    if (이어붙일것 && 이어붙일것.글.trim()) 문단들.push(이어붙일것);
+    이어붙일것 = null;
+  };
+
+  for (const 날것 of 줄들) {
+    const 줄 = 날것.replace(/\s+$/, '');
+    if (!줄.trim()) { 닫기(); continue; }
+
+    const 제목 = /^(#{1,3})\s+(.*)$/.exec(줄);
+    if (제목) {
+      닫기();
+      문단들.push({ 갈래: `제목${제목[1].length}`, 글: 제목[2].trim() });
+      continue;
+    }
+
+    /*
+     * 표는 줄 글로 내보낸다. 그리고 **몇 개였는지 센다** — 부르는 쪽이
+     * 그 수를 사람에게 말한다. 조용히 바꿔치기하면 사람은 표가 글이 된 것을
+     * 문서를 열어 보고서야 안다.
+     */
+    if (/^\s*\|.*\|\s*$/.test(줄)) {
+      // 표의 구분선(|---|---|)은 글로 옮길 것이 없다.
+      if (/^\s*\|[\s:|-]+\|\s*$/.test(줄)) { 표몇개 += 1; continue; }
+      닫기();
+      문단들.push({ 갈래: '본문', 글: 줄.replace(/^\s*\|/, '').replace(/\|\s*$/, '').split('|').map((x) => x.trim()).join('  ·  ') });
+      continue;
+    }
+
+    const 글머리 = /^\s*([-*+]|\d+[.)])\s+(.*)$/.exec(줄);
+    if (글머리) {
+      닫기();
+      // 한글의 글머리표 규격을 안 쓴다. 문자 하나로 적으면 어느 한글 판에서도
+      // 똑같이 보이고, 서식이 어긋날 자리가 없다.
+      const 표시 = /^\d/.test(글머리[1]) ? `${글머리[1]} ` : '· ';
+      문단들.push({ 갈래: '글머리', 글: `${표시}${글머리[2].trim()}` });
+      continue;
+    }
+
+    // 이어지는 줄은 한 문단으로 붙인다. 마크다운의 규칙이고, 한글에서도
+    // 줄마다 문단을 끊으면 줄 간격이 통째로 어색해진다.
+    if (이어붙일것) 이어붙일것.글 += ` ${줄.trim()}`;
+    else 이어붙일것 = { 갈래: '본문', 글: 줄.trim() };
+  }
+  닫기();
+
+  let 잘림 = 0;
+  if (문단들.length > 문단수최대) { 잘림 = 문단들.length - 문단수최대; 문단들.length = 문단수최대; }
+  for (const p of 문단들) if (p.글.length > 문단최대) p.글 = `${p.글.slice(0, 문단최대)} …(잘림)`;
+  return { 문단들, 잘림, 표몇개 };
+}
+
+// ── 이하 규격 조각들 ────────────────────────────────────────────────────
+
+const 머리 = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>';
+
+const VERSION_XML = `${머리}
+<hv:HCFVersion xmlns:hv="http://www.hancom.co.kr/hwpml/2011/version" tagetApplication="WORDPROCESSOR" major="5" minor="1" micro="1" buildNumber="0" os="1" xmlVersion="1.4" application="deel" appVersion="1.0"/>`;
+
+const CONTAINER_XML = `${머리}
+<ocf:container xmlns:ocf="urn:oasis:names:tc:opendocument:xmlns:container" xmlns:hpf="http://www.hancom.co.kr/schema/2011/hpf">
+<ocf:rootfiles><ocf:rootfile full-path="Contents/content.hpf" media-type="application/hwpml-package+xml"/></ocf:rootfiles>
+</ocf:container>`;
+
+const MANIFEST_XML = `${머리}
+<odf:manifest xmlns:odf="urn:oasis:names:tc:opendocument:xmlns:manifest:1.0" odf:version="1.2">
+<odf:file-entry odf:full-path="/" odf:media-type="application/hwp+zip"/>
+</odf:manifest>`;
+
+const SETTINGS_XML = `${머리}
+<ha:HWPApplicationSetting xmlns:ha="http://www.hancom.co.kr/hwpml/2011/app" xmlns:config="http://www.hancom.co.kr/hwpml/2011/configuration">
+<ha:CaretPosition listIDRef="0" paraIDRef="0" pos="0"/>
+</ha:HWPApplicationSetting>`;
+
+const contentHpf = (제목) => `${머리}
+<opf:package xmlns:opf="http://www.idpf.org/2007/opf/" xmlns:dc="http://purl.org/dc/elements/1.1/" version="" unique-identifier="" id="">
+<opf:metadata>
+<opf:title>${esc(제목)}</opf:title>
+<opf:language>ko</opf:language>
+<opf:meta name="creator" content="deel"/>
+</opf:metadata>
+<opf:manifest>
+<opf:item id="header" href="Contents/header.xml" media-type="application/xml"/>
+<opf:item id="section0" href="Contents/section0.xml" media-type="application/xml"/>
+<opf:item id="settings" href="settings.xml" media-type="application/xml"/>
+</opf:manifest>
+<opf:spine><opf:itemref idref="header" linear="yes"/><opf:itemref idref="section0" linear="yes"/></opf:spine>
+</opf:package>`;
+
+/*
+ * 글자·문단 모양표.
+ *
+ * 네 벌만 둔다 — 본문과 제목 셋. 더 두면 그만큼 어긋날 자리가 늘고, 우리가
+ * 내놓는 글에는 그 이상이 없다.
+ *
+ * 글꼴은 **이름만 적고 안 싣는다.** 사내 PC 에 함초롬바탕이 없는 일은 거의
+ * 없고, 없더라도 한글이 알아서 대체한다. 글꼴 파일을 담기 시작하면 그건
+ * 저작권을 우리가 지고 가는 일이다.
+ */
+const HEADER_XML = `${머리}
+<hh:head xmlns:hh="http://www.hancom.co.kr/hwpml/2011/head" xmlns:hc="http://www.hancom.co.kr/hwpml/2011/core" version="1.4" secCnt="1">
+<hh:beginNum page="1" footnote="1" endnote="1" pic="1" tbl="1" equation="1"/>
+<hh:refList>
+<hh:fontfaces itemCnt="7">
+${['HANGUL', 'LATIN', 'HANJA', 'JAPANESE', 'OTHER', 'SYMBOL', 'USER'].map((갈) => `<hh:fontface lang="${갈}" fontCnt="1"><hh:font id="0" face="함초롬바탕" type="TTF" isEmbedded="0"><hh:typeInfo familyType="FCAT_GOTHIC" weight="0" proportion="0" contrast="0" strokeVariation="0" armStyle="0" letterform="0" midline="0" xHeight="0"/></hh:font></hh:fontface>`).join('\n')}
+</hh:fontfaces>
+<hh:borderFills itemCnt="1"><hh:borderFill id="1" threeD="0" shadow="0" centerLine="NONE" breakCellSeparateLine="0"><hh:slash type="NONE" Crooked="0" isCounter="0"/><hh:backSlash type="NONE" Crooked="0" isCounter="0"/><hh:leftBorder type="NONE" width="0.1 mm" color="#000000"/><hh:rightBorder type="NONE" width="0.1 mm" color="#000000"/><hh:topBorder type="NONE" width="0.1 mm" color="#000000"/><hh:bottomBorder type="NONE" width="0.1 mm" color="#000000"/><hh:diagonal type="SOLID" width="0.1 mm" color="#000000"/></hh:borderFill></hh:borderFills>
+<hh:tabProperties itemCnt="1"><hh:tabPr id="0" autoTabLeft="0" autoTabRight="0"/></hh:tabProperties>
+<hh:charProperties itemCnt="4">
+${[[0, 10], [1, 16], [2, 14], [3, 12]].map(([id, pt]) => `<hh:charPr id="${id}" height="${pt * PT}" textColor="#000000" shadeColor="none" useFontSpace="0" useKerning="0" symMark="NONE" borderFillIDRef="1"><hh:fontRef hangul="0" latin="0" hanja="0" japanese="0" other="0" symbol="0" user="0"/><hh:ratio hangul="100" latin="100" hanja="100" japanese="100" other="100" symbol="100" user="100"/><hh:spacing hangul="0" latin="0" hanja="0" japanese="0" other="0" symbol="0" user="0"/><hh:relSz hangul="100" latin="100" hanja="100" japanese="100" other="100" symbol="100" user="100"/><hh:offset hangul="0" latin="0" hanja="0" japanese="0" other="0" symbol="0" user="0"/>${id === 0 ? '' : '<hh:bold/>'}</hh:charPr>`).join('\n')}
+</hh:charProperties>
+<hh:paraProperties itemCnt="4">
+${[0, 1, 2, 3].map((id) => `<hh:paraPr id="${id}" tabPrIDRef="0" condense="0" fontLineHeight="0" snapToGrid="1" suppressLineNumbers="0" checked="0"><hh:align horizontal="JUSTIFY" vertical="BASELINE"/><hh:heading type="NONE" idRef="0" level="0"/><hh:breakSetting breakLatinWord="KEEP_WORD" breakNonLatinWord="KEEP_WORD" widowOrphan="0" keepWithNext="${id === 0 ? '0' : '1'}" keepLines="0" pageBreakBefore="0" lineWrap="BREAK"/><hh:margin><hc:intent value="0" unit="HWPUNIT"/><hc:left value="0" unit="HWPUNIT"/><hc:right value="0" unit="HWPUNIT"/><hc:prev value="${id === 0 ? 0 : 800}" unit="HWPUNIT"/><hc:next value="${id === 0 ? 0 : 300}" unit="HWPUNIT"/></hh:margin><hh:lineSpacing type="PERCENT" value="160" unit="HWPUNIT"/><hh:border borderFillIDRef="1" offsetLeft="0" offsetRight="0" offsetTop="0" offsetBottom="0" connect="0" ignoreMargin="0"/></hh:paraPr>`).join('\n')}
+</hh:paraProperties>
+<hh:styles itemCnt="4">
+${[['바탕글', 'Normal', 0], ['개요 1', 'Outline 1', 1], ['개요 2', 'Outline 2', 2], ['개요 3', 'Outline 3', 3]].map(([이름, 영, id]) => `<hh:style id="${id}" type="PARA" name="${이름}" engName="${영}" paraPrIDRef="${id}" charPrIDRef="${id}" nextStyleIDRef="0" langID="1042" lockForm="0"/>`).join('\n')}
+</hh:styles>
+</hh:refList>
+</hh:head>`;
+
+/*
+ * 구역 속성. 첫 문단의 첫 런 안에 **딱 한 번** 들어간다.
+ *
+ * 이게 없으면 한글이 파일을 통째로 거절한다 — 조판 엔진을 세울 용지·여백이
+ * 없기 때문이다. 우리 읽개(tools/docs.js)는 <hp:t> 만 훑으니 없어도 멀쩡히
+ * 읽혔고, 그래서 검사가 전부 초록인 채로 「한글이 못 여는 파일」 을 냈다.
+ * 다른 눈(Gemini 3.8 Flash)이 규격을 대조해서 짚어 준 자리다.
+ *
+ * 값은 A4 세로다. 단위는 HWPUNIT(1/7200인치) —
+ *   210mm = 59528 · 297mm = 84188 · 좌우 30mm = 8504 · 위 20mm = 5668 · 아래·머리·꼬리 15mm = 4252
+ */
+const SEC_PR = '<hp:secPr id="" textDirection="HORIZONTAL" spaceColumns="1134" tabStop="8000" tabStopVal="4000" tabStopUnit="HWPUNIT" outlineShapeIDRef="0" memoShapeIDRef="0" textVerticalWidthHead="0" masterPageCnt="0">'
+  + '<hp:grid lineGrid="0" charGrid="0" wonggojiFormat="0" strtnum="0"/>'
+  + '<hp:startNum pageStartsOn="BOTH" page="0" pic="0" tbl="0" equation="0"/>'
+  + '<hp:visibility hideFirstHeader="0" hideFirstFooter="0" hideFirstMasterPage="0" border="SHOW_ALL" fill="SHOW_ALL" hideFirstPageNum="0" hideFirstEmptyLine="0" showLineNumber="0"/>'
+  + '<hp:lineNumberShape restartType="0" countBy="0" distance="0" startNumber="0"/>'
+  + '<hp:pagePr landscape="WIDELY" width="59528" height="84188" gutterType="LEFT_ONLY">'
+  + '<hp:margin header="4252" footer="4252" gutter="0" left="8504" right="8504" top="5668" bottom="4252"/>'
+  + '</hp:pagePr>'
+  + '<hp:footNotePr><hp:autoNumFormat type="DIGIT" userChar="" prefixChar="" suffixChar=")" supscript="0"/><hp:noteLine length="-1" type="SOLID" width="0.12 mm" color="#000000"/><hp:noteSpacing betweenNotes="850" belowLine="567" aboveLine="850"/><hp:numbering type="CONTINUOUS" newNum="1"/><hp:placement place="EACH_COLUMN" beneathText="0"/></hp:footNotePr>'
+  + '<hp:endNotePr><hp:autoNumFormat type="DIGIT" userChar="" prefixChar="" suffixChar=")" supscript="0"/><hp:noteLine length="14692344" type="SOLID" width="0.12 mm" color="#000000"/><hp:noteSpacing betweenNotes="0" belowLine="567" aboveLine="850"/><hp:numbering type="CONTINUOUS" newNum="1"/><hp:placement place="END_OF_DOCUMENT" beneathText="0"/></hp:endNotePr>'
+  + '<hp:pageBorderFill type="BOTH" borderFillIDRef="1" textBorder="PAPER" headerInside="0" footerInside="0" fillArea="PAPER"><hp:offset left="1417" right="1417" top="1417" bottom="1417"/></hp:pageBorderFill>'
+  + '<hp:pageBorderFill type="EVEN" borderFillIDRef="1" textBorder="PAPER" headerInside="0" footerInside="0" fillArea="PAPER"><hp:offset left="1417" right="1417" top="1417" bottom="1417"/></hp:pageBorderFill>'
+  + '<hp:pageBorderFill type="ODD" borderFillIDRef="1" textBorder="PAPER" headerInside="0" footerInside="0" fillArea="PAPER"><hp:offset left="1417" right="1417" top="1417" bottom="1417"/></hp:pageBorderFill>'
+  + '</hp:secPr>';
+
+/*
+ * 줄 나눔 캐시(linesegarray)는 **안 적는다.**
+ *
+ * 전에는 문단마다 같은 값 하나를 박아 넣었다. 글자 수도 줄 수도 안 보고 적는
+ * 값이라, 두 줄이 넘는 문단에서는 그 캐시가 사실과 다르다. 규격에서 이 칸은
+ * 선택이고, 없으면 한글이 제 엔진으로 다시 잰다. **모르는 것을 지어내
+ * 적어 두느니 비워 두는 편이 낫다** — 이 저장소가 값을 다루는 방식 그대로다.
+ */
+const 문단XML = (p, 번호) => {
+  const id = 갈래[p.갈래] ?? 0;
+  return `<hp:p id="${번호}" paraPrIDRef="${id}" styleIDRef="${id}" pageBreak="0" columnBreak="0" merged="0">`
+    + `<hp:run charPrIDRef="${id}">${번호 === 0 ? SEC_PR : ''}<hp:t>${esc(p.글)}</hp:t></hp:run>`
+    + '</hp:p>';
+};
+
+const sectionXML = (문단들) => `${머리}
+<hs:sec xmlns:hs="http://www.hancom.co.kr/hwpml/2011/section" xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph" xmlns:hc="http://www.hancom.co.kr/hwpml/2011/core">
+${(문단들.length ? 문단들 : [{ 갈래: '본문', 글: '' }]).map(문단XML).join('\n')}
+</hs:sec>`;
+
+/**
+ * 글을 hwpx 한 덩이(Buffer)로 만든다.
+ *
+ * 파일로 쓰지 않는다 — 쓰는 자리는 울타리(safety/guard.js)를 지나야 하고,
+ * 그 판단은 도구 쪽이 한다. 여기는 바이트만 만든다.
+ *
+ * @param {string} 글       마크다운스러운 글
+ * @param {object} [o]
+ * @param {string} [o.제목] 문서 속성의 제목. 안 주면 첫 제목 줄, 그것도 없으면 '문서'
+ * @returns {{buf: Buffer, 문단수: number, 잘림: number, 표몇개: number, 제목: string}}
+ */
+export function hwpx만들기(글, { 제목 = null } = {}) {
+  const { 문단들, 잘림, 표몇개 } = 글읽기(글);
+  const 쓸제목 = String(제목 ?? '').trim()
+    || 문단들.find((p) => p.갈래.startsWith('제목'))?.글
+    || '문서';
+
+  /*
+   * 미리보기 글을 같이 담는다.
+   *
+   * 한글은 이걸로 파일 목록의 미리보기를 그리고, 윈도우 탐색기의 내용 검색도
+   * 이 파일을 본다. 없다고 안 열리지는 않지만, 없으면 **사내 공유폴더에서
+   * 검색이 안 걸린다** — 문서를 만들어 주는 값의 절반이 거기 있다.
+   */
+  const 미리보기 = 문단들.map((p) => p.글).join('\n').slice(0, 3000);
+
+  const 담을것 = [
+    // mimetype 은 맨 앞에. 20바이트라 눌러도 커지므로 그냥 담긴다 (pack/zip.js).
+    { name: 'mimetype', data: Buffer.from('application/hwp+zip', 'utf8') },
+    { name: 'version.xml', data: Buffer.from(VERSION_XML, 'utf8') },
+    { name: 'META-INF/container.xml', data: Buffer.from(CONTAINER_XML, 'utf8') },
+    { name: 'META-INF/manifest.xml', data: Buffer.from(MANIFEST_XML, 'utf8') },
+    { name: 'Contents/content.hpf', data: Buffer.from(contentHpf(쓸제목), 'utf8') },
+    { name: 'Contents/header.xml', data: Buffer.from(HEADER_XML, 'utf8') },
+    { name: 'Contents/section0.xml', data: Buffer.from(sectionXML(문단들), 'utf8') },
+    { name: 'Preview/PrvText.txt', data: Buffer.from(미리보기, 'utf8') },
+    { name: 'settings.xml', data: Buffer.from(SETTINGS_XML, 'utf8') },
+  ];
+  return { buf: makeZip(담을것), 문단수: 문단들.length, 잘림, 표몇개, 제목: 쓸제목 };
+}
+
+/**
+ * 만들고 나서 사람에게 할 말.
+ *
+ * **바꿔치기한 것을 반드시 적는다.** 표를 줄 글로 폈으면 그렇다고 적고, 문단을
+ * 잘랐으면 몇 개를 잘랐는지 적는다. 조용히 넘기면 사람은 문서를 열어 보고서야
+ * 알고, 그때는 이미 그 문서를 남에게 보낸 뒤다.
+ */
+export function 만든말(r, 보인이름) {
+  const 줄 = [`${보인이름} · ${r.문단수}문단`];
+  if (r.표몇개) 줄.push(`표 ${r.표몇개}개는 줄 글로 폈습니다 (표 서식은 안 만듭니다)`);
+  if (r.잘림) 줄.push(`문단 ${r.잘림}개는 넘쳐서 잘랐습니다`);
+  return 줄.join(' · ');
+}

package/src/tools/index.js

@@ -15,15 +15,18 @@ import { loadSkill } from '../skills/discover.js';
 import { WEB_FETCH_TOOL } from './webfetch.js';
 import { TODO_TOOL } from './todo.js';
 import { TASK_TOOL } from './task.js';
+import { 고를말 } from '../agent/agents.js';
 import { OUTLINE_TOOL } from './outline.js';
 import { VERIFY_TOOL } from './verify.js';
 import { DEF_TOOL, REFS_TOOL } from './lsp.js';
 import { 편집후진단, 붙이기 as 진단붙이기, 데우기 } from '../lsp/diag.js';
 import { 프로젝트갈래 } from '../lsp/servers.js';
 import { allow as allowedIn } from '../agent/modes.js';
-import { 도구정의, 이름풀기, 열쇠뺀환경 } from '../backend/mcp.js';
+import { 도구정의, 이름풀기 } from '../backend/mcp.js';
+import { 셸환경 } from '../safety/shellenv.js';
 import { isExcelPath, readExcel, toText as excelText, summarize as excelSummary } from './excel.js';
 import { isDocPath, readDoc, toText as docText, summarize as docSummary, looksOldHwp, 옛hwp안내, 문서는못고침 } from './docs.js';
+import { hwpx만들기, 만든말 } from './hwpxwrite.js';
 import { 바꿔볼까, 직접못읽나, 변환기찾기, 글로바꾸기, 못바꿈말 } from './convert.js';
 import { 물음검사 } from '../agent/askcheck.js';
 import { isPdfPath, readPdf, toText as pdfText, summarize as pdfSummary, 못읽은말, pdf는못고침, 한쪽도못읽음말 } from './pdf.js';
@@ -822,6 +825,39 @@ async function 여러개옮기기(목록, ctx) {
   };
 }
 
+/** `.hwpx` 인가. 새로 만들 수 있는 유일한 문서 형식이다. */
+const isHwpxPath = (p) => /\.hwpx$/i.test(String(p ?? ''));
+
+/**
+ * 글을 한글 문서로 **새로** 만든다 (tools/hwpxwrite.js).
+ *
+ * 사내에서 오가는 것은 md 가 아니다. 주간보고도 회의록도 검토 의견도 한글
+ * 문서라, 여태 사람이 우리 md 를 한글에 붙여 넣어 서식을 다시 잡았다.
+ *
+ * 바꿔치기한 것은 **반드시 적어 돌려준다.** 표를 줄 글로 폈으면 그렇다고
+ * 적는다 — 조용히 넘기면 사람은 문서를 열어 보고서야 알고, 그때는 이미 그
+ * 문서를 남에게 보낸 뒤다.
+ */
+function hwpx새로만들기(args, ctx, abs) {
+  const 만듦 = hwpx만들기(args.content, { 제목: null });
+  ctx.history.snapshot(abs, 'Write');
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, 만듦.buf);
+  /*
+   * `seen` 에 안 올린다.
+   *
+   * seen 은 「Edit 로 고쳐도 되는 것을 읽어 뒀다」 는 표다. hwpx 는 만든
+   * 다음에도 고칠 수 없으므로, 올려 두면 모델이 Edit 를 부르고 거절당하고
+   * 또 부른다. Read 쪽이 문서를 seen 에 안 올리는 것과 같은 판단이다.
+   */
+  return {
+    content: `새로 만듦: ${만든말(만듦, ctx.scope.show(abs))}\n`
+      + '  이 문서는 이제 고칠 수 없습니다. 내용을 바꾸려면 Write 로 다시 만드세요.',
+    summary: 이어(세말('lines', 만듦.문단수), 만듦.표몇개 ? `표 ${만듦.표몇개}개는 글로` : ''),
+    changed: abs,
+  };
+}
+
 function 한파일쓰기(args, ctx) {
   const abs = ctx.scope.resolve(args.file_path);
     if (typeof args.content !== 'string') return { error: 'content 가 문자열이 아닙니다' };
@@ -832,6 +868,16 @@ function 한파일쓰기(args, ctx) {
     // 엑셀 파일을 통째로 덮어쓰면 xlsx 가 아니라 그냥 글 파일이 된다.
     // 열리지도 않는 파일이 되고, 원본은 이미 없다. 아예 막는다.
     if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
+    /*
+     * ── hwpx 는 **새로 만드는 것만** 된다 (tools/hwpxwrite.js) ──────────
+     *
+     * 고치기를 막는 까닭은 「글로 왕복시키면 반드시 뭔가 잃는데, 잃은 채로
+     * 저장된 문서는 겉보기에 멀쩡해서 알아차렸을 때는 원본이 없다」 였다.
+     * 새로 만드는 자리에는 **잃을 원본이 없다.** 그래서 여기만 연다.
+     *
+     * 있는 파일이면 그대로 아래 거절로 내려간다 — 덮어쓰기는 여전히 안 된다.
+     */
+    if (isHwpxPath(abs) && !existsSync(abs)) return hwpx새로만들기(args, ctx, abs);
     // 문서(hwpx·docx·pptx)도 같은 이유로 또렷하게 거절한다. 일반 '바이너리'
     // 오류로 넘기면 왜 안 되는지가 안 실려서, 모델이 우회로를 찾는다.
     if (isDocPath(abs)) return { error: 문서는못고침(args.file_path) };
@@ -1287,7 +1333,17 @@ export const TOOLS = {
       description: '파일을 새로 쓰거나 통째로 덮어쓴다. 일부만 고칠 때는 Edit 을 쓴다.'
         + ' **여러 파일을 한 번에 만들 수 있다** — files 에 배열로 넣으면 된다.'
         + ' 폴더 구조를 처음 잡을 때는 그렇게 해라. 한 개씩 부르면 파일 수만큼 모델을'
-        + ' 다시 불러야 해서, 여덟 개짜리 뼈대에 몇 분이 그냥 간다.',
+        + ' 다시 불러야 해서, 여덟 개짜리 뼈대에 몇 분이 그냥 간다.'
+        /*
+         * hwpx 를 여기 적는 까닭.
+         *
+         * 안 적으면 모델은 이 길이 있는 줄 모른다. 사람이 「한글로 줘」 라고
+         * 해도 md 를 만들고 「한글에서 열면 됩니다」 라고 답한다 — 실제로
+         * 그랬다. 도구 목록에 없는 기능은 없는 기능이다.
+         */
+        + ' 이름을 `.hwpx` 로 끝내면 **한글 문서로 만든다** (제목 #·##·### 과 글머리표를 옮긴다).'
+        + ' 사내에 낼 보고서·회의록을 달라고 하면 그렇게 해라. 단 **새로 만들 때만** 되고,'
+        + ' 이미 있는 문서는 못 고친다.',
       parameters: {
         type: 'object',
         properties: {
@@ -1839,7 +1895,11 @@ export const TOOLS = {
 
       // 끝나지 않는 명령은 뒤에서 띄운다. 여기서 기다리면 그 턴이 통째로 멈춘다.
       if (args.background === true) {
-        const r = await 띄우기(cmd, { cwd: ctx.scope.root, 설명: args.description ?? null });
+        const r = await 띄우기(cmd, {
+          cwd: ctx.scope.root,
+          설명: args.description ?? null,
+          남길것: ctx.셸남길것 ?? [],
+        });
         if (r.error) return { error: r.error };
         if (!r.떴나) {
           // 지켜보는 사이에 죽었다. 포트가 물려 있거나 명령이 틀린 경우다.
@@ -1871,6 +1931,9 @@ export const TOOLS = {
       const shell = 셸명령(cmd);
 
       const 제한 = args.timeout ?? 120000;
+      // 무엇을 빼고 넘길지 여기서 한 번 정한다. 뺀 이름은 아래에서 명령이
+      // 실패했을 때만 쓴다 — 잘 돌 때마다 적으면 매 부름에 군말이 붙는다.
+      const 셸것 = 셸환경(process.env, { 남길것: ctx.셸남길것 ?? [] });
       return new Promise((끝) => {
         /*
          * 끝맺음은 한 번만. 그리고 **기다리지 않는다.**
@@ -1888,9 +1951,17 @@ export const TOOLS = {
         // '�Ľ� ����' 이 된다. 바이트로 받아 이 컴퓨터가 쓰는 것으로 해독한다.
         const kid = 무리로돌리기(shell.file, shell.args, {
           cwd: ctx.scope.root,
-          // 열쇠만 빼고 나머지는 그대로 물려준다 (backend/mcp.js 열쇠뺀환경 머리말).
-          // 안 빼면 `env` 한 줄이 열쇠를 화면과 대화 기록에 그대로 싣는다.
-          env: 열쇠뺀환경(),
+          /*
+           * 열쇠처럼 생긴 것만 빼고 나머지는 그대로 물려준다 (safety/shellenv.js).
+           *
+           * 여기 도는 것은 **사용자 제 프로젝트**라 PATH·NODE_ENV·사내 프록시가
+           * 다 있어야 한다. 그런데 여태 뺀 것은 우리 열쇠뿐이었고, 그래서
+           * OPENAI_API_KEY·GITHUB_TOKEN·DB_PASSWORD 가 그대로 넘어갔다.
+           * 모델이 `env | grep -i proxy` 한 번 부르면 — 사내 프록시를 확인하는
+           * 아주 정상적인 행동이다 — 그 값들이 도구 결과에 실려 게이트웨이로
+           * 나가고 대화 기록으로 디스크에도 남는다.
+           */
+          env: 셸것.env,
           // 우리 시계(아래 뒷북)가 제한에서 먼저 나무를 끊는다. 이건 그것마저
           // 못 돌았을 때 서는 마지막 그물이라 뒤에 세운다.
           timeout: 제한 + 3000,
@@ -1971,8 +2042,27 @@ export const TOOLS = {
                 + ' `| head -n 200` 처럼 줄이거나 파일로 받아서 다시 부르세요]'
                 : 숫자코드 === null ? `\n\n[${글자코드} — 명령을 아예 못 돌렸습니다]`
                   : `\n\n[종료코드 ${code}]`;
+          /*
+           * 실패했을 때만, 무엇을 빼고 넘겼는지 이름을 적는다.
+           *
+           * 이 한 줄이 이 기능에서 제일 중요하다. 사내 저장소를 쓰는 사람은
+           * `npm ci` 에 NPM_TOKEN 이 필요하다. 우리가 조용히 빼면 npm 이 401 로
+           * 죽고 화면에는 npm 의 401 만 남는다. 사람은 토큰이 만료된 줄 알고
+           * 새로 발급받으러 가고, 새로 받아도 똑같은 화면을 본다.
+           *
+           * 값은 절대 안 적는다. 이름만 적는다 — 이름을 적는 것은 원인을
+           * 알려 주는 일이고, 값을 적는 것은 방금 막은 것을 되돌리는 일이다.
+           *
+           * 잘 돌았을 때는 안 적는다. 매 부름마다 붙으면 아무도 안 읽는 군말이
+           * 되고, 진짜 필요할 때도 안 읽힌다.
+           */
+          const 뺀말 = (!잘됨 && 셸것.뺀것.length)
+            ? `\n[열쇠처럼 생긴 환경변수 ${셸것.뺀것.length}개는 안 넘겼습니다: ${셸것.뺀것.slice(0, 8).join(' · ')}`
+              + `${셸것.뺀것.length > 8 ? ' …' : ''}.`
+              + ' 이 명령에 필요하면 설정에 "셸환경": { "남길것": ["이름"] } 을 적으세요]'
+            : '';
           done({
-            content: clip(out || '(출력 없음)', 실을만큼(ctx)) + 꼬리,
+            content: clip(out || '(출력 없음)', 실을만큼(ctx)) + 꼬리 + 뺀말,
             summary: 잘됨 ? 말('sum.ok')
               : 시그널 ? 말('sum.killedBy', { 시그널 })
                 : 넘침 ? 말('sum.tooMuchOut')
@@ -2517,7 +2607,7 @@ export function 영어설명(schema, 이름, 쓸말 = 지시말()) {
 
 // 모델에게 넘길 도구 정의 목록.
 // 스킬이 없으면 Skill 도구는 빼서 자리를 아낀다.
-export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null, lsp = false, vision = false } = {}) {
+export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null, lsp = false, vision = false, 에이전트들 = null } = {}) {
   let list = names ?? Object.keys(TOOLS).filter((n) => {
     if (n === 'Skill') return hasSkills;
     if (n === 'WebFetch') return web;
@@ -2572,6 +2662,33 @@ export function toolSchemas(names = null, { hasSkills = false, web = true, work
    * 한 모드에서 '모르는 것' 을 쥐여 주면 그 약속이 약속이 아니게 된다.
    */
   if (mcp?.length && (!work || allowedIn(work, ['Write']).length)) 우리것.push(...도구정의(mcp));
+
+  /*
+   * 이름 붙인 하위 작업이 있으면 `Task` 에 그 목록을 알려 준다 (agent/agents.js).
+   *
+   * 이름과 한 줄 설명만 싱는다. 지침 본문은 **고른 뒤에** 하위 프롬프트로 가지
+   * 여기 실리지 않는다 — 여기 실으면 안 쓰는 에이전트의 지침까지 매 요청에
+   * 나간다. 스킬을 2단계로 올리는 것과 같은 셈법이다.
+   *
+   * 원본 스키마를 안 건드린다. TOOLS 는 한 벌이라 거기 썼으면 다음 부름에도
+   * 남고, 폴더가 다른 방(ACP)의 목록까지 같이 물들인다.
+   */
+  const 골라말 = 에이전트들?.length ? 고를말(에이전트들) : null;
+  if (골라말) {
+    for (const t of 우리것) {
+      if (t.function?.name !== 'Task') continue;
+      t.function = {
+        ...t.function,
+        parameters: {
+          ...t.function.parameters,
+          properties: {
+            ...t.function.parameters.properties,
+            agent: { type: 'string', description: 골라말 },
+          },
+        },
+      };
+    }
+  }
   return 우리것;
 }
 
@@ -2714,7 +2831,9 @@ async function runMcpTool(name, args, ctx) {
     if (!갈린것) return { error: `${name} 은 MCP 도구 이름 꼴이 아닙니다` };
     const 서버 = (ctx.mcp ?? []).find((s) => s.이름 === 갈린것.서버);
     if (!서버) return { error: `${갈린것.서버} 서버가 붙어 있지 않습니다 — /mcp 로 확인하세요` };
-    if (!서버.살아있나()) return { error: `${갈린것.서버} 서버가 죽었습니다: ${서버.죽음 ?? '이유 모름'}` };
+    // 대기 중인 것은 부르는 순간 뜼다 (backend/mcp.js 의 깨우기). 죽은 것과 가른다 —
+    // 하나로 뭉개면 안 띄운 서버를 「죽었다」 고 적어 사람을 없는 탈로 보낸다.
+    if (!서버.쓸수있나()) return { error: `${갈린것.서버} 서버가 죽었습니다: ${서버.죽음 ?? '이유 모름'}` };
     try {
       // 사람이 누른 ESC 를 남의 프로그램에까지 데려간다. 안 넘기면 도구 한 번에
       // 60초(부르기제한)를 꼬박 기다리는데, 그 사이 ESC 는 아무 일도 안 한다.

package/src/tools/jobs.js

@@ -26,7 +26,7 @@
 import { spawn, execFileSync } from 'node:child_process';
 import { decode as decodeBytes, consoleCodepage } from './encoding.js';
 import { 셸명령 } from './shell.js';
-import { 열쇠뺀환경 } from '../backend/mcp.js';
+import { 셸환경 } from '../safety/shellenv.js';
 import { 말, 세말 } from '../i18n/index.js';
 
 /* 결과 한 줄을 잇는다 — 빈 조각은 버린다(tools/index.js 의 이어 와 같은 것). */
@@ -85,12 +85,17 @@ export { 셸명령 };
  * 윈도우에서는 반대로 무리를 안 만든다. detached 는 거기서 새 콘솔 창을
  * 띄우는 쪽으로 작동해서, 조용히 돌아야 할 것이 화면에 튀어나온다.
  */
-export function 띄우기옵션(cwd) {
+export function 띄우기옵션(cwd, { 남길것 = [] } = {}) {
   const win = process.platform === 'win32';
   return {
     cwd,
-    // 열쇠만 빼고 나머지는 그대로 물려준다 (backend/mcp.js 열쇠뺀환경 머리말).
-    env: 열쇠뺀환경(),
+    /*
+     * 열쇠처럼 생긴 것만 빼고 나머지는 그대로 물려준다 (safety/shellenv.js).
+     *
+     * 뒤에서 도는 일감은 Bash 보다 더 샌다 — 출력이 계속 쌓이고 Jobs 로
+     * 언제든 다시 읽히므로, 한 번 찍힌 열쇠는 그 대화가 끝날 때까지 남는다.
+     */
+    env: 셸환경(process.env, { 남길것 }).env,
     windowsHide: true,
     detached: !win,
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -489,7 +494,7 @@ function 끝난것치우기() {
  *   돌려준다. 포트가 이미 물려 있는 경우가 제일 흔한데, 그때 "떴습니다" 라고
  *   답하면 모델은 다음 단계로 넘어가고 사용자는 안 뜬 서버를 찾아다닌다.
  */
-export async function 띄우기(명령, { cwd, 설명 = null, 기다림 = 1500 } = {}) {
+export async function 띄우기(명령, { cwd, 설명 = null, 기다림 = 1500, 남길것 = [] } = {}) {
   const 도는것 = [...일감들.values()].filter((j) => j.상태 === '도는중');
   if (도는것.length >= 최대일감) {
     return { error: `뒤에서 도는 명령이 이미 ${도는것.length}개입니다. Jobs 로 안 쓰는 것을 끝내고 다시 하세요.` };
@@ -500,7 +505,7 @@ export async function 띄우기(명령, { cwd, 설명 = null, 기다림 = 1500 }
   let kid;
   try {
     kid = spawn(shell.file, shell.args, {
-      ...띄우기옵션(cwd),
+      ...띄우기옵션(cwd, { 남길것 }),
       windowsVerbatimArguments: shell.verbatim,
     });
   } catch (err) {

package/src/tools/spawn.js

@@ -33,10 +33,13 @@ import { spawn } from 'node:child_process';
  * @param {number} [옵션.timeout] 이 시간을 넘기면 죽이고 실패로 돌려준다
  * @param {number} [옵션.maxBuffer] 나온 글이 이보다 커지면 죽인다
  * @param {AbortSignal|null} [옵션.signal] 눌리면 자식을 죽인다
+ * @param {string|null} [옵션.넣을것] stdin 으로 흘려 줄 글. 다 쓰면 닫는다.
  * @param {object} [옵션.덤] spawn 에 그대로 넘길 것 (windowsVerbatimArguments 같은)
  * @returns {Promise<{error:Error|null, status:number|null, stdout:string, stderr:string}>}
  */
-export function 돌려보기(이름, 인자, { timeout = 20000, maxBuffer = 32 * 1024 * 1024, signal = null, 덤 = {} } = {}) {
+export function 돌려보기(이름, 인자, {
+  timeout = 20000, maxBuffer = 32 * 1024 * 1024, signal = null, 넣을것 = null, 덤 = {},
+} = {}) {
   return new Promise((resolve) => {
     // 이미 눌렸으면 띄우지도 않는다. 여럿을 함께 돌릴 때 뒤엣것이 여기로 온다.
     if (signal?.aborted) { resolve({ error: new Error('중단했습니다'), status: null, stdout: '', stderr: '' }); return; }
@@ -78,6 +81,21 @@ export function 돌려보기(이름, 인자, { timeout = 20000, maxBuffer = 32 *
     // 이 타이머가 프로그램을 붙들면 안 된다. 자식의 파이프가 이미 루프를 붙들고 있다.
     시계.unref?.();
 
+    /*
+     * 넘길 것이 있으면 stdin 으로 흘리고 **닫는다.**
+     *
+     * 안 닫으면 자식이 stdin 을 끝까지 읽는 모양일 때 영영 안 끝난다 —
+     * 시한에 걸려 죽을 때까지 기다리게 되고, 사람 눈에는 '훅이 느리다' 로 보인다.
+     *
+     * 자식이 다 읽기 전에 죽으면 EPIPE 가 온다. 그건 우리 탈이 아니다 —
+     * 자식은 제 할 말을 이미 했고, 그 결과는 status 로 온다. 여기서 던지면
+     * 프로그램이 통째로 죽으므로 삼킨다.
+     */
+    if (넣을것 != null) {
+      아이.stdin?.on('error', () => { /* 자식이 먼저 닫았다 — 결과는 status 로 온다 */ });
+      try { 아이.stdin?.end(String(넣을것)); } catch { /* 이미 닫혔다 */ }
+    }
+
     아이.stdout?.setEncoding('utf8');
     아이.stderr?.setEncoding('utf8');
     아이.stdout?.on('data', (조각) => {

package/src/tools/task.js

@@ -131,7 +131,7 @@ export function 하위모드(요청, 부모모드) {
  * 못 끝낸 것을 빼면 안 된다. 부모는 그걸 보고 이어서 할지 정한다 —
  * 다 됐다고 알면 안 끝난 일 위에 다음 일을 쌓는다.
  */
-export function 하위요약({ 목적, 모드, 끝, 글자수, 모델 = null, 보인이름 = (p) => p }) {
+export function 하위요약({ 목적, 모드, 끝, 글자수, 모델 = null, 에이전트 = null, 보인이름 = (p) => p }) {
   const 줄 = [];
   const w = workMode(모드);
   const 왜끝났나 = {
@@ -148,7 +148,13 @@ export function 하위요약({ 목적, 모드, 끝, 글자수, 모델 = null,
    * 모델이 대충 해 놓은 것을 제가 한 것처럼 믿는다. "1.5B 가 했다" 가 적혀
    * 있으면 미심쩍은 자리를 다시 볼 여지가 생긴다.
    */
-  줄.push(`하위 작업 "${목적}" · ${w.name} 모드${모델 ? ` · ${모델}` : ''} · ${끝?.steps ?? 0}걸음 · ${왜끝났나}`);
+  /*
+   * 어느 정의가 한 일인지도 적는다 (agent/agents.js).
+   *
+   * 모델 이름을 적는 것과 같은 까닭이다. 부모는 이 요약만 보고 이어서 일하는데,
+   * 「리뷰어가 봤다」 와 「그냥 하위가 봤다」 는 믿을 만한 정도가 다르다.
+   */
+  줄.push(`하위 작업 "${목적}"${에이전트 ? ` · ${에이전트}` : ''} · ${w.name} 모드${모델 ? ` · ${모델}` : ''} · ${끝?.steps ?? 0}걸음 · ${왜끝났나}`);
 
   const 파일들 = (끝?.files ?? []).filter((f) => !f.dir);
   if (파일들.length) {