rootr-cli 0.2.1 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rootr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,12 +3,22 @@
 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종
+- `rootr` CLI: `ls`, `read`, `write`, `append`, `edit`, `search`, `rm`, `attach`, `ws`, `ask`, `config`
+- `rootr mcp`: stdio 기반 MCP 서버 (Claude Code / Claude Desktop 등에 등록해서 사용), 도구 90종+
+  — 문서·워크스페이스/스캐폴딩·LOG 데이터스토어·RCA ask·이슈·웹훅·첨부파일에 더해
+  스프레드시트/화이트보드/폼/프레젠테이션/녹음/CRM/데이터베이스까지. 정확한 목록은 MCP `tools/list`로 확인하세요.
 
 순수 Node.js ESM, 빌드 과정 없음. Node 18 이상 필요(내장 `fetch` 사용).
 
+## 링크
+
+- 소스: https://github.com/gwmage/rootr-cli
+- npm: https://www.npmjs.com/package/rootr-cli
+- 원격 커넥터(설치 없이 바로 연결): `https://rootr.io/mcp` — Claude Code/Desktop 등에서
+  로컬 CLI 설치 없이 원격 MCP 엔드포인트로 바로 연결할 수 있습니다. 로컬 CLI(`rootr mcp`)와
+  기능은 동일하며, 자체 인프라에 CLI를 두고 싶을 때만 이 저장소를 설치하면 됩니다.
+- 라이선스: MIT (`LICENSE` 참고)
+
 ## 설치
 
 이 저장소 안에서 바로 실행하거나, 전역 설치할 수 있습니다.
@@ -130,6 +140,18 @@ rootr search "배포 절차"
 
 출력: `path — snippet` 목록.
 
+### 문서 삭제 (휴지통으로)
+
+```bash
+rootr rm /notes/todo.md          # 확인 후 삭제
+rootr rm /notes/todo.md --yes    # 확인 없이 (스크립트용)
+```
+
+휴지통으로 옮기는 **복구 가능한** 삭제입니다. 앱의 휴지통에서 되돌릴 수 있고,
+30일이 지나면 자동으로 완전 삭제됩니다. `--yes` 없이 실행하면 확인을 묻습니다
+(파이프/CI처럼 입력이 없는 환경에서는 "아니오"로 처리되어 안전합니다).
+`docs:write` 스코프가 필요합니다.
+
 ### 워크스페이스 목록
 
 ```bash
@@ -138,6 +160,38 @@ rootr ws
 
 출력: `id\tname` 목록 (계정 키면 소속된 전체 워크스페이스, 워크스페이스 키면 그 워크스페이스만).
 
+### 워크스페이스 여러 개 쓰기 (키 등록 + 전환)
+
+워크스페이스마다 키가 다르면 한 번만 등록해 두세요:
+
+```bash
+rootr config --add-key rootr_xxx --label "영업팀"
+rootr config                       # 등록된 키 목록 확인
+```
+
+이후 MCP에서 `rootr_use_workspace` 도구로 **이름이나 id**를 주면 활성 워크스페이스가
+바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정 키(PAT)를 쓰면
+소속된 어느 워크스페이스로든 바로 전환됩니다.
+
+> 원격 커넥터(`https://rootr.io/mcp`)는 승인할 때 고른 워크스페이스 하나에만 연결됩니다.
+> 다른 워크스페이스가 필요하면 그 워크스페이스로 커넥터를 새로 발급하세요.
+
+### 사용량 한도
+
+프로그램(API 키·MCP) 호출 중 **조회 계열**(`docs:read`/`graph:read`/`ask`)에만 한도가 있습니다.
+쓰기·업로드는 제한하지 않습니다.
+
+| 플랜 | 한도 |
+| --- | --- |
+| Free | **하루 180회** (KST 자정 리셋) |
+| Team | 시간당 5,000회 |
+| Business | 시간당 50,000회 |
+| Platform | 무제한 |
+
+한도의 80%를 쓰면 MCP 도구 응답 끝에 남은 횟수 안내가 붙고, 다 쓰면 429와 함께
+업그레이드 링크가 담긴 안내가 나옵니다. 응답 헤더로도 확인할 수 있습니다
+(`X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Window`).
+
 ### RCA 질의응답 (ask)
 
 ```bash
@@ -150,7 +204,14 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 
 ## MCP 서버로 사용하기
 
-`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 27종:
+`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 29종:
+
+노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
+`recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
+받습니다 — CLI와 같은 규칙으로 `/`로 시작하면 경로로 해석합니다.
+즉 `rootr_add_row`에 `databaseId: "/제작 공정/칸반"`을 그대로 넘길 수 있어,
+경로만 아는 에이전트가 uuid를 찾아 헤맬 필요가 없습니다.
+`rootr_list`·`rootr_search` 출력도 각 줄 끝에 `[노드 id]`를 함께 표시합니다.
 
 #### 문서 (workspace 키, docs:read/docs:write)
 
@@ -167,6 +228,16 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 `rootr_write`는 정말 전체를 다시 쓸 때만 (가능하면 `ifMatch`와 함께) 쓰도록
 각 도구 설명에 명시되어 있습니다.
 
+#### 첨부파일 (workspace 키, docs:write)
+
+| 도구 | 설명 |
+|---|---|
+| `rootr_upload_attachment` | 로컬 파일(`filePath`) 또는 base64(`base64Data`)를 업로드하고 `{id, url, markdown}` 반환 |
+| `rootr_attach_image_to_document` | 위 업로드 + 지정 문서에 `rootr_append`로 바로 삽입 (가장 흔한 용법) |
+
+`url`은 `/attachments/{id}/raw` — 로그인 없이 렌더되는 공개 경로라 published(`/p/`) 문서에도
+그대로 쓸 수 있습니다. CLI에서는 `rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]`.
+
 #### 워크스페이스 / 스캐폴딩
 
 | 도구 | 필요 스코프 | 설명 |
@@ -218,6 +289,32 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 | `rootr_document_versions` | 문서 버전 히스토리 조회 |
 | `rootr_delete_node` | 노드를 휴지통으로 이동(복구 가능) |
 
+#### 프레젠테이션 (현재 REST 전용 — 전용 MCP 도구는 예정)
+
+프레젠테이션(PRESENTATION) 노드는 아직 전용 MCP 도구가 없고, **같은 API 키로 REST를
+직접 호출**해 저작합니다 (`x-api-key` 헤더, `docs:write`):
+
+```bash
+# 덱 생성 (슬라이드 포함 가능)
+curl -X POST "$BASE/workspaces/$WS/presentations" -H "x-api-key: $KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"제안서","slides":[{"id":"SLD-001","kind":"cover","title":"..."}]}'
+
+# 슬라이드 부분 수정(머지) / 추가 / 순서 변경
+curl -X PATCH "$BASE/presentations/$ID/slides/SLD-001" -H "x-api-key: $KEY" \
+  -H 'Content-Type: application/json' -d '{"slide":{"notes":"발표 대본"}}'
+curl -X POST "$BASE/presentations/$ID/slides"  -d '{"slides":[...]}' ...
+curl -X POST "$BASE/presentations/$ID/reorder" -d '{"order":["SLD-002","SLD-001"]}' ...
+```
+
+**고품질 덱을 만들 때는 슬라이드 `html` 필드에 1280×720 완결 HTML을 직접 구워
+넣는 방식을 권장**합니다 — 뷰어가 기본 템플릿 대신 그대로 렌더합니다(완전 자유
+디자인). 필수 규칙(외부 요청 차단이라 전부 인라인, 이미지=data URI 내장, 폰트
+폴백 스택, `<span class="pn">`=페이지번호, 그래프용 텍스트(title/blocks/notes/alt)
+병행 유지)은 **`/llms.txt`의 "Presentations" 섹션**에 정리돼 있습니다 — 저작 전에
+꼭 읽어보세요. AI 이미지 생성은 `POST /v1/workspaces/:ws/images/generate`(AI
+크레딧 차감)를 사용합니다.
+
 모든 도구 설명은 영어(에이전트가 소비하는 스키마)로 작성되어 있고, JSON을 반환하는
 도구는 보기 좋게 들여쓴 JSON 텍스트로 응답합니다. `workspace` 인자를 받는 도구는
 생략 시 `ROOTR_WORKSPACE`/설정파일의 기본 워크스페이스를 사용하며, 그것도 없으면

package/bin/rootr.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, basename, extname } from 'node:path';
 
-import { loadConfig, saveConfig, maskKey, CONFIG_PATH, DEFAULT_BASE_URL } from '../lib/config.js';
+import { loadConfig, saveConfig, maskKey, upsertKey, CONFIG_PATH, DEFAULT_BASE_URL } from '../lib/config.js';
 import { RootrClient, RootrApiError } from '../lib/client.js';
 import { resolveTarget, requireResolved } from '../lib/resolve.js';
 
@@ -19,10 +19,13 @@ const USAGE = `Rootr CLI v${pkg.version}
   rootr append <path|id> [<text>] [--heading "## X"] [--file <f>]  문서 끝(또는 헤딩 아래)에 안전하게 추가
   rootr edit <path|id> --find <text> --replace <text> [--all]      본문 내 텍스트 치환
   rootr search <query>                             워크스페이스 검색
+  rootr rm <path|id> [--yes]                       문서/폴더를 휴지통으로 이동 (복구 가능)
+  rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]  파일 업로드(+문서에 삽입)
   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 config --add-key <k> [--label <name>] [--workspace <w>]     워크스페이스별 키 추가 등록
+  rootr mcp                                        MCP stdio 서버 구동 (도구 90종+ — README 참고)
   rootr --help                                     도움말
   rootr --version                                  버전 출력
 
@@ -215,6 +218,89 @@ async function cmdSearch(args) {
   }
 }
 
+async function cmdRm(args) {
+  const target = args._[0];
+  if (!target) throw new Error('사용법: rootr rm <path|id> [--yes]');
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, target);
+  const id = requireResolved(resolved);
+
+  // Deleting is recoverable (trash), but it still removes the node from every
+  // teammate's tree — confirm unless the caller opted out for scripting.
+  if (!args.yes) {
+    const label = resolved.path || resolved.name || id;
+    const ok = await confirmPrompt(`"${label}" 을(를) 휴지통으로 옮깁니다. 계속할까요? [y/N] `);
+    if (!ok) {
+      console.log('취소했습니다.');
+      return;
+    }
+  }
+
+  await client.deleteNode(id);
+  console.log(`휴지통으로 옮겼습니다: ${resolved.path || id}`);
+  console.log('복구하려면 앱의 휴지통에서 되돌리세요 (30일 뒤 자동 삭제).');
+}
+
+/** Minimal y/N prompt. Non-interactive stdin (pipes, CI) answers "no". */
+function confirmPrompt(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    process.stdin.setEncoding('utf8');
+    process.stdin.once('data', (data) => {
+      process.stdin.pause();
+      resolve(/^y(es)?$/i.test(String(data).trim()));
+    });
+  });
+}
+
+const MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf',
+};
+
+async function cmdAttach(args) {
+  const filePath = args._[0];
+  if (!filePath) throw new Error('사용법: rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]');
+
+  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 data = readFileSync(filePath);
+  const filename = basename(filePath);
+  const mimeType = args.mime || MIME_BY_EXT[extname(filePath).toLowerCase()] || 'application/octet-stream';
+
+  let nodeId;
+  if (typeof args.doc === 'string') {
+    const resolved = await resolveTarget(client, args.doc);
+    nodeId = requireResolved(resolved);
+  }
+
+  const { id } = await client.uploadAttachment(workspace, { filename, mimeType, nodeId, data });
+  const url = client.attachmentRawUrl(id);
+  const markdown = `![${args.alt || filename}](${url})`;
+
+  if (nodeId) {
+    const result = await client.appendDocument(nodeId, { content: markdown, underHeading: args.heading });
+    console.error(`uploaded ${filename} (id ${id}) and appended to ${args.doc} (etag ${result.etag || 'n/a'})`);
+  } else {
+    console.error(`uploaded ${filename} (id ${id})`);
+  }
+  console.log(markdown);
+}
+
 async function cmdWs() {
   const client = makeClient();
   const workspaces = await client.listWorkspaces();
@@ -248,6 +334,19 @@ async function cmdAsk(args) {
 }
 
 async function cmdConfig(args) {
+  // Registering an extra credential is its own action — several keys can live
+  // side by side, each bound to the workspace it can reach, so `rootr mcp` (and
+  // the rootr_use_workspace tool) can switch workspaces without reconfiguring.
+  if (typeof args['add-key'] === 'string') {
+    const keys = upsertKey({
+      apiKey: args['add-key'],
+      workspace: typeof args.workspace === 'string' ? args.workspace : undefined,
+      label: typeof args.label === 'string' ? args.label : undefined,
+    });
+    console.log(`키를 등록했습니다 (총 ${keys.length}개): ${CONFIG_PATH}`);
+    return;
+  }
+
   const hasAny = args['api-key'] || args.workspace || args['base-url'];
   if (!hasAny) {
     const cfg = loadConfig();
@@ -255,6 +354,9 @@ async function cmdConfig(args) {
     console.log(`apiKey:      ${maskKey(cfg.apiKey)}`);
     console.log(`workspace:   ${cfg.workspace || '(not set)'}`);
     console.log(`baseUrl:     ${cfg.baseUrl || DEFAULT_BASE_URL}`);
+    for (const k of cfg.keys || []) {
+      console.log(`  + ${maskKey(k.apiKey)}  ${k.workspace || '(any)'}  ${k.label || ''}`);
+    }
     return;
   }
 
@@ -301,6 +403,10 @@ async function main() {
       return cmdEdit(args);
     case 'search':
       return cmdSearch(args);
+    case 'attach':
+      return cmdAttach(args);
+    case 'rm':
+      return cmdRm(args);
     case 'ws':
       return cmdWs(args);
     case 'ask':