deel-local-cli 1.15.1 → 1.17.1

package/src/tools/fig.js

@@ -0,0 +1,393 @@
+/**
+ * Figma `.fig` 읽기 — 화면 하나가 어떤 조각으로 짜였는지.
+ *
+ * ── 왜 읽나 ────────────────────────────────────────────────────────────
+ *
+ * 「이 시안대로 만들어 줘」 하면서 `.fig` 를 건네는 일이 실제로 잦다. 그런데
+ * 지금까지 그 파일은 여기서 끝났다 — 「이진 파일이라 못 읽습니다」. 그러면
+ * 사람이 화면을 캡처해서 다시 붙이거나, 글자를 하나씩 옮겨 적는다.
+ *
+ * 안에 있는 것은 그림만이 아니다. **틀 이름 · 글 · 크기 · 겹친 차례**가 다
+ * 글자로 들어 있다. 「로그인」 이라는 틀 밑에 「이메일」 「비밀번호」 라는
+ * 글상자가 있고 폭이 375 라는 것 — 코드를 짜는 데 필요한 것은 대부분 그거다.
+ *
+ * ── 무엇을 안 하나 ─────────────────────────────────────────────────────
+ *
+ * 그림은 안 그린다. 색·그림자·글꼴 굵기도 안 낸다. 낼 수야 있지만 그걸 다
+ * 실으면 창이 그것만으로 찬다. **이름과 글과 짜임**까지가 이 읽개의 몫이다.
+ *
+ * 쓰기는 아예 없다. 글로 왕복시킨 시안은 시안이 아니다.
+ *
+ * ── 어떻게 생겼나 ──────────────────────────────────────────────────────
+ *
+ *   .fig  =  zip
+ *            ├ canvas.fig      ← 알맹이. 이게 Kiwi 다
+ *            ├ meta.json       ← 파일 이름 · 만든 판
+ *            ├ thumbnail.png   ← 미리보기
+ *            └ images/…        ← 쓰인 그림들
+ *
+ *   canvas.fig =  "fig-kiwi"(8바이트)  판:u32
+ *                 덩이길이:u32 덩이   ← 스키마
+ *                 덩이길이:u32 덩이   ← 알맹이
+ *
+ * 두 덩이는 눌려 있다. 예전 파일은 deflate, 요즘 파일은 zstd 다. 앞 네
+ * 바이트를 보고 가른다 — 확장자나 판 번호로 짐작하지 않는다. 짐작이 틀리면
+ * 「파일이 깨졌다」 는 엉뚱한 말이 나간다.
+ *
+ * ── zstd 와 Node 판 ────────────────────────────────────────────────────
+ *
+ * Node 가 zstd 를 들고 온 것은 22.15 부터다. 이 프로그램의 바닥은 20 이다.
+ * 그래서 zstd 로 눌린 파일을 Node 20 에서 열면 **못 연다.** 그때 「깨진
+ * 파일입니다」 라고 하면 사람은 파일을 의심하며 시간을 버린다. 무엇이
+ * 없어서 못 하는지, 그럼 무엇을 하면 되는지까지 말한다.
+ */
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { inflateRawSync, inflateSync } from 'node:zlib';
+import * as zlib from 'node:zlib';
+
+import { readZip, looksZip } from '../pack/zip.js';
+import { 스키마읽기, 알맹이읽기 } from './kiwi.js';
+
+const 머리들 = ['fig-kiwi', 'fig-jam.'];
+
+/** 이 파일이 `.fig` 인가. */
+export function isFigPath(p) {
+  return extname(String(p ?? '')).toLowerCase() === '.fig';
+}
+
+/**
+ * 우리가 담아 두는 칸 이름.
+ *
+ * Figma 스키마에는 칸이 수백 개 있고 그중 대부분이 도형 좌표다. 전부
+ * 객체로 만들면 큰 파일 하나에 몇백 MB 가 된다. 바이트는 그대로 지나가되
+ * **담기는 것만 고른다** — 이름으로 고르므로 새 판이 칸을 늘려도 안 깨진다.
+ */
+const 담을칸 = new Set([
+  'guid', 'sessionID', 'localID',
+  'parentIndex', 'position',
+  'type', 'name', 'visible',
+  'size', 'x', 'y',
+  'textData', 'characters',
+]);
+
+/**
+ * 뿌리에서 「도형 목록」 칸을 찾는다.
+ *
+ * 이름으로 `nodeChanges` 를 찾되, **못 찾으면 생김새로 찾는다** — 배열이고,
+ * 그 알맹이 정의에 `guid` 칸이 있는 것. 이름은 Figma 가 바꿀 수 있지만
+ * 「도형마다 고유 번호가 있다」 는 것은 이 형식의 뼈대라 안 바뀐다.
+ *
+ * 이름만 믿었다가 못 찾으면 「도형이 하나도 없습니다」 라는 거짓말이 나간다.
+ */
+function 도형칸찾기(스키마, 뿌리이름) {
+  const d = 스키마.정의들[스키마.이름표.get(뿌리이름)];
+  const 배열칸 = (d?.칸들 ?? []).filter((f) => f.배열 && f.형 >= 0);
+  const 이름난것 = 배열칸.find((f) => f.이름 === 'nodeChanges');
+  if (이름난것) return 이름난것.이름;
+  const 닮은것 = 배열칸.find((f) => 스키마.정의들[f.형]?.칸들?.some((x) => x.이름 === 'guid'));
+  return 닮은것?.이름 ?? null;
+}
+
+/* 이보다 많으면 그림에 다 못 싣는다. 자르되 잘랐다고 말한다. */
+const 노드최대 = 20000;
+
+/** 앞 네 바이트로 무엇에 눌렸는지 본다. 판 번호로 짐작하지 않는다. */
+function 눌린방식(buf) {
+  if (buf.length >= 4 && buf.readUInt32LE(0) === 0xfd2fb528) return 'zstd';
+  // zlib 은 첫 바이트가 0x78 이고 두 바이트를 31 로 나누면 떨어진다.
+  if (buf.length >= 2 && buf[0] === 0x78 && ((buf[0] << 8) + buf[1]) % 31 === 0) return 'zlib';
+  return 'deflate';
+}
+
+export const zstd있나 = () => typeof zlib.zstdDecompressSync === 'function';
+
+/**
+ * zstd 가 없을 때 하는 말.
+ *
+ * 「깨진 파일입니다」 라고 하면 사람은 파일을 의심하며 시간을 버린다. 파일은
+ * 멀쩡하고 **여기 Node 가 못 푸는 것**이다. 그 둘은 하는 일이 완전히 다르다.
+ */
+export function zstd안내() {
+  return 'zstd 로 눌린 .fig 입니다. 이 Node 에는 zstd 가 없습니다'
+    + ` (지금 ${process.version} · Node 22.15 부터 들어왔습니다).\n`
+    + '  파일이 깨진 것이 아닙니다 — 여기서 못 푸는 것뿐입니다.\n'
+    + '  고치는 법: Node 를 22.15 이상으로 올리면 그대로 읽힙니다.';
+}
+
+/**
+ * 덩이 하나를 편다.
+ *
+ * 상한을 **펴기 전에** 건다. 다 펴 놓고 재면 이미 늦다 — 작은 조각이 몇 GB
+ * 로 부푸는 파일을 남이 만들어 줄 수 있다(zip.js 가 같은 이유로 같은 일을
+ * 한다).
+ */
+function 펴기(덩이, 상한) {
+  const 방식 = 눌린방식(덩이);
+  if (방식 === 'zstd') {
+    if (!zstd있나()) {
+      const err = new Error(zstd안내());
+      err.끝났다 = true;
+      throw err;
+    }
+    return zlib.zstdDecompressSync(덩이, { maxOutputLength: 상한 });
+  }
+  if (방식 === 'zlib') return inflateSync(덩이, { maxOutputLength: 상한 });
+  return inflateRawSync(덩이, { maxOutputLength: 상한 });
+}
+
+/**
+ * `canvas.fig` 를 덩이 목록으로 가른다.
+ *
+ * @returns {{판:number, 덩이들:Buffer[]}}
+ */
+export function 통가르기(buf) {
+  if (buf.length < 12) throw new Error('canvas.fig 가 너무 짧습니다');
+  const 머리 = buf.toString('latin1', 0, 8);
+  if (!머리들.includes(머리)) {
+    throw new Error(`Figma 알맹이가 아닙니다 — 앞머리가 ${JSON.stringify(머리)} 입니다`);
+  }
+  const 판 = buf.readUInt32LE(8);
+
+  const 덩이들 = [];
+  let p = 12;
+  while (p + 4 <= buf.length) {
+    const 길이 = buf.readUInt32LE(p);
+    p += 4;
+    // 남은 것보다 길다고 적혀 있으면 그 자리에서 거짓이다. 그대로 잘라
+    // 가면 뒤 덩이가 통째로 헛것이 된다.
+    if (길이 > buf.length - p) throw new Error(`덩이 길이가 파일보다 깁니다 (${길이})`);
+    덩이들.push(buf.subarray(p, p + 길이));
+    p += 길이;
+  }
+  if (덩이들.length < 2) throw new Error(`덩이가 ${덩이들.length}개뿐입니다 — 스키마와 알맹이가 둘 다 있어야 합니다`);
+  return { 판, 덩이들 };
+}
+
+/** guid 를 한 줄 열쇠로. 없으면 null — 뿌리 노드는 부모가 없다. */
+function 열쇠(g) {
+  if (!g || typeof g !== 'object') return null;
+  return `${g.sessionID ?? 0}:${g.localID ?? 0}`;
+}
+
+/** 크기를 `375×812` 로. 소수점은 버린다 — 시안 치수는 정수로 읽는 게 맞다. */
+function 크기말(size) {
+  if (!size || typeof size !== 'object') return '';
+  const w = Number(size.x);
+  const h = Number(size.y);
+  if (!Number.isFinite(w) || !Number.isFinite(h) || (!w && !h)) return '';
+  return ` ${Math.round(w)}×${Math.round(h)}`;
+}
+
+/** 글은 한 줄로 접는다. 시안의 글상자에는 줄바꿈이 흔하다. */
+function 글말(node) {
+  const s = node?.textData?.characters;
+  if (typeof s !== 'string' || !s.trim()) return '';
+  const 한줄 = s.replace(/\s+/g, ' ').trim();
+  return ` "${한줄.length > 120 ? `${한줄.slice(0, 120)}…` : 한줄}"`;
+}
+
+/**
+ * 노드 목록을 부모-자식으로 엮는다.
+ *
+ * 차례는 `position` 이라는 글자열이 정한다 — 사이에 끼워 넣을 수 있게 만든
+ * 값이라 **글자 순서가 곧 화면 순서**다. 숫자로 바꾸려 들면 안 된다.
+ */
+function 나무엮기(노드들) {
+  const 자리표 = new Map();
+  for (const n of 노드들) {
+    const k = 열쇠(n.guid);
+    if (k && !자리표.has(k)) 자리표.set(k, n);
+  }
+
+  const 자식표 = new Map();
+  const 뿌리들 = [];
+  for (const n of 노드들) {
+    const 부모 = 열쇠(n.parentIndex?.guid);
+    if (부모 && 자리표.has(부모)) {
+      if (!자식표.has(부모)) 자식표.set(부모, []);
+      자식표.get(부모).push(n);
+    } else {
+      뿌리들.push(n);
+    }
+  }
+  for (const 목록 of 자식표.values()) {
+    목록.sort((a, b) => String(a.parentIndex?.position ?? '').localeCompare(String(b.parentIndex?.position ?? '')));
+  }
+  return { 자리표, 자식표, 뿌리들 };
+}
+
+/** 한 갈래를 줄들로 편다. 깊이는 두 칸씩. */
+function 가지풀기(뿌리, 자식표, 줄들, 깊이, 셈) {
+  if (셈.남은 <= 0) return;
+  const 들여 = '  '.repeat(Math.min(깊이, 12));
+  const 갈래 = typeof 뿌리.type === 'string' ? 뿌리.type : String(뿌리.type ?? '?');
+  const 이름 = String(뿌리.name ?? '').trim();
+  const 숨김 = 뿌리.visible === false ? ' (숨김)' : '';
+  줄들.push(`${들여}- ${갈래}${이름 ? ` · ${이름}` : ''}${크기말(뿌리.size)}${글말(뿌리)}${숨김}`);
+  셈.남은 -= 1;
+  for (const 아이 of 자식표.get(열쇠(뿌리.guid)) ?? []) {
+    가지풀기(아이, 자식표, 줄들, 깊이 + 1, 셈);
+  }
+}
+
+/**
+ * `.fig` 하나를 읽는다.
+ *
+ * 던지지 않는다 — 깨진 파일은 도구 실행 한가운데서 만나는 것이라, 예외가
+ * 나면 「파일이 깨졌다」 가 「도구가 터졌다」 로 보고된다. 다른 읽개들과
+ * 같은 규칙이고, 돌려주는 모양도 같다(`덩이들`).
+ *
+ * @returns {{ok:true, 갈래:'fig', 덩이들:[{이름,문단들}], 말:string[], 노드수:number}
+ *          |{ok:false, error:string, 끝났다?:boolean}}
+ */
+export function readFig(경로또는버퍼) {
+  let buf;
+  try {
+    buf = Buffer.isBuffer(경로또는버퍼) ? 경로또는버퍼 : readFileSync(경로또는버퍼);
+  } catch (err) {
+    return { ok: false, error: `못 읽었습니다: ${err.message}` };
+  }
+
+  const 말 = [];
+  let 알맹이;
+  let 메타 = null;
+  let 그림수 = 0;
+  let 미리보기 = false;
+
+  // 꾸러미로 온 것이 보통이지만, `canvas.fig` 만 따로 떨어져 오기도 한다.
+  if (looksZip(buf)) {
+    let 꾸러미;
+    try {
+      꾸러미 = readZip(buf);
+    } catch (err) {
+      return { ok: false, error: `.fig 꾸러미를 풀지 못했습니다 — ${err.message}` };
+    }
+    for (const [이름] of 꾸러미.files) {
+      if (/^images\//i.test(이름)) 그림수 += 1;
+      if (/^thumbnail\.png$/i.test(이름)) 미리보기 = true;
+    }
+    const 메타몸 = 꾸러미.files.get('meta.json');
+    if (메타몸) { try { 메타 = JSON.parse(메타몸.toString('utf8')); } catch { 메타 = null; } }
+    알맹이 = 꾸러미.files.get('canvas.fig');
+    if (!알맹이) {
+      return {
+        ok: false,
+        끝났다: true,
+        error: '.fig 꾸러미 안에 canvas.fig 가 없습니다 — '
+          + `든 것: ${[...꾸러미.files.keys()].slice(0, 8).join(' · ') || '(빈 꾸러미)'}`,
+      };
+    }
+  } else {
+    알맹이 = buf;
+  }
+
+  let 통;
+  try {
+    통 = 통가르기(알맹이);
+  } catch (err) {
+    return { ok: false, error: err.message, 끝났다: true };
+  }
+
+  const 상한 = 256 * 1024 * 1024;
+  let 스키마;
+  let 몸;
+  try {
+    스키마 = 스키마읽기(펴기(통.덩이들[0], 16 * 1024 * 1024));
+    몸 = 펴기(통.덩이들[1], 상한);
+  } catch (err) {
+    return { ok: false, error: `.fig 알맹이를 풀지 못했습니다 — ${err.message}`, 끝났다: !!err.끝났다 };
+  }
+
+  const 뿌리이름 = 스키마.이름표.has('Message')
+    ? 'Message'
+    : 스키마.정의들.find((d) => d.갈래 === 'MESSAGE')?.이름;
+  if (!뿌리이름) return { ok: false, error: '.fig 스키마에 읽을 시작점이 없습니다', 끝났다: true };
+
+  const 도형칸 = 도형칸찾기(스키마, 뿌리이름);
+  if (!도형칸) {
+    const 있는칸 = (스키마.정의들[스키마.이름표.get(뿌리이름)]?.칸들 ?? [])
+      .map((f) => f.이름).slice(0, 10).join(' · ');
+    return {
+      ok: false,
+      끝났다: true,
+      error: `.fig 를 열었는데 도형 목록 칸을 못 찾았습니다. ${뿌리이름} 에 있는 칸: ${있는칸 || '(없음)'}`,
+    };
+  }
+
+  let 것;
+  try {
+    것 = 알맹이읽기(스키마, 몸, 뿌리이름, (_정의, 칸) => 칸 === 도형칸 || 담을칸.has(칸));
+  } catch (err) {
+    // 여기까지 왔는데 못 읽었으면 스키마와 알맹이가 안 맞는 것이다. 반쯤
+    // 읽은 것을 내놓지 않는다 — 반만 맞는 시안은 틀린 시안보다 나쁘다.
+    return { ok: false, error: `.fig 를 스키마대로 읽지 못했습니다 — ${err.message}`, 끝났다: true };
+  }
+
+  const 노드들 = Array.isArray(것?.[도형칸]) ? 것[도형칸].filter(Boolean) : [];
+  if (!노드들.length) {
+    return { ok: false, error: '.fig 를 열었는데 안에 도형이 하나도 없습니다', 끝났다: true };
+  }
+
+  const { 자식표, 뿌리들 } = 나무엮기(노드들);
+
+  /*
+   * 쪽은 CANVAS 다.
+   *
+   * Figma 에서 「페이지」 라고 부르는 것이 파일 안에서는 CANVAS 이고,
+   * 그 위가 DOCUMENT 하나다. 쪽마다 한 덩이로 내면 마크다운에서 `## 쪽이름`
+   * 이 되고, 글로 낼 때도 `--- 쪽이름 ---` 으로 갈린다.
+   */
+  const 문서 = 뿌리들.find((n) => n.type === 'DOCUMENT') ?? 뿌리들[0];
+  const 쪽들 = (자식표.get(열쇠(문서?.guid)) ?? []).filter((n) => n.type === 'CANVAS');
+
+  const 셈 = { 남은: 노드최대 };
+  const 덩이들 = [];
+
+  const 개요 = [];
+  const 파일이름 = 메타?.file_name ?? 메타?.fileName ?? 메타?.name;
+  if (파일이름) 개요.push(`파일 이름: ${파일이름}`);
+  개요.push(`쪽 ${쪽들.length || 1}개 · 도형 ${노드들.length.toLocaleString('en-US')}개`);
+  if (그림수) 개요.push(`쓰인 그림 ${그림수}개 (images/ 안에 있습니다 — 이 읽개는 그림을 안 풉니다)`);
+  if (미리보기) 개요.push('미리보기 그림 thumbnail.png 가 들어 있습니다');
+  개요.push('색·그림자·글꼴은 안 냅니다. 이름 · 글 · 크기 · 짜임까지입니다.');
+  덩이들.push({ 이름: '개요', 문단들: 개요 });
+
+  if (쪽들.length) {
+    for (const 쪽 of 쪽들) {
+      const 줄들 = [];
+      for (const 아이 of 자식표.get(열쇠(쪽.guid)) ?? []) 가지풀기(아이, 자식표, 줄들, 0, 셈);
+      덩이들.push({
+        이름: String(쪽.name ?? '').trim() || '이름 없는 쪽',
+        문단들: 줄들.length ? 줄들 : ['(이 쪽은 비어 있습니다.)'],
+      });
+    }
+  } else {
+    // DOCUMENT/CANVAS 짜임이 아닌 파일도 있다 — 그때는 있는 대로 편다.
+    const 줄들 = [];
+    for (const n of 뿌리들) 가지풀기(n, 자식표, 줄들, 0, 셈);
+    덩이들.push({ 이름: '도형', 문단들: 줄들 });
+  }
+
+  if (셈.남은 <= 0) {
+    말.push(`도형이 ${노드최대.toLocaleString('en-US')}개를 넘어 거기까지만 폈습니다 — 뒷부분은 안 실렸습니다`);
+  }
+
+  return { ok: true, 갈래: 'fig', 덩이들, 말, 노드수: 노드들.length };
+}
+
+/** 한 줄 요약. Read 의 summary 자리로 간다. */
+export function summarize(r) {
+  if (!r?.ok) return '';
+  const 쪽 = Math.max(0, r.덩이들.length - 1);
+  return `fig · 쪽 ${쪽}개 · 도형 ${r.노드수.toLocaleString('en-US')}개`;
+}
+
+/** 고치려 들 때 하는 말. 문서·PDF 와 같은 꼴 — 왜 안 되는지와 그럼 어떻게 하는지. */
+export function fig는못고침(보인이름) {
+  return `.fig 시안은 이 도구로 고칠 수 없습니다: ${보인이름}\n`
+    + '  읽기만 됩니다 (이름 · 글 · 크기 · 짜임을 글로 냅니다). 시안을 글로\n'
+    + '  왕복시키면 그 자리에서 시안이 아니게 되기 때문입니다.\n'
+    + `  고칠 것이 있으면 Figma 에서 고치고 다시 내보내 주세요.\n`
+    + `  ${basename(보인이름)} 자체는 안 건드렸습니다.`;
+}

package/src/tools/hwpxwrite.js

@@ -0,0 +1,268 @@
+/**
+ * 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="1">
+<hh:fontface lang="HANGUL" 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>
+</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: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>`;
+
+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}"><hp:t>${esc(p.글)}</hp:t></hp:run>`
+    + `<hp:linesegarray><hp:lineseg textpos="0" vertpos="0" vertsize="1000" textheight="1000" baseline="850" spacing="600" horzpos="0" horzsize="42520" flags="393216"/></hp:linesegarray>`
+    + '</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(' · ');
+}