deel-local-cli 1.20.12 → 2.0.0

package/src/pack/sbom.js

@@ -33,16 +33,18 @@ import { specEn, egressEn, keyStorageEn, auditLogEn, specSummaryEn } from './she
  *
  * 1.5 에서 1.7 로 올렸다. 판을 올린 것 자체가 목적이 아니라, CISA 가
  * 2026-07-29 로 「SBOM 최소 요소」 를 새로 냈고(2021년 NTIA 문서를 대체한다)
- * 거기서 더해진 네 가지를 적을 자리가 1.5 에는 없었다.
+ * 거기서 더해진 네 가지 중 **뒤의 둘**은 1.5 에 적을 자리가 아예 없었다.
  *
  *   부품 해시 알고리즘   hashes[].alg      — 1.5 에도 있었고 이미 적고 있었다
  *   부품 라이선스        components[].licenses
  *   만든 도구 이름       metadata.tools.components[]
  *   만든 맥락            metadata.lifecycles[]
  *
- * 앞의 두 개는 자리가 있었고 우리가 안 적었다. 뒤의 두 개는 1.5 의 모양이
- * 다르다 — metadata.tools 가 1.5 에서는 {vendor,name,version} 배열이고
- * 1.6 부터 부품 목록으로 바뀌었으며, lifecycles 는 아예 없다.
+ * 앞의 두 개는 자리가 1.5 에도 있었다. 그중 해시는 이미 적고 있었고, 안 적은
+ * 것은 **부품 라이선스 하나뿐**이다 — 뿌리 부품에만 적고 파일에는 안 적었다.
+ * 뒤의 두 개는 1.5 의 모양이 다르다 — metadata.tools 가 1.5 에서는
+ * {vendor,name,version} 배열이고 1.6 부터 부품 목록으로 바뀌었으며,
+ * lifecycles 는 아예 없다.
  *
  * 판을 안 올리고 필드만 끼워 넣는 길도 있었지만 그러면 규격에 안 맞는
  * SBOM 이 된다. 스캐너가 1.5 로 검사하다 모르는 열쇠에서 멈추면, 담당자
@@ -143,8 +145,17 @@ export function sbom(a, { at = new Date(), serial = null, lang = 언어() } = {}
          *
          * 실제 서명은 npm 배포 때 붙는 SLSA 증명이고, 그건 우리 손을 안 거친다.
          * 확인하는 명령을 적어 두는 편이 서명 한 덩이보다 낫다.
+         *
+         * 이 값도 description 과 같이 말을 따라간다. 스캐너에 먹이는 파일이라도
+         * 속성 칸은 담당자가 눈으로 읽는다 — 영어 서류에 한글이 한 자리 남으면
+         * 그 문서는 통째로 미완성으로 읽힌다.
          */
-        { name: 'deel:provenance', value: `npm audit signatures — ${a.name}@${a.version} (SLSA v1, npm 신뢰 배포)` },
+        {
+          name: 'deel:provenance',
+          value: lang === 'ko'
+            ? `npm audit signatures — ${a.name}@${a.version} (SLSA v1, npm 신뢰 배포)`
+            : `npm audit signatures — ${a.name}@${a.version} (SLSA v1, npm trusted publishing)`,
+        },
       ],
     },
     // 파일마다 하나씩. 담긴 것이 담겨야 할 것과 같은지 여기서 대조한다.
@@ -202,6 +213,18 @@ export function 통신명세(a) {
         막는법: '--offline 이면 통째로 막힙니다.',
         소스: 자리('net'),
       },
+      /*
+       * 넷째 길. 심사서 본문(selfpack.js 의 [D])은 네 갈래라고 적는데 이 목록은
+       * 셋이었다 — 담당자가 둘을 나란히 놓으면 제일 못 막는 길이 기계 목록에서만 빠져 있었다.
+       */
+      {
+        갈래: 'MCP 서버',
+        언제: '.deel/mcp.json 에 사람이 적은 서버만, 대화를 켤 때',
+        어디로: '그 서버 프로그램이 정합니다 — 딴 자식 프로세스라 우리 허용 목록을 거치지 않습니다',
+        무엇이: '모델이 그 서버의 도구에 넘긴 인자',
+        막는법: '기본은 꺼져 있습니다. --offline 이면 서버 자체를 띄우지 않습니다.',
+        소스: 자리('exec'),
+      },
     ],
     여는포트: {
       개수: (a.calls?.listen ?? []).length,

package/src/pack/selfpack.js

@@ -79,19 +79,48 @@ export function scanCalls(root = repoRoot(), files = shippedFiles(root)) {
  * 소스에서 불러오는 모듈 이름만 뽑는다.
  *
  * 그냥 정규식으로 import 를 찾으면 화면 문구 안의 "외부 import" 같은 글자까지 잡힌다.
- * 실제로 그렇게 잡혀서 심사서에 없는 의존성이 적혔다. 그래서 두 가지를 함께 본다.
+ * 실제로 그렇게 잡혀서 심사서에 없는 의존성이 적혔다. 그래서 세 가지를 함께 본다.
  *   1) import / require 가 낱말로 서 있을 것
  *   2) 따온 값이 모듈 이름처럼 생겼을 것 (공백·괄호·${ 가 없다)
+ *   3) 그 자리가 **따옴표 밖**일 것
+ *
+ * 셋째가 없던 동안 앞의 둘은 `import 'foo'` 를 안내문에 적어 둔 줄을 못 걸렀다.
+ * 그 줄 하나로 심사서 1절에 없는 남의 코드가 한 줄 늘어난다 — 담당자가 그걸
+ * 찾아보면 아무 데도 없고, 그 순간 나머지 숫자도 다 못 믿을 것이 된다.
  */
 const MODULE_NAME = /^[@\w./:-]+$/;
 
+/**
+ * 줄 처음부터 이 자리까지 걸어와서, 지금 따옴표 **안**인가.
+ *
+ * 한 줄만 본다. 여러 줄 템플릿 안까지 따라가려면 소스를 통째로 읽는 자가
+ * 있어야 하는데, 여기서 막으려는 것은 화면에 찍는 안내문 한 줄이다.
+ * 진짜 import 문은 줄 앞머리에 열린 따옴표가 있을 수 없다.
+ */
+function 따옴표안인가(앞) {
+  let 열린 = null;
+  for (let i = 0; i < 앞.length; i += 1) {
+    const c = 앞[i];
+    if (열린) {
+      if (c === '\\') { i += 1; continue; }   // 이스케이프된 글자는 닫지 못한다
+      if (c === 열린) 열린 = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') 열린 = c;
+  }
+  return 열린 !== null;
+}
+
 export function importSpecs(text) {
   const out = [];
   // 동적으로 부르는 import 도 문이다 — from 이 없어서 못 잡던 것을 잡는다.
   const re = /(?:^|[\s;{(])(?:import[^'"()]*from\s*|import\s*\(\s*|import\s*|require\s*\(\s*)(['"])([^'"]+)\1/g;
   for (const m of text.matchAll(re)) {
     const spec = m[2];
-    if (MODULE_NAME.test(spec)) out.push(spec);
+    if (!MODULE_NAME.test(spec)) continue;
+    const 줄머리 = text.lastIndexOf('\n', m.index) + 1;
+    if (따옴표안인가(text.slice(줄머리, m.index))) continue;
+    out.push(spec);
   }
   return out;
 }
@@ -156,7 +185,8 @@ export function reviewSheet(a, at, { lang = 언어() } = {}) {
   L.push(a.lifecycle.length
     ? `   있음: ${a.lifecycle.join(', ')}   ← 심사 필요`
     : '   없음   ← preinstall / install / postinstall / prepare 전부 없습니다');
-  L.push('   압축을 풀고 `node bin/deel.js` 로 바로 씁니다. 설치 절차가 없습니다.');
+  // zip 안에서는 소스가 deel/ 아래에 담긴다(아래 packSelf). 읽어주세요.txt 와 같은 자리를 가리킨다 (6회차 S4).
+  L.push('   압축을 풀고 `node deel/bin/deel.js` 로 바로 씁니다. 설치 절차가 없습니다.');
   L.push('');
 
   L.push('3. 바깥으로 나가는 자리 (소스를 훑어 찾은 전부)');
@@ -202,10 +232,29 @@ export function reviewSheet(a, at, { lang = 언어() } = {}) {
   L.push('   (검증: npm test 안의 network / web / mcp 검사가 이를 확인합니다 — 항목 수는 그 출력에 있습니다)');
   L.push('');
 
+  /*
+   * 여기가 「이 묶음에는 스킬도 플러그인도 들어 있지 않습니다」 였다.
+   *
+   * 사실이 아니다. `src/skills/builtin/` 의 방법론 SKILL.md 는 그대로 실려 나가고,
+   * test/no-bundle.test.js 는 「내 방법론은 제대로 실린다」 고 못 박고 있다 —
+   * 두 자리가 반대 방향으로 초록이었다. 심사자가 zip 을 풀어 SKILL.md 를 찾아내면
+   * 이 종이의 나머지 숫자도 다 못 믿을 것이 된다. 세어서 적는다.
+   */
+  const 방법론 = (a.files ?? [])
+    .map((f) => /^src\/skills\/builtin\/([^/]+)\/SKILL\.md$/.exec(f.path)?.[1])
+    .filter(Boolean)
+    .sort();
   L.push('4. 스킬·플러그인');
   L.push(줄());
-  L.push('   이 묶음에는 스킬도 플러그인도 들어 있지 않습니다.');
-  L.push('   설치된 PC 의 ~/.claude, ~/.deel, 프로젝트 폴더를 읽어서 쓸 뿐입니다.');
+  if (방법론.length) {
+    L.push(`   deel 이 품고 가는 방법론 ${방법론.length}개가 들어 있습니다 (src/skills/builtin).`);
+    L.push(`   ${방법론.join(', ')}`);
+    L.push('   모델에게 읽히는 글일 뿐입니다 — 코드를 돌리지도, 바깥으로 나가지도 않습니다.');
+  } else {
+    L.push('   이 묶음에는 스킬이 들어 있지 않습니다.');
+  }
+  L.push('   남의 스킬·플러그인은 하나도 안 담았습니다. 설치된 PC 의 ~/.claude, ~/.deel,');
+  L.push('   프로젝트 폴더를 읽어서 쓸 뿐입니다.');
   L.push('   (검증: npm test 안의 no-bundle 검사가 이를 확인합니다)');
   L.push('');
 

package/src/pack/sheet.en.js

@@ -62,7 +62,7 @@ export function reviewSheetEn(a, at, probes) {
   L.push(a.lifecycle.length
     ? `   Present: ${a.lifecycle.join(', ')}   <- needs review`
     : '   None   <- no preinstall / install / postinstall / prepare');
-  L.push('   Unzip and run `node bin/deel.js`. There is no install step.');
+  L.push('   Unzip and run `node deel/bin/deel.js`. There is no install step.');
   L.push('');
 
   L.push('3. Every outbound call site (found by scanning the source)');
@@ -109,10 +109,23 @@ export function reviewSheetEn(a, at, probes) {
   L.push('   (Verified by the network / web / mcp checks in npm test; the count is in that output.)');
   L.push('');
 
+  // 한국어 쪽(selfpack.js 의 4절)과 같은 사실을 적는다 — 「스킬이 하나도 없다」 는
+  // 거짓이었다. src/skills/builtin 의 방법론은 실제로 실려 나간다.
+  const builtins = (a.files ?? [])
+    .map((f) => /^src\/skills\/builtin\/([^/]+)\/SKILL\.md$/.exec(f.path)?.[1])
+    .filter(Boolean)
+    .sort();
   L.push('4. Skills and plugins');
   L.push(rule());
-  L.push('   This package contains no skills and no plugins.');
-  L.push('   It only reads ~/.claude, ~/.deel and the project folder on the machine it runs on.');
+  if (builtins.length) {
+    L.push(`   It ships ${builtins.length} built-in methodology skills (src/skills/builtin).`);
+    L.push(`   ${builtins.join(', ')}`);
+    L.push('   They are prose the model reads - they run no code and reach no network.');
+  } else {
+    L.push('   This package contains no skills.');
+  }
+  L.push('   It bundles no other people\'s skills or plugins: it only reads ~/.claude, ~/.deel');
+  L.push('   and the project folder on the machine it runs on.');
   L.push('   (Verified by the no-bundle check in npm test.)');
   L.push('');
 
@@ -224,6 +237,14 @@ export function egressEn(자리, a) {
         control: 'Blocked entirely under --offline.',
         source: 자리('net'),
       },
+      {
+        lane: 'MCP servers',
+        when: 'Only servers you listed in .deel/mcp.json, when a chat starts',
+        where: 'Decided by that server program - a separate child process, so it does not pass our allow-list',
+        what: 'The arguments the model passed to that server\'s tools',
+        control: 'Off by default. Under --offline the servers are not started at all.',
+        source: 자리('exec'),
+      },
     ],
     listeningPorts: {
       count: (a.calls?.listen ?? []).length,

package/src/pack/tar.js

@@ -8,7 +8,8 @@ const BLOCK = 512;
 function str(buf, off, len) {
   const end = buf.indexOf(0, off);
   const stop = end >= 0 && end < off + len ? end : off + len;
-  return buf.toString('utf8', off, stop).trim();
+  // 깎지 않는다 — 이름 앞뒤 빈칸도 이름이다 (6회차 Gemini 묶음6). 수 칸의 빈칸은 octal 이 걸러 낸다.
+  return buf.toString('utf8', off, stop);
 }
 
 function octal(buf, off, len) {
@@ -47,7 +48,9 @@ export function untargz(gz, { 상한 = 푼것상한 } = {}) {
     // 조용히 죽는 대신 왜 안 되는지 말한다. 이 말은 install 이 그대로 화면에 올린다.
     if (err?.code === 'ERR_BUFFER_TOO_LARGE') {
       // MB 로만 적으면 작은 상한이 「0MB」 가 된다 — 사람에게 아무 말도 안 하는 숫자다.
-      const 상한말 = 상한 >= 1024 * 1024 ? `${Math.round(상한 / 1024 / 1024)}MB` : `${Math.round(상한 / 1024)}KB`;
+      // KB 도 같다: 1KB 밑을 KB 로 반올림하면 「0KB」 다. 그 밑은 바이트로 적는다 (6회차 Gemini 타르6bg).
+      const 상한말 = 상한 >= 1024 * 1024 ? `${Math.round(상한 / 1024 / 1024)}MB`
+        : 상한 >= 1024 ? `${Math.round(상한 / 1024)}KB` : `${상한}바이트`;
       throw new Error(`푼 크기가 상한(${상한말})을 넘습니다`
         + ' — 압축만 작고 풀면 몇 GB 가 되는 묶음입니다. 저장소가 맞는지 확인하세요.');
     }
@@ -59,17 +62,49 @@ export function untargz(gz, { 상한 = 푼것상한 } = {}) {
 
   while (pos + BLOCK <= buf.length) {
     const head = buf.subarray(pos, pos + BLOCK);
-    // 빈 블록 두 개면 끝.
+    // 빈 머리 블록이면 끝. 규격은 끝에 빈 블록 **두 개**를 두지만 첫 개에서 멈춘다 — 참 머리는
+    // 체크섬 칸이 있어 모두 0일 수 없고 알맹이는 크기만큼 건너뛰므로, 머리 자리의 빈 블록은
+    // 끝에서만 나온다. GNU tar 도 `-i` 없이는 여기서 멈춘다 (6회차 Gemini 타르6bg).
     if (head.every((b) => b === 0)) break;
 
     const size = octal(head, 124, 12);
-    const type = String.fromCharCode(head[156]) || '0';
+    /*
+     * 갈래(typeflag)는 **여기 한 자리에서만** 정한다.
+     *
+     * 규격은 정규 파일을 `'0'` 과 NUL 둘 다로 적게 허락한다(옛 tar 가 NUL 로
+     * 적는다). 전에는 `String.fromCharCode(head[156]) || '0'` 이었는데,
+     * `String.fromCharCode(0)` 은 빈 글자가 아니라 NUL 한 글자라 언제나 참이다 —
+     * 그 `|| '0'` 은 어떤 묶음에도 안 걸리는 죽은 폴백이었고, 실제로 NUL 을
+     * 살린 것은 아래 「type === '\0'」 한 마디였다. 한 가지를 두 자리에서
+     * 따지면 한쪽만 고치는 날이 오고, 그날 NUL 로 지은 묶음은 파일 0개로
+     * 조용히 풀린다. 그래서 읽는 즉시 '0' 으로 맞춰 두고 아래는 '0' 만 본다.
+     */
+    const type = head[156] === 0 ? '0' : String.fromCharCode(head[156]);
     const mode = octal(head, 100, 8);
-    const prefix = str(head, 345, 155);
+    // 345 자리가 이름 앞머리인 것은 POSIX ustar(매직 「ustar」 + NUL)뿐이다. GNU 머리(「ustar」 + 빈칸 둘)는
+    // 거기에 atime 을 적어, 증분 묶음이면 `14325671234/file.txt` 로 풀렸다 (6회차 Gemini 묶음6).
+    const posix = head[262] === 0 && head.toString('latin1', 257, 262) === 'ustar';
+    const prefix = posix ? str(head, 345, 155) : '';
     let name = str(head, 0, 100);
     if (prefix) name = `${prefix}/${name}`;
 
     pos += BLOCK;
+    /*
+     * ── 머리가 적은 크기만큼 알맹이가 있나 ──────────────────────────────
+     *
+     * `subarray` 는 끝을 넘으면 **있는 데까지만** 준다. 그래서 머리에 100000
+     * 바이트라고 적힌 파일이 몇 바이트짜리로 조용히 풀렸다 (2.0.0 4회차 사냥).
+     * 스크립트가 반만 깔린 플러그인은 멀쩡해 보이다가 엉뚱한 자리에서 선다.
+     * 반쪽을 깔아 두느니 안 까는 편이 낫다 — 던지면 install 이 이 말을 화면에 올린다.
+     *
+     * 알맹이 뒤의 자투리(512 바이트 맞춤)나 끝의 빈 블록이 없는 것은 봐준다.
+     * 그런 묶음은 흔하고, 파일 내용은 다 있다.
+     */
+    if (pos + size > buf.length) {
+      const 보일이름 = longName && !'Lxg'.includes(type) ? longName : name;
+      throw new Error(`묶음이 중간에 잘렸습니다 — '${보일이름}' 은 머리에 ${size}바이트라고 적혀 있는데 `
+        + `${Math.max(0, buf.length - pos)}바이트뿐입니다. 받다가 끊겼거나 망가진 묶음입니다.`);
+    }
     const data = buf.subarray(pos, pos + size);
     pos += Math.ceil(size / BLOCK) * BLOCK;
 
@@ -78,16 +113,18 @@ export function untargz(gz, { 상한 = 푼것상한 } = {}) {
       continue;
     }
     if (type === 'x' || type === 'g') {    // pax 확장 머리 — path 만 본다
-      const m = /\d+ path=([^\n]+)\n/.exec(data.toString('utf8'));
+      // 기록의 머리(맨 앞이나 줄바꿈 뒤)에서만 본다. 다른 값 안의 「20 path=…」 를 이름으로 읽었다 (6회차 Gemini 묶음6).
+      const m = /(?:^|\n)\d+ path=([^\n]+)\n/.exec(data.toString('utf8'));
       if (m) longName = m[1];
       continue;
     }
     if (longName) { name = longName; longName = null; }
 
-    if (type === '0' || type === '\0' || type === '') {
+    if (type === '0') {
       out.push({ name: name.replace(/\\/g, '/'), data: Buffer.from(data), mode: mode || 0o644 });
     }
-    // 폴더('5')·링크 등은 건너뛴다. 파일만 있으면 폴더는 만들면서 채운다.
+    // 위에서 '0' 으로 맞춰 둔 정규 파일만 담는다. 폴더('5')·링크 등은 건너뛴다 —
+    // 파일만 있으면 폴더는 만들면서 채운다.
   }
   return out;
 }

package/src/pack/zip.js

@@ -31,9 +31,31 @@ function dosTime(d) {
 function dosDate(d) {
   return (((d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate()) & 0xffff;
 }
+/*
+ * DOS 날짜의 해는 1980 부터 일곱 비트, 즉 2107 까지다 (6회차 Gemini 묶음6).
+ *
+ * 묶기는 파일 mtime 을 그대로 싣는데, 1970 시각인 파일(재현 빌드·풀어 온 묶음)은 `-10 << 9` 가 위 비트를
+ * 채워 목록에 **2098 년**으로 적혔고, 2108 년은 0 으로 돌아 1980 이 됐다. 담을 수 있는 끝에 붙인다.
+ */
+function 담을시각(d) {
+  const 해 = d.getFullYear();
+  if (!(해 >= 1980)) return new Date(1980, 0, 1);
+  if (해 > 2107) return new Date(2107, 11, 31, 23, 59, 58);
+  return d;
+}
 
 const UTF8_NAMES = 0x0800;   // 플래그 11번 비트 — 이름이 UTF-8 이라는 표시
 
+/*
+ * 한 꾸러미에서 풀어 줄 크기의 **합** (2.0.0 3회차 사냥).
+ *
+ * readZip 은 항목 하나를 64MB 에서 멈춘다. 그런데 합은 안 봤다 — 64MB 로 부푸는 몇십 KB 짜리 조각을
+ * 수백 개 담은 .docx 하나면 푼 버퍼가 전부 Map 에 붙들린 채 메모리가 바닥나 대화까지 같이 죽는다.
+ * 모델이 시키는 대로 여는 파일이라 남이 정한 바이트다. tar 쪽 푼것상한(256MB)과 같은 크기로 둔다.
+ * 넘는 항목은 건너뛴 것(skipped)으로 이름과 까닭을 남긴다.
+ */
+export const 풀기총상한 = 256 * 1024 * 1024;
+
 /**
  * @param {Array<{name:string, data:Buffer, mtime?:Date, mode?:number}>} entries
  *        name 은 zip 안에서의 경로. 구분자는 항상 '/'.
@@ -56,7 +78,7 @@ export function makeZip(entries) {
     const body = useDeflate ? packed : raw;
     const method = useDeflate ? 8 : 0;
 
-    const when = e.mtime ?? new Date();
+    const when = 담을시각(e.mtime ?? new Date());
     const time = dosTime(when);
     const date = dosDate(when);
 
@@ -91,7 +113,9 @@ export function makeZip(entries) {
     ch.writeUInt16LE(0, 34);
     ch.writeUInt16LE(0, 36);
     // 바깥 속성 위쪽 16비트에 유닉스 권한. bin 의 실행 권한이 여기 실린다.
-    ch.writeUInt32LE(((e.mode ?? 0o644) & 0xffff) << 16, 38);
+    // `<< 16` 은 부호 있는 32비트라 파일 종류 비트(statSync 의 0o100755)가 붙으면 음수가 되어
+    // writeUInt32LE 가 던졌다 — `>>> 0` 으로 부호 없는 수로 돌린다 (6회차 Gemini 묶음6).
+    ch.writeUInt32LE((((e.mode ?? 0o644) & 0xffff) << 16) >>> 0, 38);
     ch.writeUInt32LE(offset, 42);
     central.push(ch, nameBuf);
 
@@ -124,10 +148,18 @@ const LOC_SIG = 0x04034b50;
 function findEocd(buf) {
   // 주석이 붙어 있을 수 있어서 끝에서 최대 64KB 를 뒤로 훑는다.
   const 끝 = Math.max(0, buf.length - 22 - 0xffff);
+  /*
+   * 주석은 아무 바이트나 담는다 — 같은 네 바이트가 주석 안에 있으면 뒤에서 처음 만난 그것을 끝표식으로
+   * 읽어 목록 0개를 조용히 냈다 (6회차 Gemini 묶음6). 진짜 끝표식은 **목록이 바로 앞에서 끝난다**
+   * (시작 + 크기 = 제자리). 그런 것이 없으면(앞에 딴 바이트가 붙은 자체 풀림 exe 등) 예전대로 처음 것.
+   */
+  let 처음 = -1;
   for (let i = buf.length - 22; i >= 끝; i--) {
-    if (buf.readUInt32LE(i) === EOCD_SIG) return i;
+    if (buf.readUInt32LE(i) !== EOCD_SIG) continue;
+    if (처음 < 0) 처음 = i;
+    if (buf.readUInt32LE(i + 16) + buf.readUInt32LE(i + 12) === i) return i;
   }
-  return -1;
+  return 처음;
 }
 
 /**
@@ -141,9 +173,41 @@ function findEocd(buf) {
  * @param {{ only?: (name:string)=>boolean }} [opt] 필요한 것만 풀고 싶을 때
  * @returns {{ files: Map<string,Buffer>, skipped: Array<{name:string, why:string}> }}
  */
-export function readZip(buf, { only = null } = {}) {
+export function readZip(buf, { only = null, 총상한 = 풀기총상한 } = {}) {
   const files = new Map();
   const skipped = [];
+  // 푼 크기의 합. 항목마다 64MB 상한만 두면 64MB 로 부푸는 조각 수백 개로 메모리가 바닥난다(풀기총상한 머리말).
+  let 푼합 = 0;
+  /*
+   * 건너뛴 까닭을 **둘로 가른다** (2.0.0 8회차 판정).
+   *
+   * 여태 한 가지 말만 남겼다 — 「나머지는 안 풀었습니다」. 그런데 코드는
+   * `continue` 라서 **뒤따르는 작은 항목은 그대로 푼다.** 동작은 옳다(자리에
+   * 들어가는 만큼은 준다). 틀린 것은 말이었다. 받는 쪽은 그 뒤가 비었다고 읽는다.
+   *
+   *   · 자리가 아예 없다(남은 ≤ 0)  → 이 뒤로는 정말 아무것도 안 푼다
+   *   · 이 항목 하나가 자리보다 크다 → 이것만 건너뛰고 뒤엣것은 계속 푼다
+   */
+  const MB = Math.round(총상한 / 1024 / 1024 * 10) / 10;
+  const 자리없음 = () => `푼 크기의 합이 상한(${MB}MB)을 다 씀 — 이 뒤로는 아무것도 안 풀었습니다`;
+  const 혼자큼 = (크기, 남은) => `이 항목 하나가 남은 자리보다 큼 (${크기} > ${남은}, 상한 ${MB}MB) — 이것만 건너뛰고 뒤엣것은 계속 풉니다`;
+  /*
+   * ── 푼 내용이 목록의 CRC32 와 맞나 ─────────────────────────────────────
+   *
+   * 크기만 봤다 (2.0.0 4회차 사냥). 담기(store)로 들어간 알맹이 한 바이트가 망가져도,
+   * deflate 가 크기는 맞게 풀리는데 내용이 틀려도 그대로 「읽었다」 로 내놨다. xlsx 라면
+   * 숫자 하나가 소리 없이 바뀐 표다. 틀리면 건너뛴 것으로 이름과 까닭을 남긴다 —
+   * 이 함수 머리말대로 조용히 넘기지 않는다.
+   *
+   * 값: 표 기반 JS CRC32 가 64MB 에 0.1초 남짓이라 풀기총상한(256MB)을 다 채워도 1초 안이다.
+   */
+  const CRC틀림 = (name, 내용, 적힌) => {
+    const 실제 = crc32(내용);
+    if (실제 === 적힌) return false;
+    const 열여섯 = (n) => n.toString(16).padStart(8, '0');
+    skipped.push({ name, why: `CRC 가 안 맞음 — 내용이 망가졌습니다 (목록 ${열여섯(적힌)} ≠ 실제 ${열여섯(실제)})` });
+    return true;
+  };
 
   const eocd = findEocd(buf);
   if (eocd < 0) throw new Error('zip 이 아닙니다 — 끝에 있어야 할 표식을 못 찾았습니다');
@@ -163,6 +227,9 @@ export function readZip(buf, { only = null } = {}) {
     }
     const method = buf.readUInt16LE(p + 10);
     const flags = buf.readUInt16LE(p + 8);
+    // 로컬 머리의 CRC 가 아니라 중앙 목록의 것을 쓴다. 플래그 3번 비트(뒤에 붙는 기술자)가
+    // 선 항목은 로컬 머리에 0 이 적혀 있고, 중앙 목록에는 늘 참값이 있다.
+    const 적힌crc = buf.readUInt32LE(p + 16);
     const compSize = buf.readUInt32LE(p + 20);
     const rawSize = buf.readUInt32LE(p + 24);
     const nameLen = buf.readUInt16LE(p + 28);
@@ -171,7 +238,9 @@ export function readZip(buf, { only = null } = {}) {
     const localAt = buf.readUInt32LE(p + 42);
     // 이름은 UTF-8 표시가 있으면 UTF-8, 없으면 예전 zip 관례대로 그냥 바이트다.
     // xlsx 는 안쪽 이름이 전부 ASCII 라 어느 쪽이든 같다.
-    const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8');
+    // 옛 .NET(ZipFile, 4.6.1 전)은 이름을 역슬래시로 적는다. 목록에서 'xl/workbook.xml' 을 찾는 쪽이
+    // 못 찾아 표가 비어 보였다 — 표준(APPNOTE 4.4.17)의 '/' 로 맞춘다 (6회차 Gemini 묶음6).
+    const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8').replace(/\\/g, '/');
     p += 46 + nameLen + extraLen + commentLen;
 
     if (name.endsWith('/')) continue;              // 폴더
@@ -190,8 +259,21 @@ export function readZip(buf, { only = null } = {}) {
     const at = localAt + 30 + lnLen + leLen;
     const body = buf.subarray(at, at + compSize);
 
+    const 남은 = 총상한 - 푼합;
+    const 이크기 = method === 0 ? body.length : rawSize;
+    if (남은 <= 0) { skipped.push({ name, why: 자리없음() }); continue; }
+    if (이크기 > 남은) { skipped.push({ name, why: 혼자큼(이크기, 남은) }); continue; }
     if (method === 0) {
+      // 담기(store)는 누른 크기와 푼 크기가 같아야 한다. 목록이 다른 숫자를
+      // 적어 뒀으면 둘 중 하나가 거짓말이다 — 어느 쪽이든 그대로 쓰면 안 된다.
+      if (body.length !== rawSize) {
+        skipped.push({ name, why: `푼 크기가 안 맞음 (${body.length} ≠ ${rawSize})` });
+        continue;
+      }
+      // 알맹이가 버퍼 끝에서 잘려 짧아진 것도 여기서 CRC 로 걸린다.
+      if (CRC틀림(name, body, 적힌crc)) continue;
       files.set(name, Buffer.from(body));
+      푼합 += body.length;
     } else if (method === 8) {
       try {
         /*
@@ -211,13 +293,26 @@ export function readZip(buf, { only = null } = {}) {
          * 것과 달리 **메모리를 안 쓰고** 멈춘다.
          */
         const 한항목상한 = 64 * 1024 * 1024;      // 이 프로그램이 여는 문서의 현실적 위쪽
-        const 상한 = Math.min(rawSize > 0 ? rawSize : 한항목상한, 한항목상한);
+        const 상한 = Math.min(rawSize > 0 ? rawSize : 한항목상한, 한항목상한, 남은);
         const out = inflateRawSync(body, { maxOutputLength: 상한 });
-        if (rawSize && out.length !== rawSize) {
+        /*
+         * `rawSize &&` 가 앞에 있었다 (2.0.0 8회차 판정).
+         *
+         * 목록이 「이 항목은 0바이트」 라고 우기면 `&&` 가 거기서 멈춰 **크기
+         * 대조를 통째로 건너뛰었다.** 0 이라고 적힌 항목이 몇십 바이트로 풀려
+         * 나와도 그대로 「읽었다」 가 됐다. 크기를 안 보던 4회차 그 자리와 같은 꼴이다.
+         *
+         * 가운데 목록(central directory)의 크기 칸은 흘려보내기(data descriptor)를
+         * 쓴 묶음에서도 늘 채워져 있다. 그래서 조건 없이 대 봐도 된다 —
+         * 진짜 0바이트 파일은 `out.length` 도 0 이라 그대로 지나간다.
+         */
+        if (out.length !== rawSize) {
           skipped.push({ name, why: `푼 크기가 안 맞음 (${out.length} ≠ ${rawSize})` });
           continue;
         }
+        if (CRC틀림(name, out, 적힌crc)) continue;
         files.set(name, out);
+        푼합 += out.length;
       } catch (err) {
         skipped.push({ name, why: `풀지 못함 — ${err.message}` });
       }