deel-local-cli 0.5.0 → 0.8.0

package/src/pack/selfpack.js

@@ -0,0 +1,248 @@
+// deel 자기 자신을 사내 반입용으로 묶는다.
+//
+// 반입 심사에서 실제로 물어보는 것은 셋이다.
+//   1) 남의 코드가 섞여 있나        → 의존성 목록
+//   2) 설치만 해도 뭔가 도나        → 생명주기 스크립트
+//   3) 바깥 어디로 말을 거나        → 네트워크·외부 명령 호출 자리
+// 이 세 가지를 사람이 읽을 수 있는 심사서로 뽑아서 소스와 같이 담는다.
+// 소스를 읽고 쓰는 것은 전부 코드에서 훑는다 — 손으로 적으면 언젠가 사실과 어긋난다.
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { makeZip } from './zip.js';
+
+export const repoRoot = () => join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.github', 'test', '.deel']);
+const SHIP = ['bin', 'src'];
+const SHIP_FILES = ['package.json', 'README.md', 'README.en.md', 'LICENSE'];
+
+function walk(dir, base, out) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.') && e.name !== '.gitattributes') continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(full, base, out);
+      continue;
+    }
+    out.push(relative(base, full).split(/[\\/]/).join('/'));
+  }
+  return out;
+}
+
+export function shippedFiles(root = repoRoot()) {
+  const out = [];
+  for (const d of SHIP) if (existsSync(join(root, d))) walk(join(root, d), root, out);
+  for (const f of SHIP_FILES) if (existsSync(join(root, f))) out.push(f);
+  return out.sort();
+}
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+// 바깥과 말을 섞을 수 있는 자리를 소스에서 직접 찾는다.
+// 앞에 점이나 글자가 붙은 것은 뺀다. 그러지 않으면 정규식의 .exec( 까지
+// '외부 명령 실행' 으로 세어 심사서가 거짓말을 한다.
+const PROBES = [
+  { id: 'net', label: '네트워크 요청', re: /(?<![.\w])fetch\s*\(/g,
+    note: '사용자가 setup 에서 넣은 주소로만 나갑니다' },
+  { id: 'exec', label: '외부 명령 실행', re: /(?<![.\w])(execFile|execFileSync|execSync|spawn|spawnSync|exec)\s*\(/g,
+    note: '사용자·모델이 지시한 명령, 그리고 플러그인 받을 때의 git' },
+  { id: 'listen', label: '포트 열기', re: /(?<![.\w])(createServer)\s*\(/g,
+    note: '없어야 정상입니다' },
+  { id: 'eval', label: '문자열 실행', re: /(?<![.\w])(eval|new\s+Function)\s*\(/g,
+    note: '없어야 정상입니다' },
+];
+
+export function scanCalls(root = repoRoot(), files = shippedFiles(root)) {
+  const found = Object.fromEntries(PROBES.map((p) => [p.id, []]));
+  for (const f of files) {
+    if (!f.endsWith('.js')) continue;
+    const lines = readFileSync(join(root, f), 'utf8').split(/\r?\n/);
+    lines.forEach((line, i) => {
+      if (/^\s*(\/\/|\*)/.test(line)) return;   // 주석은 세지 않는다
+      for (const p of PROBES) {
+        p.re.lastIndex = 0;
+        if (p.re.test(line)) found[p.id].push({ file: f, line: i + 1, text: line.trim().slice(0, 78) });
+      }
+    });
+  }
+  return found;
+}
+
+/**
+ * 소스에서 불러오는 모듈 이름만 뽑는다.
+ *
+ * 그냥 정규식으로 import 를 찾으면 화면 문구 안의 "외부 import" 같은 글자까지 잡힌다.
+ * 실제로 그렇게 잡혀서 심사서에 없는 의존성이 적혔다. 그래서 두 가지를 함께 본다.
+ *   1) import / require 가 낱말로 서 있을 것
+ *   2) 따온 값이 모듈 이름처럼 생겼을 것 (공백·괄호·${ 가 없다)
+ */
+const MODULE_NAME = /^[@\w./:-]+$/;
+
+export function importSpecs(text) {
+  const out = [];
+  const re = /(?:^|[\s;{(])(?:import[^'"()]*from\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);
+  }
+  return out;
+}
+
+export function audit(root = repoRoot()) {
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  const files = shippedFiles(root);
+  const LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare', 'prepublish'];
+
+  const 외부모듈 = [];
+  for (const f of files) {
+    if (!f.endsWith('.js')) continue;
+    for (const s of importSpecs(readFileSync(join(root, f), 'utf8'))) {
+      if (s.startsWith('node:') || s.startsWith('.') || s.startsWith('/')) continue;
+      외부모듈.push(`${f} → ${s}`);
+    }
+  }
+
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    license: pkg.license,
+    node: pkg.engines?.node ?? '(지정 없음)',
+    deps: Object.keys(pkg.dependencies ?? {}),
+    devDeps: Object.keys(pkg.devDependencies ?? {}),
+    lifecycle: LIFECYCLE.filter((k) => pkg.scripts?.[k]),
+    외부모듈,
+    files: files.map((f) => {
+      const buf = readFileSync(join(root, f));
+      return { path: f, bytes: buf.length, sha: sha256(buf) };
+    }),
+    calls: scanCalls(root, files),
+  };
+}
+
+const 줄 = (n = 74) => '-'.repeat(n);
+
+export function reviewSheet(a, at) {
+  const L = [];
+  L.push('deel 사내 반입 심사 자료');
+  L.push(줄());
+  L.push(`이름        ${a.name}`);
+  L.push(`판          ${a.version}`);
+  L.push(`라이선스    ${a.license}`);
+  L.push(`실행 환경   Node ${a.node} (표준 내장 기능만 사용)`);
+  L.push(`만든 시각   ${at}`);
+  L.push('');
+
+  L.push('1. 외부 의존성');
+  L.push(줄());
+  L.push(`   dependencies      ${a.deps.length}개${a.deps.length ? '  ' + a.deps.join(', ') : '   ← 남의 코드를 함께 들여오지 않습니다'}`);
+  L.push(`   devDependencies   ${a.devDeps.length}개`);
+  L.push(`   소스의 외부 import ${a.외부모듈.length}건${a.외부모듈.length ? '' : '   ← node: 내장과 자기 파일만 부릅니다'}`);
+  for (const x of a.외부모듈) L.push(`       ${x}`);
+  L.push('');
+
+  L.push('2. 설치할 때 저절로 도는 코드');
+  L.push(줄());
+  L.push(a.lifecycle.length
+    ? `   있음: ${a.lifecycle.join(', ')}   ← 심사 필요`
+    : '   없음   ← preinstall / install / postinstall / prepare 전부 없습니다');
+  L.push('   압축을 풀고 `node bin/deel.js` 로 바로 씁니다. 설치 절차가 없습니다.');
+  L.push('');
+
+  L.push('3. 바깥으로 나가는 자리 (소스를 훑어 찾은 전부)');
+  L.push(줄());
+  for (const p of PROBES) {
+    const hits = a.calls[p.id];
+    L.push(`   [${p.label}]  ${hits.length}건   ${p.note}`);
+    for (const h of hits) L.push(`       ${h.file}:${h.line}   ${h.text}`);
+    if (!hits.length) L.push('       (없음)');
+  }
+  L.push('');
+  L.push('   ※ 접속 주소는 소스에 박혀 있지 않습니다. deel setup 에서 넣은 값만 씁니다.');
+  L.push('     설정 파일: ~/.deel/config.json  (또는 환경변수 DEEL_API_KEY)');
+  L.push('');
+
+  L.push('3-1. 나가는 길은 두 갈래이고 서로 섞이지 않습니다');
+  L.push(줄());
+  L.push('   [A] 모델 게이트웨이 — 소스 코드가 실려 나가는 유일한 길');
+  L.push('       · 주소: deel setup 에서 정한 곳 딱 한 자리');
+  L.push('       · 그 한 자리만 허용 목록에 오릅니다. 모델을 바꾸면 앞의 자리는 닫힙니다.');
+  L.push('       · src/safety/network.js 가 요청마다 확인하고, 목록에 없으면 요청 자체를');
+  L.push('         만들지 않습니다.');
+  L.push('');
+  L.push('   [B] 웹 읽기 (WebFetch 도구) — 받아 오기만 하는 길');
+  L.push('       · GET 만 씁니다. 본문을 실어 보내지 않습니다 (소스·대화가 나갈 수 없음).');
+  L.push('       · 이 컴퓨터·사내망(127.*, 10.*, 192.168.*, 172.16~31.*) 주소는 거절합니다.');
+  L.push('       · 쓰는 동안만 그 자리를 열고 끝나면 바로 닫습니다.');
+  L.push('       · 다녀온 주소는 전부 기록에 남습니다.');
+  L.push('');
+  L.push('   [C] 플러그인 받기 (github) — 사용자가 /plugin install 을 칠 때만');
+  L.push('       · 그 명령이 도는 동안만 열리고 끝나면 닫힙니다.');
+  L.push('');
+  L.push('   --offline 으로 켜면 [B] 와 [C] 가 모두 막히고, 이 컴퓨터 안으로만 다닙니다.');
+  L.push('   (검증: npm test 안의 network / web 검사 54항목이 이를 확인합니다)');
+  L.push('');
+
+  L.push('4. 스킬·플러그인');
+  L.push(줄());
+  L.push('   이 묶음에는 스킬도 플러그인도 들어 있지 않습니다.');
+  L.push('   설치된 PC 의 ~/.claude, ~/.deel, 프로젝트 폴더를 읽어서 쓸 뿐입니다.');
+  L.push('   (검증: npm test 안의 no-bundle 검사가 이를 확인합니다)');
+  L.push('');
+
+  L.push(`5. 담긴 파일 ${a.files.length}개 — SHA-256`);
+  L.push(줄());
+  const w = Math.max(...a.files.map((f) => f.path.length));
+  for (const f of a.files) {
+    L.push(`   ${f.path.padEnd(w)}  ${String(f.bytes).padStart(7)}B  ${f.sha}`);
+  }
+  L.push('');
+  L.push('   위 값은 다음으로 다시 확인할 수 있습니다:');
+  L.push('     sha256sum <파일>            (리눅스·맥)');
+  L.push('     certutil -hashfile <파일> SHA256   (윈도우)');
+  L.push('');
+  return L.join('\n');
+}
+
+/**
+ * 심사서 + 소스를 zip 하나로 묶는다.
+ */
+export function packSelf(outFile, { root = repoRoot(), at = new Date() } = {}) {
+  const a = audit(root);
+  const stamp = at.toISOString().replace('T', ' ').slice(0, 19);
+  const sheet = reviewSheet(a, stamp);
+
+  const entries = [{ name: '반입심사서.txt', data: Buffer.from(sheet, 'utf8'), mtime: at }];
+  for (const f of a.files) {
+    entries.push({
+      name: `deel/${f.path}`,
+      data: readFileSync(join(root, f.path)),
+      mtime: statSync(join(root, f.path)).mtime,
+      mode: f.path.startsWith('bin/') ? 0o755 : 0o644,
+    });
+  }
+  entries.push({
+    name: '읽어주세요.txt',
+    data: Buffer.from([
+      'deel — 로컬 모델·사내 게이트웨이 코딩 에이전트',
+      '',
+      '쓰는 법 (설치 절차 없음)',
+      '  1. 이 zip 을 아무 폴더에나 풉니다.',
+      '  2. Node 20 이상이 깔려 있는지 봅니다:  node -v',
+      '  3. 연결을 정합니다:                    node deel/bin/deel.js setup',
+      '  4. 대화를 시작합니다:                  node deel/bin/deel.js',
+      '',
+      '심사 담당자께',
+      '  같이 담긴 반입심사서.txt 에 의존성·설치 스크립트·네트워크 호출 자리가',
+      '  전부 적혀 있습니다. 파일별 SHA-256 도 있습니다.',
+      '',
+    ].join('\n'), 'utf8'),
+    mtime: at,
+  });
+
+  const zip = makeZip(entries);
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, zip);
+  return { out: outFile, bytes: zip.length, files: entries.length, audit: a, sheet };
+}

package/src/pack/tar.js

@@ -0,0 +1,69 @@
+// tar 읽기. GitHub 가 주는 tarball 을 풀기 위한 최소 구현.
+// git 이 없는 기기에서도 플러그인을 받을 수 있어야 해서 필요하다.
+import { gunzipSync } from 'node:zlib';
+
+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();
+}
+
+function octal(buf, off, len) {
+  const s = str(buf, off, len).replace(/[^0-7]/g, '');
+  return s ? parseInt(s, 8) : 0;
+}
+
+/**
+ * gzip 된 tar 를 풀어 파일 목록을 돌려준다.
+ * @returns {Array<{name:string, data:Buffer, mode:number}>}
+ */
+export function untargz(gz) {
+  const buf = gunzipSync(gz);
+  const out = [];
+  let pos = 0;
+  let longName = null;
+
+  while (pos + BLOCK <= buf.length) {
+    const head = buf.subarray(pos, pos + BLOCK);
+    // 빈 블록 두 개면 끝.
+    if (head.every((b) => b === 0)) break;
+
+    const size = octal(head, 124, 12);
+    const type = String.fromCharCode(head[156]) || '0';
+    const mode = octal(head, 100, 8);
+    const prefix = str(head, 345, 155);
+    let name = str(head, 0, 100);
+    if (prefix) name = `${prefix}/${name}`;
+
+    pos += BLOCK;
+    const data = buf.subarray(pos, pos + size);
+    pos += Math.ceil(size / BLOCK) * BLOCK;
+
+    if (type === 'L') {                    // GNU 긴 이름
+      longName = data.toString('utf8').replace(/\0+$/, '');
+      continue;
+    }
+    if (type === 'x' || type === 'g') {    // pax 확장 머리 — path 만 본다
+      const m = /\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 === '') {
+      out.push({ name: name.replace(/\\/g, '/'), data: Buffer.from(data), mode: mode || 0o644 });
+    }
+    // 폴더('5')·링크 등은 건너뛴다. 파일만 있으면 폴더는 만들면서 채운다.
+  }
+  return out;
+}
+
+// GitHub tarball 은 최상위에 <repo>-<커밋> 폴더 한 겹이 더 있다. 그걸 벗긴다.
+export function stripTop(files) {
+  if (!files.length) return files;
+  const first = files[0].name.split('/')[0];
+  if (!files.every((f) => f.name.startsWith(first + '/'))) return files;
+  return files.map((f) => ({ ...f, name: f.name.slice(first.length + 1) }));
+}

package/src/pack/zip.js

@@ -0,0 +1,217 @@
+// ZIP 읽기·쓰기. Node 내장 zlib 만 쓴다.
+//
+// 윈도우의 Compress-Archive 는 한글 파일 이름을 보장하지 못한다.
+// 여기서는 이름을 UTF-8 로 쓰고 플래그 11번 비트를 세워, 어디서 풀어도 이름이 살아 있게 한다.
+//
+// 읽기는 나중에 붙였다. xlsx 가 사실은 zip 이기 때문이다 — 엑셀 파일을 열려면
+// 먼저 이걸 풀어야 한다. 형식이 같으니 한자리에 둔다.
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+
+// --- CRC32 ---------------------------------------------------------------
+const TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[i] = c;
+  }
+  return t;
+})();
+
+export function crc32(buf) {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+// --- DOS 날짜·시각 --------------------------------------------------------
+function dosTime(d) {
+  return ((d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1)) & 0xffff;
+}
+function dosDate(d) {
+  return (((d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate()) & 0xffff;
+}
+
+const UTF8_NAMES = 0x0800;   // 플래그 11번 비트 — 이름이 UTF-8 이라는 표시
+
+/**
+ * @param {Array<{name:string, data:Buffer, mtime?:Date, mode?:number}>} entries
+ *        name 은 zip 안에서의 경로. 구분자는 항상 '/'.
+ *        mode 는 유닉스 권한(예: 0o755). 실행 파일에 필요하다.
+ * @returns {Buffer}
+ */
+export function makeZip(entries) {
+  const locals = [];
+  const central = [];
+  let offset = 0;
+
+  for (const e of entries) {
+    const nameBuf = Buffer.from(e.name.replace(/\\/g, '/'), 'utf8');
+    const raw = e.data;
+    const crc = crc32(raw);
+
+    // 압축해서 더 커지면 그냥 담는다(store).
+    const packed = deflateRawSync(raw, { level: 9 });
+    const useDeflate = packed.length < raw.length;
+    const body = useDeflate ? packed : raw;
+    const method = useDeflate ? 8 : 0;
+
+    const when = e.mtime ?? new Date();
+    const time = dosTime(when);
+    const date = dosDate(when);
+
+    const lh = Buffer.alloc(30);
+    lh.writeUInt32LE(0x04034b50, 0);
+    lh.writeUInt16LE(20, 4);
+    lh.writeUInt16LE(UTF8_NAMES, 6);
+    lh.writeUInt16LE(method, 8);
+    lh.writeUInt16LE(time, 10);
+    lh.writeUInt16LE(date, 12);
+    lh.writeUInt32LE(crc, 14);
+    lh.writeUInt32LE(body.length, 18);
+    lh.writeUInt32LE(raw.length, 22);
+    lh.writeUInt16LE(nameBuf.length, 26);
+    lh.writeUInt16LE(0, 28);
+    locals.push(lh, nameBuf, body);
+
+    const ch = Buffer.alloc(46);
+    ch.writeUInt32LE(0x02014b50, 0);
+    ch.writeUInt16LE(0x031e, 4);            // 만든 쪽: 유닉스, 버전 3.0
+    ch.writeUInt16LE(20, 6);
+    ch.writeUInt16LE(UTF8_NAMES, 8);
+    ch.writeUInt16LE(method, 10);
+    ch.writeUInt16LE(time, 12);
+    ch.writeUInt16LE(date, 14);
+    ch.writeUInt32LE(crc, 16);
+    ch.writeUInt32LE(body.length, 20);
+    ch.writeUInt32LE(raw.length, 24);
+    ch.writeUInt16LE(nameBuf.length, 28);
+    ch.writeUInt16LE(0, 30);
+    ch.writeUInt16LE(0, 32);
+    ch.writeUInt16LE(0, 34);
+    ch.writeUInt16LE(0, 36);
+    // 바깥 속성 위쪽 16비트에 유닉스 권한. bin 의 실행 권한이 여기 실린다.
+    ch.writeUInt32LE(((e.mode ?? 0o644) & 0xffff) << 16, 38);
+    ch.writeUInt32LE(offset, 42);
+    central.push(ch, nameBuf);
+
+    offset += lh.length + nameBuf.length + body.length;
+  }
+
+  const cd = Buffer.concat(central);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(cd.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...locals, cd, eocd]);
+}
+
+// --- ZIP 읽기 -------------------------------------------------------------
+//
+// 뒤에서부터 읽는다. zip 은 목록(중앙 디렉터리)이 파일 끝에 있고, 그 위치를
+// 알려주는 표식(EOCD)이 맨 끝에 있다. 앞에서부터 훑지 않는 이유가 이것이다.
+
+const EOCD_SIG = 0x06054b50;
+const CEN_SIG = 0x02014b50;
+const LOC_SIG = 0x04034b50;
+
+function findEocd(buf) {
+  // 주석이 붙어 있을 수 있어서 끝에서 최대 64KB 를 뒤로 훑는다.
+  const 끝 = Math.max(0, buf.length - 22 - 0xffff);
+  for (let i = buf.length - 22; i >= 끝; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) return i;
+  }
+  return -1;
+}
+
+/**
+ * zip 안의 파일들을 이름 → 내용(Buffer) 으로 돌려준다.
+ *
+ * 필요한 것만 만들었다 — 담기(store)와 deflate 두 가지. 그게 xlsx 가 쓰는 전부다.
+ * 모르는 것을 만나면 조용히 넘기지 않고 무엇을 못 했는지 말한다.
+ * 조용히 넘기면 '표가 비어 있다' 로 보이고, 그때는 원인을 찾을 수 없다.
+ *
+ * @param {Buffer} buf
+ * @param {{ only?: (name:string)=>boolean }} [opt] 필요한 것만 풀고 싶을 때
+ * @returns {{ files: Map<string,Buffer>, skipped: Array<{name:string, why:string}> }}
+ */
+export function readZip(buf, { only = null } = {}) {
+  const files = new Map();
+  const skipped = [];
+
+  const eocd = findEocd(buf);
+  if (eocd < 0) throw new Error('zip 이 아닙니다 — 끝에 있어야 할 표식을 못 찾았습니다');
+
+  let 개수 = buf.readUInt16LE(eocd + 10);
+  let 시작 = buf.readUInt32LE(eocd + 16);
+  // 0xffff/0xffffffff 는 'ZIP64 를 보라' 는 표시다. 여기서는 다루지 않는다.
+  // 못 다룬다고 말하는 편이 반쯤 읽어 놓고 맞다고 하는 것보다 낫다.
+  if (개수 === 0xffff || 시작 === 0xffffffff) {
+    throw new Error('ZIP64 형식입니다 — 이 읽기는 4GB 미만 zip 만 다룹니다');
+  }
+
+  let p = 시작;
+  for (let i = 0; i < 개수; i++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CEN_SIG) {
+      throw new Error(`zip 목록이 깨졌습니다 (${i + 1}번째 항목)`);
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const flags = buf.readUInt16LE(p + 8);
+    const compSize = buf.readUInt32LE(p + 20);
+    const rawSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localAt = buf.readUInt32LE(p + 42);
+    // 이름은 UTF-8 표시가 있으면 UTF-8, 없으면 예전 zip 관례대로 그냥 바이트다.
+    // xlsx 는 안쪽 이름이 전부 ASCII 라 어느 쪽이든 같다.
+    const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8');
+    p += 46 + nameLen + extraLen + commentLen;
+
+    if (name.endsWith('/')) continue;              // 폴더
+    if (only && !only(name)) continue;
+
+    // 암호가 걸린 항목은 첫 비트가 서 있다. xlsx 전체 암호와는 다른 것이지만,
+    // 어느 쪽이든 여기서는 못 푼다.
+    if (flags & 0x0001) { skipped.push({ name, why: '항목에 암호가 걸려 있음' }); continue; }
+
+    if (localAt + 30 > buf.length || buf.readUInt32LE(localAt) !== LOC_SIG) {
+      skipped.push({ name, why: '내용 위치가 어긋남' });
+      continue;
+    }
+    const lnLen = buf.readUInt16LE(localAt + 26);
+    const leLen = buf.readUInt16LE(localAt + 28);
+    const at = localAt + 30 + lnLen + leLen;
+    const body = buf.subarray(at, at + compSize);
+
+    if (method === 0) {
+      files.set(name, Buffer.from(body));
+    } else if (method === 8) {
+      try {
+        const out = inflateRawSync(body);
+        if (rawSize && out.length !== rawSize) {
+          skipped.push({ name, why: `푼 크기가 안 맞음 (${out.length} ≠ ${rawSize})` });
+          continue;
+        }
+        files.set(name, out);
+      } catch (err) {
+        skipped.push({ name, why: `풀지 못함 — ${err.message}` });
+      }
+    } else {
+      skipped.push({ name, why: `모르는 압축 방식 ${method}` });
+    }
+  }
+
+  return { files, skipped };
+}
+
+/** 앞머리 네 바이트로 zip 인지 본다. 엑셀 암호 파일과 구분하는 데 쓴다. */
+export function looksZip(buf) {
+  return buf.length >= 4 && buf.readUInt32LE(0) === LOC_SIG;
+}