deel-local-cli 1.5.8 → 1.6.0

package/src/setup.js

@@ -1,11 +1,14 @@
 // 첫 실행 마법사 + 진단 실행.
 import { c, say, rule, mark } from './ui/ansi.js';
+import { 주소가리기 } from './safety/secrets.js';
 import { ask, pick } from './ui/prompt.js';
 import { spin } from './ui/spinner.js';
 import { detect } from './backend/detect.js';
 import { probe } from './backend/probe.js';
 import { renderHeader, renderLine, verdict, renderVerdict, plainReport } from './report.js';
 import { load, save, upsert, slug, resolveKey, activeProfile, configPath } from './config.js';
+import { 보관방식 } from './safety/keystore.js';
+import { 애저풀기, 애저base } from './backend/azure.js';
 import { allowEndpoint } from './safety/network.js';
 import { writeFileSync } from 'node:fs';
 
@@ -18,14 +21,22 @@ export function banner() {
 // 주소와 키를 받아 연결을 찾아낸다. 실패하면 null.
 async function connect(url, key) {
   const s = spin(`${url} 확인 중...`);
-  // 사용자가 방금 적어 넣은 주소다. 확인하는 동안만 문을 연다.
-  allowEndpoint(/^https?:\/\//i.test(url) ? url : 'http://' + url);
+  /*
+   * 사용자가 방금 적어 넣은 주소다. 확인하는 동안만 문을 연다.
+   *
+   * 스킴을 안 적었으면 **두 가지 다 열어 둔다.** 자리마다 기본으로 붙이는
+   * 스킴이 다르기 때문이다 — 로컬 서버를 찾는 쪽은 `http://` 를, Azure 쪽은
+   * `https://` 를 붙인다. 한쪽만 열어 두면 우리가 만든 주소를 우리 자물쇠가
+   * 막고, 화면에는 "허용되지 않은 주소" 만 뜬다. 여는 것은 사람이 적어 넣은
+   * 그 호스트 하나뿐이라 넓어지는 것이 아니다.
+   */
+  allowEndpoint(/^https?:\/\//i.test(url) ? url : [`http://${url}`, `https://${url}`]);
   const found = await detect(url, key);
   if (!found.kind) {
     s.stop(`  ${mark.no} ${c.red('연결 실패')}`);
     say('');
     say(`    시도한 주소:`);
-    for (const t of found.tried) say(`      ${c.gray(t + '/models')}`);
+    for (const t of found.tried) say(`      ${c.gray(주소가리기(t.includes('?') ? t : `${t}/models`))}`);
     say('');
     say(`    ${c.gray('확인할 것 — 주소·포트가 맞는지, 프록시가 필요한지,')}`);
     say(`    ${c.gray('사내 인증서라면 NODE_EXTRA_CA_CERTS 환경변수가 필요합니다.')}`);
@@ -34,7 +45,8 @@ async function connect(url, key) {
   }
   const kindName = found.kind === 'ollama' ? `Ollama ${found.version ?? ''}`.trim() : 'OpenAI 호환';
   s.stop(`  ${mark.ok} ${c.green('연결됨')} ${c.gray(`${kindName} · ${found.ms}ms`)}`);
-  say(`    ${c.gray('주소')} ${found.base}`);
+  // 물음표 뒤에 열쇠를 싣는 앞단이 있다 (safety/secrets.js 의 주소가리기).
+  say(`    ${c.gray('주소')} ${주소가리기(found.base)}`);
   say(`    ${c.gray('인증')} ${found.auth === 'none' ? '없음' : found.auth}`);
   say(`    ${c.gray('모델')} ${found.models.length}개 발견`);
   if (found.warn) say(`    ${mark.warn} ${c.yellow(found.warn)}`);
@@ -70,6 +82,10 @@ export async function runProbe(conn, { out = null } = {}) {
 
 export async function runSetup() {
   banner();
+  // 설정에 적어 둔 api-version 을 **붙기 전에** 읽는다. load() 가 애저정하기()를
+  // 부른다. 이걸 뒤에서 하면 사내에서 판을 고정해 둔 곳이 확인만 GA판으로 하고,
+  // 문서에 적어 둔 대로 안 도는 셈이 된다.
+  load();
   say(`  ${c.gray('모델 연결을 설정합니다. 주소와 키만 있으면 됩니다.')}`);
   say('');
 
@@ -85,6 +101,18 @@ export async function runSetup() {
   const model = await chooseModel(found);
   if (!model) { say(`  ${mark.no} 모델이 비었습니다.`); return 1; }
 
+  /*
+   * Azure 는 모델 이름이 **주소 안에** 있다.
+   *
+   * 목록에서 다른 배포를 골랐으면 주소도 그 배포로 바꿔야 한다. 안 바꾸면
+   * 화면에는 고른 이름이 보이는데 요청은 처음 주소의 배포로 나간다 —
+   * 사람이 알아챌 방법이 없는 어긋남이다.
+   */
+  if (found.azure) {
+    const 푼것 = 애저풀기(found.base);
+    if (푼것) found.base = 애저base(푼것.origin, model, 푼것.판);
+  }
+
   const conn = { kind: found.kind, base: found.base, auth: found.auth, key, model };
   const { facts } = await runProbe(conn);
 
@@ -102,14 +130,18 @@ export async function runSetup() {
     tools: facts.tools ?? false,
     json: facts.json ?? false,
     think: facts.think ?? false,
+    vision: facts.vision ?? false,
   });
   cfg.active = id;
   const p = save(cfg);
 
   say(`  ${mark.ok} 저장됨 ${c.cyan(p)}`);
   if (key) {
-    say(`     ${c.gray('키가 이 파일에 들어 있습니다. 남기고 싶지 않으면 파일에서 지우고')}`);
-    say(`     ${c.gray('환경변수 DEEL_API_KEY 로 넣으세요 — 그쪽이 우선합니다.')}`);
+    // 열쇠가 파일에 '어떤 꼴로' 들어갔는지를 그대로 적는다. 잠겼는지 아닌지를
+    // 사람이 짐작하게 두면, 안 잠긴 파일을 잠긴 줄 알고 아무 데나 둔다.
+    const 저장한것 = activeProfile(load())?.apiKey ?? null;
+    say(`     ${c.gray(`열쇠 보관 — ${보관방식(저장한것)}`)}`);
+    say(`     ${c.gray('파일에 아예 안 남기려면 환경변수 DEEL_API_KEY 로 넣으세요 — 그쪽이 우선합니다.')}`);
   }
   say('');
   return 0;
@@ -121,6 +153,7 @@ export async function runDiagnose(flags) {
   let conn;
 
   if (flags.url) {
+    load();      // 설정의 api-version 을 먼저 읽는다 (runSetup 과 같은 이유)
     const key = flags.key ?? process.env.DEEL_API_KEY ?? '';
     const found = await connect(flags.url, key);
     if (!found) return 1;
@@ -167,7 +200,7 @@ export async function showStatus() {
       p.think ? c.green('추론') : c.gray('추론'),
     ].join(c.gray('·'));
     say(`  ${c.bold(p.name)}  ${c.gray(p.model)}  ${caps}${here}`);
-    say(`    ${c.gray(p.baseUrl)}`);
+    say(`    ${c.gray(주소가리기(p.baseUrl))}`);
   }
   say('');
   say(`  ${c.gray('설정 파일')} ${configPath()}`);

package/src/tools/clipboard.js

@@ -0,0 +1,178 @@
+/**
+ * 클립보드에 든 그림 꺼내기 — 화면 캡처 → 바로 붙이기.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────
+ *
+ * 눈이 달린 모델에게 화면을 보여 줄 수 있게 됐는데(backend/vision.js),
+ * 보여 주려면 먼저 **파일로 저장해야** 했다. 오류 화면 하나를 물어보려고
+ * 캡처 → 그림판 → 저장 → 경로 찾기를 거친다. 그 네 걸음이 「그냥 말로
+ * 설명하자」로 사람을 되돌린다.
+ *
+ * 캡처는 이미 클립보드에 있다. 꺼내 오기만 하면 된다.
+ *
+ * ── 왜 의존성 없이 되나 ─────────────────────────────────────────────────
+ *
+ * 세 운영체제 모두 **이미 깔려 있는 것**으로 꺼낸다. 새로 깔라고 하지 않는다.
+ *
+ *   윈도우   파워셸의 .NET Clipboard (윈도우에 늘 있다)
+ *   맥       osascript (맥에 늘 있다)
+ *   리눅스   wl-paste 나 xclip — 배포판에 따라 없을 수 있다
+ *
+ * ── 없으면 없다고 한다 ──────────────────────────────────────────────────
+ *
+ * 리눅스에서 둘 다 없으면 **어떻게 하면 되는지**를 같이 준다. 「안 됩니다」
+ * 로 끝내면 사람은 이 기능이 고장 난 줄 알지, 도구 하나 깔면 되는 줄 모른다.
+ * 클립보드에 글만 있을 때도 「그림이 없다」와 「못 꺼냈다」를 갈라 말한다 —
+ * 앞의 것은 사람이 캡처를 다시 하면 되고, 뒤의 것은 우리 탓이다.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** 이보다 큰 그림은 안 받는다. 화면 캡처 한 장은 보통 1MB 안쪽이다. */
+export const 그림한도 = 12 * 1024 * 1024;
+
+const 있나 = (이름, 인자) => {
+  const r = spawnSync(이름, 인자, { encoding: 'utf8', timeout: 5000, windowsHide: true });
+  return !r.error && r.status === 0;
+};
+
+/*
+ * 윈도우.
+ *
+ * 파워셸을 **파일로 적어 두고** 부른다. `-Command` 뒤에 길게 붙이면 따옴표가
+ * 셸을 두 번 거치면서 깨지고, 그 깨짐이 PC 마다 다르게 나타난다. 스크립트는
+ * ASCII 로만 쓴다 — Windows PowerShell 5.1 은 BOM 없는 .ps1 을 그 PC 의 옛
+ * 코드페이지로 읽어서, 한글이 섞이면 문법이 무너진다(src/completion.js 참고).
+ */
+function 윈도우에서(방) {
+  const 낼곳 = join(방, 'clip.png');
+  const 스크립트 = join(방, 'grab.ps1');
+  const 글 = [
+    '$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)`,
+    'Write-Output "OK"',
+  ].join('\n');
+  // Buffer 로 적어서 인코딩이 끼어들 자리를 없앤다.
+  writeFileSync(스크립트, Buffer.from(글, 'latin1'));
+
+  const r = spawnSync('powershell', [
+    '-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-File', 스크립트,
+  ], { encoding: 'utf8', timeout: 20000, windowsHide: true });
+
+  if (r.error) return { ok: false, 왜: `파워셸을 못 불렀습니다: ${r.error.message}` };
+  const 낸말 = String(r.stdout ?? '').trim();
+  if (/NOIMAGE/.test(낸말)) return { ok: false, 없음: true };
+  if (!existsSync(낼곳)) {
+    const 탈 = String(r.stderr ?? '').split('\n').find((l) => l.trim()) ?? '';
+    return { ok: false, 왜: 탈 ? `클립보드를 못 읽었습니다: ${탈.trim()}` : '클립보드를 못 읽었습니다' };
+  }
+  return { ok: true, buf: readFileSync(낼곳), mime: 'image/png' };
+}
+
+/*
+ * 맥.
+ *
+ * osascript 로 PNG 를 꺼내면 «data PNGf89504e47…» 꼴의 16진수 글이 나온다.
+ * 그림이 없으면 오류를 내므로, 그것으로 「없음」을 가른다.
+ */
+function 맥에서() {
+  const r = spawnSync('osascript', ['-e', 'the clipboard as «class PNGf»'], {
+    encoding: 'utf8', timeout: 20000,
+  });
+  if (r.error) return { ok: false, 왜: `osascript 를 못 불렀습니다: ${r.error.message}` };
+  const 낸말 = String(r.stdout ?? '');
+  const m = /«data PNGf([0-9A-Fa-f]+)»/.exec(낸말);
+  if (!m) {
+    // 그림이 아니면 osascript 가 오류를 낸다. 그건 「없음」이지 고장이 아니다.
+    if (r.status !== 0) return { ok: false, 없음: true };
+    return { ok: false, 없음: true };
+  }
+  return { ok: true, buf: Buffer.from(m[1], 'hex'), mime: 'image/png' };
+}
+
+/*
+ * 리눅스.
+ *
+ * 웨이랜드면 wl-paste, X11 이면 xclip. 배포판이 기본으로 안 깔아 주는 것이라
+ * 없을 수 있고, 그때는 **무엇을 깔면 되는지** 알려 준다.
+ */
+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']));
+  if (!있는것.length) {
+    return {
+      ok: false,
+      왜: '클립보드에서 그림을 꺼낼 도구가 없습니다.\n'
+        + '  웨이랜드면  sudo apt install wl-clipboard\n'
+        + '  X11 이면    sudo apt install xclip\n'
+        + '  둘 다 안 되면 캡처를 파일로 저장한 뒤 @경로 로 붙이세요.',
+    };
+  }
+  for (const x of 있는것) {
+    const 종류 = spawnSync(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;
+    return { ok: true, buf: Buffer.from(r.stdout), mime: 'image/png' };
+  }
+  return { ok: false, 없음: true };
+}
+
+/**
+ * 클립보드에 그림이 있으면 꺼낸다.
+ *
+ * @returns {{ok:true, buf:Buffer, mime:string}
+ *          | {ok:false, 없음:true}          그림이 없다 (사람이 다시 캡처하면 된다)
+ *          | {ok:false, 왜:string}}         못 꺼냈다 (까닭과 길을 같이 준다)
+ */
+export function 클립보드그림({ platform = process.platform } = {}) {
+  let 방 = null;
+  try {
+    if (platform === 'win32') {
+      방 = mkdtempSync(join(tmpdir(), 'deel-clip-'));
+      const r = 윈도우에서(방);
+      return 잰다(r);
+    }
+    if (platform === 'darwin') return 잰다(맥에서());
+    if (platform === 'linux') return 잰다(리눅스에서());
+    return { ok: false, 왜: `${platform} 에서는 아직 클립보드 그림을 못 꺼냅니다 — 파일로 저장한 뒤 @경로 로 붙이세요.` };
+  } catch (err) {
+    return { ok: false, 왜: `클립보드를 읽다 막혔습니다: ${err.message}` };
+  } finally {
+    if (방) { try { rmSync(방, { recursive: true, force: true }); } catch { /* 치우다 실패는 넘어간다 */ } }
+  }
+}
+
+/** 크기를 여기서 한 번만 잰다 — 운영체제마다 따로 재면 한 군데를 빠뜨린다. */
+function 잰다(r) {
+  if (!r?.ok) return r;
+  if (!r.buf?.length) return { ok: false, 없음: true };
+  if (r.buf.length > 그림한도) {
+    return { ok: false, 왜: `그림이 너무 큽니다 (${(r.buf.length / 1048576).toFixed(1)}MB · 한도 ${그림한도 / 1048576}MB)` };
+  }
+  return r;
+}
+
+/**
+ * 꺼낸 그림을 파일로 앉힌다.
+ *
+ * 살림 폴더(.deel/붙인그림/) 안에 둔다. 작업 폴더에 흩뿌리면 사람이 지우기
+ * 전에 커밋에 딸려 들어가고, 임시 폴더에 두면 대화를 다시 열었을 때 사라진다.
+ */
+export function 그림앉히기(buf, 살림, { 이제 = new Date() } = {}) {
+  const 방 = join(살림, '붙인그림');
+  mkdirSync(방, { recursive: true });
+  const 이름 = `${이제.toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19)}.png`;
+  const 자리 = join(방, 이름);
+  writeFileSync(자리, buf);
+  return { 자리, 이름, 바이트: statSync(자리).size };
+}

package/src/tools/fastgrep.js

@@ -0,0 +1,217 @@
+// 이미 깔려 있는 빠른 찾기 도구를 빌려 쓴다.
+//
+// ── 왜 필요한가 ────────────────────────────────────────────────────────
+//
+// `Grep` 은 자바스크립트로 파일을 하나씩 열어 읽는다. 의존성 0개라는 약속을
+// 지키려면 그래야 했다. 그런데 파일이 5만 개쯤 되는 저장소에서는 한 번 찾는
+// 데 수십 초가 간다. 그동안 화면은 멈춰 있고 사람은 기다린다.
+//
+// 그런데 개발자 PC 에는 `rg`(ripgrep)가 이미 깔려 있는 경우가 많다. VS Code
+// 가 같이 깔고, git 이 있으면 `git grep` 도 있다. **깔지는 않고, 있으면 쓴다.**
+// 이건 의존성이 아니다 — 없으면 예전 길로 가고 결과는 같다.
+//
+// ── 무엇을 조심하나 ────────────────────────────────────────────────────
+//
+//   1) **어느 엔진으로 찾았는지 말한다.** rg 와 자바스크립트 정규식은 문법이
+//      조금 다르다(rg 는 Rust regex — 되돌아보기가 없다). 결과가 다르게 나왔을
+//      때 무엇으로 찾은 것인지 모르면 사람은 코드를 의심한다.
+//
+//   2) **범위 밖으로 못 나간다.** 찾을 자리는 언제나 scope 가 준 절대경로
+//      하나뿐이고, 무늬는 인자로만 넘긴다. 셸을 안 거치므로 무늬 안의
+//      따옴표·세미콜론이 명령이 되지 못한다.
+//
+//   3) **못 찾으면 조용히 예전 길로.** 엔진이 죽거나 낯선 문법에 화를 내면
+//      결과가 없는 것이 아니라 우리가 못 물어본 것이다. 그때 '일치 없음' 을
+//      돌려주면 사람은 없는 줄 안다. 그래서 실패는 실패로 두고 JS 로 다시 찾는다.
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/*
+ * 정규식으로 찾을 것이 없는 파일들.
+ *
+ * **여기가 한 벌뿐인 원본이다.** Grep 의 자바스크립트 길은 이 목록으로 정규식을
+ * 만들고, rg 는 이 목록으로 `--iglob !*.png` 를 만든다. 두 군데에 따로 적어 두면
+ * 언젠가 한쪽만 고쳐지고, 그때부터 같은 명령이 PC 마다 다른 답을 낸다 —
+ * rg 가 깔린 사람만 8MB 번들 속 글자를 찾게 되는 식으로. 그건 오류도 안 나고
+ * 아무도 눈치 못 챈다.
+ */
+export const 안볼확장자 = [
+  'png', 'jpg', 'jpeg', 'gif', 'bmp', 'ico', 'webp', 'svgz', 'pdf',
+  'zip', 'gz', 'tgz', '7z', 'rar',
+  'exe', 'dll', 'so', 'dylib', 'bin', 'dat',
+  'db', 'sqlite', 'sqlite3',
+  'woff', 'woff2', 'ttf', 'otf', 'eot',
+  'mp3', 'mp4', 'wav', 'avi', 'mov', 'mkv',
+  'class', 'jar', 'pyc', 'pyo', 'o', 'a', 'lib', 'pack', 'idx',
+  'map', 'min.js', 'min.css', 'lock',
+];
+
+/** 위 목록으로 만든 정규식. 자바스크립트 길이 쓴다. */
+export const 안볼정규식 = new RegExp(`\\.(${안볼확장자.map((x) => x.replace(/\./g, '\\.')).join('|')})$`, 'i');
+
+/** 위 목록으로 만든 rg 옵션. 대소문자를 안 가린다(정규식의 `i` 와 맞춘다). */
+export function 안볼글로브() {
+  return 안볼확장자.flatMap((x) => ['--iglob', `!*.${x}`]);
+}
+
+/*
+ * 있는지 한 번만 본다.
+ *
+ * 매번 `rg --version` 을 돌리면 찾기 한 번에 프로세스가 하나 더 뜬다.
+ * 없는 PC 에서는 그 실패가 매번 수십 ms 씩 쌓인다.
+ */
+let 본것 = null;
+
+function 있나(이름, 인자) {
+  const r = spawnSync(이름, 인자, { encoding: 'utf8', timeout: 4000, windowsHide: true });
+  return !r.error && r.status === 0;
+}
+
+export function 엔진찾기({ 다시 = false, env = process.env } = {}) {
+  if (본것 && !다시) return 본것;
+  // 끄고 싶을 때가 있다 — 결과가 다르다고 의심될 때 같은 자리에서 견주려면.
+  if (env.DEEL_GREP === 'js') { 본것 = { rg: false, gitgrep: false, 왜: 'DEEL_GREP=js 로 꺼 두었습니다' }; return 본것; }
+  본것 = {
+    rg: 있나('rg', ['--version']),
+    gitgrep: 있나('git', ['--version']),
+    왜: null,
+  };
+  return 본것;
+}
+
+/** 검사가 원래대로 돌려놓을 때. */
+export function 엔진잊기() { 본것 = null; return null; }
+
+/** 이 폴더가 git 저장소 안인가. `git grep` 은 저장소 안에서만 돈다. */
+export function 저장소인가(폴더) {
+  const r = spawnSync('git', ['-C', 폴더, 'rev-parse', '--is-inside-work-tree'], {
+    encoding: 'utf8', timeout: 4000, windowsHide: true,
+  });
+  return !r.error && r.status === 0 && /true/.test(r.stdout ?? '');
+}
+
+/*
+ * rg 로 찾는다.
+ *
+ * 돌려주는 것은 **줄 목록**이다. 세는 일과 자르는 일은 부르는 쪽이 한다 —
+ * 그래야 JS 로 찾았을 때와 결과 모양이 같아진다. 모양이 갈리면 '엔진에 따라
+ * 화면이 다른' 프로그램이 되는데, 그건 이 도구가 피하려는 것이다.
+ *
+ * @returns {{ok:true, 줄들:string[], 잘림:boolean} | {ok:false, 왜:string}}
+ */
+export function rg로찾기({ 무늬, 자리, glob = null, 대소문자무시 = false, 무시파일 = null, 최대 = 5000, timeout = 20000 }) {
+  const 인자 = [
+    '--line-number',
+    '--no-heading',
+    '--with-filename',
+    '--color', 'never',
+    // 아주 큰 파일은 안 본다(JS 길과 같은 규칙). 글이 아닌 파일은 rg 가 기본으로 건너뛴다.
+    '--max-filesize', '2M',
+    /*
+     * git 저장소가 아니어도 .gitignore 를 지킨다.
+     *
+     * rg 는 기본으로 **저장소 안에서만** .gitignore 를 본다. 저장소 밖에서는
+     * 그 파일을 글자로만 여기고 out/ · secret.txt 를 그냥 뒤진다. 우리 JS 길은
+     * 저장소든 아니든 지키므로, 이 한 줄이 없으면 같은 폴더에서 엔진에 따라
+     * 답이 갈린다 — 그것도 **비밀을 더 보는 쪽으로**.
+     */
+    '--no-require-git',
+  ];
+  if (대소문자무시) 인자.push('--ignore-case');
+  if (glob) 인자.push('--glob', glob);
+  // 자바스크립트 길이 안 여는 파일은 rg 도 안 열게 한다. 같은 목록에서 나온다.
+  인자.push(...안볼글로브());
+  /*
+   * .deelignore 도 지켜야 한다.
+   *
+   * rg 는 .gitignore 는 알지만 .deelignore 는 모른다. 그대로 두면 "git 에는
+   * 안 적고 deel 만 건너뛸 것" 이 rg 가 깔린 PC 에서만 조용히 검색된다.
+   * 같은 명령이 PC 마다 다른 답을 내는 셈이라, 이건 빠른 것보다 나쁘다.
+   */
+  if (무시파일) 인자.push('--ignore-file', 무시파일);
+  // `--` 뒤로 넘겨서 무늬가 옵션으로 안 읽히게 한다. `-foo` 같은 무늬가 실제로 있다.
+  인자.push('--regexp', 무늬, '--', 자리);
+
+  const r = spawnSync('rg', 인자, {
+    encoding: 'utf8', timeout, windowsHide: true, maxBuffer: 32 * 1024 * 1024,
+  });
+  // rg 는 못 찾으면 1, 진짜 탈이 나면 2 를 준다. 1 은 성공(빈 결과)이다.
+  if (r.error) return { ok: false, 왜: r.error.message };
+  if (r.status === 2) return { ok: false, 왜: (r.stderr ?? '').split('\n')[0] || 'rg 가 무늬를 못 읽었습니다' };
+  const 줄들 = String(r.stdout ?? '').split('\n').filter(Boolean);
+  return { ok: true, 줄들: 줄들.slice(0, 최대), 잘림: 줄들.length > 최대 };
+}
+
+/** `git grep` 으로 찾는다. rg 가 없고 여기가 저장소일 때. */
+export function git로찾기({ 무늬, 자리, 대소문자무시 = false, 최대 = 5000, timeout = 20000 }) {
+  const 인자 = ['-C', 자리, '--no-pager', 'grep', '--line-number', '--no-color', '-I', '-E'];
+  if (대소문자무시) 인자.push('-i');
+  // 여기도 같은 목록으로 뺀다. git 은 경로무늬 앞머리에 마법을 붙여 빼낸다.
+  인자.push('-e', 무늬, '--', '.', ...안볼확장자.map((x) => `:(exclude,icase)*.${x}`));
+  const r = spawnSync('git', 인자, {
+    encoding: 'utf8', timeout, windowsHide: true, maxBuffer: 32 * 1024 * 1024,
+  });
+  if (r.error) return { ok: false, 왜: r.error.message };
+  if (r.status !== 0 && r.status !== 1) {
+    return { ok: false, 왜: (r.stderr ?? '').split('\n')[0] || 'git grep 이 무늬를 못 읽었습니다' };
+  }
+  const 줄들 = String(r.stdout ?? '').split('\n').filter(Boolean);
+  // git grep 은 저장소 기준 상대경로를 준다. 절대경로로 맞춰 준다 — 아래에서 한 모양으로 쓴다.
+  const 고친것 = 줄들.map((l) => {
+    const i = l.indexOf(':');
+    if (i < 0) return l;
+    return join(자리, l.slice(0, i)) + l.slice(i);
+  });
+  return { ok: true, 줄들: 고친것.slice(0, 최대), 잘림: 고친것.length > 최대 };
+}
+
+/*
+ * `경로:줄번호:내용` 한 줄을 가른다.
+ *
+ * 윈도우 경로에는 `C:` 가 있어서 **첫 번째 콜론으로 자르면 안 된다.**
+ * `C:\a\b.js:12:const x = 1;` 을 첫 콜론에서 자르면 파일 이름이 `C` 가 된다.
+ *
+ * 그 일은 아래 정규식이 이미 막는다. `(.*?)` 는 게으른 짝짓기라 짧은 쪽부터
+ * 보지만, 그 뒤에 **`:숫자:` 가 반드시 와야 한다.** `C` 다음은 `:\Users…`
+ * 라 숫자가 아니므로 그 자리는 버려지고, 진짜 줄 번호 앞 콜론까지 늘어난다.
+ *
+ * 전에는 여기에 "첫 조각이 한 글자면 다시 본다" 는 갈래가 하나 더 있었다.
+ * 지우고 검사를 돌려도 아무것도 안 빨개졌다 — 닿지 않는 길이었다는 뜻이다.
+ * 막고 있는 척만 하는 코드는 없느니만 못해서 지웠다. 대신 윈도우 경로를
+ * 재는 검사를 test/fastgrep.test.js 에 남겨 둔다.
+ */
+export function 줄가르기(줄) {
+  const m = /^(.*?):(\d+):([\s\S]*)$/.exec(줄);
+  if (!m) return null;
+  return { 파일: m[1], 줄: Number(m[2]), 내용: m[3] };
+}
+
+/**
+ * 빠른 엔진으로 찾아 본다. 못 쓰면 null — 부르는 쪽이 예전 길로 간다.
+ *
+ * @returns {{엔진:string, 줄들:Array<{파일,줄,내용}>, 잘림:boolean} | null}
+ */
+export function 빠르게찾기({ 무늬, 자리, glob = null, 대소문자무시 = false, 무시파일 = null, 최대 = 5000 }) {
+  const 것 = 엔진찾기();
+  if (것.rg) {
+    const r = rg로찾기({ 무늬, 자리, glob, 대소문자무시, 무시파일, 최대 });
+    if (r.ok) return { 엔진: 'rg', 줄들: r.줄들.map(줄가르기).filter(Boolean), 잘림: r.잘림 };
+    // rg 가 무늬를 못 읽은 것일 수 있다(Rust regex 에는 되돌아보기가 없다).
+    // 그건 '없다' 가 아니라 '못 물어봤다' 이므로 예전 길로 내려간다.
+    return null;
+  }
+  // git grep 은 .deelignore 를 시킬 방법이 없다. 그 파일이 있으면 예전 길로 간다 —
+  // 사람이 "deel 은 여기 보지 마라" 고 적어 둔 것을 못 지키면 빠른 것이 뜻이 없다.
+  if (것.gitgrep && !무시파일 && 저장소인가(자리)) {
+    const r = git로찾기({ 무늬, 자리, 대소문자무시, 최대 });
+    if (r.ok) return { 엔진: 'git grep', 줄들: r.줄들.map(줄가르기).filter(Boolean), 잘림: r.잘림 };
+    return null;
+  }
+  return null;
+}
+
+/** 화면·결과 꼬리에 적을 한마디. 무엇으로 찾았는지 사람이 알아야 한다. */
+export function 엔진말(이름) {
+  if (!이름) return '';
+  return `(${이름} 으로 찾았습니다 — 이 PC 에 이미 있어서 빌려 썼습니다)`;
+}

package/src/tools/fsutil.js

@@ -1,7 +1,8 @@
 // 파일 훑기와 glob 매칭. 외부 패키지 없이 직접 구현한다.
 import { readdirSync, statSync, readFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { join } from 'node:path';
 import { decode, looksBinary } from './encoding.js';
+import { 뿌리규칙읽기, 파일규칙읽기, 걸리나 } from './ignore.js';
 
 /**
  * 폴더를 통째로 옮겨 담는다.
@@ -142,32 +143,74 @@ function escapeLiteral(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-// 폴더를 훑어 파일 목록을 낸다. { path(절대), rel(/구분), mtime, size }
-export function walk(root, { limit = 20000, skipDirs = SKIP_DIRS } = {}) {
+/**
+ * 폴더를 훑어 파일 목록을 낸다. { path(절대), rel(/구분), mtime, size }
+ *
+ * `ignore` 가 켜져 있으면(기본) .gitignore 가 건너뛰라는 것은 건너뛴다 (tools/ignore.js).
+ * skipDirs 는 그 아래의 바닥이다 — .gitignore 가 없어도 node_modules 는 늘 건너뛴다.
+ * 돌려주는 배열에는 `건너뜀 = { 폴더, 파일 }` 이 (열거되지 않게) 붙어 있다. 부르는 쪽이 그 수를
+ * 화면에 적는다 — 조용히 빼면 "그 파일이 없다" 로 읽힌다.
+ * 폴더를 통째로 옮기거나 복사할 때는 `ignore: false` 로 — 그때는 다 있어야 한다.
+ *
+ * `잘림` 도 같이 붙는다 — **상한에서 멈췄다는 뜻이다.**
+ *
+ * 전에는 이 상한이 조용했다. 파일 5만 개짜리 저장소에서 앞의 2만 개만 훑고
+ * 멈추는데, 아무 데도 그 말이 안 나갔다. 그래서 `Grep` 이 "일치 없음" 이라고
+ * 답했다 — 실제로는 뒤쪽 3만 개에 100군데가 있는데도. 못 찾은 것과 안 본 것은
+ * 다르고, 그걸 안 가르면 사람은 없는 줄 알고 그냥 간다. 조용한 상한은
+ * 틀린 답보다 나쁘다.
+ */
+export const 기본훑기상한 = 20000;
+
+/**
+ * 몇 개까지 훑을까.
+ *
+ * 2만 개는 대부분의 저장소에 넉넉하지만 큰 단일 저장소에는 모자란다. 그래서
+ * 올릴 수 있게 열어 둔다 — 못 보는 것을 알려 주기만 하고 손쓸 방법이 없으면
+ * 알려 준 뜻이 없다. 터무니없는 값은 안 받는다(100 미만·200만 초과).
+ */
+export function 훑기상한(env = process.env) {
+  const n = Number(env.DEEL_WALK_LIMIT);
+  if (!Number.isFinite(n) || n < 100 || n > 2000000) return 기본훑기상한;
+  return Math.floor(n);
+}
+
+export function walk(root, { limit = 훑기상한(), skipDirs = SKIP_DIRS, ignore = true } = {}) {
   const out = [];
-  const stack = [root];
+  const 건너뜀 = { 폴더: 0, 파일: 0 };
+  const stack = [{ dir: root, rel: '', 규칙: ignore ? 뿌리규칙읽기(root) : [] }];
   while (stack.length && out.length < limit) {
-    const dir = stack.pop();
+    const { dir, rel, 규칙 } = stack.pop();
     let entries;
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    // 이 폴더에 .gitignore 가 있으면 그 아래에만 더한다 (뿌리 것은 위에서 읽었다).
+    let 여기규칙 = 규칙;
+    if (ignore && rel && entries.some((e) => e.name === '.gitignore' && e.isFile())) {
+      const 추가 = 파일규칙읽기(join(dir, '.gitignore'), rel);
+      if (추가.length) 여기규칙 = [...규칙, ...추가];
+    }
     for (const e of entries) {
       const full = join(dir, e.name);
+      const erel = rel ? `${rel}/${e.name}` : e.name;
       if (e.isDirectory()) {
         if (skipDirs.has(e.name)) continue;
-        stack.push(full);
+        if (여기규칙.length && 걸리나(erel, true, 여기규칙)) { 건너뜀.폴더 += 1; continue; }
+        stack.push({ dir: full, rel: erel, 규칙: 여기규칙 });
       } else if (e.isFile()) {
+        if (여기규칙.length && 걸리나(erel, false, 여기규칙)) { 건너뜀.파일 += 1; continue; }
         let st;
         try { st = statSync(full); } catch { continue; }
-        out.push({
-          path: full,
-          rel: relative(root, full).split(sep).join('/'),
-          mtime: st.mtimeMs,
-          size: st.size,
-        });
+        out.push({ path: full, rel: erel, mtime: st.mtimeMs, size: st.size });
         if (out.length >= limit) break;
       }
     }
   }
+  Object.defineProperty(out, '건너뜀', { value: 건너뜀, enumerable: false });
+  // 상한까지 찼으면 "여기서 멈췄다" 고 표시한다. 딱 맞아떨어져 끝난 경우까지
+  // 잘렸다고 하게 되지만, 그쪽으로 틀리는 편이 낫다 — 덜 봤다고 말하는 것은
+  // 사람을 한 번 더 보게 만들 뿐이고, 다 봤다고 말하는 것은 못 보게 만든다.
+  Object.defineProperty(out, '잘림', { value: out.length >= limit, enumerable: false });
+  Object.defineProperty(out, '상한', { value: limit, enumerable: false });
   return out;
 }