rootr-cli 0.1.0

package/lib/client.js

@@ -0,0 +1,468 @@
+/**
+ * Thin REST client for the Rootr API.
+ *
+ * All requests are authenticated with the `x-api-key` header. Errors from
+ * the API are normalized into RootrApiError so callers (CLI or MCP tools)
+ * can render consistent, helpful messages.
+ */
+
+export class RootrApiError extends Error {
+  constructor(message, { status, body, hint } = {}) {
+    super(message);
+    this.name = 'RootrApiError';
+    this.status = status;
+    this.body = body;
+    this.hint = hint;
+  }
+}
+
+function hintFor(status, body) {
+  if (status === 401 || status === 403) {
+    return (
+      'API 키 또는 워크스페이스 스코프를 확인하세요 (rootr config로 현재 설정 확인). ' +
+      '워크스페이스 생성(rootr_create_workspace)은 계정 키(PAT, workspaces:create 스코프)가 필요합니다 — ' +
+      '워크스페이스 키(docs:read/docs:write/graph:read/ask/webhooks:manage 스코프)로는 할 수 없습니다.'
+    );
+  }
+  if (status === 412) {
+    return '문서가 그 사이 변경되었습니다: 다시 읽고 재시도하세요.';
+  }
+  if (status === 409) {
+    return body && (body.message || body.error) ? undefined : '충돌이 발생했습니다.';
+  }
+  return undefined;
+}
+
+export class RootrClient {
+  constructor({ apiKey, workspace, baseUrl }) {
+    this.apiKey = apiKey;
+    this.workspace = workspace;
+    this.baseUrl = (baseUrl || '').replace(/\/+$/, '');
+  }
+
+  _requireWorkspace() {
+    if (!this.workspace) {
+      throw new RootrApiError('워크스페이스가 설정되지 않았습니다.', {
+        hint: 'rootr config --workspace <id> 로 설정하거나 ROOTR_WORKSPACE 환경변수를 지정하세요.',
+      });
+    }
+  }
+
+  _requireApiKey() {
+    if (!this.apiKey) {
+      throw new RootrApiError('API 키가 설정되지 않았습니다.', {
+        hint: 'rootr config --api-key <key> 로 설정하거나 ROOTR_API_KEY 환경변수를 지정하세요.',
+      });
+    }
+  }
+
+  /**
+   * Low-level request helper.
+   * @param {string} path - path beginning with '/', appended to baseUrl
+   * @param {object} opts
+   * @param {string} [opts.method]
+   * @param {object} [opts.headers]
+   * @param {any} [opts.body] - if an object, JSON-stringified and Content-Type set
+   * @param {boolean} [opts.rawText] - if true, return response text instead of parsed JSON
+   * @param {boolean} [opts.returnResponse] - if true, return the raw Response (for header access)
+   */
+  async request(path, opts = {}) {
+    this._requireApiKey();
+
+    const url = opts.url || `${this.baseUrl}${path}`;
+    const headers = {
+      'x-api-key': this.apiKey,
+      ...(opts.headers || {}),
+    };
+
+    let body = opts.body;
+    if (body !== undefined && typeof body !== 'string' && !(body instanceof Uint8Array)) {
+      headers['Content-Type'] = headers['Content-Type'] || 'application/json';
+      body = JSON.stringify(body);
+    }
+
+    let res;
+    try {
+      res = await fetch(url, {
+        method: opts.method || 'GET',
+        headers,
+        body,
+      });
+    } catch (err) {
+      throw new RootrApiError(`네트워크 오류: ${err.message}`, { hint: `요청 URL: ${url}` });
+    }
+
+    if (opts.returnResponse) {
+      if (!res.ok) {
+        await this._throwForResponse(res);
+      }
+      return res;
+    }
+
+    if (!res.ok) {
+      await this._throwForResponse(res);
+    }
+
+    if (opts.rawText) {
+      return res.text();
+    }
+
+    const text = await res.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  async _throwForResponse(res) {
+    let bodyText = '';
+    let bodyJson;
+    try {
+      bodyText = await res.text();
+      bodyJson = bodyText ? JSON.parse(bodyText) : undefined;
+    } catch {
+      // body wasn't JSON; keep raw text
+    }
+
+    const message =
+      (bodyJson && (bodyJson.message || bodyJson.error)) ||
+      bodyText ||
+      `HTTP ${res.status} ${res.statusText}`;
+
+    throw new RootrApiError(message, {
+      status: res.status,
+      body: bodyJson || bodyText,
+      hint: hintFor(res.status, bodyJson),
+    });
+  }
+
+  // ---- Tree / navigation -------------------------------------------------
+
+  async getTree() {
+    this._requireWorkspace();
+    const data = await this.request(`/workspaces/${encodeURIComponent(this.workspace)}/tree`);
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.nodes)) return data.nodes;
+    if (data && Array.isArray(data.tree)) return data.tree;
+    return [];
+  }
+
+  async getNodeByPath(path) {
+    this._requireWorkspace();
+    try {
+      const data = await this.request(
+        `/workspaces/${encodeURIComponent(this.workspace)}/nodes/by-path?path=${encodeURIComponent(path)}`,
+      );
+      return data;
+    } catch (err) {
+      if (err instanceof RootrApiError && err.status === 404) return null;
+      throw err;
+    }
+  }
+
+  async createNode({ type = 'DOCUMENT', path, createParents = true, autoRename = false, content }) {
+    this._requireWorkspace();
+    return this.request(`/workspaces/${encodeURIComponent(this.workspace)}/nodes`, {
+      method: 'POST',
+      body: { type, path, createParents, autoRename, content },
+    });
+  }
+
+  async search(query) {
+    this._requireWorkspace();
+    const data = await this.request(
+      `/workspaces/${encodeURIComponent(this.workspace)}/search?q=${encodeURIComponent(query)}`,
+    );
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.results)) return data.results;
+    return [];
+  }
+
+  // ---- Documents ----------------------------------------------------------
+
+  /** Fetch raw markdown content for a document id. Returns { content, etag }. */
+  async getDocumentMarkdown(id) {
+    const res = await this.request(`/documents/${encodeURIComponent(id)}`, {
+      headers: { Accept: 'text/markdown' },
+      returnResponse: true,
+    });
+    const content = await res.text();
+    const etag = res.headers.get('etag') || res.headers.get('ETag') || undefined;
+    return { content, etag };
+  }
+
+  /** Fetch the full JSON representation of a document. */
+  async getDocumentJson(id) {
+    const res = await this.request(`/documents/${encodeURIComponent(id)}`, {
+      headers: { Accept: 'application/json' },
+      returnResponse: true,
+    });
+    const text = await res.text();
+    const etag = res.headers.get('etag') || res.headers.get('ETag') || undefined;
+    let json;
+    try {
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      json = { content: text };
+    }
+    if (etag && json && json.etag === undefined) json.etag = etag;
+    return json;
+  }
+
+  /** Replace document content entirely. */
+  async putDocument(id, content, { ifMatch } = {}) {
+    const headers = {};
+    if (ifMatch) headers['If-Match'] = ifMatch;
+    const res = await this.request(`/documents/${encodeURIComponent(id)}`, {
+      method: 'PUT',
+      headers,
+      body: { content },
+      returnResponse: true,
+    });
+    const etag = res.headers.get('etag') || res.headers.get('ETag') || undefined;
+    return { etag };
+  }
+
+  /** Safe, conflict-free append. */
+  async appendDocument(id, { content, underHeading, createIfMissing } = {}) {
+    const res = await this.request(`/documents/${encodeURIComponent(id)}/append`, {
+      method: 'POST',
+      body: { content, underHeading, createIfMissing },
+      returnResponse: true,
+    });
+    const etag = res.headers.get('etag') || res.headers.get('ETag') || undefined;
+    let json;
+    try {
+      const text = await res.text();
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      json = {};
+    }
+    return { ...json, etag: json.etag || etag };
+  }
+
+  /** Section-mode patch: { op, heading?, content, createIfMissing? } */
+  async patchDocumentSection(id, { op, heading, content, createIfMissing, ifMatch } = {}) {
+    const headers = {};
+    if (ifMatch) headers['If-Match'] = ifMatch;
+    return this.request(`/documents/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      headers,
+      body: { op, heading, content, createIfMissing, ...(ifMatch ? { ifMatch } : {}) },
+    });
+  }
+
+  /** Anchor-edit mode patch: { find, replace, replaceAll? } */
+  async patchDocumentAnchor(id, { find, replace, replaceAll, ifMatch } = {}) {
+    const headers = {};
+    if (ifMatch) headers['If-Match'] = ifMatch;
+    return this.request(`/documents/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      headers,
+      body: { find, replace, replaceAll, ...(ifMatch ? { ifMatch } : {}) },
+    });
+  }
+
+  /** List document versions. */
+  async getDocumentVersions(id, { limit } = {}) {
+    const qs = limit ? `?limit=${encodeURIComponent(limit)}` : '';
+    return this.request(`/documents/${encodeURIComponent(id)}/versions${qs}`);
+  }
+
+  /** Move a node to the trash (recoverable). */
+  async deleteNode(id) {
+    return this.request(`/nodes/${encodeURIComponent(id)}`, { method: 'DELETE' });
+  }
+
+  // ---- Workspaces (account-key scoped) -------------------------------------
+
+  /** List workspaces visible to the current key (account key / JWT). Defensive parsing. */
+  async listWorkspaces() {
+    const data = await this.request('/workspaces');
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.workspaces)) return data.workspaces;
+    if (data && Array.isArray(data.items)) return data.items;
+    return [];
+  }
+
+  // ---- Scaffolding ----------------------------------------------------------
+
+  /** Plan a scaffold tree from a natural-language intent. No workspace required. */
+  async scaffoldPlan(intent) {
+    return this.request('/scaffold/plan', { method: 'POST', body: { intent } });
+  }
+
+  /** Create a brand-new workspace from a scaffold tree. Requires an account key (PAT) with workspaces:create. */
+  async createWorkspaceScaffold({ name, intent, tree }) {
+    return this.request('/scaffold/workspace', {
+      method: 'POST',
+      body: { name, intent, tree },
+    });
+  }
+
+  /** Apply a scaffold tree to an existing workspace. */
+  async scaffoldApply(workspace, { rootPath, tree } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/scaffold/apply`, {
+      method: 'POST',
+      body: { rootPath, tree },
+    });
+  }
+
+  // ---- LOG datastores ---------------------------------------------------
+
+  /** Create a typed LOG store node. fields: [{name,type,...}] (relation fields carry target/many/relation). */
+  async createLogStore(workspace, { name, fields, parentId } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/logs`, {
+      method: 'POST',
+      body: { name, fields, parentId },
+    });
+  }
+
+  async getLog(id) {
+    return this.request(`/logs/${encodeURIComponent(id)}`);
+  }
+
+  /** Replace the ENTIRE field set of a LOG store — resend every field you want to keep. */
+  async updateLogFields(id, fields) {
+    return this.request(`/logs/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      body: { fields },
+    });
+  }
+
+  async addLogEntries(id, entries) {
+    return this.request(`/logs/${encodeURIComponent(id)}/entries`, {
+      method: 'POST',
+      body: { entries },
+    });
+  }
+
+  async queryLogEntries(id, { from, to, source, level, anomalyOnly, limit, order } = {}) {
+    const params = new URLSearchParams();
+    if (from) params.set('from', from);
+    if (to) params.set('to', to);
+    if (source) params.set('source', source);
+    if (level) params.set('level', level);
+    if (anomalyOnly !== undefined) params.set('anomalyOnly', String(anomalyOnly));
+    if (limit !== undefined) params.set('limit', String(limit));
+    if (order) params.set('order', order);
+    const qs = params.toString();
+    return this.request(`/logs/${encodeURIComponent(id)}/entries${qs ? `?${qs}` : ''}`);
+  }
+
+  async logStats(id, { groupBy, metric, field, from, to } = {}) {
+    const params = new URLSearchParams();
+    if (groupBy) params.set('groupBy', groupBy);
+    if (metric) params.set('metric', metric);
+    if (field) params.set('field', field);
+    if (from) params.set('from', from);
+    if (to) params.set('to', to);
+    const qs = params.toString();
+    return this.request(`/logs/${encodeURIComponent(id)}/stats${qs ? `?${qs}` : ''}`);
+  }
+
+  // ---- ask (GraphRAG RCA over GraphQL) --------------------------------------
+
+  /**
+   * Ask a natural-language question against a workspace's knowledge graph.
+   * Uses the GraphQL endpoint (baseUrl with trailing /v1 swapped for /graphql),
+   * not the REST /v1 base. Requires the `ask` scope.
+   */
+  async ask(workspaceId, question) {
+    this._requireApiKey();
+    const graphqlUrl = `${this.baseUrl.replace(/\/v1\/?$/, '')}/graphql`;
+    const query =
+      'query($ws:String!,$q:String!){ask(workspaceId:$ws,question:$q){text citations{documentPath quote}}}';
+    const data = await this.request(null, {
+      url: graphqlUrl,
+      method: 'POST',
+      body: { query, variables: { ws: workspaceId, q: question } },
+    });
+    if (data && Array.isArray(data.errors) && data.errors.length) {
+      const msg = data.errors.map((e) => e.message || String(e)).join('; ');
+      throw new RootrApiError(`ask 오류: ${msg}`, { body: data.errors });
+    }
+    return (data && data.data && data.data.ask) || { text: '', citations: [] };
+  }
+
+  // ---- Issues ---------------------------------------------------------------
+
+  async createIssueTracker(workspace, name) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/issue-trackers`, {
+      method: 'POST',
+      body: { name },
+    });
+  }
+
+  async getIssueTracker(trackerId) {
+    return this.request(`/issue-trackers/${encodeURIComponent(trackerId)}`);
+  }
+
+  async listIssues(trackerId, { state, label, type, assigneeId, q } = {}) {
+    const params = new URLSearchParams();
+    if (state) params.set('state', state);
+    if (label) params.set('label', label);
+    if (type) params.set('type', type);
+    if (assigneeId) params.set('assigneeId', assigneeId);
+    if (q) params.set('q', q);
+    const qs = params.toString();
+    return this.request(`/issue-trackers/${encodeURIComponent(trackerId)}/issues${qs ? `?${qs}` : ''}`);
+  }
+
+  async createIssue(trackerId, { title, body, labels, type, assigneeId, parentIssueId } = {}) {
+    return this.request(`/issue-trackers/${encodeURIComponent(trackerId)}/issues`, {
+      method: 'POST',
+      body: { title, body, labels, type, assigneeId, parentIssueId },
+    });
+  }
+
+  async getIssue(issueId) {
+    return this.request(`/issues/${encodeURIComponent(issueId)}`);
+  }
+
+  async updateIssue(issueId, patch) {
+    return this.request(`/issues/${encodeURIComponent(issueId)}`, {
+      method: 'PATCH',
+      body: patch,
+    });
+  }
+
+  /** Comment on an issue — issues live as blocks inside the tracker document. */
+  async commentIssue(trackerId, issueId, body) {
+    return this.request(`/documents/${encodeURIComponent(trackerId)}/comments`, {
+      method: 'POST',
+      body: { body, blockId: issueId },
+    });
+  }
+
+  // ---- Webhooks ---------------------------------------------------------
+
+  async listWebhooks(workspace) {
+    const data = await this.request(`/workspaces/${encodeURIComponent(workspace)}/webhooks`);
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.webhooks)) return data.webhooks;
+    return [];
+  }
+
+  async createWebhook(workspace, { name, url, events, scopeNodeId, filterTags, debounceSeconds } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/webhooks`, {
+      method: 'POST',
+      body: { name, url, events, scopeNodeId, filterTags, debounceSeconds },
+    });
+  }
+
+  async updateWebhook(workspace, webhookId, patch) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/webhooks/${encodeURIComponent(webhookId)}`, {
+      method: 'PATCH',
+      body: patch,
+    });
+  }
+
+  async deleteWebhook(workspace, webhookId) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/webhooks/${encodeURIComponent(webhookId)}`, {
+      method: 'DELETE',
+    });
+  }
+}

package/lib/config.js

@@ -0,0 +1,71 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CONFIG_DIR = join(homedir(), '.rootr');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_BASE_URL = 'https://rootr.io/api/v1';
+
+/**
+ * Read the on-disk config file. Returns {} if it doesn't exist or is invalid.
+ */
+function readConfigFile() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    const raw = readFileSync(CONFIG_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve effective configuration: env vars take priority over the config file.
+ */
+export function loadConfig() {
+  const file = readConfigFile();
+
+  const apiKey = process.env.ROOTR_API_KEY || file.apiKey || '';
+  const workspace = process.env.ROOTR_WORKSPACE || file.workspace || '';
+  const baseUrl = process.env.ROOTR_BASE_URL || file.baseUrl || DEFAULT_BASE_URL;
+
+  return { apiKey, workspace, baseUrl };
+}
+
+/**
+ * Persist config to ~/.rootr/config.json (chmod 600). Merges with existing file contents.
+ */
+export function saveConfig(partial) {
+  const existing = readConfigFile();
+  const next = { ...existing, ...partial };
+
+  // Drop undefined values so we don't write "apiKey": undefined
+  for (const key of Object.keys(next)) {
+    if (next[key] === undefined) delete next[key];
+  }
+
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+
+  writeFileSync(CONFIG_PATH, JSON.stringify(next, null, 2) + '\n', {
+    mode: 0o600,
+  });
+
+  try {
+    // Ensure permissions are correct even if the file already existed with looser perms.
+    chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    // best effort; not fatal on platforms without chmod support
+  }
+
+  return next;
+}
+
+export function maskKey(key) {
+  if (!key) return '(not set)';
+  return key.slice(0, 12) + '...';
+}
+
+export { CONFIG_PATH, DEFAULT_BASE_URL };

package/lib/mcp-tools/ask.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+import { textResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+
+/** rootr_ask — GraphRAG root-cause-analysis question answering. */
+export function registerAskTools(server) {
+  server.registerTool(
+    'rootr_ask',
+    {
+      title: 'Ask a question over the Rootr knowledge graph (RCA)',
+      description:
+        'Ask a natural-language question against a Rootr (루터) workspace\'s knowledge graph (GraphRAG). Good for ' +
+        'root-cause-analysis style questions ("why did X happen", "what changed before Y") that need to reason ' +
+        'across linked documents and LOG anomalies rather than a single document. Requires the `ask` scope. ' +
+        'Returns the answer text plus citations pointing at the source documents/quotes it drew from.',
+      inputSchema: {
+        question: z.string().describe('Natural-language question to ask'),
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ question, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const result = await client.ask(ws, question);
+        const citations = Array.isArray(result.citations) ? result.citations : [];
+        const citationLines = citations.map((c) => `- ${c.documentPath}: ${c.quote}`);
+        const text = [
+          result.text || '(no answer text)',
+          '',
+          citations.length ? 'Citations:' : '(no citations)',
+          ...citationLines,
+        ].join('\n');
+        return textResult(text);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}