rootr-cli 0.1.0

package/lib/mcp-tools/documents.js

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+
+import { RootrApiError } from '../client.js';
+import { resolveTarget, requireResolved } from '../resolve.js';
+import { textResult, errorResult, makeClient } from './shared.js';
+
+/** Registers the original 6 document tools: list/read/append/edit/write/search. */
+export function registerDocumentTools(server) {
+  server.registerTool(
+    'rootr_list',
+    {
+      title: 'List Rootr documents',
+      description:
+        'List documents and folders in the connected Rootr (루터) workspace, optionally filtered to a path prefix. ' +
+        'Use this first to discover what exists before reading or writing.',
+      inputSchema: {
+        path: z
+          .string()
+          .optional()
+          .describe('Optional path prefix to filter results, e.g. "/notes"'),
+      },
+    },
+    async ({ path }) => {
+      try {
+        const client = makeClient();
+        const nodes = await client.getTree();
+        const rows = nodes
+          .filter((n) => {
+            if (!path) return true;
+            const p = n.path || '';
+            return p === path || p.startsWith(path.endsWith('/') ? path : path + '/');
+          })
+          .map((n) => `${n.type || '?'} ${n.path || n.name || n.id}`)
+          .sort();
+        return textResult(rows.length ? rows.join('\n') : '(no matching nodes)');
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_read',
+    {
+      title: 'Read a Rootr document',
+      description:
+        'Read the full markdown content of a Rootr (루터) document by path (starting with "/") or by node id. ' +
+        'Read a document before editing or appending to it so you know its current structure.',
+      inputSchema: {
+        target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id'),
+      },
+    },
+    async ({ target }) => {
+      try {
+        const client = makeClient();
+        const resolved = await resolveTarget(client, target);
+        const id = requireResolved(resolved);
+        const { content } = await client.getDocumentMarkdown(id);
+        return textResult(content);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_append',
+    {
+      title: 'Append to a Rootr document (preferred write)',
+      description:
+        'Append content to a Rootr document, optionally under a given heading. This is a conflict-free, ' +
+        'additive operation — it never overwrites existing content, so PREFER this over rootr_write whenever ' +
+        'you just need to add new information (log entries, notes, findings) to an existing document.',
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        content: z.string().describe('Markdown content to append'),
+        underHeading: z
+          .string()
+          .optional()
+          .describe(
+            'Heading to append under, e.g. "## Notes" or "Notes". If omitted, appends to the end of the document. ' +
+              'A missing heading section is created at the document end.',
+          ),
+      },
+    },
+    async ({ target, content, underHeading }) => {
+      try {
+        const client = makeClient();
+        const resolved = await resolveTarget(client, target);
+        const id = requireResolved(resolved);
+        const result = await client.appendDocument(id, { content, underHeading });
+        return textResult(`appended (etag ${result.etag || 'n/a'})`);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_edit',
+    {
+      title: 'Edit a Rootr document by anchor replace',
+      description:
+        'Replace an exact snippet of text ("find") with new text ("replace") inside a Rootr document. ' +
+        'Fails with a clear error if the snippet is missing or ambiguous (not unique), so read the document ' +
+        'first to copy the exact text to find. Good for precise, targeted edits; use rootr_append instead when ' +
+        'you are only adding new content.',
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        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'),
+      },
+    },
+    async ({ target, find, replace, replaceAll }) => {
+      try {
+        const client = makeClient();
+        const resolved = await resolveTarget(client, target);
+        const id = requireResolved(resolved);
+        await client.patchDocumentAnchor(id, { find, replace, replaceAll });
+        return textResult('edited');
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_write',
+    {
+      title: 'Overwrite a Rootr document (destructive)',
+      description:
+        'Replace the ENTIRE content of a Rootr document, or create a new document at a path if it does not exist. ' +
+        'This is DESTRUCTIVE — it discards whatever is currently there. Read the document first and pass its etag ' +
+        'as ifMatch to avoid clobbering concurrent changes. Prefer rootr_append or rootr_edit for incremental changes.',
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/", created if missing) or node id'),
+        content: z.string().describe('Full new markdown content for the document'),
+        ifMatch: z
+          .string()
+          .optional()
+          .describe('ETag obtained from a previous rootr_read/rootr_write, to guard against overwriting concurrent edits'),
+      },
+    },
+    async ({ target, content, ifMatch }) => {
+      try {
+        const client = makeClient();
+        const resolved = await resolveTarget(client, target);
+        if (!resolved.existed) {
+          if (!resolved.path) throw new RootrApiError(`대상을 찾을 수 없습니다: ${target}`);
+          // creating with content IS the write — a follow-up PUT would just
+          // double the version history and extraction work
+          const created = await client.createNode({
+            type: 'DOCUMENT',
+            path: resolved.path,
+            createParents: true,
+            autoRename: false,
+            content,
+          });
+          const id = created.id || (created.node && created.node.id);
+          return textResult(`created ${resolved.path} (id ${id})`);
+        }
+        const { etag } = await client.putDocument(resolved.id, content, { ifMatch });
+        return textResult(`wrote (etag ${etag || 'n/a'})`);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_search',
+    {
+      title: 'Search the Rootr workspace',
+      description:
+        'Full-text search across the connected Rootr (루터) workspace. Use this to find relevant documents before ' +
+        'reading or editing them.',
+      inputSchema: {
+        query: z.string().describe('Search query text'),
+      },
+    },
+    async ({ query }) => {
+      try {
+        const client = makeClient();
+        const results = await client.search(query);
+        const rows = results.map((r) => `${r.path || r.name || r.nodeId} — ${r.snippet || ''}`);
+        return textResult(rows.length ? rows.join('\n') : '(no results)');
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/issues.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+
+import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+
+/** Issue tracker tools: create tracker, list/create/get/update issues, comment. */
+export function registerIssueTools(server) {
+  server.registerTool(
+    'rootr_create_issue_tracker',
+    {
+      title: 'Create an issue tracker in a Rootr workspace',
+      description:
+        'Create a new GitHub-style issue tracker document in a Rootr (루터) workspace. Returns the tracker with ' +
+        'its id, plus its default labels/types — use rootr_create_issue afterward to add issues to it.',
+      inputSchema: {
+        name: z.string().describe('Name of the issue tracker'),
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ name, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const result = await client.createIssueTracker(ws, name);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_list_issues',
+    {
+      title: 'List issues in a tracker',
+      description:
+        'List issues in a Rootr (루터) issue tracker, optionally filtered by state (OPEN/CLOSED/ALL), label id, ' +
+        'type id, or a text query. Use rootr_get_issue for full details of one issue.',
+      inputSchema: {
+        trackerId: z.string().describe('Issue tracker node id'),
+        state: z.string().optional().describe('OPEN | CLOSED | ALL'),
+        q: z.string().optional().describe('Free-text search within issues'),
+        label: z.string().optional().describe('Label id to filter by'),
+        type: z.string().optional().describe('Issue type id to filter by'),
+      },
+    },
+    async ({ trackerId, state, q, label, type }) => {
+      try {
+        const client = makeClient();
+        const result = await client.listIssues(trackerId, { state, q, label, type });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_issue',
+    {
+      title: 'Create an issue',
+      description:
+        'Create a new issue in a Rootr (루터) issue tracker. labels is an array of label ids, type is a type id ' +
+        '(both from the tracker\'s custom type/label definitions — see rootr_read on the tracker or its metadata). ' +
+        'parentIssueId nests this issue under another issue (sub-issue).',
+      inputSchema: {
+        trackerId: z.string().describe('Issue tracker node id'),
+        title: z.string().describe('Issue title'),
+        body: z.string().optional().describe('Issue body (markdown)'),
+        labels: z.array(z.string()).optional().describe('Label ids to attach'),
+        type: z.string().optional().describe('Issue type id'),
+        parentIssueId: z.string().optional().describe('Parent issue id, to create this as a sub-issue'),
+      },
+    },
+    async ({ trackerId, title, body, labels, type, parentIssueId }) => {
+      try {
+        const client = makeClient();
+        const result = await client.createIssue(trackerId, { title, body, labels, type, parentIssueId });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_get_issue',
+    {
+      title: 'Get an issue',
+      description: 'Fetch full details of a single Rootr (루터) issue by id.',
+      inputSchema: {
+        issueId: z.string().describe('Issue id'),
+      },
+    },
+    async ({ issueId }) => {
+      try {
+        const client = makeClient();
+        const result = await client.getIssue(issueId);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_issue',
+    {
+      title: 'Update an issue',
+      description:
+        'Update arbitrary fields of a Rootr (루터) issue. To close an issue, set state to "CLOSED" and stateReason ' +
+        'to one of completed | not_planned | duplicate.',
+      inputSchema: {
+        issueId: z.string().describe('Issue id'),
+        title: z.string().optional(),
+        body: z.string().optional(),
+        state: z.string().optional().describe('e.g. "OPEN" or "CLOSED"'),
+        stateReason: z.string().optional().describe('completed | not_planned | duplicate (when closing)'),
+        labels: z.array(z.string()).optional().describe('Label ids (replaces current labels)'),
+        type: z.string().optional().describe('Issue type id'),
+        assigneeId: z.string().optional().describe('User id to assign'),
+      },
+    },
+    async ({ issueId, ...patch }) => {
+      try {
+        const client = makeClient();
+        // Drop undefined keys so we don't send explicit nulls for untouched fields.
+        const body = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+        const result = await client.updateIssue(issueId, body);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_comment_issue',
+    {
+      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.',
+      inputSchema: {
+        trackerId: z.string().describe('Issue tracker node id'),
+        issueId: z.string().describe('Issue id to comment on'),
+        body: z.string().describe('Comment body (markdown)'),
+      },
+    },
+    async ({ trackerId, issueId, body }) => {
+      try {
+        const client = makeClient();
+        const result = await client.commentIssue(trackerId, issueId, body);
+        return textResult(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/logs.js

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+
+/** LOG datastore tools: create/update-fields/add-entries/query-entries/stats. */
+export function registerLogTools(server) {
+  server.registerTool(
+    'rootr_create_log_store',
+    {
+      title: 'Create a typed LOG datastore',
+      description:
+        'Create a new typed LOG store (a structured, queryable table-like node) in a Rootr (루터) workspace. ' +
+        'Each field has a name/type; type is one of string|int|float|bool|datetime|json|enum|level|relation. ' +
+        'Relation fields additionally need target (a node id to relate to) and optional many/relation flags. ' +
+        'Use rootr_add_log_entries afterward to insert rows, and rootr_query_log_entries / rootr_log_stats to read them back.',
+      inputSchema: {
+        name: z.string().describe('Name of the LOG store'),
+        fields: z
+          .array(z.record(z.any()))
+          .describe(
+            'Field definitions: [{name, type, ...}]. type=string|int|float|bool|datetime|json|enum|level|relation. ' +
+              'relation fields add target (node id), many?, relation?.',
+          ),
+        parentId: z.string().optional().describe('Parent node id to nest the LOG store under'),
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ name, fields, parentId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const result = await client.createLogStore(ws, { name, fields, parentId });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_log_fields',
+    {
+      title: 'Replace a LOG store\'s field definitions (full replace)',
+      description:
+        'Update the field schema of an existing LOG store. WARNING: this REPLACES THE ENTIRE FIELD SET — ' +
+        'you must resend every field you want to keep, not just the ones you are changing/adding. ' +
+        'Read the LOG store first (e.g. via rootr_read or a get-log call) to see its current fields before calling this.',
+      inputSchema: {
+        logId: z.string().describe('LOG store node id'),
+        fields: z
+          .array(z.record(z.any()))
+          .describe('COMPLETE field list to set — omitted existing fields will be dropped'),
+      },
+    },
+    async ({ logId, fields }) => {
+      try {
+        const client = makeClient();
+        const result = await client.updateLogFields(logId, fields);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_add_log_entries',
+    {
+      title: 'Add entries to a LOG store',
+      description:
+        'Append one or more entries (rows) to a LOG store. Each entry may carry ts, source, level, message, data ' +
+        '(shaped per the store\'s field schema). This is additive — existing entries are untouched.',
+      inputSchema: {
+        logId: z.string().describe('LOG store node id'),
+        entries: z
+          .array(z.record(z.any()))
+          .describe('Entries to add: [{ts?, source?, level?, message?, data?}, ...]'),
+      },
+    },
+    async ({ logId, entries }) => {
+      try {
+        const client = makeClient();
+        const result = await client.addLogEntries(logId, entries);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_query_log_entries',
+    {
+      title: 'Query entries from a LOG store',
+      description:
+        'Query/filter entries from a LOG store by time range, source, level, and/or anomaly flag. ' +
+        'Use this to inspect recent activity or find anomalous entries before asking rootr_ask for root-cause analysis.',
+      inputSchema: {
+        logId: z.string().describe('LOG store node id'),
+        from: z.string().optional().describe('ISO timestamp lower bound'),
+        to: z.string().optional().describe('ISO timestamp upper bound'),
+        source: z.string().optional().describe('Filter by source'),
+        level: z.string().optional().describe('Filter by level'),
+        anomalyOnly: z.boolean().optional().describe('Only return entries flagged as anomalous'),
+        limit: z.number().optional().describe('Max entries to return'),
+        order: z.string().optional().describe('Sort order, e.g. "asc" or "desc"'),
+      },
+    },
+    async ({ logId, from, to, source, level, anomalyOnly, limit, order }) => {
+      try {
+        const client = makeClient();
+        const result = await client.queryLogEntries(logId, {
+          from,
+          to,
+          source,
+          level,
+          anomalyOnly,
+          limit,
+          order,
+        });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_log_stats',
+    {
+      title: 'Aggregate stats over a LOG store',
+      description:
+        'Compute aggregate statistics over a LOG store\'s entries, grouped by hour/day/source/level, with a ' +
+        'metric of count/avg/max/min/sum (avg/max/min/sum require a numeric `field`). Useful for trend/volume ' +
+        'questions without pulling raw entries.',
+      inputSchema: {
+        logId: z.string().describe('LOG store node id'),
+        groupBy: z.string().optional().describe('hour | day | source | level'),
+        metric: z.string().optional().describe('count | avg | max | min | sum'),
+        field: z.string().optional().describe('Numeric field name, required for avg/max/min/sum'),
+        from: z.string().optional().describe('ISO timestamp lower bound'),
+        to: z.string().optional().describe('ISO timestamp upper bound'),
+      },
+    },
+    async ({ logId, groupBy, metric, field, from, to }) => {
+      try {
+        const client = makeClient();
+        const result = await client.logStats(logId, { groupBy, metric, field, from, to });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/misc.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient } from './shared.js';
+import { resolveTarget, requireResolved } from '../resolve.js';
+
+/** Miscellaneous document/node tools: version history, trash. */
+export function registerMiscTools(server) {
+  server.registerTool(
+    'rootr_document_versions',
+    {
+      title: 'List a document\'s version history',
+      description:
+        'List saved versions of a Rootr (루터) document, most recent first. Useful for seeing what changed and ' +
+        'when, or to recover an older revision.',
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        limit: z.number().optional().describe('Max number of versions to return'),
+      },
+    },
+    async ({ target, limit }) => {
+      try {
+        const client = makeClient();
+        const resolved = await resolveTarget(client, target);
+        const id = requireResolved(resolved);
+        const result = await client.getDocumentVersions(id, { limit });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_delete_node',
+    {
+      title: 'Delete a node (move to trash)',
+      description:
+        'Delete a Rootr (루터) document or folder by moving it to the trash — this is recoverable, not a ' +
+        'permanent delete. Use rootr_read/rootr_list first to confirm you have the right target.',
+      inputSchema: {
+        target: z.string().describe('Document/folder path (starting with "/") or node id'),
+      },
+    },
+    async ({ target }) => {
+      try {
+        const client = makeClient();
+        const resolved = await resolveTarget(client, target);
+        const id = requireResolved(resolved);
+        await client.deleteNode(id);
+        return jsonResult({ deleted: id, note: 'moved to trash, recoverable' });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/shared.js

@@ -0,0 +1,48 @@
+import { loadConfig } from '../config.js';
+import { RootrClient, RootrApiError } from '../client.js';
+
+export function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+export function errorResult(err) {
+  const message =
+    err instanceof RootrApiError
+      ? `${err.message}${err.hint ? `\n힌트: ${err.hint}` : ''}`
+      : err.message || String(err);
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+export function jsonResult(value) {
+  return textResult(JSON.stringify(value, null, 2));
+}
+
+/**
+ * Build a RootrClient. If `workspaceOverride` is given, it wins over the
+ * configured/env workspace — this backs the optional `workspace` argument
+ * that every workspace-scoped MCP tool accepts.
+ */
+export function makeClient(workspaceOverride) {
+  const cfg = loadConfig();
+  const workspace = workspaceOverride || cfg.workspace;
+  return new RootrClient({ ...cfg, workspace });
+}
+
+/**
+ * Resolve the effective workspace id for a tool call: explicit arg wins,
+ * then ROOTR_WORKSPACE/config. Throws a clear RootrApiError otherwise.
+ */
+export function requireWorkspace(workspaceOverride) {
+  const cfg = loadConfig();
+  const workspace = workspaceOverride || cfg.workspace;
+  if (!workspace) {
+    throw new RootrApiError('워크스페이스가 설정되지 않았습니다.', {
+      hint:
+        '이 도구의 workspace 인자로 워크스페이스 id를 넘기거나, ' +
+        'rootr config --workspace <id> 로 설정하거나 ROOTR_WORKSPACE 환경변수를 지정하세요.',
+    });
+  }
+  return workspace;
+}
+
+export { RootrApiError };