deel-local-cli 0.5.0

package/src/config.js

@@ -0,0 +1,61 @@
+// 연결 프로필 저장/읽기.  ~/.deel/config.json  (프로젝트 폴더의 .deel/config.json 이 우선)
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+
+const USER_DIR = join(homedir(), '.deel');
+const PROJECT_DIR = join(process.cwd(), '.deel');
+
+export function configPath() {
+  const local = join(PROJECT_DIR, 'config.json');
+  if (existsSync(local)) return local;
+  return join(USER_DIR, 'config.json');
+}
+
+const EMPTY = { version: 1, active: null, profiles: [] };
+
+export function load() {
+  const p = configPath();
+  if (!existsSync(p)) return structuredClone(EMPTY);
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    return { ...structuredClone(EMPTY), ...raw };
+  } catch (err) {
+    throw new Error(`설정 파일을 읽지 못했습니다: ${p}\n  ${err.message}`);
+  }
+}
+
+export function save(cfg, { toProject = false } = {}) {
+  const dir = toProject ? PROJECT_DIR : USER_DIR;
+  const p = join(dir, 'config.json');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(p, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  // 키가 들어 있는 파일이므로 가능한 환경에서는 본인만 읽게 잠근다.
+  try { chmodSync(p, 0o600); } catch {}
+  return p;
+}
+
+export function activeProfile(cfg = load()) {
+  if (!cfg.profiles.length) return null;
+  return cfg.profiles.find((x) => x.id === cfg.active) ?? cfg.profiles[0];
+}
+
+// 환경변수가 있으면 파일보다 우선한다 — 사내망에서 키를 파일에 안 남기고 싶을 때 쓴다.
+export function resolveKey(profile) {
+  const byName = profile?.id ? process.env[`DEEL_KEY_${profile.id.toUpperCase()}`] : null;
+  return byName || process.env.DEEL_API_KEY || profile?.apiKey || '';
+}
+
+export function upsert(cfg, profile) {
+  const i = cfg.profiles.findIndex((x) => x.id === profile.id);
+  if (i >= 0) cfg.profiles[i] = { ...cfg.profiles[i], ...profile };
+  else cfg.profiles.push(profile);
+  if (!cfg.active) cfg.active = profile.id;
+  return cfg;
+}
+
+export function slug(name) {
+  const base = String(name).trim().toLowerCase()
+    .replace(/[^a-z0-9가-힣]+/g, '-').replace(/^-+|-+$/g, '');
+  return base || 'profile';
+}

package/src/repl.js

@@ -0,0 +1,222 @@
+// 대화 화면. 루프가 보내는 이벤트를 Claude Code 풍으로 그린다.
+import { createInterface } from 'node:readline';
+import { c, say, mark, cursor, width } from './ui/ansi.js';
+import { handle, COMMANDS } from './commands.js';
+import { run } from './agent/loop.js';
+import { Session } from './agent/session.js';
+import { makeScope } from './safety/guard.js';
+import { History } from './safety/undo.js';
+import { Audit } from './safety/audit.js';
+import { activeProfile, load, resolveKey } from './config.js';
+import { discover } from './skills/discover.js';
+
+// 도구 호출을 한 줄로 요약 — Read(src/a.js) 처럼.
+function toolLabel(name, args) {
+  const a = args ?? {};
+  const first =
+    a.file_path ?? a.pattern ?? a.path ??
+    (a.command ? String(a.command).slice(0, 48) : '') ?? '';
+  return `${name}(${c.gray(String(first))})`;
+}
+
+function toolResultLine(result, ms) {
+  if (result?.error) return `${c.red('└')} ${c.red(String(result.error).split('\n')[0])}`;
+  const s = result?.summary ?? '완료';
+  const t = ms > 1000 ? c.gray(` ${(ms / 1000).toFixed(1)}초`) : '';
+  return `${c.gray('└')} ${c.gray(s)}${t}`;
+}
+
+export async function chatLoop(opts = {}) {
+  const cfg = load();
+  const prof = activeProfile(cfg);
+  if (!prof) {
+    say('');
+    say(`  ${mark.warn} 저장된 연결이 없습니다. ${c.cyan('deel setup')} 을 먼저 실행하세요.`);
+    say('');
+    return 1;
+  }
+
+  const root = opts.root ? opts.root : process.cwd();
+  const conn = {
+    kind: prof.kind, base: prof.baseUrl, auth: prof.auth,
+    key: resolveKey(prof), model: prof.model,
+    ctx: prof.ctx ?? 32768, streaming: prof.streaming ?? false,
+    tools: prof.tools ?? false, json: prof.json ?? false, think: prof.think ?? false,
+  };
+
+  const session = new Session(conn, {
+    root,
+    mode: opts.mode ?? 'auto',
+    think: opts.think ?? 'medium',
+    maxSteps: opts.maxSteps ?? 24,
+  });
+
+  // 이 PC 에 있는 스킬·명령·플러그인을 찾아 붙인다. 품고 다니지 않는다.
+  const found = discover(root);
+  session.skills = found.skills;
+  session.commands = found.commands;
+  session.plugins = found.plugins;
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout, historySize: 200 });
+
+  // 입력을 큐로 받는다. rl.question 을 겹쳐 쓰면 파이프로 넣을 때 닫혀 버린다.
+  const queue = [];
+  let waiter = null;
+  let closed = false;
+  const echo = !process.stdin.isTTY;   // 파이프·기록용일 때는 입력을 되비춘다
+
+  rl.on('line', (l) => {
+    if (echo) say(l);
+    if (waiter) { const w = waiter; waiter = null; w(l); }
+    else queue.push(l);
+  });
+  rl.on('close', () => {
+    closed = true;
+    if (waiter) { const w = waiter; waiter = null; w(null); }
+  });
+
+  const nextLine = () => {
+    if (queue.length) return Promise.resolve(queue.shift());
+    if (closed) return Promise.resolve(null);
+    return new Promise((res) => { waiter = res; });
+  };
+
+  const ask = async (label, o = {}) => {
+    process.stdout.write(`  ${c.gray('›')} ${label} ${o.def ? c.gray(`[${o.def}] `) : ''}`);
+    const a = await nextLine();
+    if (a === null) return o.def ?? '';
+    return a.trim() || o.def || '';
+  };
+
+  const ctx = {
+    scope: makeScope(root),
+    history: new History(root),
+    audit: new Audit(root),
+    seen: new Set(),
+    skills: found.skills,
+    loadedSkills: new Set(),
+    ask,
+    confirm: async (name, args) => {
+      say('');
+      say(`  ${c.yellow('?')} ${toolLabel(name, args)}`);
+      const a = (await ask('실행할까요? (y/n)', { def: 'y' })).toLowerCase();
+      return a === 'y' || a === 'yes' || a === 'ㅇ';
+    },
+  };
+
+  // 머리말
+  say('');
+  say(`  ${c.cyan('deel')}  ${c.gray(prof.model)}  ${c.gray('·')}  ${c.gray(ctx.scope.root)}`);
+  const warn = [];
+  if (!conn.tools) warn.push('도구 호출 미확인');
+  if (!conn.streaming) warn.push('스트리밍 없음');
+  if (warn.length) say(`  ${c.yellow('⚠')} ${c.gray(warn.join(' · '))}`);
+  if (found.skills.length || found.commands.length) {
+    say(`  ${c.gray(`스킬 ${found.skills.length}개 · 명령 ${found.commands.length}개 찾음`)}${found.plugins.length ? c.gray(` (플러그인 ${found.plugins.length}개)`) : ''}`);
+  }
+  say(`  ${c.gray('/help 로 명령 목록.  Ctrl+C 로 끝냅니다.')}`);
+  say('');
+
+  let interrupted = false;
+  rl.on('SIGINT', () => {
+    if (interrupted) { rl.close(); return; }
+    interrupted = true;
+    say('');
+    say(`  ${c.gray('한 번 더 Ctrl+C 를 누르면 끝냅니다.')}`);
+    process.stdout.write(`\n${c.cyan('›')} `);
+  });
+
+  for (;;) {
+    process.stdout.write(`\n${c.cyan('›')} `);
+    const line = await nextLine();
+    if (line === null) break;          // 입력이 끝났다 (파이프 종료 / Ctrl+D)
+    interrupted = false;
+    const text = line.trim();
+    if (!text) continue;
+
+    const cmd = await handle(text, session, ctx);
+    if (cmd.exit) break;
+    if (cmd.handled) continue;
+    const toSend = cmd.text ?? text;   // 슬래시 명령이면 펼쳐진 내용을 보낸다
+
+    say('');
+    const started = Date.now();
+    let tools = 0;
+    let thinkChars = 0;
+    let streamed = false;
+    let thinkingShown = false;
+
+    try {
+      for await (const ev of run(session, ctx, toSend)) {
+        switch (ev.type) {
+          case 'waiting':
+            process.stdout.write(`  ${c.gray('생각 중…')}\r`);
+            break;
+
+          case 'thinking':
+            thinkChars += ev.text.length;
+            if (process.stdout.isTTY) {
+              cursor.clearLine();
+              process.stdout.write(`  ${c.magenta('✻')} ${c.gray(`생각 중… ${thinkChars}자`)}`);
+              thinkingShown = true;
+            }
+            break;
+
+          case 'content':
+            if (thinkingShown) { cursor.clearLine(); thinkingShown = false; }
+            if (!streamed) { streamed = true; process.stdout.write('  '); }
+            process.stdout.write(ev.text.replace(/\n/g, '\n  '));
+            break;
+
+          case 'tool_start':
+            if (thinkingShown) { cursor.clearLine(); thinkingShown = false; }
+            if (streamed) { say(''); streamed = false; }
+            say('');
+            say(`  ${c.cyan('⏺')} ${toolLabel(ev.name, ev.args)}`);
+            break;
+
+          case 'tool':
+            tools++;
+            say(`    ${toolResultLine(ev.result, ev.ms ?? 0)}`);
+            break;
+
+          case 'trimmed':
+            say(`  ${c.gray(`(컨텍스트가 차서 오래된 대화 ${ev.dropped}개를 줄였습니다)`)}`);
+            break;
+
+          case 'limit':
+            say('');
+            say(`  ${c.yellow('⚠')} 도구 호출 ${ev.steps}회에서 멈췄습니다. ${c.gray('이어서 하려면 다시 말씀하세요.')}`);
+            break;
+
+          case 'error':
+            if (thinkingShown) cursor.clearLine();
+            say('');
+            say(`  ${c.red('✗')} ${ev.text}`);
+            break;
+
+          case 'done':
+            if (streamed) say('');
+            break;
+        }
+      }
+    } catch (err) {
+      say('');
+      say(`  ${c.red('✗')} ${err.message}`);
+    }
+
+    // 꼬리말 — 이번 턴 요약
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    const bits = [`${secs}초`];
+    if (tools) bits.push(`도구 ${tools}회`);
+    if (session.usage.out) bits.push(`${session.usage.out.toLocaleString()}토큰`);
+    say('');
+    say(`  ${c.gray('─ ' + bits.join(' · '))}`);
+  }
+
+  rl.close();
+  say('');
+  say(`  ${c.gray('끝냅니다.')} ${c.gray(`도구 시간 ${(session.usage.ms / 1000).toFixed(1)}초 · 모델 호출 ${session.usage.calls}회`)}`);
+  say('');
+  return 0;
+}

package/src/report.js

@@ -0,0 +1,112 @@
+// 진단 결과를 화면에 표로 그리고, "이걸로 돌릴 수 있는지" 판정한다.
+import { c, say, rule, pad, width, mark } from './ui/ansi.js';
+
+const ICON = { ok: mark.ok, no: mark.no, warn: mark.warn, skip: c.gray('·') };
+const WORD = { ok: c.green('됨'), no: c.red('안됨'), warn: c.yellow('조건부'), skip: c.gray('확인불가') };
+
+export function renderLine(r) {
+  const icon = ICON[r.status] ?? ' ';
+  const label = pad(r.label, 20);
+  const time = r.ms ? c.gray(pad(`${r.ms}ms`, 8, 'right')) : ' '.repeat(8);
+  say(`  ${icon} ${label} ${pad(WORD[r.status], 12)} ${time}  ${c.gray(r.detail)}`);
+}
+
+export function renderHeader(facts) {
+  say('');
+  rule('연결', 74);
+  const kindName = facts.shape === 'ollama' ? 'Ollama 자체 규격' : 'OpenAI 호환';
+  const rows = [
+    ['규격', kindName],
+    ['주소', facts.base],
+    ['인증', facts.auth === 'none' ? '없음' : facts.auth],
+    ['모델', facts.model],
+  ];
+  for (const [k, v] of rows) say(`  ${c.gray(pad(k, 8))} ${v}`);
+  say('');
+  rule('검사', 74);
+}
+
+// 판정 — 무엇을 할 수 있고 무엇이 막히는지 사람 말로.
+export function verdict(facts, results) {
+  const by = Object.fromEntries(results.map((r) => [r.id, r]));
+  const get = (id) => by[id]?.status;
+  const notes = [];
+  let level;
+
+  if (get('chat') !== 'ok') {
+    level = 'stop';
+    notes.push('기본 대화가 안 됩니다. 주소·키·모델 이름을 먼저 확인해야 합니다.');
+    return { level, notes };
+  }
+
+  const toolsOk = get('tools') === 'ok' && get('toolresult') === 'ok';
+  const toolsPartial = ['ok', 'warn'].includes(get('tools'));
+
+  if (!toolsPartial) {
+    level = 'blocked';
+    notes.push('도구 호출이 안 됩니다 — 이 상태로는 파일을 읽거나 고칠 수 없습니다.');
+    notes.push('게이트웨이가 tools 필드를 지우는지 관리자에게 확인이 필요합니다.');
+  } else if (toolsOk) {
+    level = 'ready';
+    notes.push('도구 호출과 결과 되돌리기가 모두 확인됐습니다. 에이전트 루프를 그대로 올릴 수 있습니다.');
+  } else {
+    level = 'limited';
+    notes.push('도구는 부르는데 인자나 결과 활용이 불안정합니다. 3단계(편집 신뢰성)에 시간을 더 씁니다.');
+  }
+
+  if (get('json') !== 'ok') notes.push('구조적 출력이 약합니다 — 편집 형식을 프롬프트로 강제하고 검사를 붙입니다.');
+  if (get('stream') !== 'ok') notes.push('스트리밍이 없습니다 — 화면은 스피너로 대체하고 기능은 동일하게 갑니다.');
+  if (get('system') === 'warn') notes.push('시스템 지시를 약하게 따릅니다 — 스킬을 적게, 짧게 올려야 합니다.');
+  if (get('think') === 'ok') notes.push('추론 강도가 모델 층에서 먹습니다 — /think 로 바로 조절됩니다.');
+  else notes.push('추론 강도는 루프 층(계획 강제·도구 호출 상한·자기검증 횟수)으로 조절합니다.');
+  if (!facts.ctx) notes.push('컨텍스트 길이를 서버가 안 알려줍니다 — 설정에서 직접 넣어야 합니다.');
+
+  return { level, notes };
+}
+
+const VERDICT_STYLE = {
+  ready:   { tag: c.green('  준비됨  '), line: '이 연결로 deel 를 돌릴 수 있습니다.' },
+  limited: { tag: c.yellow(' 제한적 '), line: '돌아가긴 합니다. 편집 신뢰성 보강이 필요합니다.' },
+  blocked: { tag: c.red('  막힘  '),  line: '핵심 기능이 막혀 있습니다. 아래를 먼저 해결해야 합니다.' },
+  stop:    { tag: c.red(' 연결실패 '), line: '연결 자체가 되지 않았습니다.' },
+};
+
+export function renderVerdict(v) {
+  const s = VERDICT_STYLE[v.level];
+  say('');
+  rule('판정', 74);
+  say(`  ${s.tag}  ${c.bold(s.line)}`);
+  say('');
+  for (const n of v.notes) say(`    ${c.gray('•')} ${n}`);
+  say('');
+}
+
+// 사내망에서 캡처 대신 파일로 가져올 수 있게 — 색 없는 평문.
+export function plainReport(facts, results, v) {
+  const at = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const lines = [
+    'deel 연결 진단 보고서',
+    `생성 시각   ${at}`,
+    '',
+    `규격        ${facts.shape === 'ollama' ? 'Ollama 자체 규격' : 'OpenAI 호환'}`,
+    `주소        ${facts.base}`,
+    `인증        ${facts.auth === 'none' ? '없음' : facts.auth}`,
+    `모델        ${facts.model}`,
+    `컨텍스트    ${facts.ctx ? facts.ctx.toLocaleString() + ' 토큰' : '미상'}`,
+    '',
+    '검사 결과',
+    '-'.repeat(70),
+  ];
+  const plain = { ok: '됨', no: '안됨', warn: '조건부', skip: '확인불가' };
+  for (const r of results) {
+    const label = r.label + ' '.repeat(Math.max(0, 20 - width(r.label)));
+    const state = plain[r.status] + ' '.repeat(Math.max(0, 10 - width(plain[r.status])));
+    const t = r.ms ? `${r.ms}ms` : '';
+    const time = ' '.repeat(Math.max(0, 9 - t.length)) + t;
+    lines.push(`  ${label} ${state} ${time}  ${r.detail}`);
+  }
+  lines.push('-'.repeat(70), '', `판정: ${v.level}`, '');
+  for (const n of v.notes) lines.push(`  - ${n}`);
+  lines.push('');
+  return lines.join('\n');
+}

package/src/safety/audit.js

@@ -0,0 +1,40 @@
+// 감사 로그. 무엇을 언제 어떻게 했는지 전부 남긴다.
+// 자율 실행을 사내에 설득할 때 이 파일이 근거가 된다.
+import { join } from 'node:path';
+import { appendFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+
+export class Audit {
+  constructor(root) {
+    const dir = join(root, '.deel');
+    mkdirSync(dir, { recursive: true });
+    this.file = join(dir, 'audit.jsonl');
+    this.session = `${new Date().toISOString().slice(0, 19).replace(/[:T]/g, '')}`;
+  }
+
+  write(kind, data) {
+    const rec = { at: new Date().toISOString(), session: this.session, kind, ...data };
+    try { appendFileSync(this.file, JSON.stringify(rec) + '\n', 'utf8'); } catch {}
+    return rec;
+  }
+
+  tool(name, args, result) {
+    return this.write('tool', {
+      tool: name,
+      target: args?.file_path ?? args?.path ?? args?.pattern ?? args?.command ?? null,
+      ok: !result?.error,
+      note: result?.error ?? result?.summary ?? null,
+    });
+  }
+
+  turn(text) { return this.write('turn', { text: String(text).slice(0, 500) }); }
+  blocked(why, what) { return this.write('blocked', { why, what: String(what).slice(0, 300) }); }
+  undo(info) { return this.write('undo', info); }
+
+  recent(n = 20) {
+    if (!existsSync(this.file)) return [];
+    return readFileSync(this.file, 'utf8')
+      .split('\n').filter(Boolean).slice(-n)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  }
+}

package/src/safety/guard.js

@@ -0,0 +1,56 @@
+// 자율 실행의 울타리.
+// 승인 프롬프트를 안 쓰는 대신 (1) 작업 범위 밖은 못 건드리고
+// (2) 되돌릴 수 없는 명령만 막는다. 나머지는 전부 통과시킨다.
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+
+export class ScopeError extends Error {}
+export class BlockedError extends Error {}
+
+// 작업 범위 — deel 를 띄운 폴더. 그 밖은 읽기도 쓰기도 막는다.
+export function makeScope(root) {
+  const base = resolve(root);
+  return {
+    root: base,
+    resolve(p) {
+      if (!p || typeof p !== 'string') throw new ScopeError('경로가 비었습니다');
+      const abs = isAbsolute(p) ? resolve(p) : resolve(base, p);
+      const rel = relative(base, abs);
+      if (rel.startsWith('..' + sep) || rel === '..' || (isAbsolute(rel) && rel !== '')) {
+        throw new ScopeError(`작업 범위 밖입니다: ${p}\n  범위: ${base}`);
+      }
+      return abs;
+    },
+    show(abs) {
+      const rel = relative(base, abs);
+      return rel === '' ? '.' : rel.split(sep).join('/');
+    },
+  };
+}
+
+// 되돌릴 수 없는 것만 막는다. 목록이 길어지면 도구가 쓸모없어진다.
+const BLOCKED = [
+  { re: /\brm\s+(-[a-z]*[rR][a-z]*f|-[a-z]*f[a-z]*[rR])\b[^|;&]*\s(\/|~|\$HOME)\s*$/i, why: '뿌리 폴더를 통째로 지우려 합니다' },
+  { re: /\b(mkfs|fdisk|diskpart)\b/i, why: '디스크를 초기화하는 명령입니다' },
+  { re: /\bformat\s+[a-z]:/i, why: '드라이브를 포맷하는 명령입니다' },
+  { re: /\b(rd|rmdir)\s+\/s\b/i, why: '폴더를 통째로 지웁니다 — 정션이 있으면 원본까지 딸려 갑니다' },
+  { re: /\bdel\s+\/[sq]\b.*\\\*/i, why: '하위 폴더까지 전부 지웁니다' },
+  { re: /git\s+push\b[^|;&]*--force(?!-with-lease)/i, why: '원격 이력을 덮어씁니다 (--force-with-lease 를 쓰세요)' },
+  { re: /\bshutdown\b|\breboot\b/i, why: '시스템을 끕니다' },
+  { re: /curl[^|]*\|\s*(ba)?sh/i, why: '받은 스크립트를 그대로 실행합니다' },
+  { re: /\biwr\b[^|]*\|\s*iex\b/i, why: '받은 스크립트를 그대로 실행합니다' },
+];
+
+export function checkCommand(cmd) {
+  const s = String(cmd);
+  for (const b of BLOCKED) {
+    if (b.re.test(s)) throw new BlockedError(`${b.why}\n  막힌 명령: ${s.slice(0, 120)}`);
+  }
+  return true;
+}
+
+// 변경성 동작은 실패해도 다시 실행하지 않는다 — 두 번 실행되면 사고다. (RPA 에서 얻은 원칙)
+const MUTATING = /\b(git\s+(commit|push|merge|rebase|reset)|npm\s+(publish|install)|pip\s+install|mv|cp|del|rm|move|copy|curl\s+-X\s*(POST|PUT|DELETE|PATCH))\b/i;
+
+export function isMutating(cmd) {
+  return MUTATING.test(String(cmd));
+}

package/src/safety/undo.js

@@ -0,0 +1,78 @@
+// 되돌리기. 승인 프롬프트를 안 쓰는 대신 이게 안전망이다.
+// 파일을 고치기 전에 항상 이전 내용을 떠 놓고, /undo 로 턴 단위로 되돌린다.
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, appendFileSync, readdirSync } from 'node:fs';
+
+export class History {
+  constructor(root) {
+    this.dir = join(root, '.deel', 'history');
+    mkdirSync(this.dir, { recursive: true });
+    this.file = join(this.dir, 'edits.jsonl');
+    this.turn = 0;
+  }
+
+  // 새 턴 시작 — /undo 는 턴 하나를 통째로 되돌린다.
+  nextTurn() {
+    this.turn = Date.now();
+    return this.turn;
+  }
+
+  // 파일을 고치기 직전에 부른다. 없던 파일이면 before 는 null.
+  snapshot(absPath, label) {
+    const before = existsSync(absPath) ? safeRead(absPath) : null;
+    const rec = { turn: this.turn, at: new Date().toISOString(), path: absPath, before, label };
+    appendFileSync(this.file, JSON.stringify(rec) + '\n', 'utf8');
+    return rec;
+  }
+
+  all() {
+    if (!existsSync(this.file)) return [];
+    return readFileSync(this.file, 'utf8')
+      .split('\n').filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  }
+
+  turns() {
+    const seen = [];
+    for (const r of this.all()) if (!seen.includes(r.turn)) seen.push(r.turn);
+    return seen;
+  }
+
+  // 최근 n 개 턴을 되돌린다. 되돌린 파일 목록을 반환.
+  undo(n = 1) {
+    const recs = this.all();
+    const turns = this.turns().slice(-n);
+    if (!turns.length) return { restored: [], turns: 0 };
+
+    const target = recs.filter((r) => turns.includes(r.turn));
+    // 같은 파일이 여러 번 바뀌었으면 가장 이른 상태로 되돌려야 한다.
+    const first = new Map();
+    for (const r of target) if (!first.has(r.path)) first.set(r.path, r);
+
+    const restored = [];
+    for (const [path, rec] of first) {
+      try {
+        if (rec.before === null) {
+          if (existsSync(path)) { rmSync(path, { force: true }); restored.push({ path, how: '삭제됨(원래 없던 파일)' }); }
+        } else {
+          writeFileSync(path, rec.before, 'utf8');
+          restored.push({ path, how: '되돌림' });
+        }
+      } catch (err) {
+        restored.push({ path, how: `실패: ${err.message}` });
+      }
+    }
+    // 되돌린 기록은 잘라낸다.
+    const keep = recs.filter((r) => !turns.includes(r.turn));
+    writeFileSync(this.file, keep.map((r) => JSON.stringify(r)).join('\n') + (keep.length ? '\n' : ''), 'utf8');
+    return { restored, turns: turns.length };
+  }
+}
+
+function safeRead(p) {
+  const buf = readFileSync(p);
+  // 바이너리는 되돌리기 대상에서 뺀다 — 텍스트만 다룬다.
+  if (buf.includes(0)) return null;
+  return buf.toString('utf8');
+}