z2o-cli 0.4.0

package/README.md

@@ -0,0 +1,61 @@
+# z2o
+
+회사 온톨로지를 **내가 쓰는 AI에서 꺼내 쓴다.** Z2O 웹을 안 열어도 된다.
+
+```bash
+npm i -g z2o-cli
+z2o init z2o_live_...       # 설정 → 「팀 · 연결」에서 발급한 열쇠
+```
+
+`init` 이 세 가지를 한 번에 한다 — **로그인 · 워크스페이스 지정 · AI 규칙 파일에 사용법 심기.**
+
+마지막이 핵심이다: 명령어를 깔아 둬도 **AI 는 그게 있는 줄 모른다.** 규칙 파일에 한 번
+적어 두면 그다음부터 알아서 쓴다. 여러 번 돌려도 블록은 하나만 남고 기존 내용은 안 건드린다.
+
+이미 있는 `CLAUDE.md` · `AGENTS.md` · `GEMINI.md` 에 전부 심고, 하나도 없으면
+`AGENTS.md` 와 `CLAUDE.md` 를 만든다. 다른 도구를 쓰면 **그 도구의 규칙 파일을 만들어 두고
+`z2o init` 을 다시 돌리면** 된다.
+
+**폴더마다 하기 싫으면 `z2o init -g`** — `~/.claude/CLAUDE.md` 처럼 도구의 전역 자리에
+심어 **모든 폴더에서** 통하게 한다. (깔린 도구의 자리에만 심는다.)
+
+⚠️ 규칙 파일은 **편의**일 뿐이다. 없어도 CLI 는 셸을 쓸 수 있는 AI 라면 어디서든 돌아간다 —
+한 번 "z2o 로 찾아봐" 라고 말해 주면 그만이다.
+
+```bash
+z2o recent                  # 최근 들어온 슬랙·메일
+z2o find 계약               # 원본에서 찾기
+```
+
+Claude Code·Cursor·Codex 등 **셸을 쓸 수 있는 AI라면 무엇에서든** 된다.
+MCP 와 달리 앱마다 연동 설정이 필요 없고, 토큰이 만료되지 않아 한 번 연결해 두면 계속 이어진다.
+
+## 명령
+
+| | |
+|---|---|
+| `z2o init [토큰]` | 한 번에 붙이기 — 로그인 + 워크스페이스 + AI 규칙 파일 |
+| `z2o init -g` | 규칙을 **모든 폴더**에 (`~/.claude` 등). 폴더마다 안 해도 된다 |
+| `z2o login <토큰>` | 토큰만 저장 (`~/.z2o/config.json`, 0600) |
+| `z2o whoami` | 지금 누구로 붙어 있나 |
+| `z2o companies` | 워크스페이스 목록 |
+| `z2o use <id 또는 이름>` | 기본 워크스페이스 |
+| `z2o list [접두어]` | 문서 목록 (`docs/`·`ledger/` 처럼 걸러서) |
+| `z2o search <낱말>` | 본문 검색 |
+| `z2o read <경로...>` | 문서 본문 |
+| `z2o graph` | 문서가 서로 어떻게 이어져 있는지 |
+| `z2o recent [개수]` | **정리 전 원본** — 슬랙·메일이 들어온 그대로 |
+| `z2o find <낱말>` | 원본에서 찾기 |
+| `z2o raw <id...>` | 원본 본문 |
+| `z2o push <제목> <파일\|-\>` | 자료 넣기 — **쓰기 토큰 필요** |
+| `z2o organize` | 정리 돌리기 — **쓰기 토큰 필요** |
+
+`-c <id>` 로 워크스페이스를 그때만 바꿀 수 있다.
+
+## 환경 변수
+
+| | |
+|---|---|
+| `Z2O_API` | 서버 주소 (기본 `https://z2o.kr/_/backend`) |
+| `Z2O_TOKEN` | 토큰. 설정 파일보다 우선 — CI 에서 쓴다 |
+| `Z2O_COMPANY` | 워크스페이스 id |

package/index.js

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+/**
+ * z2o — 회사 온톨로지를 내가 쓰는 AI에서 꺼내 쓰는 명령어.
+ *
+ * 🔑 **속은 MCP 엔드포인트 하나를 부른다. REST 를 따로 안 부른다.**
+ *
+ *    MCP 응답은 이미 **사람 말**이다(`- docs/a.md — 물류 회의 (3,761자)`). 읽는 쪽이
+ *    LLM 이라 그렇게 만들어 뒀는데, 터미널에 그대로 찍어도 읽기 좋은 글이다. REST 를
+ *    부르면 JSON 을 여기서 다시 사람 말로 옮겨야 하고, **그 순간 MCP 와 CLI 의 말이
+ *    갈라지기 시작한다.** 한 곳에서 나오게 두면 영영 안 갈라진다.
+ *
+ * 🔑 **의존성이 없다.** node 18 부터 `fetch` 가 내장이라 설치가 `npm i -g z2o` 하나로 끝난다.
+ *    MCP 의 진입장벽(앱마다 JSON 설정을 손으로 고치는 것)을 없애려고 만든 것이므로,
+ *    이쪽 설치가 무거우면 만든 이유가 없어진다.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DEFAULT_API = 'https://z2o.kr/_/backend';
+// 발급되는 토큰의 모양. `z2o_live_` + base64url.
+//
+// ⚠️ **보내기 전에 여기서 막는다.** `fetch` 는 헤더에 ASCII 밖 글자가 있으면
+//    "Cannot convert argument to a ByteString…" 같은 말로 죽는데, 사람은 그게
+//    토큰 탓인 줄 모른다. 터미널에 붙여 넣다 보면 스마트 따옴표나 줄바꿈이
+//    딸려 오는 일이 실제로 있다.
+const TOKEN_RE = /^z2o_live_[A-Za-z0-9_-]+$/;
+const CONF_DIR = join(homedir(), '.z2o');
+const CONF_PATH = join(CONF_DIR, 'config.json');
+// 명령어 이름이 한 번 `ztoo` 였다(2026-09-10). **그때 로그인한 사람이 안 끊기게**
+// 옛 자리도 읽는다 — 저장은 언제나 새 자리로 하므로 한 번 쓰면 저절로 옮겨진다.
+const OLD_CONF_PATH = join(homedir(), '.ztoo', 'config.json');
+
+// ── 설정 ────────────────────────────────────────────────
+
+function loadConf() {
+  for (const p of [CONF_PATH, OLD_CONF_PATH]) {
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      /* 다음 자리 */
+    }
+  }
+  return {};
+}
+
+function saveConf(conf) {
+  mkdirSync(CONF_DIR, { recursive: true });
+  writeFileSync(CONF_PATH, JSON.stringify(conf, null, 2) + '\n');
+  // ⚠️ **남이 못 읽게 한다.** 토큰이 평문으로 있는 파일이고, 홈 디렉터리는 기본이
+  //    0755 라 같은 기기의 다른 계정에서 읽힌다.
+  try {
+    chmodSync(CONF_PATH, 0o600);
+  } catch {
+    /* 윈도우 등 권한 모델이 다른 곳 — 저장 자체를 막지는 않는다 */
+  }
+}
+
+/** 환경 변수가 설정 파일을 이긴다 — CI 나 일회성 실행에서 갈아끼울 수 있게. */
+function settings() {
+  const conf = loadConf();
+  return {
+    api: (process.env.Z2O_API || conf.api || DEFAULT_API).replace(/\/+$/, ''),
+    token: process.env.Z2O_TOKEN || conf.token || '',
+    companyId: process.env.Z2O_COMPANY || conf.companyId || '',
+    conf,
+  };
+}
+
+// ── 서버 부르기 ──────────────────────────────────────────
+
+function die(msg, code = 1) {
+  process.stderr.write(msg.replace(/\n?$/, '\n'));
+  process.exit(code);
+}
+
+async function rpc(method, params, { token: override } = {}) {
+  const { api, token: saved } = settings();
+  // `login` 은 **아직 저장하지 않은** 토큰으로 확인해야 한다 — 그래서 넘겨받는 길을 둔다.
+  const token = override || saved;
+  if (!token) {
+    die('연결된 토큰이 없어요.\n  z2o.kr → 오른쪽 위 프로필 → 「연결 토큰」에서 발급한 뒤 `z2o init <토큰>` 하세요.');
+  }
+
+  if (token && !TOKEN_RE.test(token)) {
+    die('토큰에 이상한 글자가 섞여 있어요. 따옴표나 줄바꿈이 딸려 오지 않았는지 확인해 주세요.');
+  }
+
+  let res;
+  try {
+    res = await fetch(`${api}/api/mcp`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+    });
+  } catch (e) {
+    die(`서버에 닿지 못했어요 (${api}).\n  ${e.message}`);
+  }
+
+  if (res.status === 401) die('토큰이 유효하지 않거나 끊겼어요. `z2o login <토큰>` 으로 다시 연결해 주세요.');
+  if (res.status === 403) {
+    // 읽기 전용 토큰으로 쓰기를 시도한 경우. 서버 문구를 그대로 전한다.
+    let detail = '';
+    try {
+      detail = (await res.json())?.detail || '';
+    } catch { /* 본문이 JSON 이 아닐 수 있다 */ }
+    die(detail || '이 토큰으로는 할 수 없는 일이에요. 쓰기 토큰이 필요합니다.');
+  }
+  if (!res.ok) die(`서버가 ${res.status} 로 답했어요.`);
+
+  const body = await res.json();
+  if (body.error) die(`요청이 거절됐어요: ${body.error.message || body.error.code}`);
+  return body.result || {};
+}
+
+/** 도구 하나를 부르고 **글만** 돌려준다. MCP 응답은 이미 사람 말이라 손대지 않는다. */
+async function callTool(name, args, opts) {
+  const result = await rpc('tools/call', { name, arguments: args }, opts);
+  const text = (result.content || [])
+    .filter((b) => b.type === 'text')
+    .map((b) => b.text)
+    .join('\n');
+  // 🔑 **도구가 「안 됐다」고 답한 것도 종료 코드로 옮긴다.** 셸에서 `&&` 로 이어
+  //    쓰는 사람이 성공/실패를 알아야 한다 — 글만 보고는 스크립트가 못 가린다.
+  if (result.isError) die(text || '요청을 처리하지 못했어요.');
+  return text;
+}
+
+/** 회사 id 를 정한다. `-c` > 환경변수 > 설정 파일 순. */
+function needCompany(flags) {
+  const id = flags.c || settings().companyId;
+  if (!id) {
+    die('워크스페이스를 안 정했어요.\n  `z2o companies` 로 목록을 보고 `z2o use <id>` 하세요.');
+  }
+  return id;
+}
+
+// ── AI 에게 알려주기 ─────────────────────────────────────
+//
+// 🔑 **이게 `init` 의 핵심이다.** 명령어를 깔아 둬도 **AI 는 그게 있는 줄 모른다.**
+//    사람이 매번 "z2o 라는 게 있어" 라고 말해줘야 하는데, 규칙 파일에 한 번 적어 두면
+//    그다음부터는 알아서 쓴다. 설치와 로그인만으로는 다리가 안 이어진다.
+
+// 🌍 **도구마다 「모든 폴더에 적용되는」 규칙 파일 자리가 따로 있다.**
+//    여기 한 번 심으면 폴더마다 `init` 을 돌릴 필요가 없다.
+const GLOBAL_RULES = [
+  ['.claude', 'CLAUDE.md'],
+  ['.codex', 'AGENTS.md'],
+  ['.gemini', 'GEMINI.md'],
+];
+
+const MARK_START = '<!-- z2o:start -->';
+const MARK_END = '<!-- z2o:end -->';
+// ⚠️ **옛 이름으로 심어 둔 블록도 알아봐야 한다.** 못 알아보면 갈아끼우지 못하고
+//    **같은 내용이 두 벌** 남는다.
+const OLD_MARKS = [['<!-- ztoo:start -->', '<!-- ztoo:end -->']];
+
+const BLOCK = `${MARK_START}
+## 회사 맥락 (z2o)
+
+슬랙·회의록·위키를 \`z2o\` 명령으로 꺼낸다. **사람에게 복사해 달라고 하지 않는다.**
+
+| 정리 전 원본 | |
+|---|---|
+| \`z2o recent\` | 최근 들어온 것 (슬랙·메일) |
+| \`z2o find <낱말>\` | 원본에서 찾기 |
+| \`z2o raw <id>\` | 원본 본문 |
+
+| 정리된 위키 | |
+|---|---|
+| \`z2o search <낱말>\` | 본문 검색 |
+| \`z2o read <경로>\` | 문서 본문 |
+| \`z2o list [접두어]\` | 문서 목록 |
+
+**정리를 부탁받으면 내가 한다** — Z2O 의 AI 에게 맡기지 않는다.
+
+| | |
+|---|---|
+| \`z2o push <제목> <파일>\` | 원본 넣기. 장부·표는 코드가 알아서 만든다 |
+| \`z2o pending\` | 요약이 필요한 원본 |
+| \`z2o write <경로> <파일>\` | 관련 문서를 읽고 고쳐 쓴 요약을 남긴다 |
+
+자세한 것은 \`z2o --help\`.
+${MARK_END}`;
+
+/** 규칙 파일에 블록을 심는다. **두 번 해도 하나만 남는다.** */
+function writeRules(file) {
+  const had = existsSync(file);
+  const before = had ? readFileSync(file, 'utf8') : '';
+  let [ms, me] = [MARK_START, MARK_END];
+  if (before.indexOf(ms) < 0) {
+    const hit = OLD_MARKS.find(([a, b]) => before.indexOf(a) >= 0 && before.indexOf(b) > before.indexOf(a));
+    if (hit) [ms, me] = hit;
+  }
+  const i = before.indexOf(ms);
+  const j = before.indexOf(me);
+  let after;
+  if (i >= 0 && j > i) {
+    // 이미 있으면 **갈아끼운다** — 규격이 바뀌어도 따라온다.
+    after = before.slice(0, i) + BLOCK + before.slice(j + me.length);
+    if (after === before) return { file, state: '그대로' };
+    writeFileSync(file, after);
+    return { file, state: '갱신' };
+  }
+  after = before.trimEnd() + (before.trim() ? '\n\n' : '') + BLOCK + '\n';
+  writeFileSync(file, after);
+  return { file, state: had ? '추가' : '새로 만듦' };
+}
+
+// ── 인자 파싱 ────────────────────────────────────────────
+// 의존성을 안 두기로 했으므로 직접 읽는다. 필요한 건 `-c <id>` 하나뿐이다.
+
+function parseArgs(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-c' || a === '--company') flags.c = argv[++i];
+    else if (a === '-g' || a === '--global') flags.global = true;
+    else if (a === '-h' || a === '--help') flags.help = true;
+    else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+const HELP = `z2o — 회사 온톨로지를 내가 쓰는 AI에서 꺼내 쓴다
+
+  z2o init [토큰]             한 번에 붙이기 — 로그인 + 워크스페이스 + AI 규칙파일
+  z2o init -g                 규칙을 **모든 폴더**에 (~/.claude 등). 폴더마다 안 해도 됨
+  z2o login <토큰>            토큰만 저장
+  z2o logout                  저장한 토큰 지우기
+  z2o whoami                  지금 어떻게 붙어 있나
+
+  z2o companies               워크스페이스 목록
+  z2o use <id 또는 이름>       기본 워크스페이스 정하기
+
+  ── 정리된 문서 ──
+  z2o list [접두어]            문서 목록 (예: z2o list ledger/)
+  z2o search <낱말>            본문 검색
+  z2o read <경로...>           문서 본문
+  z2o graph                   문서가 서로 어떻게 이어져 있는지
+
+  ── 정리 전 원본 ──  슬랙·메일이 들어온 그대로
+  z2o recent [개수]            최근 들어온 원본
+  z2o find <낱말>              원본에서 찾기
+  z2o raw <id...>              원본 본문 (id 는 recent·find 가 준 것)
+
+  ── 정리를 내 AI 가 한다 ──  (쓰기 토큰 필요)
+  z2o push <제목> <파일|->     원본 넣기 — 장부·표는 코드가 알아서 만든다
+  z2o pending                 요약이 필요한 원본
+  z2o write <경로> <파일|->    요약을 위키에 남기기 (예: topics/물류.md)
+  z2o organize                Z2O 의 AI 에게 정리를 맡긴다 (직접 안 쓸 때)
+
+  -c, --company <id>          이번만 다른 워크스페이스로
+  -g, --global                init 을 모든 폴더에 적용
+
+환경 변수: Z2O_API · Z2O_TOKEN · Z2O_COMPANY (설정 파일보다 우선)`;
+
+// ── 명령 ────────────────────────────────────────────────
+
+const COMMANDS = {
+  async login([token]) {
+    if (!token) die('토큰을 함께 적어 주세요.\n  z2o login z2o_live_...');
+    if (!TOKEN_RE.test(token)) {
+      die('토큰 모양이 아니에요. `z2o_live_` 로 시작하는 한 줄이어야 합니다.');
+    }
+    // 🔑 **저장하기 전에 한 번 써 본다.** 틀린 토큰을 저장해 두면 나중에 엉뚱한
+    // 명령에서 실패하고, 사람은 그게 토큰 탓인 줄 모른다. 확인에 실패하면
+    // `callTool` 이 여기서 끝내므로 **잘못된 토큰이 파일에 남지 않는다.**
+    const text = await callTool('list_companies', {}, { token });
+    saveConf({ ...loadConf(), token });
+    console.log('연결했어요.\n');
+    console.log(text);
+    if (!settings().companyId) console.log('\n`z2o use <id>` 로 기본 워크스페이스를 정해 두세요.');
+  },
+
+  /** 한 번에 다 붙인다 — 설치 뒤 이것만 하면 된다.
+   *
+   * 🔑 **로그인만으로는 부족하다.** AI 가 `z2o` 의 존재를 모르기 때문에, 사람이 매번
+   *    "z2o 라는 게 있어" 라고 말해줘야 한다. 규칙 파일에 적어 두는 것까지가 연결이다.
+   */
+  async init(args, flags) {
+    const [token] = args;
+    const { token: saved } = settings();
+
+    // ① 로그인 — 토큰을 줬으면 그걸로, 이미 붙어 있으면 그대로.
+    if (token) {
+      await COMMANDS.login([token]);
+    } else if (!saved) {
+      die(
+        '먼저 열쇠가 필요해요.\n' +
+          '  1. https://z2o.kr 로그인 → 오른쪽 위 프로필 → 「연결 토큰」 → 발급\n' +
+          '  2. z2o init <발급받은 열쇠>',
+      );
+    } else {
+      console.log('이미 연결돼 있어요.\n');
+    }
+
+    // ② 워크스페이스 — 하나뿐이면 묻지 않고 정한다.
+    let needPick = false;
+    if (!settings().companyId) {
+      const rows = (await callTool('list_companies', {}))
+        .split('\n')
+        .map((l) => l.match(/^- (\S+) — (.+?)(?: \(초대받음.*\))?$/))
+        .filter(Boolean);
+      if (rows.length === 1) {
+        saveConf({ ...loadConf(), companyId: rows[0][1] });
+        console.log(`워크스페이스: ${rows[0][2]}`);
+      } else if (rows.length > 1) {
+        // ⚠️ **여럿이면 고르지 않는다.** 엉뚱한 회사에 자료를 넣게 되는 쪽이 훨씬 나쁘다.
+        needPick = true;
+        console.log('워크스페이스가 여럿이에요. 하나 고르세요:\n');
+        for (const r of rows) console.log(`  ${r[1]} — ${r[2]}`);
+        console.log('');
+      } else {
+        needPick = true;
+        console.log('쓸 수 있는 워크스페이스가 없어요. z2o.kr 에서 만들거나 초대받으세요.\n');
+      }
+    }
+
+    // ③ AI 에게 알려주기 — 여기가 핵심이다.
+    if (flags.global) {
+      // 도구가 깔린 곳에만 심는다 — 안 쓰는 도구의 설정 폴더를 만들어 두지 않는다.
+      const hit = GLOBAL_RULES.filter(([d]) => existsSync(join(homedir(), d)));
+      if (hit.length === 0) hit.push(['.claude', 'CLAUDE.md']);
+      for (const [d, f] of hit) {
+        const dir = join(homedir(), d);
+        mkdirSync(dir, { recursive: true });
+        const r = writeRules(join(dir, f));
+        console.log(`~/${d}/${f} — ${r.state}`);
+      }
+      console.log('  (모든 폴더에서 통합니다)');
+      console.log('\n이제 AI 에게 그냥 물어보세요:');
+      console.log('  "최근 슬랙에서 나온 얘기 정리해줘"');
+      if (needPick) {
+        console.log('\n🔴 아직 한 걸음 남았어요:');
+        console.log('  z2o use <id 또는 이름>');
+      }
+      return;
+    }
+
+    //
+    // 🔑 **도구마다 읽는 파일이 다르다.** 이미 있는 것에는 전부 심고, 하나도 없으면
+    //    `AGENTS.md` 를 만든다 — 여러 도구가 함께 읽기로 한 이름이라 한 장으로 제일
+    //    넓게 닿는다. Claude 를 쓰는 사람이 많으므로 `CLAUDE.md` 도 같이 만든다.
+    const KNOWN = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
+    const files = KNOWN.filter((f) => existsSync(f));
+    if (files.length === 0) files.push('AGENTS.md', 'CLAUDE.md');
+    for (const f of files) {
+      const r = writeRules(f);
+      console.log(`${r.file} — ${r.state}`);
+    }
+    console.log(
+      '  (다른 도구를 쓰면 그 도구의 규칙 파일을 만들어 두고 `z2o init` 을 다시 돌리세요)',
+    );
+
+    // ⚠️ **다 된 것처럼 끝내지 않는다.** 워크스페이스를 못 정했으면 아직 아무것도 안 된다 —
+    //    여기서 "이제 물어보세요" 라고 하면 사람은 됐다고 믿고 넘어간다.
+    if (needPick) {
+      console.log('\n🔴 아직 한 걸음 남았어요:');
+      console.log('  z2o use <id 또는 이름>      (예: z2o use 린디)');
+    } else {
+      console.log('\n이제 AI 에게 그냥 물어보세요:');
+      console.log('  "최근 슬랙에서 나온 얘기 정리해줘"');
+      console.log('  "지난주 회의 내용 찾아서 할 일 뽑아줘"');
+    }
+    void flags;
+  },
+
+  async logout() {
+    const conf = loadConf();
+    delete conf.token;
+    saveConf(conf);
+    console.log('저장한 토큰을 지웠어요. (서버 쪽에서 끊으려면 프로필 → 「연결 토큰」에서 끊으세요.)');
+  },
+
+  async whoami() {
+    const { api, token, companyId } = settings();
+    console.log(`서버        ${api}`);
+    console.log(`토큰        ${token ? token.slice(0, 17) + '…' : '(없음)'}`);
+    console.log(`워크스페이스  ${companyId || '(안 정함)'}`);
+    if (!token) return;
+    console.log('');
+    console.log(await callTool('list_companies', {}));
+  },
+
+  async companies() {
+    console.log(await callTool('list_companies', {}));
+  },
+
+  async use([q]) {
+    if (!q) die('워크스페이스 id 나 이름 일부를 적어 주세요.');
+    const text = await callTool('list_companies', {});
+    // 목록 줄은 `- <id> — <이름>` 모양이다.
+    const rows = text
+      .split('\n')
+      .map((l) => l.match(/^- (\S+) — (.+?)(?: \(초대받음.*\))?$/))
+      .filter(Boolean)
+      .map((m) => ({ id: m[1], name: m[2] }));
+    const hit = rows.filter((r) => r.id === q || r.name.includes(q));
+    if (hit.length === 0) {
+      // 🔑 **매인 토큰이면 목록에 하나만 나온다.** 그걸 모르면 "왜 내 회사가 없지" 가 된다.
+      const why =
+        rows.length === 1
+          ? '\n\n이 열쇠는 위 워크스페이스에만 매여 있어요. 다른 곳도 쓰려면 「전부」로 새로 발급하세요.'
+          : '';
+      die(`「${q}」 에 해당하는 워크스페이스가 없어요.\n\n${text}${why}`);
+    }
+    // ⚠️ 여럿이면 고르지 않는다 — 엉뚱한 회사에 자료를 넣게 되는 쪽이 훨씬 나쁘다.
+    if (hit.length > 1) {
+      die(`「${q}」 가 여럿에 걸려요. id 로 정확히 골라 주세요.\n` + hit.map((r) => `- ${r.id} — ${r.name}`).join('\n'));
+    }
+    saveConf({ ...loadConf(), companyId: hit[0].id });
+    console.log(`기본 워크스페이스를 「${hit[0].name}」 로 정했어요.`);
+  },
+
+  async list(args, flags) {
+    console.log(await callTool('list_pages', { company_id: needCompany(flags), prefix: args[0] || '' }));
+  },
+
+  async search(args, flags) {
+    const q = args.join(' ').trim();
+    if (!q) die('찾을 낱말을 적어 주세요.');
+    console.log(await callTool('search_pages', { company_id: needCompany(flags), query: q }));
+  },
+
+  async read(args, flags) {
+    if (args.length === 0) die('읽을 문서 경로를 적어 주세요. (`z2o list` 로 확인)');
+    console.log(await callTool('read_pages', { company_id: needCompany(flags), paths: args }));
+  },
+
+  async graph(_args, flags) {
+    console.log(await callTool('get_graph', { company_id: needCompany(flags) }));
+  },
+
+  // ── 정리 전 원본 ──
+  //
+  // 🔑 위 넷은 **정리된 위키 문서**만 본다. 슬랙·메일이 자동으로 들어오면 정리를
+  //    돌리기 전까지 그 문서가 없어서 아무것도 안 잡힌다. 정리(유료)를 안 거치고도
+  //    맥락을 쓸 수 있어야 한다. 정리는 그다음이다.
+
+  async recent(args, flags) {
+    const n = Number(args[0]);
+    console.log(
+      await callTool('list_raw', {
+        company_id: needCompany(flags),
+        ...(Number.isFinite(n) && n > 0 ? { limit: n } : {}),
+      }),
+    );
+  },
+
+  async find(args, flags) {
+    const q = args.join(' ').trim();
+    if (!q) die('찾을 낱말을 적어 주세요.');
+    console.log(await callTool('search_raw', { company_id: needCompany(flags), query: q }));
+  },
+
+  async raw(args, flags) {
+    if (args.length === 0) die('읽을 원본 id 를 적어 주세요. (`z2o recent` 로 확인)');
+    console.log(await callTool('read_raw', { company_id: needCompany(flags), ids: args }));
+  },
+
+  async push(args, flags) {
+    const [title, path] = args;
+    if (!title || !path) die('제목과 파일을 적어 주세요.\n  z2o push "회의록" note.md\n  cat x.md | z2o push "제목" -');
+    // `-` 면 표준입력. 파이프로 이어 쓰는 게 이 명령의 주된 쓰임새다.
+    const content = path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
+    if (!content.trim()) die('본문이 비어 있어요.');
+    console.log(await callTool('ingest_text', { company_id: needCompany(flags), title, content }));
+  },
+
+  /** 요약이 안 된 원본. **표는 코드가 이미 만들었고 사람이 읽을 글만 비어 있다.** */
+  async pending(args, flags) {
+    const n = Number(args[0]);
+    console.log(
+      await callTool('list_pending', {
+        company_id: needCompany(flags),
+        ...(Number.isFinite(n) && n > 0 ? { limit: n } : {}),
+      }),
+    );
+  },
+
+  /** 요약을 위키에 남긴다.
+   *
+   * 🔑 여기서 쓴 문서는 **사람이 쓴 것으로 표시**되어 Z2O 의 자동 정리가 덮지 않는다.
+   *    `ledger/`·`entities/`·`tables/` 는 코드가 만드는 구역이라 서버가 거절한다.
+   */
+  async write(args, flags) {
+    const [path, file] = args;
+    if (!path || !file) {
+      die('경로와 파일을 적어 주세요.\n  z2o write topics/물류.md 요약.md\n  ... | z2o write topics/물류.md -');
+    }
+    const content = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8');
+    if (!content.trim()) die('본문이 비어 있어요.');
+    console.log(
+      await callTool('write_pages', {
+        company_id: needCompany(flags),
+        pages: [{ path, content }],
+      }),
+    );
+  },
+
+  async organize(_args, flags) {
+    console.log(await callTool('organize', { company_id: needCompany(flags) }));
+  },
+};
+
+// ── 진입점 ──────────────────────────────────────────────
+
+const { flags, rest } = parseArgs(process.argv.slice(2));
+const [cmd, ...args] = rest;
+
+if (!cmd || flags.help || cmd === 'help') {
+  console.log(HELP);
+  process.exit(cmd && !flags.help && cmd !== 'help' ? 1 : 0);
+}
+
+const run = COMMANDS[cmd];
+if (!run) die(`모르는 명령이에요: ${cmd}\n\n${HELP}`);
+
+run(args, flags).catch((e) => die(`문제가 생겼어요: ${e.message}`));

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "z2o-cli",
+  "version": "0.4.0",
+  "description": "제로투원 — 회사 온톨로지와 슬랙 맥락을 내가 쓰는 AI에서 꺼내 쓴다",
+  "keywords": [
+    "z2o",
+    "zerotoone",
+    "ontology",
+    "wiki",
+    "slack",
+    "cli",
+    "llm",
+    "claude",
+    "mcp"
+  ],
+  "homepage": "https://z2o.kr",
+  "bugs": {
+    "url": "https://z2o.kr"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "z2o": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}