rootr-cli 0.19.0 → 0.22.0

package/lib/credentials.js

@@ -15,6 +15,7 @@ import { t as tr } from './i18n.js';
 export function candidateClients(cfg = loadConfig()) {
   const out = [];
   const seen = new Set();
+  // (sessionKeys — 아래 rememberSessionKey 참고 — 는 맨 뒤에 붙는다.)
   if (cfg.apiKey) {
     seen.add(cfg.apiKey);
     out.push({ apiKey: cfg.apiKey, label: 'default', client: new RootrClient({ ...cfg, apiKey: cfg.apiKey }) });
@@ -24,9 +25,37 @@ export function candidateClients(cfg = loadConfig()) {
     seen.add(k.apiKey);
     out.push({ apiKey: k.apiKey, label: k.label || k.workspace || 'key', client: new RootrClient({ ...cfg, apiKey: k.apiKey }) });
   }
+  for (const apiKey of sessionKeys) {
+    if (seen.has(apiKey)) continue;
+    seen.add(apiKey);
+    out.push({ apiKey, label: 'session', ephemeral: true, client: new RootrClient({ ...cfg, apiKey }) });
+  }
   return out;
 }
 
+/**
+ * ISSUE-221 — keys this (long-running, stdio MCP) process was handed through
+ * the ROOTR_API_KEY env var and has since switched away from.
+ *
+ * rootr_use_workspace swaps process.env.ROOTR_API_KEY to the key that opens
+ * the target workspace. If the key it replaces lived only in the environment
+ * (the usual MCP client config: `env: { ROOTR_API_KEY, ROOTR_WORKSPACE }`),
+ * nothing else remembers it — so after A → B the server could no longer open
+ * A again ("none of the registered keys opens it"), although it was started
+ * with exactly that key. Keep such keys for the life of the process so the way
+ * back stays open.
+ *
+ * In memory only: an env-supplied secret is never written to
+ * ~/.rootr/config.json behind the user's back (rememberWorkspace skips
+ * `ephemeral` candidates). Never called on the hosted path — that one returns
+ * before any switch happens, so tenants cannot see each other's keys here.
+ */
+const sessionKeys = [];
+
+export function rememberSessionKey(apiKey) {
+  if (apiKey && !sessionKeys.includes(apiKey)) sessionKeys.push(apiKey);
+}
+
 /**
  * Collect every workspace the registered keys can see, and which of them a
  * key can actually open — listing is not a capability probe: a workspace key
@@ -155,22 +184,36 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
 
   if (target) {
     const scoped = lastRejection && lastRejection.status === 403;
-    // ISSUE-172 — `rootr config --add-key`/`--api-key` writes to
-    // ~/.rootr/config.json from a SEPARATE process. If this (MCP server)
-    // process was started with ROOTR_API_KEY set, config.js makes that env
-    // var win over anything just written to the file (see its ENV-WINS
-    // comment) — so the fix this message recommends silently does nothing
-    // until the server itself is restarted. Say so instead of pointing at a
-    // remedy that cannot take effect.
+    // ISSUE-172/221 — when this (MCP server) process was started with
+    // ROOTR_API_KEY set, config.js makes that env var win over the DEFAULT key
+    // in ~/.rootr/config.json (see its ENV-WINS comment), now and after every
+    // restart. So for such a server the usual first remedy (`rootr config
+    // --api-key <PAT>`) never takes effect — the PAT has to go into the MCP
+    // server's own env config. Extra keys (`--add-key`) are different: the
+    // file is re-read on every call and they are tried as candidates, so that
+    // remedy works at once, without a restart. (Measured 2026-10-09 against a
+    // real server: the earlier note had both of these the wrong way round.)
     const envPinned = !!process.env.ROOTR_API_KEY;
-    const restartNote = envPinned
-      ? tr(
-          '\n주의: 이 서버 프로세스는 ROOTR_API_KEY 환경변수로 키가 고정되어 있어, 위 명령으로 키를 추가해도 서버를 ' +
-            '재시작해야 반영됩니다 (같은 프로세스가 계속 돌아가는 동안은 파일에 새로 쓴 키를 읽지 않습니다).',
-          '\nNote: this server process has ROOTR_API_KEY pinned via env var, so adding a key with the command above ' +
-            'only takes effect after the server is restarted (it keeps reading the env-pinned key while running).',
-        )
-      : '';
+    const remediesKo = envPinned
+      ? '조치 (둘 중 하나, 사용자가 직접):\n' +
+        '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → MCP 서버 설정의 ROOTR_API_KEY 환경변수를 그 키로 바꾸고 ' +
+        '서버를 재시작 (이 서버는 ROOTR_API_KEY 환경변수의 키를 쓰므로, `rootr config --api-key` 로 파일에 적은 키는 ' +
+        '재시작해도 쓰이지 않습니다)\n' +
+        `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\` ` +
+        '(재시작 없이, 등록한 뒤 바로 다시 전환하면 됩니다)'
+      : '조치 (둘 중 하나, 사용자가 직접):\n' +
+        '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
+        `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\``;
+    const remediesEn = envPinned
+      ? 'Fix (either one, done by you):\n' +
+        '1) Create an account key (PAT) under rootr.io > Settings > API keys → put it in the ROOTR_API_KEY env var of ' +
+        'the MCP server config and restart the server (this server uses the key from ROOTR_API_KEY, so a key written ' +
+        'with `rootr config --api-key` is not used, even after a restart)\n' +
+        `2) Create a key for that workspace → \`rootr config --add-key <key> --workspace ${target.id}\` ` +
+        '(no restart needed — switch again right after registering it)'
+      : 'Fix (either one, done by you):\n' +
+        '1) Create an account key (PAT) under rootr.io > Settings > API keys → `rootr config --api-key <key>` (works everywhere)\n' +
+        `2) Create a key for that workspace → \`rootr config --add-key <key> --workspace ${target.id}\``;
     return {
       error: tr(
         `"${target.name || target.id}" (${target.id}) 는 접근 권한 목록에는 있지만, 등록된 키로는 열 수 없습니다` +
@@ -178,19 +221,13 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
           (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}\`` +
-          restartNote,
+          remediesKo,
         `"${target.name || target.id}" (${target.id}) is on your access list, but none of the registered keys opens it` +
           `${target.role ? ` (your role: ${target.role})` : ''}.\n` +
           (scoped
             ? 'Cause: the registered key belongs to a different workspace (a workspace key gets 403 outside its own).\n'
             : `Cause: ${lastRejection ? lastRejection.message : 'unknown'}\n`) +
-          'Fix (either one, done by you):\n' +
-          '1) Create an account key (PAT) under rootr.io > Settings > API keys → `rootr config --api-key <key>` (works everywhere)\n' +
-          `2) Create a key for that workspace → \`rootr config --add-key <key> --workspace ${target.id}\`` +
-          restartNote,
+          remediesEn,
       ),
     };
   }
@@ -222,7 +259,9 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
 /** Persist the switch: remember the workspace and which key covers it. */
 export function rememberWorkspace({ workspace, candidate }, cfg = loadConfig()) {
   saveConfig({ workspace: workspace.id });
-  if (candidate && candidate.apiKey !== cfg.apiKey) {
+  // `ephemeral` = a key that only ever lived in this process's environment (see
+  // rememberSessionKey) — it stays out of the config file.
+  if (candidate && candidate.apiKey !== cfg.apiKey && !candidate.ephemeral) {
     upsertKey({ apiKey: candidate.apiKey, workspace: workspace.id, label: candidate.label });
   }
 }

package/lib/mcp-tools/attachments.js

@@ -14,18 +14,41 @@ import {
   localFileArg,
 } from './shared.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
-import { RootrApiError } from '../client.js';
+import { RootrApiError, imageMarkdown } from '../client.js';
+
+// ISSUE-222 — 원격 커넥터에서 filePath 를 쓰려다 막힌 호출자가 막다른 길에 서지 않게, 거절하면서
+// 새 길(주소를 받아 직접 올리기)을 같이 알려 준다. 큰 파일은 base64Data 로도 못 싣는다.
+const PRESIGN_HINT =
+  '큰 파일은 rootr_create_upload_url 로 올리기 주소를 받아 파일 바이트를 그 주소에 직접 PUT 한 뒤 ' +
+  'rootr_complete_upload 를 부르세요 (파일 내용이 도구 호출에 실리지 않습니다).';
 
 /** Reads file bytes from a local path or a base64 string; exactly one must be given. */
 function readAttachmentBytes({ filePath, base64Data }) {
   // SEC-MCP-FILES — 원격 커넥터에서는 서버 파일을 읽게 되므로 읽기 전에 거절한다.
-  assertLocalFilesAllowed(filePath);
+  if (isHostedMcp() && filePath) {
+    throw new RootrApiError('원격 커넥터에서는 filePath 를 쓸 수 없습니다.', {
+      hint:
+        'filePath 는 MCP 서버가 도는 기계의 파일을 가리킵니다. 원격 커넥터에서는 그 기계가 Rootr 서버라 ' +
+        `쓸 수 없습니다 — 작은 파일은 내용을 base64Data 로 보내세요. ${PRESIGN_HINT}`,
+    });
+  }
+  assertLocalFilesAllowed(filePath); // 위에서 걸렀지만 두 겹으로 둔다
   if (filePath) return readFileSync(filePath);
   if (base64Data) return Buffer.from(base64Data, 'base64');
-  if (isHostedMcp()) throw new RootrApiError('base64Data 가 필요합니다 (원격 커넥터에서는 filePath 를 쓸 수 없습니다).');
+  if (isHostedMcp()) {
+    throw new RootrApiError('base64Data 가 필요합니다 (원격 커넥터에서는 filePath 를 쓸 수 없습니다).', {
+      hint: PRESIGN_HINT,
+    });
+  }
   throw new RootrApiError('filePath 또는 base64Data 중 하나가 필요합니다.');
 }
 
+/** 첨부 id 모양(UUID). 주소 칸에 들어가는 값이라 다른 모양은 서버에 보내지 않는다. */
+const ATTACHMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** 빈 값·공백뿐인 값은 받지 않는다(값 자체는 건드리지 않는다 — 앞뒤 공백도 이름의 일부일 수 있다). */
+const nonBlank = (what) => [(v) => typeof v === 'string' && v.trim().length > 0, `${what} must not be empty`];
+
 // 등록 시점(원격이면 요청마다)에 만든다 — 원격 커넥터에서는 filePath 칸이 스키마에서 빠진다.
 const buildUploadInputSchema = () => ({
   filename: z.string().describe('File name to store, e.g. "screenshot.png"'),
@@ -57,7 +80,9 @@ export function registerAttachmentTools(server) {
         '{ id, url, markdown, filename, mimeType, size } — `url` is the public, unauthenticated ' +
         '/attachments/{id}/raw link (renders in <img> tags and on published /p/ documents without login), and ' +
         '`markdown` is ready to paste into a document body (![alt](url)). For the common case of inserting an ' +
-        'image straight into a document, prefer rootr_attach_image_to_document instead.',
+        'image straight into a document, prefer rootr_attach_image_to_document instead. For a large file (or ' +
+        'over the remote connector, where filePath is not available), use rootr_create_upload_url → PUT → ' +
+        'rootr_complete_upload instead of inlining the bytes as base64Data.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: uploadInputSchema,
     },
@@ -75,7 +100,7 @@ export function registerAttachmentTools(server) {
         return jsonResult({
           id,
           url,
-          markdown: `![${filename}](${url})`,
+          markdown: imageMarkdown(filename, url),
           filename,
           mimeType,
           size: data.length,
@@ -120,7 +145,7 @@ export function registerAttachmentTools(server) {
         const data = readAttachmentBytes({ filePath, base64Data });
         const { id } = await client.uploadAttachment(ws, { filename, mimeType, nodeId, data });
         const url = client.attachmentRawUrl(id);
-        const markdown = `![${alt || filename}](${url})`;
+        const markdown = imageMarkdown(alt || filename, url);
         const result = await client.appendDocument(nodeId, { content: markdown, underHeading });
         return jsonResult({ id, url, markdown, appended: true, etag: result.etag });
       } catch (err) {
@@ -128,4 +153,97 @@ export function registerAttachmentTools(server) {
       }
     },
   );
+
+  // ISSUE-222 — rootr_upload_attachment/rootr_attach_image_to_document require
+  // the full file as base64Data over the remote connector (it can't read
+  // filePath), which breaks down for larger images. This gives the caller a
+  // short-lived presigned S3 URL instead: PUT the bytes there directly (works
+  // from anywhere with local disk access, no MCP message-size cost), then call
+  // rootr_complete_upload with the returned id.
+  server.registerTool(
+    'rootr_create_upload_url',
+    {
+      title: 'Get a presigned URL to upload a file/image as a Rootr attachment',
+      description:
+        'Get a short-lived presigned URL for uploading a file (screenshot, photo, diagram export, ...) to the ' +
+        'Rootr (루터) workspace as an attachment. PUT the raw file bytes to `uploadUrl` yourself (Content-Type ' +
+        'must match the `mimeType` you gave here) — this is the preferred path for larger files, since no file ' +
+        'bytes travel through this tool call. After the PUT succeeds, call rootr_complete_upload with the ' +
+        'returned `id` to mark the attachment ready and get its `url`/`markdown`.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        filename: z.string().refine(...nonBlank('filename')).describe('File name to store, e.g. "diagram.png"'),
+        mimeType: z.string().refine(...nonBlank('mimeType')).describe('MIME type, e.g. "image/png"'),
+        size: z
+          .number()
+          .int()
+          .positive()
+          .describe('File size in bytes (max 75MB). The stored size is whatever you actually PUT to uploadUrl.'),
+        nodeId: z.string().optional().describe(`Document/node id${NODE_TARGET_HINT} to associate the attachment with (permission-checked)`),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ filename, mimeType, size, nodeId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        nodeId = await resolveOptionalNodeId(client, nodeId);
+        const { id, uploadUrl, expiresIn } = await client.presignAttachment(ws, { filename, mimeType, size, nodeId });
+        return jsonResult({
+          id,
+          uploadUrl,
+          expiresIn,
+          instructions: `PUT the raw file bytes to uploadUrl with header Content-Type: ${mimeType}, then call rootr_complete_upload with id "${id}".`,
+        });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_complete_upload',
+    {
+      title: 'Finish a presigned attachment upload',
+      description:
+        'Call this after PUTting file bytes to the `uploadUrl` from rootr_create_upload_url. Verifies the ' +
+        'upload landed in storage and marks the attachment READY. Returns { id, url, markdown } — `url` is the ' +
+        'public /attachments/{id}/raw link and `markdown` is ready to paste into a document body.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        // id 는 주소의 한 칸으로 들어간다. `../workspaces` 같은 값은 인코딩해 보내도 운영의 프록시가
+        // 풀어서 다른 길(/v1/workspaces/complete)로 보내고, 호출한 쪽은 "Cannot POST …" 라는 날것의
+        // 라우팅 오류를 받는다(운영 실측 2026-10-09). 받은 id 모양이 아니면 보내기 전에 거절한다.
+        id: z
+          .string()
+          .refine(...nonBlank('id'))
+          .refine(
+            (v) => typeof v !== 'string' || v.trim().length === 0 || ATTACHMENT_ID.test(v),
+            'id must be the attachment id returned by rootr_create_upload_url (a UUID) — not a path, URL or filename',
+          )
+          .describe('The attachment id returned by rootr_create_upload_url'),
+        filename: z.string().optional().describe('Filename to use in the markdown alt text (defaults to the one given at presign time)'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ id, filename, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const attachment = await client.completeAttachment(id);
+        const url = client.attachmentRawUrl(id);
+        const name = filename || attachment.filename;
+        return jsonResult({
+          id,
+          url,
+          markdown: imageMarkdown(name, url),
+          filename: name,
+          mimeType: attachment.mimeType,
+          size: attachment.size,
+        });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }