rootr-cli 0.6.0 → 0.7.0

package/README.md

@@ -169,9 +169,16 @@ rootr config --add-key rootr_xxx --label "영업팀"
 rootr config                       # 등록된 키 목록 확인
 ```
 
-이후 MCP에서 `rootr_use_workspace` 도구로 **이름이나 id**를 주면 활성 워크스페이스가
-바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정 키(PAT)를 쓰면
-소속된 어느 워크스페이스로든 바로 전환됩니다.
+이후 MCP에서 `rootr_use_workspace` 도구로 **이름·id·루터 웹 주소** 중 아무거나 주면 활성
+워크스페이스가 바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정
+키(PAT)를 쓰면 소속된 어느 워크스페이스로든 바로 전환됩니다.
+
+워크스페이스 키는 자기 워크스페이스 밖에서는 열리지 않습니다 — `rootr ws`(=`rootr_workspaces`)
+목록에 보여도 접근은 안 되는 경우가 있어, 등록된 키가 워크스페이스 키뿐이면 목록에
+`[등록된 키로는 접근 불가]`를 함께 표시합니다.
+
+문서를 가리키는 웹 주소(`https://rootr.io/ko/w/<ws>/d/<doc>`)는 `rootr_read` 등 모든 노드
+인자에 그대로 붙여넣을 수 있습니다. 다른 워크스페이스의 주소면 "먼저 전환하라"고 알려줍니다.
 
 > 원격 커넥터(`https://rootr.io/mcp`)는 승인할 때 고른 워크스페이스 하나에만 연결됩니다.
 > 다른 워크스페이스가 필요하면 그 워크스페이스로 커넥터를 새로 발급하세요.

package/bin/rootr.js

@@ -5,7 +5,7 @@ import { dirname, join, basename, extname } from 'node:path';
 
 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';
+import { resolveTarget, requireResolved, resolveMoveDestination } from '../lib/resolve.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -19,6 +19,7 @@ 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 mv <path|id> <새 경로|폴더 id>              문서/폴더 이동 및/또는 이름 변경
   rootr rm <path|id> [--yes]                       문서/폴더를 휴지통으로 이동 (복구 가능)
   rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]  파일 업로드(+문서에 삽입)
   rootr ws                                         내 워크스페이스 목록 (id\tname)
@@ -218,6 +219,21 @@ async function cmdSearch(args) {
   }
 }
 
+async function cmdMv(args) {
+  const source = args._[0];
+  const dest = args._[1];
+  if (!source || !dest) throw new Error('사용법: rootr mv <path|id> <새 경로|폴더 id>');
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, source);
+  const id = requireResolved(resolved);
+
+  const { parentId, name } = await resolveMoveDestination(client, dest);
+  const updated = await client.updateNode(id, { parentId, name });
+
+  console.log(`이동했습니다: ${resolved.path || id} → ${updated.path || dest}`);
+}
+
 async function cmdRm(args) {
   const target = args._[0];
   if (!target) throw new Error('사용법: rootr rm <path|id> [--yes]');
@@ -405,6 +421,8 @@ async function main() {
       return cmdSearch(args);
     case 'attach':
       return cmdAttach(args);
+    case 'mv':
+      return cmdMv(args);
     case 'rm':
       return cmdRm(args);
     case 'ws':

package/lib/client.js

@@ -33,6 +33,19 @@ export class RootrApiError extends Error {
 }
 
 function hintFor(status, body) {
+  // WS-SCOPE — the single most confusing failure: a workspace-scoped key used
+  // against another workspace. The API says so precisely; without repeating it
+  // as an instruction the assistant reads the generic hint below and starts
+  // guessing at invitations/permissions for a workspace the user already owns.
+  const detail = body && (body.message || body.error || '');
+  if (status === 403 && typeof detail === 'string' && /does not belong to this workspace/i.test(detail)) {
+    return (
+      '이 키는 다른 워크스페이스 전용 키입니다. 목록에 보인다고 접근되는 것은 아닙니다.\n' +
+      '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하거나, ' +
+      '그 워크스페이스용 키를 `rootr config --add-key <키> --workspace <워크스페이스 id>` 로 추가하세요. ' +
+      '(rootr_workspaces 로 어떤 워크스페이스가 실제로 열리는지 확인할 수 있습니다.)'
+    );
+  }
   if (status === 401 || status === 403) {
     return (
       'API 키 또는 워크스페이스 스코프를 확인하세요 (rootr config로 현재 설정 확인). ' +
@@ -298,6 +311,14 @@ export class RootrClient {
     return this.request(`/nodes/${encodeURIComponent(id)}`, { method: 'DELETE' });
   }
 
+  /** Rename and/or move a node. `parentId: null` moves it to the workspace root. */
+  async updateNode(id, { name, icon, tags, parentId, position } = {}) {
+    return this.request(`/nodes/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      body: { name, icon, tags, parentId, position },
+    });
+  }
+
   // ---- Comments / publishing / duplication (document-level extras) --------
 
   /** Comments carry a user identity — needs an account key (PAT) or user session; workspace keys 403. */

package/lib/mcp-tools/documents.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 import { RootrApiError } from '../client.js';
-import { resolveTarget, requireResolved } from '../resolve.js';
+import { resolveTarget, requireResolved, resolveMoveDestination } from '../resolve.js';
 import { textResult, jsonResult, errorResult, makeClient } from './shared.js';
 
 /** Registers the original 6 document tools: list/read/append/edit/write/search. */
@@ -54,7 +54,7 @@ export function registerDocumentTools(server) {
         'Read a document before editing or appending to it so you know its current structure.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id'),
+        target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id, or a full rootr.io URL'),
       },
     },
     async ({ target }) => {
@@ -80,7 +80,7 @@ export function registerDocumentTools(server) {
         'you just need to add new information (log entries, notes, findings) to an existing document.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         content: z.string().describe('Markdown content to append'),
         underHeading: z
           .string()
@@ -115,7 +115,7 @@ export function registerDocumentTools(server) {
         'you are only adding new content.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         find: z.string().describe('Exact existing text to find (must be unique unless replaceAll is set)'),
         replace: z.string().describe('Text to replace it with'),
         replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness'),
@@ -144,7 +144,7 @@ export function registerDocumentTools(server) {
         'as ifMatch to avoid clobbering concurrent changes. Prefer rootr_append or rootr_edit for incremental changes.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/", created if missing) or node id'),
+        target: z.string().describe('Document path (starting with "/", created if missing) or node id, or a full rootr.io URL'),
         content: z.string().describe('Full new markdown content for the document'),
         ifMatch: z
           .string()
@@ -216,7 +216,7 @@ export function registerDocumentTools(server) {
         '(including remote-connector tokens) gets a 403; fall back to rootr_append in that case.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         body: z.string().describe('Comment text (markdown)'),
         blockId: z.string().optional().describe('Block id to anchor the comment to'),
         parentId: z.string().optional().describe('Parent comment id, to reply in a thread'),
@@ -241,7 +241,7 @@ export function registerDocumentTools(server) {
         'List the comment threads on a Rootr (루터) document, optionally filtered to one block. Works with any key.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         blockId: z.string().optional().describe('Only comments anchored to this block'),
       },
     },
@@ -270,7 +270,7 @@ export function registerDocumentTools(server) {
         'Returns the slug/URL. Check rootr_document_public_status first; unpublish or change settings via rootr_set_document_public.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
       },
     },
     async ({ target }) => {
@@ -297,7 +297,7 @@ export function registerDocumentTools(server) {
         'Owner-level action (MANAGE): works with an account key (PAT), not with workspace-scoped/connector tokens.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         isPublic: z.boolean().optional().describe('false to unpublish, true to re-enable'),
         allowCommits: z.boolean().optional().describe('Whether public readers can propose git-style edit suggestions'),
         expiresAt: z
@@ -354,7 +354,7 @@ export function registerDocumentTools(server) {
       description: 'Whether a Rootr (루터) document is published, and at which public slug/URL.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
       },
     },
     async ({ target }) => {
@@ -392,4 +392,33 @@ export function registerDocumentTools(server) {
       }
     },
   );
+
+  server.registerTool(
+    'rootr_move_node',
+    {
+      title: 'Move or rename a Rootr node',
+      description:
+        'Move a Rootr (루터) document or folder to a different folder, and/or rename it. This is the only way ' +
+        'to relocate a node that already exists — creating with a target path only works up front. ' +
+        '`destination` accepts: a folder id, a folder path ending in "/" (moves into it, keeps the name), ' +
+        'a full new path incl. name (moves and renames in one call), or "/" for the workspace root.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Node path (starting with "/") or node id to move'),
+        destination: z
+          .string()
+          .describe('Destination folder id or path — see description for the accepted forms'),
+      },
+    },
+    async ({ target, destination }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        const { parentId, name } = await resolveMoveDestination(client, destination);
+        return jsonResult(await client.updateNode(id, { parentId, name }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/shared.js

@@ -8,7 +8,7 @@ import { resolveTarget, requireResolved } from '../resolve.js';
  * takes a path too, exactly like rootr_read, so an agent that only knows where
  * a node lives in the tree never has to hunt for its uuid.
  */
-export const NODE_TARGET_HINT = ', or its path starting with "/"';
+export const NODE_TARGET_HINT = ', or its path starting with "/", or a full rootr.io URL';
 
 /**
  * Resolve a path-or-id argument to a node id. Paths go through the by-path

package/lib/mcp-tools/workspaces.js

@@ -4,6 +4,7 @@ import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } fro
 import { loadConfig, saveConfig, keyForWorkspace, upsertKey } from '../config.js';
 import { currentClientOverride } from '../context.js';
 import { RootrClient } from '../client.js';
+import { parseRootrUrl } from '../resolve.js';
 
 /**
  * Scaffold `tree` argument schema. Declared as an ARRAY of node objects so MCP
@@ -61,33 +62,54 @@ export function registerWorkspaceTools(server) {
         '(A hosted/remote connector is bound to a single workspace at consent time and cannot switch.)',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        workspace: z.string().describe('Workspace id, or its name (case-insensitive)'),
+        workspace: z
+          .string()
+          .describe('Workspace id, its name (case-insensitive), or a rootr.io URL to a page in it'),
       },
     },
     async ({ workspace }) => {
       try {
+        const wantedUrl = parseRootrUrl(workspace);
+        const wanted = (wantedUrl ? wantedUrl.workspaceId : workspace).trim();
+        const wantedLower = wanted.toLowerCase();
+
         if (currentClientOverride()) {
+          const hosted = currentClientOverride();
+          if (wanted === hosted.workspace) {
+            return textResult(`이미 이 워크스페이스(${hosted.workspace})에 연결되어 있습니다. 그대로 진행하세요.`);
+          }
           return errorResult(
             new Error(
-              '이 원격 연결은 승인 시 지정한 워크스페이스 하나에만 연결됩니다. ' +
-                '다른 워크스페이스를 쓰려면 설정>연동에서 그 워크스페이스로 커넥터를 새로 발급하세요.',
+              `이 원격 커넥터는 워크스페이스 ${hosted.workspace} 하나에만 연결되어 있어 ${wanted} 로 전환할 수 없습니다.\n` +
+                '조치: rootr.io > 설정 > 연동에서 그 워크스페이스로 커넥터를 하나 더 발급한 뒤 다시 시도하세요. ' +
+                '(사용자가 직접 해야 하는 작업입니다.)',
             ),
           );
         }
-        const wanted = workspace.trim();
-        const wantedLower = wanted.toLowerCase();
         const candidates = candidateClients();
+        if (!candidates.length) {
+          return errorResult(
+            new Error(
+              '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n' +
+                '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급받아 `rootr config --api-key <키>` 로 등록하세요.',
+            ),
+          );
+        }
 
         // Step 1 — resolve the name/id to a real workspace. /workspaces lists
         // the KEY OWNER's workspaces, so any key can answer this.
         let target = null;
+        let listed = 0;
+        const visible = [];
         for (const candidate of candidates) {
           let list = [];
           try {
             list = await candidate.client.listWorkspaces();
+            listed += 1;
           } catch {
             continue;
           }
+          for (const w of list) if (!visible.some((v) => v.id === w.id)) visible.push(w);
           const hit = list.find(
             (w) => w.id === wanted || (w.name || '').toLowerCase() === wantedLower || (w.slug || '').toLowerCase() === wantedLower,
           );
@@ -102,32 +124,69 @@ export function registerWorkspaceTools(server) {
         // owner's workspaces while being rejected by every one but its own.
         // Only a workspace-scoped call proves the binding.
         let usable = null;
+        let lastRejection = null;
         if (target) {
           for (const candidate of candidates) {
             try {
               await candidate.client.request(`/workspaces/${encodeURIComponent(target.id)}`);
               usable = candidate;
               break;
-            } catch {
+            } catch (err) {
+              lastRejection = err;
               continue;
             }
           }
         }
-        const match = target && usable ? { workspace: target, candidate: usable } : null;
+        // Listing can be unavailable (a legacy key with no owner attached gets
+        // 403 on /workspaces) — but that key may still be able to open the very
+        // workspace being asked for. Ask the workspace directly before giving up.
+        let match = target && usable ? { workspace: target, candidate: usable } : null;
+        if (!match && !target) {
+          for (const candidate of candidates) {
+            try {
+              const ws = await candidate.client.request(`/workspaces/${encodeURIComponent(wanted)}`);
+              if (ws && ws.id) {
+                match = { workspace: ws, candidate };
+                break;
+              }
+            } catch (err) {
+              lastRejection = err;
+            }
+          }
+        }
 
+        // Listed-but-unreachable is the common real case: the workspace IS the
+        // user's, but every registered key is workspace-scoped to another one.
+        // Name that cause explicitly — a vague "no key" message makes the
+        // assistant invent permission problems (asking for an invite to the
+        // user's OWN workspace).
         if (target && !usable) {
+          const scoped = lastRejection && lastRejection.status === 403;
           return errorResult(
             new Error(
-              `"${target.name || target.id}" 워크스페이스에 접근할 수 있는 키가 없습니다. ` +
-                '그 워크스페이스용 키를 등록하세요: rootr config --add-key <키>',
+              `"${target.name || target.id}" (${target.id}) 는 접근 권한 목록에는 있지만, 등록된 키로는 열 수 없습니다` +
+                `${target.role ? ` (내 역할: ${target.role})` : ''}.\n` +
+                (scoped
+                  ? '원인: 지금 등록된 키가 다른 워크스페이스 전용 키입니다 (워크스페이스 키는 자기 워크스페이스 밖에서 403).\n'
+                  : `원인: ${lastRejection ? lastRejection.message : '알 수 없음'}\n`) +
+                '조치 (둘 중 하나, 사용자가 직접):\n' +
+                '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
+                `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\``,
             ),
           );
         }
         if (!match) {
+          const seenList = visible.length
+            ? `\n지금 보이는 워크스페이스: ${visible.map((w) => `${w.name || w.slug || ''}(${w.id})`).join(', ')}`
+            : '';
           return errorResult(
             new Error(
-              `"${wanted}" 워크스페이스를 찾지 못했습니다. rootr_workspaces로 접근 가능한 목록을 확인하세요. ` +
-                '목록에 없다면 그 워크스페이스용 키가 등록되지 않은 것입니다 (rootr config --add-key <키>).',
+              listed === 0
+                ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키가 만료/취소되었거나 목록 권한이 없음).\n' +
+                  '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 새로 발급해 `rootr config --api-key <키>` 로 등록하세요.'
+                : `"${wanted}" 워크스페이스가 내 소속 목록에 없습니다.${seenList}\n` +
+                  '조치: 주소가 맞는지 확인하고, 다른 계정의 워크스페이스라면 그 계정으로 발급한 키를 ' +
+                  '`rootr config --add-key <키>` 로 등록하세요.',
             ),
           );
         }
@@ -161,24 +220,79 @@ export function registerWorkspaceTools(server) {
     async () => {
       try {
         const hosted = currentClientOverride();
-        const active = hosted ? hosted.workspace : loadConfig().workspace;
+        // Hosted (remote connector) requests have no ~/.rootr/config.json to
+        // read — candidateClients() would return nothing and the tool used to
+        // answer "(no workspaces visible to this key)" even though the
+        // connector is happily bound to one workspace. Ask the API about the
+        // bound workspace directly instead. (A connector token has no userId,
+        // so GET /workspaces is not open to it — GET /workspaces/{id} is.)
+        if (hosted) {
+          let name = '';
+          try {
+            const ws = await hosted.request(`/workspaces/${encodeURIComponent(hosted.workspace)}`);
+            name = ws.name || ws.slug || '';
+          } catch {
+            // fall through: the id alone is still more useful than nothing
+          }
+          return textResult(
+            `* ${hosted.workspace}\t${name}\n\n` +
+              '이 원격 커넥터는 위 워크스페이스 하나에만 연결되어 있습니다 (승인 시 선택). ' +
+              '다른 워크스페이스가 필요하면 rootr.io > 설정 > 연동에서 그 워크스페이스로 커넥터를 하나 더 발급하세요.',
+          );
+        }
+        const cfg = loadConfig();
+        const active = cfg.workspace;
+        // Probing costs one API call per workspace (they count against the
+        // daily read quota), so only do it in the case it actually diagnoses:
+        // no account key registered, i.e. every credential here is scoped to
+        // one workspace and most of the list is unusable.
+        const probeReachability = !cfg.apiKey && (cfg.keys || []).length > 0;
         const seen = new Map();
-        for (const { client } of candidateClients()) {
+        const reached = [];
+        let failures = 0;
+        for (const { client, label } of candidateClients()) {
           let list = [];
           try {
             list = await client.listWorkspaces();
           } catch {
+            failures += 1;
             continue; // a revoked/foreign key shouldn't hide the others
           }
           for (const w of list) if (!seen.has(w.id)) seen.set(w.id, w);
+          // Which workspace each key can actually WRITE in is what decides
+          // whether rootr_use_workspace will succeed — listing does not.
+          for (const w of probeReachability ? list.slice(0, 12) : []) {
+            if (reached.includes(w.id)) continue;
+            try {
+              await client.request(`/workspaces/${encodeURIComponent(w.id)}`);
+              reached.push(w.id);
+            } catch {
+              // scoped key rejected here; another key may still cover it
+            }
+          }
+          void label;
         }
         const rows = [...seen.values()].map(
-          (w) => `${w.id === active ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}`,
+          (w) =>
+            `${w.id === active ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}` +
+            (!probeReachability || reached.includes(w.id) ? '' : '\t[등록된 키로는 접근 불가]'),
         );
+        if (!rows.length) {
+          return textResult(
+            failures
+              ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키 만료/취소 가능성).\n' +
+                  '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.'
+              : '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n' +
+                  '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.',
+          );
+        }
+        const blocked = rows.some((r) => r.includes('접근 불가'));
         return textResult(
-          rows.length
-            ? `${rows.join('\n')}\n\n(* = current; switch with rootr_use_workspace)`
-            : '(no workspaces visible to this key)',
+          `${rows.join('\n')}\n\n(* = 현재 워크스페이스, rootr_use_workspace 로 전환)` +
+            (blocked
+              ? '\n"접근 불가" = 내 소속 워크스페이스지만 등록된 키가 워크스페이스 전용이라 못 엽니다. ' +
+                '계정 키(PAT)를 등록하면 전부 열립니다: rootr.io > 설정 > API 키 → `rootr config --api-key <키>`'
+              : ''),
         );
       } catch (err) {
         return errorResult(err);

package/lib/resolve.js

@@ -1,15 +1,67 @@
 import { RootrApiError } from './client.js';
 
+/**
+ * Web-app route segments that address a single node: rootr.io/{locale?}/w/{ws}/{kind}/{id}
+ * (mirrors frontend/src/app/w/[ws]/*). Anything else under /w/{ws} is a
+ * workspace-level screen (graph, trash, settings …) with no node to resolve.
+ */
+const NODE_URL_KINDS = new Set(['d', 'db', 'sheet', 'whiteboard', 'log', 'form', 'deck', 'rec', 'issues', 'crm']);
+
+/**
+ * Parse a Rootr web URL an agent was handed by a human ("여기 봐줘: https://rootr.io/ko/w/…/d/…").
+ * Without this every such paste is treated as a node id and comes back as a
+ * bare "Not found", which reads like a permission problem and sends the
+ * assistant guessing. Returns null for anything that isn't a Rootr URL.
+ */
+export function parseRootrUrl(target) {
+  if (typeof target !== 'string' || !/^https?:\/\//i.test(target)) return null;
+  let url;
+  try {
+    url = new URL(target);
+  } catch {
+    return null;
+  }
+  const segments = url.pathname.split('/').filter(Boolean);
+  const at = segments.indexOf('w');
+  if (at === -1 || !segments[at + 1]) return null;
+  const kind = segments[at + 2];
+  const id = NODE_URL_KINDS.has(kind) ? segments[at + 3] : undefined;
+  return { workspaceId: segments[at + 1], nodeId: id, kind: id ? kind : undefined };
+}
+
 /**
  * Resolve a CLI/MCP "target" argument to a node id.
- * If it starts with '/', treat it as a path and look it up via by-path
- * (requires a workspace to be configured). Otherwise treat it as an id already.
+ * A full rootr.io URL is unpacked to the node id it points at; a value
+ * starting with '/' is a tree path looked up via by-path (requires a
+ * workspace); anything else is already an id.
  *
  * Returns { id, existed, path } where existed indicates whether the path
  * resolved to an existing node (always true for id-form targets, since we
  * don't verify those against the API).
  */
 export async function resolveTarget(client, target) {
+  const url = parseRootrUrl(target);
+  if (url) {
+    if (!url.nodeId) {
+      throw new RootrApiError(`이 주소는 문서가 아니라 워크스페이스 화면을 가리킵니다: ${target}`, {
+        hint: `해당 워크스페이스로 전환하려면 rootr_use_workspace 에 ${url.workspaceId} 를 넘기세요.`,
+      });
+    }
+    // The URL carries the workspace it lives in, so a mismatch is knowable
+    // BEFORE the API answers 404 — say so instead of letting it look missing.
+    if (client.workspace && url.workspaceId !== client.workspace) {
+      throw new RootrApiError(
+        `이 주소는 다른 워크스페이스(${url.workspaceId})의 노드입니다. 현재 활성 워크스페이스는 ${client.workspace} 입니다.`,
+        {
+          hint:
+            `먼저 rootr_use_workspace 로 ${url.workspaceId} 로 전환하세요. ` +
+            '전환이 안 되면 그 워크스페이스에 쓸 수 있는 키가 없는 것입니다 (rootr_workspaces 로 확인).',
+        },
+      );
+    }
+    return { id: url.nodeId, existed: true, path: undefined, url };
+  }
+
   if (!target.startsWith('/')) {
     return { id: target, existed: true, path: undefined };
   }
@@ -28,3 +80,48 @@ export function requireResolved(resolved) {
   }
   return resolved.id;
 }
+
+/**
+ * Resolve a "move destination" argument (used by `rootr mv` and
+ * `rootr_move_node`) to { parentId, name }.
+ * - a bare id (no leading '/'): move into that folder, keep the current name.
+ * - a path ending in '/', or a path that already resolves to a non-DOCUMENT
+ *   node: move into that folder, keep the current name.
+ * - any other '/'-prefixed path: treated as the full destination path
+ *   (parent + new name), so the same call can rename and move at once.
+ * - '/': move to the workspace root.
+ */
+export async function resolveMoveDestination(client, dest) {
+  if (!dest.startsWith('/')) {
+    return { parentId: dest };
+  }
+  if (dest === '/') {
+    return { parentId: null };
+  }
+
+  const trailingSlash = dest.endsWith('/');
+  const destPath = trailingSlash ? dest.slice(0, -1) : dest;
+  const existing = await client.getNodeByPath(destPath);
+  const existingNode = existing && (existing.node || existing);
+  if (existingNode && existingNode.type !== 'DOCUMENT') {
+    return { parentId: existingNode.id };
+  }
+  if (trailingSlash) {
+    throw new RootrApiError(`대상 폴더를 찾을 수 없습니다: ${destPath}`);
+  }
+
+  const lastSlash = destPath.lastIndexOf('/');
+  const parentPath = lastSlash > 0 ? destPath.slice(0, lastSlash) : '';
+  const name = destPath.slice(lastSlash + 1);
+  if (!name) throw new RootrApiError(`잘못된 대상 경로: ${dest}`);
+
+  if (!parentPath) {
+    return { parentId: null, name };
+  }
+  const parent = await client.getNodeByPath(parentPath);
+  const parentNode = parent && (parent.node || parent);
+  if (!parentNode) {
+    throw new RootrApiError(`대상 폴더를 찾을 수 없습니다: ${parentPath}`);
+  }
+  return { parentId: parentNode.id, name };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.6.0",
+  "version": "0.7.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": {
@@ -37,5 +37,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.8"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
   }
 }