deel-local-cli 0.5.0

package/src/setup.js

@@ -0,0 +1,172 @@
+// 첫 실행 마법사 + 진단 실행.
+import { c, say, rule, mark, width } from './ui/ansi.js';
+import { ask, pick, confirm } 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 { writeFileSync } from 'node:fs';
+
+export function banner() {
+  say('');
+  say(`  ${c.cyan('deel')} ${c.gray('— 로컬 모델 코딩 에이전트')}`);
+  say('');
+}
+
+// 주소와 키를 받아 연결을 찾아낸다. 실패하면 null.
+async function connect(url, key) {
+  const s = spin(`${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')}`);
+    say('');
+    say(`    ${c.gray('확인할 것 — 주소·포트가 맞는지, 프록시가 필요한지,')}`);
+    say(`    ${c.gray('사내 인증서라면 NODE_EXTRA_CA_CERTS 환경변수가 필요합니다.')}`);
+    say('');
+    return null;
+  }
+  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}`);
+  say(`    ${c.gray('인증')} ${found.auth === 'none' ? '없음' : found.auth}`);
+  say(`    ${c.gray('모델')} ${found.models.length}개 발견`);
+  if (found.warn) say(`    ${mark.warn} ${c.yellow(found.warn)}`);
+  return found;
+}
+
+async function chooseModel(found) {
+  if (!found.models.length) {
+    say('');
+    say(`  ${mark.warn} ${c.yellow('모델 목록을 못 받았습니다.')} ${c.gray('이름을 직접 넣어 주세요.')}`);
+    return (await ask('모델 이름')).trim();
+  }
+  const items = found.models.slice(0, 40).map((m) => ({ label: m.id, note: m.note ?? '' }));
+  const i = await pick('사용할 모델', items);
+  return items[i].label;
+}
+
+// 진단을 돌리고 결과를 화면에 그린다.
+export async function runProbe(conn, { out = null } = {}) {
+  renderHeader({ shape: conn.kind, base: conn.base, auth: conn.auth, model: conn.model });
+  const { facts, results } = await probe(conn, renderLine);
+  const v = verdict(facts, results);
+  renderVerdict(v);
+  if (out) {
+    writeFileSync(out, plainReport(facts, results, v), 'utf8');
+    say(`  ${mark.ok} 보고서 저장됨 ${c.cyan(out)}`);
+    say(`     ${c.gray('사내망에서 돌렸다면 이 파일만 가져오시면 됩니다.')}`);
+    say('');
+  }
+  return { facts, results, v };
+}
+
+export async function runSetup() {
+  banner();
+  say(`  ${c.gray('모델 연결을 설정합니다. 주소와 키만 있으면 됩니다.')}`);
+  say('');
+
+  const name = (await ask('이름', { def: '사내게이트웨이' })).trim();
+  const url = (await ask('주소 (Base URL)')).trim();
+  if (!url) { say(`  ${mark.no} 주소가 비었습니다.`); return 1; }
+  const key = (await ask('API 키', { mask: true })).trim();
+
+  say('');
+  const found = await connect(url, key);
+  if (!found) return 1;
+
+  const model = await chooseModel(found);
+  if (!model) { say(`  ${mark.no} 모델이 비었습니다.`); return 1; }
+
+  const conn = { kind: found.kind, base: found.base, auth: found.auth, key, model };
+  const { facts } = await runProbe(conn);
+
+  const id = slug(name);
+  const cfg = load();
+  upsert(cfg, {
+    id, name,
+    kind: found.kind,
+    baseUrl: found.base,
+    auth: found.auth,
+    apiKey: key,
+    model,
+    ctx: facts.ctx ?? null,
+    streaming: facts.streaming ?? false,
+    tools: facts.tools ?? false,
+    json: facts.json ?? false,
+    think: facts.think ?? 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 로 넣으세요 — 그쪽이 우선합니다.')}`);
+  }
+  say('');
+  return 0;
+}
+
+// 저장된 프로필 또는 인자로 받은 값으로 진단만 다시 돌린다.
+export async function runDiagnose(flags) {
+  banner();
+  let conn;
+
+  if (flags.url) {
+    const key = flags.key ?? process.env.DEEL_API_KEY ?? '';
+    const found = await connect(flags.url, key);
+    if (!found) return 1;
+    const model = flags.model ?? (found.models[0]?.id ?? '');
+    if (!model) { say(`  ${mark.no} 모델을 지정해 주세요 (--model).`); return 1; }
+    conn = { kind: found.kind, base: found.base, auth: found.auth, key, model };
+  } else {
+    const cfg = load();
+    const prof = activeProfile(cfg);
+    if (!prof) {
+      say(`  ${mark.warn} 저장된 연결이 없습니다. ${c.cyan('deel setup')} 을 먼저 실행하세요.`);
+      say(`     ${c.gray('또는')} deel diagnose --url <주소> --key <키> --model <모델>`);
+      say('');
+      return 1;
+    }
+    say(`  ${c.gray('프로필')} ${c.bold(prof.name)} ${c.gray(configPath())}`);
+    conn = {
+      kind: prof.kind, base: prof.baseUrl, auth: prof.auth,
+      key: resolveKey(prof), model: flags.model ?? prof.model,
+    };
+  }
+
+  await runProbe(conn, { out: flags.out ?? null });
+  return 0;
+}
+
+export async function showStatus() {
+  banner();
+  const cfg = load();
+  if (!cfg.profiles.length) {
+    say(`  ${c.gray('아직 연결이 없습니다.')}`);
+    say('');
+    say(`    ${c.cyan('deel setup')}   ${c.gray('연결 설정하기')}`);
+    say('');
+    return 0;
+  }
+  rule('연결 목록', 74);
+  for (const p of cfg.profiles) {
+    const here = p.id === cfg.active ? c.cyan(' ← 지금') : '';
+    const caps = [
+      p.tools ? c.green('도구') : c.red('도구'),
+      p.streaming ? c.green('스트림') : c.gray('스트림'),
+      p.json ? c.green('스키마') : c.gray('스키마'),
+      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('');
+  say(`  ${c.gray('설정 파일')} ${configPath()}`);
+  say('');
+  return 0;
+}

package/src/skills/discover.js

@@ -0,0 +1,219 @@
+// 스킬·슬래시명령 찾기.
+// deel 는 스킬을 품고 다니지 않는다 — 켜질 때 그 PC 를 훑어 있는 것을 쓴다.
+// Claude Code 와 같은 형식을 읽으므로, 그쪽으로 쓰인 것이 그대로 먹는다.
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+// --- YAML 앞머리 읽기 (name, description 만 쓰므로 최소만 구현) -------------
+export function frontmatter(text) {
+  if (!text.startsWith('---')) return { data: {}, body: text };
+  const nl = text.indexOf('\n');
+  if (nl < 0) return { data: {}, body: text };
+  const end = text.indexOf('\n---', nl);
+  if (end < 0) return { data: {}, body: text };
+
+  // CRLF 로 저장된 파일이 많다. \r 를 남겨 두면 정규식의 . 와 $ 가 그걸 줄 끝으로 보고
+  // 마지막 줄을 통째로 못 읽는다. 먼저 걷어낸다.
+  const head = text.slice(nl + 1, end).replace(/\r/g, '');
+  const body = text.slice(text.indexOf('\n', end + 1) + 1);
+  const data = {};
+  let key = null;
+  for (const line of head.split('\n')) {
+    if (/^\s/.test(line) && key) {          // 이어지는 줄 (여러 줄 값)
+      data[key] = (data[key] ? data[key] + ' ' : '') + line.trim();
+      continue;
+    }
+    const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+    if (!m) { key = null; continue; }
+    key = m[1];
+    let v = m[2].trim();
+    // YAML 블록 표기( > >- | |- )는 값이 다음 줄부터 온다는 뜻이다. 표시만 지우고 비워 둔다.
+    if (/^[|>][-+]?\d*$/.test(v)) v = '';
+    else if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    data[key] = v;
+  }
+  return { data, body };
+}
+
+const dirs = (p) => {
+  try { return readdirSync(p, { withFileTypes: true }); } catch { return []; }
+};
+
+// --- 스킬 한 개 읽기 --------------------------------------------------------
+function readSkill(file, source, ns) {
+  let text;
+  try { text = readFileSync(file, 'utf8'); } catch { return null; }
+  const { data } = frontmatter(text);
+  const folder = basename(dirname(file));
+  const bare = data.name || folder;
+  return {
+    name: ns ? `${ns}:${bare}` : bare,
+    description: (data.description || '').replace(/\s+/g, ' ').slice(0, 300),
+    path: file,
+    source,
+    bytes: text.length,
+    enabled: true,
+  };
+}
+
+// skills/<이름>/SKILL.md 꼴을 한 폴더에서 모은다.
+function skillsIn(dir, source, ns, out, cap) {
+  for (const e of dirs(dir)) {
+    if (out.length >= cap) return;
+    if (!e.isDirectory()) continue;
+    const f = join(dir, e.name, 'SKILL.md');
+    if (!existsSync(f)) continue;
+    const s = readSkill(f, source, ns);
+    if (s) out.push(s);
+  }
+}
+
+// commands/*.md 를 모은다.
+function commandsIn(dir, source, ns, out, cap) {
+  for (const e of dirs(dir)) {
+    if (out.length >= cap) return;
+    if (!e.isFile() || !e.name.endsWith('.md')) continue;
+    const file = join(dir, e.name);
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch { continue; }
+    const { data } = frontmatter(text);
+    const bare = data.name || basename(e.name, '.md');
+    out.push({
+      name: ns ? `${ns}:${bare}` : bare,
+      description: (data.description || '').replace(/\s+/g, ' ').slice(0, 200),
+      path: file,
+      source,
+      enabled: true,
+    });
+  }
+}
+
+// 플러그인 하나 안에서 스킬·명령이 있을 만한 자리들.
+const PLUGIN_SKILL_DIRS = ['skills', join('.agents', 'skills'), join('.claude', 'skills')];
+const PLUGIN_CMD_DIRS = ['commands', join('.claude', 'commands'), join('.agents', 'commands')];
+
+function readPlugin(rootDir, skills, commands, caps) {
+  const manifest = join(rootDir, '.claude-plugin', 'plugin.json');
+  let info = null;
+  if (existsSync(manifest)) {
+    try { info = JSON.parse(readFileSync(manifest, 'utf8')); } catch {}
+  }
+  const ns = info?.name || basename(rootDir);
+  let found = 0;
+  for (const d of PLUGIN_SKILL_DIRS) {
+    const before = skills.length;
+    skillsIn(join(rootDir, d), 'plugin', ns, skills, caps.skills);
+    found += skills.length - before;
+  }
+  for (const d of PLUGIN_CMD_DIRS) {
+    commandsIn(join(rootDir, d), 'plugin', ns, commands, caps.commands);
+  }
+  return { name: ns, version: info?.version ?? '', license: info?.license ?? '', path: rootDir, skills: found };
+}
+
+// 플러그인 폴더를 찾는다. 캐시가 <시장>/<플러그인>/<판>/ 처럼 겹쳐 있어 몇 겹 내려간다.
+function findPluginRoots(base, depth = 4) {
+  const out = [];
+  const stack = [{ dir: base, d: 0 }];
+  while (stack.length) {
+    const { dir, d } = stack.pop();
+    if (d > depth) continue;
+    if (existsSync(join(dir, '.claude-plugin', 'plugin.json'))) { out.push(dir); continue; }
+    for (const e of dirs(dir)) {
+      if (e.isDirectory() && !e.name.startsWith('.')) stack.push({ dir: join(dir, e.name), d: d + 1 });
+    }
+    if (out.length > 200) break;
+  }
+  return out;
+}
+
+function manifestName(rootDir) {
+  const f = join(rootDir, '.claude-plugin', 'plugin.json');
+  try { return JSON.parse(readFileSync(f, 'utf8')).name || basename(rootDir); }
+  catch { return basename(rootDir); }
+}
+
+// 알맹이가 얼마나 있는지 — 같은 이름이 겹쳤을 때 어느 쪽을 쓸지 고르는 기준.
+function countSkillDirs(rootDir) {
+  let n = 0;
+  for (const d of PLUGIN_SKILL_DIRS) {
+    for (const e of dirs(join(rootDir, d))) {
+      if (e.isDirectory() && existsSync(join(rootDir, d, e.name, 'SKILL.md'))) n++;
+    }
+  }
+  return n;
+}
+
+/**
+ * 그 PC 에 있는 스킬·명령·플러그인을 전부 찾는다.
+ * 뒤에서 찾은 것이 같은 이름을 덮는다: 플러그인 < 사용자 < 프로젝트
+ */
+export function discover(root, opts = {}) {
+  const home = opts.home ?? homedir();
+  const caps = { skills: opts.maxSkills ?? 400, commands: opts.maxCommands ?? 400 };
+  const skills = [];
+  const commands = [];
+  const plugins = [];
+
+  // 1) 플러그인
+  // 같은 플러그인이 cache/ 와 marketplaces/ 양쪽에 있을 수 있다.
+  // 이름이 같으면 알맹이가 더 많은 쪽 하나만 쓴다.
+  const roots = [];
+  for (const base of [join(home, '.deel', 'plugins'), join(home, '.claude', 'plugins')]) {
+    if (existsSync(base)) roots.push(...findPluginRoots(base));
+  }
+  const best = new Map();
+  for (const r of roots) {
+    const name = manifestName(r);
+    const score = countSkillDirs(r);
+    const prev = best.get(name);
+    if (!prev || score > prev.score) best.set(name, { root: r, score });
+  }
+  for (const { root: r } of best.values()) {
+    plugins.push(readPlugin(r, skills, commands, caps));
+  }
+  plugins.sort((a, b) => b.skills - a.skills);
+
+  // 2) 사용자  3) 프로젝트
+  for (const [base, source] of [[home, 'user'], [root, 'project']]) {
+    for (const cfgDir of ['.deel', '.claude']) {
+      skillsIn(join(base, cfgDir, 'skills'), source, null, skills, caps.skills);
+      commandsIn(join(base, cfgDir, 'commands'), source, null, commands, caps.commands);
+    }
+  }
+
+  return { skills: dedupe(skills), commands: dedupe(commands), plugins };
+}
+
+// 같은 이름이면 나중 것(더 가까운 자리)이 이긴다.
+function dedupe(list) {
+  const m = new Map();
+  for (const x of list) m.set(x.name, x);
+  return [...m.values()];
+}
+
+// 스킬 본문 읽기 — 2단계 적재. 너무 길면 자르고 알려준다.
+export function loadSkill(skill, { maxChars = 8000 } = {}) {
+  let text;
+  try { text = readFileSync(skill.path, 'utf8'); } catch (err) { return { error: err.message }; }
+  const { body } = frontmatter(text);
+  const trimmed = body.trim();
+  if (trimmed.length <= maxChars) return { body: trimmed, cut: 0 };
+  return {
+    body: trimmed.slice(0, maxChars) + `\n\n(뒤쪽 ${trimmed.length - maxChars}자는 잘렸습니다. 같은 폴더의 파일을 Read 로 직접 읽으세요: ${dirname(skill.path)})`,
+    cut: trimmed.length - maxChars,
+  };
+}
+
+// 슬래시 명령 본문 읽기. $ARGUMENTS 를 사용자가 준 말로 바꾼다.
+export function loadCommand(cmd, args = '') {
+  let text;
+  try { text = readFileSync(cmd.path, 'utf8'); } catch (err) { return { error: err.message }; }
+  const { body } = frontmatter(text);
+  return {
+    text: body
+      .replace(/\$ARGUMENTS/g, args)
+      .replace(/\$(\d)/g, (_, n) => args.split(/\s+/)[Number(n) - 1] ?? ''),
+  };
+}

package/src/tools/edit-match.js

@@ -0,0 +1,146 @@
+// 편집 대상 찾기. 모델이 공백·들여쓰기·줄바꿈을 조금 틀려도 찾아낸다.
+//
+// 원칙: 느슨하게 찾되 **모호하면 무조건 거부**한다.
+// 엉뚱한 곳을 조용히 고치는 것이 못 찾는 것보다 훨씬 나쁘다.
+// 그래서 각 단계는 "정확히 한 곳"일 때만 통과시킨다.
+
+const TIERS = [
+  { id: 'exact',  label: '정확히 일치' },
+  { id: 'trail',  label: '줄 끝 공백·줄바꿈 차이 무시' },
+  { id: 'indent', label: '들여쓰기 차이 무시' },
+  { id: 'space',  label: '모든 공백 차이 무시' },
+];
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function pattern(needle, tier) {
+  const lines = needle.split(/\r?\n/);
+  switch (tier) {
+    case 'trail':
+      // 줄 끝 공백과 CRLF/LF 차이를 흡수한다.
+      return lines.map((l) => esc(l.replace(/[ \t]+$/, ''))).join('[ \\t]*\\r?\\n');
+    case 'indent':
+      // 줄 앞 들여쓰기까지 흡수한다.
+      return '[ \\t]*' + lines.map((l) => esc(l.trim())).join('[ \\t]*\\r?\\n[ \\t]*');
+    case 'space':
+      // 공백이라면 종류·개수를 가리지 않는다.
+      return esc(needle).replace(/\s+/g, '\\s+');
+    default:
+      return null;
+  }
+}
+
+// 찾은 자리들을 모두 돌려준다.
+function findAll(text, needle, tier) {
+  if (tier === 'exact') {
+    const out = [];
+    let i = 0;
+    while ((i = text.indexOf(needle, i)) >= 0) {
+      out.push({ start: i, end: i + needle.length });
+      i += needle.length || 1;
+    }
+    return out;
+  }
+  const p = pattern(needle, tier);
+  if (!p) return [];
+  let re;
+  try { re = new RegExp(p, 'g'); } catch { return []; }
+  const out = [];
+  for (const m of text.matchAll(re)) {
+    if (m[0].length === 0) continue;
+    out.push({ start: m.index, end: m.index + m[0].length });
+    if (out.length > 50) break;   // 너무 많으면 어차피 모호하다
+  }
+  return out;
+}
+
+/**
+ * @returns {{ok:true, spans, tier, tierLabel}} 또는
+ *          {{ok:false, reason, tier?, count?, near?}}
+ */
+export function findMatch(text, needle, { replaceAll = false } = {}) {
+  if (!needle) return { ok: false, reason: 'empty' };
+
+  for (const t of TIERS) {
+    const spans = findAll(text, needle, t.id);
+    if (!spans.length) continue;
+    if (spans.length > 1 && !replaceAll) {
+      return { ok: false, reason: 'ambiguous', tier: t.id, count: spans.length };
+    }
+    return { ok: true, spans, tier: t.id, tierLabel: t.label };
+  }
+  return { ok: false, reason: 'notfound', near: nearest(text, needle) };
+}
+
+// 못 찾았을 때, 모델이 스스로 고칠 수 있게 "가장 비슷한 줄"을 알려준다.
+export function nearest(text, needle) {
+  const key = String(needle).split(/\r?\n/).find((l) => l.trim()) ?? '';
+  const probe = key.trim().replace(/\s+/g, ' ');
+  if (probe.length < 4) return null;
+
+  const lines = text.split(/\r?\n/);
+  let best = null;
+  for (let i = 0; i < lines.length; i++) {
+    const cand = lines[i].trim().replace(/\s+/g, ' ');
+    if (!cand) continue;
+    const s = similarity(probe, cand);
+    if (!best || s > best.score) best = { score: s, line: i + 1, text: lines[i] };
+  }
+  return best && best.score >= 0.5 ? best : null;
+}
+
+// 두 글자씩 겹치는 비율. 정확할 필요는 없고 "이 줄인가?" 만 알면 된다.
+function similarity(a, b) {
+  if (a === b) return 1;
+  const pairs = (s) => {
+    const out = new Map();
+    for (let i = 0; i < s.length - 1; i++) {
+      const p = s.slice(i, i + 2);
+      out.set(p, (out.get(p) ?? 0) + 1);
+    }
+    return out;
+  };
+  const pa = pairs(a);
+  const pb = pairs(b);
+  let hit = 0;
+  let total = 0;
+  for (const [p, n] of pa) { total += n; hit += Math.min(n, pb.get(p) ?? 0); }
+  for (const [, n] of pb) total += n;
+  return total ? (2 * hit) / total : 0;
+}
+
+/**
+ * 들여쓰기를 흡수해 찾았다면, 넣을 내용의 들여쓰기도 파일에 맞춰 준다.
+ * 모델이 준 들여쓰기를 그대로 넣으면 코드가 어긋난다.
+ * 다만 확신이 서는 경우에만 손댄다 — 어설피 고치면 더 나쁘다.
+ */
+export function reindent(newString, matchedText, needle) {
+  const fileIndent = /^[ \t]*/.exec(matchedText)?.[0] ?? '';
+  const needleIndent = /^[ \t]*/.exec(needle)?.[0] ?? '';
+  if (fileIndent === needleIndent) return newString;
+
+  const lines = newString.split('\n');
+  // 넣을 내용의 모든 줄이 모델의 들여쓰기로 시작할 때만 갈아끼운다.
+  const shiftable = lines.every((l, i) => i === 0 || !l.trim() || l.startsWith(needleIndent));
+  if (!shiftable) return newString;
+
+  return lines
+    .map((l, i) => {
+      if (i === 0) return fileIndent + l.replace(/^[ \t]*/, '');
+      if (!l.trim()) return l;
+      return fileIndent + l.slice(needleIndent.length);
+    })
+    .join('\n');
+}
+
+// 찾은 자리들을 실제로 바꾼다. 뒤에서부터 바꿔야 앞쪽 위치가 안 밀린다.
+export function applySpans(text, spans, makeReplacement) {
+  let out = text;
+  for (const s of [...spans].sort((a, b) => b.start - a.start)) {
+    const matched = text.slice(s.start, s.end);
+    out = out.slice(0, s.start) + makeReplacement(matched) + out.slice(s.end);
+  }
+  return out;
+}
+
+export const TIER_LABELS = Object.fromEntries(TIERS.map((t) => [t.id, t.label]));

package/src/tools/fsutil.js

@@ -0,0 +1,90 @@
+// 파일 훑기와 glob 매칭. 외부 패키지 없이 직접 구현한다.
+import { readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+export const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.deel', '.svn', '.hg', 'dist', 'build',
+  '.next', '.nuxt', '.cache', '__pycache__', '.venv', 'venv', 'target',
+]);
+
+// glob 을 정규식으로. **  *  ?  {a,b}  [abc] 를 지원한다.
+export function globToRegex(pattern) {
+  let re = '';
+  let i = 0;
+  const p = pattern.replace(/\\/g, '/');
+  while (i < p.length) {
+    const ch = p[i];
+    if (ch === '*') {
+      if (p[i + 1] === '*') {
+        // **/ 는 "0개 이상의 폴더", ** 는 "무엇이든"
+        if (p[i + 2] === '/') { re += '(?:[^/]*\\/)*'; i += 3; }
+        else { re += '.*'; i += 2; }
+      } else { re += '[^/]*'; i += 1; }
+    } else if (ch === '?') { re += '[^/]'; i += 1; }
+    else if (ch === '{') {
+      const end = p.indexOf('}', i);
+      if (end < 0) { re += '\\{'; i += 1; }
+      else {
+        const parts = p.slice(i + 1, end).split(',').map(escapeLiteral);
+        re += `(?:${parts.join('|')})`;
+        i = end + 1;
+      }
+    } else if (ch === '[') {
+      const end = p.indexOf(']', i);
+      if (end < 0) { re += '\\['; i += 1; }
+      else { re += p.slice(i, end + 1); i = end + 1; }
+    } else { re += escapeLiteral(ch); i += 1; }
+  }
+  return new RegExp(`^${re}$`, process.platform === 'win32' ? 'i' : '');
+}
+
+function escapeLiteral(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// 폴더를 훑어 파일 목록을 낸다. { path(절대), rel(/구분), mtime, size }
+export function walk(root, { limit = 20000, skipDirs = SKIP_DIRS } = {}) {
+  const out = [];
+  const stack = [root];
+  while (stack.length && out.length < limit) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (skipDirs.has(e.name)) continue;
+        stack.push(full);
+      } else if (e.isFile()) {
+        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,
+        });
+        if (out.length >= limit) break;
+      }
+    }
+  }
+  return out;
+}
+
+// 텍스트 파일인지 — 앞부분에 NUL 이 있으면 바이너리로 본다.
+export function isText(path) {
+  try {
+    const fd = readFileSync(path);
+    return !fd.subarray(0, 8000).includes(0);
+  } catch { return false; }
+}
+
+export function readText(path) {
+  const buf = readFileSync(path);
+  if (buf.subarray(0, 8000).includes(0)) {
+    const err = new Error('바이너리 파일입니다 — 텍스트로 읽을 수 없습니다');
+    err.binary = true;
+    throw err;
+  }
+  return buf.toString('utf8');
+}