deel-local-cli 1.2.0 → 1.4.0

package/src/tools/desc.en.js

@@ -0,0 +1,219 @@
+/**
+ * 도구 설명 영어판 — 모델이 읽는 글이다.
+ *
+ * ── 왜 여기 따로 두나 ───────────────────────────────────────────────────
+ *
+ * index.js 의 한글 설명은 손대지 않는다. 저 글은 오래 겪으면서 한 문장씩
+ * 눌러 온 것이라(“앞부분을 다시 보내지 마라”, “파일 목록만 봐서는 안 보인다”),
+ * 그 파일을 두 언어로 갈라 놓으면 다음에 한쪽만 고치게 된다. 여기 표에
+ * 없는 것은 한글 설명이 그대로 나간다 — 화면 말과 같은 규칙이다.
+ *
+ * ── 왜 옮기나 ───────────────────────────────────────────────────────────
+ *
+ * 두 가지다. 하나는 영어로 켠 사람이 한국어 도구 설명을 받으면, 모델이
+ * 무엇을 골라야 할지를 못 읽는다는 것. 다른 하나는 **토큰**이다.
+ * 도구 정의는 매 요청에 통째로 실리는 고정 몫인데, 한글은 글자당 약 1토큰이고
+ * 영문은 약 3.6자당 1토큰이다. 32k 창에서 이 몫이 10% 를 넘게 먹고 있었다.
+ *
+ * ── 옮길 때 지킨 것 ─────────────────────────────────────────────────────
+ *
+ * 규칙을 한 줄도 안 뺐다. 특히 이런 줄들은 글자 그대로 옮겼다 —
+ * 빠지면 그 모델만 조용히 다르게 굴고, 그 차이는 몇 걸음 뒤에야 드러난다.
+ *
+ *   Edit  “먼저 Read 로 읽어야 한다”      · 안 읽고 고치는 것을 막는 자리
+ *   Append“앞부분을 다시 보내지 마라”     · 같은 자리에서 또 잘리는 것을 막는 자리
+ *   Bash  “끝나지 않는 것은 background”   · 시간 초과로 죽는 것을 막는 자리
+ *   Verify“확인 못 한 것은 못 했다고”     · 이 프로그램이 거짓말을 안 하게 하는 자리
+ *
+ * 도구 이름과 인자 이름은 **안 옮긴다.** 그건 식별자다. Task 의 목적·할일처럼
+ * 한글로 된 인자 이름도 그대로 둔다 — 이름을 바꾸면 그 도구가 아예 안 불린다.
+ */
+export const 도구설명EN = {
+  Read: {
+    desc: 'Read one file. Line numbers come back with it. You must read a file before editing it.'
+      + ' Excel files (.xlsx/.xlsm/.xls) can be read directly too — they come back as CSV per sheet,'
+      + ' so there is no need to ask the user to export anything. Excel files are read-only here, though.',
+    params: {
+      file_path: 'path of the file to read',
+      offset: 'first line (1-based). Only for large files',
+      limit: 'how many lines to read',
+    },
+  },
+  Write: {
+    desc: 'Create a file, or overwrite one completely. Use Edit to change part of a file.'
+      + ' **You can create several files in one call** — pass them as an array in files.'
+      + ' Do that when you are laying out a folder structure. One call per file means one model'
+      + ' round trip per file, and an eight-file skeleton loses minutes to that.',
+    params: {
+      file_path: 'path to write (single file)',
+      content: 'the whole file content (single file)',
+      files: 'several files at once. When you use this, leave file_path and content out.',
+    },
+  },
+  Append: {
+    desc: 'Append to the end of a file. This is how you build a large file — Write the first part,'
+      + ' then call Append repeatedly until it is complete. Splitting it and landing it for certain'
+      + ' beats trying to fit it in one call and getting cut off. No Read needed first — you are only'
+      + ' adding to the end, so there is nothing to read.',
+    params: {
+      file_path: 'path of the file to append to',
+      content: 'what to add at the end',
+    },
+  },
+  Edit: {
+    desc: 'Replace an exactly matching string in a file. You must Read it first.'
+      + ' **If there are several places to change, send them in one call as the edits array** —'
+      + ' they may even be in different files. One call per place means one model round trip per'
+      + ' place, and a six-place cleanup loses minutes to that.',
+    params: {
+      file_path: 'path of the file to edit (single edit)',
+      old_string: 'what to replace. Must be unique within the file',
+      new_string: 'what to replace it with',
+      replace_all: 'true to replace every occurrence',
+      edits: 'several places at once, applied in the order given. When you use this, leave the arguments above out.',
+    },
+  },
+  Glob: {
+    desc: 'Find files by name pattern. e.g. **/*.js, src/**/*.{ts,tsx}',
+    params: {
+      pattern: 'glob pattern',
+      path: 'folder to start from. Defaults to the whole working folder',
+    },
+  },
+  Grep: {
+    desc: 'Search file contents with a regular expression.',
+    params: {
+      pattern: 'regular expression',
+      path: 'folder or file to search',
+      glob: 'restrict which files. e.g. **/*.js',
+      output_mode: 'defaults to files_with_matches',
+      '-i': 'ignore case',
+      '-n': 'show line numbers',
+      head_limit: 'cap the number of results',
+    },
+  },
+  Skill: {
+    desc: 'Open one skill and read it. The list carries only names and descriptions,'
+      + ' so pick the one you need and pull its body with this.',
+    params: { name: 'skill name, exactly as listed' },
+  },
+  Bash: {
+    desc: 'Run a command. Commands that cannot be undone are blocked.'
+      + ' **Anything that never ends (dev servers, watch) must be started with background: true** —'
+      + ' called plainly it dies on timeout. After starting one, read its output with Jobs.',
+    params: {
+      command: 'the command to run',
+      description: 'one line on what this command does',
+      timeout: 'time limit in ms. Default 120000',
+      background: 'true for a command that never ends. Returns immediately; read it with Jobs',
+    },
+  },
+  WebFetch: {
+    desc: 'Read a web page. Read-only — nothing is sent. Use it to check documentation, an error'
+      + ' message, or how a library is used. Addresses on this machine or an internal network are'
+      + ' not read. Several calls to the same site go out one after another, so they cost that much'
+      + ' more time — fetch only what you need. Truncated JSON cannot be read, so if it comes back'
+      + ' cut, narrow the request or raise max_chars and call again.',
+    params: {
+      url: 'address to read (http/https)',
+      max_chars: 'maximum characters to pull. Left out, it is sized to the model. Raise it if the'
+        + ' material comes back cut (max 120000)',
+    },
+  },
+  Recall: {
+    desc: 'Search past sessions in this folder. When the user points back ("last time"), use this'
+      + ' instead of asking again. This does not search file contents — that is Grep.',
+    params: {
+      query: 'what to look for. Two or three words (e.g. "CP949 encoding")',
+      limit: 'how many to bring back (default 8)',
+      tools: 'also dig through tool results (default false)',
+    },
+  },
+  Remember: {
+    desc: 'Write one line that outlives this session. Rules the user set, promises made, mistakes'
+      + ' not to repeat. Do not record anything that only applies to this job, or anything a file'
+      + ' would tell you. This line rides on every later request — keep it to one sentence.',
+    params: { text: 'one line (e.g. "internal documents are read as CP949 and written back as CP949")' },
+  },
+  TodoWrite: {
+    desc: 'Create and update the todo list. For anything that takes several steps, build the list'
+      + ' first and update it the moment each step finishes. Always send the whole list. state is'
+      + ' one of todo / doing / done, and only one item may be doing at a time. The number of steps'
+      + ' is set by the size of the job — there is no fixed count and no cap. Do not squeeze unrelated'
+      + ' work into one line to hit a number. Write each step small enough to check on its own.',
+    params: { todos: 'the whole todo list. No cap — as many as the job needs' },
+  },
+  Verify: {
+    desc: 'Check that what you made actually works. Call this **before** you finish, without fail.'
+      + ' A file existing and a file working are different things — an unclosed tag, a src pointing'
+      + ' at a file that is not there, one missing bracket in JS: none of that shows in a file listing.'
+      + ' What can be run gets run (node --check, py_compile); what cannot gets read (HTML tag pairs,'
+      + ' missing references, CSS braces, JSON). Whatever it could not check, it tells you it could not.'
+      + ' Running tests or a build is Bash — that goes through the user for approval.',
+    params: { paths: 'files to check. Left out, it checks everything checkable in the working folder.' },
+  },
+  Outline: {
+    desc: 'See only the **skeleton** of a folder or file — per file, the names and line numbers of'
+      + ' functions, classes, types, and headings. Call this before touching code you did not write.'
+      + ' It tells you what is where for a fraction of what reading whole files costs. Pick the places'
+      + ' to change here, then Read **only those files**. Reads js/ts, py, java/kotlin, go, rust, c#,'
+      + ' md, html, css, sh, json.',
+    params: {
+      path: 'folder or file path. Defaults to the whole working folder',
+      pattern: 'narrow by name (e.g. **/*.js). Left out, everything',
+    },
+  },
+  Task: {
+    desc: 'Split a chunk of a large job off as a subtask and **run it separately.** The subtask works'
+      + ' start to finish in its own conversation and returns only a summary — the files it read do'
+      + ' not pile up in your window. That is why work that creates or edits several files has to be'
+      + ' divided this way to get to the end. One chunk must be finishable on its own (e.g. "create'
+      + ' index.html and style.css"). The subtask cannot see your conversation — put everything it'
+      + ' needs into 할일. Do not use this for one short job. Doing it yourself is faster.',
+    params: {
+      목적: 'this chunk in one line (e.g. "build the dashboard page skeleton")',
+      할일: 'everything the subtask has to do. It cannot see this conversation, so put the background,'
+        + ' the decisions, and the file paths here. Say what counts as done, too.',
+      모드: 'how the subtask works: code (builds and edits) · debug (finds causes) · ask (reads and'
+        + ' answers only). Defaults to code.',
+      모델: 'hand this chunk to a **different model**. Only profile names the user has configured'
+        + ' work (do not invent an address — it will not be accepted). Left out, it stays on the model'
+        + ' you are using. Handing routine work (formatting, repetitive edits, short summaries) to a'
+        + ' small model keeps your window from filling. Do the work that needs judgement yourself.',
+    },
+  },
+  Def: {
+    desc: 'Ask the language server **where a name is defined.** You get the location without reading'
+      + ' the file. Unlike Grep it does not hand you the wrong places — not the same name in a comment,'
+      + ' not the same name in a third-party library, not the same name inside a string.'
+      + ' Call this before touching code you did not write. Once you know where it is, Read only that file.'
+      + ' If the name exists in several places you get the list, and file_path picks one.',
+    params: {
+      name: 'the name to find (function, class, variable)',
+      file_path: 'the file the name is used in. Use it when the same name exists in several places',
+      line: 'line number inside file_path where the name appears (1-based)',
+    },
+  },
+  Refs: {
+    desc: 'Ask the language server for **every place a name is used.** Call it before you rename'
+      + ' something or change a function — this is what tells you how many places have to change together.'
+      + ' Unlike the hundreds of lines Grep gives you, only the places that really use it come back.'
+      + ' Grep still finds comments, config and docs, though: use this for the code and Grep for the rest'
+      + ' when you rename something outright.',
+    params: {
+      name: 'the name to find (function, class, variable)',
+      file_path: 'the file the name is defined in. Use it when the same name exists in several places',
+      line: 'line number inside file_path where the name appears (1-based)',
+      include_declaration: 'include the definition itself. Default false',
+    },
+  },
+  Jobs: {
+    desc: 'List, read, and end background commands (Bash with background). Called with no number,'
+      + ' you get the list. Given a number, you get whatever output arrived since last time.'
+      + ' If you started a server, you must end it when the job is done.',
+    params: {
+      번호: 'job number to look at. Left out, the list',
+      끝내기: 'true to end that job (stop)',
+    },
+  },
+};

package/src/tools/index.js

@@ -1,4 +1,4 @@
-// 도구 6종. 이름과 인자를 Claude Code 와 같게 맞춘다 —
+// 도구. 이름과 인자를 Claude Code 와 같게 맞춘다 —
 // 그래야 그 관례로 쓰인 스킬·명령이 그대로 먹는다.
 import { writeFileSync, appendFileSync, readFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -14,11 +14,16 @@ import { TODO_TOOL } from './todo.js';
 import { TASK_TOOL } from './task.js';
 import { OUTLINE_TOOL } from './outline.js';
 import { VERIFY_TOOL } from './verify.js';
+import { DEF_TOOL, REFS_TOOL } from './lsp.js';
+import { 편집후진단, 붙이기 as 진단붙이기, 데우기 } from '../lsp/diag.js';
+import { 프로젝트갈래 } from '../lsp/servers.js';
 import { allow as allowedIn } from '../agent/modes.js';
 import { 도구정의, 이름풀기 } from '../backend/mcp.js';
 import { isExcelPath, readExcel, toText as excelText, summarize as excelSummary } from './excel.js';
 import { diffLines } from '../ui/diff.js';
 import { 읽을줄수, 찾을개수, 찾을줄수, 설명길이 } from '../agent/budget.js';
+import { 도구설명EN } from './desc.en.js';
+import { 언어 } from '../i18n/index.js';
 
 /*
  * 한 번에 돌려줄 양은 **모델에 맞춰** 정한다 (agent/budget.js).
@@ -180,6 +185,26 @@ function 줄수(abs, 인코딩) {
   } catch { return 0; }
 }
 
+/**
+ * 그 줄과 앞뒤 몇 줄. Edit 이 빗나갔을 때 보여 줄 것.
+ *
+ * 줄 번호를 같이 붙인다 — 모델이 "몇 번 줄" 로 세어 다시 잡을 수 있어야 한다.
+ * 한 줄만 보여 주던 것을 넓힐 때, 넓힌 만큼 자리를 먹으니 짧게 자른다.
+ */
+function 둘레(text, 줄번호, 보일줄 = 1) {
+  const 줄들 = String(text ?? '').split('\n');
+  const 가운데 = Math.max(1, Number(줄번호) || 1);
+  const 반 = Math.floor(Math.max(1, 보일줄) / 2);
+  const 처음 = Math.max(1, 가운데 - 반);
+  const 끝 = Math.min(줄들.length, 처음 + Math.max(1, 보일줄) - 1);
+  const out = [];
+  for (let i = 처음; i <= 끝; i++) {
+    const 표 = i === 가운데 ? '→' : ' ';
+    out.push(`  ${표} ${String(i).padStart(5)} | ${줄들[i - 1].slice(0, 120)}`);
+  }
+  return out.join('\n');
+}
+
 function 엑셀은못고침(보인이름) {
   return `엑셀 파일은 이 도구로 고칠 수 없습니다: ${보인이름}\n`
     + '  읽기만 됩니다 (CSV 로 바꿔서 보여줍니다). 서식·수식·차트가 든 파일을\n'
@@ -335,8 +360,16 @@ function 한군데고치기(args, ctx) {
     if (m.reason === 'ambiguous') {
       return { error: `${m.count}군데에서 발견됐습니다 (${TIER_LABELS[m.tier]}). 앞뒤로 더 넓게 잡아 하나만 가리키거나 replace_all 을 쓰세요.` };
     }
+    /*
+     * 비슷한 자리를 몇 줄이나 보여 줄까는 **이 모델을 겪어 본 만큼** 정한다
+     * (agent/card.js). Edit 이 자주 빗나가는 모델에는 한 줄만 보여 줘 봐야
+     * 다음 시도도 빗나간다 — 앞뒤를 같이 보여 주면 옮겨 담을 것이 분명해진다.
+     * 겪은 것이 모자라면 여태처럼 한 줄이다. 자리를 괜히 먹지 않는다.
+     */
+    const 보일줄 = Math.max(1, ctx?.카드?.조정?.빗나갔을때보일줄 ?? 1);
     const hint = m.near
-      ? `\n  파일의 ${m.near.line}번 줄이 가장 비슷합니다:\n    ${m.near.text.trim().slice(0, 120)}\n  이 줄을 그대로 옮겨 담아 다시 시도하세요.`
+      ? `\n  파일의 ${m.near.line}번 줄이 가장 비슷합니다:\n${둘레(text, m.near.line, 보일줄)}`
+        + '\n  이 줄을 그대로 옮겨 담아 다시 시도하세요.'
       : '\n  Read 로 다시 읽어 실제 내용을 확인하세요.';
     return { error: `찾지 못했습니다.${hint}` };
   }
@@ -1111,6 +1144,16 @@ export const TOOLS = {
 
   // 뒤에서 도는 명령 보기·끝내기. Bash(background) 와 짝이다 — jobs.js 머리말 참고.
   Jobs: JOBS_TOOL,
+
+  /*
+   * 언어 서버에게 묻는 둘. Grep·Outline 을 밀어내지 않고 **더한다** —
+   * tools/lsp.js 머리말 참고.
+   *
+   * 언어 서버가 이 자리에 없으면 toolSchemas 가 목록에서 뺀다. 못 쓰는 도구를
+   * 세워 두면 모델은 그걸 부르고, 실패를 받고, 또 부른다.
+   */
+  Def: DEF_TOOL,
+  Refs: REFS_TOOL,
 };
 
 /**
@@ -1181,14 +1224,49 @@ export function 설명줄이기(schema, 한도) {
   };
 }
 
+/**
+ * 도구 설명을 지금 화면 말에 맞춘다.
+ *
+ * 표에 없는 도구·인자는 한글 설명이 그대로 나간다 — 화면 말과 같은 규칙이다.
+ * 빈 설명을 내보내지 않는다. 설명 없는 도구는 모델이 언제 쓰는지 모른 채로
+ * 목록에만 서 있게 되는데, 그건 없는 것보다 나쁘다.
+ */
+function 영어설명(schema, 이름) {
+  if (언어() !== 'en') return schema;
+  const 것 = 도구설명EN[이름];
+  if (!것) return schema;
+
+  const p = schema.parameters ?? {};
+  const 새속성 = {};
+  for (const [인자, 값] of Object.entries(p.properties ?? {})) {
+    const 글 = 것.params?.[인자];
+    새속성[인자] = 글 ? { ...값, description: 글 } : 값;
+  }
+  return {
+    ...schema,
+    description: 것.desc ?? schema.description,
+    parameters: { ...p, properties: 새속성 },
+  };
+}
+
 // 모델에게 넘길 도구 정의 목록.
 // 스킬이 없으면 Skill 도구는 빼서 자리를 아낀다.
-export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null } = {}) {
+export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null, lsp = false } = {}) {
   let list = names ?? Object.keys(TOOLS).filter((n) => {
     if (n === 'Skill') return hasSkills;
     if (n === 'WebFetch') return web;
+    // 언어 서버가 없는 자리에서는 Def·Refs 를 아예 안 보여 준다.
+    //
+    // 웹 도구를 오프라인에서 숨기는 것과 같은 이유다. 못 쓰는 도구를 목록에
+    // 세워 두면 모델은 그걸 부르고, "없습니다" 를 받고, 또 부른다. 그 왕복이
+    // 도구 설명으로 나가는 자리보다 비싸다.
+    if (n === 'Def' || n === 'Refs') return !!lsp;
     return true;
   });
+  // 이름을 직접 준 경우(하위 작업이 부모 것을 물려받을 때)에도 같은 규칙을 건다.
+  // 부모에게 있던 것이 하위에서 갑자기 못 쓰게 되지는 않지만, 시험·일회성 호출이
+  // 이름을 통째로 넘기는 길이 있어서 여기서 한 겹 더 막는다.
+  if (names && !lsp) list = list.filter((n) => n !== 'Def' && n !== 'Refs');
   // 작업 모드가 정해져 있으면 그 모드가 쓰는 것만 남긴다.
   //
   // 설계·계획·묻기 모드에서 파일을 바꾸면 안 된다고 프롬프트로 부탁할 수도 있다.
@@ -1202,7 +1280,20 @@ export function toolSchemas(names = null, { hasSkills = false, web = true, work
    * 이름과 인자는 그대로 남으므로 할 수 있는 일은 똑같다.
    */
   const 한도 = 설명길이(ctx);
-  const 우리것 = list.map((n) => ({ type: 'function', function: 설명줄이기(TOOLS[n].schema, 한도) }));
+  /*
+   * 화면 말이 영어면 도구 설명도 영어로 갈아 끼운다 (tools/desc.en.js).
+   *
+   * 줄이기 **전에** 갈아 끼운다. 순서가 반대면 한글 설명을 한도에 맞춰 자른
+   * 다음 영어로 통째로 바꾸는 셈이라, 자른 것이 아무 뜻이 없어지고 영어 글은
+   * 한도를 넘긴 채로 실린다.
+   *
+   * 이름과 인자 이름은 안 건드린다 — 그건 식별자다. Task 의 목적·할일처럼
+   * 한글로 된 인자 이름을 바꾸면 그 도구가 아예 안 불린다.
+   */
+  const 우리것 = list.map((n) => ({
+    type: 'function',
+    function: 설명줄이기(영어설명(TOOLS[n].schema, n), 한도),
+  }));
 
   /*
    * 밖에서 붙인 도구(MCP)를 뒤에 붙인다.
@@ -1215,6 +1306,58 @@ export function toolSchemas(names = null, { hasSkills = false, web = true, work
   return 우리것;
 }
 
+// 파일을 바꾸는 도구들. 이것만 고친 뒤 진단을 본다.
+const 고치는도구 = new Set(['Write', 'Append', 'Edit']);
+// 한 번에 볼 파일 수. 여덟 개를 한꺼번에 만들었다고 여덟 번 기다릴 수는 없다.
+const 진단볼파일 = 3;
+
+/**
+ * 고친 직후에 그 파일이 성한지 본다 — lsp/diag.js 머리말 참고.
+ *
+ * 여기서 절대 죽으면 안 되고, 늦어서도 안 된다. 파일은 이미 고쳐졌다.
+ * 진단은 **덤**이지 이 도구가 성공했는지의 판단 근거가 아니다. 그래서
+ * 통째로 감싸고, 이미 떠 있는 서버가 없으면 아무것도 안 하고 그냥 지나간다.
+ */
+async function 고친뒤진단(name, r, ctx) {
+  try {
+    if (!고치는도구.has(name) || !r || r.error) return r;
+    /*
+     * **부른 쪽이 켠 자리에서만** 한다. 기본은 꺼짐이다.
+     *
+     * 여기서 하는 일은 남의 프로세스를 하나 띄우는 것이다. 그건 띄운 쪽이
+     * 거둘 줄 알아야 한다 — 안 거두면 그 서버가 작업 폴더를 cwd 로 물고 있어서
+     * 윈도우에서는 폴더 이름조차 못 바꾼다. 그래서 끄는 자리를 갖춘 쪽(repl·
+     * oneshot)만 ctx.lsp.켬 을 켠다. 도구를 직접 부르는 자리는 안 켜진다.
+     */
+    if (ctx.lsp?.켬 !== true) return r;
+    const 뿌리 = ctx.scope?.root;
+    if (!뿌리) return r;
+
+    const 바뀐 = r.changed
+      ? [r.changed]
+      : (Array.isArray(r.여럿) ? r.여럿.filter((x) => x?.ok && x.path).map((x) => x.path) : []);
+    const 볼것 = [...new Set(바뀐)].slice(0, 진단볼파일);
+    if (!볼것.length) return r;
+
+    // 처음 고칠 때 뒤에서 하나 데워 둔다. 이번 것은 못 받아도 다음부터 받는다.
+    데우기(뿌리, 볼것[0]);
+
+    const 것들 = await Promise.all(볼것.map((abs) => 편집후진단(뿌리, abs)));
+    let 답 = r;
+    for (let i = 0; i < 볼것.length; i++) {
+      답 = 진단붙이기(답, 것들[i], ctx.scope.show(볼것[i]));
+    }
+    return 답;
+  } catch {
+    return r;   // 진단 보다 터져서 편집이 실패로 보이는 일은 없어야 한다
+  }
+}
+
+/** 이 폴더에서 언어 서버를 쓸 수 있나. repl 이 켤 때 한 번 물어본다. */
+export function 언어서버있나(뿌리) {
+  try { return !!프로젝트갈래(뿌리); } catch { return false; }
+}
+
 export async function runTool(name, args, ctx) {
   // 밖에서 붙인 도구(MCP)는 이름 앞머리로 갈린다.
   //
@@ -1228,7 +1371,7 @@ export async function runTool(name, args, ctx) {
   try {
     const r = await t.run(args ?? {}, ctx);
     ctx.audit.tool(name, args, r);
-    return r;
+    return await 고친뒤진단(name, r, ctx);
   } catch (err) {
     const r = { error: err.message };
     ctx.audit.tool(name, args, r);