rootr-cli 0.1.0

package/README.md

@@ -0,0 +1,275 @@
+# rootr-cli
+
+Rootr(마크다운 지식협업 SaaS) 공식 CLI + MCP 서버. 에이전트나 사람이 Rootr 문서를
+로컬 파일처럼 읽고/쓰고/검색할 수 있게 해줍니다.
+
+- `rootr` CLI: `ls`, `read`, `write`, `append`, `edit`, `search`, `ws`, `ask`, `config`
+- `rootr mcp`: stdio 기반 MCP 서버 (Claude Code / Claude Desktop 등에 등록해서 사용), 도구 27종
+  — 문서 6종 + 워크스페이스/스캐폴딩 4종 + LOG 데이터스토어 5종 + RCA ask 1종 + 이슈 6종 + 웹훅 3종 + 문서버전/삭제 2종
+
+순수 Node.js ESM, 빌드 과정 없음. Node 18 이상 필요(내장 `fetch` 사용).
+
+## 설치
+
+이 저장소 안에서 바로 실행하거나, 전역 설치할 수 있습니다.
+
+```bash
+cd cli
+npm install
+
+# 방법 1: 직접 실행
+node bin/rootr.js --help
+
+# 방법 2: 전역 설치 (심볼릭 링크로 rootr 명령 사용)
+npm install -g .
+rootr --help
+```
+
+## 설정
+
+우선순위: **환경변수 > `~/.rootr/config.json`**
+
+| 환경변수 | 설정파일 키 | 설명 |
+|---|---|---|
+| `ROOTR_API_KEY` | `apiKey` | `rootr_...` 형태의 API 키. 모든 요청에 `x-api-key` 헤더로 전송됩니다. |
+| `ROOTR_WORKSPACE` | `workspace` | 워크스페이스 id |
+| `ROOTR_BASE_URL` | `baseUrl` | 기본값 `https://rootr.io/api/v1` |
+
+설정 파일에 저장하기:
+
+```bash
+rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123
+# 필요하면 온프레미스/개발 서버용 base-url도 지정 가능
+rootr config --api-key rootr_xxx --workspace ws_123 --base-url https://dev.rootr.io/api/v1
+```
+
+`~/.rootr/config.json`은 `chmod 600`으로 생성됩니다.
+
+### 키 2종
+
+Rootr API 키는 두 종류가 있고, 도구별로 요구하는 종류가 다릅니다.
+
+- **워크스페이스 키**: 특정 워크스페이스 안에서만 동작. 스코프는
+  `docs:read`/`docs:write`/`graph:read`/`ask`/`webhooks:manage` 중 일부.
+  대부분의 문서/LOG/이슈/웹훅/ask 도구는 이 키로 충분합니다.
+- **계정 키 (PAT)**: 사용자 계정 전체로 동작. `workspaces:create` 스코프가 있으면
+  새 워크스페이스를 만들 수 있습니다 (`rootr_create_workspace`). 워크스페이스 키로
+  워크스페이스 생성을 시도하면 403과 함께 계정 키가 필요하다는 힌트가 출력됩니다.
+
+현재 설정 확인 (API 키는 앞 12자만 표시):
+
+```bash
+rootr config
+# config file: /home/you/.rootr/config.json
+# apiKey:      rootr_abcd...
+# workspace:   ws_123
+# baseUrl:     https://rootr.io/api/v1
+```
+
+## CLI 사용법
+
+경로 인자 규칙: `/`로 시작하면 **경로**로 취급되어 by-path API로 노드 id를 알아냅니다
+(워크스페이스 설정 필요). `/`로 시작하지 않으면 **노드 id**로 취급합니다.
+
+### 트리 조회
+
+```bash
+rootr ls                # 전체 트리
+rootr ls /notes         # /notes 하위만
+```
+
+출력: `TYPE\tpath` 형식, 경로 정렬.
+
+### 문서 읽기
+
+```bash
+rootr read /notes/todo.md          # 마크다운 원문을 stdout으로
+rootr read /notes/todo.md --json   # 메타데이터 포함 JSON 전체
+rootr read <nodeId>                # id로도 가능
+```
+
+### 문서 쓰기 (전체 교체, 없으면 생성)
+
+```bash
+echo "# 제목" | rootr write /notes/new.md
+rootr write /notes/new.md --file ./local.md
+rootr write <nodeId> --file ./local.md --if-match "\"abc123\""   # 낙관적 동시성 제어
+```
+
+경로가 아직 없으면 자동으로 문서를 생성합니다(`createParents: true`).
+`--if-match`를 지정했는데 그 사이 문서가 바뀌었으면 412 오류와 함께
+"문서가 그 사이 변경됨: 다시 읽고 재시도" 힌트가 출력됩니다.
+
+### 안전하게 추가 (append) — 충돌 걱정 없는 기본 수단
+
+```bash
+rootr append /notes/log.md "오늘 배포 완료"
+rootr append /notes/log.md "- 항목 하나 더" --heading "## 할 일"
+cat diff.md | rootr append /notes/log.md
+rootr append /notes/log.md --file ./chunk.md
+```
+
+`--heading`을 지정하면 해당 헤딩 섹션 끝에 추가되고, 없으면 문서 끝에 추가됩니다.
+append는 전체 내용을 다시 쓰지 않으므로 다른 프로세스와 동시에 써도 충돌하지 않습니다.
+
+### 텍스트 치환 (edit)
+
+```bash
+rootr edit /notes/todo.md --find "- [ ] 배포" --replace "- [x] 배포"
+rootr edit /notes/todo.md --find "TODO" --replace "DONE" --all
+```
+
+`--find`한 텍스트가 없거나 여러 번 나타나면(고유하지 않으면) 서버가 409를 반환하고
+그 이유가 그대로 출력됩니다. `--all`을 주면 모든 일치 항목을 치환합니다.
+
+### 검색
+
+```bash
+rootr search "배포 절차"
+```
+
+출력: `path — snippet` 목록.
+
+### 워크스페이스 목록
+
+```bash
+rootr ws
+```
+
+출력: `id\tname` 목록 (계정 키면 소속된 전체 워크스페이스, 워크스페이스 키면 그 워크스페이스만).
+
+### RCA 질의응답 (ask)
+
+```bash
+rootr ask "지난주 배포 후 지연이 왜 늘었어?"
+rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
+```
+
+워크스페이스의 지식그래프(GraphRAG)에 질문하고 답변 본문 + 인용(문서 경로: 인용문)을 출력합니다.
+`ask` 스코프가 필요합니다. `--workspace`를 생략하면 설정된 기본 워크스페이스를 사용합니다.
+
+## MCP 서버로 사용하기
+
+`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 27종:
+
+#### 문서 (workspace 키, docs:read/docs:write)
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_list` | 워크스페이스 트리 목록 |
+| `rootr_read` | 문서 마크다운 읽기 |
+| `rootr_append` | **(권장)** 문서에 안전하게 추가 — 충돌 불가능 |
+| `rootr_edit` | 정확한 텍스트 스니펫 치환 |
+| `rootr_write` | 문서 전체 교체(파괴적) 또는 신규 생성 |
+| `rootr_search` | 워크스페이스 검색 |
+
+에이전트에게는 가능하면 `rootr_append`/`rootr_edit`을 우선 사용하고,
+`rootr_write`는 정말 전체를 다시 쓸 때만 (가능하면 `ifMatch`와 함께) 쓰도록
+각 도구 설명에 명시되어 있습니다.
+
+#### 워크스페이스 / 스캐폴딩
+
+| 도구 | 필요 스코프 | 설명 |
+|---|---|---|
+| `rootr_workspaces` | 계정 키 또는 워크스페이스 키 | 내 워크스페이스 목록 |
+| `rootr_scaffold_plan` | 워크스페이스 불필요 | 의도(intent) 문장으로 문서 트리 계획 생성 |
+| `rootr_create_workspace` | **계정 키(PAT) + workspaces:create** | 계획된 트리로 새 워크스페이스 생성 |
+| `rootr_scaffold_apply` | docs:write | 기존 워크스페이스에 트리 적용 |
+
+#### LOG 데이터스토어 (docs:read/docs:write)
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_create_log_store` | 타입드 LOG 스토어 생성 (필드: string/int/float/bool/datetime/json/enum/level/relation) |
+| `rootr_update_log_fields` | 필드 스키마 갱신 — **전체 교체**(유지할 필드도 다시 보내야 함) |
+| `rootr_add_log_entries` | 엔트리(행) 추가 |
+| `rootr_query_log_entries` | 엔트리 조회/필터(시간범위·source·level·anomalyOnly) |
+| `rootr_log_stats` | 집계 통계(hour/day/source/level × count/avg/max/min/sum) |
+
+#### RCA 질의응답 (ask 스코프)
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_ask` | 지식그래프(GraphRAG)에 자연어 질문, 답변+인용 반환 |
+
+#### 이슈 트래커 (docs:read/docs:write)
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_create_issue_tracker` | 이슈 트래커 생성 |
+| `rootr_list_issues` | 이슈 목록(state/label/type/assignee/검색어 필터) |
+| `rootr_create_issue` | 이슈 생성(labels/type/parentIssueId 지원) |
+| `rootr_get_issue` | 이슈 상세 조회 |
+| `rootr_update_issue` | 이슈 갱신(닫기: state=CLOSED + stateReason) |
+| `rootr_comment_issue` | 이슈에 댓글 추가 |
+
+#### 웹훅 (webhooks:manage 스코프)
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_list_webhooks` | 워크스페이스 웹훅 목록 |
+| `rootr_create_webhook` | 웹훅 생성 — 응답의 secret은 **1회만 노출** |
+| `rootr_delete_webhook` | 웹훅 삭제 |
+
+#### 문서 버전 / 삭제
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_document_versions` | 문서 버전 히스토리 조회 |
+| `rootr_delete_node` | 노드를 휴지통으로 이동(복구 가능) |
+
+모든 도구 설명은 영어(에이전트가 소비하는 스키마)로 작성되어 있고, JSON을 반환하는
+도구는 보기 좋게 들여쓴 JSON 텍스트로 응답합니다. `workspace` 인자를 받는 도구는
+생략 시 `ROOTR_WORKSPACE`/설정파일의 기본 워크스페이스를 사용하며, 그것도 없으면
+명확한 에러를 반환합니다.
+
+### Claude Code / Claude Desktop에 등록하기
+
+`~/.claude.json`(Claude Code) 또는 Claude Desktop의 MCP 설정 파일에 다음을 추가:
+
+```json
+{
+  "mcpServers": {
+    "rootr": {
+      "command": "node",
+      "args": ["/path/to/rootr/backend/cli/bin/rootr.js", "mcp"],
+      "env": {
+        "ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",
+        "ROOTR_WORKSPACE": "ws_123"
+      }
+    }
+  }
+}
+```
+
+전역 설치했다면 `command`를 `"rootr"`, `args`를 `["mcp"]`로만 써도 됩니다.
+
+## 에러 처리
+
+API가 비-2xx를 반환하면 응답 본문의 `message`(있으면)를 stderr에 출력하고
+exit code 1로 종료합니다. 상황별 힌트:
+
+- `401`/`403` → API 키/워크스페이스 스코프 확인 안내
+- `412` → "문서가 그 사이 변경됨: 다시 읽고 재시도" 안내 (If-Match 불일치)
+- `409` → 서버가 준 이유 메시지를 그대로 표시 (예: edit의 find 불일치/중복)
+
+## 개발 메모
+
+- 의존성: `@modelcontextprotocol/sdk`(MCP 서버), `zod`(도구 입력 스키마).
+  CLI 자체(`bin/rootr.js`, `lib/config.js`, `lib/client.js`, `lib/resolve.js`)는
+  외부 의존성 없이 동작합니다.
+- 빌드 스텝 없음 — 순수 ESM 자바스크립트.
+- 파일 구성:
+  - `bin/rootr.js` — 엔트리포인트, 명령 디스패치
+  - `lib/config.js` — 설정 로드/저장
+  - `lib/client.js` — Rootr REST API 클라이언트(문서/워크스페이스/스캐폴딩/LOG/ask/이슈/웹훅)
+  - `lib/resolve.js` — path/id 타겟 해석 공통 로직
+  - `lib/mcp.js` — MCP stdio 서버 진입점, 도구 모듈 조립
+  - `lib/mcp-tools/shared.js` — MCP 도구 공통 헬퍼(textResult/jsonResult/errorResult/makeClient/requireWorkspace)
+  - `lib/mcp-tools/documents.js` — 문서 도구 6종
+  - `lib/mcp-tools/workspaces.js` — 워크스페이스/스캐폴딩 도구 4종
+  - `lib/mcp-tools/logs.js` — LOG 데이터스토어 도구 5종
+  - `lib/mcp-tools/ask.js` — RCA ask 도구 1종
+  - `lib/mcp-tools/issues.js` — 이슈 트래커 도구 6종
+  - `lib/mcp-tools/webhooks.js` — 웹훅 도구 3종
+  - `lib/mcp-tools/misc.js` — 문서버전/삭제 도구 2종

package/bin/rootr.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { loadConfig, saveConfig, maskKey, CONFIG_PATH, DEFAULT_BASE_URL } from '../lib/config.js';
+import { RootrClient, RootrApiError } from '../lib/client.js';
+import { resolveTarget, requireResolved } from '../lib/resolve.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const USAGE = `Rootr CLI v${pkg.version}
+
+사용법:
+  rootr ls [path]                                  워크스페이스 트리 조회
+  rootr read <path|id> [--json]                    문서 읽기 (마크다운 또는 JSON)
+  rootr write <path|id> [--file <f>] [--if-match <etag>]   문서 전체 교체(파일 없으면 생성)
+  rootr append <path|id> [<text>] [--heading "## X"] [--file <f>]  문서 끝(또는 헤딩 아래)에 안전하게 추가
+  rootr edit <path|id> --find <text> --replace <text> [--all]      본문 내 텍스트 치환
+  rootr search <query>                             워크스페이스 검색
+  rootr ws                                         내 워크스페이스 목록 (id\tname)
+  rootr ask <question> [--workspace <w>]           GraphRAG 질의응답 (RCA), 인용 포함 출력
+  rootr config [--api-key <k>] [--workspace <w>] [--base-url <u>]  설정 조회/저장
+  rootr mcp                                        MCP stdio 서버 구동 (도구 27종 — README 참고)
+  rootr --help                                     도움말
+  rootr --version                                  버전 출력
+
+설정 우선순위: 환경변수(ROOTR_API_KEY, ROOTR_WORKSPACE, ROOTR_BASE_URL) > ~/.rootr/config.json
+
+경로 인자는 '/'로 시작해야 합니다 (예: /notes/todo.md). 그 외 값은 노드 id로 취급됩니다.
+`;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok.startsWith('--')) {
+      const key = tok.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        args[key] = true;
+      } else {
+        args[key] = next;
+        i++;
+      }
+    } else {
+      args._.push(tok);
+    }
+  }
+  return args;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      resolve('');
+      return;
+    }
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function makeClient() {
+  const cfg = loadConfig();
+  return new RootrClient(cfg);
+}
+
+function printErrorAndExit(err) {
+  if (err instanceof RootrApiError) {
+    console.error(`오류: ${err.message}`);
+    if (err.status) console.error(`(HTTP ${err.status})`);
+    if (err.hint) console.error(`힌트: ${err.hint}`);
+  } else {
+    console.error(`오류: ${err.message || err}`);
+  }
+  process.exit(1);
+}
+
+// ---- commands -------------------------------------------------------------
+
+async function cmdLs(args) {
+  const client = makeClient();
+  const filterPath = args._[0];
+  const nodes = await client.getTree();
+
+  const rows = nodes
+    .filter((n) => {
+      if (!filterPath) return true;
+      const p = n.path || '';
+      return p === filterPath || p.startsWith(filterPath.endsWith('/') ? filterPath : filterPath + '/');
+    })
+    .map((n) => ({ type: n.type || '?', path: n.path || n.name || n.id }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+
+  for (const row of rows) {
+    console.log(`${row.type}\t${row.path}`);
+  }
+}
+
+async function cmdRead(args) {
+  const target = args._[0];
+  if (!target) throw new Error('사용법: rootr read <path|id> [--json]');
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, target);
+  const id = requireResolved(resolved);
+
+  if (args.json) {
+    const doc = await client.getDocumentJson(id);
+    console.log(JSON.stringify(doc, null, 2));
+  } else {
+    const { content } = await client.getDocumentMarkdown(id);
+    process.stdout.write(content.endsWith('\n') ? content : content + '\n');
+  }
+}
+
+async function cmdWrite(args) {
+  const target = args._[0];
+  if (!target) throw new Error('사용법: rootr write <path|id> [--file <f>] [--if-match <etag>]');
+
+  let content;
+  if (typeof args.file === 'string') {
+    content = readFileSync(args.file, 'utf8');
+  } else {
+    content = await readStdin();
+  }
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, target);
+
+  if (!resolved.existed) {
+    if (!resolved.path) {
+      throw new Error(`대상을 찾을 수 없습니다: ${target}`);
+    }
+    // 생성 자체가 쓰기 — 곧바로 PUT을 또 하면 버전/추출만 이중으로 쌓인다
+    const created = await client.createNode({
+      type: 'DOCUMENT',
+      path: resolved.path,
+      createParents: true,
+      autoRename: false,
+      content,
+    });
+    const id = created.id || (created.node && created.node.id);
+    console.error(`created ${resolved.path} (id ${id})`);
+    return;
+  }
+
+  const { etag } = await client.putDocument(resolved.id, content, { ifMatch: args['if-match'] });
+  console.error(`wrote ${target} (etag ${etag || 'n/a'})`);
+}
+
+async function cmdAppend(args) {
+  const target = args._[0];
+  if (!target) throw new Error('사용법: rootr append <path|id> [<text>] [--heading "## X"] [--file <f>]');
+
+  let content;
+  if (typeof args._[1] === 'string') {
+    content = args._[1];
+  } else if (typeof args.file === 'string') {
+    content = readFileSync(args.file, 'utf8');
+  } else {
+    content = await readStdin();
+  }
+
+  if (!content) {
+    throw new Error('추가할 내용이 없습니다 (텍스트 인자, --file, 또는 stdin 필요).');
+  }
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, target);
+  const id = requireResolved(resolved);
+
+  const result = await client.appendDocument(id, {
+    content,
+    underHeading: args.heading,
+  });
+
+  console.error(`appended to ${target} (etag ${result.etag || 'n/a'})`);
+}
+
+async function cmdEdit(args) {
+  const target = args._[0];
+  if (!target) throw new Error('사용법: rootr edit <path|id> --find <text> --replace <text> [--all]');
+  if (typeof args.find !== 'string' || typeof args.replace !== 'string') {
+    throw new Error('--find와 --replace가 모두 필요합니다.');
+  }
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, target);
+  const id = requireResolved(resolved);
+
+  await client.patchDocumentAnchor(id, {
+    find: args.find,
+    replace: args.replace,
+    replaceAll: Boolean(args.all),
+  });
+
+  console.error(`edited ${target}`);
+}
+
+async function cmdSearch(args) {
+  const query = args._[0];
+  if (!query) throw new Error('사용법: rootr search <query>');
+
+  const client = makeClient();
+  const results = await client.search(query);
+
+  for (const r of results) {
+    console.log(`${r.path || r.name || r.nodeId} — ${r.snippet || ''}`);
+  }
+}
+
+async function cmdWs() {
+  const client = makeClient();
+  const workspaces = await client.listWorkspaces();
+  for (const w of workspaces) {
+    console.log(`${w.id}\t${w.name || w.slug || ''}`);
+  }
+}
+
+async function cmdAsk(args) {
+  const question = args._.join(' ');
+  if (!question) throw new Error('사용법: rootr ask <question> [--workspace <w>]');
+
+  const cfg = loadConfig();
+  const workspace = args.workspace || cfg.workspace;
+  if (!workspace) {
+    throw new RootrApiError('워크스페이스가 설정되지 않았습니다.', {
+      hint: '--workspace <id>로 넘기거나 rootr config --workspace <id> 또는 ROOTR_WORKSPACE 환경변수를 지정하세요.',
+    });
+  }
+
+  const client = new RootrClient({ ...cfg, workspace });
+  const result = await client.ask(workspace, question);
+  console.log(result.text || '(응답 없음)');
+  const citations = Array.isArray(result.citations) ? result.citations : [];
+  if (citations.length) {
+    console.log('\nCitations:');
+    for (const c of citations) {
+      console.log(`- ${c.documentPath}: ${c.quote}`);
+    }
+  }
+}
+
+async function cmdConfig(args) {
+  const hasAny = args['api-key'] || args.workspace || args['base-url'];
+  if (!hasAny) {
+    const cfg = loadConfig();
+    console.log(`config file: ${CONFIG_PATH}`);
+    console.log(`apiKey:      ${maskKey(cfg.apiKey)}`);
+    console.log(`workspace:   ${cfg.workspace || '(not set)'}`);
+    console.log(`baseUrl:     ${cfg.baseUrl || DEFAULT_BASE_URL}`);
+    return;
+  }
+
+  const partial = {};
+  if (typeof args['api-key'] === 'string') partial.apiKey = args['api-key'];
+  if (typeof args.workspace === 'string') partial.workspace = args.workspace;
+  if (typeof args['base-url'] === 'string') partial.baseUrl = args['base-url'];
+
+  saveConfig(partial);
+  console.log(`설정을 저장했습니다: ${CONFIG_PATH}`);
+}
+
+async function cmdMcp() {
+  const { startMcpServer } = await import('../lib/mcp.js');
+  await startMcpServer({ name: 'rootr', version: pkg.version });
+}
+
+// ---- entry ------------------------------------------------------------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv);
+  const cmd = args._.shift();
+
+  if (args.version) {
+    console.log(pkg.version);
+    return;
+  }
+  if (!cmd || args.help || cmd === 'help') {
+    console.log(USAGE);
+    return;
+  }
+
+  switch (cmd) {
+    case 'ls':
+      return cmdLs(args);
+    case 'read':
+      return cmdRead(args);
+    case 'write':
+      return cmdWrite(args);
+    case 'append':
+      return cmdAppend(args);
+    case 'edit':
+      return cmdEdit(args);
+    case 'search':
+      return cmdSearch(args);
+    case 'ws':
+      return cmdWs(args);
+    case 'ask':
+      return cmdAsk(args);
+    case 'config':
+      return cmdConfig(args);
+    case 'mcp':
+      return cmdMcp(args);
+    default:
+      console.error(`알 수 없는 명령: ${cmd}\n`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+
+main().catch(printErrorAndExit);