rootr-cli 0.13.0 → 0.14.0

package/README.md

@@ -277,7 +277,7 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 
 ## MCP 서버로 사용하기
 
-`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 151종:
+`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 152종:
 
 노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
 `recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
@@ -324,6 +324,7 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 | `rootr_scaffold_review` | 워크스페이스 불필요 | 짓기 2단계 — **만들기 전에** 설계를 검사받는다(점수·고칠 곳). 컴파일러처럼 고쳐 가며 짓는다 |
 | `rootr_create_workspace` | **계정 키(PAT) + workspaces:create** | 짓기 3단계 — 계획된 트리로 새 워크스페이스 생성(검사 결과도 같이 돌려준다) |
 | `rootr_scaffold_apply` | docs:write | 짓기 3단계 — 기존 워크스페이스에 트리 적용(검사 결과도 같이 돌려준다) |
+| `rootr_delete_workspace` | **계정 키(PAT) + OWNER** | 짓다 실패해 남은 **빈 워크스페이스 치우기**. 이름을 그대로 다시 적어야 지워진다(되돌릴 수 없음) |
 
 스캐폴딩은 **plan → 물어보기 → 설계 → review → 고치기 → apply** 한 바퀴입니다.
 `review` 를 건너뛰면 "얇은 마크다운 파일 묶음"이 됩니다. CLI 로도 같은 세 단계를 쓸 수 있습니다:
@@ -369,7 +370,7 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 | 도구 | 설명 |
 |---|---|
 | `rootr_read_database` | 스키마(열 정의)+행 전체 읽기 — **다른 표 도구를 쓰기 전에 먼저** (`includeBody: true` 면 행마다 상세 내용까지) |
-| `rootr_list_rows` | 행만 조회(스키마 제외, `includeBody` 지원) |
+| `rootr_list_rows` | 행만 조회(스키마 제외, `includeBody` 지원, `backlinks: true`면 "나를 가리키는 다른 표의 행"도 함께) |
 | `rootr_add_row` | 행 추가 (`values`는 열 이름 또는 id로 지정, `body`로 상세 내용까지) |
 | `rootr_update_row` | 행 수정 (칸반 카드 이동 = select 열 값 변경, `body`로 상세 내용 교체) |
 | `rootr_bulk_create_rows` | 행 여러 개를 한 번에 추가 |
@@ -579,6 +580,8 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 | 도구 | 설명 |
 |---|---|
 | `rootr_document_versions` | 문서 버전 히스토리 조회 |
+| `rootr_read_document_version` | 그 시점 본문을 그대로 읽기(되돌리기 전에 확인용) |
+| `rootr_restore_document_version` | 문서를 예전 버전으로 되돌리기 |
 | `rootr_update_node` | 아무 노드나 이름·아이콘 변경 / 옮기기 |
 | `rootr_delete_node` | 노드를 휴지통으로 이동(복구 가능) |
 

package/bin/rootr.js

@@ -28,7 +28,7 @@ const USAGE = `Rootr CLI v${pkg.version}
   rootr use <id|이름|주소>                          활성 워크스페이스 전환 (그 워크스페이스용 키도 기억)
   rootr ask <question> [--workspace <w>]           GraphRAG 질의응답 (RCA), 인용 포함 출력
   rootr db create [--file <spec.json>] [--parent <path|id>]  표(DATABASE) 생성 — 컬럼 순서 그대로, 행까지 한 번에
-  rootr db rows <path|id> [--body] [--json]        표의 행 목록 (--body: 상세 내용까지)
+  rootr db rows <path|id> [--body] [--backlinks] [--json]        표의 행 목록 (--body: 상세 내용까지, --backlinks: 나를 가리키는 다른 표의 행까지)
   rootr db lock <path|id> [--schema managers] [--rows own] [--locked "승인,점수"]  표 자물쇠 보기·걸기
   rootr db notify <path|id> [--file rules.json] [--clear]  표 알림 규칙 보기·저장
   rootr db row-add <path|id> --values '<json>' [--body <md>|--body-file <f>]  행 추가(상세 내용 포함)
@@ -1301,10 +1301,10 @@ async function cmdDbNotify(args) {
 
 async function cmdDbRows(args) {
   const target = args._[1];
-  if (!target) throw new Error('사용법: rootr db rows <path|id> [--body] [--json]');
+  if (!target) throw new Error('사용법: rootr db rows <path|id> [--body] [--backlinks] [--json]');
   const client = makeClient();
   const id = await resolveDatabaseId(client, target);
-  const rows = await client.listRows(id, { withBody: !!args.body });
+  const rows = await client.listRows(id, { withBody: !!args.body, backlinks: !!args.backlinks });
   if (args.json) {
     console.log(JSON.stringify(rows, null, 2));
     return;
@@ -1317,6 +1317,12 @@ async function cmdDbRows(args) {
     if (args.body && row.body) {
       for (const line of String(row.body).trimEnd().split('\n')) console.log(`    ${line}`);
     }
+    // BACKLINK — "나를 가리키는 다른 표의 행" 목록(있을 때만 표시).
+    if (args.backlinks && row.backlinks && Object.keys(row.backlinks).length) {
+      for (const [refDbId, group] of Object.entries(row.backlinks)) {
+        console.log(`    ← ${refDbId} (${group.propName}): ${group.rowIds.join(', ')}`);
+      }
+    }
   }
 }
 

package/lib/client.js

@@ -322,6 +322,29 @@ export class RootrClient {
     return this.request(`/documents/${encodeURIComponent(id)}/versions${qs}`);
   }
 
+  /** 특정 버전의 본문을 그대로 읽는다(되돌리기 전에 무엇이 들었는지 확인용). */
+  async getDocumentVersion(id, versionId) {
+    return this.request(
+      `/documents/${encodeURIComponent(id)}/versions/${encodeURIComponent(versionId)}`,
+    );
+  }
+
+  /**
+   * DOC-RESTORE — **문서를 예전 버전으로 되돌린다.**
+   *
+   * 예전에는 목록 조회(getDocumentVersions)만 있고 되돌리는 문이 없었다. 그래서
+   * AI가 잘못 덮어써 내용이 통째로 날아가도 "되돌려 달라"는 부탁을 아무도 수행할
+   * 수 없었다 — 고객이 실제로 겪었다(2026-08-31 에이랩스 피드백: 일간 업무 일지
+   * 취합 문서의 대부분이 사라졌는데 AI가 복구하지 못함). 버전은 서버에 이미 다
+   * 쌓여 있었고, 부를 방법만 없었다.
+   */
+  async restoreDocumentVersion(id, versionId) {
+    return this.request(
+      `/documents/${encodeURIComponent(id)}/versions/${encodeURIComponent(versionId)}/restore`,
+      { method: 'POST' },
+    );
+  }
+
   /** Move a node to the trash (recoverable). */
   async deleteNode(id) {
     return this.request(`/nodes/${encodeURIComponent(id)}`, { method: 'DELETE' });
@@ -480,6 +503,23 @@ export class RootrClient {
     });
   }
 
+  /**
+   * WS-CLEANUP — **자기가 만든 잔해를 자기가 치울 수 있게.**
+   *
+   * 짓다가 실패하면 빈 워크스페이스가 남는데, 지우는 문이 없어서 에이전트가
+   * 치우지 못했다. 무료 한도가 5개라 몇 번 실패하면 사용자가 바로 막힌다
+   * (2026-08-30 실측: 치과 3개·아파트 4개가 잔해로 남음).
+   *
+   * 이름을 그대로 다시 적게 하는 것은 서버가 요구하는 안전장치다 — 지울 것을
+   * 정말 보고 있는지 확인한다.
+   */
+  async deleteWorkspace({ workspaceId, confirmName }) {
+    return this.request(`/workspaces/${workspaceId}`, {
+      method: 'DELETE',
+      body: { confirmName },
+    });
+  }
+
   /**
    * Check a designed tree BEFORE building it — the compiler pass of scaffolding.
    * Needs no workspace, creates nothing. Returns { score, counts, findings, summary }.
@@ -779,9 +819,15 @@ export class RootrClient {
   /**
    * All rows of a database, in position order. Returns the raw rows array.
    * DB-BODY — `withBody` 를 주면 행마다 상세 내용(본문 메모)까지 함께 온다.
+   * BACKLINK — `backlinks` 를 주면 각 행에 "나를 가리키는 다른 표의 행" 정보
+   * (`{ [referrerDatabaseId]: { propName, rowIds } }`)가 함께 붙는다. 기본은 꺼져
+   * 있다(필드 자체가 없다).
    */
-  async listRows(databaseId, { withBody = false } = {}) {
-    const query = withBody ? '?body=1' : '';
+  async listRows(databaseId, { withBody = false, backlinks = false } = {}) {
+    const params = [];
+    if (withBody) params.push('body=1');
+    if (backlinks) params.push('backlinks=1');
+    const query = params.length ? `?${params.join('&')}` : '';
     const data = await this.request(`/databases/${encodeURIComponent(databaseId)}/rows${query}`);
     if (Array.isArray(data)) return data;
     if (data && Array.isArray(data.rows)) return data.rows;

package/lib/mcp-tools/databases.js

@@ -430,13 +430,21 @@ export function registerDatabaseTools(server) {
           .boolean()
           .optional()
           .describe("true → also return each row's detail body (the note under a card). Off by default."),
+        backlinks: z
+          .boolean()
+          .optional()
+          .describe(
+            'true → also return each row\'s backlinks: other databases whose relation column points at ' +
+              'this row, as `{ [referrerDatabaseId]: { propName, rowIds } }`. Off by default (no field at all).',
+          ),
       },
     },
-    async ({ databaseId, includeBody }) => {
+    async ({ databaseId, includeBody, backlinks }) => {
       try {
         const client = makeClient();
         const rows = await client.listRows(await resolveNodeId(client, databaseId), {
           withBody: includeBody === true,
+          backlinks: backlinks === true,
         });
         return jsonResult({ rows });
       } catch (err) {

package/lib/mcp-tools/issues.js

@@ -148,8 +148,9 @@ export function registerIssueTools(server) {
     {
       title: 'Comment on an issue',
       description:
-        'Add a comment to a Rootr (루터) issue within its tracker. Comments carry a user identity, ' +
-        'so this requires an ACCOUNT key (PAT) as ROOTR_API_KEY — a workspace key gets a 403.',
+        'Add a comment to a Rootr (루터) issue within its tracker. Comments carry a user identity: ' +
+        'the comment is posted as the person the ROOTR_API_KEY belongs to. Both an account key (PAT) and a ' +
+        'workspace key work, since a workspace key is bound to the member who minted it.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         trackerId: z.string().describe(`Issue tracker node id${NODE_TARGET_HINT}`),

package/lib/mcp-tools/misc.js

@@ -31,6 +31,65 @@ export function registerMiscTools(server) {
     },
   );
 
+  /**
+   * DOC-RESTORE — **되돌리기.** 목록만 있고 되돌리는 문이 없어서, AI가 잘못
+   * 덮어써 내용이 날아가도 아무도 복구할 수 없었다(2026-08-31 에이랩스 피드백:
+   * "AI에게 이전 버전으로 돌려달라고 했지만 불가능"). 버전은 서버에 이미 쌓여
+   * 있었고, 부를 방법만 없었다.
+   */
+  server.registerTool(
+    'rootr_read_document_version',
+    {
+      title: 'Read one saved version of a document',
+      description:
+        'Read the full saved body of ONE past version of a Rootr (루터) document. Use this before ' +
+        'rootr_restore_document_version to confirm the version actually holds the content the user wants back — ' +
+        'restoring is a write, so look first. Get version ids from rootr_document_versions.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        versionId: z.string().describe('Version id from rootr_document_versions'),
+      },
+    },
+    async ({ target, versionId }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.getDocumentVersion(id, versionId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_restore_document_version',
+    {
+      title: 'Restore a document to an earlier version',
+      description:
+        'Roll a Rootr (루터) document back to one of its saved versions — the recovery path when an edit ' +
+        '(yours or anyone else\'s) destroyed content. WORKFLOW: rootr_document_versions to list, ' +
+        'rootr_read_document_version to confirm the right one, then restore. The current body is itself saved ' +
+        'as a new version first, so restoring is reversible — but it DOES overwrite what is there now, so ' +
+        'never guess at the version id. If the user says "undo what you just did" or "bring back the old ' +
+        'content", this is the tool.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        versionId: z.string().describe('Version id to restore, from rootr_document_versions'),
+      },
+    },
+    async ({ target, versionId }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.restoreDocumentVersion(id, versionId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_update_node',
     {

package/lib/mcp-tools/workspaces.js

@@ -223,6 +223,46 @@ export function registerWorkspaceTools(server) {
     },
   );
 
+  /**
+   * WS-CLEANUP — **짓다 실패해서 남은 빈 워크스페이스를 에이전트가 치울 수 있게.**
+   *
+   * 스캐폴딩이 중간에 실패하면 껍데기만 남는데 지우는 문이 없었다. 무료 한도가
+   * 5개라 몇 번 실패하면 사용자가 바로 막히고, 그 잔해를 사람이 화면에서 하나씩
+   * 지워야 했다(2026-08-30 실측: 치과 3개·아파트 4개).
+   *
+   * 이름을 그대로 다시 적게 한다 — 서버가 요구하는 안전장치이자, 모델이 엉뚱한
+   * 워크스페이스를 지목했을 때 걸리는 그물이다.
+   */
+  server.registerTool(
+    'rootr_delete_workspace',
+    {
+      title: 'Delete a workspace you created (cleanup after a failed scaffold)',
+      description:
+        'Permanently delete a Rootr (루터) workspace. Intended for cleaning up EMPTY leftovers from a scaffold ' +
+        'run that failed halfway — the free plan allows only a handful of workspaces, so abandoned shells block ' +
+        'the user from trying again. Requires OWNER on that workspace, and you must pass `confirmName` exactly ' +
+        'matching the workspace name (call rootr_workspaces first to read it). THIS CANNOT BE UNDONE: everything ' +
+        'inside is removed. Never call this on a workspace that holds the user\'s real work — if you did not ' +
+        'create it in this session, ask the user first.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        workspaceId: z.string().describe('Id of the workspace to delete'),
+        confirmName: z
+          .string()
+          .describe('The workspace name, typed again exactly — the server rejects the call if it does not match'),
+      },
+    },
+    async ({ workspaceId, confirmName }) => {
+      try {
+        const client = makeClient();
+        await client.deleteWorkspace({ workspaceId, confirmName });
+        return jsonResult({ deleted: true, workspaceId });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_scaffold_review',
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
   "type": "module",
   "bin": {