deel-local-cli 1.20.12 → 2.0.0

package/src/setup.js

@@ -1,5 +1,5 @@
 // 첫 실행 마법사 + 진단 실행.
-import { c, say, rule, mark } from './ui/ansi.js';
+import { c, say, rule, mark, clip } from './ui/ansi.js';
 import { 주소가리기 } from './safety/secrets.js';
 import { ask, pick, confirm } from './ui/prompt.js';
 import { spin } from './ui/spinner.js';
@@ -7,13 +7,13 @@ import { detect } from './backend/detect.js';
 import { 규격이름 } from './backend/adapter.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 { 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 { 인증서설정, 인증서등록 } from './backend/clientcert.js';
 import { 바깥인가, 봉인됐나 } from './safety/runmode.js';
-import { 제공자들, 제공자고르기, 어디것일까, 주소후보, 막힌까닭 } from './providers/index.js';
+import { 제공자들, 제공자고르기, 어디것일까, 주소후보, 막힌까닭, 열쇠다듬기 } from './providers/index.js';
 import { writeFileSync } from 'node:fs';
 
 export function banner() {
@@ -22,6 +22,23 @@ export function banner() {
   say('');
 }
 
+/**
+ * 사람이 친 주소가 주소 꼴인가. 틀렸으면 까닭(사람 말), 멀쩡하면 null.
+ * 스킴이 없으면 `http://` 를 붙여 본다 — connect 가 그렇게 붙어 보기 때문이다.
+ */
+function 주소꼴탈(url) {
+  if (/\s/.test(url)) return '빈칸이 들어 있습니다 — 예: http://127.0.0.1:11434/v1';
+  const 스킴붙음 = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `http://${url}`;
+  let u;
+  try { u = new URL(스킴붙음); } catch { return '주소 꼴이 아닙니다 — 예: http://127.0.0.1:11434/v1 · localhost:8000 · http://[::1]:8000'; }
+  if (!/^https?:$/.test(u.protocol)) return `http 나 https 만 됩니다 — 지금은 ${u.protocol}`;
+  // 빈 호스트는 `u.hostname` 으로 못 잡는다 — 호스트가 비면 위 `new URL` 이 먼저 던진다.
+  // 새는 꼴은 슬래시가 셋인 주소다: 파서가 경로를 호스트로 끌어올려 `/v1` 이 호스트 `v1` 이 된다.
+  // 파서가 고쳐 놓은 값 말고 적힌 글자를 본다 (doctor.js 의 주소살펴보기와 쌍둥이).
+  if (/^https?:\/\/\//i.test(스킴붙음)) return '호스트 이름이 없습니다 — 예: http://127.0.0.1:11434/v1';
+  return null;
+}
+
 // 주소와 키를 받아 연결을 찾아낸다. 실패하면 null.
 //
 // 조용히 = 후보를 여럿 훑는 중이라, 실패해도 아직 화면에 안 적는다.
@@ -68,15 +85,30 @@ async function connect(url, key, { 조용히 = false, 제공자: 어디 = null }
      */
     const 까닭 = 막힌까닭(어디, { status: found.status ?? 0, 서버말: found.why ?? '' });
     /*
-     * 옮길 말이 없으면 **받은 말을 그대로** 보여 준다.
+     * 표에 있는 말과 **받은 말을 둘 다** 낸다.
      *
      * 사람 말로 옮기는 표는 HTTP 상태코드가 있을 때만 쓸모가 있다. 닿지도
      * 못했을 때(status 0)가 오히려 원인이 또렷한 경우가 많다 — 봉인에 막힘 ·
      * 포트 닫힘 · 인증서 · 프록시. 그 한 줄을 버리면 화면에는 「연결 실패」
      * 네 글자만 남고, 정작 답이 적힌 문장을 우리가 지운 셈이 된다.
+     *
+     * 그래서 여태는 `if (까닭) … else if (found.why) …` 였는데, 그 else 가
+     * 거의 안 돌았다. 공통까닭() 은 401·403·404·429·402 에 전부 답이 있어서
+     * 표가 늘 먼저 이긴다. 그 바람에 detect.js 의 애저막힌말() 이 지은 세
+     * 줄(401·403·404)이 한 줄도 화면에 못 왔다 — 404 의 「주소에
+     * /openai/deployments/<배포이름> 까지 넣어 보세요」 까지 같이. 일반 문구는
+     * 「주소를 다시 보세요」 로 끝나는데, 정작 **어디를 어떻게** 고치는지는
+     * 덮인 쪽에만 적혀 있었다.
+     *
+     * 표는 고칠 갈래를 가르고(열쇠냐 주소냐 권한이냐), 받은 말은 그 갈래
+     * 안에서 어디를 고치는지 짚는다. 둘은 겹치는 말이 아니다. 같은 말이면
+     * 한 번만 낸다. 받은 말은 서버가 통째로 뱉은 본문일 수 있어 자른다 —
+     * 안 자르면 JSON 한 덩이가 화면을 밀어내고 「확인할 것」 이 안 보인다.
      */
-    if (까닭) { say(`    ${mark.warn} ${c.yellow(까닭)}`); say(''); }
-    else if (found.why) { say(`    ${mark.warn} ${c.yellow(found.why)}`); say(''); }
+    const 받은말 = String(found.why ?? '').trim();
+    if (까닭) say(`    ${mark.warn} ${c.yellow(까닭)}`);
+    if (받은말 && 받은말 !== 까닭) say(`    ${mark.warn} ${c.yellow(clip(받은말, 160))}`);
+    if (까닭 || 받은말) say('');
     say(`    시도한 주소:`);
     for (const t of found.tried) say(`      ${c.gray(주소가리기(t.includes('?') ? t : `${t}/models`))}`);
     say('');
@@ -113,6 +145,9 @@ async function chooseModel(found) {
  * **봉인은 진단에도 걸린다.** 여기가 빠져 있었다 — 관리자가 정책으로 밖을
  * 막아 둔 PC 에서도 `deel diagnose` 는 그냥 나갔다. 자물쇠가 명령 하나로
  * 열리면 자물쇠가 아니다. 사내망 주소는 봉인에서도 그대로 간다.
+ *
+ * 부르는 쪽 **셋 다** 이 말을 넘긴다 — 마법사(설정받기)·`deel diagnose`·`--url`.
+ * 한 곳이라도 안 넘기면 그 명령 하나가 자물쇠를 통째로 연다. 마법사가 그랬다.
  */
 export async function runProbe(conn, { out = null, 봉인 = false } = {}) {
   if (봉인 && 바깥인가(conn.base)) {
@@ -171,7 +206,7 @@ async function 붙일곳고르기() {
   let 제공자 = null;
   let 열쇠 = '';
   if (고른.id === '열쇠먼저') {
-    열쇠 = (await ask('API 키', { mask: true })).trim();
+    열쇠 = 열쇠다듬기(await ask('API 키', { mask: true }));
     if (!열쇠) { say(`  ${mark.no} 열쇠가 비었습니다.`); return null; }
     const 짚은것 = 어디것일까(열쇠);
     if (짚은것) {
@@ -228,6 +263,20 @@ async function 붙일곳고르기() {
     }
     const url = (await ask('주소 (Base URL)')).trim();
     if (!url) { say(`  ${mark.no} 주소가 비었습니다.`); return null; }
+    /*
+     * 틀린 주소는 **받은 자리에서** 알린다.
+     *
+     * `http://` · `https://` · `::1` · 빈칸 든 주소가 여기를 그냥 지나가, 열쇠를 묻고 이름을 묻고
+     * 붙어 볼 때에야 「Invalid URL」 이라는 날것의 말로 죽었다(`deel setup` 이 통째로 던졌다).
+     * 열쇠를 찾아 붙여넣은 수고가 버려진다. 스킴을 안 적은 `127.0.0.1:11434` 는 여태처럼 받는다 —
+     * 붙는 쪽(connect)이 스킴을 붙여 본다.
+     */
+    const 주소탈 = 주소꼴탈(url);
+    if (주소탈) {
+      say(`  ${mark.no} ${c.yellow('주소가 올바르지 않습니다:')} ${url}`);
+      say(`     ${c.gray(주소탈)}`);
+      return null;
+    }
     주소들 = [url];
   } else {
     say(`  ${c.gray('주소')} ${주소들.map((u) => 주소가리기(u)).join(c.gray('  ·  '))}`);
@@ -236,7 +285,7 @@ async function 붙일곳고르기() {
   // ── 열쇠 ─────────────────────────────────────────────────────────────
   if (!열쇠) {
     if (제공자.열쇠받는곳) say(`  ${c.gray('열쇠 받는 곳')} ${c.cyan(제공자.열쇠받는곳)}`);
-    열쇠 = (await ask('API 키', { mask: true })).trim();
+    열쇠 = 열쇠다듬기(await ask('API 키', { mask: true }));
   }
 
   const 기본이름 = 제공자.id === 'custom' ? '사내게이트웨이' : 제공자.이름;
@@ -244,12 +293,53 @@ async function 붙일곳고르기() {
   return { 제공자, 주소들, 열쇠, 이름 };
 }
 
-export async function runSetup() {
+/*
+ * ── 답할 사람이 없는데 목록 한가운데서 0 으로 끝났다 ────────────────────
+ *
+ * 표준입력이 닫힌 채(파이프 · CI · `deel setup < /dev/null`) 켜면 첫 물음에서
+ * 받을 글자가 영영 안 온다. 물음은 끝나지 않는 약속으로 남고, 이벤트 루프가
+ * 비면 Node 는 **그냥 0 으로** 나간다. 화면에는 「어디에 붙일까요? › 번호 [2]」
+ * 까지만 찍히고 설정은 없다. 스크립트는 설정이 된 줄 알고 다음 줄로 간다.
+ *
+ * reset.js 는 같은 자리에서 「물어볼 자리가 없습니다」 로 1 을 낸다. 여기도 그렇게
+ * 한다. 다만 **미리 막지는 않는다** — 답을 파이프로 흘려 넣어 setup 을 돌리는
+ * 쓰임이 있다. 답이 모자라서 입력이 끝났을 때만 멈춘다. 'end' 는 물음이 입력을
+ * 읽는 동안에만 날 수 있으므로(prompt.js 는 물음 사이에 입력을 멈춘다), 답을 다
+ * 받은 뒤 붙는 중에 끊기는 일은 없다.
+ */
+const 입력끝남 = Symbol('입력끝남');
+
+export async function runSetup(flags = {}) {
+  let 알리기 = null;
+  const 끝남 = new Promise((풀기) => { 알리기 = () => 풀기(입력끝남); });
+  const 표준입력 = process.stdin;
+  if (!표준입력.isTTY) 표준입력.once('end', 알리기);
+  try {
+    const r = await Promise.race([설정받기(flags), 끝남]);
+    if (r !== 입력끝남) return r;
+    say('');
+    say(`  ${mark.no} ${c.yellow('표준입력이 닫혀 답을 더 받을 수 없습니다.')} ${c.gray('아무것도 저장하지 않았습니다.')}`);
+    say(`     ${c.gray('터미널에서')} ${c.cyan('deel setup')} ${c.gray('을 다시 하거나, 이 PC 에 로컬 모델이 떠 있으면')} ${c.cyan('deel scan --save')}`);
+    say('');
+    return 1;
+  } finally {
+    표준입력.off('end', 알리기);
+  }
+}
+
+async function 설정받기(flags = {}) {
   banner();
   // 설정에 적어 둔 api-version 을 **붙기 전에** 읽는다. load() 가 애저정하기()를
   // 부른다. 이걸 뒤에서 하면 사내에서 판을 고정해 둔 곳이 확인만 GA판으로 하고,
   // 문서에 적어 둔 대로 안 도는 셈이 된다.
-  load();
+  const 첫설정 = load();
+  /*
+   * 모아 둔 소식을 여기서 비운다. `deel setup` 은 설정을 만지는 문인데
+   * 넷 중 하나도 안 비우고 있었다 — 열쇠를 방금 잠갔다는 말도, 이 폴더
+   * 설정을 안 읽었다는 말도, 관리 정책이 깨졌다는 말도 다 사라졌다.
+   * (config.js 의 소식줄들 머리말)
+   */
+  for (const 줄 of 소식줄들(첫설정)) say(줄);
   say(`  ${c.gray('모델 연결을 설정합니다.')}`);
   // 빈칸 0개짜리 길을 제일 먼저 알려 준다. 이 PC 에 이미 모델이 떠 있는데
   // 주소를 손으로 치게 만드는 것은 우리 잘못이다.
@@ -260,6 +350,33 @@ export async function runSetup() {
   const { 제공자: 붙일곳, 주소들, 열쇠: key, 이름: name } = 고른것;
 
   say('');
+  /*
+   * ── 봉인은 이 문에도 걸린다 ───────────────────────────────────────────
+   *
+   * 위 runProbe 머리말이 「봉인은 진단에도 걸린다 … 자물쇠가 명령 하나로 열리면
+   * 자물쇠가 아니다」 라고 적어 두고, 정작 이 문은 그 말을 한 번도 안 넘겼다.
+   * 관리 정책이나 설정에 offline 을 켜 둔 PC 에서도 `deel setup` 은 후보 주소를
+   * 그대로 두드렸다 — 방금 적어 넣은 열쇠까지 실려서. 두드리기 **전에** 거른다.
+   * 사내망 주소는 봉인에서도 그대로 간다. 스킴을 안 적은 주소는 connect() 가
+   * 붙이는 것과 같은 꼴로 재 준다 — 안 맞추면 `127.0.0.1:11434` 가 바깥으로 샌다.
+   */
+  // 깃발도 같이 본다. `--help` 는 `--offline` 을 「기억해 둔 허가까지 무시하고 막습니다」
+  // 라고 적는데, 여기가 `{ cfg }` 만 넘겨서 그 깃발이 조용히 버려졌다 — 설정·정책에
+  // 적어 둔 봉인만 걸리고, 사람이 그 자리에서 친 `deel setup --offline` 은 안 걸렸다.
+  // 깃발을 믿고 사내 게이트웨이 주소를 넣은 사람은 방금 적은 열쇠까지 실어 보낸 셈이 된다.
+  // (diagnose 는 같은 판에서 `깃발: flags.offline` 을 넘긴다 — 두 문이 갈려 있었다.)
+  const 봉인 = 봉인됐나({ 깃발: flags?.offline, prof: null, cfg: 첫설정 });
+  const 두드릴것 = 봉인
+    ? 주소들.filter((u) => !바깥인가(/^https?:\/\//i.test(u) ? u : `http://${u}`))
+    : 주소들;
+  if (봉인 && !두드릴것.length) {
+    say('');
+    say(`  ${mark.no} ${c.red('봉인되어 있어 이 주소는 안 두드립니다.')} ${c.gray(주소들.map((u) => 주소가리기(u)).join('  ·  '))}`);
+    say(`     ${c.gray('관리 정책이나 설정에 offline 이 켜져 있습니다. 사내망 주소는 그대로 됩니다.')}`);
+    say('');
+    return 1;
+  }
+
   /*
    * 후보를 앞에서부터 두드린다. 하나라도 붙으면 그것으로 간다.
    *
@@ -268,8 +385,8 @@ export async function runSetup() {
    * 물어보면 되는 것을 짐작으로 정하지 않는다.
    */
   let found = null;
-  for (const [n, url] of 주소들.entries()) {
-    const 마지막 = n === 주소들.length - 1;
+  for (const [n, url] of 두드릴것.entries()) {
+    const 마지막 = n === 두드릴것.length - 1;
     found = await connect(url, key, { 조용히: !마지막, 제공자: 붙일곳 });
     if (found) break;
   }
@@ -291,7 +408,9 @@ export async function runSetup() {
   }
 
   const conn = { kind: found.kind, base: found.base, auth: found.auth, key, model };
-  const { facts } = await runProbe(conn);
+  const { facts } = await runProbe(conn, { 봉인 });
+  // 봉인에 막혀 한 줄도 못 재 본 연결은 저장하지 않는다 — 안 재 본 값을 파일에 적는 셈이 된다.
+  if (!facts) return 1;
 
   /*
    * ── 「나가도 된다」 를 여기서 명시적으로 받는다 ───────────────────────
@@ -328,8 +447,14 @@ export async function runSetup() {
     // 어디 것인지 적어 둔다. 요금표 주소·열쇠 받는 곳처럼 「이 회사에만 해당되는
     // 안내」를 나중에 꺼내 쓸 때 이 한 칸이 없으면 주소를 보고 다시 짐작해야 한다.
     제공자: 붙일곳.id,
-    // 로컬·사내망이면 이 칸 자체가 없다. 있는 것만으로도 「바깥이다」 라는 뜻이라,
-    // 설정 파일을 열어 본 사람이 그것만 보고도 안다.
+    /*
+     * 이 칸은 **허락을 받았을 때만** 붙는다.
+     *
+     * 없다고 이 안이라는 뜻은 아니다 — 바깥 주소인데 사람이 「아니오」 를
+     * 고른 판도 없다. 바깥인지 아닌지는 언제나 **주소로** 가른다(바깥인가).
+     * 화면의 연결 목록도 그렇게 적는다(아래 `↗ 바깥 · 켤 때 물어봄`).
+     * 읽는 쪽은 전부 `online === true` 만 본다 — 없는 것과 false 는 같다.
+     */
     ...(나가도되나 ? { online: true } : {}),
     ctx: facts.ctx ?? null,
     streaming: facts.streaming ?? false,
@@ -362,6 +487,26 @@ export async function runDiagnose(flags) {
 
   if (flags.url) {
     쓴설정 = load();      // 설정의 api-version 을 먼저 읽는다 (runSetup 과 같은 이유)
+    /*
+     * 봉인은 **두드리기 전에** 본다.
+     *
+     * 아래 runProbe 도 봉인을 보지만 그건 붙은 뒤다 — 그때는 connect() 가
+     * 이미 그 주소로 나갔다(`/models` 를 후보마다 두드린다). 봉인을 켜 둔
+     * 사람이 「안 나갔겠지」 하는 동안 열쇠까지 실려 나간 셈이 된다. 설정에
+     * 없는 주소를 그 자리에서 치는 이 길이 오히려 제일 위험하다 —
+     * 아래 머리말이 그렇게 적어 두고도 정작 여기를 안 막고 있었다.
+     *
+     * 스킴을 안 적은 주소는 connect() 가 붙이는 것과 같은 꼴로 재 준다.
+     * 안 맞추면 `127.0.0.1:11434` 가 바깥으로 세어져 이 안까지 막힌다.
+     */
+    if (봉인됐나({ 깃발: flags.offline, prof: null, cfg: 쓴설정 })
+      && 바깥인가(/^https?:\/\//i.test(flags.url) ? flags.url : `http://${flags.url}`)) {
+      say('');
+      say(`  ${mark.no} ${c.red('봉인되어 있어 이 주소는 안 두드립니다.')} ${c.gray(주소가리기(flags.url))}`);
+      say(`     ${c.gray('관리 정책이나 설정에 offline 이 켜져 있습니다. 사내망 주소는 그대로 됩니다.')}`);
+      say('');
+      return 1;
+    }
     const key = flags.key ?? process.env.DEEL_API_KEY ?? '';
     const found = await connect(flags.url, key);
     if (!found) return 1;
@@ -398,8 +543,21 @@ export async function runDiagnose(flags) {
    * 봉인은 --url 로 주소를 직접 준 갈래에도 걸린다. 오히려 그쪽이 더 위험하다
    * — 설정에 없는 주소를 그 자리에서 두드리는 길이기 때문이다.
    */
-  await runProbe(conn, { out: flags.out ?? null, 봉인: 봉인됐나({ 깃발: flags.offline, prof: 쓴프로필, cfg: 쓴설정 }) });
-  return 0;
+  const { v, 봉인: 막혔나 } = await runProbe(conn, { out: flags.out ?? null, 봉인: 봉인됐나({ 깃발: flags.offline, prof: 쓴프로필, cfg: 쓴설정 }) });
+
+  /*
+   * ── 끝값은 판정을 그대로 옮긴다 ───────────────────────────────────────
+   *
+   * 여기가 무조건 `return 0` 이었다. 화면에는 빨간 「연결실패」 가 찍히는데 끝값은
+   * 0 이라, 사내에 넣기 전에 이 명령부터 돌리는 스크립트는 붙은 줄 알고 다음 줄로
+   * 갔다. 봉인에 막혀 **한 줄도 못 재 본** 판도 똑같이 0 이었다. 스크립트가 읽는
+   * 것은 화면 글이 아니라 이 숫자다 — 여기가 0 이면 진단을 돌린 뜻이 없다.
+   *
+   * 「돌아는 간다」(ready · limited)까지가 0 이다. blocked 는 도구 호출이 막힌
+   * 것이라 이 도구로 할 일 자체가 안 된다 — 사람에게는 실패로 알린다.
+   */
+  if (막혔나 || !v) return 1;
+  return v.level === 'ready' || v.level === 'limited' ? 0 : 1;
 }
 
 export async function showStatus() {

package/src/skills/discover.js

@@ -14,32 +14,74 @@ import { homedir } from 'node:os';
 import { homeDir } from '../config.js';
 import { pluginsDir } from '../plugins/manage.js';
 // 저장소에 딸려 온 스킬·명령이 시스템 글에 실리지 않게 한다 (discover 안구절 머리말).
-import { 믿나 } from '../safety/trust.js';
+import { 믿나, BOM떼기 } from '../safety/trust.js';
 
 // 이 파일 옆의 builtin/ — 패키지에 같이 실려 나간다(package.json files: src).
 export const 내장자리 = join(dirname(fileURLToPath(import.meta.url)), 'builtin');
 
 // --- YAML 앞머리 읽기 (name, description 만 쓰므로 최소만 구현) -------------
+/*
+ * ── 금은 **한 줄 통째로** `---` 여야 한다 (2.0.0 4회차 사냥) ───────────────
+ *
+ * 스킬·슬래시 명령·.md 에이전트(agent/agents.js)가 이 함수 하나를 같이 쓴다. 넷이 걸렸다.
+ *
+ *   · 닫는 금을 `\n---` 로 찾았다 — `---extra` · `----` 줄도 금이 됐다.
+ *   · 여는 금만 있고 안 닫힌 파일은 본문 뒤쪽의 `---`(마크다운 가로줄)까지를 앞머리로
+ *     읽어, 본문의 `name: hijack` 줄이 이름을 **덮었다.**
+ *   · 닫는 금이 파일 끝(줄바꿈 없음)이면 본문이 앞머리를 포함한 파일 전체가 됐다.
+ *   · BOM 이 붙으면 `---` 로 시작하지 않는 파일이 되어 이름·설명이 통째로 빠졌다
+ *     (파워셸 5.1 로 저장한 SKILL.md — safety/trust.js 의 BOM떼기).
+ *
+ * 그래서 줄 단위로 걷는다. 금은 `---` 뒤에 빈칸·CR 만 봐준다. 금을 만나기 전에 YAML 에
+ * 설 수 없는 줄(산문)이 나오면 앞머리가 안 닫힌 것으로 치고 **앞머리 없음**으로 돌려준다 —
+ * 본문을 앞머리로 읽는 것보다 앞머리를 잃는 쪽이 덜 나쁘다(이름은 폴더 이름으로 간다).
+ * 앞머리가 몇 백 줄일 까닭은 없어서 찾는 줄 수에도 상한을 둔다. 같은 열쇠가 두 번 오면
+ * 첫 것을 둔다 — 뒤엣것은 대개 본문이 새어 들어온 것이다.
+ */
+export const 앞머리최대줄 = 200;
+const 금인가 = (줄) => /^---[ \t]*\r?$/.test(줄);
+// YAML 앞머리에 설 수 있는 줄 꼴 — 빈 줄 · 들여 쓴 줄 · 주석 · 목록 · `열쇠:` 줄.
+const 앞머리줄인가 = (줄) => {
+  const l = 줄.replace(/\r$/, '');
+  // 콜론 뒤에는 빈칸이나 줄 끝이 와야 열쇠다. YAML 에서 `foo:bar` 는 매핑이 아니라
+  // 글자 하나다 — 그걸 열쇠로 받아 주면 `메모:여기서부터 본문입니다` 같은 산문 한 줄에
+  // 앞머리가 본문 뒤 가로줄까지 늘어나고, 그 사이의 `description:` 이 앞머리로 실린다.
+  return !l.trim() || /^\s/.test(l) || l.startsWith('#') || /^-(\s|$)/.test(l) || /^[^\s#][^:]*:(\s|$)/.test(l);
+};
+
 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 };
+  const 글 = BOM떼기(text);
+  const 없음 = { data: {}, body: 글 };
+  const 첫끝 = 글.indexOf('\n');
+  if (첫끝 < 0 || !금인가(글.slice(0, 첫끝))) return 없음;
+  const 머리 = [];
+  let 시작 = 첫끝 + 1;
+  for (let n = 0; n < 앞머리최대줄 && 시작 <= 글.length; n++) {
+    const 끝 = 글.indexOf('\n', 시작);
+    const 줄 = 끝 < 0 ? 글.slice(시작) : 글.slice(시작, 끝);
+    if (금인가(줄)) return { data: 머리펴기(머리), body: 끝 < 0 ? '' : 글.slice(끝 + 1) };
+    if (!앞머리줄인가(줄)) return 없음;
+    // CRLF 로 저장된 파일이 많다. \r 를 남겨 두면 정규식의 . 와 $ 가 그걸 줄 끝으로 보고
+    // 마지막 줄을 통째로 못 읽는다. 먼저 걷어낸다.
+    머리.push(줄.replace(/\r/g, ''));
+    if (끝 < 0) break;
+    시작 = 끝 + 1;
+  }
+  return 없음;
+}
 
-  // CRLF 로 저장된 파일이 많다. \r 를 남겨 두면 정규식의 . 와 $ 가 그걸 줄 끝으로 보고
-  // 마지막 줄을 통째로 못 읽는다. 먼저 걷어낸다.
-  const head = text.slice(nl + 1, end).replace(/\r/g, '');
-  const body = text.slice(text.indexOf('\n', end + 1) + 1);
+function 머리펴기(줄들) {
   const data = {};
   let key = null;
-  for (const line of head.split('\n')) {
+  for (const line of 줄들) {
     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; }
+    // 같은 열쇠는 첫 것을 둔다(위 머리말). `__proto__` 는 받지 않는다 — 담는 그릇의 틀이 바뀐다.
+    if (Object.hasOwn(data, m[1]) || m[1] === '__proto__') { key = null; continue; }
     key = m[1];
     let v = m[2].trim();
     // YAML 블록 표기( > >- | |- )는 값이 다음 줄부터 온다는 뜻이다. 표시만 지우고 비워 둔다.
@@ -47,7 +89,7 @@ export function frontmatter(text) {
     else if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
     data[key] = v;
   }
-  return { data, body };
+  return data;
 }
 
 const dirs = (p) => {
@@ -111,7 +153,8 @@ 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 {}
+    // BOM 을 뗀다 — 떼지 않으면 이름이 폴더 이름으로 바뀌어 `/플러그인:스킬` 이 다른 이름이 됐다(2.0.0 3회차).
+    try { info = JSON.parse(BOM떼기(readFileSync(manifest, 'utf8'))); } catch {}
   }
   const ns = info?.name || basename(rootDir);
   let found = 0;
@@ -144,7 +187,7 @@ function findPluginRoots(base, depth = 4) {
 
 function manifestName(rootDir) {
   const f = join(rootDir, '.claude-plugin', 'plugin.json');
-  try { return JSON.parse(readFileSync(f, 'utf8')).name || basename(rootDir); }
+  try { return JSON.parse(BOM떼기(readFileSync(f, 'utf8'))).name || basename(rootDir); }
   catch { return basename(rootDir); }
 }
 
@@ -267,12 +310,50 @@ export function discover(root, opts = {}) {
     try { return readdirSync(p).length > 0; } catch (e) { return e?.code !== 'ENOENT'; }
   });
 
+  /*
+   * ── 다만 안 믿는 폴더의 명령은 **내 명령을 덮지 못한다** (2.0.0 4회차 사냥) ──
+   *
+   * 명령을 그냥 두는 까닭은 「사람이 `/이름` 을 직접 칠 때만 펴진다」 였다. 그런데 사람이
+   * `/review` 를 칠 때 떠올리는 것은 **제가 만든** review 다. 저장소에 같은 이름(대소문자만
+   * 달라도 — commands.js 는 대소문자를 안 가리고 찾는다)을 넣어 두면 dedupe 가 가까운 쪽을
+   * 이기게 해서, 사람은 제 명령을 친 줄 알고 남이 적은 본문을 모델에게 보냈다.
+   *
+   * 그래서 안 믿는 폴더에서는 이미 있는 이름(사용자·플러그인 것, 플러그인은 `:` 뒤 꼬리도)과
+   * 겹치는 저장소 명령을 **빼고**, 뺀 이름을 `안믿은명령` 으로 돌려준다. 안 겹치는 것은
+   * 여전히 그대로 된다 — 위 「명령은 왜 그냥 두나」 의 판단은 그대로다. 집에서 켰으면
+   * 프로젝트 자리가 곧 사용자 자리라 건너뛴다(같은 파일을 「못 덮었다」 고 말하게 된다).
+   */
+  const 안믿은명령 = [];
+  let 있던이름 = null;
+
   // 2) 사용자  3) 프로젝트
   for (const [base, source] of [[home, 'user'], [root, 'project']]) {
     for (const cfgDir of ['.deel', '.claude']) {
       if (source !== 'project' || 믿는가) {
         skillsIn(join(base, cfgDir, 'skills'), source, null, skills, caps.skills);
       }
+      if (source === 'project' && !믿는가) {
+        if (같은자리(root, home)) continue;
+        있던이름 ??= new Set(commands.flatMap((x) => [x.name.toLowerCase(), x.name.split(':').pop().toLowerCase()]));
+        const 저장소것 = [];
+        commandsIn(join(base, cfgDir, 'commands'), source, null, 저장소것, caps.commands);
+        for (const x of 저장소것) {
+          // 겹침을 **먼저** 본다. 상한을 먼저 보면 상한에 닿는 순간 겹친 이름이
+          // 안믿은명령 에서 빠지고, 화면(repl.js)은 그 목록으로만 말하므로 사람은
+          // 제 명령이 가려졌다는 것도 모른 채 저장소 명령이 안 도는 것만 본다.
+          if (있던이름.has(x.name.toLowerCase())) { 안믿은명령.push(x.name); continue; }
+          /*
+           * 여기가 `break` 였다 (8회차 판정). 차례는 맞게 뒀는데 상한에 닿는
+           * 순간 고리를 통째로 나가서, **그 뒤의 저장소 명령은 겹침 검사를 아예
+           * 못 받았다.** 위 주석이 막으려던 바로 그 실패가 상한 뒤에서 그대로
+           * 일어난다 — 재 보니 상한 뒤에 있던 겹친 이름이 안믿은명령 에서 빠졌다.
+           * `continue` 면 더 넣지는 않으면서 겹침은 끝까지 센다.
+           */
+          if (commands.length >= caps.commands) continue;
+          commands.push(x);
+        }
+        continue;
+      }
       commandsIn(join(base, cfgDir, 'commands'), source, null, commands, caps.commands);
     }
   }
@@ -283,13 +364,22 @@ export function discover(root, opts = {}) {
     plugins,
     // 파일은 있는데 폴더를 안 믿어서 안 읽은 경우. 화면이 이걸 말해야 한다.
     안믿음: !믿는가 && 프로젝트것있음,
+    // 안 믿는 폴더의 명령 중 내 명령과 이름이 겹쳐 뺀 것. 화면이 이것도 말한다.
+    안믿은명령,
   };
 }
 
-// 같은 이름이면 나중 것(더 가까운 자리)이 이긴다.
+/*
+ * 같은 이름이면 나중 것(더 가까운 자리)이 이긴다.
+ *
+ * 대소문자만 다른 것도 **같은 이름**이다. 여태 x.name 그대로 열쇠를 삼아,
+ * `review`(집)와 `Review`(저장소)가 둘 다 살아남았다 — 겹침을 재는 바로 윗자리는
+ * 처음부터 toLowerCase() 였고, 윈도·맥에서는 파일 이름부터 같은 것이라 사람은
+ * 둘이 있는 줄도 모른다. 이름 글자는 나중 것의 것을 그대로 쓴다.
+ */
 function dedupe(list) {
   const m = new Map();
-  for (const x of list) m.set(x.name, x);
+  for (const x of list) m.set(x.name.toLowerCase(), x);
   return [...m.values()];
 }
 
@@ -311,9 +401,22 @@ export function loadCommand(cmd, args = '') {
   let text;
   try { text = readFileSync(cmd.path, 'utf8'); } catch (err) { return { error: err.message }; }
   const { body } = frontmatter(text);
+  /*
+   * **한 번에**, **함수로** 바꾼다 (2.0.0 4회차 사냥).
+   *
+   * 글자로 바꾸면 replace 가 준 말 안의 `$'` · `$&` · `` $` `` · `$$` 를 무늬로 풀었다 —
+   * `price is $'` 가 본문 뒤쪽을 통째로 끌어왔다. 그리고 두 번에 나눠 바꾸면 첫 번에 넣은
+   * 사람 말 안의 `$1` 을 둘째 번이 또 바꿨다. 자리 표시(`$1`·`$2`)는 Claude Code 명령 규격
+   * 그대로 두되, 채우는 값은 **사람이 준 말에서만** 온다.
+   *
+   * 자리는 `$1`…`$9` 뿐이다 (SK4 · 8회차). `\d` 로 받던 때는 `$0` 도 자리로 읽혀
+   * `조각[-1]` → 빈 글자가 되었다 — 명령 본문에 적어 둔 `basename $0` 의 `$0` 이
+   * 소리 없이 지워졌다. `$10` 은 열째 인자가 아니라 `$1` 뒤에 글자 `0` 이다.
+   * `\d+` 로 넓히지 않는 이유: `$1` 뒤에 숫자를 적어 둔 기존 명령이 조용히 뜻이 바뀐다.
+   */
+  const 인자 = String(args ?? '');
+  const 조각 = 인자.trim() ? 인자.trim().split(/\s+/) : [];
   return {
-    text: body
-      .replace(/\$ARGUMENTS/g, args)
-      .replace(/\$(\d)/g, (_, n) => args.split(/\s+/)[Number(n) - 1] ?? ''),
+    text: body.replace(/\$ARGUMENTS|\$([1-9])/g, (_, n) => (n === undefined ? 인자 : (조각[Number(n) - 1] ?? ''))),
   };
 }

package/src/stats.js

@@ -33,6 +33,23 @@ export function 기록자리(root = process.cwd()) {
   return join(root, '.deel', 'audit.jsonl');
 }
 
+/** 하루. 이 PC 와 기록을 적은 PC 의 시계가 조금 어긋나는 것까지는 받는다. */
+const 시계어긋남 = 86400000;
+
+/**
+ * 감사기록의 시각이 우리가 적은 꼴인가. 맞으면 견줄 수 있게 ISO 글자로, 아니면 null.
+ *
+ * 글자가 아니면(숫자·없음) 버린다. `Date.parse` 는 `"5"` 도 날짜로 읽으므로 앞머리가
+ * `YYYY-MM-DDT` 인지도 본다. **이제보다 하루 넘게 뒤**인 것도 버린다 — 9999년 한 줄이
+ * 「마지막으로 쓴 날」 을 영영 차지한다.
+ */
+function 성한시각(값, 이제) {
+  if (typeof 값 !== 'string' || !/^\d{4}-\d{2}-\d{2}T/.test(값)) return null;
+  const t = Date.parse(값);
+  if (!Number.isFinite(t) || t > 이제.getTime() + 시계어긋남) return null;
+  return new Date(t).toISOString();
+}
+
 /**
  * 감사기록을 읽어 센다.
  *
@@ -71,7 +88,9 @@ export function 세기(자리, { 날수 = 30, 이제 = new Date() } = {}) {
     대화: 0,
     도구: 0,
     도구실패: 0,
-    도구별: new Map(),    // 이름 → { 수, 실패 }
+    // 됐는지 **모르는** 것. 성공에도 실패에도 안 넣는다 (아래 tool 갈래).
+    도구모름: 0,
+    도구별: new Map(),    // 이름 → { 수, 실패, 모름 }
     막힘: 0,
     막힌까닭: new Map(),  // 까닭 → 수
     되돌림: 0,
@@ -83,33 +102,54 @@ export function 세기(자리, { 날수 = 30, 이제 = new Date() } = {}) {
     셈.줄 += 1;
     let r;
     try { r = JSON.parse(줄); } catch { 셈.깨진줄 += 1; continue; }
-    if (!r || typeof r !== 'object') { 셈.깨진줄 += 1; continue; }
-    const at = typeof r.at === 'string' ? r.at : null;
-    if (자름 && at && at < 자름) { 셈.지난줄 += 1; continue; }
+    if (!r || typeof r !== 'object' || Array.isArray(r)) { 셈.깨진줄 += 1; continue; }
+    /*
+     * ── 우리가 적은 꼴이 아닌 줄은 못 읽은 줄이다 ──────────────────────
+     *
+     * 시각이 없는 줄은 기간 자르기(`at && at < 자름`)를 그냥 지나 「최근 30일」
+     * 안으로 들어왔고, 숫자 시각도 그랬고, 9999년 줄은 「마지막」 을 9999-12-31
+     * 로 만들었다. 도구 이름이 객체면 「[object Object]」 라는 도구로 셌고, 이름이
+     * 아예 없으면 「?」 라는 도구를 지어내 그 이름으로 셌다.
+     * 감사기록(safety/audit.js)은 언제나 ISO 시각 글자와 도구 이름 글자를 적는다.
+     * 그 꼴이 아니면 손으로 고쳤거나 다른 것이 섞인 줄이다 — 셈에 넣으면 숫자가
+     * 조용히 틀리고, 버리기만 하면 몇 줄을 못 읽었는지가 사라진다. 그래서 센다.
+     */
+    const at = 성한시각(r.at, 이제);
+    if (!at) { 셈.깨진줄 += 1; continue; }
+    // 도구 이름은 **있어야** 한다. 없는 줄을 `?` 라는 도구로 세면 쓴 적 없는 도구가 화면에 생긴다.
+    if (r.kind === 'tool' && (typeof r.tool !== 'string' || !r.tool)) { 셈.깨진줄 += 1; continue; }
+    if (자름 && at < 자름) { 셈.지난줄 += 1; continue; }
 
-    if (at) {
-      if (!셈.처음 || at < 셈.처음) 셈.처음 = at;
-      if (!셈.마지막 || at > 셈.마지막) 셈.마지막 = at;
-      셈.날.add(at.slice(0, 10));
-    }
-    if (r.session) 셈.세션.add(String(r.session));
+    if (!셈.처음 || at < 셈.처음) 셈.처음 = at;
+    if (!셈.마지막 || at > 셈.마지막) 셈.마지막 = at;
+    셈.날.add(at.slice(0, 10));
+    if (typeof r.session === 'string' && r.session) 셈.세션.add(r.session);
 
     switch (r.kind) {
       case 'turn': 셈.대화 += 1; break;
       case 'tool': {
         셈.도구 += 1;
-        const 이름 = String(r.tool ?? '?');
-        const 것 = 셈.도구별.get(이름) ?? { 수: 0, 실패: 0 };
+        const 이름 = r.tool;   // 위에서 빈 이름을 이미 걸렀다 — 여기서 지어내지 않는다
+        const 것 = 셈.도구별.get(이름) ?? { 수: 0, 실패: 0, 모름: 0 };
         것.수 += 1;
-        // ok 가 아예 없는 옛 줄은 성공으로 안 친다 — 모르는 것을 좋은 쪽으로
-        // 세면 실패율이 늘 실제보다 낮게 나온다.
+        /*
+         * ok 가 없는 줄은 **모른다.** 성공도 실패도 아니다.
+         *
+         * 바로 위 주석이 「모르는 것을 좋은 쪽으로 세면 실패율이 늘 실제보다
+         * 낮게 나온다」 라고 적어 두고, 정작 `ok === false` 만 세어서 ok 없는
+         * 줄이 분모에만 들어갔다 — 그게 곧 성공으로 세는 것이다. 감사기록은
+         * 언제나 ok 를 적으므로(safety/audit.js), 없는 줄은 옛 기록이거나 손으로
+         * 고친 줄이다. 실패로 미는 것도 지어내는 것이라 **따로 세어 말한다.**
+         */
         if (r.ok === false) { 것.실패 += 1; 셈.도구실패 += 1; }
+        else if (r.ok !== true) { 것.모름 += 1; 셈.도구모름 += 1; }
         셈.도구별.set(이름, 것);
         break;
       }
       case 'blocked': {
         셈.막힘 += 1;
-        const 왜 = String(r.why ?? '(까닭 없음)');
+        // 글자가 아닌 까닭은 「[object Object]」 로 모이지 않게 없는 것으로 친다.
+        const 왜 = typeof r.why === 'string' && r.why ? r.why : '(까닭 없음)';
         셈.막힌까닭.set(왜, (셈.막힌까닭.get(왜) ?? 0) + 1);
         break;
       }
@@ -153,7 +193,8 @@ export function 셈JSON(셈) {
     turns: 셈.대화,
     tools: 셈.도구,
     toolFailures: 셈.도구실패,
-    byTool: 도구차례(셈, 100).map((x) => ({ name: x.이름, calls: x.수, failures: x.실패 })),
+    toolUnknown: 셈.도구모름,
+    byTool: 도구차례(셈, 100).map((x) => ({ name: x.이름, calls: x.수, failures: x.실패, unknown: x.모름 })),
     blocked: 셈.막힘,
     blockedBy: 막힘차례(셈, 100).map((x) => ({ why: x.왜, count: x.수 })),
     undos: 셈.되돌림,