deel-local-cli 1.20.12 → 2.0.0

package/src/tools/{/355/231/225/354/235/270/353/262/225.js → checkmethods.js}

@@ -123,6 +123,29 @@ const 검사파일 = new RegExp(
   `^(?:${검사말}[-_][^.]+|.+[._]${뒤에붙는말}|${뒤에붙는말})\\.${검사끝}$`, 'i');
 const 부르는법 = { '.js': 'node', '.mjs': 'node', '.cjs': 'node', '.ts': 'node', '.py': 'python', '.sh': 'sh' };
 
+/*
+ * ── 여기서 만든 글은 그대로 **셸 명령**이 된다 ──────────────────────────
+ *
+ * tools/verify.js 가 이 목록을 「전부 Bash 로 돌려라」 와 함께 모델에게 붙인다.
+ * 그런데 파일 이름을 정하는 것은 우리가 아니라 **그 저장소**다. 남의 저장소를
+ * 열어 보는 것이 이 프로그램의 일이니, 거기 적힌 이름은 믿을 글이 아니다.
+ *
+ *   sh scripts/test-a;echo x.sh     명령이 둘이 된다
+ *   sh scripts/qa-b$(id).sh         sh 가 뜨기도 전에 돈다
+ *   node test/my unit.test.js       빈칸 하나로 엉뚱한 파일을 찾다 죽는다
+ *
+ * 그래서 감싸면 한 낱말로 남는 것은 겹따옴표로 감싸고, 감싸도 안 되는 것
+ * (겹따옴표·백틱·$·역슬래시·줄바꿈)은 **아예 안 알려 준다.** 홑따옴표는
+ * 겹따옴표 안에서 그냥 글자라 감싸는 쪽으로 남긴다 — 막을 까닭이 없는 것을
+ * 막으면 그것도 없는 것을 말하는 셈이다.
+ */
+const 감싸도새는글자 = /["`$\\\r\n]/;
+const 그냥써도되는길 = /^[A-Za-z0-9._\-/¡-￿]+$/;
+function 셸에실을길(길) {
+  if (감싸도새는글자.test(길)) return null;
+  return 그냥써도되는길.test(길) ? 길 : `"${길}"`;
+}
+
 /*
  * 다른 생태계의 관례.
  *
@@ -187,7 +210,9 @@ export function 확인법들(뿌리) {
       const 끝 = 이름.slice(이름.lastIndexOf('.')).toLowerCase();
       const 앞 = 부르는법[끝];
       if (!앞) continue;
-      담기(`${앞} ${폴더}/${이름}`, `${폴더}/`);
+      const 길 = 셸에실을길(`${폴더}/${이름}`);
+      if (!길) continue;
+      담기(`${앞} ${길}`, `${폴더}/`);
     }
   }
 

package/src/tools/clipboard.js

@@ -34,8 +34,8 @@ import { 치수읽기, 픽셀한도 } from '../backend/vision.js';
 /** 이보다 큰 그림은 안 받는다. 화면 캡처 한 장은 보통 1MB 안쪽이다. */
 export const 그림한도 = 12 * 1024 * 1024;
 
-const 있나 = (이름, 인자) => {
-  const r = spawnSync(이름, 인자, { encoding: 'utf8', timeout: 5000, windowsHide: true });
+const 있나 = (부르기, 이름, 인자) => {
+  const r = 부르기(이름, 인자, { encoding: 'utf8', timeout: 5000, windowsHide: true });
   return !r.error && r.status === 0;
 };
 
@@ -46,24 +46,31 @@ const 있나 = (이름, 인자) => {
  * 셸을 두 번 거치면서 깨지고, 그 깨짐이 PC 마다 다르게 나타난다. 스크립트는
  * ASCII 로만 쓴다 — Windows PowerShell 5.1 은 BOM 없는 .ps1 을 그 PC 의 옛
  * 코드페이지로 읽어서, 한글이 섞이면 문법이 무너진다(src/completion.js 참고).
+ *
+ * 그래서 **저장할 경로는 스크립트 글에 넣지 않고 인자로 넘긴다.** 앞서는
+ * 경로를 글에 박아 넣었는데, 임시 폴더는 사용자 폴더 아래라 계정 이름이
+ * 한글인 PC 에서는 그 경로가 latin1 로 적히며 깨졌다 — 그림이 엉뚱한 자리로
+ * 저장되고 사람은 「클립보드를 못 읽었습니다」 만 봤다. 인자는 운영체제가
+ * 유니코드 그대로 넘겨 주니 경로가 무엇이든 안 깨진다.
  */
-function 윈도우에서(방) {
+function 윈도우에서(방, 부르기) {
   const 낼곳 = join(방, 'clip.png');
   const 스크립트 = join(방, 'grab.ps1');
   const 글 = [
+    'param([string]$Out)',
     '$ErrorActionPreference = "Stop"',
     'Add-Type -AssemblyName System.Windows.Forms',
     'Add-Type -AssemblyName System.Drawing',
     '$img = [System.Windows.Forms.Clipboard]::GetImage()',
     'if ($img -eq $null) { Write-Output "NOIMAGE"; exit 0 }',
-    `$img.Save(${JSON.stringify(낼곳)}, [System.Drawing.Imaging.ImageFormat]::Png)`,
+    '$img.Save($Out, [System.Drawing.Imaging.ImageFormat]::Png)',
     'Write-Output "OK"',
   ].join('\n');
-  // Buffer 로 적어서 인코딩이 끼어들 자리를 없앤다.
+  // Buffer 로 적어서 인코딩이 끼어들 자리를 없앤다. 글은 ASCII 뿐이다 — 경로는 param 으로만 들어온다.
   writeFileSync(스크립트, Buffer.from(글, 'latin1'));
 
-  const r = spawnSync('powershell', [
-    '-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-File', 스크립트,
+  const r = 부르기('powershell', [
+    '-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-File', 스크립트, 낼곳,
   ], { encoding: 'utf8', timeout: 20000, windowsHide: true });
 
   if (r.error) return { ok: false, 왜: `파워셸을 못 불렀습니다: ${r.error.message}` };
@@ -81,10 +88,14 @@ function 윈도우에서(방) {
  *
  * osascript 로 PNG 를 꺼내면 «data PNGf89504e47…» 꼴의 16진수 글이 나온다.
  * 그림이 없으면 오류를 내므로, 그것으로 「없음」을 가른다.
+ *
+ * 16진수는 바이트의 두 배다. 받을 자리(maxBuffer)를 기본값 1MB 로 두었더니
+ * PNG 512KB 만 넘어도 ENOBUFS 로 끊겼다 — 레티나 화면 캡처는 대개 그보다 커서
+ * 맥에서는 보통 캡처가 안 붙었다. 그림 한도의 두 배에 여유를 더해 잡는다.
  */
-function 맥에서() {
-  const r = spawnSync('osascript', ['-e', 'the clipboard as «class PNGf»'], {
-    encoding: 'utf8', timeout: 20000,
+function 맥에서(부르기) {
+  const r = 부르기('osascript', ['-e', 'the clipboard as «class PNGf»'], {
+    encoding: 'utf8', timeout: 20000, maxBuffer: 그림한도 * 2 + 1024 * 1024,
   });
   if (r.error) return { ok: false, 왜: `osascript 를 못 불렀습니다: ${r.error.message}` };
   const 낸말 = String(r.stdout ?? '');
@@ -92,7 +103,17 @@ function 맥에서() {
   if (!m) {
     // 그림이 아니면 osascript 가 오류를 낸다. 그건 「없음」이지 고장이 아니다.
     if (r.status !== 0) return { ok: false, 없음: true };
-    return { ok: false, 없음: true };
+    /*
+     * 0 으로 끝났는데 PNG 가 안 나온 것은 **우리 탓**이다 (머리말 「둘을 갈라
+     * 말한다」). 여태 두 갈래를 써 놓고 글자까지 같은 말을 돌려줬다 — 「없음」
+     * 으로 덮이면 사람은 같은 캡처를 되풀이하고, 될 리가 없다.
+     */
+    const 탈 = String(r.stderr ?? '').split('\n').find((l) => l.trim())?.trim() ?? '';
+    return {
+      ok: false,
+      왜: `클립보드에서 그림을 못 꺼냈습니다${탈 ? ` (${탈})` : ''}`
+        + ' — 캡처를 파일로 저장한 뒤 @경로 로 붙이세요.',
+    };
   }
   return { ok: true, buf: Buffer.from(m[1], 'hex'), mime: 'image/png' };
 }
@@ -103,12 +124,12 @@ function 맥에서() {
  * 웨이랜드면 wl-paste, X11 이면 xclip. 배포판이 기본으로 안 깔아 주는 것이라
  * 없을 수 있고, 그때는 **무엇을 깔면 되는지** 알려 준다.
  */
-function 리눅스에서() {
+function 리눅스에서(부르기) {
   const 후보 = [
     { 이름: 'wl-paste', 볼것: ['--list-types'], 꺼내기: ['--type', 'image/png'] },
     { 이름: 'xclip', 볼것: ['-selection', 'clipboard', '-t', 'TARGETS', '-o'], 꺼내기: ['-selection', 'clipboard', '-t', 'image/png', '-o'] },
   ];
-  const 있는것 = 후보.filter((x) => 있나(x.이름, ['--version']) || 있나(x.이름, ['-version']));
+  const 있는것 = 후보.filter((x) => 있나(부르기, x.이름, ['--version']) || 있나(부르기, x.이름, ['-version']));
   if (!있는것.length) {
     return {
       ok: false,
@@ -118,13 +139,25 @@ function 리눅스에서() {
         + '  둘 다 안 되면 캡처를 파일로 저장한 뒤 @경로 로 붙이세요.',
     };
   }
+  /*
+   * 그림이 있다고 본 뒤 꺼내기가 막힌 것(시간 초과 · 너무 큼 · 도구 오류)은
+   * 「없음」 이 아니다. 앞서는 그것도 끝의 「없음」 으로 흘러서 사람은 캡처만
+   * 되풀이했다 — 다시 찍어도 같은 자리에서 또 막히는데. 다음 도구로 한 번 더
+   * 해 보고, 끝내 못 꺼냈으면 그 까닭을 말한다.
+   */
+  let 못꺼냄 = null;
   for (const x of 있는것) {
-    const 종류 = spawnSync(x.이름, x.볼것, { encoding: 'utf8', timeout: 10000 });
+    const 종류 = 부르기(x.이름, x.볼것, { encoding: 'utf8', timeout: 10000 });
     if (!/image\/png/i.test(String(종류.stdout ?? ''))) continue;
-    const r = spawnSync(x.이름, x.꺼내기, { timeout: 20000, maxBuffer: 64 * 1024 * 1024 });
-    if (r.error || !r.stdout?.length) continue;
+    const r = 부르기(x.이름, x.꺼내기, { timeout: 20000, maxBuffer: 64 * 1024 * 1024 });
+    if (r.error || !r.stdout?.length) {
+      const 탈 = r.error?.message || String(r.stderr ?? '').split('\n').find((l) => l.trim())?.trim() || '빈 응답';
+      못꺼냄 ??= `${x.이름}: ${탈}`;
+      continue;
+    }
     return { ok: true, buf: Buffer.from(r.stdout), mime: 'image/png' };
   }
+  if (못꺼냄) return { ok: false, 왜: `클립보드에 그림은 있는데 꺼내지 못했습니다 (${못꺼냄}) — 캡처를 파일로 저장한 뒤 @경로 로 붙이세요.` };
   return { ok: false, 없음: true };
 }
 
@@ -135,16 +168,16 @@ function 리눅스에서() {
  *          | {ok:false, 없음:true}          그림이 없다 (사람이 다시 캡처하면 된다)
  *          | {ok:false, 왜:string}}         못 꺼냈다 (까닭과 길을 같이 준다)
  */
-export function 클립보드그림({ platform = process.platform } = {}) {
+export function 클립보드그림({ platform = process.platform, 부르기 = spawnSync } = {}) {
   let 방 = null;
   try {
     if (platform === 'win32') {
       방 = mkdtempSync(join(tmpdir(), 'deel-clip-'));
-      const r = 윈도우에서(방);
+      const r = 윈도우에서(방, 부르기);
       return 잰다(r);
     }
-    if (platform === 'darwin') return 잰다(맥에서());
-    if (platform === 'linux') return 잰다(리눅스에서());
+    if (platform === 'darwin') return 잰다(맥에서(부르기));
+    if (platform === 'linux') return 잰다(리눅스에서(부르기));
     return { ok: false, 왜: `${platform} 에서는 아직 클립보드 그림을 못 꺼냅니다 — 파일로 저장한 뒤 @경로 로 붙이세요.` };
   } catch (err) {
     return { ok: false, 왜: `클립보드를 읽다 막혔습니다: ${err.message}` };

package/src/tools/convert.js

@@ -33,7 +33,9 @@ import { basename, extname, join } from 'node:path';
 
 /** 변환해서 읽어 볼 만한 확장자. 여기 없는 것은 손대지 않는다. */
 const 바꿔볼확장자 = new Set([
-  '.ppt', '.doc', '.xls',      // 옛 Office (OLE 복합문서)
+  // 옛 Office (OLE 복합문서). .xlt 는 .xls 의 서식판 — 아래 직접못읽는확장자 에만 있어서
+  // 변환기가 있어도 안 불렀다 (2.0.0 6회차 CV1). 그 표는 이 표의 부분집합이어야 한다.
+  '.ppt', '.doc', '.xls', '.xlt',
   '.rtf', '.odt', '.odp', '.ods', '.wpd',
   '.pptx', '.docx', '.xlsx',   // 겉만 그 이름이고 속이 다른 것
   '.hwp',                       // 구형 한글 — soffice 가 읽는 판이 있다
@@ -102,6 +104,22 @@ function 명령짓기(cmd, 인자) {
   };
 }
 
+/*
+ * ── 윈도우에서는 이름 하나만 물어봐서는 **못 찾는다** ──────────────────
+ *
+ * scoop·choco 로 깔면 PATH 에 놓이는 것은 `soffice.cmd` 껍데기다. Node 의
+ * spawn 은 PATHEXT 를 안 보므로 `soffice` 로 물으면 ENOENT 가 나고(그 껍데기를
+ * 그냥 부르면 EINVAL 이다), 그러면 우리는 사람이 눈앞에서 쓰고 있는 프로그램을
+ * 두고 「이 PC 에 변환기가 없습니다」 라고 말한다 — 바로 위 명령짓기 머리말이
+ * 다루겠다고 적어 둔 그 껍데기다. 찾을 때도 확장자까지 붙여 물어본다.
+ * 부르는 것은 이미 된다 — `.cmd`·`.bat` 는 명령짓기 가 cmd.exe 로 감싼다.
+ */
+export function soffice이름들(platform = process.platform) {
+  return platform === 'win32'
+    ? ['soffice.exe', 'soffice.com', 'soffice.cmd', 'soffice.bat', 'soffice']
+    : ['soffice'];
+}
+
 /*
  * 변환은 **비동기로** 부른다.
  *
@@ -146,8 +164,10 @@ export function 변환기찾기({ 다시 = false, env = process.env, platform =
     return 본것;
   }
   let soffice = null;
-  if (돌아가나('soffice', ['--version'])) soffice = 'soffice';
-  else {
+  for (const 이름 of soffice이름들(platform)) {
+    if (돌아가나(이름, ['--version'])) { soffice = 이름; break; }
+  }
+  if (!soffice) {
     for (const p of soffice자리) {
       if (existsSync(p) && 돌아가나(p, ['--version'])) { soffice = p; break; }
     }
@@ -184,22 +204,36 @@ export function 변환기말(찾은것 = 변환기찾기()) {
  */
 export function 못바꿈말(보인이름, 확장자, 찾은것 = 변환기찾기()) {
   const 갈래 = String(확장자 ?? '').replace(/^\./, '').toLowerCase();
-  const 없다 = !찾은것.soffice && !찾은것.textutil;
-  const 길 = 없다
-    ? '이 PC 에 LibreOffice(soffice)가 없어서 바꿔 읽을 수도 없습니다.'
-    : '이 PC 의 변환기로 바꿔 봤지만 글이 안 나왔습니다.';
+  /*
+   * 「바꿔 봤다」 는 **이 갈래를 받는 변환기가 있을 때만** 적는다 (2.0.0 6회차 CV3·CV4).
+   *
+   * 변환기가 하나라도 있으면 해 본 것으로 쳤다. 맥은 textutil 이 늘 있는데 textutil 은
+   * doc·rtf·odt·docx 만 받는다 — 그래서 맥의 .ppt·.xls·.hwp 가 전부 **안 해 본 것**을
+   * 「바꿔 봤지만 글이 안 나왔습니다」 로 받았고 LibreOffice 안내도 빠졌다. 그리고
+   * DEEL_CONVERT=off 로 일부러 끈 사람에게 「설치하면 빌려 씁니다」 라고 했다.
+   */
+  const 껐나 = !찾은것.soffice && !찾은것.textutil && /DEEL_CONVERT=off/.test(String(찾은것.왜 ?? ''));
+  const 받는것있나 = !!찾은것.soffice || (!!찾은것.textutil && textutil갈래.has(`.${갈래}`));
+  const 길 = 껐나 ? `${찾은것.왜} — 그래서 바꿔 읽지 않았습니다.`
+    : 받는것있나 ? '이 PC 의 변환기로 바꿔 봤지만 글이 안 나왔습니다.'
+      : 찾은것.textutil ? '이 PC 의 textutil 은 이 형식을 못 바꾸고, LibreOffice(soffice)는 없습니다.'
+        : '이 PC 에 LibreOffice(soffice)가 없어서 바꿔 읽을 수도 없습니다.';
   return `${보인이름} 은 deel 이 직접 못 읽는 형식입니다 (.${갈래}).\n`
     + `${길}\n`
     + `해결: 원래 프로그램에서 ${새이름(갈래)} 로 저장한 뒤 다시 주세요.`
-    + (없다 ? ' 또는 LibreOffice 를 설치하면 deel 이 빌려 씁니다.' : '')
+    + (!껐나 && !받는것있나 ? ' 또는 LibreOffice 를 설치하면 deel 이 빌려 씁니다.' : '')
     + '\n**같은 파일을 다시 Read 하지 마세요. 결과는 같습니다.**';
 }
 
+/** textutil(맥)이 받는 갈래. 글로바꾸기 와 못바꿈말 이 같은 표를 본다 — 따로 적으면 한쪽만 고쳐진다. */
+const textutil갈래 = new Set(['.doc', '.rtf', '.odt', '.docx']);
+
 /** 그 갈래를 무엇으로 저장하면 읽히는지. */
 function 새이름(갈래) {
   if (갈래 === 'ppt') return 'pptx';
   if (갈래 === 'doc' || 갈래 === 'rtf' || 갈래 === 'odt' || 갈래 === 'wpd') return 'docx';
-  if (갈래 === 'xls' || 갈래 === 'ods') return 'xlsx';
+  // .xlt 는 .xls 의 서식판이다 — 「pdf 나 txt」 로 떨어지면 표가 사라진다 (CV1).
+  if (갈래 === 'xls' || 갈래 === 'xlt' || 갈래 === 'ods') return 'xlsx';
   if (갈래 === 'odp') return 'pptx';
   if (갈래 === 'hwp') return 'hwpx';
   return 'pdf 나 txt';
@@ -236,7 +270,7 @@ export async function 글로바꾸기(abs, root, { timeout = 90000, 찾은것 =
    * OS 에 붙어 있는 것이라 곧바로 답한다. 둘 다 되는 자리면 빠른 쪽이 맞다.
    */
   const 확장자 = extname(abs).toLowerCase();
-  if (있는것.textutil && ['.doc', '.rtf', '.odt', '.docx'].includes(확장자)) {
+  if (있는것.textutil && textutil갈래.has(확장자)) {
     const 나온것 = join(받을곳, `${basename(abs, 확장자)}.txt`);
     const r = await 부르기('textutil', ['-convert', 'txt', '-output', 나온것, abs], { timeout, signal });
     if (!r.error && r.status === 0 && existsSync(나온것)) {
@@ -259,44 +293,91 @@ export async function 글로바꾸기(abs, root, { timeout = 90000, 찾은것 =
    * 있으면 새 부탁을 그쪽에 넘기고 **곧바로 끝나 버린다.** 사람이 LibreOffice 를
    * 열어 둔 PC 에서 변환이 조용히 아무것도 안 하는 것이 그 모습이다. 우리 몫의
    * 프로필을 따로 주면 그 일이 안 생긴다.
+   *
+   * ── 성공과 실패를 무엇으로 가르나 ──────────────────────────────────
+   *
+   * **종료코드 0 과 결과 파일, 둘 다** 있어야 성공이다. textutil 쪽이 이미
+   * 그 규칙이고(`status === 0 && existsSync`), 여기만 한쪽씩 봤다가 두 자리가
+   * 서로 **반대 방향**으로 틀려 있었다 (8회차) —
+   *
+   *   · 종료코드 1 로 죽으면서 반쪽 txt 를 남긴 것을 `ok:true` 로 돌려줬다.
+   *     그 깨진 글이 그대로 모델에게 갔고, 모델은 그것이 문서 전부인 줄 안다.
+   *   · 멀쩡히 끝냈는데 받을곳에 **지난번 같은 이름 txt** 가 남아 있으면
+   *     늘어난 것이 없다며 「글을 못 뽑았습니다」 — 성공을 실패로 뒤집었다.
+   *
+   * 그래서 넣기 전에 우리가 지난번에 남긴 같은 이름 txt 를 먼저 치운다. 결과를
+   * 그 이름으로 **찾지는 않는다** — 치우는 것은 우리 사본이고, 나온 것을 찾는
+   * 일은 여전히 늘어난 파일로 한다.
    */
   const 프로필 = join(받을곳, '.soffice-profile');
+  try { rmSync(join(받을곳, `${basename(abs, 확장자)}.txt`), { force: true }); } catch { /* 못 지우면 아래에서 걸린다 */ }
   const 전 = new Set(existsSync(받을곳) ? readdirSync(받을곳) : []);
-  const r = await 부르기(있는것.soffice, [
-    `-env:UserInstallation=file:///${프로필.replace(/\\/g, '/').replace(/^\/+/, '')}`,
-    '--headless', '--norestore',
-    '--convert-to', 'txt:Text',
-    '--outdir', 받을곳,
-    abs,
-  ], { timeout, signal });
+  try {
+    const r = await 부르기(있는것.soffice, [
+      `-env:UserInstallation=file:///${프로필.replace(/\\/g, '/').replace(/^\/+/, '')}`,
+      '--headless', '--norestore',
+      '--convert-to', 'txt:Text',
+      '--outdir', 받을곳,
+      abs,
+    ], { timeout, signal });
 
-  if (r.error) {
-    return { ok: false, 왜: `변환기를 못 돌렸습니다: ${r.error.message}` };
-  }
-  const 새로생긴것 = (existsSync(받을곳) ? readdirSync(받을곳) : [])
-    .filter((f) => !전.has(f) && f.toLowerCase().endsWith('.txt'));
-  if (!새로생긴것.length) {
+    if (r.error) {
+      return { ok: false, 왜: `변환기를 못 돌렸습니다: ${r.error.message}` };
+    }
+    const 새로생긴것 = (existsSync(받을곳) ? readdirSync(받을곳) : [])
+      .filter((f) => !전.has(f) && f.toLowerCase().endsWith('.txt'));
     const 끄트머리 = String(r.stderr || r.stdout || '').trim().split('\n').slice(-2).join(' ').slice(0, 200);
-    return { ok: false, 왜: `변환기가 글을 못 뽑았습니다${끄트머리 ? ` (${끄트머리})` : ''}` };
-  }
-  const 나온것 = join(받을곳, 새로생긴것[0]);
-  let text = '';
-  try { text = readFileSync(나온것, 'utf8'); } catch (err) {
-    return { ok: false, 왜: `바꾼 글을 못 읽었습니다: ${err.message}` };
+    if (r.status !== 0) {
+      // 죽으면서 남긴 반쪽 글도 **사람 문서의 조각**이다. 실패한 자리에 남기지 않는다.
+      for (const f of 새로생긴것) { try { rmSync(join(받을곳, f), { force: true }); } catch { /* 임시치우기가 거둔다 */ } }
+      return { ok: false, 왜: `변환기가 종료 ${r.status ?? '알 수 없음'} 로 끝났습니다${끄트머리 ? ` (${끄트머리})` : ''}` };
+    }
+    if (!새로생긴것.length) {
+      return { ok: false, 왜: `변환기가 글을 못 뽑았습니다${끄트머리 ? ` (${끄트머리})` : ''}` };
+    }
+    const 나온것 = join(받을곳, 새로생긴것[0]);
+    let text = '';
+    try { text = readFileSync(나온것, 'utf8'); } catch (err) {
+      return { ok: false, 왜: `바꾼 글을 못 읽었습니다: ${err.message}` };
+    } finally {
+      /*
+       * 읽었으면 곧바로 지운다.
+       *
+       * 글은 이미 손에 있다. 남겨 두면 **사람 문서의 알맹이가 사본으로 작업
+       * 폴더에 쌓인다** — 그대로 커밋되거나 압축되어 나갈 수 있는 자리다.
+       * 나중에 거두겠다는 약속은 세션이 죽으면 안 지켜진다. 지금 지운다.
+       */
+      try { rmSync(나온것, { force: true }); } catch { /* 못 지우면 임시치우기가 거둔다 */ }
+    }
+    return { ok: true, text, 쓴것: 'soffice', 파일: 나온것 };
   } finally {
     /*
-     * 읽었으면 곧바로 지운다.
-     *
-     * 글은 이미 손에 있다. 남겨 두면 **사람 문서의 알맹이가 사본으로 작업
-     * 폴더에 쌓인다** — 그대로 커밋되거나 압축되어 나갈 수 있는 자리다.
-     * 나중에 거두겠다는 약속은 세션이 죽으면 안 지켜진다. 지금 지운다.
+     * 프로필도 **여기서** 거둔다. 지우는 것이 txt 하나뿐이던 때, 그 안에는
+     * 방금 연 문서의 캐시(user/registrymodifications.xcu·backup 따위)가 그대로
+     * 남아 작업 폴더에 쌓였다 — 글은 지워 놓고 그 글의 캐시를 남긴 셈이다.
+     * 성공하든 실패하든 중단이든 한 번은 지나가라고 finally 에 둔다.
      */
-    try { rmSync(나온것, { force: true }); } catch { /* 못 지우면 임시치우기가 거둔다 */ }
+    try { rmSync(프로필, { recursive: true, force: true }); } catch { /* 못 지우면 임시치우기가 거둔다 */ }
   }
-  return { ok: true, text, 쓴것: 'soffice', 파일: 나온것 };
 }
 
-/** 떨궈 둔 것을 거둔다. 검사와 세션 끝에서 부른다. */
+/**
+ * 떨궈 둔 것을 거둔다.
+ *
+ * 「검사와 세션 끝에서 부른다」 고 적혀 있었는데 한동안 **부르는 자리가 검사뿐**이었다.
+ * 위 rmSync 들에 붙은 「못 지우면 임시치우기가 거둔다」 가 그래서 빈말이었고, 잠겨서
+ * 못 지운 임시 파일은 `.deel/tmp` 에 그대로 쌓였다(윈도우에서 soffice 가 물고 있으면
+ * 실제로 그렇게 된다). 앞선 판은 그 사실을 주석에만 적고 부르는 자리를 안 세웠다 —
+ * 거짓말하는 주석을 고쳐도 파일은 그대로 쌓인다.
+ *
+ * 이제 두 모드의 끝맺음이 이 자를 부른다: `src/repl.js` 의 정리 블록과
+ * `src/oneshot.js` 의 `내놓기`. 둘 다 조용히 부르고, 못 거둬도 끝맺음은 그대로 간다.
+ * (검사: test/convert.test.js 의 「거두는자리」)
+ *
+ * 우리가 떨군 것만 거둔다 — soffice 프로필과 `.txt` 뿐이다. 이 둘이 이 폴더에
+ * 우리가 만드는 것의 **전부**라, 사람이 여기 `.txt` 를 손수 넣어 두지 않는 한
+ * 남의 것은 안 건드린다. (`.deel/` 는 우리 살림 폴더고 git 도 안 본다.)
+ */
 export function 임시치우기(root) {
   const 자리 = 임시자리(root);
   if (!existsSync(자리)) return 0;

package/src/tools/desc.en.js

@@ -35,7 +35,13 @@
 export const 도구설명EN = {
   Read: {
     desc: 'Read one file. Line numbers come back with it. You must read a file before editing it.'
-      + ' Excel files (.xlsx/.xlsm/.xls) can be read directly too — they come back as CSV per sheet.'
+      // 한글 쪽(index.js 의 Read 스키마)과 **같은 약속**이어야 한다. 옛 .xls(OLE)는
+      // 우리가 직접 못 읽어서 이 PC 의 엑셀이나 LibreOffice 를 빌려 읽는다.
+      // 한 묶음으로 적어 두면, 그 둘이 없는 PC 에서는 모델이 사용자에게 그 파일을
+      // 달라고 해 놓고 못 읽어 걸음 하나를 버린다.
+      + ' Excel files (.xlsx/.xlsm) can be read directly too — they come back as CSV per sheet.'
+      + ' The old .xls format needs Excel or LibreOffice on this machine —'
+      + ' without one it says it cannot read the file.'
       + ' Korean HWP, Word and PowerPoint documents (.hwpx/.docx/.pptx) read directly as well —'
       + ' they come back as plain text. There is no need to ask the user to export anything.'
       + ' All of these are read-only here, though.',
@@ -49,17 +55,39 @@ export const 도구설명EN = {
     desc: 'Create a file, or overwrite one completely. Use Edit to change part of a file.'
       + ' **You can create several files in one call** — pass them as an array in files.'
       + ' Do that when you are laying out a folder structure. One call per file means one model'
-      + ' round trip per file, and an eight-file skeleton loses minutes to that.',
+      + ' round trip per file, and an eight-file skeleton loses minutes to that.'
+      // 한글 쪽(index.js 의 Write 스키마)과 **같은 약속**이어야 한다. 이 표는 설명을
+      // 통째로 갈아 끼우니, 여기 없는 줄은 안 옮겨진 것이 아니라 **지워진 것**이다 —
+      // 지시말이 ko 가 아니면 한글 문서를 만드는 길이 아예 안 나가고, 사내에 낼
+      // 보고서를 달라고 해도 모델은 .md 를 쓰고 끝낸다 (tools/hwpxwrite.js 가 안 닿는다).
+      + ' A path ending in `.hwpx` is written as a **Korean HWP document** (# / ## / ### headings'
+      + ' and bullet lists carry over). Do that when you are asked for a report or minutes to hand'
+      + ' round a Korean office. It works only when creating a new file — an existing document'
+      + ' cannot be edited.',
     params: {
       file_path: 'path to write (single file)',
       content: 'the whole file content (single file)',
       files: 'several files at once. When you use this, leave file_path and content out.',
     },
+    /*
+     * ── 배열 **속** 칸은 따로 적는다 ──────────────────────────────────────
+     *
+     * 안 적으면 그 칸만 한국어로 나간다. 하필 이 도구들이 제일 세게 미는 길이
+     * 배열 쪽이다 — 「여러 군데는 edits 로 한 번에」 「스무 개를 옮기려고 스무 번
+     * 부르지 마라」. 영어로 켠 사람은 제일 비싼 길의 설명서만 못 읽고 있었다.
+     *
+     * 겉의 말을 그대로 물려주지 않는 까닭은, 겉이 `(single file)` 처럼 **한
+     * 개짜리 길**을 가리키는 말이라서다. 그대로 쓰면 배열 안에서 틀린 말이 된다.
+     */
+    items: {
+      files: { file_path: 'path to write', content: 'the whole file content' },
+    },
   },
   Append: {
     desc: 'Append to the end of a file. This is how you build a large file — Write the first part,'
       + ' then call Append repeatedly until it is complete. Splitting it and landing it for certain'
-      + ' beats trying to fit it in one call and getting cut off. No Read needed first — you are only'
+      + ' beats trying to fit it in one call and getting cut off. Never resend the part you already'
+      + ' wrote — send only what comes next. No Read needed first — you are only'
       + ' adding to the end, so there is nothing to read.',
     params: {
       file_path: 'path of the file to append to',
@@ -78,6 +106,14 @@ export const 도구설명EN = {
       replace_all: 'true to replace every occurrence',
       edits: 'several places at once, applied in the order given. When you use this, leave the arguments above out.',
     },
+    items: {
+      edits: {
+        file_path: 'path of the file to edit',
+        old_string: 'what to replace',
+        new_string: 'what to replace it with',
+        replace_all: 'true to replace every occurrence',
+      },
+    },
   },
   Glob: {
     desc: 'Find files by name pattern. e.g. **/*.js, src/**/*.{ts,tsx}',
@@ -122,8 +158,9 @@ export const 도구설명EN = {
       + ' cut, narrow the request or raise max_chars and call again.',
     params: {
       url: 'address to read (http/https)',
-      max_chars: 'maximum characters to pull. Left out, it is sized to the model. Raise it if the'
-        + ' material comes back cut (max 120000)',
+      // The limit sits in the first sentence — narrow windows keep only the first sentences.
+      max_chars: 'maximum characters to pull (max 120000). Left out, it is sized to the model. Raise it if the'
+        + ' material comes back cut',
     },
   },
   Move: {
@@ -136,6 +173,9 @@ export const 도구설명EN = {
       moves: 'several at once. With this, from/to are unused',
       overwrite: 'overwrite the destination if it already exists. Default false, so a clash is refused',
     },
+    items: {
+      moves: { from: 'the file or folder to move', to: 'where it goes. Missing folders are created' },
+    },
   },
   Ask: {
     desc: 'Ask the person one question at a genuine fork. **First fill in `understanding` with what you'
@@ -174,6 +214,9 @@ export const 도구설명EN = {
       + ' is set by the size of the job — there is no fixed count and no cap. Do not squeeze unrelated'
       + ' work into one line to hit a number. Write each step small enough to check on its own.',
     params: { todos: 'the whole todo list. No cap — as many as the job needs' },
+    items: {
+      todos: { text: 'one line on what to do', state: 'todo / doing / done' },
+    },
   },
   Verify: {
     desc: 'Check that what you made actually works. Call this **before** you finish, without fail.'

package/src/tools/doc2md.js

@@ -28,7 +28,7 @@
 import { basename, extname } from 'node:path';
 
 import { isDocPath, readDoc, summarize as docSummary } from './docs.js';
-import { isPdfPath, readPdf, summarize as pdfSummary } from './pdf.js';
+import { isPdfPath, readPdf, summarize as pdfSummary, 못읽은말 } from './pdf.js';
 import { isFigPath, readFig, summarize as figSummary } from './fig.js';
 import { readXlsx, toCsv } from './xlsx.js';
 import { readFileSync } from 'node:fs';
@@ -227,6 +227,16 @@ function pdf를마크다운(경로, maxChars) {
 
   const 담 = 담개(maxChars);
   담.담기(제목(경로));
+  /*
+   * 쪽이 통째로 빠진 것·쪽 차례를 못 믿는 것을 **마크다운 안에** 적는다.
+   *
+   * 여태 이 둘은 `summary` 한 줄에만 있었다. 그런데 doc2md 의 결과물은 파일로
+   * 남아 나중에 그것만 읽히는 물건이다 — 요약은 그때 이미 없다. /Count 가 12쪽
+   * 이라는데 8쪽만 건진 문서가 「8쪽짜리 온전한 문서」로 남아, 모델이 빠진 쪽을
+   * 근거로 「문서에 그런 조항은 없습니다」 라고 답하는 자리가 바로 여기다.
+   */
+  const 머리말 = 못읽은말({ ...r, 못읽은쪽: [] });
+  if (머리말) 담.담기(머리말.split('\n').map((줄) => `> ${줄.trim()}`).join('\n'));
   const 왜표 = new Map((r.못읽은쪽 ?? []).map((x) => [x.번호, x]));
   for (const d of r.덩이들) {
     const 번호 = Number((d.이름.match(/^(\d+)/) ?? [])[1]);